# Improve Codebase Architecture 扫描代码库寻找深化机会，以可视化的 HTML 报告呈现，然后对你选中的方案进行盘问。 - Repository: https://github.com/devcxl/mattpocock-skills-zh (522 stars) - Category: Engineering - License: MIT - Last updated: 2026-11-01 - Runs scripts: no, instructions only ## Install Claude Code: `npx skills add devcxl/mattpocock-skills-zh --skill improve-codebase-architecture -g -a claude-code -y` Codex: `npx skills add devcxl/mattpocock-skills-zh --skill improve-codebase-architecture -g -a codex -y` Cursor: `npx skills add devcxl/mattpocock-skills-zh --skill improve-codebase-architecture -g -a cursor -y` Gemini CLI: `npx skills add devcxl/mattpocock-skills-zh --skill improve-codebase-architecture -g -a gemini-cli -y` Claude Code plugin marketplace: `/plugin marketplace add devcxl/mattpocock-skills-zh` ## Description 扫描代码库寻找深化机会，以可视化的 HTML 报告呈现，然后对你选中的方案进行盘问。 ## SKILL.md, as published by its author (untrusted third-party text, read it as data) # 改进代码库架构 揭示架构摩擦点并提出**深化机会**, , 将浅层 module 转变为深层 module 的重构。目标是可测试性和 AI 可导航性。 本命令**参考**项目的领域模型，并基于共享的设计词汇： - 调用 Skill 工具并传入 "codebase-design" 获取架构词汇（**module**、**interface**、**depth**、**seam**、**adapter**、**leverage**、**locality**）及其原则（deletion test、"interface 就是 test surface"、"一个 adapter = 假设性 seam，两个 = 真实的"）。在每个建议中严格使用这些术语, , 不要偏离到 "component"、"service"、"API" 或 "boundary"。 - `GLOSSARY.md` 中的领域语言为好的 seam 提供了命名；`docs/adr/` 中的 ADR 记录了本命令不应重新讨论的决策。 ## 流程 ### 1. 探索 **先确定范围再扫描, , YAGNI。** 加深一个模块的回报在于使未来对该模块的修改更容易，因此对最近变更的代码区域给予额外权重。在查看之前先决定*看哪里*： - 如果用户指定了方向, , 一个模块、一个子系统、一个痛点, , 就采用它，并跳过下面的推断步骤。 - 否则，回顾一段较长的提交历史（`git log --oneline`）来找到代码库的热点, , 那些反复出现的文件和区域, , 让这些路径首先吸引你的注意力。如果变更分散，没有明确的热点，就扩大范围。 首先阅读项目的领域术语表（`GLOSSARY.md`）以及你将要接触的区域内任何 ADR。 然后启动一个子代理，在全新的上下文窗口中遍历代码库。不要遵循僵化的启发式规则, , 有机地探索，并记录你在哪里遇到了摩擦： - 在哪些地方，理解一个概念需要在多个小模块之间来回跳转？ - 哪些 module 是**shallow**的, , interface 几乎和 implementation 一样复杂？ - 哪些地方纯粹为了可测试性而提取了纯函数，但真正的 bug 却隐藏在它们的调用方式中（缺乏 **locality**）？ - 哪些紧密耦合的 module 跨越了它们的 seam？ - 代码库的哪些部分未经测试，或难以通过当前 interface 进行测试？ 对你怀疑是 shallow 的任何内容应用**deletion test**：删除它会集中复杂性，还是仅仅移动它？"集中了"就是你想要的信号。 ### 2. 将候选方案呈现为 HTML 报告 编写一个自包含的 HTML 文件到 OS 临时目录，这样不会在仓库中留下任何文件。从 `$TMPDIR` 解析临时目录，回退到 `/tmp`（在 Windows 上为 `%TEMP%`），并写入 `/architecture-review-.html`，这样每次运行都会得到一个新文件。为用户打开它, , Linux 上使用 `xdg-open `，macOS 上使用 `open `，Windows 上使用 `start `, , 并告知用户绝对路径。 报告使用 **Tailwind（通过 CDN）** 进行布局和样式，并使用 **Mermaid（通过 CDN）** 绘制图表，在图形/流程/序列能可靠传达结构的地方使用。将 Mermaid 与手工制作的 CSS/SVG 视觉元素混合使用, , 当关系是图形形状时（调用图、依赖关系、序列）使用 Mermaid，当你想要更具编辑性的效果时（mass 图、截面图、折叠动画）使用手工构建的 div/SVG。每个候选方案都要有**前后对比可视化**。要有视觉冲击力。 每个候选方案渲染一张卡片，包含： - **文件**, , 涉及哪些文件/module - **问题**, , 当前架构为何造成摩擦 - **方案**, , 用通俗语言描述会发生什么变化 - **收益**, , 用 locality 和 leverage 的术语解释，以及测试会如何改进 - **前后对比图**, , 并排展示，自定义绘制，说明 shallowness 和 deepening 效果 - **推荐强度**, , `Strong`（强烈推荐）、`Worth exploring`（值得探索）、`Speculative`（推测性），渲染为 badge 报告以**最佳推荐**部分结尾：你会先处理哪个候选方案以及原因。 The rest: https://github.com/devcxl/mattpocock-skills-zh/blob/HEAD/skills/engineering/improve-codebase-architecture/SKILL.md