easysdd-requirements

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

easysdd-requirements

easysdd/requirements/

是项目的"能力清单"——每份文档描述一个能力因什么问题而产生、怎么解决、边界在哪，写成人话，非技术读者也能扫一眼看懂。架构文档讲"怎么搭"，需求文档讲"为什么要有这个"。两者分开记录的好处是：单独讨论需求时不被实现细节干扰，单独讨论架构时也不被产品视角牵着走。

需求文档的价值在于扫一眼就能抓到重点——用户故事在最前面、痛点和解法各一段短的、边界用列表。AI 写需求文档最容易出的几种问题都会破坏"扫一眼就抓到重点"这个特性：

写成 PRD 格式（字段堆）——读者要一格一格读才能拼出全貌。
语气过于 explain——像在上课，不是在介绍。
起花哨标题或用比喻——标题像广告词，读者要读半段才知道这能力是什么。
把实现细节塞进需求里——"通过 XXX 服务调用 YYY 接口"，这是架构 doc 的事。

下面整套规则就是为了不让这四种情况发生。

共享路径与命名约定看
easysdd/reference/shared-conventions.md
。一份样例文档看
easysdd/reference/requirement-example.md
——起草前读一遍对齐语气。

easysdd/requirements/

is the "capability inventory" of the project — each document describes why a capability is needed, how it solves the problem, and what its boundaries are, written in plain language so non-technical readers can quickly grasp the key points. Architecture documents focus on "how to build it", while requirement documents focus on "why it is needed". The benefit of separating the two is that discussions about requirements are not distracted by implementation details, and discussions about architecture are not led by product perspectives.

The value of requirement documents lies in being able to capture key points at a glance — user stories are placed at the front, pain points and solutions are each a short paragraph, and boundaries are listed as bullet points. Several common problems with AI-written requirement documents will undermine this "grasp key points at a glance" feature:

Written in PRD format (stacked fields) — readers have to read through each field piece by piece to get the full picture.
Tone is overly explanatory — like giving a lecture, not introducing something.
Fancy titles or metaphors are used — titles are like advertising slogans, and readers have to read half a paragraph to understand what the capability is.
Implementation details are stuffed into requirements — "Call YYY interface via XXX service", which belongs in architecture docs.

The entire set of rules below is designed to prevent these four situations from happening.

See
easysdd/reference/shared-conventions.md
for shared paths and naming conventions. See
easysdd/reference/requirement-example.md
for a sample document — read it to align the tone before drafting.

适用场景

Applicable Scenarios

有一个能力 / 用户场景缺需求文档，想补一份
能力演进了（新增用户故事 / 痛点表述过时 / 边界变化），要刷新
feature-design 阶段发现本次要实现的能力没有对应的 requirement，先停下来补上再继续

不适用：

用户要写的是"这个系统技术上怎么搭" → 转
```
easysdd-architecture
```
用户要写的是单次 feature 的方案 → 转
```
easysdd-feature-design
```
用户要拍板一条长期规约 / 选型 → 转
```
easysdd-decisions
```
用户要写外部读者的"怎么用" → 转
```
easysdd-guidedoc
```

A capability / user scenario lacks a requirement document and needs to be filled in
A capability has evolved (new user stories added / outdated pain point descriptions / boundary changes) and needs to be refreshed
During the feature-design phase, it is found that there is no corresponding requirement for the capability to be implemented this time — stop and fill it in before proceeding

Not applicable:

The user wants to write "how to technically build this system" → redirect to
```
easysdd-architecture
```
The user wants to write a one-time feature solution → redirect to
```
easysdd-feature-design
```
The user wants to finalize a long-term specification / selection → redirect to
```
easysdd-decisions
```
The user wants to write "how to use" for external readers → redirect to
```
easysdd-guidedoc
```

单目标规则

Single-Target Rule

每次只动一份文档，二选一：

new：起草一份新需求文档（
```
easysdd/requirements/{slug}.md
```
）
update：按新素材 / 实现变化刷新一份已有需求文档

为什么不允许一次写多份？需求文档的价值在于每份都被读过——一次吐多份 AI 起草稿，用户没精力逐份仔细 review，最后要么全部粗糙合入、要么全部放着不看。

Only modify one document at a time, choose one of the two:

new: Draft a new requirement document (
```
easysdd/requirements/{slug}.md
```
)
update: Refresh an existing requirement document based on new materials / implementation changes

Why is writing multiple documents at once not allowed? The value of requirement documents lies in each being reviewed — if the AI drafts multiple documents at once, the user won't have the energy to review each one carefully, and in the end, either all will be roughly merged or all will be left unread.

允许"没有 requirement 的 feature"

Allow "Features Without Requirements"

纯内部重构 / 技术债清理 / 工具链改造这类不新增用户可感能力的 feature，不强制要有对应 requirement。feature-design 里在对应位置标记"本次不新增能力"即可，不要为了凑一份 req 硬写。

For features that do not add user-perceivable capabilities such as pure internal refactoring / technical debt cleanup / toolchain transformation, it is not mandatory to have corresponding requirements. Just mark "No new capabilities added this time" in the corresponding position in feature-design, and don't force-write a requirement just to fill a slot.

工作流

Workflow

Phase 1：锁定目标

Phase 1: Lock the Target

确认三件事：

模式（
```
new
```
/
```
update
```
）
目标文档（new：新 slug + 一句话能力描述；update：已有文档路径）
本次覆盖的范围（整份 / 某几节）

一份需求 doc 描述一个能力。用户说"把这个模块的需求全写了"时要先问清楚：这模块对外提供几个独立能力？每个独立能力一份 doc，不要把多个能力塞进同一份。

Confirm three things:

Mode (
```
new
```
/
```
update
```
)
Target document (new: new slug + one-sentence capability description; update: existing document path)
Scope covered this time (entire document / specific sections)

A requirement doc describes one capability. When the user says "Write all the requirements for this module", first clarify: how many independent capabilities does this module provide externally? Each independent capability gets its own doc; don't stuff multiple capabilities into one document.

Phase 2：读取材料

Phase 2: Read Materials

共同必读：

```
AGENTS.md
```
```
easysdd/requirements/
```
下的其他需求文档（判断"这份要不要和它们互相引用"、"有没有和哪份重复")
用户提供的素材（口述、产品想法、用户反馈、已有 feature 方案里散落的需求描述）

按情况读：

可能承载这个能力的 architecture doc（
```
easysdd/architecture/
```
）——用于
```
implemented_by
```
字段
和本能力相关的已有 feature 方案（了解这个能力最近是怎么演进的）
相关的 compound 沉淀（explore / decision 里可能记过这块能力的背景）：
bash
```
python easysdd/tools/search-yaml.py --dir easysdd/compound --query "{能力关键词}"
```

update 模式额外必读：当前版本文档全文 + 该文档

last_reviewed

之后相关实现的变化（

git log

粗扫

implemented_by

里那些 architecture doc 对应的代码模块即可）。

Mandatory reading for all:

```
AGENTS.md
```
Other requirement documents under
```
easysdd/requirements/
```
(to determine "whether this document needs to reference them" / "whether there is overlap with any of them")
Materials provided by the user (oral descriptions, product ideas, user feedback, scattered requirement descriptions in existing feature solutions)

Read as needed:

Architecture docs that may carry this capability (
```
easysdd/architecture/
```
) — used for the
```
implemented_by
```
field
Existing feature solutions related to this capability (to understand how this capability has evolved recently)
Related compound records (background of this capability may be recorded in explore / decision):
bash
```
python easysdd/tools/search-yaml.py --dir easysdd/compound --query "{capability keywords}"
```

Additional mandatory reading for update mode: Full text of the current version of the document + changes to related implementations after the document's

last_reviewed

date (a quick scan of

git log

for code modules corresponding to the architecture docs in

implemented_by

is sufficient).

Phase 3：一次性起草

Phase 3: One-Time Drafting

按下文"文档结构"写出完整初稿，不分批吐半成品。用户故事 / 痛点 / 解法 / 边界四块之间经常有跨块矛盾（用户故事里描述的场景和解法里描述的路径对不上），只有放在一起才看得出来。

Write a complete first draft according to the "Document Structure" below; don't spit out semi-finished products in batches. There are often cross-section contradictions between the four sections of user stories / pain points / solutions / boundaries (the scenario described in user stories doesn't match the path described in solutions), which can only be spotted when they are put together.

Phase 4：自查清单（起草完就地跑一遍）

