16 - 功能清单体系设计

1. 问题定义

随着项目功能增长，三个关键能力缺失：

功能全景     ❌  没有一份文件能看到"产品有哪些功能、边界在哪"
开发进度     ❌  功能状态散落在 git log 和口头记忆中
测试覆盖关联  ❌  测试纪律按函数/API 维度，无法回答"某功能是否测完"

现有体系中"接近但不等于"功能清单的机制：

机制	覆盖维度	差距
按需 PRD（`/plan`）	单个大功能的需求定义	不是持续维护的全景清单
`/impact` 影响分析	改动前的范围评估	事件驱动，不追踪全局
`/health-report` 体检	测试覆盖、模块耦合	按代码模块维度，不是功能维度
Git commit history	变更记录	需要人工从 log 中提炼功能全貌

功能清单不是项目管理工具（不替代 GitHub Issues / Linear），是产品能力的全景地图——一份文件看完所有功能的边界、状态和测试覆盖。

2. 文档层级定位

功能清单属于推荐有（中大项目），与 PRD、ADR 同级别：

文档	路径	维护方式	触发条件
功能清单	`docs/features.md`	`/features` Skill 维护	功能数 ≥ 5 或跨 2 个模块

不在 check 脚本中强制检查存在性（WARN 提醒而非 FAIL 阻断），尊重小项目的轻量需求。

3. 文件格式规范

3.1 完整示例

markdown

# 功能清单

> 最后更新：2026-02-19 | 总计：12 项 | ✅ 8 | 🚧 3 | 📋 1

## 模块：用户系统

| ID | 功能 | 状态 | 优先级 | 测试 | 关键文件 | 备注 |
|----|------|------|--------|------|---------|------|
| USR-01 | 邮箱注册 | ✅ done | P0 | ✅ 3/3 | `src/services/auth.ts` | |
| USR-02 | 微信登录 | 🚧 dev | P0 | 🔶 1/3 | `src/services/wechat.ts` | 等待微信审核 |
| USR-03 | 个人资料编辑 | 📋 todo | P1 | — | | 依赖 USR-01 |

## 模块：订单系统

| ID | 功能 | 状态 | 优先级 | 测试 | 关键文件 | 备注 |
|----|------|------|--------|------|---------|------|
| ORD-01 | 创建订单 | ✅ done | P0 | ✅ 5/5 | `src/services/order.ts` | |
| ORD-02 | 订单退款 | 📋 todo | P1 | — | | |

3.2 字段定义

字段	格式	说明
ID	`{MOD}-{NN}`	模块缩写（大写 2-5 字母）+ 两位序号，全局唯一
功能	自由文本	一句话描述，动词开头（"创建订单"而非"订单创建功能"）
状态	5 种枚举	见 §3.3 状态流转
优先级	`P0` / `P1` / `P2`	P0 必做、P1 应做、P2 可选
测试	`✅ n/n` / `🔶 n/n` / `❌ 0/n` / `—`	通过数/总数。全通过 ✅、部分 🔶、全挂 ❌、未写 —
关键文件	代码路径	主要实现文件（1-3 个），用反引号包裹
备注	自由文本	依赖关系、阻塞原因、外部依赖

3.3 状态流转

📋 todo  →  🚧 dev  →  ✅ done  →  🚀 live
                              ↘ ❌ cut

状态	含义	进入条件
`📋 todo`	已规划，未开始	功能被识别并录入
`🚧 dev`	开发中	开始编码或已有 WIP 代码
`✅ done`	开发完成，测试通过	代码合并、测试全绿
`🚀 live`	已上线	部署到生产环境
`❌ cut`	已砍掉	决定不做（保留记录，不删行）

3.4 ID 编码规则

模块缩写：取模块名的英文缩写，大写，2-5 个字母
序号：两位数字，从 01 开始递增
同一模块内序号连续，但不要求跨模块连续
删除功能（❌ cut）不回收 ID

常用缩写示例：

用户系统 → USR    订单系统 → ORD    支付 → PAY
内容管理 → CMS    通知 → NTF       设置 → SET
仪表盘  → DASH    报表 → RPT       权限 → PERM

3.5 头部统计行

文件首行 blockquote 为自动统计摘要，由 /features Skill 维护：

markdown

> 最后更新：2026-02-19 | 总计：12 项 | ✅ 8 | 🚧 3 | 📋 1

