pdlc-feature

name	pdlc-feature
description	全自动 PDLC 新功能开发（串联 PRD→设计→TDD→实现→评审→发布）
argument-hint	<功能描述 | 已有 PRD 路径>
allowed-tools	Read, Write, Edit, Glob, Grep, Bash, Task
layer	1
stage	feature
produces	["docs/01_requirements/prd/<feature-id>-<feature-name>-prd.md","docs/02_design/**","<实现与测试代码 · 项目既有布局>"]
requires	[]
next_step	pdlc-ship
terminal_state	feature_done

全自动 PDLC 新功能开发

接收功能描述或已有需求文档，全自动走完 PDLC 所有阶段，直到产出可上线状态，中途不暂停、不询问用户。

输入解析（阶段一之前执行）

从 $ARGUMENTS 中判断输入类型：

1. 检测是否为文件路径：如果输入匹配以下模式之一，视为文件输入：

   • 以 /、./、../、~ 开头的路径
   • 以 .md、.txt、.docx、.pdf、.doc 结尾
   • 包含 docs/ 或 requirements/ 路径片段
   • 是一个实际存在的文件路径

2. 文件输入：读取文件内容，从中提取功能描述、用户故事、验收标准。阶段一基于文件内容结构化生成 PRD（保留原始意图，补充缺失部分），而非从零推断。在 PRD 中标注：<!-- 来源文档: <原始文件路径> -->

3. 文本输入：按原有逻辑，从一句话描述自动推断

4. 已有 PRD 路径：如果输入指向 docs/01_requirements/prd/ 下已有的 PRD 文件，则跳过阶段一，直接从阶段一-B（任务拆解）或阶段二（技术设计）开始

执行规则

• 全程自动：不在任何阶段暂停等待确认，遇到歧义自行做合理假设并在最终报告中说明
• 严格顺序：必须按阶段一→二→三→四→五→六顺序执行，不得跳过
• 文档先行：每阶段先产出文档，再进入下一阶段
• TDD 强制：代码实现前测试必须已存在且处于失败状态
• 自查通过才结束：所有测试通过、评审记录完成后才输出最终报告
• 功能ID贯穿全程：阶段一分配功能ID后，所有后续文档和产出物统一使用该ID

---

功能ID分配（阶段一开始前执行）

1. 获取当前日期与时分秒：date +%Y%m%d、date +%H%M%S
2. 生成功能ID：F<YYYYMMDD>-<HHMMSS>（示例形如 F20260717-122801；用执行时的真实值）
3. 本地防撞：若该 ID 已被占用（docs/ 或 docs/.pdlc-state/ 下已有同名前缀），重新读取 date +%H%M%S 重取（生成本身有耗时、通常已跨秒；若仍同秒则 sleep 1 后再读一次，不手算时分秒，天然处理跨天边界）
4. 从用户描述中提取功能名关键词（英文小写+连字符，如 user-auth）

用时分秒而非当日序号，是为了多人 / 多 AI 并行时零协调也不撞号、合并零冲突。旧 F<日期>-<NN> ID 仍可解析。

关系建议（RFC#6）

