先想清楚改什么
很多人在日常使用 Claude Code 时,会觉得默认行为和自己项目不太匹配。自定义系统提示词确实能改善这种体验,但关键不是先找写法,而是先确认这次改动到底要解决什么问题。
判断是否需要自定义系统提示词,通常要看默认行为是否足够。如果项目有独特的编码规范、工具链或风险偏好,默认提示词无法覆盖,就有必要自定义。自定义前先列出要解决的三个问题:希望模型记住哪些项目约定、需要限制哪类操作、希望默认工具调用风格如何。如果问题列表为空,就不必改,避免引入额外变量。这个判断过程本身能帮你明确目标。
比如,如果仓库里约定所有命令都通过 pnpm 执行,或者提交说明必须带上任务编号,这些细节默认情况下模型只能靠临时猜测。把它们写进系统提示词,相当于在每次会话开始时给模型一份项目手册。
项目配置文件的写法和生效范围
最常用的方式是创建项目级配置文件,放置到仓库根目录,例如 CLAUDE.md。文件支持自然语言描述,也支持一些轻量级标记。建议先写“你是本项目的协作工程师”开头,然后分节列出:项目背景、命令规范、禁用事项、输出偏好。每节要短,优先写“必须”和“禁止”,少写“尽量”。写完后需要重启或重新加载会话才能生效,因为启动时只读取一次。
下面是一个可以放进仓库根目录的示例,用自然语言加少量列表构成:
# CLAUDE.md
你是本项目的协作工程师。
## 项目背景
- 项目使用 pnpm,不要引入 npm 或 cnpm 的用法
- 组件放 src/features,公共组件放 src/ui
## 命令规范
- 本地验证:pnpm test
- 提交前检查:pnpm lint
## 禁用事项
- 禁止直接改动 pnpm-lock.yaml
- 禁止在未说明理由时重命名公共函数
## 输出偏好
- 回答先给结论,再给理由
- 代码注释只写“为什么”,不写“是什么”
注意,示例里的“禁止”针对的是项目内的具体操作,不是让模型不向你提问。这样写能在多数场景下减少来回沟通。
如果你有多套环境,最好先确认用户级配置和项目级配置的优先级。通常项目目录下的 CLAUDE.md 会被优先读取,但不同版本的加载顺序可能不同,需要在当前环境里实际试一下。文件里的内容越具体,模型越容易保持一致。
改完以后怎么确认加载
验证配置是否真正生效,不要只凭感觉。可以问模型“请复述你当前的项目配置要点”,看是否准确反映你写的内容。更直接的方法是使用调试输出,查看上下文里是否包含了该文件的内容。如果模型答不出,先检查文件位置和命名是否正确,再看是否在配置变更后启动了新会话。有时编辑器缓存也会导致旧内容被读取。
我会建议把“重启会话”和“问一次配置要点”绑在一起,作为每次改完提示词后的固定动作。如果用的是命令行版本,还可以在启动时打开调试输出,确认 CLAUDE.md 确实被加载。具体的调试参数名在不同版本里并不一样,需要结合当前环境确认。
如果团队里多人共用同一个仓库,配置文件的变更会直接影响所有人的会话,所以建议用一段话写清楚改动目的,放在文件头部注释里。
别碰安全底线和冲突规则
自定义提示词能控制的是输出样式和项目偏好,不能削弱模型自身的判断底线。比如你可以在提示词里规定代码注释怎么写、回复要不要带例子,但不能要求它“忽略所有安全限制”。这种规则不仅无效,还会让模型在遇到真实风险时表现反常。
另外,要避免写入与核心指令直接冲突的规则。比如规定“不要调用任何工具”,等于把模型的手脚绑起来。系统提示词更适合描述“偏好”,而不是接管底层身份。更安全的方式是只定义项目的操作边界,比如“删除文件前先列出将影响的文件”。
提示词不是操作手册
有一个很容易踩的坑:把提示词写得像一份完整操作手册,对每一步都做规定。模型遇到没列到的情况时,反而不知道该怎么判断。更合适的做法是给出决策原则,比如“修改公共接口前先说明影响范围”,而不是列几十条具体分支。
措辞上也要留余地。你可以说“如无必要,不要打断用户”,但不要写“永远不要问用户”。在需要隐私确认或权限确认的场景里,绝对化的指令会让模型走错方向。改完文件后,最好保留一份原始版本备份,出了问题随时回滚。