Como coletar feedback de seus agentes de IA

Um agente de IA enviou código para você esta semana. Ele leu seu briefing, vasculhou a base de código, esbarrou em um obstáculo em que a documentação estava errada, adivinhou como contorná-lo e seguiu em frente. Então, a sessão terminou — e tudo o que ele aprendeu sobre os pontos críticos do seu projeto se perdeu com ela. Ninguém perguntou ao único participante que acabou de passar uma hora dentro do seu repositório o que estava causando o atraso.

As retrospectivas existem justamente para preencher essa lacuna para as pessoas: a equipe se reúne, identifica o que ajudou e o que atrapalhou, e transforma isso em mudanças. Os agentes de IA agora estão realizando um trabalho real na sua equipe — e enfrentam os mesmos obstáculos que sua equipe enfrenta, às vezes até mais. Portanto, a pergunta é simples. Se um agente realiza o trabalho da equipe, por que ele não está na retrospectiva?

Este guia trata de como incorporar essa voz. Não se trata de um novo formato de retrospectiva, nem de automatizar as contribuições da sua equipe — trata-se de um novo participante. A IA contribui com feedback; sua equipe continua decidindo o que isso significa. Veja a seguir como coletar essas informações e como incorporá-las à retrospectiva que você já realiza.

Por que vale a pena registrar a experiência do seu agente de IA

O argumento a favor de um “retro” humano é que a memória se desvanece e as lições não são compartilhadas. Com um agente de IA, o problema é ainda mais grave: sua memória de trabalho não se desvanece, ela simplesmente se evapora. No momento em que uma sessão é encerrada, o contexto desaparece. O arquivo README que faltava e que ele gostaria que existisse, a variável de ambiente que não estava documentada, o briefing que poderia ter sido interpretado de três maneiras diferentes — nada disso é transferido para a próxima sessão, a menos que alguém anote.

E os agentes acumulam um tipo específico e útil de informação. Ao longo de uma hora de trabalho, um agente percebe coisas que uma pessoa ignora, pois esta já tem o contexto em mente:

• O documento de integração que descreve uma etapa de compilação que não existe mais.
• A função que três pontos de chamada utilizam de maneiras diferentes; portanto, “siga o padrão” aponta para três padrões.
• A instrução que dizia “limpar a configuração” sem especificar qual configuração nem como fazer a limpeza.
• O conjunto de testes que precisa de um serviço em execução, mas que ninguém indica que você deve iniciar.

Um desenvolvedor humano também se depara com esses problemas, dá de ombros, encontra uma solução alternativa e raramente registra nada — o atrito fica abaixo do limite do que “vale a pena levantar na reunião”. Um agente, quando questionado da maneira correta, relatará cada um deles, com as evidências anexadas. Esse é o valor: não que a IA seja mais inteligente em relação ao seu processo, mas que ela é um novo par de olhos, sem ego e sem tolerância acumulada para esses pequenos aborrecimentos. A colaboração entre humanos e IA funciona melhor quando ambos os lados podem dizer o que os atrasou.

Uma observação importante antes de prosseguirmos, pois ela define tudo o que vem a seguir. A IA é um participante, nunca um facilitador ou um juiz. Ela contribui com pontos para a retrospectiva da mesma forma que qualquer participante. Ela não conduz a reunião, não avalia sua equipe nem decide o que deve ser corrigido. Os seres humanos leem o feedback dela, verificam se faz sentido e escolhem o que é importante. Mantenha essa linha clara e a prática permanecerá saudável; se você a confundir, terá entregue seu processo de melhoria a uma ferramenta que não pode ser responsabilizada pelo resultado.

A prática: uma retrospectiva de fim de sessão

O mecanismo é pequeno de propósito. Ao final de uma sessão de trabalho — seja uma tarefa de programação, um trabalho de pesquisa ou uma refatoração —, o agente escreve uma entrada honesta de retrospectiva em um arquivo no repositório em que estava trabalhando. Isso leva menos de um minuto para o agente. Uma pessoa leva mais ou menos o mesmo tempo para verificar se está tudo certo. Esse é todo o ciclo.

Uma boa redação tem quatro partes:

1. O que deu certo — os momentos que vale a pena guardar, referindo-se a algo concreto que aconteceu na sessão. Não são elogios nem encheção de linguiça. Se não for possível apontar um momento específico, não deve ser incluído.
2. Atrito — onde o trabalho ficou mais difícil do que precisava ser. Cada item de atrito é marcado com um dos dez rótulos fixos de causa raiz (abaixo) e — essa é a regra que o torna útil — termina com um “→ Solução:” do tamanho de um ticket. Não há constatação sem uma solução.
3. A solução principal do tipo “Faça isso primeiro” — a única mudança que teria ajudado mais. Um item destacado no topo, para que um leitor ocupado, que não leia mais nada, leia o que realmente importa.
4. Suposições feitas — todos os pontos em que o agente preencheu uma lacuna com uma suposição. Esses são valiosos. Uma suposição é um ponto em que o contexto estava ambíguo ou faltava informação; o agente está mostrando exatamente onde precisou inventar uma resposta.

