Onboarding de desenvolvedores com Claude Code: de meses para 2 semanas

Onboarding de um novo engenheiro não termina quando a empresa entrega um notebook. É o caminho entre “consigo abrir o repositório” e “consigo enviar uma mudança pequena, revisável e alinhada às regras do time”. O que mais atrasa esse processo costuma ser setup repetido, codebase grande, critérios de review pouco claros e conhecimento tribal que só pessoas antigas conhecem.

Claude Code não deve substituir mentores. O melhor uso é criar um trilho seguro: instruções em CLAUDE.md, script de setup repetível, permissões, checklist da primeira tarefa, template de PR e um jeito claro de entender CI. Em palavras simples, codebase é todo o código-fonte da aplicação, PR é o pedido de revisão de uma mudança, e CI é o sistema que roda testes e build antes do merge.

Como Claude Code muda com o tempo, use a documentação oficial como base: Claude Code setup, CLI reference, memory e settings. Para contexto, leia também codebase navigation, code review e CLAUDE.md templates.

flowchart LR
  A["Day 1: setup"] --> B["Day 2: codebase map"]
  B --> C["Day 3-5: first task"]
  C --> D["Week 2: PR review"]
  D --> E["Retrospective and docs update"]

1. Comece pelo CLAUDE.md

CLAUDE.md é a memória de projeto que o Claude Code lê como instrução compartilhada. Para onboarding, prefira comandos, limites e regras de escalação em vez de frases genéricas.

cat > CLAUDE.md <<'EOF'
# Project instructions for Claude Code

## Goal
Help new engineers make small, reviewable changes without bypassing tests or team rules.

## Daily commands
- Install: npm ci
- Type check: npm run typecheck
- Unit tests: npm test -- --runInBand
- Lint: npm run lint
- Build: npm run build

## Boundaries
- Do not edit files under migrations/ without human approval.
- Do not read .env, .env.*, secrets/, or production credentials.
- Do not push, commit, deploy, or publish packages.
- Prefer small diffs under 150 lines for first tasks.

## First PR rules
- Explain the intent before editing.
- Reuse existing patterns before adding dependencies.
- Add or update tests for behavior changes.
- Include command output in the PR description.

## When stuck
Ask the engineer to provide:
1. What they tried
2. The exact error
3. The file or command involved
4. What Claude Code inferred and what still needs human judgment
EOF

O objetivo não é transformar Claude Code em um sênior mágico. É reduzir o escopo para que a pessoa aprenda o padrão do time e produza um diff que alguém consiga revisar.

2. Torne o setup repetível

O primeiro bloqueio costuma envolver versão do Node, dependências, variáveis locais, dados de teste e o comando que prova que tudo funciona. Um script transforma isso em caminho claro.

mkdir -p scripts
cat > scripts/onboarding-setup.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

echo "== Checking required tools =="
node --version
npm --version
git --version

if ! command -v claude >/dev/null 2>&1; then
  echo "Claude Code is not installed."
  echo "Install with: npm install -g @anthropic-ai/claude-code"
  exit 1
fi

echo "== Installing dependencies =="
npm ci

if [ ! -f .env ] && [ -f .env.example ]; then
  cp .env.example .env
  echo "Created .env from .env.example. Fill in local-only values before running the app."
fi

echo "== Running baseline checks =="
npm run lint
npm run typecheck
npm test -- --runInBand

echo "== Ask Claude Code for a local map =="
claude -p "Read README.md, package.json, and CLAUDE.md. Explain how to start this project locally, which checks just ran, and what a new engineer should verify before opening the first PR."
EOF
chmod +x scripts/onboarding-setup.sh

Em um projeto npm comum, o script é copiável e executável. Times com pnpm, Yarn, Docker Compose ou Makefile só precisam trocar os comandos. Mantenha a estrutura: setup, verificação e explicação.

3. Configure permissões

Claude Code pode ler arquivos, buscar no código, executar comandos e editar se permitido. Isso ajuda, mas também pode expor .env, rodar comandos perigosos ou criar diffs grandes demais.

mkdir -p .claude
cat > .claude/settings.json <<'EOF'
{
  "permissions": {
    "allow": [
      "Read",
      "Grep",
      "Glob",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(npm run lint)",
      "Bash(npm run typecheck)",
      "Bash(npm test:*)"
    ],
    "ask": [
      "Edit",
      "Write",
      "Bash(npm install:*)",
      "Bash(git checkout:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(git push:*)",
      "Bash(git commit:*)",
      "Bash(rm:*)",
      "Bash(curl:*)",
      "Bash(npm publish:*)"
    ]
  }
}
EOF

