# Improve Codebase Architecture

> 在代码库中查找深化机会，参考 CONTEXT.md 中的领域语言和 docs/adr/ 中的决策。当用户想要改进架构、查找重构机会、整合紧密耦合的模块或使代码库更可测试和 AI 可导航时使用。

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

---


# 改进代码库架构

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

## 术语表

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

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

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

- **删除测试**：想象删除模块。如果复杂性消失，它是透传。如果复杂性在 N 个调用者中重新出现，它就在发挥作用。
- **接口是测试表面。**
- **一个适配器 = 假设的接缝。两个适配器 = 真实的接缝。**

此技能_参考_项目的领域模型。领域语言为好接缝命名；ADR 记录技能不应重新讨论的决策。

## 流程

### 1. 探索

首先阅读项目的领域术语表和你要接触的区域中的任何 ADR。

然后使用带有 `subagent_type=Explore` 的 Agent 工具遍历代码库。不要遵循僵化的启发式方法——有机地探索并注意你遇到摩擦的地方：

- 理解一个概念需要在许多小模块之间跳转的地方？
- 哪些模块是**浅的**——接口几乎与实现一样复杂？
- 纯函数是否仅为了可测试性而被提取，但真正的 bug 隐藏在它们的调用方式中（没有**局部性**）？
- 紧密耦合的模块在哪里跨越其接缝泄漏？
- 代码库的哪些部分未测试，或通过其当前接口难以测试？

对你怀疑是浅层的任何东西应用**删除测试**：删除它会集中复杂性，还是只是移动它？"是的，集中"是你想要的信号。

### 2. 展示候选者

展示深化机会的编号列表。对于每个候选者：

- **文件**——涉及哪些文件/模块
- **问题**——为什么当前架构导致摩擦
- **解决方案**——用通俗英语描述会发生什么变化
- **好处**——用局部性和杠杆来解释，以及测试将如何改进

**对领域使用 CONTEXT.md 词汇，对架构使用 [LANGUAGE.md](LANGUAGE.md) 词汇。** 如果 `CONTEXT.md` 定义了"Order"，谈论"Order 接收模块"——而不是"FooBarHandler"，也不是"Order 服务"。

**ADR 冲突**：如果候选者与现有 ADR 矛盾，仅在摩擦足够真实值得重新审视 ADR 时才提出。清楚地标记它（例如_"与 ADR-0007 矛盾——但由于……值得重新开放"_）。不要列出 ADR 禁止的每个理论重构。

不要提议接口。询问用户："你想探索其中的哪一个？"

### 3. Grilling 循环

一旦用户选择了一个候选者，进入 grilling 对话。与他们一起遍历设计树——约束、依赖、深化模块的形状、接缝后面的内容、哪些测试幸存。

副作用随着决策的结晶内联发生：

- **以不在 `CONTEXT.md` 中的概念命名深化模块？** 将该术语添加到 `CONTEXT.md`——与 `/grill-with-docs` 相同的纪律（参见 [CONTEXT-FORMAT.md](../grill-with-docs/CONTEXT-FORMAT.md)）。如果文件不存在则惰性创建。
- **在对话中 sharpening 模糊术语？** 立即更新 `CONTEXT.md`。
- **用户以有负载的原因拒绝候选者？** 提供 ADR，框架为：_"想让我将其记录为 ADR，以便未来的架构审查不会重新建议它吗？"_ 仅在原因真正被未来探索者需要以避免重新建议相同内容时才提供——跳过短暂原因（"现在不值得"）和自明的原因。参见 [ADR-FORMAT.md](../grill-with-docs/ADR-FORMAT.md)。
- **想要探索深化模块的替代接口？** 参见 [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md)。