Pack de contexto para Claude Code: 6 docs + el prompt que los genera

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.

Nota de uso honesta

El prompt los genera leyendo tu proyecto, pero los revisas tú antes de fiarte. Claude propone, tú validas. Sobre todo en decisiones.md y errores-conocidos.md: ahí va conocimiento que está en tu cabeza, no siempre en el código, así que rellena los [PENDIENTE] a mano. Y reléelos cuando el proyecto cambie de forma: un doc de contexto desactualizado miente con más confianza que uno que no existe.

La regla de oro

El mejor contexto no es el que más escribes, es el que no tienes que volver a escribir. Genéralos una vez, corrígelos, y actualiza solo el doc del eje que cambió.

---

Sígueme para más trucos con Claude Code e IA → @pabloinpublic

Waitlist de la comunidad → pabloinpublic.com