Back to Details

easysdd-feature-acceptance

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

easysdd-feature-acceptance

easysdd-feature-acceptance

到这一步代码已经写完了，但流程没结束。这一阶段做两件事，缺一不可：
  1. 核对实现有没有偏离方案——逐层对照 
    {slug}-design.md
    的四个节，发现偏差当场修，**不是在报告里"记一下"**就过去
  2. 把 feature 归并到整体架构——对照方案 doc 第 4 节，实际去更新架构中心目录下的相关 doc
为什么这两件事都重要？只做第一件，新功能加进去了但项目级架构 doc 还说着老结构，下一个 feature 的设计阶段读到的就是过期信息。只做第二件，可能把"实现已经偏离方案"的事实掩埋——架构 doc 写得很漂亮，代码却不是那么回事。
验收报告是工作流的闭环凭证。没产出报告 = 工作流未完成。这条不是仪式——后人查"上次这个功能到底验收时确认了哪些行为"，没有报告就只能去翻 git diff 重新推断。
共享路径与命名约定看 
easysdd/reference/shared-conventions.md
第 0 节。
At this point, the code has been written, but the workflow is not yet complete. This phase involves two indispensable tasks:
  1. Verify if implementation deviates from the plan – Check layer by layer against the four sections of 
    {slug}-design.md
    . If deviations are found, fix them immediately, do not just "note them down" in the report and move on
  2. Integrate the feature into the overall architecture – Refer to Section 4 of the design document, and actually update the relevant documents in the architecture center directory
Why are both tasks important? If only the first task is done, the new feature is added but the project-level architecture documentation still describes the old structure, so the next feature's design phase will read outdated information. If only the second task is done, the fact that "the implementation has deviated from the plan" may be buried – the architecture documentation looks perfect, but the code does not match.
The acceptance report is the closed-loop proof of the workflow. No report produced = workflow not completed. This is not a formality – when future team members check "what behaviors were confirmed during the acceptance of this feature last time", without a report, they can only infer by reviewing git diffs.
See Section 0 of 
easysdd/reference/shared-conventions.md
for shared paths and naming conventions.

跟 design 的章节强依赖

Strong dependency on design sections

本技能整套对照表、模板节、提示语都按 design 当前的章节编号和命名硬编码。design 那边重构章节名 / 调整编号，本技能必须同步——否则下面所有"第 X 节 XX"指针都会指错地方。
下面这两个章节快照是本技能消费的真相源。每次 design 升级时，先核对这两个快照是否还匹配 design 现状，不匹配就先改这里再往下用：
标准 design 章节快照：
  • 第 0 节：术语约定
  • 第 1 节：决策与约束（含需求摘要 / 关键决策 / 前置依赖 / 主流程概述）
  • 第 2 节：接口契约
  • 第 3 节：实现提示（含改动计划 / 实现风险 / 推进顺序 / 测试设计）
  • 第 4 节：与项目级架构文档的关系
Fastforward design 章节快照：
  • 第 0 节：需求摘要
  • 第 1 节：设计方案
  • 第 2 节：验收标准
  • 第 3 节：推进步骤
All comparison tables, template sections, and prompts of this skill are hard-coded according to the current section numbers and naming of the design document. If the design document refactors section names / adjusts numbers, this skill must be updated synchronously – otherwise, all subsequent pointers to "Section X XX" will be incorrect.
The following two section snapshots are the source of truth consumed by this skill. Every time the design is updated, first check if these two snapshots still match the current status of the design document; if not, modify here first before proceeding:
Standard design section snapshot:
  • Section 0: Terminology conventions
  • Section 1: Decisions and constraints (including requirement summary / key decisions / predecessor dependencies / main workflow overview)
  • Section 2: Interface contracts
  • Section 3: Implementation prompts (including change plan / implementation risks / promotion sequence / test design)
  • Section 4: Relationship with project-level architecture documentation
Fastforward design section snapshot:
  • Section 0: Requirement summary
  • Section 1: Design plan
  • Section 2: Acceptance criteria
  • Section 3: Promotion steps

