easysdd-feature-fastforward

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

easysdd-feature-fastforward

并不是每个功能都值得走完整的 brainstorm → design → implement → acceptance 四步流程。需求一句话能说清、改动就在两三个文件里、没什么术语冲突风险——这种功能硬走完整流程会让用户觉得"AI 在加戏"。fastforward 就是为这种情况留的快速通道。

但压缩的是流程，不是质量——代码指针、验收标准、明确不做这些一条都不能省。fastforward 不是"敷衍版的 design"，而是"省掉了发散讨论和分阶段 review 的 design"。

Not every feature deserves the full four-step brainstorm → design → implement → acceptance process. When requirements can be explained in one sentence, changes are limited to two or three files, and there is no risk of terminology conflicts—forcing such features through the full process will make users feel "the AI is overcomplicating things". Fastforward is the quick channel designed for such scenarios.

But what is compressed is the process, not the quality—code pointers, acceptance criteria, and clearly defined out-of-scope items must not be omitted. Fastforward is not a "perfunctory version of design", but a "design that skips divergent discussions and phased reviews".

什么时候走 fastforward

When to Use Fastforward

下面几条全部满足才走：

需求清晰——用户能说出"做什么、为谁、怎么算成功"，不需要发散讨论
范围明确——改动集中在少数文件或模块，不需要梳理多个子系统的对接点
复杂度低——没有复杂状态机、并发逻辑、术语冲突风险或架构变更
用户主动选——用户明说"快速模式"、"fastforward"、"快点搞"、"别那么多步骤"、"直接开干"等

下面这些情况遇到就主动告诉用户回完整 feature 流程：

涉及多个子系统的数据流向变更
需要引入新术语，或有概念冲突风险
推进步骤超过 4 步
用户自己说不清楚边界
改动可能影响现有核心架构

为什么这几条划得这么死？fastforward 跳过的不是仪式，而是"用户在多个 checkpoint 上把关方案的机会"。范围一大、概念一新，跳过这些 checkpoint 意味着实现完用户才发现你理解的不是同一回事——这时候返工的成本比走完整流程贵得多。

Only use fastforward when all the following conditions are met:

Clear Requirements – The user can state "what to do, for whom, and how to define success", no divergent discussions needed
Clear Scope – Changes are concentrated in a few files or modules, no need to sort out integration points across multiple subsystems
Low Complexity – No complex state machines, concurrency logic, terminology conflict risks, or architecture changes
User's Active Choice – The user explicitly says "quick mode", "fastforward", "hurry up", "cut the steps", "just start working", etc.

Proactively inform the user to revert to the complete feature process in the following situations:

Involves data flow changes across multiple subsystems
Needs to introduce new terminology or has concept conflict risks
Has more than 4 promotion steps
The user cannot clarify the boundaries themselves
Changes may affect the existing core architecture

Why are these rules so strict? What fastforward skips is not rituals, but "the user's opportunity to review the plan at multiple checkpoints". When the scope is large or concepts are new, skipping these checkpoints means the user only realizes your understanding differs after implementation—rework costs at that point are much higher than following the complete process.

你做的事

What You Need to Do

共享路径与命名约定（feature 目录、
{slug}-design.md
/
{slug}-checklist.yaml
文件名）看
easysdd/reference/shared-conventions.md
第 0 节。fastforward 没有额外的路径约定。

用户交代需求后，快速读相关代码（必须看涉及的主要文件，不需要通读全部架构文档），然后一次性产出紧凑的

{slug}-design.md

（含 YAML frontmatter），让用户整体确认，确认后给出实现指引。

For shared paths and naming conventions (feature directories,
{slug}-design.md
/
{slug}-checklist.yaml
filenames), see Section 0 of
easysdd/reference/shared-conventions.md
. Fastforward has no additional path conventions.

After the user explains the requirements, quickly read the relevant code (must check the main files involved, no need to read all architecture documents), then produce a compact

{slug}-design.md

(including YAML frontmatter) in one go, let the user confirm it as a whole, and provide implementation guidelines after confirmation.

启动检查

Startup Checks

