一句话

扫描代码库找 deepening 机会，出一份可视化 HTML 报告，挑一个候选再用 grilling 问透；只勘察不改代码，重构另开会话走正常 build 流程。

何时用

• 适合：定期保养防结构腐化；大改前问「怎么让这次改动容易」（最有效的问法）；审计陌生或 vibe-coded 的库；为不可测代码找缺失的 seam。
• 不适合：已选好要改哪个模块（直接 matt-codebase-design 设计它）；指望它动手重构，它只产出报告和访谈。

怎么用

/improve-codebase-architecture 扫一遍这个仓库找值得加深的模块

1. 先圈范围（YAGNI）：用户给了方向就用，否则看 git log 热点，扫常改的路径。
2. 先读 GLOSSARY.md 和相关 ADR，再派子代理走库找摩擦点（浅模块、跨 seam 泄漏、无 locality 的纯函数抽取、不可测面）。
3. 出 HTML 报告（Tailwind+Mermaid 走 CDN）：每个候选一张卡，文件/问题/方案/收益/前后对比图/Strong-Worth exploring-Speculative 徽章，结尾给 Top recommendation。
4. 问用户选哪个，选中后进入 grilling loop：命名新概念补 GLOSSARY.md，用户以承重理由否决时提 ADR，想多方案比较就调 codebase-design 的 design-it-twice。

产出

• 一份 HTML 报告（系统临时目录）+ 对选中候选的一次访谈；不改代码。

要点与坑

• 候选必须过 deletion test；与 ADR 冲突的候选只在摩擦够真时才标出。
• 全程只用 codebase-design 的词汇，不漂到 component/service/API/boundary。
• 报告落在临时目录，不是 repo 文件。

本机版本差异

术语文件改名：本机旧版读 CONTEXT.md，仓库版读 GLOSSARY.md。

关联

• 词汇：matt-codebase-design、matt-domain-modeling · 下游：matt-grill-with-docs
• 所属：00-matt-概览 · 工作流：W5-接手老项目与技术调研