Architecture Scout

---
name: architecture-scout
description: 仅在用户明确要求架构机会调查时使用。调查值得深化的模块边界、跨模块修改的根因和难测试的结构；只报告，不修改代码，允许零候选。
dsh-model-invocable: false
---

# 架构机会侦察

仅在用户主动要求架构调查时运行；实施或评审完成后不自动触发。

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

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

## 适用时机

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

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

## 委派

需要独立上下文时，用宿主通用子 agent 工具实际派发。传入目标项目的绝对路径、范围/基线、约束、所需技能资源的绝对路径和交付要求（资源不可读时附必要方法）；子 agent 只做分配的任务，回报证据、完成状态与未验证项。仅在任务及文件/工具产物互不冲突时并行；无派发能力时自行执行并说明。

## 1. 先确定范围

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

## 2. 按调查规模取证

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

**调查子 agent 只收集事实和反证，不决定哪个模块该重构。** 按 `references/research-briefs.md` 派发，各自返回证据；主 Agent 统一生成报告。

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

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

一个候选至少说清：

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

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

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

默认落盘。位置按顺序取第一个命中项：① 用户显式指定的路径；② 仓库明文约定（`AGENTS.md` / `CONTRIBUTING.md` / `README.md`）；③ 仓库已有报告类目录 `docs/research/`、`docs/architecture/`；④ 都没有时新建 `docs/architecture-scout/`（仓库无 `docs/` 则先建）。文件名 `YYYY-MM-DD-主题.md`；落在共享目录（如 `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 个调查子 agent 的调查分工和统一输出
- `references/candidate-report.md` —— 候选报告及零候选模板
- `references/evaluation-cases.md` —— 正例、反例和验收标准