AI-DLC em brownfield: engenharia reversa, contexto de 1M e a regra dos 75%

Um projeto greenfield não tem nada que o agente possa entender errado. Um projeto brownfield tem anos de decisões que o agente nunca viu. Gestão de contexto é como você mantém essas decisões dentro da janela por tempo suficiente para que elas importem.

A maioria das demos de AI-DLC começa de uma pasta vazia. O tutorial oficial da AWS constrói um quebra-cabeça de travessia do rio, e a primeira coisa que o workflow faz é detectar que o projeto é greenfield e pular a engenharia reversa, porque não há nada para reverter. Dá uma demo limpa. Não é o trabalho que a maioria de nós tem.

O trabalho que a maioria de nós tem é um serviço que está em produção há quatro anos, com decisões que ninguém escreveu, uma suíte de testes que cobre uma parte dele e um serviço vizinho com quem ele conversa por um contrato que mora na cabeça de alguém. Isso é brownfield, e é onde o AI-DLC ou justifica a cerimônia, ou desperdiça.

Nos pilotos que acompanhei dentro de uma grande organização de engenharia, duas coisas decidiram se o brownfield funcionava. Como o time rodava a engenharia reversa, e como tratava a context window. Nenhuma das duas é problema de ferramenta. As duas são hábitos, e as duas têm regras que dá para escrever.

A engenharia reversa é onde o agente conhece o seu código

Quando você começa um workflow do AI-DLC 2, a fase de Initialization detecta o workspace. Se encontra código existente, a Inception abre com o estágio 2.1, Reverse Engineering, antes de o agente poder te fazer uma única pergunta de requisitos.

O motivo é simples. Um modelo que não leu o seu código vai propor mudanças nele mesmo assim. Vai inventar um padrão que você não usa, duplicar um helper que você já tem e quebrar um contrato implícito entre dois módulos porque nada disse a ele que o contrato existia. O whitepaper original colocou a solução numa linha: em brownfield, primeiro eleve o código para um modelo semântico, um estático (os componentes e suas relações) e um dinâmico (como eles interagem nos casos de uso que importam), para que o contexto de onde a IA trabalha seja conciso e preciso.

Pense na primeira semana de uma pessoa sênior recém-contratada. Você não entrega um ticket no primeiro dia. Deixa a pessoa ler o código, desenhar as caixas e perguntar por que o módulo de pagamentos fala com o ledger por uma fila. A engenharia reversa é essa semana, comprimida num estágio, com o desenho gravado num arquivo.

O AI-DLC 2 roda esse estágio como um pipeline de dois elos. Um agente de desenvolvimento varre o código. Um agente de arquitetura lê a varredura e escreve a síntese. Depois você aprova, como em qualquer outro estágio.

Como o AI-DLC 2 abre um workflow brownfield

Entrada

Você roda /aidlc num repositório que já tem código

↓

1. 0.2O Workspace Detection marca como brownfield

   Uma varredura por regras de extensões de arquivo, manifestos e arquivos de configuração conhecidos. Sem chamada ao modelo, sem gate.

   ↓
2. 2.1aO agente de desenvolvimento varre o código

   Módulos, pontos de entrada, como as partes conversam entre si, a stack e suas versões.

   ↓
3. 2.1bO agente de arquitetura escreve a síntese

   Os artefatos da engenharia reversa vão para a pasta de registro da intent, onde todo estágio seguinte pode lê-los.

   ↓
4. GATEVocê aprova o retrato do seu próprio sistema

   Se o agente leu a arquitetura errado aqui, todo requisito, design e Unit depois disso herda o erro.

↓

Saída

Perguntas de requisitos que partem de como o seu código realmente funciona, e não de como uma codebase média funcionaria.

Esse gate é o mais subestimado do ciclo de vida. As pessoas passam o olho porque ele descreve um código que elas já conhecem, e é justamente por isso que ele merece uma leitura de verdade: é o único lugar para conferir o modelo que o agente fez do seu sistema contra o seu, antes de qualquer coisa ser construída em cima.

Limite à feature, não ao repositório

O movimento ingênuo é apontar a engenharia reversa para o repositório inteiro. Mais contexto parece mais seguro. Não é.

Cada token da saída da engenharia reversa disputa a mesma janela com os requisitos, o design e, depois, o código. Um mapa completo de um serviço grande queima uma fatia grande dessa janela com módulos que a feature nunca vai tocar. E quanto mais material irrelevante fica no contexto, mais chances o modelo tem de puxar a peça errada para a resposta. Um dos engenheiros que mantinham o setup no rollout disse sem rodeio: mais informação é mais chance de alucinar.

