writing-specs-designs
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseWriting Specs & Designs
编写规格与设计文档
Scope
范围
Covers
- Producing a Spec & Design Doc Pack that helps product, design, and engineering quickly reach shared clarity
- Converting “insights” into concrete artifacts: a low‑fidelity diagram, flows/states, prototype plan, and testable acceptance criteria
- Mobile-specific tap economy (when relevant): explicitly optimizing taps and interaction cost
When to use
- “Write a spec / feature spec / technical spec for this feature.”
- “Turn these notes into a design doc that engineering can build from.”
- “Create a shaping-style doc with a diagram of the moving pieces.”
- “We need a prototype plan to evaluate the feel of this interaction.”
When NOT to use
- You’re still validating what problem to solve (do discovery / problem definition first).
- You need a high-level strategy/vision document (do product vision / north star work first).
- You need a deep engineering architecture design (APIs, schemas, scaling, reliability) rather than product interaction clarity.
- You only need pixel-perfect UI mocks (this produces specs and structured guidance, not final visuals).
涵盖内容
- 制作一份规格与设计文档包，帮助产品、设计和开发团队快速达成共识
- 将“洞察”转化为具体交付物：low-fidelity图、流程/状态、原型计划和可测试的验收标准
- 移动端专属的tap economy（点击成本优化）（适用时）：明确优化点击次数与交互成本
适用场景
- “为这个功能编写一份规格/功能规格/技术规格文档。”
- “把这些笔记转化为开发团队可据此进行开发的设计文档。”
- “创建一份梳理型文档，包含各模块的low-fi图。”
- “我们需要一份原型计划来评估该交互的体验感。”
不适用场景
- 你仍在验证要解决的问题是什么（先进行发现/问题定义工作）。
- 你需要一份高层级的战略/愿景文档（先完成产品愿景/北极星目标工作）。
- 你需要深度的工程架构设计（API、schema、扩容、可靠性）而非产品交互层面的共识。
- 你只需要像素级精准的UI mock图（本文档产出的是规格和结构化指导，而非最终视觉稿）。
Inputs
输入要求
Minimum required
- Feature/change: 1–2 sentence description
- Target users + primary use case (happy path)
- Platform(s): web / iOS / Android / desktop (call out mobile explicitly)
- Goals + non-goals (v1 boundaries)
- Constraints: timeline, dependencies, policy/legal/privacy, technical constraints
- Success metrics (1–3) + guardrails (2–5)
Missing-info strategy
- Ask up to 5 questions from references/INTAKE.md, then proceed.
- If key info remains missing, state assumptions explicitly and provide 2–3 options (scope/flows/prototype approach).
必填信息
- 功能/变更：1-2句话描述
- 目标用户+核心使用场景（理想路径）
- 平台：网页/iOS/Android/桌面端（明确标注移动端）
- 目标与非目标（v1版本边界）
- 约束条件：时间线、依赖项、政策/法律/隐私要求、技术限制
- 成功指标（1-3个）+ 防护指标（2-5个）
缺失信息处理策略
- 从references/INTAKE.md中最多提出5个问题，然后推进工作。
- 如果关键信息仍缺失，明确说明假设条件，并提供2-3个选项（范围/流程/原型方案）。
Outputs (deliverables)
输出交付物
Produce a Spec & Design Doc Pack in Markdown (in-chat; or as files if the user requests):
- Context snapshot (problem, why now, goals/non-goals, constraints, stakeholders)
- Low‑fidelity diagram of the moving pieces (≤10) + key decisions
- User flows + states (happy path + top edge cases) with clear entry/exit points
- Prototype brief (what to prototype, fidelity, timebox, data realism, success criteria)
- Requirements + acceptance criteria (testable; must/should/could)
- Measurement plan (metrics → data/events → owner → cadence)
- Risks / Open questions / Next steps (always included)
Templates: references/TEMPLATES.md
生成一份Markdown格式的规格与设计文档包（可直接在对话中呈现；若用户要求，也可作为文件交付）：
- 上下文快照（问题、当前背景、目标/非目标、约束条件、相关干系人）
- low-fidelity图（展示不超过10个核心模块）+ 关键决策说明
- 用户流程+状态（理想路径+主要边缘场景），包含清晰的进入/退出节点
- 原型简介（原型内容、保真度、时间限制、数据真实性、成功标准）
- 需求+验收标准（可测试；分为必须/应该/可选三个层级）
- 度量计划（指标→数据/事件→负责人→频率）
- 风险/待解决问题/下一步行动（必须包含）
模板参考：references/TEMPLATES.md
Workflow (8 steps)
工作流程（8个步骤）
1) Choose the smallest artifact set that unblocks the team
1) 选择能为团队扫清障碍的最小交付物组合
- Inputs: User request + constraints.
- Actions: Decide whether to deliver: (a) Spec & Design Doc only, or (b) Spec & Design Doc + Prototype Brief emphasis (feel-critical).
- Outputs: Artifact selection + rationale.
- Checks: Artifacts match the decision being made (alignment vs build execution vs interaction feel).
- 输入：用户需求+约束条件。
- 行动：决定交付内容：(a) 仅规格与设计文档，或(b) 规格与设计文档+重点突出的原型简介（体验关键型场景）。
- 输出：交付物选择结果+理由。
- 检查项：交付物与当前要做的决策匹配（对齐共识/开发执行/交互体验）。
2) Intake + context snapshot
2) 信息收集+上下文快照
- Inputs: references/INTAKE.md.
- Actions: Ask up to 5 questions; confirm audience/DRI, platform(s), constraints, and success metrics/guardrails.
- Outputs: Context snapshot section.
- Checks: You can state the problem, user, and success measure in 1–2 sentences.
- 输入：references/INTAKE.md。
- 行动：最多提出5个问题；确认受众/负责人、平台、约束条件、成功指标/防护指标。
- 输出：上下文快照章节。
- 检查项：你能在1-2句话内说明问题、用户群体和成功衡量标准。
3) Lock scope boundaries (and define “tap budget” if mobile)
3) 锁定范围边界（若为移动端则定义“点击预算”）
- Inputs: Context snapshot.
- Actions: Write goals, non-goals, out-of-scope, assumptions, dependencies. For mobile flows, define a “tap budget” (max taps to value) and where attention is most fragile.
- Outputs: Scope boundaries + (optional) tap budget.
- Checks: “What we are NOT doing” is explicit; mobile value path has a clear tap target.
- 输入：上下文快照。
- 行动：撰写目标、非目标、超出范围内容、假设条件、依赖项。对于移动端流程，定义“点击预算”（获取价值所需的最大点击次数）以及注意力最容易分散的节点。
- 输出：范围边界+（可选）点击预算。
- 检查项：“我们不做什么”明确清晰；移动端价值路径有明确的点击目标。
4) Draft the low‑fidelity diagram (the “shaping” output)
4) 起草low-fidelity图（梳理型输出）
- Inputs: Scope + constraints.
- Actions: Produce a diagram that shows the moving pieces (≤10), data/hand-offs, and where UX decisions matter. Avoid pixel-level UI; prefer clarity of structure.
- Outputs: Low‑fidelity diagram + annotated decisions.
- Checks: A partner can say “I know what to build” without a meeting.
- 输入：范围+约束条件。
- 行动：生成展示核心模块（≤10个）、数据/交接节点以及UX决策关键节点的图。避免像素级UI细节；优先保证结构清晰。
- 输出：low-fidelity图+标注的决策说明。
- 检查项：协作方无需开会就能明确“需要开发什么”。
5) Specify user flows + states (make edge cases concrete)
5) 明确用户流程+状态（将边缘场景具体化）
- Inputs: Diagram + use case(s).
- Actions: Document entry points, happy path, and top edge cases; include error/empty/loading states, permissions, and copy notes where ambiguity causes bugs.
- Outputs: Flow + state table(s).
- Checks: Another person can role-play the flow; each edge case has an intended outcome.
- 输入：low-fidelity图+使用场景。
- 行动：记录进入节点、理想路径和主要边缘场景；包含错误/空/加载状态、权限说明以及可能引发bug的模糊文案注释。
- 输出：流程+状态表格。
- 检查项：其他人可以模拟整个流程；每个边缘场景都有明确的预期结果。
6) Write the prototype brief (only where “feel” matters)
6) 撰写原型简介（仅适用于体验关键型场景）
- Inputs: Flows/states + unknowns.
- Actions: Identify the 1–3 riskiest interaction uncertainties; specify prototype type (low-fi, hi-fi, or in-code), timebox, realism (use real data where possible), and what “good” feels like.
- Outputs: Prototype brief.
- Checks: Prototype plan is testable (scenarios + success criteria), and explicitly disposable if using throwaway code.
- 输入：流程/状态+未知项。
- 行动：识别1-3个风险最高的交互不确定性；明确原型类型（low-fi、高保真或代码级）、时间限制、真实性（尽可能使用真实数据）以及“良好体验”的标准。
- 输出：原型简介。
- 检查项：原型计划可测试（包含场景+成功标准），若使用临时代码需明确说明可丢弃。
7) Convert into testable requirements + acceptance criteria
7) 转化为可测试的需求+验收标准
- Inputs: Flows/states + prototype learnings (if any).
- Actions: Write requirements with acceptance criteria (must/should/could). Include non-functional needs (accessibility, performance, privacy) and instrumentation needs.
- Outputs: Requirements section.
- Checks: Engineering/QA can derive test cases without re-interpreting intent.
- 输入：流程/状态+原型学习成果（如有）。
- 行动：撰写包含验收标准（必须/应该/可选）的需求。包含非功能性需求（可访问性、性能、隐私）和埋点需求。
- 输出：需求章节。
- 检查项：开发/QA团队无需重新解读意图就能推导测试用例。
8) Quality gate + finalize for circulation
8) 质量校验+最终定稿用于分发
- Inputs: Full draft pack.
- Actions: Run references/CHECKLISTS.md and score with references/RUBRIC.md. Add Risks/Open questions/Next steps and clearly mark decisions vs assumptions.
- Outputs: Final Spec & Design Doc Pack (shareable as-is).
- Checks: Owners, metrics, and open questions are explicit; the diagram + flows remove the biggest ambiguities.
- 输入：完整的文档草稿包。
- 行动：使用references/CHECKLISTS.md进行检查，并通过references/RUBRIC.md进行评分。添加风险/待解决问题/下一步行动，并明确标注决策与假设条件。
- 输出：最终版规格与设计文档包（可直接分享）。
- 检查项：负责人、指标和待解决问题明确清晰；low-fi图+流程消除了最大的歧义点。
Quality gate (required)
质量校验（必填）
- Use references/CHECKLISTS.md and references/RUBRIC.md.
- Always include: Risks, Open questions, Next steps.
- 使用references/CHECKLISTS.md和references/RUBRIC.md。
- 必须包含：风险、待解决问题、下一步行动。
Examples
示例
Example 1 (mobile flow): “Write a spec + design doc for a new ‘invite friends’ flow in our iOS app. Goal: increase successful invites; minimize taps to first value.”
Expected: tap budget + flow/state tables, a low-fi diagram of screens/transitions, and a prototype brief for the critical interaction.
Expected: tap budget + flow/state tables, a low-fi diagram of screens/transitions, and a prototype brief for the critical interaction.
Example 2 (B2B web feature): “Create a design doc/spec for ‘bulk edit roles’ for admins. Include edge cases and acceptance criteria.”
Expected: permissions-focused flows/states, requirements with acceptance criteria, and a measurement plan.
Expected: permissions-focused flows/states, requirements with acceptance criteria, and a measurement plan.
Boundary example: “Write a spec to ‘improve engagement’ (no product context, no user, no success metric).”
Response: ask the minimum intake questions; if still missing, provide 2–3 scoped options + assumptions and recommend upstream discovery before committing to a spec.
Response: ask the minimum intake questions; if still missing, provide 2–3 scoped options + assumptions and recommend upstream discovery before committing to a spec.
示例1（移动端流程）：“为我们iOS应用中的新‘邀请好友’流程编写规格+设计文档。目标：提升成功邀请数；最小化获取首次价值所需的点击次数。”
预期产出：点击预算+流程/状态表格、展示页面/跳转的low-fi图、针对关键交互的原型简介。
预期产出：点击预算+流程/状态表格、展示页面/跳转的low-fi图、针对关键交互的原型简介。
示例2（B2B网页功能）：“为管理员的‘批量编辑角色’功能创建设计文档/规格。包含边缘场景和验收标准。”
预期产出：聚焦权限的流程/状态、包含验收标准的需求、度量计划。
预期产出：聚焦权限的流程/状态、包含验收标准的需求、度量计划。
边界示例：“编写一份规格文档来‘提升用户参与度’（无产品上下文、无用户信息、无成功指标）。”
回应：提出最少的必填信息问题；若信息仍缺失，提供2-3个限定范围的选项+假设条件，并建议先完成上游发现工作再推进规格文档编写。
回应：提出最少的必填信息问题；若信息仍缺失，提供2-3个限定范围的选项+假设条件，并建议先完成上游发现工作再推进规格文档编写。