/pdlc-feature

name: pdlc-feature
description: 全自动 PDLC 新功能开发（串联 PRD→设计→TDD→实现→评审→发布）
argument-hint: "<功能描述 | 已有 PRD 路径> [--lite] [--autonomous]"
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task, Agent
layer: 1
stage: feature
# 串联的阶段：逐阶段写状态机（adapters/sync_skills.py 据此生成正文里的 pdlc:meta）
phases: requirements design tdd impl review
produces:
  - docs/01_requirements/prd/<feature-id>-<feature-name>-prd.md
  - docs/02_design/**
  # 跟随项目既有布局，不限定固定目录
  - <实现与测试代码 · 项目既有布局>
requires: []
next_step: pdlc-ship
terminal_state: feature_done

全自动 PDLC 新功能开发

<!-- @include templates/prompts/iron-law.md（已内联于下方，无需另读） --> ⛔ **IRON LAW · 不可违反的硬门禁**

以下规则为**不可协商**的执行约束：

1. **文件必须落盘**：所有带编号（功能ID / 缺陷ID）的文档，必须作为实际文件写入磁盘，不可仅在对话中输出。 2. **阶段必须落章**：每个阶段完成后必须在状态机 `docs/.pdlc-state/<feature-id>.json` 追加 history，不可跳过。 3. **测试必须存在**：进入 `/pdlc-implement` 前，对应测试必须存在且处于红灯状态。违反则中止。 4. **自检必须执行**：段二自检为强制步骤，不得以"已经很好了"为由跳过。 5. **防循环**：段三修复为单次，不递归。无法自动修复的问题记录到报告，继续往下走。 6. **状态必推进**：成功执行某 phase 后 `current_stage` 必须变更。收尾时若发现 `current_stage` 未推进，视为失败并报错，**不得静默返回**（防止外层循环拿滞后的状态空转烧额度）。唯一例外：命中人工点主动 block 时，`current_stage` 保持不变但必须写 `last_phase_result.ok=false` + `blocked_reason`。

**违反任一条 = 立即中止当前命令，输出违规详情，等待人工介入。** <!-- @include-end templates/prompts/iron-law.md -->

接收功能描述或已有需求文档，全自动走完 PDLC 所有阶段，直到产出可上线状态。唯一的提问点在开工前：文字描述太单薄时问一轮澄清（带 `--autonomous` 则一个都不问）；开工后中途不暂停、不询问用户。

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

从本命令的参数中判断输入类型：

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

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

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

3. **文本输入**：先按下文「需求澄清」对照清单，描述太单薄时问一轮（`--autonomous` 下不问），再从描述自动推断

4. **已有 PRD 路径**：如果输入指向 `docs/01_requirements/prd/` 下已有的 PRD 文件，则**跳过阶段一**，直接从阶段一-B（任务拆解）或阶段二（技术设计）开始；带 `--lite` 时直接从阶段三开始。 功能ID **沿用该 PRD 追溯头里的 `功能ID`**，不另分配（PRD 没有追溯头时才按下文分配新 ID）

5. **按已有功能ID续跑**：输入是功能ID（`F<日期>-<时分秒>`）且 `docs/.pdlc-state/<功能ID>.json` 存在 → 读它的 `current_stage` / `next_step`， **从下一个未完成的阶段继续**（`requirements` 完成 → 阶段二，但 `next_step` 是 `pdlc-tdd`（轻量模式）→ 阶段三；`design` → 阶段三；`tdd` → 阶段四；`impl` → 阶段五；`review` 且 `next_step=pdlc-ship` → 已走完，只出最终报告）。 上次停在阻塞（`last_phase_result.ok=false`）时，先读 `blocked_reason`：原因已消除才继续，否则报告原因后停止

<!-- @include templates/prompts/clarify.md（已内联于下方，无需另读） -->

需求澄清（文字输入时，写 PRD 之前执行）

只对**文字输入**生效。输入是文件、已有 PRD 或功能ID 时跳过本节——已有文档按原文结构化，不再追问。

参数里的 `--autonomous` 是开关，不是需求的一部分：先把它剥掉，剩下的才是需求描述。

1. 对照清单打勾

逐项判断用户的描述里**有没有明说**——看的是「写了没有」，不是「能不能猜出来」：

| 项 | 算「明说」的样子 | |---|---| | 给谁用 | 点出了用户角色或使用场景 | | 要做什么 | 点出了具体行为，不只是一个名词（「登录」不算，「用手机号收验证码登录」算） | | 明确不做什么 | 划了边界 | | 怎样算做完 | 给了可观察的结果或验收口径 | | 有什么限制 | 技术栈、兼容、性能、时间等约束 |

**缺 3 项及以上 = 描述太单薄**，按下面第 2 或第 3 步处理；缺得更少就不问，直接写 PRD（缺的项按推断补，照常写进 PRD）。

2. 交互模式：问一轮

• 只问缺的项，**一次最多 3 个**，按「要做什么 → 怎样算做完 → 给谁用 → 明确不做什么 → 有什么限制」的先后挑
• 每个问题后面附上你推断的默认答案，用户回「按默认」或不答，就采纳默认
• **只问这一轮**：拿到回答就开始写，不追问第二轮
• 用户说「别问了 / 直接写」→ 全部按默认
• 问完仍是靠默认补上的项，写进 PRD「待确认问题」一节，状态标「待确认」

3. `--autonomous`：不问，把默认摆出来

• 不提问。缺的项按推断的默认写进 PRD
• PRD「待确认问题」一节逐条列出：缺的是哪一项、这次采用的默认、状态「待确认」
• 状态机本次 history 条目的 `auto_decisions[]` 每项追加一条：`{ "point": "需求澄清：<项>", "chose": "<采用的默认>", "at": "<ISO 8601>" }`

——推进时给状态推进脚本传 `--decision "需求澄清：<项>=<采用的默认>"`，每项一个

• 交接时把这几条列给人看
• **连「要做什么」都没有**（只有一个名词或一句口号）→ 这不是能安全默认的缺口：不分配功能ID、不写任何文件，

末行输出哨兵 `<<<PDLC blocked reason="需求描述没有说要做什么">>>` 后结束，交还人类 <!-- @include-end templates/prompts/clarify.md -->

执行规则

• **全程自动**：开工前的需求澄清之后，不在任何阶段暂停等待确认，遇到歧义自行做合理假设并在最终报告中说明
• **严格顺序**：必须按阶段一→二→三→四→五→六顺序执行，不得跳过（`--lite` 按下文「轻量模式」跳过的阶段除外）
• **文档先行**：每阶段先产出文档，再进入下一阶段
• **TDD 强制**：代码实现前测试必须已存在且处于失败状态
• **自查通过才结束**：所有测试通过、评审记录完成后才输出最终报告
• **自检只做一轮**：各阶段的质量关卡与评审都受下面的防循环规则约束
• **功能ID贯穿全程**：阶段一分配功能ID后，所有后续文档和产出物统一使用该ID
• **逐阶段写状态机**（中途失败也能续跑，`/pdlc-retro` 也看得到每个阶段）：每个阶段收尾各写一次，规则见文末「状态机更新」。

每个阶段收尾运行一次 `bash scripts/pdlc-advance.sh <功能ID> --stage <下表短名> --next <下表下一跳> --produced <本阶段产物> <项目根>` （阶段一新建状态文件时加 `--name <功能名>`；`--autonomous` 照传）。检查由脚本按阶段自己跑，不手写 `checks`：

| 阶段 | `--stage` | `--next` | 脚本跑的检查 | |---|---|---|---| | 一（PRD + 任务拆解 + PRD 评审）完成时**创建**状态文件 | `requirements` | `pdlc-design` | 不跑（`{}`） | | 二（技术设计） | `design` | `pdlc-tdd` | 不跑（`{}`） | | 三（TDD 红灯） | `tdd` | `pdlc-implement` | 红灯验证；`--produced` 要列出写的测试文件，脚本记下指纹 | | 四（编码实现） | `impl` | `pdlc-review` | unit、coverage、lint；tdd 写的测试被改过就不推进 | | 五（自查评审） | `review` | `pdlc-ship` | unit、coverage、lint、e2e |

脚本退出码 `3` = 没推进（检查没过 / 主动 block）：停在这里，不往下一阶段走。 某阶段失败或卡在需人判断的点（后者传 `--blocked "<原因>"`）→ 状态停在上一阶段，最终报告说明可用 `/pdlc-feature <功能ID>` 续跑。 旧版本只在最后写一条 `stage: feature`，读侧仍认这个短名，但本版起不再写它

阶段派发：每个阶段一个全新子代理

有子代理工具（Claude Code 的 Task / Agent）时，**阶段二～五各交给一个全新的子代理执行**，主会话只做编排与核对。 为什么：子代理只看得到磁盘上的文档和代码，看不到前一阶段的推理过程——写实现的子代理只能对着测试和设计干活， 不会顺着「写测试时怎么想的」去迁就；主会话的上下文也不会随阶段一路膨胀。

• **主会话自己做**：输入解析、需求澄清（要问人）、功能ID分配、阶段一（PRD + 任务拆解 + PRD 评审，并创建状态文件）、阶段六最终报告
• **派给子代理**：阶段二、三、四、五，**一个接一个**（不并行，后一阶段要读前一阶段的产物）；`--lite` 跳过的阶段照样不派
• **每次都是全新的子代理**（general-purpose），不复用上一个阶段的那个
• **没有子代理工具**（其它平台，或工具被禁用）→ 主会话按下文各阶段依次执行；最终报告标题下的「阶段执行方式」一行写「各阶段未隔离执行（没有子代理工具）」

派发时把下面的提示词填好交给子代理（尖括号都换成实际值；路径一律写绝对路径）：

你在执行 PDLC /pdlc-feature 的「阶段<N>：<阶段名>」。功能ID <功能ID>，项目根 <项目根绝对路径>，轻量模式：<是 | 否>。
产出语言：<主会话判定的语言>（你看不到用户的对话，按这里写）。
1. 读 <本 skill 基础目录>/SKILL.md：通读「执行规则」「防循环规则」「测试代码在哪」「状态机更新」，
   然后只执行「阶段<N>」一节及其质量关卡，不做别的阶段。
2. 需求和上游产物只从磁盘读：状态文件 <项目根>/docs/.pdlc-state/<功能ID>.json，以及其中 history[].produced 列出的文件。
3. 收尾运行 bash <本 skill 基础目录>/scripts/pdlc-advance.sh <功能ID> --stage <短名> --next <下一跳> --produced <本阶段产物> <项目根>
   <主会话带了 --autonomous 就加上 --autonomous>。脚本退出码 3 = 没推进：停下，不要自己补救到下一阶段。
4. 你不能和用户对话：遇到必须由人判断的点，带 --blocked "<原因>" 运行上面的脚本后结束。
5. 结束时用不超过 15 行回报：产物路径、脚本最后输出的那行 JSON、自行做出的假设。

**子代理回来后，主会话自己读状态文件核对，不信子代理的文字**：`last_phase_result.stage` 是本阶段短名、`last_phase_result.ok` 为 `true`、 `current_stage` 等于本阶段短名，三条都满足才派下一个阶段。

• **不满足** → 停在这里：最终报告写明停在哪个阶段、`blocked_reason` 是什么，提示用 `/pdlc-feature <功能ID>` 续跑（续跑同样按本节派发）
• **子代理本身出错**（工具报错、没有回报、状态文件没被写）→ 重派一次全新的子代理；还不行就按上一条停下。

**不要在主会话里替它把这一阶