Back to Details

pm-spec-writing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PM Spec Writing

PM规格文档写作

Take an idea (often vague) and turn it into a specification a developer or AI agent can actually build from. Stack-agnostic. Works for new features, bug fixes, content changes, or infrastructure work.
将一个（通常模糊的）想法转化为开发者或AI Agent可以直接据此实现的规格文档。与技术栈无关，适用于新功能开发、bug修复、内容变更或基础设施工作。

When to use

使用场景

  • Translating an idea into a buildable feature spec
  • Writing a PRD or product requirement document
  • Filing a bug report that someone else can act on
  • Scoping a project before kickoff
  • Prioritizing a backlog of feature requests
  • Writing acceptance criteria for an existing feature
  • Breaking a large initiative into shippable increments
  • 将想法转化为可落地的feature spec
  • 撰写PRD或产品需求文档
  • 提交他人可据此处理的bug报告
  • 项目启动前划定范围
  • 对功能需求待办列表进行优先级排序
  • 为现有功能撰写acceptance criteria
  • 将大型项目拆解为可交付的增量任务

When NOT to use

不适用场景

  • Quarterly or annual planning across multiple initiatives (use 
    roadmap-planning
    )
  • Code review or debugging existing code (use 
    code-review-web
    )
  • Design decisions for a feature already specced (use 
    design-standards
    )
  • User research to validate an idea (use 
    ux-research
    )
  • 跨多个项目的季度或年度规划（请使用
    roadmap-planning
    ）
  • 代码评审或现有代码调试（请使用
    code-review-web
    ）
  • 已完成规格定义的功能的设计决策（请使用
    design-standards
    ）
  • 验证想法的用户研究（请使用
    ux-research
    ）

Required inputs

必要输入

  • The idea, request, or problem being addressed
  • The audience or user affected
  • Any existing constraints (stack, deadlines, dependencies)
  • The success metric (how will you know it worked?)
If the idea is vague, the workflow's first step is clarification. Do not write specs around vagueness.
  • 要解决的想法、需求或问题
  • 受影响的受众或用户群体
  • 现有约束条件（技术栈、截止日期、依赖项）
  • 成功指标（如何判断该方案有效？）
如果想法模糊不清，工作流的第一步是澄清需求。不要基于模糊的内容撰写规格文档。

The framework: 4 phases

框架：4个阶段

Every PM workflow follows the same arc. The phases are universal even if the specific outputs vary.
每个PM工作流都遵循相同的流程。即使具体输出有所不同，这些阶段也具有通用性。

Phase 1: Clarify the idea

阶段1：澄清想法

Before any spec, answer four questions. If any answer is "I don't know," go back to the user.
  1. What user problem does this solve? Not "what does it do." The problem comes first; the feature is the proposed solution.
  2. Who specifically benefits? Be precise. "Users" is not specific. "First-time visitors who don't convert" is.
  3. What is the success metric? How will you know it worked? Pick one primary metric.
  4. Why now? What changed that makes this the right time to build it? If "nothing changed," it might not be the right time.
在撰写任何规格文档之前，先回答四个问题。如果任何一个问题的答案是“我不知道”，请返回用户处确认。
  1. 这解决了用户的什么问题？ 不是“它能做什么”。问题优先，功能只是提出的解决方案。
  2. 具体哪些用户会受益？ 请精准描述。“用户”不够具体，“未完成转化的首次访客”才是精准的表述。
  3. 成功指标是什么？ 如何判断它有效？选择一个核心指标。
  4. 为什么是现在？ 发生了什么变化让现在成为实现它的合适时机？如果“没有变化”，那可能不是合适的时机。

Phase 2: Scope by impact and effort

阶段2：按影响与工作量划定范围

Plot every candidate idea on the impact/effort grid:
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
This is not a perfect framework. Some "low impact" things are mandatory (compliance, accessibility, security). Note exceptions.
将每个候选想法标注在影响/工作量矩阵上：
高影响 / 低工作量       立即交付
  示例：文案修复、对比度调整、元标签修复、失效链接修复、缺失替代文本修复、重定向设置

