easysdd-feature-implement

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

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

写代码时的三条姿态

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

1. 默认写最少的代码

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

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

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

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

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

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

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

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

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

启动检查

动手前先过这几关：

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

打开 {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。

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

{slug}-checklist.yaml 的生命周期看 easysdd/reference/shared-conventions.md。本阶段只消费并推进 steps 这一段：

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

3. 把上下文读全

动手前必读：

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

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

通常是第 1 步，但如果是接续上次中断，参考 {slug}-checklist.yaml 里已 done 的步骤，从下一步继续。

实现期间的几条核心约束

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

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

按 steps 列表顺序执行，不合并步骤、不跳步。每完成一步立即把该步 status 从 pending 改为 done。

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

不做方案外的改动

读代码时如果发现值得重构的点（参考 AGENTS.md 里"边实现边识别"那节），只要不在本次功能影响面内，就记成后续 issue，不要顺手改。

记录格式：

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

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

术语守护

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

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

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

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

如果你写代码写到一半冒出 if (特殊情况) { 特殊处理 } 这种结构，停。

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

代码质量反射检查

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

核心思路：不是"超过 N 行必须拆"，而是"遇到 X 情况就停下来问自己"。每条都对应一个 AI 默认会走进去的坑——往一个已经很长的文件里继续追加、往一个已经很重的类里再加方法、函数做的事越来越多但没拆、写 if 这类用户特殊处理 补丁分支、复制粘贴、加第 4+ 个参数、往万能 util 里堆东西。写代码过程中触发就停。

如果反射检查的结论是"要拆 / 要新建文件 / 要重命名 / 要抽共用层"，而这个动作超出了 {slug}-checklist.yaml 里现有步骤的范围，先跟用户商量再决定——不要偷偷拆完继续写。

写完后输出统一汇报

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

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

## 实现完成汇报

### 动了哪些文件
{运行 git status，贴真实输出}

### 改了哪些函数 / 类型（按步骤分组）
**步骤 N：{步骤名}**
- file:line  函数名  改动类型（新增 / 修改 / 删除）
- ...

### 是否触碰到方案外的文件？
{是 / 否。是的话说明为什么，以及是否已同步更新方案 doc}

### 是否引入了方案 doc 里没有的新概念 / 抽象？
{是 / 否。是的话说明已回填方案 doc（标准 design 补第 0 节术语约定；fastforward 补第 1 节设计方案）并做过 grep 防冲突}

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

### 推进顺序退出信号核对
{对照 {slug}-checklist.yaml steps，逐条列出 action + exit_signal + status（应全为 done）}

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

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

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

测试用例怎么落

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

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

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

退出条件

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

退出后

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

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

容易踩的坑

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