debug

Debug - 根因调试工作流

完整的调试工作流，强制执行根因分析：调查 → 理解 → 推理 → 修复。

概述

Debug 结合了多种调试方法：

• 代码库调查 - 搜索相关代码
• GitHub issue 搜索 - 查找已知问题和变通方案
• 多框架推理 - 应用系统性思维
• 修复生成 - 附带代码的具体建议

前置条件

# Gemini CLI for AI analysis
pip install google-generativeai
export GEMINI_API_KEY=your_api_key

# gh CLI for GitHub issue search
brew install gh
gh auth login

调试工作流

完整调试（推荐用于复杂问题）

# Phase 1: Investigate codebase
rg -l "error pattern" --type ts
rg "relevant_function" -A 10 -B 5

# Phase 2: Search GitHub for known issues
gh search issues "error message" --repo owner/repo --limit 10
gh issue view 123 --repo owner/repo

# Phase 3: Reason about root cause
gemini -m pro -o text -e "" "Given this error and code context, what is the root cause?

Error: [error message]

Code:
\$(cat src/file.ts)

Investigation findings:
- [finding 1]
- [finding 2]

Apply first principles, systematic, and critical thinking frameworks."

# Phase 4: Generate fix
gemini -m pro -o text -e "" "Based on root cause: [cause]

Provide:
1. Specific code fix
2. Before/after code
3. How to verify
4. How to prevent"

快速调试（简单问题）

# Skip deep reasoning, focus on investigation + fix
rg "error pattern" --type ts -A 5 -B 5

gemini -m pro -o text -e "" "Debug this quickly:

Problem: [description]
Error: [message]

Code:
\$(cat src/problematic-file.ts)

Give me the root cause and fix in 3 sentences."

带上下文调试（已知文件）

# When you already know which files are involved
gemini -m pro -o text -e "" "Debug using these files:

Problem: [description]

File 1:
\$(cat src/file1.ts)

File 2:
\$(cat src/file2.ts)

Provide:
1. Root cause
2. Specific fix with line numbers
3. Verification steps"

全面诊断（复杂问题）

# Parallel investigation of multiple sources

# Terminal 1: Codebase search
rg "error" --type ts --stats > /tmp/codebase.txt &

# Terminal 2: GitHub issues
gh search issues "error" --limit 20 > /tmp/github.txt &

# Terminal 3: Git history
git log --oneline --all -S "problematic_function" > /tmp/history.txt &

wait

# Synthesize findings
gemini -m pro -o text -e "" "Synthesize these diagnostic findings:

Codebase:
\$(cat /tmp/codebase.txt)

GitHub Issues:
\$(cat /tmp/github.txt)

Git History:
\$(cat /tmp/history.txt)

Provide unified diagnosis with:
1. Most likely root cause
2. Confidence level
3. Key evidence
4. Differential diagnosis
5. Recommended action"

根因协议

始终遵循此层级：

1. 调查 - 首先搜索证据
2. 理解 - 阅读相关代码
3. 推理 - 应用系统性思维
4. 修复 - 只有到这时才提出更改

禁止的捷径

症状	禁止的修复	必需的修复
空值错误	if (x) { x.y }	找出 x 为空的原因
超时	增加超时时间	找出慢的原因
不稳定测试	跳过测试	找出竞态条件
类型错误	as any	修复类型层级

调查命令

代码库搜索

# Find error patterns
rg "throw.*Error" --type ts -A 3

# Find function definitions
rg "function functionName|const functionName" --type ts

# Find usages
rg "functionName\(" --type ts

# Find recent changes
git log --oneline -20 --all -- src/problematic/
git diff HEAD~5 -- src/problematic/

GitHub Issue 搜索

# Search issues
gh search issues "error message" --repo owner/repo --state all

# View issue details
gh issue view 123 --repo owner/repo --comments

# Search across multiple repos
for repo in repo1 repo2 repo3; do
  gh search issues "error" --repo owner/$repo --limit 5
done

日志分析

# Find logs first
find . -name "*.log" -type f

# Tail recent logs
tail -100 logs/app.log | grep -i error

# Search logs for patterns
grep -n "ERROR\|WARN" logs/*.log | tail -50

基于框架的推理

第一性原理

gemini -m pro -o text -e "" "Apply first principles to this bug:

Problem: [description]

Questions:
1. What is this code supposed to do?
2. What is it actually doing?
3. What assumptions are being made?
4. Which assumption is wrong?"

系统性分析

gemini -m pro -o text -e "" "Systematically analyze:

Problem: [description]

Walk through:
1. Input → What data enters?
2. Processing → What transformations?
3. State → What state changes?
4. Output → What comes out?
5. Where does expected diverge from actual?"

批判性思维

gemini -m pro -o text -e "" "Challenge assumptions:

Problem: [description]

For each potential cause:
- What evidence supports it?
- What evidence contradicts it?
- What would we expect to see if true?
- Can we rule it out?"

输出格式

一次调试会话应产生：

## ROOT CAUSE
Single sentence identifying the actual cause.

## CONFIDENCE
high | medium | low

## FIX
Specific code changes:
- File: src/file.ts
- Line: 42
- Before: `oldCode()`
- After: `newCode()`

## VERIFICATION
How to verify the fix works:
1. Run test: `npm test -- specific.test.ts`
2. Manual check: [steps]

## PREVENTION
How to prevent this in the future:
- Add validation at boundary
- Add regression test

最佳实践

1. 日志优先 - 先读日志，再读代码
2. 需要证据 - 没有引用具体证据就不修复
3. 单一原因 - 找到根本原因，而非症状
4. 验证假设 - 在修复前测试你的理论
5. 防止复发 - 为失败模式添加测试
6. 记录发现 - 记录你学到的东西