My Secret Rainbow

Claude 5 模型的上下文工程新规则

我之前写过，如何更好地为最新一代 Claude 5 模型编写提示词，以及如何通过与它反复协作，发现自己真正想构建的东西。

但当你给 Claude 发送消息时，提示词只是它收到的上下文中的一小部分。大量上下文来自系统提示词、Skills、CLAUDE.md 文件、记忆和其他来源的组合。我们把这称为上下文工程。无论你在使用 Claude Code，还是构建自己的智能体，它都会显著影响最终结果。

与提示词不同，上下文通常会用于许多不同的请求，因此不能写得那么具体。尤其在不知道用户可能提出什么请求时，你该如何为 Claude 编写这些通用提示和指导？

随着 Claude 自身能力的演进，这件事可能比想象中更难。最近，我们发现，面向最新一代 Claude 模型的提示方式发生了很大的变化。对于 Claude Opus 5 和 Claude Fable 5 等模型，我们删掉了 Claude Code 系统提示词中超过 80% 的内容，而编码评测没有出现可测量的性能损失。

下面是我们在为这类新模型编写提示时学到的经验，以及你可以如何据此更新自己的上下文工程。我们已经把这些最佳实践整合进 claude doctor。在 Claude Code 中使用 /doctor 命令，就能让你的 Skills 和 CLAUDE.md 文件保持适当的规模。

为 Claude 松绑

总体而言，我们发现，系统提示词、CLAUDE.md 文件和 Skills 都对 Claude Code 施加了过多约束。

例如，阅读内部使用 Claude Code 的对话记录时，我们会在同一个请求中看到相互冲突的指令，比如“酌情补充文档”和“不要添加注释”。系统提示词、Skills 和用户请求会互相打架。

通常，Claude 能理解用户意图，并找到正确答案。但面对这些相互重叠、彼此冲突的信息，它必须在决定行动前投入更多思考。

这些约束曾经是避免最糟糕情况所必需的。不过，我们后来发现，其中许多都可以删掉，转而让模型依据周围的上下文自行判断。

此外，Claude Code 现在拥有更多工具。过去，Claude 依赖 CLAUDE.md 来获取记忆、信息和指导；如今，我们有了记忆、Artifacts 和 Skills，Claude 可以利用它们，创造在不同会话之间加载和共享上下文的新方式。

过去与现在

过去的一些上下文工程最佳实践，如今已经变成了误区，包括以下这些：

过去：给 Claude 制定规则；现在：让 Claude 自行判断

最初推出 Claude Code 时，我们必须确保它避开删除文件之类的最糟糕情况。这意味着我们会给出非常强硬、却未必始终正确的指导。例如，过去的系统提示词会这样写：

在代码中：默认不写注释。绝不编写多段文档字符串或多行注释块，最多只写简短的一行。除非用户要求，否则不要创建规划、决策或分析文档；依据对话上下文开展工作，而不是使用中间文件。

但对于某些请求，这样的指导就是错的。以文档为例，用户可能有自己的偏好；非常复杂的代码中，某些部分也可能确实需要多行注释。

即便如此，如果不给旧模型这些约束，Claude 写出的注释在很多情况下就会不合适，我们只能接受这种取舍。新模型的判断力更好，即使没有明确规则，也能妥善做出这些决定。

在新的系统提示词中，我们这样写：让你写出的代码与周围代码保持一致，包括注释密度、命名方式和惯用写法。

过去：给 Claude 提供示例；现在：设计好接口

过去，工具使用的首要原则是向 Claude 提供使用示例。但对于最新模型，我们发现，示例反而会把它们限制在某个特定的探索空间内。

与其提供示例，不如多想想工具、脚本和文件本身的设计：Claude 可以使用哪些参数？如何让这些参数拥有更强的表达能力？

例如，在 Todo 工具的例子中，只要把状态定义为 pending、in_progress 和 completed 这几个枚举值，就已经在提示 Claude 如何使用这个工具。而“保持一个条目处于 in_progress 状态”的指令，则有助于定义我们期望的行为。

过去：一开始就提供所有信息；现在：使用渐进式披露

由于 Claude Code 专注于编程，我们曾在系统提示词中加入详细的代码审查和验证说明。这些信息并非始终需要，但一旦需要，就至关重要。

