Como navegar codebases grandes com Claude Code e Codex

Ao entrar em uma base de código grande, o primeiro objetivo não é entender todos os arquivos. O objetivo inicial é construir um mapa: onde o sistema começa, quais pastas são geradas, quais arquivos carregam risco de negócio e quais limites de ownership não devem ser cruzados sem revisão.

Claude Code e Codex são ótimos para esse tipo de leitura, mas só funcionam bem quando a investigação é disciplinada. Se você cola arquivos inteiros, logs longos e centenas de resultados na conversa principal, ganha mais texto, não mais clareza. Esse é o inchaço de contexto: a conversa cresce enquanto a densidade de informação útil diminui.

Este guia transforma o fluxo que uso em handoffs, auditorias e manutenção de artigos da ClaudeCodeLab em comandos e pacotes de prompts copiáveis. Para comportamento das ferramentas, uso documentação oficial: Claude Code common workflows, CLI reference, memory, Codex non-interactive mode e Codex AGENTS.md.

Comece Com Um Mapa Do Repo

Antes de pedir para um agente explicar o repositório, reduza a forma externa você mesmo. rg é ripgrep. Ele é rápido, respeita regras comuns de ignore e permite excluir pastas geradas antes que elas poluam a análise.

git status --short
git rev-parse --show-toplevel
git branch --show-current

rg --files \
  -g '!*node_modules*' \
  -g '!dist' \
  -g '!build' \
  -g '!coverage' \
  -g '!*.lock' \
  | sed 's#^[^/]*/##' \
  | sort \
  | uniq -c \
  | sort -nr \
  | head -40

find . -maxdepth 3 \( \
  -name package.json -o \
  -name pnpm-workspace.yaml -o \
  -name pyproject.toml -o \
  -name go.mod -o \
  -name Cargo.toml -o \
  -name Dockerfile -o \
  -name docker-compose.yml -o \
  -name AGENTS.md -o \
  -name CLAUDE.md \
\) -print

Depois peça um mapa em modo somente leitura. Os workflows oficiais do Claude Code recomendam começar com perguntas amplas e depois focar em componentes específicos. A documentação do Codex diz que codex exec roda por padrão em um sandbox read-only, o que combina com o primeiro resumo do repo.

codex exec "Read only. Summarize the repository map: apps, packages, entrypoints, test commands, generated folders, and files that define project rules. Do not edit files."

No Claude Code, use -p para obter uma resposta não interativa. A referência CLI documenta isso como print mode.

claude -p "
Somente leitura. Crie um mapa deste repositório.
Responda nesta ordem:
1. Apps, packages e services
2. Entrypoints de runtime, testes e build
3. Pastas geradas e pastas que devem ser ignoradas
4. Pontos principais de AGENTS.md, CLAUDE.md, README e notas de design
5. Os próximos 10 arquivos a ler, com um motivo para cada um
Apenas sugira edições ou comandos; não execute.
"

Pesquise Em Camadas

Um match de texto não é compreensão. Busca gera candidatos. Use cinco camadas: estrutura, vocabulário de domínio, referências, configuração e histórico.

# 1. Candidatos a entrypoint
rg -n "createServer|listen\(|app\.use|router\.|main\(|bootstrap|hydrateRoot|createRoot" \
  src apps packages server web

# 2. Vocabulário de domínio. Troque estes termos para o seu produto.
rg -n "Auth|Billing|Invoice|Notification|Search|FeatureFlag" \
  src apps packages test tests

# 3. Chamadores e referências da área que talvez você modifique
rg -n "AuthService|useAuth|requireAuth|authMiddleware" \
  src apps packages test tests

# 4. Configuração e variáveis de ambiente
rg -n "process\.env|import\.meta\.env|PUBLIC_|DATABASE_URL|JWT|STRIPE|OPENAI|ANTHROPIC" \
  . -g '!node_modules' -g '!dist' -g '!build'

# 5. Histórico: por que este design existe
git log --oneline --decorate --date=short --max-count=30 -- src/auth packages/auth

Não cole cem resultados no agente. Veja primeiro o formato dos hits e passe um conjunto pequeno para classificação.

Você é um revisor de navegação de codebase.
Classifique estes resultados de rg em: entrypoint de implementação, chamador, configuração, teste e ruído.
Limite cada classe aos 5 arquivos mais importantes para ler em seguida.
Para cada arquivo escolhido, dê um motivo concreto.
Se não houver certeza, escreva "precisa de outra busca" em vez de adivinhar.

Desenhe Um Grafo De Dependências Leve

Antes de instalar um analisador completo, um pequeno script Node pode trazer sinal suficiente. Ele não é um compilador TypeScript; apenas segue imports relativos locais. Ainda assim ajuda a enxergar o raio de impacto direto.

#!/usr/bin/env node
import { execFileSync } from "node:child_process";
import { readFileSync } from "node:fs";
import path from "node:path";

