Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
ba14d93
fix: 补齐维度覆盖表缺行、扩展维度清单、硬编码口径三处同步;lint 新增相对表述检查
Luo-root Oct 21, 2026
7c1c4ea
fix(dimensions): 纠正命名/分包判据里的事实错误——同名包一起 import 编译器会报错
Luo-root Oct 21, 2026
7cc3fb0
docs(evals): 补评测卫生规则(中性化样本、原始输出隔离、skill 副本路径)
Luo-root Oct 21, 2026
22ea56c
docs(evals): 折进判分细则 + 记录 v4 轮基线(25 条口径,冻结提交 7c1c4ea)
Luo-root Oct 21, 2026
260d8f8
feat: 加「反驳」一遍与「规模扫描」——补上算法复杂度与语义分裂的审查面
Luo-root Oct 28, 2026
d017821
test(evals): 新增 rule-engine 样本与标准答案——测算法复杂度与语义分裂
Luo-root Oct 28, 2026
97814bd
refine(dimensions): 规模扫描补可识别形状,语义分裂与跨层形状补误报边界
Luo-root Oct 28, 2026
2abfddf
fix(output): 覆盖表补「规模与复杂度」一行
Luo-root Oct 28, 2026
dad4adc
fix(skill): 七维速查表补第 2 维跨层形状与第 6 维语义分裂
Luo-root Oct 28, 2026
ae06201
test(evals): 标准答案 v2——按两轮实测校正 R2/R4/R5,补 R7-R10
Luo-root Oct 28, 2026
e1ea4d2
docs(evals): 记录 rule-engine 与 tiny-shop 回归四轮结果(冻结提交 dad4adc)
Luo-root Oct 28, 2026
452e418
docs(evals): 独立复算交叉校验——更正 rule-engine C 的 C1 判定并补记复算对照
Luo-root Oct 28, 2026
cd5b19b
Merge pull request #25 from Luo-root/feat/refute-and-scale
Luo-root Oct 28, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 38 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,10 +38,10 @@
| | 快模式(回归判定) | 全量模式(设计体检) |
|---|---|---|
| 用户在问 | 「有没有回归」「能不能合」「改坏了吗」 | 「这设计怎么样」「还有哪些坑」「按七维审」 |
| 做什么 | 读全 + 证伪 | 读全 + 类型 playbook + 七维 + 证伪 |
| 做什么 | 读全 + 证伪 | 读全 + 反驳 + 类型 playbook + 七维 + 规模扫描 + 证伪 |
| 输出 | 紧凑列表,每条 2~3 行;零发现一句话 | 六段式 + 维度覆盖表 |

两档**共用**「读全」与「证伪」,不重复劳动。拿不准就走全量——全量的产出可以裁成快模式,快模式的产出补不回全量。
两档**共用**「读全」与「证伪」,不重复劳动。**反驳与规模扫描只在全量模式跑**——它们找的是设计与算法层面的问题,不是「这次改动有没有坏」。拿不准就走全量——全量的产出可以裁成快模式,快模式的产出补不回全量。

快模式的完整契约(范围、只报什么、输出形态、什么时候升级到全量)见 `references/regression-review.md`。

Expand All @@ -53,13 +53,26 @@
| 2 | 方法契约 | 参数是否遗漏?缺省值是否有歧义(没传 vs 传了零值)?调用方会不会传错、漏传,或被迫绕开函数自己拼? |
| 3 | 实现 | 在什么输入、状态或并发交错下会算错、漏处理、泄漏、死锁? |
| 4 | 文档 | 读者照着注释/README/错误信息会不会做错事? |
| 5 | 硬编码 | 哪个值本该随环境/租户/调用方/数据规模/版本变化,却被写死在代码里? |
| 6 | 重复 | 同一行为是否存在第二个真相源? |
| 5 | 硬编码 | 哪个值被写死了,而它应当可变?先分清它是**协议固定值**(改了就是 bug)还是**业务政策值**(改了只是口径变了,如退款窗口、账期)? |
| 6 | 重复 | 同一行为是否存在第二个真相源?同一个概念是否分裂成了几条行为不一致的路径? |
| 7 | 过度设计 | 删掉它,今天会有什么损失? |