确认适用性——按上面那几条判断是不是适合 fastforward。不适合就主动告诉用户原因，建议走完整流程
查重——检查
```
easysdd/features/
```
下是不是已经有同名 feature 目录。有的话先问是继续还是新建
读代码——Glob + Read 快速浏览用户描述里涉及的主要文件；必要时 Grep 关键词确认改动范围

不读相关代码就直接产出

{slug}-design.md

是反模式——fastforward 也要看主要文件。原因是没读代码写出来的方案大概率跟实际项目结构对不上，省下这一步会让后面整阶段全跑偏。

Confirm Applicability – Judge if fastforward is suitable based on the above criteria. If not, proactively inform the user of the reason and suggest following the complete process
Duplicate Check – Check if there is already a feature directory with the same name under
```
easysdd/features/
```
. If yes, first ask whether to continue or create a new one
Read Code – Use Glob + Read to quickly browse the main files mentioned in the user's description; use Grep to confirm the scope of changes if necessary

Producing

{slug}-design.md

without reading relevant code is an anti-pattern—fastforward still requires checking the main files. The reason is that a plan written without reading code will most likely not match the actual project structure, and skipping this step will derail the entire subsequent phase.

{slug}-design.md 结构

{slug}-design.md Structure

fastforward 的

{slug}-design.md

比标准方案精简，但必须包含 YAML frontmatter + 下面 4 节，一次性产出，不分批。

The

{slug}-design.md

for fastforward is more streamlined than the standard plan, but must include YAML frontmatter + the following 4 sections, produced in one go, not in batches.

YAML frontmatter

开头必须写统一 frontmatter，便于

search-yaml.py

在

features/

下检索。必填字段：

```
doc_type
```
：固定写
```
feature-design
```
```
feature
```
：当前 feature 目录名
```
status
```
：初稿写
```
draft
```
，用户确认后改成
```
approved
```
；被替代时写
```
superseded
```
```
summary
```
：一句话描述本功能目标
```
tags
```
：可检索标签列表，至少 2 个

模板：

markdown

---
doc_type: feature-design
feature: 2026-04-12-export-csv
status: draft
summary: 为订单列表增加 CSV 导出能力
tags: [export, csv, orders]
---

Must start with a unified frontmatter to facilitate

search-yaml.py

to search under

features/

. Required fields:

```
doc_type
```
: Fixed as
```
feature-design
```
```
feature
```
: Current feature directory name
```
status
```
: Write
```
draft
```
for the initial version, change to
```
approved
```
after user confirmation; write
```
superseded
```
when replaced
```
summary
```
: One-sentence description of the feature's goal
```
tags
```
: List of searchable tags, at least 2

Template:

markdown

---
doc_type: feature-design
feature: 2026-04-12-export-csv
status: draft
summary: Add CSV export capability to the order list
tags: [export, csv, orders]
---

第 0 节：需求摘要

Section 0: Requirements Summary

用 2-4 句话说清楚：做什么、为谁、什么算成功、明确不做什么。

markdown

undefined

Use 2-4 sentences to clarify: what to do, for whom, how to define success, and clearly defined out-of-scope items.

markdown

undefined

0. 需求摘要

0. Requirements Summary

做什么：...
为谁：...
成功标准：...
明确不做：...（至少 1-2 条）


"明确不做"不是凑数——这一节最重要的就是它。后面验收要靠它划出范围边界，没写就等于范围开放。

What to do: ...
For whom: ...
Success Criteria: ...
Clearly Out of Scope: ... (at least 1-2 items)


"Clearly Out of Scope" is not a formality—it is the most important part of this section. Later acceptance will rely on it to define scope boundaries; not writing it means the scope is open.

第 1 节：设计方案

Section 1: Design Solution

关键设计决策，写清楚：

改动的主要文件和位置（代码指针：文件路径 + 函数 / 类型名）
新增的类型 / 接口（如有，用 TypeScript / Rust 伪代码）
关键边界情况的处理方式

markdown

undefined

Key design decisions, clarify:

Main files and locations to be modified (code pointers: file path + function / type name)
New types / interfaces (if any, use TypeScript / Rust pseudocode)
Handling methods for key boundary cases

markdown

undefined

