Module 7: Subagents for Debugging, Regenerate vs Edit

Capsule overview

Modules 1 through 6 gave you a complete toolkit: you know how to calibrate trust, detect hallucinations, do professional code review, identify error patterns, and debug with Claude Code as a tool. That's professional competence. Now we enter mastery.

This module covers two topics that seem separate but are deeply connected: (1) using subagents as investigation tools before changing code, and (2) having a decision framework for the question you ask yourself 10 times a day: "do I regenerate this code or edit it manually?"

The connection is direct: you investigate with subagents, you understand the scope of the problem, and that understanding informs whether regenerating or editing is the best option. They're two sides of the same coin — deep understanding before acting.

Module Context

Where are we?

This is the first module of Phase 3: Mastery. You've completed the whole path from understanding the problem (Phase 1) to professional code review and debugging (Phase 2). Now you refine your judgment with advanced tools and frameworks.

Guide: Debugging & Code Review with Claude Code

Phase 1: Understand the Problem (Modules 1-3)
├── Module 1: Calibrated trust
├── Module 2: Mental models
└── Module 3: Detect hallucinations

Phase 2: Professional Code Review (Modules 4-6)
├── Module 4: Code review of AI output
├── Module 5: Common error patterns
└── Module 6: Debugging with Claude Code

Phase 3: Mastery (Modules 7-8)
├── Module 7: Subagents, Regenerate vs Edit  ← you are here
└── Module 8: Capstone Project

Why does this module open Phase 3?

Because both topics require everything that came before:

Subagents are only useful if you know what to ask (modules 1-3) and what to look for in the answers (modules 4-6). A developer who can't do code review can't evaluate what a subagent reports back.
Regenerate vs edit only makes sense if you know how to evaluate code quality (code review, modules 4-5) and diagnose problems (debugging, module 6). Without those skills, regenerating is a shot in the dark and editing is guesswork.

The key transition

Phase 2 (Module 6):    "I found a bug. I diagnose it and fix it."
Phase 3 (This module): "I found a problem. Do I investigate deeper?
                        Do I regenerate? Do I edit? A combination?"

The previous phase gave you tools for targeted problems. This phase gives you the judgment for complex problems where the answer isn't obvious.

The Two Topics and Their Connection

Topic 1: Subagents as investigation tools

Claude Code offers exploration and investigation capabilities that let you understand a codebase before making changes. You're not asking it to solve the problem — you're asking it to help you understand it.

Investigation with subagents:

  "Explain the authentication flow in this codebase"
  → Claude Code navigates files, follows imports, maps the flow
  → You get a mental map of the system
  → NOW you can decide what to change and how

  vs

  Without prior investigation:
  "Fix the authentication bug"
  → Claude Code guesses where the problem is
  → It may change the wrong thing, break dependencies
  → You introduce new bugs

The difference isn't the tool — it's the intent. The exploration subagent gives you understanding. Understanding gives you informed decisions.

Topic 2: The regenerate vs edit framework

This is the most frequent decision when you work with AI coding tools. Claude Code generated 100 lines of code and it has problems. What do you do?

The spectrum of options:

  Regenerate everything ←──────────────────────→ Edit one line
       │                                              │
       │    Regenerate    Regenerate     Edit         │
       │    entire        specific       several      │
       │    file          function       lines        │
       │                                              │
  "The approach   "The function  "The approach  "Just an
   is wrong        has the        is correct     off-by-one
   from the        wrong          but there      error"
   ground up"      approach       are details
                   but the rest   wrong"
                   is fine"

It's not binary. There's a full spectrum of options and each situation has its optimal answer.

The connection between the two topics

Typical flow when you face a complex problem:

1. INVESTIGATE (subagents)
   → "How does this part of the codebase work?"
   → "Which files depend on this module?"
   → "What's the impact of changing this function?"

2. EVALUATE (your judgment + modules 4-6)
   → "Is the approach fundamentally incorrect?"
   → "How much of the code needs to change?"
   → "What context would I lose if I regenerate?"

3. DECIDE (regenerate vs edit framework)
   → Regenerate: "The approach is incorrect"
   → Edit: "90% is fine, just details"
   → Mixed: "I regenerate this function, edit the rest"

