Modifying system prompts¶

URL: https://platform.claude.com/docs/en/agent-sdk/modifying-system-prompts.md
Retrieved: 2026-01-08T05:11:35.311795+00:00

Modifying system prompts¶

Learn how to customize Claude's behavior by modifying system prompts using three approaches - output styles, systemPrompt with append, and custom system prompts.

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 an empty system prompt by default for maximum flexibility. To use Claude Code's system prompt (tool instructions, code guidelines, etc.), specify systemPrompt: { preset: "claude_code" } in TypeScript or system_prompt="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

IMPORTANT: The SDK only reads CLAUDE.md files when you explicitly configure settingSources (TypeScript) or setting_sources (Python):

Include 'project' to load project-level CLAUDE.md
Include 'user' to load user-level CLAUDE.md (~/.claude/CLAUDE.md)

The claude_code system prompt preset does NOT automatically load CLAUDE.md - you must also specify setting sources.

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¶

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

// IMPORTANT: You must specify settingSources to load CLAUDE.md // The claude_code preset alone does NOT load CLAUDE.md files 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

```python Python
from claude_agent_sdk import query, ClaudeAgentOptions

# IMPORTANT: You must specify setting_sources to load CLAUDE.md
# The claude_code preset alone does NOT load CLAUDE.md files
messages = 

async for message in query(
    prompt="Add a new React component for user profiles",
    options=ClaudeAgentOptions(
        system_prompt={
            "type": "preset",
            "preset": "claude_code"  # Use Claude Code's system prompt
        },
        setting_sources=["project"]  # Required to load CLAUDE.md from project
    )
):
    messages.append(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)
⚠️ Requires loading settings via 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¶

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

```python Python
from pathlib import Path

async def create_output_style(name: str, description: str, prompt: str):
    # User-level: ~/.claude/output-styles
    # Project-level: .claude/output-styles
    output_styles_dir = Path.home() / '.claude' / 'output-styles'

    output_styles_dir.mkdir(parents=True, exist_ok=True)

    content = f"""---
name: {name}
description: {description}
---

{prompt}"""

    file_name = name.lower().replace(' ', '-') + '.md'
    file_path = output_styles_dir / file_name
    file_path.write_text(content, encoding='utf-8')

# Example: Create a code review specialist
await create_output_style(
    '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.

```typescript TypeScript 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); } }

```python Python
from claude_agent_sdk import query, ClaudeAgentOptions

messages = 

async for message in query(
    prompt="Help me write a Python function to calculate fibonacci numbers",
    options=ClaudeAgentOptions(
        system_prompt={
            "type": "preset",
            "preset": "claude_code",
            "append": "Always include detailed docstrings and type hints in Python code."
        }
    )
):
    messages.append(message)
    if message.type == 'assistant':
        print(message.message.content)

Method 4: Custom system prompts¶

You can provide a custom string as systemPrompt to replace the default entirely with your own instructions.

```typescript TypeScript 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); } }

```python Python
from claude_agent_sdk import query, ClaudeAgentOptions

custom_prompt = """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"""

messages = 

async for message in query(
    prompt="Create a data processing pipeline",
    options=ClaudeAgentOptions(
        system_prompt=custom_prompt
    )
):
    messages.append(message)
    if message.type == 'assistant':
        print(message.message.content)

Comparison of all four approaches¶

Feature	CLAUDE.md	Output Styles	`systemPrompt` with append	Custom `systemPrompt`
Persistence	Per-project file	Saved as files	Session only	Session only
Reusability	Per-project	Across projects	Code duplication	Code duplication
Management	On filesystem	CLI + files	In code	In code
Default tools	Preserved	Preserved	Preserved	Lost (unless included)
Built-in safety	Maintained	Maintained	Maintained	Must be added
Environment context	Automatic	Automatic	Automatic	Must be provided
Customization level	Additions only	Replace default	Additions only	Complete control
Version control	With project	Yes	With code	With code
Scope	Project-specific	User or project	Code session	Code 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"

Important: To load CLAUDE.md files, you must explicitly set settingSources: ['project'] (TypeScript) or setting_sources=["project"] (Python). The claude_code system prompt preset does NOT automatically load CLAUDE.md without this setting.

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¶

```typescript TypeScript 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); }

```python Python
from claude_agent_sdk import query, ClaudeAgentOptions

# Assuming "Code Reviewer" output style is active (via /output-style)
# Add session-specific focus areas
messages = 

async for message in query(
    prompt="Review this authentication module",
    options=ClaudeAgentOptions(
        system_prompt={
            "type": "preset",
            "preset": "claude_code",
            "append": """
            For this review, prioritize:
            - OAuth 2.0 compliance
            - Token storage security
            - Session management
            """
        }
    )
):
    messages.append(message)

Modifying system prompts¶

Modifying system prompts¶

Understanding system prompts¶

Methods of modification¶

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

How CLAUDE.md works with the SDK¶

Example CLAUDE.md¶

Using CLAUDE.md with the SDK¶

When to use CLAUDE.md¶

Method 2: Output styles (persistent configurations)¶

Creating an output style¶

Using output styles¶

Method 3: Using systemPrompt with append¶

Method 4: Custom system prompts¶

Comparison of all four approaches¶

Use cases and best practices¶

When to use CLAUDE.md¶

When to use output styles¶

When to use systemPrompt with append¶

When to use custom systemPrompt¶

Combining approaches¶

Example: Output style with session-specific additions¶

See also¶

Method 3: Using `systemPrompt` with append¶

When to use `systemPrompt` with append¶

When to use custom `systemPrompt`¶