Module 2: Agentic Research with the Explore Subagent

Capsule description

You're going to meet the tool that changes how you investigate codebases: Claude Code's Explore subagent. In the previous module you learned a systematic method for onboarding — the 5 questions, ordered exploration, documentation. That method works with Claude Code directly. But general Claude Code can read, write, and execute. That means every time you explore, there's a possibility — however remote — that a poorly worded prompt modifies something. Explore eliminates that possibility entirely.

Explore is a subagent that operates in read-only mode. It can't modify files, it can't run destructive commands, it can't write code. It can only read, search, and answer questions. That restriction sounds like a limitation, but it's exactly the opposite: it's a safety net that gives you total confidence to investigate. You can ask the most aggressive questions about a production codebase without risk. You can explore modules you don't understand without fear of breaking something. You can let the agent navigate freely because you know the worst it can do is read.

This module teaches you to master Explore as a dedicated investigation tool. You're going to learn when to use it (investigate) vs when to use general Claude Code (modify). You're going to experience the difference between text search (grep) and meaning search (semantic). And you're going to practice three exploration patterns — top-down, dependency-following, and feature-tracing — that turn vague questions into precise answers.

Module Context

Where are we?

This is Guide #8 of the Claude Code Agentic Development Path — "Refactoring & Legacy Code with Claude Code." You're in Module 2 of 8, within Phase 1: Understand Codebases.

What you built in Module 1:

Skill	What you learned
Onboarding method	The 5 initial questions: structure, entry points, data flow, patterns, tech debt
Claude Code as a reader	Using Claude Code to analyze existing code, not just to generate
Mental model	Building a mental map of the codebase in 3 levels of depth
Documentation	Producing a tangible onboarding doc that others can use
Validation	Making a small change to confirm your understanding

Module 1 gave you the method — what to ask and in what order. Module 2 gives you the specialized tool — an agent designed exclusively for investigation. It's like the difference between using a generic kitchen knife (works for everything) and a scalpel (designed for precision). Both cut, but the scalpel is optimized for a specific task.

Where are we headed?

All of Phase 1 has 3 modules, each adding a layer of depth in understanding codebases:

Phase 1: Understand Codebases (Modules 1-3)
+-- Module 1: Onboarding with AI — 5-10x Faster          [COMPLETED]
+-- Module 2: Agentic Research with the Explore Subagent  <-- YOU ARE HERE
+-- Module 3: Understand an Existing Architecture

Phase 2: Refactoring (Modules 4-6)
+-- Module 4: Coordinated Multi-File Refactoring
+-- Module 5: Framework and Language Migration
+-- Module 6: Context Management for Large Projects

Phase 3: Legacy and Project (Modules 7-8)
+-- Module 7: Modernize Legacy Code
+-- Module 8: Capstone Project — Full Migration

The progression within Phase 1:

Module 1: General onboarding method (completed)
    |     (5 questions, systematic exploration, document findings)
    v
Module 2: Specialized tool — Explore subagent (here)
    |     (read-only, semantic search, exploration patterns)
    v
Module 3: Deep architectural analysis
          (dependency maps, flow analysis, pattern identification)

After this module, Module 3 takes your exploration findings and turns them into visual and documented representations: dependency maps that show what depends on what, architecture diagrams that map layers and components, and flow analysis that traces the path of the data.

Why does this module matter?

The problem it solves

Module 1 taught you to explore with Claude Code directly. It works well. But it has an inherent tension: general Claude Code can do everything — read, write, execute, modify. When you ask it "explain to me how the payments module works," it may decide that to explain it to you it needs to run something, or modify something to test it. It's not common, but it's possible.

That possibility creates a subtle but real anxiety:

Developer thinking while exploring:
"I want to understand this codebase, but..."
- "What if I ask it something and it modifies a file without me noticing?"
- "What if it runs a destructive command while looking for information?"
- "I don't want to touch anything until I understand how it works"
- "Should I create a safety branch before exploring?"

Explore eliminates that anxiety completely. It's read-only by design — not by policy, not by convention, but by technical restriction. It can't modify anything even if it wanted to. You can hand it the keys to your production codebase and the worst it can do is read files.

