Notas para el agente de la otra persona

Somos dos trabajando sobre el mismo repositorio. Entre los dos corremos Claude Code, Cursor, Codex y Grok. Cuatro agentes escribiendo código, ninguno compartiendo memoria.

Lo primero que se rompe no es la calidad del código. Es que mi agente vuelve a abrir una pregunta que el tuyo cerró ayer, o la responde al revés sin decir nada.

Las transcripciones no arreglan eso. Nadie lee la transcripción de otro, y una ventana de contexto más grande no ayuda cuando el contexto vive en otra máquina. Así que la memoria la lleva el repositorio.

Qué pasó

Al final de una sesión el agente escribe un archivo corto y fechado bajo docs/agents/sessions/: hecho, archivos, decisiones, preguntas abiertas, siguiente, y Notas para el compañero.

Esa última sección es el punto, y está escrita para el agente de la otra persona, no para la otra persona. Un párrafo: qué debería contarle su agente a su humano mañana por la mañana.

Leerlo de vuelta es la mitad que tiene que seguir siendo barata.

Tres reglas evitan que se pudra.

Lee el índice, nunca las sesiones. INDEX.md es una línea por sesión, la más nueva primero. Carga solo lo que no has leído, primero lo del otro autor. Nunca las noventa y seis.

El estado de lectura es local y va fuera de git. Lo que yo he leído no es un hecho del equipo, y commitearlo significa un conflicto de merge en cada sesión.

Las sesiones viejas salen del árbol de trabajo. A los pocos días se les hace git rm y viven en el historial. Restaurarlas para que el índice se vea completo convierte un resumen en una excavación.

Qué acordamos

El registro dice qué pasó. No dice qué acordamos antes de que pasara, que es donde están los errores caros.

Cualquier cambio que toque el esquema, un canal de cliente, dinero o el aislamiento entre tenants abre primero una carpeta: intent.md, design.md, tasks.md. Primero se acuerda la intención, después el diseño si la elección es irreversible, después el código. La carpeta viaja en el mismo PR. Sin carpeta, no hay merge.

La regla que hace el trabajo es la negativa: no escribas el diseño como un resumen a la hora del merge. Un diseño escrito después del código es una descripción de lo que hiciste, y nunca puede decirte que estabas equivocado. Setenta y siete carpetas después, las secciones a las que vuelvo son siempre Alternatives rejected.

Por qué no una herramienta

Miramos OpenSpec y lo dejamos. La línea en nuestro propio registro es «las mismas carpetas, menos archivos». Lado a lado el traslape es casi total:

En las tres primeras filas OpenSpec es claramente mejor. Un comando que arma la carpeta y funciona en todos los asistentes que existen le gana a un cp, y no discutiría lo contrario. Nos quedamos con lo nuestro porque la estructura ya existía y lo que seguía fallando era que la gente no escribía, que ninguna herramienta arregla, y porque un vocabulario nuevo es un costo que se paga cuatro veces cuando cuatro agentes tienen que aprenderlo.

La fila cuatro es el desacuerdo de verdad, no una preferencia. OpenSpec es fluido a propósito: sin etapas obligatorias, se puede actualizar cualquier artefacto en cualquier momento. Nosotros hicimos rígidas cuatro clases a propósito, porque son aquellas donde equivocarse sale caro y se descubre tarde.

La fila seis no es una competencia. Los Stores sí son una función de equipo, pero comparten el plan, y un plan no es una sesión. Nada ahí le dice a mi agente que el tuyo pasó la noche descubriendo que el acento vive en el repositorio equivocado, que es el dato que de verdad necesitaba a las nueve de la mañana.

Quién gana

Cuatro lugares donde anotar cosas son tres de más, salvo que cada uno sea dueño de una pregunta. Sin esa tabla se vuelven cuatro copias medio verdaderas, y el agente le cree a la primera que encuentra.