Modifying system prompts

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

• How system prompts work, with a decision table for choosing between the preset, the preset with append, and a custom prompt
• Customize agent behavior with CLAUDE.md files, output styles, append, or a custom string
• Compare the four approaches by persistence, scope, and what they preserve
• Combine approaches to layer customization methods together

​

How system prompts work

• Minimal default: when you don’t set systemPrompt in TypeScript or system_prompt in Python, the SDK uses a minimal prompt that covers tool calling but omits Claude Code’s coding guidelines, response style, and project context. This differs from claude -p, which uses the full Claude Code prompt by default. If you’re migrating from the CLI and want matching behavior, set the claude_code preset.
• claude_code preset: the full system prompt that the Claude Code CLI uses, with tool usage instructions, code style and formatting guidelines, response tone and verbosity rules, security and safety instructions, and context about the working directory and environment. Set systemPrompt: { type: "preset", preset: "claude_code" } in TypeScript or system_prompt={"type": "preset", "preset": "claude_code"} in Python, optionally with append to add your own instructions on the end.
• Custom string: a prompt you write yourself. The SDK sends only what you provide.

​

Decide on a starting point

• Different surface: the output isn’t read in a terminal by the person who triggered it. Chat UIs, structured-output consumers, and non-coding automation each need a prompt that matches how their output is rendered and reviewed. Unattended coding automation, like a CI job that fixes lint errors or reviews diffs, still fits the preset because the work itself is what the preset is written for.
• Different identity: the agent shouldn’t present itself as Claude Code. A support bot, a data-analysis assistant, or any domain-specific agent needs its own name, scope, and persona.
• Different permission model: the agent runs autonomously without a human approving each step, or operates on a narrow set of resources. Claude Code’s prompt assumes a human is in the loop with access to a full toolset.
• Non-coding tasks: most of Claude Code’s prompt is coding guidance. For research, content, or operations agents, that guidance competes with the instructions you actually need.

​

Customize agent behavior

​

CLAUDE.md files for project-level instructions

​

Load 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

​

Output styles for persistent configurations

​

Create an output style

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

​

Activate an output style

• CLI: run /config and select an output style
• Settings: set outputStyle in .claude/settings.local.json
• TypeScript SDK: set outputStyle inside the inline settings object passed to query(), or point settings at a settings file that sets it. outputStyle is not a top-level Options field

​

Append to the claude_code preset

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

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
    }
  }
})) {
  // ...
}

​

Custom system prompts

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

​

Compare the four approaches

​

Use cases and best practices

​

When to use CLAUDE.md

​

When to use output styles

• Persistent behavior changes across sessions
• Team-shared configurations
• Specialized assistants like a code reviewer, data scientist, or DevOps assistant
• Complex prompt modifications that need versioning

• 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

• 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

• 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

​

Combine approaches

​

Combine an output style with session-specific additions

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

​

See also

• Output styles: create, manage, and share output styles for the CLI, including the file format and storage locations
• How Claude remembers your project: what to put in CLAUDE.md, where to place it, and how to write effective project instructions
• TypeScript SDK reference: the full Options type, including systemPrompt, settingSources, and settings
• Python SDK reference: the full ClaudeAgentOptions type, including system_prompt and setting_sources
• Settings: the settings.json reference, including where output styles and other configuration are stored