Registro de riscos: o que montar antes de levar Claude Code para a equipe

Numa sexta de tarde, um colega soltou: “Claude Code é sensacional, semana que vem todo mundo vai usar.”

Senti um arrepio ruim. Enquanto ele usava sozinho, ele mesmo revisava o próprio branch e ele mesmo dava o merge. Se algo quebrasse, o prejuízo era só dele. Mas usar em equipe muda tudo. Com a permissão de quem, até onde pode mexer, e quem confere a mudança? Se seis pessoas começam a usar sem isso definido, é perfeitamente normal que uma alteração que apaga o banco de produção acabe mergeada sem ninguém perceber.

E olha que eu já vi isso acontecer em outra equipe. Três pessoas rodavam Claude Code, cada uma com a sua configuração do jeito que gostava. Aí um pediu “organiza isso aqui pra ficar bonito”, o arquivo de configuração compartilhado foi reescrito, e na segunda de manhã o deploy inteiro quebrou. Meio dia só para achar a causa. Ninguém agiu de má-fé. Faltava só uma “regra de como delegar em equipe”.

Foi por isso que criei o que vou mostrar neste artigo: o registro de riscos. Falo “registro”, mas é só uma tabela de uma página. Só que ter ou não ter essa tabela decide se a adoção de Claude Code na equipe termina em “ficou mais leve” ou em “me consumi apagando incêndio”.

Pontos principais

• Acidente de adoção em equipe não vem da inteligência do modelo, e sim de não ter definido “quem, até onde e com a conferência de quem”.
• O registro de riscos é uma tabela com uma linha por área perigosa, dizendo “responsável, forma de verificar e condição para avançar”. No começo, três linhas bastam.
• Trave primeiro estes três pontos: permissão (quais arquivos pode tocar), CI (prova de que a mudança não quebrou) e publicação (conferência do que vai ao ar).
• Delegue a Claude Code só “escrever o rascunho e rodar a verificação”. Apagar, banco de produção, cobrança e force push sempre passam por aprovação humana.
• Trago um template de registro que roda colado e um exemplo de config que barra operações perigosas. O segredo é começar testando em um único arquivo.

Afinal, o que é um registro de riscos?

O registro de riscos é uma tabela que lista os “lugares onde é fácil dar acidente” quando você delega trabalho a Claude Code em equipe.

Cada linha precisa de só três colunas. Onde é perigoso, qual é a prova de que aquilo está seguro e quem faz essa conferência. Só isso. Não precisa de ferramenta de gestão complicada. No início, uma planilha basta. Se quiser, até um array dentro do código já resolve.

Por que virar tabela? Porque “vou ficar de olho mais ou menos” é justamente o mais perigoso. Quem está corrido sempre pula a conferência. Se você transforma em tabela e combina “não dá merge enquanto essa linha não estiver preenchida”, o acidente trava até numa sexta de tarde corrida. Aquele acidente de deploy do começo seria evitado só escrevendo uma linha marcando o arquivo de configuração compartilhado como “área que não se toca”.

Os três pontos de perigo para travar primeiro

Os lugares onde a adoção em equipe tropeça quase sempre se resumem a estes três. Ou seja, se você já escrever esses pontos no registro, o desastre do primeiro dia é praticamente evitado.

1. Permissão (quais arquivos pode tocar)

O acidente mais comum é “deixar tocar demais”. Quando você pede “organiza o repositório”, Claude Code reescreve sem dó o arquivo de configuração e até a definição do CI. Por isso, decida antes e deixe por escrito onde pode editar e onde nunca se toca.

Meu critério é simples. Artigos, rascunhos e código de teste: pode mexer. .github/, variáveis de ambiente de produção, configuração de deploy e migração de banco: “para até uma pessoa conferir”. Se você deixa esse limite a gosto de cada um, as regras ficam diferentes por pessoa, e no fim a config mais frouxa é a que causa o acidente. O essencial é a equipe alinhar em uma única regra.

2. CI (faça-o produzir a prova de que não quebrou)

Quando Claude Code diz “consertei”, isso é uma impressão. Não é prova. Por isso, anote no registro o comando que produz a prova de que a mudança não quebrou. Build passa, testes ficam verdes, sem erro de tipo. Combine que uma dessas coisas “sempre roda antes de relatar sucesso”.

O importante aqui é deixar o comando de verificação rápido. Se o teste completo leva 10 minutos, ninguém roda. Se você consegue rodar em 30 segundos só os testes ligados aos arquivos alterados, conferir vira hábito.

