Module 2: Agentic Research with the Explore Subagent

Module Project: Codebase Exploration with Explore

Project description

This project tests everything you learned in the module: using the Explore subagent to investigate a real codebase by answering specific questions. You're not going to modify anything — just investigate, analyze, and document. It's the proof that you can use Explore as a professional investigation tool.

The difference from the Module 1 project (Onboarding) is that now you have Explore as a dedicated tool and three exploration patterns (top-down, dependency-following, feature-tracing). Module 1 taught you to do general onboarding. This project asks you for deep, directed investigation.

The project simulates a real scenario: you're assigned to a team with an existing codebase and your tech lead gives you 5 specific questions they need answered before planning the next sprint. You have to answer them using Explore, document your findings, and deliver a report that any team member could read and understand.

This project connects directly with Module 3 (Understand an Existing Architecture), where your exploration findings turn into formal dependency maps and flow diagrams.

Project Objective

Demonstrate mastery of the Explore subagent by answering specific questions about a real codebase using the three exploration patterns.

By completing this project:

✅ You'll have used Explore to investigate a 5K+ line codebase
✅ You'll have applied the three patterns (top-down, dependency-following, feature-tracing)
✅ You'll have used semantic search to find code by meaning
✅ You'll have produced a professional investigation report
✅ You'll have measured Explore's efficiency vs manual investigation

Technical Specifications

Suggested Codebase

Use one of these open-source Python projects (they all have the right size and complexity):

Project	Lines	Description	Why it's good for this project
httpx	~15K	Async HTTP client	Multiple layers, async patterns, middleware
typer	~8K	CLI framework	Clear architecture, dependency injection
rich	~20K	Terminal formatting	Many components, rendering pipeline
fastapi	~12K	Web framework	Routing, middleware, dependency injection

Recommendation: httpx or typer. Both have good documentation but enough complexity for the investigation to be interesting.

Setup

# Clone the chosen project
git clone https://github.com/encode/httpx.git
cd httpx

# Open Claude Code in the project
claude

# Verify that Explore works
> "Use Explore to describe the structure of this project"

Tools needed

Claude Code with access to the Explore subagent
Terminal / text editor to document
Git to clone the project

The 5 Investigation Questions

Your tech lead needs these 5 questions answered. Each one requires a different exploration pattern:

Question 1: General Structure (Top-Down)

"What's the project's general architecture? Describe the main layers, the key components, and how the files are organized."

Answer requirements:

First-level directory structure with the purpose of each folder
Identification of layers (if they exist): API, logic, data, utils
Main components with 1 descriptive sentence each
A simple diagram (ASCII or mermaid) of the architecture

Pattern: Top-Down, levels 1-2

Question 2: Main Flow (Feature-Tracing)

"How does the project's main flow work? Trace the path from when a user starts an action to when they get a result."

For httpx: "How is an HTTP request executed from httpx.get(url) to receiving the response?" For typer: "How is a CLI command processed from when the user types it to when it runs?"

Answer requirements:

A complete step-by-step trace: file → function → what it does
The data that flows at each step (input → output)
At least 5 steps in the trace
Identification of where data transformations happen

Pattern: Feature-Tracing

Question 3: Dependency System (Dependency-Following)

"What are the 3 most connected modules in the project? For each one, what does it depend on and who depends on it?"

Answer requirements:

Identification of the 3 modules with the most connections
For each one: outgoing dependencies (imports) and incoming dependents (who imports it)
Warning signs: are there circular dependencies? god object modules?
A mini dependency map (text or mermaid)

Pattern: Dependency-Following

Question 4: Semantic Search (Semantic vs Grep)

"Find where error handling is implemented in the project. Compare what you find with grep vs what you find with Explore."

Answer requirements:

The result of grep -rn "error\|exception\|raise" src/ (count of results)
The result of Explore: "Where and how are errors handled in this project?"
Comparison: what did Explore find that grep didn't find
At least 2 examples of code that handles errors without using the words "error" or "exception"

