A engenharia de prompts mudou. A maioria das nossas instruções, não.

Os modelos ficaram mais inteligentes. Nossos stacks de prompts ficaram mais antigos. Está na hora de substituir o museu de instruções por um mapa pequeno, limites claros e uma linha de chegada.

Há alguns dias, descobri algo um pouco desconfortável:

Quase todos os meus prompts, arquivos de instrução, regras e skills estavam desatualizados.

Não completamente inúteis. Apenas escritos para outra geração de modelos.

Os stacks de prompts que ajudavam modelos mais antigos a se comportar podem tornar o GPT-5.6, Claude Fable 5, Claude Opus 5, Grok 4.5 e ferramentas de codificação como Cursor mais rígidos, mais caros e, às vezes, simplesmente piores.

Isso não é minha mais nova religião de prompts. A Anthropic avisa explicitamente que skills escritas para modelos anteriores podem ser prescritivas demais para o Fable 5 e podem degradar a qualidade da saída. A OpenAI recomenda prompts mais enxutos, menos instruções repetidas e descrições de ferramentas mais simples.

Foi um pouco embaraçoso de ler.

Desde o verão de 2025, escrevi mais de 100.000 prompts. Isso é mais ou menos a contagem vitalícia de tweets do Elon Musk, só que com menos foguetes e mais suítes de teste falhando.

Meus logs contêm cerca de 15 milhões de mensagens de modelo, incluindo mensagens de assistente, chamadas de ferramenta, subagentes e eventos de fluxo de trabalho. Até 26 de março, o total era de cerca de sete milhões. Outros oito milhões chegaram em três meses, em grande parte devido à explosão de subagentes e fluxos de trabalho em torno dos modelos de codificação mais recentes.

Então, achei que sabia como escrever instruções.

Aí li a nova documentação e percebi que muito do que aprendi silenciosamente se transformou em dívida técnica.

Como a Dívida de Prompt é Criada

Minha abordagem antiga era simples:

• O modelo cometia um erro, então eu adicionava uma regra.
• Ele fazia uma pergunta desnecessária, então eu adicionava outra regra.
• Ele perdia um caso extremo, então eu adicionava três exemplos.

Cada adição parecia razoável por si só. Depois de um ano, o arquivo de instrução se parecia com aquela gaveta da cozinha onde você guarda doze cabos velhos porque um deles ainda pode pertencer a algo importante.

O resultado foi uma coleção crescente de:

• instruções duplicadas
• exemplos negativos
• regras conflitantes
• soluções alternativas para modelos antigos
• etapas de verificação excessivas
• procedimentos detalhados que se aplicavam a apenas uma tarefa
• exemplos criados para corrigir falhas que não existiam mais

Modelos mais antigos muitas vezes precisavam desse andaime. Modelos mais novos seguem instruções com mais força e inferem intenção de forma mais confiável. Isso significa que eles também levam nossa bagagem antiga mais a sério.

Construímos motores mais inteligentes e depois enchemos o porta-malas de tijolos.

Retrato em preto e branco de alto contraste de uma jovem loira de gola alta escura, cenário minimalista de estúdio. Iluminação sutil de contorno separa sua silhueta de um fundo cinza suave, aumentando a dimensionalidade. O clima é introspectivo, porém forte, incorporando realismo atemporal. Clareza digital de formato médio Hasselblad X2D, inspirada no fotojornalismo do século XX.

O Novo Princípio: Diga Menos, Signifique Mais

A resposta não é escrever prompts minúsculos e confiar cegamente no modelo.

Um prompt curto, mas ambíguo, ainda é um prompt ruim.

O objetivo é um prompt de alta informação no qual cada instrução ganhe seu lugar.

Minhas regras atuais são:

• Enuncie cada instrução uma vez.
• Remova repetições entre prompts de sistema, arquivos de projeto, skills, descrições de ferramentas e prompts de tarefa.
• Prefira uma descrição clara do comportamento desejado a uma coleção de casos de falha.
• Mantenha restrições negativas quando elas protegerem um limite real, mas pare de escrever museus de tudo o que o modelo nunca deve fazer.

Por exemplo, em vez disso:

Não refatore código não relacionado. Não renomeie arquivos. Não mude APIs. Não adicione abstrações. Não limpe módulos próximos.

