Runbook da primeira tarefa no Claude Code: prompts seguros, diff e revisão antes do commit

A primeira tarefa decide se Claude Code parece seguro

Logo depois de instalar o Claude Code, dá vontade de pedir uma funcionalidade inteira, um grande refactor ou “corrija este repositório todo”. É aí que muitas primeiras sessões falham. Normalmente o problema não é falta de capacidade do Claude Code, mas ausência de acordo sobre escopo, verificação, permissões e contexto do projeto.

Este runbook é para a primeira tarefa prática em um repositório real. Um runbook é uma checklist operacional reutilizável. Aqui, a primeira tarefa não é “construa a funcionalidade”. É um fluxo pequeno: pedir com clareza, confirmar o plano, fazer uma mudança limitada, revisar o diff e deixar uma nota de handoff.

Se o básico ainda é novo para você, comece pelo guia inicial de Claude Code. Quando quiser registrar regras do projeto, combine com os templates de CLAUDE.md para Claude Code. Como referências oficiais, use Claude Code overview, memory e CLAUDE.md, permission modes, common workflows e a CLI reference.

flowchart LR
  A["Ler o repositório"] --> B["Listar 3 opções seguras"]
  B --> C["Escolher 1 tarefa"]
  C --> D["Revisar o plano primeiro"]
  D --> E["Criar o menor diff"]
  E --> F["Verificar testes e diff"]
  F --> G["Escrever nota de handoff"]

O que torna uma primeira tarefa boa

A primeira tarefa não é medida pelo tamanho do resultado. Ela mostra se o fluxo pode continuar confiável. As melhores tarefas iniciais têm cinco características.

Característica	Significado simples	Bom exemplo
Local	Sem produção, dados de clientes ou efeitos externos	Verificar comandos do README ou adicionar uma assertion
Limitada	Arquivos e ponto de parada são visíveis	Um componente, um teste, um documento
Verificável	Um comando, página ou diff prova o sucesso	npm.cmd run test, git diff --check
Reversível	Um resultado ruim pode ser descartado rápido	Arquivos fonte comuns, não exports gerados
Explicável	Uma pessoa entende por que a mudança existe	Razão, risco e incerteza ficam escritos

Pedidos como “refaça a autenticação”, “modernize todo o código” ou “corrija CI e faça deploy” são péssimas primeiras tarefas. Eles misturam contexto ausente, prompts de permissão, testes fracos e diffs difíceis de revisar.

Menu de tarefas seguras

Para onboarding de equipe, escolha deste menu antes de inventar uma tarefa.

Tarefa	Por que ajuda	Condição de sucesso
Mapear o repositório	Testa entendimento antes de editar	Entry points, comandos e áreas de risco são identificados
Resumir um teste falhando	Mostra granularidade de debug	Ponto de falha, hipótese e menor próximo passo ficam claros
Corrigir um comando antigo do README	Testa uma edição real de baixo risco	O comando roda e o diff fica pequeno
Adicionar uma assertion a um teste existente	Avalia intenção e julgamento de teste	A assertion protege um comportamento claro
Alterar uma frase de UI	Verifica busca e edição mínima	Só o componente alvo muda
Corrigir um aviso de lint	Mede disciplina de mudança local	Um aviso desaparece sem mudar comportamento
Criar um CLAUDE.md mínimo	Melhora sessões futuras	Comandos, limites e revisão estão escritos de forma curta

O ponto é “pequeno, mas real”. A tarefa deve se conectar a onboarding, diagnóstico de bug, documentação, testes ou qualidade de revisão.

Prompts prontos para copiar

Comece pedindo para Claude Code ler e propor, não editar.

Leia este repositório e ainda não edite.

Retorne:
1. principais entry points
2. comandos comuns de build/test/lint
3. diretórios arriscados ou arquivos gerados
4. 3 opções seguras para uma primeira tarefa de 30 minutos
5. como verificar e reverter cada opção

Depois das opções, escolha uma e exija um plano.

Siga apenas com a opção 2. Ainda não edite.
Primeiro escreva os arquivos que você tocaria, o motivo da mudança, o diff esperado,
o comando de verificação e os riscos. Se o escopo crescer, proponha uma opção menor.

Só então autorize a edição.

Siga o plano aprovado e faça o menor diff possível.
Não toque arquivos fora do pedido.
Depois de editar, resuma comandos de verificação executados, checks que falharam ou foram pulados
e riscos restantes.

Use outro prompt para revisão antes do commit.

Faça uma revisão antes do commit.

1. Leia git diff e procure mudanças fora do pedido
2. Encontre testes ausentes ou verificação fraca
3. Revise riscos de segurança, perda de dados e configuração
4. Encontre arquivos que não deveriam ser commitados
5. Identifique decisões que ainda exigem uma pessoa

Termine com exatamente um veredito: "pronto para commit", "corrigir antes" ou "parar".

Fluxo de 30 minutos

Use os primeiros cinco minutos para congelar o estado atual antes de delegar. No Windows PowerShell:

Get-Location
git status --short
git branch --show-current
rg --files | Select-Object -First 40

No macOS ou Linux:

pwd
git status --short
git branch --show-current
rg --files | head -n 40

Se o worktree já estiver sujo, diga quais mudanças são humanas e não devem ser tocadas. Caso contrário, o diff final fica difícil de julgar.

Use os próximos dez minutos para escolher uma tarefa. Boas opções são um comando antigo do README, uma assertion em teste ou o resumo de um teste falhando. Evite funcionalidades novas na primeira sessão.

