---
name: architecture-scout
description: 代码库架构机会侦察。当用户想找值得深化的模块边界、评估频繁跨模块修改的根因、在大功能开工前判断怎样让修改更容易，或审视难测试的模块时使用。只调查和报告，不修改代码；允许结论为“暂无值得优先改造的机会”。
disable-model-invocation: true
---

# 架构机会侦察

调查代码库中**有证据表明值得进一步设计**的模块边界。不把“代码看起来不漂亮”当作重构理由，也不把热点自动当架构问题。

这是**候选发现**，不是设计或实施：报告后停下，等用户选一个；不自行修改代码、架构文档或 ADR。

## 适用时机

- 大功能开工前：“怎样让接下来的改动更容易？”
- 某个概念每次修改都要跨多个文件、反复协调
- 现有模块难以通过公开接口测试
- 用户明确要求检查代码库结构或寻找改造机会

不作为 `implementation-workflow` 每次完成后的必经质量门。`complexity-audit` 分析函数级 CRAP 风险；`diff-review` 评审本次改动；本技能调查**模块级、面向未来改动的摩擦**。

## 1. 先确定范围

用户指定模块、痛点或即将开展的需求时，以其为范围；否则通过近期相关提交找调查起点。提交热点**只决定先查哪里**，不证明那里需要改造。范围过大时先缩到具体业务概念；不要无目标全仓扫描。

## 2. 按调查规模取证

| 范围 | 调查方式 |
|---|---|
| 少数文件、单个明确问题 | 主 Agent 直接查 |
| 单个模块但调用链较长 | 1 个 `researcher` |
| 多模块、需要交叉核对 | 并行 2–3 个 `researcher`，按**结构／历史／测试与约束**分工 |
| 大范围且改造方向有争议 | 可增加第 4 个 researcher 专门找**反证与最小替代** |

只有调查问题清晰、各方向相对独立、汇总收益大于调度成本时才并行。**researcher 只收集事实和反证，不决定哪个模块该重构。** 每个任务给出范围、时间/版本和统一输出格式，见 `references/research-briefs.md`。没有可用 researcher 通道时，主 Agent 自行分阶段调查，不假装已委派。

多个报告回来后按**证据**而非投票汇总：去重、核对互相矛盾的观察，抽查关键文件/行号，标记未知项。不得把几个 researcher 的猜测合并成“多方确认”。

## 3. 筛选候选：先过硬门槛

一个候选至少说清：

1. **真实摩擦**：具体哪类修改需要跨哪些模块；给出文件、调用路径或历史变更证据。
2. **当前边界为何浅**：接口暴露了什么本应隐藏的知识。
3. **删除测试**：去掉这层后，复杂度会集中在更小的接口后面，还是仅仅转移到调用方？转移或无法证明时，不推荐“深化”。
4. **反证**：现有边界为什么可能合理？什么事实会推翻建议？
5. **最小替代**：改名、局部收拢或补测试是否已能解决同一摩擦？
6. **成本与迁移风险**：公共调用方、兼容性、测试保护、分阶段迁移与回滚。

**过不了这些门槛就不进推荐清单。允许输出零候选；默认最多推荐 3 个有证据的候选。** 具体判据与“维持现状／最小整理／结构改造”的对比方法见 `references/deep-module-criteria.md`。

## 4. 只出报告，停下等用户

默认写入当前仓库 `docs/research/YYYY-MM-DD-architecture-scout-主题.md`；用户只要即时回答时可直接在对话中报告。文档报告列出候选及证据、反证、三方案取舍和迁移风险；证据不足时明确写“未发现值得优先改造的机会”。格式见 `references/candidate-report.md`。

**不生成依赖网络 CDN 的 HTML，不自动打开浏览器。** 需要可视化时，经用户确认后再采用当前环境已有且不引入新强依赖的方式；图示不能代替源码证据。

报告后询问用户要深入哪个候选；用户未选之前**不设计新接口、不开始重构、不进入无限追问循环**。选定后可另行做详细设计，再交给 `implementation-workflow` 实施。

## 质量自检

评估不应只奖励“找到几个候选”。必须能正确回答“现在不值得改”，也必须面对看似浅但由 ADR、兼容性或性能约束支撑的反例。测试用例与评分点见 `references/evaluation-cases.md`。

## References

- `references/deep-module-criteria.md` —— 深/浅边界、删除测试、反证与成本判据
- `references/research-briefs.md` —— 0–4 个 researcher 的调查分工和统一输出
- `references/candidate-report.md` —— 候选报告及零候选模板
- `references/evaluation-cases.md` —— 正例、反例和验收标准