4. EXECUTE (with precision)
   → If you regenerate: a prompt better informed by the investigation
   → If you edit: you know exactly what to change because you investigated

Without the investigation in step 1, the decision in step 3 is a gamble. With the investigation, it's an informed decision.

Professional Objective

By the end of this module you'll be able to:

✅ Use Claude Code's exploration capabilities to investigate a codebase before making changes
✅ Formulate investigation queries that produce actionable (not generic) information
✅ Know when to investigate with subagents vs doing the investigation manually
✅ Recognize clear signals that regenerating is the best option
✅ Recognize clear signals that editing manually is the best option
✅ Apply a decision framework that covers the full spectrum: from regenerating everything to editing one line
✅ Make informed and justified decisions across 5 realistic scenarios
✅ Combine investigation and decision into an efficient workflow

Module Progression

Module Map

Capsule	Topic	What you'll learn
02	Explore Subagents for Investigation	Use Claude Code's exploration before changing code
03	When to Regenerate Code	Clear signals, costs, and techniques to regenerate effectively
04	When to Edit Manually	Clear signals, efficient editing techniques with Claude Code
05	Decision Framework: Regenerate vs Edit	The complete framework with 5 realistic scenarios

Learning flow

Capsule 02: Investigate                → The understanding tool
     │
     ├───→ Capsule 03: When to Regenerate → One end of the spectrum
     │
     ├───→ Capsule 04: When to Edit       → The other end of the spectrum
     │
     └───→ Capsule 05: The Framework      → Integration + practical scenarios

You start with investigation (capsule 02) because it's the prerequisite for making good decisions — you need to understand the code before deciding what to do with it. Then you learn the signals to regenerate (capsule 03) and the signals to edit (capsule 04) as the two ends of the spectrum. Finally, the integrating framework (capsule 05) brings it all together into a decision flowchart with 5 scenarios where the answer isn't obvious.

Dependencies between capsules

Capsule 02 (Investigate) ─────┐
                               ├── Capsule 05 (Framework)
Capsule 03 (Regenerate)  ─────├── Integrates the 3 topics
                               │   + 5 practical scenarios
Capsule 04 (Edit)        ─────┘

Capsule 02 is a prerequisite for all of them — without knowing how to investigate, you can't make informed decisions. Capsules 03 and 04 are independent of each other but both are prerequisites for capsule 05.

Connection to the Project

How it connects to the capstone project (Module 8)

The capstone project will give you a codebase with multiple problems. Before you touch a single line, you need to:

Investigate with subagents: understand the structure, the dependencies, and the scope of the problems
Decide for each problem: do I regenerate, edit, or do a combination?
Execute with the right technique for each case

Module 8 is where everything you learn here gets tested in a real, complete scenario.

This module (7):
├── You learn to investigate with subagents
├── You learn the signals to regenerate
├── You learn the signals to edit
└── You practice the decision framework

Capstone project (8):
├── You investigate the codebase with subagents
├── You decide regenerate vs edit for each problem
├── You execute with the right technique
└── You document each decision with justification

Documenting the decisions is part of the project deliverable. "I fixed the code" isn't enough — you need to explain "I investigated the codebase, found that X was the problem, decided to regenerate/edit because Y, and the result was Z."

What You Need for This Module

Tools

✅ Claude Code CLI installed and working
✅ Python 3.10+ with FastAPI installed
✅ A real codebase or the practice codebase provided in the exercises
✅ A terminal to run commands
✅ A code editor (VS Code, Cursor, etc.)

Prior knowledge

✅ Modules 1-6 of this guide completed (or equivalent)
✅ Experience with Claude Code to generate and modify code
✅ Professional code review (modules 4-5)
✅ Debugging with Claude Code (module 6)
✅ Familiarity with Python and FastAPI

Quick install if you need it

pip install fastapi uvicorn pydantic sqlalchemy httpx

Boundaries: What This Module Does NOT Cover

