Claude 5 这一代模型的上下文怎么写：少定规则，多给判断空间

这是“Claude Code 开发系列”的第五篇。

这一篇解决的问题是：你的 CLAUDE.md 和 skill 是按老模型的习惯写的，放到新模型上可能反而在拖后腿。 Claude Code 团队自己就遇到了这件事：他们为 Claude Opus 5、Claude Fable 5 这类模型删掉了系统提示词的 80% 以上，在编码评测上没有可以测出来的下降。

如果只想要结论：在 Claude Code 里运行 /doctor。团队把这篇文章里的做法放进了 claude doctor，它会帮你把 skill 和 CLAUDE.md 精简到合适的大小。想知道为什么要这样改，往下看。

提示词只是上下文的一小部分

你给 Claude 发一条消息，它实际拿到的远不止这一句。系统提示词、skill、CLAUDE.md、记忆，都会一起送进去。怎么安排这些东西，原文叫“上下文工程”。

它和写提示词的区别在于：提示词只管这一次请求，可以写得很具体；上下文要在很多次请求里通用，而你并不知道用户下一句会说什么。

问题出在哪：管得太死

团队读了自己内部使用 Claude Code 的会话记录，发现同一次请求里常常有互相打架的话。比如一处写着“适当留下文档”，另一处写着“不要加注释”，分别来自系统提示词、skill 和用户的要求。

Claude 一般能猜出用户真正想要什么，但它得先花力气想清楚这些重叠、冲突的话该听哪一句。

这些限制当初是为了防止最坏的情况。团队后来发现，其中很多可以删掉，让模型根据周围的情况自己判断。另一个变化是工具多了：以前 Claude 靠 CLAUDE.md 来记事、存资料、拿指导，现在有了记忆、artifacts 和 skill，可以分担这些事。

六条“以前和现在”

原文把过去的几条最佳实践称为“已经变成迷思”。整理成一张表：

以前	现在	原因
给规则	让它判断	硬规则总会在一部分情况下是错的
给例子	设计好接口	例子会把新模型限制在一小块范围里
全部写在前面	用到时再加载	不是每次都用得上的内容，不该一直占着上下文
重要的话多说几遍	工具说明写一处、写简单	新模型不需要重复提醒
往 `CLAUDE.md` 里存记忆	自动记忆	Claude 现在会自己保存相关的记忆
简单的规格文档	更丰富的参考资料	Claude 能用好更复杂的参考

下面逐条说。

给规则 → 让它判断

Claude Code 刚推出时，系统提示词里有这样的话（译自原文）：

写代码时默认不写注释。不要写多段的文档字符串或多行注释块，最多一行短的。
除非用户要求，不要创建计划、决策或分析文档，直接根据对话内容工作，不要用中间文件。

对一部分请求，这条指导是错的：用户可能有自己的文档习惯，很复杂的代码也确实需要多行注释。但老模型没有这道护栏时，写出来的注释很多是不对的，团队只能接受这个取舍。

新模型的判断力更好，不需要明确的规则也能处理好。新的系统提示词里换成了一句（译自原文）：

写出来的代码要读起来像周围的代码：注释的多少、命名和写法都与之一致。

给例子 → 设计好接口

以前工具使用的头号规则是“给 Claude 看例子”。团队发现，对最新的模型，例子反而会把它限制在某一块探索范围里。

替代的做法是多想想工具、脚本和文件本身的设计：Claude 能填哪些参数，怎样让这些参数表达得更清楚。原文举的是待办工具：状态字段只能取 pending、in_progress、completed 三个值，这本身就在提示 Claude 该怎么用；再加一句“同时只保持一项处于 in_progress”，行为就定义清楚了。

全部写在前面 → 用到时再加载

Claude Code 的系统提示词以前包含了怎么做代码评审和验证的详细说明。这些不是每次都需要，但需要时又很关键。

现在 Claude Code 很会“渐进式披露”，也就是在合适的时候加载合适的内容。团队把验证和代码评审各自挪成了 skill，由 Claude 按需调用。