只统计活跃状态（todo/dev/done/live），不计 cut。

4. 维护纪律

4.1 什么时候更新

事件	操作	由谁触发
`/plan` 输出新功能方案	在清单中新增条目，状态 `📋 todo`	`/features add` 或手动
开始编码某功能	状态 → `🚧 dev`，填写关键文件	`/features update` 或手动
功能代码合并 + 测试全绿	状态 → `✅ done`，更新测试列	`/features update`
部署到生产环境	状态 → `🚀 live`	手动
决定不做某功能	状态 → `❌ cut`，备注填原因	手动
`/test` 生成或更新测试	更新对应功能的测试列	`/features update`

4.2 与 git 的关系

功能清单的变更包含在功能分支的 commit 中，不单独提交。典型流程：

git checkout -b feat/wechat-login
# 编码...
# 更新 docs/features.md 中 USR-02 状态为 dev
git add src/ docs/features.md
git commit -m "feat(auth): add wechat login"

4.3 规模控制

单个模块超过 20 项功能 → 考虑拆分子模块
总计超过 50 项功能 → 按模块拆分为独立文件（docs/features/usr.md），主文件只保留索引
❌ cut 状态的条目超过总数 30% → 清理到归档区（文件底部的 ## 归档 章节）

5. /features Skill

5.1 概述

维度	说明
触发时机	需要查看、添加或更新功能清单时
前置条件	`docs/features.md` 存在（不存在时引导创建）
产物	更新后的 `docs/features.md` 或进度报告

5.2 三个子命令

`/features` 或 `/features add`

交互式添加功能条目：

读取 docs/features.md，解析现有模块和 ID
询问用户：
- 归属模块（已有模块列表 / 新建模块）
- 功能名称（一句话，动词开头）
- 优先级（P0 / P1 / P2）
自动分配 ID（模块缩写 + 递增序号）
写入对应模块表格末尾，初始状态 📋 todo
更新头部统计行

`/features update`

扫描并批量更新：

读取 docs/features.md，解析所有条目
对每个 🚧 dev 状态的功能：
- 检查关键文件字段是否有值且文件存在
- 搜索对应测试文件，统计通过数/总数
- 如果测试全通过，建议状态 → ✅ done
对每个 ✅ done 状态的功能：
- 验证测试列是否有值（无测试 → 警告）
输出变更建议清单，等待用户确认后写入
更新头部统计行

`/features report`

输出功能进度统计报告（不修改文件）：

## 功能进度报告（2026-02-19）

### 总览
- 总计：12 项功能
- ✅ 已完成：8（67%） | 🚧 开发中：3（25%） | 📋 待开始：1（8%）

### 测试覆盖
- 有测试的功能：10/12（83%）
- 测试全通过：7/10（70%）
- ⚠️ 已完成但无测试：USR-01

### 模块进度
| 模块 | 完成率 | 测试覆盖 |
|------|--------|---------|
| 用户系统 | 1/3（33%） | 1/1 ✅ |
| 订单系统 | 1/2（50%） | 1/1 ✅ |

### 风险项
- [列出状态异常或长期未推进的条目]

5.3 不存在时的行为

如果 docs/features.md 不存在：

提示用户是否创建
确认后生成模板（与 CLI Level 1 模板一致）
引导用户录入第一批功能

6. 工具链集成

6.1 CLI 模板（Level 1）

cli/templates/level-1/docs/features.md.tpl：

markdown

# 功能清单

> 最后更新：— | 总计：0 项

## 模块：核心功能

| ID | 功能 | 状态 | 优先级 | 测试 | 关键文件 | 备注 |
|----|------|------|--------|------|---------|------|
| CORE-01 | | 📋 todo | P0 | — | | |

<!--
功能清单维护指南：
- /features add — 添加新功能
- /features update — 批量更新状态和测试覆盖
- /features report — 查看进度报告
- 状态：📋 todo → 🚧 dev → ✅ done → 🚀 live / ❌ cut
- ID 格式：{模块缩写}-{序号}，如 USR-01、ORD-02
- 详见设计文档：16-功能清单体系
-->

在 npx ai-dev-cli init Level 1 阶段生成到 docs/features.md。

6.2 check 检查项

新增 checkFeaturesDoc() 函数，WARN 级别（推荐有，不阻断）：