const target = process.argv[2]?.replace(/\\/g, "/");
if (!target) {
  console.error("Usage: node scripts/dependency-map.mjs src/path/to/file.ts");
  process.exit(1);
}

const tracked = execFileSync("git", ["ls-files"], { encoding: "utf8" })
  .split(/\r?\n/)
  .filter(Boolean)
  .map((file) => file.replace(/\\/g, "/"));

const trackedSet = new Set(tracked);
const sourceFiles = tracked.filter((file) => /\.(mjs|cjs|js|jsx|ts|tsx)$/.test(file));
const importPattern =
  /(?:from\s+["']([^"']+)["']|import\s*\(\s*["']([^"']+)["']\s*\)|require\s*\(\s*["']([^"']+)["']\s*\))/g;

function resolveLocalImport(specifier, fromFile) {
  if (!specifier.startsWith(".")) return null;
  const base = path.normalize(path.join(path.dirname(fromFile), specifier)).replace(/\\/g, "/");
  const candidates = [
    base,
    `${base}.ts`,
    `${base}.tsx`,
    `${base}.js`,
    `${base}.jsx`,
    `${base}/index.ts`,
    `${base}/index.tsx`,
    `${base}/index.js`,
  ];
  return candidates.find((candidate) => trackedSet.has(candidate)) ?? base;
}

const incoming = [];
for (const file of sourceFiles) {
  const source = readFileSync(file, "utf8");
  for (const match of source.matchAll(importPattern)) {
    const resolved = resolveLocalImport(match[1] || match[2] || match[3], file);
    if (resolved && (resolved === target || resolved.endsWith(`/${path.basename(target)}`))) {
      incoming.push(file);
    }
  }
}

console.log(`Target: ${target}`);
console.log("Direct importers:");
for (const file of incoming.sort()) console.log(`- ${file}`);

Salve e execute assim.

mkdir -p scripts
$EDITOR scripts/dependency-map.mjs
node scripts/dependency-map.mjs src/services/AuthService.ts

Depois transforme a saída em mapa de risco.

Com estes direct importers, avalie o raio de impacto de mudar AuthService.ts.
Use high / medium / low.
High significa autenticação, billing, autorização, persistência ou API pública.
Para cada classe, liste testes e arquivos de configuração que devem ser lidos antes de editar.

Trace A Partir Dos Entrypoints

Uma lista de arquivos não explica comportamento em runtime. No backend, trace request, middleware, route, controller, service, repository e database. No frontend, trace route, loader, state, API client, component e analytics.

rg -n "middleware|loader|action|controller|handler|route|repository|service" \
  src apps packages \
  -g '*.ts' -g '*.tsx' -g '*.js' -g '*.jsx'

rg -n "fetch\(|axios|graphql|trpc|prisma|drizzle|sequelize|typeorm" \
  src apps packages \
  -g '*.ts' -g '*.tsx' -g '*.js' -g '*.jsx'

Peça uma tabela de fluxo, não um parágrafo.

Lente	Boa saída	Saída fraca
Entrada	POST /login -> auth route -> AuthService.login	”Auth é importante”
Estado	Cookie, session, DB, cache ou queue alterado	Sem mudanças de estado
Falha	Resposta de erro, log, auditoria, retry	Apenas happy path
Testes	Teste existente e casos faltantes	”Adicionar testes” genérico

Trace o fluxo de login do entrypoint até a persistência.
Retorne uma tabela com: ordem, arquivo, função/classe, mudança de estado, comportamento em falha, testes a ler.
Não preencha lacunas com suposições. Se uma etapa for desconhecida, diga o próximo arquivo a inspecionar.

Mapeie Ownership E Risco

Em um repositório grande, a primeira pergunta não é “roda?”, mas “de quem é este limite?”. Limites podem ser de equipe, dados, release, compliance ou receita.

find . -maxdepth 4 \( \
  -name CODEOWNERS -o \
  -name OWNERS -o \
  -name README.md -o \
  -name AGENTS.md -o \
  -name CLAUDE.md \
\) -print

rg -n "owner|maintainer|deprecated|legacy|do not edit|generated|migration|rollback|release" \
  . -g '!node_modules' -g '!dist' -g '!build'

Codex lê oficialmente AGENTS.md, então vale colocar regras do projeto ali. Claude Code pode usar CLAUDE.md e memory para encurtar sessões futuras. Para um modelo mais completo, veja CLAUDE.md Best Practices.

## Codebase map

### Entry points
- Web: apps/web/src/main.tsx
- API: services/api/src/server.ts
- Jobs: services/jobs/src/index.ts

### Ownership boundaries
- services/payments: owned by payments team; never change schema without migration review.
- packages/ui: shared design system; visual regression test required.
- legacy/: read-only unless the issue is production severity.

### High-risk files
- services/api/src/auth/AuthService.ts: login, session rotation, audit log.
- packages/db/schema.ts: migrations affect API and jobs.
- apps/web/src/routes/checkout.tsx: revenue path and analytics.

