Claude Code --system-prompt 与 --append-system-prompt 怎么用:和 CLAUDE.md 的优先级关系与脚本定制

Claude Code 提供 --system-prompt 与 --append-system-prompt(及对应的 -file 参数)定制单次运行的系统提示词。本文讲清完全替换与末尾追加的巨大差异、与 CLAUDE.md 的分工及脚本实例。

NNathaniel bigo··原创首发·AI 辅助撰写
9 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 Pro 账号

结论先说

  1. 九成场景选 --append-system-prompt:它在保留 Claude Code 全部内置编程工具说明与默认工程规范的基础上,把你的额外要求追加到系统提示词末尾。
  2. 慎用 --system-prompt:该参数会整段替换默认系统提示词,一旦替换,内置的文件编辑规范与安全约定都会被清空,仅适合极少数纯文本处理或完全自管提示词的实验。
  3. 长提示词用 -file 变体:规则超过两句话时,改用 --append-system-prompt-file ./review-role.md 直接读文件,避免命令行换行混乱。
  4. 和 CLAUDE.md 按生命周期分工:全员常驻的项目常识写进 CLAUDE.md;只在某一个脚本或终端别名里单次生效的角色约束用 --append-system-prompt。
  5. 开通与额度升级入口:高频跑多角色审查脚本需稳定付费配额;国内用户可通过本站 Claude Code 订阅专页 或免密兑换的 Claude Pro iOS 卡密 开通,重度团队脚本可看 Claude Pro 自助充值。

四类系统提示词参数与 CLAUDE.md 对比

图:本站根据 Claude Code 官方文档:CLI reference 整理的示意图

本文根据 Claude Code 官方文档《CLI reference》《Run Claude Code programmatically》与《How Claude remembers your project》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Anthropic 官方网站。

适用于谁

  • 想在 CI 审单、发版总结或安全扫描脚本里给 Claude 注入专属角色,又不想污染仓库公共 CLAUDE.md 的开发者;
  • 误用了 --system-prompt 结果发现 Claude 突然不会正常调内置编程工具的人;
  • 想理清命令行提示词参数与各级 CLAUDE.md 作用范围边界的团队负责人。

一、四个 CLI 系统提示词参数对比

官方 CLI 参考页列出了两组共四个定制系统提示词的启动标志(注意 --system-prompt 与 --system-prompt-file 互斥,不可同时传入):

参数名称对默认系统提示词的影响传入内容形式典型用途
--append-system-prompt保留内置默认提示词,在末尾追加命令行内联字符串注入单次审查视角、输出语言或红线
--append-system-prompt-file保留内置默认提示词,从文件追加本地 .md / .txt 路径CI 流水线加载长篇审计规范模板
--system-prompt完全覆盖替换默认系统提示词命令行内联字符串纯文本转换等脱离默认代理设定的场景
--system-prompt-file完全覆盖替换默认系统提示词本地 .md / .txt 路径测试自定义底层 Agent 系统提示词

编写高质量系统级约束的结构技巧,可同步参考 系统提示词四段结构写法。

二、和 CLAUDE.md 的优先级关系与职责边界

很多开发者纠结「规则到底该写进 CLAUDE.md 还是放在命令行参数里」。结合官方记忆机制文档,两者并不是二选一,而是上下层叠加关系:

  1. 注入层级不同:--append-system-prompt 直接拼在系统提示词(System Prompt)层,对当次会话拥有顶层角色定调作用;而各级 CLAUDE.md 作为项目与用户上下文记忆在启动时自动拼接载入;
  2. 污染范围不同:你把「只挑安全漏洞、不提代码风格意见」写进项目 ./CLAUDE.md,同事平时写业务代码也会被它干扰;而写在 --append-system-prompt 里,只对这条命令生效,退出即销毁;
  3. 冲突处理原则:如果命令行追加了「一律用英文输出报告」,而全局 ~/.claude/CLAUDE.md 写了「一律用中文回复」,建议在命令行提示词里明确点出「忽略常规语言偏好,本次仅输出英文」。全局与项目记忆的加载顺序详见 全局 CLAUDE.md 配置指南。
