a9a7a328e6
Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD across contents and paths, upstream package/repo coordinates -> @golem15/msd-core and golem15com/msd-core. Deep links into upstream history, sibling upstream packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is. Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line, package/plugin identity, regenerated lockfile, install-tree fixtures, derived registries and benchmark baseline; migration checksum baseline re-locked (MSD keeps its own install state, so no install had applied the old sums); sort-order and regex-escaped expectations in tests adjusted.
130 lines
9.0 KiB
Markdown
130 lines
9.0 KiB
Markdown
# 阶段循环
|
||
|
||
> MSD Core 组织工作的核心思维模型。
|
||
|
||
---
|
||
|
||
## 循环是什么
|
||
|
||
MSD Core 将所有开发工作结构化为一个重复周期：
|
||
|
||
```text
|
||
Discuss → (UI design) → Plan → Execute → Verify → Ship
|
||
```
|
||
|
||
每个工作单元——称为**阶段**——按顺序经历这些步骤。循环并非形式主义。每个步骤的存在都是为了防范某一类特定的失败，而这类失败是上一步骤单独无法预防的。
|
||
|
||
本文档解释*为什么*循环是这种形态。有关运行每个步骤的操作说明，请参见底部链接的操作指南。
|
||
|
||
---
|
||
|
||
## 每个步骤存在的原因
|
||
|
||
### Discuss
|
||
|
||
在知道*如何*构建某物之前，规划无法开始——而不仅仅是*构建什么*。`ROADMAP.md` 中的阶段目标描述了结果。Discuss 步骤捕捉塑造通往该结果路径的实现决策：选用哪些库、采用哪种错误处理策略、某功能是按路由还是全局实现、边缘情况应如何处理。
|
||
|
||
没有 Discuss 步骤，规划器必须自行做出这些判断。有时它猜对了。但往往猜得似是而非却实际有误——产出一个逻辑连贯却与你实际偏好相悖的计划。等到执行完成、发现错误时，你已经在撤销大量工作了。
|
||
|
||
Discuss 步骤刻意保持轻量。它是一次对话，而非规格说明练习。输出是阶段目录中的 `CONTEXT.md`：一份规划器、执行器和验证器都可以阅读的结构化决策记录。对话只需几分钟，却能节省数小时的返工时间。
|
||
|
||
### UI design（可选）
|
||
|
||
对于有视觉组件的阶段，在 Discuss 和 Plan 之间有一个可选的 `/msd-ui-phase` 步骤。它生成 `UI-SPEC.md`——一份在编写任何代码之前描述布局、交互和视觉行为的设计契约。当 UI 足够复杂，设计中的歧义会导致不同的实现选择时，值得运行此步骤。一份清晰的设计契约比重新实现要便宜得多。
|
||
|
||
### Plan
|
||
|
||
Plan 步骤完成执行所需的研究、分解和结构性思考。它以一系列全新上下文的子代理运行：一个研究者调查生态系统并将发现记录在 `RESEARCH.md` 中，一个规划器同时阅读研究结果和 `CONTEXT.md` 以生成 `PLAN.md` 文件，以及一个计划检查器验证计划是否完整、一致且在范围内。
|
||
|
||
计划包含什么？每个 `PLAN.md` 描述一个有边界的工作单元：需要修改的文件、要做的具体更改、定义完成状态的验收标准。计划按依赖波次排序，以便并行执行是安全的——同一波次中的执行器处理互不重叠的关注点。
|
||
|
||
Plan 步骤是歧义代价最高的时刻。一个模糊的计划会产生一个需要做假设的执行器。多个并行执行器对同一关注点做出不同假设会产生冲突。计划检查器的工作是在执行开始前捕捉这些问题，而不是事后。
|
||
|
||
### Execute
|
||
|
||
执行运行计划。每个执行器获得一个全新的 200k token 上下文窗口，其中精确加载了它所需的内容：项目摘要、阶段上下文、研究结果，以及其任务对应的特定 `PLAN.md`。仅此而已。
|
||
|
||
执行器编写代码并原子性地提交。每次提交对应计划中的一个已完成任务。当一波并行执行器完成时，协调器合并其状态并开始下一波。
|
||
|
||
执行器的全新上下文不是便利设施——它是防止上下文腐化的机制。一个带着 180k token 积累会话历史运行的执行器是一个性能退化的执行器。一个干净启动、只读取其计划所需内容的执行器，是以满状态运行的执行器。
|
||
|
||
### Verify
|
||
|
||
所有执行器完成后，一个验证器代理读取阶段目标、`CONTEXT.md` 决策、计划和执行摘要——并检查构建的内容是否与预期相符。它生成 `VERIFICATION.md`，如果存在差异，则生成有针对性的修复计划。
|
||
|
||
验证不仅仅是测试。它检查需求覆盖率（所有 REQ-ID 都被处理了吗？）、决策覆盖率（`CONTEXT.md` 中记录的决策是否实际实现了？），以及整体阶段目标对齐情况。阶段完成不是因为执行没有报错。而是因为构建的内容符合计划，计划的内容符合决策。
|
||
|
||
### Ship
|
||
|
||
Ship 步骤创建拉取请求并归档阶段产出物。`STATE.md` 更新以标记阶段完成。循环随后为下一个阶段重新开始。
|
||
|
||
---
|
||
|
||
## 里程碑与阶段
|
||
|
||
**里程碑**是一个版本周期——项目有意义的、可发布的增量。它有名称、版本号，以及定义其必须交付内容的一组需求。当里程碑的所有阶段都已发布且需求都已覆盖时，里程碑才算完成。
|
||
|
||
**阶段**是里程碑中的一个工作单元。阶段有目标、它所处理的一组需求，以及实现它的一组计划。
|
||
|
||
这种关系很重要，因为里程碑和阶段有不同的关注范围。里程碑问："这个版本的产品能做什么，不能做什么？"阶段问："下一个我们可以研究、规划、执行和验证的有边界的事情是什么？"
|
||
|
||
里程碑边界划定在自然产品边界处——一个可部署的 API、一个可用的 UI 流程、一个完整的数据模型。阶段边界划定在可以在一次循环中安全执行而不使循环变得笨重的工作量极限处。
|
||
|
||
---
|
||
|
||
## 什么是好的阶段范围
|
||
|
||
这值得深入探讨，因为它是循环中最常见的摩擦来源。
|
||
|
||
阶段太大会变成一个独立的研究项目。规划器难以将其分解为独立计划。后续波次的执行器被阻塞，等待前面的波次。验证变成全面审计而非有针对性的审查。反馈周期从数小时延伸到数天，而在大量代码编写后期才发现根本性设计错误的风险急剧上升。
|
||
|
||
阶段太小则会将本属于一体的工作碎片化。你最终会得到只有几行的计划文件、在几分钟内完成的阶段，以及规划开销远超执行成本的局面。循环感觉像官僚主义而非帮助。
|
||
|
||
好的阶段范围具备以下特征：
|
||
|
||
- 目标可以用一句话表述，既不显然琐碎，也不可疑宽泛。
|
||
- 规划所需的研究是有边界的——生态系统问题有答案，且不依赖于其他阶段的先行完成。
|
||
- 执行可以并行化为少数几个不重叠的计划，而不是几十个。
|
||
- 有清晰的、可测试的完成定义，验证器无需阅读整个代码库即可检查。
|
||
|
||
具体来说："添加 HMAC-SHA256 签名验证中间件"是一个好的阶段范围。"构建认证系统"通常不是——它几乎总是包含多个独立关注点，作为单独阶段会更好。"修复 README 中的拼写错误"低于循环能增添价值的门槛；请使用 `/msd-quick` 代替。
|
||
|
||
有疑问时，拆分。更小的阶段完成得更快，验证更有把握，当设计决策被证明有误时也更容易纠偏。
|
||
|
||
---
|
||
|
||
## `.planning/` 如何在循环中保持状态
|
||
|
||
循环不是单次会话。研究、规划和执行可能跨越多个会话，中间有上下文重置。`.planning/` 目录使这成为可能。
|
||
|
||
循环的每个步骤都读取早期步骤产生的产出物，并为后续步骤写入产出物。Discuss 步骤生成的 CONTEXT.md 在规划器运行时仍然可用——即使那是数小时后的不同会话。规划器生成的 PLAN.md 文件在执行器运行时仍然可用——即使跨越重启。验证器写入的 VERIFICATION.md 在你审查阶段时仍然可用。
|
||
|
||
`STATE.md` 是凌驾于这一切之上的导航层。它精确记录项目当前在循环中所处的位置：哪个里程碑处于活动状态，哪个阶段正在进行，哪些计划已完成，哪些待处理。任何需要定向的代理或工作流都首先读取 `STATE.md`。
|
||
|
||
有关这些文件的精确结构，请参见[规划产出物](../reference/planning-artifacts.md)和 [STATE.md 架构](../reference/state-md.md)。
|
||
|
||
---
|
||
|
||
## 循环是一种节奏，而非约束
|
||
|
||
很容易将循环视为官僚主义——一组你在被允许编写代码之前必须执行的步骤。这种框架是错误的。
|
||
|
||
循环之所以存在，是因为每个步骤都能防范在事后修复真正代价高昂的失败。Discuss 防止在错误假设上规划。Plan 防止执行从根本上存在缺陷的设计。Verify 防止发布偏离了需求的工作。这些不是人为制造的问题。它们是真实功能规模的 AI 辅助开发的实际失败模式。
|
||
|
||
循环运行良好时，感觉像是一种节奏：有节奏的专注、有边界的工作，每个步骤都清晰，因为上一步骤做好了它的工作。开销是真实的，但它是前置支付的——用几分钟规划换取而不是数小时返工。
|
||
|
||
对于低于循环门槛的工作，MSD Core 提供更轻量的原语。阶段循环是一种工具，而非唯一工具。
|
||
|
||
---
|
||
|
||
## 相关内容
|
||
|
||
- [上下文工程](context-engineering.md) — 为什么全新上下文子代理能防止使循环成为必要的质量退化
|
||
- [讨论一个阶段](../how-to/discuss-a-phase.md)
|
||
- [规划一个阶段](../how-to/plan-a-phase.md)
|
||
- [执行一个阶段](../how-to/execute-a-phase.md)
|
||
- [验证与发布](../how-to/verify-and-ship.md)
|
||
- [规划产出物](../reference/planning-artifacts.md)
|
||
- [STATE.md 架构](../reference/state-md.md)
|
||
- [文档索引](../README.md)
|