git-learn/skill-workbench/docs/value/latest-design.md

value-scan / value-dig · 设计文档（Latest Design）

定位：从已交付的代码里逆向萃取「值得讲的价值点」，交人勾选后深挖成可讲、可追问、可被审的文档。 适用：面试/简历素材重建、模块价值盘点、交接文档提级。 形态：两个 skill 接力 —— value-scan（广度枚举，停在人工勾选门）→ value-dig（深度产出，三件套任选）。 战果（its 仓库实测，2026-09-18）：4 轮扫描产出 9 份文档全部通过机械校验；2 条主链路各带 1 个 P0 级实锤缺陷。

---

1. 为什么要有这两个 skill

盘点代码价值时，agent 有三个系统性偏差：

偏差	表现	解药
判不了价值	把"用了 Redis""有 4 个 handler"当亮点	简历行填空测试：用【机制】解决了【问题】，代价是【取舍】——机制格填不出就不是价值点
缺陷导向	扫一遍变成挑毛病大会，清单全是负面	阶段隔离：S1 只产亮点，缺陷是深挖链路时自然浮现的副产物，归宿在改造方案
自作主张	替用户挑完直接开写	门控：产出候选清单后必须停，勾选权在人

一句话设计哲学：agent 负责采样与结构化，人负责价值判断。

2. 两段流水线

S0 定范围 → S1 枚举 → S2 勾选【硬门：必须停】
                              ↓（人勾选 / 否决改向 A′）
                    value-dig：①功能点清单 ②设计复盘 ③改造方案（各自独立，可只做其一）

value-scan（广度）

• 三层结构：域 → 链路 → 机制节点。链路按触发者拆（谁在改这行数据），不按业务功能拆——收敛点多半是机制所在。
• 三条硬标准（全过才进清单）：① 核心链路 ② 高级工程师的设计（非框架常识）③ 简历够硬。
• 数量闸：5–8 条为宜，>12 = 颗粒度掉到实现层，退回重并。
• 两层锚点：机制级 路径#方法名（不写行号，防漂移），深挖级 文件:行号（必须读过再写）。

value-dig（深度）

三份文档三种读者：

文档	读者	灵魂
① 功能点清单	自己/接手人	主干调用骨架：整条链压成一段伪代码，每行标方式（[锁]``[幂等]``[MQ]），功能点互为索引
② 设计思路与取舍	面试官	第一人称复盘 + "与代码的对照说明"：判断与代码事实不一致处逐条列出——诚实性是可信度唯一来源
③ 改造方案	架构评审	缺陷唯一归属地；产出门槛：必须有②加机制/③重构档改造点才立方案，全是补漏档不立（防灌水）

跨文档资产复用：tb_order_anomaly 台账、token 锁工具、巡检 Job——两链路方案共用一套，是"结构必然"不是"省事"。

3. 机制设计要点（为什么这样设计）

3.1 门控（S2 必停）

价值判断权如果不在人，整个流水线退化成"agent 自嗨产出没人看的文档"。所以：

• 候选清单落盘 + 显式请求勾选（"请从 N 条挑 3–6 条"）；
• 用户禁用提问工具也一样停——请求写成文字；
• 整批否决且未给新目标 = 流程终点，不强续。

3.2 判据外化为填空

"价值"无法定义，但"简历行填得出来吗"可判定。两级：

• 准入：三条硬标准（反例驱动的剔除表）；
• 表达：机制+问题两格必填，取舍格留给 value-dig（不误杀）。

被剔除的点不丢弃——进「已剔除」表注明未过哪条标准，供复核筛选口径。

3.3 机械校验（check.py）与模板外置

• 模板是活资产：产出照模板填空，被纠正过就回写模板；
• check.py 十余条规则：引号配对 / mermaid 合法性 / 表格列一致+不缩进 / 章节完整性（模板必备节 ⊆ 产出节）/ scan 专属（无代码围栏、锚点格式、候选数 ≤12）/ dig 专属（骨架行必带方式标记、证据必含行号）/ doc 专属（改造方案必有关键片段）；
• FAIL 必须为 0，WARN 允许保留但写明原因。

3.4 缺陷的归宿隔离

缺陷只在改造方案出现，且不是枚举出来的是贴着链路走出来的——三把刀（按触发者拆链路 / 竞态矩阵 / 幂等键清单+状态流转图）+ 机制模式库（结构性限制 → 可引入机制对照表）+ 三档尺度（补漏⭐/加机制⭐⭐⭐/重构⭐⭐⭐，每缺陷必追问"能否升一档"）。

4. 实战演化记录（its 仓库 4 轮，2026-09-18）

这轮实战暴露的边界案例与回写（模板活资产的实证）：

#	事件	回写
1	用户否决 5 条单点："都不够硬，直接分析整链路"	value-dig 新增入口 A′（否决改向）：否决原因入清单、按 B 重走、产物声明
2	权益域首轮以"机制格填不出"剔除，复评翻案（快照轮询机制实存，藏在 2349 行大类的私有方法群）	"机制格填不出"剔除加硬门槛：没读过入口方法向下 ~100 行不得定稿剔除；翻案不删行留痕
3	"不够硬"出现两次（单点否决、权益否决）	S2 门控新增否决即校准：负反馈记入清单，同域复扫先读否决记录
4	勾选回写两次压列（3 列变 2 列）	候选清单模板补回写示例（3 列不压列）；check.py 报错附行内容摘要
5	check.ps1 仅 Windows	移植 check.py（等价回归 8 产物一致）；顺带发现初版 __name__ 损坏静默 exit 0——校验工具自身的静默通过比报错更危险

实测产出骨架（可作参考样例）

docs/
├── 赢客下单-候选价值点.md        S1 清单（5 候选 + 5 剔除）
├── 赢客下单-功能点清单.md        7 功能点 + 主干骨架
├── 赢客下单-设计思路与取舍.md    4 不变量 / 7 决策 / 口述版
├── 赢客下单-改造方案.md          6 缺陷（3🔴）→ 3 阶段
├── 全仓其余域-候选价值点.md      二轮 8 候选（含翻案 ★7/★8）
├── 工单全生命周期-{功能点清单,设计思路与取舍,改造方案}.md

两个 P0 实锤（深挖才浮现的典型）：

• 幂等双关口键不一致：bossOrderId vs requestId，组合穿透 → 重复扣权益；
• updateConfirmInfo 条件更新漏 status=51：设计是 DB 仲裁，落地是应用层检查 → 人工确认可被自动确认覆盖。

5. 已知限制与下一步

限制	说明	候选方向
单域节奏	一次一域，全仓扫描靠人反复发起	域清单自动切片 + 断点续扫
判据主观残留	"简历够硬"仍依赖人对目标岗位的校准	按 JD 关键词加权候选排序
深挖成本	一个功能点 ≈ 1–2 份 20KB 文档，人工审读压力大	功能点清单先行 + 复盘/方案按勾选再出
校验器无自检	check.py 自身损坏会静默通过	CI 里对已知 BAD 样例断言必 FAIL