后来，Claude Code 已经非常擅长渐进式披露，也就是在恰当的时机加载合适的上下文。例如，我们把验证和代码审查移入各自的 Skill，让 Claude Code 有选择地调用。

渐进式披露也不只适用于 Skills，我们还把它用于工具。部分工具采用“延迟加载”：智能体必须先通过 ToolSearch 搜索其完整定义，才能使用。这样，我们可以提供更多工具，例如 Task 工具，而它们只在被需要时才占用上下文。

同样的做法也适用于你的 CLAUDE.md 和 Skill.md 文件。一个常见误区是：因为担心 Claude 找不到信息，就把一切可能用到的已知实践都集中塞进这些文件。相反，可以组织一棵能在恰当时机按需加载的文件树。

过去：反复强调；现在：简洁的工具说明

早期 Claude 模型有时需要重复指令，或者更容易遵循上下文窗口末尾的指令，而不是开头的指令。因此，我们有时既在系统提示词正文中提及工具，也在工具说明里加入使用指令。

我们发现，可以删除这些重复示例，把工具使用指令放进工具说明本身，而不是系统提示词中。

过去：把记忆写进 CLAUDE.md；现在：自动记忆

我们曾鼓励用户使用 # 快捷键，把内容自动写进 CLAUDE.md，存入 Claude 的记忆。现在，Claude 会自动保存与你和当前工作相关的记忆。

过去：简单的规格说明；现在：丰富的参考资料

在规划模式中，Claude Code 曾大量依赖包含计划的 Markdown 文件。把计划保存在这些文件里，便于 Claude 在需要时查阅。类似的最佳实践还包括：把规格说明保存在代码库中，方便 Claude 在较长期的项目中参考。

但我们发现，Claude 能处理越来越复杂的参考资料。除了简单的 Markdown 文件，它还可以参考通过新 Artifacts 功能创建的 HTML 产物。

你也可以用代码的形式提供参考资料。规格说明可以是一套详细的测试，也可以是另一个代码库中需要 Claude 移植的函数。

评分标准也是一种参考资料。借助动态工作流，以及依据这些标准启动的验证智能体，Claude 能够尝试理解并检验你在特定领域的品味，例如怎样的 API 设计才算好。

把这些原则应用到你的上下文中

把上述内容结合起来，在组装上下文时，具体应该是什么样子？

系统提示词

系统提示词与产品场景密切相关。它告诉 Claude 自己运行在什么产品里、正在做什么。对于 Claude Code，你很可能永远不会修改它；但如果你在构建自己的智能体运行框架，就应该在这里投入大量精力。

CLAUDE.md

让 CLAUDE.md 保持轻量，简要描述代码库的用途，并把大部分 token 用在代码库中容易踩坑的地方。例如，你可能规定所有类型都集中在一个大文件中，不能放在其他位置。不要重复那些 Claude 只要查看文件系统或代码库就应该知道的“显而易见”的事情。

通过渐进式披露提供更多细节。例如，如果你有几条独特的工作验证要求，就创建一个验证 Skill，并在 CLAUDE.md 中引用它。

Skills

把 Skills 看作轻量指南，帮助 Claude 在需要时找到信息。除非涉及极其重要的领域，否则应避免对它们施加过多约束。

对于较长的 Skill，尽可能使用渐进式披露，把内容拆分到多个文件中。

Skills 最适合承载你、你的团队或产品特有的观点、知识和最佳实践。

参考资料

你可以通过 @ 提及文件，将其作为参考资料加入上下文。参考资料让 Claude 能查阅当前计划的深入信息。

这些资料可以是规格文件、设计原型，甚至整个代码库。通常，应该优先采用代码形式的文件，因为它们以 Claude 非常熟悉的语言提供了清晰、高保真的指导。例如，一份 HTML 设计原型通常比设计文字说明或截图带来更好的结果。

试着做减法

对于系统提示词、Skills 和 CLAUDE.md 文件，你可能也需要像我们一样进行精简。我们推出了一个名为 claude doctor 的新命令，也可以自动帮助你完成这件事。要进一步了解如何为更先进的模型编写提示词，请阅读我们的 Fable 实战指南。

---

作者：Thariq（@trq212）
原文标题：The new rules of context engineering for Claude 5 models
原文发布于：2026 年 7 月 25 日 01:45（UTC+8）
原文链接：https://x.com/trq212/article/2080710971228918066