Checklist dos primeiros 30 minutos com Claude Code

Os primeiros 30 minutos devem criar confiança, não um patch gigante

A primeira sessão com Claude Code costuma dar errado quando o pedido é amplo demais. A pessoa pede uma feature completa, uma limpeza geral ou um redesenho inteiro e depois não sabe se o diff é seguro. O objetivo correto é menor: entender o repositório, gerar uma pequena vitória verificável, salvar evidência e deixar o próximo passo pronto.

A documentação oficial de Claude Code overview explica que a ferramenta pode ler o codebase, editar arquivos, executar comandos e integrar com ferramentas de desenvolvimento. Esse poder pede limites claros. Na primeira sessão, você não precisa provar que Claude Code consegue fazer tudo. Precisa provar que ele trabalha bem em uma tarefa pequena e revisável.

Este checklist combina com First Task Runbook, Repo Map First Pass, Session Handoff Template e Verification Receipt Workflow. Depois que o fluxo fica estável, ele serve para bugs, testes, conteúdo e onboarding de equipe.

Conceitos para quem está começando

Repositório é a pasta do projeto com código, testes, configuração, scripts e documentação. Agente é o executor que investiga, edita, roda comandos e propõe verificações. Permissões são as regras que dizem o que Claude Code pode ler, alterar ou executar. A documentação oficial de permissions explica regras allow, ask, deny e modos de aprovação.

CLAUDE.md é o guia do projeto. Nele você registra padrões de código, decisões de arquitetura, comandos proibidos, build, testes e critérios de review. O guia oficial de memory ajuda a entender como instruções de projeto e memória tornam as próximas sessões mais consistentes.

Verificação é prova repetível. Pode ser npm run build, teste passando, screenshot, checagem de logs ou uma nota clara sobre o que ainda não foi verificado. Um diff plausível não basta. Antes de editar, defina qual prova conta.

O que deve existir depois de 30 minutos

Resultado	Conteúdo	Por que importa
Mapa do repo	Entradas, diretórios importantes, comandos, áreas de risco	Evita editar no escuro
Pequena vitória	Diagnóstico, link corrigido, teste explicado ou nota de reprodução	Mantém o diff revisável
Nota de verificação	Comandos, resultados e incertezas	Permite repetir a prova
Próximo passo	Menor tarefa útil	Acelera a segunda sessão

Mudanças grandes podem vir depois. A primeira sessão serve para separar entendimento, edição e evidência.

Minutos 0 a 5: peça contexto, não implementação

O primeiro prompt deve ser somente leitura. Ele mostra se Claude Code entende o projeto antes de tocar nos arquivos.

Read this repository and tell me:
1. the main entry points
2. the commands I will probably need
3. the risky directories I should avoid first
4. the safest high-value first task for a 30-minute session

Do not edit files yet. Give me a short plan and the proof command you would run.

Esse prompt força a identificação de entradas, comandos, diretórios de risco e uma primeira tarefa razoável. Os common workflows oficiais seguem o mesmo ritmo: explorar, planejar, implementar e verificar. Os cinco primeiros minutos são para ler.

Minutos 5 a 20: escolha um caso de onboarding

O primeiro caso é explicar um teste falhando. Peça qual teste falhou, qual era o valor esperado, qual foi o valor real e qual arquivo parece relacionado. Não peça a correção ainda. Uma falha bem descrita já é um resultado útil.

O segundo caso é uma pequena atualização de conteúdo ou CTA. Em um site monetizado, isso pode ser confirmar que o link de produto aponta para /products/, que o link de consultoria aponta para /training/ e que o texto explica o próximo passo. O diff é pequeno, mas o valor de negócio é visível.

O terceiro caso é transformar um bug vago em uma nota de reprodução. “O dashboard quebra às vezes” não é uma tarefa boa. Uma primeira sessão útil descreve ambiente, passos, resultado esperado, resultado real, logs e arquivos candidatos.

