Onboarding de Código

Analise sistematicamente um codebase desconhecido e produza um guia de onboarding estruturado. Projetado para desenvolvedores que ingressam em um novo projeto ou configuram o Claude Code em um repositório existente pela primeira vez.

Quando Usar

• Primeira vez abrindo um projeto com o Claude Code
• Ingressando em uma nova equipe ou repositório
• O usuário pergunta "me ajude a entender este codebase"
• O usuário pede para gerar um CLAUDE.md para um projeto
• O 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. Package manifest detection
   → package.json, go.mod, Cargo.toml, pyproject.toml, pom.xml, build.gradle,
     Gemfile, composer.json, mix.exs, pubspec.yaml

2. Framework fingerprinting
   → next.config.*, nuxt.config.*, angular.json, vite.config.*,
     django settings, flask app factory, fastapi main, rails config

3. Entry point identification
   → main.*, index.*, app.*, server.*, cmd/, src/main/

4. Directory structure snapshot
   → Top 2 levels of the directory tree, ignoring node_modules, vendor,
     .git, dist, build, __pycache__, .next

5. Config and tooling detection
   → .eslintrc*, .prettierrc*, tsconfig.json, Makefile, Dockerfile,
     docker-compose*, .github/workflows/, .env.example, CI configs

6. Test structure detection
   → tests/, test/, __tests__/, *_test.go, *.spec.ts, *.test.js,
     pytest.ini, jest.config.*, vitest.config.*

Fase 2: Mapeamento da Arquitetura

A partir dos dados de reconhecimento, identifique:

Stack de Tecnologia

• 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 CI/CD

Padrão de Arquitetura

• Monolito, monorepo, microsserviços ou serverless
• Divisão frontend/backend ou full-stack
• Estilo de API: REST, GraphQL, gRPC, tRPC

Diretórios Chave Mapeie os diretórios de nível superior para seu propósito:

src/components/  → React UI components
src/api/         → API route handlers
src/lib/         → Shared utilities
src/db/          → Database models and migrations
tests/           → Test suites
scripts/         → Build and deployment scripts

Fluxo de Dados Trace uma requisição da entrada à resposta:

• Onde uma requisição entra? (router, handler, controller)
• Como ela é validada? (middleware, schemas, guards)
• Onde está a lógica de negócios? (services, models, use cases)
• Como ela chega ao banco de dados? (ORM, queries brutas, repositories)

Fase 3: Detecção de Convenções

Identifique os padrões que o codebase 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 de branches recentes
• Estilo de mensagens de commit de commits recentes
• Fluxo de trabalho de PR (squash, merge, rebase)
• Se o repositório ainda não tiver commits ou tiver apenas um histórico raso (por exemplo, git clone --depth 1), pule esta seção e anote "Histórico Git indisponível ou muito raso para detectar convenções"

Fase 4: Geração de Artefatos de Onboarding

Produza duas saídas:

Saída 1: Guia de Onboarding

# Guia de Onboarding: [Nome do Projeto]

## Visão Geral
[2-3 frases: o que este projeto faz e para quem ele serve]

## Stack de Tecnologia
<!-- 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 Chave
<!-- Exemplo para um projeto Next.js — substitua pelos caminhos detectados -->
- **Rotas de API**: `src/app/api/` — manipuladores de rota Next.js
- **Páginas de UI**: `src/app/(dashboard)/` — páginas autenticadas
- **Banco de Dados**: `prisma/schema.prisma` — fonte da verdade do modelo de dados
- **Configuração**: `next.config.ts` — configuração de build e runtime

## Mapa de Diretórios
[Mapeamento de diretório de nível superior → propósito]

## Ciclo de Vida da 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]

…