Como usar o Claude Opus 5.5 para documentar um projeto legado que ninguém entende mais

Fala aí, beleza? Existe um tipo de projeto que dá arrepio em qualquer dev: repo com anos de vida, README de duas linhas e nenhuma pessoa do time original ainda por perto

Aí chega a demanda de mexer na cobrança, e ninguém no time consegue dizer o que acontece depois que aquele método é chamado

Qualquer deploy vira roleta

A Anthropic anunciou o Claude Opus 5.5 em 22 de setembro de 2026, primeiro modelo da família 5.5, voltado a trabalho agêntico de longa duração e codificação

A janela de contexto dele é de 1 milhão de tokens, que é ao mesmo tempo o padrão e o máximo (não existe variante menor), e isso muda o tamanho da arqueologia de código que cabe numa sessão

Só que janela grande não é botão mágico: sem fatiar por domínio e sem revisão humana, o que sai é texto bonito e errado…

O que você precisa antes de começar

A lista é curta, beleza?

• Claude Code instalado e com o Opus 5.5 selecionado: o comando /model salva o modelo escolhido nas configurações do usuário e vale pra próximas sessões, e aceita tanto o alias opus quanto o ID completo claude-opus-5-5
• O repositório completo, com histórico de git: commit antigo e mensagem de commit são a pista de intenção que sobrou, e quem vai atrás disso é você (ou o Claude, quando você pedir dentro do prompt)
• Uma pasta de destino pra documentação DENTRO do repo: algo como docs/arquitetura/, versionado junto do código

Não usa Claude Code? O Opus 5.5 está disponível na Claude Platform (a API da Anthropic), na Amazon Bedrock, no Google Cloud e no Microsoft Foundry

E também no GitHub Copilot, desde o anúncio de 22/09/2026

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

E o custo disso em repo grande?

Se você for tocar essa tarefa via API, vale calibrar a expectativa antes

O preço do Opus 5.5 é de US$ 4 por milhão de tokens de entrada e US$ 20 por milhão de tokens de saída, 20% menos que o Opus 5 (que custa US$ 5 e US$ 25)

O detalhe que segura a conta em pé é o cache: um cache hit custa 5% do preço de entrada padrão, ou seja, US$ 0,20 por milhão de tokens, e o prompt mínimo cacheável é de 512 tokens

Junto com o anúncio do modelo, a Anthropic também aumentou os limites de uso de cinco horas nos planos Pro, Max, Team e Enterprise por assento, e deu aos assinantes um reset de limite que pode ser aplicado quando o usuário quiser

Passo a passo: documentando o legado sem quebrar nada

A lógica geral é sempre a mesma: ler muito, escrever pouco, revisar tudo

1. Escolha o modelo e o nível de effort

Primeira coisa da sessão:

/model opus

O Opus 5.5 suporta cinco níveis de effort (low, medium, high, xhigh e max) e o padrão dele é medium, um nível ABAIXO do padrão high que o Opus 5 usava

Ou seja: se você só abrir e mandar ver, está rodando num nível mais econômico do que talvez precise

No Claude Code tu ajusta com o comando /effort dentro da sessão, ou com a flag --effort na linha de comando

Pra dar uma noção do que muda entre níveis, o Artificial Analysis mediu o Opus 5.5 assim no Intelligence Index (v4.3.2, dez avaliações):

O 58 no effort máximo é o maior score já medido pela plataforma

Na prática de documentação: mapa geral e varredura ampla rodam bem em medium (que já é o padrão, então nem precisa mexer), e fluxo crítico com muita ramificação é onde vale rodar /effort high ou acima, voltando pra medium quando for varrer largo de novo

O erro comum deste passo: deixar no padrão e depois culpar o modelo pela resposta rasa, quando o que faltou foi effort e escopo apertado

2. Rode o /init pra ter um ponto de partida

/init

O /init faz o Claude analisar o codebase e criar um CLAUDE.md com comandos de build, instruções de teste e convenções descobertas

Isso não é a documentação do projeto, é o mínimo pro modelo (e pro próximo dev) não ficar chutando como se roda o negócio

Leia esse arquivo linha por linha antes de commitar: em legado, é comum o modelo descobrir três formas de rodar teste e nenhuma delas ser a que o time usa de verdade

O erro comum deste passo: aceitar o CLAUDE.md gerado como verdade e sair usando. Ele é rascunho, você é o revisor

3. Fatie o repositório por DOMÍNIO, não por pasta

Esse é o passo que decide a qualidade de tudo que vem depois

Pasta é organização de arquivo, domínio é comportamento do sistema

"Cobrança", "autenticação", "importação de planilha", "fila de notificação": esses são recortes que geram documentação útil, mesmo que os arquivos estejam espalhados em cinco diretórios diferentes

