Skip to main content
System prompts define Claude’s behavior, capabilities, and response style. The Claude Agent SDK provides three ways to customize system prompts: using output styles (persistent, file-based configurations), appending to Claude Code’s prompt, or using a fully custom prompt.

​
Understanding system prompts

A system prompt is the initial instruction set that shapes how Claude behaves throughout a conversation.
Default behavior: The Agent SDK uses a minimal system prompt by default. It contains only essential tool instructions but omits Claude Code’s coding guidelines, response style, and project context. To include the full Claude Code system prompt, specify systemPrompt: { type: "preset", preset: "claude_code" } in TypeScript or system_prompt={"type": "preset", "preset": "claude_code"} in Python.
Claude Code’s system prompt includes:
  • Tool usage instructions and available tools
  • Code style and formatting guidelines
  • Response tone and verbosity settings
  • Security and safety instructions
  • Context about the current working directory and environment

​
Methods of modification

​
Method 1: CLAUDE.md files (project-level instructions)

CLAUDE.md files provide project-specific context and instructions that are automatically read by the Agent SDK when it runs in a directory. They serve as persistent “memory” for your project.

​
How CLAUDE.md works with the SDK

Location and discovery:
  • Project-level: CLAUDE.md or .claude/CLAUDE.md in your working directory
  • User-level: ~/.claude/CLAUDE.md for global instructions across all projects
CLAUDE.md files are read when the corresponding setting source is enabled: 'project' for project-level CLAUDE.md and 'user' for ~/.claude/CLAUDE.md. With default query() options both sources are enabled, so CLAUDE.md loads automatically. If you set settingSources (TypeScript) or setting_sources (Python) explicitly, include the sources you need. CLAUDE.md loading is controlled by setting sources, not by the claude_code preset. Content format: CLAUDE.md files use plain markdown and can contain:
  • Coding guidelines and standards
  • Project-specific context
  • Common commands or workflows
  • API conventions
  • Testing requirements

​
Example CLAUDE.md

# Project Guidelines

## Code Style

- Use TypeScript strict mode
- Prefer functional components in React
- Always include JSDoc comments for public APIs

## Testing

- Run `npm test` before committing
- Maintain >80% code coverage
- Use jest for unit tests, playwright for E2E

## Commands

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

​
Using CLAUDE.md with the 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

​
When to use CLAUDE.md

Best for:
  • Team-shared context - Guidelines everyone should follow
  • Project conventions - Coding standards, file structure, naming patterns
  • Common commands - Build, test, deploy commands specific to your project
  • Long-term memory - Context that should persist across all sessions
  • Version-controlled instructions - Commit to git so the team stays in sync
Key characteristics:
  • ✅ Persistent across all sessions in a project
  • ✅ Shared with team via git
  • ✅ Automatic discovery (no code changes needed)
  • ⚠️ Not loaded if you pass settingSources: []

​
Method 2: Output styles (persistent configurations)

Output styles are saved configurations that modify Claude’s system prompt. They’re stored as markdown files and can be reused across sessions and projects.

​
Creating an output style

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)`
);

​
Using output styles

Once created, activate output styles via:
  • CLI: /output-style [style-name]
  • Settings: .claude/settings.local.json
  • Create new: /output-style:new [description]
Note for SDK users: Output styles are loaded when you include settingSources: ['user'] or settingSources: ['project'] (TypeScript) / setting_sources=["user"] or setting_sources=["project"] (Python) in your options.

​
Method 3: Using systemPrompt with append

You can use the Claude Code preset with an append property to add your custom instructions while preserving all built-in functionality. 
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);
  }
}

​
Improve prompt caching across users and machines

By default, two sessions that use the same claude_code preset and append text still cannot share a prompt cache entry if they run from different working directories. This is because the preset embeds per-session context in the system prompt ahead of your append text: the working directory, platform and OS version, current date, git status, and auto-memory paths. Any difference in that context produces a different system prompt and a cache miss. To make the system prompt identical across sessions, set excludeDynamicSections: true in TypeScript or "exclude_dynamic_sections": True in Python. The per-session context moves into the first user message, leaving only the static preset and your append text in the system prompt so identical configurations share a cache entry across users and machines.
excludeDynamicSections requires @anthropic-ai/claude-agent-sdk v0.2.98 or later, or claude-agent-sdk v0.1.58 or later for Python. It applies only to the preset object form and has no effect when systemPrompt is a string.
The following example pairs a shared append block with excludeDynamicSections so a fleet of agents running from different directories can reuse the same cached system prompt: 
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
    }
  }
})) {
  // ...
}
Tradeoffs: the working directory, git status, and memory location still reach Claude, but as part of the first user message rather than the system prompt. Instructions in the user message carry marginally less weight than the same text in the system prompt, so Claude may rely on them less strongly when reasoning about the current directory or auto-memory paths. Enable this option when cross-session cache reuse matters more than maximally authoritative environment context. For the equivalent flag in non-interactive CLI mode, see --exclude-dynamic-system-prompt-sections.

​
Method 4: Custom system prompts

You can provide a custom string as systemPrompt to replace the default entirely with your own instructions. 
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);
  }
}

​
Comparison of all four approaches

FeatureCLAUDE.mdOutput StylessystemPrompt with appendCustom systemPrompt
PersistencePer-project fileSaved as filesSession onlySession only
ReusabilityPer-projectAcross projectsCode duplicationCode duplication
ManagementOn filesystemCLI + filesIn codeIn code
Default toolsPreservedPreservedPreservedLost (unless included)
Built-in safetyMaintainedMaintainedMaintainedMust be added
Environment contextAutomaticAutomaticAutomaticMust be provided
Customization levelAdditions onlyReplace defaultAdditions onlyComplete control
Version controlWith projectYesWith codeWith code
ScopeProject-specificUser or projectCode sessionCode session
Note: “With append” means using systemPrompt: { type: "preset", preset: "claude_code", append: "..." } in TypeScript or system_prompt={"type": "preset", "preset": "claude_code", "append": "..."} in Python.

​
Use cases and best practices

​
When to use CLAUDE.md

Best for:
  • Project-specific coding standards and conventions
  • Documenting project structure and architecture
  • Listing common commands (build, test, deploy)
  • Team-shared context that should be version controlled
  • Instructions that apply to all SDK usage in a project
Examples:
  • “All API endpoints should use async/await patterns”
  • “Run npm run lint:fix before committing”
  • “Database migrations are in the migrations/ directory”
CLAUDE.md files load when the project setting source is enabled, which it is for default query() options. If you set settingSources (TypeScript) or setting_sources (Python) explicitly, include 'project' to keep loading project-level CLAUDE.md.

​
When to use output styles

Best for:
  • Persistent behavior changes across sessions
  • Team-shared configurations
  • Specialized assistants (code reviewer, data scientist, DevOps)
  • Complex prompt modifications that need versioning
Examples:
  • Creating a dedicated SQL optimization assistant
  • Building a security-focused code reviewer
  • Developing a teaching assistant with specific pedagogy

​
When to use systemPrompt with append

Best for:
  • Adding specific coding standards or preferences
  • Customizing output formatting
  • Adding domain-specific knowledge
  • Modifying response verbosity
  • Enhancing Claude Code’s default behavior without losing tool instructions

​
When to use custom systemPrompt

Best for:
  • Complete control over Claude’s behavior
  • Specialized single-session tasks
  • Testing new prompt strategies
  • Situations where default tools aren’t needed
  • Building specialized agents with unique behavior

​
Combining approaches

You can combine these methods for maximum flexibility:

​
Example: Output style with session-specific additions

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);
}

​
See also