improve-codebase-architecture Skill：扫描代码库生成可视化架构报告的工程神器

Skill超级捕获手 技术创作者 2026-08-16 13 阅读

总结

improve-codebase-architecture 是 Matt Pocock 出品的一个 Claude Code Engineering Skill，核心能力是自动扫描代码库寻找架构深化机会，生成带可视化图表的 HTML 架构报告，并引导你逐个”烧烤”每个改进候选。解决的是大型代码库里模块越写越浅、依赖越来越乱、测试越来越难写的通病。隶属拥有 21.8 万 star 的 mattpocock/skills 仓库，工程化程度极高。

功能与原则

核心能力： 扫描代码库 → 识别浅层模块/高耦合区域 → 生成带 Before/After 可视化的 HTML 报告 → 引导决策。

设计哲学：
– Deletion Test：删掉一个模块，复杂度是集中了还是分散了？”集中”才是好模块的信号。
– Depth over Width：模块要有真正的内部复杂度，而不是一堆简单方法的堆叠。
– One Adapter = Hypothetical Seam, Two = Real：单个适配器还只是假设的分界点，两个才构成真实接口。
– Locality：真实 bug 藏在调用方式里，而非被测函数的实现里。

认可度

  • GitHub Star：218,890（mattpocock/skills 整体，截至 2026-08-16）
  • Fork：18,860
  • 最近推送：2026-08-16（今日活跃）
  • 定位：Engineering Skill 分类，TypeScript 社区最活跃的 AI 编程 skill 合集

链接

GitHub：https://github.com/mattpocock/skills

子 Skill 路径：skills/engineering/improve-codebase-architecture/SKILL.md

原作者

Matt Pocock（@mattpocock）——TypeScript 界知名开发者，Total TypeScript 创始人。其 mattpocock/skills 仓库被称为”Real Engineers 的技能库”，每个 skill 都来自他真实高频使用的 .agents 配置。

介绍

大型代码库开发中，模块往往会自然”腐化”：原本设计良好的模块因为不断的需求变更而越写越浅，接口和实现复杂度差不多，新增功能要在十几个小文件间跳跃理解。这就是 improve-codebase-architecture 要解决的问题。

它首先从项目 CONTEXT.md 和 ADRs（Architecture Decision Records）中读取项目专属的领域词汇，然后用一套标准架构术语（module、interface、depth、seam、adapter、leverage、locality）对代码库进行有机扫描——不是死板的启发式规则，而是真正像资深工程师一样感受摩擦点。

扫描完成后，它把每个”架构深化机会”以卡片形式呈现在一个自包含的 HTML 报告中，每张卡片包含：涉及文件、问题描述、解决方案、收益分析，以及手绘 Before/After 可视化图。报告使用 Tailwind 做样式，Mermaid 做关系图，最后打开浏览器让你直接查看。

特点

  • 领域词汇感知：先读 CONTEXT.md 获取项目专属术语，用统一语言描述架构问题，避免”组件/服务/API”等模糊词汇
  • 子 Agent 并行扫描：扫描阶段会 spawn 一个 sub-agent 有机探索代码库，不依赖固定启发式规则
  • 可视化 HTML 报告：每次运行生成带时间戳的独立 HTML 文件到系统临时目录，浏览器直接打开，支持 Tailwind + Mermaid + 手绘 SVG
  • Before/After 双图对比：每个候选都有现状图和深化后图的并排展示
  • 推荐强度分级：每张卡片标注 Strong / Worth exploring / Speculative 三级推荐强度，帮助优先排序
  • 架构决策不重审：自动读取 docs/adr/ 目录，已决策事项不再重复讨论

使用方法

安装（从父仓库引入）：

claude skills add mattpocock/skills/engineering/improve-codebase-architecture

触发：

/improve-codebase-architecture

工作流程：

  1. Scope：先看 git log 找热点区域，或直接指定要审查的模块
  2. Explore：sub-agent 有机扫描代码库，感受摩擦点，识别浅层模块/耦合泄漏/测试死角
  3. Present：生成 HTML 报告到 /tmp/architecture-review-<timestamp>.html，自动用 xdg-open / open 打开
  4. Grill：用户选择最想深化的候选，Skill 引导逐步”烧烤”每个改进点

依赖：
– Claude Code 最新版
– 项目最好有 CONTEXT.md（领域词汇表）和 docs/adr/（架构决策记录），但非强制

使用场景与人群

适用场景：
– 大型代码库（50+ 文件）架构维护审查
– 接手旧项目时的快速架构理解
– 引入 AI 编程前清理代码库结构
– 团队技术债优先级排序

目标用户：
– 中高级开发者 / 架构师（需要读懂和维护大型代码库）
– Tech Lead（需要向团队清晰展示架构改进方案）
– AI Coding 深度用户（想让 Claude Code 更精准地导航代码库）

输入与输出案例

输入：

/improve-codebase-architecture
→ 扫描 src/utils 目录，这个目录感觉越来越乱

输出（部分）：

/tmp/architecture-review-2026-08-16-134200.html
→ 浏览器打开，包含 3 张候选卡片：

┌─────────────────────────────────────────────────────┐
│ 🔍 Candidate #1: auth/token-utils (Strong)          │
├─────────────────────────────────────────────────────┤
│ Files: src/utils/token.ts, src/utils/auth-helpers.ts│
│ Problem: 两个模块互相调用，接口复杂度≈实现复杂度      │
│ Solution: 合并为一个深模块，对外只暴露一个适配器接口   │
│ Before/After: [SVG图: 并列的两个浅盒] → [一个深盒]   │
│ Benefits: 测试覆盖率可从 23% 提升到 71%，            │
│           locality 提升，真实 bug 暴露率提高         │
└─────────────────────────────────────────────────────┘

输入：

/improve-codebase-architecture
→ 我想把整个 API 层重构，先给我个全局视图

输出：
生成含 Mermaid 调用图的热力图，标注高扇入/扇出节点，帮助判断重构边界。

GitHub: https://github.com/mattpocock/skills

评论区

0 条评论

登录后可评论。

Skill超级捕获手 13 阅读