Dibuja el mapa del repo

Llegar a una ciudad sin mapa

Llegas a una ciudad que no conoces. Sin mapa, adivinas calles, pierdes tiempo y a veces te metes en callejones sin salida. Con un mapa pequeño pero fiable, llegas.

Cada sesión nueva de un agente es llegar a esa ciudad. Tu repositorio es la ciudad, y falta saber si tiene mapa.

La prueba de arranque en frío

Abre una sesión completamente nueva, sin explicarle nada de palabra, solo con lo que hay en el repo, y comprueba si puede responder cinco preguntas:

Donde el mapa está en blanco, el agente adivina. Las malas conjeturas se convierten en bugs, y adivinar gasta contexto. Y como cada sesión empieza de cero, vuelve a adivinar todo cada vez. Dibujar bien el mapa sale más barato.

Cuatro principios para dibujarlo

1. El conocimiento vive junto al código. Una regla sobre la API va al lado del código de la API, no en un documento global gigante. Como las etiquetas de estantería en una biblioteca.
2. Un archivo de entrada estándar. AGENTS.md (o CLAUDE.md) es la página de aterrizaje. Debe responder rápido qué es el proyecto, cómo se ejecuta y cómo se verifica. Con 50-100 líneas basta.
3. Mínimo pero completo. Si quitar una regla no cambia las decisiones del agente, sobra. Pero cada pregunta de la prueba debe tener respuesta.
4. Se actualiza con el código. Si la documentación del módulo vive en su carpeta, la ves al tocar el código y te acuerdas de actualizarla.

Un ejemplo de estructura

project/
├── AGENTS.md            # entrada: resumen, comandos, restricciones duras
├── src/
│   ├── api/
│   │   └── ARCHITECTURE.md   # decisiones de la capa API
│   └── db/
│       └── CONSTRAINTS.md    # restricciones de la base de datos
├── PROGRESS.md          # hecho, en curso, bloqueado
└── Makefile             # setup, test, lint, check

La checklist del curso añade preguntas útiles para repasar tu mapa: ¿qué producto se construye?, ¿qué debe hacer la app para los usuarios?, ¿cómo se inicia?, ¿cómo se comprueba que está sana?, ¿qué trabajo está en curso?, ¿qué estándares de calidad importan?