新功能

在已有 DevDocs 项目中追加新功能，确保编号延续、文档一致。

语言规则

• 支持中英文提问
• 统一中文回复

触发条件

• 用户要在已有项目中添加新功能
• 用户提到"增量"、"迭代"、"新增功能"、"追加需求"
• 用户要求扩展现有功能

前置条件

• 已存在 DevDocs 文档目录：docs/devdocs/
• 至少存在 01-requirements.md

如不存在，建议：

• 新项目 → /devdocs-requirements
• 已有代码无文档 → /devdocs-retrofit

运行模式

模式选择

/devdocs-feature "功能描述"        → 自动检测模式
/devdocs-feature --lite "功能描述" → 强制轻量模式

模式对比

模式	适用场景	更新文档	上下文负载
轻量模式	配置修改、UI 微调、简单字段	01 + 04	低
完整模式	新模块、新接口、架构变更	01 + 02 + 03 + 04	高（分步）

自动模式检测

分析需求描述，检测是否涉及：

[ ] 新增 API 接口
[ ] 数据模型变更
[ ] 组件间依赖变化
[ ] 第三方服务集成
[ ] 新增独立模块

• 以上均无 → 轻量模式
• 任一命中 → 完整模式（提示用户确认）

检测到可能涉及架构变更：
- 新增接口: UserPreferenceAPI

建议使用完整模式。是否继续轻量模式？[是/否]

核心理念

新功能开发 = 延续编号 + 追加文档 + 影响分析 + 回归保护

轻量模式流程 (--lite)

1. 扫描编号
   │
   ├── 读取 01-requirements.md → 获取 AC 最大编号
   └── 读取 04-dev-tasks*.md → 获取 T 最大编号
   │
   ▼
2. 收集需求（简化）
   │
   └── 验收标准（AC 级别）
   │
   ▼
3. 追加文档（仅两份）
   │
   ├── 01-requirements.md → 追加 AC（挂载到现有 F/US）
   └── 04-dev-tasks*.md → 追加 1-3 个任务
   │
   ▼
4. 用户确认

轻量模式约束

• 不新建 F-XXX（功能点），仅追加 AC 到现有功能
• 不更新 02-system-design（无架构变更）
• 不更新 03-test-cases（由 /devdocs-sync 后续补齐）
• 任务数量限制 1-3 个

完整模式流程（分步编排）

核心变更：不再一次性更新 4 份文档，而是分步执行，每步确认后再进入下一步。

┌─────────────────────────────────────────────────────────────┐
│  Step 0: 扫描现有文档，获取编号和架构摘要                    │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  Step 1: 需求追加                                           │
│  ├── 收集新功能描述                                         │
│  ├── 追加 01-requirements.md（F/US/AC）                     │
│  └── ✅ 用户确认                                            │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  Step 2: 设计追加                                           │
│  ├── 影响分析（模块/接口/数据）                             │
│  ├── 追加 02-system-design*.md                              │
│  └── ✅ 用户确认                                            │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  Step 3: 测试追加                                           │
│  ├── 根据新增 AC 设计测试用例                               │
│  ├── 追加 03-test-cases*.md + 更新追溯矩阵                  │
│  └── ✅ 用户确认                                            │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  Step 4: 任务追加                                           │
│  ├── 根据设计和测试拆分开发任务                             │
│  ├── 追加 04-dev-tasks*.md                                  │
│  └── ✅ 用户确认                                            │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  Step 5: 生成功能日志                                       │
│  └── 更新 00-feature-log.md                                 │
└─────────────────────────────────────────────────────────────┘

分步执行优势

问题	传统方式	分步编排
编号重复	一次维护 4 份编号，易出错	每步只关注当前文档编号
漏更新	上下文过长，易遗漏	每步确认，不遗漏
追溯不完整	难以保证 AC→测试 完整性	Step 3 专注追溯矩阵
回滚困难	全量修改难回滚	可在任意步骤终止

Step 0: 扫描现有文档

编号提取

从现有文档中提取最大编号：

## 当前状态