Na primeira semana, libere leitura, busca, diff, log e testes. Edição pode pedir confirmação. Push, commit, deploy, publish e segredos devem ficar fora do onboarding.

4. Fixe o checklist do primeiro PR

O primeiro PR é uma prática de trabalho. Bons candidatos: adicionar teste para comportamento existente, corrigir um texto pequeno de UI, melhorar uma mensagem de erro ou remover duplicação em uma pasta. Evite autenticação, cobrança, permissões, migrations, formatação ampla e upgrades de dependências.

mkdir -p docs/onboarding
cat > docs/onboarding/first-task-checklist.md <<'EOF'
# First task checklist

## Before editing
- [ ] I can run `npm ci`.
- [ ] I can run `npm run lint`.
- [ ] I can run `npm run typecheck`.
- [ ] I can run the nearest test for the area I will touch.
- [ ] I understand the user-visible behavior being changed.

## Good first task examples
- [ ] Add a missing unit test around existing behavior.
- [ ] Fix a small UI copy typo with screenshot evidence.
- [ ] Replace duplicated helper logic in one folder.
- [ ] Improve one error message without changing API contracts.

## Not good for the first task
- [ ] Authentication, billing, permissions, or migrations.
- [ ] Broad formatting changes.
- [ ] Dependency upgrades.
- [ ] Refactors across multiple packages.

## PR evidence
- [ ] Summary of the change.
- [ ] Test commands and results.
- [ ] Screenshot or log if behavior changed.
- [ ] Open question for reviewer, if any.
EOF

Esse fluxo cobre casos reais: setup autônomo, leitura da codebase, escolha da primeira tarefa e auto-review antes do PR.

5. Padronize o pedido de review

Muitos primeiros PRs voltam porque o reviewer não sabe o que foi verificado. A template força intenção, segurança, verificação e foco de review.

mkdir -p .github
cat > .github/pull_request_template.md <<'EOF'
## Summary
- TODO

## Why this is safe for a first PR
- Scope:
- Files changed:
- Behavior changed:

## Verification
- [ ] `npm run lint`
- [ ] `npm run typecheck`
- [ ] `npm test -- --runInBand`

## Claude Code self-review prompt used
Ask Claude Code:
"Review git diff origin/main...HEAD for naming, tests, security, and consistency with CLAUDE.md. Return only actionable issues."

## Reviewer focus
- TODO

## Screenshots or logs
- TODO
EOF

Isso também ajuda mentores. Fica claro se a revisão é de design, testes, comportamento, screenshots ou entendimento do processo.

6. Mostre CI desde o primeiro dia

CI significa integração contínua. É o sistema que roda verificações antes de um PR ser mesclado. A pessoa nova precisa aprender a reproduzir falhas localmente, não apenas ver um status vermelho.

name: onboarding-checks

on:
  pull_request:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test -- --runInBand
      - run: npm run build

Mesmo usando outra CI, documente os mesmos comandos. Depois, peça ao Claude Code para ler o log com falha e explicar o primeiro comando local a executar.

Armadilhas comuns

A primeira é delegar julgamento de negócio ao Claude Code. Ele infere a partir de código e histórico, mas compromissos com clientes, exceções e compliance continuam humanos.

A segunda é deixar o primeiro PR grande demais. Mantenha abaixo de 150 linhas quando possível, com testes e rollback simples.

A terceira é expor segredos. Bloqueie .env, credenciais e arquivos de produção nas settings, e use apenas valores de exemplo nos docs.

A quarta é proibir perguntas humanas. “Pergunte ao Claude primeiro” só funciona se as duas primeiras semanas tiverem check-ins frequentes com mentores.

CTA

Para times, padronize CLAUDE.md, permissões, evidências de PR e CI juntos. Individualmente, comece pela cheatsheet gratuita. Para templates reutilizáveis, veja ClaudeCodeLab products. Para treinamento, desenho de permissões e rollout em repositórios reais, use Claude Code training and consultation.

Resultado ao testar

Em melhorias de artigos do ClaudeCodeLab e pequenas mudanças de código, o maior ganho veio de escrever as regras antes de pedir implementação. Com CLAUDE.md, permissões limitadas, comandos de verificação e template de PR, o diff ficou muito mais fácil de revisar. Quando Claude Code errava, as premissas e comandos registrados ajudavam a encontrar rapidamente o ponto de confusão.