启动检查

Startup checks

1. 代码确实实现到位了

1. Code is fully implemented

git status / 最近提交里能看到本功能的代码改动。没看到就是 implement 还没收尾，先回去。
The code changes for this feature can be seen in git status / recent commits. If not, the implement phase is not yet completed; go back first.

2. 方案 doc 完整

2. Design document is complete

文件头有 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 无架构维度变更"
The file header has YAML frontmatter, with 
doc_type=feature-design
, 
feature
matching the current directory, 
status=approved
, non-empty 
summary
, and 
tags
≥ 2.
Standard design: All four sections (0 Terminology conventions, 1 Decisions and constraints, 2 Interface contracts, 3 Implementation prompts) have substantial content, and Section 4 (Relationship with project-level architecture documentation) has been filled out.
Fastforward design: All four sections (0 Requirement summary, 1 Design plan, 2 Acceptance criteria, 3 Promotion steps) have substantial content. Map the plan to the acceptance report using the following comparison table:
Acceptance report sectionStandard design referenceFastforward design reference
1 Interface contract checkSection 2 (Interface contracts) of the designChange points in Section 1 (Design plan) of the design
2 Behavior and decision checkSection 1 (Decisions and constraints) of the designSection 0 (Requirement summary) of the design
3 Test constraint checkSection 3 (Test design) of the designSection 2 (Acceptance criteria) of the design
4 Terminology consistencySection 0 (Terminology conventions) of the designNo terminology table; just check code naming consistency
5 Architecture integrationSection 4 (Architecture relationship) of the designUsually no architecture changes; if indeed irrelevant, write "No architecture dimension changes in this fastforward"

3. {slug}-checklist.yaml 状态

3. Status of {slug}-checklist.yaml

{slug}-checklist.yaml
的生命周期看 
easysdd/reference/shared-conventions.md
。本阶段只核对并更新 
checks
一段：
  • 文件存在，
    feature
    字段跟当前 feature 目录一致
  • steps
    所有条目 status 为 
    done
    （有 
    pending
    说明 implement 没完成，先退回）
  • checks
    列表非空，所有条目 status 为 
    pending
  • 不存在 → 停下来，让用户先回 design 阶段生成
See 
easysdd/reference/shared-conventions.md
for the lifecycle of 
{slug}-checklist.yaml
. In this phase, only check and update the 
checks
section:
  • The file exists, and the 
    feature
    field matches the current feature directory
  • All entries in 
    steps
    have status 
    done
    (if there are 
    pending
    entries, the implement phase is not completed; return first)
  • The 
    checks
    list is non-empty, and all entries have status 
    pending
  • If it does not exist → stop and ask the user to go back to the design phase to generate it

4. 把上下文读全

4. Read all context

  • 方案 doc 全文（重点是第 1 节需求摘要 / 明确不做、第 2 节接口契约、第 3 节测试设计）
  • {slug}-checklist.yaml
  • 架构中心目录下方案 doc 第 4 节提到的所有 doc
  • AGENTS.md
  • 本次功能的代码改动（git log / git diff）
  • Full content of the design document (focus on Section 1 Requirement summary / Explicitly not doing, Section 2 Interface contracts, Section 3 Test design)
  • {slug}-checklist.yaml
  • All documents mentioned in Section 4 of the design document under the architecture center directory
  • AGENTS.md
  • Code changes for this feature (git log / git diff)

5. 断点恢复

5. Breakpoint recovery

如果 
{slug}-acceptance.md
已存在且有部分填好的节，看哪些节已有实质内容（有 checklist 勾选或文字填写），从下一个未完成节继续。同时检查 
{slug}-checklist.yaml
的 
checks
中已 
passed
的项，跳过已验证完的检查。汇报一句："上次验收做到第 X 节，我从第 Y 节继续。"
If 
{slug}-acceptance.md
already exists and has some completed sections, check which sections have substantial content (with checklist ticks or filled-in text), and continue from the next incomplete section. At the same time, check the items in 
{slug}-checklist.yaml
's 
checks
that have status 
passed
, and skip the verified checks. Report: "The last acceptance was completed up to Section X, I will continue from Section Y."

