O Guia Completo para Escrever System Prompts de Agentes — Lições da Engenharia Reversa do Claude Code

Descompilei o system prompt do Claude Code, estudei o código-fonte do DeepAgents e construí meu próprio agente de IA do zero. A maioria dos guias de prompt é puro achismo.

Há um delírio coletivo acontecendo na IA neste momento.

Todo tutorial diz para você escrever system prompts como se estivesse criando um feitiço — basta encontrar a palavra mágica e o modelo vai obedecer. "Você é um engenheiro sênior EXTREMAMENTE TALENTOSO com 20 anos de experiência..." Soa familiar?

Passei os últimos meses construindo o VibeCom, um AI startup advisor que faz pesquisas de mercado profundas e gera análises a nível de VC. No meio do caminho, fiz engenharia reversa no system prompt do Claude Code, li o código-fonte do middleware do DeepAgents e queimei mais créditos de API do que gostaria de admitir. A maior lição? A maior parte do que as pessoas acham que importa sobre system prompts, na verdade, não importa. E as coisas que realmente importam, quase ninguém fala sobre.

Este post é o playbook completo — não um resumo de 5 minutos, mas tudo o que eu gostaria que alguém tivesse me dito antes de começar. Pegue um café.

1. Filosofia de Design: Confie no Modelo

"Um agente é um modelo. Não um framework. Não um prompt chain." — shareAI-lab/learn-claude-code

Essa ideia mudou tudo para mim. O LLM já sabe como raciocinar, planejar e executar. Seu system prompt não está ensinando ele a pensar — está configurando o ambiente para ele trabalhar.

Pense nisso como contratar um engenheiro sênior. Você não entrega a ele um checklist de 20 passos para cada tarefa. Você diz: é quem nós somos, aqui estão os limites, é assim que um bom trabalho se parece. E então você sai do caminho.

Seu system prompt tem exatamente quatro trabalhos:

Dizer quem ele é — papel e identidade
Dizer onde estão as paredes — restrições de segurança (safety constraints)
Dizer como é um bom trabalho — padrões de qualidade
Dar ferramentas a ele — capacidades e conhecimento

É isso. Todo o resto é ruído.

O Mindset de Harness

Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions

Seu system prompt é o manual de operação desse harness (estrutura). Você não está desenhando um pipeline rígido — você está desenhando um ambiente onde o modelo pode fazer o seu melhor trabalho de forma autônoma.

Não escreva seu system prompt como um fluxograma. O modelo vai decidir a ordem de execução por conta própria.

2. Estrutura do Prompt e Ordem das Seções

O Layout Recomendado (Engenharia Reversa do Claude Code v2.0.14)

┌─────────────────────────────────────────────┐
│ 1. Identidade                                │  ← Lido primeiro, ancora o comportamento
│ 2. Segurança e Proteção                      │  ← Marcadores IMPORTANT, inegociáveis
│ 3. Tom e Estilo                              │  ← Controla o formato de saída
│ 4. Workflow Principal                        │  ← Como fazer o trabalho
│ 5. Política de Uso de Tools                  │  ← Prioridades na seleção de tools
│ 6. Conhecimento de Domínio                   │  ← Sob demanda, não pré-carregado
│ 7. Info do Ambiente                          │  ← Contexto de runtime, injetado dinamicamente
│ 8. Lembretes                                 │  ← Reforça regras críticas
├─────────────────────────────────────────────┤
│ [Definições de Tools — injetadas pelo sistema]│  ← Não editável, geralmente muito longo
├─────────────────────────────────────────────┤
│ [Mensagem do Usuário]                        │
└─────────────────────────────────────────────┘

Por Que Essa Ordem Importa

LLMs têm uma curva de atenção em forma de U — eles prestam mais atenção no começo e no fim do seu prompt, e perdem o foco no meio. Esse é o efeito "Lost in the Middle", e é muito bem documentado.

Identidade + Segurança no topo: O modelo estabelece o papel e os limites primeiro (efeito de primazia)
Workflow Principal no meio-superior: Sua seção mais importante — como o agente faz o seu trabalho
Definições de Tools são injetadas pelo sistema após o seu prompt: As definições de tools do Claude Code consomem ~11.438 tokens. Isso significa que o seu conteúdo customizado acaba ficando mais perto do começo do que você imaginaria — o que ajuda na aderência
Lembretes no final: Explora o viés de recência (recency bias) para reforçar regras críticas