1. 设计方案

1. Design Solution

改动点

Modification Points

文件	改动内容
`path/to/file.ts`	描述具体改动

File	Modification Content
`path/to/file.ts`	Describe specific changes

新增类型（如有）

New Types (if any)

typescript // 伪代码，字段名和类型写全

typescript // Pseudocode, write full field names and types

边界情况

Boundary Cases

情况 A：处理方式
情况 B：处理方式

undefined

Case A: Handling method
Case B: Handling method

undefined

第 2 节：验收标准

Section 2: Acceptance Criteria

这是 fastforward 和标准方案 doc 的关键差异——验收标准在这里就要写好，不留占位。

{slug}-acceptance.md

会直接从这里抽验收点，留占位等于后面验收无据可依。

每条验收点必须是可操作的步骤 + 期待结果，不接受"功能正常运行"这种不可验证的描述。原因很简单：不可验证的标准等于没标准。

markdown

undefined

This is the key difference between fastforward and standard plan docs—acceptance criteria must be written here, no placeholders allowed.

{slug}-acceptance.md

will directly extract acceptance points from here; leaving placeholders means there is no basis for later acceptance.

Each acceptance point must be operable steps + expected results, unaccepting unverifiable descriptions like "function runs normally". The reason is simple: unverifiable standards are equivalent to no standards.

markdown

undefined

2. 验收标准

2. Acceptance Criteria

功能验收

Function Acceptance

（操作步骤）→（期待结果）
...

(Operation steps) → (Expected result)
...

异常与边界

Exceptions and Boundaries

边界情况 X 发生时，表现为 Y
...

When boundary case X occurs, behaves as Y
...

回归检查

Regression Checks

已有功能 X 不受影响（具体说明怎么验）

undefined

Existing feature X is not affected (specify how to verify)

undefined

第 3 节：推进步骤

Section 3: Promotion Steps

简化版推进顺序，不超过 4 步。每步要有退出信号（怎么算这步做完）。

为什么卡 4 步？超过 4 步意味着这件事已经不"简单"了——继续走 fastforward 只会让 implement 阶段失去节奏。遇到这种情况告知用户切到完整流程。

markdown

undefined

Simplified promotion sequence, no more than 4 steps. Each step must have an exit signal (how to define completion of this step).

Why limit to 4 steps? More than 4 steps means the task is no longer "simple"—continuing with fastforward will only disrupt the rhythm of the implementation phase. In such cases, inform the user to switch to the complete process.

markdown

undefined

3. 推进步骤

3. Promotion Steps

步骤名：改动描述 → 退出信号
步骤名：...

---

Step Name: Modification description → Exit signal
Step Name: ...

---

用户确认与 {slug}-checklist.yaml

User Confirmation and {slug}-checklist.yaml

产出

{slug}-design.md

后向用户发一次整体确认提示：

"fastforward {slug}-design.md 已就绪，请整体 review 后确认：

需求摘要是否准确？明确不做的部分有没有遗漏？

改动点有没有遗漏的文件或函数？

验收标准能不能覆盖你期望的场景？

确认后直接进入实现阶段。"

用户可以提修改意见，修订后再次确认。用户明确说"可以了"就视为放行，把 frontmatter 的

status

改成

approved

。

确认后立即从
{slug}-design.md
抽行动清单，落到同目录
{slug}-checklist.yaml
。清单格式和生命周期看

easysdd/reference/shared-conventions.md

，本阶段只负责初始生成。提取规则：

```
steps
```
：从第 3 节"推进步骤"逐步抽
```
checks
```
：从第 0 节"明确不做"项 + 第 2 节"验收标准"各条抽

落盘后用

validate-yaml.py --file {slug-checklist.yaml 路径} --yaml-only

校验语法。

After producing

{slug}-design.md

, send the user an overall confirmation prompt:

"fastforward {slug}-design.md is ready, please review and confirm as a whole:

Is the requirements summary accurate? Are there any omissions in the clearly out-of-scope items?

Are there any omitted files or functions in the modification points?

Can the acceptance criteria cover the scenarios you expect?

After confirmation, proceed directly to the implementation phase."