多角色脚本与额度准备提示:在本地封装「安全审计员」「性能挑刺员」「发版文案员」等多个 Shell 别名并高频调用时,单账号的 5 小时滚动额度消耗较快。需要更高并发余量的开发者可直接升级 5 倍额度的 Claude Max 订阅服务 或选购 Claude Max 会员升级。

三、两个即抄即用的脚本定制配方

系统提示词与记忆文件选型判断

图:本站根据 Claude Code 官方文档:Run Claude Code programmatically 整理的示意图

配方 1:CI 自动审 PR 只抓高危阻断问题

bash
git diff origin/main...HEAD | claude -p "审查标准输入中的代码变更" \
  --append-system-prompt-file ./scripts/security-reviewer.md

完整流水线触发配置可结合 Claude Code 在 CI 里无头运行示例;若要固化环境变量与工具白名单,可搭配 Claude Code settings.json 配置详解。

配方 2:给交互模式封装专用终端别名

在 ~/.zshrc 或 PowerShell Profile 中定义专用角色启动命令:

bash
alias claude-sec='claude --append-system-prompt "你当前处于只读安全审计角色,严禁修改业务逻辑,重点排查越权、注入与密钥硬编码。"'

常见问题

问:为什么用了 --system-prompt 后 Claude 不按平时的习惯搜文件了?

答:因为 --system-prompt 把官方内置的工具使用指南和代码代理默认指令全部替换掉了。日常在代码库里干活,请改回 --append-system-prompt。

问:--system-prompt 和 --append-system-prompt 能同时传吗?

答:可以组合(先用前者设定基底再追加后缀),但 --system-prompt 与 --system-prompt-file 互斥不能同传。

问:-file 参数支持传入相对路径吗?

答:支持,相对路径按你执行 claude 命令时的当前工作目录解析;在跨目录脚本中建议用绝对路径防找不到文件。

问:国内开发者没有外币卡,怎么开通订阅或申请企业报销发票?

答:可通过本站 Claude Code 订阅专页 或 AI 会员充值总览 选购,支持支付宝、微信支付与 AlipayHK,提供免交密码的卡密自助兑换,团队采购可开具国内增值税发票。实时价格与售后细则以页面为准:订阅期内非违规掉订阅按剩余天数折退,风控封号不在质保范围。

相关教程

参考资料

  • Claude Code 官方文档:CLI reference — https://code.claude.com/docs/en/cli-reference
  • Claude Code 官方文档:Run Claude Code programmatically — https://code.claude.com/docs/en/headless
  • Claude Code 官方文档:How Claude remembers your project — https://code.claude.com/docs/en/memory

Nathaniel 的更多内容

  1. 01

    独立开发者用 ChatGPT + Codex 跑通产品全流程:市场验证、PRD、原型到代码上线复盘清单

    单人做独立产品最容易陷入「闭门写两个月代码上线零用户」或「AI 写到一半目录越改越崩」。本文整理「ChatGPT 负责市场验证、PRD 与复盘 + Codex 负责工程实现与测试」的五阶段双轨流程,附起手提示词与 7 项上线复盘清单。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成规范文件命名规则、整理混乱目录树与合并零散发票抬头清单脚本

    面对满桌面的「新建文件夹」「最终版2」和上百张零散电子发票,手工改名抄台账耗时又容易漏重。本文分享先脱敏取样、再用 ChatGPT 生成带预演和回滚日志的本地 Python 脚本,离线安全完成目录整理与发票抬头合并去重的实战流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外邮件营销(EDM)受众分层文案、A/B 主题行测试与防进垃圾箱自检

    做海外独立站或出海 SaaS 邮件营销(EDM),最怕千人一面群发被直接送进垃圾箱。本文结合 Gmail/Yahoo 批量发件人规范,梳理用 ChatGPT 设计受众分层文案、批量生成 A/B 主题行矩阵并开展发前垃圾词与合规自检的实战提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写 Notion Formula 2.0 公式、Obsidian Dataview 查询与 Airtable 自动化脚本

    给 Notion 数据库写多条件 Formula 2.0 公式、给 Obsidian 写 Dataview 动态看板,或在 Airtable 里写自动化脚本,经常因为一个小括号或类型不匹配报错半天。本文整理三大工具的通用上下文喂料规范与三套直接可复制的生成提示词。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 处理复杂 JSON / YAML / XML 字段映射、格式转换与校验规则编写实战

    对接第三方 API、迁移 Kubernetes 配置或解析政企 XML 报文时,手工对照几百行嵌套字段既慢又容易漏掉空值与类型边界。本文整理用 ChatGPT 完成字段映射表梳理、生成确定性转换脚本以及编写 JSON Schema / Pydantic / XSD 校验规则的实战流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 准备本科/硕士毕业论文答辩:提炼答辩 PPT 结构、模拟导师犀利追问与 3 分钟自述稿

    毕业论文写完后,要在 3–5 分钟内讲清研究价值并顶住答辩评委的连环追问并不轻松。本文整理在严格遵守高校学术规范的前提下,用 ChatGPT 提炼答辩 PPT 结构、打磨 3 分钟口语自述稿并开展模拟导师犀利追问的排练流程与提示词。

    ChatGPT0

