Onboarding de Equipa no Claude Code

Problema: Passaste três meses a construir um harness personalizado do Claude Code. Dezenas de skills. Alguns slash commands personalizados. Dois ou três subagentes. O teu uso dele é uma segunda natureza. Cada novo colega que tenta usá-lo fica perdido na primeira hora.

Ganho Rápido: Adicionado na v2.1.101. Corre o comando uma vez na raiz do teu projeto e escreve um doc completo de arranque baseado em como realmente trabalhas:

claude -p "/team-onboarding"

O Claude lê os teus últimos 30 dias de uso local, analisa a pasta .claude/, inspeciona o CLAUDE.md, percorre a estrutura do projeto, e deposita um ficheiro markdown que podes entregar a um novo colega. Sem README manual. Sem folha de cálculo de "conhecimento tribal". Sem auditoria trimestral de onboarding.

O Que o /team-onboarding Realmente É

É um slash command integrado que gera um guia de arranque a partir de duas fontes de dados muito diferentes. Dados estruturais: os teus .claude/commands/, .claude/skills/, .claude/agents/, CLAUDE.md, servidores MCP configurados, repositórios irmãos. Dados comportamentais: com que frequência correste cada comando nos últimos 30 dias, a que tipos de trabalho esses comandos correspondem, quais os servidores MCP que tocaste.

As duas fontes são combinadas num doc markdown que lê como um engenheiro sénior a escrever um guia de primeiro dia para o novo contratado que está a sombreá-lo.

Não é uma interface de onboarding em tempo real. Não é um chat. Corre uma vez, escreve um ficheiro, e sai. O ficheiro que obtens é um snapshot de como a ferramenta foi usada dentro do teu repositório.

O Que Lê

Seis inputs alimentam o guia. Cada input é local. Nada sai da tua máquina exceto as chamadas ao próprio Claude.

O histórico de uso é a razão pela qual esta funcionalidade é interessante. Qualquer ferramenta pode listar ficheiros. Muito poucas conseguem dizer a um novo contratado que o developer sénior corre o /claude-scout sete vezes por mês e nunca tocou no MCP. Essa segunda camada é o que transforma uma listagem de ficheiros num doc de arranque.

O Que o Output Parece

Aqui está uma amostra real, sem edição, de um repositório de content-factory que tem estado em uso ativo por um mês:

# Welcome to Build This Now

## How We Use Claude

Based on speedy_devv's usage over the last 30 days:

Work Type Breakdown:
  Write Docs        █████████░░░░░░░░░░░  44%
  Build Feature     ███████░░░░░░░░░░░░░  33%
  Plan Design       ████░░░░░░░░░░░░░░░░  22%

Top Skills & Commands:
  /claude-scout     ████████████████████  7x/month
  /carousel         ██████░░░░░░░░░░░░░░  2x/month
  /compact          ██████░░░░░░░░░░░░░░  2x/month
  /claude-research  ███░░░░░░░░░░░░░░░░░  1x/month
  /resume           ███░░░░░░░░░░░░░░░░░  1x/month

Top MCP Servers:
  _None configured yet_

## Your Setup Checklist

### Codebases
- [ ] btn-content-factory (this repo, content generation pipeline)
- [ ] claude-code-seo-machine, sibling repo (blog paraphrase + SEO)
- [ ] build-kit-template, the framework itself

### MCP Servers to Activate
- [ ] _None in use yet_

### Skills to Know About
- /claude-scout: hourly scout for Anthropic/Claude Code news. Most-used
  command on the team.
- /carousel: builds an Instagram carousel via the carousel-designer +
  carousel-evaluator GAN loop.
- /blog-post: turns a carousel into a /blog/guide/ MDX page + hero image.

## Team Tips
_TODO_

## Get Started
_TODO_

Voltam cinco secções. O cabeçalho puxa o nome da equipa do CLAUDE.md. "How We Use Claude" é a camada comportamental. "Your Setup Checklist" é estrutural. "Team Tips" e "Get Started" são placeholders interativos que o comando te pede para preencher após a primeira execução.

Os gráficos de barras não são decoração. São ASCII seguro para shell, por isso podes colar o ficheiro em qualquer lugar e o ritmo do trabalho da equipa é visível de relance. Um novo colega a folheá-lo sabe, em dez segundos, que esta equipa documenta mais do que constrói, vive no /claude-scout, e não tem MCP ligado. Esse é melhor contexto do que a maioria das apresentações de onboarding.

Como Executá-lo

Duas formas de o invocar. Ambas chegam ao mesmo output.

Corre sem interface, pipe para um ficheiro:

claude -p "/team-onboarding" > ONBOARDING.md

Ou corre dentro de uma sessão interativa:

/team-onboarding

A versão interativa faz três perguntas de acompanhamento depois do primeiro rascunho. Como se chama a equipa. Se há uma boa primeira tarefa para o novo contratado. Que dicas de equipa queres que sejam escritas e que ainda não estão no CLAUDE.md. Responde-lhes e as secções _TODO_ ficam preenchidas. Ignora-as e o ficheiro é enviado com os placeholders.

A versão sem interface não pergunta. Escreve o rascunho tal como está, secções _TODO_ e tudo.

Dia Um Versus Semana Um

