一句话
设计 deep modules：大量行为 · 小 interface · 干净 seam · 经 interface 可测。
这是语言不是流程——不写架构 HTML、不代重构；给 leverage / locality / 可测性统一用词。
何时伸手
- 设计/改进 module interface、找 deepening、决定 seam、可测性 / AI-navigable
- 其它 skill 需要 deep-module 词汇（architecture、tdd、to-spec…）
- 不要用它修领域术语 →
domain-modeling；整库 survey → improve-codebase-architecture
Glossary（禁替代词）
- Module
- 有 interface + implementation 的任何尺度（函数/类/包/切片）。避免：unit、component、service。
- Interface
- 调用者必须知道的一切：签名 + invariants、顺序、错误模式、配置、性能。避免：API、signature（过窄）。≠ TS
interface 关键字全集。
- Implementation
- 模块内部代码体。谈「里面是什么」用它；谈「填哪个槽」用 adapter。
- Depth
- Interface 上的 leverage。Deep = 小面后大行为；shallow = 面与实现几乎同复杂。用 leverage 量，不用行数比。
- Seam（Feathers）
- 可不编辑该处即改变行为的位置；interface 的落点。避免：boundary（DDD 过载）。
- Adapter
- 在 seam 上满足 interface 的具体物（角色，非物质）。
- Leverage
- 调用者收益：每学一单位 interface 得到更多能力；一份实现服务 N 调用 + M 测试。
- Locality
- 维护者收益：变更/缺陷/知识/验证集中一处。
关系（记骨架）
Module ──has one──► Interface ──lives at──► Seam ──filled by──► Adapter
Depth 属性在 Interface 上；Depth → Leverage（调用者）+ Locality（维护者）
Internal seams 可存在于实现内；勿为测试暴露到 external interface
四原则
- Depth 是 interface 的属性，不是 implementation 的属性
- Deletion test：删模块 → 复杂度消失=pass-through；散回 N 调用者=赚 keep
- Interface is the test surface：调用者与测试同 seam；想测穿 → 形状多半错
- One adapter = hypothetical；two = real：无变化轴不开 seam
Deep vs shallow
Deep: 小 interface + 深 implementation（藏复杂度）
Shallow: 大 interface + 薄 implementation（转发）— 避免
三问：少方法？简参数？多藏复杂度？
可测性三启发式
- Accept dependencies, don't create them
- Return results, don't produce side effects
- Small surface area
Rejected framings
- Depth = 实现行数/接口行数（注水）→ 用 leverage
- Interface = 仅 public methods / TS keyword
- Boundary 代替 seam
DEEPENING · 依赖类别
| # | 类 | 测法要点 |
|---|
| 1 | In-process | 合并；直接经 interface 测；无 adapter |
| 2 | Local-substitutable | PGLite 等 stand-in；内部 seam；对外不必 port |
| 3 | Remote but owned | Port + HTTP/gRPC prod adapter + in-memory test |
| 4 | True external | 注入 port；mock adapter |
Replace, don't layer：新测在深 interface → 删旧浅 unit tests；
断言可观察结果；测试应扛住内部 refactor。
DESIGN-IT-TWICE · 流程卡
- Frame problem space（约束、依赖类别、非提案 sketch）→ 给用户后立刻并行
- 3+ sub-agents：极简面 / 最大灵活 / 最常见调用者 /（可选）ports&adapters；brief 含 SKILL 词 + CONTEXT 词
- 顺序展示 → 比 depth · locality · seam placement → 给推荐（可 hybrid）
消费者
improve-codebase-architecture — survey + temp HTML；用词强制；pick → grill → 可选 design-it-twicetdd / implement — 先约定 seams；interface = 测试面to-spec — sketch seams（优先已有、尽量高、越少越好）domain-modeling — 平行地板（领域词 vs 模块形状）
副作用
单独使用：主要无持久副作用（词汇与设计讨论）。
Temp HTML 报告是 architecture 的事，不是本 skill。
真改代码形状 → 主 flow / tdd。
下一步
- 形状清了 → to-spec 或在约定 seam 上 tdd
- 从 architecture 选出 deepening → grill-with-docs 进主 flow
- design-it-twice 后 → 决策进 spec/ADR → implement