El repo, fuente de verdad

La decisión que solo sabía Marta

Tu equipo decidió el viernes, tomando un café, que todas las fechas se guardan en UTC. Marta lo sabe. Lo comentaron en Slack. Pero el lunes un agente escribe una función que guarda la hora local, y nadie se lo había dicho.

No es un fallo del modelo. Es un fallo de visibilidad: la decisión estaba fuera del único sitio donde el agente puede mirar.

Qué ve realmente un agente

Las entradas de un agente son pocas: el prompt de sistema, la descripción de la tarea, los archivos del repositorio y la salida de sus herramientas. Eso es todo. No ve tu Slack, ni Jira, ni Confluence. No puede preguntarle a un compañero.

Es como un ingeniero encerrado dentro del repositorio: de lo que queda fuera de las paredes no sabe nada. Por eso el curso (y OpenAI, cuyo enfoque describe) lo resume así: la información que no existe en el repo no existe para el agente. Es el principio de que el repo es la especificación con más autoridad.

Conceptos útiles

• Sistema de registro: el repositorio es la fuente autorizada de decisiones, restricciones, estado y estándares de verificación. Si hay conflicto, manda el repo.
• Brecha de visibilidad del conocimiento: la parte del conocimiento del proyecto que NO está en el repo. Cuanto mayor, más fallos del agente.
• Coste de descubrimiento: cuánto contexto gasta el agente en encontrar algo. Un dato crítico escondido diez carpetas abajo cuesta mucho.
• Degradación del conocimiento: una documentación que ya no coincide con el código es peor que no tener ninguna, porque manda al agente en la dirección equivocada con total confianza.

Cómo mover conocimiento al repo

Una guía rápida de dónde va cada cosa (basada en el procedimiento de OpenAI incluido en los recursos del curso):

Y cuatro reglas: escribe para que se encuentre, no para que luzca; prefiere documentos cortos con nombres claros; guarda reglas duraderas, no actas de reuniones; y actualiza el repo en la misma sesión en que se toma la decisión. Elimina las copias antiguas para que haya una sola verdad.

Ejemplo mínimo

La decisión de Marta, escrita donde el agente la verá:

<!-- docs/ARCHITECTURE.md -->
## Fechas
Todas las fechas se almacenan en UTC y se convierten a hora local
solo en la capa de interfaz. Decidido el 2025-03-14 por consistencia
entre servidores en distintos países.

Tres líneas. A partir de ahora cualquier sesión nueva puede cumplirla.