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 ficar adivinhando. 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 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. 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 convicção 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 não está certo 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 confia nela. As linhas mais onerosas em seus arquivos de contexto não são as que estão faltando. 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 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 foram úteis 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 permanece por mais ou menos o tempo que 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 formular 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 houve atrito e, o que importa aqui, cada ponto de atrito é marcado com uma das dez etiquetas fixas 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 o fez. 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. 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 seguindo um cronograma; 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 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, pois já conhece 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á foi 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 é uma manutenção de contexto orientada pelo uso real: apenas as linhas que realmente causaram um erro em um agente são sinalizadas; assim, 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 em busca de fumaça.

Isso também se acumula. Corrija os itensincorrect-documentation nesta semana e, nas sessões da próxima semana, o impacto nessa barreira será menor, 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, e o humano decide a correção.

Inicie o loop

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 desvalorize. É um projeto de código aberto sob licença MIT:

• Obtenha as habilidades e o pacote de prompts: github.com/TeamRetroHQ/teamretro-skills: uma habilidade do Claude Code que escreve 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 o guia completo: 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, e 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, pois às vezes a documentação está correta e o agente a interpretou mal. Essa ainda é uma indicação útil (uma frase fácil de interpretar erroneamente é uma frase que vale a pena reescrever), mas é uma correção diferente, e é por isso que uma pessoa precisa permanecer envolvida no processo. O agente é um participante que sinaliza o que o incomodou, 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ê ao final de cada sessão. Você só precisa anotá-las. E se sua equipe quiser que essas correções sejam publicadas em um local 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 com [AI retro], ao lado das demais melhorias da sua equipe.