Claude 5 时代的 Context 工程最佳实践指南

我们为更先进的模型删掉了 Claude Code 系统 prompt 中超过 80% 的内容。下面介绍如何将我们从中总结的经验，应用到你在 Claude Code 以及自有 Agent 中的 context engineering。

类别：Claude Code、Agent

产品：Claude Code、Claude Enterprise、Claude Platform

分享：复制链接

我之前写过，如何更好地为最新一代 Claude 5 模型编写 prompt，以及如何通过迭代协作，逐步探索出你真正想构建的东西。

但当你向 Claude 发送消息时，prompt 只是它所接收 context 中很小的一部分。你的大部分 context 来自系统 prompt、Skills、CLAUDE.md 文件、memory 以及其他来源的组合。我们将这个过程称为 context engineering。无论是使用 Claude Code，还是构建自己的 Agent，它都会显著影响最终生成的结果。

与 prompt 不同，context 通常会被用于大量不同的请求，因此不能写得过于具体。那么，应该如何为 Claude 构建这些通用的 prompt 和指导信息，特别是在你根本不知道用户可能会输入什么 prompt 的情况下？

随着 Claude 自身能力不断演进，这件事可能会出乎意料地困难。最近，我们注意到，为最新一代 Claude 模型编写 prompt 的方式发生了巨大变化。对于 Claude Opus 5 和 Claude Fable 5 这样的模型，我们删掉了 Claude Code 系统 prompt 中超过 80% 的内容，而在编码评测中没有观察到任何可衡量的性能损失。

下面是我们在为这类新模型编写 prompt 时总结的经验，以及你如何利用这些经验更新自己的 context engineering。我们已经将这些最佳实践加入 claude doctor;；在 Claude Code 中使用命令 /doctor，即可合理调整 Skills 和 CLAUDE.md 文件的规模。

总体而言，我们发现，无论是在系统 prompt 中，还是在 CLAUDE.md 文件与 Skills 中，我们都对 Claude Code 施加了过多约束。

例如，当我们阅读内部使用 Claude Code 的对话记录时，会发现同一个请求中经常同时出现多条互相冲突的信息，比如“在适当的情况下保留文档”，以及“DO NOT add comments”。这是因为系统 prompt、Skills 和用户请求之间发生了冲突。

一般来说，Claude 能够理解用户意图并得出正确答案，但在决定具体该怎么做之前，它必须更加谨慎地思考这些彼此重叠、互相冲突的信息。

这些约束过去确实有必要，可以帮助我们规避最坏情况；但后来我们发现，其中很多都可以删除，让模型根据周围的 context 和自身判断来做决定。

此外，Claude Code 现在拥有的工具也多得多。过去，Claude 依赖 CLAUDE.md 来获取 memory、信息和指导。现在我们有了 memory、artifacts 和 Skills，Claude 可以利用它们创造新的方式，跨会话加载和共享 context。

许多过去被视为 context engineering 最佳实践的做法，如今已经变成了误区，其中包括：

过去：给 Claude 制定规则

现在：让 Claude 运用判断力

刚推出 Claude Code 时，我们必须确保 Claude 能够避免最坏情况，例如删除文件。这意味着我们会提供非常强硬的指导，即使这些指导并不总是正确。例如，我们过去曾在系统 prompt 中这样写：

在代码中：默认不写注释。绝对不要编写多段 docstring 或多行注释块——最多只能写一行简短注释。除非用户明确要求，否则不要创建规划、决策或分析文档——应根据对话 context 开展工作，而不是依赖中间文件。

但对于某些 prompt，这样的指导是错误的。以文档为例，用户可能有自己的偏好，而某些非常复杂的代码也可能确实需要多行注释块。

尽管如此，对于较老的模型来说，如果没有这些护栏，Claude 编写的注释在很多情况下都会有问题，因此我们不得不接受这种取舍。但新模型拥有更好的判断力，即使没有明确规则，也能妥善处理这些决定。

在新的系统 prompt 中，我们这样写：编写与周围代码风格一致的代码，包括注释密度、命名方式和惯用写法。

过去：给 Claude 提供示例

现在：设计接口

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

与其使用示例，不如更多地思考工具、脚本和文件的设计——Claude 可以使用哪些参数？如何让这些参数具备更强的表达能力？

