6 documentos (.md) para darle contexto a tus agentes

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

## 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

# 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.]

# 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 / ...]

# 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:** [...]

# 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]

# 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.]

# Troubleshooting

> Las trampas que ya te mordieron. 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"]

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.