easysdd-feature-implement

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

easysdd-feature-implement

到这一步用户已经在方案上签过字了，你的活是把方案变成代码。听起来直白，但实际容易出问题的不是写代码本身，而是实现路上发现方案没覆盖到的情况时怎么办——硬冲下去就把方案当摆设了，停下来回去谈又觉得麻烦。下面整套规则就是为了让"停下来"成为默认动作。

共享路径与命名约定看
easysdd/reference/shared-conventions.md
第 0 节。到这一步 feature 目录已经由 brainstorm 或 design 创建好。

At this point, the user has already signed off on the plan. Your task is to turn the plan into code. It sounds straightforward, but the actual problem is not writing the code itself, but what to do when you encounter situations not covered by the plan during implementation — forcing ahead makes the plan a mere formality, while stopping to discuss feels troublesome. The entire set of rules below is designed to make "stopping" the default action.

See Section 0 of
easysdd/reference/shared-conventions.md
for shared paths and naming conventions. By this stage, the feature directory has already been created by brainstorm or design.

写代码时的三条姿态

Three Principles for Writing Code

下面"启动检查"和"实现期间的核心约束"会讲具体规则。这一节先讲三条更靠前的姿态——它们决定了你写代码时默认往哪个方向偏。具体规则是这三条姿态在常见场景下的落点。

The specific rules will be covered in "Startup Checks" and "Core Constraints During Implementation" below. This section first explains three overarching principles — they determine your default orientation when writing code. The specific rules are the applications of these three principles in common scenarios.

1. 默认写最少的代码

1. Default to writing the least code possible

只写当前步骤明确要的那点东西。不顺手加"以后可能要"的可配置项、抽象层、参数开关、防御性兜底。一个判断口径：写完一段觉得"是不是还得加点 X 才完整"，先问自己 X 是不是当前这一步用户能感知到的——不是就别加。

整体写完一看，200 行其实 50 行能讲清楚——重写。多出来的代码不是中性的，是后人维护时要先读懂、要怀疑、要担心是不是漏了某条不变量的负担。

Only write exactly what is explicitly required in the current step. Do not casually add configurable items, abstraction layers, parameter switches, or defensive fallbacks that "might be needed later". A judgment criterion: After writing a piece of code, if you think "Should I add X to make it complete?", first ask yourself whether X is perceivable by the user in the current step — if not, don't add it.

After finishing the entire implementation, if you find that 200 lines could be clearly expressed in 50 — rewrite it. Extra code is not neutral; it becomes a burden for future maintainers who have to first understand it, doubt it, and worry about missing some invariant.

2. 只动该动的，不顺手"改善"邻居

2. Only modify what needs to be modified; do not "improve" adjacent code casually

打开一个文件改某个函数时，只改那个函数。同一个文件里别的函数风格丑、命名怪、注释陈旧——除非和你这次改动直接冲突，否则别碰。新写的代码风格匹配当前文件已有的写法，哪怕你自己平时不这么写。

混进 PR 的"顺手改"会让用户没法快速看清这次到底改了什么、为什么改。原本一个干净的功能 PR 会被风格调整、变量改名、邻近函数重写稀释成"一坨综合改动"，review 成本翻几倍。真看到值得改的，按下文"不做方案外的改动"里的"顺手发现"格式记成后续 issue。

孤儿处理同样收紧：你这次改动让某个 import / 变量 / 函数变成了死代码——删掉。不是你这次改动造成的、本来就在那儿的死代码——留着，记成顺手发现。

When opening a file to modify a certain function, only modify that function. If other functions in the same file have ugly styles, strange naming, or outdated comments — do not touch them unless they directly conflict with your current changes. The style of newly written code should match the existing style in the current file, even if you don't usually write this way.

"Casual improvements" mixed into a PR prevent users from quickly seeing exactly what was changed and why. A clean feature PR can be diluted into a "mess of comprehensive changes" by style adjustments, variable renaming, and adjacent function rewrites, multiplying the review cost several times. If you really find something worth modifying, record it as a subsequent issue in the format of "Casual Discovery" as described below.

