调查代码中的理解与测试成本，用可视化报告展示重构候选，再深入讨论你选中的一个。
安装与准备
在项目目录的终端执行以下命令，安装后在 Claude Code 中输入下方提示。这里选择项目内的可编辑文件安装。
npx skills@latest add mattpocock/skills --skill improve-codebase-architecture --skill codebase-design --skill grilling --skill domain-modeling --agent claude-code
使用 Codex 时，把安装命令最后的 claude-code 换成 codex，对话里把 /improve-codebase-architecture 换成 $improve-codebase-architecture。如果使用完整的 Claude Code 插件，则选择 /mattpocock-skills:improve-codebase-architecture，不要再重复安装文件版本。
安装 codebase-design、grilling 和 domain-modeling 作为配套。打开仓库并指出最近频繁修改、难以理解或难以测试的区域；现有 ADR 应作为约束。
第一次使用
把下面的场景和路径替换成你的项目情况，在 Agent 对话里输入：
/improve-codebase-architecture
最近每次改优惠券都要动结算、订单和营销三个目录。请重点调查这一条调用链，给出候选重构的前后图和收益，先让我选一个再深入设计。
怎样推进任务
先限定调查区域
使用最近的 Git 变更和具体痛点确定重点，避免按文件数量平均审查整个仓库。优惠券例子需要理解为什么一个规则散落在三个目录，以及测试是否只能靠大量内部 Mock 才能执行。
比较模块的外部复杂度
候选方案应说明哪些复杂规则可以藏在更小、更稳定的接口后面，以及调用者因此少知道什么。合并文件并不是目标；如果只是移动代码，外部仍需理解同样多的细节，就未必值得重构。
阅读报告后选择一个
它会生成临时 HTML 报告，包含涉及文件、问题、方案、前后图和建议强度。选中一个之后再进入追问，讨论接口、测试和约束；确定的新领域概念可同步写入术语表，有长期意义的取舍可记录 ADR。
完成后检查什么
你应拿到可打开的报告和一个明确的下一步决定：继续某项重构、先验证收益或暂时放下。确认建议解释了修改成本与测试改善，而不只是让目录看起来更整齐。
常见问题
会直接重写项目吗？ 默认先给候选，再围绕你的选择展开设计。
为什么报告样式没有加载？ 报告使用 CDN 资源，离线环境可能影响样式和图表。
每次都发现新建议怎么办？ 用近期改动和实际维护成本决定是否值得做，不以“零建议”为目标。
报告卡片应回答“改了以后少懂什么”
假设权限判断散在 API、中间件和页面里，每加一个角色就要三处同步。可以输入：“用 improve-codebase-architecture 调查权限规则的最近修改，不改代码。报告中逐个说明哪层目前知道过多角色细节、可能的新接口是什么、哪些测试可从内部 Mock 移到公开边界。”先让它读最近变更和真实调用路径，再读 HTML 报告中的候选卡片。
一张有价值的卡片应解释调用方以后可以不知道什么，而不只是建议新建 PermissionsService。若删除某个浅模块只会把 if 语句复制到所有调用方，它没有通过删除测试。选定一项后再讨论实现边界和代价；如果这轮调查直接改了代码或列出几十个与最近工作无关的清理项，就偏离了该 Skill 的报告用途。
重构前后对照真实界面
若报告建议调整会影响页面组件的边界，修改前先在真实页面记录正常、加载中、空状态和错误状态；修改后用同一组输入比较画面与交互。已有用户在使用这个 Skill 重构时，类型检查、测试和代码评审全绿，仍因条件渲染分支及属性透传丢失而改变了界面。把“用户看见和能操作的结果保持一致”写进这次重构的验收，而不是只检查模块依赖是否变整齐。