Como escrever o pedido da primeira tarefa para o Claude Code

“Esse repositório aqui, dá um jeito de ajeitar o README pra mim.”

Trinta minutos depois de instalar, esse foi o primeiro pedido que mandei para o Claude Code. O que voltou: eu queria só o README, mas o diff também tinha reescrito o nome dos scripts no package.json. Funcionava, sim, mas três arquivos mudaram em lugares que não eram o que eu queria corrigir. Fiquei travado na frente da tela pensando: “Isso aqui eu posso publicar?”.

Por que o Claude Code, que é esperto, mexe em lugares que ninguém pediu? Não é problema de capacidade. É que eu não tinha definido uma única vez “até onde ele pode ir”. É como dizer para o novato “cuida da loja aí” e sair: você volta e ele reorganizou as prateleiras inteiras.

Este artigo é sobre escrever esse “até onde” em uma folha só. Eu chamo isso de pedido da primeira tarefa.

Pontos principais

• A primeira tarefa dá errado porque você pede “dá um jeito” sem definir objetivo, escopo permitido, verificação e como reverter.
• O pedido tem 9 campos: objetivo / estado do leitor / pode ler / pode editar / pode executar / não tocar / verificação / como reverter / próximo passo.
• Ao Claude Code você delega “ler, corrigir, rodar o comando de verificação”. Deletar, subir para produção e gastar dinheiro são decisões humanas.
• Tem um template de pedido para copiar e colar, e um script em JavaScript que checa automaticamente se faltou algum campo.
• Comece por uma única tarefa pequena que dá para reverter com git se falhar — é o caminho mais curto para a primeira vitória.

Por que a primeira tarefa dá errado

Logo depois de instalar o Claude Code, a maioria das pessoas faz “o pedido amplo”: “organiza o repositório”, “conserta o README”. É compreensível — você quer testar o que ele consegue fazer.

Mas, com um pedido amplo, os primeiros dez minutos viram exploração. O Claude Code lê arquivos espalhados, conserta por conta própria o que parece relacionado e termina com um relatório vago do tipo “deve funcionar”. Você acaba tendo que reler o diff inteiro e conclui: “teria sido mais rápido fazer eu mesmo”.

A causa não é a inteligência do modelo. É não ter entregado o objetivo e os limites. Até um novato humano, no primeiro dia, se você disser “fica à vontade”, ou trava ou descontrola. Definir os limites primeiro faz esse acidente quase desaparecer.

Se você ainda tem insegurança com o básico da operação, dê uma olhada no Guia de primeiros passos do Claude Code antes de voltar — aí esta conversa sobre o pedido entra muito mais fácil.

Os 9 campos que entram no pedido

Toda vez eu escrevo estes 9 campos em uma folha. Não precisa de palavra difícil. Basta preencher uma resposta por linha.

Campo	O que escrever	Exemplo ruim → bom
Objetivo	Como fica “pronto e certo” no fim	”Corrigir o README” → “Alinhar os passos do README ao package.json”
Estado do leitor	Para quem é o trabalho	(em branco) → “Iniciante, quer acertar de primeira uma vez”
Pode ler	Arquivos que ele pode consultar	(tudo) → “Só README.md e package.json”
Pode editar	Arquivos que ele pode reescrever	(tudo) → “Só README.md”
Pode executar	Comandos que ele pode rodar	(qualquer um) → “Só npm run build”
Não tocar	Lugares que jamais pode mudar	(não dito) → “package-lock, config de deploy, preços”
Verificação	A prova de que deu certo	”Funcionou, ok” → “build passa / diff só no README”
Como reverter	Como voltar ao estado anterior se falhar	(nenhuma) → “Restaurar o README pelo git”
Próximo passo	Um único caminho para o leitor seguir	(lista 3) → “Primeiro só o material introdutório grátis”

O importante são “não tocar”, “verificação” e “como reverter”. No momento em que você escreve esses três, o pedido deixa de ser “um favor” e vira “um trabalho que dá para delegar com segurança”.

Template de pedido para copiar e colar

Este é o modelo que dá para usar direto. Está dentro de um bloco de código de propósito, para você colar e entregar inteiro ao Claude Code. Troque pelo nome do seu repositório e pelo lugar que quer corrigir.

# Pedido da primeira tarefa

