Prompts para Claude Code/Codex: 5 padrões práticos para iniciantes

Comece por aqui: um bom prompt é um briefing de trabalho claro

Quando Claude Code ou Codex entrega um resultado confuso, o problema muitas vezes não é que o agente “não sabe programar”. O prompt não deu limites de trabalho suficientes. Um prompt não é uma frase mágica. É um briefing para um agente de programação: o que mudar, o que não tocar, o que conta como pronto, que prova de verificação coletar e o que a próxima pessoa precisa saber.

Este guia para iniciantes transforma essa ideia em 5 padrões práticos: escopo, contexto do repositório, critérios de aceitação, evidência de verificação e handoff. Eles servem para corrigir bugs, adicionar pequenas features, gerar artigos, auditar repositórios e revisar código. O objetivo não é escrever bonito para a IA. O objetivo é reduzir suposições.

Como os produtos mudam, mantenha os links oficiais perto. Comece por Claude Code overview, Claude Code memory e Claude Code settings. Para Codex e fluxos de código com OpenAI, use o OpenAI code generation guide. Se você ainda está começando com a ferramenta, leia também o guia inicial de Claude Code e as boas práticas de CLAUDE.md.

Os 5 padrões

Padrão	Significado simples	O que acontece se faltar
Escopo	O limite da tarefa	O agente mexe em arquivos sem relação
Contexto do repo	Regras e exemplos existentes	A saída não segue o estilo local
Critérios de aceitação	Definição de pronto	“Pronto” significa coisas diferentes
Evidência de verificação	Prova de que algo foi checado	O trabalho termina em “implementei”
Handoff	Nota curta para a próxima sessão	Ninguém entende depois por que aquilo mudou

Critérios de aceitação são as condições concretas que a mudança precisa cumprir para ser aceita. Evidência de verificação é o recibo: comandos executados, telas conferidas, testes manuais ou pontos que não foram verificados. Handoff é a nota que permite que você amanhã, uma pessoa do time ou outro agente continue sem reler toda a conversa.

Padrão 1: defina um escopo pequeno

Um prompt fraco começa amplo demais.

Melhore este app e deixe tudo melhor.

Esse prompt não diz se o agente pode tocar UI, API, testes, texto, schema do banco, dependências ou deploy. Claude Code e Codex conseguem inferir, mas cada inferência aumenta o risco.

Use assim:

Edite somente site/src/content/blog-pt/5-tips-for-better-prompts.mdx.
Objetivo: tornar o artigo mais prático para iniciantes em Claude Code/Codex.

Permitido:
- title, description, updatedDate e tags no frontmatter
- corpo do artigo

Não mudar:
- heroImage
- slug
- outros artigos
- configuração de build

Isso é essencial em sites monetizados. Um rewrite amplo pode remover links internos, CTAs de produto ou atributos de analytics sem querer. Um escopo claro dá espaço para o agente trabalhar sem transformar uma atualização de artigo em refatoração geral.

Para tarefas de investigação, deixe o limite ainda mais claro:

Leia os arquivos relacionados e proponha apenas um plano. Não edite ainda.
Liste os arquivos que mudaria, o motivo e o comando de verificação para cada mudança.

O erro comum é dizer “só dá uma olhada” enquanto permite edição. Quando o repositório é desconhecido, separe descoberta e implementação.

Padrão 2: entregue contexto do repositório

Claude Code/Codex consegue ler arquivos, mas não conhece automaticamente sua prioridade de negócio, decisões de estilo ou erros anteriores. Contexto do repositório explica como esse projeto funciona.

Este site usa Astro content collections para artigos MDX localizados.
Use site/src/content/blog-pt/claude-code-productivity-tips.mdx como referência de qualidade.

Contexto do projeto:
- Artigos devem ser tutoriais evergreen práticos, não resumos finos de IA.
- Incluir 3 ou mais casos de uso concretos.
- Incluir links oficiais externos e links internos.
- Preservar o caminho de conversão: /pt/thanks/, /en/products/, /en/training/.
- Manter frontmatter válido.

