Back to Details

requirements-engineering

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Requirements Engineering

需求工程

Master the art of capturing what needs to be built before diving into how to build it. This skill teaches the EARS (Easy Approach to Requirements Syntax) format for creating clear, testable requirements.
掌握在深入研究如何构建之前，先明确需要构建什么的技巧。本技能将教授用于创建清晰、可测试需求的EARS（Easy Approach to Requirements Syntax，需求语法简易方法）格式。

When to Use This Skill

何时使用本技能

Use requirements engineering when:
  • Starting any new feature or project
  • Clarifying ambiguous stakeholder requests
  • Creating acceptance criteria for user stories
  • Documenting system behavior for testing
  • Ensuring all team members share understanding
在以下场景使用需求工程：
  • 启动任何新功能或项目时
  • 澄清利益相关者模糊的需求请求时
  • 为用户故事创建验收标准时
  • 为测试记录系统行为时
  • 确保所有团队成员对需求达成共识时

The EARS Format

EARS格式

EARS provides consistent patterns for writing requirements that are specific, testable, and unambiguous.
EARS提供了一致的模式，用于编写具体、可测试且无歧义的需求。

Basic Patterns

基础模式

Event-Response (Most Common):
WHEN [triggering event] THEN [system] SHALL [required response]
Conditional Behavior:
IF [precondition is met] THEN [system] SHALL [required response]
Complex Conditions:
WHEN [event] AND [additional condition] THEN [system] SHALL [response]
Optional Conditions:
WHEN [event] OR [alternative event] THEN [system] SHALL [response]
事件-响应（最常用）：
WHEN [触发事件] THEN [系统] SHALL [所需响应]
条件行为：
IF [前置条件满足] THEN [系统] SHALL [所需响应]
复杂条件：
WHEN [事件] AND [附加条件] THEN [系统] SHALL [响应]
可选条件：
WHEN [事件] OR [备选事件] THEN [系统] SHALL [响应]

Advanced Patterns

高级模式

State-Based:
WHEN [system is in specific state] THEN [system] SHALL [behavior]
Performance:
WHEN [user action] THEN [system] SHALL [respond within X seconds/milliseconds]
Security:
IF [authentication condition] THEN [system] SHALL [security response]
基于状态：
WHEN [系统处于特定状态] THEN [系统] SHALL [行为]
性能：
WHEN [用户操作] THEN [系统] SHALL [在X秒/毫秒内响应]
安全：
IF [身份验证条件满足] THEN [系统] SHALL [安全响应]

Step-by-Step Process

分步流程

Step 1: Capture User Stories

步骤1：捕获用户故事

Format: As a [role], I want [feature], so that [benefit]
Focus on:
  • Who is the user? (role)
  • What do they want to accomplish? (feature)
  • Why does it matter? (benefit/value)
Example:
markdown
As a returning customer, I want to save my payment methods, so that I can checkout faster in the future.
格式：作为[角色]，我想要[功能]，以便[收益]
重点关注：
  • 用户是谁？（角色）
  • 他们想要完成什么？（功能）
  • 这为什么重要？（收益/价值）
示例：
markdown
作为回头客，我想要保存我的支付方式，以便未来能更快完成结账。

Step 2: Generate Acceptance Criteria

步骤2：生成验收标准

For each user story, define specific acceptance criteria using EARS:
Example for payment methods:
markdown
**User Story:** As a returning customer, I want to save my payment methods, so that I can checkout faster.

**Acceptance Criteria:**
1. WHEN user adds a valid credit card THEN system SHALL securely store card details
2. WHEN user adds a card with invalid number THEN system SHALL display validation error
3. WHEN user has saved cards THEN system SHALL display list during checkout
4. WHEN user selects saved card THEN system SHALL pre-fill payment form
5. WHEN user deletes saved card THEN system SHALL remove card from list
6. IF user is not authenticated THEN system SHALL redirect to login before saving card
7. WHEN user adds card THEN system SHALL mask all but last 4 digits in display
针对每个用户故事，使用EARS格式定义具体的验收标准：
支付方式功能示例：
markdown
**用户故事：** 作为回头客，我想要保存我的支付方式，以便更快完成结账。