另加扩展面:错误路径与部分失败、并发与生命周期、安全、兼容性、可观测性、性能、测试盲区。

## 三个机制
七维之外还有两遍:

- **反驳**:先假设设计本身可能是错的,对每个公开概念质问四句——它有几处实现?同一条业务动作在正常/异常/恢复路径上语义一致吗?统一调用方能用同一个类型吗?职责有没有被另一个抽象认领?这一遍抓的是**语义分裂**与**职责重叠**,产出大多进「需要你拍板」。
- **规模扫描**:对每条含循环、递归、聚合、查找、拷贝的路径问——规模 N 是什么、随 N 怎么长、有没有重复访问同一状态/每层拷贝完整结果/每次重新全量扫描。**规模问题不需要有错误结果才算数**,它的证据是规模关系加实测。

## 四个机制

### 反驳一遍

七维全是「和现有东西比」——第 1 维问能不能组合出来,第 6 维问有没有第二个真相源,第 7 维问删掉损失什么。**没有一个动作要求质疑设计本身。**

反驳这一遍补的就是这个:对每个公开概念(类型、接口、入口、操作、状态名)逐条质问它凭什么存在。抓的典型形态是**语义分裂**——同一个动作有「普通版」和「可靠版」两个名字,两者在异常路径上分叉,文档还只描述了其中一条。

每条质问必须落到「谁会因为这个不一致而写错、改错或被绊住」,指不出具体后果就删掉。反驳不是找茬。

### 证伪闸门

Expand All @@ -68,8 +81,10 @@
- 实现 bug → 具体输入是什么?走到哪一行?得到什么错误结果?
- 并发问题 → 两个执行体在哪个窗口交错?共享对象是什么?
- 重复 → 哪条需求变了,这两处必须一起改?
- 语义分裂 → 两条路径各是什么?一个具体场景下它们的结果差在哪?调用方凭什么知道该走哪条?
- 过度设计 → 删掉它,今天的损失是什么?
- 硬编码 → 它必须随什么变化?不变时会怎样静默过期?
- 硬编码 → 它是协议固定值还是业务政策值?若是业务政策值:必须随什么业务口径变化?不改会怎样静默过期?
- 规模 → N 的取值范围是多少?这条路径随 N 怎么长?实测开销是多少?

这条规则的作用不是让报告更短,而是让每条结论都能被作者复核。

Expand All @@ -81,13 +96,13 @@

七维是通用面,但有些缺陷只在特定改动类型里高频出现:

- **批处理 / Job / CLI**:成功判定、游标语义、幂等、环境隔离、dry-run、参数绑定、分页;
- **批处理 / Job / CLI**:成功判定、游标语义、幂等、环境隔离、dry-run、参数绑定、分页、规模;
- **数据重放 / 迁移 / 回填**:时间窗口上下界、数据快照、未来数据泄漏、重复执行、只读宣称;
- **API / 库 / SDK**:默认值、零值歧义、向后兼容、错误语义;
- **API / 库 / SDK**:默认值、零值歧义、向后兼容、错误语义、共享状态、零值可用性、单位一致性、跨层形状、规模;
- **并发 / 服务 / 守护进程**:锁顺序、取消传播、关闭顺序、后台线程;
- **配置 / 部署 / 脚本**:环境差异、密钥、退出码、可观测性。

每份 playbook 都标注了它覆盖了扩展维度的哪些条目——**扫完 playbook 即视为那些条目已覆盖,不重复扫**。
每份 playbook 都标注了它覆盖了扩展维度的哪些条目——**扫完 playbook 即视为那些条目已覆盖,不重复扫**。**规模扫描不被任何 playbook 覆盖**:它跟改动类型无关,只要代码里有循环、递归、聚合、查找或整块拷贝就要跑;playbook 里带「规模」标记的条目是该类型的高发场景,不是它的替代品。

## 快速开始

Expand Down Expand Up @@ -171,22 +186,27 @@ git clone https://github.com/Luo-root/deep-code-review.git ~/.claude/skills/deep

