Analisando e entendendo código existente com o Codex

Até aqui você aprendeu a instalar o Codex, controlar o que ele pode executar, escrever pedidos precisos e registrar as regras do projeto no AGENTS.md. Neste capítulo você vai usar tudo isso para uma tarefa diferente: entender código que já existe e que não foi você quem escreveu. Ao final, você vai saber pedir um mapa da arquitetura de um repositório desconhecido, rastrear o caminho de uma requisição, descobrir onde uma regra de negócio está implementada, gerar documentação a partir do código e, principalmente, conferir se a explicação do agente é verdadeira.

Prepare uma sessão de leitura, não de escrita

Explorar um repositório é uma atividade de leitura. Então comece desligando a capacidade de escrita do agente. Abra o Codex CLI dentro da pasta do projeto e use o sandbox somente de leitura:

cd ~/projetos/sistema-heranca
codex --sandbox read-only

Com o modo read-only, o agente pode ler arquivos e rodar comandos de inspeção, mas não altera nada. Isso traz duas vantagens. A primeira é óbvia: nenhum risco de mexer em código que você ainda não compreende — desde que você não aprove pedidos de escalonamento, porque o agente ainda pode solicitar permissão para rodar um comando fora do sandbox, e nesse momento a proteção deixa de valer. A segunda é de foco. Sem permissão de escrita, o Codex não tenta consertar o que encontra pelo caminho, e a conversa fica dedicada a explicar.

Se o repositório for grande, vale também escolher um nível de raciocínio mais alto para essa sessão, porque tarefas de exploração dependem de o agente encadear muitas leituras antes de responder.

O primeiro pedido: um mapa da arquitetura

Resista à tentação de perguntar o que esse projeto faz e nada mais. Peça um mapa com formato definido, como você aprendeu no capítulo de prompts. Um pedido que funciona bem:

Continue em nosso aplicativo e ...

• Ouça o áudio com a tela desligada
• Ganhe Certificado após a conclusão
• + de 5000 cursos para você explorar!

ou continue lendo abaixo...

Baixar o aplicativo

Objetivo: quero entender a arquitetura deste repositório antes
de tocar em qualquer coisa.

Faça o seguinte:
1. Liste os pontos de entrada da aplicação e diga qual arquivo
   inicia cada um.
2. Descreva as camadas ou módulos principais em no máximo oito
   itens, com uma frase por item e o caminho da pasta.
3. Diga onde ficam configuração, migrações de banco e testes.
4. Aponte as três partes que parecem mais complexas ou frágeis.

Formato: lista curta. Para cada afirmação, cite o arquivo e, se
possível, a linha em que você se baseou.
Não proponha mudanças.

A última linha é um escopo negativo importante. Sem ela, muitos agentes terminam a resposta sugerindo melhorias, o que polui a leitura.

Repare também na exigência de citar arquivo e linha. Essa é a sua âncora de verificação. Uma explicação sem referência é uma opinião; uma explicação com referência é algo que você pode abrir e conferir em dez segundos.

Descendo um nível: módulos e funções

Com o mapa em mãos, escolha um ponto e aprofunde. Aqui a menção de arquivo é sua melhor amiga. No Codex CLI, escreva o símbolo de arroba seguido do caminho para trazer o arquivo ao contexto, ou selecione o trecho no editor e pergunte pelo painel lateral da extensão.

Um pedido de explicação útil separa três perguntas diferentes:

• O que este código faz, em linguagem de negócio, sem jargão de implementação.
• Como ele faz, passo a passo, incluindo estruturas de dados e efeitos colaterais como escrita em banco, envio de mensagem ou gravação de arquivo.
• Quem chama e quem é chamado, ou seja, as bordas desse pedaço de código.

Peça também as premissas implícitas: o que a função espera que já tenha acontecido antes, quais valores ela assume que nunca são nulos, que formato de entrada ela não valida. Essa pergunta costuma revelar mais sobre um sistema do que a descrição do fluxo feliz.

Rastreando o caminho de uma requisição

Em sistemas web, a pergunta mais valiosa é: o que acontece, do começo ao fim, quando alguém chama determinado endereço. O Codex é bom nisso porque pode seguir as chamadas abrindo um arquivo atrás do outro. Um exemplo de pedido:

Rastreie o fluxo completo da requisição POST para /pedidos.
Mostre a sequência na ordem de execução: rota, middlewares,
validação, camada de serviço, acesso a banco, eventos publicados
e resposta. Para cada etapa, informe arquivo, função e linha.
Marque explicitamente qualquer ponto em que você não conseguiu
confirmar a ligação no código.

A instrução final é decisiva. Quando você abre espaço para o agente dizer não confirmei esta parte, ele tende a preencher menos lacunas com suposições. É uma forma prática de reduzir alucinação em tarefas de leitura.

Encontrando onde mora a regra de negócio

Outra necessidade clássica: alguém diz que clientes com mais de cinco pedidos recebem frete grátis, e ninguém sabe onde isso está escrito. Descreva a regra em palavras do negócio, dê os termos que provavelmente aparecem no código e peça uma busca sistemática.

