用途
该技能用于扫描代码库，识别“深化机会”（deepening opportunities）——即把浅模块（shallow modules）转化为深模块（deep modules）的重构，目标是提升可测试性与 AI 可导航性。适合在用户希望先看到架构改进候选、再决定具体动手对象的场景使用。触发语句包括：improve the architecture、find deepening opportunities、where should we refactor。
该技能导入自 mattpocock/skills（MIT），在源头属用户主动调用（user-invoked upstream）。
主要能力
- 在扫描前先确定范围：优先关注近期变更频繁的热点区域。若用户已指明模块、子系统或痛点，则直接采用；否则通过 git log --oneline 回溯提交历史，找出频繁出现的文件与区域。
- 在进入某个区域前，先阅读项目的领域术语表 CONTEXT.md，以及该区域的 ADR。
- 生成子代理遍历代码库，以有机探索方式记录摩擦点，例如：理解某个概念需要在多个小模块间来回跳转；模块接口复杂度几乎等同实现；为可测试性抽取纯函数但真实缺陷藏于调用方式（缺乏 locality）；紧耦合模块跨越缝隙泄漏；未测试或难以通过现有接口测试的部分。
- 对疑似浅模块应用删除测试（deletion test）：删除它是能集中复杂度，还是只是转移复杂度。
- 以自包含 HTML 报告呈现候选方案，写至系统临时目录（$TMPDIR，回退 /tmp 或 Windows 的 %TEMP%），文件名为 <tmpdir>/architecture-review-<timestamp>.html，每次运行生成新文件，并使用对应平台命令打开（Linux: xdg-open；macOS: open；Windows: start），同时告知用户绝对路径。
- 报告通过 CDN 使用 Tailwind 进行布局与样式，通过 CDN 使用 Mermaid 绘制图/流程/时序图，并混合手工 CSS/SVG 视觉元素。每个候选方案均提供 before/after 可视化。
- 每个候选方案的卡片包含：Files（涉及的文件/模块）、Problem（当前架构为何造成摩擦）、Solution（将会发生什么变化的通俗描述）、Benefits（以 locality 与 leverage 及测试改善角度说明）、Before/After 图（并排、手绘，展示浅与深）、Recommendation strength（Strong、Worth exploring、Speculative 徽标）。
- 报告结尾给出 Top recommendation 部分：优先处理哪个候选及原因。
- 在用户选定候选方案后，进入 grilling 循环，逐步厘清约束、依赖、深化后模块的形态、seam 背后的内容、哪些测试能保留。
- 过程中按需调用 domain-modeling 同步领域模型：为 CONTEXT.md 中不存在的新概念命名时补充术语（文件不存在则惰性创建）；会话中细化模糊术语时即时更新 CONTEXT.md；用户以关键理由否决候选时，询问是否记录为 ADR，以避免未来架构评审重复建议。
- 如需探索深化模块的备选接口，可调用 codebase-design 的 design-it-twice 并行子代理模式。
使用方式（术语与词汇约束）
- 以项目的领域模型为依据，并建立在共享设计词汇之上：调用 Skill 工具传入 "codebase-design" 获取架构词汇（module、interface、depth、seam、adapter、leverage、locality）及其原则（删除测试、“接口即测试面”、“一个 adapter = 假想 seam，两个 = 真实 seam”）。所有建议需精确使用这些术语，不漂移到 “component”“service”“API”“boundary”。
- CONTEXT.md 中的领域语言为好的 seam 命名；docs/adr/ 中的 ADR 记录了本命令不应重新争论的决策。
- 报告中领域词汇使用 CONTEXT.md 的用词，架构词汇使用 /codebase-design 的用词。例如 CONTEXT.md 定义了 “Order”，则应说 “the Order intake module”，而非 “the FooBarHandler” 或 “the Order service”。
- ADR 冲突处理：若某候选与现有 ADR 矛盾，仅当摩擦足够真实、值得重新审视该 ADR 时才提出，并在卡片中明确标注（如警告提示：“contradicts ADR-0007, but worth reopening because…”）。不要列出 ADR 禁止的每一个理论性重构。
- 在报告写入文件后，暂不提出接口方案，而是询问用户：“Which of these would you like to explore?”
适用场景
- 用户希望在动手重构前先看到架构改进候选清单。
- 需要定位代码库中最值得重构的热点区域。
- 需要以可视化报告方式呈现架构摩擦与深化方案。
- 选定方向后需要逐步厘清重构约束与测试影响。
限制与注意事项
- 报告写入系统临时目录，避免落入代码仓库。
- 上游流程需保持完整；若有偏离应明确记录，而非静默即兴发挥。
- 在每个该技能标记为“由用户决定”的决策点，应停下并把控制权交还用户。
- 优先采用小而可逆的改动，并明确陈述假设而非将其埋没。
- 需要仓库或环境事实时，应自行查询而非询问用户。
- 建议先用一个较窄范围应用该技能，确认输出符合上述形态，再扩展到完整任务。
参考资料
- Upstream skill: mattpocock/skills skills/engineering/improve-codebase-architecture/SKILL.md（commit 3cca18b, MIT）
- Companion doc: references/HTML-REPORT.md
- Project standards: .agent-skills/skill-standardization/SKILL.md
- Validator script: .agent-skills/skill-standardization/scripts/validate_skill.sh