A engenharia de contexto precisa de um ciclo de feedback

A engenharia de contexto é a disciplina que consiste em fornecer a um agente de IA as informações certas, no formato adequado e no momento certo, para que ele realize um bom trabalho em vez de ter que adivinhar. Na prática, para a maioria das equipes, isso significa arquivos: umCLAUDE.md na raiz do repositório, um AGENTS.md, uma pasta com regras e convenções, um prompt do sistema que alguém configurou uma vez. Você documenta como seu projeto funciona para que o agente não precise redescobri-lo a cada sessão.

Essa é, de fato, a medida de maior impacto que você pode tomar para tornar os agentes úteis. E quase todos que fazem isso enfrentam o mesmo problema não explicitado: esses arquivos ficam desatualizados, e ninguém sabe quais partes estão erradas. Você escreveu o contexto uma vez, a base de código evoluiu e, agora, metade dele está discretamente incorreto. Essa prática tem uma etapa de entrada — escrever o contexto —, mas não possui um ciclo de manutenção. É essa lacuna que este post aborda.

O contexto é código, e o código se deteriora

Já sabemos que a documentação fica desatualizada. A etapa de compilação que você documentou é substituída, a pasta que você descreveu é renomeada, a convenção que você registrou é substituída, e a documentação continua descrevendo com segurança o mundo antigo. Os arquivos de contexto são piores do que a documentação comum nesse aspecto, por duas razões.

Primeiro, um agente as lê à risca e age de acordo com elas. Um ser humano dá uma olhada rápida em um README desatualizado, percebe que algo está errado e pergunta a alguém. Um agente levaCLAUDE.md ao pé da letra. Se disser “execute make setup” e esse alvo tiver sido excluído no último trimestre, o agente não se importa — ele perde tempo tentando fazer o que está errado funcionar, ou inventa uma solução alternativa e segue em frente, levando a instrução incorreta para sua saída.

Em segundo lugar, um contexto incorreto é pior do que a falta de contexto. Uma lacuna, às vezes, o agente consegue contornar ou identificar. Uma afirmação errada, mas proferida com confiança, ele acredita. As linhas mais onerosas em seus arquivos de contexto não são as que faltam — são aquelas que antes eram verdadeiras.

Então, você precisa de um ciclo de manutenção. O problema é que as opções habituais não funcionam. Você não vai auditarCLAUDE.mdlinha por linha de acordo com um cronograma — ninguém faz isso. Você não vai perceber que o código está desatualizado olhando de fora, porque ele parece estar em boas condições. A obsolescência só se revela no momento do uso, para quem estiver usando o código. E, cada vez mais, quem está usando não é uma pessoa.

A única testemunha que sabe

Eis a mudança. O agente que acabou de executar uma sessão no seu projeto é o único participante que sabe, concretamente, quais partes do seu contexto ajudaram e quais partes o enganaram. Ele simplesmente usou os arquivos. Executou o comando de compilação desatualizado. Encontrou a pasta que não existe. Seguiu o padrão que acabou se revelando três padrões. Esse conhecimento existe — mais ou menos enquanto a sessão durar, e depois desaparece.

Ninguém diz qual contexto está faltando ou está errado, exceto o próprio sistema que acabou de ser afetado por isso. Esse é o ciclo de feedback, bem ali, à espera de ser aproveitado. Basta pedir ao agente para anotar o que aprendeu antes do encerramento da sessão e estruturar a solicitação de forma que o resultado aponte diretamente para os arquivos que precisam ser editados.

O registro retroativo da sessão é o ciclo de manutenção

É exatamente isso que uma análise retrospectiva de IA no final da sessão produz. No final de uma sessão de trabalho, o agente escreve uma anotação curta e sincera: o que deu certo, onde houve atrito e — a parte que importa aqui — cada item de atrito é marcado com um dos dez rótulos fixos de causa raiz e termina com um “→ Corrigir:” do tamanho de um ticket. Duas dessas dez etiquetas apontam diretamente para seus arquivos de contexto:

• missing-documentation**** — o agente precisava de algo que o projeto deveria ter documentado, mas não documentou. Essa é a lista de itens a serem escritos do seu arquivo de contexto. Cada um desses itens é uma linha que você deve adicionar àCLAUDE.md sua documentação.
• incorrect-documentation**** — a documentação existia, mas estava incorreta ou desatualizada. Esta é a lista de itens a corrigir do seu arquivo de contexto. Cada um desses itens é uma linha desatualizada que o agente detectou da única maneira possível: ao utilizá-la e esbarrar em um problema.

