它到底是什么

--append-system-prompt 用于在 Claude Code 默认系统提示词（即 claude_code preset，包含工具使用说明、安全指令、工作目录/环境上下文等）的末尾追加一段自定义文本，不会替换默认提示词的任何内容。

• 接受值：一段字符串文本
• 默认值：不设置该 flag 时不追加任何内容，仅使用默认系统提示词

用法

claude --append-system-prompt "Always use TypeScript"

也可以配合初始 query 一起使用：

claude "explain this project" --append-system-prompt "Always use TypeScript"

文本较长时，官方提供了文件版本的等价 flag --append-system-prompt-file:

claude --append-system-prompt-file ./extra-rules.txt

在 Agent SDK 中的等价写法是给 claude_code preset 传 append 字段：

systemPrompt: {
  type: "preset",
  preset: "claude_code",
  append: "Always include detailed docstrings and type hints in Python code."
}

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

与其他 flag 的组合 / 互斥

• --append-system-prompt-file 是 --append-system-prompt 的文件版本，用于加载较长文本后追加到默认系统提示词末尾；官方文档未说明这两个 flag 互斥，"the two flags can't be combined" 这句话实际描述的是 --append-subagent-system-prompt 与 --append-subagent-system-prompt-file 这一对 subagent flag。
• 与 --append-subagent-system-prompt / --append-subagent-system-prompt-file 是两套独立机制：后两者只作用于 subagent 的系统提示词，且官方文档标注"仅在非交互模式（-p）下生效"，而 --append-system-prompt 本身的文档条目没有这种交互/非交互模式的限制说明。
• 若改用 --system-prompt 或 --system-prompt-file 完全替换系统提示词，则不再是"追加"语义 —— 这会丢失默认的工具指导和安全指令，需要自己补齐。

在 settings.json / env 的等价配置

运行约束 / 限制

常见坑

1. 想完全替换而不是追加：--append-system-prompt 只做追加，若需要完全自定义、丢弃默认的工具/安全指令，应使用 --system-prompt 或 --system-prompt-file，但这样会丢失默认工具指导，需自行补充安全指令等内容。
2. 误以为 --append-system-prompt 与 --append-system-prompt-file 不能同时使用：官方文档中"两个 flag 不能合并"的说明只针对 --append-subagent-system-prompt 与 --append-subagent-system-prompt-file，并不适用于本文的这对主 flag。
3. 对已恢复的会话无效：如果是对一个已存在会话执行 --resume/--continue 并附加新的 --append-system-prompt 文本，该文本不会在下一轮立即生效，要等会话被压缩或开启新会话。

经典使用场景

• 在保留 Claude Code 默认行为（工具指导、安全指令、环境上下文）的前提下，叠加项目级规则，例如强制使用 TypeScript、约定代码风格等 —— 这是官方文档给出的定位："Everything above, with your instructions added after the preset. Nothing is removed, so this is the lowest-risk customization"。
• Headless / 非交互场景（claude -p）中注入领域特定指令，同时保留 Claude Code 内置能力。

来源

• CLI reference - Claude Code Docs
• Modifying system prompts - Claude Code Docs
• Docs: Clarify how CLAUDE.md and --append-system-prompt influence Claude's instructions · Issue #6973 · anthropics/claude-code
• 10 Claude Code CLI flags you probably aren't using - mager.co