类型系统的一个经典论断:让非法状态不可表示(make illegal states unrepresentable)——设计得好的类型在编译期就堵死 bug,而不是靠运行时检查和文档约定兜底。pr-review-toolkit 插件里的 type-design-analyzer Agent 把这套类型设计方法论做成了自动化审计:识别类型的不变量(invariants),从封装性、表达力、实用性、执行强度四个轴各打 1~10 分,输出结构化设计评审。本文按"定位 → 四轴分析框架 → 反模式清单 → 提示词工艺 → 总结"拆解这份官方 Agent 定义。
1、定位:类型设计专家
提示词开篇定义人设:"type design expert with extensive experience in large-scale software architecture",专长是分析与改进类型设计,确保其不变量强、表达清晰、封装良好。核心信念同样开门见山——设计良好的类型是可维护、抗 bug 软件系统的地基。
frontmatter 为 model: inherit、color: pink。description 给了三类触发场景:引入新类型时确保封装与不变量遵循最佳实践、创建 PR 时评审全部新增类型、重构存量类型时提升设计质量——覆盖类型的诞生、合入、改造三个时刻。
内嵌的两个代表性场景:用户刚写完一个处理认证与权限的领域模型类型,想要确认不变量与封装的设计质量;用户准备提交一个引入多个新数据模型类型的 PR,要求评审 diff 里每个新类型。第二个场景点出了它的批量工作模式——PR diff 里的每个新类型都过一遍四轴评审。
2、四轴分析框架
分析流程分两步:先识别不变量,再在四个维度各打一个 1~10 分。
第一步:识别不变量。找出类型的全部隐式与显式不变量——数据一致性要求、合法状态转移、字段间关系约束、编码在类型里的业务规则、前置与后置条件。这一步是后面所有评分的基础:不变量找不全,四轴分数就是空中楼阁。
第二步:四轴评分。每轴 1~10 分,各带一组检查问题:
| 维度 | 评什么 | 关键检查项 |
|---|---|---|
| 封装性 | 内部实现是否藏好 | 实现细节是否隐藏、不变量能否被外部破坏、访问修饰符是否得当、接口是否最小且完备 |
| 不变量表达力 | 约束是否通过结构清晰传达 | 结构是否自文档、能否编译期强制、边界与约束是否从类型定义一目了然 |
| 不变量实用性 | 约束是否防真 bug | 是否防住真实错误、是否对齐业务需求、是否让代码更易推理、松紧是否得当 |
| 不变量执行强度 | 约束是否被切实把守 | 构造时是否校验、所有变更点是否设防、能否杜绝非法实例、运行时检查是否得当 |
四个轴构成一条从"设计"到"落地"的链:封装是基础,表达是沟通,实用性是价值,执行强度是保障——一个类型封装再好、执行不设防,非法实例照样能造出来。
3、反模式与改进克制
提示词列了七类常见反模式,每条都是可直接对号入座的坏味道:
- 贫血领域模型(只有数据没有行为)
- 暴露可变内部状态的类型
- 只靠文档维持的不变量
- 职责过多的类型
- 构造边界缺失校验
- 各变更方法的执行不一致
- 依赖外部代码维持不变量的类型
与之配套的是一节"当建议改进时"的自我约束:始终考虑建议的复杂度成本、改进是否配得上潜在破坏性变更、存量代码库的技术水平与惯例、额外校验的性能影响、安全与易用之间的平衡。提示词甚至说出了关键的一句:"Sometimes a simpler type with fewer guarantees is better than a complex type that tries to do too much"——有时保证更少的简单类型优于大而全的复杂类型。评审者被要求克制,不做过度设计推手。
关键原则一节同样务实:优先编译期保证而非运行时检查、清晰表达优于聪明、完美是好的敌人、构造器校验是维持不变量的关键、不可变性常能简化不变量维护——这是 Martin Fowler 与 Haskell 社区类型设计思想的大众化浓缩。
4、提示词工艺
这个定义的手法与 pr-test-analyzer 一脉相承——量表化,但更进一步:四轴各有独立量表,输出格式直接内嵌评分模板(每个类型一份"不变量清单 + 四项评分加理由 + 优势 / 关注点 / 改进建议"的结构化报告)。模型没有自由发挥空间,产出天然可比较、可追踪——同一个类型重构前后的两次评审,四轴分数的变化就是量化证据。
另一个值得学的细节是框架的检查项写成问题而非陈述:"不变量能否被外部破坏?"、"能否杜绝非法实例?"——问句形式引导模型逐项自查,比陈述式规则的执行率高,这是提示词工程里"用问题驱动检查"的典型应用。
输出模板里每个分数都要求附"Brief justification"(简短理由),防止模型只给数字不说话——评分必须可解释,这让报告的读者(人或主 Agent)能够质疑与修正。
5、总结
type-design-analyzer 是官方 pr-review-toolkit 插件的类型设计审计 Agent:先识别不变量、再按封装性 / 表达力 / 实用性 / 执行强度四轴各打 1~10 分,输出带理由的结构化报告;七类反模式清单加"改进克制"的自我约束,让它在严格与务实之间站稳——推动好的类型设计,但不做过度设计推手,"让非法状态不可表示"是它的精神底色。
它适合三个时机:新类型落地前的设计自检、PR 里批量新类型的合入评审、存量类型的重构导航。装好插件后自然语言触发("评审一下这个 PR 里的类型设计")。边界方面:四轴评分是模型判断,阈值含义因团队而异,建议在 CLAUDE.md 里写明自己的分数口径;它的框架偏静态类型语言(TypeScript / Rust / Kotlin 等),动态语言项目里"编译期强制"一轴会失去意义,评分需人工重新加权;分析基于 diff 与可见代码,跨服务的分布式约束不在其视野内。对"类型设计怎么算好"这个评审难题,这份官方提示词给出了可操作的答案:找出不变量,四个维度打分,用分数说话。


