easysdd-feature-acceptance

到这一步代码已经写完了，但流程没结束。这一阶段做两件事，缺一不可：

核对实现有没有偏离方案——逐层对照 {slug}-design.md 的四个节，发现偏差当场修，**不是在报告里"记一下"**就过去
把 feature 归并到整体架构——对照方案 doc 第 4 节，实际去更新架构中心目录下的相关 doc

为什么这两件事都重要？只做第一件，新功能加进去了但项目级架构 doc 还说着老结构，下一个 feature 的设计阶段读到的就是过期信息。只做第二件，可能把"实现已经偏离方案"的事实掩埋——架构 doc 写得很漂亮，代码却不是那么回事。

验收报告是工作流的闭环凭证。没产出报告 = 工作流未完成。这条不是仪式——后人查"上次这个功能到底验收时确认了哪些行为"，没有报告就只能去翻 git diff 重新推断。

共享路径与命名约定看 easysdd/reference/shared-conventions.md 第 0 节。

跟 design 的章节强依赖

本技能整套对照表、模板节、提示语都按 design 当前的章节编号和命名硬编码。design 那边重构章节名 / 调整编号，本技能必须同步——否则下面所有"第 X 节 XX"指针都会指错地方。

下面这两个章节快照是本技能消费的真相源。每次 design 升级时，先核对这两个快照是否还匹配 design 现状，不匹配就先改这里再往下用：

标准 design 章节快照：

第 0 节：术语约定
第 1 节：决策与约束（含需求摘要 / 关键决策 / 前置依赖 / 主流程概述）
第 2 节：接口契约
第 3 节：实现提示（含改动计划 / 实现风险 / 推进顺序 / 测试设计）
第 4 节：与项目级架构文档的关系

Fastforward design 章节快照：

第 0 节：需求摘要
第 1 节：设计方案
第 2 节：验收标准
第 3 节：推进步骤

启动检查

1. 代码确实实现到位了

git status / 最近提交里能看到本功能的代码改动。没看到就是 implement 还没收尾，先回去。

2. 方案 doc 完整

文件头有 YAML frontmatter，doc_type=feature-design、feature 跟当前目录一致、status=approved、summary 非空、tags ≥ 2。

标准 design：四个节（0 术语约定、1 决策与约束、2 接口契约、3 实现提示）都有实质内容，第 4 节（与项目级架构文档的关系）已填写。

Fastforward design：四个节（0 需求摘要、1 设计方案、2 验收标准、3 推进步骤）都有实质内容。验收报告按下面这个对照表去映射方案：

验收报告节	标准 design 对照	Fastforward design 对照
1 接口契约核对	方案第 2 节（接口契约）	方案第 1 节（设计方案）的改动点
2 行为与决策核对	方案第 1 节（决策与约束）	方案第 0 节（需求摘要）
3 测试约束核对	方案第 3 节（测试设计）	方案第 2 节（验收标准）
4 术语一致性	方案第 0 节（术语约定）	无术语表，检查代码命名一致性即可
5 架构归并	方案第 4 节（架构关系）	通常无架构变更；如果确实无关，写"本次 fastforward 无架构维度变更"

3. {slug}-checklist.yaml 状态

{slug}-checklist.yaml 的生命周期看 easysdd/reference/shared-conventions.md。本阶段只核对并更新 checks 一段：

文件存在，feature 字段跟当前 feature 目录一致
steps 所有条目 status 为 done（有 pending 说明 implement 没完成，先退回）
checks 列表非空，所有条目 status 为 pending
不存在 → 停下来，让用户先回 design 阶段生成

4. 把上下文读全

方案 doc 全文（重点是第 1 节需求摘要 / 明确不做、第 2 节接口契约、第 3 节测试设计）
{slug}-checklist.yaml
架构中心目录下方案 doc 第 4 节提到的所有 doc
AGENTS.md
本次功能的代码改动（git log / git diff）

5. 断点恢复

