Cómo recabar opiniones de sus agentes de IA

Un agente de IA le ha enviado código esta semana. Leyó sus instrucciones, analizó el código fuente, se topó con un obstáculo debido a que la documentación era errónea, adivinó cómo superarlo y siguió adelante. A continuación, la sesión finalizó, y todo lo que había aprendido sobre los puntos problemáticos de su proyecto se perdió con ella. Nadie preguntó al único participante que acababa de pasar una hora en su repositorio qué era lo que ralentizaba el sistema.

Las retrospectivas existen precisamente para colmar esa brecha en el equipo: el equipo se reúne, identifica qué ha ayudado y qué ha supuesto un obstáculo, y lo convierte en un cambio. Los agentes de IA están realizando ahora trabajo real en su equipo y se enfrentan a las mismas dificultades que su personal, a veces incluso a más. Así pues, la pregunta es sencilla. Si un agente realiza el trabajo del equipo, ¿por qué no se incluye en la retrospectiva?

Esta guía trata sobre cómo incorporar esa perspectiva. No se trata de un nuevo formato de retrospectiva, ni de automatizar las aportaciones de su equipo: se trata de un nuevo participante. La IA aporta comentarios; su equipo sigue siendo quien decide qué significan. A continuación le explicamos cómo recopilarlos y cómo incorporarlos a la retrospectiva que ya lleva a cabo.

Esta entrada es una guía de inicio rápido. La práctica cuenta ya con una guía completa, Retrospectivas de agentes de IA, que abarca todo el ciclo, desde la recopilación de datos hasta la reunión del equipo; comience por aquí y consulte allí para obtener una visión completa.

Por qué merece la pena recopilar la experiencia de su agente de IA

El argumento a favor de una «retro» humana es que la memoria se desvanece y las lecciones no se comparten. Con un agente de IA, el problema es aún más grave: su memoria de trabajo no se desvanece, sino que se evapora. En el momento en que se cierra una sesión, el contexto desaparece. Nada de ello se traslada a la siguiente sesión a menos que alguien lo anote: el archivo README que echaba en falta y que le hubiera gustado que existiera, la variable de entorno que no estaba documentada, el resumen que se podía interpretar de tres maneras diferentes.

Además, los agentes recogen un tipo específico y útil de información. A lo largo de una hora de trabajo, un agente se percata de detalles que una persona pasa por alto, ya que esta última ya tiene el contexto en mente:

• El documento de incorporación que describe un paso de compilación que ya no existe.
• La función que tres puntos de llamada utilizan de forma diferente, por lo que «siga el patrón» hace referencia a tres patrones.
• Las instrucciones que decían «poner en orden la configuración» sin especificar de qué configuración se trataba ni cómo debía hacerse.
• El conjunto de pruebas que requiere que se ejecute un servicio que nadie le indica que debe iniciar.

Un desarrollador humano también se encuentra con estos problemas, se encoge de hombros, los sortea y rara vez presenta ninguna incidencia, ya que la dificultad está por debajo del umbral de «merecer la pena mencionarlo en la reunión». Un agente, si se le pregunta de la forma adecuada, informará de cada uno de ellos, adjuntando las pruebas pertinentes. Ahí radica el valor: no es que la IA sea más inteligente en lo que respecta a su proceso, sino que aporta una nueva perspectiva, sin ego y sin tolerancia acumulada ante los pequeños contratiempos. La colaboración entre humanos e IA funciona mejor cuando ambas partes pueden expresar qué es lo que les ha ralentizado.

Una advertencia antes de continuar, ya que condiciona todo lo que viene a continuación. La IA es un participante, nunca un moderador ni un juez. Aporta elementos a la retrospectiva del mismo modo que lo hace cualquier participante. No dirige la reunión, no puntúa a su equipo ni decide qué hay que corregir. Las personas leen sus comentarios, los evalúan y eligen lo que realmente importa. Mantenga esa línea clara y la práctica seguirá siendo eficaz; si la difumina, habrá entregado su proceso de mejora a una herramienta que no puede asumir la responsabilidad del resultado.

La sesión: una retrospectiva de fin de sesión

