Menu
feature 流程阶段 3——验收闭环：对照 design 核实现 + 回写 architecture / requirement / roadmap，最后产出 {slug}-acceptance.md。触发：用户说"功能写完了验收一下"、"做最后检查"、"准备 merge"、"出验收报告"。前置依赖 k-feat-impl 完成。
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
维护 `.kflow/architecture/` 这份只记现状的系统地图，三种模式 update / check / backfill。触发：用户说"刷新 architecture"、"做架构检查"、"补这个模块的架构文档"、"方案和代码对得上吗"，或 feature 阶段需要先做架构动作。不写未来规划（走 k-roadmap）。
feature 流程阶段 1——为新功能起草 {slug}-design.md 作为后续实现和验收的唯一输入，拍板后抽出 checklist。触发：用户说"开始设计方案"、"写 design doc"、"准备实现 XX"，前提是已知道做什么、为谁、怎么算成功。
feature 流程阶段 2——按 {slug}-checklist.yaml 里 design 切好的 paradigm 维度 steps 推进，每步具体改哪个文件由 implement 自决，写完用统一格式汇报。触发：用户说"方案确认了开始实现"、"按方案写代码"、"开工"。前提是 design 已 approved 且有 checklist。遇到方案外情况要回方案谈不要硬冲。
issue 流程阶段 2——读 report + 读代码定位根因、评估风险，给用户 2-3 个修复方案让 TA 拍板。这一步不改代码。触发：用户说"分析这个 bug"、"找根因"、"定位问题"，且已有 {slug}-report.md。
issue 流程阶段 3——按已确认根因和方案定点修复、验证、写 {slug}-fix-note.md 落档。两个入口：标准路径从 analyze 来，快速通道从 report 直接来。触发：用户说"开始修 bug"、"按分析修"、"动手改代码"。只动方案声明的文件，不顺手优化。
把新仓库或有零散文档的仓库接入 kflow 体系——两条路径自动判断：空仓库从零搭骨架，已有文档走审计 + 迁移映射——然后释放技能文件和跨平台入口（AGENTS.md，可选 CLAUDE.md）。触发：用户说"在这个项目里用 kflow"、"搭 kflow 结构"、"初始化 kflow"、"迁移到 kflow"。
| name | k-feat-accept |
| description | feature 流程阶段 3——验收闭环：对照 design 核实现 + 回写 architecture / requirement / roadmap，最后产出 {slug}-acceptance.md。触发：用户说"功能写完了验收一下"、"做最后检查"、"准备 merge"、"出验收报告"。前置依赖 k-feat-impl 完成。 |
开始任何判断或动作前，先读取 .kflow/attention.md；缺失则视为骨架不完整，提示先补齐或运行 k-onboard。
代码已经写完，但流程没结束。本阶段做四件事，缺一不可：
{slug}-design.md，发现偏差当场修，**不是在报告里"记一下"**就过去roadmap / roadmap_item 字段时必须改 items.yaml 对应条目为 done 并同步主文档漏掉任何一件的代价：架构 doc 过期下个 feature 读到错信息；req 和实际能力脱节；roadmap 规划层和实际进度脱节，下次推进会重复跑流程。
没产出报告 = 工作流未完成。后人查"上次这个功能验收时确认了哪些行为"，没报告就只能翻 git diff 重新推断。
共享路径与命名约定看
.kflow/reference/shared-paths.md。读取材料遵守.kflow/reference/shared-token-budget.md，先按验收节读取相关章节和代码证据，必要时再升级到全文。
本技能整套对照表按 design 当前章节编号硬编码。design 升级章节名 / 编号时本技能必须同步，否则下面所有"第 X 节"指针都指错地方。
标准 design 章节快照：
Fastforward design：第 0 需求摘要 / 第 1 设计方案 / 第 2 验收标准 / 第 3 推进步骤
doc_type=feature-design / feature 一致 / status=approved / summary 非空 / tags ≥ 2；标准 design 第 0/1/2/3 节 + 第 4 节已填写{slug}-checklist.yaml——存在且 feature 一致；steps 全 done（有 pending 退回 implement）；checks 非空全 pendinggit diff --stat / 文件列表，再读对应 diff。发现跨节矛盾、要回填方案、或要改写目标 doc 时再读全文。{slug}-acceptance.md 已存在且部分填好 → 从下一个未完成节继续，跳过 checks 中已 passed 的项；汇报"上次做到第 X 节，从第 Y 节继续"Fastforward design 验收报告映射表：
| 验收报告节 | 标准 design 对照 | Fastforward design 对照 |
|---|---|---|
| 1 接口契约核对 | 第 2.1 接口示例 | 第 1 节改动点 |
| 2 行为与决策核对（含挂载点） | 第 1 节 + 第 2.2 + 第 2.3 | 第 0 节；挂载点现场盘点 |
| 3 验收场景核对 | 第 3 节场景清单 + 反向核对 | 第 2 节验收标准 |
| 4 术语一致性 | 第 0 节 + 第 2.1 命名 | 检查代码命名一致性 |
| 5 架构归并 | 第 4 节 | 通常无；写"无架构维度变更" |
逐节填写别跳节。报告路径在 feature 目录下（位置看 shared-paths.md）。
# {功能名称} 验收报告
> 阶段：阶段 3（验收闭环）
> 验收日期：YYYY-MM-DD
> 关联方案 doc：{方案 doc 路径}
## 1. 接口契约核对
对照方案第 2.1 节名词层逐一核查：
**接口示例逐项核对**：
- [ ] 示例 A（{文件路径 + 函数名}）：示例输入→输出 → 代码实际行为：{一致 / 偏差说明}
**名词层"现状 → 变化"逐项核对**：
- [ ] 名词 X：声称的变化 → 代码改动：{一致 / 偏差}
**流程图核对**（第 2.2 节开头 mermaid 图）：
- [ ] 图中节点 / 调用关系在代码均有实际落点（grep 确认）
发现偏差**先修代码或回填方案 doc**。报告里写"已知偏差暂不处理"是反模式——下次按方案找代码会被绊倒。
## 2. 行为与决策核对
对照方案第 1 节 + 第 2.2 节：
**需求摘要逐项验证**：
- [ ] 行为 A：{描述 + 实测结果}
**明确不做逐项核对**（用第 3 节"反向核对项"）：
- [ ] 范围外事项 X **确实没做**（grep / review 确认）
**关键决策落地**：
- [ ] 决策 D1：{决策内容} → 代码体现：{描述}
**编排层"现状 → 变化"逐项核对**：
- [ ] 变化 V1：{在哪一步插入 / 哪条分支变更} → 代码实际落点
**流程级约束核对**（错误语义 / 幂等 / 并发 / 扩展点 / 可观测点）：
- [ ] 纪律 R1：{描述} → 代码遵守方式
**挂载点反向核对（可卸载性）**——对照第 2.3 节，必做两件事：
- [ ] 挂载点 M1：清单条目 → 代码实际落点：{一致 / 偏差}
- [ ] **反向核查**（grep）：本 feature 在代码里的所有引用是否都落在清单内？清单外的引用 → 漏记，补进第 2.3 节
- [ ] **拔除沙盘推演**：按清单逆向操作后是否还有残留？残留 → 写进"遗留"或补挂载点
Fastforward 方案没有挂载点清单 → 现场 grep 盘点本次改动命中的挂入位置作为卸载依据。
## 3. 验收场景核对
对照方案第 3 节关键场景清单，逐条可观察证据验证：
- [ ] **S1**：{场景"输入 / 触发 → 期望可观察结果"}
- 证据来源：{类型系统 / 单测 / 集成 / 手工 / 肉眼}
- 结果：{通过 / 未通过 + 原因 + 补救}
**前端改动必须浏览器肉眼验证**（typecheck 通过不代表用户用起来对）：
- [ ] UI 区域 X：浏览器验证 OK / 截图链接
## 4. 术语一致性
对照方案第 0 节 + 第 2.1 节命名 grep 代码：
- 术语 X：代码命中 N 处全部一致 ✓
- 防冲突：禁用词 grep 无命中 ✓
发现不一致 → 改代码，别在报告里写"已知差异"。
## 5. 架构归并
**目标**：把本次 feature 里稳定、系统级可见的内容**实际写入** architecture，让读者只看 architecture 就能看懂新能力的存在和形态。**不是加 design 链接就算数**。
对照方案第 4 节，三类东西实际写入对应架构 doc：
- **名词归并** ← 第 2.1 节新增 / 变化的实体、类型、对外契约 → architecture 的"结构与交互 / 数据与状态"节
- **动词骨架归并** ← 第 2.2 节跨模块可见的主流程 / 关键编排 → architecture 的结构图 / 模块交互
- **流程级约束归并** ← 第 2.2 节跨 feature 稳定的约束 → architecture 的"已知约束"节
逐项核对：
- [ ] 架构 doc X（{路径}）：归并内容 {描述}；已写入 ✓ / 不需要（理由：{具体}）
方案第 4 节为空或过简 → 在此补充评估：
- 新增哪些模块 / 改了哪些接口 / 引入哪些跨模块纪律
- 架构总入口要不要新增描述（描述不是贴链接）
- `.kflow/attention.md` 要不要补新规约或已知坑
**判据**：归并完成后，没读过 design 的人打开 architecture 应该能知道"系统里现在有这个能力、它的大致形态、和它交互要遵守什么"。
## 6. requirement 回写
req 是能力愿景层，本节是 draft → current 升级和 backfill 的触发点。对照方案 frontmatter 的 `requirement` 和第 1 节需求摘要：
- [ ] `requirement` 空 + 方案明确"不新增能力"（纯重构 / 技术债）→ 跳过，写"无 requirement 回写"
- [ ] `requirement` 空 + 新增了用户可感能力 → 触发 `k-req` **backfill** 直接落 `status: current`
- [ ] `requirement` 指向 draft req → 触发 `k-req` **update**：`draft` → `current`，按实际实现刷新用户故事 / 边界，**保留原始愿景**（愿景不被覆盖，只在文末加变更日志记录本次改动）
- [ ] `requirement` 指向 current req 且本次改了边界 / 用户故事 / pitch → 触发 `k-req` **update** 刷新
- [ ] `requirement` 指向 current req 但本次未改用户视角 → 写"req-{slug} 未变，无需更新"
这是**实际写文件的动作**，不是自评"应该不需要改"。
## 7. roadmap 回写
对照方案 frontmatter 的 `roadmap` / `roadmap_item`：
- [ ] 两字段都空（feature 未从 roadmap 起头）→ 跳过，写"非 roadmap 起头"
- [ ] 两字段都有值：
- 打开 `.kflow/roadmap/{roadmap}/{roadmap}-items.yaml`
- 找到 `slug: {roadmap_item}`，核对当前 `status: in-progress` + `feature: {目录名}`——不对停下来找原因
- 改 `status: done`，用 `validate-yaml.py` 校验
- 同步 `{roadmap}-roadmap.md` 主文档第 3 节子 feature 清单的对应条目状态
- [ ] 两字段不一致（只填了一个）→ 停下来补齐或澄清
衔接协议看 `shared-roadmap-feature.md`。和归并 / req 同规则：实际写文件的动作。
## 8. attention.md 候选盘点
回看本次实现，盘点"每个 feature 都会撞一次"的环境 / 工具 / 工作流类信息。典型候选：编译命令、代理配置、本地起服务步骤、反复踩的环境坑、仓库内非显然的工作流约定。
**判据**：下一个 feature 的 AI 还会再踩一次的事才记。一次性踩坑、和具体业务耦合的细节归 learning / decide。
- [ ] 无候选：写"本 feature 未暴露需要补入 attention.md 的内容"
- [ ] 有候选：列出来，**不擅自写入**——本节只登记，落不落由用户在"退出后"环节定
- 候选 1：{描述 + 建议放 attention.md}
## 9. 遗留
- 后续优化点（已开 issue 或加入 issue 列表）：{列表}
- 已知限制：{列表}
- 实现阶段"顺手发现"列表：{列表}
逐节做。每节完成后逐条更新 {slug}-checklist.yaml 的 checks：通过 → passed，失败 → failed（先修代码 / 方案再改回 passed）。所有 checks 全 passed 后报告才算完成。
第 1/2 节最容易暴露偏离，先做。第 2 节挂载点反向核对必须实际 grep + 沙盘推演，不能凭印象勾选。第 5/6/7 节是写文件的动作，不是自评。
passed告诉用户："验收报告已就绪，架构文档已归并，k-feat 工作流走完。后续 BUG 走 issue 流程。"
按 shared-closeout.md收尾推荐顺序逐项一句话提示（用户说"不用"立刻跳过）：
k-learn）"k-decide）"
k-decide 归档？"——这种是 design 阶段就识别出的稳定模式，比一般"问问看"更应该主动提k-guide）"k-libdoc）"k-note 走分节归类 / 查重 / 软上限检查（不在 accept 里手写，避免和 k-note 各搞一套口径）；一次一条收尾提交规则看 shared-closeout.md。提交范围：功能代码 + 方案 doc + 验收报告 + 本次实际更新的架构 doc / req doc / roadmap items.yaml + 主文档。
roadmap 却在第 7 节写"跳过"——有值就必须回写git commit