prd-update-progress

摘自 vfarcic/dot-ai shared-prompts/prd-update-progress.md（MIT，版权所有 (c) 2025 Viktor Farcic）。原作者：Viktor Farcic。

PRD 进度更新斜杠命令

说明

你将协助根据已完成的实现工作更新现有的产品需求文档（PRD）。此命令会分析 Git 提交和代码变更，并结合对话上下文，跟踪 PRD 的完成进度并提出有依据的更新建议。

流程概述

1. 识别目标 PRD - 确定要更新的 PRD
2. 优先依据上下文分析进度 - 首先使用对话上下文，必要时再通过 Git 分析
3. 将变更映射到 PRD 条目 - 智能地将工作与需求关联起来
4. 提出更新建议 - 建议勾选已完成项并修改需求
5. 用户确认 - 核实建议并处理边界情况
6. 更新 PRD - 更新复选框和状态
7. 标记偏差 - 当实际工作与计划工作不一致时发出提醒
8. 提交进度更新 - 保留进度检查点
9. 继续下一项任务 - 提示用户运行 /prd-next

第 1 步：智能识别 PRD

根据对话上下文自动检测目标 PRD：

1. 当前工作上下文：查找近期关于特定 PRD 工作、功能或问题的对话
2. Git 分支分析：检查当前 Git 分支中的 PRD 标识（功能分支/PRD 编号、问题编号）
3. 近期文件活动：识别 prds/ 目录中近期修改的 PRD 文件
4. 待办事项列表上下文：检查 TodoWrite 工具中是否有正在进行的 PRD 特定任务

检测优先级顺序：

• 如果对话中明确提到“PRD #X”或特定 PRD 文件 → 使用该 PRD
• 如果 Git 分支包含 PRD 引用（例如“feature/prd-12-*”）→ 使用 PRD #12
• 如果 TodoWrite 显示有 PRD 特定任务 → 使用对应的 PRD 上下文
• 如果近期只修改了一个 PRD 文件 → 使用该 PRD
• 如果有多个可能的 PRD → 请用户澄清

第 2 步：优先依据上下文分析进度

优先事项：先使用对话上下文，再进行 Git 分析

对话上下文分析（快速 - 优先使用）

如果近期对话清楚地表明工作已完成：

• 近期讨论的实现：“刚完成 X”“已实现 Y”“已构建 Z”
• 待办事项列表上下文：检查 TodoWrite 工具中的已完成/进行中事项
• 提及文件创建：“已创建文件 X”“已添加 Y 功能”
• 测试完成情况：“测试通过”“所有 X 个测试均已完成”
• 用户确认：“可以正常工作”“实现已完成”“准备进入下一步”

有可用的对话上下文时请优先使用——它比解析 Git 更快、更准确

Git 变更分析（备用 - 仅在上下文不明确时使用）

仅当对话上下文不足时才使用 Git 工具：

提交分析

# Get recent commits (last 10-20 commits)
git log --oneline -n 20

# Get detailed changes since last PRD update
git log --since="1 week ago" --pretty=format:"%h %an %ad %s" --date=short

文件变更分析

# See what files were modified recently
git diff --name-status HEAD~10..HEAD

# Get specific changes in key directories
git diff --stat HEAD~10..HEAD

变更分类

识别不同类型的变更：

• 新文件：表示新增功能或组件
• 已修改文件：表明现有功能已更新
• 测试文件：实现经过测试的证据
• 文档文件：表明文档已更新
• 配置文件：表示设置或部署方面的变更

第 3 步：全面分析 PRD 结构

CRITICAL：系统性扫描复选框

必须执行此步骤，以避免遗漏需求：

1. 使用 grep 或搜索，扫描 PRD 中的所有未勾选项

