Enseñarle tu repo

Paso a paso

1. El fallo primero. /clear (mesa nueva) y el pedido simple:

Corre los tests del repo y dime si la suite está sana.

Resultado esperado: la sesión nueva paga el peaje entero. Crea otro entorno, tropieza con el mismo problema del import que la sesión anterior ya resolvió, redescubre que hay que levantar la base para los tests de concurrencia. Cuenta las aprobaciones, los minutos y los tokens. El veredicto final da lo mismo; la lección es el peaje. A veces el propio agente lo confiesa al final: “puedo dejar algo armado para no repetir esto cada vez”.

Nota: Claude Code tiene memoria automática activada por defecto. Si ya trabajaste el Nivel 2 en esta máquina, puede que recuerde el comando correcto y el peaje no aparezca. Para ver el fallo limpio, borra la carpeta de auto-memory (/memory, tercera opción) antes de este paso.

2. El archivo. Tipea /init: genera el borrador del CLAUDE.md explorando el repo. Aprueba la creación. Si el borrador sale rico (trae las lecciones del peaje solas), solo agrega las reglas del equipo con el prompt siguiente; si sale genérico, el prompt hace todo el trabajo.

Completa el CLAUDE.md con lo que descubriste a los golpes corriendo la
suite (si ya lo anotaste, revísalo): el comando correcto de tests y por
qué pytest a secas falla, cómo se corren los tests de concurrencia, y el
entorno que hay que usar. Agrega estas reglas del equipo: jamás tocar
scripts/legacy_import.py sin hablar con Marcos, y correr la suite crítica
antes de cualquier build. Y cierra con una sección "Verification" con los
comandos reales de verificación del repo (tests unitarios, concurrencia,
stack local, build de imagen, y fmt y validate de infra), más dos reglas:
NUNCA terraform apply sin un plan aprobado, y NUNCA mutar producción
directamente.

Dos fuentes distintas: las lecciones las trae la propia sesión, que acaba de pagar el peaje; las reglas las pones tú, que eres el equipo. El archivo guarda lo sufrido y lo decretado.

3. La prueba. /clear y exactamente el mismo pedido del paso 1:

Corre los tests del repo y dime si la suite está sana.

Resultado esperado: la sesión nueva lee el CLAUDE.md y va directo, comando correcto a la primera. Su primera línea suele ser algo como “según lo indicado en el CLAUDE.md del repo”. Mismo modelo, mismo prompt, resultado distinto.

El mapa del contexto persistente

• CLAUDE.md global (~/.claude/CLAUDE.md): tus reglas personales, te siguen a todos los proyectos.
• CLAUDE.md del repositorio: va en git. El harness compartido: tu agente y el de tu colega se comportan igual.
• CLAUDE.local.md: tu contexto personal del proyecto, fuera de git.
• .claude/rules/: reglas modulares que aplican por rutas.
• Skills: procedimientos que se cargan cuando hacen falta (Nivel 4).
• Memoria automática: /memory muestra tres filas. Las dos primeras las escribes tú (proyecto y usuario); la tercera la escribe él solo. Ábrela en el proyecto donde llevas semanas: está llena y nunca la has mirado. Revisarla y limpiarla es mantenimiento, como rotar logs.

Dos reglas para que no se desordene: el CLAUDE.md solo contiene lo que el agente no puede inferir del repositorio; todo lo demás es ruido que ocupa mesa. Y CLAUDE.md no reemplaza un runbook: le dice al agente qué debe saber siempre y dónde encontrar el procedimiento (mira runbooks/).

Monorepos: un CLAUDE.md chico en la raíz con lo transversal, y uno por paquete con lo específico. Claude Code los carga anidados: el de la raíz siempre, el del paquete cuando trabaja ahí. Las rules por rutas, igual. Un repo gigante no se le enseña entero: se le enseña por capas. (Este repo es de un solo paquete, así que no hay demo; el mecanismo funciona igual.)

/doctor: cuando un CLAUDE.md no carga, una skill no aparece o un MCP no conecta, diagnostica el setup completo. Es el primer comando cuando algo “no funciona”.

Advertencia que vuelve en el Nivel 7: todo esto es contexto. Instrucciones que el modelo sigue. No son muros.

Comandos desbloqueados

• /init · borrador del CLAUDE.md.
• /memory · las tres memorias, incluida la automática.
• /doctor · diagnóstico de configuración.
• CLAUDE.md anidados y .claude/rules/ · contexto por capas.

Marcador: autonomía sube (recuerda solo) · control sube (tú decides qué recuerda).