La ingeniería de contexto requiere un ciclo de retroalimentación

La ingeniería de contexto es la disciplina que consiste en proporcionar a un agente de IA la información adecuada, en el formato adecuado y en el momento oportuno, para que realice un buen trabajo en lugar de tener que adivinar. En la práctica, para la mayoría de los equipos, esto se traduce en archivos: un CLAUDE.mden la raíz del repositorio, un AGENTS.md, una carpeta con reglas y convenciones, y una indicación del sistema que alguien configuró en su momento. Se describe cómo funciona su proyecto para que el agente no tenga que volver a descubrirlo en cada sesión.

Es, sin duda, la medida más eficaz que puede tomar para que los agentes resulten útiles. Y casi todos los que lo hacen se enfrentan al mismo problema tácito: esos archivos quedan obsoletos y nadie sabe qué partes lo están. Se redactó el contexto una sola vez, el código ha evolucionado y, ahora, la mitad de él está erróneo sin que nadie se dé cuenta. Esta disciplina cuenta con una fase de entrada (la redacción del contexto), pero carece de un ciclo de mantenimiento. Esa es la laguna de la que trata esta entrada.

El contexto es código, y el código se deteriora

Ya sabemos que la documentación se queda obsoleta. El paso de compilación que ha documentado se sustituye, la carpeta que ha descrito cambia de nombre, la convención que ha anotado queda obsoleta y la documentación sigue describiendo con total seguridad el mundo tal y como era. Los archivos de contexto son peores que la documentación habitual en este sentido, por dos razones.

En primer lugar, un agente las lee al pie de la letra y actúa en consecuencia. Una persona echa un vistazo rápido a un archivo README desactualizado, se da cuenta de que algo no cuadra y pregunta a alguien. Un agente se toma CLAUDE.mdal pie de la letra. Si dice «ejecutar make setup» y ese objetivo se eliminó el trimestre pasado, el agente no se encoge de hombros. Pierde tiempo intentando que funcione lo que no debe, o inventa una solución alternativa y sigue adelante, trasladando la instrucción errónea a su resultado.

En segundo lugar, un contexto incorrecto es peor que la falta de contexto. En el caso de una laguna, el agente a veces puede razonar en torno a ella o señalarla. Sin embargo, si se trata de una afirmación errónea expresada con seguridad, el agente confía en ella. Las líneas más costosas de sus archivos de contexto no son las que faltan, sino aquellas que antes eran ciertas.

Por lo tanto, necesita un ciclo de mantenimiento. El problema es que las soluciones habituales no funcionan. No va a realizar una auditoría CLAUDE.mdlínea por línea según un calendario. Nadie lo hace. Desde fuera no se nota que esté desactualizado, porque se lee bien. La desactualización solo se pone de manifiesto en el momento de su uso, para quienquiera que lo utilice. Y, cada vez más, quien lo utiliza no es una persona.

El único testigo que sabe

Aquí está el cambio. El agente que acaba de ejecutar una sesión con su proyecto es el único participante que sabe, de forma concreta, qué partes de su contexto le han ayudado y cuáles le han engañado. Simplemente utilizó los archivos. Ejecutó el comando de compilación obsoleto. Encontró la carpeta que no existe. Siguió el patrón que resultó ser, en realidad, tres patrones. Ese conocimiento perdura aproximadamente mientras dura la sesión, y luego desaparece.

Nadie le indica qué contexto falta o es incorrecto, salvo el propio sistema que acaba de verse afectado por ello. Ese es el ciclo de retroalimentación, ahí mismo, sin que nadie lo aproveche. Lo único que debe hacer es pedir al agente que anote lo que ha aprendido antes de que finalice la sesión, y formular la solicitud de tal manera que el resultado apunte directamente a los archivos que deben editarse.

El registro retroactivo de la sesión es el bucle de mantenimiento

Esto es exactamente lo que genera una retroalimentación de IA al final de la sesión. Al término de una sesión de trabajo, el agente redacta una entrada breve y sincera: qué salió bien, dónde se produjeron dificultades y, lo que nos interesa aquí, cada dificultad se etiqueta con una de las diez etiquetas fijas de causa raíz y termina con un «→ Solución:» del tamaño de un ticket. Dos de esas diez etiquetas hacen referencia directa a sus archivos de contexto:

• missing-documentation****: el agente necesitaba algo que el proyecto debería haber documentado, pero no lo había hecho. Esta es la lista de tareas pendientes de su archivo de contexto. Cada uno de estos puntos es una línea que debería añadir CLAUDE.mda su documentación.
• incorrect-documentation****: la documentación existía, pero era errónea o estaba desactualizada. Esta es la lista de correcciones pendientes de su archivo de contexto. Cada una de estas entradas es una línea obsoleta que el agente ha detectado de la única forma posible: al utilizarla y toparse con un obstáculo.

Añada un tercer punto y habrá cubierto la mayor parte del mantenimiento que jamás necesitará: ambiguous-instruction****, cuando un escrito o una norma puedan interpretarse de más de una forma. Ese es el bucle. No revisa sus archivos de contexto según un calendario; deja que los agentes que los utilizan le indiquen, en el momento de su uso, exactamente qué líneas debe modificar, con la evidencia adjunta, ya que la práctica se basa exclusivamente en la evidencia citada.

