Mapa de codebase existente com Claude Code: fluxo seguro de 45 minutos

Ao colocar Claude Code em uma codebase existente, o primeiro entregável não deveria ser um diff. Deveria ser um mapa. Um repo map mostra onde a aplicação começa, quais pastas importam, quais áreas não devem ser tocadas hoje, como verificar uma mudança e o que a próxima pessoa precisa saber. Sem esse mapa, uma sessão útil pode virar limpeza ampla, refatorações laterais ou alterações difíceis de revisar.

Este guia traz um fluxo de 45 minutos para mapear um repositório antes de editar. A documentação oficial Claude Code overview explica que Claude Code pode ler a codebase, editar arquivos e executar comandos. Justamente por isso, vale definir limites antes de qualquer edição.

Para complementar, leia primeiros prompts para codebase existente, o guia de permissões do Claude Code e o starter template de CLAUDE.md.

O repo map de 45 minutos

Use 25 minutos para exploração somente leitura, 10 para escrever o mapa, 5 para escolher a primeira tarefa segura e 5 para revisar o plano. Não busque uma arquitetura perfeita. Você precisa de um mapa de trabalho para fazer uma mudança pequena, reversível e verificável.

flowchart TD
  A["Inventário somente leitura"] --> B["Encontrar entradas"]
  B --> C["Separar áreas seguras e arriscadas"]
  C --> D["Escolher um primeiro patch"]
  D --> E["Fixar comandos de prova"]
  E --> F["Escrever repo-map.md"]

Entrada é onde a aplicação começa: rota, handler de API, bootstrap de servidor, comando CLI, job agendado ou loader de conteúdo. Área arriscada é qualquer lugar onde um erro pequeno afeta confiança ou receita: autenticação, cobrança, exclusão, configuração de produção, secrets, deploy, analytics e anúncios.

Passo 1: inventário somente leitura

Comece com comandos que descrevem o repo sem modificá-lo. No Windows PowerShell, este bloco já dá uma primeira visão.

git status --short
Get-ChildItem -Force | Select-Object Name, Mode, Length
Get-ChildItem -Recurse -File -Include package.json,astro.config.*,next.config.*,vite.config.*,README*,CLAUDE.md,AGENTS.md | Select-Object -ExpandProperty FullName
rg --files | Select-Object -First 120

Procure stack, documentação, pastas geradas, caches e alterações sem commit. Se a árvore estiver dirty, entenda de quem são as mudanças antes de pedir a Claude Code para editar. Isso evita sobrescrever trabalho de outra pessoa.

O primeiro prompt deve fixar a fronteira de leitura.

Read this repository as an existing codebase. Do not edit files yet.

Goal:
- Create a first repo map in 45 minutes
- Pick exactly one safe starter task
- Identify areas that should not be touched today

Return:
1. Up to 8 important directories
2. Up to 5 runtime or content entry points
3. Risky areas with reasons
4. Three safe starter task candidates
5. Candidate proof commands

If something is uncertain, write "unverified" instead of guessing.

Do not edit files yet mantém a sessão em modo de exploração até existir um plano revisável.

Passo 2: escrever repo-map.md

Não deixe a descoberta apenas no chat. Escreva um repo-map.md curto para a próxima sessão reutilizar. A documentação oficial de memory explica como CLAUDE.md pode guardar instruções persistentes, mas a primeira investigação costuma ficar melhor separada. Regras estáveis podem migrar depois para CLAUDE.md.

# repo-map.md

## Purpose
- First working map for using Claude Code safely in this repository

## Entry points
| Type | File | Role | Proof |
| --- | --- | --- | --- |
| Web | site/src/pages/index.astro | Home page | npm run build |
| Content | site/src/content/blog | Article source | Open article URL |

## Safe candidates
- docs/
- site/src/content/blog/
- Small display copy

## Do not touch today
- .env and secrets
- Auth, billing, deletion flows
- Deploy scripts
- Generated dist and cache folders

## First safe task
- Improve one article CTA
- Change one file only
- Verify with build and preview

## Remaining risks
- Production data flow is unverified
- External service integrations need a separate pass

Não é uma arquitetura completa. É um guardrail para a primeira mudança útil.

Passo 3: reforçar com permissões

Instruções ajudam, mas não são enforcement. A documentação de permissions descreve allow, ask e deny. Na primeira sessão em um repo existente, permita leitura e checks seguros, peça confirmação antes de build ou edição, e negue push, comandos destrutivos e secrets.

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(rg *)",
      "Bash(npm run test *)",
      "Read"
    ],
    "ask": [
      "Bash(npm run build *)",
      "Edit(site/src/content/blog/**)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Read(.env)",
      "Read(**/.env)",
      "Edit(scripts/deploy*)"
    ]
  }
}