Orphan code handling is also tightened: If your current change makes an import / variable / function dead code — delete it. Dead code that was already there before your change — leave it and record it as a casual discovery.

3. design 没说的事别自己拍板

3. Do not make decisions on matters not specified in the design

写到一半发现 design 没覆盖的角落（一个新的边界条件、一个没说怎么处理的错误路径、一个方案外的文件需要碰）——默认动作是停下来回 design 谈，不是自己挑个合理做法继续写。

下面"出现需要打补丁分支的冲动时停下来"和"术语守护"是这条姿态的两个典型落点；但范围更广——不限于补丁分支和术语，任何"design 没明说我替它选了一个"的瞬间都触发这条。

If you encounter corners not covered by the design halfway through writing code (a new boundary condition, an error path not specified how to handle, an out-of-scope file that needs to be modified) — the default action is to stop and discuss with the user based on the design, not to choose a reasonable approach on your own and continue writing.

"Stop when you have the urge to create a patch branch" and "Terminology Guard" below are two typical applications of this principle; but the scope is broader — not limited to patch branches and terminology, any moment when you "make a choice that the design didn't explicitly state" triggers this rule.

启动检查

Startup Checks

动手前先过这几关：

Go through these checks before starting to code:

1. 方案文件够不够撑实现

1. Is the plan file sufficient to support implementation?

打开

{slug}-design.md

，先看 frontmatter：

文件头有 YAML frontmatter，
```
doc_type=feature-design
```
```
feature
```
字段跟当前 feature 目录一致
```
status=approved
```
```
summary
```
非空，
```
tags
```
至少 2 个

然后看节内容——标准 design 和 fastforward design 的检查项不一样：

标准 design（节编号 0/1/2/3/4）：

第 0 节（术语约定）有内容
第 2 节（接口契约）有具体代码指针
第 3 节（实现提示）的改动计划落到具体路径和函数
第 3 节的推进顺序步骤明确，有退出信号
第 3 节的测试设计按功能点覆盖，每个功能点都有测试约束 / 验证方式 / 用例骨架

Fastforward design（节编号 0/1/2/3）：

第 0 节（需求摘要）含"明确不做"
第 1 节（设计方案）有改动点（文件路径 + 函数 / 类型名）
第 2 节（验收标准）每条可验证（操作步骤 + 期待结果）
第 3 节（推进步骤）步骤明确，有退出信号

任一项不达标就停下来，告诉用户先回

easysdd-feature-design

补齐。原因是方案漏的项实现时一定要现场补——而现场补意味着用户没在方案上把过关，等于绕过了 checkpoint。

Open

{slug}-design.md

and first check the frontmatter:

The file header has YAML frontmatter with
```
doc_type=feature-design
```
The
```
feature
```
field matches the current feature directory
```
status=approved
```
```
summary
```
is not empty, and
```
tags
```
has at least 2 items

Then check the section content — the check items for standard design and fastforward design are different:

Standard design (section numbers 0/1/2/3/4):

Section 0 (Terminology Conventions) has content
Section 2 (Interface Contract) has specific code pointers
The implementation plan in Section 3 (Implementation Tips) specifies exact paths and functions
The implementation sequence in Section 3 has clear steps and exit signals
The test design in Section 3 covers each feature point, with test constraints / verification methods / use case skeletons for each

Fastforward design (section numbers 0/1/2/3):

Section 0 (Requirement Summary) includes "Explicitly Not Doing"
Section 1 (Design Plan) has change points (file path + function / type name)
Each item in Section 2 (Acceptance Criteria) is verifiable (operation steps + expected results)
The implementation steps in Section 3 have clear steps and exit signals

If any item fails, stop and tell the user to first go back to

easysdd-feature-design

to complete it. The reason is that missing items in the plan must be filled in on-site during implementation — and on-site filling means the user didn't review the plan, which bypasses the checkpoint.

2. {slug}-checklist.yaml 在不在、能不能用

2. Does {slug}-checklist.yaml exist and is it usable?

{slug}-checklist.yaml

的生命周期看

