创建部署文档

<!-- @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 --> <!-- @include templates/prompts/noninteractive.md（已内联于下方，无需另读） -->

非交互模式（--autonomous）

若本命令的参数含 --autonomous，本命令进入无人值守模式，按以下规则处理原本需要人应答的交互点。参数是唯一真源：不带 --autonomous 即为交互模式，一切照旧正常询问用户；绝不回读状态机 run_mode 兜底（「掉出 autonomous」是安全的失败方向）。

1. 流程性确认（如「测试已绿是否继续」「是否覆盖已有文件」）→ 不询问，按预设默认前进，并把决策追加到状态机 history[].auto_decisions[]

（写状态机的命令：推进时给状态推进脚本传 --decision "<确认点描述>=<所选默认>"，可重复；脚本写成下面的样子）：

   { "point": "<确认点描述>", "chose": "<所选默认>", "at": "<ISO 8601>" }

1. 真需人判断（PRD 关键取舍、评审「需人工确认」项、真实循环依赖、测试与设计 / PRD 矛盾等无法安全默认的点）→ 不猜。

改测试、改检查命令让它变绿，永远不是「流程性默认」，不能记成 --decision：

• current_stage 保持不变（不推进）
• 写 last_phase_result.ok = false 且 blocked_reason = "<原因>"（写状态机的命令：给状态推进脚本传 --blocked "<原因>"）
• 末行输出哨兵：<<<PDLC blocked reason="<原因>">>>
• 立即结束命令，交还人类
• 守卫拦截也走这一条：前置守卫（缺设计文档、缺测试、测试没红等）在 --autonomous 下拦住本命令时，

不能只输出 ⛔ 就停——同样写 ok=false + blocked_reason（写明哪条守卫、缺什么）并输出哨兵。 否则状态机里仍是上一阶段的 ok=true，循环驱动只看到 current_stage 没动，会把「被拦」误报成「卡住」，真实原因丢失。

1. 破坏性操作（发布 / 部署 / 打 tag / 触发 CI / DROP / force-push 等不可逆·外发操作）→ --autonomous 无效，仍必须人工显式确认。
2. 顺手的 sidecar 产物（如缺失时创建 CHANGELOG.md、补全文档 PDLC-TRACE 的创建时间等本阶段职责内、可安全默认的辅助改动）→ 视为流程性默认，直接做并记入 `auto_decisions[]`；这类改动不新增外部副作用，不属破坏性操作。

进入 autonomous 模式时，在状态机顶层写 run_mode: "autonomous" 仅供留痕（复盘区分人工 vs 循环产出）。

<!-- @include-end templates/prompts/noninteractive.md -->

⛔ 部署面向生产、不可逆·外发：真实执行部署属破坏性范畴。`--autonomous` 对涉及真实部署动作的环节无效——仍必须人工显式确认。本命令默认只产出部署文档，不代表授权自动上线。

为一次发布、指定服务或应用创建部署手册。

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

先按输入形态确定本次部署涉及的功能：

• 版本号（v1.2.0 / 1.2.0，/pdlc-ship 交接时给的就是它）→ 发布级部署：读 CHANGELOG.md 里 ## [<版本>] 段，

收集其中的功能 / 缺陷 ID（F… / B…）；这些就是本次部署涉及的功能。 段落不存在 → 停止并提示先跑 /pdlc-ship。段落里一个 ID 都没有（如只发了文档 / 依赖升级）→ 照常出发布级文档，跳过下面的评审记录查找

• 功能ID（F… / B…）→ 单个功能
• 服务名 / 应用名 / 关键词 → 按下面第 2 步搜评审记录

对上面确定的每个功能（或关键词）做评审记录检查：

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

1. 从用户输入中提取服务/功能名称关键词（输入已是版本号或功能ID时，用上面确定的功能ID）
2. 按下面「定位上游产物」的顺序找 docs/07_reviews/code/ 下的评审记录（有功能ID时先看状态机里 review 阶段记下的 produced）
3. 未找到评审记录 → 输出以下信息后立即停止，不继续执行：

   ⛔ PDLC 守卫：未找到与「<功能名>」相关的评审记录。
   部署文档必须基于已完成评审的代码。请先运行：
   👉 /pdlc-review <评审目标>

1. 找到 → 提取功能ID（如 F20260326-090000），读取评审记录内容，继续执行。

发布级部署时逐个功能检查，缺评审记录的功能列在停止信息里一并指出

工作流程

1. 阅读目标服务/应用的 README.md 和技术栈信息
2. 阅读 docs/02_design/architecture/ 下的架构设计文档（如有）
3. 阅读评审记录，确认功能状态
4. 【必须创建文件】 在 docs/05_deployment/guides/ 下创建部署手册

