name	improve-codebase-architecture
description	Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
disable-model-invocation	true

Improve Codebase Architecture改进代码库架构

Surface architectural friction and propose deepening opportunities — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.发现架构摩擦并提出深化机会——将浅层模块重构为深层模块。目标是可测试性和 AI 可导航性。

This command is informed by the project's domain model and built on a shared design vocabulary:此指令基于项目的领域模型，并使用共享的设计词汇表：

• Run the /codebase-design skill for the architecture vocabulary (module, interface, depth, seam, adapter, leverage, locality) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion — don't drift into "component," "service," "API," or "boundary."运行 /codebase-design 技能以获取架构词汇（module、interface、depth、seam、adapter、leverage、locality）及其原则（删除测试，“接口是测试表面”，“一个适配器 = 假设的 seam，两个 = 真正的 seam”）。在每个建议中严格使用这些术语——不要漂移到“component”“service”“API”或“boundary”。
• The domain language in CONTEXT.md gives names to good seams; ADRs in docs/adr/ record decisions this command should not re-litigate.CONTEXT.md 中的领域语言为良好 seam 命名；docs/adr/ 中的 ADR 记录了本指令不应重新讨论的决策。

Process过程

1. Explore1. 探索

Read the project's domain glossary (CONTEXT.md) and any ADRs in the area you're touching first.首先阅读项目的领域词汇表（CONTEXT.md）以及你将要触及的区域中的任何 ADR。

Then use the Agent tool with subagent_type=Explore to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:然后使用 Agent 工具，subagent_type=Explore，遍历代码库。不要遵循僵硬的启发式——有机探索并记录你感受到摩擦的地方：

• Where does understanding one concept require bouncing between many small modules?理解一个概念是否需要在许多小模块之间来回跳转？
• Where are modules shallow — interface nearly as complex as the implementation?哪些模块是浅层的——接口几乎和实现一样复杂？
• Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no locality)?哪些纯函数仅为可测试性而抽取，但真实的 bug 隐藏在调用方式中（缺乏 locality）？
• Where do tightly-coupled modules leak across their seams?哪些紧耦合的模块在它们的 seam 之间泄漏？
• Which parts of the codebase are untested, or hard to test through their current interface?代码库的哪些部分未被测试，或通过当前接口难以测试？

Apply the deletion test to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.对任何你怀疑是浅层的东西应用删除测试：删除它会使复杂度集中，还是仅仅把复杂度移动？“是，集中”就是你想要的信号。

2. Present candidates as an HTML report2. 将候选项呈现为 HTML 报告

Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from $TMPDIR, falling back to /tmp (or %TEMP% on Windows), and write to <tmpdir>/architecture-review-<timestamp>.html so each run gets a fresh file. Open it for the user — xdg-open <path> on Linux, open <path> on macOS, start <path> on Windows — and tell them the absolute path.将自包含的 HTML 文件写入操作系统临时目录，以免任何内容落入仓库。先从 $TMPDIR 获取临时目录，若不存在则回退到 /tmp（Windows 上为 %TEMP%），并写入 <tmpdir>/architecture-review-<timestamp>.html，使每次运行生成新文件。为用户打开它——Linux 上使用 xdg-open <path>，macOS 上使用 open <path>，Windows 上使用 start <path>——并告知其绝对路径。

The report uses Tailwind via CDN for layout and styling, and Mermaid via CDN for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals — use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a before/after visualisation. Be visual.报告通过 CDN 引入 Tailwind 进行布局和样式，通过 CDN 引入 Mermaid 绘制图表，当图/流/序列能可靠传达结构时使用。将 Mermaid 与手工 CSS/SVG 视觉相结合——当关系呈图形形状（调用图、依赖、序列）时使用 Mermaid；当需要更具编辑性的展示（大规模图、截面、折叠动画）时使用手工构建的 div/SVG。每个候选项都提供前后对比的可视化。要可视化。

For each candidate, render a card with:对于每个候选项，渲染一个卡片，内容包括：

• Files — which files/modules are involved文件——涉及的文件/模块
• Problem — why the current architecture is causing friction问题——当前架构为何导致摩擦
• Solution — plain English description of what would change解决方案——用简明英文描述将会改变什么
• Benefits — explained in terms of locality and leverage, and how tests would improve收益——以 locality 和 leverage 为维度解释，并说明测试如何改进
• Before / After diagram — side-by-side, custom-drawn, illustrating the shallowness and the deepening前后图示——并排、定制绘制，展示浅层与深化的对比
• Recommendation strength — one of Strong, Worth exploring, Speculative, rendered as a badge推荐强度——Strong、Worth exploring、Speculative 之一，以徽章形式呈现

End the report with a Top recommendation section: which candidate you'd tackle first and why.在报告末尾添加“最高推荐”章节：你会首先着手的候选项以及原因。

Use CONTEXT.md vocabulary for the domain, and the /codebase-design vocabulary for the architecture. If CONTEXT.md defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."使用 CONTEXT.md 的词汇描述领域，使用 /codebase-design 的词汇描述架构。如果 CONTEXT.md 定义了 “Order”，则谈论 “Order intake module”——而不是 “FooBarHandler”，也不是 “Order service”。

ADR conflicts: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: "contradicts ADR-0007 — but worth reopening because…"). Don't list every theoretical refactor an ADR forbids.ADR 冲突：如果某候选项与已有 ADR 矛盾，仅在摩擦足够真实、值得重新审视该 ADR 时才提出。将在卡片中明确标记（例如警告提示：“与 ADR-0007 矛盾——但值得重新打开，因为…”。）不要列出每一个理论上被 ADR 禁止的重构。

See HTML-REPORT.md for the full HTML scaffold, diagram patterns, and styling guidance.参见 HTML-REPORT.md 获取完整的 HTML 框架、图表模式和样式指南。

Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"不要立即提出接口。文件写入后，询问用户：“你想进一步探索哪一个？”

3. Grilling loop3. 深入讨论循环

Once the user picks a candidate, run the /grilling skill to walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.用户选择候选项后，运行 /grilling 技能与其一起遍历设计树——约束、依赖、深化模块的形态、seam 背后是什么、哪些测试仍然有效。

Side effects happen inline as decisions crystallize — run the /domain-modeling skill to keep the domain model current as you go:在决策具体化时即时产生副作用——运行 /domain-modeling 技能以保持领域模型同步：

• Naming a deepened module after a concept not in CONTEXT.md? Add the term to CONTEXT.md. Create the file lazily if it doesn't exist.将深化后的模块命名为 CONTEXT.md 中不存在的概念？将该术语添加到 CONTEXT.md。若文件不存在则懒惰创建。
• Sharpening a fuzzy term during the conversation? Update CONTEXT.md right there.在对话中澄清模糊术语？立即更新 CONTEXT.md。
• User rejects the candidate with a load-bearing reason? Offer an ADR, framed as: "Want me to record this as an ADR so future architecture reviews don't re-suggest it?" Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones.用户因关键原因拒绝候选项？提供一个 ADR，表述为：“要我把它记录为 ADR，以便未来的架构评审不再重新建议它吗？”仅在该原因确实会被后续探索者用来避免重复建议时提供——跳过短暂原因（“现在不值得”）和显而易见的原因。
• Want to explore alternative interfaces for the deepened module? Run the /codebase-design skill and use its design-it-twice parallel sub-agent pattern.想为深化的模块探索替代接口？运行 /codebase-design 技能并使用其 design-it-twice 并行子代理模式。