Phase 4: Self-Check List (Run Immediately After Drafting)

用户 review 前，自己先把下面这组检查过一遍。每一条都针对一种 AI 默认会犯的错：

语气是不是人话？——挑一段读出来，像在跟朋友介绍这东西吗？还是像在上课 / 写 PRD？像后者就重写。
标题是不是平铺？——标题直接说这能力是什么，不要比喻、不要花哨。"修 bug 时先探索和分析" > "让 AI 当你的第一个读者"。
用户故事够具体吗？——每条用户故事要能想象出一个具体场景。"作为用户，我希望系统好用"这种是废话，删掉。
有没有把实现细节塞进来？——需求文档里不该出现"通过 X 接口"、"调用 Y 服务"、"用 Z 算法"这种。有就移到对应 architecture doc。
边界写了没？——没写边界的需求会被误用。至少给一条"它不管什么"。
pitch 字段能当宣传词用吗？——frontmatter 的
```
pitch
```
要去技术化、一句话、读者不用上下文也能看懂。做不到就改。
update 模式专项：本次新加 / 改动的段落是否都有对应的素材或实现依据？纯凭空"加一句听起来更完整的描述"是漂移的开端。

自查结果简短汇报给用户——发现问题就说发现了、怎么处理（删掉 / 改写 / 补），不要当成"走过场"隐形步骤。

Before user review, go through the following checks yourself. Each item targets a mistake that AI tends to make by default:

Is the tone in plain language? — Read a paragraph aloud; does it sound like introducing something to a friend? Or like giving a lecture / writing a PRD? Rewrite if it's the latter.
Is the title straightforward? — The title directly states what the capability is; no metaphors, no fancy wording. "Explore and analyze first when fixing bugs" > "Let AI be your first reader when fixing bugs".
Are user stories specific enough? — Each user story should allow you to imagine a specific scenario. Empty phrases like "As a user, I want the system to be easy to use" are nonsense; delete them.
Have implementation details been stuffed in? — Requirement documents should not contain phrases like "Via X interface", "Call Y service", "Use Z algorithm". Move such content to the corresponding architecture doc.
Have boundaries been written? — Requirements without boundaries will be misused. At least include one "What it doesn't handle".
Can the pitch field be used as promotional copy? — The
```
pitch
```
in the frontmatter should be non-technical, one sentence, and understandable to readers without context. Rewrite if it can't be done.
Special check for update mode: Do all newly added / modified paragraphs have corresponding materials or implementation basis? Adding a "sounding more complete description" out of thin air is the start of drift.

Report the self-check results briefly to the user — if problems are found, state what was found and how it was handled (deleted / rewritten / supplemented); don't treat it as a "routine" invisible step.

Phase 5：用户 review

Phase 5: User Review

把初稿完整贴给用户，提示 review。用户提意见就改，反复直到用户明确"这份 doc 可以了"。用户放行后才进入 Phase 6。

Post the complete first draft to the user and prompt for review. Revise according to the user's feedback until the user clearly states "This doc is okay". Only proceed to Phase 6 after the user approves.

Phase 6：落盘 + 索引更新

Phase 6: Finalize + Update Index

new 模式：写入

easysdd/requirements/{slug}.md

，frontmatter

status: current

，

last_reviewed

填当天

update 模式：覆盖已有文件，
```
last_reviewed
```
更新为当天；如果结构性改动大，在文档末尾
```
变更日志
```
节加一条"YYYY-MM-DD：{一句话描述}"
索引更新：如果
```
easysdd/requirements/
```
下有
```
README.md
```
或索引文件，顺带加一行链接。没有就不强求——requirements 目前扁平，
```
ls
```
本身就是索引

new mode: Write to
```
easysdd/requirements/{slug}.md
```
, set frontmatter
```
status: current
```
, fill
```
last_reviewed
```
with the current date
update mode: Overwrite the existing file, update
```
last_reviewed
```
to the current date; if there are major structural changes, add a line "YYYY-MM-DD: {one-sentence description}" in the "Change Log" section at the end of the document
Update Index: If there is a
```
README.md
```
or index file under
```
easysdd/requirements/
```
, add a link. If not, it's not mandatory — requirements are currently flat, and
```
ls
```
itself is the index

文档结构

Document Structure

frontmatter

yaml

