#/improve-codebase-architecture

架构体检。扫描代码库寻找深化机会——把浅模块变深模块的重构。目标是可测试性和 AI 可导航性。它是发现候选的调查；codebase-design 是设计选中模块的"工作台"。

#概述

基于项目的领域模型（CONTEXT.md）和共享设计词汇（codebase-design：模块、接口、深度、接缝、适配器、杠杆、局部性）运作。领域语言给好接缝命名；docs/adr/ 记录本命令不该重开的决策。

#日常使用

/improve-codebase-architecture
/improve-codebase-architecture 重点看订单模块
/improve-codebase-architecture 支付网关这块最近很难改

#实战

#1. 探索（先定范围再扫描，YAGNI）

深化模块的回报是未来改动它更容易，所以近期常改的部分权重更高：

• 用户点名方向就采用它，跳过下面的推断
• 否则走一段 git log --oneline 找热点：哪些文件和区域反复出现，让它们先吸引注意。改动分散无热点就放宽网

先读 CONTEXT.md 领域词汇表和改动区域的 ADR，然后派子 agent 走查代码库。别用僵化启发式，有机地探索，记下在哪里感到摩擦：

• 理解一个概念要跨多少个小模块来回跳？
• 哪里模块浅（接口和实现一样复杂）？
• 哪里纯粹函数被提取出来只为可测试，但真实 bug 藏在调用方式里（无局部性）？
• 哪里紧耦合模块泄漏过它们的接缝？
• 哪些部分没测试、或通过当前接口很难测？

对怀疑是浅的东西跑删除测试：删掉它复杂度会集中，还是只是转移？"会集中"就是要的信号。

#2. 生成 HTML 报告

写一个自包含 HTML 文件到 OS 临时目录（$TMPDIR，回退 /tmp），命名 architecture-review-<timestamp>.html 每次新鲜生成，用 open（macOS）/xdg-open（Linux）/start（Windows）打开并告诉绝对路径。

报告用 Tailwind（CDN） 布局、Mermaid（CDN） 画图——图状关系（调用图、依赖、时序）用 Mermaid，编辑感更强的东西（质量图、剖面、折叠动画）用手工 div/SVG。每个候选一张卡片：

• Files：涉及的文件/模块
• Problem：当前架构为什么摩擦
• Solution：会改变什么的通俗英语描述
• Benefits：用局部性和杠杆解释，以及测试会怎么改善
• Before / After diagram：并排定制绘制，展示浅和深化
• Recommendation strength：Strong / Worth exploring / Speculative 徽章

报告末尾是 Top recommendation：先动哪个候选、为什么。领域用 CONTEXT.md 词汇，架构用 codebase-design 词汇。

ADR 冲突：候选与已有 ADR 矛盾时，只在摩擦足够真实、值得重开时才提出，卡片上明确标注（如警告框："与 ADR-0007 矛盾，但值得重开，因为……"）。不要列出每个 ADR 禁止的理论重构。

现在不要提议接口。文件写完后问用户："这些里你想深入哪个？"

#3. 访谈循环

用户选中一个候选后，调 "grilling" 走决策树：约束、依赖、深化模块的形状、接缝后有什么、哪些测试存活。决策结晶时副作用就地发生，调 "domain-modeling" 保持领域模型同步：

• 给不在 CONTEXT.md 里的概念命名了深化模块？加术语进 CONTEXT.md（懒创建文件）
• 对话中磨尖了模糊术语？就地更新
• 用户以承重理由拒绝候选？提议记 ADR——"要我把这个记成 ADR 吗？这样未来的架构审查就不会再提它了"。只在理由确实需要未来探索者避免重提时提议；跳过短暂理由（"现在不值得"）和自明的
• 想探索替代接口？调 "codebase-design" 用它的"设计两次"并行子 agent 模式

#与其它技能的关系

• 词汇：codebase-design（架构词汇）+ domain-modeling（领域语言）
• 访谈：内部调 "grilling"
• 产物：选中的想法可汇入主流程从 /grill-with-docs 开始