它到底是什么

--system-prompt 用命令行传入的一段文本，完全替换 Claude Code 默认的系统提示词。默认系统提示词（Claude Code 官方文档称之为 claude_code preset）包含 Tool 使用指引、安全 / safety 规则，以及关于当前工作目录、Git 状态、平台环境等的上下文说明；一旦使用 --system-prompt，这些内容全部消失，Claude 只会看到你提供的文本。

接受值：一段任意长度的字符串（命令行参数）。若文本较长，官方文档提供了配套的 --system-prompt-file（从文件读取）作为替代输入方式。 默认值：未设置时，Claude Code 使用其内置的 claude_code 系统提示词。

用法

claude --system-prompt "You are a Python expert"

对应的 Agent SDK 参数（不是 --system-prompt 本身，而是同一能力在 SDK 里的等价写法）：

• TypeScript：options.systemPrompt 直接传入字符串
• Python：ClaudeAgentOptions(system_prompt=...) 直接传入字符串

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

for await (const message of query({
  prompt: "Create a data processing pipeline",
  options: { systemPrompt: "You are a Python coding specialist..." }
})) {
  // ...
}

官方文档未提及 --system-prompt 有对应的环境变量或 settings.json 字段——它是一个纯运行期命令行参数。

与其他 flag 的组合 / 互斥

• --system-prompt-file：功能等价，只是从文件而非命令行参数读取文本；两者是同一能力的两种输入方式。
• --append-system-prompt / --append-system-prompt-file：这两个是追加而非替换——保留默认提示词，把文本加在末尾。官方文档明确写道：设置 --system-prompt 或 --system-prompt-file 后，--exclude-dynamic-system-prompt-sections 会被忽略（该 flag 只对"默认系统提示词"生效，用于把工作目录、Git 状态等按机器变化的内容挪到第一条用户消息里以提升 prompt cache 复用率——既然默认提示词已经被整段替换掉，这个优化自然无意义）。
• SDK 侧的行为差异：Agent SDK 文档指出，SDK 不设置 systemPrompt 时用的是"极简默认提示词"（只含 tool-calling 支持），而 claude -p（CLI 的 print 模式）不设置任何 system-prompt 相关 flag 时，默认用的仍是完整的 claude_code 提示词。也就是说 CLI 和"什么都不传的 SDK"默认行为并不相同；如果从 CLI 迁移到 SDK 并想保持一致行为，需要显式设置 SDK 的 systemPrompt: { type: "preset", preset: "claude_code" }。

运行约束 / 限制

经典使用场景

官方 SDK 文档给出的决策依据可以直接类推到 CLI 的 --system-prompt：当你要构建的东西和"一个人盯着终端、在仓库里干活的编码助手"差别较大时，用完全自定义的 prompt 替换默认值，包括：

• 输出面向的不是终端里的操作者，比如结构化输出的下游消费者、聊天 UI，或者无人值守的自动化流水线
• Agent 需要不同的身份 / 人设，不希望以"Claude Code"的身份出现
• 权限模型不同——Agent 自主运行、没有人逐步审批工具调用
• 非编码类任务（调研、内容生成、运营类 Agent），默认提示词里大量的编码规范指引反而会跟真正需要的指令"抢注意力"

常见坑

• 只想加规则、不想丢默认能力时用错了 flag：--system-prompt 是整段替换，容易在不知情的情况下把默认的安全规则和工具指引也删掉；只想"叠加"应使用 --append-system-prompt。
• 和 --exclude-dynamic-system-prompt-sections 一起用是无效组合：官方文档写明后者在设置了 --system-prompt 或 --system-prompt-file 时会被直接忽略。
• 恢复旧会话（--continue / --resume）时以为改了 --system-prompt 就能立刻让 Claude "看到"新指令——实际上系统提示词在会话首次请求后被记录并复用，改动要到会话被 compact 或另开新会话才会生效。

来源

• CLI reference - Claude Code Docs
• Modifying system prompts - Claude Code Docs