验收报告模板

Acceptance report template

逐节填写，别跳节。报告路径在 feature 目录下，跟 
{slug}-design.md
聚合（具体位置看 
easysdd/reference/shared-conventions.md
第 0 节）。
markdown
undefined
Fill in section by section, do not skip sections. The report path is in the feature directory, aggregated with 
{slug}-design.md
(see Section 0 of 
easysdd/reference/shared-conventions.md
for the specific location).
markdown
undefined

{功能名称} 验收报告

{Feature Name} Acceptance Report

阶段：阶段 3（验收闭环） 验收日期：YYYY-MM-DD 关联方案 doc：{方案 doc 路径}
Phase: Phase 3 (Acceptance Closed Loop) Acceptance Date: YYYY-MM-DD Associated Design Document: {Design Document Path}

1. 接口契约核对

1. Interface Contract Check

对照方案 doc 第 2 节接口契约，逐一核查实现与契约的一致性：
契约示例逐项核对：
  • 示例 A（{文件路径 + 函数名}）：示例中的输入→输出 → 代码实际行为：{一致 / 偏差说明}
  • 示例 B：...
正式类型定义核对（如方案 doc 中有补充类型定义）：
  • 类型 X：{关键字段} → 代码里对应定义：{一致 / 偏差说明}
流程图核对（如方案 doc 中有 Mermaid 图）：
  • 图中的所有节点 / 调用关系，在代码中均有实际落点（grep 确认）
发现偏差就停下来先修代码或回填方案 doc。在报告里写"已知偏差，暂不处理"是反模式——下一次有人按方案找代码时会被这个偏差绊倒。
Check the consistency between implementation and contract one by one against Section 2 Interface contracts of the design document:
Item-by-item check of contract examples:
  • Example A ({File Path + Function Name}): Input→Output in example → Actual behavior in code: {Consistent / Deviation description}
  • Example B: ...
Formal type definition check (if supplementary type definitions are included in the design document):
  • Type X: {Key fields} → Corresponding definition in code: {Consistent / Deviation description}
Flowchart check (if there is a Mermaid diagram in the design document):
  • All nodes / call relationships in the diagram have actual implementations in the code (confirmed via grep)
If deviations are found, stop and fix the code or update the design document first. Writing "Known deviation, temporarily not processed" in the report is an anti-pattern – the next person looking for code according to the plan will be tripped by this deviation.

2. 行为与决策核对

2. Behavior and Decision Check

对照方案 doc 第 1 节决策与约束：
需求摘要逐项验证：
  • 行为 A：{描述 + 实测结果}
  • 行为 B：{描述 + 实测结果}
明确不做逐项核对：
  • 范围外事项 X 确实没做（grep / 代码 review 确认）
  • 范围外事项 Y 确实没做
关键决策落地：
  • 决策 D1：{决策内容} → 代码里如何体现：{描述}
Check against Section 1 Decisions and constraints of the design document:
Item-by-item verification of requirement summary:
  • Behavior A: {Description + Actual test result}
  • Behavior B: {Description + Actual test result}
Item-by-item check of explicitly not doing:
  • Out-of-scope item X is indeed not implemented (confirmed via grep / code review)
  • Out-of-scope item Y is indeed not implemented
Key decision implementation:
  • Decision D1: {Decision content} → How it is reflected in code: {Description}

3. 测试约束核对

3. Test Constraint Check

对照方案 doc 第 3 节测试设计，逐条测试约束验证：
  • C1：{约束断言}
    • 验证方式：{类型系统 / 单测 / 集成测试 / 肉眼}
    • 结果：{通过 / 未通过 + 原因 + 补救方案}
  • C2：...
前端改动必须浏览器肉眼验证（AGENTS.md 硬要求——typecheck 通过不代表用户用起来对）：
  • UI 区域 X：浏览器验证 OK / 截图链接
  • 交互行为 Y：浏览器验证 OK