### Handoff notes
- Always start with rg search, then read top files.
- Prefer small diffs with tests.
- Do not paste large logs into the main conversation; summarize first.

Use Prompts Exploradores Somente Leitura

Na primeira exploração, mantenha o agente consultivo. Você quer mapa, hipóteses e incógnitas antes de qualquer alteração.

Investigue em modo somente leitura. Não edite arquivos, não adicione dependências, não formate código e não rode testes.

Objetivo:
Entender o escopo de implementação e o risco de mudança para [nome da feature].

Retorne:
1. Arquivos entrypoint
2. Modelos de dados centrais
3. Dependências diretas e indiretas
4. Limites de ownership
5. Mapa de risco: high / medium / low
6. Arquivos para inspecionar em seguida
7. Hipóteses ainda não confirmadas

Regras:
Marque palpites como hipóteses.
Inclua nomes de arquivo e evidência.
Não cite corpos grandes de arquivos.

Subagents do Claude Code são úteis quando a exploração encheria a conversa principal com leituras de arquivos. A documentação oficial explica que eles trabalham em contexto próprio e retornam apenas um resumo. Codex também documenta subagents para exploração paralela de codebase. Use com escopo limitado porque também consomem tokens. Veja Subagent Patterns.

Execute três subagents em modo somente leitura:
1. Entrypoints API e limites de auth
2. DB schema e limites de migration
3. Rotas UI e caminho de receita

Cada subagent pode ler no máximo 8 arquivos e deve retornar apenas achados finais.
Depois, o agente pai deve mesclar duplicatas, conflitos e incógnitas.

Evite Inchaço De Contexto

A regra simples é separar evidências de decisões. Arquivos inteiros, logs longos e cem hits de busca são evidência pesada demais. Filtre primeiro, decida depois.

A compaction da OpenAI é um recurso de API, mas o princípio operacional serve aqui: manter o resumo necessário e descartar detalhe antigo.

Comprima a investigação para que a próxima pessoa continue em menos de 300 palavras.
Mantenha:
- Entrypoints confirmados
- Arquivos high risk
- Limites que não devem ser cruzados
- Hipóteses não confirmadas
- Próximo comando a executar

Descarte:
- Hipóteses já refutadas
- Logs longos
- Arquivos gerados que não precisam ser lidos

Notas de handoff importam em desenvolvimento e operação de conteúdo. Em artigos multilíngues, registre quais locale files eram sua responsabilidade. Em app, registre até qual entrypoint você traçou. Em bug, registre hipóteses descartadas. Combine com Claude Code Testing Strategies e o guia de approval e sandbox.

Três Casos De Uso

Primeiro, handoff de um SaaS. No primeiro dia, mapeie login, billing, admin e notificações. Encontre importers de AuthService e BillingService, depois trace checkout da route até o banco. Ainda não edite. A saída deve ser mapa de risco e ordem de leitura.

Segundo, migração legacy. Busque legacy, deprecated e migration antes de pedir código substituto. Pergunte por riscos de compatibilidade. Migrations de banco, APIs públicas, batch jobs e cron merecem cuidado porque rollback é caro.

Terceiro, um site de conteúdo e monetização como ClaudeCodeLab. Artigos, componentes CTA, links internos, páginas de produto e traduções vivem em pastas diferentes. Trabalhe por slug. Diga ao agente para possuir apenas um slug e usar outros artigos somente para checar links.

Falhas Comuns

• Confiar só no README. Entrypoints reais frequentemente se afastam de documentação antiga.
• Tratar hits de busca como fluxo de execução. Hit é candidato, não prova.
• Deixar o agente editar antes de esclarecer ownership.
• Colocar pastas geradas, lockfiles, coverage ou dist na conversa.
• Pedir aos subagents uma investigação ampla demais.
• Dizer “corrija com segurança” sem definir high / medium / low.

CTA Para Equipes

Navegação em codebases grandes também afeta receita. Checkout, formulários de lead, conteúdo pago, analytics e anúncios ficam atrás de limites de risco. Um mapa antes da edição reduz retrabalho.

Se sua equipe vai adotar Claude Code ou Codex, comece com um template de repo map, regras em AGENTS.md/CLAUDE.md, critérios de review e prompts exploradores somente leitura. Individualmente, comece pela cheat sheet gratuita. Para treinamento em repositórios reais, veja Claude Code training and consulting.

Nota De Verificação Prática

Quando uso este fluxo, os prompts de implementação seguintes ficam mais estáveis do que quando começo colando arquivos grandes. Os artefatos mais úteis são mapa do repo, resultados rg classificados, pequena tabela de dependências e mapa high / medium / low. Quando pulo essas etapas, pastas geradas, testes antigos e módulos de outras equipes entram na conversa. Antes de publicar, revisei comandos, prompts e script Node para garantir formato copiável e estrutura JavaScript básica correta.