Si le das a Claude un contexto vago, trabaja a ciegas: se inventa la estructura de tu proyecto, rehace cosas ya decididas y tropieza dos veces con el mismo error. La solución no es escribir un documento enorme a mano. Es tener 6 docs especializados, uno por tipo de trabajo, y un prompt que te los genera leyendo tu repo.
Aquí tienes las 6 plantillas para rellenar (o dejar que el prompt del final las rellene por ti).
Cómo enchufar estos docs
Crea una carpeta docs/contexto/ (o donde prefieras) y mete un archivo por doc. Luego los referencias desde tu archivo de contexto raíz para que Claude los lea al arrancar:
## Contexto del proyecto - Arquitectura → @docs/contexto/arquitectura.md - Convenciones → @docs/contexto/convenciones.md - Decisiones → @docs/contexto/decisiones.md - Glosario → @docs/contexto/glosario.md - Flujo de trabajo → @docs/contexto/flujo-de-trabajo.md - Errores conocidos → @docs/contexto/errores-conocidos.md
Un doc por eje hace que Claude cargue solo lo que necesita y que tú actualices solo lo que cambia.
1 · Arquitectura
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 · Convenciones
Para que escriba código como tú, 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 · Decisiones
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 · Glosario y entidades
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 · Flujo de trabajo
Para que no se salte pasos al hacer cambios.
# Flujo de trabajo ## Antes de tocar nada 1. [Ej: leer el doc de decisiones] 2. [Ej: crear rama desde main] ## Para hacer un cambio 1. [Ej: tests primero] 2. [Ej: implementar] 3. [Ej: pasar linter y typecheck] ## 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 · Errores conocidos
Para que no tropiece dos veces con el mismo agujero.
# Errores conocidos (gotchas) > Las trampas que ya te han mordido. Cada una ahorra una hora de Claude (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"]
El prompt que genera los 6 docs
En vez de rellenarlos a mano, suelta esto a Claude Code dentro de tu proyecto. Inspecciona el repo y te deja los 6 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/contexto/, uno por archivo: 1. arquitectura.md — stack, mapa de carpetas, flujo de datos, qué NO existe. 2. convenciones.md — estilo, naming, patrones que usamos y los prohibidos, tests, commits. 3. decisiones.md — decisiones técnicas que detectes en el código/commits, con su porqué y lo descartado. 4. glosario.md — términos del dominio, entidades principales y siglas internas. 5. flujo-de-trabajo.md — pasos para hacer un cambio, checklist de "terminado" y deploy. 6. errores-conocidos.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.
Cuando termine, referéncialos desde tu archivo de contexto raíz (ver arriba) y Claude los carga solo.