**验收标准：**
1. WHEN 用户添加有效的信用卡 THEN 系统 SHALL 安全存储卡片详情
2. WHEN 用户添加卡号无效的卡片 THEN 系统 SHALL 显示验证错误
3. WHEN 用户已有已保存的卡片 THEN 系统 SHALL 在结账时显示卡片列表
4. WHEN 用户选择已保存的卡片 THEN 系统 SHALL 预填充支付表单
5. WHEN 用户删除已保存的卡片 THEN 系统 SHALL 从列表中移除该卡片
6. IF 用户未通过身份验证 THEN 系统 SHALL 在保存卡片前重定向至登录页面
7. WHEN 用户添加卡片 THEN 系统 SHALL 在显示时隐藏除最后4位以外的所有数字

Step 3: Identify Edge Cases

步骤3：识别边缘情况

For each requirement, ask:
  • What if the input is empty/null?
  • What if the input is at boundary values?
  • What if the operation fails?
  • What if the user is not authorized?
  • What if there are concurrent operations?
Edge case patterns:
markdown
**Error Handling:**
- WHEN [operation fails] THEN system SHALL [display error / retry / log]

**Boundary Conditions:**
- WHEN [value equals minimum/maximum] THEN system SHALL [specific behavior]

**Concurrent Access:**
- WHEN [multiple users access same resource] THEN system SHALL [conflict resolution]

**Empty States:**
- WHEN [collection is empty] THEN system SHALL [display empty state message]
针对每个需求，思考以下问题：
  • 如果输入为空/空值会怎样？
  • 如果输入处于边界值会怎样？
  • 如果操作失败会怎样？
  • 如果用户未获授权会怎样？
  • 如果存在并发操作会怎样？
边缘情况模式：
markdown
**错误处理：**
- WHEN [操作失败] THEN 系统 SHALL [显示错误 / 重试 / 记录日志]

**边界条件：**
- WHEN [值等于最小值/最大值] THEN 系统 SHALL [特定行为]

**并发访问：**
- WHEN [多个用户访问同一资源] THEN 系统 SHALL [冲突解决]

**空状态：**
- WHEN [集合为空] THEN 系统 SHALL [显示空状态提示]

Step 4: Validate Requirements

步骤4：验证需求

Use this checklist:
Completeness:
  • All user roles identified and addressed
  • Normal flow scenarios covered
  • Edge cases documented
  • Error cases handled
  • Business rules captured
Clarity:
  • Each requirement uses precise language
  • No ambiguous terms (fast, easy, user-friendly)
  • Technical jargon avoided or defined
  • Expected behaviors are specific
Consistency:
  • EARS format used throughout
  • Terminology consistent across requirements
  • No contradictory requirements
  • Similar scenarios handled similarly
Testability:
  • Each requirement can be verified
  • Success criteria are observable
  • Inputs and expected outputs specified
  • Performance requirements are measurable
使用以下检查清单：
完整性：
  • 已识别并覆盖所有用户角色
  • 已覆盖正常流程场景
  • 已记录边缘情况
  • 已处理错误场景
  • 已捕获业务规则
清晰度：
  • 每个需求使用精确语言
  • 无模糊术语（如快速、简单、用户友好）
  • 避免技术术语或已对其进行定义
  • 预期行为具体明确
一致性：
  • 全程使用EARS格式
  • 需求中的术语保持一致
  • 无相互矛盾的需求
  • 相似场景的处理方式一致
可测试性：
  • 每个需求可被验证
  • 成功标准可被观察
  • 已指定输入和预期输出
  • 性能需求可被衡量

Common Mistakes to Avoid

需避免的常见错误

Mistake 1: Vague Requirements

错误1：模糊需求