Por volta do minuto vinte, priorize prova em vez de mais edições. Uma mudança correta e explicada vale mais do que três mudanças sem verificação.

git diff --stat
git diff --check
git diff
git status --short

Reserve os últimos cinco minutos para uma nota de handoff. É uma nota curta para a próxima pessoa ou próxima sessão do Claude Code. Ela importa porque conversas longas podem perder limites, e a sessão seguinte precisa de um ponto limpo de partida.

Quatro casos de uso concretos

Caso 1: onboarding de novo desenvolvedor

Não entregue uma issue grande no primeiro dia. Peça ao Claude Code um mapa do repo, comandos principais, diretórios perigosos e primeiros arquivos para ler.

Prompt: “Crie uma nota de onboarding para uma pessoa nova. Separe fatos de suposições. Inclua saída de comandos quando puder.” Sucesso significa que a nota adiciona contexto prático além do README, como arquivos gerados, settings locais ou diferenças entre CI e local.

Caso 2: nota de reprodução para bug visível

Se o bug é “às vezes quebra”, não comece pelo fix. Peça condições, resultado esperado, resultado real, arquivos relevantes e logs faltantes. Isso combina bem com o template de bug report do Claude Code.

Sucesso não é um patch. Sucesso é uma nota que uma pessoa consegue verificar. Se o bug não reproduz, a saída deve dizer isso e listar os próximos logs ou dados necessários.

Caso 3: documentação ou texto de UI

Sites de marketing, ferramentas admin e dashboards internos costumam funcionar bem na primeira sessão porque uma mudança de texto é visível e reversível. Mantenha estreito: um CTA, uma explicação de settings ou um parágrafo.

Sucesso significa que apenas os arquivos alvo mudaram, o significado foi preservado e o resultado pode ser revisado localmente. Em sites multilíngues, confira também se você não atualizou só um idioma deixando os outros inconsistentes.

Caso 4: pequena melhoria de teste

Se o projeto já tem testes, adicionar uma assertion é mais seguro do que adicionar uma funcionalidade. Inclua um caso de borda, uma expectativa de mensagem de erro ou um caso de lista vazia.

Testes verdes não bastam. Claude Code deve explicar qual comportamento a assertion protege. Uma assertion que não pode ser explicada vira ruído de manutenção.

Revisão de diff antes do commit

Depois que Claude Code editar, volte para revisão humana. Na primeira tarefa, evite commits e pushes automáticos. Permission modes trocam conveniência por supervisão, então comece com revisão normal ou plan mode. Evite modos fortes como bypass permissions, exceto em ambientes isolados.

Checklist antes do commit

[ ] Só arquivos pedidos mudaram
[ ] Nenhum gerado, segredo ou setting local entrou
[ ] Um teste ou verificação substituta foi registrado
[ ] Checks que falharam ou foram pulados foram declarados
[ ] Não resta diff inexplicado
[ ] A nota de handoff contém o próximo TODO

Comece com git diff --stat para ver a extensão. Rode git diff --check para whitespace e higiene do patch. Depois leia o diff procurando refactors surpresa, renomeações ou mudanças de comportamento sem testes.

Falhas comuns

A primeira falha é escopo grande demais. Diga “verifique a mensagem de erro de login com um teste”, não “corrija login”. Dê autonomia depois que houver confiança em tarefas pequenas.

A segunda falha é aceitar “pronto” sem prova. Se não há testes, defina uma prova substituta: página renderizada, type check, git diff --check, comparação de logs ou comando do README.

A terceira falha é aprovar prompts de permissão sem atenção. Quando aparecer um prompt, pergunte qual comando roda, quais paths toca e se inclui rede ou exclusão. Se os prompts incomodam, aprove comandos estreitos em vez de abrir tudo.

A quarta falha é perda de contexto. Conversas longas desfocam o limite inicial. Guarde limite, comandos executados e risco restante na nota de handoff. Não misture regras permanentes de CLAUDE.md com notas de uma sessão.

A quinta falha é danificar trabalho não commitado. Em repos compartilhados, outra pessoa ou agente pode já ter mudanças. Comece com git status --short e proteja explicitamente mudanças não relacionadas.

Template de handoff

Cole isto no fim da primeira tarefa.

## Handoff note

- Task:
- Changed files:
- Verification run:
- Verification not run:
- Important diff points:
- Remaining risks:
- Do not touch next time:
- Suggested next smallest task:

Essa nota é mais ampla que uma mensagem de commit. Antes do commit, vira material para descrição de PR. Sem commit, vira o ponto de partida da próxima sessão.

Próximos passos e caminhos pagos

Depois que a primeira tarefa der certo, construa repetibilidade. Quem trabalha sozinho deve transformar regras recorrentes em templates de CLAUDE.md. Se approvals e sandbox ainda não estão claros, leia o guia de approval e sandbox do Claude Code.

Para templates, checklists e material de onboarding prontos para usar, veja /products/. Para rollout em equipe, onboarding específico do repositório, desenho de permissões e workflows de revisão, use /training/. Uma primeira tarefa segura pode ser resolvida com este artigo. Um rollout de equipe precisa de regras, evidências e treinamento antes de ampliar o uso.

No teste real de Masa, o padrão mais estável foi: ler o repo primeiro, editar apenas um arquivo, revisar git diff em conjunto e deixar uma nota de handoff. Sessões que começaram com um pedido grande criaram mais trabalho de revisão do que economizaram. Sessões que venceram uma tarefa de 30 minutos tornaram a segunda tarefa mais fácil de delimitar e explicar para a equipe.