The difference between investigating and modifying

In a developer's professional workflow, there are two distinct phases:

Phase	Goal	Ideal tool	Risk
Investigation	Understand what the code does, how it works, where the problems are	Explore subagent	Zero (read-only)
Modification	Change code, refactor, migrate, fix bugs	General Claude Code	Controlled (writes files)

Most developers mix both phases. They investigate a bit, modify a bit, investigate more, modify more. The result: changes made without complete understanding, bugs from not understanding side effects, and hours of debugging that would have been avoided with 15 more minutes of investigation.

Explore forces you to separate the phases. Investigate first — everything you need, without limit, without risk. When you have complete understanding, switch to general Claude Code and modify with confidence.

Read-only is a feature

Some developers see the read-only restriction as a limitation. "If it can't modify anything, what's it good for?" It's the same logic that asks "if a microscope can't operate, what's it good for?" The answer: because seeing with precision is a prerequisite for acting with precision.

Concrete benefits of read-only:

✅ Total confidence. You can explore without creating a safety branch.
✅ Anxiety-free exploration. There's no "what if something goes wrong."
✅ Investigation in production. You can use Explore directly on your production codebase.
✅ Safe delegation. You can let Explore navigate the codebase autonomously.
✅ Focus on understanding. Without the option to modify, all your attention is on understanding.

Semantic search: the differentiator

Explore doesn't just read files — it understands meaning. The difference from grep is fundamental:

# With grep: you search for text
grep -r "validate" src/
# Result: files that contain the word "validate"
# If the function is called check_params, you do NOT find it

# With Explore: you search for meaning
"Where are user inputs validated?"
# Result: finds check_params, sanitize_input, ensure_valid
# Because it understands that those functions VALIDATE even if they don't say "validate"

This difference is especially powerful in legacy codebases where the names don't always reflect the real function. Functions with historical names, cryptic abbreviations, or another team's conventions — Explore finds them by what they do, not by what they're called.

The Evolution of Agentic Research

From grep to semantic search

The way we search for code has evolved dramatically:

1990s: grep (literal text search)
    "Find this exact string in these files"

2000s: IDE search (search + basic context)
    "Find this string and show me the file"

2010s: ctags/LSP (symbol search)
    "Find where this function is defined/used"

2020s: GitHub Code Search (indexed search)
    "Find this pattern across millions of repos"

2025-26: AI-powered search (semantic search)
    "Find where AUTHENTICATION IS HANDLED 
     without knowing the function's name"

Each step was a leap in productivity. From searching for exact text to searching for meaning. Explore represents the latest step: questions in natural language, answers that understand context and intent.

How Claude Code spawns the Explore subagent

When you ask Claude Code to investigate something in Explore mode, internally the following happens:

Your prompt: "Use Explore to understand how the payment system works"

Claude Code:
1. Spawns a subagent in read-only mode
2. The subagent has access to the file system (read-only)
3. The subagent can:
   - Read files
   - Search in files (grep, find)
   - Navigate the directory structure
   - Analyze file content
4. The subagent CANNOT:
   - Write files
   - Run code
   - Install packages
   - Modify configuration
5. The subagent reports findings to Claude Code
6. Claude Code presents the results to you

You don't need to understand the internal details to use Explore effectively. What matters is the result: an investigation agent with all reading capabilities and no writing capabilities.

When to use Explore vs general Claude Code

The decision is simple:

If your goal is to UNDERSTAND -> use Explore
If your goal is to CHANGE     -> use general Claude Code

Practical rules:

Situation	Tool	Reason
Explore a new codebase	Explore	Pure investigation, zero risk
Understand how a feature works	Explore	Semantic search + read-only
Find where a function is used	Explore	Code navigation
Diagnose a bug (investigate)	Explore	Risk-free investigation
Fix a bug (modify)	General Claude Code	You need to write
Refactor code	General Claude Code	You need to write
Write tests	General Claude Code	You need to write
Evaluate tech debt	Explore	Read-only analysis
Document a module	Explore (investigate) + Claude Code (write)	A combination of both

