prd-done

从 vfarcic/dot-ai 的 shared-prompts/prd-done.md 引入（MIT，Copyright (c) 2025 Viktor Farcic）。原作者：Viktor Farcic。

完成 PRD 实现

完成 PRD 实现工作流，包括分支管理、创建拉取请求和关闭问题。

与代码托管平台无关：下方的 gh 命令以 GitHub 为例。通过 git remote get-url origin 检测代码托管平台，并使用相应的 CLI，将每个操作映射为等效命令：GitHub → gh；GitLab → glab（PR 称为合并请求，使用 glab mr …）；Forgejo/Gitea → tea。如果缺少所需的 CLI，请告知用户并提供其安装页面链接。

工作流步骤

0. 检测实现类型

首先：确定 PRD 完成类型，以选择相应的工作流

仅文档的完成情况（跳过 PR 工作流）：

• ✅ 仅修改 PRD 文件或项目管理文档
• ✅ 没有源代码变更
• ✅ 没有配置变更
• ✅ 功能已在之前的工作中实现
• → 使用简化工作流（仅步骤 1、2-简化版、5）

代码实现的完成情况（完整 PR 工作流）：

• ✅ 包含源代码变更
• ✅ 包含配置变更
• ✅ 包含新功能或修改
• ✅ 需要测试和集成
• → 使用完整工作流（步骤 1-6）

1. 完成前验证

• 完成所有 PRD 复选框：确认每项需求均已实现并测试。实时验收检查不属于 PRD 复选框：将 PRD 中剩余的检查项移至关联的 acceptance 问题（绝不能使用批量处理标签）后再进行统计。PRD 在合并时完成；仅文档的完成情况则在文档变更落地时完成；实时验收绝不能阻碍 PRD 完成。
• 更新文档：所有面向用户的文档均反映已实现的功能
• 没有未解决的阻碍事项：解决所有依赖问题并处理技术债务
• 更新 PRD 状态：将 PRD 标记为“Complete”，并填写完成日期
• 归档 PRD 文件：将已完成的 PRD 移至 ./prds/done/ 目录，以保持项目结构清晰
• 更新 ROADMAP.md（如存在）：如果 docs/ROADMAP.md 文件存在，则从路线图中移除已完成的功能

注意：创建 PR 时，测试会在 CI/CD 流水线中自动运行。完成工作流期间不要在本地运行测试。

2. 分支和提交管理

对于仅文档的完成情况：

• 直接提交到 main：运行 git add [prd-files]，并使用跳过 CI 的标志提交
• 在提交消息中使用跳过 CI 的标记：在提交消息中加入跳过 CI 的模式，避免不必要的 CI 运行
  • 常见模式：[skip ci]、[ci skip]、***NO_CI***、[skip actions]
  • 检查项目的 CI 配置，确认正确的模式
• 推送到远程：运行 git pull --rebase origin main && git push origin main 同步变更

对于代码实现的完成情况：

• 创建功能分支：运行 git checkout -b feature/prd-[issue-id]-[feature-name]
• 提交所有变更：确保所有实现工作均已提交
• 整理提交历史：压缩或整理提交，以保持历史记录清晰
• 推送到远程：运行 git push -u origin feature/prd-[issue-id]-[feature-name]

3. 创建拉取请求

重要：始终检查并使用可用的 PR 模板

3.1. PR 模板检测与解析

• 检查常见位置是否存在 PR 模板：

  • .github/PULL_REQUEST_TEMPLATE.md
  • .github/pull_request_template.md
  • .github/PULL_REQUEST_TEMPLATE/（包含多个模板的目录）
  • docs/pull_request_template.md

• 全面阅读并解析模板：如果找到模板，请分析并提取：

  • 结构元素：必需章节、检查清单、格式要求
  • 内容要求：每个章节需要提供哪些信息
  • 流程说明：模板中指定的工作流改进或前置条件
  • 验证要求：提及的任何检查、签核或验证

• 从模板中提取可执行的说明：

  • 提交要求：查找 DCO 签核、提交消息格式、提交签名要求
  • 提交前操作：构建命令、测试命令、代码检查、格式检查
  • 文档要求：必须更新哪些文档、必须添加哪些链接
  • 评审要求：必需的评审者、审批流程、特殊注意事项

  需要识别并执行的模板说明示例：

  • “所有提交都必须包含一行 Signed-off-by” → 验证提交是否包含 DCO 签核，缺少时进行修正
  • “提交前运行 npm test” → 执行测试命令
  • “PR 标题遵循 Conventional Commits 格式” → 验证标题格式
  • “更新 CHANGELOG.md” → 检查是否已更新变更日志
  • 代码块中显示的任何 bash 命令 → 考虑是否应执行

