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: unCLAUDE.md en 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 adoptarse 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 escribió el contexto una vez, el código ha evolucionado y ahora la mitad de él está, sin que nadie se dé cuenta, incorrecto. 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 los documentos habituales en este sentido, por dos razones.

En primer lugar, un agente las lee al pie de la letra y actúa en consecuencia. Un ser humano 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 tomaCLAUDE.md al 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 revisarCLAUDE.mdel código línea por línea según un calendario preestablecido —nadie lo hace—. No se dará cuenta de que está obsoleto a simple vista, ya que se lee correctamente. La obsolescencia 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, concretamente, 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 existe —más o menos mientras dura la sesión— y, después, desaparece.

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

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

Esto es exactamente lo que genera un resumen de IA al final de la sesión. Al final de una sesión de trabajo, el agente redacta una entrada breve y sincera: qué ha salido bien, dónde ha habido 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 apuntan directamente 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 aCLAUDE.md 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 elemento y habrá cubierto la mayor parte del mantenimiento que jamás necesitará: ambiguous-instruction****, en los casos en que 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 el trabajo 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 suceder 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, ya que 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 provocado un error en 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 losincorrect-documentationpuntos 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:

• Consiga 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 aborda las diez etiquetas, la verificación humana y cómo las aportaciones alimentan una retrospectiva de equipo —no solo sus archivos de contexto—.

Hay un matiz que conviene tener en cuenta. Cuando un agente le indique que la documentación es errónea, compruébelo antes de editarla; en ocasiones, la documentación es correcta y el agente la ha interpretado mal. Aun así, 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 un humano siga estando al tanto. 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 facilitan esas correcciones al final de cada sesión; usted 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 —confirmadas por usted, marcadas [AI retro]con , junto al resto de las mejoras de su equipo—.