Como reduzir drasticamente o tempo de onboarding com Claude Code

O tempo de adaptação de um novo engenheiro é um custo enorme em qualquer empresa. Bases de código gigantes, docs espalhados, conhecimento tribal. Torne o Claude Code o copiloto do novo contratado e 3 meses de adaptação viram 2 semanas.

1. Concluir o setup do ambiente em meio dia

Configurar é a primeira barreira. Em vez de incomodar os seniores no Slack:

# O novo contratado roda isto no Mac dele
claude -p "
Me guie no setup do ambiente de desenvolvimento deste repo
(https://github.com/our-org/main-app) no macOS.

Para cada passo:
1. Ferramentas necessárias (com versões)
2. Comandos de instalação
3. Env vars a configurar
4. Como verificar que está rodando
5. Erros comuns e correções

Leia .env.example e README; seja concreto.
"

DMs no Slack para seniores caem drasticamente.

2. Entender a base de código em 5 minutos

Repos gigantes ficam digeríveis.

claude -p "
Explique a estrutura geral deste repo:

1. Layout de diretórios e o propósito de cada um
2. Principais pontos de entrada
3. Fluxo de dados (como um request é processado)
4. Integrações externas (BD, APIs, filas)
5. Cinco arquivos que devo ler primeiro

Proponha também uma ordem de leitura que permita a um
novo contratado começar a mexer em código em uma semana.
"

Combine com Navegação da Base de Código para efeito máximo.

3. Converter conhecimento tribal em docs

Faça emergir o “porquê está assim” que só os veteranos sabem.

claude -p "
Para src/services/billing/LegacyInvoiceService.ts,
infira a partir de git log --follow + blame:

1. Por que o design ficou assim
2. Pegadinhas ao modificá-lo (padrões históricos de bugs)
3. Services relacionados
4. O que rechecar antes de mexer

Salve em docs/onboarding/legacy-notes.md
num formato que os colegas possam anotar facilmente.
"

Use o resultado como thread de discussão no GitHub Discussions — isso impulsiona a documentação guiada por review.

4. Recomendar automaticamente candidatos a primeiro PR

Encontre tarefas pequenas e seguras para o novo contratado.

claude -p "
Sugira 5 candidatos a primeiro PR deste repo:

Critérios:
- Mudanças isoladas (baixo efeito colateral)
- Testes existentes cobrem a área
- Não é lógica de negócio central
- Diff entre 30 e 100 linhas

Olhe tendências de good-first-issue,
comentários TODO/FIXME e pequenos candidatos a refactor.
Para cada um, inclua esforço estimado e o que ensina.
"

5. Auto-review antes de enviar o PR

Reduz bounce-backs dos novos contratados.

claude -p "
Inspecione git diff origin/main...HEAD.
Faça auto-review como novo contratado antes de abrir o PR:

1. Violações das regras de CLAUDE.md
2. Nomes estranhos
3. Testes ausentes
4. Inconsistências de estilo com o código existente
5. Preocupações de segurança

Liste só os pontos que exigem mudança, com prioridade.
"

Idas e vindas de review despencam. Veja Code Review com Claude.

6. Cultura “Pergunte ao Claude primeiro”

Codifique isso em CLAUDE.md.

## Guia de Q&A do Onboarding

### Pergunte ao Claude Code primeiro
- Como o código funciona
- Significado de erros
- Razão do design (via git log + blame)
- Uso de ferramentas

### Escale para Slack #dev-help apenas para
- Interpretação de regras de negócio
- Decisões de priorização
- Tarefas com controle de acesso

### Ao perguntar a um senior, inclua
1. O que você está tentando fazer
2. O que tentou (incluindo a resposta do Claude)
3. Onde está travado

Só isso reduz as interrupções a seniores em ~30%.

7. Gerar retrospectivas semanais automaticamente

Para os 1:1 com o mentor.

claude -p "
Resuma minha atividade da última semana:

- git log --author='new-hire-name' --since='1 week ago'
- PRs criados + status
- Tendências no feedback de review
- Onde eu travei (inferido das commit messages)

Sugira 3 tópicos para levar ao 1:1 com o mentor.
"

O novo contratado ganha uma meta-visão do próprio crescimento.

Anti-padrões

❌ Deixar tudo a cargo do Claude

Claude apenas infere conhecimento tribal. Sempre valide o “porquê” do negócio com especialistas humanos do domínio.

❌ Bloquear perguntas em excesso

Impor demais “pergunte ao Claude” isola o novo contratado. Agende 1:1 agressivos nas primeiras 2 semanas.

❌ Negligenciar a manutenção dos docs

Notas de conhecimento tribal geradas pelo Claude apodrecem se forem abandonadas. Reviews de time em cadência.

Conclusão

• Setup de ambiente self-service em meio dia
• Entender a base de código em 5 minutos
• Converter conhecimento tribal em docs
• Auto-recomendar candidatos a primeiro PR
• Reduzir bounce-backs de PR com auto-review
• Diminuir interrupções a seniores via cultura “Claude primeiro”
• Gerar retros semanais automaticamente

Adaptação mais rápida = menos carga de mentor + mais throughput do time.

Relacionados: Navegação da Base de Código / Code Review / Colaboração em Equipe

Docs oficiais: Anthropic Claude Code