Series ID: EDKS-BASIC-ZH-0113 · Lesson No.113 · Expert Maintenance: Requirements Writing
Writing Requirements, Specifications and Acceptance Criteria | 编写需求、规格与验收标准
A requirement is useful only when another person can understand what must be true and determine whether it has been met.
Requirements writing converts needs into inspectable conditions. Good specifications reduce hidden assumptions, prevent teams from solving different problems, and make testing possible before disagreement appears at the end.
高质量需求写作不是“把想法写得正式”。真正的标准是：读者能否知道要实现什么、范围在哪里、什么算完成，以及如何验证。
Chinese Edition Hub · 中文版入口 · ← Lesson No.112 · Long-Term Expert Maintenance Review
The requirements map | 需求写作地图
- need
- scope
- requirement
- constraint
- specification
- acceptance criterion
- edge case
- traceability
- change control
- verification
1. Need vs requirement | 需要 vs 需求
Need:
Users need to recover access quickly.
Requirement:
The system must allow an eligible user to reset access within the recovery flow.
2. Requirement vs solution | 需求 vs 解决方案
Do not lock in a technical solution unless the solution itself is required.
3. Functional requirement | 功能需求
Describes what the system, process or person must be able to do.
4. Non-functional requirement | 非功能需求
Describes qualities or constraints such as speed, reliability, security, accessibility or usability.
5. Constraint | 约束
A condition that limits the solution space.
- budget
- deadline
- law
- compatibility
- safety
6. Scope | 范围
State what is included and excluded.
7. Out of scope | 不在范围
Explicit exclusions prevent later assumption drift.
8. Actor | 执行主体
Who or what performs the action?
9. Trigger | 触发条件
When should the requirement apply?
10. Desired behaviour | 期望行为
What observable result must occur?
11. Requirement pattern | 需求句型
When [trigger], the [actor/system] must [observable behaviour] within [condition/threshold].
12. Must / should / may | 强制程度
- must = mandatory requirement
- should = strong recommendation/expected practice
- may = permission or possibility depending context
13. Avoid modal ambiguity | 避免情态歧义
In formal specifications, define modal force if the document has contractual or compliance consequences.
14. Testability | 可测试性
A requirement should normally be testable or otherwise verifiable.
15. Weak requirement | 弱需求
The page should load quickly.
16. Stronger requirement | 更强需求
For 95% of standard requests under the defined load, the page must render the primary content within two seconds.
17. Measurable does not mean arbitrary | 可测量不等于随便数字化
A threshold needs a reason.
18. Acceptance criterion | 验收标准
Defines the observable condition used to decide whether a requirement is satisfied.
19. Requirement vs acceptance criterion | 需求 vs 验收标准
Requirement states what must be true. Acceptance criterion states how success will be judged.
20. Given / When / Then | Given-When-Then
A useful pattern for scenario-based acceptance:
- Given initial condition
- When action/event
- Then expected result
21. Example | 例子
Given a verified account, when the user requests a password reset, then the system sends a single-use recovery link to the registered address.
22. Positive case | 正常案例
What should happen under normal conditions?
23. Negative case | 失败案例
What should happen when input is invalid or a condition is unmet?
24. Edge case | 边界案例
What happens near the boundary: empty input, maximum size, duplicate request, expired token, simultaneous action?
25. Error behaviour | 错误行为
Specify what users see and what the system records when a process fails.
26. Ambiguous words | 模糊词
Watch for:
- fast
- easy
- secure
- normal
- appropriate
- user-friendly
27. Define or operationalise | 定义或操作化
If the word materially affects acceptance, define it.
28. Compound requirement | 复合需求
One sentence that contains several independently testable behaviours should often be split.
29. Atomic requirement | 原子化需求
One requirement, one primary obligation.
30. Consistency | 一致性
Two requirements must not demand contradictory behaviour under the same condition.
31. Traceability | 可追溯性
Link requirement to:
- user/business need
- design decision
- test evidence
- change request
32. Requirement ID | 需求编号
Stable IDs make discussion and change tracking easier.
33. Rationale | 理由
Record why a critical requirement exists when future teams may otherwise remove it as “unnecessary”.
34. Priority | 优先级
Distinguish mandatory core from desirable enhancement.
35. Dependency | 依赖关系
Some requirements cannot be delivered until another capability exists.
36. Conflict | 冲突需求
Expose trade-offs such as security vs convenience or speed vs verification.
37. Resolution record | 冲突解决记录
Document the chosen criterion and rationale.
38. Change control | 变更控制
When a requirement changes, record:
- what changed
- why
- impact
- who approved
- which tests change
39. Requirement drift | 需求漂移
Informal conversation can quietly change scope without updating the specification.
40. Single source of truth | 单一可信版本
Teams need one current authoritative requirement set.
41. Verification vs validation | 验证 vs 有效性确认
Verification: did we build according to specification?
Validation: did we solve the right user/problem need?
42. Passing tests can still solve the wrong problem | 测试通过也可能解决错问题
Keep the original need visible.
43. User story caution | 用户故事边界
A user story can capture intent but may need detailed acceptance criteria for implementation.
44. Example user story | 用户故事例子
As a returning user, I want to recover account access so that I can continue without contacting support.
45. Specification hierarchy | 规格层级
- objective
- requirement
- acceptance criterion
- test case
46. Requirements review | 需求评审
Ask:
- Is it necessary?
- Is it clear?
- Is it testable?
- Is scope explicit?
- Does it conflict?
47. Review with implementers and testers | 让实施者和测试者一起评审
Different roles expose different ambiguity.
48. Mandarin transfer: “需求”可对应 need / requirement / demand | 要按功能选择
49. Mandarin transfer: “验收”不是简单 accept | acceptance criteria are test conditions
50. Practice A | 练习 A
Rewrite five vague requirements into observable statements.
51. Practice B | 练习 B
Create three acceptance criteria for one requirement.
52. Practice C | 练习 C
Add one edge case and one negative case.
53. Error clinic | 常见问题
| Problem | Repair |
|---|---|
| Need mixed with solution. | Separate outcome from implementation. |
| Requirement vague. | Define observable behaviour. |
| No acceptance test. | Add criterion. |
| Scope changes informally. | Use change control. |
| Passing spec misses user need. | Add validation. |
54. First weak link diagnosis | 第一个卡点诊断
- teams disagree on meaning → definition problem.
- cannot test → acceptance problem.
- too many hidden assumptions → scope/prerequisite problem.
- late conflict → traceability/review problem.
- wrong outcome despite compliance → validation problem.
55. Seven-day training cycle | 七天训练
| Day 1 | need vs requirement | 需要需求 |
| Day 2 | observable wording | 可观察措辞 |
| Day 3 | acceptance criteria | 验收 |
| Day 4 | edge cases | 边界 |
| Day 5 | traceability | 追溯 |
| Day 6 | change control | 变更 |
| Day 7 | full specification review | 综合 |
56. Self-test | 自测
Write a small specification whose requirements are scoped, atomic, testable, traceable and paired with acceptance criteria.
57. For parents and teachers | 给家长和老师
This skill also works for school projects: define what “done” means before students build the product.
58. Final real-world challenge | 最终真实任务
- Choose one product/process.
- State user need.
- Write five requirements.
- Add scope exclusions.
- Add acceptance criteria.
- Add two edge cases.
- Add IDs/rationale.
- Build traceability table.
- Run peer review.
- Revise ambiguous wording.
Next: Lesson No.114 | 下一课
The next lesson develops knowledge transfer: how to hand over not only instructions but also context, decisions, exceptions, dependencies and the judgement that future teams need.
Lesson No.114 · Knowledge Handoffs, Succession and Institutional Memory · 知识交接、传承与组织记忆
Reference floor: expert-maintenance requirements writing. Specifications are judged by observable, testable and traceable meaning rather than formal appearance.
