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 Code 的约束过多，无论是通过系统提示词，还是通过我们的 CLAUDE.md 文件和 skills。

例如，当我们阅读我们自己内部使用 Claude Code 的记录时，我们看到在单个请求中有几条相互冲突的信息，比如“酌情保留文档”，或者“不要添加注释”，因为我们的系统提示词、skills 和用户请求相互冲突。

通常，Claude 可以解读用户的意图以得出正确答案，但在决定如何行动之前，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 在使用渐进式披露方面变得非常熟练——在正确的时机加载正确的上下文。例如，我们将验证和代码审查移入了各自的技能中，Claude Code 可以有选择地调用它们。

但渐进式披露不仅适用于技能，我们也将其用于工具。我们的一些工具是“延迟加载”的，这意味着智能体必须在使用前通过 ToolSearch 搜索其完整定义。这使我们能够拥有更多工具（例如我们的 Task 工具），它们在需要之前不会占用上下文。

同样的方法也可以应用于你自己的 CLAUDE.md 和 Skill.md 文件。一个常见的误区是，你希望将这些文件做成一个包含所有已知实践的中央仓库，因为你可能会遇到它们，否则 Claude 就找不到它们。相反，考虑建立一个可以在正确时机加载的文件树。

然后：重复自己

现在：简洁的工具描述

早期的 Claude 模型有时需要重复的指令，或者更倾向于听从上下文窗口末尾而非开头的指令。这意味着我们的系统提示有时会在主系统提示中引用工具，同时在工具描述中也有指令。

我们发现可以删除这些重复的示例，将如何使用工具的指令放在工具描述中，而不是系统提示中。

然后：CLAUDE.md 文件中的记忆

现在：自动记忆

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

然后：简单的规格说明

现在：丰富的参考资料

在计划模式中，Claude Code 大量依赖包含计划的 markdown 文件。将这些文件存储为计划有助于 Claude 在需要时参考它们。另一个类似的最佳实践是将规格说明存储在代码库中，以便 Claude 在进行较长项目时参考。

但我们发现 Claude 能够处理越来越复杂的参考资料。Claude 可以引用由我们新的 artifacts 功能创建的 HTML 制品，而不是简单的 markdown 文件。

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

评分标准（Rubrics）是另一种形式的参考资料。评分标准允许 Claude 通过使用 动态工作流 并启动带有这些评分标准的验证器代理，来尝试并验证你在特定领域（例如，优秀的 API 设计是什么样的）的品味。

将此应用于你的上下文

把所有这些综合起来，当你组装你的上下文时，这看起来是什么样的？

系统提示

系统提示与产品上下文紧密相关。它告诉 Claude 它正在操作什么产品以及它在做什么。对于 Claude Code，你可能永远不需要修改它，但如果你是 在构建自己的代理框架，这就是你应该花费大量时间的地方。

CLAUDE.md

让你的 CLAUDE.md 保持轻量，简要描述你的仓库是做什么的，但把大部分 token 花在代码库中的陷阱上。例如，你可能将代码组织成将类型保存在一个整体文件中，而不在其他任何地方。避免陈述 Claude 通过查看你的文件系统或仓库就能知道的“显而易见”的事情。

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

技能

将 技能视为轻量级指南，以便 Claude 在需要时查找信息。避免让它们受到过多限制，除非是在非常重要的领域。

对于较长的技能，尽量尽可能多地使用渐进式披露——将其分成许多文件并拆分出来。

当技能编码了你、你的团队或产品特有的特定观点、知识或最佳实践时，效果最好。

参考资料

你可以通过 @ 提及文件来将它们作为参考资料包含在内。参考资料允许 Claude 参考有关当前计划的深入信息。

这可能在规范文件、模型设计图，甚至整个代码库中。通常你应该优先选择代码中的文件，因为它以 Claude 非常熟悉的语言提供了清晰、高保真的指令。例如，设计的 HTML 模型通常会比设计描述或截图产生更好的结果。

尝试简化

在你的系统提示、技能和 CLAUDE.md 文件中，你可能需要像我们一样进行简化。我们推出了一个名为 claude doctor 的新命令，它也将帮助你自动完成这项工作。有关专门针对更高级模型的提示的更多详细信息，请查看我们的 Fable 现场指南。

本文由 Anthropic 技术团队成员 Thariq Shihipar 撰写。