• 使用模板: 本 skill 目录下的 assets/deploy-doc-template.md（结构完整、章节齐全）
• 文件名格式：
• 发布级部署：v<版本>-deploy.md（如 v1.2.0-deploy.md）——一份文档覆盖本次发布的全部功能，

各功能涉及的配置 / 迁移 / 回滚要点在文档里分节写明

• 单个功能：<功能ID>-<功能名>-deploy.md（如 F20260326-090000-user-auth-deploy.md）
• 若无功能ID，则使用旧格式 YYYYMMDD-<服务名>-deploy.md
• 文档顶部必须包含 PDLC 追溯头（发布级部署的 功能ID 与 前置文档 列出全部，逗号分隔，并加一行 版本）：

     <!-- PDLC-TRACE -->
     <!-- 功能ID: F20260326-090000 -->
     <!-- 功能名称: user-auth -->
     <!-- 阶段: 部署 -->
     <!-- 前置文档: docs/07_reviews/code/F20260326-090000-user-auth-review.md -->

发布级示例：<!-- 功能ID: F20260326-090000, B20260328-140000 -->、<!-- 版本: v1.2.0 -->

文档内容

• 前置条件（环境要求、依赖服务）
• 环境配置（环境变量、配置文件）
• 构建步骤
• 部署步骤
• 健康检查验证
• 回滚方案
• 常见问题排查

部署文档自审与自动修复（创建后立即执行，不可跳过）

重新阅读刚创建的部署文档，逐项检查以下质量门禁：

关键章节检查

• [ ] 前置条件：是否列出了所有运行时依赖（数据库版本、中间件版本、系统配置）
• [ ] 环境变量：是否列出了每个环境变量的名称、用途、示例值、是否必填
• [ ] 构建步骤：是否可直接复制执行，无需额外推断
• [ ] 部署步骤：是否区分了首次部署与升级部署
• [ ] 健康检查：是否定义了健康检查 URL、预期响应、超时时间
• [ ] 回滚方案：是否有明确的回滚步骤（不是简单写「回滚到上一版本」）
• [ ] 数据库迁移：如涉及 DB 变更，是否有迁移执行和回滚步骤
• [ ] 常见问题排查：是否有至少 3 个常见错误场景及解决方案

可执行性检查

• [ ] 所有命令是否完整可复制（无省略号 ...、无占位符未说明）
• [ ] 端口号、域名、路径是否使用了变量或占位符并在前置条件中说明
• [ ] 步骤顺序是否合理（不会因顺序错误导致部署失败）

自动修复

• 缺失的健康检查：根据服务类型（HTTP/gRPC）自动补充标准健康检查配置
• 缺失的回滚方案：自动补充基于版本的回滚步骤模板
• 缺失的环境变量说明：从代码中扫描 process.env/os.Getenv/System.getenv 等，自动补充
• 模糊的操作步骤：改写为具体命令
• 缺失的常见问题：自动补充 3 个通用排查项（端口占用、权限不足、依赖不可达）
• 修复后在文档末尾追加审查记录：

  ## 自审记录
  - 审查时间：<ISO 8601>
  - 发现问题：X 项
  - 自动修复：X 项
  - 修复明细：
    - [已修复] <问题描述>

要求

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

1. 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.

1. 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.

1. 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 -->

• 步骤要具体可执行，不要模糊描述
• 包含回滚方案
• 如需 Docker 部署，同时生成 Dockerfile 和 docker-compose.yml

目标: $ARGUMENTS

段四：更新状态机 + 交接

<!-- pdlc:meta 由 frontmatter 生成（adapters/sync_skills.py），勿手改 -->

本命令的状态机取值：阶段短名 deploy（写进 history[].stage 与 last_phase_result.stage）；下一跳 null（流程到此结束：next_step 写 null）。

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

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

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

用脚本推进，不要手写状态 JSON

bash scripts/pdlc-advance.sh <功能ID> --stage <本阶段短名> --next <下一跳命令名|null> \
  [--produced <产物路径，逗号分隔>] [--autonomous] [--decision "<确认点>=<所选默认>"]... \
  [--name <kebab-case>（状态文件还不存在时）] <项目根>

• 脚本是本 skill 自带的 scripts/pdlc-advance.sh。阶段短名与下一跳就是本命令正文里「本命令的状态机取值」那两个值；带了 --autonomous 就照传
• 检查由脚本自己跑：它按阶段调用同目录的 scripts/pdlc-checks.sh（tdd 验红灯；impl / fix / refactor 跑 unit、coverage、lint；

review 再加 e2e；e2e 只跑 e2e；文档类阶段不跑），据此判 ok、整段写入 history 与 last_phase_result， 写完调用 scripts/pdlc-state-lint.sh 体检。不要自己先写 checks，也不要挑检查项

