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

我们为更先进的模型删去了 Claude Code 系统提示词 80% 以上的内容。以下介绍如何将这些经验应用到 Claude Code 和你自己的智能体中的上下文工程。

我之前写过，怎样更好地提示最新一代 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 示例，说明如何使用工具。对于最新的模型，我们发现，提供示例反而会把它们限制在某个探索空间里。

与其提供示例，不如多考虑工具、脚本和文件的设计——Claude 可以使用哪些参数？怎样才能让这些参数表达力更强？

例如，在 Todo 工具的示例中，只要把 status 列为 pending、in_progress 和 completed 这几个枚举值，就能向 Claude 暗示如何使用这个工具。关于要让一个条目保持 in_progress 状态的指令，则有助于明确我们希望它表现出的行为。

过去：把所有内容都放在前面

现在：使用渐进式披露

由于 Claude Code 专注于编码，我们的系统提示词中包含了关于如何进行代码审查和验证的详细信息。这些信息并非总是用得上，但需要时却至关重要。

后来，Claude Code 已经非常擅长使用渐进式披露——在合适的时机加载合适的上下文。例如，我们把验证和代码审查分别放进独立的 Skills 中，让 Claude Code 可以按需调用。

渐进式披露不只适用于 Skills，我们也把它用于工具。我们有些工具采用“延迟加载”（deferred loading），这意味着智能体在使用之前，必须先通过 ToolSearch 查找这些工具的完整定义。这样我们就能提供更多工具（例如 Task 工具），而这些工具只有在需要时才会占用上下文。

同样的做法也适用于你自己的 CLAUDE.md 和 Skill.md 文件。一个常见误区是：你应该把这些文件做成一个中央知识库，把所有可能遇到的已知做法都收进去，因为否则 Claude 就找不到这些信息。相反，可以考虑构建一棵文件树，让文件在合适的时机加载。

过去：重复说明

现在：简洁的工具描述

较早的 Claude 模型有时需要重复指令，或者更容易听从上下文窗口末尾的指令，而不是开头的指令。这意味着我们的系统提示词有时会在主系统提示词中提及工具，同时也在工具描述中加入使用说明。

我们发现，可以删掉这些重复示例，把工具的使用说明放进工具描述，而不是系统提示词。

过去：把记忆放在 CLAUDE.md 文件中

现在：自动记忆

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

过去：简单的规格说明

现在：丰富的参考资料

在计划模式下，Claude Code 很大程度上依赖包含计划的 Markdown 文件。把这些文件存成计划，能帮助 Claude 在需要时查阅它们。另一个类似的最佳实践，是把规格说明存放在代码库中，供 Claude 在较长的项目过程中参考。

但我们发现，Claude 已经能够处理越来越复杂的参考资料。现在，Claude 不必只依赖简单的 Markdown 文件，也可以引用我们新增的 Artifacts 功能所创建的 HTML Artifacts。

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

评判标准也是一种参考资料。借助评判标准，Claude 可以通过动态工作流，并依据这些标准启动验证智能体，尝试理解并验证你在某个领域的偏好（例如，怎样才算好的 API 设计）。

将这些经验应用到你的上下文

综合以上内容，组装上下文时应该是什么样子？

系统提示词

系统提示词与产品上下文密切相关。它会告诉 Claude 正在运行于什么产品中，以及它正在做什么。对于 Claude Code，你可能永远都不会修改系统提示词；但如果你在构建自己的智能体框架，这里就值得投入大量时间。

CLAUDE.md

让 CLAUDE.md 保持轻量，简要说明代码库的用途，但把大部分篇幅留给代码库中容易踩坑的地方。例如，你可能会把代码中的类型集中在一个大型文件里，其他地方都不放类型定义。避免写那些 Claude 看一眼文件系统或代码库就应该知道的“显而易见”的内容。

大量使用渐进式披露。例如，如果你有几条关于如何验证工作的独特指示，可以创建一个验证 Skill，并在 CLAUDE.md 中引用它。

Skills

把 Skills 看作轻量指南，让 Claude 在需要时能够找到信息。除非涉及特别重要的领域，否则不要给它们施加过多限制。

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

最好让 Skills 编码你、你的团队或你的产品特有的观点、知识或最佳实践。

参考资料

你可以用 @ 提及文件，将其作为参考资料纳入上下文。

参考资料让 Claude 能够查阅与当前计划有关的深入信息。

这些资料可以是规格说明文件、设计稿，甚至是整个代码库。

通常，你应该优先选择代码中的文件，因为代码能以 Claude 非常熟悉的语言，向它提供清晰且高度保真的指引。例如，与对设计的描述或截图相比，HTML 设计稿通常能带来更好的结果。

试着简化

你可能需要像我们一样，精简系统提示词、Skills 和 CLAUDE.md 文件。我们推出了一个名为 claude doctor 的新命令，它也能帮你自动完成这项工作。要了解更多专门针对更先进模型的提示方法，请查看 Fable field guide。

本文作者是 Anthropic 技术团队成员 Thariq Shihipar。