Sem esse contexto, você pode receber um artigo bem escrito, mas que não combina com ClaudeCodeLab. Aqui o leitor precisa de prompts copiáveis, exemplos de falha, hábitos de verificação e um próximo passo natural para cheatsheet, produtos ou training.

Se você repete o mesmo contexto sempre, coloque a parte estável em CLAUDE.md. As dicas de produtividade com Claude Code mostram como regras de projeto, comandos seguros e verificação reduzem explicações repetidas.

Padrão 3: escreva critérios de aceitação antes de começar

Critérios de aceitação evitam o ciclo “melhore mais”. Um prompt fraco seria:

Deixe este artigo mais legível e melhor para SEO.

Legibilidade e SEO são importantes, mas desse jeito não são verificáveis o suficiente. Divida em condições:

Critérios de aceitação:
- Somente o arquivo alvo é alterado.
- A description tem 120 caracteres ou menos.
- Cada um dos 5 padrões tem exemplo de prompt Before/After.
- Há templates para bugfix, nova feature e geração de artigo.
- Há falhas concretas e formas de evitá-las.
- Há links oficiais, links internos e CTA clara.
- No final, são reportados verificação e riscos restantes.

Para uma feature, os critérios devem ser mais técnicos:

Critérios de aceitação:
- O layout UI existente é preservado.
- Não há erros de TypeScript.
- Validação e estados de erro visíveis são adicionados.
- Pelo menos um teste relevante é adicionado ou atualizado.
- O resultado de npm test e npm run build é reportado.

Cada item precisa ser checável. Se o agente não consegue provar, ele deve dizer que não verificou em vez de fingir que passou.

Padrão 4: peça evidência de verificação

“Implementei” não basta. Peça um verification receipt.

No final, devolva um verification receipt:

- Arquivos alterados:
- Comandos executados:
- Resultados:
- Verificações manuais:
- Não verificado:
- Riscos restantes:

Esse hábito pega muitos erros de iniciante. Ele também força clareza quando um comando não roda porque faltam dependências, a suíte de testes é lenta demais ou um serviço local não está disponível. A partir daí você decide se o risco é aceitável.

Não resuma demais os erros. Isto é fraco:

O build falhou. Corrija.

Isto é útil:

Comando:
npm run build

Erro:
Type error: Property 'name' does not exist on type 'User | undefined'.
File: src/components/Profile.tsx:15:22

Pedido:
Explique a causa provável, faça a menor correção segura e rode npm run build de novo.

Para um fluxo mais completo, leia o guia de verification receipt. O formato pode variar, mas o princípio é o mesmo: não encerre sem prova.

Padrão 5: solicite uma nota de handoff

Trabalho com agente muitas vezes passa de uma sessão. Uma nota de handoff evita redescobrir tudo depois.

No final, escreva uma handoff note com:
- Objetivo
- O que mudou
- O que não mudou
- Resultados de verificação
- Arquivos para olhar em seguida
- Riscos ou decisões abertas

Isso ajuda em artigos, SEO, fluxos de checkout e repositórios de time. Um diff mostra o que mudou, mas raramente explica por que uma CTA foi colocada em certa seção ou por que uma correção pequena foi escolhida em vez de um refactor maior.

Para equipes, combine isso com regras de handoff para Claude Code. Um formato constante torna sessões com IA mais fáceis de revisar.

Templates copiáveis

Template de bugfix

Objetivo:
  Corrigir o bug com o menor diff seguro.

Sintoma:
  O que acontece:
  Comportamento esperado:
  Comportamento real:

Passos para reproduzir:
  1.
  2.
  3.

Escopo:
  Arquivos que pode editar:
  Arquivos que não deve editar:

Contexto do repositório:
  Implementação parecida para seguir:
  Regras locais a preservar:

Critérios de aceitação:
  Explicar causas prováveis antes de editar.
  Corrigir a causa raiz, não só esconder o sintoma.
  Adicionar ou atualizar teste relevante quando viável.
  Devolver evidência de verificação e risco restante.

Template de nova feature

Objetivo:
  Adicionar uma pequena feature com segurança.

Feature:
  Mudança visível para o usuário:
  Mudanças em API/banco/config:

Restrições:
  Preservar o estilo UI existente.
  Seguir padrões atuais de nomes e arquivos.
  Se for necessária uma mudança de design maior, explicar antes de implementar.

Critérios de aceitação:
  Incluir implementação, tipos, estados de erro, testes e verification receipt.

Template de artigo

Objetivo:
  Melhorar isto como artigo evergreen para iniciantes.

Leitor:
  Dev solo ou pequeno time começando com Claude Code/Codex.

Elementos obrigatórios:
  3 ou mais casos de uso concretos.
  Exemplos de prompt Before/After.
  Falhas específicas e correções.
  Templates copiáveis.
  Links oficiais, links internos e CTA.

Critérios de aceitação:
  Description com 120 caracteres ou menos.
  Frontmatter válido.
  Code fences balanceados.
  Finalizar com uma autoavaliação curta.

Três casos de uso práticos

O primeiro caso é tela branca depois do login. Não diga apenas “corrija o dashboard”. Entregue passos de reprodução, resultado esperado, erro real no console, arquivos editáveis e comandos de verificação. Assim o agente procura a causa raiz em vez de só esconder o sintoma.

O segundo caso é adicionar um campo “tipo de consulta” em um formulário de lead. Um bom prompt nomeia opções como training, consulting e other, regra de validação, contrato da API, evento de analytics e expectativa de teste. Isso protege o caminho de monetização e mantém o diff pequeno.

O terceiro caso é geração de artigo. Para ClaudeCodeLab, o prompt deve especificar profundidade, exemplos concretos, falhas, links oficiais, links internos, CTA e o parágrafo final sobre o resultado real de testar o fluxo. Assim você evita um resumo genérico de IA e cria algo útil para iniciantes.

Rubrica rápida de QA para prompts

Antes de enviar, dê uma nota de 0 a 10.

Pontos	Área	Pergunta
0-2	Escopo	Arquivos editáveis e protegidos estão claros?
0-2	Contexto	Incluí exemplos locais, leitor e objetivo de negócio?
0-2	Aceitação	O agente sabe quando terminou?
0-2	Verificação	Nomeei comandos ou checagens manuais?
0-2	Handoff	Defini o que reportar no final?

Oito pontos ou mais geralmente está pronto. Cinco ou menos significa que você está pedindo ao agente para compensar contexto humano ausente.

Gerador executável de briefing

Em vez de pedir “melhore isso”, crie sempre o mesmo formato de briefing. Este script gera prompt-brief.md; ajuste o arquivo e os critérios de aceite antes de entregar ao Claude Code ou Codex, deixando escopo, restrições e verificação claros desde o primeiro turno.

cat > prompt-brief.md <<'EOF'
# Task brief for Claude Code / Codex

Goal:
- Improve one article or feature without changing unrelated files.

Scope:
- May edit: site/src/content/blog/example.mdx
- Do not edit: hero images, routes, unrelated articles, billing code.

Context to read first:
- AGENTS.md
- A similar high-quality article
- The target file

Acceptance criteria:
- The intro explains who the reader is and why this matters.
- The draft includes at least three concrete examples.
- Code or prompt templates are copy-pasteable.
- Pitfalls and verification steps are explicit.
- Internal links and a natural CTA are included.

Verification:
- npm run build
- node scripts/check-code-fences.mjs
- Read the changed file once as a reviewer.

Return:
- What changed
- Checks run
- Remaining risks
EOF

CTA: transforme o padrão em workflow

Você não precisa reescrever esses padrões todos os dias. Comece pelo cheatsheet gratuito de Claude Code para comandos diários e hábitos seguros. Se quiser packs de prompts e material de setup prontos, veja ClaudeCodeLab products. Se seu time precisa de ajuda com CLAUDE.md, permissões, política de review, verification receipts e rollout, use Claude Code training and consultation.

Ao aplicar esse fluxo em artigos e tarefas reais do site ClaudeCodeLab, a maior melhora veio de escrever escopo, critérios de aceitação e evidência de verificação antes de pedir edição. As notas de handoff também reduziram o tempo de review no dia seguinte, porque o motivo de cada CTA e link ainda estava visível.