easysdd/reference/shared-conventions.md

。本阶段只消费并推进

steps

这一段：

文件存在，
```
feature
```
字段跟当前 feature 目录一致
```
steps
```
列表非空，每条 status 为
```
pending
```
（接续上次中断时部分会是
```
done
```
，正常）
不存在 → 停下来，让用户回
```
easysdd-feature-design
```
生成

See

easysdd/reference/shared-conventions.md

for the lifecycle of

{slug}-checklist.yaml

. In this phase, only the

steps

section is consumed and advanced:

The file exists, and the
```
feature
```
field matches the current feature directory
The
```
steps
```
list is not empty, and each item's status is
```
pending
```
(some may be
```
done
```
if resuming from a previous interruption, which is normal)
If it does not exist → stop and ask the user to generate it in
```
easysdd-feature-design
```

3. 把上下文读全

3. Read the full context

动手前必读：

方案 doc 全文
```
{slug}-checklist.yaml
```
需求来源（用户描述 + brainstorm note，如有）
```
AGENTS.md
```
标准 design 第 2 节契约示例 / fastforward design 第 1 节改动点里提到的所有现有代码文件——读相关函数即可，不必通读

Must-read before starting:

Full content of the plan document
```
{slug}-checklist.yaml
```
Requirement source (user description + brainstorm note, if any)
```
AGENTS.md
```
All existing code files mentioned in the contract examples of Section 2 of standard design / change points of Section 1 of fastforward design — only read the relevant functions, no need to read the entire file

4. 跟用户确认从哪一步开始

4. Confirm with the user which step to start from

通常是第 1 步，但如果是接续上次中断，参考

{slug}-checklist.yaml

里已

done

的步骤，从下一步继续。

Usually Step 1, but if resuming from a previous interruption, refer to the

done

steps in

{slug}-checklist.yaml

and start from the next step.

实现期间的几条核心约束

Core Constraints During Implementation

下面这些不是凭空的禁令，每条背后都有具体代价。理解了为什么再去执行才不会僵化。

These are not arbitrary bans; each has a specific cost behind it. Only by understanding the reasons can you avoid rigid execution.

严格按 {slug}-checklist.yaml 的步骤顺序走

Strictly follow the step sequence in {slug}-checklist.yaml

按

steps

列表顺序执行，不合并步骤、不跳步。每完成一步立即把该步

status

从

pending

改为

done

。

最常见的违规是**"顺手把下一步也做了"**——为什么不行？因为方案里把动作切成步骤是有用意的：每一步都对应一个独立可验证的退出信号。两步合在一起做意味着出问题时你不知道是哪一步引入的，回滚也回不到一个干净的中间态。

Execute in the order of the

steps

list; do not merge or skip steps. Immediately change the status of each step from

pending

done

after completion.

The most common violation is "casually doing the next step as well" — why is this not allowed? Because splitting actions into steps in the plan has a purpose: each step corresponds to an independently verifiable exit signal. Combining two steps means that when a problem occurs, you don't know which step introduced it, and you can't roll back to a clean intermediate state.

不做方案外的改动

Do not make changes outside the plan

读代码时如果发现值得重构的点（参考

AGENTS.md

里"边实现边识别"那节），只要不在本次功能影响面内，就记成后续 issue，不要顺手改。

记录格式：

markdown

> 顺手发现：{文件:行号} {问题简述}。不在本次范围，记录待后续 issue。

为什么这么严？顺手改的代码不在方案里，验收时核对不上；后人看 git blame 也分不清哪些改动是为了这次功能、哪些是顺手。一次混进去三五个"顺手"，整个 PR 就讲不清楚到底改了什么。

If you find points worth refactoring while reading code (refer to the "Identify During Implementation" section in

AGENTS.md

), as long as they are not within the scope of this feature, record them as subsequent issues and do not modify them casually.

Recording format:

markdown

> Casual Discovery: {File:Line Number} {Brief description of the problem}. Not within the scope of this iteration, recorded for subsequent issue.

