# Improve Codebase Architecture

扫描代码库中的深化机会，生成可视化 HTML 报告，然后围绕你选中的候选项继续追问。

- 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 improve-codebase-architecture -g -a claude-code -y`
Codex: `npx skills add vinvcn/mattpocock-skills-zh-CN --skill improve-codebase-architecture -g -a codex -y`
Cursor: `npx skills add vinvcn/mattpocock-skills-zh-CN --skill improve-codebase-architecture -g -a cursor -y`
Gemini CLI: `npx skills add vinvcn/mattpocock-skills-zh-CN --skill improve-codebase-architecture -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add vinvcn/mattpocock-skills-zh-CN`

## Description

扫描代码库中的深化机会，生成可视化 HTML 报告，然后围绕你选中的候选项继续追问。

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

# 改进代码库架构

暴露 architectural friction，并提出 **deepening opportunities**：把 shallow modules 变成 deep modules 的 refactors。目标是 testability 和 AI-navigability。

这个命令由项目的 domain model 提供信息，并建立在共享 design vocabulary 上：

- 调用 Skill 工具并指定 `codebase-design`，获取 architecture vocabulary（**module**、**interface**、**depth**、**seam**、**adapter**、**leverage**、**locality**）及其 principles（deletion test、"the interface is the test surface"、"one adapter = hypothetical seam, two = real"）。每条建议都准确使用这些术语，不要漂移到 "component"、"service"、"API" 或 "boundary"。
- `GLOSSARY.md` 中的 domain language 会为好的 seams 命名；`docs/adr/` 中的 ADRs 记录这个命令不应重新争论的 decisions。

## 流程

### 1. 探索

**先划定扫描范围：YAGNI。** 深化 module 的收益在于让未来修改更容易，因此要更关注最近仍在变化的 codebase 区域。开始探索前先决定去哪里看：

- 如果用户点名了方向（module、subsystem 或 pain point），就按该方向探索，跳过下面的推断。
- 否则，向前回看一段足够长的 commit history（`git log --oneline`），找出反复出现的 files 和 areas，让这些 hot spots 成为首要关注点。如果变更分散、没有明显 hot spot，再扩大范围。

先读取项目 domain glossary（`GLOSSARY.md`）以及你将触碰区域的 ADRs。

然后 spawn 一个 sub-agent 来遍历 codebase。不要套死板 heuristics；自然探索，并记录你感到 friction 的地方：

- 理解一个概念是否需要在许多小 modules 之间来回跳？
- 哪些 modules 是 **shallow** 的，即 interface 几乎和 implementation 一样复杂？
- 是否存在为了 testability 抽出的 pure functions，但真正 bugs 藏在它们如何被调用之处（没有 **locality**）？
- 哪些 tightly-coupled modules 泄漏到了 seams 之外？
- Codebase 的哪些部分未测试，或很难通过当前 interface 测试？

对任何你怀疑 shallow 的东西应用 **deletion test**：删除它会让复杂度集中，还是只把复杂度移动到别处？"yes, concentrates" 才是你要的 signal。

### 2. 用 HTML 报告呈现候选项

把 self-contained HTML file 写到 OS temp directory，避免任何内容落进 repo。Temp dir 从 `$TMPDIR` 解析，fallback 到 `/tmp`（Windows 用 `%TEMP%`），写到 `<tmpdir>/architecture-review-<timestamp>.html`，让每次运行都有新文件。为用户打开它：Linux 用 `xdg-open <path>`，macOS 用 `open <path>`，Windows 用 `start <path>`，并告诉用户 absolute path。

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