3. Publicação (sempre olhe a mudança que vai ao ar)

Seja a página de receita do blog ou uma API, para tudo que vai para fora registre “se você olhou na URL de verdade”. Que o build passou e que a página que o usuário realmente vê está correta são duas coisas diferentes. Abra a URL de produção e guarde uma captura de tela. Faça disso a condição de “concluído”.

Se a URL pública devolve 200 mas o conteúdo é de outra página, é o mesmo que não publicado. Se é uma página em português mas tem corpo em inglês misturado, também está incompleto. Parece óbvio, mas é justo nos dias de pressa que se pula essa parte.

O que delegar à IA e o que a pessoa decide

Se bater dúvida no limite, use esta tabela direto. O critério de decisão é “dá para desfazer ou não”.

Operação	Delegar a Claude Code	Executar só após aprovação humana
Criar/corrigir rascunho	◯
Rodar teste/build	◯
Explicar a mudança (resumo do diff)	◯
Apagar arquivo		◯
Escrever no banco de produção		◯
Operação que gera cobrança		◯
Force push / reescrever histórico		◯
Deploy / publicação em produção		◯

A regra é só uma. Operação difícil de desfazer começa toda como “pergunta para a pessoa”. Só depois, quando a operação se mostra segura, você a promove para automática. Em vez de começar frouxo e dar acidente, começar apertado e ir afrouxando aos poucos sai mais rápido no fim das contas.

Template de registro de riscos para copiar e colar

Antes do pedido, primeiro transforme em template a instrução que você passa para Claude Code. Colar isso toda vez já evita que ele estenda o escopo por conta própria.

Antes de trabalhar, siga o seguinte.
- Você só pode editar dentro de src/content/ e tests/.
- Não toque em .github/, variáveis de ambiente de produção, config de deploy e migração de banco. Se precisar mexer, não edite: relate o motivo.
- Após mudar, sempre rode `npm run check` e relate o resultado.
- Se precisar apagar, escrever no banco de produção, gerar cobrança ou force push, não execute: peça confirmação.
Antes de editar, repita as restrições acima com suas próprias palavras e só então comece.

E o registro em si. No começo, três linhas bastam. Troque pelos pontos de perigo da sua equipe.

// Registro de riscos da adoção em equipe: uma linha por ponto de perigo, com "responsável, prova e condição para avançar"
type RolloutRisk = {
  area: string;       // área perigosa
  risk: string;       // o que pode acontecer
  owner: string;      // responsável por conferir
  proof: string;      // prova de que está seguro
  nextGate: string;   // condição para poder avançar
};

const rolloutRisks: RolloutRisk[] = [
  {
    area: "Permissão",
    risk: "Claude Code reescreve até a config compartilhada",
    owner: "Líder",
    proof: "lista documentada de pode-editar e proibido-editar",
    nextGate: "testar primeiro só em um arquivo",
  },
  {
    area: "CI",
    risk: "o comando de verificação é lento ou não existe",
    owner: "Dev responsável",
    proof: "build verde, ou só os testes relacionados verdes",
    nextGate: "incluir o passo de verificação no template de PR",
  },
  {
    area: "Publicação",
    risk: "mudança que vai ao ar não foi conferida no real",
    owner: "Responsável de operação",
    proof: "captura de tela da URL pública",
    nextGate: "deixar anotado o procedimento de rollback",
  },
];

console.table(rolloutRisks);

Salve para rodar no node e execute: a tabela é impressa. Não é nada espetacular, mas o valor está em “conseguir colocar em palavras os pontos de perigo antes de começar a trabalhar”. Se a regra for “não dá merge enquanto cada linha não estiver preenchida”, o registro vira o porteiro contra acidentes.

Equipes em que isso funciona (três exemplos reais)

Se houver uma situação parecida, não refaça o registro: só troque os nomes e use.

1. Time pequeno, de duas pessoas Antes de mexer no código compartilhado, as três leem juntas e juntam numa página: onde pode editar, onde não se toca e quais operações exigem aprovação humana. Só isso já apaga o acidente de “um quebra a config sem o outro saber”. Quanto menor o time, mais ele tropeça no “dá para entender mesmo sem falar”, então escrever por escrito no começo vale muito.

2. Time que passa por review O líder torna obrigatório, antes de a mudança feita por Claude Code ir para o review, “o resultado de ter rodado o comando de verificação” e “o resumo das mudanças”. PR sem isso, não olha. A meta é chegar a um estado em que o revisor leia o diff, rode a verificação de novo e saiba explicar como desfazer.

