pm-spec-writing

PM 规格编写

将一个想法（通常比较模糊）转化为开发者或 AI Agent 能够据此实际构建的规格。与技术栈无关。适用于新功能、错误修复、内容更改或基础设施工作。

---

适用场景

• 将想法转化为可实现的功能规格
• 编写 PRD 或产品需求文档
• 提交可供他人采取行动的错误报告
• 在项目启动前界定范围
• 确定待办事项中功能请求的优先级
• 为现有功能编写验收标准
• 将大型计划拆分为可交付的增量

不适用场景

• 跨多个计划进行季度或年度规划（使用 roadmap-planning）
• 代码审查或调试现有代码（使用 code-review-web）
• 为已有规格的功能做设计决策（使用 design-standards）
• 通过用户研究验证想法（使用 ux-research）

---

必需输入

• 要处理的想法、请求或问题
• 受影响的受众或用户
• 任何现有限制（技术栈、截止日期、依赖项）
• 成功指标（如何判断是否成功？）

如果想法比较模糊，工作流的第一步就是澄清。不要围绕模糊不清的想法编写规格。

---

框架：4 个阶段

每个 PM 工作流都遵循相同的流程。即使具体产出有所不同，各阶段也具有普适性。

阶段 1：澄清想法

编写任何规格之前，先回答以下四个问题。如果有任何一个问题的答案是“我不知道”，就回去询问用户。

1. 要解决什么用户问题？ 不是“它有什么功能”。问题优先；功能是拟议的解决方案。
2. 具体哪些人会受益？ 要明确。“用户”不够具体；“访问后未完成转化的首次访客”才具体。
3. 成功指标是什么？ 如何判断是否成功？选定一个主要指标。
4. 为什么是现在？ 发生了什么变化，让现在成为构建它的合适时机？如果“什么都没变”，现在可能并不是合适的时机。

阶段 2：根据影响和工作量界定范围

将每个候选想法放到影响／工作量矩阵中：

HIGH IMPACT / LOW EFFORT       Ship immediately
  Examples: copy fixes, contrast fixes, meta tags,
            broken links, missing alt text, redirects

HIGH IMPACT / HIGH EFFORT      Plan and batch
  Examples: new page type, new feature, schema overhaul,
            major redesign, new integration

LOW IMPACT / LOW EFFORT        Nice-to-have batch
  Examples: tooltip improvements, minor copy polish,
            cosmetic UX touches

LOW IMPACT / HIGH EFFORT       Skip or defer indefinitely
  Examples: rebuilding what already works, exotic
            edge case features, premature optimization

这并非完美的框架。有些“低影响”事项是强制要求（合规性、无障碍、安全性）。请注明例外情况。

阶段 3：编写规格

根据工作类型，选择以下三种格式之一。

格式 A：功能规格（适用于新功能）

TITLE: [Specific, action-oriented]

PROBLEM
[1-2 sentences. The user problem and current state.]

USERS
[Who specifically benefits. Be precise about the user segment.]

PROPOSAL
[1 paragraph. The proposed solution. Stay at the conceptual level.]

USER STORIES
- As a [user type], I want to [action], so that [outcome]
- As a [user type], I want to [action], so that [outcome]

ACCEPTANCE CRITERIA
- Given [context], when [action], then [expected outcome]
- Given [context], when [action], then [expected outcome]

OUT OF SCOPE
[What this spec explicitly does NOT cover. Important for scope control.]

DEPENDENCIES
[Other systems, APIs, designs, content needed before this can ship.]

SUCCESS METRIC
[The one primary metric that tells us this worked. With current baseline if known.]

ESTIMATED EFFORT
[Small (hours) / Medium (1-3 days) / Large (1-2 weeks) / XL (sprints)]

PRIORITY
[P0 launch blocker / P1 next sprint / P2 within quarter / P3 backlog]

格式 B：开发简报（用于交接给开发者或 AI Agent）