Why is this so strict? Casually modified code is not in the plan, so it cannot be verified during acceptance; future maintainers looking at git blame can't tell which changes are for this feature and which are casual. If three or five "casual" changes are mixed in, the entire PR becomes unclear about what was actually changed.

术语守护

Terminology Guard

仅适用于标准 design：新写的类型名、函数名、变量名都要去方案 doc 第 0 节（术语约定）对照，不允许出现 doc 里没有的新概念。觉得需要引入新概念时，先停下来改方案 doc 第 0 节、grep 防冲突、用户确认，再继续写代码。

这条的代价同样具体：术语冲突意味着将来同一个概念在代码里有两个名字，或者两个不同的概念共用同一个名字——后者尤其致命，会让搜索完全失效。

Fastforward design 没有正式的术语表，但同样的姿态适用：写到要新起一个概念名（类型 / 函数 / 关键变量）时，grep 一下当前代码里有没有同名或近义的命名，发现冲突就停下来改名或回方案谈。

Only applicable to standard design: All newly written type names, function names, and variable names must be cross-checked against Section 0 (Terminology Conventions) of the plan document. New concepts not in the document are not allowed. If you feel the need to introduce a new concept, first stop to modify Section 0 of the plan document, grep for conflicts, confirm with the user, and then continue writing code.

The cost behind this rule is specific: Terminology conflicts mean that in the future, the same concept will have two names in the code, or two different concepts will share the same name — the latter is particularly fatal, as it will make search completely ineffective.

Fastforward design does not have a formal terminology table, but the same principle applies: when you need to create a new concept name (type / function / key variable), grep the current code for the same or similar names. If a conflict is found, stop to rename it or discuss with the user based on the plan.

出现"需要打补丁分支"的冲动时停下来

Stop when you have the urge to create a patch branch

如果你写代码写到一半冒出

if (特殊情况) { 特殊处理 }

这种结构，停。

新功能里出现这种补丁分支基本只有一个原因：方案没覆盖到这种情况。继续硬写下去得到的是一段"为了让代码能跑而加的特殊逻辑"，下次别人改这块时根本不知道这个分支为什么存在。正确做法是回到方案谈，要么把这个情况补进 design 里、要么砍掉、要么明确为遗留问题。

If you have the urge to write code like

if (special case) { special handling }

halfway through writing, stop.

The only reason for patch branches in new features is usually that the plan does not cover this situation. Continuing to write forcefully will result in "special logic added just to make the code run", and future maintainers will have no idea why this branch exists. The correct approach is to discuss with the user based on the plan: either add this situation to the design, cut it, or clearly mark it as a legacy issue.

代码质量反射检查

Code Quality Reflection Check

除了上面"不跳步 / 不改方案外 / 术语守护 / 不打补丁分支"这几条流程约束，还有一组针对代码质量的反射检查——看

easysdd/reference/shared-conventions.md

第 7 节。

核心思路：不是"超过 N 行必须拆"，而是"遇到 X 情况就停下来问自己"。每条都对应一个 AI 默认会走进去的坑——往一个已经很长的文件里继续追加、往一个已经很重的类里再加方法、函数做的事越来越多但没拆、写

if 这类用户特殊处理

补丁分支、复制粘贴、加第 4+ 个参数、往万能 util 里堆东西。写代码过程中触发就停。

如果反射检查的结论是"要拆 / 要新建文件 / 要重命名 / 要抽共用层"，而这个动作超出了

{slug}-checklist.yaml

里现有步骤的范围，先跟用户商量再决定——不要偷偷拆完继续写。

In addition to the process constraints above ("No skipping steps / No out-of-plan changes / Terminology Guard / No patch branches"), there is a set of reflection checks for code quality — see Section 7 of

easysdd/reference/shared-conventions.md

Core idea: It's not "must split if more than N lines", but "stop and ask yourself when encountering situation X". Each item corresponds to a pit that AI will default to — appending to an already long file, adding methods to an already heavy class, making functions do more and more without splitting, writing

if (special user handling)

patch branches, copy-pasting, adding the 4+ parameter, piling code into a universal util. Stop when triggered during writing.