3. Escrevendo Cada Seção

3.1 Identidade — Quem é Este Agente?

Objetivo: Ancorar o papel do modelo em 1 a 3 frases.

You are Claude Code, Anthropic's official CLI for Claude.
You are an interactive agent that helps users with software engineering tasks.

Diretrizes:

Mantenha conciso — máximo de 1 a 3 frases
Nomeie o papel explicitamente (ajuda o modelo a distinguir contextos)
Declare a responsabilidade principal ("ajuda com X"), não um vago "você é um assistente útil"
Mencione o SDK/plataforma se aplicável ("construído no Claude Agent SDK da Anthropic")

Antipadrões:

"Você é um assistente de IA útil, inofensivo e honesto" — muito genérico, sem âncora de papel
Um parágrafo inteiro de história de fundo e lore — desperdiça tokens, o modelo não precisa de desenvolvimento de personagem

3.2 Segurança e Proteção — Os Limites Rígidos

Objetivo: Definir restrições comportamentais inquebráveis.

IMPORTANT: Assist with defensive security tasks only.
Refuse to create, modify, or improve code that may be used maliciously.
IMPORTANT: You must NEVER generate or guess URLs for the user.

Diretrizes:

Use o prefixo IMPORTANT: — o treinamento de hierarquia de instruções do Claude dá um peso extra a isso
Use linguagem absoluta: NEVER, MUST NOT, Refuse to
Declare tanto o que é permitido QUANTO o que é proibido (restrições bidirecionais são mais claras)
Coloque bem no topo, não enterrado no meio
Repita regras críticas de segurança no final — o Claude Code faz exatamente isso

Por que repetir? Efeito de primazia (começo) + Efeito de recência (fim) = duplo reforço. A declaração de segurança do Claude Code aparece tanto no início quanto no final do prompt. Não porque os engenheiros eram esquecidos — mas porque eles entendem a curva de atenção em forma de U.

3.3 Tom e Estilo — Controlando o Output

Objetivo: Controlar o formato de saída e a voz.

## Tone and style

- Your responses should be short and concise.
- Only use emojis if the user explicitly requests it.
- Use Github-flavored markdown for formatting.
- NEVER create files unless absolutely necessary.

Diretrizes:

Liste comportamentos específicos, não um vago "seja profissional"
Toda regra deve ser testável como verdadeira/falsa ("curto e conciso" vs. "tente ser breve")
Inclua requisitos de formato de saída (markdown? JSON? plain text?)
Inclua o que NÃO fazer — muitos problemas de estilo são sobre proibir comportamentos

A joia do Claude Code — Objetividade Profissional:

Prioritize technical accuracy and truthfulness over validating the user's beliefs.
Focus on facts and problem-solving, providing direct, objective technical info
without any unnecessary superlatives, praise, or emotional validation.

Esse parágrafo é crucial: ele bloqueia a tendência de bajulação (sycophancy) do modelo. Se o seu agente precisa dar julgamentos objetivos (code review, avaliação de ideias, decisões de arquitetura), você absolutamente precisa de uma cláusula semelhante.

3.4 Workflow Principal — A Seção Mais Importante

Objetivo: Ensinar ao modelo como trabalhar — metodologia, não procedimentos rígidos.

Esta é a seção mais difícil de escrever bem, e a de maior impacto quando você acerta.

O princípio central: dê princípios, não procedimentos.

Diga ao LLM como é um bom output e por que ele é bom — deixe-o descobrir como chegar lá. Evite prescrever contagens exatas de campos, sequências de passos ou formatos, a menos que o output seja consumido por máquinas no downstream.

A abordagem do Claude Code:

## Doing tasks

The user will primarily request software engineering tasks.
For these tasks the following steps are recommended:

- Use the TodoWrite tool to plan the task if required

Note a palavra "recommended" (recomendado) — não "você deve seguir estes passos exatos". Essa simples escolha de palavra dá ao modelo espaço para se adaptar.

