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 的对话记录时，我们经常会看到同一个请求中出现多条相互冲突的信息：系统提示词说“在适当的情况下补充文档”，Skill 又说“不要添加注释”，用户的要求可能还会与两者冲突。

图中示例仅用于说明冲突结构，并非任何真实提示词、Skill 或用户请求的逐字引用。

通常，Claude 能理解用户意图并得出正确答案。但在采取行动之前，它不得不投入更多推理，处理这些彼此重叠、互相冲突的信息。

这些约束过去确实有价值，可以帮助模型避免最糟糕的操作后果。但现在我们发现，其中很多都可以删掉，让模型根据周围的上下文自行判断。

与此同时，Claude Code 拥有的工具也比以前多得多。过去，Claude 主要依赖 CLAUDE.md 来保存记忆、信息和指导。现在，我们有了记忆、Artifacts 和 Skills，Claude 可以用它们创造新的方式，在不同会话之间加载和共享上下文。

过去与现在

过去有不少被视为“上下文工程最佳实践”的做法，如今已经变成了迷思。

过去：给 Claude 制定规则

现在：让 Claude 运用判断力

Claude Code 刚推出时，我们必须确保 Claude 不会做出删除文件之类的危险操作。因此，我们会加入非常强硬、却未必在所有情况下都正确的指导。例如，旧版系统提示词中曾经写道：

编写代码时，默认不添加注释。绝不要编写多段式文档字符串或多行注释块，最多只能写一行简短注释。除非用户明确要求，否则不要创建规划、决策或分析文档；应直接依据对话上下文工作，而不是依赖中间文件。

但对于某些请求，这种指导其实是错的。以文档为例，用户可能有自己的偏好；面对特别复杂的代码，某些位置也确实需要多行注释。

对于旧模型，如果没有这些护栏，Claude 写出的注释在很多情况下可能并不正确，所以我们只能接受这种取舍。但新模型拥有更好的判断力，即使没有明确规则，也能更妥善地作出决定。

在新的系统提示词中，我们只需要这样写：

编写与周围代码风格一致的代码：匹配现有代码的注释密度、命名方式和惯用写法。

过去：给 Claude 提供示例

现在：设计好接口

过去，工具使用的第一原则，是给 Claude 提供工具调用示例。但在最新模型上，我们发现，示例反而会把模型限制在某个固定的探索空间内。

与其堆叠示例，不如把更多精力放在工具、脚本和文件的接口设计上：Claude 可以使用哪些参数？怎样让这些参数拥有更强的表达能力？

例如，对于 Todo 工具，只要把 status 定义成包含 pending、in_progress 和 completed 的枚举，就已经在暗示 Claude 应该怎样使用它。再加上一条“同一时间只能有一个任务处于 in_progress 状态”的说明，就能清楚界定我们期望的行为。

过去：把所有信息一次性放在最前面

现在：使用渐进式披露

由于 Claude Code 最初专注于编程，我们曾在系统提示词中加入大量关于代码审查和验证的详细说明。这些内容并非每次都会用到，但一旦需要，又非常关键。

如今，Claude Code 已经很擅长使用渐进式披露，也就是在正确的时间加载正确的上下文。例如，我们把验证和代码审查拆成了独立 Skills，让 Claude Code 只在需要时选择性调用。

渐进式披露并不只适用于 Skills，也适用于工具。我们的一些工具采用“延迟加载”：智能体必须先通过 ToolSearch 搜索完整定义，才能使用这些工具。这样一来，我们可以提供更多工具，例如 Task 工具，而不必让它们在尚未使用时就占据上下文空间。

同样的思路也可以用于你自己的 CLAUDE.md 和 Skill.md 文件。一个常见误区是：应该把它们做成一个中央知识库，收纳未来可能遇到的每一条实践，因为 Claude 否则就找不到这些信息。更好的做法是，设计一棵可以在恰当时机按需加载的文件树。

过去：反复强调同一件事

现在：使用简洁的工具描述

较早的 Claude 模型有时需要重复指令，或者更容易听从上下文窗口末尾的内容，而不是开头的内容。因此，我们会在主系统提示词里提到某个工具，同时又在工具描述中重复一遍相关说明。

现在，我们可以删掉这些重复内容，把工具使用说明直接放进工具描述，而不是写在系统提示词里。

过去：把记忆写进 CLAUDE.md

现在：使用自动记忆

过去，我们鼓励用户使用 # 快捷键，把需要记住的内容自动写入 CLAUDE.md。

现在，Claude 会自动保存与你本人及当前工作相关的记忆。

过去：使用简单的规格说明

现在：提供丰富的参考资料

在规划模式中，Claude Code 长期以来高度依赖以 Markdown 文件保存的计划。把计划写入文件，可以让 Claude 在需要时重新查阅。类似的最佳实践还包括：把规格说明保存在代码库中，方便 Claude 在长期项目里持续引用。

但我们发现，Claude 已经能够处理越来越复杂的参考资料。除了简单的 Markdown 文件，它还可以引用由新 Artifacts 功能创建的 HTML 交互式产物。

你也可以直接把代码作为参考资料。规格说明可以是一套详细的测试用例，也可以是另一个代码库中的某个函数，供 Claude 移植到当前项目。

评判标准（Rubrics）也是一种参考资料。它可以让 Claude 尝试理解并验证你在某个领域里的品位，例如，怎样的 API 设计才算优秀。Claude 可以结合动态工作流^[3]，启动带有这些评判标准的验证智能体。

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

把以上变化综合起来，当你真正组装一份上下文时，它应该是什么样子？

上下文由以下部分共同组装而成：

1. 1. 你的提示词
2. 2. 参考资料：通过 @ 提及的文件、规格说明、设计稿、代码库和 Artifacts
3. 3. 系统提示词
4. 4. CLAUDE.md 文件
5. 5. Skills
6. 6. 记忆

系统提示词

系统提示词与产品场景高度绑定。它告诉 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 实战指南

引用链接
[1] 最新一代 Claude 5 模型编写提示词: https://x.com/trq212/status/2073100352921215386
[2] 上下文工程: https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
[3] 设计一棵可以在恰当时机按需加载的文件树: https://claude.com/blog/a-harness-for-every-task-dynamic-workflows-in-claude-code
[4] CLAUDE.md: http://claude.md/
[5] Fable 实战指南: https://claude.com/blog/a-field-guide-to-claude-fable-finding-your-unknowns