Acrescente um terceiro e você terá coberto a maior parte da manutenção de que precisará: ambiguous-instruction****, nos casos em que um documento ou uma regra possam ser interpretados de mais de uma maneira. Esse é o ciclo. Você não faz auditoria em seus arquivos de contexto de acordo com um calendário; você deixa que os agentes que os utilizam lhe indiquem, no momento do uso, exatamente quais linhas devem ser alteradas — com as evidências anexadas, pois a prática se baseia exclusivamente em evidências citadas.

E há um quarto sinal que é fácil deixar passar despercebido: as suposições. Uma boa entrada lista todos os pontos em que o agente preencheu uma lacuna com uma suposição. Cada suposição é um ponto em que seu contexto era tão escasso que o agente teve que inventar uma resposta. Leia as suposições de uma semana e você terá uma lista de tarefas para seus arquivos de contexto que você mesmo nunca teria conseguido escrever — porque você já sabe as respostas e, por isso, não consegue perceber onde elas estão faltando.

Aqui está o formato do resultado — um exemplo ilustrativo, não são dados reais:

## 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 linha corresponde a uma edição específica em um arquivo específico. Esse é um ciclo de manutenção que uma pessoa realmente executará, pois o trabalho de identificar o problema — a parte mais trabalhosa — já está feito.

Por que isso é melhor do que a auditoria manual

Você poderia tentar manter os arquivos de contexto atualizados da maneira antiga: agendar uma revisão, lê-los do início ao fim, verificar cada afirmação em relação à realidade. Isso não acontece e, mesmo quando acontece, não é a ferramenta certa. Ao ler um documento de forma abstrata, não dá para saber quais linhas estão desatualizadas — todas parecem plausíveis. A desatualização só fica visível durante o uso. O registro retroativo é a manutenção de contexto orientada pelo uso real: apenas as linhas que realmente causaram um erro em um agente são sinalizadas, então você corrige o que está realmente com problema, em vez de reler o que já está certo. É a diferença entre um detector de fumaça e percorrer o prédio farejando fumaça.

Isso também se acumula. Corrija osincorrect-documentationitens nesta semana e, nas sessões da próxima semana, o grupo encontrará menos obstáculos, de modo que o registro fica mais curto e passa a abordar questões mais profundas. Seus arquivos de contexto tendem a ser precisos não porque alguém os auditou, mas porque as pessoas — e os agentes — que os utilizam tinham uma maneira simples e estruturada de relatar os desvios. Essa é uma colaboração saudável entre humanos e IA: o agente identifica o desvio, o humano decide a correção.

Inicie o loop

Se você já está investindo em engenharia de contexto, esta é a metade que faltava — o ciclo de manutenção que impede que o investimento se perca. É um projeto de código aberto sob licença do MIT:

• Baixe as habilidades e o pacote de prompts: github.com/TeamRetroHQ/teamretro-skills — uma habilidade do Claude Code que redige a entrada de fim de sessão, outra que sintetiza as entradas em um resumo e um pacote de prompts independente de ferramenta para o Cursor, o GitHub Copilot ou qualquer agente ao qual você possa enviar prompts.
• Veja a prática completa: como coletar feedback de seus agentes de IA aborda todos os dez rótulos, a verificação humana e como as contribuições alimentam uma retrospectiva da equipe — não apenas seus arquivos de contexto.
• Aprofunde-se no próprio ciclo: ciclos de feedback do agente mapeiam todo o panorama — o ciclo de “captura para correção”, as ferramentas que o executam e onde uma sessão se encaixa nesse contexto.

Uma nuance que vale a pena ter em mente. Quando um agente informar que a documentação está errada, verifique antes de editar — às vezes, a documentação está correta e o agente a interpretou mal. Essa ainda é uma indicação útil (uma linha fácil de interpretar erroneamente é uma linha que vale a pena reescrever), mas é uma correção diferente, e é por isso que um ser humano continua no processo. O agente é um participante que sinaliza o que o fez acionar o alerta, nunca a autoridade sobre o que seu projeto deve dizer.

A qualidade dos seus arquivos de contexto depende da última correção feita com rigor. Os agentes que os utilizam estão lhe entregando essas correções no final de cada sessão — basta você anotá-las. E se sua equipe quiser que essas correções sejam publicadas em algum lugar onde as pessoas já costumam olhar, o agente pode preparar suas recomendações e publicá-las diretamente no seu quadro por meio do servidor TeamRetro MCP — confirmadas por você, marcadas [AI retro]com , ao lado das demais melhorias da sua equipe.