工具也是同样的思路：有些工具是“延迟加载”的，代理要先用 ToolSearch 查到完整定义才能使用。这样可以有更多工具，而不用的时候不占上下文。

对你自己的 CLAUDE.md 和 SKILL.md，原文点破了一个常见的误解：把它们写成收录所有做法的总库，因为担心 Claude 找不到。更好的做法是组织成一棵文件树，到需要时再加载对应的那一份。

重复强调 → 工具说明写简单

早期的模型有时需要重复的指示，或者更容易听上下文末尾的话而不是开头的。所以系统提示词里会提一遍某个工具，工具说明里又写一遍。

团队发现这些重复可以删掉：怎么用工具，写在工具说明里就够了，不用再写进系统提示词。

往 CLAUDE.md 存记忆 → 自动记忆

以前鼓励用户用 # 快捷键把内容写进 CLAUDE.md。现在 Claude 会自动保存和工作、和你有关的记忆。

简单的规格文档 → 更丰富的参考资料

计划模式一直很依赖 Markdown 写的计划文件，另一个常见做法是把规格文档放在代码库里供 Claude 查阅。团队发现 Claude 能处理越来越复杂的参考资料：

HTML artifacts：代替简单的 Markdown 文件。
代码本身：一套详细的测试，或者另一个代码库里要移植过来的函数，都可以当作规格。
评分标准（rubric）：把你在某个领域的品味写下来，比如“好的 API 设计是什么样”。Claude 可以用动态工作流启动验证代理，按这份标准来检查。

落到你自己的上下文

系统提示词

系统提示词和产品紧密相关，告诉 Claude 它在什么产品里、在做什么。用 Claude Code 的人基本不会去改它；自己做智能体的人，应该在这里花大量时间。

CLAUDE.md

保持轻量，用几句话说明这个仓库是做什么的。
大部分篇幅留给代码库里的“坑”。原文的例子：你们把所有类型都放在一个大文件里，别处一概不放。
不要写 Claude 看一眼文件系统或仓库就能知道的事。
多用渐进式披露。比如验证工作有好几条特别的要求，就单独做成一个验证 skill，在 CLAUDE.md 里引用它。

Skill

把 skill 看作轻量的指引，让 Claude 在需要时能找到信息。
除了特别重要的地方，不要限制得太死。
长的 skill 尽量拆成多个文件，按需加载。
最有价值的 skill，写的是你、你的团队或产品特有的看法、知识和做法。

skill 的基本写法见本站的 Claude Code 自定义 skill 教程。

参考资料

用 @ 提到文件，就能把它作为参考资料带进来，可以是规格文件、设计稿，甚至整个代码库。

原文的建议是优先用代码形式的参考，因为这是 Claude 非常熟悉的语言，指令清楚、不失真。例子：一份 HTML 做的设计稿，通常比一段文字描述或一张截图效果更好。

对你有什么用

只是用 Claude Code 的人：

先运行 /doctor，让它帮你精简 CLAUDE.md 和 skill。
自己过一遍 CLAUDE.md：全大写的“绝对不要”、同一件事说了几遍的、Claude 自己能从仓库看出来的，都是可以删的候选。留下的应该主要是“坑”。
检查有没有互相矛盾的话。它们分散在 CLAUDE.md、skill 和你平时的提示词里，自己不容易发现。
想让 Claude 照着某个样子做，给它一份代码或 HTML，比写一段描述管用。

在做自己智能体的人：

换到新一代模型后，重新审一遍系统提示词。为老模型加的护栏，现在可能是多余的，甚至在互相冲突。
删之前要有评测。团队敢删掉八成，是因为有编码评测证明没有下降。
例子少放，把精力放在参数的设计上：枚举值、字段名本身就是说明。
工具的用法只写在工具说明里，不常用的工具做成延迟加载。

原文最后提到，针对更先进的模型怎么写提示词，另有一份 Fable field guide，可以到原文里找链接。