¿Qué hace Generador de Contexto de Proyecto?
Crear o actualizar .claude/docs/project.md — la referencia concisa del proyecto que Claude carga en cada conversación. A diferencia de un README (escrito para humanos), project.md está escrito para Claude: denso, factual, sin prosa de marketing.
Por qué existe esta habilidad
.claude/docs/project.md se carga automáticamente en cada conversación de Claude a través de CLAUDE.md. Cuando falta o está desactualizado, Claude desperdicia turnos redescubriendo la pila tecnológica, los comandos de prueba y la arquitectura. Esta habilidad automatiza ese descubrimiento y produce un archivo de referencia preciso y compacto.
Flujo de trabajo
Paso 1: Analizar el código base
Ejecuta un análisis estructurado de tres fases para recopilar datos del proyecto. Etiqueta cada dato con un nivel de confianza: [confirmado] (leído del código fuente), [inferido-alto] (evidencia sólida), [inferido-bajo] (evidencia parcial) o [desconocido].
Consulta referencias/metodologia-de-analisis.md para acciones detalladas de herramientas, patrones glob/grep y plantillas de registro.
Fase 1 — Metadatos del Proyecto: Busca archivos de gestor de paquetes, plantillas de entorno, configuraciones de CI y archivos de herramientas. Extrae: nombre del proyecto, lenguaje, versión de Python, dependencias (con propósitos), scripts/comandos, variables de entorno, etapas de CI, marcadores de prueba.
Fase 2 — Escaneo de Arquitectura: Busca todos los archivos fuente. Identifica puntos de entrada, construye el grafo de importaciones, clasifica módulos (núcleo/hoja/orquestador), e identifica el patrón de arquitectura. Lee los archivos de configuración referenciados por el código fuente.
Fase 3 — Fuentes de Datos e Infraestructura: Identifica fuentes de datos externas (bases de datos, APIs, archivos), destinos de salida (archivos, cargas, APIs), estructura de pruebas y jerarquía de excepciones personalizadas.
Paso 2: Hacer preguntas aclaratorias
Después del análisis, pregunta al usuario sobre elementos [inferido-bajo] y [desconocido]. Mantén el enfoque — no preguntes sobre cosas que ya sabes. Brechas comunes:
- Propósito del proyecto: ¿Qué problema resuelve? (si no es obvio por el código)
- Fuentes de datos: ¿Qué sistemas alimentan datos? ¿Qué recibe la salida?
- Despliegue: ¿Cómo/dónde se ejecuta? (local, programado, nube)
Si el código base es sencillo, puede que solo necesites 1-2 preguntas — o ninguna.
Paso 3: Generar project.md
Escribe el archivo usando la estructura a continuación. Si .claude/docs/project.md ya existe, confirma con el usuario antes de sobrescribir.
Estructura de Salida
El project.md generado debe seguir esta estructura. Escala la profundidad según el proyecto — los proyectos pequeños pueden omitir secciones, los complejos pueden añadir subsecciones.
# {Nombre del Proyecto} — Contexto del Proyecto
{Descripción de una oración: qué es, qué hace, tecnología clave.}
## Pila Tecnológica
- **{Lenguaje/Runtime}** — {restricción de versión si se conoce}
- **{Framework}** — {para qué se usa}
- **{Biblioteca Clave}** — {propósito}
- ...lista con viñetas, negrita en el nombre de la herramienta, anota el propósito
## Diseño del Proyecto
```text
{árbol de directorios anotado — una frase corta por entrada}
Flujo de Datos
{diagrama ASCII mostrando el pipeline origen → transformación → salida}
Fuentes de Datos
{NOMBRE_FUENTE}— {lo que proporciona}- ...para bases de datos, APIs, archivos locales, etc.
Marcadores de Prueba
{comando de prueba}— {lo que ejecuta}{nombre del marcador}— {lo que habilita}
Patrones de Arquitectura Clave
- {Nombre del Patrón} (
{archivo}): {explicación de una oración} - ...solo patrones no obvios que merezcan ser destacados
---
## Pautas de Escritura
- **Denso sobre verboso.** Cada línea debe merecer su lugar. Claude no necesita motivación o contexto — solo datos.
- **Específico sobre genérico.** "Ejecuta `uv run pytest -m 'not snowflake'`" es mejor que "Ejecuta las pruebas excluyendo dependencias externas."
- **Una oración por patrón.** Los patrones de arquitectura deben tener una línea cada uno — nombre, archivo, explicación.
- **Comandos reales.** Copia comandos de prueba de `pyproject.toml` o configuraciones de CI, no versiones parafraseadas.
- **Anota dependencias.** No te limites a listar `polars` — di `polars — DataFrames de alto rendimiento`.
- **Las fuentes de datos son críticas.** Claude necesita conocer los sistemas externos que existen. Enumera cada base de datos, API y fuente de archivos.
- **Mantenlo por debajo de 100 líneas.** Si project.md supera las ~100 líneas de contenido, está demasiado detallado — mueve los detalles a documentación dedicada y enlázalos.
## Salida
Guarda el archivo como `.claude/docs/project.md` (crea el directorio si es necesario). Si el archivo ya existe, muestra al usuario un resumen de diferencias antes de sobrescribir.
Después de generar project.md, verifica si `CLAUDE.md` lo referencia. Si no, sugiere añadir una línea como:
```markdown
Consulta [.claude/docs/project.md](.claude/docs/project.md) para detalles específicos del proyecto (pila tecnológica, arquitectura, marcadores de prueba).