同产品的其他教程

  1. 01

    Anthropic Contextual Retrieval(上下文增强检索)是什么、怎么实现:给文档块自动补背景摘要结合缓存降失误率

    长文档切成小块后丢了公司名、年份和主语指代导致 RAG 频频搜错?本文按 Anthropic 官方技术文章详解 Contextual Retrieval 原理、官方公开评测失误率下降 49% 至 67% 的组合架构,以及用 Claude 提示词缓存低成本批量生成切片背景的完整 Python 代码。

    Claude其他 AI 工具0
  2. 02

    RAG 知识库回答不准怎么调优:切片大小(Chunking)、BM25 + 向量混合检索与 Rerank 重排序三步排查法

    搭好的 RAG 企业知识库一问具体型号、报错码或跨行表格就答非所问?本文按 OpenAI 与 Anthropic 官方检索文档,给出先隔离检索与生成故障、再按结构化切片(Chunking)、BM25 加向量混合召回(RRF)与 Rerank 重排序逐层调优的三步法。

    Claude其他 AI 工具0
  3. 03

    Langfuse 开源本地部署(Docker Compose)与提示词版本管理(Prompt Management)从零上手教程

    企业内网严禁业务日志出境,又想免费拥有大模型调用链追踪与不发版热更新提示词的能力?本文按 Langfuse 官方文档整理 Docker Compose 本地一键启动(含 ClickHouse 架构注意事项)、密钥配置与 Prompt Management 标签化版本管理全流程。

    Claude其他 AI 工具0
  4. 04

    LangSmith 入门教程:给 LangGraph 与原生 OpenAI / Claude 接口加调用链追踪、Token 成本统计与免费层限额

    智能体多步调用总是找不到哪一轮提示词跑偏、单次请求到底烧了多少 Token?本文按 LangSmith 官方文档讲清环境变量零侵入接入 LangGraph、用 wrap_openai / wrap_anthropic 与 @traceable 追踪原生接口,以及 Developer 免费层额度与留存规则。

    Claude其他 AI 工具0
  5. 05

    Zotero 搭配 Claude / ChatGPT 高效读英文文献:PDF 翻译插件、批注导出精读与防捏造参考文献流程

    在 Zotero 里读英文顶会论文怎么无缝联动 Claude 与 ChatGPT?本文整理 Translate for Zotero 划词翻译配置、高亮批注导出精读提示词,以及杜绝 AI 捏造假 DOI 参考文献的核验闭环。

    Claude其他 AI 工具0
  6. 06

    Obsidian 接入 Claude、ChatGPT 与本地 Ollama 做个人双链笔记问答:主流插件配置与隐私脱敏边界

    想在 Obsidian 里基于自己的双链笔记库做 AI 问答又担心隐私外泄?本文对比 Copilot 与 Smart Connections 插件,整理接入 Claude、OpenAI 官方 API 与本地 Ollama 的步骤及敏感目录隔离规则。

    Claude其他 AI 工具0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~