| 类型 | 当前最大编号 | 下一编号 |
|------|-------------|----------|
| 功能点 (F) | F-003 | F-004 |
| 用户故事 (US) | US-008 | US-009 |
| 验收标准 (AC) | AC-015 | AC-016 |
| 单元测试 (UT) | UT-012 | UT-013 |
| 集成测试 (IT) | IT-003 | IT-004 |
| E2E 测试 (E2E) | E2E-002 | E2E-003 |
| 开发任务 (T) | T-10 | T-11 |

架构摘要（完整模式）

从 02-system-design*.md 提取：

• 现有模块列表
• 核心接口
• 数据实体

Step 1: 需求追加

收集信息

使用 AskUserQuestion 收集：

1. 新功能描述：要添加什么功能？
2. 用户价值：解决什么问题？
3. 范围边界：包含/不包含什么？

追加 01-requirements.md

---

## 功能 v2: <功能名称> (2024-01-15)

> 本次新增 F-004，包含 2 个用户故事、5 个验收标准。

### F-004: <功能名称>

**描述**：<功能描述>

**用户故事**：

| 编号 | 角色 | 期望 | 目的 |
|------|------|------|------|
| US-009 | 作为<角色> | 我希望<功能> | 以便于<价值> |

**验收标准**：

- [ ] AC-016: <标准1>
- [ ] AC-017: <标准2>

✅ 确认点

已追加到 01-requirements.md：
- 新增 F-004: <功能名称>
- 新增 US-009, US-010
- 新增 AC-016 ~ AC-020

是否确认并继续到 Step 2（设计追加）？[确认/修改/终止]

Step 2: 设计追加（完整模式）

影响分析

维度	问题	影响级别
模块	是否需要新增模块？	高
接口	是否修改现有接口签名？	高
数据	是否修改现有数据模型？	高
依赖	是否引入新依赖？	中
配置	是否需要新配置项？	低

追加 02-system-design*.md

## 设计变更 v2: <功能名称> (2024-01-15)

### 影响摘要

| 影响类型 | 说明 | 级别 |
|----------|------|------|
| 新增模块 | PaymentModule | 高 |
| 修改接口 | IOrderService.create() 增加参数 | 高 |

### 接口变更

#### IOrderService（变更）

| 方法 | 变更类型 | 说明 |
|------|----------|------|
| `create` | 参数新增 | 新增 `paymentMethod` 参数 |
| `processPayment` | 新增 | 处理支付（关联 F-004） |

**向后兼容性**：
- `paymentMethod` 参数可选，默认值为 `'default'`

### 回归风险

- [ ] OrderService 的现有测试需要更新
- [ ] checkout 流程的 E2E 测试需要验证

✅ 确认点

已追加到 02-system-design.md：
- 新增模块: PaymentModule
- 接口变更: IOrderService

是否确认并继续到 Step 3（测试追加）？[确认/修改/终止]

Step 3: 测试追加（完整模式）

根据新增 AC 设计测试

为每个新增的 AC-XXX 设计对应测试用例。

追加 03-test-cases*.md

## 测试用例 v2: <功能名称> (2024-01-15)

### 新增单元测试

| 编号 | 测试名称 | 关联 AC | 测试类型 |
|------|----------|---------|----------|
| UT-013 | 支付金额计算 | AC-016 | 单元测试 |
| UT-014 | 支付状态转换 | AC-017 | 单元测试 |

### 追溯矩阵更新

| AC 编号 | 单元测试 | 集成测试 | E2E 测试 | 状态 |
|---------|----------|----------|----------|------|
| AC-016 | UT-013 | IT-004 | - | ⏳ |
| AC-017 | UT-014 | - | E2E-003 | ⏳ |

✅ 确认点

已追加到 03-test-cases.md：
- 新增 UT-013, UT-014
- 新增 IT-004, E2E-003
- 追溯矩阵已更新

是否确认并继续到 Step 4（任务追加）？[确认/修改/终止]

Step 4: 任务追加

根据设计和测试拆分任务

遵循 TAR 原则：

• Testable: 有测试方法
• Acceptable: 有完成标准
• Reviewable: 有审查点

追加 04-dev-tasks*.md

## 任务 v2: <功能名称> (2024-01-15)

### T-11: 支付模块基础架构 🔴