If the conclusion of the reflection check is "Need to split / Need to create a new file / Need to rename / Need to extract a shared layer", and this action is beyond the scope of the existing steps in

{slug}-checklist.yaml

, discuss with the user first before making a decision — do not split secretly and continue writing.

写完后输出统一汇报

Submit a Unified Report After Completion

所有步骤写完后用下面这个固定模板出一份汇报，然后停下来等用户 review。

为什么要固定模板？因为含糊汇报（"大致完成了"、"应该没问题"）等于把验证责任全推给用户。固定模板逼着把改了哪些文件、是否触碰方案外的东西、是否引入新概念这几件事一一说清楚，用户拿着这份汇报就能定向去看，不用从 git diff 重读一遍。

markdown

undefined

After completing all steps, submit a report using the fixed template below, then stop and wait for user review.

Why a fixed template? Vague reports (e.g., "Basically done", "Should be okay") shift all verification responsibility to the user. The fixed template forces you to clearly state which files were modified, whether any out-of-plan content was touched, and whether new concepts were introduced. With this report, the user can directly check the relevant points without re-reading the entire git diff.

markdown

undefined

实现完成汇报

Implementation Completion Report

动了哪些文件

Modified Files

{运行 git status，贴真实输出}

{Run git status and paste the actual output}

改了哪些函数 / 类型（按步骤分组）

Modified Functions / Types (Grouped by Step)

步骤 N：{步骤名}

file:line 函数名改动类型（新增 / 修改 / 删除）
...

Step N: {Step Name}

file:line Function Name Change Type (Add / Modify / Delete)
...

是否触碰到方案外的文件？

Did you touch any files outside the plan?

{是 / 否。是的话说明为什么，以及是否已同步更新方案 doc}

{Yes / No. If yes, explain why and whether the plan document has been updated synchronously}

是否引入了方案 doc 里没有的新概念 / 抽象？

Did you introduce new concepts / abstractions not in the plan document?

{是 / 否。是的话说明已回填方案 doc（标准 design 补第 0 节术语约定；fastforward 补第 1 节设计方案）并做过 grep 防冲突}

{Yes / No. If yes, explain that the plan document has been updated (Section 0 of standard design for terminology conventions; Section 1 of fastforward design for design plan) and grep has been done to prevent conflicts}

代码质量反射检查自检

Self-Check of Code Quality Reflection

{对照 shared-conventions 第 7 节，本次实现过程中有没有触发反射信号（大文件追加 / 大类加方法 / 函数超过一屏 / 特殊分支 / copy-paste / 多参函数 / 往 util 堆东西）。触发了就说明当时是怎么处理的（停下来拆 / 和用户商量后纳入步骤 / 确认是自然聚合无需拆）；都没触发就写"无触发"}

{Compare with Section 7 of shared-conventions. Did any reflection signals trigger during this implementation (appending to large files / adding methods to large classes / functions longer than one screen / special branches / copy-paste / multi-parameter functions / piling into util)? If triggered, explain how it was handled (stopped to split / discussed with user and added to steps / confirmed natural aggregation no need to split); if none triggered, write "No triggers"}

推进顺序退出信号核对

Check of Implementation Sequence Exit Signals

{对照 {slug}-checklist.yaml steps，逐条列出 action + exit_signal + status（应全为 done）}

{Compare with steps in {slug}-checklist.yaml, list action + exit_signal + status (should all be done)}

测试约束自检

Self-Check of Test Constraints

标准 design： {对照方案第 3 节测试设计，每个功能点的测试约束——当前实现是否满足？靠什么保证（类型系统 / 单测 / 集成 / 运行时 assert）？}

Fastforward design： {对照方案第 2 节验收标准，逐条核对是否满足}


汇报后停下等 review。用户提修改意见就按意见改，改完再次发简短确认，反复直到用户明确放行进入验收阶段。

---

Standard Design: {Compare with the test design in Section 3 of the plan. Does the current implementation meet the test constraints for each feature point? How is it guaranteed (type system / unit test / integration test / runtime assert)?}

Fastforward Design: {Compare with the acceptance criteria in Section 2 of the plan, check each item for compliance}


