Lección 03 — El repositorio como fuente única de verdad

Las decisiones de arquitectura de tu equipo están dispersas entre Confluence, Slack, Jira y la cabeza de un par de ingenieros senior. Para los humanos esto apenas funciona: podés preguntarle a un compañero, buscar en el historial del chat, revisar documentación. Si todo falla, podés acorralar a alguien en la cocina de la oficina. Pero para un agente, la información que no está en el repositorio simplemente no existe.

No es una exageración. Pensá cuáles son realmente las entradas de un agente: prompts de sistema y descripciones de tarea, contenidos de archivos del repositorio y salidas de herramientas. Eso es todo. Tu historial de Slack, los tickets de Jira, las páginas de Confluence y esa decisión de arquitectura que charlaste con un compañero un viernes a la tarde: el agente no ve nada de eso. Es un ingeniero encerrado dentro del repositorio.

La pregunta es: ¿le vas a dar a ese ingeniero un buen mapa?

Qué debe estar en el mapa

OpenAI lo dice sin rodeos: la información que no existe en el repo no existe para el agente. Lo llaman el principio repo as spec: el propio repositorio es el documento de especificación con mayor autoridad.

La documentación de Anthropic sobre agentes de larga duración apunta en la misma dirección: el estado persistente es condición necesaria para la continuidad en tareas largas, y ese estado debe existir en el repositorio, porque es el único almacenamiento estable y accesible que tiene el agente.

Podés pensar: “nuestro equipo es chico, el conocimiento está en la cabeza de todos y funciona bien”. Para humanos, tal vez. Pero si usás un agente, aceptá este hecho: el agente no puede preguntarle a personas.

No se trata de “escribir más documentación”. Se trata de poner la información de decisión en el lugar correcto. Un ARCHITECTURE.md de 50 líneas dentro de src/api/ es infinitamente más útil que un documento de diseño de 500 páginas en Confluence que nadie mantiene.

La prueba de arranque en frío

¿Cómo comprobás si tu mapa es suficientemente bueno? Abrí una sesión de agente completamente nueva usando solo el contenido del repo y mirá si puede responder cinco preguntas:

flowchart TD
    S["Sesión nueva<br/>solo con el repo"] --> Q1["1. ¿Qué es este sistema?"]
    Q1 --> Q2["2. ¿Cómo está organizado?"]
    Q2 --> Q3["3. ¿Cómo lo ejecuto?"]
    Q3 --> Q4["4. ¿Cómo lo verifico?"]
    Q4 --> Q5["5. ¿Cuál es el progreso actual?"]
    Q5 --> R{"¿Respondió<br/>las cinco?"}
    R -->|Sí| OK["El mapa está completo"]
    R -->|No| GAP["Zona en blanco:<br/>el agente va a adivinar"]
    GAP --> FIX["Escribir esa información<br/>donde el agente la encuentre"]
    FIX --> S

Donde el mapa está en blanco, el agente adivina. Las malas conjeturas se convierten en bugs y adivinar demasiado desperdicia contexto. Y cada sesión nueva vuelve a adivinar todo. El costo de adivinar siempre es mayor que el costo de dibujar bien el mapa desde el principio.

Conceptos clave

• Knowledge Visibility Gap: la proporción del conocimiento total del proyecto que NO está en el repositorio. Cuanto mayor sea la brecha, mayor la tasa de fallos del agente. Contá todo el conocimiento implícito que vive en tu cabeza y mirá cuánto llegó al repo: la diferencia es tu brecha.
• System of Record: el repositorio como fuente autorizada para decisiones de proyecto, restricciones de arquitectura, estado de ejecución y estándares de verificación. El repo tiene la última palabra; lo demás no cuenta.
• Cold-Start Test: las cinco preguntas de arriba. Cuántas puede responder indica qué tan completo es tu mapa.
• Discovery Cost: cuánto presupuesto de contexto consume el agente para encontrar una información clave. Cuanto más escondida esté, mayor el costo y menos presupuesto queda para la tarea real.
• Knowledge Decay Rate: la proporción de entradas de conocimiento que quedan obsoletas por unidad de tiempo. Que la documentación se desincronice del código es peor que no tener documentación.
• Analogía ACID: aplicar principios de transacciones de base de datos a la gestión del estado de agentes. Lo desarrollamos abajo.

Cómo dibujar un buen mapa

Principio 1: el conocimiento vive junto al código. Una regla sobre autenticación de endpoints debe estar junto al código de API, no enterrada en un documento global gigante. Poné un documento corto en cada directorio de módulo explicando responsabilidades, interfaces y restricciones especiales. Como las etiquetas de estantería en una biblioteca.

Principio 2: usá un archivo de entrada estandarizado. AGENTS.md (o CLAUDE.md) es la página de aterrizaje. No necesita contener toda la información, pero debe permitir que el agente responda rápido tres preguntas: qué es este proyecto, cómo lo ejecuto y cómo lo verifico. 50-100 líneas alcanzan.

Principio 3: mínimo pero completo. Cada pieza de conocimiento debe tener un caso de uso claro. Si eliminar una regla no afecta la calidad de decisión del agente, esa regla no debería existir. Pero cada pregunta de la prueba de arranque en frío debe tener respuesta.

Principio 4: actualizá junto con el código. Vinculá las actualizaciones de conocimiento a los cambios de código. El enfoque más simple: colocá los documentos de arquitectura en el directorio del módulo correspondiente. Cuando modificás código, ves el documento naturalmente.