如果 {slug}-acceptance.md 已存在且有部分填好的节，看哪些节已有实质内容（有 checklist 勾选或文字填写），从下一个未完成节继续。同时检查 {slug}-checklist.yaml 的 checks 中已 passed 的项，跳过已验证完的检查。汇报一句："上次验收做到第 X 节，我从第 Y 节继续。"

验收报告模板

逐节填写，别跳节。报告路径在 feature 目录下，跟 {slug}-design.md 聚合（具体位置看 easysdd/reference/shared-conventions.md 第 0 节）。

# {功能名称} 验收报告

> 阶段：阶段 3（验收闭环）
> 验收日期：YYYY-MM-DD
> 关联方案 doc：{方案 doc 路径}

## 1. 接口契约核对

对照方案 doc 第 2 节接口契约，逐一核查实现与契约的一致性：

**契约示例逐项核对**：

- [ ] 示例 A（{文件路径 + 函数名}）：示例中的输入→输出 → 代码实际行为：{一致 / 偏差说明}
- [ ] 示例 B：...

**正式类型定义核对**（如方案 doc 中有补充类型定义）：

- [ ] 类型 X：{关键字段} → 代码里对应定义：{一致 / 偏差说明}

**流程图核对**（如方案 doc 中有 Mermaid 图）：

- [ ] 图中的所有节点 / 调用关系，在代码中均有实际落点（grep 确认）

发现偏差就**停下来先修代码或回填方案 doc**。在报告里写"已知偏差，暂不处理"是反模式——下一次有人按方案找代码时会被这个偏差绊倒。

## 2. 行为与决策核对

对照方案 doc 第 1 节决策与约束：

**需求摘要逐项验证**：

- [ ] 行为 A：{描述 + 实测结果}
- [ ] 行为 B：{描述 + 实测结果}

**明确不做逐项核对**：

- [ ] 范围外事项 X **确实没做**（grep / 代码 review 确认）
- [ ] 范围外事项 Y **确实没做**

**关键决策落地**：

- [ ] 决策 D1：{决策内容} → 代码里如何体现：{描述}

## 3. 测试约束核对

对照方案 doc 第 3 节测试设计，逐条测试约束验证：

- [ ] **C1**：{约束断言}
  - 验证方式：{类型系统 / 单测 / 集成测试 / 肉眼}
  - 结果：{通过 / 未通过 + 原因 + 补救方案}
- [ ] **C2**：...

**前端改动必须浏览器肉眼验证**（AGENTS.md 硬要求——typecheck 通过不代表用户用起来对）：

- [ ] UI 区域 X：浏览器验证 OK / 截图链接
- [ ] 交互行为 Y：浏览器验证 OK

## 4. 术语一致性

对照方案 doc 第 0 节术语约定，grep 代码：

- 术语 X：代码命中 N 处，全部一致 ✓
- 术语 Y：代码命中 N 处，全部一致 ✓
- **防冲突**：方案 doc 第 0 节列的禁用词（如有），grep 无命中 ✓

发现不一致就回到代码改正，别在报告里写"已知差异"后跳过——理由同第 1 节。

## 5. 架构归并

对照方案 doc 第 4 节"与项目级架构文档的关系"，逐项**实际执行更新**：

- [ ] 架构中心目录下的 doc X（{路径}）：
  - 需要更新的内容：{描述}
  - 已更新：✓ / 未更新（理由：{不需要更新的具体理由}）
- [ ] 架构中心目录下的 doc Y：...

如果方案 doc 第 4 节为空或描述过于简略，在此补充评估：

- 本 feature 新增了哪些模块 / 改变了哪些接口
- 架构总入口是否需要新增对本 feature 设计 doc 的引用
- `AGENTS.md` 是否需要补充新的规约或已知坑

架构归并是**实际写文件的动作**，不是自评"应该不需要改"。每条都要有明确结论。

## 6. 遗留

- 后续优化点（已开 issue 或加入 issue 列表）：{列表}
- 已知限制：{列表}
- 实现阶段"顺手发现"列表：{列表}

核对节奏