O que funcionou foi engenharia reversa focada. O agente mapeia os módulos que a feature vai usar, as fronteiras que ela vai cruzar e os contratos de que vai depender. O resto ele deixa quieto. Você perde um documento de arquitetura completo. Ganha uma janela com espaço sobrando para o trabalho.

Rode antes do mob, não durante

Num repositório pequeno, a engenharia reversa levou uns vinte minutos. Num grande, mais. Vinte minutos não é nada para um engenheiro. É muito para seis pessoas sentadas numa sessão de Mob Elaboration olhando um indicador de progresso.

O padrão que os times adotaram: quem conduz a sessão instala o workflow, inicia e deixa a engenharia reversa terminar antes da reunião. O time entra quando a síntese está aprovada e as perguntas de requisitos estão prontas para responder. O tempo síncrono vai para decisões, que é a única coisa para a qual tempo síncrono serve.

Uma feature, vários repositórios

Feature de verdade raramente mora num repositório só. Uma mudança mexe na API, no front-end, talvez num cliente mobile e num serviço de outro time.

A primeira versão do AI-DLC era de repositório único. Os times contornavam isso dividindo o trabalho por stack: uma sessão para o back-end, outra para o front-end, com o contrato entre eles combinado antes de qualquer um começar. Quando o back-end precisava entender o que o front-end esperava, eles adicionavam a pasta do front-end como um diretório extra, só de leitura, no contexto do agente, para a engenharia reversa conseguir ver o mock ou o código do cliente sem ser dona dele.

O AI-DLC 2 tornou o trabalho com vários repositórios uma ideia de primeira classe. Uma intent pode registrar o conjunto de repositórios que ela abrange, de forma explícita ou descobrindo repositórios irmãos no workspace. A engenharia reversa então roda uma cadeia completa de varredura e síntese por repositório antes da sua aprovação, e a Construction amarra cada operação de git ao repositório certo. Existe também um estágio de Contract Design na Inception para as interfaces entre Units.

Nada disso tira a parte difícil. Dois repositórios de dois times ainda precisam de um contrato que os dois lados aprovem. O motor consegue mapear as duas codebases. Não consegue fazer o outro time concordar com você.

Orce a janela como memória, porque ela é

A context window é a memória de trabalho do agente, e uma Inception de AI-DLC usa muito dela. O agente lê cada requisito que você passa, a saída da engenharia reversa, as próprias perguntas e as suas respostas, e os documentos que gera pelo caminho.

No rollout, uma Inception completa num serviço real ficou em algum ponto entre 500.000 e 600.000 tokens. Isso cabe numa janela de um modelo de um milhão de tokens e não cabe numa menor sem o harness compactar a conversa pelo caminho. A Construction é o contrário: cada Unit tem a própria spec, então o contexto necessário por Unit é pequeno.

Para onde vai a janela

A janela grande é para a fase que mais lê. Pagar por ela durante a Construction não compra nada.

Momento	O que enche o contexto	O que funcionou
Inception	Engenharia reversa, requisitos, perguntas e respostas, documentos de design.	Rodar numa janela só, num modelo de 1M de tokens. Conferir o uso antes de começar.
Construction, por Unit	A spec da Unit, o código que ela toca, os testes.	Limpar entre Units. Um modelo menor e mais barato muitas vezes basta.
Uma conversa longa de discovery	Vai e volta, correções, direções abandonadas.	Escrever as conclusões num arquivo e começar limpo. Não continuar conversando.

No Claude Code você vê quanto a janela está cheia com /context. Olhe antes de começar uma Inception. Descobrir em 70% que você está na janela pequena é uma tarde perdida.

A regra dos 75%

Esta é a heurística em que os times convergiram: quando a janela passa de uns três quartos, a qualidade cai. O agente começa a repetir as suas próprias respostas, perde o fio de decisões tomadas uma hora antes e inventa detalhes no mesmo tom confiante que usava quando estava certo.

Não é lei, e o número exato muda com o modelo. O mecanismo por trás é bem documentado. Os modelos prestam mais atenção ao começo e ao fim do contexto e passam o olho no meio, então a decisão que você tomou no meio de uma sessão longa é a que tem mais chance de se perder. Quem trabalha com isso chama o declínio lento de context rot. Um engenheiro de um dos squads do piloto deu a versão prática: lá pelo meio milhão de tokens, limpe e retome pelo arquivo de estado, porque isso é melhor do que ver o agente começar a alucinar.

Limpe nos gates, nunca no meio de uma fase

Limpar o contexto não é desistir da tarefa. É jogar fora o ruído da sessão: os desvios, as correções, os rascunhos intermediários de que ninguém precisa mais. O trabalho em si mora em arquivos. A sessão sempre foi descartável.

