Module 6: Debugging with Claude Code
Module 6: Debugging with Claude Code
Module 6: Debugging with Claude Code
Capsule overview
Modules 4 and 5 taught you to find problems through static inspection — reading code, identifying error patterns, applying checklists. But there's a category of problems you can't find by reading alone: the ones that appear when the code runs. A TypeError that only occurs with a certain input. An endpoint that returns incorrect data but only when the database has records with a certain format. A timeout that appears only under load.
Those problems require debugging — a process different from code review. And Claude Code can be an extremely useful tool in that process, but only if you understand its role correctly. In this module you're going to learn to use Claude Code as a debugging tool: pass it logs, stack traces, and runtime errors to get diagnostic hypotheses. And most importantly: you're going to learn to evaluate those hypotheses, not accept them blindly.
Module context
Where are we?
This is the last module of Phase 2 (Professional Code Review). In module 4 you built a professional code review checklist. In module 5 you learned to recognize common error patterns in AI-generated code. Now you close the phase with the most practical skill of all: diagnosing and resolving problems that show up at runtime.
Where are we headed?
After this module, you enter Phase 3: Mastery. Module 7 will give you advanced tools (subagents for investigation and the regenerate-vs-edit framework). Module 8 is the capstone project where you'll apply code review, debugging, and all the techniques you've learned to a codebase with real problems.
The key transition
Code review finds potential problems. Debugging solves real problems. The developer who masters both has a complete toolkit.
Professional objective
By the end of this module you'll be able to:
- ✅ Use Claude Code to analyze application logs and get actionable diagnoses
- ✅ Interpret Python stack traces with help from Claude Code and verify the diagnosis
- ✅ Follow a systematic debugging process: reproduce → isolate → diagnose → fix → verify
- ✅ Identify when Claude Code helps with debugging and when you need manual tools
- ✅ Debug a FastAPI application with multiple bugs using the systematic process
The Fundamental Distinction: Tool vs Oracle
Before getting into techniques, you need to internalize an idea that defines this entire module:
Claude Code is a debugging tool, not a debugging oracle.
What does this mean in practice?
Claude Code as an oracle (incorrect)
You: "My app doesn't work, fix it"
Claude Code: [generates a fix]
You: [apply the fix without understanding what was happening]
This fails because:
- Claude Code doesn't have access to your application's runtime
- It can't see the state of memory, the variables, the connections
- It can't reproduce the error — it can only read static code
- If you give it incomplete information, it'll give you an incomplete (or incorrect) diagnosis
Claude Code as a tool (correct)
You: [reproduce the error and capture the log/stack trace]
You: "Here's the stack trace. What does it suggest about the cause?"
Claude Code: [analyzes and gives a hypothesis]
You: [verify the hypothesis against the code and the real behavior]
You: [apply the fix AND verify that it resolves the problem]
The difference is that you control the process. Claude Code gives you hypotheses based on the information you provide. You verify, you decide, you confirm.
The impact on your day-to-day
This distinction isn't philosophical — it has immediate practical consequences:
| Approach | Average time | Success rate | Risk |
|---|---|---|---|
| Paste error → accept fix | 2 min | ~40% | High: can create new bugs |
| Complete process with Claude Code | 10-20 min | ~85% | Low: you verify before applying |
| Manual without AI | 20-60 min | ~90% | Low: but inefficient |
The sweet spot is the middle: you use Claude Code to accelerate the diagnosis, but you keep control of the process and the verification. That gives you AI's speed with the precision of a professional process.
Code Review vs Debugging: Two Complementary Skills
It's important to understand the difference between what you did in modules 4-5 and what you'll do in this module:
Code Review (Modules 4-5): Static inspection
Input: Source code
Process: Read → Identify patterns → Evaluate risk
Output: A list of potential problems
When: BEFORE the code runs
In code review, you look at the code and say: "This SQL query uses string concatenation — it could have SQL injection." You don't need to run anything. The problem is visible in the code.
Debugging (This module): Runtime diagnosis
Input: Error + Logs + Stack trace + Code
Process: Reproduce → Isolate → Diagnose → Fix → Verify
Output: A bug fixed and verified
When: AFTER the code fails at execution
In debugging, the code already ran and something failed. You have a concrete error: "The endpoint returns 500 when the user sends an empty list." You need to find why it fails and fix it.
How they complement each other
The best developers do both:
- Code review before merge — finds problems before they reach production
- Debugging when something fails — solves the problems code review didn't catch
Code review can't detect everything (especially subtle logic bugs and timing problems). Debugging shouldn't be your only defense (it's more expensive to fix bugs in production than to prevent them in review). Together, they form your complete safety net.
The Systematic Debugging Process
The backbone of this module is a 5-step process you'll apply to every bug:
┌─────────────┐ ┌─────────────┐ ┌──────────────┐ ┌──────────┐ ┌──────────────┐
│ REPRODUCE │ ──→ │ ISOLATE │ ──→ │ DIAGNOSE │ ──→ │ FIX │ ──→ │ VERIFY │
│ │ │ │ │ │ │ │ │ │
│ "Can I make │ │ "What's the │ │ "Why does │ │ "What's │ │ "Does the │
│ it fail │ │ minimum │ │ it fail?" │ │ the │ │ fix solve │
│ again?" │ │ input that │ │ │ │ correct │ │ the original│
│ │ │ triggers │ │ 🤖 Claude │ │ solution│ │ problem?" │
│ │ │ the error?"│ │ Code helps │ │ ?" │ │ │
└─────────────┘ └─────────────┘ │ here │ └──────────┘ └──────────────┘
└──────────────┘
Claude Code is most useful in step 3 (diagnose), but it doesn't replace the other 4 steps. Many developers jump straight to "paste the error into Claude Code and apply what it says" — that's jumping from step 1 to step 4 without passing through 2, 3, or 5. And it's the recipe for fixes that don't work or that create new bugs.
Why each step matters
Reproduce: Without reproduction, you can't confirm your fix works. "I was told there's a bug" isn't enough — you need to see it yourself under specific conditions.
Isolate: An error that occurs with a 15-field request could be caused by any of those fields. Reducing to the minimum input tells you exactly where the problem is. This turns a mystery into a concrete clue.
Diagnose: This is where Claude Code shines. With a minimum input that causes the error and the stack trace, you can pass it precise data and get a high-quality hypothesis. Without steps 1 and 2, the diagnosis is generic and imprecise.
Fix: Not every fix is the same. A try/except that silences the error is a patch. Fixing the validation in the Pydantic schema is a root-cause fix. Claude Code sometimes suggests patches — you must evaluate whether the fix is a root-cause fix.
Verify: The most-skipped step and the most important. You verify that: (a) the original bug no longer occurs, (b) the functionality that did work still works, (c) related edge cases don't cause new bugs.
Where Claude Code Helps in Each Step
Not all steps benefit equally from Claude Code:
| Step | Usefulness of Claude Code | Why |
|---|---|---|
| Reproduce | Low | Claude Code can't run your app or make requests |
| Isolate | Medium | It can suggest which variables to test, but you run them |
| Diagnose | High | Excellent at analyzing stack traces, logs, and code |
| Fix | High | It can generate the fix code based on the diagnosis |
| Verify | Medium | It can suggest edge cases to test, but you run them |
The key is that Claude Code is most useful in the analytical steps (diagnose, suggest fixes) and least useful in the executive steps (reproduce, verify) — because those require interaction with your real application.
Module progression
Module map
| Capsule | Topic | What you'll learn |
|---|---|---|
| 02 | Log Analysis with Claude Code | Pass logs to Claude Code, give context, evaluate the diagnosis |
| 03 | Runtime Errors and Stack Traces | Interpret Python stack traces with help from Claude Code |
| 04 | Systematic Debugging | The complete process: reproduce → isolate → diagnose → fix → verify |
| 05 | When Claude Code Doesn't Help | Real limitations and when to use manual tools |
| 06 | Exercise: Real Debugging | Debug a FastAPI application with 4-5 real bugs |
Learning flow
You start with the most common and most useful skill: log analysis (capsule 02). You learn what logs to copy, how much context to give, and how to evaluate Claude Code's response. Then you move on to stack traces (capsule 03) — the second most valuable source of debugging information. With those two skills, you learn the complete systematic process (capsule 04) that integrates both techniques into a disciplined flow. Capsule 05 is the most important conceptually: when Claude Code doesn't help — the real limitations that keep you from wasting time. And you close with a real debugging exercise (capsule 06) where you apply it all to an application with bugs.
Difficulty progression
Capsule 02: Log Analysis → Individual skill, guided examples
Capsule 03: Stack Traces → Individual skill, more variety of errors
Capsule 04: Systematic Process → Integration of skills into a process
Capsule 05: Limitations → Judgment: knowing when NOT to use Claude Code
Capsule 06: Real Exercise → Complete application with multiple bugs
Each capsule builds on the previous one. Log analysis and stack traces are the inputs to the systematic process. The systematic process is the framework where you decide whether Claude Code helps or not. And the final exercise requires it all together.
Connection to the Project
This module's exercise
In capsule 06 you'll receive a FastAPI application with 5 bugs of different types: a runtime error, a logic error, an unhandled edge case, a silent data bug, and an incomplete validation. You'll have to diagnose each one using the systematic process and document each step.
Connection to the capstone project (Module 8)
The capstone project includes bugs that require real debugging — not just code review. The process you learn here (reproduce → isolate → diagnose → fix → verify) is exactly what you'll follow in the debugging phase of the final project. The difference is scale: here you debug 5 isolated bugs; in module 8, you debug bugs within a larger codebase where the problems can interact with each other.
The documentation of the debugging process is part of the capstone project's delivery. The format you practice in capsule 06 (reproduce → isolate → diagnose → fix → verify, documented) is the format you'll use in module 8.
What You Need for This Module
Tools
- ✅ Claude Code CLI installed and working
- ✅ Python 3.10+ with FastAPI installed
- ✅ A terminal where you can run FastAPI applications
- ✅ A code editor (to read code while you debug)
- ✅
curlor similar to make HTTP requests (or Postman/httpie)
Prior knowledge
- ✅ Modules 1-5 of this guide (or equivalent experience)
- ✅ Basics of Python and FastAPI (routes, Pydantic models, responses)
- ✅ Comfort reading terminal logs
- ✅ A basic concept of what a stack trace is (this module teaches you to read them in detail)
Quick installation if you need it
pip install fastapi uvicorn pydantic httpxLimits: What this module does NOT cover
- ❌ Frontend or JavaScript debugging — The module focuses on Python/FastAPI. The principles apply to other languages, but the examples are Python.
- ❌ Advanced configuration of debugging tools — We don't do a tutorial on pdb, IDE debuggers, or profilers. We mention when to use them, but the module focuses on the process and on using Claude Code.
- ❌ Infrastructure debugging — Docker, networking, or deployment problems are out of scope. We focus on application code bugs.
- ❌ Testing — Testing is guide #8 of the path. Here we mention tests as a verification tool (step 5), but we don't teach how to write tests.
- ❌ Debugging in production — Techniques like feature flags, canary deploys, and advanced observability are out of scope. We focus on debugging in the development environment.
Signs of success
By the end of this module, you'll know you succeeded if:
- ✅ You can pass logs to Claude Code and get a useful diagnosis (not just paste the error, but give enough context)
- ✅ You can read a Python stack trace and explain what happened, with or without help from Claude Code
- ✅ You follow the reproduce → isolate → diagnose → fix → verify process naturally, without skipping steps
- ✅ You know when to stop using Claude Code and open pdb or a profiler
- ✅ You successfully debugged the 5 bugs in the exercise application (capsule 06)
- ✅ You documented your debugging process for each bug
Indicators that you need to review
- ⚠️ You copy and paste errors into Claude Code without including context — review capsule 02
- ⚠️ You can't explain a stack trace without help from AI — review capsule 03
- ⚠️ You apply fixes without verifying — review step 5 in capsule 04
- ⚠️ You spend more than 30 minutes with Claude Code without resolving a bug — review capsule 05
Debugging in the AI Era: What Changed and What Didn't
What changed
Before AI, debugging was 100% manual: you read the error, search on Stack Overflow, set breakpoints, read documentation, test hypotheses one by one. The bottleneck was the diagnosis time — understanding what was happening could take longer than fixing it.
With Claude Code, the diagnosis accelerates dramatically for certain types of errors:
- ✅ Stack traces of known errors — Claude Code knows the patterns of hundreds of Python exceptions and can explain them in seconds
- ✅ Log analysis — Claude Code can process 200 lines of logs and find the anomaly faster than a human reading line by line
- ✅ Library errors — "What does
sqlalchemy.exc.IntegrityErrormean?" Claude Code knows the answer immediately - ✅ Suggesting fixes — Once diagnosed, generating the fix code is fast
What did NOT change
- ❌ You need to understand your application — Claude Code doesn't know your business rules or your architecture
- ❌ You need to reproduce the bug — Without reproduction, neither you nor Claude Code can confirm the fix
- ❌ You need to verify — An AI-generated fix can create new bugs if you don't verify it
- ❌ Complex bugs require manual tools — Race conditions, memory leaks, performance issues need pdb, profilers, and observability tools
The effective developer combines both
The most effective developer in 2026 isn't the one who uses the most AI nor the one who refuses to use it. It's the one who knows when to use each tool:
Error with a clear stack trace → Claude Code first
Intermittent bug with no errors → Logging + manual debugging
Performance issue → Profiler first, Claude Code for the fix
Business logic bug → Understand the requirement, manual debugging
This module gives you the judgment to make that decision quickly.
Anatomy of a Bug: The Types You'll Encounter
In this module you'll work with 4 categories of bugs, each requiring a different approach:
Runtime Errors (crash)
The server returns 500 with a stack trace. It's the easiest type to debug because Python tells you exactly where it failed.
TypeError: 'NoneType' object is not subscriptable
→ Something is None when you expected a dict or list
Claude Code helps: A lot. The stack trace is textual information that Claude Code processes excellently.
Logic Errors (incorrect result)
The code doesn't crash — it returns 200. But the data is incorrect. The discount calculation gives 55% when it should give 20%. The filter includes records it should exclude.
GET /api/stats → {"completion_rate": -15.0}
→ The completion rate shouldn't be negative
Claude Code helps: Partially. It can analyze the code and find the incorrect logic, but it needs you to tell it what the expected result is vs the one obtained.
Edge Case Errors (fails with specific inputs)
The code works with "normal" inputs but fails with valid but unexpected inputs: empty lists, strings with special characters, dates in the past, None values where they aren't expected.
GET /api/tasks/search?q=test → 200 OK
GET /api/tasks/search?q=test with a task with no description → 500
Claude Code helps: A lot, especially if you show it an input that works and one that fails. The comparison lets it isolate the problem.
Silent Data Corruption (incorrect data with no error)
The most dangerous. The code doesn't crash or return errors. But it silently corrupts data: fields that should update don't update, values that should be None become empty strings, IDs that get reused.
PATCH /api/tasks/1 with {"assignee_id": null} → 200 OK
GET /api/tasks/1 → assignee_id is still the previous one
Claude Code helps: A little. These bugs don't produce stack traces or errors in the logs. You need to inspect the state of the data before and after each operation.
Summary
- This module closes Phase 2 with the most practical skill: debugging with AI assistance
- Claude Code is a debugging tool, not an oracle — you give it data, it gives you hypotheses, you verify
- The systematic process (reproduce → isolate → diagnose → fix → verify) is the backbone of the module
- Log analysis is the most common and most useful use case of Claude Code for debugging
- Stack traces are your second ally: learning to read them gives you independence
- Knowing when Claude Code doesn't help is as important as knowing when it does
- There are 4 types of bugs (runtime, logic, edge case, silent corruption) and each requires a different approach
- Everything you learn here applies directly to the capstone project in module 8
- Documenting the process is as important as the fix — it's evidence of professional thinking
Additional resources
- Python Debugging — Real Python - A complete Python debugging tutorial with pdb
- FastAPI — Debugging Tips - Official FastAPI documentation on debugging
- Python Logging HOWTO - Python's official guide to effective logging
- Anthropic — Claude Code Best Practices - Official Claude Code documentation
- The Debugging Mindset — ACM Queue - A classic article on the debugging mindset
- Nine Rules for Debugging — David Agans - A professional debugging framework applicable to any technology
Quick Preview: What You'll See in Each Capsule
So you know what to expect:
-
Capsule 02: You'll copy 20+ lines of logs from a failing FastAPI application and pass them to Claude Code with a structured prompt. You'll see the difference between giving context and not giving it. You'll learn to evaluate whether Claude Code's diagnosis is correct before acting.
-
Capsule 03: You'll read Python stack traces — starting with the simple ones (KeyError, TypeError) up to the chained ones (an exception during the handling of another exception). You'll practice reading them without AI first, and then you'll use Claude Code for the complex ones.
-
Capsule 04: You'll go through the complete 5-step process with a realistic bug: duplicate tasks in an endpoint with filters. You'll see how each step reduces the uncertainty until you reach the correct fix.
-
Capsule 05: You'll see 5 categories of bugs where Claude Code CANNOT help: race conditions, business logic, performance, in-memory state, and environment configuration. For each one, you'll learn the correct manual tool.
-
Capsule 06: You'll receive a complete FastAPI application (TaskFlow API) with 5 planted bugs. You'll debug each one following the systematic process and document your work.
Next capsule: Log Analysis with Claude Code — the most useful AI debugging skill.
Debugging & Code Review with Claude Code — Module 6, Capsule 01 Claude Code Agentic Development Path — Guide #6 of 11