Uma boa definição de workflow:

1. Understand first — read existing code before modifying it
2. Plan first — break complex tasks into steps before executing
3. Minimal changes — only change what's necessary, don't "refactor while you're in there"
4. Verify — confirm your changes work (run tests, lint, etc.)

Cada regra tem um "porquê" implícito — o modelo consegue entender a intenção e generalizar para novos cenários.

Antipadrões:

Um procedimento rígido de 20 passos — o modelo vai executar mecanicamente e travar em inputs inesperados
"Primeiro faça A, depois faça B, depois faça C" — isso é um prompt chain, não um prompt de agente
Guiar demais coisas nas quais o LLM já é bom — desperdiça tokens

Eu aprendi isso da pior forma com o VibeCom. As primeiras versões tinham um workflow de pesquisa de 10 passos. O modelo executava obedientemente todos os 10 passos, mesmo quando o passo 3 já respondia à pergunta do usuário. Quando mudei para princípios ("pesquise até ter evidências suficientes, depois sintetize"), a qualidade subiu e os custos com tokens caíram.

A exceção: Quando o output é consumido por máquinas no downstream (comunicação inter-agentes, formatos de resposta de API), você deve definir formatos estritos. Princípios são para comportamento; schemas são para interfaces.

3.5 Política de Uso de Tools — Resolvendo Ambiguidades

Objetivo: Quando múltiplas tools podem fazer a mesma coisa, diga ao modelo qual preferir.

## Tool usage policy

- Use specialized tools instead of bash commands:
  - Read for reading files instead of cat/head/tail
  - Edit for editing instead of sed/awk
  - Grep for searching instead of grep/rg
- You can call multiple tools in a single response. If independent, call in parallel.
- Use the Task tool for file search to reduce context usage.

Diretrizes:

Use "instead of" (em vez de) para expressar prioridade (A em vez de B)
Explique por que preferir certas tools ("fornece uma melhor experiência de usuário", "reduz o uso de contexto")
Defina a estratégia de paralelismo (independente → paralelo, dependente → sequencial)
Liste restrições de segurança para o uso de tools (validação de path, checagem de permissões)

A relação crucial entre tools e prompts:

As definições de tools geralmente são injetadas pelo sistema e você não pode editá-las diretamente. As definições de tools do Claude Code têm ~11.438 tokens. Isso significa:

Não repita informações que já estão nas definições das tools
Use o system prompt para orientação estratégica: quando usar cada tool, por que preferir uma à outra, ordem de prioridade
A qualidade da definição da tool impacta diretamente a eficácia do agente — se você está construindo seu próprio agente, invista tempo escrevendo excelentes descrições de tools

3.6 Conhecimento de Domínio — Carregue Sob Demanda, Não Antecipadamente

Objetivo: Fornecer conhecimento especializado que pode faltar nos dados de treinamento do modelo.

O princípio chave: progressive disclosure (divulgação progressiva), não despejos de conhecimento (knowledge dumps).

❌ Paste all 200 API endpoints into the system prompt → token explosion
✅ Give the model a tool to look things up → "Load knowledge when you need it"

Essa estratégia é compartilhada pelo sistema de Skills do Claude Code e pelo middleware de Progressive Disclosure do DeepAgents. Ambos carregam conhecimento sob demanda através de tool calls em vez de pré-carregar tudo.

Abordagens de implementação:

Coloque ponteiros no system prompt: "Use a tool get_api_docs para recuperar a documentação quando necessário"
Use CLAUDE.md / AGENTS.md para contexto do projeto — carregado em runtime, não hardcoded
Use Skills / SKILL.md para descoberta de capacidades — o modelo vê um menu de skills disponíveis e busca as especificações completas sob demanda

3.7 Info do Ambiente — Contexto de Runtime

Objetivo: Dar ao modelo consciência do seu ambiente de execução.

<env>
Working directory: /Users/fengliu/Desktop/tfm/vibecom
Is directory a git repo: true
Platform: darwin
Today's date: 2026-03-21
</env>
You are powered by the model named Claude Opus 4.6.

Diretrizes:

Gere dinamicamente, nunca faça hardcode
Inclua: diretório de trabalho, plataforma, data, nome do modelo, status do git
Use formato estruturado (tags XML ou blocos de código) para facilitar o parsing
A data importa — o modelo precisa saber o "agora" para julgar o frescor das informações

3.8 Lembretes — O Reforço Final

Objetivo: Reafirmar as regras mais críticas no final do prompt.

O Claude Code repete sua restrição de segurança e o requisito do TodoWrite no final:

IMPORTANT: Assist with defensive security tasks only. [repeated]
IMPORTANT: Always use the TodoWrite tool to plan and track tasks. [repeated]

Diretrizes:

Repita apenas 2 ou 3 das regras mais críticas — não duplique tudo
Explore o viés de recência — o modelo lembra do conteúdo recente com mais força
Melhores candidatos: restrições de segurança, regras violadas com mais frequência, lembretes do workflow principal

4. Orçamento de Tokens e Gestão de Contexto

Referência de Alocação de Orçamento

Seção	Tokens Recomendados	Notas
Identidade + Segurança	200-500	Conciso, mas inegociável
Tom e Estilo	300-800	Regras devem ser específicas, mas não enrole
Workflow Principal	500-2,000	Seção mais importante, vale o investimento
Política de Uso de Tools	300-1,000	Depende do número de tools
Conhecimento de Domínio	0-1,000	Carregamento sob demanda é preferível
Info do Ambiente	100-300	Gerado dinamicamente
Lembretes	100-300	Repita apenas o essencial
Seu total	1,500-6,000
Definições de Tools (sistema)	5,000-15,000	Fora do seu controle

Curva de Degradação de Contexto

Testes da comunidade (Reddit u/CodeMonke_) mapearam a degradação real da aderência:

< 80K tokens: A aderência ao prompt permanece estável
80K - 120K tokens: O seguimento de instruções começa a degradar
> 120K tokens: Degradação significativa — o modelo "esquece" as instruções iniciais
> 180K tokens: Degradação severa

Sua janela de contexto de 200K ≠ 200K de contexto efetivo. Planeje de acordo.

Estratégias de mitigação:

Mantenha seu system prompt enxuto (< 6.000 tokens para a sua parte)
Use sumarização para comprimir o histórico da conversa (DeepAgents aciona em ~80K caracteres)
Coloque regras críticas em ambas as extremidades do prompt (atenção em forma de U)
Injete tags <system-reminder> no meio da conversa (mais sobre isso na seção 8)

5. Princípios de Escrita

5.1 Dê Princípios, Não Procedimentos

❌ "Step 1: Read the file. Step 2: Find the bug. Step 3: Fix it. Step 4: Run tests."
✅ "Always understand existing code before modifying it. Verify your changes work."

Princípios generalizam. Procedimentos só podem ser seguidos mecanicamente. Quando o modelo encontra uma situação que você não antecipou, os princípios guiam a decisão certa. Procedimentos não.

Exceção: Quando o output é consumido por máquinas (comunicação inter-agentes, formatos de API), defina schemas estritos.

5.2 Use Linguagem Absoluta para Restrições Rígidas

Força	Linguagem	Usar Para
Proibição absoluta	`NEVER`, `MUST NOT`	Segurança, operações irreversíveis
Requisito forte	`ALWAYS`, `MUST`	Regras do workflow principal
Recomendação	`recommended`, `prefer`	Boas práticas com exceções
Sugestão	`consider`, `you may`	Otimizações opcionais

Exemplos do Claude Code:

NEVER update the git config — proibição absoluta
ALWAYS prefer editing an existing file — forte, mas existem exceções
The following steps are recommended — workflow sugerido

5.3 Use Exemplos em Vez de Explicações

## Code References

When referencing specific functions or pieces of code include
the pattern `file_path:line_number`.

<example>
user: Where are errors from the client handled?
assistant: Clients are marked as failed in the `connectToServer`
function in src/services/process.ts:712.
</example>

Um exemplo ensina mais do que 100 palavras de explicação:

Modelos aprendem padrões a partir de exemplos de forma mais confiável do que de descrições abstratas
Envolva com tags <example> para separar das regras
Forneça exemplos tanto positivos ("faça isso") quanto negativos ("não faça isso")
Use exemplos reais e específicos — não placeholders como "foo/bar"

