{"slug":"pdlc-design","title":"pdlc-design","summary":"创建技术设计文档（自动生成 + 自检 + handoff）","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-23T18:54:22.998187Z","repo":{"url":"https://github.com/kanfu-panda/pdlc-skills","stars":15,"forks":2,"license":"MIT","updatedAt":"2026-09-23T15:59:31Z"},"bodyHtml":"
\n

name: pdlc-design\ndescription: 创建技术设计文档（自动生成 + 自检 + handoff）\nargument-hint: <功能ID | 功能描述>\nallowed-tools: Read, Write, Edit, Glob, Grep, Bash\nlayer: 2\nstage: design\nproduces:

\n\n
\n

创建设计文档

\n\n

⛔ IRON LAW · 不可违反的硬门禁

\n

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

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

违反任一条 = 立即中止当前命令，输出违规详情，等待人工介入。

\n\n

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

\n

输入解析

\n

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

\n\n

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

\n
    \n
  1. 若输入为文件路径，直接读取文件内容作为需求，提取功能名和功能ID（如有），跳到步骤 4
    2. \n
  2. 从用户输入中提取功能名称关键词
    3. \n
  3. 在 docs/01_requirements/prd/ 目录下搜索包含该关键词的 PRD 文档\n\n
    4. \n
  4. 未找到 → 输出以下信息后立即停止，不继续执行：\n
    ⛔ PDLC 守卫：未找到与「<功能名>」相关的 PRD 文档。\n设计文档必须基于已有的 PRD。请先运行：\n\uD83D\uDC49 /pdlc-prd <需求描述>\n
    \n
    5. \n
  5. 找到 → 提取功能ID（如 F20260326-090000），读取该 PRD 内容，继续执行
    6. \n
\n

输出位置

\n\n

要求

\n
    \n
  1. 先阅读找到的 PRD 文档，全面理解需求
    2. \n
  2. 参考 本 skill 目录下的 assets/api-design-template.md 获取 API 设计模板格式
    3. \n
  3. 参考 docs/00_standards/ 目录了解项目规范（未命中 → 提示 consider /pdlc-standard add <category>/<topic>）
    4. \n
  4. 文件名格式: <功能ID>-<功能名>-<类型>.md（如 F20260326-090000-user-auth-api.md），类型可以是 api / arch / db\n\n
    5. \n
  5. 文档顶部必须包含 PDLC 追溯头：\n
    <!-- PDLC-TRACE -->\n<!-- 功能ID: F20260326-090000 -->\n<!-- 功能名称: user-auth -->\n<!-- 阶段: 设计 -->\n<!-- 前置文档: docs/01_requirements/prd/F20260326-090000-user-auth-prd.md -->\n
    \n
    6. \n
\n\n

\uD83C\uDF10 Output language for generated artifacts

\n

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

\n
    \n

  1. Default — match the conversation language exactly:

    \n\n
    2. \n

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

    \n
    3. \n

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

    \n
    4. \n

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

    \n
    5. \n
\n

This policy applies to content (prose, comments, headings). It does\nnot override technical conventions like English variable names, English\ngit commit subjects, or English error codes when the project's conventions\nrequire them.

\n\n
    \n

  1. 必须包含：概述、接口/架构/表结构定义、错误码/异常处理、数据模型

    \n
    2. \n

  2. API 设计需遵循 RESTful 规范，统一响应格式 { code, message, data }

    \n
    3. \n

  3. 设计文档自审与自动修复（每份设计文档创建后立即执行，不可跳过）：

    \n\n

    PRD 一致性检查：

    \n\n

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

    \n\n

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

    \n\n

    跨文档一致性检查（如同时有 API + DB 文档）：

    \n\n

    自动修复：

    \n\n
    4. \n

  4. 创建完成后，提示用户下一步是编写测试用例（/pdlc-tdd <功能名>）

    \n
    5. \n
\n

设计目标: $ARGUMENTS

\n\n
\n

本命令的状态机取值：阶段短名 design（写进 history[].stage 与 last_phase_result.stage）；下一跳 pdlc-tdd（写进 next_step，交接时提示）。

\n
\n\n\n

状态机更新（段四必须执行）

\n

本命令完成主产出后，必须更新状态机文件 docs/.pdlc-state/<feature-id>.json。

\n

文件格式

\n
{\n  \"feature_id\": \"<F/B ID>\",\n  \"feature_name\": \"<kebab-case>\",\n  \"created_at\": \"<首次创建时间 ISO 8601>\",\n  \"current_stage\": \"<当前阶段名>\",\n  \"run_mode\": \"interactive | autonomous\",\n  \"history\": [\n    {\n      \"stage\": \"<阶段名>\",\n      \"done_at\": \"<ISO 8601>\",\n      \"produced\": [\"<相对路径 1>\", \"<相对路径 2>\"],\n      \"self_audit\": { \"passed\": <N>, \"failed\": <N>, \"manual\": <N> },\n      \"auto_decisions\": [\n        { \"point\": \"<autonomous 下自动前进的确认点>\", \"chose\": \"<所选默认>\", \"at\": \"<ISO 8601>\" }\n      ]\n    }\n  ],\n  \"last_phase_result\": {\n    \"stage\": \"<本次阶段名>\",\n    \"ok\": true,\n    \"advanced_to\": \"<推进到的下一阶段 | null>\",\n    \"checks\": {},\n    \"self_audit\": { \"failed\": 0 },\n    \"blocked_reason\": null,\n    \"run_mode\": \"interactive | autonomous\",\n    \"at\": \"<ISO 8601>\"\n  },\n  \"relations\": {\n    \"extends\": [],\n    \"depends_on\": [],\n    \"supersedes\": [],\n    \"resolves\": [],\n    \"conflicts_with\": [],\n    \"relates_to\": [],\n    \"_updated_at\": \"<ISO 8601 | 省略>\"\n  },\n  \"next_step\": \"<下一跳命令名，如 pdlc-design；若流程结束则为 null>\"\n}\n
\n
\n

⛔ 示例里的 \"checks\": {} 是「本阶段没有命令可跑」的样子，不是键名示范——键名与取值见下方 §1。

\n
\n
\n

relations 块（RFC#6，Phase 1 可选，Phase 2 推荐）：6 个 key 对应 6 种关系类型，各为 ID 数组，存出边。其中 conflicts_with / relates_to 是对称类型，两端都要写；其余四种有向，只写在源 feature 上。拿不准时用 /pdlc-relate set 写入，它会按规则校验。旧状态文件无此块时视为全空，向后兼容。入边由 /pdlc-relate rebuild 派生到 _relations.json，不在此块手维护。

\n
\n
\n

⛔ 写状态机的四条硬约束——读侧（/pdlc-status、/pdlc-retro、/pdlc-relate）会逐条体检，\n违反的每一处都会出现在它们输出的最前面：

\n
    \n
  1. 实例里不写 terminal_state。skill frontmatter 的 terminal_state: 是「这个命令走完后应到达的终态名」，\n不是状态字段。判终态只看 current_stage 是否以 _done 结尾。
    2. \n
  2. history[].stage 写本命令的阶段短名（见本命令正文里「本命令的状态机取值」）——pdlc-implement 写 impl，\n不写 implement / implementation；pdlc-prd 写 requirements，不写 prd。
    3. \n
  3. 时间戳必须带时刻：created_at / done_at / at 一律写完整 ISO 8601（如 2026-07-28T10:40:00+08:00）。\n只写日期，同一天内的阶段耗时就全部算成 0——读侧只能记「不可测」。
    4. \n
  4. next_step 只写命令名或 null，不附说明文字（如「pdlc-ship（等评审通过）」）。\n要说明原因，阻塞时写进 last_phase_result.blocked_reason。
    5. \n
\n
\n
\n

⛔ _done 的含义是「已发布」，只由 /pdlc-ship（写 ship_done）与 /pdlc-deploy（写 deploy_done）写入。\n其它命令的 current_stage 一律写本命令的阶段短名，走完整条链路的编排命令（/pdlc-feature）也一样——\n它收尾时 current_stage 是最后一个阶段的短名，next_step 是 pdlc-ship。

\n\n
\n

更新流程

\n
    \n
  1. 文件不存在 → 创建文件，写入初始结构（history 为含当前阶段的数组）
    2. \n
  2. 文件存在 → 读取 JSON，追加当前阶段到 history，更新 current_stage 和 next_step
    3. \n
  3. 写回文件：用 jq 或等效工具保持格式化
    4. \n
\n

⚠️ 若更新失败（文件损坏/权限问题），必须中止命令并在最终报告中报错。状态机不可跳过。

\n

last_phase_result（机器可读阶段结果，每个 phase 收尾必写）

\n

顶层 last_phase_result 是循环判停的唯一真源，外层只需 jq '.last_phase_result.ok' 即可决定 继续 / 停止 / 交还人类。规则：

\n
    \n

  1. checks 必须客观、真跑得来：只放真跑命令的退出码结果（命令取自 docs/00_standards/test-commands.yml，见 test-commands-template.yml），绝不用模型自评、绝不填占位。有测试的阶段用 tests_pass / coverage_pass / lint_clean（退出码 0 → true，非 0 → false）；stage 语义不同用对应键（如 tdd 段 { \"red_verified\": true } 表示红灯已验证）。

    \n
    \n

    ⛔ 键名与类型都是契约的一部分：键名只能是 tests_pass / coverage_pass /\nlint_clean / e2e_pass（tdd 段 red_verified），值只能是布尔。\n最常见的两种错法：① 照抄 test-commands.yml 的 unit / coverage / lint / e2e\n——那是命令表的字段名，不是状态机的（跑 unit 得到的结论写进 tests_pass）；\n② 写成 \"4 passed, 1 failed\" 这类字符串摘要。两种都会让 jq '.checks.tests_pass'\n读回 null，消费方（发布闸门、质量报告、自主循环）只看到「无法判定」——\n你诚实跑出来的结果等于没写。三态怎么分见本命令正文里「跑 check 命令：退出码的三态语义」一节；正文里没有这一节的命令不跑 check 命令，checks 写 {}。

    \n

    ⚠️ 没有检查命令可跑的阶段（如 requirements/design 只产文档，或项目无 test-commands.yml）→ checks: {} 留空。绝不因为「本阶段成功」就把 tests_pass/lint_clean 等填 true——那是虚报，会污染跨工具共用的状态机、误导自主循环判停。 上面 schema 示例里 checks 之所以是空的，正是这个原因——空是\"没跑\"的意思，不是键名的示范。

    \n
    \n
    2. \n

  2. self_audit 单列：只放自检未通过数，仅供参考，不作循环判停依据。

    \n
    3. \n

  3. ok 的定义：本阶段全部 checks 通过且未命中 blocked_reason → true；否则 false。

    \n
    4. \n

  4. 命名空间：advanced_to = 下一阶段的短名，不是命令名、也不是本阶段的 current_stage。三者关系：stage=本阶段短名、current_stage=本阶段完成后的当前短名、advanced_to=下一阶段短名、next_step=下一跳命令名。

    \n

    ⛔ 短名不是「命令名去掉 pdlc- 前缀」——pdlc-implement 的短名是 impl，不是 implement。别推导，查下表：

    \n
    5. \n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
next_step（下一跳命令名）advanced_to（下一阶段短名）
pdlc-tddtdd
pdlc-implementimpl
pdlc-reviewreview
pdlc-designdesign
pdlc-shipship
pdlc-deploydeploy
\n\n

next_step 为 null（终态或无后续）时 advanced_to 也是 null。

\n
\n

\uD83D\uDCCC 本表是唯一真源，且是被断言钉住的：每行的短名必须等于该 skill 自己 frontmatter\n里声明的 stage:，且任何 skill 的非 null next_step 都必须在表里有行——两个方向\n都由 tests/frontmatter-check.sh 检查，所以表不会和实现各自漂移。

\n

写错短名的后果与键名写错同类：消费方按契约名匹配，认不出就当没这个阶段。

\n
\n
    \n
  1. 推进一致：ok=true 时本阶段必须真的推进了 current_stage（与第 6 条 IRON LAW 呼应）；到达终态或无后续时 advanced_to=null。ok=false（含 blocked）时 current_stage 不变、advanced_to=null、blocked_reason 写明原因。
    2. \n
  2. run_mode：镜像本次调用是否带 --autonomous（带了写 autonomous，没带写 interactive）。
    3. \n
\n\n\n

段四：交接（Handoff）

\n

命令完成后必须输出以下格式的最终消息：

\n
✅ <阶段名> 完成：<主要产出物路径>\n\uD83D\uDCCA 自检：<通过数>/<总数> 通过（若有未通过，附要点）\n\uD83D\uDCE6 状态快照：docs/.pdlc-state/<feature-id>.json\n\uD83D\uDC49 下一步：/pdlc-<next_step>\n   （如果有分叉）或 /pdlc-<alt>（条件：<选择依据>）\n
\n

规则：

\n\n\n","files":[{"path":"assets/api-design-template.md","sizeBytes":10225,"isText":true},{"path":"SKILL.md","sizeBytes":17572,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-23T18:54:40.893639Z","sha256":"88E6DF220E834F2B9A60BE2BC419892829B24A31F1EB129B8EC20EFDAD7D6929","sizeBytes":11780},"review":null,"source":{"repositoryUrl":"https://github.com/kanfu-panda/pdlc-skills","path":"skills/pdlc-design","license":"MIT","commit":"3cd2f02ab45cb1cd48962e0f298ae4dad9fb442f","subtreeSha":"2184FE565B8818B66B26FE479F5B1EB5218AD3F0E43F79AB56EF0FD2F343CD44","lastSyncedAt":"2026-09-23T18:54:21.123477Z"},"reviewedAt":"2026-09-23T18:55:29.935784Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/kanfu-panda/pdlc-skills/tree/main/skills/pdlc-design"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install kanfu-panda-pdlc-skills@llmmart"},{"target":"git","command":"git clone https://github.com/kanfu-panda/pdlc-skills.git"}]}