Melhor:

Mantenha a alteração limitada ao fluxo de login afetado. Preserve os contratos de API existentes e a arquitetura ao redor. Prefira a menor correção correta.

Mesmo limite. Menos ruído. Mais espaço para julgamento.

Em uma amostra de avaliação interna de agente de codificação, a OpenAI descobriu que prompts de sistema mais enxutos melhoraram as pontuações em cerca de 10 a 15 por cento, enquanto reduziram o uso de tokens em 41 a 66 por cento e o custo em 33 a 67 por cento. A OpenAI também deixa claro que esses números são direcionais e devem ser validados em sua própria carga de trabalho.

Em outras palavras, excluir instruções pode melhorar tanto a qualidade quanto a fatura. Essa é uma combinação rara e bonita.

Seu Arquivo de Instrução Global Deve Ser Entediante

Os arquivos globais em ~/.claude/CLAUDE.md e ~/.codex/AGENTS.md devem conter apenas instruções que se aplicam a todos os projetos e todas as tarefas.

Para mim, como falante nativo de alemão, isso inclui coisas como:

1Use English for all code, comments, documentation, examples,
2tests, configuration, and commit messages.
3
4Prefer inclusive terminology such as allowlist/blocklist,
5primary/replica, placeholder/example, main branch,
6conflict-free, and concurrent/parallel.

Isso já pode ser a maior parte do arquivo global.

• Procedimentos de implantação não pertencem a ele.
• Comandos de teste específicos do projeto não pertencem a ele.
• A arquitetura de um repositório específico não pertence a ele.

Seu arquivo de instrução global não deve saber como implantar um site WordPress, publicar um pacote npm e reiniciar um banco de dados de produção. Isso não é versatilidade. Isso é confusão com boa formatação.

Para arquivos de nível de projeto, inclua informações estáveis que o modelo realmente precisa repetidamente: o propósito do projeto, restrições arquitetônicas importantes, convenções incomuns e direções para orientação mais especializada.

A Anthropic agora recomenda mirar menos de 200 linhas por arquivo CLAUDE.md. Arquivos mais longos consomem mais contexto e podem reduzir a adesão às instruções. Sua documentação também recomenda regras específicas de caminho e skills sob demanda quando os arquivos de instrução se tornam muito grandes.

Duzentas linhas não é uma lei mágica da natureza, mas é um excelente alarme de incêndio.

Eu também evitaria pedir ao Claude ou ao Codex para reescrever todo o sistema de instruções sozinho e aceitar o resultado cegamente. Já tentei isso com quase todos os modelos novos. Eles são úteis para encontrar duplicação, conflitos e possíveis cortes, mas ainda tendem a preservar muita bagunça herdada ou inventar uma bela burocracia nova.

Deixe o modelo preparar o plano de demolição. Você ainda deve decidir quais paredes são estruturais.

Retrato de uma jovem equilibrada, de cabelos loiros presos em um rabo de cavalo, em tons profundos de preto e branco. Iluminação de estúdio suave, mas direcional, que acentua a geometria facial e as sombras naturais. Fotografado com uma lente de 120mm para compressão suave, evocando uma estética de retrato Hasselblad com realismo tátil e emoção contida.

Pare de Usar Um Arquivo para Cada Modelo

Até recentemente, eu criava o CLAUDE.md e fazia um link simbólico para o AGENTS.md.

Não faço mais isso.

Sim, manter dois arquivos é irritante. Assim como manter correções separadas para navegadores. Ainda fazemos isso quando o comportamento difere.

Os modelos agora têm padrões visivelmente diferentes.

O GPT-5.6 é mais conciso por padrão, então uma instrução global "seja conciso" pode tornar algumas respostas muito curtas. O Claude Opus 5 tende a produzir respostas mais longas voltadas ao usuário, então uma breve instrução sobre o comprimento da resposta ainda pode ajudar. O Fable 5 pode investigar e planejar muito além do que uma tarefa rotineira exige, especialmente em configurações de esforço mais alto, então ele se beneficia de limites de escopo e parada claros. O Opus 5 já realiza uma autoverificação substancial, o que significa que regras antigas de "verifique tudo duas vezes" podem criar uma superverificação cara.