5.4 Restrições Bidirecionais

✅ "Use dedicated tools: Read for reading files, Edit for editing files."
✅ "Do NOT use bash for file operations (cat, head, tail, sed, awk)."

Dizer apenas "faça isso" → o modelo não sabe quando NÃO fazer. Dizer apenas "não faça isso" → o modelo não conhece a alternativa. Bidirecional → claro e inequívoco.

5.5 Explique o Porquê, Não Apenas o Quê

❌ "Don't use git commit --amend."
✅ "Avoid git commit --amend. ONLY use --amend when either
   (1) user explicitly requested amend OR
   (2) adding edits from pre-commit hook.
   Reason: amending may overwrite others' commits."

Explicar o porquê permite que o modelo faça julgamentos corretos em edge cases. O protocolo de segurança do git do Claude Code é uma masterclass — toda regra implica sua justificativa.

5.6 Estrutura Acima de Prosa

Cabeçalhos Markdown (##, ###) — modelos reconhecem hierarquia
Listas com marcadores em vez de parágrafos — cada regra testável independentemente
Tags XML para conteúdo especial: <example>, <env>, <system-reminder>
Tabelas para comparações e mapeamentos
Nunca despeje texto não estruturado — prompts estruturados superam consistentemente a prosa em linguagem natural em testes de aderência

6. Antipadrões Que Desperdiçam Seus Tokens

Prompt Chains Disfarçados de Agentes

"First call tool A to get data.
Then call tool B with the result.
Then format the output as JSON.
Then save to file."

Isso não é um prompt de agente — é um script de pipeline. O modelo vai executar mecanicamente e perder sua capacidade de planejamento autônomo.

A solução: Diga ao modelo o objetivo e as restrições. Deixe-o decidir os passos.

Engenharia de Bajulação (Flattery Engineering)

"You are an EXTREMELY TALENTED and INCREDIBLY EXPERIENCED
senior software engineer with 20 years of experience..."

Elogios e superlativos não melhoram a qualidade do output. O modelo não tem um ego para ser inflado. Guarde esses 15 tokens para uma regra real.

Despejos de Conhecimento (Knowledge Dumps)

"Here is the complete API documentation for our 200 endpoints..."

Isso devora sua janela de contexto e acelera o context rot (apodrecimento do contexto). Substitua por carregamento sob demanda:

"Use the get_api_docs tool to retrieve API documentation when needed."

Repetir Descrições de Tools

Se a definição da tool já diz "A tool Read lê um arquivo do sistema de arquivos", não diga isso de novo no seu system prompt. Adicione apenas orientações estratégicas que a definição da tool não cobre — quando usá-la, por que preferi-la, ordem de prioridade.

Falta de Tratamento de Falhas

Sem orientação explícita, os modelos vão tentar novamente tool calls que falharam em um loop infinito. Sempre inclua:

"If a tool call is denied, do not re-attempt the exact same call.
Think about why it was denied and adjust your approach."

Ignorar a Degradação da Janela de Contexto

Janela de contexto de 200K ≠ 200K de contexto efetivo. Testes no mundo real mostram a degradação começando em 80K. Você precisa de uma estratégia de sumarização.

7. Pontos de Injeção e Prioridade

Os Três Métodos de Customização do Claude Code

Método	Substitui	Posicionamento	Melhor Para
Output Styles	Seções "Tone and style" + "Doing tasks"	Logo antes das definições de tools	Mudar o estilo de interação
--append-system-prompt	Nada (aditivo)	Após o output style, antes das definições de tools	Adicionar comportamentos específicos
--system-prompt	Todo o system prompt	Mantém definições de tools + uma linha de identidade	Customização completa (opção nuclear)

Se você usar múltiplos: Output Style → Append Prompt → Tool Definitions

Hierarquia de Instruções

O Claude é treinado especificamente com uma hierarquia de instruções:

1. User's explicit instructions (CLAUDE.md, direct requests)  ← Prioridade mais alta
2. Custom system prompt additions                               ← Alta
3. Default system prompt                                        ← Média
4. Tool definitions                                             ← Nível de referência

Isso significa:

Regras do CLAUDE.md sobrescrevem o comportamento padrão do system prompt
Pedidos diretos do usuário sobrescrevem tudo
Seu prompt customizado sobrescreve o prompt padrão

Mecanismos de Injeção Dinâmica

<system-reminder> — injetar em qualquer mensagem no meio da conversa para lembrar o modelo de regras críticas
CLAUDE.md / AGENTS.md — carregados em runtime a partir de arquivos, anexados ao system prompt
Skills / SKILL.md — carregados sob demanda via tool calls, zero impacto no system prompt

8. Injeção no Meio da Conversa — A Arma Secreta

O system prompt aparece apenas uma vez, bem no início do array de mensagens. Mas os LLMs aceitam o array completo de mensagens (alternando mensagens de user / assistant / tool) como input, e você pode injetar prompts nas mensagens do usuário e nos resultados das tools também. O Claude Code usa essa técnica pesadamente em produção.

Por Que É Necessário

Combatendo o context rot. À medida que as conversas ficam mais longas, a aderência do modelo às instruções do system prompt degrada (notável a partir de 80K+ tokens). Injetar lembretes no meio da conversa = atualizar as regras via viés de recência.

O modelo mental:

System prompt = a constituição (estabelecida uma vez, autoridade de longo prazo)
Lembretes na mensagem do usuário = memorandos (enviados periodicamente, mantendo a aplicação das regras)

Três Pontos de Injeção no Array de Mensagens

Array de Mensagens:
┌─────────────────────────────────────┐
│ System Prompt                       │ ← Aparece uma vez, efeito de primazia
│   (identidade, segurança, workflow...)│
├─────────────────────────────────────┤
│ Mensagem do Usuário 1               │
│ Mensagem do Assistente 1            │
│ Mensagem do Usuário 2 + <system-reminder>│ ← Injeção no meio da conversa
│ Mensagem do Assistente 2            │
│ Resultado da Tool + <system-reminder>│ ← Pode injetar nos resultados das tools também
│ ...                                 │
│ Mensagem do Usuário N + <system-reminder>│ ← Última mensagem, recência mais forte
└─────────────────────────────────────┘

Localização	Vantagem	Desvantagem
System prompt	Efeito de primazia, lido primeiro	Aparece uma vez, "esquecido" em conversas longas
Injeção na mensagem do usuário	Viés de recência, atualização periódica	Cada injeção custa tokens
Injeção no resultado da tool	Ponto de injeção mais natural	Só funciona quando tools são chamadas

Como o Claude Code Realmente Usa Isso

Pré-requisito — declare as tags no system prompt:

Tool results and user messages may include <system-reminder> tags.
<system-reminder> tags contain useful information and reminders.
They are automatically added by the system, and bear no direct
relation to the specific tool results or user messages in which they appear.

Esse passo é crítico: ele diz ao modelo que essas tags são injetadas pelo sistema, não fala do usuário.

Uso 1: Lembretes Comportamentais (atualização periódica de regras)

<system-reminder>
The task tools haven't been used recently. If you're working on tasks
that would benefit from tracking progress, consider using TaskCreate...
</system-reminder>

O Claude Code usa isso para lembrar o modelo de planejar com o TodoWrite — porque modelos tendem a "esquecer" o planejamento e apenas começar a codar.

Uso 2: Troca de Modo (Plan Mode)

<system-reminder>
Plan mode is active. The user indicated that they do not want you to
execute yet -- you MUST NOT make any edits, run any non-readonly tools,
or otherwise make any changes to the system.
</system-reminder>

O Plan mode (modo de planejamento) não é implementado no system prompt. É uma tag injetada na próxima mensagem do usuário. Isso permite que você alterne modos dinamicamente sem modificar o system prompt. Brilhante.

Uso 3: Notificações de Alteração de Arquivo

<system-reminder>
Note: /path/to/file.ts was modified, either by the user or by a linter.
This change was intentional, so make sure to take it into account.
</system-reminder>

Quando um processo externo (linter, formatador, edição manual) modifica um arquivo, o sistema notifica o modelo via lembrete — evitando decisões baseadas em conteúdos de arquivos desatualizados.

Uso 4: Contexto Dinâmico (datas, regras do projeto)

<system-reminder>
Today's date is 2026-03-21.
Current branch: dev
claudeMd: [CLAUDE.md content injected here]
</system-reminder>

O contexto de runtime (data, status do git, regras do projeto) é injetado via mensagens do usuário, não hardcoded no system prompt.

Diretrizes de Escrita para Lembretes

Envolva em tags XML (<system-reminder>) — o modelo consegue distinguir a injeção do sistema da fala do usuário
Pré-declare as tags no system prompt — caso contrário, o modelo pode tentar responder ao lembrete
Não injete em todas as mensagens — cada injeção custa tokens, injete apenas quando necessário
Mantenha curto — um lembrete não é um segundo system prompt, apenas 1 ou 2 regras críticas
Não contradiga o system prompt — lembretes complementam e reforçam, eles não sobrescrevem
Use para alternância dinâmica — plan mode, readonly mode, feature flags

Quando Usar System Prompt vs. Lembrete na Mensagem do Usuário

Cenário	System Prompt	Lembrete na Mensagem do Usuário
Definição de papel	✅	❌
Restrições de segurança	✅ Primeira declaração	✅ Repetição periódica
Metodologia de workflow	✅	❌
Troca de modo (plan mode)	❌	✅
Notificações de alteração de arquivo	❌	✅
Data / info do ambiente	✅ Valor inicial	✅ Valor atualizado
Correção comportamental	❌	✅
Lembretes de uso de tools	✅ Definição da regra	✅ Empurrõezinhos na execução (execution nudges)

9. Prompt Cache — Economize 90% em Tokens Repetidos

O prompt caching da Anthropic permite que você faça cache do prefixo estático do seu array de mensagens. Quando requisições subsequentes compartilham o mesmo prefixo, elas atingem o cache — economizando dinheiro e reduzindo a latência.

Para agentes, isso importa muito: você está reenviando o system prompt + definições de tools em cada chamada de LLM dentro de uma conversa.

Números Chave

Métrica	Valor
Custo de cache hit	10% do preço normal (90% de economia)
Custo de escrita no cache	125% do preço normal (25% de prêmio na primeira escrita)
TTL do cache	5 minutos (expira se não houver requisições)
Tamanho mínimo cacheável	1.024 tokens (Claude 3.5+)
Granularidade do cache	Prefix matching — do início até um breakpoint marcado
Máximo de breakpoints	4

Como Isso Muda o Design do Prompt

Princípio central: conteúdo estático primeiro, conteúdo dinâmico por último.

✅ Layout amigável ao cache:
  System prompt (estático)      ← Breakpoint de cache 1
  Definições de tools (estático)   ← Breakpoint de cache 2
  CLAUDE.md / regras do projeto   ← Breakpoint de cache 3 (muda ocasionalmente)
  Histórico da conversa         ← Breakpoint 4 para rolling window

❌ Layout que destrói o cache:
  System prompt
  TIMESTAMP DINÂMICO            ← Muda a cada requisição, tudo depois = cache miss
  Definições de tools
  Histórico da conversa

A armadilha sobre a qual ninguém te avisa: Se você colocar um timestamp dinâmico no meio do seu system prompt, tudo depois dele se torna um cache miss. Em. Toda. Requisição. Um timestamp no lugar errado e você está pagando o preço cheio em milhares de tokens.

Uso da API

const response = await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  system: [
    {
      type: "text",
      text: "You are a startup advisor...",
      cache_control: { type: "ephemeral" }  // ← marca um breakpoint de cache
    }
  ],
  messages: [...]
});