Y hay una cuarta señal que es fácil pasar por alto: las suposiciones. Una buena entrada enumera todos los puntos en los que el agente ha llenado un vacío con una suposición. Cada suposición es un punto en el que su contexto era lo suficientemente escaso como para que el agente tuviera que inventarse una respuesta. Lea las conjeturas de una semana y obtendrá una lista de tareas pendientes para sus archivos de contexto que usted mismo nunca habría podido redactar, ya que conoce las respuestas y, por lo tanto, no puede detectar dónde faltan.

A continuación se muestra el formato de los resultados obtenidos. Se trata de un ejemplo ilustrativo, no de datos reales:

## Friction
- CLAUDE.md says "run `make setup`" but that target was removed; the
  actual setup is `pnpm install && pnpm db:migrate`. Lost ~10 min.
  (incorrect-documentation)
  → Fix: Update the "Getting started" block in CLAUDE.md to the pnpm commands.
- Nothing documents that integration tests need the worker running.
  Found it by reading the CI config. (missing-documentation)
  → Fix: Add a "Running tests" note naming `pnpm worker` as a prerequisite.

## Guesses I made
- Assumed the `api/` package is the public surface and `internal/` is not,
  because nothing states it. Please confirm before I rely on it again.

Cada línea corresponde a una modificación concreta en un archivo específico. Se trata de un bucle de mantenimiento que una persona ejecutará realmente, ya que la labor de localizar el problema —la parte más laboriosa— ya se ha realizado.

Por qué esto es mejor que la auditoría manual

Podría intentar mantener actualizados los archivos de contexto a la antigua usanza: programar una revisión, leerlos de principio a fin y contrastar cada afirmación con la realidad. Esto no suele ocurrir, y, aun cuando ocurre, no es el método adecuado. Al leer un documento de forma abstracta, no se puede determinar qué líneas están desactualizadas. Todas parecen plausibles. La obsolescencia solo se hace evidente con el uso. El registro retrospectivo es un mantenimiento del contexto impulsado por el uso real: solo se marcan las líneas que realmente han activado un agente, por lo que se corrige lo que realmente falla en lugar de volver a leer lo que ya funciona correctamente. Es la diferencia entre un detector de humo y recorrer el edificio en busca de humo.

Además, se acumula. Si se resuelven los problemasincorrect-documentation esta semana, las sesiones de la próxima semana se toparán menos con ese obstáculo, por lo que el registro se acorta y se centra en cuestiones más profundas. Sus archivos de contexto tienden a ser precisos no porque alguien los haya auditado, sino porque las personas y los agentes que los utilizan disponían de una forma sencilla y estructurada de informar de las desviaciones. Esa es una colaboración saludable entre humanos e IA: el agente detecta la desviación y el humano decide la modificación.

Inicie el bucle

Si ya está invirtiendo en ingeniería de contexto, esta es la pieza que le faltaba: el ciclo de mantenimiento que evita que la inversión se eche a perder. Es de código abierto y cuenta con licencia del MIT:

• Obtenga las habilidades y el paquete de indicaciones: github.com/TeamRetroHQ/teamretro-skills: una habilidad de Claude Code que redacta la entrada de fin de sesión, otra que sintetiza las entradas en un resumen y un paquete de indicaciones independiente de la herramienta para Cursor, GitHub Copilot o cualquier agente al que pueda enviar indicaciones.
• Consulte la guía completa: Cómo recabar comentarios de sus agentes de IA abarca las diez etiquetas, la verificación humana y cómo las aportaciones se incorporan a una retrospectiva de equipo, y no solo a sus archivos de contexto.
• Profundice en el propio bucle: los bucles de retroalimentación de los agentes ofrecen una visión general del panorama completo: el bucle «detectar-corregir», las herramientas que lo ejecutan y el lugar que ocupa una sesión en este contexto.

Hay un matiz que conviene tener en cuenta. Cuando un agente le indique que la documentación es errónea, compruébela antes de realizar cualquier modificación, ya que, en ocasiones, la documentación es correcta y el agente la ha interpretado erróneamente. Sigue siendo una indicación útil (una línea que se malinterpreta fácilmente merece ser reescrita), pero se trata de una corrección diferente, y por eso es necesario que una persona siga interviniendo en el proceso. El agente es un participante que señala lo que le ha llamado la atención, nunca la autoridad que decide qué debe decir su proyecto.

La calidad de sus archivos de contexto depende de su última corrección veraz. Los agentes que los utilizan le entregan esas correcciones al final de cada sesión. Solo tiene que anotarlas. Y si su equipo desea que esas correcciones se publiquen en un lugar donde la gente ya las vea, el agente puede preparar sus recomendaciones y publicarlas él mismo en su tablero a través del servidor MCP de TeamRetro, tras su confirmación, marcadas con [AI retro], junto al resto de las mejoras de su equipo.