3. Time com página de receita Mudanças em páginas ligadas a dinheiro, como blog e página de produto, ganham uma captura de tela da URL pública antes de virar “concluído”. Não pare em “o build passou”: confira a tela que o usuário de fato vê. Olhe com os olhos se título, corpo, imagem e fluxo estão como o esperado.

Falhas comuns e como corrigir

Vou ser honesto: este registro também não rodou bem de cara. Compartilho três tropeços.

Cada um criou a própria regra No início, deixei a config a cargo de cada pessoa, e o escopo editável ficou diferente por gente. Quem tem a config mais frouxa causa o acidente. A correção é simples: unifiquei a lista de pode-editar e proibido em uma só para a equipe e a coloquei no repositório.

Empurrei as falhas de CI para depois Quando “depois eu junto tudo e conserto” vira bordão, a primeira adoção em equipe termina com a má impressão de “botou Claude Code e quebrou”. Passei a regra: se o comando de verificação cai, para na hora e fica como rascunho até ficar verde.

Deixei o responsável vago e fugi da decisão difícil Sem definir “quem aprova”, a decisão mais difícil — a de subir para produção — fica no ar. Preencha sempre a coluna owner do registro. Não avance com ela em branco. Só isso já fez as decisões pararem de travar.

Quando sentir que o trabalho começou a se espalhar, em vez de reescrever a instrução inteira, aperte nesta ordem: estreite o escopo que pode tocar, peça a verificação antes e defina uma pessoa responsável pela conferência. Também é importante deixar as falhas registradas como aprendizado do time. Quem só olha os casos de sucesso não percebe quando está entrando numa situação perigosa.

Perguntas frequentes

P. Mesmo num time pequeno preciso de registro? Mesmo com duas pessoas, sim. Aliás, quanto menos gente, mais se acidenta acreditando que “dá para entender sem falar”. No começo o template de três linhas basta, então monte em 5 minutos e compartilhe.

P. Só a configuração de permissão de Claude Code não dá conta? A configuração de permissão é o “mecanismo que impede tocar”; o registro é a “regra de operação de quem confere o quê”. Você precisa dos dois. Trave tecnicamente na config e faça a conferência humana girar com o registro. Para detalhes, veja o guia de configuração de permissões.

P. Que comando de verificação devo escolher? O comando mais curto com que a sua equipe consegue dizer “não quebrou”. Pode ser o type-check, rodar só os testes relacionados, ou o build. Se o teste completo leva 10 minutos, ninguém roda, então primeiro escolha um que termine em 30 segundos.

P. Funciona mesmo com gente que não é engenheira no time? Funciona. O registro é só ler a tabela e preencher, então dá para operar mesmo sem saber ler código. Para começar do zero quem não é da área, o guia para quem não é engenheiro ajuda.

P. Onde escrevo as regras específicas do projeto? Escreva no CLAUDE.md do repositório, e Claude Code lê toda vez. Concentrar aqui as áreas proibidas de editar e os comandos de verificação facilita alinhar com o registro. Como escrever está reunido em como escrever o CLAUDE.md. Confira também a documentação oficial de Claude Code da Anthropic como fonte primária.

O que eu confirmei na prática

Depois daquele acidente de deploy do começo, parei de me angustiar com “confio em Claude Code ou não?”. No lugar disso, passei a olhar qual linha do registro está sem preencher.

Quando de fato adotei o registro de três linhas e deixei explícito o arquivo de configuração compartilhado como “área que não se toca”, os merges que quebram a config zeraram. Quando tornei o comando de verificação “obrigatório antes de relatar sucesso”, parei de descobrir quebras só no review, e os retornos de PR caíram visivelmente. E desde que coloquei a conferência por captura de tela nas páginas publicadas, a falha de “o build passou, mas estava saindo outra página” também parou.

Confirmei só estes três pontos. Em vez de procurar o agente mais inteligente, montar primeiro uma operação que se desfaz quando você tropeça. Parece o caminho mais longo, mas na adoção em equipe é o mais rápido — é o que sinto hoje.

Se você está no estágio de levar a sério a adoção de Claude Code na empresa, ou de desenhar as regras de operação em conjunto, em treinamento e consultoria dá para montar junto até o passo a passo concreto. Comece escrevendo três linhas com os pontos de perigo da sua equipe.