1. 基本信息
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 名称 | improve-codebase-architecture（mattpocock/skills 合集仓库子技能；项目自述名称与正式名称一致） |
GitHub |
| 作者/维护者 | Matt Pocock（个人开发者/技术教育者，运营 aihero.dev，自述约 6 万订阅 newsletter） | 仓库 README |
| 来源链接 | https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture | — |
| 许可证 | MIT（仓库根 LICENSE 文件） | GitHub API |
| GitHub Stars / Forks | 所属 mattpocock/skills 仓库整体星标量属整个合集仓库，不代表本技能自身热度 |
GitHub API |
| 最新版本 | 插件包版本 1.2.0（.claude-plugin/plugin.json） |
仓库核对 |
| 安装方式 | Claude Code 官方插件市场 / Agent Skills 通用 CLI / 手动复制 | 仓库 README |
2. 功能介绍与亮点
improve-codebase-architecture 扫描代码库，找出“浅模块”（接口复杂度接近实现复杂度）、职责耦合、难以测试的区域，并用一套统一词汇（模块、接口、深度、接缝、适配器）描述问题——这套词汇来自同仓库的 codebase-design 技能，避免“组件/服务/边界”等说法各说各话。
核心流程分三步：① 探索——先看近期改动热点而非全库扫描，用“删除测试法”判断某处是真的浅还是只是挪了复杂度；② 生成自包含的可视化 HTML 报告，每个候选项配“问题/方案/收益/前后对比图”卡片和推荐强度标签，写入系统临时目录后自动打开；③ 用户选定候选项后，调用同仓库的 grilling 技能逐条追问约束与测试影响，决策落地时同步更新 domain-modeling 维护的领域词汇表，必要时提议记录一条 ADR。
亮点：作为 Claude Code 官方插件市场收录的 mattpocock-skills 插件组成部分；GitHub 代码搜索按精确路径命中 2,700+ 个仓库复用了该技能文件；仓库 issue 区可查证到至少 8 名与作者无关联的外部用户报告过使用体验与缺陷，是有真实使用者持续在用的技能，而非上架即止。
3. 适用场景
固定分类：工程效率与代码质量
面向面对存量代码库、怀疑某些模块耦合过重或难以测试、想要一份可视化改进建议再决定下手顺序的开发者，尤其适合“改动前想先摸清全貌，而不是凭直觉重构”的场景；由于依赖同仓库姊妹技能才能走完整流程，更适合已在使用 mattpocock/skills 其余技能的团队。
4. 跨 Agent 兼容性
- Claude Code：原生支持——
mattpocock/skills是 Claude Code 官方插件市场收录的插件，仓库自带.claude-plugin/plugin.json清单，/plugin install mattpocock-skills即可安装。 - Codex：支持——作者 README 将 Codex 列为“Codex, and other agents”安装分支的目标，经通用安装器
npx skills add mattpocock/skills安装；该安装器官方文档的 Supported Agents 表格明确列出 Codex 的项目/全局路径。 - OpenClaw / Hermes Agent：支持——同一份 Supported Agents 表格分别列出 OpenClaw（
skills/）与 Hermes Agent（.hermes/skills/）的独立安装路径；作者本人 README 未逐一点名这两个生态，是经通用安装器而非厂商原生渠道达成。
5. 推荐理由
把“这段代码是不是该重构”从直觉判断变成一份可视化、带前后对比图的候选清单，再用追问式对话把选定方案打磨到可落地，比直接要求 agent“帮我重构一下”更系统；已进入 Claude Code 官方插件市场，且有稳定的真实外部使用者持续反馈问题，不是发布即弃的一次性作品。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 8 | Claude Code 官方插件市场具名收录本技能；GitHub 代码搜索精确路径命中 2,700+ 个仓库，抽样核实为真实采纳而非同名巧合；仓库 issue 区可查证到至少 8 名外部用户（非作者本人）就本技能提交过具体使用反馈 |
| 可用性 | 7 | SKILL.md 文档完整、含分步流程说明与 HTML 报告结构示例；但完整流程显式依赖同仓库三个姊妹技能（codebase-design 提供词汇、grilling 负责追问、domain-modeling 维护词汇表），脱离这三者只能拿到候选清单本身，独立可用性因此打折 |
| 安全性 | 8 | 见下方安全检查清单 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令与权限范围 | 仅读取本地代码库与 git 历史、用系统原生命令（open/xdg-open/start）打开一个写入系统临时目录的 HTML 文件，不引入其他执行面 |
| ② 运行时联网外发 | 技能本身不外发数据；生成的 HTML 报告通过 CDN 加载 Tailwind 与 Mermaid 渲染库，在离线或限制第三方脚本的网络环境下会导致报告显示异常（详见第 11 章），但这是渲染依赖而非数据外发 |
| ③ API Key/凭据存储 | 不涉及，全程无需任何凭据 |
| ④ 可疑指令 | 全文通读未发现提示注入、混淆代码或隐蔽外发迹象 |
| ⑤ 作者/组织信誉 | Matt Pocock，已知技术教育者与开源作者，同仓库此前多个技能均未发现造假迹象 |
| ⑥ License | 仓库级 MIT，明确 |
| ⑦ 最近维护 | 本子技能最近一次提交约 3 周前，仓库整体近日仍持续有提交，活跃维护中 |
综合评分 = 三项均值 = 7.67
7. 跟同类 Skills 相比的优势
| 竞品 | 定位 | 与 improve-codebase-architecture 的差异 |
|---|---|---|
| refactor（github/awesome-copilot） | 聚焦“外科手术式”局部重构——提取函数、拆分超长函数、消除代码异味，明确要求不改变外部行为，定位是渐进式小步改进 | refactor 处理“已经决定要改的一小块代码怎么改得更干净”；improve-codebase-architecture 处理更前置的问题——先扫描全局找出“哪些地方值得改”并给出前后对比可视化，两者可以先后接力使用 |
| codebase-design（mattpocock/skills 同仓库） | 提供模块/接口/深度/接缝等设计词汇与“设计两遍”的并行子代理模式，用于新模块的接口设计讨论 | codebase-design 面向“要新写一个模块，接口该怎么设计”；improve-codebase-architecture 面向“已有代码库里哪些模块该重构”，本技能直接复用前者的词汇体系作为共同语言，两者定位互补而非重叠 |
8. 用户评价
- fuzzyhope1502（GitHub issue #274）：早期版本的重度用户，评价“感觉像魔法”——认为它能给出全面的改进分析并帮助排除过度设计的方案；同时指出后续版本接入 grilling 追问环节后，在部分场景下输出变得“几乎不可用、频繁给出无关信息”，反映功能迭代带来了体验上的取舍。
- sergical（GitHub issue #651）：报告生成的 HTML 报告依赖 CDN 加载 Tailwind 与 Mermaid，在启用了安全策略或离线的开发环境中会导致报告完全无样式渲染，是一个可复现的技术限制而非偶发问题。
9. 其他补充
作者维护一份约 6 万订阅的技术 newsletter，用于同步该仓库技能集的更新。
10. 安装使用方式
方式一（推荐，Claude Code 官方插件市场）：
claude plugins install mattpocock-skills或在会话内执行：
/plugin install mattpocock-skills已在 Claude Code 官方市场上架，无需额外添加来源，后续更新自动到达。
方式二（Codex / OpenClaw / Hermes Agent 等，Agent Skills 通用 CLI）：
npx skills@latest add mattpocock/skills安装时可勾选仅安装 improve-codebase-architecture。
方式三（手动复制）：
git clone https://github.com/mattpocock/skills /tmp/mattpocock-skills
cp -r /tmp/mattpocock-skills/skills/engineering/improve-codebase-architecture ~/.claude/skills/安装后注意事项：本技能 SKILL.md 声明 disable-model-invocation: true，不会被模型自动触发，需显式调用（如输入 /improve-codebase-architecture）；建议先运行一次同仓库的 /setup-matt-pocock-skills 完成 issue 追踪工具与标签规范等初始配置。
11. 注意事项
- 完整体验依赖同仓库三个姊妹技能（codebase-design、grilling、domain-modeling），只安装本技能本体的话，只能拿到候选清单和可视化报告。
- 生成的 HTML 报告经 CDN 加载 Tailwind 与 Mermaid，离线环境或启用严格内容安全策略时会渲染失败。
- 方式二依赖的第三方安装器
skills（npx skills）截至当前仍有两个未解决的开放 issue，指控其未经明确同意上报使用数据；建议优先用方式一或方式三规避。 - 已有真实用户反馈指出，追问环节在部分场景下会让输出变得冗长或偏题，可按需跳过追问、只取候选清单部分。