codebase-recon

代码库分析

基于证据的调查 → 发现 → 置信度可追踪的结论。

步骤

1. 从多个来源收集证据（代码、文档、测试、历史记录）
2. 随着调查推进，追踪置信度
3. 根据调查发现：
   • 如果需要模式分析 → 加载 outfitter:patterns 技能
   • 如果需要调查根本原因 → 加载 outfitter:find-root-causes 技能
   • 如果可以准备报告 → 加载 outfitter:report-findings 技能
4. 提交调查发现，并注明置信度和注意事项

<when_to_use>

• 探索和了解代码库
• 分析和梳理架构
• 提取和识别模式
• 在代码中开展技术研究
• 分析性能或安全性

不适用于：毫无根据的猜测、缺乏证据的假设、调查前就下结论

</when_to_use>

等级	级别	名称	操作
░░░░░	0	收集证据中	收集初步证据
▓░░░░	1	初步摸排	广泛扫描，识别表层模式
▓▓░░░	2	深入调查中	深入分析，验证模式
▓▓▓░░	3	分析中	交叉核对，补齐缺口
▓▓▓▓░	4	综合归纳中	联系各项发现，置信度较高
▓▓▓▓▓	5	已得出结论	提交调查发现

校准：0=0–19%，1=20–39%，2=40–59%，3=60–74%，4=75–89%，5=90–100%

从诚实评估开始。代码库清晰且问题聚焦 → 级别 2–3。问题模糊或复杂 → 级别 0–1。

达到级别 4 时：“对调查发现有较高置信度。再从一个角度调查即可完全确定。继续调查还是现在提交？”

低于级别 5 时：包含 △ 注意事项 部分。

核心方法

证据优先于假设——能调查时就调查，只有必要时才猜测。

从多种来源收集信息——代码、文档、测试、历史记录、网络研究、运行时行为。

多角度分析——得出结论前，从不同角度进行检查。

记录缺口——用 △ 标记不确定之处，追踪尚不明确的内容。

展示推理过程——调查发现应包含支持证据，而不只是结论。

校准置信度——区分事实、推断和假设。

<evidence_gathering>

来源优先级

1. 直接观察——阅读代码、执行搜索、检查文件
2. 文档——官方文档、行内注释、ADR
3. 测试——揭示预期行为和边缘情况
4. 历史记录——git log、提交消息、PR 讨论
5. 外部研究——库文档、Stack Overflow、RFC
6. 推断——根据现有证据进行逻辑推导
7. 假设——无法获得其他来源时，明确标记

调查模式

先广泛探索，再逐步聚焦：

• 文件树 → 确定相关区域
• 搜索模式 → 定位特定代码
• 代码结构 → 无需阅读全部内容即可了解结构
• 阅读目标文件 → 检查实现
• 交叉核对 → 验证理解

分层收集证据：

• 代码做了什么？（直接观察）
• 为什么这样编写？（历史记录、注释）
• 它如何融入系统？（架构、依赖关系）
• 有哪些边缘情况？（测试、错误处理）

循线追踪：

• 函数调用 → 追踪执行路径
• 导入/导出 → 梳理依赖关系
• 测试文件 → 了解使用模式
• 错误消息 → 揭示假设
• 注释 → 记录历史背景

</evidence_gathering>

<output_format>

调查期间

每完成一步证据收集后，输出：

• 置信度： {BAR} {NAME}
• 发现： { 关键发现 }
• 模式： { 正在显现的主题 }
• 缺口： { 仍不明确的内容 }
• 下一步： { 调查方向 }

提交调查结果时（级别 5）

调查发现

{ 列出带有支持证据的发现 }

1. {FINDING} — 证据：{SOURCE}
2. {FINDING} — 证据：{SOURCE}

模式

{ 识别出的反复出现的主题或结构 }

影响

{ 这些发现对当前问题意味着什么 }

</output_format>

置信度评估

总体：{BAR} {PERCENTAGE}%

高置信度领域：

• {AREA} — {REASON}

较低置信度领域：

• {AREA} — {REASON}

支持证据

• 代码：{ file paths and line ranges }
• 文档：{ references }
• 测试：{ relevant test files }
• 历史记录：{ commit SHAs if relevant }
• 外部来源：{ URLs if applicable }

低于 5 级

△ 注意事项

假设：

• {ASSUMPTION} — { why necessary, impact if wrong }

缺口：

• {GAP} — { what's missing, how to fill }

未知项：

• {UNKNOWN} — { noted for future investigation }

</output_format>

<specialized_techniques>

加载适用于专项分析的技能（参见“步骤”部分）：

• 模式分析 → outfitter:patterns
• 根因调查 → outfitter:find-root-causes
• 研究综合 → outfitter:report-findings
• 架构分析 → 参见 architecture-analysis.md

</specialized_techniques>

循环：收集 → 分析 → 更新置信度 → 下一步

1. 校准初始置信度 — 我们已经了解了什么？
2. 确定证据来源 — 可以从哪里查找？
3. 系统地收集 — 从多个角度收集信息
4. 交叉核对发现 — 验证规律是否成立
5. 标记不确定性 — 用 △ 标记缺口
6. 综合结论 — 将证据与洞见关联起来
7. 给出置信度等级 — 明确说明确定程度

每一步：

• 记录发现的内容（证据）
• 说明其含义（解读）
• 跟踪仍不清楚的内容（缺口）
• 更新置信度条

结束前（4 级及以上）：

检查证据质量：

• ✓ 是否有多个来源证实这一规律？
• ✓ 是否明确区分了直接观察与推断？
• ✓ 是否明确标记了假设？
• ✓ 是否考虑了反例？

检查完整性：

• ✓ 是否充分回答了原始问题？
• ✓ 是否探讨了边缘情况？
• ✓ 是否排除了其他解释？
• ✓ 是否记录了已知的未知项？

检查交付内容：

• ✓ 发现是否有证据支持？
• ✓ 置信度是否经过诚实校准？
• ✓ 置信度低于 100% 时，是否包含注意事项部分？
• ✓ 若未完成，后续步骤是否明确？

始终：

• 先调查，再下结论
• 使用文件路径/URL 引用证据来源
• 使用置信度条跟踪确定程度
• 用 △ 标记假设和缺口
• 从多个角度交叉核对
• 记录调查过程
• 区分事实与推断
• 低于 5 级时包含注意事项

绝不：

• 能调查时不要猜测
• 不要将假设说成事实
• 不要仅依据单一来源下结论
• 不要掩盖不确定性或缺口
• 不要跳过验证检查
• 不要在未评估置信度的情况下交付
• 不要混淆证据与解读

核心方法：

• confidence.md — 置信度校准（与 pathfinding 共用）

微技能（按需加载）：

• outfitter:patterns — 提取并验证模式
• outfitter:find-root-causes — 系统化问题诊断
• outfitter:report-findings — 多来源研究综合

本地参考资料：

• architecture-analysis.md — 绘制系统结构图

相关技能：

• outfitter:pathfinding — 在分析前明确需求
• outfitter:debugging — 结构化错误调查