agentleFS
guang-lee-cnguang-lee-cn/scaffold-skills/skills/class-design-review/SKILL.md

class-design-review

Skill2 starsChanged 13 days agoMITView on GitHub

类与结构体设计的红绿判定:成员聚合是否成簇、不变式有无类型承载、声明序与依赖序、锁跨度与并发写点、抽象是否落成类型约束、拷贝/移动/析构一致性。评审"这个 class/struct 站不站得住"时用;不教怎么写(正向样本看 cpp-exemplars)。触发词:类设计/结构体设计/class 评审/成员聚合/不变式/声明序/析构顺序/锁跨度/抽象是否合理/大杂烩设计/成员变量组合。

The file

Files
SKILL.md

类与结构体设计评审

定位

判"设计是否站得住",不判"业务是否正确",不教"该怎么写"。要正向样本 → cpp-exemplars; 技能只给判据与产出格式,改法留给执行者。

术语对齐(先对齐,否则判定会飘)

词本文口径
不变式任何时候都必须成立的关系(如"名字与句柄同生共死")。判据:能否一句话说出"它破了哪个行为会错"
聚合成员按"共同变化"聚成簇。判据:改一个需求时,是否只有一簇成员被改
抽象用类型把约束表达出来(让非法状态不可表示)。不是"多加一层接口"或"多一个基类"
承载不变式由类型/编译器保证(构造即拒绝、非法态不可构造),而非注释、约定或调用顺序

硬线(违反即红,不参与"权衡")

#硬线判据(可机械判断)
H1不变式必须有类型承载删掉所有注释后,仍能构造出违反该不变式的对象 → 红
H2声明序 = 依赖序成员 A 的生存期须覆盖使用 A 的成员 B ⇒ B 声明在 A 之后;典型反例:线程成员声明在被它访问的容器之前
H3锁不得跨慢操作持锁区间内出现 IO / 网络 / 实体创建(如 DDS 端点)/ 阻塞等待 → 红
H4锁与它保护的数据同处一个类型同一类里既有裸 mutex 又有多组互不相关的数据 → 红(锁应下放到数据所在类型)
H5并发写点 > 1 时不得共用一把锁计数/记账类成员被多线程写且走 mutex → 红(应原子或分片)
H6基类析构:public+virtual 或 protected+非虚其它组合 → 红
H7拷贝/移动/析构成对定义了其一而另一未定义/未 delete;资源类析构非 noexcept → 红
H8跨对象存活的回调不得捕获裸 this回调存入生命周期更长的对象且捕获 this/裸指针 → 红(除非有文档化不变式保证其存活)

十二维(判据细则见 references/dimensions.md)

1 不变式承载 · 2 职责单一 · 3 内聚(有无并行集合)· 4 依赖方向 · 5 暴露面 · 6 所有权与归还 · 7 特殊成员函数 · 8 异常安全等级 · 9 线程安全契约 · 10 初始化/析构顺序 · 11 可测试性 · 12 演进性(新增一类实体要改几处)

分级与出报告口径

  • 红 = 触硬线 H1–H8
  • 黄 = 可收敛、但当前不阻碍正确性(如并行集合、双布尔表一状态、内聚偏低)
  • 绿不入报告——只出红黄,避免绿清单淹没问题

产出格式

每条 finding 必须五段齐全,缺一即视为无效 finding:

[维度] H?/1..12 | 等级 红|黄
判据:<引用的硬线或维度判据原文>
证据:<file:line>(含关键行摘录)
影响:<哪条不变式/哪个行为会错>
建议方向:<指向类型或边界,不写实现步骤>

报告末尾必须给三项:① 命中硬线计数;② 红/黄计数;③ 未覆盖面(哪些维度因信息不足未评)。 未覆盖面不得省略——省略等于假绿。

防假绿三条

  1. "注释里写了"不算承载——注释是不变式的说明,不是保证。
  2. "以后会改"不算理由——按当前代码判,不按意图判。
  3. "测试过了"不豁免 H2/H3——测试覆盖行为,不覆盖析构顺序与锁跨度。

边界(明确不做)

  • 不评业务语义正确性、不评算法复杂度
  • 不评命名风格(→ comment-policy、test-naming-and-structure)
  • 不评性能数值,只评"锁是否跨慢操作"这一结构性问题
  • 不把"抽象层数多"当缺陷:抽象只看"非法状态是否仍可表示"

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.