Guia de colaboração em equipe com Claude Code: handoff, revisão e permissões

Claude Code já ajuda bastante no uso individual: investigar código, aplicar correções e escrever testes ficam mais rápidos. Em equipe, porém, o desafio muda. É preciso saber quem aprovou qual comando, quais arquivos Claude leu, quais riscos ainda não foram verificados e quais sugestões da IA foram aceitas por uma pessoa.

Este guia mostra um fluxo prático para equipes pequenas e médias. Ele cobre handoff, pré-revisão de PR, regras em CLAUDE.md, limites de permissão, onboarding, troca de turno em incidentes e falhas de comunicação. Limite de permissão é o conjunto de arquivos e comandos que Claude Code pode ler, editar ou executar. Recibo de revisão é uma nota curta no PR que registra como o time tratou as sugestões da IA.

flowchart LR
  A["Pedido do desenvolvedor"] --> B["CLAUDE.md e regras"]
  B --> C["Trabalho do Claude Code"]
  C --> D["Testes e diff"]
  D --> E["Recibo de revisão"]
  E --> F["Revisão humana do PR"]

Quatro lugares compartilhados

Um fluxo de equipe estável não pode depender de uma pessoa lembrar bons prompts. As regras precisam morar em arquivos reutilizáveis.

Lugar	Objetivo	Em Git
CLAUDE.md	Convenções, proibições, comandos de teste	Sim
.claude/settings.json	Permissões compartilhadas, regras deny, hooks	Sim
.claude/settings.local.json	URLs pessoais e ajustes temporários	Não
.claude/prompts/*.md	Modelos de handoff, revisão e investigação	Sim

A documentação oficial explica memória do Claude Code, configurações, permissões e segurança. Para aprofundar no site, veja boas práticas de CLAUDE.md, guia de hooks do Claude Code e GitHub Actions avançado.

Caso 1: handoff do desenvolvedor para o revisor

O erro mais comum é entregar um PR com “Claude corrigiu”. O revisor precisa saber quais arquivos foram inspecionados, quais comandos foram aprovados, quais testes falharam e quais decisões ainda são humanas.

Crie .claude/prompts/handoff.md:

# Escrever handoff para a equipe

Leia o diff atual e escreva o handoff neste formato.

## Objetivo
- Problema que esta mudança resolve:

## Escopo
- Arquivos alterados:
- Arquivos não alterados mas possivelmente afetados:

## Verificação
- Comandos executados:
- Resultado:
- Resumo dos logs de falha:

## Foco para o revisor
- Decisão de produto:
- Segurança:
- Performance:
- Testes ausentes:

## Próxima pessoa responsável
- Verificar primeiro:
- Pode esperar:

Depois de preparar o diff, execute:

claude -p "Leia git diff e crie um handoff de equipe usando .claude/prompts/handoff.md"

Cole o resultado no corpo do PR. Assim o revisor começa pelos riscos conhecidos, não pela reconstrução do contexto.

Caso 2: pré-revisão de PR com IA

Claude Code não deve substituir aprovação humana. Ele funciona melhor como leitura prévia que encontra bugs óbvios, testes faltando, riscos de segurança e mudanças inconsistentes.

Crie .claude/prompts/pr-review.md:

# Pré-revisão de PR

Revise o diff com estes critérios:

1. Branches, null/undefined e valores limite que podem virar bug
2. Autorização, validação e exposição de segredos
3. Consultas N+1, rerenders desnecessários e trabalho síncrono pesado
4. Violações de CLAUDE.md
5. Casos de teste faltando

Formato de saída:
- Gravidade: alta / média / baixa
- Arquivo:
- Linha ou função:
- Motivo:
- Sugestão de correção:

Marque achados especulativos como “precisa confirmar”.

Execução local com GitHub CLI:

gh pr diff 123 | claude -p "$(cat .claude/prompts/pr-review.md)"

Com GitHub Actions, deixe a automação apenas comentar. A decisão de merge continua humana.

name: Claude PR pre-review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  pre-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install tools
        run: npm install -g @anthropic-ai/claude-code
      - name: Run Claude Code review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          gh pr diff "$PR_NUMBER" > /tmp/pr.diff
          claude -p "$(cat .claude/prompts/pr-review.md)

          Diff:
          $(cat /tmp/pr.diff)" > /tmp/claude-review.md
          gh pr comment "$PR_NUMBER" --body-file /tmp/claude-review.md

A página oficial de fluxos comuns também cobre revisão e testes. A regra do time deve ser simples: comentários da IA ajudam, pessoas aprovam.

Caso 3: onboarding de novos membros

Uma pessoa nova costuma travar menos na sintaxe e mais em “qual comando é seguro”, “onde está a regra de negócio” e “qual arquivo ler primeiro”. Claude Code pode criar o primeiro mapa do repositório.

claude -p "
Explique este repositório para uma pessoa nova no time.
Inclua:
- Diretórios principais e responsabilidades
- Comandos para rodar localmente, lint, test e build
- Primeiros 3 arquivos para ler
- Regras de negócio a verificar antes de mudar código
- Erros comuns e como evitar
- Uma tarefa prática de 30 minutos

Não chute. Liste pontos desconhecidos como precisa confirmar.
"

Não publique a saída sem revisão. Uma pessoa experiente deve gastar 30 minutos adicionando restrições de produção, decisões históricas e riscos operacionais. Para investigações maiores, os padrões com subagentes ajudam a separar exploração e resumo.

Caso 4: handoff de incidente

Durante um incidente, Claude Code ajuda a resumir logs e organizar hipóteses. Os riscos também aumentam: colar segredos, compartilhar hipótese não verificada como fato ou perder o que já foi tentado quando a pessoa responsável muda.

Salve como .claude/prompts/incident-handoff.md:

# Handoff de incidente

## Sintoma
- Desde quando:
- Escopo:
- Impacto em usuários:

## Fatos observados
- Logs:
- Métricas:
- Passos de reprodução:

## Tentativas
- Comandos:
- Resultado:
- Hipóteses descartadas:

## Risco restante
- Corrupção de dados:
- Impacto de segurança:
- Estado do rollback:

## Próxima pessoa responsável
- Primeira tela/log a verificar:
- Comandos que não devem ser executados:

Masque emails, tokens de acesso e IDs de clientes antes de enviar logs ao Claude Code. A documentação de segurança oficial também alerta sobre permissões e injeção de prompt.

Regras úteis em CLAUDE.md

CLAUDE.md deve conter fatos que o time repete o tempo todo. Mantenha curto, concreto e verificável.

# Instruções do projeto para Claude Code

## Antes de trabalhar
- Executar `git status --short` antes de editar.
- Não reverter mudanças existentes de outras pessoas.
- Se o comportamento do produto não estiver claro, escrever “precisa confirmar” no PR.

## Regras de código
- Validar todas as entradas de API.
- Explicitar limites de transação em escritas no banco.
- Reutilizar chaves de tradução existentes antes de criar texto de UI.

## Testes
- Adicionar testes unitários para mudanças de lógica.
- Adicionar um teste de regressão para cada correção de bug.
- Se testes não puderem ser executados, explicar o motivo.

## PR
- Incluir resumo, verificação e risco restante.
- Usar sugestões do Claude Code somente após revisão humana.

Se o repositório já usa AGENTS.md, importe em vez de duplicar regras.

@AGENTS.md

## Apenas Claude Code
- Usar plan mode em fluxos de cobrança, autenticação e exclusão.
- Pessoas executam `git push`, deploys de produção e migrações.

Fixar limites de permissão

O maior risco é ampliar permissões por conveniência. Comece com deny claro e allow mínimo.

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm test)",
      "Bash(git diff *)",
      "Bash(git status *)",
      "Edit(src/**)",
      "Edit(tests/**)"
    ],
    "ask": [
      "Bash(npm install *)",
      "Bash(git commit *)",
      "Write(.github/**)"
    ],
    "deny": [
      "Read(.env*)",
      "Read(**/secrets/**)",
      "Bash(git push --force*)",
      "Bash(rm -rf *)",
      "Bash(npm publish*)"
    ]
  }
}

Hooks podem rodar verificações após edição ou bloquear comandos perigosos. Leia a referência oficial de hooks antes de adotar.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --quiet"
          }
        ]
      }
    ]
  }
}

Esse exemplo só vale se existir npm run lint. Em monorepo grande, prefira verificações por arquivo ou deixe o trabalho pesado para CI.

Deixar recibo de revisão no PR

Revisão com IA fica perigosa quando ninguém registra quais sugestões foram aceitas. Adicione isto ao modelo de PR:

## Recibo de revisão do Claude Code

- Prompt usado:
- Diff revisado pelo Claude Code:
- Sugestões aceitas:
- Sugestões rejeitadas e motivo:
- Verificações humanas adicionais:
- Testes executados:
- Risco restante:

Responsável pela decisão final:

Se Claude Code não foi usado, escreva “não usado”. O objetivo é deixar trabalho assistido por IA tão transparente quanto o trabalho normal.

Falhas concretas e correções

Falha	Impacto	Correção
CLAUDE.md desatualizado	Comandos antigos e APIs removidas voltam	Revisar mensalmente com falhas reais
Permissões amplas	Segredos e ações de produção ficam próximos	Escrever deny primeiro e reduzir allow
Aprovação só por IA	Decisões de produto e responsabilidade somem	Aprovação do PR sempre humana
Handoff verbal	No dia seguinte ninguém rastreia o motivo	Colar nota no PR ou Issue
/clear apaga contexto	O motivo da mudança desaparece	Salvar resumo antes de reset ou compact
Hooks pesados	O time começa a contornar o fluxo	Usar hooks por arquivo ou CI

A comunicação também falha com pedidos vagos. “Arrume bem” obriga Claude Code a adivinhar o destino. Escreva limites curtos: “somente esta função”, “não mexer em schema”, “ler primeiro o log do teste falho”.

Checklist mínima do time

• CLAUDE.md tem comandos, proibições e regras de PR
• .claude/settings.json separa allow, ask e deny
• .claude/settings.local.json está em .gitignore
• Prompts de handoff, PR e incidente estão compartilhados
• Modelo de PR inclui recibo de revisão
• Responsável pela decisão final está claro
• Existe tarefa de onboarding de 30 minutos

ClaudeCodeLab continua refinando modelos para equipes de desenvolvimento com IA. Para acelerar a adoção interna, veja os produtos da ClaudeCodeLab.

Conclusão

Usar Claude Code em equipe não é encontrar um prompt mágico. É combinar instruções compartilhadas, permissões estreitas, handoffs duráveis e recibos de revisão auditáveis.

No uso individual, alguns prompts bons já ajudam. Em equipe, outra pessoa precisa reproduzir o fluxo, rastrear falhas e separar sugestões do Claude Code de decisões humanas.

Ao testar essa estrutura em um pequeno repositório de validação de Masa, a melhora mais visível veio das notas de handoff e dos recibos de revisão no PR. Revisores fizeram menos perguntas como “o que você verificou?”. A pior configuração foi rodar lint completo após cada edição via hook: ficou lento demais, então CI foi melhor. Comece por CLAUDE.md, prompt de pré-revisão e recibo de revisão.