Aqui está a parte que a maioria das pessoas não percebe. O comando combina dados estruturais com dados comportamentais. Os dados estruturais existem no dia um. Os dados comportamentais não.

Um clone fresco do teu repositório com zero histórico de uso dá-te um doc meio preenchido. Tens a checklist de configuração, o inventário de skills, a lista de MCP. Não tens a distribuição de tipos de trabalho, as barras de frequência, ou o sinal que diz ao novo contratado qual é o comando mais usado.

Corre o comando cedo demais e o output lê como uma listagem seca de ficheiros. Corre depois de uma semana de trabalho real e lê como um engenheiro sénior o escreveu para ti.

A jogada certa não é "o novo colega corre-o no dia um." A jogada certa é "o engenheiro experiente corre-o no seu próprio ambiente, edita o output, e entrega o ficheiro curado ao novo contratado."

Envia-o Com o Teu Harness

Se mantens um framework, template, ou toolkit interno que outras pessoas usam, o comando torna-se uma funcionalidade de distribuição.

Corre /team-onboarding no teu ambiente de dev principal. O teu histórico de uso é rico por agora. Obtens a camada comportamental completa. Edita quaisquer caminhos pessoais que não queiras partilhar. Faz commit do resultado no teu repositório como docs/how-we-use-claude-code.md. Envia-o com a tua próxima versão.

Os teus utilizadores recebem agora algo que nenhum boilerplate ou starter kit alguma vez lhes deu. Um snapshot de como as pessoas que construíram o framework o usam realmente dia a dia. Não a versão de marketing. Não a lista de funcionalidades. Os padrões de uso reais.

Atualiza-o em cada versão. Novos comandos que adicionaste aparecem automaticamente porque os tens estado a correr. Novas skills que ligaste aparecem porque o scan estrutural as apanha. Os comandos antigos que paraste de usar desaparecem da lista de topo. O doc evolui com a ferramenta, sem tu escreveres uma única frase à mão.

O mesmo padrão funciona dentro de uma empresa. Corre-o no ambiente do engenheiro de staff. Faz commit do output como o ficheiro canónico "how we use Claude Code" da tua equipa. Revê-o uma vez por trimestre. Atualiza quando divergir.

Configuração e Controlo

Três ajustes que vale a pena conhecer.

Destino do output. Redireciona a execução sem interface para onde quiseres. Para um ficheiro no repositório, para uma wiki de equipa, para um doc partilhado. O output é markdown simples com barras seguras para ASCII.

Janela de lookback. O padrão é 30 dias. Para um engenheiro sénior que está no repositório há meses, esta é a janela certa. Para um projeto curto, 30 dias pode cobrir tudo o que alguma vez fizeste.

Follow-ups interativos. A versão interativa faz perguntas. A versão sem interface salta-as. Se queres automatizar todo o fluxo, usa sem interface e preenche as secções _TODO_ à mão. Se queres que o Claude te ajude a redigir as dicas de equipa, usa interativo.

Há também um sinal oculto no fundo do ficheiro. Um comentário HTML que lê onboarding buddy mode. Esse é um hook de follow-up. Da próxima vez que um colega abre uma sessão do Claude Code no mesmo repositório, o Claude trata-se a si próprio como o buddy de onboarding para esse ficheiro. Entregas ao novo contratado o doc markdown e o próprio Claude Code. O Claude guia-o pelo doc, secção a secção, respondendo a perguntas pelo caminho.

Melhores Práticas

Corre-o no ambiente com o uso mais rico. A camada comportamental só vale a pena se o comando tiver dados reais para ler. Não o corras num clone fresco. Corre-o no portátil onde o trabalho realmente acontece.

Edita antes de enviares. O primeiro rascunho tem caminhos pessoais, referências a repositórios irmãos, e às vezes o handle do GitHub de um colega incorporado. Limpa estes antes de fazer commit do ficheiro. Trata o output como um primeiro rascunho, não como um doc final.

Regenera em cada versão. Configura um just onboarding ou script npm. Uma linha, um comando. Corre novamente quando cortas uma nova versão. O doc mantém-se atual sem tu tocares nele.

Combina-o com o CLAUDE.md. O CLAUDE.md é as tuas regras para o AI. O doc de onboarding é as tuas regras para o humano. Complementam-se. Um diz ao Claude como se comportar. O outro diz ao novo contratado como a equipa funciona.

Lê o output tu próprio. A primeira vez que o corres, passa cinco minutos a ler o que o Claude notou sobre o teu próprio trabalho. Vais aprender algo. A maioria dos engenheiros não sabe os seus próprios três comandos de topo até ver o gráfico de barras.

Próximos Passos

• Configura o CLAUDE.md para ancorar as regras da tua equipa para o Claude
• Explora a auto memória para conhecimento por projeto que o Claude escreve para si próprio
• Aprende o diretório .claude/rules/ para instruções modulares do projeto
• Lê sobre skills personalizadas para entender o que o teu doc de onboarding está a inventariar
• Olha para as equipas de agentes se o teu fluxo de trabalho abrange múltiplos subagentes em paralelo

O onboarding de equipa fecha o loop entre o que construíste e o que a tua equipa consegue realmente usar. O teu harness deixa de ser uma cabine de pilotagem pessoal e começa a ser uma bancada de trabalho partilhada. Corre-o uma vez, entrega o ficheiro ao novo contratado, e volta a fazer shipping.