**为什么保留"需要你拍板"?** 设计后果不都是缺陷。把"设计使然"和"bug"分开,作者才不用在错误的问题上改代码。

**为什么要单独跑"反驳"?** 七维全是「和现有东西比」——能不能组合出来、有没有第二个真相源、删掉损失什么。**没有一个动作要求质疑设计本身。** 于是同一个动作分裂成"普通版"和"可靠版"、抽象层与后端层的类型形状不一致、职责被两个抽象同时认领——这些都在七维的缝隙里漏掉。反驳这一遍把"先假设设计是错的"变成一个固定动作,而不是可选项。

**为什么规模扫描要单独跑?** 七维第 3 维的成立条件是「输入 → 走到哪行 → 错误结果」,而复杂度问题**没有错误结果**——它表现为随规模爆炸。按七维的闸门去卡,它永远不成立。所以它需要自己的证据形态:规模关系加实测数字。

## 目录

```text
.
├── SKILL.md # 执行流程、两档模式、七维速查、分级、输出契约
├── SKILL.md # 执行流程、两档模式、反驳、七维速查、规模扫描、分级、输出契约
├── references/
│ ├── dimensions.md # 七维扫描动作与误报边界
│ ├── dimensions.md # 七维扫描动作与误报边界 + 规模与复杂度
│ ├── playbooks.md # 按改动类型的追加检查
│ ├── verification.md # 证伪闸门与证据阶梯
│ ├── regression-review.md # 快模式:合并判定契约(不依赖任何其他 skill)
│ └── output-template.md # 六段式报告骨架与示例
├── evals/ # 可复现评测护栏
│ ├── fixtures/tiny-shop/ # 自写的样本仓库(12 个已知缺陷 + 1 个确认点)
│ ├── fixtures/tiny-shop/ # 自写的样本仓库(25 个已知缺陷 + 1 个确认点)
│ ├── ground-truth.md # 标准答案
│ ├── rubric.md # 评分表
│ └── runbook.md # 操作手册
│ ├── runbook.md # 操作手册
│ └── baseline.md # 历次评测基线(追加,不覆盖)
├── tools/
│ └── lint-skill.mjs # 仓库自带的 skill 校验器
├── .github/workflows/ci.yml # CI:换行符 + skill lint
Expand All @@ -203,7 +223,11 @@ git clone https://github.com/Luo-root/deep-code-review.git ~/.claude/skills/deep

同一 skill 两轮之间会有波动,它不是确定性工具;它的价值是把"证据在哪、结论有多强"写清楚,最终判断仍然由人做。

因为它有波动,**"改完 skill 之后有没有变好"不能靠感觉**。`evals/` 里有一套可复现的护栏:一份自写的、带 12 个已知缺陷的样本仓库,加标准答案、评分表和操作手册。它同时测「能不能找到 bug」和「会不会乱报」——后者才是让作者不看报告的主因。
因为它有波动,**"改完 skill 之后有没有变好"不能靠感觉**。`evals/` 里有一套可复现的护栏:一份自写的、带 25 个已知缺陷的样本仓库,加标准答案、评分表和操作手册。它同时测「能不能找到 bug」和「会不会乱报」——后者才是让作者不看报告的主因。

首轮评测跑下来的结论值得记一笔:**三轮共同漏掉的两条,恰恰是标准答案自己写错的那两条**——所以「漏报率」这个指标在标准答案没校准之前,是不能直接拿来比较 skill 好坏的。这也是 `evals/baseline.md` 存在的理由:它同时记分数和口径缺陷。

**样本决定了测得到什么。** 现有样本是 150 行的结算模块,它测得出契约、文档、错误路径、并发这些面,**测不出算法复杂度与语义分裂**——样本里没有指数级回溯,也没有分裂成两条路径的动作。新能力要落地,得先有能触发它的样本与标准答案条目,否则「改完变好了还是变坏了」又变成凭感觉。

```bash
node tools/lint-skill.mjs . # 本地跑一遍 skill 校验
Expand Down
Loading
Loading