Formación › Programar con Claude Code en 12 horas › Hora 3

Programar con Claude Code en 12 horas · hora 3 de 12

CLAUDE.md, AGENTS.md, reglas y memoria

CLAUDE.md es lo primero que Claude lee en cada sesión. Bien escrito, ahorra horas de explicaciones; demasiado largo, hace que Claude ignore justo lo importante. Verás el CLAUDE.md real que generó /init en el repositorio de práctica y lo mejorarás.

Al terminar sabrásEscribir un CLAUDE.md de menos de 200 líneas con comandos, reglas y trampas que Claude no puede deducir, decidir qué sobra con la pregunta «¿fallaría sin esto?» y conectarlo con AGENTS.md.

60 minutos· 1 esquema· 6 preguntas· 1 ejercicio· laboratorio· entregable

Repaso

Comprueba De la hora 2: diste una regla en un mensaje y, tras una compactación, Claude dejó de seguirla. ¿Cuál es el arreglo definitivo?

Comprueba De la hora 2: ¿qué no se puede deshacer con /rewind?

Comprueba De la hora 1: en la primera sesión, ¿qué hizo que el mapa del repositorio fuera fiable?

Vocabulario

CLAUDE.md: Un fichero de instrucciones que Claude lee al principio de cada sesión.
AGENTS.md: Un formato común de instrucciones que leen otros agentes de programación.
Regla por ruta: Un fichero de .claude/rules/ que solo se carga al trabajar con ciertos ficheros.
Memoria automática: Las notas que Claude escribe por su cuenta sobre tus preferencias y correcciones.

El ejemplo: lo que genera /init

/init analiza el proyecto y escribe un primer CLAUDE.md con los comandos y las convenciones que encuentra. Esta es la sesión real en el repositorio de práctica, con el fichero que dejó.

Antes y después /init en el repositorio de práctica

Antes de mirar: ¿Qué crees que pondrá /init en el CLAUDE.md? ¿Encontrará los dos fallos sembrados del repositorio?

El prompt

Petición

/init

Se lanzó en modo de aceptar ediciones.

La sesión real

Salida real Claude Sonnet 5.5 · 24 de octubre de 2026 · sin editar · Claude Code en modo acceptEdits sobre el repositorio de práctica

Para repetirla, en el repositorio: claude --permission-mode acceptEdits y pega la petición. Se grabó con claude -p, sin conversación: lo que aquí se deniega, a ti te lo preguntaría.

Lo que hizo: 3 acciones

Bash: ls -la; git ls-files | head -50; cat README* CLAUDE.md package.json 2>/dev/null | head -80
Bash: cat src/cli.js src/fechas.js src/informes/semanal.js src/paradas.js; head -5 datos/paradas.csv; head -30 pruebas/parte.test.js
Write: CLAUDE.md

He creado CLAUDE.md en la raíz del repositorio. No he ejecutado npm test ni npm run parte; los comandos salen del package.json y del README.

Incluye:

Comandos: npm test, cómo lanzar una sola prueba con --test-name-pattern, y npm run parte. También anota que no hay linter ni build.
Arquitectura: el flujo cli.js → leerParadas → parteSemanal, el formato del CSV (separador ;, sin soporte de comillas) y el formato numérico es-ES.
Dos limitaciones que vi leyendo el código:
horasEntre da horas negativas si la parada cruza medianoche, como P-104 (23:30;01:15) en los datos.
El CLI toma la semana solo de la primera parada y no filtra por semana.

No lo comprobé ejecutándolo. Si algo de esto es intencionado y no un fallo, dímelo y lo ajusto.

Los cambios que dejó (diff)

