dive
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDive
Dive
Dives deep into your project to investigate any question, from business logic to technical implementation. Uses layered search strategy to find evidence-based answers backed by documentation and code.
深入研究你的项目，调查从业务逻辑到技术实现的任何问题。采用分层搜索策略，找到由文档和代码支持的基于证据的答案。
Philosophy
理念
Why Dive?
为什么选择Dive？
Dive exists because assumptions are dangerous.
The core question isn't "how do I find the answer?" but "how do I know my answer is true?"
The Fundamental Problem:
├── Memory is unreliable (yours and the codebase's docs)
├── Code evolves faster than documentation
├── "I think it works like..." is not evidence
└── Only the current codebase tells the current truthDive的存在是因为假设是危险的。
核心问题不是“我如何找到答案？”，而是“我如何确定我的答案是正确的？”
The Fundamental Problem:
├── Memory is unreliable (yours and the codebase's docs)
├── Code evolves faster than documentation
├── "I think it works like..." is not evidence
└── Only the current codebase tells the current truthEvidence Over Intuition
证据优先于直觉
Intuition: "This probably uses X pattern"
Dive: "render.ts:273 shows reconcileKeyedChildren() implementation"Intuition is a starting point, not an answer. Dive converts intuition into verified knowledge through evidence gathering.
Intuition: "This probably uses X pattern"
Dive: "render.ts:273 shows reconcileKeyedChildren() implementation"直觉只是起点，而非答案。Dive通过收集证据将直觉转化为经过验证的知识。
Layered Search: Why This Order?
分层搜索：为何按此顺序？
Layer 1: Documentation → What the project CLAIMS to do
Layer 2: Code → What the project ACTUALLY does
Layer 3: Deep Analysis → HOW it all connectsWhy documentation first?
- It's faster to read
- It gives you vocabulary for code search
- Discrepancies between docs and code are themselves findings
Why code second?
- Code is ground truth—it can't lie about what it does
- Tests show expected behavior in executable form
- Types reveal contracts and constraints
Why deep analysis last?
- It's expensive (time, context)
- Only needed when layers 1-2 don't converge
- Cross-component questions need tracing
Layer 1: Documentation → What the project CLAIMS to do
Layer 2: Code → What the project ACTUALLY does
Layer 3: Deep Analysis → HOW it all connects为何先看文档？
- 阅读速度更快
- 为代码搜索提供专业词汇
- 文档与代码之间的差异本身就是发现
为何再看代码？
- 代码是最真实的依据——它不会谎报自身功能
- 测试以可执行形式展示预期行为
- 类型定义揭示契约和约束
为何最后进行深度分析？
- 成本高（时间、上下文）
- 仅在第一层和第二层无法得出结论时才需要
- 跨组件问题需要跟踪
Cross-Referencing Reveals Truth
交叉引用揭示真相
When documentation says X but code does Y:
- The code is always correct about behavior
- The documentation reveals intent or outdated understanding
- The discrepancy itself is valuable information
This is not a failure of search. It's a success—you found something real.
当文档说X但代码做Y时：
- 代码的行为永远是正确的
- 文档反映了意图或过时的理解
- 这种差异本身就是有价值的信息
这并非搜索失败，而是成功——你发现了真实存在的问题。
Core Concepts
核心概念
Evidence Has Hierarchy
证据有层级之分
Not all evidence is equal:
| Source | Reliability | What it proves |
|---|---|---|
| Running code | Highest | Current behavior |
| Tests | High | Expected behavior |
| Implementation | High | How it works |
| Type definitions | Medium-High | Contracts |
| Comments | Medium | Developer intent |
| Documentation | Medium | Claimed behavior |
| Commit messages | Low-Medium | Historical intent |
Multiple sources agreeing = high confidence.
Single source = verify with another layer.
并非所有证据的价值都相同：
| 来源 | 可靠性 | 能证明什么 |
|---|---|---|
| 运行中的代码 | 最高 | 当前行为 |
| 测试 | 高 | 预期行为 |
| 实现代码 | 高 | 工作原理 |
| 类型定义 | 中高 | 契约 |
| 注释 | 中 | 开发者意图 |
| 文档 | 中 | 声称的行为 |
| 提交信息 | 中低 | 历史意图 |
多个来源一致 = 高可信度。
单一来源 = 需用另一层验证。
The Question Shapes the Search
问题决定搜索方式
Different questions need different approaches:
"How does X work?" → Start with code, verify with tests
"Why is X designed this way?" → Start with docs/ADRs, check history
"What calls X?" → Start with grep, trace references
"When did X change?" → Start with git log, find the commit
Don't apply the same search pattern to every question. Let the question guide you.
不同的问题需要不同的方法：
“X如何工作？” → 从代码开始，用测试验证
“X为何如此设计？” → 从文档/ADRs开始，查看历史记录
“什么调用了X？” → 从grep开始，跟踪引用
“X何时变更？” → 从git log开始，找到相关提交
不要对所有问题应用相同的搜索模式，让问题引导你的搜索。
Uncertainty is Information
不确定性也是信息
When you can't find clear evidence:
- State what you searched
- State what you found (even partial)
- State what's missing
- Offer hypotheses, clearly labeled as such
"I couldn't find X" is a valid finding. It tells the next investigator where not to look.
当你找不到明确的证据时：
- 说明你搜索了什么
- 说明你找到了什么（即使是部分内容）
- 说明缺失的信息
- 给出假设，并明确标记为假设
“我找不到X”是一个有效的发现，它能告诉后续调查者哪些地方不用再查。
The Dive Loop
Dive循环
1. Understand: What exactly is being asked?
↓
2. Search: Layer 1 → Layer 2 → Layer 3 (as needed)
↓
3. Collect: Gather evidence with file:line citations
↓
4. Synthesize: What do the sources tell us together?
↓
5. Respond: Direct answer + evidence + uncertaintyThis isn't a checklist to follow blindly. It's a mental model for thorough investigation.
1. Understand: What exactly is being asked?
↓
2. Search: Layer 1 → Layer 2 → Layer 3 (as needed)
↓
3. Collect: Gather evidence with file:line citations
↓
4. Synthesize: What do the sources tell us together?
↓
5. Respond: Direct answer + evidence + uncertainty这不是一个需要盲目遵循的检查清单，而是用于全面调查的思维模型。
When Layers Conflict
当各层信息冲突时
Documentation says one thing, code does another. This is common. Here's how to think about it:
| Situation | What to trust | What to report |
|---|---|---|
| Docs outdated | Code | Note the discrepancy |
| Feature removed | Code | Flag potential doc cleanup |
| Docs wrong | Code | Recommend doc fix |
| Code buggy | Neither | Flag as potential bug |
The key: always report both, let context determine action.
文档说一套，代码做一套，这种情况很常见。以下是应对思路：
| 情况 | 该相信什么 | 该报告什么 |
|---|---|---|
| 文档过时 | 代码 | 注明差异 |
| 功能已移除 | 代码 | 标记文档需要清理 |
| 文档错误 | 代码 | 建议修复文档 |
| 代码有bug | 都不信 | 标记为潜在bug |
关键：始终报告两者，让上下文决定后续行动。
Reference
参考资料
Load these as needed, not upfront:
- reference/search-strategies.md - Detailed search patterns
- reference/code-search-patterns.md - Code navigation techniques
- reference/evidence-collection.md - Citation formats and templates
按需加载这些资料，无需提前阅读：
- reference/search-strategies.md - 详细搜索模式
- reference/code-search-patterns.md - 代码导航技巧
- reference/evidence-collection.md - 引用格式和模板
Understanding, Not Rules
理解而非遵循规则
Instead of memorizing anti-patterns, understand the underlying tensions:
| Tension | Resolution |
|---|---|
| Speed vs Thoroughness | Match depth to stakes. Quick question? Layer 1 may suffice. Critical decision? Go deep. |
| Confidence vs Evidence | Never state confidence without evidence. "I'm 90% sure" means nothing without sources. |
| Intuition vs Verification | Use intuition to guide search, not to answer. Then verify. |
| Completeness vs Relevance | Answer the question asked. Note related findings briefly, don't digress. |
The goal isn't to follow a procedure. It's to know when you know something is true.
与其死记硬背反模式，不如理解背后的矛盾：
| 矛盾 | 解决方案 |
|---|---|
| 速度 vs 彻底性 | 根据问题的重要程度匹配调查深度。简单问题？第一层可能就足够。关键决策？深入调查。 |
| 信心 vs 证据 | 没有证据就不要声称有信心。“我90%确定”在没有来源支撑的情况下毫无意义。 |
| 直觉 vs 验证 | 用直觉引导搜索，而非直接给出答案。然后进行验证。 |
| 完整性 vs 相关性 | 回答被问到的问题。简要提及相关发现，但不要偏离主题。 |
目标不是遵循流程，而是知道自己何时确定某件事是真实的。