requirements

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Requirements

需求规范

Write requirements about outcomes and observable behavior. Keep explicit user choices; do not replace their product with a preferred solution.
编写围绕结果与可观测行为的需求。保留明确的用户选择;不要用你偏好的解决方案替代用户的产品需求。

Work

工作内容

  • Extract the user goal, initiating event, allowed actor, inputs, result, and failure behavior from the brief or running product.
  • Give requirements stable IDs only when traceability helps. Prefer “An editor can rename a project; a viewer cannot” to legalistic filler.
  • For each write, identify server authorization, validation, persistence, duplicate submission behavior, and what happens if the result is unknown after a timeout.
  • Specify applicable quality constraints with conditions: target devices, input methods, content size, latency measurement, supported languages, privacy, and availability. Mark proposed targets as proposals.
  • Name dependencies, unresolved contract questions, and excluded scope. Do not invent APIs or imply they exist.
  • When revisiting implementation, report which requirements are met, changed, missing, or unverified, with evidence.
  • 从需求简报或已上线产品中提取用户目标、触发事件、允许的参与者、输入、结果及失败行为。
  • 仅在需要可追溯性时为需求分配稳定ID。优先使用“编辑者可重命名项目;查看者不可”这样的表述,而非生硬的法律式套话。
  • 针对每一项写入操作,明确服务器授权、校验、持久化、重复提交处理逻辑,以及超时后结果未知时的处理方式。
  • 明确适用的质量约束及对应条件:目标设备、输入方式、内容大小、延迟度量方式、支持语言、隐私性及可用性。将提议性目标标记为提案。
  • 列出依赖项、未解决的契约问题及排除范围。不要虚构API或暗示其存在。
  • 复盘实现情况时,需报告哪些需求已满足、已变更、缺失或未验证,并附上证据。

Deliver

交付要求

Use requirement → acceptance example → dependency/unknown. Add only enough examples to distinguish correct behavior from a plausible implementation.
Write each requirement as:
FR-01: [actor + behavior] — Accept: [observable example] — Depends/unknown: [...] NFR-01: [constraint + condition] — Verify: [scoped check] Close with out-of-scope, assumptions, open questions, and next step.
Example: Given a viewer sends a rename request directly, the server rejects it and the stored name remains unchanged. Hiding the edit button alone does not satisfy this requirement.
Include a failure or boundary case for consequential behavior. “Accessible,” “fast,” and “secure” need scoped verification criteria. Use
$flow
when branch order is the open question;
$component
when a reusable interaction needs a contract.
采用 需求 → 验收示例 → 依赖/未知项 的结构。仅添加足够的示例,以区分正确行为与看似合理的实现。
每条需求的编写格式如下:
FR-01: [参与者 + 行为] — 验收: [可观测示例] — 依赖/未知项: [...] NFR-01: [约束 + 条件] — 验证: [范围明确的检查项]
最后附上范围外内容、假设、待解决问题及下一步动作。
示例:若查看者直接发送重命名请求,服务器会拒绝该请求,且存储的名称保持不变。仅隐藏编辑按钮不满足此项需求。
需包含针对关键行为的失败或边界用例。“可访问性”、“快速”、“安全”这类表述需要明确范围的验证标准。当分支顺序是待解决问题时使用
$flow
;当可复用交互需要契约定义时使用
$component
。

Worked example

实操示例

FR-01: The system shows the last 30 days of activity when a user opens the dashboard — Accept: recent work is reviewable without navigation — Depends: activity API exists, rate limits undocumented. FR-02: The system preserves the date-range filter in the URL — Accept: the view can be shared and bookmarked — Depends: none. NFR-01: Dashboard load reaches LCP under 2.5s on 4G mobile — Verify: measure on a mid-tier device; mark the target as a proposal. NFR-02: All dashboard controls are keyboard-reachable with WCAG 2.2 AA contrast — Verify: keyboard pass plus contrast check. Out of scope: custom report builder, CSV scheduling, mobile push notifications. Assumptions: activity data is server-side and queryable by date range. Open questions: past 30 days — paginate or show a summary? Next:
$sitemap
for the app shell and dashboard routes.
FR-01: 用户打开仪表盘时,系统展示最近30天的活动记录 — 验收: 无需跳转即可查看近期工作内容 — 依赖: 存在活动API,速率限制未文档化。 FR-02: 系统在URL中保留日期范围筛选条件 — 验收: 视图可被分享和收藏 — 依赖: 无。 NFR-01: 4G移动网络下仪表盘加载的LCP低于2.5秒 — 验证: 在中端设备上测量;将该目标标记为提案。 NFR-02: 所有仪表盘控件均可通过键盘操作,且符合WCAG 2.2 AA对比度标准 — 验证: 键盘可访问测试 + 对比度检查。 范围外内容:自定义报表生成器、CSV定时调度、移动推送通知。 假设:活动数据存储在服务端,可按日期范围查询。 待解决问题:过去30天的数据 — 分页展示还是展示摘要? 下一步:为应用外壳和仪表盘路由生成
$sitemap
。

Gotchas

注意事项

  • Do not treat a hidden button as access control; require server rejection with unchanged data.
  • Do not invent endpoints or imply they exist; list undocumented contracts as unknowns.
  • Do not write "fast," "secure," or "accessible" without scoped verification criteria.
  • Do not specify UI solutions; define observable behavior and defer interaction to flow or component.
  • Do not present proposed latency or quality targets as committed guarantees.
  • 不要将隐藏按钮视为访问控制;需要求服务器拒绝请求且数据保持不变。
  • 不要虚构接口或暗示其存在;将未文档化的契约列为未知项。
  • 不要在没有明确范围的验证标准时,使用“快速”、“安全”或“可访问”这类表述。
  • 不要指定UI解决方案;定义可观测行为,将交互细节交由
    $flow
    或
    $component
    处理。
  • 不要将提议性的延迟或质量目标表述为已承诺的保障指标。

Boundaries

适用边界

  • Do not use when the idea is still vague — run
    $intent
    first.
  • Do not use when requirements exist and the open question is navigation — use
    $sitemap
    instead.
  • Do not specify UI solutions; define comparable behavior and let
    $component
    or
    $flow
    resolve the interaction.
  • 当想法仍模糊时请勿使用 — 请先执行
    $intent
    。
  • 当需求已存在且待解决问题是导航设计时请勿使用 — 请改用
    $sitemap
    。
  • 不要指定UI解决方案;定义可对比的行为,交由
    $component
    或
    $flow
    明确交互细节。