plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Scope

规格文档

Turn ideas into specs that AI tools can execute and stakeholders can evaluate.

将想法转化为AI工具可执行、利益相关者可评估的规格文档。

When to Use This Skill

何时使用本技能

Starting any new feature or product
Before hiring developers or estimating costs
When AI keeps building the wrong thing (unclear spec)
When stakeholders need to review scope and budget

启动任何新功能或新产品时
雇佣开发人员或估算成本之前
当AI始终构建出不符合预期的产物时（规格文档模糊）
当利益相关者需要审核项目范围和预算时

Choose Your Approach

选择合适的方案

Quick Feature Spec (10-15 minutes)

Use for: Single features, iterations, additions
Give to: AI tools (Claude Code, Lovable, Replit) to build directly
See: QUICK-SPEC.md

Full Project Scope (1-2 hours)

Use for: New products, major releases, stakeholder review
Give to: Contractors, team members, budget planning
See: PROJECT-SCOPE.md

快速功能规格文档（10-15分钟）

适用场景：单一功能、迭代优化、功能新增
交付对象：AI工具（Claude Code、Lovable、Replit）直接用于构建
参考文档：QUICK-SPEC.md

完整项目范围文档（1-2小时）

适用场景：新产品开发、重大版本发布、利益相关者审核
交付对象：承包商、团队成员、用于预算规划
参考文档：PROJECT-SCOPE.md

Quick Feature Spec Workflow

快速功能规格文档工作流程

Use this checklist and complete each section:

Feature Spec Progress:
- [ ] Write what users will do (2-3 sentences)
- [ ] Show what it looks like (reference, screenshot, or description)
- [ ] Define happy path (3-5 steps)
- [ ] List edge cases (2-4 scenarios)
- [ ] Specify out of scope items
- [ ] Save to docs/specs/YYYY-MM-DD-feature-name.md

使用以下清单完成每个部分：

功能规格文档进度：
- [ ] 描述用户操作（2-3句话）
- [ ] 展示界面效果（参考案例、截图或文字描述）
- [ ] 定义正常流程（3-5个步骤）
- [ ] 列出边缘情况（2-4种场景）
- [ ] 明确排除范围的内容
- [ ] 保存至docs/specs/YYYY-MM-DD-feature-name.md

Section 1: What Users Will Do

第一部分：用户操作描述

Write 2-3 sentences describing user actions and outcomes.

Template:

Users can [ACTION] to [OUTCOME].
When they [DO THIS], they see [WHAT HAPPENS].
If [EDGE CASE], then [WHAT HAPPENS].

Example:

Users sign up with email/password, receive confirmation email, and log in to 
see their dashboard. They can reset forgotten passwords via email link.

用2-3句话描述用户的操作及预期结果。

模板：

用户可以[操作]以达成[结果]。
当他们[执行此操作]时，会看到[对应反馈]。
如果出现[边缘情况]，则[系统处理逻辑]。

示例：

用户通过邮箱/密码注册账号，收到确认邮件后登录，即可查看个人仪表盘。他们可通过邮件链接重置遗忘的密码。

Section 2: What It Looks Like

第二部分：界面效果说明

Pick ONE:

Reference app: "Login like Linear - minimal, centered, email/password/button"
Screenshot/sketch: Quick mockup or phone photo
Description: "Card 400px wide, 'Welcome' header Inter 24px, two inputs, blue button"

选择以下一种方式：

参考应用：“登录界面参考Linear - 极简风格、居中布局、包含邮箱/密码输入框和按钮”
**截图/草图：**快速制作的原型或手机拍摄的照片
文字描述：“卡片宽度400px，标题为'欢迎'（Inter字体24px），包含两个输入框和蓝色按钮”

Section 3: Happy Path

第三部分：正常流程

List 3-5 steps users take to complete the task.

列出用户完成任务的3-5个步骤。

Section 4: Edge Cases

第四部分：边缘情况

List 2-4 scenarios where things don't go as planned and what happens.

Format:

- **[Scenario]:** [Response shown to user]

列出2-4种异常场景及对应的系统处理逻辑。

格式：

- **[场景]：** [展示给用户的反馈]

Section 5: Out of Scope

第五部分：排除范围

Define what you're NOT building to prevent scope creep.

For complete template and examples, see QUICK-SPEC.md

明确不需要开发的内容，避免范围蔓延。

完整模板及示例请参考QUICK-SPEC.md

Full Project Scope Workflow

完整项目范围文档工作流程

Use this checklist for comprehensive project planning:

Project Scope Progress:
- [ ] Write introduction (background, in/out of scope)
- [ ] Define user roles
- [ ] List all pages/screens
- [ ] Describe core features
- [ ] Identify integrations
- [ ] Create milestones with hour estimates
- [ ] Document assumptions and open questions
- [ ] Save to docs/specs/YYYY-MM-DD-project-name.md

使用以下清单进行全面项目规划：

项目范围文档进度：
- [ ] 撰写引言（背景、包含/排除范围）
- [ ] 定义用户角色
- [ ] 列出所有页面/界面
- [ ] 描述核心功能
- [ ] 识别集成需求
- [ ] 创建带工时估算的里程碑
- [ ] 记录假设条件和待解决问题
- [ ] 保存至docs/specs/YYYY-MM-DD-project-name.md

The 7 Required Sections

7个必填部分

Introduction - Background, in scope, out of scope
User Roles - Each role's responsibilities
Pages & Screens - Every page with one-line purpose
Core Features - Outcome-focused capabilities
Integrations - External services with complexity/risk notes
Milestones & Tasks - Phases with hour estimates
Open Questions - Assumptions and unresolved decisions

For complete template and examples, see PROJECT-SCOPE.md

引言 - 项目背景、包含范围、排除范围
用户角色 - 每个角色的职责
页面与界面 - 每个页面的核心用途（一句话描述）
核心功能 - 以结果为导向的功能说明
集成需求 - 外部服务集成，标注复杂度/风险
里程碑与任务 - 项目阶段及工时估算
待解决问题 - 假设条件和未决议题

完整模板及示例请参考PROJECT-SCOPE.md

Using Your Spec With AI Tools

如何结合AI工具使用规格文档

Claude Code / Cursor:

Build this feature: [paste Quick Feature Spec]

Lovable / Replit / Bolt:

Paste Quick Feature Spec as initial prompt
Break complex features into smaller chunks
Iterate: "Close, but error message should say X not Y"

Hiring contractors:

Send Full Project Scope
Ask: "What's unclear? What would you change?"
Get hour estimate and compare to yours

Claude Code / Cursor：

构建此功能：[粘贴快速功能规格文档]

Lovable / Replit / Bolt：

将快速功能规格文档作为初始提示词粘贴
将复杂功能拆分为多个小模块
迭代优化：“接近预期，但错误提示应显示X而非Y”

雇佣承包商时：

发送完整项目范围文档
询问：“哪些内容不明确？你会做出哪些调整？”
获取工时估算并与自己的估算对比

Common Mistakes

常见错误

Mistake	Fix
"Build a dashboard"	Describe what's ON dashboard and what each thing does
Describing HOW to code it	Describe WHAT it should do
Forgetting mobile	Add "Works on mobile" to every spec
Skipping edge cases	Define what happens when things break
No out-of-scope	Prevents scope creep

常见错误	修复方案
“搭建一个仪表盘”	描述仪表盘上的具体内容及每个元素的功能
描述编码实现方式	描述功能应该实现的效果
忘记移动端适配	在每个规格文档中添加“支持移动端”
忽略边缘情况	定义出现异常时的处理逻辑
未明确排除范围	明确排除范围以避免蔓延

When You're Stuck

遇到瓶颈时的解决方法

"I don't know what I want yet"

Use competitor's product for 20 minutes
Screenshot 3 things you like
Write: "I want these 3 things, but simpler"

"AI keeps building the wrong thing"

Your spec is vague
Use templates in QUICK-SPEC.md or PROJECT-SCOPE.md
Fill in EVERY section

“我不知道自己想要什么”

使用竞品产品20分钟
截图3个你喜欢的功能点
写下：“我想要这3个功能，但更简洁”

“AI始终构建出不符合预期的产物”

你的规格文档不够明确
使用QUICK-SPEC.md或PROJECT-SCOPE.md中的模板
填写所有必填部分

After Scoping

规格文档完成后

Save as:

docs/specs/YYYY-MM-DD-feature-name.md

Then:

Quick Feature Spec → Give directly to AI tool
Full Project Scope → Review with stakeholders/contractors first

保存路径：

docs/specs/YYYY-MM-DD-feature-name.md

后续操作：

快速功能规格文档 → 直接交付给AI工具使用
完整项目范围文档 → 先与利益相关者/承包商审核

Success Looks Like

成功标准

✅ AI builds it right first time (or very close) ✅ Contractors give realistic estimates without surprises
✅ Edge cases don't surprise you in production ✅ Stakeholders know exactly what they're getting

✅ AI首次构建即符合预期（或接近预期） ✅ 承包商给出符合实际的估算，无意外情况 ✅ 边缘情况在生产环境中未造成突发问题 ✅ 利益相关者清楚了解最终交付产物