# Codebase Design

用于设计深模块的共享词汇。适用于用户想设计或改进模块接口、寻找深化机会、决定 seam 放在哪里、让代码更容易测试或更适合 AI 导航，或其他技能需要深模块词汇时。

- Repository: https://github.com/vinvcn/mattpocock-skills-zh-CN (5461 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-28
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add vinvcn/mattpocock-skills-zh-CN --skill codebase-design -g -a claude-code -y`
Codex: `npx skills add vinvcn/mattpocock-skills-zh-CN --skill codebase-design -g -a codex -y`
Cursor: `npx skills add vinvcn/mattpocock-skills-zh-CN --skill codebase-design -g -a cursor -y`
Gemini CLI: `npx skills add vinvcn/mattpocock-skills-zh-CN --skill codebase-design -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add vinvcn/mattpocock-skills-zh-CN`

## Description

用于设计深模块的共享词汇。适用于用户想设计或改进模块接口、寻找深化机会、决定 seam 放在哪里、让代码更容易测试或更适合 AI 导航，或其他技能需要深模块词汇时。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 代码库设计

设计 **deep modules**：把大量行为放在小 interface 之后，把 interface 放在清晰 seam 上，并通过该 interface 测试。凡是在设计或重构代码时，都使用这套语言和原则。目标是给 callers 带来 leverage，给 maintainers 带来 locality，并让每个人都更容易测试。

## 术语表

准确使用这些术语，不要替换成 "component"、"service"、"API" 或 "boundary"。一致语言就是重点。

**Module** - 任何拥有 interface 和 implementation 的东西。它故意不限定尺度：function、class、package，或跨层 slice 都可以。_Avoid_: unit, component, service.

**Interface** - caller 为了正确使用 module 必须知道的一切：type signature，以及 invariants、ordering constraints、error modes、required configuration 和 performance characteristics。_Avoid_: API, signature（太窄，只指 type-level surface）。

**Implementation** - module 内部的代码体。它不同于 **Adapter**：一个东西可以是小 adapter 但有大 implementation（Postgres repo），也可以是大 adapter 但 implementation 很小（in-memory fake）。讨论 seam 时说 adapter；其他时候说 implementation。

**Depth** - interface 上的 leverage：caller（或 test）每学习一单位 interface，就能触达多少行为。大量行为藏在小 interface 后面时，module 是 **deep**；interface 几乎和 implementation 一样复杂时，module 是 **shallow**。

**Seam**（Michael Feathers）- 你可以在不编辑当前位置的情况下改变行为的地方；也就是 module 的 interface 所在的 *location*。seam 放在哪里是独立设计决策，不同于 seam 后面放什么。_Avoid_: boundary（它和 DDD bounded context 过载）。

**Adapter** - 在 seam 上满足某个 interface 的具体东西。描述的是 *role*（填哪个槽位），不是 substance（内部是什么）。

**Leverage** - callers 从 depth 获得的收益：每学习一单位 interface，就得到更多能力。一个 implementation 会在 N 个 call sites 和 M 个 tests 中回本。

**Locality** - maintainers 从 depth 获得的收益：change、bugs、knowledge 和 verification 集中在一个地方，而不是散到 callers 里。修一次，到处都修好。

## Deep 与 shallow

**Deep module** = small interface + lots of implementation:

```text
+------------------+
| Small Interface  | -> few methods, simple params
+------------------+
|                  |
| Deep             | -> complex logic hidden
| Implementation   |
|                  |
+------------------+
```

**Shallow module** = large interface + little implementation（避免）：

The rest: https://github.com/vinvcn/mattpocock-skills-zh-CN/blob/HEAD/skills/engineering/codebase-design/SKILL.md