Bad: "System should be fast" Good: "WHEN user submits search THEN system SHALL return results within 2 seconds"
反面示例： "系统应该很快" 正面示例： "WHEN 用户提交搜索 THEN 系统 SHALL 在2秒内返回结果"

Mistake 2: Implementation Details

错误2：包含实现细节

Bad: "System shall use Redis for caching" Good: "WHEN user requests frequently accessed data THEN system SHALL return cached results"
反面示例： "系统应使用Redis进行缓存" 正面示例： "WHEN 用户请求频繁访问的数据 THEN 系统 SHALL 返回缓存结果"

Mistake 3: Missing Error Cases

错误3：遗漏错误场景

Bad: Only documenting happy path Good: Include WHEN/IF statements for all error conditions
反面示例： 仅记录正常流程 正面示例： 为所有错误条件添加WHEN/IF语句

Mistake 4: Untestable Requirements

错误4：不可测试的需求

Bad: "System should be user-friendly" Good: "WHEN new user completes onboarding THEN system SHALL require no more than 3 clicks to reach main dashboard"
反面示例： "系统应该用户友好" 正面示例： "WHEN 新用户完成引导流程 THEN 系统 SHALL 要求不超过3次点击即可进入主仪表盘"

Mistake 5: Conflicting Requirements

错误5：需求相互矛盾

Bad: Requirements that contradict each other Good: Review all requirements together, resolve conflicts explicitly
反面示例： 存在相互矛盾的需求 正面示例： 共同审查所有需求，明确解决冲突

Examples

示例

Example 1: File Upload Feature

示例1：文件上传功能

markdown
**User Story:** As a user, I want to upload files, so that I can share documents with my team.

**Acceptance Criteria:**
1. WHEN user selects file under 10MB THEN system SHALL accept file for upload
2. WHEN user selects file over 10MB THEN system SHALL display "file too large (max 10MB)" error
3. WHEN user selects unsupported file type THEN system SHALL display "unsupported format" error with list of allowed types
4. WHEN upload is in progress THEN system SHALL display progress indicator with percentage
5. WHEN upload completes successfully THEN system SHALL display success message with file link
6. WHEN upload fails due to network error THEN system SHALL display retry option
7. IF user is not authenticated THEN system SHALL redirect to login before upload
8. WHEN user uploads file with same name as existing file THEN system SHALL prompt for rename or replace

**Supported File Types:** PDF, DOC, DOCX, XLS, XLSX, PNG, JPG, GIF
**Maximum File Size:** 10MB
**Maximum Files Per Upload:** 5
markdown
**用户故事：** 作为用户，我想要上传文件，以便与团队共享文档。

**验收标准：**
1. WHEN 用户选择小于10MB的文件 THEN 系统 SHALL 接受该文件进行上传
2. WHEN 用户选择大于10MB的文件 THEN 系统 SHALL 显示“文件过大（最大10MB）”错误
3. WHEN 用户选择不支持的文件类型 THEN 系统 SHALL 显示“不支持的格式”错误并列出允许的类型
4. WHEN 上传进行中 THEN 系统 SHALL 显示带百分比的进度指示器
5. WHEN 上传成功完成 THEN 系统 SHALL 显示包含文件链接的成功提示
6. WHEN 因网络错误导致上传失败 THEN 系统 SHALL 显示重试选项
7. IF 用户未通过身份验证 THEN 系统 SHALL 在上传前重定向至登录页面
8. WHEN 用户上传与现有文件同名的文件 THEN 系统 SHALL 提示重命名或替换

**支持的文件类型：** PDF, DOC, DOCX, XLS, XLSX, PNG, JPG, GIF
**最大文件大小：** 10MB
**单次上传最大文件数：** 5个

Example 2: Search Feature

示例2：搜索功能

markdown
**User Story:** As a customer, I want to search products, so that I can find items quickly.