Pra achar as fatias, delega ao subagente Explore, que é justamente pra quando o Claude precisa buscar ou entender um codebase sem fazer alteração, especificando o nível de profundidade (quick, medium ou very thorough)

Mapa geral com quick:

Use o Explore com profundidade quick e me liste os domínios
de negócio presentes neste repositório.
Para cada domínio: quais diretórios e arquivos participam dele,
e qual o ponto de entrada mais provável.
Não proponha mudanças.

Depois, na fatia crítica, aprofunda:

Use o Explore com profundidade very thorough no domínio de cobrança,
considerando os arquivos listados antes.
Quero quem chama quem, onde há chamada externa e onde há escrita no banco.
Cite arquivo e linha em cada afirmação.

Se o repo é daqueles com grafo de dependências impossível de seguir na mão, vale olhar como ferramentas de grafo ajudam no legado antes de gastar contexto nisso

O erro comum deste passo: mandar "documente esse repositório" com tudo de uma vez. Você queima contexto, recebe um resumo genérico e não consegue revisar nada, porque a saída não tem onde ser conferida

4. Entre em Plan mode pra descrever fluxos ponta a ponta

Aqui a gente está lendo, então não quer risco NENHUM de escrita

O Plan mode faz o Claude pesquisar e propor mudanças sem executá-las, e você entra nele com Shift+Tab ou prefixando o prompt com /plan

A pesquisa é delegada ao subagente Plan, cuja saída fica numa janela de contexto separada enquanto a conversa principal segue somente leitura

Isso é ótimo pra documentação: o trabalho pesado de leitura não entope a sua sessão

/plan Descreva o fluxo completo de criação de uma cobrança,
do endpoint HTTP até a escrita final no banco.
Inclua validações, side effects, eventos disparados e pontos de falha.
Cite arquivo e linha em cada etapa.

Detalhe importante que pega muita gente: Explore e Plan pulam os arquivos CLAUDE.md e o snapshot do git status, pra manter a pesquisa rápida e barata

Repara que git status é a foto do estado atual da árvore, não o log de commits: o histórico continua no repo do mesmo jeito, só que é você que traz ele pra conversa quando importa

Então convenção que você escreveu no CLAUDE.md não chega até eles: o que precisa valer na pesquisa, você repete dentro do prompt

O erro comum deste passo: escrever no CLAUDE.md "sempre cite arquivo e linha" e achar que o Explore vai obedecer

5. Peça os contratos entre módulos

Fluxo conta a história, contrato é o que segura o refactor

Pra cada módulo da fatia, o pedido é bem específico:

Para cada módulo público do domínio de cobrança, monte uma ficha com:
- entradas esperadas (tipo, formato, obrigatoriedade)
- saídas e formato de retorno
- efeitos colaterais (banco, fila, arquivo, chamada externa)
- erros que ele lança e quem trata
- suposições implícitas que o código faz e não valida
Se algo não estiver claro no código, escreva DESCONHECIDO em vez de inferir.

Esse último parágrafo do prompt é o mais importante de todos

Sem ele, o que você recebe é um texto bonito onde não dá pra distinguir o que está no código do que o modelo imaginou

O erro comum deste passo: aceitar inferência de regra de negócio como fato. "Esse campo é o desconto do cliente VIP" pode ser palpite em cima de um nome de variável

6. Materialize tudo em markdown dentro do repo

Documentação que mora no chat morre no chat

Escreva o resultado em docs/arquitetura/cobranca.md, em markdown,
com as seções: visão geral, fluxo principal, contratos por módulo,
pontos de falha e lacunas (o que ficou como DESCONHECIDO).

Markdown versionado junto do código tem uma vantagem boba e enorme: ele aparece no diff

Quando alguém mexe no módulo e não atualiza a ficha, dá pra cobrar em code review

O erro comum deste passo: salvar a documentação numa ferramenta externa. Em seis meses ela está desatualizada e ninguém confia mais nela

7. Vigie a janela de contexto o tempo todo

Durante a sessão, dois comandos são seus amigos

O /context mostra o que está ocupando a janela, e o /context all detalha os tokens de cada ferramenta MCP carregada

O /compact resume o histórico antigo pra liberar espaço

O ritmo saudável é: fecha uma fatia, grava o markdown, compacta, começa a próxima

O erro comum deste passo: ir empilhando cinco domínios na mesma sessão e só perceber o problema quando a resposta começa a ficar vaga

Quatro tipos de documentação que vale pedir ao Opus 5.5

Não é tudo que compensa gerar

Esses quatro aqui rendem, porque são coisas verificáveis no próprio código

1. Mapa de arquitetura por domínio

O recorte é amplo de propósito, e é o único momento em que vale uma varredura geral