Estructura concreta del repositorio

flowchart TD
    R["proyecto/"] --> A["AGENTS.md<br/>entrada: resumen, comandos,<br/>restricciones duras"]
    R --> S["src/"]
    R --> P["PROGRESS.md<br/>hecho, en curso, bloqueado"]
    R --> M["Makefile<br/>setup, test, lint, check"]
    S --> API["src/api/"]
    S --> DB["src/db/"]
    API --> AA["ARCHITECTURE.md<br/>decisiones de la capa API"]
    DB --> DC["CONSTRAINTS.md<br/>restricciones duras de BD"]

La regla es simple: el documento vive donde vive el código que describe. El agente que abre src/db/ ve CONSTRAINTS.md sin tener que buscarlo.

Gestionar el estado de agentes con principios ACID

La analogía viene de la gestión de transacciones en bases de datos. Parece una complicación excesiva, pero da un marco muy práctico:

flowchart LR
    A["Atomicity<br/>Un commit por<br/>operación lógica"] --> Z["Estado del agente<br/>gestionable"]
    C["Consistency<br/>Predicados de<br/>verificación"] --> Z
    I["Isolation<br/>Archivos o ramas<br/>por agente"] --> Z
    D["Durability<br/>Conocimiento crítico<br/>versionado en git"] --> Z

• Atomicity: cada operación lógica (“agregar endpoint nuevo y actualizar tests”) recibe un commit de git. Si falla a mitad de camino, git stash para revertir. Todo o nada: no hay “medio hecho”.
• Consistency: definí predicados de verificación de “estado consistente” —todos los tests pasan, lint sin errores—. El agente los ejecuta después de cada operación; los estados intermedios inconsistentes no se commitean.
• Isolation: cuando varios agentes trabajan en paralelo, diseñá archivos de estado que eviten condiciones de carrera. Enfoque simple: cada agente usa su propio archivo de progreso, o se usan ramas y worktrees de git para aislar.
• Durability: el conocimiento crítico del proyecto vive en archivos versionados por git. El estado temporal puede quedarse en memoria de sesión, pero el conocimiento entre sesiones debe persistirse en archivos.

Una historia real de transformación

Un equipo mantenía una plataforma de e-commerce con unos 30 microservicios. Las decisiones de arquitectura —protocolos de comunicación entre servicios, estrategias de consistencia de datos, reglas de versionado de API— estaban dispersas entre Confluence (parcialmente obsoleto), Slack (difícil de buscar), la cabeza de algunos ingenieros senior (no escalable) y comentarios de código esporádicos (no sistemáticos).

Después de introducir agentes, el 70% de las tareas requería intervención humana. Casi todos los fallos implicaban que el agente violaba alguna restricción implícita de “todo el mundo lo sabe pero nadie lo escribió”.

El equipo ejecutó una transformación:

1. Creó AGENTS.md en la raíz con resumen del proyecto, versiones del stack y restricciones globales duras.
2. Agregó ARCHITECTURE.md en cada directorio de microservicio describiendo responsabilidades, interfaces y dependencias.
3. Creó un CONSTRAINTS.md centralizado con restricciones duras en lenguaje explícito MUST / MUST NOT.
4. Agregó PROGRESS.md en cada directorio de servicio para seguir el estado actual del trabajo.

Después de la transformación, el mismo agente podía responder todas las preguntas clave del proyecto en arranque en frío, y la calidad de finalización de tareas mejoró significativamente.

Ideas clave

• El conocimiento que no está en el repo no existe para el agente. Poner decisiones críticas en el repo es la inversión más básica en harness.
• Usá la prueba de arranque en frío para evaluar la calidad del repo: ¿puede una sesión fresca responder las cinco preguntas usando solo el contenido del repo?
• El conocimiento debe estar cerca del código, ser mínimo pero completo y actualizarse junto con el código.
• Aplicá ACID al estado del agente: commits atómicos, verificación de consistencia, aislamiento de concurrencia y conocimiento crítico durable.
• La degradación del conocimiento es el mayor enemigo. Documentación desincronizada del código es más peligrosa que no tener documentación: manda al agente en la dirección equivocada mientras cree que va bien.

Ejercicios

1. Prueba de arranque en frío: abrí una sesión de agente completamente nueva en tu proyecto (sin contexto verbal, solo contenido del repo). Hacele las cinco preguntas. Registrá lo que no puede responder y mejorá el repo hasta que pueda.
2. Cuantificación de externalización: listá todas las decisiones y restricciones importantes de tu proyecto. Marcá cada una como dentro o fuera del repo. Calculá tu Knowledge Visibility Gap y hacé un plan para bajarlo por debajo del 10%.
3. Evaluación ACID: evaluá la gestión de estado de tu proyecto con la analogía ACID. ¿Pueden revertirse limpiamente las operaciones del agente? ¿Existe verificación de estado consistente? ¿Los agentes concurrentes se pisan? ¿Todo el conocimiento entre sesiones está persistido?

Lecturas adicionales

• OpenAI: Harness Engineering
• Anthropic: Effective Harnesses for Long-Running Agents
• Infrastructure as Code — Martin Fowler
• ADR: Architecture Decision Records
• The Twelve-Factor App

---

Anterior: Lección 02 — Qué significa realmente harness · Siguiente: Lección 04 — Dividí las instrucciones entre archivos