高影响 / 高工作量       规划并批量处理
  示例：新页面类型开发、新功能开发、架构重构、重大改版、新集成对接

低影响 / 低工作量       归类为“锦上添花”批量处理
  示例：提示框优化、文案小幅润色、UX细节美化

低影响 / 高工作量       跳过或无限期推迟
  示例：重构现有可用功能、小众边缘场景功能、过早优化
这并非完美的框架。有些“低影响”的工作是强制性的（合规性、可访问性、安全性）。请标注例外情况。

Phase 3: Write the spec

阶段3：撰写规格文档

Three formats based on the type of work.
根据工作类型分为三种格式。

Format A: Feature spec (for new features)

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

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]
标题：[具体、面向行动的表述]

问题
[1-2句话。描述用户问题及当前状态。]

用户群体
[具体受益的用户群体。请精准描述用户细分。]

提案
[1段话。描述提议的解决方案。保持概念层面的表述。]

USER STORIES
- 作为[用户类型]，我希望[执行操作]，以便[达成结果]
- 作为[用户类型]，我希望[执行操作]，以便[达成结果]

ACCEPTANCE CRITERIA
- 当[场景]，执行[操作]，则[预期结果]
- 当[场景]，执行[操作]，则[预期结果]

非范围内容
[本规格明确不涵盖的内容。这对控制范围至关重要。]

依赖项
[交付前所需的其他系统、API、设计、内容等。]

成功指标
[用于判断方案有效的核心指标。如有已知当前基准请一并提供。]

预估工作量
[小（数小时）/ 中（1-3天）/ 大（1-2周）/ 超大（多个迭代）]

优先级
[P0 上线阻塞项 / P1 下个迭代 / P2 本季度内 / P3 待办列表]

Format B: Dev brief (for handing to a developer or AI agent)

格式B：Dev brief（适用于交付给开发者或AI Agent）

For tactical, ready-to-build work. Lighter than a full spec.
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]
The verify section is the most-skipped and most-important. Without it, "done" means whatever the implementer thinks done means.
适用于战术性、可立即开工的工作。比完整规格文档更简洁。
背景：[1-2句话解释这项工作的重要性]

任务：[具体文件、所需的精确变更]

约束条件：[哪些内容绝对不能更改，需要保留的部分]

验证：[确认工作完成的精确步骤]
验证部分是最容易被忽略但最重要的部分。没有它，“完成”的定义就取决于实现者的主观判断。

Format C: Bug report

格式C：Bug报告

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]
URL或场景：[问题发生的位置]

症状：[用户看到或体验到的情况]

预期结果：[应该发生的情况]

复现步骤：
1. [具体步骤]
2. [具体步骤]
3. [具体步骤]

假设：[已知的可能根本原因]

待排查文件：[已知的可能涉及的文件]

优先级：
  P0 - 阻塞关键用户流程，立即修复上线
  P1 - 严重影响UX，本迭代修复
  P2 - 小问题，方便时修复
  P3 - 锦上添花的改进

浏览器/设备：[如果问题可能与浏览器相关，请注明]

Phase 4: Sequence and ship

阶段4：排序与交付

Specs without sequencing become dust on a shelf.
For a single feature: identify the smallest shippable increment. What is the smallest version that delivers user value? Ship that first. Then iterate.
For a backlog: order by dependencies first, then by priority, then by impact/effort. The order matters more than the priority labels.
没有排序的规格文档只会被束之高阁。
对于单个功能：确定最小可交付增量。即能为用户带来价值的最小版本是什么？先交付这个版本，再进行迭代。
对于待办列表：首先按依赖关系排序，然后按优先级，最后按影响/工作量排序。排序顺序比优先级标签更重要。

Workflow

