Prompt engineering avançado para Claude Code e Codex: briefs práticos que resistem ao trabalho real

Quando Claude Code ou Codex entrega resultados irregulares, o problema muitas vezes não é o modelo. É a forma como a tarefa foi entregue. Prompt engineering avançado não é uma frase mágica. É desenho de fluxo de trabalho: objetivo, escopo, contexto, restrições, critérios de aceite, verificação e handoff em um pacote.

Este guia mostra como criar um “pacote de prompt” reutilizável para Claude Code e Codex. Iniciantes podem copiar os modelos, mas o desenho também serve para equipes, repositórios reais, trabalho em paralelo, código de produção e artigos publicados. Para a base, leia antes 5 dicas para prompts melhores e boas práticas de CLAUDE.md.

O comportamento das ferramentas muda, então afirmações sobre recursos precisam vir de documentação oficial. Para Claude Code, comece por Claude Code overview, Memory e prompt engineering overview. Para Codex, use OpenAI Codex docs e AGENTS.md guidance.

Avançado significa contrato de trabalho

Um prompt fraco não é apenas curto. Ele não tem regras de decisão, não diz quais arquivos não podem ser tocados, não define o que é “pronto” e não pede prova. Com essas lacunas, o agente precisa adivinhar.

Um prompt prático funciona como um pequeno contrato.

Parte	O que escrever	Falha quando falta
Goal	Resultado esperado	A resposta parece boa, mas resolve outra coisa
Scope	O que pode e não pode mudar	Refatorações sem relação entram no diff
Context	Docs, código parecido, fontes oficiais	O agente copia padrões antigos ou inventa
Constraints	Regras e mudanças proibidas	Dependências, APIs ou tom mudam sem querer
Acceptance criteria	Como julgar conclusão	A revisão vira gosto pessoal
Verification	Comandos e checagens manuais	O trabalho termina sem evidência

O overview de prompt engineering da Anthropic começa por critérios de sucesso e testes empíricos. Para agentes de código isso pesa mais, porque Claude Code e Codex podem ler arquivos, editá-los e executar comandos antes de o resultado estar realmente validado.

Coloque o pacote de prompt em um arquivo

Digitar uma instrução longa no chat toda vez é ruim para revisar e reaproveitar. Um arquivo como prompt-packet.md deixa a tarefa repetível. O Bash abaixo cria um pacote mínimo.

cat > prompt-packet.md <<'EOF'
# Goal
Improve one published article so it is practical, accurate, and ready for review.

# Scope
May edit:
- site/src/content/blog/example-article.mdx

Do not edit:
- heroImage
- slug
- unrelated articles
- package or deployment files

# Context to read
- AGENTS.md
- site/src/content/blog/claude-md-best-practices.mdx
- Official docs relevant to the article topic

# Constraints
- Preserve existing frontmatter keys unless this task explicitly changes them.
- Use copy-pasteable examples, not pseudocode.
- Avoid unsupported claims. Link to official docs for tool behavior.
- Keep paragraphs short enough for mobile reading.

# Acceptance criteria
- updatedDate is 2026-06-02.
- The article has at least three concrete use cases.
- The article names specific pitfalls and how to avoid them.
- The article includes an internal link, an official external link, and a natural CTA.
- The final section explains what was actually verified.

# Verification
- node scripts/check-code-fences.mjs
- node scripts/check-updated-article-quality.mjs
- Read the diff once as a critical reviewer.

# Return format
- Changed files
- Key improvements
- Checks run
- Residual risks
EOF

Depois diga ao agente: “Leia prompt-packet.md primeiro, inspecione o arquivo alvo e o contexto listado, e trabalhe apenas dentro do Scope.” Isso não é burocracia. Evita que o agente tente ajudar alterando páginas vizinhas, imagens, configuração ou código fora da tarefa.

Valide o prompt antes de usar

Prompts são texto natural, então a qualidade pode variar. Um verificador pequeno pega estrutura faltando antes da tarefa chegar ao agente. Salve como check-prompt-packet.cjs.

// save as check-prompt-packet.cjs
const fs = require("node:fs");

