name: 调查代码模式 description: 系统性地追踪代码流，定位实现，诊断性能问题，映射系统架构。当理解现有系统如何工作、研究概念、探索代码结构或回答“X如何/在哪里/为什么实现？”问题时使用。
调查代码模式
何时使用此技能
- 理解现有系统端到端的工作方式
- 研究代码库中的概念或技术
- 探索代码结构、模式和依赖关系
- 回答关于实现的“如何/在哪里/什么”问题
- 不用于构建新功能（使用实现技能进行）
核心调查类型
1. 代码流：“X 如何工作？”
从入口点到结果端到端追踪执行。
步骤:
- 找到入口点（API 端点、组件、函数）
- 追踪函数调用和数据转换
- 跟随导入和依赖关系
- 识别关键决策点和错误处理
2. 代码位置：“X 在哪里实现？”
在代码库中找到功能所在位置。
步骤:
- 使用 grep 搜索相关关键词
- 检查相关文件和模块
- 识别主要实现和支持文件
- 验证入口点和使用模式
3. 性能分析：“为什么 X 慢？”
使用 3 阶段方法诊断瓶颈。
阶段 1: 定位瓶颈
- 找到发生缓慢的入口点
- 追踪执行路径
- 识别所有操作（数据库查询、API 调用、计算、I/O）
- 查找明显问题：N+1 查询、嵌套循环、大负载
阶段 2: 根本原因（如果不明确）
- 生成按可能性排序的假设
- 用代码证据验证
阶段 3: 修复或检测
- 如果修复清楚 → 实施优化
- 如果不确定 → 添加日志/性能分析供用户测试
常见性能模式:
| 模式 | 症状 | 修复方向 |
|---|---|---|
| N+1 查询 | 顺序数据库调用 | 批量/急切加载 |
| 算法复杂度 | 随数据增长 | 优化算法 |
| 大负载 | 网络时间高 | 分页/过滤 |
| 缺少缓存 | 重复获取相同数据 | 添加缓存 |
| 顺序操作 | 系列等待 | 并行化 |
4. 架构映射：“X 如何结构化？”
理解系统组织、组件和集成点。
步骤:
- 映射组件边界和职责
- 识别层之间的数据流模式
- 记录集成点和依赖关系
- 追踪外部服务交互
调查策略
从文档开始
按此顺序阅读:
docs/product-requirements.md— 项目概述和功能（F-##）docs/feature-spec/F-##-*.md— 技术细节docs/system-design.md— 架构docs/api-contracts.yaml— API 参考
选择您的工具
对于已知文件路径:
Read— 直接检查特定文件
对于模式搜索:
Grep— 查找精确文本匹配（函数名、导入、错误消息）Glob— 通过名称模式发现文件
对于语义查询:
- 启动
Explore代理用于复杂、多文件模式发现 - 使用
senior-engineer代理用于微妙性能瓶颈
并行调查
对于大型代码库，启动 2-4 个独立代理:
全栈流:
- 代理 1: 前端（UI、状态、API 调用）
- 代理 2: 后端（端点、服务、数据库）
- 代理 3: 集成（测试、配置、外部 API）
多服务架构:
- 代理 1: 认证（认证、令牌）
- 代理 2: 用户服务（个人资料、同步）
- 代理 3: 授权（权限、RBAC）
性能问题:
- 代理 1: 前端性能（渲染、打包、资源）
- 代理 2: API/网络（查询、负载、缓存）
- 代理 3: 后端性能（算法、数据库、服务）
记录发现
代码流模板
## 如何 [功能] 工作
### 目的
[简要描述及存在原因]
### 高级别流
1. 用户操作触发 [组件/函数]（文件:行）
2. [步骤 2 带文件:行引用]
3. [步骤 3 带文件:行引用]
4. 最终结果
### 关键文件
- `path/to/file.ts:123` - [目的]
- `path/to/other.ts:45` - [目的]
### 重要细节
- 错误处理: [方法带文件引用]
- 边缘情况: [如何处理]
- 安全: [如果适用，考虑事项]
代码位置模板
## 位置: [功能]
### 主要实现
`path/to/file.ts:45-120` - [目的]
### 相关文件
- `path/component.tsx` - UI 层
- `path/service.ts` - 业务逻辑
- `path/api.ts` - API 集成
### 入口点
1. [用户如何触发此]
2. [系统启动的触发器]
性能分析模板
## 性能分析: [功能]
### 症状
- 慢当: [条件]
- 观察: [X] 秒
- 预期: [Y] 秒
### 根本原因
[什么导致它带文件:行证据]
### 修复选项
**选项 A: [名称]**
- 改变: [做什么]
- 影响: [预期改进]
- 努力: [时间估计]
**推荐:** [哪个选项及原因]
架构映射模板
## 架构: [系统/功能]
### 概述
[高级别描述]
### 组件分解
**[层/模块名称]:**
- 责任: [它做什么]
- 关键文件: [文件路径]
- 依赖: [它需要什么]
### 数据流
[步骤或图表]
### 集成点
- [外部服务]
- [相关功能]
调查工作流
- 澄清问题 — 您试图理解什么？
- 阅读项目文档 — 从概述、功能规格、架构开始
- 选择调查类型 — 流、位置、性能或架构
- 策略性搜索 — 使用直接工具或委托给代理
- 用文件引用记录 — 对所有发现使用
file:line格式 - 提供下一步 — 更深入的调查、文档或实现
关键原则
- 文件引用重要 — 始终引用
file:line作为证据 - 基于证据 — 引用实际代码，不猜测
- 多领域问题需要并行代理 — 前端 + 后端需要独立调查者
- 从简单开始 — 委托前使用直接 grep/read
- 整合发现 — 将并行代理结果综合成连贯解释