architecture-audit git:20261008.6378243A

Immutable. This exact content never changes and is served at /api/v1/blob/57224b94692713b0.

---
name: architecture-audit
description: 架构体检：找出该合并加深的浅模块，用 eli5 图解呈现，再为选中的一项并行设计几种接口。
disable-model-invocation: true
---

# 架构体检

找出值得加深的模块：接口几乎和实现一样复杂、理解一个概念要在许多小文件间来回跳、bug 藏在调用方式里的地方。目标是改一处就够、测试只打一个入口。

## 1. 圈范围

用户指了模块、子系统或痛点就只看那里。否则沿较长一段 `git log --oneline` 找反复改动的热点，优先看它们；改动分散时再扩大。按 [fan-out](../fan-out/SKILL.md) 中档按热点拆片，交回摩擦点及证据（文件、调用方）。

判断一个模块是不是透传层，用**删除测试**：想象删掉它，复杂度随之消失的是透传层；复杂度散回 N 个调用方的，它在干活。

## 2. 呈现

按 [eli5](../eli5/SKILL.md) 把候选画成图解，文件放 `$TMPDIR`，不进仓库。每个候选讲清：涉及文件、问题、改法、收益（用行为说：改价格规则只动一个文件，不写「更易维护」）、改前改后对比图、推荐强度（值得做 / 值得探索 / 推测）、依赖类别（见下）。最后说最先做哪一个及原因。此时不提接口方案，问用户想展开哪一个。

## 3. 设计接口

用户选定后，先写一段约束说明（新接口必须满足什么、依赖属于哪一类、一段粗略代码示意）给用户看，同时按 fan-out 高档并行出 3 个以上截然不同的接口：

- 最小接口：1–3 个入口，每个入口承担尽量多的行为。
- 最大灵活：支持多种用例与扩展。
- 为最常见的调用方优化：默认情况最简单。
- （跨进程依赖时）围绕端口与适配器设计。

每份方案交回：接口（类型、不变量、调用顺序、错误形态）、调用示例、藏在接口后面的东西、依赖与适配器、强弱处。逐个展示后比较：调用方学一个接口能用到多少行为、改动会不会集中在一处、接口放在哪。给出明确推荐，能取长补短就提混合方案。需要逐项和用户对齐决策时用 [grilling](../../workflow/grilling/SKILL.md)。

## 依赖类别

类别决定加深后怎么测：

1. **进程内**（纯计算、内存状态）：直接合并，经新接口测试。
2. **可本地替代**（PGLite 代 Postgres、内存文件系统）：用替代物测，不在接口上开端口。
3. **自有远程服务**：接口处定义端口，生产用 HTTP/队列适配器，测试用内存适配器。
4. **第三方服务**（Stripe 等）：作为注入的端口，测试给模拟适配器。

## 判断规则

- 只有一个适配器的端口是假设，两个（通常是生产 + 测试）才是真的；不够两个就别开端口，那只是多一层间接。
- 内部接缝可以给自己的测试用，不为此暴露到接口上。
- 加深后，浅模块上的旧单元测试删掉；新测试按 [better-test](../better-test/SKILL.md) 只经新接口断言可观察结果。