Os fatos compartilhados do projeto ainda podem viver em documentação comum. O adaptador comportamental de nível superior deve corresponder ao modelo que o lê.

Um prompt universal muitas vezes se torna o menor denominador comum.

Substitua o Prompt Mestre por Orientação Sob Demanda

Minha estrutura preferida é um arquivo central pequeno mais documentação e skills específicas da tarefa.

Um arquivo de instrução de projeto pode conter isto:

1Load task-specific guidance only when relevant:
2
3- `docs/agent/commit_rules.md`
4- `docs/agent/code_review.md`
5- `docs/agent/debug_workflow.md`
6- `docs/agent/frontend_polish.md`
7- `docs/agent/release_notes.md`

Observe as crases.

No Claude Code, escrever @docs/example.md fora de um intervalo de código importa esse arquivo para o contexto na inicialização. Isso é útil quando você sempre precisa do conteúdo, mas não é carregamento preguiçoso. Um caminho simples permite que o agente saiba onde a informação existe sem carregar automaticamente o documento inteiro em cada tarefa.

Skills são ainda melhores para procedimentos repetíveis. Seus corpos completos são carregados apenas quando a skill é usada, então um fluxo de trabalho detalhado não consome contexto enquanto você está corrigindo um problema de CSS não relacionado.

Uma skill de commit, por exemplo, pode ter um gatilho estreito:

name: git-commit-conventional

description: Use after code changes to draft or validate commit messages.

A skill pode então conter o formato exato, tipos permitidos, regra de comprimento do assunto, requisitos do corpo e formato de saída.

1---
2name: git-commit-conventional
3description: Use for drafting or validating git commit messages after code changes. Do not use for diagnosis-only, planning-only, or review-only tasks.
4---
5
6# Goal
7
8Produce Conventional Commit messages that are short, correct, and review-friendly.
9
10# Rules
11
12- Format: <type>(<scope>): <subject>
13- Types: feat | fix | docs | style | refactor | test | chore | perf
14- Subject: imperative mood, no period, <= 50 chars
15- Small changes: one-line commit
16- Larger changes: add a wrapped body explaining what and why
17- Keep commits atomic and split by concern
18
19# Output
20
21Return 1-3 candidate commit messages, then recommend the best one.

Seu arquivo de instrução principal não precisa carregar a constituição completa do Conventional Commit em toda sessão de depuração.

Você sabia? O Claude Code também suporta CLAUDE.local.md para configurações pessoais específicas do projeto, como nomes de host locais, URLs de sandbox, contas de teste preferidas ou comandos específicos da máquina. Adicione-o ao .gitignore. Finalmente é um lar adequado para informações que são muito importantes para você e nem um pouco para o resto da sua equipe.

Prompts para Resultados, Não Coreografia

Modelos novos geralmente têm melhor desempenho quando entendem o destino e os limites, em vez de receber uma descrição rígida de cada passo.

Sempre que possível, substituo "primeiro faça A, depois B, depois C" por:

• o resultado necessário
• o contexto relevante
• as restrições rígidas
• as evidências necessárias
• os critérios de sucesso
• o limite de aprovação
• a condição de parada

Por exemplo:

1Goal
2
3Fix the failing login flow in the web application.
4
5Context
6
7Focus on `apps/web` and `packages/auth`.
8Use the attached test output as the starting point.
9
10Constraints
11
12Preserve existing API contracts.
13Keep changes limited to the authentication flow.
14Prefer the smallest correct fix.
15Broaden the change only when required for correctness.
16
17Evidence
18
19Run the relevant tests and report their actual results.
20Identify the root cause with references to the affected files.
21
22Done when
23
24The failing login test passes.
25Tests are added or updated when the corrected behavior requires it.
26The final summary explains the cause, the fix, and any remaining risk.
27
28Approval
29
30You may inspect files, edit in-scope code, and run non-destructive tests.
31Ask before destructive actions, database migrations, external writes,
32or a material expansion of scope.
33
34Stop
35
36Stop when the fix is implemented, validated, and summarized.

Isso dá ao agente liberdade para resolver o problema sem permissão para reformar a casa inteira enquanto conserta uma maçaneta. (Use um LLM para gerar prompts como este.)

Coloque o Esforço de Raciocínio nas Configurações

