Modificando prompts do sistema

• Como os prompts do sistema funcionam, com uma tabela de decisão para escolher entre a predefinição, a predefinição com append e um prompt personalizado
• Personalize o comportamento do agente com arquivos CLAUDE.md, estilos de saída, append ou uma string personalizada
• Compare as quatro abordagens por persistência, escopo e o que elas preservam
• Combine abordagens para sobrepor métodos de personalização

​

Como os prompts do sistema funcionam

• Padrão mínimo: quando você não define systemPrompt em TypeScript ou system_prompt em Python, o SDK usa um prompt mínimo que cobre chamadas de ferramentas, mas omite as diretrizes de codificação do Claude Code, estilo de resposta e contexto do projeto. Isso difere de claude -p, que usa o prompt completo do Claude Code por padrão. Se você está migrando da CLI e quer um comportamento correspondente, defina o preset claude_code.
• Preset claude_code: o prompt do sistema completo que a CLI do Claude Code usa, com instruções de uso de ferramentas, diretrizes de estilo e formatação de código, regras de tom de resposta e verbosidade, instruções de segurança e proteção, e contexto sobre o diretório de trabalho e ambiente. Defina systemPrompt: { type: "preset", preset: "claude_code" } em TypeScript ou system_prompt={"type": "preset", "preset": "claude_code"} em Python, opcionalmente com append para adicionar suas próprias instruções no final.
• String personalizada: um prompt que você escreve por conta própria. O SDK envia apenas o que você fornece.

​

Decida sobre um ponto de partida

• Superfície diferente: a saída não é lida em um terminal pela pessoa que a acionou. UIs de chat, consumidores de saída estruturada e automação não-codificação cada uma precisa de um prompt que corresponda a como sua saída é renderizada e revisada. Automação de codificação desatendida, como um job de CI que corrige erros de lint ou revisa diffs, ainda se encaixa no preset porque o trabalho em si é o que o preset foi escrito para.
• Identidade diferente: o agente não deve se apresentar como Claude Code. Um bot de suporte, um assistente de análise de dados ou qualquer agente específico de domínio precisa de seu próprio nome, escopo e persona.
• Modelo de permissão diferente: o agente é executado autonomamente sem um humano aprovando cada etapa, ou opera em um conjunto restrito de recursos. O prompt do Claude Code assume que um humano está no loop com acesso a um conjunto completo de ferramentas.
• Tarefas não-codificação: a maior parte do prompt do Claude Code é orientação de codificação. Para agentes de pesquisa, conteúdo ou operações, essa orientação compete com as instruções que você realmente precisa.

​

Personalizar o comportamento do agente

​

Arquivos CLAUDE.md para instruções em nível de projeto

​

Carregar CLAUDE.md com o SDK

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

const messages = [];

for await (const message of query({
  prompt: "Add a new React component for user profiles",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code" // Use Claude Code's system prompt
    },
    settingSources: ["project"] // Loads CLAUDE.md from project
  }
})) {
  messages.push(message);
}

// Now Claude has access to your project guidelines from CLAUDE.md

​

Estilos de saída para configurações persistentes

​

Criar um estilo de saída

---
name: Code Reviewer
description: Thorough code review assistant
keep-coding-instructions: true
---

You are an expert code reviewer.

For every code submission:
1. Check for bugs and security issues
2. Evaluate performance
3. Suggest improvements
4. Rate code quality (1-10)

​

Ativar um estilo de saída

• CLI: execute /config e selecione um estilo de saída
• Configurações: defina outputStyle em .claude/settings.local.json
• TypeScript SDK: defina outputStyle dentro do objeto settings inline passado para query(), ou aponte settings para um arquivo de configurações que o defina. outputStyle não é um campo Options de nível superior

​

Adicionar à predefinição claude_code

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

const messages = [];

for await (const message of query({
  prompt: "Help me write a Python function to calculate fibonacci numbers",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: "Always include detailed docstrings and type hints in Python code."
    }
  }
})) {
  messages.push(message);
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}

​

Melhorar o cache de prompt entre usuários e máquinas

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

for await (const message of query({
  prompt: "Triage the open issues in this repo",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: "You operate Acme's internal triage workflow. Label issues by component and severity.",
      excludeDynamicSections: true
    }
  }
})) {
  // ...
}

​

Prompts do sistema personalizados

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

const customPrompt = `You are a Python coding specialist.
Follow these guidelines:
- Write clean, well-documented code
- Use type hints for all functions
- Include comprehensive docstrings
- Prefer functional programming patterns when appropriate
- Always explain your code choices`;

const messages = [];

for await (const message of query({
  prompt: "Create a data processing pipeline",
  options: {
    systemPrompt: customPrompt
  }
})) {
  messages.push(message);
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}

​

Comparação das quatro abordagens

​

Casos de uso e melhores práticas

​

Quando usar CLAUDE.md

​

Quando usar estilos de saída

• Mudanças de comportamento persistentes em sessões
• Configurações compartilhadas em equipe
• Assistentes especializados como revisor de código, cientista de dados ou assistente DevOps
• Modificações de prompt complexas que precisam de versionamento

• 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

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

​

Quando usar systemPrompt personalizado

• 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

​

Combinar um estilo de saída com adições específicas da sessão

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

// Assuming "Code Reviewer" output style is active (via /config or settings)
// Add session-specific focus areas
const messages = [];

for await (const message of query({
  prompt: "Review this authentication module",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: `
        For this review, prioritize:
        - OAuth 2.0 compliance
        - Token storage security
        - Session management
      `
    }
  }
})) {
  messages.push(message);
}

​

Veja também

• Estilos de saída: criar, gerenciar e compartilhar estilos de saída para a CLI, incluindo o formato de arquivo e locais de armazenamento
• Como Claude se lembra do seu projeto: o que colocar em CLAUDE.md, onde colocá-lo e como escrever instruções de projeto eficazes
• Referência do SDK TypeScript: o tipo Options completo, incluindo systemPrompt, settingSources e settings
• Referência do SDK Python: o tipo ClaudeAgentOptions completo, incluindo system_prompt e setting_sources
• Configurações: a referência settings.json, incluindo onde estilos de saída e outras configurações são armazenados