**关联需求**：F-004, AC-016
**分层**：Core（强制 TDD）
**涉及文件**：
- `src/services/payment.ts`
- `src/services/payment.test.ts`

**TDD 执行**：
1. 🔴 编写 `payment.test.ts` 失败测试
2. 🟢 实现 `payment.ts` 最小代码
3. 🔵 重构优化

**完成标准**：
- [ ] UT-013 通过
- [ ] 代码审查通过

✅ 确认点

已追加到 04-dev-tasks.md：
- 新增 T-11 ~ T-14（4 个任务）
- 已标注 TDD 分层

是否确认并生成功能日志？[确认/修改/终止]

Step 5: 生成功能日志

输出文件

docs/devdocs/
└── 00-feature-log.md    # 功能日志（追加）

报告模板

# 新功能开发日志

## v2: <功能名称> (2024-01-15)

### 新增内容

| 类型 | 编号 | 描述 |
|------|------|------|
| 功能点 | F-004 | <描述> |
| 用户故事 | US-009, US-010 | <描述> |
| 验收标准 | AC-016 ~ AC-020 | 5 条 |
| 测试用例 | UT-013 ~ UT-015, E2E-003 | 4 条 |
| 开发任务 | T-11 ~ T-14 | 4 个 |

### 影响范围

- 新增模块：PaymentModule
- 修改接口：IOrderService
- 回归风险：OrderService 测试

### 关联文档

- [01-requirements.md](01-requirements.md) - 已更新
- [02-system-design.md](02-system-design.md) - 已更新
- [03-test-cases.md](03-test-cases.md) - 已更新
- [04-dev-tasks.md](04-dev-tasks.md) - 已更新

---

## v1: 初始版本 (2024-01-01)

...

Skill 协作

阶段	协作 Skill	说明
需求追加	-	本 skill 处理
设计追加	/devdocs-system-design	复杂设计变更时调用
测试追加	/devdocs-test-cases	复杂测试设计时调用
任务追加	/devdocs-dev-tasks	任务拆分时调用
开发实现	/code-quality, /testing-guide	编码阶段

约束

编号约束

• 必须延续现有编号，不得重复
• 必须先扫描现有文档获取最大编号
• 编号格式保持一致（F-XXX, US-XXX, AC-XXX）

文档约束

• 追加内容必须标注功能版本和日期
• 不得删除或覆盖现有内容
• 追加位置必须正确（章节末尾）
• 格式必须与现有文档一致

分步编排约束（完整模式）

• 每步完成后必须等待用户确认
• 不得跳过步骤（除非用户明确要求）
• 用户可在任意步骤选择"终止"
• 每步只关注当前文档的编号和格式
• 步骤间传递的信息仅限：新增编号列表

轻量模式约束

• 仅更新 01-requirements.md 和 04-dev-tasks.md
• 不新建 F-XXX，仅追加 AC 到现有功能
• 任务数量限制 1-3 个
• 检测到架构影响时必须提示用户

影响分析约束

• 修改现有接口必须说明向后兼容性
• 必须列出回归风险点
• 高影响变更需用户确认

追溯约束（完整模式）

• 新增 F-XXX 必须有对应 US-XXX 和 AC-XXX
• 新增 AC-XXX 必须有对应测试用例
• 必须更新追溯矩阵

特殊情况

文档结构不完整

如果只有部分文档存在：

1. 提示用户缺失的文档
2. 建议先补全文档（使用 /devdocs-retrofit）
3. 或仅追加到已有文档

大规模功能

如果新功能需求较大（超过 3 个功能点）：

建议拆分为多次迭代：
1. 按功能模块拆分
2. 每次迭代独立完成
3. 分别提交和验证

需求变更（非新增）

如果是修改现有需求而非新增：

⚠️ 这是需求变更，不是新功能需求。

建议：
1. 在原 F-XXX 下标注变更
2. 更新相关 US/AC
3. 更新受影响的测试用例
4. 记录变更原因

输出

• 更新 01-requirements.md（追加）
• 更新 02-system-design*.md（追加/修改）
• 更新 03-test-*.md（追加）
• 更新 04-dev-tasks*.md（追加）
• 更新/创建 00-feature-log.md（追加）