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

​
Entendendo prompts do sistema

Um prompt do sistema é o conjunto inicial de instruções que molda como o Claude se comporta ao longo de uma conversa. O prompt do sistema padrão 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 appendSystemPrompt

A opção appendSystemPrompt adiciona suas instruções personalizadas ao prompt do sistema padrão enquanto preserva toda a funcionalidade integrada. 
import { query } from "@anthropic-ai/claude-code"

const messages = []

for await (const message of query({
  prompt: "Me ajude a escrever uma função Python para calcular números fibonacci",
  options: {
    appendSystemPrompt: "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: Usando customSystemPrompt

A opção customSystemPrompt substitui todo o prompt do sistema padrão por suas instruções personalizadas. 
import { query } from "@anthropic-ai/claude-code"

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: {
    customSystemPrompt: customPrompt
  }
})) {
  messages.push(message)
  if (message.type === 'assistant') {
    console.log(message.message.content)
  }
}

​
Comparação das três abordagens

RecursoEstilos de SaídaappendSystemPromptcustomSystemPrompt
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⚠️ Substitui 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

​
Casos de uso e melhores práticas

​
Quando usar estilos de saída

Melhor para:
  • Mudanças persistentes de comportamento entre sessões
  • Configurações compartilhadas pela 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 appendSystemPrompt

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

​
Quando usar customSystemPrompt

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

​
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-code"

// 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: {
    appendSystemPrompt: `
      Para esta revisão, priorize:
      - Conformidade com OAuth 2.0
      - Segurança de armazenamento de token
      - Gerenciamento de sessão
    `
  }
})) {
  messages.push(message)
}

​
Veja também