# Codebase Design

> 判断复杂规则的职责归属与必要接口。适用于实现或评审中需要调整模块边界、适配器或测试接缝的设计取舍。

- Skill: `zuozh11/codebase-design` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add zuozh11/codebase-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zuozh11/codebase-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zuozh11 (https://skillmd.com/u/zuozh11)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zuozh11/codebase-design

---


# Codebase Design

让必须共同变化的业务规则集中在明确的函数、类或模块中，由这个所有者承担复杂度，消费者只接触必要接口。复杂度能够消失时删除；现有所有者能够承担时直接收回；只有没有合适所有者时才创建最小的新所有者。

按项目知识协议使用相关 CONTEXT 与适用 RULE；已有知识足够时复用，知识不可用时说明缺口并继续。

实现选择先读取 [MIN-IMPL.md](./MIN-IMPL.md)，停在第一项成立的位置。不要为了套用本 Skill 创建接口、模块或接缝。

## 所有权判断

对准备抽取或保留的每段结构执行删除检验：

- 删除后复杂度随之消失：删除或内联；
- 删除后同一业务规则散落到多个调用者：集中到已有所有者；
- 规则确实需要共同变化但没有所有者：创建一个最小所有者；
- 只是转发调用、改名、调换参数或补固定默认值：调用方直接表达更清楚时内联。

调用方数量不是单独依据。两个调用方共享多项必须共同变化的业务不变量，可以集中；十个调用方调用一行 getter，也可能不值得封装。

新结构必须同时指出：

- 不可删除的业务规则或边界行为；
- 负责这些规则的所有者；
- 使用该所有者的真实消费者；
- 删除或替换的旧结构。

一个实现不创建可替换接口、工厂或策略；一个固定值不创建配置。以最少概念和文件完成调整，替换旧结构而不是叠加新层。保留显式需求、信任边界校验、安全、无障碍和防止数据丢失的必要行为。

## 必要词汇

**真实复杂度**：需求本身要求且删除后仍会由调用者承担的业务规则、状态变化、边界处理或外部交互。

**所有者**：唯一负责一组必须共同变化规则的现有函数、类或模块。

**接口**：消费者正确使用所有者必须知道的最小信息，包括签名、不变量、顺序约束和错误模式。

**接缝**：无需修改消费者即可替换真实外部行为的位置。一个实现通常不形成可替换接缝。

**适配器**：在必要接缝处连接具体外部行为的代码。不要只为测试创建生产适配器。

**局部性**：同一规则的变化、缺陷和验证集中在所有者内部，而不是散落到消费者。

引用真实代码时保留已有标识和项目术语，不为统一词汇强行重命名。

## 最小接口与依赖

- 接口只暴露当前消费者必须使用的操作，不为未来增加方法、参数或配置。
- 依赖只有在真实外部边界或两个真实实现需要替换时才注入；不要把每个 helper 都参数化。
- 优先使用依赖已有的客户端、类型和调用方式，不复制第三方接口。
- 根因修复放在所有调用者汇合的所有者处，不在每个调用者重复加分支。
- 返回值只有在能减少副作用或简化调用契约时才优于原地修改。
- 朴素实现优于聪明实现；两个同样小的方案选择边界行为更正确的一项。

## 验证面

沿用项目已有验证方式。只有用户要求或现有信号无法建立改动正确性时才补最小检查；不为每个内部函数创建测试层。测试通过所有者的必要接口观察行为，不绑定内部实现。

## 比较方案

只有用户要求比较方案，或确认必须创建新所有者但仍存在影响显著的接口分歧时，才读取 [DESIGN-IT-TWICE.md](./DESIGN-IT-TWICE.md)。普通实现采用第一个可行最小方案。