A maioria das pessoas escreve prompts para Claude Code do mesmo jeito que escreve para ChatGPT. Esse é o bug.

ChatGPT é motor de pergunta-resposta. Claude Code é agente. O formato de uma boa pergunta não é o formato de um bom objetivo.

Depois de um ano rodando Claude Code em codebases de produção, reduzi a quatro partes que sempre precisam estar no prompt:

• Objetivo — como o sucesso se parece.
• Restrições — o que não pode mudar.
• Definition of Done — como o agente sabe que terminou.
• Contexto — ponteiros para os arquivos / tickets / erros relevantes.

Pule alguma e você tem deriva. Inclua as quatro e o agente roda em silêncio por 5 minutos e volta com um diff limpo.

O prompt ruim

> Refatore o user service para performance.

Por que falha:

• "Performance" não é definida. Latência? Memória? Throughput?
• Sem restrições — pode reescrever seu schema de DB.
• Sem definition of done — para quando enjoa.
• Sem contexto — precisa adivinhar qual arquivo é "o user service".

Você recebe algo que parece trabalho mas não é.

O prompt bom

> Objetivo: Reduzir latência p95 de GET /api/users/:id de 240 ms para menos de 80 ms.
>
> Restrições:
> - NÃO mudar o formato da API pública.
> - NÃO adicionar dependências novas.
> - Manter código em app/api/users — sem novas camadas.
>
> Definition of Done:
> - Os testes existentes passam.
> - Adicionar um load test (50 chamadas concorrentes × 100 iterações).
> - p95 < 80 ms localmente em Node 20.
> - Adicionar uma descrição de PR de um parágrafo.
>
> Contexto:
> - app/api/users/route.ts é o ponto de entrada.
> - lib/db/users.ts tem a query N+1 lenta.
> - Usamos Postgres 15 e drizzle ORM.

Mesma tarefa. Resultado diferente. O agente vai:

1. Ler os dois arquivos.
2. Identificar o N+1.
3. Escrever o fix com uma única query batched.
4. Adicionar o load test.
5. Rodar o teste, confirmar o número.
6. Devolver um diff com descrição de PR.

Isso é delegação, não autocomplete.

Por que cada parte importa

Objetivo

Escreva como resultado, não como ação. "Reduzir p95 para 80 ms" é resultado. "Refatorar chamadas à DB" é ação — e um agente fraco vai executar a ação sem atingir o resultado.

Restrições

Restrições são o que te surpreenderia. Se um júnior reescrevendo aquele arquivo te surpreenderia mudando o formato da API, escreva isso. Se te surpreenderia adicionando Redis, escreva isso.

A maioria das histórias "Claude Code fez algo estranho" é restrição faltando, não inteligência faltando.

Definition of Done

A parte mais subutilizada de qualquer prompt. Sem ela, o agente para quando acha que a tarefa terminou — geralmente depois de escrever código, antes de rodar os testes.

DoDs boas são testáveis:

• "Os testes existentes passam."
• "O novo endpoint retorna 201 e um header Location válido."
• "lighthouse-ci não mostra regressão na home."

Se você não consegue escrever uma DoD, a tarefa não está pronta para delegar.

Contexto

Não precisa colar arquivos. Ponteiros bastam:

• app/api/users/route.ts — ponto de entrada.
• tests/api/users.test.ts — testes existentes.
• "Vimos a regressão no PR #842."

Claude Code sabe ler e buscar. Só precisa que você aponte o bairro certo.

O template 80/20 que guardo em .claude/commands/

# /goal — cole esse template, preencha os espaços

Objetivo: <resultado com número se possível>

Restrições:
- <coisa que não pode mudar>
- <regra de dependência>
- <regra de estilo ou arquitetura>

Definition of Done:
- <comando de teste que passa>
- <checagem de performance ou correção>
- <descrição de PR em 1 parágrafo>

Contexto:
- <arquivo ou pasta>
- <ticket / erro / log relacionado>

Aliasar isso como slash command faz com que um prompt novo de feature leve 90 segundos. Vamos ver slash commands a fundo no artigo 4.

Anti-padrões para abandonar hoje

• "Deixa mais limpo." Mais limpo por qual métrica? Escolha: linhas de código, complexidade ciclomática ou uma regra de lint específica.
• "Conserta o bug." Qual bug? Qual o comportamento esperado? E o atual?
• "Refatora por legibilidade." Legibilidade é gosto. Escolha um padrão concreto: "extrair para funções puras", "trocar ifs aninhados por early returns".

Prompts vagos produzem código vago. O agente é espelho.

Último truque: o "exemplo negativo"

Às vezes o jeito mais limpo de restringir um agente é mostrar o que não fazer.

> NÃO adicione uma nova camada de abstração.
> A tentativa anterior adicionou uma classe UserRepository — removemos.
> O fix deve ter ~20 linhas em lib/db/users.ts, não 200.

Brutalmente eficaz. Você antecipa o modo de falha mais comum de um agente afobado: construir um reino quando uma única função bastava.

---

Próximo artigo: Slash commands — como transformar o template acima num comando /feature de uma tecla só, e como encadear /init, /agents, /compact para construir um esqueleto de projeto completo numa sessão.