The most productive pattern is: Explore first, general Claude Code later. Investigate everything you need with Explore, form your plan, and then execute with general Claude Code.

Self-diagnosis: Where Are You Today?

Before moving on, evaluate your current relationship with code search.

Quick 5-question test

1. When you need to find "where authentication is handled" in an unfamiliar codebase, what do you do?

(a) grep -r "auth" src/ and I review the results
(b) I look for files with names like auth.py, login.py, security.py
(c) I ask a colleague
(d) I ask Claude Code directly

2. How comfortable do you feel exploring a production codebase?

(a) Very comfortable — I'm not worried about breaking anything while exploring
(b) Somewhat uncomfortable — I always create a branch first
(c) Uncomfortable — I prefer someone to explain it to me
(d) I never do it directly — I only read documentation

3. Do you know the difference between text search and semantic search?

(a) Yes, and I use semantic search regularly
(b) I've heard of semantic search but I don't use it
(c) I'm not sure of the difference
(d) No, they're the same to me

4. When you explore a codebase, do you follow any exploration pattern?

(a) Yes — I start with entry points and follow the flow
(b) More or less — I have a general sequence
(c) No — I go from file to file as needed
(d) No — I open random files until I understand

5. Have you used AI tools specifically for code investigation (not writing)?

(a) Yes, regularly
(b) Occasionally
(c) I've tried it but not systematically
(d) No, I only use AI to generate code

Interpretation

Mostly (a): You have a good base. This module will give you a specialized tool that boosts what you already do.
Mostly (b): You have the right intuition. Explore will formalize your process and make it more efficient.
Mostly (c) or (d): You're going to experience a significant change. Explore will give you investigation superpowers you didn't have.

It doesn't matter where you are — Explore is a new tool for most developers, and mastering it is a direct competitive advantage.

Key Vocabulary

Terms you'll use throughout the module:

Term	Definition
Explore subagent	A Claude Code subagent that operates in read-only mode, designed specifically for codebase investigation
Read-only mode	A technical restriction that prevents any write operation — only file reading and navigation
Semantic search	Finding code by meaning and intent, not by exact text. "Where are inputs validated?" finds functions that validate even if they're called check_params
Text search	Searching for an exact string (grep, Ctrl+F). Only finds literal matches
Top-down exploration	An exploration pattern that starts with the entry point and goes down to the details, level by level
Dependency-following	An exploration pattern that follows imports and function calls from one module to another
Feature-tracing	An exploration pattern that traces a complete feature end-to-end — from the request to the response
Subagent	A subordinate agent that Claude Code spawns internally to perform specific tasks
Agentic research	Code investigation where an AI agent autonomously navigates the codebase looking for answers

These terms will be reinforced with practice in the following capsules. You don't need to memorize them now — you'll internalize them as you use them.

Professional Objective

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

Invoke and use the Explore subagent for read-only investigation of codebases, knowing exactly when it's the right tool and when you should use general Claude Code.
Apply semantic search to find code by meaning and intent — "where authentication is handled" — instead of relying exclusively on exact text search.
Distinguish semantic search vs grep and know when to use each: grep for known exact text, semantic search for concepts and functionalities.
Use 3 exploration patterns: top-down (from entry point to depth), dependency-following (following imports and calls between modules), and feature-tracing (tracing a feature end-to-end from request to response).
Combine multiple Explore queries to build a complete picture of a codebase, connecting partial findings into a coherent map.
Separate investigation from modification as a working principle: Explore first (understand), general Claude Code later (change).

The shift in perspective

You enter this module knowing how to explore with general Claude Code — a powerful but generic tool. You leave knowing that for investigation there's a specialized tool that eliminates risk, optimizes the search, and gives you total confidence. The central insight: the read-only restriction is a feature that makes you more productive, not less.

Why this matters for your career

Code investigation is a daily activity that most developers do inefficiently:

Junior: Needs to understand modules others wrote to contribute to the team
Mid-level: Investigates bugs in someone else's code, needs to find the root cause fast
Senior: Reviews others' PRs, evaluates the impact of changes in areas they don't master
Tech Lead: Evaluates architecture, identifies technical risks, makes informed decisions
Consultant: Investigates unfamiliar codebases constantly, speed is income

