msd-core/docs/zh-CN/explanation/context-engineering.md

上下文工程

MSD Core 的存在原因及其旨在解决的问题。

---

问题：上下文腐化

每次 AI 编码会话都从全新开始。模型读取你的问题，对其进行推理，然后作出回复。但一次会话很少只有一轮交互。你会追问后续问题、粘贴错误信息、迭代代码，并在模型偏离方向时加以纠正。每一轮都会向上下文窗口中添加令牌——这是一个模型在同一时刻能"看到"的有限文本缓冲区。

随着该窗口逐渐填满，一些微妙的变化随之而来。模型不会高调地出错，它仍然持续作答，但答案的质量会悄然下降。早期的指令被推到它所能关注范围的边缘。最初几轮交互中的细节——你陈述的约束、你达成共识的架构、你标注的边界情况——都在与后续堆积的内容争夺注意力。研究人员将这种现象称为上下文腐化。

上下文腐化会以多种方式显现：

• 模型开始与它此前已认可的决定相矛盾。
• 代码风格偏离了会话开始时确立的规范。
• 计划开始忽略那些明确陈述过、但如今已深埋于历史记录中的需求。
• 模型产生幻觉，给出二十条消息前还正确的文件名或函数签名。

这些问题都不是模型的 bug。这是 Transformer 注意力机制在长序列上运作的基本属性。模型并非在"遗忘"——它从未以人类的方式"记住"过任何东西。它在有限窗口中对相关性进行加权，而随着窗口被积累的噪声填满，信噪比不断下降。

最直觉的应对方式是使用 /clear 重新开始。但这会丢失连贯性。你必须重新解释背景、重新粘贴相关文件、重新陈述约束条件。会话实质上归零重启了。

---

MSD Core 的答案：全新上下文的子智能体

MSD Core 的核心洞见是：编码会话中大多数工作根本无需在主上下文中完成。研究、规划、代码编写和验证各自是独立且边界清晰的任务。每项任务都可以交给一个专门的子智能体来处理——该智能体以一个干净、精心限定范围的上下文窗口启动，并将其结果报告给一个保持精简状态的薄层编排器。

这不是上下文腐化的变通之法，而是一种结构性解决方案。

编排器——也就是你的主会话——从不接触源文件。它生成智能体、收集其结果、更新共享状态，并路由到下一个步骤。正因为它自身承担的工作很少，其上下文窗口的增长缓慢且可预测。繁重的工作发生在各个智能体中——每个智能体都以全新状态启动，仅接收完成其任务所需的上下文，并在完成后终止。

考虑这在实践中意味着什么。当你运行 /msd-plan-phase 时，编排器会：

1. 加载一个紧凑的 JSON 上下文有效载荷（项目摘要、阶段目标、相关配置）。
2. 生成一个拥有 20 万令牌全新窗口的研究智能体。
3. 以研究输出和阶段需求为输入，生成一个规划智能体。
4. 生成一个计划检查智能体，在执行前验证计划。

每个智能体都以满负荷运行，不受会话积累历史的拖累。当规划器将其 PLAN.md 文件写入 .planning/phases/ 时，该输出成为持久的产物——而非共享上下文窗口中脆弱的记忆。

---

规格驱动开发与元提示

仅靠上下文工程还不够。如果一个智能体以全新状态启动，却接收到模糊的指令，它产生的输出也将是模糊的。MSD Core 将全新上下文的子智能体与两项互补的原则相结合：

规格驱动开发意味着每个阶段在执行开始之前都会生成结构化产物。CONTEXT.md 捕获来自讨论步骤的实现决策。RESEARCH.md 记录研究智能体的发现。PLAN.md 将工作分解为离散的、按依赖关系排序的任务，并附有明确的验收标准。在执行器智能体接触文件之时，它已拥有一份精确的规格说明——而非对一段漫长对话的重新解读。

元提示意味着智能体定义本身就是经过精心设计的提示，而非临时指令。msd-core/workflows/ 和 agents/ 中的文件编码了关于如何限定任务范围、需要验证什么，以及何时上报至人工检查点的宝贵经验。用户无需在每次会话中重新解释这些知识；它已内嵌于系统自身的提示中。

这种组合是刻意为之的。全新上下文确保每个智能体清晰推理。规格驱动的产物确保每个智能体针对正确的事物进行推理。元提示确保每个智能体知道如何将其做好。

---

.planning/ 的作用

上下文工程要求知识能在上下文重置后得以保留。MSD Core 为此使用文件系统。每一项有意义的输出都以人类可读的 Markdown 或 JSON 格式写入 .planning/。这意味着：

• 重启会话（或模型崩溃）不会丢失工作成果。
• 任何后续智能体都可以直接读取先前的产物，而无需依赖共享的对话历史。
• 你可以检查、编辑规划产物，或将其提交到 git——它们是纯文本，而非数据库中不透明的状态。

STATE.md 是这个系统的支柱。它记录项目的当前位置（处于哪个里程碑、哪个阶段、哪些计划已完成）、活跃的决策和阻碍项，以及进度指标。每当工作流启动时，它都会读取 STATE.md 来定向自身。每当工作流完成一个有意义的步骤时，它都会回写 STATE.md。智能体不依赖记忆；它们依赖文件。

---

权衡

这里需要如实说明权衡之处。

额外开销。 阶段循环引入了真实的摩擦。将 /msd-discuss-phase、/msd-plan-phase 和 /msd-execute-phase 作为独立步骤运行，比直接在普通会话中输入"实现这个功能"需要更多的耗时。对于小型、已充分理解的改动，这种开销并不值得。

延迟。 生成多个拥有全新上下文的子智能体，比单次上下文内编辑要慢。研究、规划和执行各自都会产生往返成本。

简单任务的繁文缛节。 如果你只需要重命名一个变量、修复一个错别字，或添加一个缺失的导入，阶段循环就是杀鸡用牛刀。MSD Core 提供了 /msd-quick 和 /msd-fast，用于处理不需要完整阶段的临时工作。请参阅处理快速任务。

当工作足够复杂、上下文腐化成为真实风险时，阶段循环才物有所值——例如多文件功能、横切重构、跨越数小时或多个会话的工作。其他情况下，请使用更轻量的原语。

一个有用的经验法则：如果任务可以用一个简短的提示完整描述，且无需进一步澄清就能在一次智能体回合中完成，跳过阶段循环。如果任务需要研究、涉及你近期未读取的文件，或依赖尚未确定的决策，阶段循环则能保护你。

---

相关内容

• 阶段循环 — 讨论 → 规划 → 执行 → 验证 → 发布的循环如何将上下文工程付诸实践
• 多智能体编排 — 子智能体如何被生成、限定范围和协调
• 架构 — 系统架构、智能体模型和数据流
• 文档索引