CLAUDE.md: el contrato con el agente

En la intro repetías las mismas correcciones cada sesión: "usa pnpm", "no toques eso", "los tests van con tal comando". CLAUDE.md es donde escribes todo eso una vez para no volver a teclearlo. Es un fichero markdown que Claude Code lee al inicio de cada sesión y mantiene en contexto mientras trabajas.

Cómo se siente sin él vs. con él

Sin CLAUDE.md:

Tú: "Añade una dependencia para validar formularios." Claude: instala yarn add ... — pero tu proyecto usa pnpm. Lo corriges. (mañana, sesión nueva) — vuelve a usar yarn. Lo corriges otra vez.

Con CLAUDE.md:

## Stack
- pnpm — usar `pnpm`, nunca `npm` ni `yarn`.

Claude: pnpm add ... — desde la primera vez, en cada sesión, sin que lo digas.

Eso es el contrato: dejas de gastar turnos (y tu tiempo) explicando lo mismo.

Cuándo añadir algo a CLAUDE.md

Trátalo como el sitio donde escribes lo que, si no, volverías a explicar. Añade una línea cuando:

• Claude comete el mismo error por segunda vez.
• Una review pilla algo que debería haber sabido de este repo.
• Tecleas la misma corrección que ya tecleaste la sesión pasada.
• Alguien nuevo en el equipo necesitaría ese mismo contexto para ser productivo.

Qué poner (y qué no)

Buen material —hechos que Claude debería tener en cada sesión:

# Proyecto

## Stack
- Next.js 16 (App Router), React 19, Tailwind v4.
- TypeScript estricto, sin `any`.

## Comandos
- Build: `pnpm build`
- Tests: `pnpm test`

## Convenciones
- Indentación 2 espacios.
- Async/await sobre `.then()`.

## Lo que NO quiero
- No añadas dependencias sin preguntar.
- No crees README ni docs salvo que lo pida.
- No hagas commit sin que te lo pida.

Sé concreto y verificable: "usa 2 espacios de indentación" funciona mucho mejor que "formatea bien el código".

Tamaño: apunta a menos de 200 líneas. Cuanto más largo, más contexto consume y peor lo sigue. Si crece, hay dos herramientas: partirlo por temas (lección 3 de este curso) o moverlo a una skill (lo ves en el curso de slash commands y skills). Lo que es un procedimiento de varios pasos no va aquí.

Genera un primer borrador con /init: Claude analiza tu repo y propone comandos, tests y convenciones que detecta. Si ya existe un CLAUDE.md, sugiere mejoras en vez de sobrescribir.

La regla de oro

Esto es lo que separa a quien domina Claude Code de quien pelea con él cada día:

Si Claude Code se equivoca dos veces en lo mismo, no se lo digas otra vez en el chat — escríbelo en CLAUDE.md.

La corrección que tecleas hoy y volverás a teclear mañana es, literalmente, una línea que le falta a tu contrato.

Verlo en cualquier momento

El comando /memory lista los CLAUDE.md, reglas y ficheros de auto memory cargados en la sesión, te deja activar o desactivar la auto memory, y abre cualquiera de esos ficheros para editarlos. Si dudas de si tu fichero se está cargando, ese es el sitio para comprobarlo.

Importante: CLAUDE.md es contexto que el modelo intenta seguir, no una regla que se imponga por la fuerza. Para barreras que se cumplen sí o sí (bloquear git push --force, por ejemplo) están los permisos y los hooks, en cursos posteriores. Cada cosa, su herramienta.

Qué llevas hasta aquí

• CLAUDE.md es un contrato que Claude lee en cada sesión: deja de repetirte.
• Añades una línea cada vez que corriges algo por segunda vez.
• Concreto y corto (< 200 líneas); /init te da un borrador; /memory lo abre.

En la siguiente lección: dónde colocar estos ficheros (hay cuatro niveles) y cómo encadenarlos con imports.

Fuente oficial: How Claude remembers your project