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

Os modelos ficaram mais inteligentes. Nossas pilhas de prompts envelheceram. 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.

As pilhas 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 código como Cursor mais rígidos, mais caros e, às vezes, simplesmente piores.

Isso não é a 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.

Isso foi um pouco embaraçoso de ler.

Desde o verão de 2025, escrevi mais de 100.000 prompts. Isso é aproximadamente o número total 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 modelos, incluindo mensagens de assistente, chamadas de ferramenta, subagentes e eventos de workflow. 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 workflows em torno dos modelos de código mais recentes.

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

Aí li a nova documentação e percebi que grande parte do que havia aprendido tinha se transformado silenciosamente 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 de borda, 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 de cozinha onde você guarda doze cabos velhos porque um deles ainda pode pertencer a algo importante.

O resultado era 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 geralmente 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 em uma gola rolê escura, cenário minimalista de estúdio. Iluminação sutil de contorno separa sua silhueta de um fundo cinza suave, aumentando a tridimensionalidade. O clima é introspectivo, porém forte, incorporando realismo atemporal. Clareza de formato médio digital 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 merece seu lugar.

Minhas regras atuais são:

• Declare cada instrução uma vez.
• Remova repetições em system prompts, arquivos de projeto, skills, descrições de ferramentas e task prompts.
• Prefira uma descrição clara do comportamento desejado a uma coleção de casos de falha.
• Mantenha restrições negativas quando elas protegem um limite real, mas pare de escrever museus de tudo 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 altere 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 interna de avaliação de agente de codificação, a OpenAI descobriu que system prompts 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 genuinamente precisa repetidamente: o propósito do projeto, restrições arquiteturais importantes, convenções incomuns e direções para orientações mais especializadas.

A Anthropic agora recomenda segmentar 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 por conta própria e aceitar o resultado cegamente. Já tentei isso com quase todos os novos modelos. 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 mulher jovem e serena com cabelo loiro preso em um rabo de cavalo, renderizado em tons profundos de preto e branco. Iluminado em estúdio com luz suave, mas direcional, que acentua a geometria facial e as sombras naturais. Fotografado com uma lente de 120 mm para compressão suave, evocando uma estética de retrato Hasselblad com realismo tátil e emoção contida.

Pare de Usar um Único Arquivo para Cada Modelo

Até recentemente, eu criava o CLAUDE.md e fazia um symlink do AGENTS.md para ele.

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 curtas demais. O Claude Opus 5 tende a produzir respostas mais longas voltadas para o usuário, então uma instrução breve sobre o comprimento da resposta ainda pode ajudar. O Fable 5 pode investigar e planejar muito além do que uma tarefa de rotina exige, especialmente em configurações de esforço mais altas, 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 novamente" podem criar uma verificação excessiva e 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 do projeto pode conter isso:

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 span 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 workflow 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 oferece suporte a CLAUDE.local.md para configurações pessoais específicas do projeto, como hostnames 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.

Crie Prompts para Resultados, Não para Coreografia

Modelos mais 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."
• "Pense 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

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 modo Goal do Codex é 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 esperar que o jantar esteja 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 modo Goal como adequado para objetivos que podem durar horas ou dias e apoia explicitamente a continuação da 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 é a 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 system prompt, execute uma tarefa e declare a migração bem-sucedida.

A OpenAI recomenda remover um grupo de instruções, exemplos ou ferramentas de cada vez e, em seguida, reexecutar as mesmas avaliações. É 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 apenas uma demonstração amigável que já funcionava antes da migração.

A limpeza de prompts sem avaliação ainda é um palpite. É apenas um palpite 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 aplicativo 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, eu 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 de longa duração, 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 o 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 consequenciais.
• 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 orientações de migração para o 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. Em seguida, inspecione cada alteração você mesmo. Um agente de migração é um engenheiro júnior muito rápido, não um tribunal constitucional.

A Conclusão

• Trate sua pilha 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 roteirizar cada passo.
• 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 :-)