用途:在代码库中寻找架构摩擦点,提出把浅模块变为深模块的重构机会,目标是提升可测试性与 AI 可导航性。它依据 CONTEXT.md 中的领域语言和 docs/adr/ 中的决策来判断,避免重复讨论已有 ADR 决定的事项。
主要能力:使用统一术语(模块、接口、实现、深度、接缝、适配器、杠杆、局部性),并遵循若干原则,如删除测试(删掉模块后复杂度消失说明是直通层,复杂度在 N 个调用方重现说明其有价值)、接口即测试面、一个适配器是假设接缝、两个适配器才是真实接缝。流程上先探索代码库,用 Agent 工具以 subagent_type=Explore 有机地走查,记录理解一个概念需在多个小模块间跳转、接口与实现复杂度相当、纯函数仅为可测试性而抽取但真实缺陷藏在调用方式中、紧耦合模块跨接缝泄漏、以及未测试或难以通过当前接口测试的部分。
使用方式:将候选改进写成自包含 HTML 报告,输出到系统临时目录(由 $TMPDIR 解析,回退 /tmp 或 Windows 的 %TEMP%),文件名为 architecture-review-<timestamp>.html,并用 xdg-open、open 或 start 打开,告知用户绝对路径。报告用 CDN 的 Tailwind 布局、Mermaid 画图,每个候选含文件、问题、方案、收益、前后对比图与推荐强度徽章(Strong、Worth exploring、Speculative),结尾给出首选建议。之后询问用户想探索哪个候选,再进入“拷问”式对话,逐步明确约束、依赖、加深后模块的形态、接缝背后的内容与可存活的测试。若用户要求把候选转为 GitHub issue,则创建规划类 issue(非实现任务),先验证仓库/认证/分支,搜索重复项,逐个创建并核对 OPEN 状态、标题、URL、标签与 status:needs-plan,保持仅规划,不直接改代码。
适用场景:需要系统性审视架构、寻找可加深重构点、并希望结果可被 AI 与人类共同导航的项目。
限制:资料未提供具体安装命令、收费或价格信息;报告写入临时目录而非仓库;不提出具体接口设计,需用户先选择候选;涉及 ADR 冲突时仅在摩擦足够真实时标注;状态 status:plan-approved 只能由用户自行应用。