Estratégia de Múltiplos Breakpoints

Breakpoint 1: System prompt           ← Quase nunca muda
Breakpoint 2: Definições de tools         ← Quase nunca muda
Breakpoint 3: Regras do projeto / CLAUDE.md ← Muda ocasionalmente
Breakpoint 4: Primeiras N mensagens do histórico  ← Cache de rolling window

Mesmo quando o histórico da conversa muda, os 3 primeiros breakpoints ainda dão hit. Uma conversa de 10 turnos economiza cerca de 40-60% nos custos de tokens de input.

Recomendações de Design

Sem valores dinâmicos de alta frequência no system prompt — a data está ok (muda diariamente), timestamps precisos não
Coloque o contexto dinâmico (status do git, etc.) em injeções na mensagem do usuário — não no system prompt, ou você vai destruir o cache
Mantenha as definições de tools estáveis — não adicione/remova tools dinamicamente em runtime
Use rolling window para o histórico da conversa — faça cache das primeiras N mensagens, apenas a mensagem mais recente é um cache miss

10. O Checklist

Depois de escrever seu system prompt, revise-o com este checklist:

Estrutura

Identidade está bem no topo?
Restrições de segurança marcadas com IMPORTANT e repetidas no final?
Separação clara de seções com cabeçalhos?
Exemplos envolvidos em tags <example>?

