Notas para el agente de la otra persona

Somos dos trabajando en el mismo repo. Usamos Claude Code, Cursor, Codex y Grok: son cuatro agentes y no comparten memoria.

Pensé que el primer problema sería el código, pero mi agente volvía a preguntar algo que el otro ya había cerrado ayer. A veces decidía lo contrario y ni avisaba.

No íbamos a leer las transcripciones del otro, y una ventana de contexto más grande no servía porque el contexto que necesitábamos estaba en otra máquina. Así que empezamos a dejar un archivo por sesión en el repo, con fecha y reglas para leerlo.

Notas de sesión

Al terminar una sesión, el agente escribe un archivo corto bajo docs/agents/sessions/, donde anota qué hizo, archivos, decisiones, preguntas abiertas y qué sigue. Después viene Notas para el compañero.

Esa sección es un párrafo que va a leer el agente de la otra persona, diciéndole qué tiene que contarle a su humano mañana en la mañana. Este es un ejemplo recortado:

Hay 171 archivos de sesión ahora, y leerlos todos cada mañana sería demasiado, incluso para un agente.

Mi agente parte por INDEX.md, que tiene una línea por sesión, la más nueva primero. Desde ahí carga solo las sesiones que no ha leído, empezando por las del otro autor, en vez de cargar las 171.

El estado de lectura queda local y fuera de git, porque si commiteamos eso tendríamos un conflicto de merge en cada sesión.

Después de unos días, las sesiones viejas salen del árbol de trabajo (con git rm, quedan en el historial). No las traigas de vuelta solo para completar el índice, o tendríamos otra vez todos esos archivos para leer.

Acordar un cambio

Las notas de sesión cuentan lo que pasó, pero también necesitamos lo que acordamos antes de partir, sobre todo si equivocarse cuesta plata o afecta a un cliente.

Para cambios de esquema, un canal de cliente, plata o aislamiento entre tenants, abrimos una carpeta con intent.md, design.md, tasks.md. Primero acordamos la intención, después el diseño si no podemos deshacer la decisión, y después escribimos código. La carpeta va en el mismo PR, y sin ella no hacemos merge.

No dejes el diseño para la hora del merge, porque ahí solo estás describiendo código que ya escribiste. Llevamos 91 carpetas y vuelvo seguido a Alternatives rejected para ver por qué elegimos algo.

Por qué seguimos con los archivos

Revisamos OpenSpec. En nuestro registro dice «las mismas carpetas, menos archivos». Esta es la comparación:

OpenSpec resuelve mejor las tres primeras filas, y prefiero un comando que cree la carpeta en distintos asistentes antes que usar cp. Nos quedamos con lo nuestro porque ya estaba ahí: la gente no escribía las notas, y no creo que otra herramienta arregle eso, mientras que cuatro agentes tendrían que aprender el vocabulario nuevo también.

La fila cuatro la queríamos así. OpenSpec deja cambiar cualquier artefacto cuando quieras, sin etapas rígidas, pero necesitamos esas revisiones para nuestros cuatro tipos de cambio donde equivocarse sale caro y puedes demorarte en notarlo.

Los Stores, en la fila seis, comparten el plan con el equipo, pero igual necesitamos saber qué pasó en la sesión. A las nueve de la mañana necesitaba saber que el otro agente había pasado la noche ubicando el bug del acento en otro repo, y mi agente no iba a sacar eso del plan.

Dónde buscar

Con cuatro lugares para escribir, ¿dónde debería buscar un agente? Le asignamos una pregunta a cada uno:

Sin esto terminamos con cuatro copias incompletas, y el agente usa la primera que lee, aunque la decisión que acordamos esté en otro archivo.