Verify each test constraint against Section 3 Test design of the design document:
  • C1: {Constraint assertion}
    • Verification method: {Type system / Unit test / Integration test / Visual inspection}
    • Result: {Passed / Failed + Reason + Remedial plan}
  • C2: ...
Frontend changes must be verified visually in the browser (hard requirement in AGENTS.md – typecheck passing does not mean it works correctly for users):
  • UI Area X: Verified OK in browser / Screenshot link
  • Interaction Behavior Y: Verified OK in browser

4. 术语一致性

4. Terminology Consistency

对照方案 doc 第 0 节术语约定，grep 代码：
  • 术语 X：代码命中 N 处，全部一致 ✓
  • 术语 Y：代码命中 N 处，全部一致 ✓
  • 防冲突：方案 doc 第 0 节列的禁用词（如有），grep 无命中 ✓
发现不一致就回到代码改正，别在报告里写"已知差异"后跳过——理由同第 1 节。
Check via grep in code against Section 0 Terminology conventions of the design document:
  • Terminology X: Hit N times in code, all consistent ✓
  • Terminology Y: Hit N times in code, all consistent ✓
  • Conflict prevention: No hits for forbidden words listed in Section 0 of the design document (if any) ✓
If inconsistencies are found, go back to the code to correct them; do not write "Known difference" in the report and skip it – same reason as Section 1.

5. 架构归并

5. Architecture Integration

对照方案 doc 第 4 节"与项目级架构文档的关系"，逐项实际执行更新：
  • 架构中心目录下的 doc X（{路径}）：
    • 需要更新的内容：{描述}
    • 已更新：✓ / 未更新（理由：{不需要更新的具体理由}）
  • 架构中心目录下的 doc Y：...
如果方案 doc 第 4 节为空或描述过于简略，在此补充评估：
  • 本 feature 新增了哪些模块 / 改变了哪些接口
  • 架构总入口是否需要新增对本 feature 设计 doc 的引用
  • AGENTS.md
    是否需要补充新的规约或已知坑
架构归并是实际写文件的动作，不是自评"应该不需要改"。每条都要有明确结论。
Refer to Section 4 "Relationship with project-level architecture documentation" of the design document, and actually perform updates item by item:
  • Document X ({Path}) under the architecture center directory:
    • Content to be updated: {Description}
    • Updated: ✓ / Not updated (Reason: {Specific reason for not needing update})
  • Document Y under the architecture center directory: ...
If Section 4 of the design document is empty or too brief, supplement the evaluation here:
  • Which modules this feature has added / which interfaces it has changed
  • Whether the architecture main entry needs to add a reference to this feature's design document
  • Whether 
    AGENTS.md
    needs to supplement new conventions or known pitfalls
Architecture integration is an actual action of writing files, not a self-assessment of "should not need to change". Each item must have a clear conclusion.

6. 遗留

6. Outstanding Items

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

---
  • Follow-up optimization points (already created as issues or added to the issue list): {List}
  • Known limitations: {List}
  • "Found along the way" list from the implementation phase: {List}

---

核对节奏

Check Rhythm

逐节做，别跳：
  1. 第 1 节（接口契约）和第 2 节（行为与决策）——这两节最容易暴露"实现跟方案对不上"，先做
  2. 第 3 节（测试约束）——逐条对照，涉及类型系统的让 typecheck 跑一遍，涉及单测 / 集成的让测试跑一遍
  3. 第 4 节（术语）——用 Grep，把命中数和位置写进报告
  4. 第 5 节（架构归并）——读完方案 doc 第 4 节后逐项执行。"整体不影响架构"一句话带过是反模式，要么找出影响在哪、要么明确写"X 节列出的某项确认无影响（理由）"
  5. 第 6 节（遗留）——把实现阶段攒下的"顺手发现"和已知限制都记进来