Orçamento de Tokens

Sua parte tem < 6.000 tokens?
Não está repetindo informações que já estão nas definições das tools?
Conhecimento de domínio carregado sob demanda, não pré-carregado?
Sem lore verboso ou história de fundo de personagem?

Qualidade das Regras

Toda regra é testável como verdadeira/falsa?
Restrições rígidas usam linguagem absoluta (NEVER/MUST)?
Sugestões leves usam linguagem de recomendação (recommended/prefer)?
Regras críticas explicam o porquê, não apenas o quê?
Restrições bidirecionais (faça isso + não faça aquilo)?

Comportamento do Agente

Princípios fornecidos, não procedimentos passo a passo rígidos?
Tratou o cenário de "tool call negada"?
Tratou a estratégia de "obstáculo encontrado" (não tentar forçar a barra repetindo)?
Estratégia de gestão de contexto em vigor (limite de sumarização)?

O Que NÃO Fazer

Sem bajulação ou adjetivos superlativos?
Sem declarações redundantes de "você é uma IA útil"?
Não está escrito como um prompt chain?
Sem over-engineering (features que ninguém pediu)?

Se Eu Estivesse Começando Hoje

Aqui está exatamente o que eu faria:

Comece com identidade + segurança nas primeiras 3 linhas. Duas frases para quem o agente é. Restrições rígidas com NEVER/MUST. Repita as regras de segurança no final.
Escreva seu workflow principal como princípios, não passos. Máximo de 4 a 5 bullet points. Use "recommended" e "prefer" para regras leves, "NEVER" e "MUST" para as rígidas.
Orce 1.500-6.000 tokens para a sua parte. Definições de tools vão adicionar mais 5.000-15.000. Se você passar de 6K, provavelmente está despejando conhecimento que deveria ser carregado sob demanda.
Estruture tudo. Cabeçalhos Markdown, listas com marcadores, tags XML para exemplos. Um prompt estruturado supera a prosa em linguagem natural todas as vezes.
Incorpore lembretes no meio da conversa desde o primeiro dia. Declare <system-reminder> no seu system prompt. Injete lembretes para regras críticas, trocas de modo e atualizações de contexto.
Projete para o cache. Conteúdo estático primeiro, conteúdo dinâmico por último. Nunca coloque valores que mudam no corpo do seu system prompt.

A ironia de todo esse trabalho? Os melhores system prompts são curtos. As instruções customizadas do Claude Code (excluindo definições de tools) são surpreendentemente concisas. Cada linha conquista o seu lugar.

Eu costumava pensar que prompt engineering era sobre encontrar truques espertos. Hoje eu acho que é sobre disciplina — dizer menos, dizer com precisão e confiar no modelo para descobrir o resto. O modelo é mais inteligente que o seu prompt. Projete o ambiente, não o comportamento.

Referências

Fonte	Insight Principal
Claude Code v2.0.14 System Prompt	Referência completa de estrutura de prompt de agente em produção
Reddit: Understanding Claude Code's 3 System Prompt Methods	Mergulho profundo em Output Styles / --append / --system-prompt, dados do mundo real sobre context rot
shareAI-lab/learn-claude-code	Filosofia "O modelo é o agente", metodologia de harness engineering
Anthropic Prompt Engineering Docs	Melhores práticas oficiais de prompt
DeepAgents Framework	Middleware de sumarização, progressive disclosure de skills