easysdd-feature-acceptance
到这一步代码已经写完了，但流程没结束。这一阶段做三件事，缺一不可：
- 核对实现有没有偏离方案——逐层对照
{slug}-design.md的四个节，发现偏差当场修，不是在报告里"记一下"就过去 - 把 feature 归并到整体架构——对照方案 doc 第 4 节，实际去更新架构中心目录下的相关 doc
- 把变化回写到 requirement——对照方案 doc frontmatter 的
requirement字段，如果本次实现改变了对应 req 的用户故事 / 边界 / pitch 表述，触发easysdd-requirementsupdate 把 req doc 一起刷新（纯重构无 req 的 feature 跳过这步）
为什么这三件事都重要？只做第一件，新功能加进去了但项目级架构 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. requirement 回写
对照方案 doc frontmatter 的 `requirement` 字段（以及第 1 节里任何涉及用户可感能力变化的描述），判断本次 feature 是否改变了对应 requirement 的用户故事 / 边界 / pitch：
- [ ] `requirement` 字段为空（纯重构 / 技术债）：跳过本节，写一句"本 feature 不新增能力，无 requirement 回写"
- [ ] 有对应 req，但本次实现没改变能力的用户视角：写一句"req-{slug} 用户故事 / 边界未变，无需更新"
- [ ] 有对应 req，且本次实现改变了 req 的边界 / 用户故事 / pitch 表述：
- 需要更新的内容：{描述}
- 已更新：✓（触发 `easysdd-requirements` update 模式实际执行）/ 未更新（理由：{具体理由}）
和架构归并一样，这是**实际写文件的动作**，不是自评"应该不需要改"。
## 7. 遗留
- 后续优化点（已开 issue 或加入 issue 列表）：{列表}
- 已知限制：{列表}
- 实现阶段"顺手发现"列表：{列表}核对节奏
逐节做，别跳：
- 第 1 节（接口契约）和第 2 节（行为与决策）——这两节最容易暴露"实现跟方案对不上"，先做
- 第 3 节（测试约束）——逐条对照，涉及类型系统的让 typecheck 跑一遍，涉及单测 / 集成的让测试跑一遍
- 第 4 节（术语）——用 Grep，把命中数和位置写进报告
- 第 5 节（架构归并）——读完方案 doc 第 4 节后逐项执行。"整体不影响架构"一句话带过是反模式，要么找出影响在哪、要么明确写"X 节列出的某项确认无影响（理由）"
- 第 6 节（requirement 回写）——对照方案 frontmatter 的
requirement判断要不要更新对应 req；和架构归并同规则，有变化就触发easysdd-requirementsupdate 实际执行 - 第 7 节（遗留）——把实现阶段攒下的"顺手发现"和已知限制都记进来
各节核对完后，逐条更新 {slug}-checklist.yaml 的 checks：
- 验证通过 →
status改为passed - 验证失败 →
status改为failed，先修代码 / 方案再改回passed - 所有 checks 都为
passed后，验收报告才算完成
退出条件
- 验收报告 7 节都填完
- 第 1 节接口契约核对全部勾选，无未处理偏差
- 第 2 节行为与决策核对全部勾选
- 第 3 节测试约束核对全部勾选（未通过的有补救方案），前端改动已浏览器验证
- 第 4 节术语一致性无遗漏
- 第 5 节架构归并每条都有明确结论，需要更新的 doc 已实际写入
- 第 6 节 requirement 回写有明确结论：跳过 / 未变 / 已更新三种之一
{slug}-checklist.yaml所有 checks 的 status 都已更新为passed- 用户终审确认
收尾提交
按 easysdd/reference/shared-conventions.md 第 4 节"收尾提交（scoped-commit）"的规则执行。本阶段的特定要点：
- 提交范围：功能代码 + 方案 doc + 验收报告 + 本次实际更新过的架构 doc + 本次实际更新过的 requirement 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