3.2. 分析变更以编写 PR 内容

• 检查 git diff：分析 git diff main...HEAD，了解变更范围
• 检查提交历史：使用 git log main..HEAD 了解实现进展
• 确定变更类型：判断变更是否包括：
  • 新功能、错误修复、重构、文档、测试、配置、依赖项
  • 破坏性变更或向后兼容的变更
  • 性能改进或安全修复
• 检查修改的文件：确定代码库中受影响的区域
  • 源代码文件
  • 测试文件
  • 文档文件
  • 配置文件

3.3. 自动填写 PR 信息

自动填写可通过分析推断的信息：

• PR 标题：

  • 如果模板指定了标题格式，则遵循该格式（例如，Conventional Commits：feat(scope): description）
  • 从 PRD 标题/描述和提交消息中提取
  • 如果模板要求，则包含问题引用

• 描述章节：

  • 内容/原因：从 PRD 目标和实现细节中提取
  • 相关问题：使用 Closes #[issue-id] 或 Fixes #[issue-id] 自动关联
  • 变更类型：根据文件分析勾选相应选项

• 测试检查清单：

  • 如果修改了测试文件，则勾选“已添加/更新测试”
  • 注意：测试会在 CI/CD 中自动运行

• 文档检查清单：

  • 根据更新的文档（README、API 文档、代码注释）勾选相应项目
  • 检查是否遵循 CONTRIBUTING.md 指南

• 安全检查清单：

  • 扫描提交中是否存在潜在机密或凭据
  • 如果身份验证/授权代码发生变更，则标记
  • 说明任何依赖项更新

3.4. 提示用户补充无法推断的信息

重要：不要只提问——先分析并提出答案，再让用户确认或更正

对于每一项，先利用可用上下文提出答案，再请用户确认：

• 手动测试结果：

  • 分析 PRD 中的测试策略部分，了解计划进行哪些测试
  • 检查 git 提交中的测试相关消息
  • 根据变更类型提出测试方案（例如：“已检查文档的准确性和清晰度，并验证了交叉引用”）
  • 向用户展示建议并询问：“这样准确吗？还是需要修改？”

• 破坏性变更：

  • 扫描提交和 PRD，查找破坏性变更的迹象
  • 如果发现相关迹象，根据 PRD 内容提出迁移指南
  • 如果未发现，确认：“未发现破坏性变更。正确吗？”

• 性能影响：

  • 分析变更类型：文档／配置变更通常不会影响性能
  • 根据分析提出答案（例如：“不会影响性能——仅涉及文档”）
  • 询问：“正确吗？还是有其他性能方面的考虑？”

• 安全注意事项：

  • 检查是否修改了涉及安全的文件（身份验证、凭据、API 密钥）
  • 扫描提交，查找安全相关关键词
  • 提出安全状态（例如：“无安全影响——仅修改文档”）
  • 询问：“准确吗？还是有需要记录的安全方面考虑？”

• 审查者关注重点：

  • 分析 PRD 目标和 git 变更，找出关键关注点
  • 提出具体的关注重点（例如：“核实文档准确性、检查交叉引用链接、确认工作流示例与实现一致”）
  • 向用户展示列表并询问：“这些是合适的关注重点吗？还是需要调整？”

• 后续工作：

  • 检查 PRD 中是否有“未来增强”或“范围之外”部分
  • 分析 prds/ 目录中的其他 PRD，查找相关工作
  • 如有，提出后续事项（例如：“PRD 中列出的未来增强：模板验证、AI 生成描述”）
  • 询问：“要列出这些事项吗？还是还有其他后续工作？”

• 补充背景信息：

  • 查阅 PRD 中的特殊注意事项
  • 检查这是否是用于自我验证／测试的 PR
  • 提出任何相关背景信息（例如：“此 PR 本身就在测试其所记录的增强版工作流”）
  • 询问：“还有什么是审查者需要了解的吗？”

展示格式： 以摘要形式一次性展示所有建议答案：