Encontre onde a regra de frete grátis é aplicada. Termos prováveis:
frete, shipping, desconto, isencao. Procure também em migrações,
arquivos de configuração e testes.
Retorne uma tabela com arquivo, linha, trecho relevante e o quanto
você confia de que aquele é o ponto que decide a regra.
Se houver mais de uma implementação da mesma regra, liste todas.

Pedir todas as ocorrências é fundamental em código legado, onde a mesma regra costuma estar duplicada em um serviço, em um relatório e em um gatilho de banco de dados. Vale ainda pedir ao agente que mostre os comandos de busca que usou. Se ele rodou uma busca por texto no repositório, você pode repetir o mesmo comando e comparar o resultado.

Dependências: o que este projeto puxa e o que depende dele

Peça dois inventários diferentes. O primeiro é de dependências externas: bibliotecas declaradas nos arquivos de manifesto, quais delas realmente aparecem no código, quais estão declaradas mas nunca importadas e quais são críticas para o funcionamento. O segundo é de dependências internas: quais módulos importam quais, onde há ciclos e qual módulo tem mais vizinhos.

Lembre-se de que, na configuração padrão do sandbox local, o acesso à rede vem desativado, mas isso pode ser alterado nas configurações e ambientes em nuvem podem ter regras próprias — vale conferir o que está valendo na sua instalação. Portanto ele não consulta registros de pacotes para verificar versões ou vulnerabilidades. O inventário que ele produz vem do que está escrito no repositório, e isso é exatamente o que queremos nesta etapa.

Validar é parte do método

Uma explicação convincente e errada é pior do que nenhuma explicação. Adote três hábitos simples:

1. Abra pelo menos duas referências de cada resposta longa e confira se o arquivo e a linha dizem o que o agente afirmou.
2. Faça uma pergunta de controle cuja resposta você já conhece. Se o agente errar o que você sabe, desconfie do resto.
3. Peça o caminho contrário. Se ele disse que a função de cálculo é chamada pelo serviço de checkout, peça a lista de todos os chamadores dessa função. Explicações verdadeiras sobrevivem à pergunta invertida.

Regra prática: trate a saída do Codex como o relatório de um colega competente que leu o código rápido. Você assina embaixo somente depois de conferir as citações.

Transformando entendimento em documentação

Depois de compreender uma área, registre o que aprendeu. Aqui o agente precisa de permissão de escrita, então troque para o modo automático com o sandbox de escrita na pasta de trabalho, mantendo a árvore do Git limpa antes de começar.

Três produtos valem o esforço:

• Docstrings e comentários nas funções públicas de um módulo por vez. Exija que descrevam parâmetros, retorno, exceções e efeitos colaterais, e proíba comentários que apenas repitam o nome da função. Peça que nenhuma linha de código executável seja alterada, apenas documentação.
• Um README ou um documento de arquitetura com o mapa que você validou, incluindo como rodar o projeto localmente, extraído dos scripts existentes e não inventado.
• Um glossário de domínio com os termos de negócio que aparecem no código, muito útil quando nomes em português e inglês convivem no mesmo repositório.

Revise a documentação gerada com o mesmo rigor que você aplicaria a código. E quando o agente descobrir algo estável e importante, como o comando real de execução dos testes, mova essa informação para o AGENTS.md, para que as próximas sessões já comecem sabendo.

Código legado e linguagens que você não domina

Em sistemas antigos, o Codex ajuda de um jeito específico: ele não se cansa. Peça que ele leia arquivos de milhares de linhas e produza um sumário por blocos, dizendo onde cada responsabilidade começa e termina. Peça também que identifique código morto aparente, marcando o nível de confiança, e que aponte convenções da época, como prefixos de variáveis ou uso de variáveis globais.

Quando a linguagem não é sua, mude o formato do pedido. Peça a explicação em termos da linguagem que você conhece. Por exemplo: explique esta classe em Java como se fosse um módulo em Python, indicando o que não tem equivalente direto. Peça um pequeno glossário da sintaxe que aparece no arquivo, item por item, e peça que o agente aponte armadilhas típicas daquela linguagem que afetam a leitura do trecho. Você continua responsável por decidir, mas passa a decidir informado.

Um cuidado final: em repositórios muito grandes, o contexto do agente é finito. Trabalhe por áreas, uma conversa nova para cada área, e leve para a conversa seguinte apenas o resumo validado da anterior. Sessões longas e desorganizadas produzem respostas cada vez mais genéricas.

Recapitulando

• Explore sempre com o sandbox somente de leitura, para segurança e para manter o foco na explicação.
• Comece por um mapa da arquitetura com formato definido e escopo negativo, e só depois desça para módulos e funções.
• Para fluxos, peça a sequência em ordem de execução com arquivo, função e linha, e autorize o agente a marcar o que não conseguiu confirmar.
• Para regras de negócio, forneça termos prováveis e exija todas as ocorrências, inclusive em migrações, configuração e testes.
• Valide abrindo as referências, fazendo perguntas de controle e pedindo o caminho inverso das chamadas.
• Converta o entendimento em docstrings, README e glossário, sem alterar código executável, e promova ao AGENTS.md o que for permanente.
• Em legado e em linguagens desconhecidas, peça sumários por blocos, traduções conceituais para a linguagem que você domina e glossários de sintaxe.