它到底是什么

--system-prompt-file 是 Claude Code 的 CLI 启动 flag。它从指定文件加载系统提示，替换默认的系统提示。官方 CLI reference 的原文是："Load system prompt from a file, replacing the default prompt"。

• 参数：文件路径，例如 ./custom-prompt.txt。
• 默认值：不传这个 flag 时，使用 Claude Code 内置的默认系统提示。
• 官方文档说明，系统提示相关的 flag 在交互模式和非交互模式下都可用。

官方文档还提醒：替换会丢掉整个默认提示，包括工具使用指引和安全指令。这些内容里你的任务仍然需要的部分，得自己补进文件里。

用法

claude --system-prompt-file ./custom-prompt.txt

# 官方表格中的另一个示例
claude --system-prompt-file ./prompts/review.txt

官方文档列出的同族 flag 如下：

与其他 flag 的组合 / 互斥

• --system-prompt 与 --system-prompt-file 互斥，不能同时传。
• 两个 append flag（--append-system-prompt / --append-system-prompt-file）可以与任一替换类 flag 组合使用。
• --exclude-dynamic-system-prompt-sections 只在使用默认系统提示时生效。设置了 --system-prompt 或 --system-prompt-file 后，它会被忽略。
• --system-prompt-snapshot off 用来控制续接对话时是否重建提示，见下文"常见坑"。

运行约束 / 限制

经典使用场景

官方文档给出的选择依据如下：

• 用替换类 flag（包括本 flag）的情况：界面、身份或权限模型与 Claude Code 不同，例如流水线里没有人盯着的非编码 agent。
• 相反，如果 Claude 仍然是编码助手，只是要额外遵守一些规则，应改用 append 类 flag。append 会保留默认的工具指引、安全指令和编码约定。

官方文档还建议：需要可切换、可在项目内共享的持久人设时，用 output styles；需要 Claude 始终遵循的项目约定时，用 CLAUDE.md。

常见坑

• 续接对话时新提示可能不生效。 默认情况下，系统提示在对话第一次请求时构建并记录到 session 里。在对话被 compact 之前，后续每次请求都用这份记录的提示，--resume / --continue 也一样。续接时换了文件，或不再传这个 flag，要等对话被 compact，或开始新对话后才生效。
• 反复调试提示措辞时，可以加 --system-prompt-snapshot off，让每次请求都重建提示。官方文档标注该 flag 需要 Claude Code v2.1.257 或更高版本。
• 第三方资料与官方文档不一致。 ClaudeLog 的页面写着该 flag "仅在 print mode 下可用"，但官方 CLI reference 写的是所有系统提示 flag 在交互与非交互模式下都可用。请以官方文档为准，用你安装的版本实测确认。
• 官方文档提到：claude --help 不会列出所有 flag，所以 --help 里查不到它，不代表它不可用。

来源

• CLI reference - Claude Code Docs
• What is the --system-prompt-file Flag in Claude Code | ClaudeLog（第三方，仅作对照）