📋 **Proposed PR Information** (based on analysis)

**Manual Testing:** [proposed answer]
**Breaking Changes:** [proposed answer]
**Performance Impact:** [proposed answer]
**Security Considerations:** [proposed answer]
**Reviewer Focus:** [proposed list]
**Follow-up Work:** [proposed items or "None"]
**Additional Context:** [proposed context or "None"]

Please review and respond:
- Type "yes" or "confirm" to accept all
- Specify corrections for any items that need changes

3.5. 执行模板要求

重要：创建 PR 前，找出并执行模板中的所有可操作要求

• 分析模板中的可操作说明：

  • 扫描模板内容，查找祈使语句、要求或命令
  • 留意“必须”、“应该”、“运行”、“执行”、“确保”、“验证”等模式
  • 找出代码块中看起来是前置条件的 bash 命令
  • 提取检查清单中提及的验证要求

• 对找出的要求进行分类：

  • 提交级操作：签署确认、格式整理、验证
  • 提交前命令：测试、构建、代码检查、格式检查
  • 验证检查：文件是否存在、格式是否合规、内容要求
  • 文档操作：需要进行的更新、需要添加的链接

• 提出并执行要求：

  • 向用户展示已找出的要求：“模板规定了以下操作：[列表]”
  • 对每项要求，判断是否可以自动执行
  • 提议执行：“现在要执行这些操作吗？”
  • 执行用户确认的操作并报告结果
  • 妥善处理失败，并询问用户如何继续

• 创建 PR 前的摘要：

  ✅ Template Requirements Status:
  [List each requirement with status: executed/validated/skipped/failed]
  
  Ready to create PR? (yes/no)
  

3.6. 检测并应用 PR 标签（如果存在 release.yml）

重要：仅当 .github/release.yml 存在时才应用标签——完全根据该文件动态处理

• 检查是否存在 .github/release.yml：

  • 如果文件存在 → 继续检测标签
  • 如果文件不存在 → 跳过标签检测，创建不带标签的 PR

• 如果 release.yml 存在，解析它以了解可用的类别和标签：

  • 读取 YAML 文件
  • 提取所有类别定义及其关联标签
  • 建立映射：类别 → 标签列表
  • 注意类别顺序（排在前面的类别通常更重要）

• 分析 PR 特征：

  • 主要变更类型：此 PR 的主要目的是什么？
  • 文件变更：修改的文件类型（扩展名、路径、用途）
  • 变更范围：受影响的代码库区域
  • 提交消息：关键词、模式、前缀
  • PR 标题和描述：表明变更类型的关键词
  • PRD 上下文：问题／解决方案的原始描述

• 选择唯一最匹配的标签：

  • 对 release.yml 中的每个类别评分，判断其与 PR 主要目的的匹配程度
  • 考虑 release.yml 中的重要性层级：
    • 破坏性变更 > 新功能 > Bug 修复 > 文档 > 依赖项 > 其他
  • 从最能体现主要变更的类别中选择一个标签
  • 为什么只选一个标签？：避免 PR 同时出现在多个发行说明类别中
  • 选择优先级：
    1. 如果存在破坏性变更 → 使用 breaking-change 或 breaking
    2. 如果主要是新增功能 → 使用 feat、feature 或 enhancement
    3. 如果主要是修复 Bug → 使用 fix、bug 或 bugfix
    4. 如果主要是文档变更 → 使用 documentation 或 docs
    5. 如果主要是依赖项变更 → 使用 dependencies、deps 或 dependency
    6. 其他情况 → 无需特定标签（将显示在“其他变更”中）

• 应用检测到的标签：将唯一最匹配的标签添加到创建 PR 的命令中

  • 示例：gh pr create --title "..." --body "..." --label "fix"

3.7. 创建拉取请求

• 构建 PR 正文：按照模板结构，合并自动填充的信息和用户提供的信息
• 创建 PR：
  • 如果检测到标签：gh pr create --title "[title]" --body "[body]" --label "[single-label]"
  • 如果没有 release.yml 或没有匹配的标签：gh pr create --title "[title]" --body "[body]"
• 验证 PR 已创建：确认 PR 已成功创建、模板已正确填充，并且已应用标签（如适用）
• 请求评审：如果有指定，为代码评审指派相应的团队成员

3.8. 没有模板的项目的备用方案

如果未找到 PR 模板，请创建合理的默认结构：