工作流程

  1. Clarify. If the idea is vague, ask the four phase-1 questions before proceeding.
  2. Scope. Plot the work on the impact/effort grid.
  3. Pick the right format. Feature spec for new features, dev brief for tactical work, bug report for defects.
  4. Write the spec. Use the template format. Fill in every section. Empty sections are flags.
  5. Define done. Verify steps must be unambiguous. "Test it" is not a verify step.
  6. Get buy-in. Walk through the spec with whoever will build it before they start.
  7. Sequence. Identify the smallest shippable increment.
  1. 澄清需求：如果想法模糊，先询问阶段1的四个问题再继续。
  2. 划定范围：将工作标注在影响/工作量矩阵上。
  3. 选择合适格式：新功能用Feature spec，战术性工作用Dev brief，缺陷用Bug报告。
  4. 撰写规格文档：使用模板格式，填写每个部分。空白部分是需要注意的信号。
  5. 定义完成标准：验证步骤必须明确。“测试一下”不属于有效的验证步骤。
  6. 获得认可：在执行者开始工作前，与其一起过一遍规格文档。
  7. 排序：确定最小可交付增量。

Failure patterns

常见失败模式

  • Specs that describe solutions before problems. Always start with the user problem. The solution is downstream.
  • Specs without a success metric. Without a metric, you cannot tell if the feature worked.
  • Acceptance criteria that are not testable. "User experience is improved" is not testable. "User completes signup in under 60 seconds" is.
  • Specs that include the "how" instead of the "what." Implementation details belong in the dev brief, not the spec. The spec is the desired outcome.
  • No "out of scope" section. Without explicit boundaries, scope creeps.
  • Bug reports without reproduction steps. Cannot be acted on. Always include steps.
  • Verify steps that are vague. "Make sure it works." Useless. Must be specific actions with observable outcomes.
  • Skipping the smallest-shippable-increment exercise. Leads to 6-month projects that should have been 2-week experiments.
  • 先描述解决方案而非问题的规格文档：始终从用户问题入手，解决方案是后续步骤。
  • 没有成功指标的规格文档：没有指标就无法判断功能是否有效。
  • 不可测试的Acceptance criteria：“用户体验得到提升”不可测试，“用户在60秒内完成注册”才是可测试的。
  • 包含“如何实现”而非“要实现什么”的规格文档：实现细节属于Dev brief，而非规格文档。规格文档应描述期望的结果。
  • 没有“非范围内容”部分：没有明确的边界，范围就会不断扩大。
  • 没有复现步骤的Bug报告：无法被处理，务必包含步骤。
  • 模糊的验证步骤：“确保能正常工作”毫无用处。必须是带有可观察结果的具体操作。
  • 跳过最小可交付增量分析：会导致本该是2周实验的项目变成6个月的大工程。

Output format

输出格式

Output is one of three formats based on work type, all in markdown:
  • spec-[feature-name].md
    for feature specs
  • brief-[task-name].md
    for dev briefs
  • bug-[summary].md
    for bug reports
For larger initiatives, group related specs in a folder:
specs/
  initiative-name/
    spec-feature-1.md
    spec-feature-2.md
    brief-task-1.md
    README.md   (overview and sequencing)
根据工作类型，输出为以下三种格式之一，均为markdown格式：
  • spec-[功能名称].md
    用于Feature spec
  • brief-[任务名称].md
    用于Dev brief
  • bug-[摘要].md
    用于Bug报告
对于大型项目，将相关规格文档归类到一个文件夹中：
specs/
  initiative-name/
    spec-feature-1.md
    spec-feature-2.md
    brief-task-1.md
    README.md   (overview and sequencing)

Reference files

参考文件

  • references/feature-spec-template.md
     - Full feature spec template.
  • references/dev-brief-template.md
     - Compact dev brief template for tactical work.
  • references/prioritization-frameworks.md
     - Beyond impact/effort: RICE, weighted scoring, MoSCoW.
  • references/feature-spec-template.md
     - 完整的Feature spec模板。
  • references/dev-brief-template.md
     - 适用于战术性工作的简洁Dev brief模板。
  • references/prioritization-frameworks.md
     - 除影响/工作量外的其他优先级框架：RICE、加权评分、MoSCoW。