A regra é sobre quando. Limpe num checkpoint: depois que a engenharia reversa é aprovada, depois que os requisitos são aprovados, entre Units da Construction. Nunca no meio de uma fase que ainda está produzindo o artefato, porque aí o raciocínio pela metade não fica guardado em lugar nenhum.

O AI-DLC mantém um arquivo de estado por intent, o aidlc-state.md, com a fase atual, o estágio e o status de cada estágio. No AI-DLC 2 ele fica na pasta de registro da intent, ao lado de um log de auditoria só de acréscimo, e um hook grava um ponto de recuperação antes de o harness compactar. É isso que torna a limpeza segura. Uma sessão nova lê o estado e continua de onde a anterior parou.

Como limpar sem perder trabalho

1. 01

   Faça commit e push antes de limpar.

   Os artefatos são a memória. Se não estão commitados, limpar apaga a única cópia do raciocínio que os produziu.

   Digite isto

   Commit the approved artifacts for this stage with a message that names the stage, then push.

2. 02

   Limpe só num gate.

   Um gate quer dizer que o artefato está pronto e aprovado. O que estiver em andamento termina antes.

   Digite isto

   /clear

3. 03

   Retome pelo arquivo de estado, não pela sua memória da sessão.

   O arquivo de estado sabe a fase, o estágio e o que está feito. Você lembra do que pareceu importante.

   Digite isto

   /aidlc --status

4. 04

   Antes de limpar uma sessão travada, faça o agente escrever o que aprendeu.

   Uma sessão de debugging que não chegou a lugar nenhum ainda descartou hipóteses. Guarde isso, jogue fora o ruído, e a sessão nova começa com a mesma profundidade e nenhuma confusão.

   Digite isto

   Do not change any code. Write a summary of this issue to notes/issue-summary.md: what we tried, what we ruled out, and what we still suspect.

A compactação quebra as suas regras em silêncio

Quando a janela enche e você não limpa, o harness faz algo por você. Ele compacta: troca a conversa anterior por um resumo para a sessão poder continuar. Parece inofensivo. Não é.

Um resumo é otimizado para continuar a tarefa. Ele guarda o que parece central e descarta o que parece periférico. E uma restrição que você disse uma vez, no começo da sessão (“não mexa no módulo de faturamento”, “nunca apague uma migration”), parece periférica até o momento em que o agente a viola.

Isso deixou de ser palpite. Dois papers de 2026 mediram.

O que a compactação faz com as restrições

0% a 30%

violações de restriçãoantes e depois da compactação, em sete famílias de modelos

59%

pior casotaxa de violação em alguns modelos

17%

restrições mantidasem média, pelos compactadores atuais

O estudo Governance Decay rodou 1.323 episódios de agentes em sete famílias de modelos. Com a política inteira no contexto, os agentes a violaram 0% das vezes. Depois da compactação, 30%, e 59% em alguns modelos. Quando a restrição sobrevivia ao resumo, as violações ficavam em zero. Quando o resumo a descartava, elas disparavam. Os autores propõem fixar as restrições de governança fora do resumo com perda, o que trouxe as violações de volta a zero no benchmark deles.

O estudo Lost in Compaction olhou para instruções que os usuários dão para o resto da sessão, como “não apague nenhum e-mail até eu confirmar”. Os compactadores atuais mantiveram em média 17% delas, e a maioria se saiu pior do que não compactar nada. Um extrator que puxa essas restrições para fora antes da compactação manteve mais de 90%.

A lição prática para trabalho em brownfield é curta. Uma regra que você digitou no chat mora dentro da conversa que vai ser resumida. Uma regra num arquivo que o harness carrega sozinho, o seu AGENTS.md ou CLAUDE.md, ou os arquivos de regras que o AI-DLC 2 mantém na memória do espaço, mora fora dela. Coloque toda restrição que importa num arquivo. O guia de AGENTS.md cobre o que vai lá.

Uma janela maior trata o sintoma

Quando um agente começa a se repetir numa sessão longa, o reflexo é trocar para um modelo com janela maior. Uma pessoa de produto no rollout fez exatamente isso durante um discovery longo: o agente quebrou, começou a devolver como eco as respostas que recebia, e um modelo maior resolveu.

Resolveu o sintoma. A causa era uma sessão que continuava acumulando contexto que deveria ter sido escrito e descartado. Uma janela maior deixa você acumular por mais tempo antes da mesma falha. Não impede a falha, e custa mais por turno enquanto você espera por ela.

