/pdlc-design

name: pdlc-design
description: 创建技术设计文档（自动生成 + 自检 + handoff）
argument-hint: "<功能ID | 功能描述> [--autonomous]"
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
layer: 2
stage: design
produces:
  - docs/02_design/<subsystem>/<feature-id>-design.md
requires:
  - docs/01_requirements/prd/
next_step: pdlc-tdd
terminal_state: design_done

创建设计文档

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

根据已有的需求文档，在 `docs/02_design/` 对应子目录下创建技术设计文档。

输入解析

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

• **文件路径**（以 `/`、`./` 开头，或以 `.md`、`.txt`、`.pdf` 结尾，或实际存在的文件）：直接读取该文件作为需求来源，跳过 PRD 搜索
• **功能ID**（`F<日期>-<时分秒>`，`/pdlc-prd` 交接时给的就是它）或**功能名关键词**：按下方守卫找 PRD

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

定位上游产物：先查状态机，再按关键词搜

守卫要找的上游文档（PRD、设计文档、评审记录等），按下面的顺序定位，**命中即停**：

1. **输入是功能ID / 缺陷ID**（`F…` / `B…`）且 `docs/.pdlc-state/<ID>.json` 存在 → 读它 `history[].produced` 里记下的路径，取所需类型的文档。这是上游阶段亲手记的，最可靠 2. **没有状态机、或 `produced` 里没有所需文档** → 在对应目录下搜：文件名含该 ID 或功能名关键词，或文件顶部 PDLC 追溯头的 `功能ID` 等于该 ID 3. **命中多份** → 不要随手挑一份：交互模式下列出来请人选；`--autonomous` 下优先取文件名含该 ID 的，仍不止一份则按「真需人判断」阻塞（写 `blocked_reason`，列出候选）

找到后从文件名或追溯头取功能ID，后续产出一律沿用它，**不另分配新 ID**。 <!-- @include-end templates/prompts/artifact-lookup.md -->

PDLC 前置检查（必须执行，不可跳过）

1. 若输入为文件路径，直接读取文件内容作为需求，提取功能名和功能ID（如有），跳到步骤 4 2. 按上面的顺序在 `docs/01_requirements/prd/` 下找本功能的 PRD 3. **未找到** → 输出以下信息后**立即停止，不继续执行**：

   ⛔ PDLC 守卫：未找到与「<功能名>」相关的 PRD 文档。
   设计文档必须基于已有的 PRD。请先运行：
   👉 /pdlc-prd <需求描述>

4. **找到** → 提取功能ID（如 `F20260326-090000`），读取该 PRD 内容，继续执行

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

方案比较（写设计文档之前）

先判断这次设计有没有**值得比较的技术取舍**——存储怎么选、同步还是异步、新建服务还是扩展现有模块、接口怎么切、数据模型拆不拆等。

• **没有**（沿用项目里已有的做法、PRD 也没留可争的点）→ 不比较，在设计文档开头写一句「沿用 <既有做法>，没有值得比较的取舍」，直接写设计。**不要为了凑数编出几个明显不会选的方案**
• **有** → 列 2～3 个候选，用一张表比较，然后给出推荐：

| 方案 | 做法（一句话） | 改动面 | 主要风险 | 对 PRD 验收标准 / 非功能需求 | 与现有代码和规范的契合 | |---|---|---|---|---|---|

推荐写明理由，理由要落到 PRD 条目或项目规范上，不写「更优雅」「更灵活」这类说不出依据的话。

**谁来选**：

• **交互模式**：把表和推荐给人看，问一次选哪个（只问这一轮），人选定后再写设计
• **问不了人**（参数带 `--autonomous`，或在 `/pdlc-feature` 里——开工后不再提问，阶段二还可能跑在子代理里）→ 选推荐的方案，推进状态时传

`--decision "设计方案=<方案名>（<一句理由>）"`；候选之间的差别取决于 PRD 没交代的业务取舍（比如成本和一致性二选一）时，也照推荐选， 但把这个假设写进设计文档的「方案比较」节，让人在评审时看得到

**落盘**：设计文档开头加「方案比较」一节——比较表、选定的方案、怎么选的（人选 / 按推荐自动选）；没比较的就是上面那一句。 后面的接口、表结构、架构都按选定的方案写，不要在正文里又混进落选方案的做法。 <!-- @include-end templates/prompts/design-options.md -->

输出位置

• API 设计 → `docs/02_design/api/`
• 架构设计 → `docs/02_design/architecture/`
• 数据库设计 → `docs/02_design/database/`

要求

1. 先阅读找到的 PRD 文档，全面理解需求 2. 参考 本 skill 目录下的 `assets/api-design-template.md` 获取 API 设计模板格式 3. 参考 `docs/00_standards/` 目录了解项目规范（未命中 → 提示 `consider /pdlc-standard add <category>/<topic>`） 4. **文件名格式**: `<功能ID>-<功能名>-<类型>.md`（如 `F20260326-090000-user-auth-api.md`），类型可以是 api / arch / db

• 若 PRD 为旧格式无功能ID，则使用旧格式 `YYYYMMDD-<功能名>-<类型>.md`

5. **文档顶部必须包含 PDLC 追溯头**：

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

<!-- @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. 必须包含：概述、接口/架构/表结构定义、错误码/异常处理、数据模型 8. API 设计需遵循 RESTful 规范，统一响应格式 `{ code, message, data }` 9. **设计文档自审与自动修复**（每份设计文档创建后立即执行，不可跳过）：

• 重新阅读刚创建的设计文档，对照 PRD 逐项检查以下质量门禁：

**方案比较检查**：

• [ ] 文档开头有「方案比较」节：比较表 + 选定方案 + 怎么选的；或一句「沿用 <既有做法>，没有值得比较的取舍」
• [ ] 正文按选定方案写，没有混进落选方案的做法

**PRD 一致性检查**：

• [ ] PRD 中每条 P0/P1 功能是否都有对应的设计覆盖（接口/表结构/架构组件）
• [ ] 接口的入参/出参是否与 PRD 描述的功能行为一致
• [ ] 错误码是否覆盖了 PRD 中列出的异常场景

**API 设计检查**（如有 API 文档）：

• [ ] 接口 URL 命名是否遵循 RESTful 规范（名词复数、层级清晰）
• [ ] 请求/响应结构是否完整（无缺失字段）
• [ ] 统一响应格式 `{ code, message, data }` 是否一致执行
• [ ] 分页接口是否有 page/pageSize/total 参数
• [ ] 鉴权方式是否明确说明

**数据库设计检查**（如有 DB 文档）：

• [ ] 每张表是否有主键定义
• [ ] 外键关系是否与 ER 图一致
• [ ] 常用查询字段是否有索引设计
• [ ] 是否有 `created_at`、`updated_at` 等审计字段
• [ ] 迁移 DDL 是否完整可执行

**跨文档一致性检查**（如同时有 API