Objetivo: alinhar os passos de setup do README ao conteúdo do package.json.
Estado do leitor: iniciante. Quer acertar de primeira, uma vez só.
Pode ler:
- README.md
- package.json
Pode editar:
- só README.md
Pode executar:
- npm run build
Não tocar:
- package-lock.json
- config de deploy (variáveis de ambiente, configuração de publicação)
- preços ou links de inscrição
Verificação:
- npm run build passa
- git diff mostra mudança só em README.md
Como reverter:
- se a verificação falhar, restaurar README.md pelo git
Próximo passo:
- por enquanto, indicar só o material introdutório grátis

Num exemplo real: se for só alinhar os passos do README ao package.json, ele lê o README e o package.json, edita só o README, e a prova é npm run build. Nessa granularidade, se falhar você reverte com um único git checkout -- README.md. A primeira tarefa pode ser estreita assim mesmo. Aliás, quanto mais estreita, mais você mesmo consegue julgar se deu certo ou não.

O que delegar ao Claude Code e o que você decide

Quando escrevo o pedido, traço esta linha na cabeça. Se o limite fica vago, o Claude Code atravessa a linha “achando que está ajudando”.

Pode delegar ao Claude Code	Você decide (não automatize)
Ler os arquivos indicados	Decidir quais arquivos ele pode tocar
Corrigir só os arquivos indicados	Deletar arquivos
Rodar comandos de verificação como npm run build	Subir para produção / fazer deploy
Devolver um resumo do diff	Operações que geram cobrança
Relatar a causa de uma falha	Operações irreversíveis como git push --force

O lado esquerdo você delega. O lado direito, no começo, deixe tudo como “confirmar com a pessoa antes de executar”. Só depois mova para o lado automático as operações que você já sabe que são seguras, aos poucos. Só de seguir essa ordem, o número de sustos no meio da madrugada despenca.

Na hora de entregar o pedido, acrescente uma frase assim.

Execute apenas uma tarefa pequena, dentro do escopo deste pedido.
O que você julgar fora do escopo, não execute: apenas proponha.

Primeiro, devolva estes 5 itens:
1. arquivos que vai ler
2. arquivos que vai editar
3. comandos de verificação antes e depois do trabalho
4. resumo do diff das mudanças
5. como reverter se falhar

O segredo é pedir “devolva o plano e a verificação antes de implementar”. Se o plano que voltar ultrapassar o escopo do pedido, você consegue parar ali mesmo. Parar antes de ele colocar a mão na massa significa zero faxina depois.

Código que checa falhas no pedido automaticamente

Mesmo achando que escreveu tudo, é comum faltar um campo. Eu deixo a máquina conferir a presença de cada item. É um JavaScript que roda copiando e colando. Dá para executar com Node.js, tipo node check-brief.mjs.

// Confere mecanicamente se o pedido tem todos os campos necessários
const requiredFields = [
  "Objetivo",
  "Pode ler",
  "Pode editar",
  "Pode executar",
  "Não tocar",
  "Verificação",
  "Como reverter",
  "Próximo passo",
];

export function validateFirstTaskBrief(markdown) {
  // Lista os campos que estão faltando
  const missing = requiredFields.filter((field) => !markdown.includes(field));

  // Verifica também se o comando de prova (aqui, npm run build) está escrito
  const hasProofCommand = markdown.includes("npm run build");

  return {
    ok: missing.length === 0,
    missing,
    readyForClaudeCode: missing.length === 0 && hasProofCommand,
  };
}

// Exemplo de execução
const sample = `
Objetivo: alinhar o README ao package.json
Pode ler: README.md
Pode editar: README.md
Pode executar: npm run build
Não tocar: package-lock.json
Verificação: npm run build passa
Como reverter: restaurar README.md pelo git
Próximo passo: material introdutório grátis
`;

const result = validateFirstTaskBrief(sample);
console.log(result);
// → { ok: true, missing: [], readyForClaudeCode: true }

Se você passar o pedido por essa checagem antes de entregar, o esquecimento de “não tocar” e “como reverter” some. Quando se confia só no olho humano, num dia corrido sempre escapa algo. O que a máquina consegue conferir, é mais cômodo deixar com a máquina.

Casos em que isso funciona (3 exemplos)

1. Corrigir README ou documentação de procedimentos “Atualiza a documentação” tem escopo infinito. “Só o capítulo de setup do README, alinhado aos nomes dos scripts do package.json” reduz o diff a um arquivo só e dá para conferir com npm run build. É o que mais combina com a primeira tarefa.

2. Primeira revisão de um pull request Em vez de “dá uma olhada nesse PR”, peça: “leia só o que está dentro de src/ entre os arquivos alterados e aponte onde os testes podem quebrar. Não corrija o código, só aponte”. Delegue a leitura, mas deixe a decisão de corrigir com a pessoa. Isso evita o acidente de “corrigir por conta própria e criar outro bug”.