逐节做，别跳：

第 1 节（接口契约）和第 2 节（行为与决策）——这两节最容易暴露"实现跟方案对不上"，先做
第 3 节（测试约束）——逐条对照，涉及类型系统的让 typecheck 跑一遍，涉及单测 / 集成的让测试跑一遍
第 4 节（术语）——用 Grep，把命中数和位置写进报告
第 5 节（架构归并）——读完方案 doc 第 4 节后逐项执行。"整体不影响架构"一句话带过是反模式，要么找出影响在哪、要么明确写"X 节列出的某项确认无影响（理由）"
第 6 节（遗留）——把实现阶段攒下的"顺手发现"和已知限制都记进来

各节核对完后，逐条更新 {slug}-checklist.yaml 的 checks：

验证通过 → status 改为 passed
验证失败 → status 改为 failed，先修代码 / 方案再改回 passed
所有 checks 都为 passed 后，验收报告才算完成

退出条件

验收报告 6 节都填完
第 1 节接口契约核对全部勾选，无未处理偏差
第 2 节行为与决策核对全部勾选
第 3 节测试约束核对全部勾选（未通过的有补救方案），前端改动已浏览器验证
第 4 节术语一致性无遗漏
第 5 节架构归并每条都有明确结论，需要更新的 doc 已实际写入
{slug}-checklist.yaml 所有 checks 的 status 都已更新为 passed
用户终审确认

收尾提交

按 easysdd/reference/shared-conventions.md 第 4 节"收尾提交（scoped-commit）"的规则执行。本阶段的特定要点：

提交范围：功能代码 + 方案 doc + 验收报告 + 本次实际更新过的架构 doc。代码交付要带文档，否则下次做 feature 的人查不到上下文。
提交是收尾推荐序列的最后一环（见下文"退出后"）——前面那几项问完，再回到提交。

退出后

告诉用户："验收报告已就绪，架构文档已归并，easysdd-feature 工作流走完。后续如发现 BUG，走 issue 修复工作流（不再回到本工作流）。"

然后按 easysdd/reference/shared-conventions.md 第 3 节的收尾推荐顺序，逐项一句话提示（用户说"不用"立刻跳过）：

本次 feature 暴露出值得复用的坑点或经验 → "需要沉淀一条 learning 文档吗？（走 easysdd-learning，会写入 easysdd/compound/）"
引入了超出单个功能的长期约束 / 技术选型 → "需要把这条决定归档吗？（走 easysdd-decisions）"
方案 doc 第 2 节有接口变更 / 第 1 节有用户可见行为变更 → "需要更新开发者或用户指南吗？（走 easysdd-guidedoc）"
新增 / 修改了库公开接口（组件、函数、命令等） → "需要更新库 API 参考文档吗？（走 easysdd-libdoc）"
最后问一次是否需要代为提交本次代码和文档（scoped-commit）。用户同意时，按收尾提交规则执行到 commit 完成。

可以建议：

提交时把方案 doc + 验收报告 + 更新后的架构 doc 当作同一次提交的一部分
验收报告里"遗留"的后续优化点真要做的话另开新一轮 easysdd-feature 流程，不要在现有 PR 里塞

容易踩的坑

"测试都过了" → 测试约束 ≠ 测试用例，要逐条核对第 3 节测试设计
"我肉眼看了一下没问题" → 按清单走，逐项勾选
第 1 节发现接口偏差后在报告里写"已知偏差"而不去修代码或回填方案 doc
第 4 节术语 grep 发现不一致就在报告里写"已知差异"而不去改代码
第 3 节前端改动只 typecheck 没在浏览器跑过 → AGENTS.md 硬要求
第 5 节架构归并只写"整体不影响架构"一句话，没逐条核查方案 doc 第 4 节
架构 doc 需要更新而只写"建议以后更新"——归并是当下的动作，不是建议
报告写完没让用户终审就宣告"工作流完成"
工作流收尾时没问用户是否需要代为 commit
用户没明确同意就直接 git commit