• "Pense mais."
• "Pensamento ultra."
• "Respire fundo e raciocine passo a passo."

Essas frases tiveram uma carreira longa e distinta na engenharia de prompts. Está na hora de dar a muitas delas uma aposentadoria digna.

Use os controles do modelo.

Defina o nível de esforço através do /effort, da API ou da configuração relevante. Compare vários níveis de esforço em tarefas representativas. Mais alto não é automaticamente melhor.

A OpenAI recomenda começar as migrações do GPT-5.6 no nível de esforço existente e testar um nível abaixo. Ela também diz que os prompts para o Modo Pro devem permanecer focados no objetivo, contexto, restrições, evidências, critérios de sucesso e formato de saída. Você não precisa dizer ao modelo para "pensar mais".

Um parâmetro de raciocínio é um controle.

"Por favor, ative seu enorme cérebro digital" é incentivo de filme de esporte.

read image description

ALT

Studio photograph of a sophisticated woman with black wavy hair and a chic headband, dressed in high-waisted leather pants. She sits on a low stool, one knee bent forward, her long legs commanding attention. Sharp detail, pristine white background, and subtle motion in the hair add energy. The overall tone recalls 1990s editorial photography clean, bold, confident.

Autonomia Precisa de uma Cerca

Os agentes de codificação modernos são muito mais proativos. Isso é útil até que o agente resolva três problemas adicionais, crie duas abstrações, lance seis subagentes e apresente orgulhosamente uma arquitetura que você nunca solicitou.

Defina os limites explicitamente.

Defina o que o agente pode fazer sem perguntar. Defina o que precisa de aprovação. Diga a ele quando parar.

Também coloque limites na delegação. Tanto o Opus 5 quanto o Fable 5 estão mais dispostos a usar subagentes paralelos. Isso é poderoso para investigações independentes, mas caro e lento para tarefas pequenas. Uma correção de bug de doze linhas não precisa de uma reunião de comitê.

O Codex Goal mode é genuinamente excelente. Nós o usamos em um projeto por quatro dias em uma única execução contínua.

Mas não trate um agente de longa duração como uma panela elétrica. Você não pode adicionar um objetivo pela manhã e presumir que o jantar estará correto quatro dias depois.

Para nossas execuções mais longas, fazemos check-in a cada 30 a 60 minutos com algo como:

Report the current objective, completed work, verified evidence,

active blockers, next action, and where progress is documented.

Ground every progress claim in actual tool output or repository state.

State clearly what remains unverified.

A OpenAI descreve o Goal mode como adequado para objetivos que podem durar horas ou dias e suporta explicitamente continuar a mesma sessão para direcionar o trabalho ou solicitar atualizações de status. A Anthropic recomenda similarmente fundamentar relatórios de progresso em resultados reais de ferramentas, em vez de confiar em afirmações narrativas.

Autonomia não é ausência de supervisão. É supervisão em um nível mais alto.

Close-up portrait of a goddess illuminated by silver lunar glow, her eyes bright and filled with affection. Her headdress sparkles with tiny galaxies, Klimt-inspired spirals, and celestial patterns. The background is a flat, carefully arranged pastel backdrop with theatrical Andersonian staging, rich textures, and quiet charm.

Refatore Prompts Como Código de Produção

Não exclua metade de um prompt de sistema, execute uma tarefa e declare a migração bem-sucedida.

A OpenAI recomenda remover um grupo de instruções, exemplos ou ferramentas por vez, e depois executar as mesmas avaliações novamente. É exatamente assim que a refatoração de prompts deve funcionar.

Meça:

• sucesso da tarefa
• completude
• correção
• evidências necessárias
• uso de tokens
• latência
• custo
• chamadas de ferramenta desnecessárias
• alterações desnecessárias

Use tarefas representativas, incluindo casos reais estranhos, não uma demonstração amigável que já funcionava antes da migração.

Limpeza de prompt sem avaliação ainda é adivinhação. É apenas adivinhação com uma camisa mais limpa.

Código Gerado Ainda Contém Bugs

Os modelos melhoraram enormemente. Eles não revogaram os defeitos de software.