2. 按类型对每项未勾选的需求进行分类：

   • 实现（代码、功能、技术任务）
   • 文档（指南、示例、交叉引用）
   • 验证（测试示例是否可用、用户流程）
   • 用户验收（实际使用、跨客户端测试）
   • 发布活动（培训、部署、推广）
   • 成功指标（采用情况、分析数据、支持影响）

   当前 prd-create 编写的 PRD 会将实时验收事项放在关联的 acceptance issue 中，而不是作为 PRD 复选框；实现里程碑合并后，PRD 即视为完成。对于仍包含实时验收复选框的旧版 PRD，在统计完成情况之前，将这些事项移至关联的 acceptance issue 中（绝不使用 sweep 标签），以免 /prd-full 和 /prd-done 因此等待；将它们列在 用户验收 类别下，并注明由该 issue 跟踪。

3. 仅将 git 变更映射到相应类别

4. 谨慎处理——只有直接证据能够证明项目已完成时，才将其标记为完成

基于证据的完成标准

实现需求——满足以下条件时标记为完成：

• 代码文件：表明功能已实现
• 测试文件：证明已进行全面测试
• 集成：组件已正确连接

文档需求——满足以下条件时标记为完成：

• 已创建文件：文档文件已存在
• 已验证示例：命令和示例已测试
• 交叉引用有效：已验证内部链接

验证需求——满足以下条件时标记为完成：

• 已完成手动测试：已端到端测试工作流
• 已验证示例：所有文档示例均可运行
• 已确认用户流程：已验证完整工作流

发布活动——满足以下条件时标记为完成：

• 已完成培训：团队已接受培训
• 已完成部署：功能已上线且可使用
• 已完成推广：用户正在积极使用该功能

谨慎标记完成政策

没有直接证据时，切勿标记为完成：

• ❌ 未经验证，不要假设文档“已经足够好”
• ❌ 没有实际测试证据，不要标记测试已完成
• ❌ 没有推广证明，不要标记发布事项已完成
• ❌ 没有指标，不要标记成功标准已完成

差距分析

系统性识别：

• 缺少证据的需求（仍需完成的工作）
• 需求之外的证据（范围外已完成的工作）
• 缺少验证（已实现但未测试）
• 尚未推广（已就绪但尚未部署或采用）

步骤 4：全面进度报告

必需：完整状态分析

提供全面的分类说明：

## PRD Progress Analysis: [PRD Name]

### ✅ COMPLETED (with evidence):
**Implementation** (X/Y items):
- [x] Item name - Evidence: specific files/changes
- [x] Item name - Evidence: specific files/changes

**Documentation** (X/Y items):
- [x] Item name - Evidence: docs created, examples tested
- [x] Item name - Evidence: cross-references verified

### ⏳ REMAINING WORK:
**Validation** (X items unchecked):
- [ ] Item name - Reason: needs manual testing/validation
- [ ] Item name - Reason: examples not tested

**User Acceptance** (X items unchecked):
- [ ] Item name - Reason: no cross-client testing done
- [ ] Item name - Reason: no user feedback collected

**Launch Activities** (X items unchecked):
- [ ] Item name - Reason: team not trained
- [ ] Item name - Reason: not deployed to production

**Success Metrics** (X items unchecked):
- [ ] Item name - Reason: no usage data available
- [ ] Item name - Reason: adoption not measured

