/pdlc-prd

name: pdlc-prd
description: 创建 PRD 文档（自动化生成 + 自检 + handoff）
argument-hint: "<功能描述 | 已有需求文档路径> [--autonomous]"
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
layer: 2
stage: requirements
produces:
  - docs/01_requirements/prd/<feature-id>-<feature-name>-prd.md
requires: []
next_step: pdlc-design
terminal_state: prd_done

创建 PRD 文档

根据用户提供的需求描述或已有需求文档，在 `docs/01_requirements/prd/` 目录下创建一份完整的 PRD（产品需求文档）。

<!-- @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 -->

段一：生成 PRD

1.1 输入解析（必须执行）

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

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

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

2. **文件输入处理**：

• 读取文件内容（支持 Markdown、纯文本、PDF）
• 若为飞书文档链接，通过飞书 API 获取
• 从内容提取：功能名称、范围、用户故事、验收标准
• **保留原文档核心内容**，仅补充和结构化，不重写
• 在 PRD 中添加：`<!-- 来源文档: <原始路径> -->`

3. **文本输入处理**：先按下文「需求澄清」对照清单，描述太单薄时问一轮（`--autonomous` 下不问、把默认列进「待确认问题」），再推断功能需求

> **核心原则**：文件输入是「基于已有内容结构化」，文本输入是「从零生成」。

<!-- @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 -->

1.2 功能ID分配

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

功能ID分配（必须执行）

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

**为什么用时分秒而非序号**：多人 / 多 AI 并行开发时，各自独立取「当日序号 max+1」会分到相同编号，合并时状态机文件同名冲突、只能手工重编号。改用创建时刻的 `HHMMSS`：各副本零协调也几乎不撞（仅同一秒创建才可能），合并时文件名互异、git 自动合并。旧的 `F<日期>-<NN>`（2 位序号）ID 仍然有效、可解析。

**注意**：日期与时分秒使用执行时的实际值，**严禁**复制示例值。 <!-- @include-end templates/prompts/feature-id.md -->

1.3 生成 PRD 文档

1. 阅读 本 skill 目录下的 `assets/prd-template.md` 获取模板格式 2. 阅读 `docs/00_standards/coding/` 获取编码规范（若存在；**查找未命中 → 在报告里提示 `consider /pdlc-standard add coding/<topic>`**） 3. 文件名格式：`<功能ID>-<功能名>-prd.md` 4. 文档顶部加 PDLC 追溯头：

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

PDLC 追溯头（文档顶部必须包含）

每个带编号的文档必须以下列注释开头：

<!-- PDLC-TRACE -->
<!-- 功能ID: <F/B 开头的 ID> -->
<!-- 功能名称: <kebab-case 名> -->
<!-- 阶段: <requirements | design | tdd | impl | review | e2e | ship | deploy | retro> -->
<!-- 前置文档: <上一阶段文档路径 | 无> -->
<!-- 创建时间: <执行时的实际 ISO 8601 时间戳> -->
<!-- 关系: <type=id; ... | 整行省略> -->

**严禁**把占位符（`<...>`）或示例日期原样写入实际文档。必须用真实值替换。

**关系行（RFC#6，可选）**：表达 feature 间关系链。无关系时**整行省略**（保持旧文档有效）。语法 `type=id` 对，多 id 用 `,` 分隔、多对用 `; ` 分隔，例：`<!-- 关系: extends=F20260510-100000; depends_on=F20260501-090000 -->`。6 种类型：`extends` / `depends_on` / `supersedes` / `resolves`（有向）与 `conflicts_with` / `relates_to`（对称）。 <!-- @include-end templates/prompts/pdlc-trace.md -->

5. 文档必须包含：背景与目标、目标用户、功能需求（含优先级）、非功能需求、验收标准 <!-- @include templates/prompts/output-language.md（已内联于下方，无需另读） --> 🌐 **Output language for generated artifacts**

All generated artifacts (PRDs, design docs, code comments, review reports, test plans, deployment manuals, changelog entries, etc.) follow this policy:

1. **Default — match the conversation language exactly**:

• 用户用中文与 Claude 对话 → 产中文文档、中文代码注释、中文报告
• User talks to Claude in English → produce English artifacts
• User talks in another language → produce artifacts in that language
• **Never silently default to a fixed language regardless of the user's input.**

2. **Explicit override always wins**: when the user specifies a language for an artifact (e.g. "write the PRD in English", "用英文写 API 设计文档", "output the deploy doc in Japanese"), use that language for that artifact, regardless of conversation language.

3. **Mixed-language requirements**: if the user wants some artifacts in one language and others in a different language (common: Chinese PRD + English API docs for partners), honour each per-artifact instruction.

4. **Uncertain**: if you cannot reliably detect the conversation language, ask once before producing the first artifact.

This policy applies to **content** (prose, comments, headings). It does **not** override technical conventions like English variable names, English git commit subjects, or English error codes when the project's conventions require them. <!-- @include-end templates/prompts/output-language.md --> 7. 用户故事使