name: 代码库调查 description: 在规划或设计功能时使用，需要理解当前代码库状态，查找现有模式，或验证关于存在内容的假设；当设计对文件位置、结构或现有代码做出假设需要验证时 - 通过将计划基于现实来防止幻觉 user-invocable: false
代码库调查
概述
理解当前代码库状态，以便将规划和设计决策基于现实而非假设。查找现有模式，验证设计假设，并提供关于存在内容和位置的明确答案。
何时使用
使用于：
- 在实施前验证设计假设（“设计假设 auth.ts 存在 - 验证”）
- 查找现有模式以遵循（“我们目前如何处理 API 错误？”）
- 定位功能或代码（“用户身份验证在哪里实现？”）
- 理解组件架构（“路由系统如何工作？”）
- 明确确认存在性（“功能 X 是否存在？”）
- 防止关于文件路径和结构的幻觉
不用于：
- 外部文档中可用的信息（使用互联网研究）
- 通过阅读1-2个特定已知文件可回答的问题（直接阅读）
- 不特定于此代码库的通用编程问题
核心调查工作流
- 从入口点开始 - 主要文件、index、package.json、配置
- 使用多种搜索策略 - Glob模式、Grep关键词、阅读文件
- 跟踪痕迹 - 导入、引用、组件关系
- 验证而非假设 - 确认文件位置和结构
- 明确报告 - 确切路径或搜索策略的"未找到"
验证设计假设
当给定设计假设进行验证时：
- 提取假设 - 列出设计期望存在的内容
- 搜索每个 - 文件路径、函数、模式、依赖
- 比较现实与期望 - 匹配、差异、附加、缺失
- 明确报告：
- ✓ 确认：“设计假设正确：auth.ts:42 有 login()”
- ✗ 差异：“设计假设 auth.ts，但找到 auth/index.ts”
-
- 附加：“找到未在设计提到的 logout()”
-
- 缺失：“设计期望 resetPassword()，未找到”
为什么重要： 防止基于代码库结构错误假设的实施计划。
快速参考
| 任务 | 策略 |
|---|---|
| X 在哪里 | Glob 可能名称 → Grep 关键词 → 阅读匹配 |
| X 如何工作 | 找到入口点 → 跟踪导入 → 阅读实现 |
| 存在哪些模式 | 找到示例 → 比较实现 → 提取约定 |
| X 是否存在 | 多次搜索 → 明确是/否 → 证据 |
| 验证假设 | 提取声明 → 搜索每个 → 比较现实与期望 |
调查策略
多种搜索方法：
- Glob 用于跨代码库的文件模式
- Grep 用于关键词、函数名、导入
- 阅读关键文件以理解实现
- 跟踪导入和引用以了解关系
- 检查 package.json、配置文件以了解依赖
不要停留在第一个结果：
- 探索多个路径以验证发现
- 交叉参考代码库的不同区域
- 确认模式一致而非偶然
- 跟踪使用和定义痕迹
验证一切：
- 从不假设文件位置 - 总是用阅读/Glob验证
- 从不假设结构 - 探索并确认
- 报告"未找到"时记录搜索策略
- 区分"不存在"和"未能定位"
报告发现
以直接答案开头：
- 先回答问题
- 支持细节其次
- 证据带有确切文件路径和行号
提供可操作的情报：
- 确切文件路径（src/auth/login.ts:42），而非模糊位置
- 显示当前模式的相关代码片段
- 依赖和版本（当相关时）
- 配置文件和当前设置
- 命名、结构和测试约定
自信处理"未找到"：
- "功能 X 不存在"是有效且有用的
- 解释搜索了什么和在哪里查找
- 建议相关代码作为起点
- 报告负面发现以防止幻觉
常见错误
| 错误 | 修复 |
|---|---|
| 假设文件位置 | 在报告前总是用阅读/Glob验证 |
| 停留在第一个结果 | 探索多个路径以验证发现 |
| 模糊位置（“在 auth 文件夹”） | 确切路径（src/auth/index.ts:42） |
| 未记录搜索策略 | 报告"未找到"时解释检查了什么 |
| 混淆"未找到"类型 | 区分"不存在"和"未能定位" |
| 跳过设计假设比较 | 明确报告：确认/差异/附加/缺失 |
| 将假设报告为事实 | 只报告在代码库中验证的内容 |