分配 ID 后，扫描 docs/.pdlc-state/*.json 列出已有 feature 名，结合用户描述判断本功能与既有 feature 的关系：

• 描述含「基于 / 扩展 / 增强 X」→ 建议 extends X
• 描述含「需要 / 依赖 X」→ 建议 depends_on X
• 描述含「替代 / 重做 X」→ 建议 supersedes X
• 命中后填入 PRD §6.1 关系表，并在阶段四状态机的 relations 块写入。类型语义见 relations.md
• 无明显关系则跳过

---

阶段一：需求分析（PRD）

1. 根据功能描述，自动推断：功能范围、目标用户、核心用户故事（至少 3 条）、验收标准
2. 在 docs/01_requirements/prd/ 下创建文件，命名格式：<功能ID>-<功能名>-prd.md
3. 使用 templates/prd-template.md 作为模板
4. 文档顶部必须包含 PDLC 追溯头：

   <!-- PDLC-TRACE -->
   <!-- 功能ID: F20260326-090000 -->
   <!-- 功能名称: user-auth -->
   <!-- 阶段: 需求 -->
   <!-- 前置文档: 无 -->
   <!-- 创建时间: 2026-03-26T10:30:00 -->
   

5. 文档须包含：背景、目标、用户故事、功能清单、验收标准、非功能要求、不在范围内的事项

🔍 阶段一质量关卡（PRD 自审，必须执行）

PRD 创建后、任务拆解前，立即执行自审：

• 完整性：检查背景、目标用户、用户故事（≥3条）、功能清单（有优先级）、验收标准（可度量）、非功能需求、不在范围内 — 缺失的章节自动补充
• 一致性：用户故事与功能清单一一对应，验收标准覆盖所有 P0 功能
• 可操作性：验收标准无模糊表述，均可转化为测试用例 — 模糊的自动改写为量化指标
• 修复后在 PRD 末尾追加「自审记录」（含审查时间、问题数、修复明细）
• 自审通过才进入阶段一-B

阶段一-B：任务拆解（紧接 PRD 之后自动执行）

1. 扫描 docs/06_tasks/ 目录，查找是否已存在该功能的任务文件
2. 若不存在，立即按 pdlc-task plan 的逻辑自动执行任务拆解：
   • 读取刚创建的 PRD，提取功能清单与验收标准
   • 为每条功能清单项生成任务条目，分配任务ID（格式：T<功能ID的日期-时分秒>-<NN>-<type>，前缀嵌入本功能ID的时分秒段，NN 为本功能内递增序号）
   • 创建任务文件：docs/06_tasks/<功能ID>-<功能名>-tasks.md
   • 格式参考 pdlc-task plan 的输出规范（每条任务含 ID、标题、类型、状态 ⬜、前置依赖）
3. 在阶段报告中输出任务文件路径和任务总数

阶段一-C：PRD 文档评审（紧接任务拆解后自动执行）

1. 按 /pdlc-review 的文档评审段落逻辑，对 PRD 执行正式文档评审（聚焦格式规范性、模板符合度、交叉引用）
2. 对照 templates/prd-template.md 检查格式规范性
3. 发现问题直接修复原 PRD 文档，修复后仅复查一次，不递归
4. 在 docs/07_reviews/doc/ 下创建评审记录：<功能ID>-<功能名>-prd-doc-review.md
5. 评审通过后进入阶段二

---

阶段二：技术设计

根据 PRD 自动判断需要哪些设计文档，按需创建（不需要的跳过）：

API 设计（如涉及接口变更）：

• 路径：docs/02_design/api/<功能ID>-<功能名>-api.md
• 模板：templates/api-design-template.md
• 必须包含：接口列表、请求/响应结构、错误码

数据库设计（如涉及数据存储）：

• 路径：docs/02_design/database/<功能ID>-<功能名>-db.md
• 模板：templates/db-design-template.md
• 必须包含：ER 图、表结构、索引设计、迁移 DDL

架构设计（如涉及新服务或重大架构变更）：

• 路径：docs/02_design/architecture/<功能ID>-<功能名>-arch.md
• 模板：templates/arch-design-template.md

所有设计文档顶部必须包含 PDLC 追溯头：

<!-- PDLC-TRACE -->
<!-- 功能ID: F20260326-090000 -->
<!-- 功能名称: user-auth -->
<!-- 阶段: 设计 -->
<!-- 前置文档: docs/01_requirements/prd/F20260326-090000-user-auth-prd.md -->

🔍 阶段二质量关卡（设计文档自审，必须执行）

每份设计文档创建后立即执行自审：

• PRD 一致性：PRD 中每条 P0/P1 功能是否有对应设计覆盖 — 遗漏的自动补充
• API 检查：URL 规范、请求/响应完整、统一响应格式、分页参数、鉴权说明
• DB 检查：主键、索引、审计字段（created_at/updated_at）、迁移 DDL
• 跨文档一致性：API 响应字段与 DB 字段对应，查询参数有索引支撑
• 修复后在设计文档末尾追加「自审记录」
• 在 docs/07_reviews/doc/ 下创建设计评审记录：<功能ID>-<功能名>-design-doc-review.md
• 修复后仅复查一次，不递归；复查仍有问题则记录到评审报告
• 自审通过才进入阶段三

---

阶段三：测试先行（TDD 红灯）

1. 在 docs/04_testing/unit-tests/ 下创建测试计划：<功能ID>-<功能名>-test-plan.md
   • 文档顶部包含 PDLC 追溯头（阶段: 测试，前置文档指向设计文档）
2. 写到项目既有的测试布局里（定位规则见下），不新造平行目录：

3. 测试必须覆盖：正常流程、边界条件、异常场景
4. 单元测试覆盖率：覆盖率达标线以项目配置为准：优先取 docs/00_standards/test-commands.yml 的 coverage 命令阈值参数（那才是强制点，退出码即判定），其次 quality-targets.yml；两者都没有时按 >= 80% 兜底。
5. 运行测试，确认测试处于失败状态（红灯），记录失败输出
6. 同步编写 E2E 测试骨架（可暂时 skip，实现阶段补全）：
   • 路径：docs/04_testing/e2e-tests/<功能ID>-<功能名>-e2e.md

🔍 阶段三质量关卡（测试计划自审，必须执行）

测试代码编写完成、运行前执行自审：

• 验收标准覆盖度：PRD 每条验收标准至少有一个对应测试用例 — 缺失的自动补充
• 场景完备性：边界条件（空值/最大值/零值）、异常场景（401/403/404/409）、幂等性
• 测试质量：方法命名是否描述场景、是否单一断言、测试数据是否有意义
• 修复后在测试计划末尾追加「自审记录」（含验收标准覆盖数、API 接口覆盖数）
• 自审通过才运行测试确认红灯

---

阶段四：编码实现（绿灯）

1. 阅读 docs/00_standards/coding/ 目录确认编码规范
2. 编写最少量的实现代码使所有单元测试通过
3. 实现过程中不偏离设计文档；若发现设计遗漏，自行补充设计文档后继续
4. 运行测试，确认全部通过（绿灯）
5. 在测试通过前提下，重构优化代码结构（不改变行为）
6. 补全 E2E 测试代码并运行验证

🔍 阶段四质量关卡（实现自检，必须执行）

代码实现完成、测试全部通过后，执行快速自检：

• 设计偏离检查：对照设计文档，确认没有遗漏的接口或功能点
• 测试覆盖验证：按上述口径确认覆盖率达标，不达标则补充测试
• 编码规范快检：快速运行 lint check，有问题立即 lint fix
• 自检通过才进入阶段五正式评审

---

阶段五：自查评审（代码评审 + 自动修复）

按 /pdlc-review 增强版逻辑执行全面评审，发现问题直接修复：

1. 设计一致性检查：对照设计文档逐项确认实现完整性
   • API URL/方法/参数是否与设计一致
   • DB 表结构/字段是否与设计一致
   • 响应格式是否统一 — 不一致的直接修复代码
2. 验收标准验证：对照 PRD 逐条确认验收标准是否满足，未满足的补充实现
3. 代码质量检查与修复：
   • 按 pdlc-lint check 运行 lint 工具，存在问题则 pdlc-lint fix 自动修复
   • 检查命名规范 — 不规范的直接重命名
   • 检查错误处理 — 缺失的直接补充
   • 检查日志 — 关键操作缺日志的直接添加
4. 安全检查与修复：
   • SQL 注入：字符串拼接 SQL → 自动改写为参数化查询
   • XSS：未转义输出 → 自动添加转义
   • 权限控制：缺鉴权的接口 → 标记为需人工处理
   • 敏感数据：日志中打印敏感字段 → 自动脱敏
5. 性能检查：N+1 查询、缺失分页、缺失索引 — 能修的直接修复
6. 修复后验证：重新运行全部测试，确认修复未引入新问题
   • 测试失败 → 回滚修复，标记为需人工处理
7. 生成评审报告：在 docs/07_reviews/code/ 下创建评审记录：<功能ID>-<功能名>-review.md
   • 包含 PDLC 追溯头（阶段: 评审，含创建时间）
   • 包含：评审总结（问题总数/自动修复数/需人工处理数）、自动修复记录表、需人工处理表、检查项结论
8. 更新对应服务的 CHANGELOG.md，在 [未发布] 下新增 feat 条目

阶段六：最终报告

⚠️ 文件落盘验证：输出最终报告前，必须逐一确认以下文件均已作为实际文件创建到磁盘（不可仅在对话中显示）：

产出物	路径	验证方式
PRD 文档	docs/01_requirements/prd/<功能ID>-*-prd.md	确认文件存在
任务清单	docs/06_tasks/<功能ID>-*-tasks.md	确认文件存在
PRD 评审记录	docs/07_reviews/doc/<功能ID>-*-prd-doc-review.md	确认文件存在
设计文档	docs/02_design/ 下对应目录	确认文件存在
设计评审记录	docs/07_reviews/doc/<功能ID>-*-design-doc-review.md	确认文件存在
测试计划	docs/04_testing/unit-tests/<功能ID>-*-test-plan.md	确认文件存在
测试代码	对应服务测试目录	确认文件存在
代码评审记录	docs/07_reviews/code/<功能ID>-*-review.md	确认文件存在

如有文件缺失，立即补创建，不可跳过。

所有文件确认到位后，输出一份结构化的完成报告，格式如下：

## PDLC 完成报告：<功能名>（<功能ID>）

### 产出物清单
| 类型 | 文件路径 |
|------|----------|
| PRD | docs/01_requirements/prd/<功能ID>-... |
| API 设计 | docs/02_design/api/<功能ID>-... |
| 数据库设计 | docs/02_design/database/<功能ID>-... |
| 测试计划 | docs/04_testing/unit-tests/<功能ID>-... |
| 评审记录 | docs/07_reviews/code/<功能ID>-... |

### 测试结果
- 单元测试：X 个通过 / 0 个失败
- E2E 测试：X 个通过 / 0 个失败
- 覆盖率：XX%

### 任务完成情况
- 任务文件：`docs/06_tasks/<功能ID>-<功能名>-tasks.md`
- 总任务数：X  完成：X  进行中：X  未开始：X

### 验收标准确认
- [x] 验收标准 1
- [x] 验收标准 2

### 假设与决策说明
（记录执行过程中自行做出的关键假设）

### 上线前待办
（如有需要人工处理的事项，如数据库迁移、环境变量配置等）

---

要求

• 文件名中的功能名使用英文小写+连字符，如 user-login
• 日期使用执行当天的实际日期，格式 YYYYMMDD
• 不引入不必要的依赖
• 不过度设计，实现够用即可

功能描述: $ARGUMENTS