Contexto de Código Base - Documentación

Contexto del Código Base - Documentación

Genera un CLAUDE.md compacto en la raíz del repositorio, junto con un conjunto de archivos de referencia detallados en .claude/docs/.

El objetivo no es "documentar el proyecto". Es: hacer que un agente futuro sea efectivo en su primer turno, gastando la menor cantidad de tokens posible. CLAUDE.md se carga en el contexto en cada turno, para siempre. Cada línea es un impuesto. Una línea gana su lugar solo si cambia lo que un agente hace en una tarea que aún no ha visto. Todo lo demás pertenece a .claude/docs/, y se carga solo cuando es relevante.

Esa compensación impulsa cada regla a continuación.

Flujo de Trabajo

Sigue este orden. Escribir CLAUDE.md primero es el fallo más común: produce un archivo de sonido plausible lleno de suposiciones, y luego los documentos se escriben para coincidir con las suposiciones en lugar del código.

1. Inspeccionar el repositorio mecánicamente (comandos abajo).
2. Leer los puntos de entrada, la configuración y una porción representativa del código fuente.
3. Escribir .claude/docs/*.md — aquí reside el detalle.
4. Escribir CLAUDE.md al final — es un índice sobre lo que acabas de aprender.
5. Verificar — contar líneas, cada comando, cada archivo:línea.

Paso 1 — Inspección

Ejecuta estos antes de leer nada. Cuestan poco y evitan suposiciones incorrectas sobre el tamaño, la combinación de idiomas y las herramientas.

# Forma y escala
git ls-files | wc -l
git ls-files | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -40
git ls-files | grep -oE '\.[a-z0-9]+$' | sort | uniq -c | sort -rn | head -20

# Herramientas y puntos de entrada (lee cada archivo que esto encuentra)
ls -a
git ls-files | grep -iE '(package\.json|pyproject\.toml|setup\.py|requirements.*\.txt|Cargo\.toml|go\.mod|pom\.xml|build\.gradle|Gemfile|composer\.json|pubspec\.yaml|Makefile|justfile|Taskfile|docker-compose|Dockerfile)'
git ls-files '.github/workflows/*' '.gitlab-ci.yml' '.circleci/*'

# Documentos existentes — léelos, codifican la intención que no se puede inferir del código
git ls-files | grep -iE '(readme|contributing|architecture|adr|docs/)' | head -30

# La actividad reciente muestra qué partes del repositorio están realmente activas
git log --oneline -15
git log --pretty=format: --name-only -n 200 | sort | uniq -c | sort -rn | head -20

Nota cualquier cosa que la inspección no encuentre. Un repositorio sin configuración de CI y sin directorio de pruebas es un hallazgo real, no una brecha que cubrir.

Paso 2 — Leer

Lee, en este orden:

• Archivos de manifiesto (package.json, pyproject.toml, …) — de principio a fin, incluyendo la sección de scripts/tareas. Aquí es donde viven los comandos reales.
• Archivos de flujo de trabajo de CI — los comandos que ejecuta CI son los comandos que realmente funcionan.
• README.md y cualquier CONTRIBUTING.md / docs/ — para el por qué, que el código no puede decirte.
• Los puntos de entrada de la aplicación, luego 5–15 archivos fuente representativos distribuidos en los directorios principales.

Usa subagentes paralelos para el paso de lectura de código fuente cuando el repositorio es grande y los subagentes están disponibles — uno por directorio principal, cada uno informando qué hace ese directorio, qué patrones usa y los anclajes archivo:línea para esos patrones. Esto es más rápido y mantiene los volcados de archivos sin procesar fuera del contexto principal.

Mientras lees, mantén una lista en ejecución de patrones candidatos con la ubicación exacta ruta/al/archivo.ts:142 donde viste cada uno. Necesitarás estos anclajes más tarde, y volver para encontrarlos es costoso.

Paso 3 — Escribir .claude/docs/

Crea solo los archivos que el código base realmente soporta. Un documento vacío o inflado es peor que uno faltante, porque le enseña al agente a desconfiar de todo el conjunto.

Archivo	Crear cuando	Contiene
architectural_patterns.md	Siempre (a menos que el repositorio sea trivialmente pequeño)	Decisiones estructurales recurrentes: DI, gestión de estado, manejo de errores, límites de módulos, convenciones de diseño de API, reglas de capas
testing_strategy.md	Existen pruebas	Frameworks, dónde viven las pruebas, convenciones de fixtures/fábricas, cómo ejecutar una prueba frente a la suite, qué está simulado vs. real
build_and_deploy.md	Las herramientas de construcción o CI no son obvias	Pipeline de construcción, variables de entorno y dónde se declaran, artefactos, flujo de lanzamiento/despliegue, problemas de configuración de desarrollo local
data_model.md	Existen datos persistentes, esquemas o migraciones	Entidades y relaciones principales, ubicación de esquemas/migraciones y flujo de trabajo, capa de validación
api_reference.md	El proyecto expone o consume una API significativa	Organización de rutas/endpoints, convenciones de solicitud/respuesta, autenticación, versionado, forma de errores

Puedes agregar un archivo específico del dominio cuando un código base tenga un subsistema grande que no encaje en estos (realtime_sync.md, billing.md). Prefiere un número pequeño de archivos sustanciales sobre muchos archivos delgados.

La regla de evidencia de múltiples archivos

Esta es la regla que separa un documento de patrones útil de uno alucinado.

Documenta un patrón solo si lo has visto en al menos tres archivos separados, y cita al menos dos de ellos. Una abstracción inteligente aislada es una trivia. Una convención repetida en todo el código base es lo que un nuevo agente debe seguir para escribir código que encaje.

Cuando encuentres algo que parece un patrón pero aparece solo una vez, elimínalo o usa grep para confirmar que se generaliza:

rg -n 'useAppDispatch' --stats           # ¿qué tan extendido está?
rg -l 'implements Repository' | head     # ¿qué archivos comparten esta forma?

Si una convención se aplica de manera inconsistente — la mitad del código base lo hace de una manera, la otra mitad de otra — dilo explícitamente y señala cuál es más nueva (git log en los archivos te lo dice). Un agente que sabe que un código base está en medio de una migración escribe mejor código que uno que asume uniformidad.

Referencia por anclaje, no por fragmento

Escribe Ver src/services/base.py:34 en lugar de pegar la clase. Los fragmentos se vuelven obsoletos en el momento en que alguien edita el archivo, y un fragmento obsoleto engaña activamente, mientras que un número de línea obsoleto vale claramente la pena volver a verificar. También mantiene los documentos lo suficientemente cortos para ser leídos.

Incluye el nombre del símbolo junto con la línea para que el anclaje sobreviva a ediciones pequeñas: PaymentProcessor.execute — src/billing/processor.py:88.

Deja el estilo de código en paz

El usuario ejecuta linters y formateadores. No documentes sangría, estilo de comillas, longitud de línea, orden de importaciones o nomenclatura. Estos se aplican mecánicamente; reiterarlos en un archivo siempre cargado gasta contexto para duplicar una herramienta. Documenta convenciones que un linter no puede aplicar: qué capa puede importar qué, cuándo agregar una migración, dónde se registra una nueva ruta.

Paso 4 — Escribir CLAUDE.md

Menos de 150 líneas, estrictamente. Usa esta estructura:

# <Nombre del Proyecto>

<2-4 oraciones: qué es este proyecto y a quién/ qué sirve. El POR QUÉ —
el problema que resuelve. Esta es la parte que no se puede inferir del código,
por lo que es la parte que vale la pena escribir con más cuidado.>

## Stack Tecnológico

<Lista compacta: lenguaje + versión, framework, base de datos, infraestructura clave.
Solo lo que cambia cómo se escribe el código. Omite el volcado de dependencias transitivas.>

## Estructura del Proyecto

<Tabla o lista de directorios de nivel superior, una línea cada uno, diciendo qué
pertenece allí y — cuando no sea obvio — qué no.>

## Comandos

<Solo comandos verificados y universalmente útiles: instalar, dev, construir, probar,
probar-un-solo-archivo, lint, verificación de tipos. Anota el gestor de paquetes si no es
el predeterminado para el ecosistema.>

## Convenciones

<3-8 líneas, solo reglas que se aplican en todo el repositorio y que un linter no puede
capturar. Si una regla es específica de un subsistema, pertenece a un archivo de docs en su lugar.>

## Documentación Adicional

Lee estos cuando la tarea lo requiera — no los cargues de forma preventiva.

- `.claude/docs/architectural_patterns.md` — <cuándo leerlo>
- `.claude/docs/testing_strategy.md` — <cuándo leerlo>

Dos cosas hacen que la sección "Documentación Adicional" funcione o falle:

• Cada entrada dice cuándo leerlo, no qué contiene. "Leer antes de agregar un endpoint o cambiar una forma de respuesta" dirige correctamente a un agente; "documenta la API" no lo hace.
• La lista es el único lugar donde se referencia detalle especializado. Si te encuentras explicando la configuración de pruebas en CLAUDE.md y en testing_strategy.md, elimínalo de CLAUDE.md.

Consulta references/templates.md para ver un ejemplo completo de CLAUDE.md y cada archivo de documentación.

Paso 5 — Verificar

No te saltes esto. Cada modo de fallo de esta tarea es una falsedad con sonido de confianza, y cada uno es barato de detectar.

wc -l CLAUDE.md                          # debe ser < 150

Luego:

• Ejecuta cada comando que escribiste, o al menos confirma que cada uno existe en el manifiesto / configuración de CI. Un npm test en CLAUDE.md que no está en package.json desperdiciará el tiempo de un agente en cada sesión futura. Si no puedes ejecutar un comando, márcalo como leído desde el código fuente en lugar de verificado.
• Verifica aleatoriamente cada archivo:línea — abre algunos y confirma que el símbolo citado está allí.
• Vuelve a leer CLAUDE.md en frío, como un agente que ve este repositorio por primera vez. Elimina cualquier línea que no cambie lo que harías. Los consejos genéricos ("escribe código limpio", "maneja los errores apropiadamente") son los infractores habituales.
• Informa el recuento final de líneas y la lista de archivos creados.

Si CLAUDE.md tiene más de 150 líneas, corta en lugar de comprimir — mueve una sección completa a un archivo de documentación y deja una línea de índice atrás. Apretar la prosa para que quepa produce un archivo denso que nadie analiza.

Trabajar con un CLAUDE.md existente

Si ya existe uno, no sobrescribas a ciegas. Léelo primero, luego verifícalo contra el código actual: comandos que ya no existen, directorios que fueron renombrados, patrones de los que se migró. Conserva cualquier instrucción escrita a mano que codifique una preferencia humana que no puedas derivar del código ("nunca toques el SDK empaquetado", "pregunta antes de agregar una dependencia") — esas son las líneas de mayor valor en el archivo y las más fáciles de destruir. Muestra al usuario qué estás eliminando y por qué antes de cortar algo sustancial.