6.3 KiB
System Prompt Configuration Patterns
This guide covers different ways to configure system prompts in the Claude Agent SDK.
Overview
System prompts define Claude's role, behavior, and capabilities. The SDK supports multiple configuration patterns.
Configuration Types
1. No System Prompt (Vanilla Claude)
Claude operates without additional instructions:
from claude_agent_sdk import query
async for message in query(prompt="What is 2 + 2?"):
# Process messages
pass
Use when: You want vanilla Claude behavior without specialized instructions.
2. String System Prompt
Custom instructions as a simple string:
from claude_agent_sdk import ClaudeAgentOptions, query
options = ClaudeAgentOptions(
system_prompt="You are a helpful Python expert. Explain concepts simply."
)
async for message in query(prompt="Explain async/await", options=options):
pass
Use when: You need custom behavior for a specific task or domain.
3. Preset System Prompt
Use the official Claude Code preset:
options = ClaudeAgentOptions(
system_prompt={"type": "preset", "preset": "claude_code"}
)
The "claude_code" preset includes:
- Tool usage patterns (Bash, Read, Write, Edit, etc.)
- Best practices for code modification
- Knowledge of the Task tool for delegating to subagents
- Git commit and PR workflows
- Security guidelines
Use when: Building SDK applications that orchestrate subagents or use file tools.
4. Preset with Append
Extend the Claude Code preset with additional instructions:
options = ClaudeAgentOptions(
system_prompt={
"type": "preset",
"preset": "claude_code",
"append": "Always explain your reasoning before implementing changes."
}
)
Use when: You need Claude Code behavior plus domain-specific instructions.
Common Patterns
Orchestrator Agent
Main agent that delegates to subagents:
options = ClaudeAgentOptions(
system_prompt="claude_code", # Knows how to use Task tool
allowed_tools=["Bash", "Task", "Read", "Write"],
agents={
"subagent-1": AgentDefinition(...),
"subagent-2": AgentDefinition(...)
}
)
Critical: Orchestrators must use system_prompt="claude_code" to understand how to delegate to subagents.
Domain Expert
Specialized behavior for specific tasks:
options = ClaudeAgentOptions(
system_prompt={
"type": "preset",
"preset": "claude_code",
"append": """You are a security auditor for Python applications.
Focus on:
- SQL injection vulnerabilities
- Command injection risks
- Authentication/authorization flaws
- Secrets management issues
Provide specific, actionable security recommendations."""
},
allowed_tools=["Read", "Grep", "Glob"]
)
Constrained Agent
Agent with specific behavioral constraints:
options = ClaudeAgentOptions(
system_prompt="""You are a read-only code analyzer.
IMPORTANT:
- Never modify files
- Never execute code
- Only analyze and report findings
Provide detailed analysis with file/line references.""",
allowed_tools=["Read", "Grep", "Glob"]
)
Shorthand vs Dict Format
The SDK accepts both shorthand and dictionary formats for the claude_code preset:
# Dict format (official examples prefer this)
system_prompt={"type": "preset", "preset": "claude_code"}
# Shorthand format (equivalent, but less explicit)
system_prompt="claude_code"
# With append (dict only)
system_prompt={
"type": "preset",
"preset": "claude_code",
"append": "Additional instructions here"
}
Note: The shorthand system_prompt="claude_code" is a convenience that's equivalent to the full dict format. Both are valid and produce identical behavior. Official examples prefer the dict format for explicitness, but shorthand works fine for simple cases.
Best Practices
- Use preset for orchestrators - Orchestrators need
system_prompt="claude_code"for Task tool knowledge - Use append for specialization - Extend preset with domain-specific instructions
- Match tools to prompt - System prompt should align with allowed_tools
- Be specific - Clear, specific instructions produce better results
- Test variations - Experiment with different prompts for your use case
Examples
File Processing Agent
options = ClaudeAgentOptions(
system_prompt={
"type": "preset",
"preset": "claude_code",
"append": """Process CSV files with these requirements:
- Validate data types
- Handle missing values
- Generate summary statistics
- Create visualizations using matplotlib"""
},
allowed_tools=["Read", "Write", "Bash"]
)
Documentation Generator
options = ClaudeAgentOptions(
system_prompt="""You are a technical documentation specialist.
Generate clear, comprehensive documentation with:
- Overview and purpose
- API reference with types
- Usage examples
- Common pitfalls and troubleshooting
Use Google-style Python docstrings.""",
allowed_tools=["Read", "Write", "Edit", "Grep"]
)
Test Writer
options = ClaudeAgentOptions(
system_prompt={
"type": "preset",
"preset": "claude_code",
"append": """Write pytest-based tests following these patterns:
- Use fixtures for setup/teardown
- Parametrize tests when appropriate
- Include edge cases and error conditions
- Aim for >90% code coverage"""
},
allowed_tools=["Read", "Write", "Bash"]
)
Anti-Patterns
❌ Orchestrator without claude_code preset
# Orchestrator won't know how to use Task tool
options = ClaudeAgentOptions(
agents={...}
# Missing system_prompt="claude_code"
)
✅ Proper orchestrator configuration
options = ClaudeAgentOptions(
system_prompt="claude_code",
agents={...}
)
❌ Conflicting instructions
# Tells agent to modify files but only allows read tools
options = ClaudeAgentOptions(
system_prompt="Fix any bugs you find",
allowed_tools=["Read", "Grep"] # Can't actually fix anything
)
✅ Aligned tools and instructions
options = ClaudeAgentOptions(
system_prompt="Analyze code for bugs and report findings",
allowed_tools=["Read", "Grep", "Glob"]
)