改进代码库架构

揭示架构摩擦并提出深化机会——将浅模块转变为深模块的重构。目标是可测试性和 AI 可导航性。

术语表

在每个建议中精确使用这些术语。一致的语言是重点——不要偏离到"组件"、"服务"、"API"或"边界"。完整定义在 LANGUAGE.md 中。

• 模块——任何具有接口和实现的东西（函数、类、包、切片）。
• 接口——调用者使用模块必须知道的一切：类型、不变量、错误模式、顺序、配置。不仅仅是类型签名。
• 实现——内部的代码。
• 深度——接口处的杠杆：小接口后面的大量行为。深 = 高杠杆。浅 = 接口几乎与实现一样复杂。
• 接缝——接口所在的位置；可以在不编辑位置的情况下改变行为的地方。（使用这个，而不是"边界"。）
• 适配器——在接缝处满足接口的具体事物。
• 杠杆——调用者从深度中获得的东西。
• 局部性——维护者从深度中获得的东西：更改、bug、知识集中在一个地方。

关键原则（完整列表参见 LANGUAGE.md）：