Os prompts do sistema definem o comportamento, capacidades e estilo de resposta do Claude. O Claude Agent SDK fornece três maneiras de personalizar prompts do sistema: usando estilos de saída (configurações persistentes baseadas em arquivos), anexando ao prompt do Claude Code, ou usando um prompt totalmente personalizado.

​
Entendendo prompts do sistema

Um prompt do sistema é o conjunto de instruções inicial que molda como o Claude se comporta ao longo de uma conversa.
Comportamento padrão: O Agent SDK usa um prompt do sistema vazio por padrão para máxima flexibilidade. Para usar o prompt do sistema do Claude Code (instruções de ferramentas, diretrizes de código, etc.), especifique systemPrompt: { preset: "claude_code" } em TypeScript ou system_prompt="claude_code" em Python.
O prompt do sistema do Claude Code inclui:
  • Instruções de uso de ferramentas e ferramentas disponíveis
  • Diretrizes de estilo e formatação de código
  • Configurações de tom de resposta e verbosidade
  • Instruções de segurança e proteção
  • Contexto sobre o diretório de trabalho atual e ambiente

​
Métodos de modificação

​
Método 1: Estilos de saída (configurações persistentes)

Estilos de saída são configurações salvas que modificam o prompt do sistema do Claude. Eles são armazenados como arquivos markdown e podem ser reutilizados em sessões e projetos.

​
Criando um estilo de saída

import { writeFile, mkdir } from 'fs/promises'
import { join } from 'path'
import { homedir } from 'os'

async function createOutputStyle(name: string, description: string, prompt: string) {
  // Nível do usuário: ~/.claude/output-styles
  // Nível do projeto: .claude/output-styles
  const outputStylesDir = join(homedir(), '.claude', 'output-styles')
  
  await mkdir(outputStylesDir, { recursive: true })
  
  const content = `---
name: ${name}
description: ${description}
---

${prompt}`
  
  const filePath = join(outputStylesDir, `${name.toLowerCase().replace(/\s+/g, '-')}.md`)
  await writeFile(filePath, content, 'utf-8')
}

// Exemplo: Criar um especialista em revisão de código
await createOutputStyle(
  'Code Reviewer',
  'Assistente completo de revisão de código',
  `Você é um especialista em revisão de código.

Para cada submissão de código:
1. Verifique bugs e problemas de segurança
2. Avalie performance
3. Sugira melhorias
4. Classifique a qualidade do código (1-10)`
)

​
Usando estilos de saída

Uma vez criados, ative estilos de saída via:
  • CLI: /output-style [nome-do-estilo]
  • Configurações: .claude/settings.local.json
  • Criar novo: /output-style:new [descrição]

​
Método 2: Usando systemPrompt com append

Você pode usar o preset Claude Code com uma propriedade append para adicionar suas instruções personalizadas enquanto preserva toda a funcionalidade integrada. 
import { query } from "@anthropic-ai/claude-agent-sdk"

const messages = []

for await (const message of query({
  prompt: "Me ajude a escrever uma função Python para calcular números fibonacci",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: "Sempre inclua docstrings detalhadas e type hints no código Python."
    }
  }
})) {
  messages.push(message)
  if (message.type === 'assistant') {
    console.log(message.message.content)
  }
}

​
Método 3: Prompts de sistema personalizados

Você pode fornecer uma string personalizada como systemPrompt para substituir completamente o padrão por suas próprias instruções. 
import { query } from "@anthropic-ai/claude-agent-sdk"

const customPrompt = `Você é um especialista em codificação Python.
Siga estas diretrizes:
- Escreva código limpo e bem documentado
- Use type hints para todas as funções
- Inclua docstrings abrangentes
- Prefira padrões de programação funcional quando apropriado
- Sempre explique suas escolhas de código`

const messages = []

for await (const message of query({
  prompt: "Crie um pipeline de processamento de dados",
  options: {
    systemPrompt: customPrompt
  }
})) {
  messages.push(message)
  if (message.type === 'assistant') {
    console.log(message.message.content)
  }
}

​
Comparação das três abordagens

RecursoEstilos de SaídasystemPrompt com appendsystemPrompt Personalizado
Persistência✅ Salvos como arquivos❌ Apenas sessão❌ Apenas sessão
Reutilização✅ Entre projetos❌ Duplicação de código❌ Duplicação de código
Gerenciamento✅ CLI + arquivos⚠️ No código⚠️ No código
Ferramentas padrão✅ Preservadas✅ Preservadas❌ Perdidas (a menos que incluídas)
Segurança integrada✅ Mantida✅ Mantida❌ Deve ser adicionada
Contexto do ambiente✅ Automático✅ Automático❌ Deve ser fornecido
Nível de personalização⚠️ Substituir padrão⚠️ Apenas adições✅ Controle completo
Controle de versão✅ Sim✅ Com código✅ Com código
Descoberta✅ /output-style❌ Não descobrível❌ Não descobrível
Nota: “Com append” significa usar systemPrompt: { type: "preset", preset: "claude_code", append: "..." } em TypeScript ou system_prompt={"type": "preset", "preset": "claude_code", "append": "..."} em Python.

​
Casos de uso e melhores práticas

​
Quando usar estilos de saída

Melhor para:
  • Mudanças de comportamento persistentes entre sessões
  • Configurações compartilhadas em equipe
  • Assistentes especializados (revisor de código, cientista de dados, DevOps)
  • Modificações complexas de prompt que precisam de versionamento
Exemplos:
  • Criar um assistente dedicado de otimização SQL
  • Construir um revisor de código focado em segurança
  • Desenvolver um assistente de ensino com pedagogia específica

​
Quando usar systemPrompt com append

Melhor para:
  • Adicionar padrões ou preferências específicas de codificação
  • Personalizar formatação de saída
  • Adicionar conhecimento específico de domínio
  • Modificar verbosidade de resposta
  • Aprimorar o comportamento padrão do Claude Code sem perder instruções de ferramentas

​
Quando usar systemPrompt personalizado

Melhor para:
  • Controle completo sobre o comportamento do Claude
  • Tarefas especializadas de sessão única
  • Testar novas estratégias de prompt
  • Situações onde ferramentas padrão não são necessárias
  • Construir agentes especializados com comportamento único

​
Combinando abordagens

Você pode combinar esses métodos para máxima flexibilidade:

​
Exemplo: Estilo de saída com adições específicas da sessão

import { query } from "@anthropic-ai/claude-agent-sdk"

// Assumindo que o estilo de saída "Code Reviewer" está ativo (via /output-style)
// Adicionar áreas de foco específicas da sessão
const messages = []

for await (const message of query({
  prompt: "Revise este módulo de autenticação",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: `
        Para esta revisão, priorize:
        - Conformidade OAuth 2.0
        - Segurança de armazenamento de token
        - Gerenciamento de sessão
      `
    }
  }
})) {
  messages.push(message)
}

​
Veja também