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

中文精读

原文约 1,728 词 · 15 节

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

   • 文章主题：为 Claude 5 代模型（如 Claude Opus 5、Claude Fable 5）重写上下文工程的做法，并把这套经验用到 Claude Code 和自己的 agent 上。
   • 关键数据：针对新一代模型，Claude Code 的系统提示词被删掉了 80% 以上，编码评测上没有可测量的损失。
   • 作者指出，发给 Claude 的消息里提示词只占一小部分，其余上下文来自系统提示词、Skills、CLAUDE.md、记忆等，这部分即上下文工程。
   • 上下文与单次提示词不同，它跨多个请求通用，因此无法写得那么具体；难点在于不知道用户会问什么，却要写通用指导。
   • 文中把最佳实践做进了 `claude doctor`，在 Claude Code 中用 `/doctor` 命令可以调整 skills 与 CLAUDE.md 的规模。

2. 解除对 Claude 的束缚（Unhobbling Claude）

   • 总体发现：系统提示词、CLAUDE.md 和 skills 对 Claude Code 构成了过度约束。
   • 读内部使用记录时，单个请求里会出现互相冲突的话，比如“按需保留文档”与“不要加注释”，系统提示词、skills 和用户请求彼此打架。
   • Claude 一般能从用户意图推断正确答案，但面对这些重叠冲突的信息必须先多想一步再决定怎么做。
   • 这些限制原本是为了避免最坏情况，现在很多可以直接删掉，改由模型依据周边上下文和判断力处理。
   • Claude Code 的工具变多了：过去靠 CLAUDE.md 承载记忆、信息和指导，现在有记忆、artifacts 和 skills，可以创造新的跨会话加载与共享上下文的方式。

3. 过去与现在：几点过时的做法

   • 这一节是过渡段落：列出过去曾被当作上下文工程最佳实践、如今已成“误区”的若干做法。
   • 文章随后按“现在（Now）”逐条展开替代做法，共六点，下面几节分别对应。

4. 现在：让 Claude 自己判断

   • 早期上线 Claude Code 时要确保模型不踩最坏情况（例如删文件），因此给出可能并不总成立的很强硬指导。
   • 旧系统提示词要求：默认不写注释、绝不写多段 docstring 或多行注释块（最多一行）、除非用户要求否则不创建规划/决策/分析文档。
   • 对某些提示词这类指导是错的：用户可能有自己的文档偏好，复杂代码的个别部分也可能需要多行注释块。
   • 旧模型若没有这些护栏，写出的注释在很多情况下会不正确，当时只能接受这个取舍；新模型判断力更好，无需显式规则也能处理好。
   • 新系统提示词改为：写代码要像周围的代码一样，匹配其注释密度、命名和惯用法。

5. 现在：设计接口

   • 过去工具使用的第一原则是给 Claude 示例演示怎么用；对最新模型，示例反而会把它的探索空间限定住。
   • 替代思路是把重心放在工具、脚本和文件的设计上：Claude 有哪些参数，参数怎样表达才更有表现力。
   • 以 Todo 工具为例，把状态设计成 pending、in_progress、completed 的枚举，本身就在暗示 Claude 该怎么用。
   • 要求同时只保持一项处于 in_progress 的说明，也起到了定义所期望行为的作用。

6. 现在：渐进式披露（Progressive disclosure）

   • 早期因为主打编码，系统提示词里包含详细的代码审查与验证说明；这些并不总用得上，但需要时很关键。
   • Claude Code 现在很擅长渐进式披露，即在恰当的时刻加载恰当的上下文；例如验证和代码审查被拆成独立 skills，由 Claude Code 按需调用。
   • 渐进式披露也用于工具：部分工具采用“延迟加载”，agent 必须先用 ToolSearch 搜到完整定义才能使用，这样能容纳更多工具（如 Task 工具）而不占用上下文。
   • 同样适用于自己的 CLAUDE.md 和 Skill.md：常见误区是把它们做成“可能遇到的所有实践”的中央仓库。
   • 更合适的做法是组织成一棵文件树，在需要时加载对应文件。

7. 现在：精简的工具描述

   • 较早的模型有时需要重复指令，且更容易听信上下文窗口末尾的指令而不是开头的。
   • 因此旧做法会在主系统提示词里引用工具，同时又在工具描述里重复一遍说明。
   • 现在这些重复示例可以删掉，把工具使用说明直接写进工具描述，而不是放在系统提示词里。

8. 现在：自动记忆

   • 过去鼓励用户主动保存内容：用 `#` 快捷键自动写入自己的 `CLAUDE.md`。
   • 现在 Claude 会自动保存与当前工作相关、也与你本人相关的记忆，不再需要这套手动流程。

9. 现在：更丰富的引用形式

   • 计划模式下曾高度依赖 markdown 计划文件，把这些文件存下来便于 Claude 按需查阅。
   • 类似做法还有把规格说明（spec）放进代码库，供 Claude 在较长的项目中参考。
   • 现在 Claude 能处理更复杂的引用：可以用新的 artifacts 功能生成的 HTML artifacts，替代简单的 markdown 文件。
   • 引用也可以做成代码形式：一份 spec 可能是一套详细的测试套件，或另一代码库中可供移植的函数。
   • 评分标准（rubrics）也是一种引用，让 Claude 通过动态工作流和按 rubrics 启动的验证 agent 来校验你在某领域（如 API 设计好坏）的口味。

10. 把这些应用到你的上下文

    • 这一节是过渡段落，承上启下：把前面各条原则汇总，说明组装上下文时各部分应该长什么样。
    • 后文分别从系统提示词、CLAUDE.md、Skills、引用四类上下文展开。

11. 系统提示词

    • 系统提示词与产品语境强绑定，它告诉 Claude 正在什么产品里运行、在做什么。
    • 在 Claude Code 里基本永远不会改动它；如果自己在搭 agent harness，这里才是值得大量投入的地方。

12. CLAUDE.md

    • 保持 CLAUDE.md 轻量：简短说明仓库用途，大部分 token 花在代码库里的坑（gotchas）上。
    • 例如说明代码组织约定：类型统一放在单个大文件里、别处不放。
    • 避免写 Claude 看文件系统或仓库就能知道的“显而易见”的内容。
    • 大幅使用渐进式披露：例如验证方式有多条特殊要求时，建一个 verification skill，并在 CLAUDE.md 里引用它。

13. Skills

    • 把 skills 当作轻量指南，让 Claude 在需要时找到信息。
    • 不要把它们写得过度约束，只有极重要的领域例外。
    • 较长的 skill 尽量用渐进式披露：拆成多个文件分开存放。
    • skills 最适合承载你自己、团队或产品特有的观点、知识和最佳实践。

14. 引用（References）

    • 可以用 @ 提及文件，把它作为引用纳入上下文；引用让 Claude 参考当前计划的深入信息。
    • 引用可以是规格文件、mockup，甚至整个代码库。
    • 一般优先用代码形式的文件，因为它用 Claude 熟悉的语言给出清晰、高保真的指令。
    • 例如设计的 HTML mockup 通常比文字描述或截图产生更好的结果。

15. 尝试简化

    • 系统提示词、skills 和 CLAUDE.md 都可能需要像 Anthropic 那样做简化。
    • 新推出的 `claude doctor` 命令能帮用户自动完成这件事。
    • 想要更多针对更高级模型的提示词细节，可参阅 Fable 实战指南。