Roadmap: <epic name>

Status legend: planned · in-progress · done

ID	Sub-feature	Intent	Scope boundary	Depends on	Status	Sub-spec
R1			<in / deferred>	—	planned	—
R2			<in / deferred>	R1	planned	—
R3			<in / deferred>	R1	planned	—

维护上的两条纪律（[原文档](https://gitcode.com/GitHub_Trending/sp/spec-kit/blob/9f19be9cad6e83d8b293041d8dbb1b7787c3ed54/docs/concepts/spec-of-specs.md?utm_source=gitcode_repo_files#L71-L73)）：

- **`ID` 列一旦被子规格引用就不可变**——它是可追溯性的锚点；
- 创建子特性目录后，把 `Sub-spec` 列回填为该子特性的 spec 目录路径，并随工作推进更新 `Status`。

### Roadmap 与 Spec Kit 既有状态机制的关系

从仓库机制看，roadmap 补充的是 Spec Kit 原生状态机“之上”的一层人类可读视图。Spec Kit 追踪当前活动特性靠的是 `.specify/feature.json` 中记录的 feature 目录（可用环境变量 `SPECIFY_FEATURE_DIRECTORY` 覆盖），命令从该状态而非 Git 分支解析特性——这一点在 [quickstart 文档](https://gitcode.com/GitHub_Trending/sp/spec-kit/blob/9f19be9cad6e83d8b293041d8dbb1b7787c3ed54/docs/quickstart.md?utm_source=gitcode_repo_files#L13) 中有明确说明。而每次 `/speckit.specify` 调用会创建一个特性目录并持久化状态：按 [specify 命令模板](https://gitcode.com/GitHub_Trending/sp/spec-kit/blob/9f19be9cad6e83d8b293041d8dbb1b7787c3ed54/templates/commands/specify.md?utm_source=gitcode_repo_files#L81-L106)，目录默认在 `specs/` 下自动生成（目录名形如 `003-user-auth` 或时间戳 `20260319-143022-user-auth`，编号风格由 `.specify/init-options.json` 的 `feature_numbering` 决定），解析出的路径写入 `.specify/feature.json` 的 `feature_directory` 字段，供 plan/tasks/implement 等下游命令定位。

也就是说：**每个切片都是一个完整的、独立的 Spec Kit 特性**，拥有自己的 `spec.md`/`plan.md`/`tasks.md` 和目录编号；roadmap 本身不进入这套状态机，它只是把这些并列的特性目录“串”成一个 epic 的骨架。

## 四、逐个规格化子特性：没有新东西要学

有了 roadmap，按条目逐个推进即可，用的就是普通 Spec Kit 流程（[原文档](https://gitcode.com/GitHub_Trending/sp/spec-kit/blob/9f19be9cad6e83d8b293041d8dbb1b7787c3ed54/docs/concepts/spec-of-specs.md?utm_source=gitcode_repo_files#L77-L89)）：

1. 挑下一条**依赖已 `done`（或无依赖）**的 roadmap 条目；
2. 只为这一个切片跑 `/speckit.specify`，描述只取自 roadmap 条目的意图与范围。因为切片有界，其 spec、plan、tasks 都能稳稳落在上下文窗口内；
3. 照常为该切片跑 `/speckit.plan`、`/speckit.tasks`、`/speckit.implement`；
4. 把该 roadmap 条目标记 `done`，进入下一条。

这里有一个值得注意的实践细节：`/speckit.specify` 产出的 `spec.md` 顶部天然带有 `**Input**` 行——[spec 模板](https://gitcode.com/GitHub_Trending/sp/spec-kit/blob/9f19be9cad6e83d8b293041d8dbb1b7787c3ed54/templates/spec-template.md?utm_source=gitcode_repo_files#L9) 的默认值是 `**Input**: User description: "$ARGUMENTS"`。spec of specs 约定的正是**把 roadmap 回溯引用写进这一行**（见下节），这与模板结构无缝契合，不需要改动任何模板文件。

## 五、子规格与 Roadmap 的双向链接

为了防止范围与意图在多次独立运行间漂移，每个子规格都引用其 roadmap 条目，roadmap 再链接回去——原文档称之为“一个简单的、可 grep 的、双向的约定”（[原文档](https://gitcode.com/GitHub_Trending/sp/spec-kit/blob/9f19be9cad6e83d8b293041d8dbb1b7787c3ed54/docs/concepts/spec-of-specs.md?utm_source=gitcode_repo_files#L91-L109)）：

**子规格 → roadmap。** 在子特性的 `spec.md` 中，在 `Input` / 摘要行写明父 roadmap 和条目 ID，例如：

```markdown
**Input**: Parent roadmap: `specs/<epic>/roadmap.md` → entry **R3**. <feature description>

Roadmap → 子规格。 在 roadmap 表格中，把该条目的 Sub-spec 列设为子特性的目录，例如 specs/<epic>-part-3/。

由于两个方向都是纯文本，任何一份子规格都可以用一次搜索回溯到它在 epic 中的位置（并顺带找到它的兄弟切片）——不需要工具，也不需要元数据 schema。

六、保持 Roadmap 与子规格同步

roadmap 是一份活文档。随着对功能理解的加深，要让它和子规格保持对齐（原文档）：

• 先改 roadmap，再对齐子规格。 范围变化时，先更新 roadmap 条目，再更新受影响的子规格。roadmap 是“epic 如何被切分”的唯一事实来源。
• 尊重依赖与顺序。 若某切片依赖另一切片，先构建前置项，并让依赖方子规格交叉引用被依赖方，使关系在两侧都可见。
• 切片仍然太大时就递归。 如果某个子特性被发现大到无法在一个循环内规格化，就为它单独建一份 roadmap，再拆一层——同样的方法在下一层同样适用。但递归会增加开销，只下沉到上下文问题实际要求的深度。

并行化：worktree + 活动特性状态

对于互不依赖的切片，原文档建议用单独的 worktree 并行构建，“让每次运行都有隔离的 active-feature 状态”。从源码结构看，这正好落在 Spec Kit 的目录作用域设计上：项目由包含 .specify/ 的目录界定，活动特性由该目录下的 .specify/feature.json 指示。两个独立 worktree 各自拥有自己的 .specify/ 状态副本，因此两个切片可以各占一个 worktree 互不干扰地推进；此外 monorepo 指南 也说明 Spec Kit 项目本就是目录作用域的，每个项目目录拥有独立的 specs/ 与特性编号，这与“一个 epic、多个并列子特性目录”的布局天然一致。若不做并行，顺序推进时切换活动特性只需更新 .specify/feature.json 或设置 SPECIFY_FEATURE_DIRECTORY（core 参考 给出了这两轴模型：SPECIFY_INIT_DIR 选项目、SPECIFY_FEATURE_DIRECTORY/feature.json 选特性）。

七、完整示例：自助计费门户

以原文档的 worked example（原文档）完整走一遍：epic 是**“添加自助计费门户”**——大到无法单次循环完成，roadmap 路径把它拆成三个可独立规格化的切片。

specs/billing-portal/roadmap.md：

# Roadmap: Self-service billing portal

Let customers view invoices, manage payment methods, and change plans without
contacting support. Too large for one cycle, so it is split into independent slices.

**Status legend**: planned · in-progress · done

| ID | Sub-feature        | Intent                                   | Scope boundary                              | Depends on | Status  | Sub-spec |
|----|--------------------|------------------------------------------|---------------------------------------------|-----------|---------|----------|
| R1 | Invoice history    | Customers view and download past invoices | Read-only; no payment actions               | —         | done    | specs/billing-invoices/ |
| R2 | Payment methods    | Add, remove, and set a default card       | No plan changes; assumes invoices exist     | R1        | in-progress | specs/billing-payment-methods/ |
| R3 | Plan changes       | Upgrade/downgrade the subscription plan   | Uses R2's default payment method            | R1, R2    | planned | — |

每个切片随后独立规格化。例如 R2 的 spec.md 以回溯引用开头：

# Feature Specification: Billing — payment methods

**Input**: Parent roadmap: `specs/billing-portal/roadmap.md` → entry **R2**.
Let customers add, remove, and set a default payment method in the billing portal.