msd-core/docs/zh-CN/reference/plan-md.md

PLAN.md 模式参考

每个计划的 PLAN.md 是 GSD Core 的可执行工作单元——一份结构化文档，精确告知执行器代理需要构建什么以及如何验证构建是否正确完成。本页记录其结构。参见文档索引。

---

概述

计划存放在以下位置的阶段目录中：

.planning/phases/<NN>-<slug>/<NN>-<PP>-PLAN.md

例如：.planning/phases/03-post-feed/03-02-PLAN.md（第 3 阶段，第 2 计划）。

计划由 gsd-planner 代理生成（由 /gsd-plan-phase 触发），并由 execute-phase 消费。一个阶段通常包含一到四个计划；同一阶段内的计划被分配到执行波次，以便独立工作并行运行。

---

YAML 前置元数据

每个 PLAN.md 以位于 --- 分隔符之间的 YAML 前置元数据块开头。

注释示例

---
phase: 03-post-feed
plan: 02
type: execute
wave: 2
depends_on: ["03-01"]
files_modified:
  - src/components/PostFeed.tsx
  - src/components/PostCard.tsx
  - src/app/feed/page.tsx
autonomous: true
requirements: ["FEED-01", "FEED-03"]
user_setup: []

must_haves:
  truths:
    - "User can scroll through posts from followed accounts"
    - "Each post shows author avatar, name, timestamp, and content"
    - "Empty state appears when no posts exist"
  artifacts:
    - path: "src/components/PostFeed.tsx"
      provides: "Scrollable post list"
      min_lines: 40
    - path: "src/components/PostCard.tsx"
      provides: "Individual post card"
      exports: ["PostCard"]
  key_links:
    - from: "src/components/PostFeed.tsx"
      to: "/api/feed"
      via: "fetch in useEffect"
      pattern: "fetch.*api/feed"
---

前置元数据字段参考

字段	是否必填	类型	用途
phase	是	string	阶段标识符，例如 03-post-feed。
plan	是	string	阶段内的计划编号，例如 02。
type	是	execute 或 tdd	标准计划使用 execute；测试驱动计划使用 tdd，测试在实现之前编写。
wave	是	integer	执行波次。波次 1 中的计划并行运行（无依赖关系）。波次 2 及以上的计划等待上一波次的所有计划完成后才开始。由 gsd-planner 在规划时预先计算。
depends_on	是	array of plan IDs	该计划必须等待的前置计划。空数组表示波次 1。示例：["03-01"] 表示该计划在第 3 阶段计划 01 完成后运行。
files_modified	是	array of paths	该计划创建或修改的所有文件。被计划检查器用于检测同波次文件冲突，也被 execute-phase 用于合并跟踪。
autonomous	是	boolean	当所有任务类型均为 auto 时为 true。当计划包含任何需要人工交互的 checkpoint:* 任务时为 false。
requirements	是	array of IDs	该计划所对应的 ROADMAP.md 中的需求 ID。每个阶段需求 ID 必须出现在至少一个计划的 requirements 字段中。空数组是阻断项（BLOCKER）。
user_setup	否	array of objects	Claude 无法自动化的外部服务设置步骤（账户创建、密钥获取、控制台配置）。存在时，execute-phase 会为开发者生成 USER-SETUP.md 检查清单。
must_haves	是	object	以目标为导向的验证标准。详见下文。

---

must_haves 字段

must_haves 描述了阶段目标达成后必须可观测到的真实状态。该字段在规划阶段派生，并在执行后由 gsd-verifier 代理验证。

子字段

子字段	类型	用途
truths	array of strings	从用户视角可观测到的行为。每项必须可验证。示例："User can send a message"，而非 "WebSocket library installed"。
artifacts	array of objects	必须存在且具有实质性实现（非桩代码）的文件。
artifacts[].path	string	相对于项目根目录的文件路径。
artifacts[].provides	string	该文件所提供的能力。
artifacts[].min_lines	integer（可选）	被视为非桩代码的最小行数。
artifacts[].exports	array of strings（可选）	需要验证的预期命名导出项。
artifacts[].contains	string（可选）	必须出现在文件中的正则表达式或字面量模式。
key_links	array of objects	制品之间的关键连接——使系统端到端运行的接线。
key_links[].from	string	源文件或组件。
key_links[].to	string	目标文件、端点或模块。
key_links[].via	string	连接方式描述（例如 fetch in useEffect、Prisma query、import）。
key_links[].pattern	string（可选）	用于验证源代码中连接是否存在的正则表达式。

---

正文结构

前置元数据之后，计划正文使用执行器代理读取的具名 XML 风格块。

<objective>

说明计划所交付的内容及其对项目的重要性：

<objective>
Implement the post feed as a scrollable card list.

Purpose: Core display feature for the social feed phase.
Output: PostFeed and PostCard components wired to /api/feed.
</objective>

<execution_context>

列出执行器在开始前读取的工作流文件。始终包含 execute-plan 工作流；当计划包含检查点任务时，额外添加检查点参考：

<execution_context>
@~/.claude/gsd-core/workflows/execute-plan.md
@~/.claude/gsd-core/templates/summary.md
</execution_context>

<context>

引用执行器需要读取的源文件。包括项目级规划文档以及计划必须复用其模式或类型的源文件。仅当后续计划对其类型或决策存在真实依赖时，才引用前序计划的 SUMMARY.md 文件——而非无条件引用：

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@src/components/UserCard.tsx
</context>

<tasks>

包含一个或多个 <task> 元素。对于 type="auto" 的任务，每个任务元素必须包含 <name>、<files>、<read_first>、<action>、<verify>、<acceptance_criteria> 和 <done>。

---

任务类型