3. Trocar a CTA (o link para o próximo passo do leitor) Mesmo para trocar um único botão no fim de um artigo popular, “acha o componente relacionado e conserta” é amplo demais. Defina antes no pedido: “arquivos que pode tocar”, “URL pública a conferir”, “link a trocar”. A conferência depois muda de “parece bom mais ou menos” para “com essa prova, dá para publicar”.

Três erros que eu mesmo cometi

Vou ser sincero. Antes de usar o pedido, eu repetia os mesmos erros.

O primeiro foi não escrever “não tocar”. Eu queria só o README corrigido, mas o Claude Code, por gentileza, ajeitou até o package.json, e o build parou de passar. Bastou adicionar as 3 linhas de Não tocar: package-lock.json, config de deploy e isso nunca mais aconteceu.

O segundo foi resolver a verificação com “se funcionar, ok”. Como eu não tinha definido o que significa “funcionar”, toda vez percorria o diff inteiro com o olho. Quando passei para um comando concreto, Verificação: npm run build passa / diff só no README, a conferência passou a levar 10 segundos.

O terceiro foi listar três próximos passos. Quando colei no fim do artigo material, curso e consultoria de uma vez, a reação do leitor virou névoa. Quando reduzi a um só, conforme o estado do leitor, no fim aquele um é que recebia clique de verdade. O que deve estar escrito vale a pena registrar como regra do projeto em Como escrever um bom CLAUDE.md, para não oscilar a cada vez.

Perguntas frequentes

P. Não é trabalhoso escrever os 9 campos toda vez? Só nas primeiras vezes. Faça um template e guarde como first-task-brief.md: a partir daí, basta trocar 3 ou 4 linhas do conteúdo. O tempo de escrever é muito menor do que o de reler um diff descontrolado.

P. Preciso do pedido até para tarefas simples? Para algo do nível “corrigir um erro de digitação em um arquivo”, um pedido verbal já basta. O pedido vale quando o trabalho pode tocar vários arquivos, ou quando passa perto de produção, cobrança ou exclusão. Na dúvida, escreva — não custa nada.

P. Devo escrever as chaves em inglês (Goal, May edit etc.)? Se a equipe compara logs lado a lado, chaves em inglês ficam alinhadas e ajudam. Para uso individual, português basta. O Claude Code entende as duas formas. O que importa não é o idioma, e sim não faltar nenhum campo.

P. Quem não programa também consegue usar? Consegue. Em redação de artigos e organização de materiais, a ideia de “pode ler / pode editar / não tocar” é a mesma. Montei a porta de entrada para quem não é engenheiro em Claude Code para quem não é engenheiro.

P. E se o Claude Code ignorar o pedido e tocar fora do escopo? Primeiro, peça “devolva o plano e a verificação antes de tudo” e pare antes de ele agir — esse é o básico. Se mesmo assim ele ultrapassar, é bem provável que o “não tocar” do seu pedido não esteja concreto. Especificar até o nome da pasta e do arquivo costuma resolver.

O que aconteceu quando testei na prática

O caso mais claro foi testar este pedido naquele trabalho pequeno de alinhar o README ao package.json. Como eu escrevia antes Pode editar: só README.md, o impulso do Claude Code de estender a mão para o package-lock ou arquivos de config parava já na etapa do plano, antes da execução. O ganho grande foi ter eliminado o trabalho de reler o diff.

Colocar dois itens na Verificação, npm run build e git diff, também funcionou. O julgamento depois do trabalho deixou de ser “no clima, parece bom” e virou uma afirmação: “build verde, diff só no README, então dá para publicar”. Por outro lado, na vez em que deixei o Próximo passo em branco, eu mesmo fiquei na dúvida — “o que mesmo eu indico agora?” — e o link no fim do artigo ficou borrado.

No fim, o que eu entendi é que dar muita liberdade ao Claude Code não é o que tem valor. Cortar a primeira tarefa em algo pequeno e deixar sucesso, falha e próxima ação visíveis aos seus próprios olhos — isso é o mais rápido. A chatice de escrever uma folha de limites é quase nada perto da chatice de reler depois um diff descontrolado.

Quem quer afinar mais a engrenagem de fora encontra o comportamento das configurações de permissão na documentação oficial do Claude Code da Anthropic — ali fica claro como o pedido e as configurações dividem o papel. Se você quer levar o Claude Code para o trabalho da empresa e ajustar as regras de operação junto, na trilha de treinamento e consultoria dá para começar pela montagem do tipo de pedido sob medida para o seu trabalho real.