各节核对完后，逐条更新 
{slug}-checklist.yaml
的 
checks
：
  • 验证通过 → 
    status
    改为 
    passed
  • 验证失败 → 
    status
    改为 
    failed
    ，先修代码 / 方案再改回 
    passed
  • 所有 checks 都为 
    passed
    后，验收报告才算完成
Do section by section, do not skip:
  1. Section 1 (Interface contract) and Section 2 (Behavior and decision) – These two sections are most likely to expose "implementation does not match the plan", do them first
  2. Section 3 (Test constraint) – Check item by item; for type system-related constraints, run typecheck; for unit test / integration-related ones, run tests
  3. Section 4 (Terminology) – Use Grep, write the hit count and positions into the report
  4. Section 5 (Architecture integration) – After reading Section 4 of the design document, execute item by item. Writing "No overall impact on architecture" in one sentence is an anti-pattern; either find where the impact is, or explicitly write "Confirmed no impact on item listed in Section X (Reason)"
  5. Section 6 (Outstanding items) – Record all "found along the way" and known limitations accumulated during the implementation phase
After checking each section, update the 
checks
in 
{slug}-checklist.yaml
item by item:
  • Verified passed → Change 
    status
    to 
    passed
  • Verified failed → Change 
    status
    to 
    failed
    , fix the code / design document first then change back to 
    passed
  • The acceptance report is only considered complete when all checks are 
    passed

退出条件

Exit Conditions

  • 验收报告 6 节都填完
  • 第 1 节接口契约核对全部勾选，无未处理偏差
  • 第 2 节行为与决策核对全部勾选
  • 第 3 节测试约束核对全部勾选（未通过的有补救方案），前端改动已浏览器验证
  • 第 4 节术语一致性无遗漏
  • 第 5 节架构归并每条都有明确结论，需要更新的 doc 已实际写入
  • {slug}-checklist.yaml
    所有 checks 的 status 都已更新为 
    passed
  • 用户终审确认
  • All 6 sections of the acceptance report are filled out
  • All items in Section 1 Interface contract check are ticked, no unprocessed deviations
  • All items in Section 2 Behavior and decision check are ticked
  • All items in Section 3 Test constraint check are ticked (failed items have remedial plans), frontend changes have been verified in the browser
  • No omissions in Section 4 Terminology consistency
  • Each item in Section 5 Architecture integration has a clear conclusion, and the documents that need to be updated have been actually written
  • All checks in 
    {slug}-checklist.yaml
    have status updated to 
    passed
  • User final approval confirmed

收尾提交

Final Commit

按 
easysdd/reference/shared-conventions.md
第 4 节"收尾提交（scoped-commit）"的规则执行。本阶段的特定要点：
  • 提交范围：功能代码 + 方案 doc + 验收报告 + 本次实际更新过的架构 doc。代码交付要带文档，否则下次做 feature 的人查不到上下文。
  • 提交是收尾推荐序列的最后一环（见下文"退出后"）——前面那几项问完，再回到提交。
Execute according to the rules of Section 4 "Final Commit (scoped-commit)" in 
easysdd/reference/shared-conventions.md
. Specific points for this phase:
  • Commit scope: Feature code + design document + acceptance report + architecture documents actually updated in this phase. Code delivery must include documentation, otherwise the next person working on a feature will not find the context.
  • The commit is the last step in the recommended closing sequence (see "After Exit" below) – ask about the previous items first, then return to the commit.

退出后

After Exit

告诉用户："验收报告已就绪，架构文档已归并，easysdd-feature 工作流走完。后续如发现 BUG，走 issue 修复工作流（不再回到本工作流）。"
然后按 
easysdd/reference/shared-conventions.md
第 3 节的收尾推荐顺序，逐项一句话提示（用户说"不用"立刻跳过）：
  1. 本次 feature 暴露出值得复用的坑点或经验 → "需要沉淀一条 learning 文档吗？（走 
    easysdd-learning
    ，会写入 
    easysdd/compound/
    ）"
  2. 引入了超出单个功能的长期约束 / 技术选型 → "需要把这条决定归档吗？（走 
    easysdd-decisions
    ）"
  3. 方案 doc 第 2 节有接口变更 / 第 1 节有用户可见行为变更 → "需要更新开发者或用户指南吗？（走 
    easysdd-guidedoc
    ）"
  4. 新增 / 修改了库公开接口（组件、函数、命令等） → "需要更新库 API 参考文档吗？（走 
    easysdd-libdoc
    ）"
  5. 最后问一次是否需要代为提交本次代码和文档（scoped-commit）。用户同意时，按收尾提交规则执行到 commit 完成。