• tdd 阶段的 --produced 必须列出写的测试文件：脚本记下它们的指纹，之后 impl / refactor / review 推进时比对
• 主动交还人类（命中人工点、评审有阻塞项、测试本身有矛盾等）→ 加 --blocked "<原因>"：脚本照跑检查、如实记录，但不推进，原因写进 blocked_reason
• /pdlc-ship 写 ship_done、/pdlc-deploy 写 deploy_done → 加 --done（只有这两个命令能用）

脚本的退出码决定怎么收尾：

退出码 3 且原因是「tdd 阶段写的测试被改动」：实现阶段不改测试。测试是否真的写错了（与设计 / PRD 矛盾），只有人能判断： - 交互模式：先把矛盾讲清楚、问人；人同意后再带 --tests-changed "<理由>" 重跑，理由记进 auto_decisions - --autonomous：没有人可问，不要改测试，带 --blocked "<矛盾在哪>" 收尾。自主模式下带 --tests-changed 脚本也不推进

>

项目开了 PDLC 护栏（docs/00_standards/pdlc-hooks.yml）时，用 Write / Edit 直接写状态文件会被拦下。

状态文件格式（读状态时参考；只有脚本跑不了时才照它手写）

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

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

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

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

>

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

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

>

- 「评审通过、等待发布」就是 current_stage 为 review 且 next_step 为 pdlc-ship（/pdlc-e2e 在评审之前，它的下一跳是 pdlc-review）。 循环相关文档里说的 review_done 指的就是这个状态，不是要写进 current_stage 的值。 - 为什么：读侧判「已抵达终态」只看 current_stage 是否以 _done 结尾。评审通过就写 _done， /pdlc-ship 就分不清哪些功能已经发布过，发布说明会重复或漏收。 - 旧版本写入的 feature_done / fix_done / review_done 分不清是否已发布，/pdlc-ship 会列出来请人确认。

手写回退（仅脚本退出码 2 且无法修正时）

1. 文件不存在 → 创建文件，写入初始结构（history 为含当前阶段的数组）
2. 文件存在 → 读取 JSON，追加当前阶段到 history，更新 current_stage 和 next_step
3. 写回文件：用 jq 或等效工具保持格式化
4. 写完体检：运行 bash scripts/pdlc-state-lint.sh <项目根>，属于本功能状态文件的偏差当场改正。退出码 2（缺 jq 等）= 没体检，报告里写明「未体检」，不得当作通过。

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

last_phase_result（机器可读阶段结果；脚本按下面的规则写，手写回退时照做）

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

1. `checks` 只放真跑命令的退出码结果（scripts/pdlc-checks.sh 的 stdout 原样），键名只能是 tests_pass / coverage_pass /

lint_clean / e2e_pass（tdd 段 red_verified），值只能是布尔或 null（无法判定）。不照抄 test-commands.yml 的 unit / lint， 不写 "4 passed, 1 failed" 这类摘要。没有检查可跑的阶段（文档类阶段、项目无 test-commands.yml）→ checks: {}， 绝不因为「本阶段成功」就填 true——schema 示例里 checks 是空的，正是这个意思。

1. `self_audit` 单列：只放自检未通过数，仅供参考，不作循环判停依据。
2. `ok` 的定义：没有命中 blocked_reason，且 tdd 段 red_verified 为 true、其它阶段没有任何检查为 false（null 不拦）→ true；否则 false。
3. 命名空间：advanced_to = 下一阶段的短名，不是命令名、也不是本阶段的 `current_stage`。三者关系：stage=本阶段短名、current_stage=本阶段完成后的当前短名、advanced_to=下一阶段短名、next_step=下一跳命令名。

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

<!-- stage-map:start -->

<!-- stage-map:end -->

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

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

>

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

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

<!-- @include-end templates/prompts/state-update.md -->

本阶段状态机更新：只对本次部署涉及、且当前已是 ship_done 的功能，各运行一次 bash scripts/pdlc-advance.sh <功能ID> --stage deploy --next null --done --produced <部署文档> <项目根>：脚本追加 deploy 到 history，写 current_stage: deploy_done、next_step: null。

• 涉及但还不是 ship_done 的功能（未发布，或旧版终态写法）→ 不改它的状态机，在交接里逐个列出，提示先走 /pdlc-ship
• 没有状态机文件的功能（按服务名部署的旧流程）→ 不新建状态机

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

段四：交接（Handoff）

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

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

规则：

• 主流程命令（写状态机的命令；下一跳见正文里「本命令的状态机取值」）必须显式输出"下一步"，不可省略
• 工具型命令（Layer 3）可以没有 next_step，此时输出 👉 下一步：（本次流程结束，无后续）
• 分叉场景必须说明选择条件，例如"若需补充测试用例 → /pdlc-tdd；若测试已齐 → /pdlc-review"

<!-- @include-end templates/prompts/handoff.md -->