---

name: pdlc-deploy description: 创建部署文档 argument-hint: <服务名 | 应用名> allowed-tools: Read, Write, Edit, Glob, Grep, Bash layer: 2 stage: deploy produces:

• docs/05_deployment/** requires: [] next_step: null terminal_state: deploy_done

---

创建部署文档

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

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

为指定服务或应用创建部署手册。

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

1. 从用户输入中提取服务/功能名称关键词
2. 在 docs/07_reviews/code/ 目录下搜索包含该关键词的评审记录
   • 匹配新格式：F<日期>-<编号>-*<关键词>*-review.md
   • 匹配旧格式：YYYYMMDD-*<关键词>*-review.md
   • 同时检查文件内容中是否包含该关键词
3. 未找到评审记录 → 输出以下信息后立即停止，不继续执行：

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

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

工作流程

1. 阅读目标服务/应用的 README.md 和技术栈信息
2. 阅读 docs/02_design/architecture/ 下的架构设计文档（如有）
3. 阅读评审记录，确认功能状态
4. 【必须创建文件】 在 docs/05_deployment/guides/ 下创建部署手册
   • 使用模板: templates/deploy-doc-template.md（结构完整、章节齐全）
   • 文件名格式: <功能ID>-<功能名>-deploy.md（如 F20260326-090000-user-auth-deploy.md）
     • 若无功能ID，则使用旧格式 YYYYMMDD-<服务名>-deploy.md
   • 文档顶部必须包含 PDLC 追溯头：

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

文档内容

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

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

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

关键章节检查

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

可执行性检查

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

自动修复

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

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

要求

<!-- @include templates/prompts/output-language.md -->

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

目标: $ARGUMENTS

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