## Description
[What this PR does and why]

## Related Issues
Closes #[issue-id]

## Changes Made
- [List key changes]

## Testing
- [Testing approach and results]

## Documentation
- [Documentation updates made]

4. 审查与合并流程

• 检查进行中的流程：使用 gh pr checks [pr-number] 检查是否有正在进行的 CI/CD、安全分析或自动化审查（CodeRabbit、CodeQL 等）
• 检查 PR 详情：使用 gh pr view [pr-number] 查看人工审查评论和 PR 元数据
• 审查所有自动化反馈：检查 PR 评论区中的自动化代码审查反馈（机器人、代码检查工具、分析器）
  • 使用多种方法获取所有反馈：
    • MCP 服务（有条件时优先）：使用任何可用的 MCP 服务获取全面的审查数据
      • 代码审查 MCP（例如 CodeRabbit、自定义审查服务），用于获取详细的 AI 代码审查
      • 检查是否有与代码审查、拉取请求或自动化反馈相关的 MCP 工具/函数
    • CLI 命令：gh pr view [pr-number]、gh pr checks [pr-number]、gh api repos/owner/repo/pulls/[pr-number]/comments
    • 检查 Web 界面：直接获取 PR URL，以收集所有评论，包括 CLI 工具可能遗漏的行内代码建议
    • 查找自动化工具的评论（用户名以 'ai'、'bot' 结尾，或来自已知审查工具）
• 展示所有代码审查发现：始终向用户展示每条审查评论，无论其严重程度如何
  • 展示所有评论：展示每条建议、细枝末节的意见和推荐，不要筛选或遗漏
  • 对发现分类：根据影响分为严重、重要、可选/细枝末节
  • 提供具体示例：引用实际建议及其位置
  • 说明评估依据：解释每项发现的分类原因
  • 由用户决定：让用户决定在合并前实施哪些改进（必须处理严重问题，其他由用户选择）
• 评估反馈优先级：对审查反馈分类
  • 严重：安全问题、破坏性变更、测试失败——合并前必须处理
  • 重要：代码质量、可维护性、性能——为确保生产就绪，应当处理
  • 可选：风格偏好、轻微优化——可根据项目标准酌情处理
• 等待所有审查完成：如果仍有任何审查待处理或进行中，不要合并，包括：
  • 自动化代码审查（CodeRabbit、CodeQL 等）——必须等待审查完成，即使 CI 已通过
  • 安全分析——必须完成并通过
  • CI/CD 流程——所有构建和测试都必须通过
  • 人工审查——如果已请求的审查者尚未批准
  • 严重提醒：绝不要跳过自动化代码审查——即使 CI 已通过，它们仍能提供有价值的反馈
• 处理审查反馈：根据代码审查（自动化和人工）进行必要修改
  • 在功能分支上创建额外的提交，以处理反馈
  • 如有需要，更新测试以覆盖建议的改进
  • 记录有意未处理的反馈及原因
• 确认所有检查均已通过：确保所有 CI/CD、测试、安全分析和自动化流程均已完成并通过
• 最终审查：确认 PR 满足原始 PRD 的要求，并保持代码质量
• 合并到 main：只有在处理完所有反馈且所有流程完成后，才完成拉取请求的合并
• 验证部署：确保功能在生产环境中正常运行
• 监控问题：留意部署后可能出现的问题

5. 关闭 Issue

• 更新 Issue 的 PRD 链接：更新 GitHub Issue 描述，使其指向 ./prds/done/ 目录中的新 PRD 路径
• 关闭 GitHub Issue：添加最终完成评论并关闭 Issue
• 归档材料：如有需要，保存临时文件或测试数据
• 通知团队：向相关利益相关者宣布功能已完成

6. 分支清理

• 切换到 main 分支：git checkout main
• 拉取最新更改：git pull origin main，确保本地 main 分支已是最新版本
• 删除本地功能分支：git branch -d feature/prd-[issue-id]-[feature-name]
• 删除远程功能分支：git push origin --delete feature/prd-[issue-id]-[feature-name]

成功标准

✅ 功能已上线且运行正常
✅ 所有测试均在生产环境中通过
✅ 文档准确且完整
✅ PRD 问题已关闭，并附有完成总结
✅ 团队已获知功能可用

只有当用户能够按照文档成功使用该功能时，PRD 实施才算完成。