# Build Workflow Plan

> 把 spec 拆成可执行的任务。当 spec 已批准需要拆分任务，或提到"计划""任务拆分""排期"

- Skill: `zeroz-lab/build-workflow-plan` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add zeroz-lab/build-workflow-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zeroz-lab/build-workflow-plan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: zeroz-lab (https://skillmd.com/u/zeroz-lab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zeroz-lab/build-workflow-plan

---


# Plan — 任务分解


## 入口/出口
- **入口**: 已批准 spec（`docs/features/YYYYMMDD-<name>/01-spec.md`）+ 已批准 design（如 required）
- **出口**: `docs/features/<name>/03-plan.md`；大型/并行任务额外产出 `docs/features/<name>/plans/*.md` + 用户批准
- **指向**: 用户批准 plan 后必须调用 `build-workflow-execute`
- **输出路径**: → build-workflow-execute
- **前置加载**: CANON.md
- **辅助参考**: `task-templates.md`（任务模板、Subplan Contract、Parallel Safety 判定、代码示例规则）、`plan-review.md`（Plan Review Army 详细规则）

## 何时不使用
- 变更只涉及 1-2 个文件且 scope 明显
- spec 已经包含明确定义的任务（此时直接进入 build）

## Agent Dispatch Contract

`/plan` 主执行 persona 是 `agents/task-planner.md`。

- Plan Review Army 在 Step 7.5 按 `plan-review.md` 最少触发条件选择 `agents/plan-ceo-reviewer.md`、`agents/plan-eng-reviewer.md`、`agents/plan-design-reviewer.md`、`agents/plan-security-reviewer.md`
- 标准变更至少 CEO + Eng；大型、安全、合规或 `--full` 才全开
- 未被选中的 reviewer 不产出占位反馈；所有已选 reviewer 反馈在 plan 批准前分级处理

## 核心锚点

### Vertical Slicing

每个任务交付一个完整、可独立验证的功能路径。不按技术层水平切片。

**执行规则：**
- Software：一个任务 = 一个用户路径（schema + API + UI），不拆成"建所有 DB → 建所有 API → 建所有 UI"
- Content（document/article）：一个章节 = 一个任务（目标 + 草稿 + 事实核查 + 编辑验证）
- Deck：一组连续页面 = 一个任务（标题 + 内容 + 视觉 + speaker notes）
- 任务标题出现 "and" = 拆分信号

### Plan Topology

按依赖关系和并行需求选择拓扑。

**执行规则：**
- `serial`：有序依赖、共享文件、小任务 → 只写 `03-plan.md`
- `parallel`：无共享文件、无顺序依赖，且共享契约已冻结 → `03-plan.md` + 多个 `plans/*.md`，标记 `parallel_safe`
- `gated-parallel`：共享契约先定，后续可并行 → `03-plan.md` + `plans/01-contracts.md` + 后续子计划
- 实现顺序按依赖图自底向上；只有 `Parallel Execution Matrix` 标记 `parallel_safe: yes` 的子计划才能并行

### Bite-sized Tasks

每个任务 3-7 步、≤5 文件、2-5 分钟可执行操作。

**执行规则：**
- Software 任务用 RED → GREEN → REFACTOR 结构；非 software 用产物切片 + 验证证据结构
- 禁止占位符：TBD/TODO/"implement later"/"添加适当的错误处理"（无具体代码）= plan 失败
- 给执行 agent 提供方向和约束，不提供完整实现（复杂算法/安全逻辑/精确产物除外）

## 核心流程

### Step 1：进入只读模式

不写代码。读取 spec、design 和相关代码库，识别模式和依赖。

**单计划 vs 多计划决策门：**
- XS/S 任务：只写 `03-plan.md`
- M/L 或跨子系统：`03-plan.md` 总控 + `plans/*.md` 子计划
- 有共享契约但可拆分：先写 `plans/01-contracts.md`，后续子计划基于契约并行

### Step 2：识别依赖图和 Plan Topology（锚点执行）

先读取 `artifact_type` 选择依赖图模型（software/content/deck/visual），再按 Plan Topology 锚点选择拓扑。

### Step 3：确定文件结构

映射出哪些文件会被创建或修改。每个文件一个明确职责；一起变化的放一起；遵循现有模式。

如果 `01-spec.md` 的 `Documentation Impact` 不是 `feature_only`，这里还必须映射 project doc 写入面：哪些是 `root docs`，哪些是 `project docs`，哪些继续留在 `feature docs`。

### Step 4：垂直切片（锚点执行）

### Step 5：写 bite-sized 任务（锚点执行）

任务模板见 `task-templates.md`。

### Step 6：排序、Topology 和检查点

排列任务使依赖满足、系统保持可工作、高风险任务放前面、每 2-3 个任务设验证检查点。

多计划模式下 `03-plan.md` 必须包含：Subplans + Parallel Execution Matrix + Integration Order + Shared Contracts。任何子计划没有 `Write Scope` / `Shared Contracts` / `Global Invariants` / `Cross-check Command` / `Semantic Independence Reason` 不能分派；两个 `parallel_safe` 子计划 Write Scope 不能重叠，且共享契约必须已冻结。

### Step 6.5：写 `Project Doc Sync Plan`

如果 spec 声明 `project_truth_changed: yes` 或 `doc_intent != feature_only`，`03-plan.md` 必须额外写：

- `Must update`：本次必须同步的项目级文档路径
- `Optional update`：可选同步，但不是发布门
- `Stage owner`：由 `/build`、`/review` 或 `/ship` 哪个阶段收口
- `Verification method`：如何判断这些文档已兑现
- `Deferred docs with reason`：明确延后项和原因

即使 `doc_intent: feature_only`，也要显式写 `Project Doc Sync Plan`，并说明 `not-needed`。

### Step 7：自审

写完 plan 后对照以下 10 项检查：

- [ ] Spec 覆盖：每条 spec 要求能找到对应任务
- [ ] 占位符扫描：无 TBD/TODO/"implement later"/"添加适当的错误处理"
- [ ] 类型一致性：后续任务的函数签名匹配前面定义的
- [ ] Subplans 完整：每个 `plans/*.md` 存在且有 Subplan Contract
- [ ] 并行安全：`parallel_safe` 子计划无重叠写入，且语义独立性已说明
- [ ] 收口顺序：release/ship 类子计划默认串行
- [ ] 任务独立性：每个任务有验收标准、独立验证步骤、依赖已标注
- [ ] 验证完整性：每个验证步骤有具体命令 + 预期输出 + 失败诊断
- [ ] 代码示例风格：最小示例 + 意图注释，无完整实现逻辑
- [ ] 任务粒度：≤5 文件、3-7 步、标题无 "and"
- [ ] 文档同步：如果 spec 要求同步 project docs，plan 已写 `Project Doc Sync Plan`

### Step 7.5：Plan Review Army

自审通过后按风险升级执行 Review Army。详见 `plan-review.md`。

### Step 8：用户批准

## 验证失败处理

| 失败场景 | 处理方式 |
|---------|---------|
| 用户拒绝 plan | 问清原因，修改 plan，重新提交 |
| plan 遗漏 spec 需求 | 补充任务；每条 spec 需求必须能找到对应任务 |
| 依赖关系不正确 | 重做依赖图验证 |
| 任务过大 | 分解到 ≤5 文件；标题出现 "and" = 拆分 |
| 验收条件缺失 | 强制补充；无验收条件的任务不能进入 build |
| parallel_safe 写入重叠 | 标记为串行，调整 Integration Order |
| shared contract / global invariant 未冻结 | 改为 `gated-parallel` 或串行 |
| spec 要求同步 project docs 但 plan 未写 owner / verification | 阻塞。补 `Project Doc Sync Plan` 后再进入 build |

## 常见说辞

| 说辞 | 现实 | 后果 |
|------|------|------|
| "边做边想" | 10 分钟计划节省数小时。 | 无计划遗漏 2-3 个依赖，每个导致 2-4 小时返工 |
| "任务很明显不需要写下来" | 写下来暴露隐藏依赖和边界情况。 | 未记录的"明显"任务隐藏 1-2 个边界，上线后 bug |
| "计划就是开销" | 计划就是任务。没计划的实现只是在打字。 | 无计划 → 依赖混乱 → 集成阶段 >50% 代码需重排 |
| "之后补验收条件" | 没有验收条件就无法判断"做完"。 | 后补验收条件倾向顺应已实现行为，遗漏被永久锁定 |

## 红旗

- 没有书面任务清单就开始实现
- 任务说"实现功能"但没有验收条件
- plan 中没有验证步骤
- spec 里说要同步 project docs，但 plan 没写 `Project Doc Sync Plan`
- 所有任务都是 L 或 XL 大小
- 阶段之间没有检查点
- 依赖顺序没有执行
- plan 中任务标题出现 "and"（= 两个任务）

## 验证清单

- [ ] 每个任务有验收条件和验证步骤
- [ ] 任务依赖已识别并正确排序
- [ ] 没有任务超过 ~5 个文件
- [ ] 主要阶段间设了检查点
- [ ] plan 没有占位符
- [ ] spec 每个需求在 plan 中都有对应任务
- [ ] `Project Doc Sync Plan` 已存在；需要同步时包含 owner / verification / deferred reason
- [ ] 多计划任务有 Subplans、Parallel Execution Matrix、Integration Order
- [ ] `parallel_safe` 子计划之间没有重叠写入
- [ ] 用户已审查并批准 plan

## 好坏示例

### Good — 垂直切片 + 验收条件

```
Task 1: 用户注册 — Files: User.ts, register.ts, RegisterForm.tsx
  Step 1: 定义 schema → 验证: prisma validate
  Step 2: 实现 API → 验证: curl POST /api/register → 201
  Step 3: 实现 UI → 验证: 浏览器提交表单 → 成功提示
  Verification: npm test --coverage --grep register > 80%
```

### Bad — 水平切片 + 无验收

```
Task 1: 建数据库（整个 schema）
Task 2: 建所有 API
Task 3: 建所有 UI
→ 水平切片: Task 3 完成前无法验证任何用户路径
→ 无验收条件: "建完"无法判定
→ 依赖链过长: 任何前置阻塞后续全部
```

## 输出模板

```markdown
### Plan — <feature-name>

Plan Topology: [serial / parallel / gated-parallel] | artifact_type: [software/...]

Project Doc Sync Plan:
- Must update: [paths or none]
- Optional update: [paths or none]
- Stage owner: [phase / task]
- Verification method: [review / validate / manual]
- Deferred docs with reason: [items or none]

Task 清单:
| Task N | 标题 | 文件数 | 验收条件 | 验证命令 | 依赖 |
|--------|------|-------|---------|---------|------|
| 1 | [标题] | [N] | [条件] | [命令] | [无/Task N] |

子计划索引（如适用）:
| 子计划 | Write Scope | Shared Contracts | Cross-check Command | parallel_safe | 依赖 | 验证 |
|--------|------------|------------------|---------------------|--------------|------|------|
| plans/01-*.md | [范围] | [契约] | [命令] | [yes/no] | [依赖] | [命令] |

Parallel Execution Matrix（如适用）:
| A | B | safe | 无重叠 |
|---|---|------|--------|
| [1] | [2] | [yes/no] | [✓/✗] |

用户批准: [已批准 / 待批准]
```