In every case, the quality of your investigation determines the quality of your decisions. Explore gives you high-quality investigation without risk.

Module Progression

Module Map

Capsule	Topic	What you'll learn
02	Explore Subagent — Read-Only Investigation	What Explore is, how to invoke it, when to use it. Read-only as a feature. Practical demos with the Claude Code CLI
03	Semantic Search vs Grep — Finding by Meaning	The difference between searching for text and searching for meaning. When to use grep vs Explore. Progressive examples
04	Exploration Patterns — Top-Down, Dependency-Following, Feature-Tracing	3 systematic patterns to investigate codebases. When to use each one. Combining them for a complete picture
05	Project: Codebase Exploration with Explore	Explore a medium codebase answering specific questions using only Explore. Document findings

Learning flow

Capsule 02: The Tool             Capsule 03: The Differentiator
(what Explore is, how to use it) -> (semantic vs grep, when each)
        |                                  |
        v                                  v
Capsule 04: The Patterns          Capsule 05: The Project
(3 ways to explore)          ->   (all together in a real codebase)

Each capsule builds on the previous one. Capsule 02 establishes the tool — what it is, how it works, why read-only is an advantage. Capsule 03 goes deeper into the key differentiator: semantic search. Capsule 04 gives you 3 systematic patterns to investigate. Capsule 05 integrates everything into a real project.

The module's narrative

First you're going to understand what Explore is and why its read-only restriction is a feature, not a limitation (capsule 02). You're going to see practical demos of Explore in action and compare its behavior with general Claude Code. Then you'll learn the difference between searching for text and searching for meaning — Explore's real power — with examples that demonstrate why grep isn't enough for serious investigation (capsule 03). With the tool and the differentiator clear, you'll learn 3 exploration patterns that turn vague questions into systematic investigations (capsule 04). Finally, you integrate everything into a project where you explore a real codebase using only Explore (capsule 05).

The progression is intentional: you can't apply patterns without understanding the tool, you can't appreciate the tool without understanding its differentiator (semantic search), and you can't consolidate without real practice.

Connection with the Project

Module mini-project: Codebase Exploration with Explore

In capsule 05 you're going to take a medium codebase and answer a series of specific questions using only Explore. You're not going to modify anything — just investigate. The questions are concrete and require real investigation:

"How does a login request flow from the endpoint to the database?"
"What dependencies does the payments module have?"
"Where are user inputs validated?"
"What design patterns are used and in what modules?"
"Where is the most critical tech debt?"

The focus isn't knowledge of the codebase — it's the efficiency and depth of the investigation.

What you'll deliver:

✅ Documented answers to each question with the exploration process
✅ Comparison: prompts used, findings, and how you connect the information
✅ Analysis of when you used semantic search vs when you would have needed grep
✅ Reflection on which exploration pattern you used for each question

Connection with the guide's capstone project (Module 8)

Module 8 is a Full Migration of a Legacy Project. The investigation with Explore that you learn here is the base of the analysis phase of that migration. Before migrating, you need to understand: what dependencies there are, how the data flows, where the risks are. Explore is your tool for that phase.

Module 1: Onboarding -> understand the codebase (method)     -+
Module 2: Explore -> investigate in depth (tool)              |
Module 3: Architecture -> map dependencies and patterns       | Feed the
Module 4: Refactoring -> coordinated changes                 +- Capstone
Module 5: Migration -> framework change                       | Project
Module 6: Context -> handle large projects                    | (Module 8)
Module 7: Legacy -> modernize old code                       -+

Connection with Module 3

The direct connection is with Module 3 (Understand an Existing Architecture). The findings you get with Explore in this module become formal representations in Module 3:

What you produce with Explore (M2)	What you produce in Architecture (M3)
"The payments module depends on users and products"	A formal dependency map with graphs
"A login request passes through auth -> users -> db"	A flow diagram with mermaid
"The project uses service layer + repository pattern"	An architecture diagram by layers
"There's a circular dependency between orders and inventory"	Anti-pattern documentation

Explore gives you the findings. Architecture gives you the way to represent them.

Limits: What We WON'T Do

