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.
207 lines
6.2 KiB
Markdown
207 lines
6.2 KiB
Markdown
# 如何规划阶段
|
||
|
||
**目标：** 将阶段决策和研究成果转化为可原子化执行、可验证的任务计划。
|
||
|
||
**前提条件：** `.planning/ROADMAP.md` 已存在。强烈建议（但非必须）先通过 `/msd-discuss-phase` 生成 `{phase}-CONTEXT.md`。
|
||
|
||
---
|
||
|
||
## 运行标准规划流程
|
||
|
||
```bash
|
||
/msd-plan-phase 2
|
||
```
|
||
|
||
该命令按顺序执行三个阶段：
|
||
|
||
1. **研究** — `msd-phase-researcher` 子代理调查相关领域并写入 `{phase}-RESEARCH.md`。
|
||
2. **规划** — `msd-planner` 子代理读取上下文、研究成果和需求，然后写入一个或多个 `{phase}-{N}-PLAN.md` 文件。
|
||
3. **验证** — `msd-plan-checker` 子代理从八个维度验证计划质量，并触发修订循环（最多三次迭代），直至质量门控通过。
|
||
|
||
若未指定阶段编号，MSD Core 将自动定位 ROADMAP.md 中下一个未规划的阶段。
|
||
|
||
---
|
||
|
||
## 跳过或强制执行研究
|
||
|
||
**如果领域已熟悉且无需新的研究：**
|
||
|
||
```bash
|
||
/msd-plan-phase 3 --skip-research
|
||
```
|
||
|
||
**如果 RESEARCH.md 已存在但需要强制刷新：**
|
||
|
||
```bash
|
||
/msd-plan-phase 3 --research
|
||
```
|
||
|
||
**如果只想运行研究** — 写入 RESEARCH.md 后在规划前退出：
|
||
|
||
```bash
|
||
/msd-plan-phase --research-phase 4
|
||
```
|
||
|
||
若 RESEARCH.md 已存在，系统会提示选择更新、查看或跳过。如需强制刷新而不显示提示：
|
||
|
||
```bash
|
||
/msd-plan-phase --research-phase 4 --research
|
||
```
|
||
|
||
将现有 RESEARCH.md 打印到标准输出而不启动研究代理：
|
||
|
||
```bash
|
||
/msd-plan-phase --research-phase 4 --view
|
||
```
|
||
|
||
注意：`--research-phase <N>` 是 `/msd-plan-phase` 上的标志。不存在独立的研究阶段命令——原来的独立研究命令已被弃用，以此标志取而代之。
|
||
|
||
---
|
||
|
||
## 按垂直功能切片而非水平层次进行规划
|
||
|
||
**如果希望任务按端到端的薄切片组织**（每个功能从 UI → API → DB），而非按技术层次：
|
||
|
||
```bash
|
||
/msd-plan-phase 1 --mvp
|
||
```
|
||
|
||
在新项目的第一阶段且无先前阶段摘要的情况下，`--mvp` 还会生成 `SKELETON.md`——一份 Walking Skeleton，涵盖项目脚手架、路由、一次真实的数据库读写、一次真实的 UI 交互以及开发部署。
|
||
|
||
也可在 ROADMAP.md 中该阶段的条目里添加 `**Mode:** mvp`，无需每次使用标志即可持久启用 MVP 模式。
|
||
|
||
---
|
||
|
||
## 要求每个新增行为任务包含一个失败测试
|
||
|
||
**如果需要强制 TDD** — 每个新增行为的任务在实现前先编写一个失败测试：
|
||
|
||
```bash
|
||
/msd-plan-phase 1 --tdd
|
||
```
|
||
|
||
可与 `--mvp` 组合使用：
|
||
|
||
```bash
|
||
/msd-plan-phase 1 --mvp --tdd
|
||
```
|
||
|
||
这将生成垂直切片，其中每个新增行为的任务均遵循 RED → GREEN → REFACTOR 流程。规划器会对符合条件的任务（业务逻辑、API 端点、数据转换）应用 `type: tdd`，并对 UI、配置和胶水代码使用标准的 `type: execute`。
|
||
|
||
TDD 模式也可在配置中持久化：
|
||
|
||
```bash
|
||
node msd-tools.cjs config-set workflow.tdd_mode true
|
||
```
|
||
|
||
---
|
||
|
||
## 基于跨 AI 评审反馈重新规划
|
||
|
||
**如果已运行 `/msd-review --phase N` 且存在 `REVIEWS.md`：**
|
||
|
||
```bash
|
||
/msd-plan-phase 3 --reviews
|
||
```
|
||
|
||
规划器会读取 `REVIEWS.md` 并修订计划以解决反馈问题。不可与 `--gaps` 组合使用。
|
||
|
||
**如果需要自动化循环** — 持续重新规划和重新评审，直至不再存在 HIGH 级别关注点：
|
||
|
||
```bash
|
||
/msd-plan-review-convergence 3
|
||
```
|
||
|
||
收敛循环执行规划 → 评审 → 重新规划 → 再评审的周期（默认最多三次）。使用 `--max-cycles N` 可覆盖上限。
|
||
|
||
---
|
||
|
||
## 在验证失败后弥补差距
|
||
|
||
**如果 `VERIFICATION.md` 存在未解决的差距，且只想针对这些差距重新规划：**
|
||
|
||
```bash
|
||
/msd-plan-phase 3 --gaps
|
||
```
|
||
|
||
研究阶段将被跳过；规划器直接读取验证中的差距信息。
|
||
|
||
---
|
||
|
||
## 规划完成后运行外部弹跳验证
|
||
|
||
**如果已配置 `workflow.plan_bounce_script` 且需要对完成的计划进行外部验证：**
|
||
|
||
```bash
|
||
/msd-plan-phase 1 --bounce
|
||
```
|
||
|
||
即使在配置中已启用弹跳，也可跳过：
|
||
|
||
```bash
|
||
/msd-plan-phase 1 --skip-bounce
|
||
```
|
||
|
||
---
|
||
|
||
## 禁止交互式确认
|
||
|
||
```bash
|
||
/msd-plan-phase --auto
|
||
```
|
||
|
||
跳过所有提示。适用于自动化流水线。若配置中 `research_enabled` 为 false，则跳过研究阶段。
|
||
|
||
---
|
||
|
||
## 计划输出内容
|
||
|
||
成功运行后会写入以下文件：
|
||
|
||
| 文件 | 用途 |
|
||
|---|---|
|
||
| `{phase}-RESEARCH.md` | 领域研究、软件包合法性审计、验证架构 |
|
||
| `{phase}-VALIDATION.md` | 奈奎斯特测试映射——计划必须满足的测试用例（第 8 维度） |
|
||
| `{phase}-{N}-PLAN.md` | 包含前置信息、波次分配和验收标准的可执行任务计划 |
|
||
| `{phase}/SKELETON.md` | Walking Skeleton（MVP 模式，仅限新项目的第一阶段） |
|
||
|
||
每个 PLAN.md 包含带有强制 `<read_first>` 和 `<acceptance_criteria>` 字段的任务。每个 `<acceptance_criteria>` 条目均可作为源断言、行为断言、测试命令或 CLI 输出进行验证——绝不使用主观性语言。
|
||
|
||
完整的字段参考请参阅 [PLAN.md 模式](../reference/plan-md.md)。
|
||
|
||
### 计划质量维度
|
||
|
||
`msd-plan-checker` 在允许执行前从八个维度验证计划：
|
||
|
||
1. 任务原子性——每个任务只关注单一问题
|
||
2. 依赖正确性——波次顺序一致
|
||
3. 验收标准可验证性——无主观标准
|
||
4. `<read_first>` 完整性——被修改的文件始终列入其中
|
||
5. 具体的 `<action>` 值——无模糊的"对齐"类指令
|
||
6. `must_haves` 源自阶段目标
|
||
7. 需求 ID 覆盖率——每个阶段需求 ID 至少出现在一个计划中
|
||
8. 奈奎斯特测试映射——计划涵盖 VALIDATION.md 中的验证策略
|
||
|
||
修订循环最多运行三次。若三次迭代后质量门控仍未通过，检查器将显示剩余问题供人工审查。
|
||
|
||
---
|
||
|
||
## 重新规划已关闭的阶段
|
||
|
||
如果某阶段的 `VERIFICATION.md` 中 `status: passed`，则该阶段被视为已关闭。尝试重新规划会以错误终止。如果关闭操作有误，可使用 `--force` 覆盖：
|
||
|
||
```bash
|
||
/msd-plan-phase 2 --force
|
||
```
|
||
|
||
警告信息将写入转录记录和所有已提交的计划文档中。
|
||
|
||
---
|
||
|
||
## 相关内容
|
||
|
||
- [讨论阶段](discuss-a-phase.md)
|
||
- [执行阶段](execute-a-phase.md)
|
||
- [PLAN.md 模式](../reference/plan-md.md)
|
||
- [命令](../COMMANDS.md)
|