**Acceptance Criteria:**
1. WHEN user enters search term THEN system SHALL display matching products
2. WHEN search returns results THEN system SHALL show result count
3. WHEN search returns no results THEN system SHALL display "no products found" with suggestions
4. WHEN user searches with special characters THEN system SHALL sanitize input and search
5. WHEN user submits empty search THEN system SHALL display validation message
6. WHEN results exceed 20 items THEN system SHALL paginate with 20 items per page
7. WHEN user searches THEN system SHALL return results within 2 seconds
8. WHEN user types in search box THEN system SHALL show autocomplete suggestions after 3 characters

**Search Fields:** Product name, description, category, SKU
**Minimum Search Length:** 2 characters
markdown
**用户故事：** 作为客户，我想要搜索产品，以便快速找到所需商品。

**验收标准：**
1. WHEN 用户输入搜索关键词 THEN 系统 SHALL 显示匹配的产品
2. WHEN 搜索返回结果 THEN 系统 SHALL 显示结果数量
3. WHEN 搜索无结果返回 THEN 系统 SHALL 显示“未找到产品”提示及建议
4. WHEN 用户使用特殊字符搜索 THEN 系统 SHALL 清理输入后再执行搜索
5. WHEN 用户提交空搜索 THEN 系统 SHALL 显示验证提示
6. WHEN 结果超过20条 THEN 系统 SHALL 进行分页，每页显示20条
7. WHEN 用户执行搜索 THEN 系统 SHALL 在2秒内返回结果
8. WHEN 用户在搜索框中输入 THEN 系统 SHALL 在输入3个字符后显示自动补全建议

**搜索字段：** 产品名称、描述、分类、SKU
**最小搜索长度：** 2个字符

Requirements Document Template

需求文档模板

markdown
undefined
markdown
undefined

Requirements Document: [Feature Name]

需求文档：[功能名称]

Overview

概述

[Brief description of the feature and its purpose]
[对功能及其用途的简要描述]

User Roles

用户角色

  • [Role 1]: [Description of this user type]
  • [Role 2]: [Description of this user type]
  • [角色1]：[该用户类型的描述]
  • [角色2]：[该用户类型的描述]

Requirements

需求

Requirement 1: [Name]

需求1：[名称]

User Story: As a [role], I want [feature], so that [benefit]
Acceptance Criteria:
  1. WHEN [event] THEN system SHALL [response]
  2. IF [condition] THEN system SHALL [response]
  3. WHEN [event] AND [condition] THEN system SHALL [response]
Edge Cases:
  • [Edge case 1 and how it's handled]
  • [Edge case 2 and how it's handled]
用户故事： 作为[角色]，我想要[功能]，以便[收益]
验收标准：
  1. WHEN [事件] THEN 系统 SHALL [响应]
  2. IF [条件] THEN 系统 SHALL [响应]
  3. WHEN [事件] AND [条件] THEN 系统 SHALL [响应]
边缘情况：
  • [边缘情况1及其处理方式]
  • [边缘情况2及其处理方式]

Requirement 2: [Name]

需求2：[名称]

[Continue pattern...]
[遵循上述模式继续...]

Non-Functional Requirements

非功能性需求

  • Performance: [Specific metrics]
  • Security: [Security requirements]
  • Accessibility: [Accessibility standards]
  • 性能： [具体指标]
  • 安全： [安全需求]
  • 可访问性： [可访问性标准]

Out of Scope

范围外内容

  • [Items explicitly not included in this feature]
  • [明确不包含在本功能中的项]

Open Questions

待解决问题

  • [Questions that need stakeholder input]
undefined
  • [需要利益相关者提供输入的问题]
undefined

Next Steps

后续步骤

After completing requirements:
  1. Review with stakeholders for accuracy
  2. Get explicit approval before proceeding
  3. Move to Design Phase to create technical architecture
  4. Use requirements as foundation for acceptance testing
完成需求定义后：
  1. 与利益相关者一同审查以确保准确性
  2. 在推进前获得明确批准
  3. 进入设计阶段，创建技术架构
  4. 将需求作为验收测试的基础