const file = process.argv[2] || "prompt-packet.md";
const text = fs.readFileSync(file, "utf8");

const required = [
  "# Goal",
  "# Scope",
  "# Context to read",
  "# Acceptance criteria",
  "# Verification",
  "# Return format",
];

const missing = required.filter((heading) => !text.includes(heading));
const hasDoNotTouch = /do not (edit|change|touch)/i.test(text);
const hasCommand = /npm run|npm test|pnpm |yarn |node scripts\//i.test(text);

if (missing.length || !hasDoNotTouch || !hasCommand) {
  console.error("Prompt packet is not ready.");
  if (missing.length) console.error("Missing headings: " + missing.join(", "));
  if (!hasDoNotTouch) console.error("Add an explicit do-not-touch boundary.");
  if (!hasCommand) console.error("Add at least one verification command.");
  process.exit(1);
}

console.log("Prompt packet looks actionable.");

Execute assim:

node check-prompt-packet.cjs prompt-packet.md

É simples de propósito. Na operação de artigos de Masa, os erros mais comuns apareciam quando faltava o limite de “não tocar” ou a prova final. Em código de produto é igual. Se o pedido não define conclusão, o review vira opinião.

Transforme metas vagas em critérios de aceite

“Melhore isso”, “deixe mais forte para SEO” e “prepare para produção” são intenções úteis, mas não são verificáveis. Transforme em checks que passam ou falham.

Prompt fraco:

Melhore este artigo e fortaleça o SEO.

Prompt útil:

Reescreva o artigo como um guia prático para desenvolvedores começando com Claude Code.

Acceptance criteria:
- O título inclui "Claude Code" e "prompt engineering".
- A description tem menos de 120 caracteres.
- O corpo inclui pelo menos três casos de uso concretos.
- Há pelo menos dois exemplos ruins de prompt e duas versões melhoradas.
- O artigo linka documentação oficial e artigos internos relacionados.
- A seção final diz o que foi realmente verificado.
- Rode o check de code fences depois de editar e reporte o resultado.

Para implementação, deixe os critérios técnicos.

Acceptance criteria:
- Não mudar o tipo da API pública.
- Adicionar validação e erros visíveis para o usuário.
- Adicionar ou atualizar pelo menos um teste de caminho de falha.
- Rodar npm test e npm run build, e reportar resultados.
- Explicar arquivos alterados e arquivos relevantes inspecionados sem mudança.

Critérios de aceite não são microgerenciamento. Eles compartilham o padrão de revisão antes do trabalho começar.

Controle o orçamento de contexto

A documentação de Memory explica que CLAUDE.md e auto memory são carregados como contexto, não como configuração forçada. Mais texto não garante mais adesão. Pode esconder a regra importante.

Separe o contexto em três camadas.

Camada	Exemplos	Melhor lugar
Sempre necessário	Comandos de build, nomes, áreas proibidas	CLAUDE.md ou AGENTS.md
Específico da tarefa	Arquivo alvo, implementação similar, padrão de qualidade	prompt-packet.md
Ler só se precisar	Specs longas, notas antigas, logs crus	Citar arquivo, não colar tudo

O erro comum é despejar material demais. Se você mistura atas, notas antigas, logs e tarefa atual, o agente precisa inferir prioridade. Escreva a ordem de leitura.

Context to read in order:
1. AGENTS.md for project rules.
2. The target article.
3. One similar high-quality article for tone and structure.
4. Official docs only for tool behavior.

Ignore:
- Old brainstorming notes unless they contradict the current implementation.
- Unrelated product pages.
- Generated files and build output.

Isso reduz exploração inútil. Também ajuda em trabalho paralelo, porque o agente não deve tratar todo arquivo visível como permissão para editar.

Separe exemplos de restrições

Exemplos mostram o padrão a imitar. Restrições definem a fronteira. Misturar os dois deixa o pedido nebuloso.

Prompt fraco:

Deixe esta página parecida com o artigo de produtividade.

Prompt melhor:

Reference style:
- Use site/src/content/blog-pt/claude-code-productivity-tips.mdx only for section density and CTA placement.
- Do not copy its examples or claims.

