🎯 Learning Objectives
Upon completing this issue, you will master:
- How to directly paste error messages to Claude Code for automatic diagnosis
- Claude's complete repair loop: Stack Trace → File Location → Code Modification → Secondary Verification
- Best practices for structured submission of Bug context
- Systematic troubleshooting strategies for multi-layered nested errors
📖 Core Concepts Explained
11.1 Traditional Debugging vs. Agent Debugging
| Dimension |
Traditional Debugging |
Claude Code Debugging |
| Process |
View error → Search Google → Try solutions → Manual modification |
Paste error → Claude automatically reads files → Locate root cause → One-click fix |
| Time Consumption |
30 minutes ~ several hours |
Typically 1-3 minutes |
| Knowledge Dependency |
Requires developers to be familiar with internal framework mechanisms |
Claude possesses vast framework knowledge |
| Secondary Verification |
Manually re-run tests |
Claude automatically verifies with npm test |
11.2 The Golden Flow of Bug Fixing
Paste Stack Trace
│
▼
Claude Analyzes Call Stack
│
▼
Grep / Read to Locate Problem File
│
▼
Understand Code Context
│
▼
Edit to Modify Code
│
▼
Bash to Re-run Verification (npm test / reproduction command)
│
▼
Pass → Commit Fix ✅
Fail → Enter Self-healing Loop 🔄
11.3 Three Common Bug Types
Type 1: Single Point Failure
Characteristic: Stack trace directly points to the error line
Difficulty: ⭐ Easy
Example: TypeError: Cannot read property 'map' of undefined
Type 2: Chain Error
Characteristic: True cause is upstream, error reported downstream
Difficulty: ⭐⭐⭐ Medium
Example: API return structure changed, causing a null pointer error in a component 5 layers deep
Type 3: Phantom Error
Characteristic: Appears only in specific environments or timing sequences
Difficulty: ⭐⭐⭐⭐⭐ Difficult
Example: Race condition, inconsistent state due to hot reload
💻 Simulating Claude TUI Interaction
Scenario 1: Paste Error, One-Click Fix
> The following error occurred after running npm run dev, please fix it:
TypeError: Cannot read properties of undefined (reading 'map')
at UserList (src/components/UserList.tsx:24:18)
at renderWithHooks (node_modules/react-dom/...)
at mountIndeterminateComponent (...)
╭─ Claude ─────────────────────────────────────────────╮
│ │
│ I will analyze this error. The stack trace shows │
│ the problem is in `UserList.tsx` line 24, │
│ in the `.map()` call. │
│ │
│ 🔍 Tool: Read → src/components/UserList.tsx │
│ │
│ Found it! Line 24: │
│ `{users.map(u => <UserCard key={u.id} ... />)}` │
│ │
│ Problem: `users` is `undefined` when data has not │
│ yet loaded, and `.map()` cannot be called on │
│ `undefined`. │
│ │
│ 🔍 Tool: Read → src/hooks/useUsers.ts │
│ This Hook's initial return value indeed lacks a │
│ default value. │
│ │
│ ⚙️ Tool: Edit → src/hooks/useUsers.ts │
│ ╭─ DIFF ────────────────────────────────────╮ │
│ │ - const [users, setUsers] = useState(); │ │
│ │ + const [users, setUsers] = useState([]); │ │
│ ╰────────────────────────────────────────────╯ │
│ │
│ ⚙️ Tool: Bash │
│ $ npm run dev │
│ ✅ Compiled successfully │
│ │
│ ✅ Fix completed. The root cause was `useState` │
│ lacking a default empty array, leading to `users` │
│ being `undefined` during initial rendering. │
│ │
╰──────────────────────────────────────────────────────╯
Scenario 2: Deep Tracing of Chain Errors
> A 500 error was reported after deployment to the production environment:
Error: ENOENT: no such file or directory,
open '/app/config/secrets.json'
at Object.openSync (fs.js:498:3)
at loadConfig (src/config/loader.ts:15:22)
at initDatabase (src/db/connection.ts:8:18)
at startServer (src/index.ts:12:3)
╭─ Claude ─────────────────────────────────────────────╮
│ │
│ This is a chain error. Let me trace it from bottom up:│
│ │
│ 📍 Level 1: src/index.ts:12 → startServer() │
│ 📍 Level 2: src/db/connection.ts:8 → initDatabase() │
│ 📍 Level 3: src/config/loader.ts:15 → loadConfig() │
│ 📍 Root Cause: Failed to read '/app/config/secrets.json'│
│ │
│ 🔍 Tool: Read → src/config/loader.ts │
│ │
│ Problem found! Line 15 hardcoded the file path: │
│ `const config = JSON.parse( │
│ fs.readFileSync('/app/config/secrets.json'))` │
│ │
│ In the production environment, this path does not │
│ exist. Environment variables should be used. │
│ │
│ ⚙️ Tool: Edit → src/config/loader.ts │
│ ╭─ DIFF ────────────────────────────────────╮ │
│ │ - const configPath = │ │
│ │ - '/app/config/secrets.json'; │ │
│ │ + const configPath = │ │
│ │ + process.env.CONFIG_PATH │ │
│ │ + || path.join(__dirname, │ │
│ │ + '../../config/secrets.json'); │ │
│ ╰────────────────────────────────────────────╯ │
│ │
│ ⚙️ Tool: Read → Dockerfile │
│ ⚙️ Tool: Edit → Dockerfile │
│ Add: ENV CONFIG_PATH=/etc/app/secrets.json │
│ │
│ ✅ Fix completed. Now supports configuring paths │
│ via environment variables, while retaining default │
│ values for local development. │
│ │
╰──────────────────────────────────────────────────────╯
💻 Code Demo: Efficient Bug Debugging Techniques
# ✅ Strategy 1: Directly paste the complete error
claude "The following error was reported after running pytest, please fix it: [Paste error]"
# ✅ Strategy 2: Pipe error logs
npm test 2>&1 | claude -p "Analyze the following test failures and fix them"
# ✅ Strategy 3: Bug report with context
claude "This Bug only appears when the user is not logged in:
1. Access /dashboard
2. See a blank screen
3. Console error: [Paste error]
Please fix"
# ✅ Strategy 4: Self-healing loop (Print Mode)
claude -p "Run npm test, and if there are failures, fix them,
repeat until all tests pass"
Providing Claude with a Good Bug Context Template
# Add debugging guidelines to CLAUDE.md
cat >> CLAUDE.md << 'EOF'
## Bug Fixing Protocol
Upon receiving a Bug report:
1. First use `Read` to locate all files mentioned in the stack trace
2. Use `Grep` to search for relevant variable names or function names
3. After fixing, `npm test` must be run for verification
4. If tests fail, enter a self-healing loop (maximum 5 times)
5. Output a fix summary: root cause, modified files, verification results
EOF
🔧 Tools Involved
| Tool |
Debugging Phase |
Function |
Read |
Locating |
Reads source files mentioned in the stack trace |
Grep |
Searching |
Searches for relevant functions or variables in the codebase |
Edit |
Fixing |
Modifies Bugs in the source code |
Bash |
Verifying |
Runs test commands to verify the fix |
Glob |
Discovering |
Finds related configuration/dependency files |
📝 Key Takeaways from this Issue
- Pasting the complete Stack Trace is the most efficient way to report Bugs
- Claude follows an automatic closed loop of Analysis → Location → Fix → Verification
- Chain errors require tracing the call chain from bottom up
- Using piping can directly transmit terminal errors to Claude
- Configuring a Bug Fixing Protocol in CLAUDE.md can significantly improve fix accuracy
🔗 References