Cómo llevar un cuaderno de laboratorio cuando trabajas con agentes de IA

Si trabajas con agentes de IA —Claude Code, Codex, OpenCode, el que sea— te habrá pasado: un agente descubre por la tarde que cierta opción tumba el servidor, y por la noche otro agente (o el mismo, en otra sesión) la vuelve a poner. Los agentes no tienen memoria entre sesiones. Tú sí, pero a medias.

En el laboratorio lo resolvemos con algo muy poco espectacular: una carpeta de texto en Git que todos los agentes leen antes de empezar y actualizan al terminar. La llamamos «la bóveda». Esto es lo que hemos aprendido manteniéndola.

Los cuatro ficheros que importan

No hace falta más para empezar:

fichero	qué contiene
ESTADO.md	qué está funcionando ahora mismo y con qué configuración exacta
TRAMPAS.md	cada error que te costó más de media hora: qué pasaba, por qué y cómo evitarlo
DECISIONES.md	por qué elegiste lo que elegiste (dentro de tres meses no lo recordarás)
AGENTES.md	las reglas que cualquier agente debe leer antes de tocar nada

Y una carpeta experimentos/ con un fichero por prueba: qué querías saber, qué hiciste, qué salió.

Al empezar cada sesión, dile al agente: «lee ESTADO.md y TRAMPAS.md antes de hacer nada». La primera vez que un agente no repite un error que ya cometió otro, entiendes para qué sirve.

Las reglas que la mantienen útil

1. Etiqueta cada afirmación

No es lo mismo «lo hemos medido» que «lo dice un README». Usamos etiquetas muy simples:

• HECHO: lo hemos visto en nuestras máquinas.
• HIPÓTESIS: creemos que es así, sin comprobar.
• REFERENCIA EXTERNA: lo dice otro; no lo hemos reproducido.
• PENDIENTE: falta por hacer o por saber.

Parece burocracia. Es lo que permite que un agente lea «esto mejora un 79 %» y sepa si puede fiarse.

2. La máquina manda sobre el cuaderno

Esta regla nació de un error: durante un día entero nuestras notas decían que una función estaba apagada cuando estaba encendida, y atribuimos su efecto a otra cosa. Desde entonces, antes de fiarse de una configuración escrita, se comprueba contra lo que está funcionando:

docker ps
docker inspect <contenedor> --format '{{json .Config.Cmd}}'

Si no coinciden, se corrige el cuaderno en el momento. Documentar lo planeado en vez de lo que de verdad está desplegado es peor que no documentar.

3. Los fallos no se borran

Un experimento que sale mal se queda. No se edita para que quede mejor: si hay información nueva, se añade. Nuestros experimentos más útiles son precisamente los fallidos, como el modelo de 295B que descartamos el mismo día o el día que descubrimos que medíamos mal.

4. No mezcles cifras ajenas con las tuyas

Lo que publica otro laboratorio va aparte, marcado como referencia externa, hasta que lo reproduces. Si lo reproduces, pasa a ser tuyo. Si no, también lo apuntas: «no se reproduce aquí» es información valiosa.

5. Para cuando no quede nada barato por probar, no cuando «funciona»

«Funciona» no es un buen criterio para cerrar una prueba. Antes de cerrarla, apunta qué no has probado. Si alguna de esas cosas es barata y puede cambiar mucho el resultado, pruébala ahora en lugar de dejarla para «otro día». Nos pasó cerrar un informe diciendo que un aviso limitaba el contexto; comprobarlo costaba treinta segundos y habría demostrado que no.

6. Si varios agentes escriben a la vez, edita con cuidado

Con varios agentes trabajando en paralelo, dos pueden editar el mismo fichero:

• antes de editar, git status y mira qué cambió hace poco;
• pide a los agentes que editen reemplazando un texto exacto, no reescribiendo el fichero entero: si otro lo cambió, fallará en vez de borrar su trabajo en silencio;
• haz commits pequeños y frecuentes.

7. Nada de secretos

Ni claves, ni tokens, ni contraseñas. Si documentas un comando que lleva una clave, escribe [REDACTED]. Un cuaderno que leen agentes acaba copiado en muchos sitios.

Cómo empezar hoy

mkdir -p mi-lab/experimentos && cd mi-lab && git init
touch ESTADO.md TRAMPAS.md DECISIONES.md AGENTES.md

En AGENTES.md, tres líneas bastan para arrancar:

1. Antes de trabajar, lee ESTADO.md y TRAMPAS.md.
2. Si algo de lo escrito no coincide con la máquina, gana la máquina: corrige el fichero.
3. Al terminar, apunta lo que cambiaste y lo que aprendiste. Nunca escribas claves.

Las trampas que hemos ido acumulando nosotros están en Trampas, por si quieres empezar tu fichero con ventaja.