用途:发现代码库中的架构摩擦,提出“深化机会”——把浅模块变成深模块的重构建议,目标是提升可测试性与 AI 可导航性。
主要能力:依托项目领域模型与共享设计词汇工作。先调用 Skill 工具加载 codebase-design 获取架构词汇(module、interface、depth、seam、adapter、leverage、locality)及原则(删除测试、接口即测试面、一个适配器是假想缝两个才是真缝),建议中须严格使用这些术语。CONTEXT.md 提供领域命名,docs/adr/ 中的 ADR 记录不应被重复推翻的决策。
使用方式:
- 探索。先定范围(YAGNI)。用户指定方向时直接采用;否则用 git log --oneline 回溯历史找热点文件。先读 CONTEXT.md 与相关 ADR,再派子代理有机地遍历代码,标记摩擦点:理解一个概念是否要在多个小模块间跳转、模块是否浅、纯函数是否只为测试抽出而真实缺陷藏在调用处、紧耦合模块是否越过 seam 泄漏、哪些部分未测试或难以通过现有接口测试。对可疑的浅模块用删除测试判断:删除它会让复杂度集中还是只是转移。
- 以 HTML 报告呈现候选。写到系统临时目录($TMPDIR,回退 /tmp 或 Windows 的 %TEMP%),文件名 <tmpdir>/architecture-review-<timestamp>.html,不落入仓库;用 xdg-open/open/start 打开并告知绝对路径。报告用 CDN 引入 Tailwind 与 Mermaid,图形式关系用 Mermaid,其他用自绘 CSS/SVG。每张卡片含 Files、Problem、Solution、Benefits(以 locality 与 leverage 及测试改进表述)、前后对比图、推荐强度徽章(Strong / Worth exploring / Speculative),结尾给 Top recommendation。若候选与 ADR 冲突且摩擦真实,明确标注而非罗列所有理论重构。此阶段不提出接口。
- 追问循环。用户选定候选后,调用 Skill 工具加载 grilling 走决策树,并内联调用 domain-modeling 同步领域模型:新概念写入 CONTEXT.md(不存在则惰性创建)、术语精化即时更新;用户以关键理由否决候选时,可询问是否记录为 ADR,仅在该理由对未来探索者确有避免重复建议价值时提出,跳过临时性理由。探索替代接口时调用 codebase-design 的 design-it-twice 并行子代理模式。
限制:需配合支持 Skill 工具与子代理的环境;依赖 CONTEXT.md 与 ADR;HTML 报告写在临时目录;引用 HTML-REPORT.md 获取完整脚手架与样式指引。收费、平台等信息资料未提供。