Dois princípios garantem a confiabilidade das contribuições. Apenas momentos comprovados — cada ponto faz referência a algo que realmente aconteceu, para que ninguém leia conselhos genéricos. E a honestidade vale para os dois lados: o agente critica o material que recebeu e seus próprios erros. Uma postagem que apenas culpa o código-fonte e nunca diz “Eu interpretei mal isso e perdi vinte minutos” não está sendo honesta; a prática exige ambos.

As dez categorias de causas fundamentais

Cada ponto de atrito recebe exatamente um rótulo. Um vocabulário pequeno e fixo é o que transforma uma pilha de reclamações isoladas em um padrão sobre o qual você pode agir: quando o mesmo rótulo aparece em dez sessões, você sabe onde dedicar sua próxima hora. Esses dez rótulos abrangem as formas pelas quais o trabalho real fica bloqueado.

Etiqueta	O que isso significa	Onde a correção geralmente ocorre
ambiguous-instruction	O documento poderia ser interpretado de mais de uma maneira.	A pessoa que está redigindo a tarefa
missing-context	As informações de que o agente precisava não foram fornecidas.	O briefing, ou o contexto compartilhado
incorrect-context	As informações fornecidas estavam incorretas ou desatualizadas.	O briefing, ou o contexto compartilhado
missing-documentation	O repositório não documenta algo que deveria.	A documentação / CLAUDE.md / AGENTS.md
incorrect-documentation	A documentação existe, mas está incorreta ou desatualizada.	A documentação / CLAUDE.md / AGENTS.md
codebase-friction	O próprio código dificultou a alteração — estrutura confusa, sem pontos de integração.	A base de código / a lista de pendências de dívida técnica
missing-access-or-tool	Uma credencial, permissão ou ferramenta não estava disponível.	Operações / plataforma / controle de acesso
agent-error	O agente errou — interpretou mal, tomou o caminho errado, foi um esforço em vão.	O próprio relato do agente, com toda a sinceridade
changed-requirements	O gol foi marcado no meio da sessão.	Planejamento / gerenciamento do escopo
environment-friction	O ambiente de desenvolvimento deu trabalho — compilação instável, configuração demorada, ferramentas com falhas.	Experiência do desenvolvedor

Observe como os rótulos dividem as responsabilidades de forma clara. Alguns apontam para você — ambiguous-instruction, missing-context. Outros apontam para o projeto — missing-documentation, codebase-friction, environment-friction. Eagent-error aponta para o executor. Essa diversificação é o ponto principal: ela evita que o registro se torne uma lista de reclamações e o transforma em um mapa que mostra onde são necessárias melhorias, por parte de todos os envolvidos.

O log: Markdown simples, no seu repositório

Não há nenhum produto a ser instalado para a etapa de captura. O agente grava emdocs/ai-retros/entries/ como Markdown simples, que é submetido junto com o código. Essa é uma escolha deliberada:

• Está onde o trabalho foi realizado. O atrito ocorreu neste repositório; o registro disso também está aqui. Qualquer pessoa que ler o histórico do Git verá o feedback ao lado da alteração que o motivou.
• grepÉ possível comparar e pesquisar. Quer todosmissing-documentationos itens do mês passado? Está lá. Quer ver se a tendência de atrito diminuiu depois que você corrigiu a compilação? Está no controle de versão.
• É independente de ferramentas. O Markdown em uma pasta funciona com qualquer agente, qualquer editor, qualquer processo. Nada proprietário, nada para migrar posteriormente.

Aqui está um exemplo ilustrativo de registro — trata-se de uma sessão fictícia para mostrar o formato, não são dados reais de um 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.

Leia isso como uma anotação de participante, porque é exatamente isso que é. É específico, apresenta suas próprias hipóteses e cada problema vem acompanhado de um próximo passo.

Incorporando isso à retrospectiva da sua equipe

As entradas individuais são a matéria-prima. Antes da sua retrospectiva, uma etapa de síntese complementar analisa as entradas registradas desde a última vez e produz um resumo de uma página para a reunião: os atritos que se repetiram, as principais soluções agrupadas por rótulo, as suposições que continuam surgindo no mesmo ponto. Ele segue o mesmo padrão das entradas — sem elogios nem encheção de linguiça, nenhuma constatação sem uma solução — e sua honestidade vale para os dois lados: ele critica as entradas que recebeu (evidências insuficientes, uma solução muito vaga para ser colocada em prática) com a mesma facilidade com que as resume.

E, em seguida, a parte humana, que não muda:

1. Leia o resumo antes da retrospectiva — encare-o como mais uma leitura prévia dos participantes, e não como a pauta.
2. Coloque o primeiro ou os dois primeiros itens no quadro, ao lado do que sua equipe trouxe. Agora, a anotação damissing-documentation IA fica ao lado da observação de um colega de equipe que diz “a integração levou uma semana” — e você pode ver que se trata do mesmo problema.
3. Discutam e decidam em equipe. O agente trouxe o assunto à tona; cabe às pessoas presentes na sala decidir o que acontecerá a seguir. Alguns assuntos serão colocados em prática, outros serão deixados de lado e outros ainda serão alvo de discordância. Tudo bem — isso é uma contribuição dos participantes, não uma imposição do sistema.

Existem duas maneiras de concluir esta última etapa, e a primeira não custa nada:

• Com qualquer ferramenta de retrospectiva. O resumo é apenas um documento. Leia-o antes da reunião e adicione o(s) primeiro(s) item(ns) ao quadro que você estiver usando — incluindo post-its. Todo o processo funciona assim, do início ao fim, sem o TeamRetro ou qualquer outro produto específico.
• Com o TeamRetro, o agente publica por conta própria. Se sua equipe realiza suas retrospetivas no TeamRetro, o agente pode preparar suas recomendações a partir do registro e — com a sua confirmação em cada item — publicá-las por meio do servidor MCP do TeamRetro: itens em espera na fila para sua próxima retrospectiva, ações quando uma correção já tem um responsável ou ideias contribuídas diretamente no quadro de tarefas. Cada item publicado é precedido pelo prefixo [AI retro], para que todos na sala possam ver qual participante o levantou. Essa é a diferença em uma linha: em vez de você levar o feedback da IA para a reunião, o próprio participante o apresenta.

Comece em cerca de 10 minutos

O projeto inteiro é de código aberto sob uma licença MIT. O repositório TeamRetro-skills abrange ambas as opções:ai-session-retro (escreve uma entrada de fim de sessão) eai-retro-brief (sintetiza as entradas no resumo pré-retro) não exigem nenhum produto, eteamretro-post-recommendationsadiciona a rota de postagem para equipes do TeamRetro. Um pacote de prompts independente de ferramentas completa o conjunto.

Para começar:

1. Clone o repositório e insira as habilidades na sua configuração do Claude Code, ou importe o pacote de prompts caso você trabalhe com outra plataforma.
2. Ainda não usa o Claude Code? O pacote de prompts foi desenvolvido para funcionar com o Cursor, o GitHub Copilot ou qualquer agente ao qual você possa enviar um prompt de sistema — a mesma entrada em quatro partes, os mesmos dez rótulos, a mesma regra de “nenhuma solução sem correção”.
3. Faça uma sessão com o programa ativado. No final, leia o que ele registrou. Essa primeira leitura costuma ser o momento em que tudo faz sentido — o agente terá identificado algo sobre o seu projeto que você já sabia, de certa forma, mas nunca havia colocado no papel.

Direcione as entradas para umadocs/ai-retros/entries/pasta no repositório em que seus agentes trabalham, faça o commit e pronto: você já começou.

Limitações sinceras

Este é um escritório jovem que conquista a confiança dos clientes por ser sincero sobre o que não pode fazer.

• Uma IA não consegue enxergar todos os seus próprios erros. Algumasagent-errorfalhas são invisíveis para o agente que as cometeu — ele não sabe o que não sabe. A revisão humana não é um mero complemento opcional; é assim que os pontos cegos são detectados. É por isso que a IA permanece como participante e nunca como juíza.
• Uma observação é apenas uma anedota. São necessárias cerca de cinco observações para que os padrões tenham algum significado. Um problema em uma única sessão pode ser apenas azar daquela sessão; a mesma classificação cinco vezes seguidas já é um sinal. Espere algumas semanas antes de tirar conclusões precipitadas.
• O agente relata sua experiência, não a realidade objetiva. Quando ele afirma que a documentação está errada, verifique — às vezes a documentação está correta e o agente a interpretou mal. Isso ainda é útil (significa que a documentação é fácil de ser mal interpretada), mas a correção a ser feita é outra.
• Briefings ruins geram entradas ruins. Essa prática apenas traz à tona atritos; ela não cria insights onde não havia nenhum. Uma sessão com um briefing claro e um repositório organizado produz uma entrada curta e sem graça — o que é exatamente o que se espera.

Nada disso enfraquece o argumento. Seus agentes de IA já estão fazendo o trabalho e já estão esbarrando em obstáculos. A única questão é se você vai descobrir isso. Dê a eles um minuto no final da sessão para que se expressem, analise o que for relatado com o bom senso humano e incorpore as observações sinceras à retrospectiva que você já realiza — bem ao lado de sua equipe, onde o feedback dos participantes deve estar.

---

Quer saber o que aconteceu quando fizemos isso com a nossa própria equipe? Leia Nossa IA participou da nossa retrospectiva — veja o que ela nos disse. Está criando arquivos de contexto para seus agentes? Veja por que a engenharia de contexto precisa de um ciclo de feedback. E se você ainda não tem experiência em conduzir retrospectivas, comece com como conduzir uma retrospectiva ágil.