类型	使用场景	自主程度
auto	执行器可独立完成的所有内容。	完全自主。
checkpoint:human-verify	需要人工查看运行中的界面或服务进行视觉或功能验证。	暂停执行；呈现给开发者；批准后恢复。
checkpoint:decision	执行过程中出现的需要开发者输入的实现选择。	暂停执行；呈现选项；选择后恢复。
checkpoint:human-action	真正不可避免的手动步骤（账户创建、硬件交互）。谨慎使用。	暂停执行；确认后恢复。

包含任何检查点任务的计划必须在前置元数据中设置 autonomous: false。

---

auto 任务结构

<task type="auto">
  <name>Task 1: Create PostCard component</name>
  <files>src/components/PostCard.tsx</files>
  <read_first>src/components/UserCard.tsx, src/types/post.ts</read_first>
  <action>Create PostCard component accepting a Post prop (id, authorId, content, createdAt,
    reactionCount). Render author avatar using UserAvatar from UserCard pattern. Show timestamp
    using date-fns formatDistanceToNow. Export as named export PostCard.</action>
  <verify>npx tsc --noEmit</verify>
  <acceptance_criteria>
    - src/components/PostCard.tsx exports named export PostCard
    - PostCard.tsx contains "reactionCount" prop usage
    - npx tsc --noEmit exits 0
  </acceptance_criteria>
  <done>PostCard renders post content with author and timestamp</done>
</task>

auto 任务必填字段

字段	规则
<files>	任务创建或修改的所有文件。执行器只写入这些文件。
<read_first>	执行器在修改任何内容之前必须读取的文件——包括待修改文件、任何真实来源的模式文件以及必须复用其类型或约定的文件。
<action>	包含精确标识符、文件路径、函数签名和预期值的具体指令。不能在未指定目标状态的情况下说"将 X 与 Y 对齐"。不包含代码围栏块或完整实现。
<verify>	可运行的命令或检查，用于证明任务已成功完成。必须能区分通过与失败——echo "done" 无效。
<acceptance_criteria>	可验证的条件：可通过 grep 验证的字符串、命令退出码、可观测行为。不含主观性语言（"看起来正确"、"配置正确"）。
<done>	已完成结果的简短可量化陈述。

---

计划质量维度

gsd-plan-checker 代理在执行开始前对每个 PLAN.md 进行 12 个维度的审查。任何未通过 BLOCKER 级别检查的计划将被退回给 gsd-planner 修订（最多 3 次迭代）：

维度	检查内容
1 — 需求覆盖率	ROADMAP.md 中每个阶段需求 ID 出现在至少一个计划的 requirements 前置元数据字段中，并有相应的覆盖任务。
2 — 任务完整性	每个 auto 任务携带所有必填字段（<files>、<action>、<verify>、<acceptance_criteria>、<done>）。无模糊或空字段。
3 — 依赖正确性	depends_on 引用有效、无循环，并与波次编号一致。第 N 波次计划仅依赖波次 < N 的计划。
4 — 关键链接规划	must_haves.key_links 中的制品有对应的实现接线任务——而非仅创建制品。
5 — 范围合理性	计划保持在上下文预算内：每个计划 2–3 个任务（4 个 = 警告，5 个及以上 = BLOCKER），每个计划 ≤ 8–10 个文件（15 个及以上 = BLOCKER）。
6 — 验证推导	must_haves.truths 是用户可观测行为，而非实现细节。制品映射到真实状态。关键链接覆盖关键接线。
7 — 上下文合规性	CONTEXT.md 中每个 D-NN 决策至少由一个任务处理。没有任务实现 <deferred> 中的内容。
7b — 范围缩减检测	任务操作不会在未交付完整决策范围的情况下，悄悄将已锁定决策降级为"v1"、"桩代码"或"未来增强"。发现时始终为 BLOCKER。
7c — 架构层级合规性	任务按照 RESEARCH.md 架构责任映射（如存在）将能力分配到正确层级。安全敏感能力分配到错误层级时为 BLOCKER。
8 — 奈奎斯特合规性	当 workflow.nyquist_validation 已启用且 RESEARCH.md 存在时，每个任务有 <automated> 验证命令，连续 3 个任务的窗口内不缺少覆盖，且 VALIDATION.md 存在。
9 — 跨计划数据契约	当计划共享数据管道时，其转换相互兼容——没有计划删除另一个计划需要原始形式的数据。
10 — CLAUDE.md 合规性	计划遵守 ./CLAUDE.md 中的项目特定约定、禁止模式、必需工具和安全要求。
11 — 研究解决	当 RESEARCH.md 存在时，其 ## Open Questions 部分在规划继续之前标记为 (RESOLVED)。
12 — 模式合规性	当 PATTERNS.md 存在时，任务为每个新建或修改的文件引用正确的类比模式。

---

波次执行模型

波次编号在规划阶段预先计算。Execute-phase 按波次编号对计划进行分组，并行运行每个波次的计划：

Wave 1: Plan 01, Plan 02, Plan 03  (all run simultaneously — no dependencies)
Wave 2: Plan 04                    (waits for Wave 1 to complete)
Wave 3: Plan 05                    (waits for Wave 2 to complete)

同一波次中修改重叠文件的计划不得处于同一波次——计划检查器的维度 3 会将此标记为 BLOCKER。

---

计划输出

计划成功执行后，执行器在以下路径写入 SUMMARY.md：

.planning/phases/<NN>-<slug>/<NN>-<PP>-SUMMARY.md

SUMMARY.md 是所构建内容的权威记录。同一阶段内的后续计划，仅当对其类型或决策存在真实依赖时，才可引用该文件。

---

相关内容

• CONTEXT.md 模式
• 规划制品
• 功能特性
• 文档索引