Formatação de Prompts de Sistema para Comportamento Consistente do Claude
O parâmetro system é onde você define persona, restrições e formato de saída uma vez para toda a conversa, em vez de repetir instruções a cada turno.
Um prompt de sistema bem estruturado é a única coisa com maior alavancagem que você pode ajustar para obter um comportamento consistente e previsível do Claude.
Resumo
O parâmetro system é um campo de nível superior na requisição, separado do array messages.
Ele se aplica a toda a conversa, não apenas ao primeiro turno, portanto, é o local natural para qualquer coisa que deva permanecer verdadeira em todas as trocas - tom, função, restrições e formato de saída.
Ao contrário de um turno user, o conteúdo system nunca é "respondido" - o Claude o trata como instruções permanentes em vez de algo para responder diretamente.
Como ele fica no início do prompt renderizado, também é o ponto de ancoragem para o cache de prompt: manter o prompt estável e byte a byte idêntico entre as requisições é o que torna o cache eficaz.
Bons prompts de sistema são específicos e estruturados, não discursos motivacionais vagos - "seja prestativo" faz muito menos do que uma descrição concreta de persona, escopo e formato.
Receita
Cartão de receita de referência rápida - pronto para copiar e colar.
import anthropic
client = anthropic.Anthropic()
SYSTEM_PROMPT = """You are a customer support assistant for an e-commerce platform.
Persona: professional, warm, concise.
Scope: order status, returns, and shipping questions only. For anything else, say you can't help with that and suggest contacting a human agent.
Output format: plain sentences, no markdown headers, no bullet lists unless the user asks for a list."""
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=1024,
system=SYSTEM_PROMPT,
messages=[{"role": "user", "content": "Where is my order #4821?"}],
)
print(response.content[0].text)Quando usar isso:
- Qualquer aplicativo onde o Claude precise de uma persona ou voz consistente em todas as respostas.
- Qualquer lugar onde você precise que o Claude permaneça dentro de um escopo definido e recuse previsivelmente solicitações fora do escopo.
- Saída que o código downstream analisa (estrutura semelhante a JSON, um modelo fixo, regras de formatação específicas).
- Conversas com vários turnos, onde repetir instruções em cada turno
userseria um desperdício e inconsistente.
Exemplo de Trabalho
import anthropic
client = anthropic.Anthropic()
SYSTEM_PROMPT = """You are a triage assistant for an internal bug tracker.
Persona:
- Direct and technical. No pleasantries, no "I'd be happy to help."
Constraints:
- Only classify bugs into exactly one of: "critical", "high", "medium", "low".
- Never invent a severity level outside that list.
- If the report doesn't have enough information to classify confidently, ask exactly one clarifying question instead of guessing.
Output format:
- Respond with two lines only:
Severity: <level>
Reason: <one sentence>
- Do not add any other text, headers, or explanation beyond those two lines."""
def triage(report: str) -> str:
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=256,
system=SYSTEM_PROMPT,
messages=[{"role": "user", "content": report}],
)
return response.content[0].text
if __name__ == "__main__":
print(triage("Login button does nothing when clicked on Safari 17. Works fine on Chrome."))
print(triage("Typo in the footer: 'Copyright 2025' should say 'Copyright 2026'."))O que isso demonstra:
- O prompt do sistema é organizado em seções claras - Persona, Restrições, Formato de saída - em vez de um único parágrafo indiferenciado.
- As restrições enumeram explicitamente os valores permitidos (
crítico/alto/médio/baixo), fechando a tendência do modelo de inventar alternativas que soam plausíveis. - A seção de formato de saída especifica a estrutura exata esperada, o que é importante quando o código downstream irá analisar a resposta.
triage()reutiliza a mesma stringSYSTEM_PROMPTcongelada em cada chamada, mantendo o comportamento consistente de chamada para chamada.
Análise Detalhada
Como Funciona
systemé renderizado antes demessagesno prompt que o Claude realmente vê, que é por isso que ele funciona como contexto permanente em vez de um turno ao qual o Claude responde diretamente.- Ele é avaliado a cada requisição - não há memória parcial dele entre as chamadas, então você reenvia o mesmo valor toda vez que deseja o mesmo comportamento.
- O Claude segue instruções explícitas e estruturadas de forma mais confiável do que linguagem vaga ou aspiracional - restrições concretas superam "tente ser preciso".
- Como
systemfica na frente da requisição (antes detoolsna ordem de renderização, ele vem depois detools, mas antes demessages), é a âncora natural para o cache de prompt: uma stringsystemestável e inalterada permite que requisições repetidas reutilizem tokens cacheados em vez de processar o mesmo texto toda vez. - Editar o prompt do sistema no meio da conversa é possível, mas muda o prefixo antes de todo o seu histórico de mensagens, o que muda o comportamento e invalida qualquer cache construído com o prefixo antigo.
Estruturando um Prompt de Sistema
| Seção | Propósito | Exemplo |
|---|---|---|
| Persona | Quem o Claude está interpretando e seu tom | "Você é um assistente jurídico formal." |
| Escopo | Com o que o Claude deve e não deve ajudar | "Responda apenas a perguntas sobre o código deste repositório." |
| Restrições | Regras rígidas que a resposta deve seguir | "Nunca sugira uma severidade fora desta lista fixa." |
| Formato de saída | A forma exata da resposta | "Responda com JSON válido correspondendo a este esquema." |
| Comportamento de fallback | O que fazer quando a requisição não se encaixa | "Se o escopo for incerto, faça uma pergunta esclarecedora." |
Nem todo prompt precisa de todas as cinco seções, mas usar essa estrutura evita que você escreva um único bloco de texto que seja difícil de auditar ou atualizar.
Notas de Python
# Keep system prompts in one place, not inline strings scattered across call sites.
# Loading from a file also makes long prompts easier to review and diff in version control.
from pathlib import Path
SYSTEM_PROMPT = Path("prompts/support_agent.txt").read_text()
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=1024,
system=SYSTEM_PROMPT,
messages=[{"role": "user", "content": "Hi, I need help with a return."}],
)Tratar um prompt de sistema longo como um ativo de texto versionado - em vez de uma string inline - torna muito mais fácil revisar alterações e garantir que a mesma string exata seja usada em todas as implantações.
Armadilhas
- Interpolar valores dinâmicos (timestamps, IDs de usuário, IDs de requisição) diretamente no prompt do sistema. Isso torna o prompt uma string diferente a cada requisição, o que quebra silenciosamente o cache de prompt. Correção: mantenha
systemcongelado e coloque o contexto dinâmico em um turnouserem vez disso, ou em modelos suportados use uma mensagem de sistema no meio da conversa. - Escrever instruções vagas e aspiracionais como "seja preciso e prestativo". Linguagem vaga dá ao Claude pouca coisa para seguir. Correção: declare restrições concretas e um formato de saída específico em vez de encorajamento geral.
- Repetir as mesmas instruções em cada mensagem
userem vez do prompt do sistema. Isso desperdiça tokens e arrisca inconsistência se o texto repetido variar entre os locais de chamada. Correção: mova qualquer coisa que deva valer para toda a conversa parasystemuma vez. - Assumir que o Claude irá "responder" ao prompt do sistema como uma mensagem.
systemnão é um turno ao qual o Claude responde - é um contexto permanente, então não espere uma resposta direta a nada formulado como uma pergunta nele. Correção: formule o conteúdo desystemcomo instruções e fatos, não como uma mensagem aguardando uma resposta. - Alterar o prompt do sistema entre requisições na mesma conversa sem um motivo. Fazer isso muda o comportamento no meio da conversa de maneiras que podem confundir tanto o Claude quanto seus usuários, e invalida qualquer cache de prompt construído com o texto antigo. Correção: mantenha-o estável durante a vida de uma conversa; se você realmente precisar de uma atualização no meio da conversa, consulte a página dedicada a mensagens de sistema no meio da conversa.
- Esquecer a seção de formato de saída para respostas analisadas por máquina. Sem uma especificação de formato explícita, a formulação do Claude pode variar de uma execução para outra, quebrando um analisador downstream. Correção: sempre descreva a forma exata esperada quando o código consumirá a resposta, ou considere saídas estruturadas para garantias rígidas.
Alternativas
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
Saídas estruturadas (output_config.format) | Você precisa de uma forma JSON garantida e analisável em vez de uma resposta formatada com melhor esforço | Uma resposta conversacional de formato livre é aceitável e não precisa de validação de esquema rigorosa |
Instruções repetidas em cada turno user | Uma instrução única se aplica apenas a uma requisição | A instrução deve valer para toda a conversa |
| Mensagens de sistema no meio da conversa (limitado ao modelo) | Uma instrução precisa mudar no meio de uma longa conversa sem reconstruir todo o prompt do sistema | A instrução é conhecida antecipadamente e não muda durante a conversa |
FAQs
Onde o prompt do sistema vai na requisição?
É um parâmetro system de nível superior em client.messages.create(), separado do array messages - não é uma mensagem com um papel.
O Claude responde diretamente ao prompt do sistema?
Não. Ele é tratado como instruções permanentes e contexto para toda a conversa, não um turno ao qual o Claude responde - a resposta real do Claude é gerada em resposta aos turnos user.
Preciso reenviar o prompt do sistema em cada requisição em uma conversa?
Sim. Ao contrário de messages, que acumula turnos, system não é cumulativo - você passa o mesmo valor em cada chamada para manter o comportamento consistente.
Por que mudar o prompt do sistema no meio da conversa é importante para o cache?
O cache de prompt depende de um prefixo estável. Como system é renderizado perto do início do prompt, qualquer alteração nele invalida o cache para tudo o que se segue, forçando um reprocessamento completo na próxima requisição.
Qual é a melhor maneira de estruturar um prompt de sistema longo?
Divida-o em seções claras - persona, escopo, restrições, formato de saída e comportamento de fallback - em vez de um único parágrafo indiferenciado. É mais fácil para você e para o Claude raciocinarem sobre isso.
As regras de formato de saída devem ir no prompt do sistema ou na mensagem do usuário?
Se o formato deve se aplicar a todas as respostas na conversa, coloque-o em system. Se for específico para uma requisição, um turno user é aceitável - mas repetir regras de formato por turno é mais propenso a erros do que defini-las uma vez.
O prompt do sistema pode fazer o Claude se recusar a responder a certos tópicos?
Sim - declarar um escopo explícito e uma instrução de fallback ("se perguntado sobre X, diga que você não pode ajudar com isso") é uma maneira confiável de manter as respostas dentro de um limite definido.
Um prompt de sistema mais longo é sempre melhor?
Não. O comprimento não é o objetivo - a especificidade é. Um prompt curto e precisamente formulado com restrições concretas geralmente supera um prompt longo cheio de encorajamento vago.
Posso carregar o prompt do sistema de um arquivo em vez de uma string inline?
Sim, e é uma boa prática para prompts mais longos - mantê-lo como um ativo de texto separado e versionado facilita a revisão de alterações e garante que a mesma string exata seja usada em todas as implantações.
O que acontece se meu prompt do sistema entrar em conflito com algo que o usuário pergunta?
O Claude geralmente segue as restrições do prompt do sistema em detrimento de uma solicitação conflitante do usuário, que é exatamente por que é o lugar certo para colocar regras rígidas como limites de escopo ou valores de saída proibidos.
Existe um formato rigoroso que o Claude exige para o próprio parâmetro system?
Não - system aceita uma string simples (ou uma lista de blocos de texto para uso avançado como pontos de interrupção de cache); não há sintaxe interna obrigatória, portanto, qualquer estrutura clara e bem organizada em linguagem natural funciona.
Relacionados
- Entendendo Papéis e Turnos na API de Mensagens - como
systemse relaciona com o arraymessages. - Noções Básicas da API de Mensagens - um primeiro exemplo que inclui um prompt
system. - Implementando Mensagens de Sistema no Meio da Conversa no Claude Opus 4.8 - atualizando instruções no meio de uma conversa sem reconstruir
system.
Versões de Stack: Escrito contra a linha de modelos Claude atual em aproximadamente junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5 - e o SDK oficial
anthropicpara Python (última versão 0.x). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.