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: 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 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 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 não deve 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 soluções habituais não funcionam. Você não vai revisarCLAUDE.mdlinha por linha de acordo com um cronograma — ninguém faz isso. Você não vai perceber que o código está desatualizado só de olhar, porque ele parece estar em ordem. 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 pelo tempo que a sessão durar, e depois desaparece.

Ninguém diz qual contexto está faltando ou está errado, exceto o próprio elemento 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 formular o pedido 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 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 resumo 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 digam, 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 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 é 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 fumaça.

Isso também se acumula. Corrija osincorrect-documentationitens nesta semana e, nas sessões da próxima semana, você vai se deparar menos com esse obstáculo; assim, 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 parte que faltava — o ciclo de manutenção que impede que o investimento se perca. É de código aberto e está 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 ferramentas 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.

Uma nuance que vale a pena ter em mente. Quando um agente informar que os documentos estão errados, verifique antes de editar — às vezes, os documentos estão corretos e o agente os 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 ao 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.