git diff

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..ce98f41
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,23 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+Repositorio sintético de práctica (curso MaestrIA). Lee `datos/paradas.csv` y genera el parte semanal de horas de parada por línea. Sin dependencias; requiere Node.js 20+ y módulos ES (`"type": "module"`).
+
+## Comandos
+
+- Todas las pruebas: `npm test` (usa el runner nativo `node --test`)
+- Una prueba concreta: `node --test --test-name-pattern="suma las horas" pruebas/parte.test.js`
+- Generar el parte de ejemplo: `npm run parte` (equivale a `node src/cli.js datos/paradas.csv`)
+
+No hay linter ni paso de build.
+
+## Arquitectura
+
+Flujo: `src/cli.js` lee el CSV → `leerParadas` (`src/paradas.js`) → `parteSemanal` (`src/informes/semanal.js`) que usa `horasPorLinea` y formatea la tabla de texto.
+
+- El CSV usa `;` como separador; la cabecera es `id;fecha;linea;equipo;inicio;fin` (fechas `AAAA-MM-DD`, horas `HH:MM`). El parser es propio y no soporta comillas.
+- `src/fechas.js` contiene `horasEntre` y `semanaIso`.
+- El parte usa formato `es-ES` (coma decimal, un decimal); las pruebas lo comprueban.
+- `cli.js` calcula la semana ISO solo a partir de la fecha de la primera parada; no filtra paradas por semana.
+- `horasEntre` asume que inicio y fin son del mismo día: una parada que cruza medianoche (p. ej. `23:30;01:15` en `P-104` de los datos) da horas negativas.

Qué ha pasado

Un buen punto de partida, con detalles que ahorran tiempo: el comando para lanzar una sola prueba y la advertencia sobre la parada que cruza la medianoche. Encontró uno de los dos fallos: vio la medianoche y se le escapó la fila duplicada (P-106), que el mapa de la hora 1 sí había visto. Un CLAUDE.md generado es un borrador, no un diagnóstico. Fíjate además en tres cosas que podar o completar:

La primera línea está en inglés y es genérica («This file provides guidance…»): no aporta nada a Claude. Fuera.
La arquitectura («flujo: cli.js lee el CSV → leerParadas…») es algo que Claude puede deducir leyendo el código. Con la pregunta «¿fallaría sin esto?», sobra casi entera.
Falta lo que Claude no puede deducir: qué no se toca (la carpeta datos/, por ejemplo) y cómo verificar antes de dar algo por terminado.

Qué es CLAUDE.md y dónde vive

CLAUDE.md se lee al principio de cada sesión. Hay varios niveles y se cargan todos:

Fichero	Para qué
`~/.claude/CLAUDE.md`	Tus preferencias personales en todos los proyectos
`./CLAUDE.md` (o `./.claude/CLAUDE.md`)	Las reglas del proyecto, compartidas con el equipo en Git
`./CLAUDE.local.md`	Tus preferencias en este proyecto, fuera de Git (añádelo a `.gitignore`)
`.claude/rules/*.md`	Reglas por tema; con `paths:`, solo al trabajar con ciertos ficheros

Lo que Claude Code carga siempre, lo que carga cuando hace falta y lo único que obliga.

Una idea clave de la documentación: CLAUDE.md es contexto, no una obligación. Claude lo tiene en cuenta, pero lo que debe pasar siempre, sin excepciones, es un hook (hora 10).

La regla de oro: corto y que no se pueda deducir

La guía oficial apunta a menos de 200 líneas por fichero y propone una pregunta para cada línea: «¿quitarla haría que Claude cometiera errores?». Si la respuesta es no, bórrala. Los CLAUDE.md inflados hacen que Claude ignore tus instrucciones de verdad.

AGENTS.md: un fichero para todos los agentes

Según la documentación de Claude Code, Claude lee AGENTS.md solo si no hay un CLAUDE.md en tu carpeta de trabajo o por encima; si hay los dos, solo lee CLAUDE.md. La solución oficial para tener una sola fuente es un CLAUDE.md que importe el otro:

CLAUDE.md que comparte las reglas con otros agentes

@AGENTS.md

## Solo para Claude Code
- Usa el modo plan para cambios de más de un fichero.

Reglas por ruta y memoria: en proyectos grandes, divide las instrucciones en .claude/rules/ con paths: para que se carguen solo cuando hacen falta. Y Claude apunta por su cuenta lo que aprende de tus correcciones en una memoria automática por repositorio, de la que carga las primeras 200 líneas o 25 KB al empezar. Revísala de vez en cuando.

Practica

Clasifica ¿Incluir en CLAUDE.md o dejar fuera?

«Para una sola prueba: node --test --test-name-pattern="…" pruebas/x.test.js»Categoría
«Escribe código limpio y bien documentado»Categoría
«No modifiques nada en datos/: son datos de origen»Categoría
La descripción del flujo entre ficheros, módulo a móduloCategoría
«La prueba de formato necesita que Node traiga el idioma es-ES; si falla solo ahí, revisa Node antes que el código»Categoría
La documentación completa de la API de un proveedorCategoría

