retro y writing-for-agents: mejora el entorno de tu agente después de cada sesión

Cuando una sesión con un agente sale mal, lo habitual es corregir el código y seguir. Las skills de Matt Pocock proponen un paso más: preguntar qué del entorno hizo que saliera mal y cambiarlo, para que la próxima sesión empiece desde un sitio mejor. retro hace esa retrospectiva y writing-for-agents es la referencia de cómo escribir los cambios que propone: CLAUDE.md, AGENTS.md, estándares de código y skills. Van juntas porque retro carga writing-for-agents en su primer paso.

Es la decimotercera parte de la guía de las skills de Matt Pocock (repositorio mattpocock/skills, licencia MIT).

retro: cerrar el bucle

ask-matt sitúa /retro al final del flujo principal: "después de construir, y sobre todo si salió torcido". No propone cambios en el código, sino en el entorno del agente.

Siete categorías, de más a menos grave

retro lee las fuentes primarias de la sesión (la actual por defecto, o los logs de otra) y busca candidatos en estas categorías:

Y presenta los candidatos ordenados por gravedad.

Mecánico o de criterio

La regla más útil de retro es cómo clasificar un error:

• Mecánico (un patrón sintáctico fijo, una API prohibida, la forma de un import, dónde va un fichero): se convierte en un chequeo determinista, punto. Una regla en el linter del repositorio, un hook de pre-commit o un job de CI, el que sea más barato.
• De criterio (coherencia entre ficheros, "encaja con el estilo de alrededor"): va a CODING_STANDARDS.md, que lee el revisor.

Antes de proponer un chequeo nuevo, retro lee los scripts de lint y check del repositorio y su CI: si el chequeo ya existe pero no está conectado o está roto en silencio, ese es el hallazgo. Y un repositorio sin ningún guardarraíl (ni hook de pre-commit ni job de CI que pase lint, tipos y tests) es un hallazgo por sí mismo.

Implementador y revisor

retro se apoya en una idea sobre dónde poner cada regla. Todo trabajo pasa por dos fases:

• El agente implementador tiene la mayor presión de contexto: explora, escribe código y depura.
• El agente revisor tiene la menor: recibe un diff, no necesita explorar.

Conclusión: los estándares de código los debe hacer cumplir el revisor (con code-review, que vimos en la parte 7), no el implementador. Por eso CLAUDE.md y AGENTS.md, que se cargan en cada sesión, deben usarse "con muchísima moderación", casi solo para punteros de navegación hacia otros ficheros.

writing-for-agents: cómo escribir para un agente

writing-for-agents es la referencia para cualquier documento que lee un agente: una skill, un AGENTS.md o CLAUDE.md, o un documento al que se llega por un enlace. Es la más densa del repositorio; estas son sus ideas principales.

Punteros de contexto

Un puntero de contexto es una referencia en el contexto del agente que nombra material externo y dice cuándo ir a buscarlo. La descripción de una skill es uno; una línea de AGENTS.md que nombra un documento es otro. La clave: la redacción del puntero, no su destino, decide si el agente lo usa. Si un material imprescindible no se está usando, primero afila la redacción; solo si no basta, pégalo dentro.

Las dos cargas

• Carga de contexto: lo que siempre está cargado (una línea de AGENTS.md, la descripción de una skill) gasta tokens y atención en cada turno, se use o no.
• Carga cognitiva: lo que tiene que recordar la persona (qué documentos existen y cuándo usarlos). No es algo a minimizar: es el precio de que tú decidas.

Jerarquía de información

Un documento tiene pasos (lo que el agente hace, en orden) y referencia (definiciones y reglas que consulta). Se ordenan en una escalera: pasos en el fichero, referencia en el fichero, y referencia revelada en otro fichero al que se llega por un puntero. La prueba para mover algo abajo: si todos los casos lo necesitan, va dentro; si solo algunos, detrás de un puntero. El fallo opuesto es la expansión: un documento demasiado largo aunque cada línea sea válida.

Criterios de terminado

Cada paso termina en un criterio que dice cuándo está hecho. Un criterio vago ("cuando se entienda") invita a terminar antes de tiempo, porque la atención se va a los pasos siguientes. Los mejores criterios son comprobables y exhaustivos: "todos los modelos modificados contemplados" obliga a más trabajo que "haz una lista de cambios".

Palabras guía y negaciones

Una palabra guía es un concepto compacto que el modelo ya conoce y que ancla un comportamiento en pocos tokens: "un bucle *tight*", "el test se pone *rojo*". El repositorio está lleno de ellas: *frontera*, *bala trazadora*, *niebla de guerra*. Y su contrario: prohibir algo ("no hagas X") lo trae al contexto y lo hace más probable. Escribe en positivo el comportamiento que quieres.

Poda

• Una sola fuente de verdad por idea.
• No copies el entorno: package.json, la configuración o --help ya son fuentes de verdad. Escribe solo lo que el agente no puede encontrar mirando: la convención no escrita, el motivo de una decisión.
• Caza los no-ops: una instrucción que el modelo ya cumple por defecto no hace nada. Si una frase no cambia el comportamiento, bórrala entera.

Para skills

El fichero SKILL-MECHANICS.md añade la decisión de invocación: una skill invocada por el modelo mantiene su descripción siempre cargada (carga de contexto a cambio de que el agente la encuentre); una invocada por el usuario no cuesta contexto pero tienes que recordarla tú. Cuando las skills de usuario se acumulan, la cura es una skill router como ask-matt.

Cómo se combinan

retro encuentra qué cambiar en el entorno; writing-for-agents dice cómo escribirlo para que funcione. Un ejemplo típico: en una sesión el agente usó npm en un repositorio que usa pnpm. retro lo clasifica como mecánico y propone un chequeo (un hook que falle si aparece package-lock.json), no una línea más en CLAUDE.md. Si el agente tardó en encontrar dónde viven las consultas a la base de datos, propone un puntero de navegación, y writing-for-agents dice cómo redactarlo: palabra clave al principio, una condición clara y nada que el propio árbol de carpetas ya diga.

retro también cierra el círculo con diagnosing-bugs: después de arreglar un bug difícil, ejecutarla en la misma sesión pregunta qué lo habría evitado.

Errores frecuentes

• Convertir cada error en una línea de CLAUDE.md. Es el patrón que la skill intenta evitar: crece, se vuelve sedimento y el agente lo ignora.
• Escribir reglas en negativo. "Nunca uses npm" es más débil que "usa pnpm para instalar y ejecutar scripts".
• Ejecutar retro después de /clear. Pierde la fuente primaria. Hazlo antes, o apúntala al log de la sesión.
• Duplicar en documentos lo que dice el package.json. Se queda desactualizado.

Preguntas frecuentes

¿retro cambia ficheros? Su SKILL.md le pide presentar los candidatos ordenados por gravedad; tú decides cuáles aplicar.

¿writing-for-agents sirve para escribir prompts normales? Sí: las ideas de punteros, criterios de terminado y no-ops valen para cualquier texto que vaya a leer un modelo.

¿Dónde van los estándares que lee el revisor? En CODING_STANDARDS.md (o CONTRIBUTING.md), que code-review busca siempre.

Siguiente paso

Al terminar tu próxima sesión larga, antes de limpiar el contexto, ejecuta /retro y aplica solo el primer candidato. En la parte 14, la última de la guía, vemos teach y wait-what, las dos skills pensadas para que tú entiendas lo que hace el agente.