Constraints:
- Keep this article focused on prompt engineering.
- Do not introduce pricing claims.
- Preserve heroImage and slug.

Não pare em “não quebre nada”. Dê também a fronteira positiva. “Não adicione bibliotecas” fica melhor como “use apenas dependências existentes”. “Não mude demais” fica melhor como “edite só o arquivo listado e preserve a API pública”.

Peça uma iteração segura

Para trabalho sério, um comando gigante é menos confiável que um loop claro.

1. Ler alvo, regras e exemplo mais próximo.
2. Explicar brevemente o plano.
3. Editar apenas dentro do escopo.
4. Verificar com comandos e checagem manual.
5. Reportar alterações, evidências e riscos.

Você pode escrever assim.

Workflow:
- First inspect the target file and the nearest quality reference.
- If the change is larger than two files, explain the plan before editing.
- Edit only the files listed in Scope.
- After editing, run the Verification commands if feasible.
- End with a verification receipt, not a general summary.

Um verification receipt é o recibo do trabalho. O padrão completo está no guia de verification receipt, mas o formato mínimo basta no dia a dia.

Verification receipt:
- Changed files:
- Commands run:
- Results:
- Manual checks:
- Could not verify:
- Residual risks:

Quatro casos de uso concretos

O primeiro caso é correção de bug. Entregue sintoma, passos de reprodução, comportamento esperado, logs e arquivos permitidos. Peça para explicar a causa provável antes de editar, fazer o menor fix e adicionar um teste de caminho de falha. Isso evita correção apenas visual.

O segundo caso é pequena funcionalidade. Descreva a mudança visível ao usuário, se API ou banco podem mudar, qual padrão de UI seguir e quais testes provam o resultado. Para adicionar categoria a um formulário de contato, inclua opções, validação, payload, evento de analytics e localização.

O terceiro caso é reescrita de artigo. Informe leitor, intenção de busca, tamanho alvo, exemplos obrigatórios, falhas, links internos, CTA e fontes oficiais. Na ClaudeCodeLab, isso evita transformar um artigo raso apenas em um resumo mais fluido.

O quarto caso é revisão de código. Prompt de revisão precisa mais de formato do que criatividade. Peça severidade, arquivo e linha, condição de reprodução, direção de correção e testes faltantes. Em vez de “revise tudo”, priorize segurança, perda de dados, mudanças de API pública e caminhos de erro sem teste.

Falhas comuns

Falha 1: misturar objetivos. “Refatore, acelere, melhore SEO e mude CTA” são vários trabalhos. Use um objetivo por pacote.

Falha 2: escrever só proibições. “Não quebre nada” não diz o que o agente pode fazer. Combine área proibida com área permitida.

Falha 3: tratar conhecimento antigo como comportamento oficial. Claude Code, Codex, memory, settings e AGENTS.md podem mudar. Linke docs oficiais e não afirme além delas.

Falha 4: deixar verificação opcional. Se um comando não puder rodar, o agente deve dizer. Silêncio é pior que uma lacuna declarada.

Falha 5: deixar bons prompts presos no chat. Mova instruções úteis para prompt-packet.md, CLAUDE.md ou checklist de revisão. Para continuidade de equipe, combine com regras de handoff.

CTA: padronize antes de escalar

Você não precisa reescrever este pacote todo dia. Comece com a folha gratuita para checks diários, compare materiais reutilizáveis em produtos e templates e use treinamento ou consultoria Claude Code quando a equipe precisar adaptar CLAUDE.md, permissões, revisão, verification receipts e qualidade editorial a um repositório real.

O que verifiquei neste artigo

Para este artigo, conferi no overview oficial que Claude Code pode ler uma base de código, editar arquivos e executar comandos. Conferi em Memory a diferença entre CLAUDE.md, auto memory e configuração forçada. Também confirmei no prompt engineering overview da Anthropic que critérios de sucesso e testes devem existir antes de melhorar prompts, e alinhei a parte de Codex com OpenAI Codex docs e AGENTS.md guidance. A conclusão prática é tratar prompts como contratos de trabalho revisáveis, não como mensagens soltas de chat.