Pattern: Semantic search + grep combined

Question 5: Open Investigation

"Find something interesting, unexpected, or concerning in the codebase that wasn't asked about above."

Answer requirements:

An original finding (don't repeat previous answers)
An explanation of why it's interesting, unexpected, or concerning
Evidence (specific files and functions)
An action recommendation (if applicable)

Pattern: Any or a combination

Report Format

Your deliverable is a markdown document with this structure:

# Investigation Report: [Project Name]

**Investigator:** [Your name]
**Date:** [Date]
**Codebase:** [repo URL]
**Tool:** Claude Code with the Explore subagent

---

## Question 1: General Structure

### Answer
[Your answer with a diagram]

### Method
[What pattern you used, what prompts you gave Explore]

### Prompts used

[The exact prompts you used]


---

## Question 2: Main Flow

### Answer
[Complete step-by-step trace]

### Method
[Feature-tracing, prompts used]

---

[... Questions 3-5 ...]

---

## Metrics

| Metric | Value |
|---------|-------|
| Total investigation time | [X minutes] |
| Number of prompts to Explore | [X] |
| Number of grep commands | [X] |
| Manual time estimate | [X hours] |
| Acceleration factor | [X hrs manual / X min with Explore] |

---

## Reflection

[2-3 paragraphs about what you learned about the codebase
and about the investigation process with Explore]

Validations and Process

Before you start

Project cloned and accessible
Claude Code open in the project directory
Explore subagent working (verify with a simple prompt)
Report document created with the base structure

During the investigation

Each question uses the right pattern
Document the exact prompts you use (not just the answers)
If a prompt doesn't work, document the failed attempt and the correction
Time each question separately

When you finish

The 5 questions have complete answers
Each answer includes evidence (files, functions, lines)
The metrics section is complete
The reflection has substance (it's not generic)

Success Criteria

Your project is complete when:

✅ The 5 questions have documented answers with evidence
✅ Each answer identifies the exploration pattern used
✅ The exact prompts are documented (reproducibility)
✅ The grep vs Explore comparison (Question 4) has concrete data
✅ The original finding (Question 5) is genuinely interesting
✅ The time metrics are complete
✅ The report is readable by any developer on the team

Evaluation Rubric (100 points)

Investigation Quality (50 points)

(10 pts) Question 1: Complete general structure with a diagram
(10 pts) Question 2: Flow trace with 5+ detailed steps
(10 pts) Question 3: Dependency map of 3 modules with analysis
(10 pts) Question 4: grep vs Explore comparison with concrete data
(10 pts) Question 5: Original finding with evidence and a recommendation

Use of Patterns (25 points)

(5 pts) Top-Down applied correctly (Question 1)
(5 pts) Feature-Tracing applied correctly (Question 2)
(5 pts) Dependency-Following applied correctly (Question 3)
(5 pts) Semantic search vs grep demonstrated (Question 4)
(5 pts) Pattern choice justified in each question

Documentation (25 points)

(5 pts) Exact prompts documented (reproducibility)
(5 pts) Time metrics complete and credible
(5 pts) Report readable and well structured
(5 pts) Concrete evidence (specific files, functions, lines)
(5 pts) Reflection with genuine insights

Extra Credit (up to +10 points)

(+5 pts) Investigation includes an additional sixth finding
(+3 pts) A mermaid diagram generated by Claude Code included
(+2 pts) Efficiency comparison with a colleague who investigated manually

Minimal Implementation Example

This is an abbreviated example of what an answer to Question 2 (Main Flow) looks like for the httpx project:

## Question 2: Main Flow

### Answer

The flow of `httpx.get("https://example.com")` passes through 7 steps:

1. **httpx/_api.py:get()** — Convenience function that creates
   a temporary Client and delegates to client.get()

2. **httpx/_client.py:Client.get()** — Calls self.request()
   with method="GET"

3. **httpx/_client.py:Client.request()** — Builds the Request
   object, applies auth and redirects

4. **httpx/_client.py:Client._send()** — Handles transport
   selection and connection pooling

5. **httpx/_transports/default.py:HTTPTransport.handle_request()**
   — Uses httpcore for the real TCP connection

6. **httpcore — TCP + TLS + HTTP/1.1 or HTTP/2 connection**
   — Sends bytes, receives bytes

7. **httpx/_models.py:Response** — Builds the Response object
   with status_code, headers, content

### Method
Pattern: Feature-Tracing
3 prompts to Explore, 12 minutes total

### Prompts used
> "Use Explore to trace the complete flow of
   httpx.get('https://example.com'). Start from
   the get() function and follow every call up to the
   HTTP response."

> "Dig into the Client._send() step. How does it
   select the transport and handle connection pooling?"

> "What transformations does the data undergo from the
   raw HTTP response to the Response object that the
   user receives?"

This example:

✅ A complete trace with 7 steps
✅ Each step identifies the file and function
✅ Prompts documented
❌ It's missing the manual time estimate metric (that's your job)

Common Errors

Error 1: Answers that are too vague

Bad example: "The project has several modules that connect to each other." Good example: "The _client.py module depends on _transports/, _models.py, and _auth.py. It's imported by _api.py (convenience functions) and the async _client.py."

Solution: Always include specific file names, functions, and lines.

Error 2: Not documenting failed prompts

If your first prompt doesn't produce a good answer, document it. Iteration is part of the process.

Good practice:

# Attempt 1 (too vague):
> "How does httpx work?"
# Result: generic description, not useful

# Attempt 2 (specific):
> "Use Explore to trace the flow of httpx.get()
   from the public function to the TCP connection"
# Result: a detailed 7-step trace ✅

Error 3: Using only one pattern for everything

Each question requires a different pattern. If you use only top-down for the 5 questions, the report will be superficial.

Error 4: Not measuring time

The metrics are part of the deliverable. Without them, you can't demonstrate Explore's value. Time each question.

Error 5: Copying Explore's output without analysis

Explore gives you data. You interpret. "Explore found 3 circular dependencies" is data. "The 3 circular dependencies are in the auth module, which suggests that auth and sessions should be separated" is analysis.

Error 6: Choosing a project that's too simple

A 500-line project doesn't demonstrate Explore's value. You need at least 5K lines for the tool to shine vs manual investigation.

Error 7: Not using semantic search when it's appropriate

Question 4 specifically requires comparing grep vs Explore. If you use grep for everything, you miss the opportunity to demonstrate the difference.

Error 8: A report only you understand

The report must be readable by any developer. If you assume knowledge that only you have, it doesn't fulfill its purpose.

Resources for the Project

httpx - GitHub - Async HTTP client for Python, excellent for this project
typer - GitHub - CLI framework, a smaller alternative
rich - GitHub - Terminal formatting, a larger alternative
Claude Code - Explore Docs - Official reference for the Explore subagent
Mermaid Live Editor - To visualize mermaid diagrams generated by Claude Code
Code Reading Techniques - Complementary code reading techniques

Connection with the Next Module

What you built here — documented exploration findings — is the input for Module 3: Understand an Existing Architecture. In Module 3 you're going to take these findings and turn them into formal representations:

Your answer to Question 1 (structure) becomes a formal dependency map
Your answer to Question 2 (flow) becomes a documented flow diagram
Your answer to Question 3 (dependencies) becomes a dependency graph with coupling analysis
Your findings from Question 5 may reveal anti-patterns that you'll document formally

The transition is: "You can already explore and find code efficiently. Now turn those findings into something durable: dependency maps, architecture diagrams, and flow analysis that any team member can consult."

← PreviousExploration Patterns — Top-Down, Dependency-Following, Feature-Tracing Next →Module 3: Understand an Existing Architecture