To stay focused:

❌ You won't modify code. This module is 100% investigation. Modifying comes in modules 4-7.
❌ You won't generate dependency maps or formal diagrams. That's Module 3. Here you investigate; in Module 3 you represent visually.
❌ You won't configure Explore in an advanced way. You use Explore with its default configuration. Advanced customization is out of scope.
❌ You won't work with extremely large codebases (100K+ lines). Context management comes in Module 6.
❌ You won't compare Explore with external tools (GitHub Copilot search, Sourcegraph). The focus is mastering Explore, not evaluating alternatives.
❌ You won't cover searching for non-code files (images, binary configs). The scope is Python code.

What we do cover in depth:

✅ The Explore subagent as a read-only investigation tool
✅ Semantic search vs grep — when to use each
✅ 3 exploration patterns: top-down, dependency-following, feature-tracing
✅ Combining multiple queries for a complete picture
✅ Explore vs general Claude Code: when to use each
✅ Investigate before you modify as a professional principle

Evidence of Success

By the end of the module, these are the measurable criteria that show you completed it successfully:

Mandatory criteria:

Criterion	How to verify it
You can invoke Explore and use it to investigate a codebase	You open an unfamiliar project and answer 3 questions using only Explore
You understand the difference between semantic search and grep	You can give an example where grep fails and Explore finds the result
You apply the 3 exploration patterns	You can choose the right pattern for a given question and justify your choice
You combine findings from multiple queries	Your investigation connects information from different parts of the codebase into a coherent narrative
You separate investigation from modification	Your workflow is: Explore first (understand), general Claude Code later (change)

Excellence criteria (optional):

✅ Your investigation discovers something that wasn't obvious from the project's documentation
✅ You can explain the codebase to another developer based only on what you found with Explore
✅ You identify an exploration pattern that's more natural for your way of thinking and you articulate it

What success looks like in practice

Before this module:

Question: "Where are inputs validated?"
-> grep -r "valid" src/ -> 47 results -> review one by one
-> 20 minutes later: you found 3 functions but you're not sure
   if there are more. check_params() didn't show up because it doesn't have "valid" in the name.

After this module:

Question: "Where are inputs validated?"
-> Explore: "Where are user inputs validated in this project?"
-> 30 seconds: Explore identifies check_params(), sanitize_input(),
   ensure_valid(), and the global validation middleware in api/deps.py
-> Complete picture, no matter what the functions are called

The difference isn't just speed — it's completeness. Explore finds what grep can't because it searches by meaning, not by text.

The final validation question:

If someone gives you a 10K-line codebase with specific questions — "how does it handle authentication?", "what dependencies does module X have?", "where are payments processed?" — can you answer them all using Explore in under 30 minutes?

If the answer is yes, you completed this module successfully.

Module Prerequisites

Required knowledge:

✅ Module 1 completed: the method of the 5 questions and systematic exploration
✅ Basic Claude Code: knowing how to invoke Claude Code, write prompts, work in the terminal
✅ Intermediate Python: reading Python code without difficulty
✅ Basic Git: cloning repos, navigating between files

You don't need:

❌ Previous experience with Explore — it's taught from scratch
❌ Knowledge of semantic search — it's explained in capsule 03
❌ A project of your own — you'll use open-source projects
❌ Experience with static analysis tools

Technical setup:

Tool	What for
Claude Code installed and updated	The Explore subagent requires a recent version
Terminal with Git access	Cloning repos to explore
Internet connection	Cloning open-source projects
Text editor	Documenting findings

Quick setup check

# Check Claude Code
claude --version
# Expected: recent version (2025+)

# Check that you can invoke Explore
claude "Use Explore to list the Python files in the current directory"
# Expected: a response with a list of files

# Check Git
git --version
# Expected: git 2.0+

# Clone a test project
git clone --depth 1 https://github.com/encode/httpx /tmp/httpx-explore-test
# Expected: clones without errors

If something doesn't work, review your Claude Code installation before continuing.

The Core Principle

Investigate before you modify

This principle from Module 1 is deepened here. Not just "investigate before you modify" — now you have the right tool to do it:

Explore is your first step in any unfamiliar codebase. Investigate without risk, understand in depth, and only then modify with confidence.

The professional workflow this module establishes:

Step 1: Explore (investigate)
    - What does this codebase do?
    - How does the data flow?
    - Where are the risks?
    
Step 2: Analyze (think)
    - What do I need to change?
    - What can the change break?
    - What's the safest strategy?
    
Step 3: General Claude Code (modify)
    - Execute the change with complete understanding
    - Verify with tests
    - Document

Phase 1 (Explore) is where the game is won or lost. A superficial investigation produces dangerous changes. A deep investigation produces safe changes.

Specific questions produce useful answers

Module 1 established that "exploring without purpose" doesn't work. This module reinforces the principle with Explore:

Bad:   "Explore, look at this codebase"
       -> Vague result, no focus, scattered information

Good:  "Explore, how does a request from /api/users 
        flow from the endpoint to the response?"
       -> Precise result: handler -> service -> repository -> DB -> response

Each Explore session should start with a specific question. The question defines the quality of the investigation.

What Comes After This Module

Module 3: Understand an Existing Architecture

The direct transition: "You can already investigate any aspect of a codebase with Explore — finding functions, tracing flows, identifying dependencies. Now learn to turn those findings into formal representations you can share with your team."

Module 3 teaches you to produce:

Dependency maps: Graphs that show which module depends on which. Generated by Claude Code as mermaid or ASCII.
Flow diagrams: Diagrams that trace the path of a request from the entry point to the response.
Architecture diagrams: Representations of the system's layers, components, and interfaces.
Pattern identification: Formal recognition of MVC, service layer, repository pattern, and others.
Anti-pattern detection: Identification of circular dependencies, god objects, spaghetti code.

The progression of all of Phase 1:

Module 1: "I know how to explore a codebase" (method)
    |
    v
Module 2: "I can investigate in depth safely" (tool)
    |
    v
Module 3: "I can visualize and communicate the architecture" (representation)

Each module gives you a deeper level. By the end of Phase 1, you don't just understand a codebase — you can create a complete, verifiable, and shareable map.

Estimated Time Distribution

Capsule	Estimated time	Main activity
01 (this one)	10-15 min	Reading: module objectives and context
02	20-25 min	Reading + demos: the Explore subagent in action
03	20-25 min	Reading + exercises: semantic search vs grep
04	20-25 min	Reading + exercises: 3 exploration patterns
05	30-45 min	Project: codebase exploration with Explore
Total	~1.75-2.25 hrs

The module is designed to be completed in one session. If you need to split it, the natural pause point is after capsule 03 (semantic search vs grep).

Summary

✅ This module introduces the Explore subagent — Claude Code's read-only investigation tool
✅ Read-only is a feature, not a limitation: it gives total confidence to investigate without risk
✅ Semantic search finds code by meaning, not by text — Explore's key differentiator
✅ 3 exploration patterns: top-down, dependency-following, feature-tracing
✅ The reinforced principle: investigate before you modify, with the right tool
✅ Explore first (understand), general Claude Code later (change)
✅ The module project: explore a codebase answering specific questions using only Explore
✅ Connects directly with Module 3: the Explore findings become visual architecture

Additional Resources

Claude Code Documentation — Explore Subagent — Official documentation about the Explore subagent and its capabilities.
Agentic Research Patterns — Anthropic — How AI agents perform autonomous codebase investigation.
Working Effectively with Legacy Code — Michael Feathers — The principle of understanding before modifying applied to legacy code.
Semantic Code Search — GitHub Blog — How code search evolved from text to semantic.
The Art of Reading Code — Felienne Hermans — Techniques for reading and understanding others' code, complementary to the AI approach.
Code as a Crime Scene — Adam Tornhill — Investigating codebases using historical data and behavior patterns.

Next capsule: Explore Subagent — Read-Only Investigation — what it is, how to invoke it, and why read-only mode makes you more productive.

Module 2, Capsule 01 — Refactoring & Legacy Code with Claude Code Guide

← PreviousModule Project: Onboarding to an Open-Source Codebase Next →Explore Subagent — Read-Only Investigation