适用于战术性、可立即构建的工作。内容比完整规格精简。

CONTEXT: [1-2 sentences explaining why this matters]

TASK: [Specific files, exact changes needed]

CONSTRAINTS: [What must NOT change, what to preserve]

VERIFY: [Exact steps to confirm the work is done correctly]

验证部分最容易被跳过，却也最为重要。没有它，“完成”就只能由实施者自行定义。

格式 C：错误报告

URL or context: [Where it happens]

Symptom: [What the user sees or experiences]

Expected: [What should happen instead]

Steps to reproduce:
1. [Specific step]
2. [Specific step]
3. [Specific step]

Hypothesis: [Likely root cause if known]

Files to investigate: [Likely files involved if known]

Priority:
  P0 - blocking critical user flow, ship immediately
  P1 - degrades UX significantly, fix this sprint
  P2 - minor issue, fix when convenient
  P3 - nice-to-have improvement

Browser/device: [If reproducibility might be browser-specific]

阶段 4：排序并交付

没有排序的规格只会积灰。

对于单个功能：找出最小的可交付增量。能够为用户带来价值的最小版本是什么？先交付它，然后再迭代。

对于待办事项：先按依赖关系排序，再按优先级排序，最后按影响／工作量排序。排序顺序比优先级标签更重要。

---

工作流

1. 澄清。 如果想法比较模糊，先提出阶段 1 中的四个问题，再继续。
2. 界定范围。 将工作放到影响／工作量矩阵中。
3. 选择合适的格式。 新功能用功能规格，战术性工作用开发简报，缺陷用错误报告。
4. 编写规格。 使用模板格式，填写每个部分。留空的部分就是警示信号。
5. 定义完成标准。 验证步骤必须明确无误。“测试一下”不算验证步骤。
6. 取得认同。 在开始之前，与负责构建的人一起过一遍规格。
7. 排序。 找出最小的可交付增量。

---

失败模式

• 先描述解决方案，而不是问题的规格说明。 始终从用户问题出发。解决方案应在后续提出。
• 没有成功指标的规格说明。 没有指标，就无法判断功能是否有效。
• 无法测试的验收标准。“改善用户体验”无法测试。“用户在 60 秒内完成注册”则可以。
• 写明“如何做”而非“做什么”的规格说明。 实现细节应放在开发简报中，而非规格说明中。规格说明描述的是预期结果。
• 没有“范围之外”章节。 不明确界定边界，范围就会不断扩大。
• 没有复现步骤的错误报告。 无法据此采取行动。务必附上步骤。
• 验证步骤含糊不清。“确保它能正常工作。”毫无用处。必须写明具体操作及可观察到的结果。
• 跳过最小可交付增量练习。 这会导致原本只需进行为期 2 周实验的项目变成持续 6 个月的项目。

---

输出格式

根据工作类型，输出以下三种 Markdown 格式之一：

• spec-[feature-name].md，用于功能规格说明
• brief-[task-name].md，用于开发简报
• bug-[summary].md，用于错误报告

对于较大型的计划，请将相关规格说明归入一个文件夹：

specs/
  initiative-name/
    spec-feature-1.md
    spec-feature-2.md
    brief-task-1.md
    README.md   (overview and sequencing)

---

所需数据不可用时

此技能的输出依赖于其自身无法生成的数据、测量结果或工具结果。当所需输入、工具或数据源不可用或无法验证时，合规的输出应是交付内容，并说明存在的缺口：需要什么、实际获取或验证了什么，以及输出中的哪些部分受到影响。绝不能为了完成交付内容而编造、估算或插值所需数值。明确说明缺口本身就是完整的答复。

---

参考文件

• references/feature-spec-template.md - 完整的功能规格说明模板。
• references/dev-brief-template.md - 用于战术性工作的精简开发简报模板。
• references/prioritization-frameworks.md - 超越影响/投入的优先级框架：RICE、加权评分、MoSCoW。