pdlc-deploy

创建部署文档

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

2. 真需人判断（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 没动，会把「被拦」误报成「卡住」，真实原因丢失。
3. 破坏性操作（发布 / 部署 / 打 tag / 触发 CI / DROP / force-push 等不可逆·外发操作）→ --autonomous 无效，仍必须人工显式确认。
4. 顺手的 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 <评审目标>
   

4. 找到 → 提取功能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.

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

• 步骤要具体可执行，不要模糊描述
• 包含回滚方案
• 如需 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（只有这两个命令能用）

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

退出码	含义	你要做的
0	已推进	交接里引用 stdout 那行 JSON（checks、current_stage、next_step）
3	未推进：检查没过 / 红灯没验证 / 主动 block / tdd 写的测试被改	把 stdout 里的 blocked_reason 原样写进报告，按阻塞收尾。不要为了让它推进去改测试或改检查命令
2	脚本跑不了（参数错、缺 jq、状态文件损坏）	参数错就改正重跑；缺 jq 才按下面的格式手写，并在报告里写明「状态机未经脚本写入」

退出码 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 写入，它会按规

---

Content truncated.