A cura é a que o método já tem. Todo estágio do AI-DLC grava o artefato num arquivo, e o estágio seguinte lê o arquivo em vez da conversa. Dentro de um estágio, faça o mesmo na mão: quando uma linha de discussão chega a uma conclusão, escreva a conclusão e comece limpo. Isso é context engineering aplicado a um ciclo de vida. O chat é papel de rascunho. Os arquivos são a memória. Se algo de que a próxima sessão precisa só existe na conversa, está a uma compactação de sumir.

O seu repo brownfield está pronto para o AI-DLC?

Prontidão para brownfield

• ✓Obrigatório:
  O repo tem um AGENTS.md ou CLAUDE.md curto com a stack, os padrões, as bibliotecas proibidas e o porquê, e um exemplo de cada padrão.Cada lacuna aqui vira uma pergunta que o agente faz durante a Inception ou, pior, um chute que ele dá sem perguntar.
• ✓Obrigatório:
  A engenharia reversa está limitada aos módulos que a feature toca.Um mapa completo do repo gasta a janela com código que a feature nunca vai chamar.
• ✓Obrigatório:
  A engenharia reversa roda antes do mob, não durante.O time entra quando a síntese está aprovada e as perguntas estão prontas.
• ✓Obrigatório:
  Os contratos entre repositórios são combinados antes de as sessões começarem.O AI-DLC 2 consegue varrer vários repositórios numa intent. Não consegue negociar com o time dono do outro.
• ✓Obrigatório:
  A Inception roda num modelo de 1M de tokens, e alguém confere a janela antes de começar.Descubra que você está na janela pequena no começo, não em 70%.
• ✓Obrigatório:
  O time limpa nos gates, por volta de três quartos da janela, depois de commit e push.Nunca no meio de uma fase. Retome pelo arquivo de estado.
• ✓Obrigatório:
  Toda restrição que importa mora num arquivo, não só no chat.A compactação guarda uma fração do que você disse. Ela não toca no que está em disco.

Perguntas frequentes

O que é context rot?+

A queda gradual de qualidade de um agente de IA conforme a context window enche. O modelo presta mais atenção ao começo e ao fim do contexto, então detalhes do meio de uma sessão longa se perdem, e o agente começa a se repetir ou a contradizer decisões anteriores.

Na prática, isso fica visível em algum ponto depois de três quartos da janela. A solução é tirar as decisões da conversa e colocar em arquivos, e limpar o contexto em checkpoints naturais.

O que é compactação de contexto, e por que ela é um risco?+

Compactação é o que o harness faz quando a janela enche: troca a conversa anterior por um resumo para a sessão poder continuar. O resumo guarda o que parece central e descarta o resto.

O risco é que restrições que você disse uma vez parecem periféricas. Um estudo de 2026 mediu as violações de restrição indo de 0% para 30% depois da compactação, e até 59% em alguns modelos. Mantenha as regras importantes em arquivos que o harness carrega sozinho.

O AI-DLC funciona em código legado?+

Sim, e foi desenhado para isso. Em projetos brownfield a Inception começa com um estágio de Reverse Engineering que modela o código existente antes de qualquer mudança ser proposta. A qualidade desse estágio, e do AGENTS.md ou CLAUDE.md que o repo já tem, decide o quanto o agente precisa chutar.

O AI-DLC 2 suporta vários repositórios?+

Sim. Uma intent do AI-DLC 2 pode registrar os repositórios que ela abrange, de forma explícita ou descobrindo repositórios irmãos no workspace. O Reverse Engineering roda uma cadeia completa por repositório, e a Construction amarra as operações de git a cada repositório. A primeira versão era de repositório único.

De que tamanho de context window eu preciso para o AI-DLC?+

Para a Inception num serviço real, planeje uma janela de um milhão de tokens. A Inception completa no rollout que acompanhei ficou entre 500.000 e 600.000 tokens. As Units da Construction precisam de bem menos, então um modelo menor e mais barato costuma funcionar ali.

Uso /compact ou /clear?+

Num workflow de AI-DLC, prefira /clear num gate, depois de commitar os artefatos aprovados, e retome pelo arquivo de estado. A compactação resume a sessão e pode descartar restrições em silêncio. Limpar joga fora o ruído e mantém o trabalho, porque o trabalho já está em arquivos.

Para onde ir agora

Brownfield é onde o AI-DLC se paga ou queima dinheiro, e a diferença é quase toda higiene. Mapeie só o que a feature toca, mapeie antes da reunião, dê a janela grande para a Inception, limpe nos gates e coloque em disco toda regra que importa. O agente não precisa lembrar do seu sistema. Precisa conseguir ler de novo.