Modificando prompts do sistema

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), adicionando ao prompt do Claude Code, ou usando um prompt totalmente personalizado.

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 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: Arquivos CLAUDE.md (instruções em nível de projeto)

Arquivos CLAUDE.md fornecem contexto e instruções específicas do projeto que são lidos automaticamente pelo Agent SDK quando ele é executado em um diretório. Eles servem como "memória" persistente para seu projeto.

Como CLAUDE.md funciona com o SDK

Localização e descoberta:

• Nível de projeto: CLAUDE.md ou .claude/CLAUDE.md no seu diretório de trabalho
• Nível de usuário: ~/.claude/CLAUDE.md para instruções globais em todos os projetos

IMPORTANTE: O SDK só lê arquivos CLAUDE.md quando você configura explicitamente settingSources (TypeScript) ou setting_sources (Python):

• Inclua 'project' para carregar CLAUDE.md em nível de projeto
• Inclua 'user' para carregar CLAUDE.md em nível de usuário (~/.claude/CLAUDE.md)

A predefinição de prompt do sistema claude_code NÃO carrega automaticamente CLAUDE.md - você também deve especificar fontes de configuração.

Formato de conteúdo: Arquivos CLAUDE.md usam markdown simples e podem conter:

• Diretrizes e padrões de codificação
• Contexto específico do projeto
• Comandos ou fluxos de trabalho comuns
• Convenções de API
• Requisitos de teste

Exemplo CLAUDE.md

# Diretrizes do Projeto

## Estilo de Código

- Use modo strict do TypeScript
- Prefira componentes funcionais em React
- Sempre inclua comentários JSDoc para APIs públicas

## Testes

- Execute `npm test` antes de fazer commit
- Mantenha >80% de cobertura de código
- Use jest para testes unitários, playwright para E2E

## Comandos

- Build: `npm run build`
- Dev server: `npm run dev`
- Type check: `npm run typecheck`

Usando CLAUDE.md com o SDK

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

// IMPORTANTE: Você deve especificar settingSources para carregar CLAUDE.md
// A predefinição claude_code sozinha NÃO carrega arquivos CLAUDE.md
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"], // Required to load CLAUDE.md from project
  },
})) {
  messages.push(message);
}

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

Quando usar CLAUDE.md

Melhor para:

• Contexto compartilhado com a equipe - Diretrizes que todos devem seguir
• Convenções do projeto - Padrões de codificação, estrutura de arquivos, padrões de nomenclatura
• Comandos comuns - Comandos de build, teste, deploy específicos do seu projeto
• Memória de longo prazo - Contexto que deve persistir em todas as sessões
• Instruções controladas por versão - Faça commit no git para que a equipe fique sincronizada

Características principais:

• ✅ Persistente em todas as sessões em um projeto
• ✅ Compartilhado com a equipe via git
• ✅ Descoberta automática (sem necessidade de mudanças de código)
• ⚠️ Requer carregamento de configurações via settingSources

Método 2: 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
) {
  // User-level: ~/.claude/output-styles
  // Project-level: .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");
}

// Example: Create a code review specialist
await createOutputStyle(
  "Code Reviewer",
  "Thorough code review assistant",
  `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)`
);

Usando estilos de saída

Uma vez criados, ative estilos de saída via:

• CLI: /output-style [style-name]
• Configurações: .claude/settings.local.json
• Criar novo: /output-style:new [description]

Nota para usuários do SDK: Estilos de saída são carregados quando você inclui settingSources: ['user'] ou settingSources: ['project'] (TypeScript) / setting_sources=["user"] ou setting_sources=["project"] (Python) em suas opções.

Método 3: Usando systemPrompt com append

Você pode usar a predefinição do 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: "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);
  }
}

Método 4: Prompts do sistema personalizados

Você pode fornecer uma string personalizada como systemPrompt para substituir completamente o padrão pelas suas próprias instruções.

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 de todas as quatro abordagens

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 CLAUDE.md

Melhor para:

• Padrões e convenções de codificação específicos do projeto
• Documentação da estrutura e arquitetura do projeto
• Listagem de comandos comuns (build, teste, deploy)
• Contexto compartilhado com a equipe que deve ser controlado por versão
• Instruções que se aplicam a todo o uso do SDK em um projeto

Exemplos:

• "Todos os endpoints de API devem usar padrões async/await"
• "Execute npm run lint:fix antes de fazer commit"
• "Migrações de banco de dados estão no diretório migrations/"

Importante: Para carregar arquivos CLAUDE.md, você deve definir explicitamente settingSources: ['project'] (TypeScript) ou setting_sources=["project"] (Python). A predefinição de prompt do sistema claude_code NÃO carrega automaticamente CLAUDE.md sem essa configuração.

Quando usar estilos de saída

Melhor para:

• Mudanças de comportamento persistentes entre sessões
• Configurações compartilhadas com a equipe
• Assistentes especializados (revisor de código, cientista de dados, DevOps)
• Modificações de prompt complexas que precisam de versionamento

Exemplos:

• Criação de um assistente dedicado de otimização SQL
• Construção de um revisor de código focado em segurança
• Desenvolvimento de um assistente de ensino com pedagogia específica

Quando usar systemPrompt com append

Melhor para:

• Adição de padrões ou preferências de codificação específicas
• Personalização de formatação de saída
• Adição de conhecimento específico do domínio
• Modificação de verbosidade de resposta
• Aprimoramento do 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
• Teste de novas estratégias de prompt
• Situações em que as ferramentas padrão não são necessárias
• Construção de 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";

// Assuming "Code Reviewer" output style is active (via /output-style)
// 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

• Output styles - Documentação completa de estilos de saída
• Guia do SDK TypeScript - Guia completo de uso do SDK
• Guia de configuração - Opções gerais de configuração