Esse JSON é ponto de partida. Seu projeto talvez não tenha npm run test ou precise de outro caminho editável. O importante é decidir o que negar antes de ampliar permissões.

Passo 4: escolher o primeiro patch seguro

Com o mapa pronto, escolha uma tarefa pequena, reversível e fácil de verificar. Três casos funcionam bem.

O primeiro é corrigir CTA de conteúdo. Por exemplo, garantir que um artigo popular conecte naturalmente com produtos e treinamento. Normalmente muda um arquivo e passa por build e preview.

O segundo é documentar comandos de prova no README ou CLAUDE.md. Registrar build, test, lint e preview reduz o custo das próximas sessões sem alterar comportamento da aplicação.

O terceiro é ajustar texto ou formato de data em uma tela. Limite o patch a um ou dois arquivos e valide com teste, screenshot ou preview local. Autenticação, cobrança, permissões e exclusão ficam fora da primeira tarefa.

Using repo-map.md, implement only the first safe task.

Target:
- site/src/content/blog/example.mdx

Requirements:
- Make the final CTA more natural
- Keep internal links to /products/ and /training/
- Do not change pubDate, category, tags, author, or heroImage
- Change this one file only

After finishing, report:
1. Changed files
2. Why they changed
3. Proof commands run
4. Remaining risks

Assim uma solicitação ampla vira um patch revisável.

Passo 5: verificar o mapa

Um repo map é texto, mas as seções mínimas podem ser verificadas. Salve como check-repo-map.js.

const fs = require("node:fs");

const file = process.argv[2] || "repo-map.md";
const text = fs.readFileSync(file, "utf8");
const required = ["Entry points", "Safe candidates", "Do not touch today", "First safe task", "Remaining risks"];
const missing = required.filter((heading) => !text.includes(heading));

if (missing.length > 0) {
  console.error(`Missing repo-map sections: ${missing.join(", ")}`);
  process.exit(1);
}

console.log(`OK: ${file} has the minimum repo-map sections.`);

node check-repo-map.js repo-map.md

O script é simples, mas força cada sessão a deixar o mesmo handoff mínimo.

Falhas comuns

A primeira falha é começar com uma solicitação ampla demais: “refatore a app” ou “melhore a qualidade”. A correção é definir exploração somente leitura, número máximo de arquivos, áreas proibidas e comandos de prova antes de editar.

A segunda é misturar artefatos gerados no mapa. dist, .astro, .next, coverage e node_modules aumentam o ruído. Exclua esses diretórios, salvo quando forem o alvo real de inspeção.

A terceira é subestimar serviços externos. Email, webhooks de pagamento, anúncios, analytics e CRM podem ter pouco código e muito impacto de negócio. Leia primeiro; edite em tarefa separada.

A quarta é parar no build. Um build pode passar enquanto layout mobile, code blocks, CTAs ou links internos quebram. Em site de conteúdo, abra o preview e cheque corpo, código, /products/ e /training/.

Checklist de revisão

Lente	Checagem	Sinal ruim
Diff	Só arquivos pedidos mudaram	Formatação incidental grande
Entrada	Caminho de carregamento claro	Arquivo editado não é usado
Risco	Auth, billing, delete, prod intactos	Secrets ou deploy alterados
Prova	Comando ou check manual existe	Só “provavelmente ok”
Funil	CTA e links internos naturais	Links de produto forçados
Handoff	Riscos restantes escritos	Próxima sessão repete pesquisa

A checklist não é para desconfiar de Claude Code. É para tornar o trabalho repetível.

Incluir rotas de receita

Em um site como ClaudeCodeLab, o mapa também deve incluir monetização. Quais artigos trazem tráfego? Onde o leitor vê download, produto ou consulta? Templates prontos ficam na biblioteca de produtos. Para adoção em equipe, permissões e operações de conteúdo, veja Claude Code training.

Quando as rotas de receita estão no mapa, um pequeno CTA não é apenas copy. Você também verifica links internos, páginas de produto, formulários, analytics e anúncios. Código correto não gera receita se o leitor não tiver um próximo passo claro.

Resumo

Use os primeiros 45 minutos com Claude Code para mapear a codebase, não para reescrevê-la. Faça inventário, identifique entradas, marque riscos, escolha uma tarefa segura, fixe provas e deixe repo-map.md. Depois faça um patch pequeno em um ou dois arquivos.