Documentación para agentes: plantillas y buenas prácticas
Guía para recurrir cuando haya que explicar cómo documentar un proyecto para que Claude Code, Cursor u otro agente no trabaje a ciegas.
Si le das contexto vago, se inventa la estructura, rehace decisiones ya cerradas y tropieza dos veces con el mismo error. La solución no es un README gigante: son 6 docs especializados (uno por tipo de trabajo) y, si querés, un prompt que los genera leyendo el repo.
Basado en el pack de contexto para Claude Code de PabloInPublic, adaptado a nombres en inglés y a la separación AGENTS.md / CLAUDE.md que usamos en este repo.
Cuándo usar esta guía
- Arrancás un repo nuevo y querés dejar el contexto listo para agentes.
- Alguien pregunta "¿cómo documentamos esto para la IA?".
- Un agente repite errores ya resueltos o "corrige" decisiones intencionales.
- Necesitás regenerar o actualizar un doc concreto sin reescribir todo.
La estructura
AGENTS.md ← instrucciones genéricas (cualquier agente)
CLAUDE.md ← índice: importa AGENTS.md + los 6 docs
docs/
├── ARCHITECTURE.md
├── CONVENTIONS.md
├── DECISIONS.md
├── GLOSSARY.md
├── WORKFLOW.md
└── TROUBLESHOOTING.md
CLAUDE.md no repite contenido: actúa como índice con @ruta/al/archivo.md (Claude Code lo carga al arrancar):
## Contexto del proyecto
- Arquitectura → @docs/ARCHITECTURE.md
- Convenciones → @docs/CONVENTIONS.md
- Decisiones → @docs/DECISIONS.md
- Glosario → @docs/GLOSSARY.md
- Flujo de trabajo → @docs/WORKFLOW.md
- Troubleshooting → @docs/TROUBLESHOOTING.md
Un doc por eje: el agente carga solo lo que necesita y vos actualizás solo lo que cambió.
AGENTS.md vs CLAUDE.md
| Archivo | Para qué |
|---|---|
AGENTS.md | Cómo correr, lintear y buildear el proyecto; gotchas de setup. Agnóstico de herramienta (Cursor, Claude Code, etc.). |
CLAUDE.md | Índice específico de Claude Code: apunta a AGENTS.md + los 6 docs de contexto. |
No mezcles "cómo hacer npm install" con "por qué no usamos ORM".
1 · ARCHITECTURE.md
Para que no se invente la estructura del proyecto.
# Arquitectura
## En una frase
[Qué es el proyecto y qué hace, sin marketing.]
## Stack
- Lenguaje / runtime: [...]
- Framework principal: [...]
- Base de datos: [...]
- Servicios externos: [...]
## Mapa de carpetas
- `src/[...]` → [qué vive aquí]
- `src/[...]` → [qué vive aquí]
- `[...]` → [qué vive aquí]
## Flujo de datos
[De dónde entra una petición, por dónde pasa, dónde acaba. 3-5 líneas.]
## Lo que NO existe (y no hay que crear)
- [Ej: no hay capa de cache, no usamos ORM, etc.]
2 · CONVENTIONS.md
Para que escriba código como vos, no como la media de internet.
# Convenciones de código
## Estilo
- Formato: [Prettier / gofmt / Black / ...]
- Naming: [camelCase para variables, kebab-case para archivos, ...]
- Imports: [orden, alias, absolutos vs relativos]
## Patrones que SÍ usamos
- [Ej: server actions en vez de API routes]
- [Ej: errores como valores, no excepciones]
## Patrones PROHIBIDOS
- [Ej: nada de `any` en TS]
- [Ej: nada de lógica de negocio en componentes]
## Tests
- Dónde van: [...]
- Qué se testea sí o sí: [...]
## Commits
- Formato: [conventional commits / ...]
3 · DECISIONS.md
Para que no rehaga lo ya cerrado ni reabra debates muertos.
# Decisiones tomadas
> Una entrada por decisión. Lo importante es el "por qué" y el "qué descartamos".
## [Fecha] · [Título de la decisión]
- **Decisión:** [qué se eligió]
- **Por qué:** [razón]
- **Descartado:** [alternativas que NO usamos y por qué]
- **Estado:** [vigente / revisar en X / obsoleta]
## [Fecha] · [Otra decisión]
- **Decisión:** [...]
- **Por qué:** [...]
- **Descartado:** [...]
- **Estado:** [...]
4 · GLOSSARY.md
Para que sepa qué es cada cosa tuya cuando la nombras.
# Glosario y entidades
## Términos del dominio
- **[Término]** → [qué significa en ESTE proyecto, no en general]
- **[Término]** → [...]
## Entidades principales
- **[Entidad]** → [qué representa, campos clave, con qué se relaciona]
- **[Entidad]** → [...]
## Siglas y nombres internos
- **[Sigla / nombre de módulo]** → [a qué se refiere]
5 · WORKFLOW.md
Para que no se salte pasos al hacer cambios.
# Flujo de trabajo
## Antes de tocar nada
1. [Ej: leer DECISIONS.md y TROUBLESHOOTING.md]
2. [Ej: crear rama desde main]
## Para hacer un cambio
1. [Ej: implementar]
2. [Ej: pasar linter y typecheck]
3. [Ej: verificar en el browser]
## Antes de dar algo por terminado
- [ ] [Ej: `npm run build` pasa]
- [ ] [Ej: tests verdes]
- [ ] [Ej: no quedan `console.log`]
## Deploy
[Cómo se publica: comando, rama, automatismo. 2-3 líneas.]
6 · TROUBLESHOOTING.md
Para que no tropiece dos veces con el mismo agujero.
# Troubleshooting
> Las trampas que ya te han mordido. Cada una ahorra una hora de agente (y tuya).
## [El síntoma raro]
- **Pasa cuando:** [...]
- **Causa real:** [...]
- **Solución:** [...]
## [Otra trampa]
- **Pasa cuando:** [...]
- **Causa real:** [...]
- **Solución:** [...]
## Cosas que parecen rotas pero son a propósito
- [Ej: el warning X es esperado, no lo "arregles"]
Prompt para generar los 6 docs
Prompt original de PabloInPublic, adaptado a los nombres de archivo de esta guía.
En vez de rellenarlos a mano, pegá esto en Claude Code / Cursor dentro del proyecto. Inspecciona el repo y deja los archivos rellenados:
Lee mi proyecto entero (estructura de carpetas, dependencias,
código, tests, README y commits recientes) y genera 6 documentos
de contexto en docs/, uno por archivo:
1. ARCHITECTURE.md — stack, mapa de carpetas, flujo de datos, qué NO existe.
2. CONVENTIONS.md — estilo, naming, patrones que usamos y los prohibidos, tests, commits.
3. DECISIONS.md — decisiones técnicas que detectes en el código/commits, con su porqué y lo descartado.
4. GLOSSARY.md — términos del dominio, entidades principales y siglas internas.
5. WORKFLOW.md — pasos para hacer un cambio, checklist de "terminado" y deploy.
6. TROUBLESHOOTING.md — gotchas que se intuyan del código, tests y comentarios.
Reglas:
- Básate SOLO en lo que veas en el repo. No inventes.
- Donde no haya información suficiente, deja un hueco marcado [PENDIENTE: ...]
en vez de rellenar a ciegas.
- Sé concreto y breve: cada doc se lee en menos de 2 minutos.
Después referencialos desde CLAUDE.md (sección de arriba) y el agente los carga solo.
Cómo mantenerlos
- Claude propone, vos validás. Sobre todo
DECISIONS.mdyTROUBLESHOOTING.md: ahí va conocimiento que está en tu cabeza, no siempre en el código. Rellená los[PENDIENTE]a mano. - Actualizá solo el eje que cambió. Si cambió el deploy, tocá
WORKFLOW.md/TROUBLESHOOTING.md, no reescribas los seis. - Un doc desactualizado miente con más confianza que uno que no existe. Si algo quedó obsoleto, marcá el estado o borrá la entrada.
La regla de oro
El mejor contexto no es el que más escribís: es el que no tenés que volver a escribir. Generá una vez, corregí, y actualizá solo el doc del eje que cambió.
Documentá lo que no es obvio leyendo el código: el porqué de una decisión, un error ya resuelto, o una convención que existe porque algo salió mal sin ella.