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 certo 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: um CLAUDE.mdna 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 redescobrir isso 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. Você escreveu o contexto uma vez, a base de código evoluiu e, agora, metade dele está discretamente errada. 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 os documentos comuns nesse aspecto, por duas razões.

Primeiro, um agente as interpreta literalmente e age de acordo com elas. Um ser humano dá uma olhada rápida em um arquivo README desatualizado, percebe que algo está errado e pergunta a alguém. Um agente leva CLAUDE.mdao 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 a coisa errada 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. Em caso de lacuna, o agente às vezes consegue contornar a situação ou identificá-la. Mas, diante de uma afirmação errada apresentada com convicção, ele acredita nela. As linhas mais onerosas em seus arquivos de contexto não são as que estão faltando. São aquelas que costumavam ser verdadeiras.

Então, você precisa de um ciclo de manutenção. O problema é que os métodos habituais não funcionam. Você não vai fazer uma auditoria CLAUDE.mdlinha por linha de acordo com um cronograma. Ninguém faz isso. Você não vai perceber que o código está desatualizado de fora, porque ele parece estar certo. A desatualização só se revela no momento do uso, para quem estiver usando. 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 enquanto a sessão dura 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 registrar 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 retrospectiva de IA no final da sessão produz. Ao final de uma sessão de trabalho, o agente redige uma anotação breve e sincera: o que deu certo, onde surgiram atritos e, o 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 queCLAUDE.md você deve adicionar à sua documentação.
• incorrect-documentation****: a documentação existia, mas estava incorreta ou desatualizada. Essa é 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 usá-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 dos 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: as suposições. Uma boa anotação 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 uma semana de suposições e você terá uma lista de tarefas para seus arquivos de contexto que você mesmo nunca teria conseguido escrever, pois já conhece as respostas e, por isso, não consegue perceber onde elas estão faltando.

Aqui está o formato do resultado obtido. Trata-se de um exemplo ilustrativo, não de 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 representa uma alteraçã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 acionaram um agente são sinalizadas; assim, você corrige o que está de fato com problema, em vez de reler o que já está correto. É a diferença entre um detector de fumaça e percorrer o prédio farejando fumaça.

Isso também se acumula. Corrija os itensincorrect-documentation nesta semana e as sessões da próxima semana encontrarão 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 ficar 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 o desvio. Essa é uma colaboração saudável entre humanos e IA: o agente identifica o desvio, o humano decide a correção. O mesmo ciclo funciona entre as pessoas também: reunimos as memórias particulares de cinco desenvolvedores sobre o Claude Code e promovemos as regras que vários de nós havíamos anotado independentemente.

Inicie o ciclo

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

• Baixe o pacote de habilidades e 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 abrange todos os dez rótulos, a verificação humana e como as contribuições alimentam uma retrospectiva da equipe, e não apenas seus arquivos de contexto.
• Aprofunde-se no próprio ciclo: os 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, pois às vezes a documentação está correta e o agente a interpretou mal. Essa ainda é uma indicação útil (uma linha fácil de ser mal interpretada é uma linha que vale a pena reescrever), mas é uma correção diferente, e é por isso que um ser humano permanece 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 entregam essas correções a você no final de cada sessão. Você só precisa anotá-las. E se sua equipe quiser que essas correções fiquem em um 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, com a sua confirmação[AI retro], marcadas ao lado das demais melhorias da sua equipe.