Claude 5 代模型的上下文工程新规则
核心要点
- 删繁就简：Anthropic 为 Claude Opus 5、Claude Fable 5 等新一代模型删除了 Claude Code system prompt 中 80% 以上的内容，编码评测指标没有任何可测量的下降——过去为了兜底而堆砌的硬性规则，现在多数可以删掉，交给模型的判断力。
- 给判断力，别给硬规则：不要用"绝不写注释""不要生成文档"这类一刀切指令去约束模型；改为让它"写出与周围代码风格一致的代码"，靠上下文和判断力自行取舍。
- 设计接口，别堆示例：与其给工具用法举例（会把模型的探索空间框死），不如把精力花在工具/脚本/文件的接口设计上——用富有表达力的参数（如枚举状态）来暗示正确用法。
- progressive disclosure（渐进式披露）：别把所有可能用到的知识一股脑塞进 CLAUDE.md 或 skill；把它拆成"按需加载的文件树"，用 skills、deferred loading 工具在恰当时机加载恰当上下文。
- 动手精简你自己的上下文：CLAUDE.md 保持轻量、聚焦代码库里的"坑点"；skill 用来编码你/团队/产品特有的观点与最佳实践；references 优先用代码形式（如 HTML mockup 胜过截图或文字描述）。可用新命令 claude doctor / /doctor 自动帮你瘦身。
原文 英文原文：The new rules of context engineering for Claude 5 generation models
Claude 5 代模型的上下文工程新规则
我们为更先进的模型删除了 Claude Code system prompt 中 80% 以上的内容。本文分享我们从中学到的经验，以及如何把它应用到你自己在 Claude Code 里、乃至构建自有 agent 时的 context engineering（上下文工程）实践中。
我此前写过如何最好地为新一代 Claude 5 模型撰写 prompt，以及如何与它们迭代协作、逐步厘清自己到底想做什么。
但当你给 Claude 发一条消息时，prompt 只是它拿到的上下文的一小部分。你的大部分上下文,其实是由 system prompt、Skills、CLAUDE.md 文件、memory 以及其他来源共同拼装而成的。我们把这件事称为 context engineering（上下文工程）,它对你在使用 Claude Code 或构建自有 agent 时得到的结果影响巨大。
与 prompt 不同,上下文是被众多请求通用复用的,因此它没法像 prompt 那样具体。那么,在你并不知道用户会输入什么 prompt 的前提下,该如何为 Claude 构建这些通用的提示和指引呢？
随着 Claude 自身能力的演进,这件事会难得出人意料。最近一次,我们注意到为新一代 Claude 模型撰写 prompt 的方式发生了很大跃迁:针对 Claude Opus 5、Claude Fable 5 这样的模型,我们删除了 Claude Code system prompt 中 80% 以上的内容,而在我们的编码评测上没有任何可测量的损失。
以下是我们关于为这一新类别模型撰写 prompt 的心得,以及你可以如何借鉴它来更新自己的 context engineering。我们已经把这些最佳实践内置进了 claude doctor;在 Claude Code 里使用 /doctor 命令,就能帮你把 skills 和 CLAUDE.md 文件调整到合适的规模。
为 Claude "松绑"（Unhobbling）
总体而言,我们发现自己对 Claude Code 施加了过度约束——无论是通过 system prompt,还是在 CLAUDE.md 文件与 skills 里。
举个例子,当我们翻阅自己内部使用 Claude Code 的会话记录时,会在同一个请求里看到好几条互相冲突的指令:比如 system prompt、skills 和用户请求彼此打架,一边说"酌情保留文档(leave documentation as appropriate)",另一边又说"不要添加注释(DO NOT add comments)"。
一般来说,Claude 能够领会用户的意图、给出正确答案,但它必须先更审慎地权衡这些重叠且冲突的指令,才能决定该怎么做。
这些约束曾经是必要的——它们用来规避最坏情况;但如今我们发现,可以删掉其中许多条,转而让模型借助周围的上下文和自身判断力来处理。
此外,Claude Code 现在拥有了多得多的工具。过去 Claude 主要依赖 CLAUDE.md 作为 memory、信息和指引的来源;而现在我们有了 memory、artifacts 和 skills,Claude 可以用它们创造出跨会话加载、共享上下文的新方式。
或者你也可以阅读官方文档。
昔与今
此前不少 context engineering 的"最佳实践",如今已经变成了迷思,包括:
昔:给 Claude 定规则
今:让 Claude 用判断力
我们最初推出 Claude Code 时,必须确保 Claude 避开最坏情况,比如删除文件。这意味着我们会给出一些格外强硬、却未必总是成立的指引。例如,过去我们在 system prompt 里会这样写:
写代码时:默认不写注释。绝不写多段落的 docstring 或多行注释块——最多一行短注释。除非用户要求,否则不要创建规划、决策或分析文档——依据对话上下文工作,而不是生成中间文件。
但对某一类 prompt 而言,这种指引是错的。以文档为例:用户可能有自己的偏好,或者某些极其复杂的代码片段确实需要多行注释块来说明。
尽管如此,对旧模型而言,如果没有这些护栏,Claude 写出的注释在很多情况下都会是错的,我们不得不接受这种取舍。但新模型有更好的判断力,无需明确规则也能把这些决定处理得很好。
在新的 system prompt 里,我们改成这样说:写出读起来和周围代码一致的代码:匹配它的注释密度、命名方式和惯用写法。
昔:给 Claude 举例子
今:设计接口
工具使用的第一铁律,曾经是给 Claude 演示该怎么用。而在最新模型上我们发现,给例子反而会把它们约束在某个特定的探索空间里。
与其举例子,不如多花心思在工具、脚本和文件的接口设计上——Claude 有哪些参数可用?这些参数怎样才能更具表达力?
举例来说,在 Todo 工具的例子里,仅仅把状态列为 pending、in_progress、completed 三者之间的枚举,就已经在向 Claude 暗示该怎么用它;而"任何时刻只保留一项处于 in_progress"这条说明,则帮助界定了我们期望的行为。
昔:全部前置塞满
今:用 progressive disclosure(渐进式披露)
由于 Claude Code 专注于编码,我们的 system prompt 里曾包含大量关于如何做 code review 和验证的详细信息。这些信息并非总是用得上,但一旦需要,就是至关重要的。
从那以后,Claude Code 已经非常擅长运用 progressive disclosure——在恰当的时机加载恰当的上下文。举例来说,我们把验证和 code review 挪进了各自独立的 skill,让 Claude Code 可以按需选择性地调用它们。
但 progressive disclosure 不只适用于 skill,我们对工具也采用同样思路。我们的一部分工具是"延迟加载(deferred loading)"的,也就是说 agent 在使用它们之前,必须先通过 ToolSearch 搜索出完整的定义。这让我们能够拥有更多工具(比如我们的 Task 工具),而它们在真正被用到之前不会占用上下文。
同样的做法也适用于你自己的 CLAUDE.md 和 Skill.md 文件。一个常见的迷思是:你想把它们做成一个中央仓库,把每一条你可能用到的实践统统塞进去,因为担心 Claude 否则就找不到。恰恰相反,不妨设计成一棵可以在恰当时机加载的文件树。
昔:反复叮嘱
今:简洁的工具描述
早期的 Claude 模型有时需要重复的指令,或者更倾向于听从上下文窗口末尾而非开头的指令。这导致我们的 system prompt 有时会既在主体部分提到某个工具,又在该工具的描述里再写一遍使用说明。
我们发现,这些重复的例子完全可以删掉,把"如何使用工具"的说明放进工具描述里,而不是塞进 system prompt。
昔:把 memory 写进 CLAUDE.md
今:自动 memory
我们过去会鼓励用户把东西存进 Claude 的 memory,方法是用 # 快捷键自动写入他们的 CLAUDE.md。而现在,Claude 会自动保存那些与当前工作以及与你相关的 memory。
昔:简单的 spec
今:丰富的 references
在 plan mode 下,Claude Code 一直高度依赖装着计划的 markdown 文件。把计划存成文件,便于 Claude 在需要时回头参考。另一个类似的最佳实践,是把 spec 存进代码库,供 Claude 在跨越更长周期的项目中随时查阅。
但我们发现,Claude 能够驾驭日益复杂的 references。除了简单的 markdown 文件,Claude 还可以引用由我们新的 artifacts 功能创建的 HTML artifact。
你也可以用代码的形式给 Claude 提供 references。一份 spec 可以是一套详尽的测试套件,也可以是另一个代码库里、有待 Claude 移植的某个函数。
Rubric(评分标准)是 references 的又一种形式。Rubric 让 Claude 可以借助动态工作流(dynamic workflows),启动带有这些 rubric 的验证器 agent,去尝试并核验你在某个领域的品味(比如:什么样才算好的 API 设计)。
把这些应用到你自己的上下文里
把上面这些串起来,当你亲手拼装自己的上下文时,它会是什么样子?
System Prompt
System prompt 与产品语境紧密绑定。它告诉 Claude 自己正运行在什么产品里、在做什么。对 Claude Code 而言,你大概永远都不会去改动它;但如果你在构建自己的 agent harness,这里就是你应当投入大量精力的地方。
CLAUDE.md
让你的 CLAUDE.md 保持轻量,简要说明这个仓库是干什么用的,而把大部分 token 花在代码库里的"坑点(gotchas)"上。比如,你可能把所有类型定义都集中放在某一个巨型文件里、别处一概没有——这类事就值得写。要避免陈述那些"显而易见"、Claude 只要看一眼你的文件系统或仓库就能知道的事。
大量运用 progressive disclosure。举例来说,如果你有好几条关于如何验证工作成果的特殊说明,就把它们做成一个验证 skill,并从 CLAUDE.md 里引用它。
Skills
把 skill 想象成轻量的指南,让 Claude 在需要时找到信息即可。除了在极为关键的领域,不要把它们做得过度约束。
对于篇幅很长的 skill,尽量运用 progressive disclosure——把它拆成多个文件、分而治之。
skill 最理想的用法,是把那些专属于你、你的团队或你的产品的特定观点、知识或最佳实践编码进去。
References
你可以用 @ 提及文件,把它们作为 references 纳入。References 让 Claude 能够参考关于当前计划的深入信息。
这些 references 可以是 spec 文件、mockup(原型),甚至是整个代码库。总体而言,你应当优先选用代码形式的文件,因为它能给 Claude 提供清晰、高保真、且用它非常熟悉的语言写就的指令。举例来说,一份设计的 HTML mockup,通常会比一段设计描述或一张截图产生更好的结果。
试着做减法
在你的 system prompt、skills 和 CLAUDE.md 文件里,你或许都需要像我们一样做减法。我们推出了一个新命令 claude doctor,它也能帮你自动完成这件事。想了解更多专门针对更先进模型的 prompt 撰写方法,请参阅我们的 Fable field guide。
本文作者为 Anthropic 技术团队成员 Thariq Shihipar。
产品更新、操作教程、社区精选等内容,每月一期,直达你的收件箱。
Related Documents
- AI 技术博客索引
- 英文原文：Original