---
doc_type: requirement
slug: {英文描述，连字符分隔；和文件名一致}
pitch: {一句话去技术化说清楚这能力是什么，可直接当宣传素材}
status: current | draft | outdated
last_reviewed: YYYY-MM-DD
implemented_by: []   # 承载这个能力的 architecture doc slug 列表，可空
tags: []
---

yaml

---
doc_type: requirement
slug: {English description, hyphen-separated; consistent with filename}
pitch: {One non-technical sentence clearly stating what this capability is, can be directly used as promotional material}
status: current | draft | outdated
last_reviewed: YYYY-MM-DD
implemented_by: []   # List of architecture doc slugs that carry this capability, can be empty
tags: []
---

正文节

Body Sections

markdown

undefined

markdown

undefined

{标题 — 直接平铺说这能力是什么，不玩比喻}

{Title — directly state what the capability is, no metaphors}

用户故事

User Stories

作为 {具体角色 / 处境}，我希望 {能做什么}，而不是 {现在怎么难受}。
...（2-4 条，每条一行）

As {specific role / situation}, I want {to be able to do what}, instead of {how I'm struggling now}.
... (2-4 items, one per line)

为什么需要

Why It's Needed

一段短的，讲这能力不存在时的痛点。对象是非技术读者也能读懂的程度。这段内容直接就是宣传素材——痛点描述得越真切，对外讲这系统解决什么问题时就越有抓手。

A short paragraph explaining the pain points when this capability doesn't exist. Written in a way that non-technical readers can understand. This content is directly promotional material — the more vividly pain points are described, the more compelling it will be when explaining what problems the system solves externally.

怎么解决

How It Solves the Problem

一段短的，讲这能力大概是怎么工作的。不写实现细节——不提模块名、接口、算法。讲"用户体验上发生了什么"就够。

A short paragraph explaining roughly how this capability works. Do not write implementation details — no module names, interfaces, or algorithms mentioned. Just describe "what happens in the user experience".

边界

Boundaries

它不管什么（哪些事情看起来相关但它不负责）
什么情况下别用它
用的前提（用户需要先做什么）

undefined

What it doesn't handle (things that seem related but are not its responsibility)
When not to use it
Prerequisites (what the user needs to do first)

undefined

变更日志（update 模式才有）

Change Log (Only for update mode)

markdown

undefined

markdown

undefined

变更日志

Change Log

YYYY-MM-DD：{一句话描述}

---

YYYY-MM-DD: {One-sentence description}

---

硬性边界

Hard Boundaries

语气是人话，不是 PRD——字段堆、上课腔、花哨标题都不行；每段都要能被非技术读者一眼看懂。
不写实现细节——需求文档只讲"是什么 / 为什么 / 解决什么"，不讲"怎么搭"。涉及实现的描述一律移到 architecture。
不替用户编用户故事——用户故事必须来自用户素材或可追溯的场景（已有 feature、用户反馈、explore 记录）。AI 不允许凭空造一个"听起来合理"的使用场景。
单目标——一次只动一份文档。
不改代码、不改 architecture doc——本技能只写需求 doc。发现 architecture 有问题就记为"观察项"交给用户决定是否另开工作流处理。
不发散——用户描述的范围外问题一律不扩展，记成观察项即可。

Tone is plain language, not PRD — stacked fields, lecture-style tone, fancy titles are not allowed; every paragraph must be understandable to non-technical readers at a glance.
No implementation details — Requirement documents only cover "what it is / why it's needed / what it solves", not "how to build it". All descriptions involving implementation must be moved to architecture docs.
Do not make up user stories for the user — User stories must come from user materials or traceable scenarios (existing features, user feedback, explore records). AI is not allowed to create a "sounding reasonable" usage scenario out of thin air.
Single-target — Only modify one document at a time.
Do not modify code or architecture docs — This skill only writes requirement docs. If problems are found in architecture, record them as "observations" and let the user decide whether to start another workflow to handle them.
Do not diverge — Do not expand on issues outside the scope described by the user; just record them as observations.

退出条件

Exit Conditions

已锁定单一模式（new / update）和单一目标文档
Phase 4 自查清单逐条跑过，并已汇报处理结果
文档 frontmatter 完整，
```
doc_type: requirement
```
、
```
pitch
```
、
```
status
```
、
```
last_reviewed
```
都填了
正文四节齐全（用户故事 / 为什么需要 / 怎么解决 / 边界）
用户故事每条都能想象出具体场景，没有"作为用户希望系统好用"这种废话
没有把实现细节塞进需求 doc
```
pitch
```
字段读起来能直接当宣传词
update 模式：如有结构性改动，
```
变更日志
```
节已加一条
用户明确 review 通过
没有顺手修改代码 / architecture doc / 其他 spec
没有范围外的额外文档改动

Single mode (new / update) and single target document have been locked
Phase 4 self-check list has been gone through item by item, and handling results have been reported
Document frontmatter is complete, with
```
doc_type: requirement
```
,
```
pitch
```
,
```
status
```
,
```
last_reviewed
```
all filled in
All four body sections are complete (User Stories / Why It's Needed / How It Solves the Problem / Boundaries)
Each user story allows imagining a specific scenario, no nonsense like "As a user, I want the system to be easy to use"
No implementation details are stuffed into the requirement doc
The
```
pitch
```
field can be directly used as promotional copy
update mode: If there are structural changes, a line has been added to the "Change Log" section
User has clearly approved the review
No code / architecture doc / other spec has been modified by accident
No extra document changes outside the scope

和其他工作流的关系

Relationship with Other Workflows

方向	关系
`easysdd-architecture` 配合	requirement 描述"为什么要有"、architecture 描述"怎么搭"；architecture doc 的 frontmatter 里用 `implements: [req-slug]` 反向链到承载的需求
`easysdd-feature-design` 上游	feature 要新增 / 修改一个能力时，先确认对应 requirement 存在或触发本技能新建；纯重构 / 技术债的 feature 不强制要 req
`easysdd-feature-acceptance` 下游	验收时发现 feature 改变了某个能力的边界或用户故事 → 触发本技能 `update` 模式刷新对应 req
`easysdd-onboarding` 创建者	onboarding 阶段建 `easysdd/requirements/` 空目录，之后由本技能填实

Direction	Relationship
Collaboration with `easysdd-architecture`	Requirements describe "why it's needed", architecture describes "how to build it"; the frontmatter of architecture docs uses `implements: [req-slug]` to link back to the requirements it carries
Upstream of `easysdd-feature-design`	When a feature needs to add / modify a capability, first confirm that the corresponding requirement exists or trigger this skill to create a new one; features for pure refactoring / technical debt do not require a mandatory requirement
Downstream of `easysdd-feature-acceptance`	If it is found during acceptance that a feature has changed the boundaries or user stories of a capability → trigger the `update` mode of this skill to refresh the corresponding requirement
Creator of `easysdd-onboarding`	Create an empty `easysdd/requirements/` directory during onboarding, which will be filled by this skill later

常见错误

Common Mistakes

写成 PRD 字段堆：读者要一格一格读才能拼出全貌
语气像在上课："本能力旨在提供……"这种开头立刻扔掉
标题用比喻："修 bug 时让 AI 当你的第一个读者" < "修 bug 时先探索和分析"
用户故事太抽象："作为用户，我希望系统好用"——删掉
把实现细节塞进来："通过调用 X 接口实现 Y" —— 这是架构 doc 的事
没写边界：需求会被误用然后失望
```
pitch
```
字段塞了技术黑话：宣传时抽不出来用
一次起草多份：用户 review 不深，全部粗糙合入
范围太大：一份 doc 塞了多个独立能力——拆
update 模式凭空加段：内容会越写越飘离实际

Written as a PRD field stack: Readers have to read through each field to get the full picture
Tone is like giving a lecture: Throw away openings like "This capability aims to provide..." immediately
Title uses metaphors: "Let AI be your first reader when fixing bugs" < "Explore and analyze first when fixing bugs"
User stories are too abstract: "As a user, I want the system to be easy to use" — delete it
Implementation details are stuffed in: "Implement Y by calling X interface" — this belongs in architecture docs
Boundaries are not written: Requirements will be misused leading to disappointment
Technical jargon is stuffed into the
```
pitch
```
field: Cannot be extracted for promotional use
Drafting multiple documents at once: User review is not in-depth, all are roughly merged
Scope is too large: Multiple independent capabilities are stuffed into one doc — split it
Adding paragraphs out of thin air in update mode: Content will drift further from reality