Use o Explore com profundidade quick.
Monte um mapa de domínios: nome, responsabilidade em uma frase,
diretórios envolvidos, ponto de entrada e dependências para outros domínios.

Formato de saída ideal: um arquivo só, docs/arquitetura/mapa.md, com uma tabela e uma lista de dependências entre domínios

Esse arquivo é o índice de tudo que vier depois

2. Descrição de fluxo crítico ponta a ponta

O clássico: o que acontece de um endpoint até o banco

/plan Rastreie a requisição POST /pedidos do controller até a última
escrita no banco. Numere as etapas, e em cada uma cite arquivo e linha.
Marque explicitamente onde há transação, retry ou chamada externa.

Formato de saída ideal: lista numerada de etapas, com arquivo e linha ao lado de cada uma

É o formato que sobrevive melhor, porque qualquer dev consegue conferir no código em dois minutos

3. Ficha de contrato por módulo

Um arquivo por módulo, sempre com a mesma estrutura

Entradas, saídas, efeitos colaterais, erros, suposições implícitas e lacunas

Formato de saída ideal: um template fixo repetido, porque padrão igual é o que permite bater o olho e comparar dois módulos

4. Inventário de código morto e dependências suspeitas

Esse é o que costuma dar mais retorno imediato

Liste funções, classes, rotas e arquivos deste domínio sem nenhuma
referência no restante do repositório. Para cada item, mostre onde
você procurou referência. Não remova nada, só liste.

Formato de saída ideal: tabela com item, caminho, onde foi procurado e nível de confiança

E trata como candidato, nunca como sentença: reflection, chamada dinâmica e cron externo fazem código "morto" acordar no pior momento possível. Já vi gente se ferrar com isso

Como fazer a documentação sobreviver ao próximo refactor

Gerar é a parte fácil

O problema é que cada sessão do Claude Code começa com uma janela de contexto limpa, ou seja: o que não está em arquivo, não existe na próxima vez

1. Use CLAUDE.md e AGENTS.md como contexto persistente

O CLAUDE.md dá esse contexto que atravessa sessões, e o Claude também lê arquivos AGENTS.md do repositório, sozinhos ou junto com o CLAUDE.md

O que entra ali: onde a documentação mora, qual template de ficha usar e a regra de sempre citar arquivo e linha

2. Navegue a auto memory com /memory

O comando /memory permite navegar na pasta de auto memory, que é markdown editável

É markdown, então é seu: se tem coisa errada ali, você corrige na mão

3. Crie um subagente de documentação

Subagentes são arquivos Markdown com frontmatter YAML definidos em diretórios .claude/agents/

O frontmatter traz nome, description, tools e model, e o corpo do arquivo vira o system prompt

---
name: doc-legado
description: Documenta um domínio do repositório em markdown, sem alterar código
tools: Read, Grep, Glob, Write
model: claude-opus-5-5
---

Você documenta código legado.
Regras:
- cite arquivo e linha em toda afirmação sobre comportamento
- escreva DESCONHECIDO quando o código não permitir concluir
- nunca infira regra de negócio a partir de nome de variável
- siga o template de docs/arquitetura/_template.md

Desde a v2.1.198 o comando /agents não abre mais o assistente interativo de criação: ele apenas lembra de pedir ao Claude ou editar .claude/agents/ direto

E olho no acúmulo: quando a soma das descrições dos subagentes passa de 15.000 tokens, o Claude Code mostra um aviso na inicialização com a contagem total

4. Rode atualização em lote sem entrar na sessão

A flag -p (ou --print) roda o Claude Code de forma não interativa com um prompt

claude -p "Releia src/billing e atualize docs/arquitetura/cobranca.md. \
Marque com ATUALIZADO EM as seções que mudaram."

Existe também a flag --bare, que reduz o tempo de inicialização pulando a descoberta automática de hooks, skills, comandos customizados, subagentes, plugins, servidores MCP, auto memory e CLAUDE.md

Rápida, sim, mas repara no que ela pula: se o seu fluxo depende do subagente doc-legado e das regras do CLAUDE.md, --bare justamente derruba o que você montou

5. Trate doc como parte do PR

Regra simples de combinar com o time: mexeu no módulo, atualizou a ficha dele

E se você costuma tocar mais de um repositório ao mesmo tempo, vale entender antes os limites de rodar duas sessões em paralelo, porque contexto trocado entre projetos é receita pra documentação errada

Problemas comuns nessa tarefa (e como contornar)

Sessão estourando o contexto no meio da varredura

Sintoma: o Claude começa preciso e vai ficando vago, ou o auto-compact dispara toda hora e você perde o fio

Causa: fatia grande demais somada a histórico longo de conversa na mesma sessão

