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 lo ralentizaba.

Las retrospectivas sirven precisamente para subsanar esa brecha en el equipo: el equipo se reúne, identifica lo que ha ayudado y lo que ha supuesto un obstáculo, y lo transforma en un cambio. Los agentes de IA están realizando ahora un 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, sino 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.

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

El argumento a favor de un «retro» humano 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 finaliza una sesión, el contexto desaparece. El archivo README 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… Nada de ello se traslada a la siguiente sesión a menos que alguien lo anote.

Además, los agentes recogen un tipo de información específico y útil. En 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 iniciación que describe un paso de compilación que ya no existe.
• La función que las tres llamadas utilizan de forma diferente, por lo que «siga el patrón» hace referencia a tres patrones.
• Las instrucciones que decían «limpiar la configuración» sin especificar de qué configuración se trataba ni cómo debía realizarse dicha limpieza.
• El conjunto de pruebas que requiere que esté en ejecución 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; la fricción está por debajo del umbral de «merecer la pena plantearlo en la reunión». Un agente, si se le pregunta de la forma adecuada, informará de cada uno de ellos, adjuntando las pruebas correspondientes. 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 esto 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 al final de la sesión

El mecanismo es pequeño a propósito. Al final de 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é correcto. Ese es todo el ciclo.

Una buena entrada consta de cuatro partes:

1. Lo que salió bien: los momentos que merece la pena recordar, referidos a algo concreto que haya ocurrido durante la sesión. No se trata de elogios ni de comentarios de relleno. Si no se puede señalar un momento concreto, 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 etiqueta con una de las diez etiquetas fijas de causa raíz (que se indican a continuación) y —esta es la norma que lo hace útil— termina con un «→ Solución:» del tamaño de un ticket. 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, para que un lector ocupado que no lea nada más pueda leer lo que realmente importa.
4. Suposiciones realizadas: 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 su contexto era ambiguo o estaba incompleto; el agente le está mostrando 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 facilitado y sus propios errores. Una entrada que solo culpa al código fuente y nunca dice «Lo he interpretado mal 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 individuales en un patrón sobre el que puede actuar: cuando la misma etiqueta aparece a lo largo de diez sesiones, sabrá en qué dedicar su próxima hora. Estas diez etiquetas abarcan las formas en que se obstaculiza el trabajo real.

Etiqueta	Qué significa	Dónde suele aparecer la corrección
ambiguous-instruction	El escrito podría interpretarse 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 común
incorrect-context	La información que se facilitó era errónea o estaba desactualizada.	El resumen, o el contexto común
missing-documentation	El repositorio no incluye información que debería contener.	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
codebase-friction	El propio código dificultó el cambio: una estructura enredada, sin puntos de unión.	El código fuente / la lista de tareas pendientes relacionadas con 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 lectura errónea, un giro equivocado, un esfuerzo en vano.	El propio relato del agente, con toda sinceridad
changed-requirements	El objetivo cambió a mitad de la sesión.	Planificación / gestión del alcance
environment-friction	El entorno de desarrollo se rebeló: compilaciones inestables, configuración lenta y herramientas defectuosas.	Experiencia de los desarrolladores

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, codebase-friction, environment-friction. Yagent-error se refiere 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 endocs/ai-retros/entries/formato Markdown sin formato, y los cambios se incorporan junto con el código. Se trata de una decisión deliberada:

• Se encuentra allí donde se llevó a cabo el trabajo. La discusión tuvo lugar en este repositorio; allí también se encuentra el registro de la misma. Cualquiera que lea el historial de Git podrá ver los comentarios junto al cambio que los motivó.
• grepSe puede comparar y buscar con grep. ¿Quiere todosmissing-documentationlos elementos del último mes? Ahí los tiene. ¿Quiere ver cómo baja la fricción después de 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: se trata de una sesión ficticia destinada a mostrar el formato, no de 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. (codebase-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 va acompañado de un paso siguiente.

Incorporarlo a la retrospectiva de su equipo

Las entradas individuales constituyen la materia prima. Antes de su reunión retrospectiva, una fase de síntesis complementaria 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 retro: considérelo como la lectura previa de un participante más, no como el orden del día.
2. Coloque uno o dos de los elementos superiores en el tablero, junto a lo que han aportado sus compañeros. Ahora, la nota demissing-documentation la IA aparece junto al comentario de un compañero de equipo que dice «la incorporación me llevó una semana», y se puede ver que se trata del mismo problema.
3. Debatan y tomen una decisión en equipo. El agente ha planteado el tema; los presentes en la sala son los responsables de lo que suceda a continuación. Habrá temas que se abordarán, otros que se dejarán de lado 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 así, 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: elementos en espera para su próxima retrospectiva, acciones cuando una solución ya tiene un responsable, o ideas aportadas directamente a un tablero activo. Cada elemento publicado lleva el prefijo [AI retro], para que los asistentes a la sala puedan ver qué participante lo ha planteado. Esa es la diferencia en una sola línea: en lugar de que usted 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 escribe la entrada de fin de sesión) yai-retro-brief (que sintetiza las entradas en el resumen previo a la retro) no requieren ningún producto, yteamretro-post-recommendations añade la vía 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 resultados sin una solució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á identificado algún aspecto de su proyecto que usted ya intuía, pero que nunca había puesto por escrito.

Dirija las entradas a unadocs/ai-retros/entries/carpeta 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. Ciertasagent-errordificultades resultan invisibles para el agente que las 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 sola entrada es 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.
• Unas instrucciones deficientes dan lugar a entradas deficientes. Esta práctica pone de manifiesto las contradicciones; no genera ideas nuevas donde no las había. Una sesión con unas instrucciones claras y un repositorio ordenado da como resultado una entrada breve y aburrida, lo cual 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 cuenten, analice lo que le devuelvan con criterio humano e incorpore las partes sinceras a la sesión de retroalimentación que ya lleva a cabo —justo junto a su equipo, que es donde debe estar la opinión de los participantes—.

---

¿Quiere conocer la historia de lo que ocurrió cuando aplicamos esto a nuestro propio equipo? Lea «Nuestra IA se unió a nuestra retrospectiva: esto es lo que nos contó». ¿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 llevar a cabo una retrospectiva ágil».