The user can propose revision suggestions, and you need to revise and confirm again. When the user explicitly says "it's okay", it is considered approved, and change the

status

in the frontmatter to

approved

After confirmation, immediately extract the action checklist from
{slug}-design.md
and save it to
{slug}-checklist.yaml
in the same directory. For the checklist format and lifecycle, see

easysdd/reference/shared-conventions.md

; this phase only responsible for initial generation. Extraction rules:

```
steps
```
: Extract step by step from Section 3 "Promotion Steps"
```
checks
```
: Extract from Section 0 "Clearly Out of Scope" items + each item in Section 2 "Acceptance Criteria"

After saving, use

validate-yaml.py --file {slug-checklist.yaml path} --yaml-only

to verify syntax.

退出条件

Exit Conditions

第 0 节含"明确不做"（至少 1-2 条）
YAML frontmatter 存在，
```
doc_type
```
/
```
feature
```
/
```
status
```
/
```
summary
```
/
```
tags
```
都填了
第 1 节每个改动点都有代码指针（文件路径 + 函数 / 类型名）
第 2 节包含功能验收 + 至少一条异常或回归检查，每条可验证
第 3 节推进步骤 ≤ 4 步，每步有退出信号
用户明确确认
用户确认后，frontmatter 的
```
status
```
已改成
```
approved
```

{slug}-checklist.yaml

已从

{slug}-design.md

抽出生成，且通过

validate-yaml.py

校验

文件路径：方案 doc 和

{slug}-checklist.yaml

都在同一 feature 目录下；feature 目录不存在就在这一步建。位置看

easysdd/reference/shared-conventions.md

第 0 节。

Section 0 includes "Clearly Out of Scope" (at least 1-2 items)
YAML frontmatter exists, with
```
doc_type
```
/
```
feature
```
/
```
status
```
/
```
summary
```
/
```
tags
```
all filled
Each modification point in Section 1 has a code pointer (file path + function / type name)
Section 2 includes function acceptance + at least one exception or regression check, each verifiable
Section 3 has ≤ 4 promotion steps, each with an exit signal
User explicitly confirms
After user confirmation,
```
status
```
in frontmatter has been changed to
```
approved
```

{slug}-checklist.yaml

has been extracted from

{slug}-design.md

and passed verification by

validate-yaml.py

File Paths: Both the plan doc and

{slug}-checklist.yaml

are in the same feature directory; create the feature directory in this step if it does not exist. For the location, see Section 0 of

easysdd/reference/shared-conventions.md

退出后

After Exit

告诉用户："{slug}-design.md 已确认，行动清单

{slug}-checklist.yaml

已生成，直接进入实现阶段。可以触发

easysdd-feature-implement

技能。"

别自己顺手开始写代码——用户确认是硬约束，理由跟标准流程一样：跨阶段无停顿地往下跑会让用户来不及把关。

Tell the user: "{slug}-design.md has been confirmed, action checklist

{slug}-checklist.yaml

has been generated, proceed directly to the implementation phase. You can trigger the

easysdd-feature-implement

skill."

Do not start writing code on your own—user confirmation is a hard constraint, for the same reason as the standard process: running continuously across phases without pausing will leave the user no time to review.

容易踩的坑

Common Pitfalls

需求不清楚还硬走 fastforward——先问清楚或建议走完整流程
不读相关代码就产出
```
{slug}-design.md
```
第 2 节验收标准写"功能正常"、"表现符合预期"这种不可操作的描述
第 3 节超过 4 步还不提示切完整流程
产出后没经用户确认就开始实现
把 fastforward 当成"敷衍了事的借口"——紧凑不等于粗糙，代码指针和验收标准一条都不能省

Forcing fastforward when requirements are unclear—first clarify or suggest following the complete process
Producing
```
{slug}-design.md
```
without reading relevant code
Writing unverifiable descriptions like "function works normally" or "behaves as expected" in Section 2 acceptance criteria
Not prompting to switch to the complete process when Section 3 has more than 4 steps
Starting implementation without user confirmation after production
Treating fastforward as an "excuse for perfunctory work"—compact does not mean rough, code pointers and acceptance criteria must not be omitted