### 🎯 COMPLETION STATUS:
- **Overall Progress**: X% complete (Y of Z total items)
- **Implementation Phase**: 100% complete ✅
- **Validation Phase**: X% complete (what's missing)
- **Launch Phase**: X% complete (what's missing)

谨慎推荐政策

只有在有直接证据时，才建议将项目标记为完成。 清楚列出仍需完成的工作。 除非所有项目确实都已完成，否则不要声称“一切已完成”。

步骤 5：实现与计划分析

偏差检测

当实际实现与计划方案不同时，标记出来：

• 架构变更：采用了与最初计划不同的技术方案
• 范围变更：在实现过程中新增或移除了功能
• 需求演变：开发过程中逐渐明确的用户需求
• 技术发现：编码过程中发现的限制或机会

更新建议

发现偏差时，建议更新 PRD：

• 更新决策日志：记录实现方案变更的原因
• 修改需求：更新需求以匹配实际功能
• 更新架构：修订技术方案文档
• 调整范围：在不同阶段之间移动项目，或更新功能定义

步骤 6：用户确认流程

清晰、透明地展示拟议的更改：

1. 证据摘要：展示检测到的工作
2. 拟议完成项：列出有证据支持、建议标记为已完成的具体复选框条目
3. 剩余工作分析：清楚说明仍未勾选的内容及原因
4. 偏差提醒：突出显示计划与实际情况之间的差异
5. 如实评估进度：给出切合实际的完成百分比

关键要求：

• 除非所有复选框都已完成，否则绝不声称“一切都已完成”（在关联的 acceptance issue 中跟踪的实时验收项不属于 PRD 复选框）
• 明确说明基于 git 分析的局限性
• 无法验证功能是否有效时，承认验证方面的不足
• 区分实现与验证／发布

更改前请等待用户确认，并妥善处理：

• 部分接受：用户同意部分建议，但不同意其他建议
• 补充背景信息：用户提供 git 历史记录中不可见的信息
• 范围澄清：用户解释看似超出范围的工作
• 未来规划：用户希望根据当前进度调整后续工作

步骤 7：系统化应用更新

应用更新时：

1. 仅更新已确认的条目——不要自行假设
2. 更新状态部分，使其反映当前阶段
3. 保留仍需处理的未勾选条目
4. 如实更新完成百分比

步骤 7.5：代码示例验证

根据实现进度更新 PRD 时：

关键要求：始终检查 PRD 中的代码示例是否与当前实现相符

示例影响检测

1. 接口变更：函数签名、参数类型、返回格式
2. API 演进：方法名称、类结构、数据模型
3. 工作流更新：用户交互模式、步骤顺序
4. 集成变更：组件之间的连接和通信方式

代码示例更新流程

1. 扫描 PRD：找出所有代码片段和示例
2. 交叉核对实现：将示例与实际代码进行比较
3. 标记过时内容：标记不再匹配的示例
4. 评估优先级：确定哪些示例需要立即更新
5. 更新示例：修订代码片段，使其与当前实现相符
6. 验证示例：测试更新后的示例，确保其有效

需要检查的示例类别

• 函数调用：参数顺序、类型、名称
• 接口定义：TypeScript 接口、类结构
• API 响应：数据格式、字段名称、响应结构
• 工作流步骤：用户交互顺序、工具使用模式
• 配置：设置示例、环境变量、配置文件

更新示例的时机

• 立即更新：接口变更导致现有示例失效时
• 完成前：将实现里程碑标记为完成时
• 评审期间：验证 PRD 准确性时
• 用户反馈时：有人报告示例无法使用时

步骤 8：提交进度更新

成功更新 PRD 后，提交所有更改以保留进度检查点：

提交实现工作

# MANDATORY: Stage ALL files - implementation work AND PRD updates together
# DO NOT selectively add only PRD files - commit everything as one atomic unit
git add .

# Verify what will be committed
git status

# Create comprehensive commit with PRD reference
git commit -m "feat(prd-X): implement [brief description of completed work]

- [Brief list of key implementation achievements]
- Updated PRD checkboxes for completed items

Progress: X% complete - [next major milestone]"

提交信息指南

• 引用 PRD 编号：提交信息中始终包含 prd-X
• 描述性摘要：简短、清晰地说明已实现的内容
• 进度说明：注明完成状态和后续步骤
• 以证据为依据：仅在确有实现进展时提交

注意：除非用户明确要求，否则不要推送提交。提交可以保留本地进度检查点，而不会影响远程分支。

步骤 9：根据 PRD 状态确定后续步骤

完成 PRD 更新并提交更改后，根据完成状态为用户提供指引：

如果 PRD 还有未完成的任务

---

PRD 进度已更新并提交。

要继续处理此 PRD：

1. 清除/重置对话上下文
2. 运行 /prd-next 获取下一个任务

---

如果 PRD 已 100% 完成

---

PRD #X 已完成！

要完成收尾：

1. 清除/重置对话上下文
2. 运行 /prd-done 将 PRD 移至已完成文件夹并关闭 GitHub issue

---