El mecanismo es deliberadamente sencillo. Al finalizar una sesión de trabajo (una tarea de programación, un trabajo de investigación, una refactorización), el agente escribe una entrada de retroalimentación sincera en un archivo del repositorio en el que estaba trabajando. Al agente le lleva menos de un minuto. Una persona tarda aproximadamente el mismo tiempo en comprobar que todo esté en orden. Ese es todo el ciclo.

Una buena entrada consta de cuatro partes:

1. Lo que salió bien: los momentos que merece la pena destacar, referidos a algo concreto que haya ocurrido durante la sesión. No se trata de elogios ni de relleno. Si no se puede señalar un momento específico, no se incluye.
2. Fricción: aquellos casos en los que el trabajo resultó más complicado de lo necesario. Cada elemento de fricción se clasifica con una de las diez etiquetas fijas de causa raíz (que se indican a continuación) y termina con un «→ Solución:» del tamaño de un ticket, es decir, la norma que lo hace útil. No hay constatación sin solución.
3. Una solución prioritaria del tipo «Haga esto primero»: el único cambio que habría sido de mayor ayuda. Un punto destacado en primer lugar, de modo que un lector ocupado que no lea nada más pueda leer lo que realmente importa.
4. Suposiciones formuladas: cada punto en el que el agente ha completado una laguna con una suposición. Son muy valiosas. Una suposición es un punto en el que el contexto era ambiguo o faltaba información; el agente le muestra exactamente dónde tuvo que inventarse una respuesta.

Hay dos principios que garantizan la fiabilidad de las entradas. Solo se citan hechos contrastados: cada punto hace referencia a algo que realmente ocurrió, por lo que nadie lee consejos genéricos. Y la honestidad es recíproca: el agente critica el material que se le ha entregado y sus propios errores. Una entrada que solo culpa al código fuente y nunca dice «He interpretado mal esto y he perdido veinte minutos» no es honesta; esta práctica exige ambas cosas.

Las diez etiquetas de causas fundamentales

Cada elemento de fricción recibe exactamente una etiqueta. Un vocabulario reducido y fijo es lo que convierte un montón de quejas aisladas en un patrón sobre el que puede actuar: cuando la misma etiqueta aparece en diez sesiones, sabrá en qué dedicar su próxima hora. Estas diez etiquetas abarcan las formas en que el trabajo real se ve obstaculizado.

Etiqueta	Qué significa	Dónde suele aparecer la solución
ambiguous-instruction	El escrito se puede interpretar de más de una forma.	La persona que redacta la tarea
missing-context	No se facilitó la información que necesitaba el agente.	El resumen, o el contexto compartido
incorrect-context	La información que se le facilitó era errónea o estaba desactualizada.	El resumen, o el contexto compartido
missing-documentation	El repositorio no recoge información que debería incluir.	La documentación / CLAUDE.md / AGENTS.md
incorrect-documentation	La documentación existe, pero es errónea o está desactualizada.	La documentación / CLAUDE.md / AGENTS.md
work-material-friction	El material en el que se estaba trabajando dificultó el cambio (código, cuenta o plantilla enredados).	La cartera de trabajo pendiente / la deuda técnica
missing-access-or-tool	No se disponía de una credencial, un permiso o una herramienta.	Operaciones / plataforma / control de acceso
agent-error	El agente se equivocó: una interpretación errónea, un giro equivocado, un esfuerzo en vano.	El propio relato del agente, con toda sinceridad
changed-requirements	El gol se marcó a mitad de la sesión.	Planificación / gestión del alcance
environment-friction	El entorno de desarrollo nos dio problemas: compilaciones inestables, configuración lenta y herramientas defectuosas.	Experiencia de los desarrolladores

(En la versión 2, las habilidades han pasado codebase-frictiona denominarse work-material-friction; las entradas anteriores que conservan la denominación anterior siguen considerándose parte de la misma causa.)

Fíjese en cómo las etiquetas reparten las responsabilidades de forma clara. Algunas se refieren a usted: ambiguous-instruction, missing-context. Otras se refieren al proyecto: missing-documentation, work-material-friction, environment-friction. Y se agent-errorrefiere al agente. Esa distribución es precisamente la clave: evita que el registro se convierta en una lista de quejas y lo transforma en un mapa que indica dónde es necesario mejorar, por todas las partes.

El registro: Markdown sin formato, en su repositorio

No es necesario instalar ningún producto para la fase de captura. El agente escribe en docs/ai-retros/entries/en formato Markdown sin formato, y se integra junto con el código. Se trata de una decisión deliberada:

• Se encuentra allí donde se llevó a cabo el trabajo. La discrepancia se produjo en este repositorio; allí también se encuentra el registro de la misma. Cualquiera que consulte el historial de Git podrá ver el comentario junto al cambio que la motivó.
• Se puede comparar y buscar con grep. ¿Desea ver todos los elementosmissing-documentation del último mes? Eso es un grep. ¿Quiere comprobar si la fricción ha disminuido tras corregir la compilación? Está en el control de versiones.
• Es independiente de la herramienta que se utilice. El Markdown en una carpeta funciona con cualquier agente, cualquier editor y cualquier proceso. No hay nada propietario, ni nada que haya que migrar más adelante.

A continuación se muestra un ejemplo ilustrativo de una entrada. Se trata de una sesión ficticia destinada a mostrar el formato; no son datos reales de un piloto:

# Session retro — add rate limiting to the public API
Agent: Claude Code · 2026-07-13 · ~50 min

## Do this first
→ Fix: Document the Redis connection setup in CLAUDE.md — three of us
  will hit this same wall. (missing-documentation)

## What went well
- The `middleware/` folder has a clear pattern; the existing auth
  middleware was a clean model to copy for the rate limiter.
- Tests ran fast once the service was up.

## Friction
- Nothing documented that the test suite needs Redis running locally.
  Spent ~15 min chasing a connection error before finding it by reading
  docker-compose.yml. (missing-documentation)
  → Fix: Add a "Running tests locally" section to CLAUDE.md naming the
    Redis dependency and the `docker compose up redis` command.
- The brief said "add sensible rate limits" without numbers. I chose
  100 req/min per key. (ambiguous-instruction)
  → Fix: Decide the real limits with the team and put them in the ticket.
- `config/limits.ts` and `config/throttle.ts` both looked like the right
  home for the setting; I couldn't tell which was canonical. (work-material-friction)
  → Fix: Merge or clearly comment which config owns rate limiting.

## Guesses I made
- Assumed 100 req/min because the payment endpoints use that. May be
  wrong for read-heavy public endpoints — please check.
- Assumed rate-limit responses should be 429 with a Retry-After header.

Considérelo como una nota de un participante, porque eso es lo que es. Es concreta, expone sus propias hipótesis y cada problema viene acompañado de un paso siguiente.

Incorporarlo a la retrospectiva de su equipo

Las entradas individuales constituyen la materia prima. Antes de su sesión retrospectiva, una fase complementaria de síntesis revisa las entradas registradas desde la última vez y elabora un resumen de una página para la reunión: las fricciones que se han repetido, las soluciones principales agrupadas por etiqueta y las conjeturas que siguen reapareciendo en el mismo lugar. Se rige por los mismos criterios que las entradas (sin elogios ni relleno, ninguna constatación sin una solución), y su honestidad es recíproca: critica las entradas que se le han facilitado (pruebas insuficientes, una solución demasiado vaga para ponerla en práctica) con la misma facilidad con la que las resume.

Y luego está la parte humana, que no cambia:

1. Lea el resumen antes de la reunión de retroalimentación: considérelo como la lectura previa de un participante más, no como el orden del día.
2. Anote los dos primeros puntos en el tablero, junto a lo que han aportado sus compañeros. Ahora, la notamissing-documentation de la IA aparece junto a la de un compañero que dice «la incorporación me llevó una semana», y puede ver que se trata del mismo problema.
3. Debatan y tomen una decisión en equipo. El agente ha planteado el asunto; los presentes en la sala son los responsables de lo que suceda a continuación. Habrá asuntos que se abordarán, otros que se dejarán en suspenso y otros con los que no estarán de acuerdo. No pasa nada: eso es una contribución de los participantes, no un sistema que dicta lo que hay que hacer.

Hay dos formas de completar este último paso, y la primera no tiene ningún coste:

• Con cualquier herramienta de retrospectiva. El resumen no es más que un documento. Léalo antes de la reunión y añada uno o dos puntos destacados al tablero que utilice, incluidas las notas adhesivas. Toda la práctica funciona de esta manera, de principio a fin, sin necesidad de TeamRetro ni de ningún otro producto específico.
• Con TeamRetro, el agente publica por sí mismo. Si su equipo lleva a cabo sus retrospectivas en TeamRetro, el agente puede preparar sus recomendaciones a partir del registro y, con su confirmación en cada punto, publicarlas a través del servidor MCP de TeamRetro: puntos en espera para su próxima retrospectiva, acciones cuando una solución ya tiene un responsable, o ideas aportadas directamente al tablero de trabajo. Cada punto publicado lleva el prefijo [AI retro], de modo que la sala pueda ver qué participante lo ha planteado. Esa es la diferencia en una sola línea: en lugar de que sea usted quien transmita los comentarios de la IA a la reunión, es el propio participante quien los presenta.

Empezar en unos 10 minutos

Todo el proyecto es de código abierto bajo una licencia MIT. El repositorio teamretro-skills abarca ambas vías: ai-session-retro(que redacta la entrada de fin de sesión) y (ai-retro-briefque sintetiza las entradas en el resumen previo a la retro) no requieren ningún producto en absoluto, y teamretro-post-recommendationsañade la ruta de publicación para los equipos de TeamRetro. Un paquete de indicaciones independiente de la herramienta completa el conjunto.

Para empezar:

1. Clone el repositorio e incorpore las habilidades a su configuración de Claude Code, o utilice el paquete de indicaciones si trabaja con otra herramienta.
2. ¿No utiliza Claude Code? El paquete de indicaciones está diseñado para funcionar con Cursor, GitHub Copilot o cualquier agente al que pueda proporcionar una indicación del sistema: la misma entrada de cuatro partes, las mismas diez etiquetas y el mismo principio de «no hay solución sin corrección».
3. Realice una sesión con la herramienta activada. Al finalizar, lea la entrada que haya generado. Esa primera lectura suele ser el momento en el que todo cobra sentido: el agente habrá señalado algún aspecto de su proyecto que usted ya intuía, pero que nunca había puesto por escrito.

Dirija las entradas a una carpetadocs/ai-retros/entries/ del repositorio en el que trabajen sus agentes, realice el commit y ya habrá dado el primer paso.

Limitaciones sinceras

Se trata de un despacho joven que se gana la confianza de sus clientes al ser sincero sobre lo que no puede hacer.

• Una IA no puede detectar todos sus propios errores. Algunos agent-errorproblemas son invisibles para el agente que los ha generado. No sabe lo que no sabe. La revisión humana no es un mero complemento opcional; es la forma de detectar los puntos ciegos. Por eso la IA sigue siendo un participante y nunca el juez.
• Una entrada es solo una anécdota. Se necesitan aproximadamente cinco entradas para que los patrones cobren sentido. Los contratiempos de una sola sesión podrían deberse simplemente a la mala suerte de esa sesión; que se repita la misma etiqueta cinco veces es una señal. Espere un par de semanas antes de sacar conclusiones definitivas.
• El agente informa de su experiencia, no de la realidad objetiva. Cuando indique que la documentación es errónea, compruébelo: a veces la documentación es correcta y es el agente quien la ha malinterpretado. Eso sigue siendo útil (significa que la documentación se malinterpreta con facilidad), pero la solución es otra.
• Las instrucciones de mala calidad dan lugar a entradas de mala calidad. Esta práctica pone de manifiesto las dificultades; no genera ideas donde no las había. Una sesión con unas instrucciones claras y un repositorio ordenado da como resultado una entrada breve y aburrida, que es exactamente lo que se busca.

Nada de eso resta fuerza al argumento. Sus agentes de IA ya están realizando el trabajo y ya se están topando con obstáculos. La única cuestión es si usted se da cuenta. Deles un minuto al final de la sesión para que se lo comuniquen, analice lo que le devuelvan con criterio humano e incorpore las observaciones sinceras a la sesión de retroalimentación que ya lleva a cabo. Ahí es donde debe situarse la retroalimentación de un participante: junto a su equipo.

Recorrimos todo el circuito con nuestro propio equipo, incluidos los agentes. Vea lo que ocurrió cuando nuestros compañeros de equipo de IA se unieron a nuestra sesión retro.

---

¿Está creando archivos de contexto para sus agentes? Descubra por qué la ingeniería de contexto necesita un ciclo de retroalimentación. Y si es la primera vez que organiza una retrospectiva, empiece por cómo organizar una retrospectiva ágil.