检查项	级别	说明
`docs/features.md` 存在性	WARN	提醒创建，不阻断
表头列数完整（7 列）	WARN	格式合规性
ID 无重复	WARN	数据完整性
状态值在允许范围内	WARN	`todo/dev/done/live/cut`

6.3 文档站同步

在 site/sync.mjs 的 DESIGN_SLUG_MAP 中新增：

javascript

'16-功能清单体系': '16-feature-inventory',

设计文档随其他文档一起同步，无需额外处理。

7. 与现有体系的联动

7.1 联动关系图

/spec → 需求定义
  ↓
/plan → 方案设计 ──→ /features add（注册新功能）
  ↓
编码 ──→ /features update（状态 → dev）
  ↓
/test → 生成测试 ──→ /features update（更新测试列）
  ↓
/review → 代码审查
  ↓
/commit → 提交 ──→ features.md 随代码一起提交
  ↓
/health-report ──→ 功能覆盖维度（已完成但无测试的功能数）

7.2 各 Skill 的联动规则

Skill	联动行为
`/plan`	输出方案时，检查 `features.md` 是否存在。如有，建议在其中注册新功能条目
`/test`	生成测试后，提示运行 `/features update` 同步测试覆盖数据
`/health-report`	健康度报告新增"功能覆盖"维度：已完成但无测试的功能数、开发中超过 2 周的功能数
`/check`	脚本层 WARN 检查 `features.md` 的格式合规性

联动是提示性的，不是强制的。各 Skill 在输出末尾附带提示语，用户决定是否执行。

8. 渐进式采用

第一步：建立清单（5 分钟）

bash

npx ai-dev-cli init  # Level 1 自动生成 docs/features.md

或手动创建，录入现有功能。从最核心的 3-5 个功能开始，不需要一次列全。

第二步：融入开发流程（日常）

每次开始新功能时 /features add，完成时 /features update。不需要刻意维护，跟着开发节奏走。

第三步：定期审视（每两周）

与 /health-report 一起运行 /features report，审视整体进度和测试覆盖。

9. 与其他子系统的关系

CLAUDE.md：不在 CLAUDE.md 中写功能清单规则（避免膨胀），
          /features Skill 自包含所有逻辑
Skills：/features 新增 Skill，/plan /test /health-report 联动
Hooks：不参与（功能清单维护不是确定性操作）
MCP：不参与（本地文件操作）
脚本 check：WARN 级别格式检查
文档站：设计文档自动同步

16 - 功能清单体系设计 ​

1. 问题定义 ​

2. 文档层级定位 ​

3. 文件格式规范 ​

3.1 完整示例 ​

3.2 字段定义 ​

3.3 状态流转 ​

3.4 ID 编码规则 ​

3.5 头部统计行 ​

4. 维护纪律 ​

4.1 什么时候更新 ​

4.2 与 git 的关系 ​

4.3 规模控制 ​

5. /features Skill ​

5.1 概述 ​

5.2 三个子命令 ​

/features 或 /features add ​

/features update ​

/features report ​

5.3 不存在时的行为 ​

6. 工具链集成 ​

6.1 CLI 模板（Level 1） ​

6.2 check 检查项 ​

6.3 文档站同步 ​

7. 与现有体系的联动 ​

7.1 联动关系图 ​

7.2 各 Skill 的联动规则 ​

8. 渐进式采用 ​

第一步：建立清单（5 分钟） ​

第二步：融入开发流程（日常） ​

第三步：定期审视（每两周） ​

9. 与其他子系统的关系 ​

16 - 功能清单体系设计

1. 问题定义

2. 文档层级定位

3. 文件格式规范

3.1 完整示例

3.2 字段定义

3.3 状态流转

3.4 ID 编码规则

3.5 头部统计行

4. 维护纪律

4.1 什么时候更新

4.2 与 git 的关系

4.3 规模控制

5. /features Skill

5.1 概述

5.2 三个子命令

`/features` 或 `/features add`

`/features update`

`/features report`

5.3 不存在时的行为

6. 工具链集成

6.1 CLI 模板（Level 1）

6.2 check 检查项

6.3 文档站同步

7. 与现有体系的联动

7.1 联动关系图

7.2 各 Skill 的联动规则

8. 渐进式采用

第一步：建立清单（5 分钟）

第二步：融入开发流程（日常）

第三步：定期审视（每两周）

9. 与其他子系统的关系