Integração de Código-Fonte (Onboarding)

O que Integração de Código-Fonte (Onboarding) faz?

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 em um repositório existente pela primeira vez.

Quando Usar

• Primeira vez abrindo um projeto com Claude Code
• Ingressando em um novo time ou repositório
• Usuário pergunta "ajude-me a entender esta base de código"
• Usuário pede para gerar um CLAUDE.md para um projeto
• Usuário diz "me integre" ou "explique 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 pacotes
   → 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
   → Top 2 níveis da árvore de diretórios, ignorando node_modules, vendor,
     .git, dist, build, __pycache__, .next

5. Detecção de configurações e ferramentas
   → .eslintrc*, .prettierrc*, tsconfig.json, Makefile, Dockerfile,
     docker-compose*, .github/workflows/, .env.example, configurações de CI

6. Detecção de estrutura de testes
   → 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 Tecnológico

• 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 de Arquitetura

• Monolito, 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 alto nível para seus propósitos:

src/components/  → Componentes de UI React
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 deploy

Fluxo de Dados Trace uma requisição desde a entrada até a 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, queries 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 mensagens de commit a partir de commits recentes
• Fluxo de PR (squash, merge, rebase)
• Se o repositório não tiver commits 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 serve]

## Stack Tecnológico
<!-- Exemplo para um projeto Next.js — substitua pelo stack detectado -->
| 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 rotas 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
[Diretório de alto nível → mapeamento de propósito]

## Ciclo de Vida da Requisição
[Trace uma requisição de API desde a entrada até a 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 de 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 de UI  | `src/app/(dashboard)/`   |
| Adicionar uma tabela no banco | `prisma/schema.prisma`   |
| Adicionar um teste          | `tests/` correspondendo ao caminho da fonte |
| Alterar configuração de build | `next.config.ts`         |

Saída 2: CLAUDE.md Inicial

Gere ou atualize um CLAUDE.md específico do projeto com base nas convenções detectadas. Se CLAUDE.md já existir, leia-o primeiro e aprimore-o — preserve as instruções específicas do projeto existentes e indique claramente o que foi adicionado ou alterado.

# Instruções do Projeto

## Stack Tecnológico
[Resumo do stack detectado]

## Estilo de Código
- [Convenções de nomenclatura detectadas]
- [Padrões detectados a serem seguidos]

## Testes
- Executar testes: `[comando de teste detectado]`
- Padrão de teste: [convenção de nomenclatura de arquivo de teste detectada]
- Cobertura: [se configurado, o comando de cobertura]

## Build & Execução
- Dev: `[comando de dev detectado]`
- Build: `[comando de build detectado]`
- Lint: `[comando de lint detectado]`

## Estrutura do Projeto
[Diretório chave → mapa de propósito]

## Convenções
- [Estilo de commit se detectável]
- [Fluxo de PR se detectável]
- [Padrões de tratamento de erros]

Melhores Práticas

1. Não leia tudo — o reconhecimento deve usar Glob e Grep, não Read em cada arquivo. Leia seletivamente apenas para sinais ambíguos.
2. 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.
3. Respeite o CLAUDE.md existente — se já existir um, aprimore-o em vez de substituí-lo. Destaque o que é novo vs. existente.
4. Seja conciso — o guia de integração deve ser escaneável em 2 minutos. Detalhes pertencem ao código, não ao guia.
5. Sinalize desconhecidos — 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 do que uma resposta errada.

Anti-Padrões a Evitar

• Gerar um CLAUDE.md com mais de 100 linhas — mantenha o foco
• Listar todas as dependências — 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 insights estruturais 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: Execute o fluxo completo de 4 fases → produza Guia de Integração + CLAUDE.md Inicial Saída: Guia de Integração impresso diretamente na conversa, mais 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: Execute as Fases 1-3, pule o Guia de Integração, produza apenas o CLAUDE.md Saída: CLAUDE.md específico do projeto com as convenções detectadas

Exemplo 3: Aprimorar CLAUDE.md existente

Usuário: "Atualize o CLAUDE.md com as convenções atuais do projeto" Ação: Leia o CLAUDE.md existente, execute as Fases 1-3, mescle as novas descobertas Saída: CLAUDE.md atualizado com adições claramente marcadas