Backlog Feature 管理规范

本文档总结的是 jqkai-apis 在 planning/backlog 中形成的 backlog feature 管理方式。重点不在某个业务 feature，而在这套管理系统本身。

1. 核心原则

PRD.md 是 feature 唯一需求真源。
implementation-checklist.md 是验收面板，不是第二份 PRD，也不是开发任务拆解。
backlog 目录是状态化文档系统，不只是待办列表。
目录位置和文档顶部状态都表达信息，但二者不是同一个维度。
已实现但未回填文档的 feature，可以继续留在 active/，这是受控状态，不是异常。
补充议题优先写成 feature 内补充 PRD，而不是滥开新的 backlog 编号。

2. 目录结构

推荐结构如下：

planning/
  notes/
    roadmap.md
  backlog/
    README.md
    active/
      README.md
      feat-{seq}-{slug}/
        PRD.md
        implementation-checklist.md
        <topic>-PRD.md
        subtask-<topic>.md
    completed/
      feat-{seq}-{slug}/
        PRD.md
        implementation-checklist.md
        <topic>-PRD.md
        subtask-<topic>.md
      archive/
        README.md
        feat-{seq}-{slug}/
          PRD.md

2.1 各层职责

planning/notes/roadmap.md
- 记录工程主线、阶段性方向和高层判断
- 不替代 feature PRD
planning/backlog/README.md
- backlog 总索引
- 汇总 active、completed、archive
- 不是 feature 真源
planning/backlog/active/
- 当前仍处于管理周期内的 feature
- 允许混合存在 Proposed、Active、Implemented
planning/backlog/completed/
- 已正式收口并完成迁移的 feature
planning/backlog/completed/archive/
- 更早期、历史化的 completed backlog
- 用于进一步压缩现行 completed 视图，而不是所有 completed 的默认位置

2.2 目录契约

推荐固定以下路径契约：

planning/backlog/active/feat-{seq}-{slug}/PRD.md
planning/backlog/active/feat-{seq}-{slug}/implementation-checklist.md
planning/backlog/completed/feat-{seq}-{slug}/PRD.md
planning/backlog/completed/archive/feat-{seq}-{slug}/PRD.md

这个契约的价值是：

让人一眼知道 feature 真源在哪里
让 Agent 能稳定生成和查找文档
让目录迁移具有一致性

3. 单文件职责

3.1 `PRD.md`

PRD.md 是 feature 的唯一需求真源，负责回答：

为什么要做
解决什么问题
边界在哪里
什么算完成
当前处于什么阶段

建议固定包含：

状态区
Summary
背景
问题定义
目标
非目标
方案概览
验收标准
依赖与边界
验证方式

3.2 `implementation-checklist.md`

implementation-checklist.md 不是开发任务拆解，也不重新讲一遍需求。

它的职责是把 feature 的交付与验收面板化，记录：

该 feature 交付后应该能观察到什么
哪些接口、页面、文档、脚本、测试已经收口
哪些回归和验证仍未通过

正确写法：

勾选项写成“完成后应看到的结果”
与 PRD 一一对应
用于验收、回填、收口

错误写法：

把它写成开发子任务分解
把它写成第二份 PRD
把实施细节和需求边界混在一起

3.3 `<topic>-PRD.md`

这是补充 PRD，用于 feature 内的局部议题，例如：

rename 纠偏
某个补充子能力
某个方案被否决后的历史记录

使用规则：

不新开 backlog 编号
必须说明它和主 PRD.md 的关系
必须说明为什么作为补充 PRD，而不是单独新 feature
可标记为 Completed 或 Superseded

3.4 `subtask-<topic>.md`

这是 session handoff 或收尾任务文档。

它不是新的产品 PRD，适合承接：

下一轮会话要继续的收尾任务
某个 patch、迁移、实库校准
某个 narrow scope 的实施交接

建议内容：

当前基线
待处理范围
明确不做什么
验证建议

3.5 `README.md`

各级 README.md 只做三件事：

索引
摘要
口径同步

不做的事：

不承担需求真源
不替代 PRD
不承载大段实现细节

4. 命名规范

4.1 目录命名

