improve-codebase-architecture

改进代码库架构

揭示架构摩擦，并提出 深化机会——将浅（shallow）模块改造成深（deep）模块的重构。目标是提升可测试性和 AI 导航能力。

此技能以项目的领域模型为依据，并建立在共享的设计词汇之上：

• 运行技能 /codebase-design，了解架构词汇（module、interface、depth、seam、adapter、leverage、locality）及其原则（删除测试、“interface 就是 test surface”、“一个 adapter = 假设的 seam，两个 = 真实的 seam”）。在所有建议中都准确使用这些术语——不要改用“component”、“service”、“API”或“boundary”。
• CONTEXT.md 中的领域语言为良好的 seam 命名；docs/adr/ 中的 ADR 记录了此技能不应重新讨论的决策。

流程

1. 探索

先界定范围再扫描——YAGNI。 深化模块的价值在于让未来对其进行修改更容易，因此应特别关注近期发生过变化的代码库部分。在查看之前，先决定查看哪里：

• 如果用户指出了一个方向——某个模块、子系统或痛点——就从那里着手，并跳过下面的推断步骤。
• 否则，查看足够多的提交历史（git log --oneline），找出代码库中的热点——反复出现的文件和区域——并优先关注这些路径。如果变更分散，没有明显热点，就扩大搜索范围。

先阅读项目领域词汇表（CONTEXT.md）以及你要处理区域中的任何 ADR。

然后启动一个 sub-agent 遍历代码库。不要遵循僵化的启发式规则——自然地探索，并留意让你感到摩擦的地方：

• 理解某个概念是否需要在许多小模块之间来回跳转？
• 哪些模块是 shallow 的——interface 是否几乎和实现一样复杂？
• 是否有纯函数仅为可测试性而抽取出来，但真正的 bug 却藏在调用方式中（缺乏 locality）？
• 强耦合的模块是否通过各自的 seam 泄漏？
• 代码库中哪些部分缺少测试，或难以通过当前的 interface 进行测试？

对所有你怀疑是 shallow 的内容应用删除测试：删除它会让复杂性集中起来，还是只会把复杂性转移到别处？“会集中”正是你要找的信号。

2. 将候选方案呈现为 HTML 报告

在操作系统的临时目录中编写一个独立的 HTML 文件，避免任何内容写入仓库。根据 $TMPDIR 确定临时目录，若未设置则回退到 /tmp（Windows 上使用 %TEMP%），并写入 <tmpdir>/architecture-review-<timestamp>.html，确保每次运行都会生成新文件。为用户打开文件 — Linux 上使用 xdg-open <path>，macOS 上使用 open <path>，Windows 上使用 start <path> — 并告知用户绝对路径。

报告使用通过 CDN 加载的 Tailwind进行布局和样式设置，使用通过 CDN 加载的 Mermaid绘制图表，适用于图、流程或序列能可靠呈现结构的情况。将 Mermaid 与手工制作的 CSS/SVG 视觉元素结合使用 — 关系呈图形结构时使用 Mermaid（调用图、依赖关系、序列），想要更具编辑感的呈现时使用手工构建的 div/SVG（质量图、剖面图、折叠动画）。每个候选方案都要配有改造前／改造后对比图。视觉效果要出色。

为每个候选方案渲染一张卡片，包含：

• 文件 — 涉及哪些文件／模块
• 问题 — 为什么当前架构造成了摩擦
• 解决方案 — 用通俗易懂的语言描述将要做出的改变
• 收益 — 从局部性和杠杆效应的角度说明收益，以及测试会如何改进
• 改造前／改造后图示 — 并排展示的自定义图示，说明浅层结构以及如何加深
• 建议力度 — 从 Strong、Worth exploring、Speculative 中选择一个，并以徽章形式呈现

在报告末尾添加一个首选建议部分：说明你会优先处理哪个候选方案，以及原因。

使用 CONTEXT.md 中的领域词汇，以及 /codebase-design 中的架构词汇。 如果 CONTEXT.md 定义了“Order”，就说“Order 接入模块” — 不要说“FooBarHandler”，也不要说“Order service”。

与 ADR 冲突：如果候选方案与现有 ADR 相矛盾，只有当摩擦确实足以成为重新审议 ADR 的理由时才提及。请在卡片中清楚标示（例如，添加警告提示：“与 ADR-0007 相矛盾 — 但值得重新审议，因为……”）。不要列出 ADR 禁止的所有理论性重构方案。

完整的 HTML 脚手架、图示模式和样式指南请参阅 HTML-REPORT.md。

暂时不要提出接口。写完文件后，询问用户：“你想探索以下哪一个方案？”

3. 方案审议循环

用户选定一个候选方案后，运行 skill /grilling，与用户一起走完决策树 — 约束、依赖关系、加深后的模块形态、哪些内容留在 seam 后面，以及哪些测试会保留。

随着决策逐步明确，副作用会同步发生 — 运行 skill /domain-modeling，在推进过程中维护领域模型：

• 使用 CONTEXT.md 中尚未出现的概念为一个加深后的模块命名？ 将该术语添加到 CONTEXT.md。如果文件不存在，则按需创建。
• 在对话中细化一个含义模糊的术语？ 立即更新 CONTEXT.md。
• 用户因重要理由拒绝候选方案？ 提议记录为 ADR，措辞如下：“你希望我将此记录为 ADR，以免未来的架构审查再次建议这个方案吗？” 只有当这个理由确实有助于未来的探索者避免再次提出同样的建议时才提出 — 跳过短暂的理由（“现在不值得”）和显而易见的理由。
• 想探索加深后的模块的其他接口方案？ 运行 skill /codebase-design，并使用其中的并行 sub-agents design-it-twice 模式。