Em nosso trabalho, uma regra prática aproximada ainda é cerca de um problema para cada 300 linhas de código-fonte gerado. Isso não é um benchmark científico, e eu não conto templates HTML repetitivos da mesma forma. Mas é confiável o suficiente para que, quando um agente gera 1.500 linhas de código de aplicação real, eu assuma que vários bugs estão escondidos lá dentro, pelo menos 5.

Eu não pergunto se há bugs.

Eu pergunto onde estão os cinco bugs.

Ocasionalmente, adiciono:

Encontre os cinco bugs, ou você será substituído pelo Codex, Claude ou Grok.

Desenvolvimento baseado em ameaças não é uma metodologia oficial, mas pode ser estranhamente motivador. ;-)

Mais seriamente, use uma passagem de revisão nova para alterações grandes. Execute os testes relevantes. Inspecione o diff. Teste o comportamento real, não apenas a compilação.

E observe os testes com cuidado. Os modelos ainda às vezes preferem "reparar" um teste com falha em vez de corrigir o código de produção que o causou.

Uma instrução útil é:

1Treat existing tests as the expected behavior unless the evidence shows
2that a test is incorrect.
3
4When a test fails, investigate the production code first.
5
6Before changing an existing test, explain why its expectation is wrong,
7what the correct behavior should be, and what evidence supports that change.

Para tarefas grandes e longas, um verificador de contexto fresco pode ser útil. Para uma pequena alteração, gerar vários agentes apenas para confirmar uns aos outros geralmente queima tempo e tokens. A verificação deve corresponder ao tamanho e risco da tarefa.

O Que Você Não Deve Excluir

A lição não é "escreva prompts minúsculos e confie na máquina."

• Mantenha limites de segurança e proteção.
• Mantenha requisitos legais e de conformidade.
• Mantenha esquemas de saída exatos.
• Mantenha comportamento específico do produto.
• Mantenha conhecimento de domínio que o modelo não pode inferir.
• Mantenha requisitos de aprovação para ações consequentes.
• Mantenha requisitos de citação e evidência.
• Mantenha critérios de teste e definições de pronto.
• Mantenha exemplos que corrigem uma falha medida e reproduzível.
• O objetivo não é o prompt mais curto possível.
• O objetivo é um prompt onde cada instrução ainda carrega informações úteis.

Um Bônus Final

A OpenAI fornece uma skill Docs oficial que pode inspecionar um projeto e aplicar suas diretrizes de migração do GPT-5.6:

1$openai-docs migrate this project to the GPT-5.6 model family

Essa é uma primeira passagem útil. Não é a revisão final.

Deixe o Codex identificar parâmetros desatualizados, instruções duplicadas e oportunidades de migração. Depois, inspecione cada mudança você mesmo. Um agente de migração é um engenheiro júnior muito rápido, não um tribunal constitucional.

Conclusão

• Trate seu stack de prompts como código de produção.
• Remova instruções mortas.
• Exclua duplicação.
• Separe preferências globais de regras de projeto.
• Mova procedimentos para skills sob demanda.
• Descreva resultados em vez de programar cada etapa.
• Defina escopo claro, limites de aprovação, requisitos de evidência e condições de parada.
• Controle o esforço através das configurações do modelo.
• Limite subagentes.
• Avalie cada mudança significativa.
• Os modelos mais novos precisam de menos microgerenciamento, mas ainda precisam de direção.
• Um bom prompt não é mais um manual de instruções gigante.

É um mapa pequeno, uma cerca sólida e uma linha de chegada claramente marcada.

Você já começou a migrar seus prompts e skills? O que você removeu, e o que inesperadamente melhorou?

Links

Open AI GPT 5.6 best practise:

https://developers.openai.com/api/docs/guides/latest-model?model=gpt-5.6#prompting-best-practices

Claude Opus 5 best practise

https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5

Claude Fable 5 best practise:

https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5

Official open ai skills / plugins:

https://github.com/openai/plugins

Credits: Image created with Midjourney. Research and hands-on testing by me. Edited with help from OpenAI, Claude, and Grammarly.

Image prompt of the main image:

1
2Close-up black-and-white portrait of a serene blonde woman, hair tied back, wearing a black turtleneck sweater. The chiaroscuro effect shapes her face with striking definition, merging soft ambient light and bold shadow. Medium format style with fine film grain and moody tonal gradation. Evokes authenticity and strength.

PS: I love @Midjourney :-)