feature 目录统一使用 feat-{seq}-{slug}
seq 建议连续递增
slug 应表达 feature 名称，而不是团队内部临时代号

示例：

feat-12-user-billing-reconciliation
feat-41-upstream-billing-tiered-routing

4.2 文件命名

主需求文件固定为 PRD.md
验收文件固定为 implementation-checklist.md
补充 PRD 固定为 <topic>-PRD.md
handoff 固定为 subtask-<topic>.md

这样做的好处是：

主文件位置稳定
辅助文件用途可读
后续检索和生成更可靠

4.3 文档顶部状态区

建议在 PRD.md 顶部固定保留：

状态
优先级
建议目录
当前阶段

这样做有两个作用：

即使目录没迁移，读者也能先看到当前真实状态
文档在被复制、单独打开或引用时仍能保留上下文

5. 状态契约

推荐固定使用以下状态枚举：

Proposed
Active
Implemented
Completed
Superseded

5.1 `Proposed`

表示：

PRD 和 checklist 已建立
方案和边界已经明确
尚未进入正式实现或主线修复

通常特征：

当前阶段常写为 PRD and checklist only
代码和文档真源还未进入收口

5.2 `Active`

表示：

feature 已进入推进、修复或集中收口窗口
需求与实际实现都可能继续变化

它强调的是“当前正在推进”，不要求已经完成代码落地。

5.3 `Implemented`

这是 jqkai 方法里很关键的状态，表示：

代码主线已经有明确实现信号
但 backlog 文档、索引、迁移动作还没有完全追平

这个状态非常适合真实项目，因为很多 feature 都会出现：

功能先落地
文档后回填
checklist 还没全勾

如果没有 Implemented，团队很容易只能在“假装还没做”和“强行迁 completed”之间二选一。

5.4 `Completed`

表示：

feature 已正式收口
目录已迁入 completed/
索引与文档口径已经同步

这是“需求、实现、文档、索引”同时收口后的状态，而不只是“代码已经写了”。

5.5 `Superseded`

用于：

被否决的补充提案
后续判定为误判的方案
不再驱动实施、但需要保留历史判断的文档

典型做法：

文件保留在原 feature 目录下
主 PRD 顶部显式链接
明确写出“不作为实现真源”

6. 目录状态与 PRD 状态不是一回事

这是这套方法最重要的规则之一。

6.1 目录表达的是“生命周期分层”

例如：

active/ 表示这个 feature 还在当前管理期
completed/ 表示这个 feature 已正式收口
archive/ 表示这个 feature 已经进入历史层级

6.2 PRD 状态表达的是“feature 本身当前语义”

例如同样在 active/ 中，PRD 可能分别是：

Proposed
Active
Implemented

所以不要假设：

在 active/ 就一定是“未实现”
在 completed/ 就一定不再有补充文档

7. 过程管理与阶段流转

7.1 标准流转

推荐流转如下：

新 feature 建立在 active/feat-{seq}-{slug}/
先写 PRD.md
同目录建立 implementation-checklist.md
feature 进入 Proposed 或 Active
代码开始落地后，根据事实更新为 Active 或 Implemented
文档、索引、验证、收尾全部同步后，整个目录迁到 completed/
更早期 completed backlog 再根据需要迁到 completed/archive/

7.2 `active/` 中允许的三种现实状态

active/ 不只承载一个状态，允许同时存在：

Proposed
Active
Implemented

这能真实反映项目现场，而不是要求所有 feature 都整齐划一。

7.3 `completed/` 的进入条件

建议同时满足以下条件再迁入 completed/：

主 PRD 已明确为 Completed
checklist 已追平当前现实
backlog 索引已同步
读者不再需要通过 active/ 继续跟踪它

8. 迁移规则

8.1 新 feature 先进入 `active/`

原因：

它仍处于当前管理期
需要持续修订 PRD、checklist 和边界

8.2 已实现但未回填，继续留在 `active/`

这是这套方法的一个核心经验：

不要因为代码写完了就急着迁到 completed/
只要 backlog 文档和索引还没收口，就允许保留在 active/
此时把 PRD 状态标成 Implemented 即可

8.3 正式收口后再迁 `completed/`