O quarto caso é criar um CLAUDE.md mínimo. Não escreva um manual completo de equipe. Comece com comandos proibidos, build, testes, estilo e evidência de review. Quando isso virar configuração compartilhada, use a documentação oficial de settings.

Scripts prontos para copiar e rodar

No macOS, Linux ou WSL, rode isto na raiz do repositório. Ele lê estado e não modifica arquivos.

#!/usr/bin/env bash
set -euo pipefail

echo "== location =="
pwd

echo "== git status =="
git status --short

echo "== package scripts =="
if [ -f package.json ]; then
  node -e "const p=require('./package.json'); console.log(p.scripts || {})"
else
  echo "package.json not found"
fi

echo "== likely docs =="
find . -maxdepth 2 \( -name 'README*' -o -name 'CLAUDE.md' -o -name 'AGENTS.md' \) -print

echo "== recent changed files =="
git diff --name-only

No Windows PowerShell, use esta versão.

$ErrorActionPreference = "Stop"

Write-Host "== location =="
Get-Location

Write-Host "== git status =="
git status --short

Write-Host "== package scripts =="
if (Test-Path package.json) {
  node -e "const p=require('./package.json'); console.log(p.scripts || {})"
} else {
  Write-Host "package.json not found"
}

Write-Host "== likely docs =="
Get-ChildItem -Force -File -Include README*,CLAUDE.md,AGENTS.md -Recurse -Depth 2 |
  Select-Object -ExpandProperty FullName

Write-Host "== recent changed files =="
git diff --name-only

Para uma nota de handoff repetível, salve como first-30-handoff.mjs, edite os valores e rode node first-30-handoff.mjs.

const handoff = {
  outcome: "Adjusted one CTA sentence and confirmed the product/training links stayed visible.",
  verified: ["git status --short", "npm run build"],
  notVerified: ["Mobile visual check"],
  nextStep: "Open the page locally and inspect the CTA area at 390px width.",
};

for (const [label, value] of Object.entries(handoff)) {
  const body = Array.isArray(value) ? value.map((item) => `- ${item}`).join("\n") : value;
  console.log(`## ${label}\n${body}\n`);
}

Permissões devem começar de forma conservadora. Este exemplo é JSON válido; ajuste os comandos ao projeto real.

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(npm run build)",
      "Bash(npm test *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

Falhas concretas para evitar

A primeira falha é pedir “corrija tudo”. Isso não tem escopo nem critério de sucesso. Troque por “explique um teste falhando” ou “atualize um bloco CTA e verifique os links”.

A segunda falha é usar permissões amplas em uma árvore de trabalho normal. Modos fortes podem ser úteis em ambientes isolados, mas iniciantes devem começar com leitura, confirmação de edição e regras deny para segredos ou ações destrutivas. Se o projeto tem credenciais ou dados privados, leia a documentação oficial de security.

A terceira falha é não rodar prova nenhuma. Explicação convincente não substitui verificação. Decida antes se a prova será npm run build, testes, parse JSON, inspeção visual ou screenshot.

A quarta falha é terminar sem handoff. Sem registrar o que mudou, o que foi verificado, o que ficou incerto e o próximo passo, a próxima sessão repete a exploração.

Próximo passo e caminho de conversão

Para praticar sozinho, comece pela cheatsheet gratuita e transforme prompts seguros em rotina. Para prompts reutilizáveis, modelos de CLAUDE.md e checklists de review, veja ClaudeCodeLab products. Se sua equipe precisa alinhar permissões, hooks, receipts de verificação e treinamento, use Claude Code training and consultation.

Ao testar este fluxo em um repositório real, o mais útil não foi o script, mas o hábito de pedir um mapa antes de editar e fechar com git status --short. Nota japonesa do artigo: 実際に試した結果, uma primeira tarefa menor deixou o diff mais confiável e a segunda sessão de Claude Code muito mais limpa.