investigating-a-codebase
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseInvestigating a Codebase
代码库调查
Overview
概述
Understand current codebase state to ground planning and design decisions in reality, not assumptions. Find existing patterns, verify design assumptions, and provide definitive answers about what exists and where.
了解当前代码库的实际状态，让规划和设计决策基于真实情况而非假设。查找现有模式，验证设计假设，并提供关于现有内容及其位置的明确答案。
When to Use
使用场景
Use for:
- Verifying design assumptions before implementation ("Design assumes auth.ts exists - verify")
- Finding existing patterns to follow ("How do we currently handle API errors?")
- Locating features or code ("Where is user authentication implemented?")
- Understanding component architecture ("How does the routing system work?")
- Confirming existence definitively ("Does feature X exist or not?")
- Preventing hallucination about file paths and structure
Don't use for:
- Information available in external docs (use internet research)
- Questions answered by reading 1-2 specific known files (use Read directly)
- General programming questions not specific to this codebase
适用场景：
- 实现前验证设计假设（例如：“设计假设auth.ts存在——需要验证”）
- 查找可遵循的现有模式（例如：“我们当前如何处理API错误？”）
- 定位功能或代码（例如：“用户认证功能在哪里实现？”）
- 理解组件架构（例如：“路由系统如何工作？”）
- 明确确认内容是否存在（例如：“功能X是否存在？”）
- 避免对文件路径和结构的凭空设想
不适用场景：
- 外部文档中可获取的信息（应使用互联网搜索）
- 阅读1-2个已知特定文件即可解答的问题（应直接使用Read功能）
- 与当前代码库无关的通用编程问题
Core Investigation Workflow
核心调查工作流
- Start with entry points - main files, index, package.json, config
- Use multiple search strategies - Glob patterns, Grep keywords, Read files
- Follow traces - imports, references, component relationships
- Verify don't assume - confirm file locations and structure
- Report definitively - exact paths or "not found" with search strategy
- 从入口点开始——主文件、index文件、package.json、配置文件
- 使用多种搜索策略——Glob模式、Grep关键词、读取文件
- 追踪关联——导入关系、引用、组件依赖
- 验证而非假设——确认文件位置和结构
- 明确报告——提供确切路径，或说明“未找到”及所使用的搜索策略
Verifying Design Assumptions
验证设计假设
When given design assumptions to verify:
- Extract assumptions - list what design expects to exist
- Search for each - file paths, functions, patterns, dependencies
- Compare reality vs expectation - matches, discrepancies, additions, missing
- Report explicitly:
- ✓ Confirmed: "Design assumption correct: auth.ts:42 has login()"
- ✗ Discrepancy: "Design assumes auth.ts, found auth/index.ts instead"
- + Addition: "Found logout() not mentioned in design"
- - Missing: "Design expects resetPassword(), not found"
Why this matters: Prevents implementation plans based on wrong assumptions about codebase structure.
当需要验证设计假设时：
- 提取假设内容——列出设计预期存在的内容
- 逐一搜索——文件路径、函数、模式、依赖
- 对比实际与预期——匹配项、差异、新增内容、缺失内容
- 明确报告：
- ✓ 已确认：“设计假设正确：auth.ts第42行包含login()函数”
- ✗ 存在差异：“设计假设存在auth.ts，实际找到的是auth/index.ts”
-
- 额外发现：“找到设计中未提及的logout()函数”
-
- 缺失内容：“设计预期存在resetPassword()，未找到”
重要性： 避免基于错误的代码库结构假设制定实现计划。
Quick Reference
快速参考
| Task | Strategy |
|---|---|
| Where is X | Glob likely names → Grep keywords → Read matches |
| How does X work | Find entry point → Follow imports → Read implementation |
| What patterns exist | Find examples → Compare implementations → Extract conventions |
| Does X exist | Multiple searches → Definitive yes/no → Evidence |
| Verify assumptions | Extract claims → Search each → Compare reality vs expectation |
| 任务 | 策略 |
|---|---|
| X在哪里？ | 用Glob匹配可能的名称 → 用Grep搜索关键词 → 读取匹配文件 |
| X如何工作？ | 找到入口点 → 追踪导入关系 → 读取实现代码 |
| 存在哪些模式？ | 查找示例 → 对比实现方式 → 提炼约定 |
| X是否存在？ | 多种方式搜索 → 明确是/否 → 提供证据 |
| 验证假设 | 提取声明内容 → 逐一搜索 → 对比实际与预期 |
Investigation Strategies
调查策略
Multiple search approaches:
- Glob for file patterns across codebase
- Grep for keywords, function names, imports
- Read key files to understand implementation
- Follow imports and references for relationships
- Check package.json, config files for dependencies
Don't stop at first result:
- Explore multiple paths to verify findings
- Cross-reference different areas of codebase
- Confirm patterns are consistent not one-off
- Follow both usage and definition traces
Verify everything:
- Never assume file locations - always verify with Read/Glob
- Never assume structure - explore and confirm
- Document search strategy when reporting "not found"
- Distinguish "doesn't exist" from "couldn't locate"
多种搜索方法：
- 用Glob匹配代码库中的文件模式
- 用Grep搜索关键词、函数名、导入语句
- 读取关键文件以理解实现逻辑
- 追踪导入和引用关系
- 检查package.json、配置文件以了解依赖
不要停留在首个结果：
- 探索多种路径以验证发现
- 交叉参考代码库的不同区域
- 确认模式是通用的而非特例
- 同时追踪使用和定义的关联
验证所有内容：
- 永远不要假设文件位置——始终通过Read/Glob验证后再报告
- 永远不要假设结构——探索并确认
- 当报告“未找到”时，记录所使用的搜索策略
- 区分“不存在”和“无法定位”
Reporting Findings
报告调查结果
Lead with direct answer:
- Answer the question first
- Supporting details second
- Evidence with exact file paths and line numbers
Provide actionable intelligence:
- Exact file paths (src/auth/login.ts:42), not vague locations
- Relevant code snippets showing current patterns
- Dependencies and versions when relevant
- Configuration files and current settings
- Naming, structure, and testing conventions
Handle "not found" confidently:
- "Feature X does not exist" is valid and useful
- Explain what you searched and where you looked
- Suggest related code as starting point
- Report negative findings prevents hallucination
先给出直接答案：
- 首先回答问题
- 其次提供支持细节
- 附上包含确切文件路径和行号的证据
提供可落地的信息：
- 确切的文件路径（如src/auth/login.ts:42），而非模糊的位置
- 展示当前模式的相关代码片段
- 相关依赖及其版本（如适用）
- 配置文件和当前设置
- 命名、结构和测试约定
自信地处理“未找到”的情况：
- “功能X不存在”是有效且有用的结论
- 说明你搜索的内容和范围
- 建议相关代码作为起点
- 报告负面结果可避免凭空设想
Common Mistakes
常见错误
| Mistake | Fix |
|---|---|
| Assuming file locations | Always verify with Read/Glob before reporting |
| Stopping at first result | Explore multiple paths to verify findings |
| Vague locations ("in auth folder") | Exact paths (src/auth/index.ts:42) |
| Not documenting search strategy | Explain what was checked when reporting "not found" |
| Confusing "not found" types | Distinguish "doesn't exist" from "couldn't locate" |
| Skipping design assumption comparison | Explicitly report: confirmed/discrepancy/addition/missing |
| Reporting assumptions as facts | Only report what was verified in codebase |
| 错误 | 解决方法 |
|---|---|
| 假设文件位置 | 报告前始终通过Read/Glob验证 |
| 停留在首个结果 | 探索多种路径以验证发现 |
| 位置描述模糊（如“在auth文件夹中”） | 使用确切路径（如src/auth/index.ts:42） |
| 未记录搜索策略 | 报告“未找到”时说明检查过的内容 |
| 混淆“未找到”的类型 | 区分“不存在”和“无法定位” |
| 跳过设计假设对比 | 明确报告：已确认/存在差异/额外发现/缺失内容 |
| 将假设作为事实报告 | 仅报告在代码库中验证过的内容 |