例如，在 Todo 工具中，只要把 status 列为 pending、in_progress 和 completed 三个枚举值，就能提示 Claude 应该如何使用它。要求始终只保留一个 in_progress 项目的指令，也有助于定义我们期望的行为。

过去：一开始就把所有内容全部提供出来

现在：使用渐进式披露

由于 Claude Code 专注于编码，我们的系统 prompt 曾包含如何进行代码审查和验证的详细信息。这些信息并非总能派上用场，但一旦需要，就至关重要。

此后，Claude Code 已经非常擅长使用渐进式披露，也就是在合适的时间加载正确的 context。例如，我们将验证和代码审查分别移入独立的 Skills，让 Claude Code 可以按需调用。

但渐进式披露并不只适用于 Skills，我们也将其用于工具。部分工具采用“延迟加载”，这意味着 Agent 在使用它们之前，必须先通过 ToolSearch 搜索完整定义。这样，我们就可以提供更多工具，例如 Task 工具，同时在它们真正被需要之前，不会占用 context。

同样的思路也可以应用到你自己的 CLAUDE.md 和 Skill.md 文件。一个常见误区是，应该把这些文件当成中央知识库，囊括所有可能遇到的已知实践，否则 Claude 就找不到这些信息。更好的方式是构建一个文件树，让 Claude 能在合适的时间加载相应文件。

过去：重复指令

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

较早的 Claude 模型有时需要重复指令，或者更容易遵循 context window 末尾的指令，而不是开头的指令。因此，我们有时不仅会在工具描述中编写使用说明，还会在主系统 prompt 中再次提及这些工具。

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

过去：将 memory 存入 CLAUDE.md 文件

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

在 plan mode 中，Claude Code 一直高度依赖包含计划的 Markdown 文件。将这些文件保存为计划，有助于 Claude 在需要时引用它们。另一个类似的最佳实践，是将规格说明保存在代码库中，供 Claude 在长期项目的工作过程中参考。

但我们发现，Claude 现在已经能够处理越来越复杂的引用。除了简单的 Markdown 文件，Claude 还可以引用由新 artifacts 功能创建的 HTML artifacts。

你也可以用代码的形式为 Claude 提供引用。规格说明既可以是一套详细的测试，也可以是另一个代码库中的某个函数，供 Claude 移植。

Rubrics 也是一种引用形式。Claude 可以通过 Rubrics 尝试验证你在特定领域中的品味，例如什么样的 API 设计才算优秀。它可以使用动态工作流，并启动带有这些 Rubrics 的验证 Agent 来完成这项工作。

将这些原则应用到你的 context

把以上内容整合起来，当你组装自己的 context 时，具体应该是什么样子？

系统 prompt 与产品 context 高度相关。它告诉 Claude 当前运行在哪个产品中，以及正在做什么。对于 Claude Code，你可能永远都不需要修改它；但如果你正在构建自己的 Agent harness，就应该在这里投入大量时间。

让 CLAUDE.md 保持轻量，只需简要说明代码库的用途；大部分 token 应该用来记录代码库中的易错点。例如，你可能要求所有类型都集中放在一个单体文件中，其他地方一律不能定义。不要陈述那些 Claude 通过查看文件系统或代码库就应该能够知道的“显而易见”的内容。

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

将 Skills 看作轻量级指南，帮助 Claude 在需要时找到相关信息。除非涉及极其重要的领域，否则不要对 Skills 施加过多约束。

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

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

你可以使用 @ 提及文件，将其纳入引用。引用可以让 Claude 查阅与当前计划相关的详细信息。

这些引用可以是规格文件、mockup，甚至是整个代码库。通常应该优先选择以代码形式存在的文件，因为它们能用 Claude 非常熟悉的语言，为其提供清晰且高保真的指令。例如，一个设计的 HTML mockup，通常会比设计说明或截图带来更好的结果。

你的系统 prompt、Skills 和 CLAUDE.md 文件可能都需要像我们一样进行简化。我们推出了一个名为 claude doctor, 的新命令，它也可以帮助你自动完成这项工作。若想进一步了解如何专门为更先进的模型编写 prompt，请参阅我们的 Fable 实战指南。

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

利用 Claude 改变组织的运作方式

订阅开发者新闻通讯

每月将产品更新、操作指南、社区精选等内容发送到你的邮箱。