Solução: roda /context pra ver quem está comendo a janela, /compact pra resumir histórico antigo, e ajusta a variável CLAUDE_CODE_AUTO_COMPACT_WINDOW, que define o limite de auto-compactação e aceita de 100K a 1M tokens

Se você quer padronizar as sessões do time em 200K, existe CLAUDE_CODE_DISABLE_1M_CONTEXT=1, que remove as variantes de 1M do seletor de modelos e mantém as sessões em 200K em todo modelo com janela nativa de 1M

No Claude Code, os modelos que suportam janela de 1 milhão de tokens pra sessão longa em codebase grande são Fable 5.1, Fable 5, Sonnet 5, Opus 4.6 e posteriores e Sonnet 4.6

Como prevenir: uma fatia por sessão, markdown gravado antes de seguir

Resposta genérica, que serve pra qualquer projeto

Sintoma: sai um texto tipo "o módulo processa os dados e persiste no banco", que não diz nada

Causa: fatia mal recortada (pasta em vez de domínio) e prompt sem exigência de evidência

Solução: aperta o escopo pra um fluxo só, sobe o effort com /effort high (ou acima) e exige arquivo e linha em cada afirmação

Como prevenir: todo prompt de documentação pede evidência. Sem exceção

O modelo descreve o que o código DEVERIA fazer

Sintoma: a documentação está coerente, bonita, e não corresponde ao comportamento real em produção

Causa: nome de função, comentário velho e nome de variável induzindo a leitura. Legado é cheio de comentário que mente

Solução: pede citação de arquivo e linha, e manda o modelo marcar DESCONHECIDO em vez de completar a lacuna

Depois você confere por amostragem: pega três afirmações fortes do documento e abre o código

Como prevenir: proibir explicitamente no prompt inferência baseada em nome ou comentário

Custo subindo rápido demais

Sintoma: a conta de API cresce mais rápido do que a documentação avança

Causa: reenviar o mesmo bloco enorme de contexto em cada chamada, sem cache

Solução: estrutura os prompts pra reaproveitar cache, lembrando que o cache hit custa 5% do preço de entrada padrão (US$ 0,20 por milhão de tokens) e que o prompt mínimo cacheável é de 512 tokens

Vale também usar o Explore com profundidade quick no reconhecimento e guardar o very thorough só pras fatias que realmente importam

Como prevenir: definir antes quais domínios merecem profundidade máxima, em vez de descobrir no meio do caminho

O que não delegar ao modelo

Essa seção é a mais importante do post, então vou ser direto

O Claude Opus 5.5 lê comportamento observável no código

Ele não lê intenção, política interna nem reunião de 2021

O que fica FORA:

• Decisões históricas. "Por que fizeram assim?" não está no código. Está numa thread morta, num contrato ou na memória de alguém. O modelo consegue no máximo descrever o resultado da decisão
• Regra de negócio que só existe na cabeça de alguém. Aquele if cliente.tipo == 3 pode ser uma condição comercial negociada por um vendedor. Nome de variável não é fonte de regra de negócio
• Motivo de gambiarra que segura integração externa. Aquele sleep inexplicável antes de chamar a API do parceiro provavelmente existe porque alguém se ferrou sem ele. O modelo vê o sleep, não vê o incidente
• Prioridade de refactor. O que refatorar primeiro depende de roadmap, risco de negócio e time disponível. Isso é decisão de gente

O jeito de lidar com isso não é fingir que a lacuna não existe, é marcar ela

Pede pro modelo abrir uma seção fixa no fim de cada documento:

No fim do arquivo, crie a seção "Lacunas para entrevista" e liste
toda condição, constante mágica ou comportamento cuja MOTIVAÇÃO
não pode ser determinada a partir do código.
Para cada item: onde está, o que faz, e qual pergunta precisa ser
feita a uma pessoa.

Essa lista é ouro puro

É ela que você leva pra conversa de vinte minutos com quem está na empresa há mais tempo, em vez de tomar a hora da pessoa perguntando coisa que o código já responde

Conclusão

O ganho aqui não está no volume de texto gerado

Está em duas coisas: fatiar por domínio (e não por pasta) e revisar com olho humano em cima de citação de arquivo e linha

Documentação gerada sem revisão não é documentação, é ficção coerente

Próximo passo bem concreto, pra hoje: escolhe UM fluxo crítico do teu legado, aquele que ninguém quer tocar

Roda o ciclo completo nele (Explore pra mapear, Plan mode pra descrever, markdown gravado em docs/arquitetura/), revisa três afirmações no código e commita

Se esse ciclo funcionar numa fatia, aí sim escala pro resto do repositório

Se ele não funcionar numa fatia, escalar só multiplica o erro 🙂

até o próximo post!