project-docs: el framework que le da memoria y estructura a tus agentes de IA
El problema real no es la capacidad
Si usás Claude Code o Codex para escribir código, probablemente ya te pasó: el agente es técnicamente capaz de resolver el problema, pero lo resuelve mal porque no entiende el contexto. Adivina la arquitectura. Ignora convenciones del proyecto. Pierde continuidad entre sesiones. Te genera un componente de clase en un proyecto que usa hooks, o toca un módulo que estaba explícitamente fuera de scope.
El problema no es que el agente sea tonto. El problema es que le falta un mapa.
project-docs es ese mapa. Un sistema de documentación satelital que se instala en cualquier repo y le da a los agentes de IA contexto estructurado sobre tu proyecto: qué es, cómo está construido, qué convenciones seguir, qué no tocar, y qué hacer cuando hay ambigüedad.
Qué es project-docs
Es un directorio de documentación con una estructura fija que se clona dentro de tu proyecto. Tiene 8 carpetas temáticas que cubren desde la visión del producto hasta un registro de errores recurrentes. Pero lo interesante no es la documentación en sí — es el sistema de agentes y reglas que la consume.
La premisa central es: los agentes no necesitan más libertad, necesitan un mapa mejor. En vez de darle al agente acceso total y esperar que descubra todo solo, le das documentos bien definidos que le dicen exactamente qué necesita saber para cada tipo de tarea.
Arquitectura de dos capas
El diseño más inteligente de project-docs es su arquitectura de dos capas. El problema que resuelve es concreto: Claude Code autodescubre su configuración desde la raíz del repo (CLAUDE.md, .claude/agents/), pero project-docs vive en un subdirectorio. Si la config queda adentro de project-docs/, los agentes nunca la encuentran.
La solución:
Capa 1 — Contenido de documentación vive dentro de project-docs/. Es la base de conocimiento que los agentes leen:
project-docs/├── product/ # Visión, scope, roadmap├── architecture/ # Overview del sistema, módulos, ADRs, dependencias├── context/ # Tech stack, convenciones, estado actual, issues conocidos├── references/ # Mapa del repo, archivos clave, flujos críticos├── plans/ # Planes de implementación├── sessions/ # Logs de sesión de trabajo├── handoffs/ # Transferencias entre agentes└── memory/ # Errores recurrentes, changelog con impactoCapa 2 — Configuración de agentes vive en la raíz del repo host. El script de bootstrap copia templates desde project-docs/scaffold/ hacia la raíz, reemplazando placeholders como {{PROJECT_NAME}} y {{PROJECT_DOCS_PATH}} con valores reales del proyecto.
Después de correr el bootstrap, tu repo queda así:
mi-proyecto/├── CLAUDE.md # Instrucciones master para Claude Code (generado)├── AGENTS.md # Política de routing para Codex (generado)├── .claude/agents/ # 6 definiciones de subagentes (generado)├── .claude/rules/ # 4 conjuntos de reglas (generado)├── .agents/skills/ # 6 skills de Codex (generado)└── project-docs/ # La documentación real del proyectoContext loading: el truco de los tokens
Uno de los problemas más subestimados de trabajar con agentes es el desperdicio de tokens. Si le das al agente toda la documentación, se pierde en el ruido y se olvida de lo importante. Si no le das nada, adivina.
project-docs resuelve esto con una política de carga de contexto explícita:
| Categoría | Archivos | Cuándo |
|---|---|---|
| Siempre leer | VISION.md, TECH_STACK.md, CONVENTIONS.md | Cada tarea, sin excepción |
| Leer cuando sea relevante | SCOPE.md, KNOWN_ISSUES.md, CRITICAL_FLOWS.md, planes activos | Solo si la tarea toca esas áreas |
| Nunca cargar por defecto | Sesiones históricas, planes completados, memoria | Solo por pedido explícito |
Cada archivo de documentación tiene un campo read_policy en su frontmatter YAML que hace esta política legible por máquina. El CLAUDE.md generado traduce esta política en instrucciones concretas para el agente.
Los 6 roles de agentes
El sistema define 6 roles con responsabilidades exactas, formatos de salida definidos, y restricciones explícitas. Cada rol existe como subagente de Claude Code (.claude/agents/) y como skill de Codex (.agents/skills/):
Planner — Convierte objetivos en planes de implementación. Es read-only: tiene prohibido escribir o editar archivos. Su salida es un plan estructurado con scope, riesgos, tareas ordenadas, y checkpoints humanos.
Implementer — Ejecuta cambios de código acotados según el plan activo. Tiene una regla fundamental: hacer el cambio coherente más pequeño posible. Prohibido expandir scope sin documentar la razón. Prohibido refactorizar archivos no relacionados.
Tester — Define la estrategia de validación mínima suficiente. Tiene un modelo de 4 niveles: sin tests (para cambios triviales), unit, integration, y E2E. También es read-only.
Reviewer — Revisa el trabajo completado. Emite uno de tres veredictos: Aprobado, Aprobado con Cambios, o Rechazado. Rechaza automáticamente si se cambia comportamiento sin validación, si hay refactors no relacionados, o si se viola la arquitectura sin un ADR.
Docs Maintainer — Mantiene la documentación sincronizada con la realidad del código. Crea notas de sesión, handoffs, y actualiza el estado del proyecto.
Bootstrapper — Inicializa la documentación interactivamente. Te hace preguntas sobre el proyecto y genera los 3 archivos always-read. Tiene una regla clave: no inventa información. Si no sabe algo, deja un marcador NEEDS_HUMAN_INPUT en vez de hallucinar contenido.
Task routing: no todo necesita el pipeline completo
El sistema tiene tres niveles de complejidad:
Fast path: Implementer solo → Typos, formato, config sin impacto
Standard path: Planner → Implementer → Tester → Reviewer → Features, bug fixes, refactors
Full path: Todos los roles + checkpoints humanos → Arquitectura, seguridad, migraciones, operaciones destructivasEl routing no es automático — el agente lo decide basándose en las reglas definidas en CLAUDE.md. La regla de oro: en caso de duda, usar el standard path.
Resolución de conflictos
Acá es donde project-docs se diferencia de la mayoría de los sistemas multi-agente. En vez de dejar que los agentes resuelvan conflictos entre sí (spoiler: no pueden), define reglas de escalación explícitas:
- Si el implementer se desvía del plan, documenta la desviación y pausa para review humano
- Si el reviewer rechaza el mismo trabajo dos veces, escala al humano
- Si hay ambigüedad, el agente pausa y pide intervención humana
- Los desacuerdos arquitectónicos nunca se resuelven entre agentes
El humano siempre es el árbitro final. Esto suena obvio pero es sorprendentemente raro en frameworks de agentes.
Cómo instalarlo en tu proyecto
La instalación tiene dos pasos:
Paso 1 — Mecánico. Cloná el repo y corré el bootstrap:
# Dentro de tu proyectogit clone https://github.com/lea2696/project-docs.git project-docs/
# Correr el bootstrap (genera CLAUDE.md, AGENTS.md, configs de agentes)node project-docs/scripts/bootstrap.mjs
# O con opcionesnode project-docs/scripts/bootstrap.mjs --dry-run # Preview sin escribirnode project-docs/scripts/bootstrap.mjs --non-interactive # Usar defaultsEl script detecta automáticamente el nombre del proyecto (desde package.json o el nombre del directorio) y el directorio de tests (prueba tests/, test/, __tests__/, spec/). Te pregunta si querés confirmar o cambiar estos valores.
Paso 2 — Conversacional. Pedile al agente bootstrapper que llene la documentación:
# En Claude Code"Usá el agente bootstrapper para inicializar los docs del proyecto"
# En Codex"Usá el skill de bootstrap para inicializar los docs del proyecto"El bootstrapper te hace preguntas sobre el propósito del proyecto, usuarios target, tech stack, convenciones, y estado actual. Genera los archivos always-read y opcionalmente los de referencia. Lo que no puede completar lo marca con NEEDS_HUMAN_INPUT.
El sistema de memoria
Una de las features más útiles es la memoria de errores en memory/RECURRING_MISTAKES.md. Cada entrada tiene una estructura formal:
### MIS-001: Tests pasaban con mock pero fallaban en prod- Date: 2026-03-15- Category: testing- What happened: Los tests mockeaban la DB y pasaban, pero la migración real falló- Root cause: Divergencia entre mock y esquema real- Resolution: Migrar a integration tests con DB real- Prevention rule: No mockear la base de datos en tests de integraciónEsto es oro para los agentes. En vez de repetir el mismo error, leen el registro de errores previos y ajustan su enfoque.
El CHANGELOG_NOTES.md tiene una columna de Agent Impact que dice no solo qué cambió, sino qué tienen que hacer los agentes diferente a partir de ese cambio.
CI/CD incluido
El repo viene con tres GitHub Actions:
- docs-lint — Valida la estructura de documentación en cada push (8 directorios, 19 archivos, frontmatter válido)
- structure-check — Verifica que el scaffold tenga exactamente 18 archivos y que las configs de agentes existan
- scaffold-smoke — Corre el bootstrap en un repo temporal y verifica que no queden placeholders sin resolver
Por qué esto importa
La tendencia actual es darle a los agentes más capacidad: más herramientas, más contexto, más autonomía. project-docs va en la dirección opuesta. Le da al agente menos libertad pero mejor información. Le dice exactamente qué leer, qué no tocar, cuándo parar, y a quién preguntar.
El resultado es que los agentes producen trabajo más predecible, más alineado con las decisiones del proyecto, y con menos necesidad de corrección humana. No porque sean más inteligentes, sino porque están mejor informados.
Si estás usando Claude Code o Codex en proyectos reales, dale una mirada. Es open source, se instala en 5 minutos, y la diferencia en calidad de output se nota desde la primera sesión.