修改系统提示

系统提示定义 Claude 的行为、能力和响应风格。SDK 提供三种起点：最小默认提示、claude_code preset（完整 Claude Code 提示）、自定义字符串。选择依据是 Agent 与 Claude Code 的相似程度。

核心机制

三种起点：

• 不设置：最小提示，只含工具调用支持（与 claude -p 不同，后者默认用完整提示）
• claude_code preset：完整 Claude Code 提示，含编码规范、安全规则、响应风格、工作目录上下文
• 自定义字符串：完全自主控制，需自行包含工具指导和安全规则

选择决策：

场景	推荐方式
CLI/IDE 类编码工具，人工监督	claude_code preset
同上 + 产品特定规则	claude_code preset + append
不同界面/身份/权限模型的 Agent	自定义字符串
薄工具调用层，行为全在 user prompt	不设置

四种定制方法对比：

方法	持久性	保留内置工具指导	适用场景
CLAUDE.md	项目文件	是	项目级持久指令
Output Styles	保存为文件	是（可选）	跨项目复用的角色
preset + append	仅当前会话	是	追加特定规则
自定义字符串	仅当前会话	需自行添加	完全不同的 Agent

关键细节

使用 preset + append：

options = ClaudeAgentOptions(
    system_prompt={
        "type": "preset",
        "preset": "claude_code",
        "append": "Always include detailed docstrings and type hints in Python code.",
    }
)

跨会话缓存优化（多实例部署）：

system_prompt={
    "type": "preset",
    "preset": "claude_code",
    "append": "You operate Acme's internal triage workflow.",
    "exclude_dynamic_sections": True,  # 移除工作目录等动态内容，使 system prompt 可缓存
}

CLAUDE.md 加载：通过 settingSources 控制，注入到对话而非系统提示，与任何系统提示配置兼容。

Output Styles：保存为 ~/.claude/output-styles/ 或 .claude/output-styles/ 下的 Markdown 文件，Python SDK 不支持编程式选择（需通过 settings.local.json）。

与其他概念的关联

• claude-code-features - CLAUDE.md 和 settingSources
• permissions - 自定义提示时需自行包含权限相关指令
• skills - Skills 与系统提示独立工作

实践要点

• exclude_dynamic_sections 将工作目录等动态信息移到第一条 user message，使 system prompt 可跨实例缓存，但这些信息权重略低
• 自定义提示时，如果 Agent 仍需要工具调用能力，需要自行包含工具使用指导
• CLAUDE.md 不修改系统提示本身，而是注入到对话上下文，因此与所有系统提示配置兼容
• 从 CLI 迁移到 SDK 时，如需保持相同行为，需显式设置 preset: "claude_code"