代码库架构优化

技能文档

---
name: codebase-architecture-review
title: 代码库架构优化
category: 开发工具
description: 扫描代码库发现架构深化机会，以可视化 HTML 报告呈现，然后针对选中的候选项进行深入讨论。目标：提升可测试性和AI可导航性。触发词：架构审查、代码库优化、模块深化、架构改进、代码重构建议。
---

# 代码库架构优化

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

## 设计词汇

本技能基于共享设计语言：
- **模块**（module）、**接口**（interface）、**深度**（depth）
- **接缝**（seam）、**适配器**（adapter）、**杠杆**（leverage）、**局部性**（locality）

核心原则：
- 删除测试：删掉它是否会集中复杂度？
- 接口即测试面
- 一个适配器 = 假设接缝，两个 = 真实接缝

## 执行流程

### 1. 探索

**先定范围再扫描 —— YAGNI。**

- 如果用户指定了方向，直接定位
- 否则回溯 commit 历史找热点文件

读取项目的领域术语表和 ADR（架构决策记录）。

探索时关注：
- 理解一个概念需要在多个小模块间跳转？
- 模块**浅** —— 接口几乎和实现一样复杂？
- 纯函数仅为测试提取，但真正 bug 在调用方式？
- 紧耦合模块跨接缝泄漏？

### 2. 生成 HTML 报告

写入系统临时目录（不进入仓库），自动打开。

每个候选项包含：
- **文件** — 涉及的模块
- **问题** — 当前架构为何造成摩擦
- **方案** — 变更描述
- **收益** — 局部性和杠杆角度
- **前后对比图** — 并排展示浅化和深化
- **推荐强度** — 强/值得探索/推测性

### 3. 深入讨论

用户选择候选项后，通过决策树讨论：
- 约束和依赖
- 深化模块的形状
- 接缝后面放什么
- 哪些测试保留

## 输出规范

- 报告用 Tailwind CDN 排版 + Mermaid CDN 画图
- 用项目领域词汇谈领域，用架构词汇谈架构
- ADR 冲突仅在摩擦真实存在时才提出

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。