After submitting the report, stop and wait for review. If the user provides modification suggestions, make the changes and submit a brief confirmation again, repeating until the user explicitly approves to enter the acceptance phase.

---

测试用例怎么落

How to Implement Test Cases

方案第 3 节测试设计里的关键用例骨架是实现测试的输入，不是装饰——按骨架写出完整测试用例。

注意一个常见误解：测试通过 ≠ 测试约束满足。测试通过只说明你写的那些用例都过了，但不说明每条测试约束都被某个用例覆盖了。所以汇报时要逐项确认每个功能点的测试约束都已被某个用例覆盖。

如果某条测试约束靠类型系统保证（比如 TypeScript 的类型签名直接排除了某种调用），在汇报里说明"该类型签名已落地，编译期保证"。

The key use case skeletons in the test design of Section 3 of the plan are the input for implementing tests, not decoration — write complete test cases based on the skeletons.

Note a common misunderstanding: Test pass ≠ Test constraints satisfied. A test pass only means the test cases you wrote passed, but it does not mean each test constraint is covered by a test case. Therefore, during the report, you must confirm item by item that each test constraint for each feature point is covered by a test case.

If a test constraint is guaranteed by the type system (e.g., TypeScript type signature directly excludes a certain call), explain in the report "This type signature has been implemented, guaranteed at compile time".

退出条件

Exit Conditions

```
{slug}-checklist.yaml
```
所有 steps 的 status 都更新为
```
done
```
完成汇报已输出，用户明确 review 通过
没有未处理的"需要叫停"信号
第 3 节测试设计里每个功能点的测试约束都有测试覆盖（fastforward 时对照第 2 节验收标准）
没有"顺手发现"被偷偷修掉（都进了 issue 列表）
没有方案外的文件改动（或改动已同步更新方案 doc）

All steps in
```
{slug}-checklist.yaml
```
have been updated to
```
done
```
status
Completion report has been submitted, and the user has explicitly approved the review
No unprocessed "need to stop" signals
Each feature point's test constraint in Section 3 test design has test coverage (compare with Section 2 acceptance criteria for fastforward design)
No "casual discoveries" have been secretly fixed (all have been added to the issue list)
No out-of-plan file modifications (or modifications have been synchronized to the plan document)

退出后

After Exit

告诉用户："所有步骤完成，方案 doc 已同步。下一步是阶段 3：验收闭环。可以触发 easysdd-feature-acceptance 技能。"

别自己顺手开始写验收报告——验收阶段需要独立的 checklist 节奏，提前进入会让验收的把关性失效。

Tell the user: "All steps are completed, and the plan document has been updated synchronously. The next step is Phase 3: Acceptance Closure. You can trigger the easysdd-feature-acceptance skill."

Do not casually start writing the acceptance report yourself — the acceptance phase requires an independent checklist rhythm. Entering early will invalidate the gatekeeping role of acceptance.

容易踩的坑

Common Pitfalls

代码只写了一部分就发完成汇报——汇报只在全部步骤完成后发一次
汇报里写"修改了相关文件"而不列具体 file:line
看到方案外的代码顺手改了
引入新类型 / 新概念但没回去更新方案 doc（标准 design 改第 0 节术语约定；fastforward 改第 1 节设计方案）
加
```
if (用户是 X) { 特殊处理 }
```
补丁分支而不停下来反思方案
用户 review 还没通过就自己进入验收阶段
测试设计里的用例骨架一条都没实现，或测试约束没逐条验证

Submitting a completion report after only writing part of the code — the report is only submitted once after all steps are completed
Writing "Modified relevant files" in the report instead of listing specific file:line
Casually modifying code outside the plan
Introducing new types / concepts without updating the plan document (modify Section 0 of standard design for terminology conventions; modify Section 1 of fastforward design for design plan)
Adding
```
if (user is X) { special handling }
```
patch branches without stopping to reflect on the plan
Entering the acceptance phase on your own before the user's review is approved
Not implementing any of the use case skeletons in the test design, or not verifying each test constraint one by one",