可以建议：
  • 提交时把方案 doc + 验收报告 + 更新后的架构 doc 当作同一次提交的一部分
  • 验收报告里"遗留"的后续优化点真要做的话另开新一轮 easysdd-feature 流程，不要在现有 PR 里塞
Tell the user: "The acceptance report is ready, the architecture documents have been integrated, and the easysdd-feature workflow is completed. If bugs are found later, follow the issue fix workflow (do not return to this workflow)."
Then, according to the recommended closing sequence in Section 3 of 
easysdd/reference/shared-conventions.md
, give item-by-item prompts in one sentence (skip immediately if the user says "no"):
  1. This feature exposed pitfalls or experiences worth reusing → "Do you need to create a learning document? (Follow 
    easysdd-learning
    , will be written to 
    easysdd/compound/
    )"
  2. Introduced long-term constraints / technical selections beyond a single feature → "Do you need to archive this decision? (Follow 
    easysdd-decisions
    )"
  3. Section 2 of the design document has interface changes / Section 1 has user-visible behavior changes → "Do you need to update the developer or user guide? (Follow 
    easysdd-guidedoc
    )"
  4. Added / modified public library interfaces (components, functions, commands, etc.) → "Do you need to update the library API reference documentation? (Follow 
    easysdd-libdoc
    )"
  5. Finally ask once if you need to commit this code and documentation on behalf of the user (scoped-commit). When the user agrees, execute according to the final commit rules until the commit is completed.
You can suggest:
  • Include the design document + acceptance report + updated architecture documents as part of the same commit
  • If the follow-up optimization points in the "Outstanding Items" section of the acceptance report are to be implemented, start a new round of easysdd-feature workflow instead of adding them to the existing PR

容易踩的坑

Common Pitfalls

  • "测试都过了" → 测试约束 ≠ 测试用例，要逐条核对第 3 节测试设计
  • "我肉眼看了一下没问题" → 按清单走，逐项勾选
  • 第 1 节发现接口偏差后在报告里写"已知偏差"而不去修代码或回填方案 doc
  • 第 4 节术语 grep 发现不一致就在报告里写"已知差异"而不去改代码
  • 第 3 节前端改动只 typecheck 没在浏览器跑过 → AGENTS.md 硬要求
  • 第 5 节架构归并只写"整体不影响架构"一句话，没逐条核查方案 doc 第 4 节
  • 架构 doc 需要更新而只写"建议以后更新"——归并是当下的动作，不是建议
  • 报告写完没让用户终审就宣告"工作流完成"
  • 工作流收尾时没问用户是否需要代为 commit
  • 用户没明确同意就直接 
    git commit
  • "All tests passed" → Test constraints ≠ test cases; check Section 3 Test design item by item
  • "I checked visually and it's fine" → Follow the checklist and tick items one by one
  • After finding interface deviations in Section 1, write "Known deviation" in the report instead of fixing the code or updating the design document
  • After finding terminology inconsistencies via grep in Section 4, write "Known difference" in the report instead of fixing the code
  • Only ran typecheck for frontend changes in Section 3 without verifying in the browser → Hard requirement in AGENTS.md
  • In Section 5 Architecture integration, only wrote "No overall impact on architecture" in one sentence without checking each item in Section 4 of the design document
  • Needed to update architecture documents but only wrote "Suggest updating later" – integration is an immediate action, not a suggestion
  • Declared "workflow completed" without getting user final approval after writing the report
  • Did not ask the user if they need help with the commit when closing the workflow
  • Directly ran 
    git commit
    without explicit user consent