build-prd

build-prd

通过与用户协作讨论，创建产品需求文档（PRD），最终生成一份可直接着手实施的完整 GitHub issue。

适用场景

• 用户要求“创建 PRD”或“撰写需求”
• 处理标记为 feature-request 或 enhancement 的 GitHub issue
• 用户需要在实施前记录需求
• 将模糊的想法转化为结构化、可实施的规格说明

不适用场景

• Issue 已包含完整的 PRD（检查标题是否带有 [PRD] 前缀）
• 纯 Bug 报告——这类问题需要复现步骤，而不是需求
• 实施工作已经开始——应改为事后撰写规格说明

前提条件

gh auth status        # GitHub CLI authenticated
gh repo view          # Inside a valid repo (or org/repo provided)

工作流

步骤 1：理解请求

如果请求来自 GitHub issue：

gh issue view ISSUE_NUMBER --repo ORG/REPO

阅读项目背景：

cat project-instructions.md  # or equivalent project instructions file
cat README.md

用 1-2 句话概述核心请求。如果无法做到，请先向用户询问清楚，再继续。

步骤 2：找出缺漏

根据 PRD 必需章节检查请求：

章节	是否必需？	来源
问题陈述	是	为什么这很重要？
用户故事	是	谁需要它？为什么？
成功指标	是	如何衡量成功？
范围（包含与不包含）	是	包含什么，不包含什么？
技术限制	是	有哪些限制、集成或模式？
设计稿/示例	否	如有，可提供视觉参考
依赖项	否	相关功能或系统
时间线	否	优先级或截止日期

针对所有缺失的信息整理问题。

步骤 3：一次性提出所有问题

To create a complete PRD, I need some additional information:

Q1: [specific question]
Q2: [specific question]
Q3: [specific question]
Q4 (Optional): [nice-to-have question]

Warning: 一次性提出所有问题。不要一次只问一个问题——这会浪费用户时间，也会打断交流。

如果是基于 GitHub issue 开展工作，请添加 question 标签：

gh issue edit ISSUE_NUMBER --repo ORG/REPO --add-label "question"

等待用户回复后再继续。

步骤 4：起草 PRD

使用以下模板——将所有占位符替换为实际内容：

# [Feature Name]

## Problem Statement
[2-3 sentences: what user problem this solves and why it matters now]

## User Stories
- As a [user type], I want [goal] so that [benefit]
- As a [user type], I want [goal] so that [benefit]

## Success Metrics
- [Metric]: [specific target or measurement approach]
- [Metric]: [specific target or measurement approach]

## Scope

### In Scope
- [Concrete feature or deliverable]
- [Concrete feature or deliverable]

### Out of Scope
- [Explicitly excluded item — prevents scope creep]
- [Explicitly excluded item]

## Technical Requirements
- [Requirement referencing existing codebase patterns]
- [Constraint or integration point]

## Dependencies
- [Related system or feature, if any]

## Open Questions
- [Anything unresolved — do not guess]

## Implementation Notes
[Architectural decisions, patterns to follow, files to reference]

步骤 5：与用户一起审阅

展示完整的 PRD 草稿，并指出其中的假设：

I've drafted a PRD based on our discussion. Please review:

[FULL PRD]

Assumptions I made:
- [Assumption 1]
- [Assumption 2]

Does this capture everything? Anything to change?

Warning: 未获得用户明确批准，绝不能继续执行步骤 6。“看起来不错”或“是的”都算批准。未回复不算。

步骤 6：更新 GitHub issue

仅在用户批准后执行：

gh issue edit ISSUE_NUMBER --repo ORG/REPO \
  --body "$(cat /tmp/prd-draft.md)" \
  --title "[PRD] Feature Name" \
  --add-label "ready-to-work"

gh issue edit ISSUE_NUMBER --repo ORG/REPO --remove-label "question" 2>/dev/null || true

标签	操作
ready-to-work	添加——表示 PRD 已完成
question	如存在则移除
feature-request、enhancement	保留——维持原有标签

步骤 7：确认

gh issue comment ISSUE_NUMBER --repo ORG/REPO \
  --body "PRD created. Issue updated with complete requirements. Ready for implementation planning."

错误处理

用户不确定范围——提出 MVP 方案：只包含实现核心价值所必需的内容，其余内容移至“范围外（未来）”。

范围过大——建议拆分为多个 PRD，每个 PRD 聚焦一项能力。先从基础能力开始。

用户提供的是实现细节，而非需求——引导用户回到需求：“开始实施前，我们先明确一下：这要解决什么问题？用户应该能够做哪些现在还做不到的事？”

缺少成功指标——根据功能类型提出建议：

功能类型	建议指标
面向用户	采用率、使用频率、满意度
性能	延迟降低、错误率下降
开发者工具	节省时间、代码质量提升
基础设施	正常运行时间、成本降低、事件发生频率

关键规则

• 未经用户明确批准，绝不更新 GitHub issue——PRD 是一份契约
• 绝不捏造技术细节——将未知事项标记为待解答问题
• 一次性汇总所有问题——在一条消息中以 Q1-Qn 编号
• 最终 PRD 中不得包含占位文本——必须替换所有方括号内容
• 保留原有标签——只添加 ready-to-work，绝不移除 feature-request 或 enhancement