迁移动作应包括：

目录整体移动
更新根 backlog README
从 active/README.md 中移除
在 completed/ 视图中加入

8.4 历史化后再迁 `archive/`

archive/ 适合：

早期阶段的 backlog
已不再需要和现行 completed 混看的一组主题
需要保留历史链路，但不想干扰当前 completed 阅读体验的内容

8.5 补充 PRD 不新开号

如果某个议题满足以下特征，更适合写成补充 PRD：

它严格依附于已有 feature
它只是边界纠偏、rename、补充能力或误判修正
它不值得拥有独立 backlog 生命周期

9. 索引契约

9.1 根 backlog README

职责：

汇总 active / completed / archive 入口
给出当前高层口径
做 feature 列表导航

不应承担：

feature 真源
细粒度需求边界

9.2 `active/README.md`

建议承担：

当前管理期条目列表
带日期的口径说明
哪些是 Proposed
哪些是 Implemented
哪些 feature 虽然已实现但尚未迁 completed

9.3 `archive/README.md`

建议承担：

历史层说明
已归档条目索引
为什么这些内容不再放在现行 completed 里

10. 编号管理与冲突处理

编号冲突不是理论问题，而是长期 backlog 系统里真实会发生的事。

10.1 推荐分配规则

在分配新编号前，先执行三步检查：

搜索 active/
搜索 completed/
搜索 archive/

确认：

当前最大编号
是否已有同号目录
是否已有同主题但不同命名的历史条目

10.2 冲突处理建议

如果发现同号冲突：

优先重新分配新编号
不要让两个新 feature 长期共享同一编号
若冲突已经进入仓库历史，需要在索引和规范中显式说明，并尽快收口

10.3 编号不是状态

不要让编号承担这些职责：

优先级
负责人
发布顺序

编号只用于唯一标识和目录排序。

11. 常见坑与管理经验

11.1 checklist 被误写成任务分解

这是最常见的问题。

修正方式：

所有勾选项改写成结果态
不写“先做 A 再做 B”
写“完成后应能看到 A / B / C”

11.2 backlog 索引滞后于代码

这是正常现象，不必掩盖。

推荐做法：

在 README 里加“截至某日期的当前口径”
显式写出哪些 feature 已实现但尚未回填

11.3 已实现 feature 长期留在 `active/`

这不是错误，而是一个需要被定义的中间状态。

如果没有 Implemented：

团队会误判 feature 仍未落地
或者被迫过早迁入 completed/

11.4 archive 被当成 completed 的别名

正确理解应是：

completed/ 是现行已完成 backlog
archive/ 是进一步历史化后的完成 backlog

11.5 补充 PRD 滥开新编号

判断标准：

如果它不值得独立生命周期，就不要新开号
如果它只是原 feature 的补充、纠偏、误判修正，就留在原目录下

12. 推荐落地步骤

把这套方法复制到其他项目时，建议按以下顺序：

先建立 planning/backlog/ 基本目录
建立根 README.md、active/README.md、archive/README.md
固化 PRD.md 与 implementation-checklist.md 模板
约定状态枚举和顶部状态区
约定 feature 目录命名规则
约定迁移时必须同步更新索引
约定补充 PRD 与 handoff 的写法

13. 最小管理接口

如果你只想保留这套方法里最关键的契约，最少应固化下面三组规则。

13.1 目录契约

planning/backlog/active/feat-{seq}-{slug}/PRD.md
planning/backlog/active/feat-{seq}-{slug}/implementation-checklist.md
planning/backlog/completed/feat-{seq}-{slug}/PRD.md
planning/backlog/completed/archive/feat-{seq}-{slug}/PRD.md

13.2 状态契约

Proposed 只表示提案完成，不代表开发开始
Implemented 表示实现先行、文档迁移滞后
Completed 必须伴随目录迁移和索引同步
Superseded 只用于被否决或失效的补充提案

13.3 索引契约

根 backlog README 维护 active / completed / archive 总入口
active/README.md 维护当前管理期口径，允许附日期说明
archive/README.md 只维护历史层说明，不与现行 completed 混放

14. 配套资料

模板见 templates/
样例见 samples/README.md