❌ How to create custom subagents — We use the exploration capabilities Claude Code offers, we don't create new tools
❌ Automating decisions — The framework is for humans, not for automating the regenerate vs edit decision
❌ Code review — That was modules 4-5. Here you assume you already know how to evaluate code quality
❌ Debugging — That was module 6. Here you assume you already know how to diagnose problems
❌ Project management — We don't cover when to regenerate an entire project or change the tech stack
❌ Advanced refactoring — Deep refactoring patterns are out of scope. We focus on the decision, not on advanced transformation techniques

Before You Start: Self-Diagnosis

Assess your current level in the two areas of this module:

Investigation with subagents

How do you investigate a new codebase before making changes?

A. "I don't investigate — I open the file and start changing things"
   → This module will change your workflow completely

B. "I do grep/find to look for relevant files"
   → You're at the manual level — subagents speed you up 10x

C. "I ask Claude Code but without structure"
   → Formulating better queries will give you better results

D. "I investigate systematically before every change"
   → Validate that your queries are well formulated

E. "I combine investigation with subagents and manual work depending on the case"
   → You're at the advanced level — refine your judgment with the exercises

Regenerate vs edit decision

How do you decide whether to regenerate or edit problematic code?

A. "I always regenerate — it's easier"
   → You're losing hours per week and valuable customizations

B. "I always edit — I don't trust regenerating"
   → Sometimes regenerating is more efficient and produces better code

C. "It depends on my mood"
   → A framework will give you consistency and better results

D. "I have an intuition but I can't articulate it"
   → This module turns your intuition into a process

E. "I have clear criteria for each case"
   → Compare your criteria with the framework — you could refine it

What level you should have at the start

To get the most out of this module, you need:

Real prerequisites (not theoretical):
├── ✅ You've done at least 5 code reviews of AI-generated code
├── ✅ You've debugged at least 3 bugs with Claude Code's help
├── ✅ You can read a Python stack trace and understand what happened
├── ✅ You know at least 3 common error patterns in AI code
├── ✅ You've used Claude Code to generate code at least 20 times
└── ✅ You've faced the "do I regenerate or edit?" question at least once

If you don't meet these prerequisites:
└── Review modules 4-6 before continuing

The Cost of Not Having a Framework

To understand why this module matters, consider what happens without a decision framework:

Without a framework: the inefficient routine

Monday 9:00 — Claude Code generates an endpoint with 3 problems
  → "Hmm, I'll regenerate" (15 min)
  → The new code has 2 different problems
  → "I'll regenerate again" (15 min)
  → Now it works but you lost an hour

Monday 11:00 — An off-by-one in a filter
  → "I'll regenerate to be safe" (15 min)
  → The new code loses the logging you added yesterday
  → "I'll re-add the logging" (10 min)
  → A 30-second fix took 25 minutes

Monday 14:00 — Incorrect algorithmic approach
  → "I'll edit, I can surely fix it" (30 min of patches)
  → The code is a Frankenstein of patches over an incorrect design
  → "Ok, I'll regenerate from scratch" (15 min)
  → 45 minutes lost on useless edits

Monday's total: ~2 hours lost on sub-optimal decisions.

With a framework: the efficient routine

Monday 9:00 — Claude Code generates an endpoint with 3 problems
  → Framework: "3 changes, independent, no customizations → edit"
  → 10 minutes editing → done

Monday 11:00 — An off-by-one in a filter
  → Framework: "1 character, 95% correct → edit"
  → 30 seconds → done

Monday 14:00 — Incorrect algorithmic approach
  → Framework: "Incorrect approach → regenerate function"
  → Informed prompt → 12 minutes → done

Monday's total: ~25 minutes. The difference is ~1.5 hours per day, or ~7.5 hours per week.

The Tone of This Module: Senior-to-Senior

This module has a different tone than the previous ones. It's not introductory — it's a conversation between seniors:

Modules 1-3 (Phase 1): "Let me explain why this matters"
Modules 4-6 (Phase 2): "Here are the professional tools"
This module (Phase 3):  "In my experience, this works and this doesn't"

The approach is practical and experience-based:

No long definitions — you already know what a subagent is, what code review is, what debugging is
There's judgment and heuristics — "when I see X, I generally do Y, because Z"
There are nuances — "sometimes the right answer is to regenerate the function but edit the file"
There are concrete signals — not "regenerate when the code is bad" but "regenerate when the algorithmic approach is incorrect: it used bubble sort where you need a hash map lookup"

