Cuando Claude Code trabaja sin un contexto sólido, improvisa: deduce estructuras que no existen, reabre decisiones ya cerradas y repite errores que el proyecto ya había resuelto. La solución no es crear un único documento gigantesco, sino dividir el contexto en 6 piezas especializadas y generar cada una automáticamente leyendo tu repositorio.
Este pack reúne esas 6 plantillas y el prompt capaz de generarlas de forma autónoma.
Cómo integrar estos documentos en tu proyecto
Crea la carpeta docs/contexto/ (o la ruta que prefieras).
Guarda dentro un archivo por cada documento.
Desde tu archivo de contexto principal, referencia cada uno para que Claude los cargue al iniciar:
Código
## 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
Trabajar por ejes evita ruido, reduce inventos y te permite actualizar solo lo que realmente cambia.
1. Arquitectura
Documento para que Claude entienda la estructura real del proyecto y no la imagine.
Incluye:
Descripción breve del proyecto
Stack técnico
Mapa de carpetas
Flujo de datos
Lista de elementos que no existen y no deben crearse
2. Convenciones
Guía para que Claude escriba código como tú, no como la media de internet.
Incluye:
- Estilo y formato
- Reglas de naming
- Organización de imports
- Patrones permitidos
- Patrones prohibidos
- Criterios de testing
- Formato de commits
3. Decisiones técnicas
Evita que Claude reabra debates ya resueltos o proponga alternativas descartadas.
Incluye por cada decisión:
- Qué se eligió
- Por qué
- Qué alternativas se descartaron
- Estado actual (vigente, revisar, obsoleta)
4. Glosario y entidades
Para que Claude entienda tu lenguaje interno y tus conceptos de dominio.
Incluye:
- Términos clave del proyecto
- Entidades principales y sus relaciones
- Siglas, abreviaturas y nombres internos
5. Flujo de trabajo
Guía operativa para que Claude siga tus pasos y no se salte ninguno.
Incluye:
Qué revisar antes de tocar código
Pasos para implementar un cambio
Checklist de finalización
Proceso de deploy
6. Errores conocidos
El documento que más tiempo ahorra: evita que Claude tropiece con los mismos problemas.
Incluye por cada “trampa”:
Síntoma
Causa real
Solución
Advertencias o comportamientos “que parecen errores pero no lo son”
El prompt que genera automáticamente los 6 documentos
En lugar de rellenarlos a mano, puedes pedirle a Claude Code que lea tu repositorio completo y genere los 6 archivos dentro de docs/contexto/.
El prompt:
Analiza estructura, dependencias, código, tests, README y commits recientes
Crea los 6 documentos con la información real del proyecto
Deja marcadores [PENDIENTE: ...] cuando no haya datos suficientes
Mantiene cada documento breve y concreto (lectura < 2 min)
Después solo tienes que revisarlos, corregir lo necesario y enlazarlos desde tu archivo de contexto raíz.
Uso recomendado
El generador automatiza el 80%, pero la validación final es tuya. Especialmente en:
decisiones.md
errores-conocidos.md
Ahí suele haber conocimiento tácito que no siempre está en el código.
Actualiza solo el documento del eje que cambie. Un contexto desactualizado es peor que no tener contexto.