用途:扫描代码库中的架构摩擦与“加深”机会,即把浅模块重构为深模块,目标是提升可测试性与 AI 可导航性。基于项目领域模型与共享设计词汇,命令会引用 /codebase-design 的术语(module、interface、depth、seam、adapter、leverage、locality)及原则(deletion test、接口即测试面、一个适配器=假设接缝两个=真实接缝),建议中须精确使用这些词,不漂移到 component、service、API、boundary。领域语言来自 CONTEXT.md,docs/adr/ 中的 ADR 记录不应被重复争论的决策。
主要能力与流程:
- 探索。先界定范围而非全面扫描,优先关注近期变更的热点区域;可用 git log --oneline 回看提交历史定位热点;先读 CONTEXT.md 与相关 ADR;再用 Agent 工具 subagent_type=Explore 有机地遍历代码库,注意理解一个概念是否要在许多小模块间跳转、模块是否过浅、纯函数是否为测试性被抽离而真实缺陷藏在调用处、耦合模块是否跨越接缝泄漏、哪些部分未测试或难以通过当前接口测试。对疑似浅模块做 deletion test:删除是集中复杂性还是仅仅移动它。
- 候选以 HTML 报告呈现。写入操作系统临时目录($TMPDIR,回退 /tmp 或 Windows %TEMP%),文件名为 architecture-review-<timestamp>.html,并用 xdg-open、open 或 start 打开,同时告知绝对路径。报告用 CDN 的 Tailwind 与 Mermaid,每个候选含 Files、Problem、Solution、Benefits、Before/After 图、推荐强度徽章(Strong、Worth exploring、Speculative),结尾给出 Top recommendation。若候选与 ADR 冲突,只在摩擦足够真实时以警示标注呈现,不罗列所有被 ADR 禁止的理论重构。此阶段不提出接口。
- 推演循环。用户选定候选后运行 /grilling 走决策树,讨论约束、依赖、加深模块的形态、接缝背后是什么、哪些测试能存活。决策成型时内联运行 /domain-modeling 维护领域模型:新概念加入 CONTEXT.md(不存在则惰性创建),模糊术语就地更新;若用户以有实质理由拒绝候选,可提议记录为 ADR,仅当未来探索者确实需要该理由时才提议。想探索替代接口时运行 /codebase-design,使用其 design-it-twice 并行子代理模式。
限制:需要代码库上下文、CONTEXT.md 与 ADR 的配合;报告写入临时目录而不落库;具体安装命令、收费与平台信息暂未提供。