requirements-specification
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseRequirements & Specification Skill
需求与规格说明技能
Transform customer insights into clear, detailed specifications that engineering can build from. Master user story writing, define acceptance criteria, and manage scope ruthlessly.
将客户洞察转化为开发团队可据此构建的清晰、详细的规格说明。掌握用户故事编写方法，明确验收标准，并严格管理范围。
User Story Writing (INVEST Format)
用户故事编写（INVEST 格式）
INVEST Principles
INVEST 原则
I - Independent (minimal dependencies)
N - Negotiable (details can be discussed)
V - Valuable (delivers customer value)
E - Estimable (team can estimate effort)
S - Small (can complete in 1-2 sprints)
T - Testable (clear success criteria)
I - 独立性（最小化依赖关系）
N - 可协商性（细节可讨论）
V - 价值性（为客户传递价值）
E - 可估算性（团队可估算工作量）
S - 小型化（可在1-2个迭代内完成）
T - 可测试性（明确成功标准）
User Story Template
用户故事模板
As a [user role]
I want [action/capability]
So that [benefit/outcome]
Acceptance Criteria:
Given [context]
When [user action]
Then [expected result]As a [用户角色]
I want [操作/能力]
So that [收益/结果]
Acceptance Criteria:
Given [场景]
When [用户操作]
Then [预期结果]Good vs Bad Examples
正反示例
Bad Story:
As a user
I want a better dashboard
So that I can see my dataProblem: Too vague, not testable, too large
Good Story:
As a project manager
I want to see all tasks assigned to me in the last 24 hours
So that I can track what happened while I was offline
Acceptance Criteria:
Given I'm logged in
When I view the Home dashboard
Then I see a "Recent Tasks" section
And it shows tasks assigned to me from last 24 hours
And tasks are sorted by assignment time (newest first)
And clicking a task opens the task detail page反面案例：
As a user
I want a better dashboard
So that I can see my data问题：过于模糊、不可测试、范围过大
正面案例：
As a project manager
I want to see all tasks assigned to me in the last 24 hours
So that I can track what happened while I was offline
Acceptance Criteria:
Given I'm logged in
When I view the Home dashboard
Then I see a "Recent Tasks" section
And it shows tasks assigned to me from last 24 hours
And tasks are sorted by assignment time (newest first)
And clicking a task opens the task detail pageAcceptance Criteria (BDD Format)
验收标准（BDD 格式）
Scenario Template
场景模板
Scenario: [Specific user action]
Given [initial context/state]
When [user performs action]
Then [expected result]
And [additional verification]Scenario: [具体用户操作]
Given [初始场景/状态]
When [用户执行操作]
Then [预期结果]
And [额外验证项]Example: Password Reset Feature
示例：密码重置功能
Scenario: User resets password with valid email
Given I'm on the login page
And I'm not logged in
When I click "Forgot Password?"
And enter my email address
And click "Send Reset Email"
Then I see message "Check your email for reset link"
And a password reset email is sent to that address
And the email contains a valid reset link
Scenario: User uses expired reset link
Given I received a password reset email
And the reset link is more than 24 hours old
When I click the reset link
Then I see "Link has expired"
And I'm offered to request a new reset link
Scenario: Password doesn't meet requirements
Given I'm on password reset page
When I enter password "123"
Then I see error "Password must be 8+ characters"
And the form doesn't submitScenario: 用户使用有效邮箱重置密码
Given I'm on the login page
And I'm not logged in
When I click "Forgot Password?"
And enter my email address
And click "Send Reset Email"
Then I see message "Check your email for reset link"
And a password reset email is sent to that address
And the email contains a valid reset link
Scenario: 用户使用过期的重置链接
Given I received a password reset email
And the reset link is more than 24 hours old
When I click the reset link
Then I see "Link has expired"
And I'm offered to request a new reset link
Scenario: 密码不符合要求
Given I'm on password reset page
When I enter password "123"
Then I see error "Password must be 8+ characters"
And the form doesn't submitRequirements Document Structure
需求文档结构
Executive Summary (1 page)
执行摘要（1页）
- Overview of feature/product
- Business goal/context
- Key benefits
- Timeline
- Success metrics
- 功能/产品概述
- 业务目标/背景
- 核心收益
- 时间线
- 成功指标
Requirements Overview (5-10 pages)
需求概述（5-10页）
Functional Requirements
- What the system must do
- Features and capabilities
- User interactions
- Data handling
Non-Functional Requirements
- Performance (response time < 2s)
- Scalability (support 10K concurrent users)
- Security (encrypt PII)
- Availability (99.9% uptime)
- Accessibility (WCAG AA compliance)
Business Requirements
- Why we're building this
- Business metrics
- Customer need
- Competitive advantage
Constraints
- Technical constraints
- Budget constraints
- Timeline constraints
- Resource constraints
功能性需求
- 系统必须实现的功能
- 特性与能力
- 用户交互流程
- 数据处理规则
非功能性需求
- 性能（响应时间<2秒）
- 可扩展性（支持10000并发用户）
- 安全性（加密个人可识别信息PII）
- 可用性（99.9% uptime）
- 可访问性（符合WCAG AA标准）
业务需求
- 开发该功能的原因
- 业务指标
- 客户需求
- 竞争优势
约束条件
- 技术约束
- 预算约束
- 时间线约束
- 资源约束
User Stories & Epics (20-50 pages)
用户故事与史诗（20-50页）
Structure:
- Epic: Large initiative grouping related stories
- User Stories: Individual features (10-20 stories per epic)
- Tasks: Engineering breakdown (if needed)
Each Story Includes:
- Story ID and title
- As a... I want... so that...
- Acceptance criteria (3-8 scenarios)
- Story points estimate
- Dependencies
- Design reference (wireframe/mockup)
- Note/clarifications
结构：
- Epic（史诗）：包含相关故事的大型倡议
- 用户故事：单个功能点（每个史诗包含10-20个故事）
- 任务：开发任务拆分（如有需要）
每个故事包含：
- 故事ID与标题
- As a... I want... so that... 格式内容
- 验收标准（3-8个场景）
- 故事点估算
- 依赖关系
- 设计参考（线框图/原型图）
- 备注/说明
Use Cases & Flows (10-20 pages)
用例与流程（10-20页）
Use Case Template:
Use Case: [Use Case Name]
Primary Actor: [User role]
Precondition: [State before action]
Main Flow:
1. User does X
2. System responds with Y
3. User does Z
4. System returns result
Alternative Flows:
3a. If data invalid
- System shows error
- User corrects and resubmits用例模板：
Use Case: [用例名称]
Primary Actor: [用户角色]
Precondition: [操作前状态]
Main Flow:
1. 用户执行X操作
2. 系统返回Y结果
3. 用户执行Z操作
4. 系统返回最终结果
Alternative Flows:
3a. 如果数据无效
- 系统显示错误信息
- 用户修正后重新提交Data Models (10 pages)
数据模型（10页）
Entity Relationship Diagram
- Entities (User, Post, Comment)
- Relationships (User creates Posts)
- Attributes (Post title, content, creation_date)
- Primary keys, foreign keys
实体关系图
- 实体（用户、帖子、评论）
- 关系（用户创建帖子）
- 属性（帖子标题、内容、创建日期）
- 主键、外键
UI/Wireframes (Attached)
UI/线框图（附件）
- User interface mockups
- User flows and navigation
- Key interactions
- 用户界面原型
- 用户流程与导航
- 核心交互
Scope Management
范围管理
MVP vs Nice-to-Have
MVP与锦上添花功能
MoSCoW Method:
MUST Have (Non-negotiable)
- Core functionality
- Without these: product won't work
- Must launch with these
- Example: User login, basic content view
SHOULD Have (Important but not critical)
- Enhance user experience
- Value add
- If time allows
- Example: Advanced search, saved preferences
COULD Have (Nice-to-have)
- Polish features
- Low priority
- Do if extra time/budget
- Example: Dark mode, animations
WON'T Have (Explicitly out of scope)
- Clear for future
- Helps say "no" to stakeholders
- Plan for later version
- Example: Mobile app (launching web first)
MoSCoW方法：
MUST Have（必须具备）（不可协商）
- 核心功能
- 缺少则产品无法正常工作
- 必须随版本首发
- 示例：用户登录、基础内容查看
SHOULD Have（应该具备）（重要但非关键）
- 提升用户体验
- 增值功能
- 时间允许则实现
- 示例：高级搜索、保存偏好设置
COULD Have（可以具备）（锦上添花）
- 优化特性
- 低优先级
- 有额外时间/预算时实现
- 示例：深色模式、动画效果
WON'T Have（暂不具备）（明确排除在范围外）
- 为未来版本预留
- 帮助向利益相关者说“不”
- 计划在后续版本实现
- 示例：移动端应用（先发布网页版）
Scope Creep Prevention
范围蔓延预防
Red Flags:
- "Can we just add...?"
- "This would be better if..."
- "What about also including..."
- "One more thing..."
Responses:
- "That's a great idea. Let's add it to the roadmap for Q2."
- "That would add 3 weeks. What would you deprioritize?"
- "That's outside current scope. Document for next phase."
预警信号：
- “我们能不能再加个...？”
- “如果...的话会更好”
- “要不要同时包含...？”
- “还有一件事...”
应对话术：
- “这是个很棒的想法，我们把它加入Q2的路线图吧。”
- “这会增加3周的开发时间，您希望优先放弃哪项功能？”
- “这超出了当前范围，我们记录下来留到下一阶段再考虑。”
Change Management
变更管理
Change Request Process:
- Document the change
- Assess impact (time, complexity)
- Present trade-offs
- Get stakeholder decision
- Update requirements document
- Communicate to team
变更请求流程：
- 记录变更内容
- 评估影响（时间、复杂度）
- 呈现取舍方案
- 获取利益相关者决策
- 更新需求文档
- 向团队同步信息
Common Pitfalls
常见陷阱
Too Vague
过于模糊
❌ "Improve performance"
✅ "Reduce page load time from 4s to under 2s"
❌ “提升性能”
✅ “将页面加载时间从4秒缩短至2秒以内”
No Success Criteria
缺少成功标准
❌ "Build dashboard"
✅ "Build dashboard showing active users in last 24h with 95% accuracy"
❌ “构建仪表盘”
✅ “构建可显示过去24小时活跃用户的仪表盘，数据准确率达95%”
Missing Context
缺少上下文
❌ "Fix the bug"
✅ "When searching with special characters, results show error. Fix to handle special chars."
❌ “修复bug”
✅ “当使用特殊字符搜索时，结果页面显示错误。修复该问题以支持特殊字符处理。”
Over-Specifying
过度指定实现细节
❌ "Use Redux with saga middleware for state management"
✅ "State changes must be traceable and debuggable"
❌ “使用Redux搭配saga中间件进行状态管理”
✅ “状态变更必须可追踪、可调试”
Ambiguous Acceptance Criteria
验收标准模糊
❌ "System should be fast"
✅ "API response time < 200ms for 95th percentile"
❌ “系统应该足够快”
✅ “95%分位的API响应时间<200毫秒”
Requirements Review Checklist
需求评审检查清单
- ✓ Each requirement is testable
- ✓ No requirement specifies implementation
- ✓ Dependencies identified and documented
- ✓ Acceptance criteria clear and complete
- ✓ Engineering has estimated effort
- ✓ Design mockups provided
- ✓ Data models documented
- ✓ Edge cases considered
- ✓ Scope clearly defined (MVP vs future)
- ✓ Success metrics identified
- ✓ Timeline realistic
- ✓ Reviewed by engineering lead
- ✓ Reviewed by design lead
- ✓ Stakeholder aligned
- ✓ 每项需求均可测试
- ✓ 没有需求指定具体实现方式
- ✓ 依赖关系已识别并记录
- ✓ 验收标准清晰完整
- ✓ 开发团队已估算工作量
- ✓ 提供了设计原型
- ✓ 数据模型已文档化
- ✓ 考虑了边缘案例
- ✓ 范围明确定义（MVP vs 未来版本）
- ✓ 已确定成功指标
- ✓ 时间线符合实际
- ✓ 已通过开发负责人评审
- ✓ 已通过设计负责人评审
- ✓ 利益相关者达成一致
Troubleshooting
问题排查
Yaygın Hatalar & Çözümler
常见错误与解决方案
| Hata | Olası Sebep | Çözüm |
|---|---|---|
| Story çok büyük | Epic olarak yazıldı | Story breakdown |
| AC belirsiz | Vague criteria | Given/When/Then format |
| Scope creep | Change mgmt yok | Change request process |
| Missing edge cases | Happy path focus | Edge case workshop |
| 错误 | 可能原因 | 解决方案 |
|---|---|---|
| 故事范围过大 | 被写成了Epic | 拆分故事 |
| 验收标准不明确 | 标准模糊 | 使用Given/When/Then格式 |
| 范围蔓延 | 无变更管理流程 | 启用变更请求流程 |
| 遗漏边缘案例 | 仅关注正常流程 | 开展边缘案例研讨会 |
Debug Checklist
调试检查清单
[ ] Her story INVEST criteria geçiyor mu?
[ ] Acceptance criteria testable mı?
[ ] Non-functional requirements tanımlı mı?
[ ] Dependencies documented mı?
[ ] Engineering review yapıldı mı?[ ] 每个故事是否符合INVEST标准？
[ ] 验收标准是否可测试？
[ ] 非功能性需求是否已定义？
[ ] 依赖关系是否已记录？
[ ] 是否已完成开发评审？Recovery Procedures
恢复流程
- Ambiguous Requirements → Clarification meeting
- Scope Creep → Trade-off matrix
- Missing Feasibility → Engineering spike
Write clear requirements and avoid 90% of project problems!
- 需求模糊 → 召开澄清会议
- 范围蔓延 → 使用取舍矩阵评估
- 可行性缺失 → 开展技术调研
编写清晰的需求，可避免90%的项目问题！