# Improve Codebase Architecture

> 扫描代码库中的模块深化机会，生成可视化 HTML 报告，并围绕用户选中的候选继续决策追问。

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

---


# Improve Codebase Architecture

发现架构摩擦并提出**模块深化机会**：把浅模块重构为深模块，提高可测试性和 AI 可导航性。本 Skill 只做只读探索、报告和决策收口，不修改业务代码；用户确认要实施后再进入 `impl`。

## 流程

### 1. 加载项目上下文

按项目知识协议使用相关 CONTEXT 与适用 RULE；已有知识足够时复用，知识不可用时说明缺口并继续。项目术语用于命名业务概念，相关 ADR 用于识别不应无故重新打开的既有决策。

读取 `codebase-design`，使用其中的职责归属、必要接口与局部性判断。这里的模块深化指：让消费者通过更简单的接口使用模块，把必须处理的复杂规则集中到模块内部。

### 2. 探索

**先限定扫描范围：YAGNI。** 深化模块的收益来自让未来变化更容易，因此优先关注近期频繁变化的区域。

- 用户指定模块、子系统或痛点时，直接使用该方向。
- 用户未指定时，查看一段足够长的 `git log --oneline`，找出反复出现的文件和热点区域；没有明显热点时再扩大范围。

把选定范围、相关 CONTEXT、RULE、ADR 和 `codebase-design` 判断准则交给一个只读子 Agent 探索。不要套用固定检查表，而是在理解代码时记录真实摩擦：

- 理解一个概念是否需要在许多小模块之间来回跳转？
- 哪些模块较浅，接口几乎与实现同样复杂？
- 哪些纯函数只是为了测试而抽出，但真实缺陷藏在调用方式中，缺少局部性？
- 哪些紧耦合模块让细节泄漏到接缝之外？
- 哪些区域无法通过当前接口自然测试？

对疑似浅模块执行**删除检验**：删除它会让复杂度消失，还是只会把复杂度重新散到多个调用者？复杂度重新散开才说明该模块具有深化价值。

### 3. 生成 HTML 报告

在操作系统临时目录写入一个新的 `architecture-review-<timestamp>.html`，不向仓库写入报告。优先使用 `$TMPDIR`，否则使用 `/tmp`；Windows 使用 `%TEMP%`。生成后用当前系统的默认方式打开，并向用户返回绝对路径。

报告使用 Tailwind CDN 完成布局和样式，使用 Mermaid CDN 表达调用图、依赖图和时序；需要质量感、剖面或折叠效果时使用手写 CSS、div 或内联 SVG。每个候选都必须有 before / after 可视化。

每个候选卡片包含：

- **涉及文件**：相关文件与模块；
- **问题**：当前架构造成的具体摩擦；
- **方案**：用业务可读语言说明要改变什么；
- **收益**：说明规则集中位置、消费者调用和必要验证如何改善；
- **Before / After**：并排展示当前浅形状与深化后形状；
- **推荐强度**：`强烈推荐`、`值得探索` 或 `推测性`。

有成立的候选时，在报告末尾给出一个**首选建议**及原因；没有可证实收益时直接说明，不为填满报告制造候选。

使用 CONTEXT 词汇命名业务概念，使用 `codebase-design` 词汇描述架构。候选与 ADR 冲突时，只有摩擦真实且足以重新讨论 ADR 才展示，并在卡片中明确标记冲突。

完整格式、图形模式和样式要求见 [HTML-REPORT.md](./HTML-REPORT.md)。此阶段不设计具体接口。有候选且用户尚未选择时，请用户选择下一步探索方向；用户已指定时直接继续。

### 4. 决策追问

用户选中候选后，依据已有需求和代码判断常规设计选择。关键取舍需要用户决定时，围绕该候选调用 `ask-me`；已确认的选择直接用于后续方案。

决策过程中：

- 出现新的长期项目术语或可复用规则时，按项目知识协议提出记录建议，并在用户确认后写入；
- 用户因长期、承重原因拒绝候选时，询问是否记录 ADR，避免未来重复建议；短期优先级等一次性原因不记录；
- 用户希望比较多种接口时，读取 `codebase-design` 的 `DESIGN-IT-TWICE.md` 并执行多方案设计；
- 用户确认实施时，结束本 Skill，转入 `impl`，不在架构探索流程内直接修改代码。