What makes this module different

A generic module:
├── "Regenerate: when the code has many errors"
├── "Edit: when the code is almost correct"
└── No nuances, no scenarios, no concrete signals

This module:
├── "Regenerate: it used an O(n²) for loop where you need an O(1) dict lookup"
│   └── Signal: the algorithmic approach is fundamentally incorrect
├── "Edit: the sort is fine but it's missing a reverse=True"
│   └── Signal: 95% of the code is correct, the fix is targeted
├── "Mixed: regenerate the calculation function, edit the imports"
│   └── Signal: part of the code is incorrect, part is fine
└── Each decision with justification and cost analysis

Evidence of Success

By the end of this module, you'll know you succeeded if:

✅ You can use Claude Code's exploration capabilities to investigate a codebase you don't know and get a mental map of the system
✅ You formulate investigation queries that produce useful and actionable information
✅ When facing a problem in AI-generated code, your first reaction is to investigate before acting
✅ You can articulate why regenerating is better than editing (or vice versa) with concrete signals
✅ You make the right decision in at least 4 of the 5 scenarios in capsule 05
✅ Your justification for each decision includes: observed signals, costs considered, and alternatives discarded

Indicators that you need to review

⚠️ You regenerate code without first investigating the scope of the problem — review capsule 02
⚠️ You regenerate whenever there's more than one error — review capsule 04 (sometimes editing is more efficient)
⚠️ You patch over patches when the approach is incorrect — review capsule 03
⚠️ You can't justify your regenerate vs edit decision — review capsule 05

Quick Preview: What You'll See in Each Capsule

So you know what to expect:

Capsule 02: You'll use Claude Code's exploration capabilities to investigate a FastAPI API codebase before making changes. You'll learn to formulate queries like "Explain the authentication flow in this project" and "Find all the places where user permissions are checked." You'll see the difference between investigating before acting vs acting blindly.
Capsule 03: You'll learn the 5 clear signals that regenerating is better than editing: incorrect algorithmic approach, wrong architecture, more than 50% of the code needs changes, the code doesn't meet the requirements, and the technical debt would be massive if patched. You'll also learn the cost of regenerating — you lose context, customizations, and you may get new problems.
Capsule 04: You'll learn the 5 signals that editing is better: 90% is correct, the fix is targeted and clear, the context would be lost, the issue is a known pattern, and regenerating would take longer. You'll practice efficient editing techniques with Claude Code's assistance.
Capsule 05: You'll apply the complete framework across 5 realistic scenarios where the answer isn't obvious. Each scenario has real code with real problems. You'll use the flowchart: assess damage → estimate edit time → estimate regeneration time → consider context loss → decide. The full spectrum: regenerate everything ↔ regenerate function ↔ edit multiple lines ↔ edit one line.

Summary

This module opens Phase 3: Mastery with two connected topics: investigation with subagents and the regenerate vs edit framework
Exploration subagents give you an understanding of the codebase before making changes — investigation, not solution
Regenerate vs edit is a spectrum, not a binary decision — from regenerating everything to editing one line
The two topics connect: you investigate → understand → decide → execute
The tone is senior-to-senior: experience-based judgment, concrete signals, real nuances
Everything you learn here applies directly to the capstone project in module 8
Both topics require everything learned in modules 1-6: without code review and debugging, you can't investigate effectively or decide with judgment

Additional Resources

Anthropic — Claude Code Best Practices - Official Claude Code documentation, including subagents
Refactoring Guru — When to Refactor - A professional framework for deciding when to refactor vs rewrite
Joel Spolsky — Things You Should Never Do - The classic article on why rewriting isn't always the answer
Martin Fowler — Refactoring - The reference book on when and how to change existing code
The Pragmatic Programmer — Refactoring - Decision principles for code changes

Next capsule: Explore Subagents for Investigation — the tool that transforms code investigation.

Debugging & Code Review with Claude Code — Module 7, Capsule 01 Claude Code Agentic Development Path — Guide #6 of 11

← PreviousExercise: Real Debugging Next →Explore Subagents for Investigation