Divulgación progresiva y la estructura docs/

Una guía de museo

En un museo grande no lees todo lo que hay en la sala 1 antes de pasar a la 2. El plano de la entrada te dice qué hay en cada sala, y entras en la que te interesa. Eso es la divulgación progresiva: primero lo general, y el detalle cuando hace falta.

Un repositorio preparado para agentes funciona igual. El curso incluye un paquete avanzado basado en el enfoque de OpenAI, para cuando el harness mínimo se queda corto.

La estructura

AGENTS.md              # recepcionista: corto, enruta
ARCHITECTURE.md        # mapa del sistema y reglas de dependencia
docs/
├── design-docs/       # decisiones de diseño y creencias base
├── exec-plans/
│   ├── active/        # planes que dirigen el trabajo ahora
│   ├── completed/     # planes terminados (contexto futuro)
│   └── tech-debt-tracker.md
├── generated/         # material generado (p. ej. esquema de BD)
├── product-specs/     # comportamiento del producto y criterios
├── references/        # documentación externa útil para modelos
├── DESIGN.md  FRONTEND.md  PLANS.md
├── PRODUCT_SENSE.md  QUALITY_SCORE.md
└── RELIABILITY.md  SECURITY.md

No hay que copiarlo entero. El propio paquete advierte de que hay que empezar por el pack mínimo si el repo es pequeño y adaptarlo, no copiarlo a ciegas.

Cómo se conecta

El AGENTS.md de la plantilla actúa como mapa de enrutamiento: dice qué archivo leer para cada cosa, por ejemplo ARCHITECTURE.md para el mapa del sistema y reglas de dependencia, docs/PLANS.md para el ciclo de vida de los planes, docs/SECURITY.md para secretos y límites. Incluye también un flujo de inicio (confirmar la raíz, leer arquitectura, calidad y el plan activo, ejecutar la verificación base) y una definición de completado.

Dos archivos merecen mención:

• PLANS.md define cuándo hace falta un plan (trabajo que dura más de una sesión, toca varios subsistemas o tiene riesgos), y qué lleva: objetivo, alcance, ruta de verificación, riesgos, registro de progreso y decisiones abiertas. Los planes acabados pasan a completed/ para que los agentes los encuentren.
• QUALITY_SCORE.md puntúa cada dominio y capa con una escala A-D, de modo que se vea si el repo mejora o empeora con el tiempo.

Ejemplo: una decisión, un sitio

Siguiendo el procedimiento del pack para codificar conocimiento que está fuera del repo, la decisión «los pagos se reintentan 3 veces» podría acabar así:

<!-- docs/design-docs/pagos-reintentos.md -->
# Reintentos de pagos
Se reintenta hasta 3 veces con espera creciente. Más reintentos
duplicaban cobros en el proveedor. Ver docs/RELIABILITY.md.

Y en docs/design-docs/index.md se añade una línea que lo enlaza, para que se pueda encontrar.