Laboratorio Poda y completa el CLAUDE.md de /init

Reescribe el CLAUDE.md del repositorio de práctica (o el de tu proyecto). Las comprobaciones miden la forma; la prueba de verdad es ver si Claude cambia su comportamiento.

Tu CLAUDE.md

Las comprobaciones miden la estructura, no la calidad: la prueba de verdad es usarlo en tu herramienta.

Pendiente: Incluye los comandos de pruebas
Pendiente: Quita la línea genérica en inglés
Pendiente: Tiene una regla propia del proyecto
Pendiente: Dice qué no tocar
Pendiente: Dice cómo verificar antes de terminar
Pendiente: Tiene menos de 200 líneas

Empieza borrando la línea en inglés y añadiendo los dos comandos que usarás siempre: todas las pruebas y una sola prueba.
Añade lo que Claude no puede deducir: la coma decimal, que datos/ no se toca y la trampa de las paradas nocturnas.
Cierra con cómo verificar: «ejecuta npm test y no des nada por terminado con pruebas en rojo».

Una versión de referencia. La tuya no tiene que ser igual: compárala pieza a pieza.

Versión de referencia

# informes-mantenimiento
Genera el parte semanal de paradas a partir de datos/paradas.csv. Node.js 20+, sin dependencias.

## Comandos
- Todas las pruebas: `npm test`
- Una prueba: `node --test --test-name-pattern="suma las horas" pruebas/parte.test.js`
- Parte de ejemplo: `npm run parte`

## Reglas
- Horas con coma decimal (formato es-ES), como comprueban las pruebas.
- No modifiques nada en datos/: son datos de origen. Si hay que transformarlos, genera el resultado en otra carpeta.

## Trampas
- Una parada que cruza la medianoche (23:30 → 01:15) necesita un tratamiento propio en horasEntre.

## Al terminar
- Ejecuta `npm test` y no des nada por terminado con pruebas en rojo.

Comprueba lo que has aprendido

Comprueba Tu CLAUDE.md tiene 600 líneas y Claude se salta una regla importante. ¿Qué haces primero?

Comprueba Tu repositorio tiene AGENTS.md y acabas de crear un CLAUDE.md vacío. ¿Qué lee Claude Code?

Comprueba Quieres que nadie modifique datos/ en ningún caso. ¿Basta con escribirlo en CLAUDE.md?

Entregable Tu CLAUDE.md

Genera un CLAUDE.md con /init en el repositorio de práctica o en el tuyo y pódalo con la pregunta «¿fallaría sin esto?». Añade lo que falte: comandos, reglas propias, trampas, qué no tocar y cómo verificar. Pega aquí la versión final y una prueba: una tarea en la que Claude se comportó distinto gracias a una línea concreta.

Está bien si: tiene menos de 200 líneas; incluye al menos una regla que Claude no puede deducir del código; dice cómo verificar; y aportas la tarea en la que una línea cambió su comportamiento. Tiempo: unos 25 minutos.

Tu entregable: Tu CLAUDE.md

Lo esencial

CLAUDE.md se lee en cada sesión: comandos, reglas propias, trampas, qué no tocar y cómo verificar.
Menos de 200 líneas y la pregunta «¿fallaría sin esto?» para cada línea.
/init da un buen punto de partida, pero hay que podarlo y completarlo.
AGENTS.md solo se lee si no hay CLAUDE.md: impórtalo con @AGENTS.md.
CLAUDE.md es contexto, no obligación: lo que debe pasar siempre va en un hook.

Fuentes y para seguir

Cómo recuerda Claude tu proyecto: CLAUDE.md, AGENTS.md y memoria (se abre en otra pestaña) (documentación oficial, consultada el 24/10/2026).
Buenas prácticas: escribir un CLAUDE.md eficaz (se abre en otra pestaña).
En MaestrIA: el generador de AGENTS.md y CLAUDE.md y las plantillas del kit gratuito.

← Hora 2La ventana de contexto y las sesiones Hora 4 →Explorar, planificar y pedir un cambio

Lección revisada el 24/10/2026 con la documentación oficial enlazada en sus fuentes. Revisamos los cursos cada trimestre.