Onboarding de Código Base
Analise sistematicamente uma base de código desconhecida e produza um guia de integração estruturado. Projetado para desenvolvedores que ingressam em um novo projeto ou configuram o Claude Code pela primeira vez em um repositório existente.
Quando Usar
- Primeira vez abrindo um projeto com Claude Code
- Ingressando em um novo time ou repositório
- Usuário pergunta "me ajude a entender essa base de código"
- Usuário pede para gerar um CLAUDE.md para um projeto
- Usuário diz "me integre" ou "me guie por este repositório"
Como Funciona
Fase 1: Reconhecimento
Colete sinais brutos sobre o projeto sem ler todos os arquivos. Execute estas verificações em paralelo:
1. Detecção de manifesto de pacote
→ package.json, go.mod, Cargo.toml, pyproject.toml, pom.xml, build.gradle,
Gemfile, composer.json, mix.exs, pubspec.yaml
2. Identificação de framework
→ next.config.*, nuxt.config.*, angular.json, vite.config.*,
django settings, flask app factory, fastapi main, rails config
3. Identificação de ponto de entrada
→ main.*, index.*, app.*, server.*, cmd/, src/main/
4. Instantâneo da estrutura de diretórios
→ Topo 2 níveis da árvore de diretórios, ignorando node_modules, vendor,
.git, dist, build, __pycache__, .next
5. Detecção de configuração e ferramentas
→ .eslintrc*, .prettierrc*, tsconfig.json, Makefile, Dockerfile,
docker-compose*, .github/workflows/, .env.example, configurações de CI
6. Detecção de estrutura de teste
→ tests/, test/, __tests__/, *_test.go, *.spec.ts, *.test.js,
pytest.ini, jest.config.*, vitest.config.*
Fase 2: Mapeamento de Arquitetura
A partir dos dados de reconhecimento, identifique:
Stack Tecnológica
- Linguagem(ns) e restrições de versão
- Framework(s) e bibliotecas principais
- Banco(s) de dados e ORMs
- Ferramentas de build e bundlers
- Plataforma de CI/CD
Padrão Arquitetural
- Monólito, monorepo, microsserviços ou serverless
- Separação frontend/backend ou full-stack
- Estilo de API: REST, GraphQL, gRPC, tRPC
Diretórios-chave Mapeie os diretórios de topo para sua finalidade:
src/components/ → Componentes React UI
src/api/ → Manipuladores de rotas de API
src/lib/ → Utilitários compartilhados
src/db/ → Modelos e migrações de banco de dados
tests/ → Suítes de teste
scripts/ → Scripts de build e implantação
Fluxo de Dados Trace uma requisição da entrada à resposta:
- Onde a requisição entra? (roteador, manipulador, controlador)
- Como é validada? (middleware, schemas, guards)
- Onde está a lógica de negócio? (serviços, modelos, casos de uso)
- Como alcança o banco de dados? (ORM, consultas SQL brutas, repositórios)
Fase 3: Detecção de Convenções
Identifique padrões que a base de código já segue:
Convenções de Nomenclatura
- Nomenclatura de arquivos: kebab-case, camelCase, PascalCase, snake_case
- Padrões de nomenclatura de componentes/classes
- Nomenclatura de arquivos de teste:
*.test.ts,*.spec.ts,*_test.go
Padrões de Código
- Estilo de tratamento de erros: try/catch, tipos Result, códigos de erro
- Injeção de dependência ou imports diretos
- Abordagem de gerenciamento de estado
- Padrões assíncronos: callbacks, promises, async/await, channels
Convenções Git
- Nomenclatura de branches a partir de branches recentes
- Estilo de mensagem de commit a partir de commits recentes
- Fluxo de trabalho de PR (squash, merge, rebase)
- Se o repositório não tiver commits ainda ou tiver apenas um histórico raso (ex.:
git clone --depth 1), pule esta seção e anote "Histórico Git indisponível ou muito raso para detectar convenções"
Fase 4: Gerar Artefatos de Integração
Produza duas saídas:
Saída 1: Guia de Integração
# Guia de Integração: [Nome do Projeto]
## Visão Geral
[2-3 frases: o que este projeto faz e a quem atende]
## Stack Tecnológica
<!-- Exemplo para um projeto Next.js — substitua pela stack detectada -->
| Camada | Tecnologia | Versão |
|--------|------------|--------|
| Linguagem | TypeScript | 5.x |
| Framework | Next.js | 14.x |
| Banco de Dados | PostgreSQL | 16 |
| ORM | Prisma | 5.x |
| Testes | Jest + Playwright | - |
## Arquitetura
[Diagrama ou descrição de como os componentes se conectam]
## Pontos de Entrada Principais
<!-- Exemplo para um projeto Next.js — substitua pelos caminhos detectados -->
- **Rotas da API**: `src/app/api/` — manipuadores de rotas Next.js
- **Páginas da UI**: `src/app/(dashboard)/` — páginas autenticadas
- **Banco de Dados**: `prisma/schema.prisma` — fonte da verdade do modelo de dados
- **Config**: `next.config.ts` — configuração de build e runtime
## Mapa de Diretórios
[Diretório de topo → mapeamento de finalidade]
## Ciclo de Vida de uma Requisição
[Trace uma requisição de API da entrada à resposta]
## Convenções
- [Padrão de nomenclatura de arquivos]
- [Abordagem de tratamento de erros]
- [Padrões de teste]
- [Fluxo de trabalho Git]
## Tarefas Comuns
<!-- Exemplo para um projeto Node.js — substitua pelos comandos detectados -->
- **Executar servidor dev**: `npm run dev`
- **Executar testes**: `npm test`
- **Executar linter**: `npm run lint`
- **Migrações de banco de dados**: `npx prisma migrate dev`
- **Build para produção**: `npm run build`
## Onde Olhar
<!-- Exemplo para um projeto Next.js — substitua pelos caminhos detectados -->
| Eu quero... | Olhe em... |
|-------------|------------|
| Adicionar um endpoint de API | `src/app/api/` |
| Adicionar uma página da UI | `src/app/(dashboard)/` |
| Adicionar uma tabela no banco | `prisma/schema.prisma` |
| Adicionar um teste | `tests/` correspondente ao caminho da fonte |
| Alterar config de build | `next.config.ts` |
Saída 2: CLAUDE.md Inicial
Gere ou atualize um CLAUDE.md específico do projeto baseado nas convenções detectadas. Se CLAUDE.md já existir, leia-o primeiro e aprimore-o — preserve as instruções existentes específicas do projeto e destaque claramente o que foi adicionado ou alterado.
# Instruções do Projeto
## Stack Tecnológica
[Resumo da stack detectada]
## Estilo de Código
- [Convenções de nomenclatura detectadas]
- [Padrões detectados a seguir]
## Testes
- Executar testes: `[comando de teste detectado]`
- Padrão de teste: [convenção de arquivo de teste detectada]
- Cobertura: [se configurada, o comando de cobertura]
## Build & Execução
- Dev: `[comando dev detectado]`
- Build: `[comando de build detectado]`
- Lint: `[comando de lint detectado]`
## Estrutura do Projeto
[Diretório-chave → mapa de finalidade]
## Convenções
- [Estilo de commit se detectável]
- [Fluxo de trabalho de PR se detectável]
- [Padrões de tratamento de erros]
Melhores Práticas
- Não leia tudo — o reconhecimento deve usar Glob e Grep, não Read em cada arquivo. Leia seletivamente apenas para sinais ambíguos.
- Verifique, não adivinhe — se um framework for detectado a partir da configuração mas o código real usar algo diferente, confie no código.
- Respeite o CLAUDE.md existente — se já existir um, aprimore-o em vez de substituí-lo. Destaque o que é novo vs. existente.
- Seja conciso — o guia de integração deve ser escaneável em 2 minutos. Detalhes pertencem ao código, não ao guia.
- Sinalize incógnitas — se uma convenção não puder ser detectada com confiança, diga isso em vez de adivinhar. "Não foi possível determinar o executor de testes" é melhor que uma resposta errada.
Antipadrões a Evitar
- Gerar um CLAUDE.md com mais de 100 linhas — mantenha-o focado
- Listar cada dependência — destaque apenas aquelas que moldam como você escreve código
- Descrever nomes de diretórios óbvios —
src/não precisa de explicação - Copiar o README — o guia de integração adiciona insight estrutural que o README não tem
Exemplos
Exemplo 1: Primeira vez em um novo repositório
Usuário: "Me integre a esta base de código"
Ação: Executar fluxo de trabalho completo de 4 fases → produzir Guia de Integração + CLAUDE.md Inicial
Saída: Guia de Integração impresso diretamente na conversa, além de um CLAUDE.md escrito na raiz do projeto
Exemplo 2: Gerar CLAUDE.md para projeto existente
Usuário: "Gere um CLAUDE.md para este projeto"
Ação: Executar Fases 1-3, pular Guia de Integração, produzir apenas CLAUDE.md
Saída: CLAUDE.md específico do projeto com convenções detectadas
Exemplo 3: Aprimorar CLAUDE.md existente
Usuário: "Atualize o CLAUDE.md com as convenções atuais do projeto"
Ação: Ler CLAUDE.md existente, executar Fases 1-3, mesclar novas descobertas
Saída: CLAUDE.md atualizado com adições claramente marcadas