Module 1: Onboarding with AI — 5-10x Faster

Module Project: Onboarding to an Open-Source Codebase

Project description

You're going to take a real open-source Python project — one you've never seen before — and apply everything you learned in this module to understand it in depth. You're not going to write new code from scratch. You're going to read, analyze, document, and validate your understanding of an existing codebase using Claude Code as your main tool.

This project integrates the three fundamental skills of the module: systematic exploration (the 5 questions), building a mental model (3 levels), and documenting findings (a 6-section onboarding doc). You can't complete the project without having mastered all three — and by completing it, you'll have tangible evidence that you master them.

The reason we use a real open-source project (not a sample project) is intentional: in your daily work, the code you need to understand wasn't designed to be easy to learn. It has historical decisions, tech debt, inconsistent patterns, and partial documentation. A 5K-10K-line open-source project gives you exactly that experience, but in a context where you can verify your understanding without risk.

By completing this project you'll have three artifacts: a record of your systematic exploration (the 5 questions answered), a mental model documented in 3 levels, and a professional onboarding doc. In addition, you'll have made a small change to the codebase to validate that your mental model is correct — and you'll have a time comparison that demonstrates the impact of using AI for onboarding.

Project Objective

Onboard to a 5K-10K-line open-source Python codebase in under 2 hours, producing documentation that another developer could use to understand the project.

By completing this project:

✅ You'll have applied the 5-initial-questions method to a real project
✅ You'll have a 3-level mental model documented with diagrams
✅ You'll have produced a professional 6-section onboarding doc
✅ You'll have validated your understanding with a small change to the codebase
✅ You'll have a time comparison of AI vs manual estimate

Technical Specifications

Technology Stack

Language: Python 3.10+
Main tool: Claude Code (command line)
Version control: Git
Documentation format: Markdown
Diagrams: Mermaid and/or ASCII

Open-Source Project to Choose

Choose ONE of these projects (or a similar one that meets the criteria):

Project	Approx. lines	What it does	Difficulty
httpx	~10K	Modern HTTP client (sync + async)	Medium
typer	~5K	CLI framework based on type hints	Medium-low
rich	~15K	Terminal formatting and rendering	Medium-high
pydantic-settings	~3K	Configuration management with Pydantic	Low
textual	~20K	TUI framework (Terminal UI)	High

Criteria if you choose another project:

✅ Pure Python (no C extensions as a requirement)
✅ Between 3K-15K lines of code (not counting tests)
✅ Actively maintained (commits in the last 3 months)
✅ With tests (so you can verify that your change doesn't break anything)
❌ Don't use a project you already know well
❌ Don't use a project with fewer than 3K lines (too simple)

Initial Setup

# Step 1: Create the working directory
mkdir onboarding-project
cd onboarding-project

# Step 2: Clone the chosen project (example with httpx)
git clone https://github.com/encode/httpx.git
cd httpx

# Step 3: Create a virtual environment
python -m venv venv
source venv/bin/activate  # Mac/Linux
# venv\Scripts\activate   # Windows

# Step 4: Install dependencies
pip install -e ".[dev]"
# Or alternatively:
pip install -r requirements.txt

# Step 5: Verify that the tests pass (baseline)
pytest --tb=short -q
# You should see something like: "142 passed, 3 skipped"

# Step 6: Verify that Claude Code can access the project
claude "How many Python files does this project have?
About how many lines of code?"

Important: Before starting your exploration, verify that the tests pass. That's your baseline — any change you make must keep the tests passing.

If the setup fails:

# Common problem: dependencies that require C compilation
# Solution: install only the core dependencies
pip install -e .

# Common problem: tests require external services (Redis, DB)
# Solution: run only the unit tests
pytest tests/unit/ -q --tb=short

# Common problem: incompatible Python version
python --version
# If it's < 3.10, use pyenv to install the correct version:
# pyenv install 3.11.0
# pyenv local 3.11.0

# Verify that Claude Code works in the project
claude "How many Python files are there in this directory?
Exclude tests and __pycache__."

Deliverables Structure

Your final directory should look like this:

onboarding-project/
├── httpx/                    # (or the project you chose)
│   └── ... (with your small change applied)
├── deliverables/
│   ├── 01-systematic-exploration.md
│   ├── 02-mental-model.md
│   ├── 03-onboarding-doc.md
│   ├── 04-validation-change.md
│   └── 05-time-comparison.md
└── README.md                 # Project summary

Mandatory Features

1. Systematic Exploration — The 5 Questions

Deliverable: deliverables/01-systematic-exploration.md

You must answer the 5 systematic exploration questions using Claude Code. For each question, document:

The exact prompt you used with Claude Code
The answer you got
Your analysis/interpretation of the answer

The 5 questions:

## Question 1: What's the project's structure?

### Prompt used:
[The exact prompt you gave Claude Code]

### Claude Code's answer:
[The complete answer]

### My analysis:
[Your interpretation: what surprised you, what you expected,
what wasn't clear]

---

## Question 2: Where are the entry points?

[Same format]

---

## Question 3: How does data flow?

[Same format]

---

## Question 4: What patterns are used?

[Same format]

---

## Question 5: Where's the tech debt?

[Same format]

What it should do:

✅ Answer the 5 questions in order (big picture first, details later)
✅ Include the exact prompts (so it's reproducible)
✅ Include Claude Code's answer (not summarized — complete)
✅ Include your personal analysis of each answer
✅ Mark things that surprised you or that you didn't understand

2. Documented Mental Model — 3 Levels

Deliverable: deliverables/02-mental-model.md

You must build and document your mental model in the 3 levels learned in capsule 04.

## Level 1: High-Level — Architecture and Layers

### Layer Diagram
[ASCII or Mermaid diagram of the project's layers]

### Main Components
[List of components with a brief description]

### Entry Points
[Where execution enters the system]

### Exit Points
[Where information leaves: DB, API, files, etc.]

---

## Level 2: Mid-Level — Modules and Dependencies

### Dependency Map
[For the 5 most important modules: who they depend on
and who depends on them]

### Circular Dependencies
[If there are, document them. If not, confirm it.]

### Hub Files
[The 3-5 most connected files in the project]

---

## Level 3: Low-Level — Key Functions and Data Structures

### Critical Functions
[The 3-5 most important functions. For each one:
input, output, side effects, error handling]

### Main Data Structures
[The 3-5 most important data structures.
For each one: fields, relationships, where it's created/consumed]

### Data Flow of the Main Operation
[Step-by-step flow of the project's most common operation]

What it should do:

✅ Cover the 3 levels (not just Level 1)
✅ Include at least one diagram (ASCII or Mermaid)
✅ Document the hub files (most connected files)
✅ Include the data flow of at least one end-to-end operation
✅ Be specific (real names of files, functions, classes)

3. Professional Onboarding Doc — 6 Sections

Deliverable: deliverables/03-onboarding-doc.md

You must produce a complete onboarding doc following the 6-section structure from capsule 05.

# Onboarding Doc: [Project Name]

**Generated:** [Date]
**Author:** [Your name] (with assistance from Claude Code)
**Project:** [Name and URL of the repo]
**Onboarding time:** [How long it took you]

---

## Table of Contents
1. Project Overview
2. Architecture Overview
3. Key Patterns
4. Gotchas
5. Data Flows
6. Getting Started

---

## 1. Project Overview
[What it does, stack, size, status, consumers]

## 2. Architecture Overview
[Layers, directory structure, entry points, dependencies]

## 3. Key Patterns
[Architectural patterns, naming, error handling, testing]

## 4. Gotchas
[Minimum 5 gotchas specific to the project]

## 5. Data Flows
[Minimum 2 data flows documented step by step]

## 6. Getting Started
[Setup, tests, how to contribute, files to read first]

What it should do:

✅ Have all 6 sections complete
✅ The Gotchas section must have a minimum of 5 specific items
✅ The Data Flows section must have a minimum of 2 documented flows
✅ The Getting Started section must be functional (following the steps must work)
✅ Be written for a developer who does NOT know the project
✅ Include at least one personal opinion (not just Claude Code output)

4. Validation Change

Deliverable: deliverables/04-validation-change.md

You must make ONE small change to the codebase to validate your understanding. The change can be:

Add a test for a function that isn't tested
Improve an existing docstring
Add type hints to a function that doesn't have them
Fix a typo in code or documentation
Add logging to a critical function

Document:

## Change Made

### What I changed:
[Description of the change in 1-2 sentences]

### File(s) modified:
[List of files]

### Prediction before the change:
"If I make [change], I expect that [consequence].
The tests [should/should not] pass because [reason]."

### Actual result:
[What happened when you made the change? Was your prediction correct?]

### Verification:
```bash
# Command to verify that the tests pass
pytest --tb=short -q
# Result: [X passed, Y skipped]

Learning:

[What did you learn from this change about your mental model? Was there something you didn't predict correctly?]


**What it should do:**

- ✅ The change must be real (not simulated)
- ✅ You must predict the result BEFORE making the change
- ✅ The tests must still pass after the change
- ✅ Document whether your prediction was correct or not
- ✅ Explain what you learned about your mental model

### 5. Time Comparison

**Deliverable:** `deliverables/05-time-comparison.md`

You must compare how long it took you with Claude Code vs how long it would have taken without AI.

```markdown
## Time Comparison

### Actual Time (with Claude Code)

| Activity | Time |
|-----------|--------|
| Setup and test verification | X min |
| Systematic exploration (5 questions) | X min |
| Mental model Level 1 | X min |
| Mental model Level 2 | X min |
| Mental model Level 3 | X min |
| Onboarding doc — Project Overview | X min |
| Onboarding doc — Architecture | X min |
| Onboarding doc — Key Patterns | X min |
| Onboarding doc — Gotchas | X min |
| Onboarding doc — Data Flows | X min |
| Onboarding doc — Getting Started | X min |
| Validation change | X min |
| **TOTAL** | **X min** |

### Manual Estimate (without AI)

| Activity | Estimate |
|-----------|-----------|
| Setup and test verification | X min |
| Read the directory structure manually | X min |
| Read the main files (grep, reading) | X hrs |
| Build the mental model by reading code | X hrs |
| Document findings manually | X hrs |
| Make the validation change | X min |
| **ESTIMATED TOTAL** | **X hrs** |

### Acceleration Factor

Time with Claude Code: X hours
Manual estimate: Y hours
Factor: Y/X = Zx faster

### Reflection

[In 3-5 sentences: where was Claude Code most useful? Where didn't it help?
What would you do differently next time?]

What it should do:

✅ Track the real time of each activity
✅ Honestly estimate how long it would have taken without AI
✅ Calculate the acceleration factor
✅ Reflect on where Claude Code was more/less useful

Validations and Error Handling

Mandatory Validations

The original project's tests pass before your change
The project's tests still pass after your change
The onboarding doc has all 6 sections complete
The mental model has the 3 levels documented
The 5 exploration questions are answered with real prompts
The time comparison has real data (not made up)

Handling Common Errors

Error: The tests don't pass before you start

# Some projects have tests that require specific dependencies
# Try installing all the development dependencies
pip install -e ".[dev,test]"

# If there are tests that fail because of the environment (Redis, DB, etc.)
# Run only the unit tests
pytest tests/unit/ --tb=short -q

# If it persists, document which ones fail and why
pytest --tb=short 2>&1 | tail -20

Error: Claude Code can't analyze the project (too large)

# Focus Claude Code on specific subdirectories
claude "Analyze ONLY the src/httpx/ directory (no tests, no docs).
How many files does it have and what's the structure?"

# Use @-references for specific files
claude "Analyze @src/httpx/_client.py — what functions does it expose
and what modules does it depend on?"

Error: You don't know what change to make for validation

# Ask Claude Code to suggest a safe change
claude "Suggest a small, safe change I can make
to this project to validate that I understand the structure.
Criteria: it shouldn't break tests, it should be useful, and it should touch at least 1
file that I analyze in my mental model."

Errors that MUST be handled:

If the chosen project has more than 15K lines: document how you focused your analysis (which parts you prioritized and why)
If your prediction for the validation change was incorrect: explain why it failed and how you adjusted your mental model
If any section of the onboarding doc is incomplete: explain why and what you'd do with more time

Detailed Step-by-Step Guide

This section walks you through each phase of the project with the exact prompts you can use.

Phase 1: Setup and Verification (10 min)

# 1. Clone (example with httpx)
git clone https://github.com/encode/httpx.git
cd httpx

# 2. Virtual environment
python -m venv venv
source venv/bin/activate

# 3. Install
pip install -e ".[dev]"

# 4. Verify tests (save the baseline)
pytest -q --tb=short 2>&1 | tail -5
# Note how many tests pass — this is your baseline

# 5. Count the project's size
find . -name "*.py" -not -path "*/test*" -not -path "*/__pycache__/*" | \
  xargs wc -l | tail -1
# It should give 5,000+ lines

# 6. Create the deliverables directory
mkdir -p ../deliverables

Phase 2: Systematic Exploration (20 min)

Run each question in order. Copy the prompt and the answer into your document.

# Question 1: Structure (4 min)
claude "Analyze the directory structure of this Python project.
For each main directory, explain what type of code it contains.
Don't include __pycache__, .git, or build directories."

# Question 2: Entry Points (4 min)
claude "Identify the entry points of this project:
1. What does a user import when they do 'import httpx'?
2. What file defines the package's public API?
3. Are there CLI entry points or scripts?"

# Question 3: Data Flow (4 min)
claude "Trace the data flow of this project's main operation.
If it's an HTTP library: what happens when a user calls
the main function (get, post, etc.)? What modules
are involved and in what order?"

# Question 4: Patterns (4 min)
claude "What design patterns are used in this project?
Look for: factory pattern, adapter pattern, strategy pattern,
dependency injection, observer, or any other.
Give specific examples with file and class names."

# Question 5: Tech Debt (4 min)
claude "Identify tech debt in this project. Look for:
1. TODOs and FIXMEs in the code
2. Commented-out code
3. Functions that are too long (>50 lines)
4. Deprecated dependencies
5. Inconsistencies in style or patterns"

After each answer, add your analysis to the document. Don't just copy — interpret.

Phase 3: Mental Model — Level 1 and 2 (20 min)

# Level 1: Architecture (10 min)
claude "Generate an architecture analysis of this project:
1. What are the main layers or components?
2. Generate an ASCII diagram showing the layers
3. What's the dependency rule between layers?
4. What are the external dependencies and what are they used for?"

# Level 2: Dependencies (10 min)
claude "Analyze the dependencies between modules:
1. For the 5 most important files in the project,
   list what they depend on and who depends on them
2. Identify the hub files (files with the most connections)
3. Are there circular dependencies?"

claude "Generate a Mermaid diagram showing the dependencies
between the 8-10 main modules of the project.
Use graph TD with dependency arrows."

Phase 4: Mental Model — Level 3 (20 min)

# Critical functions (10 min)
claude "Identify the 3 most critical functions in this project.
For each one:
1. Complete signature (name, parameters, return type)
2. What it does in 2-3 sentences
3. What side effects it has
4. How it handles errors
5. Who calls it"

# Data structures (5 min)
claude "Which are the 3-5 main data structures?
For each one: fields, relationships, where it's created, where it's consumed."

# Detailed data flow (5 min)
claude "Trace the complete flow of the most common operation
in this project, step by step. Include every file and
function that runs, in order."

Phase 5: Onboarding Doc (30 min)

Generate each section separately for more control:

# Section 1: Project Overview (3 min)
claude "Generate the 'Project Overview' section of an onboarding doc.
Include: what it does, stack, size (files and LOC), status
(git activity), and main consumers."

# Section 2: Architecture (5 min)
claude "Generate the 'Architecture Overview' section with:
layer diagram, directory structure, entry points,
external dependencies and what each one is used for."

# Section 3: Key Patterns (5 min)
claude "Generate the 'Key Patterns' section. Identify:
architectural patterns with code examples,
naming conventions, error handling patterns,
testing patterns."

# Section 4: Gotchas (10 min — the most valuable)
claude "Generate the 'Gotchas' section of the onboarding doc.
Look for a MINIMUM of 5 specific gotchas:
1. Non-obvious dependencies between modules
2. Hidden side effects in functions
3. Implicit or undocumented configuration
4. Behavior that differs from what the name suggests
5. Discrepancies between documentation and real code
6. Import hacks or workarounds
Each gotcha must have a file name and a concrete explanation."

# Section 5: Data Flows (5 min)
claude "Generate the 'Data Flows' section with a MINIMUM of 2 flows.
For each one: trigger, step by step with real modules,
side effects, final result."

# Section 6: Getting Started (2 min)
claude "Generate the 'Getting Started' section: setup steps,
how to run tests, how to make a first change, and the 5
files a new developer should read first (in order)."

# Assemble and review
claude "Review this complete onboarding doc. Look for:
1. Inconsistencies between sections
2. Missing information
3. Factual errors vs the real code
Suggest corrections."

Phase 6: Validation Change (10 min)

# 1. Ask for a change suggestion
claude "Suggest 3 small changes I can make to this project
to validate my understanding. Criteria:
- It must touch a file I analyze in my mental model
- It shouldn't break tests
- It should be useful (not trivial)
Suggestions: add a test, improve a docstring, add type hints."

# 2. BEFORE making the change, write your prediction:
# "If I make [change X], I expect [consequence Y]
#  because according to my mental model [reason Z]."

# 3. Make the change
claude "Make the following change: [description of the chosen change]"

# 4. Verify
pytest -q --tb=short
# The tests must pass

Phase 7: Comparison and Review (10 min)

# 1. Note the real times of each phase
# 2. Estimate how long it would have taken without Claude Code
# 3. Write a reflection (3-5 sentences)
# 4. Final review of all the deliverables
# 5. Create the project's README.md

Success Criteria

Your project is complete when:

✅ The 5 exploration questions are answered with real prompts and personal analysis
✅ The mental model has the 3 levels with at least one diagram
✅ The onboarding doc has the 6 sections with at least 5 gotchas
✅ You made a real change to the codebase with a prediction and verification
✅ The time comparison has real data and a reflection
✅ The project's tests pass after your change
✅ All the deliverables are in the specified directory structure

Evaluation Rubric (100 points)

Functionality (50 points)

(10 pts) Complete systematic exploration: The 5 questions answered with real prompts, Claude Code's answers, and personal analysis for each one
(10 pts) 3-level mental model: Level 1 (layers, entry points), Level 2 (dependencies between modules, hub files), Level 3 (critical functions, data structures, data flow)
(10 pts) 6-section onboarding doc: Project Overview, Architecture, Key Patterns, Gotchas (minimum 5), Data Flows (minimum 2), Getting Started (functional)
(10 pts) Validation change: Real change, prior prediction, post-change verification, tests pass, learning documented
(10 pts) Time comparison: Real time tracked, reasoned manual estimate, acceleration factor calculated, personal reflection

Code (30 points)

(10 pts) Effective prompts: The prompts used with Claude Code are specific, well-structured, and produce useful results. They aren't generic ("explain this project to me")
(10 pts) Diagrams and visualizations: At least 1 Mermaid or ASCII diagram in the mental model. At least 1 data flow documented with real modules and step by step
(5 pts) Correct validation change: The change is useful (not trivial), the tests pass, and it demonstrates understanding of the codebase area it touches
(5 pts) Reproducibility: Following the documented prompts, another developer could reproduce the analysis

Documentation (20 points)

(8 pts) Useful onboarding doc: A developer who doesn't know the project could read the doc and understand the architecture, patterns, and gotchas in 15-20 minutes
(5 pts) Clear structure: The 5 deliverables follow the specified format, are navigable, and are well organized
(4 pts) Personal opinions: The onboarding doc includes at least 2-3 observations of your own (not just Claude Code output)
(3 pts) Project README: Includes a README.md with a project summary, chosen codebase, and how to navigate the deliverables

Extra Credit (up to +10 points)

(+3 pts) TL;DR version: Create a 1-page version of the onboarding doc in addition to the complete version
(+3 pts) Second data flow: Document a third data flow (in addition to the 2 mandatory ones)
(+2 pts) Validation script: Create a script that verifies the onboarding doc is up to date vs the code
(+2 pts) Comparison of 2 projects: Onboard to a second project and compare the architectures

Minimal Implementation Example

This is the minimal skeleton you must complete. It is NOT the complete solution — it's the base structure you build on.

`deliverables/01-systematic-exploration.md` (skeleton)

# Systematic Exploration: [Project Name]

## Date: [YYYY-MM-DD]
## Project: [repo URL]

---

## Question 1: What's the project's structure?

### Prompt used:

claude "Analyze the directory structure of this project. Identify the main directories and what type of code each one contains."


### Claude Code's answer:
[Paste answer here]

### My analysis:
- What I expected: [...]
- What surprised me: [...]
- What I didn't understand: [...]

---

## Question 2: Where are the entry points?

### Prompt used:

claude "[Your prompt here]"


### Claude Code's answer:
[Paste answer]

### My analysis:
[Your analysis]

---

[Repeat for questions 3, 4, 5]

`deliverables/02-mental-model.md` (skeleton)

# Mental Model: [Project Name]

## Level 1: High-Level

### Layer Diagram

[Your ASCII diagram here] Layer 1: [name] | v Layer 2: [name] | v Layer 3: [name]


### Entry Points
- [file 1] — [what it does]
- [file 2] — [what it does]

---

## Level 2: Mid-Level

### Dependency Map (Top 5 Modules)

**[module 1]:**
- Depends on: [list]
- Depended on by: [list]

[Repeat for 4 more modules]

### Hub Files
1. [file] — [X incoming dependencies, Y outgoing]
2. [file] — [...]
3. [file] — [...]

---

## Level 3: Low-Level

### Critical Function: [name]
- Input: [...]
- Output: [...]
- Side effects: [...]
- Error handling: [...]

[Repeat for 2-4 more functions]

### Data Flow: [main operation]

[Step 1] → [Step 2] → [Step 3] → [Result]

`deliverables/03-onboarding-doc.md` (skeleton)

# Onboarding Doc: [Project Name]

**Generated:** [Date]
**Author:** [Your name]
**Onboarding time:** [X hours]

---

## 1. Project Overview

**What it is:** [1-2 sentences]
**Stack:** [Language, frameworks, dependencies]
**Size:** [~X files, ~Y LOC]
**Status:** [Active/legacy, commit frequency]

## 2. Architecture Overview

[Layer diagram]
[Directory structure]
[Entry points]

## 3. Key Patterns

- [Pattern 1: name and code example]
- [Pattern 2: name and example]
- [Pattern 3: name and example]

## 4. Gotchas

- ⚠️ [Gotcha 1]
- ⚠️ [Gotcha 2]
- ⚠️ [Gotcha 3]
- ⚠️ [Gotcha 4]
- ⚠️ [Gotcha 5]

## 5. Data Flows

### Flow 1: [name]
[Step by step]

### Flow 2: [name]
[Step by step]

## 6. Getting Started

```bash
# Steps to run the project

Files to read first:

[file] — [why]
[file] — [why]
[file] — [why]


### `deliverables/04-validation-change.md` (skeleton)

```markdown
# Validation Change

## What I changed:
[Description]

## File(s) modified:
- [file 1]

## My prediction:
"If I make [change], I expect [consequence]."

## Actual result:
[What happened]

## Tests:
```bash
pytest --tb=short -q
# Result: [X passed]

Learning:

[What you learned]


### `deliverables/05-time-comparison.md` (skeleton)

```markdown
# Time Comparison

## Actual Time (with Claude Code)

| Activity | Time |
|-----------|--------|
| Setup | X min |
| Exploration 5 questions | X min |
| Mental model (3 levels) | X min |
| Onboarding doc | X min |
| Validation change | X min |
| **TOTAL** | **X min** |

## Manual Estimate (without AI)

| Activity | Estimate |
|-----------|-----------|
| [Same activities] | X hrs |
| **TOTAL** | **X hrs** |

## Factor: X hrs / Y hrs = Zx

## Reflection:
[3-5 sentences]

`README.md` (skeleton)

# Onboarding Project: [Project Name]

## Summary

Onboarding to the open-source codebase [name] using Claude Code
and the systematic method from Module 1 of the guide
"Refactoring & Legacy Code with Claude Code."

## Chosen Project

- **Name:** [name]
- **URL:** [github URL]
- **Size:** ~[X] LOC (without tests)
- **Why I chose it:** [1 sentence]

## Total Time

- With Claude Code: [X] minutes
- Manual estimate: [Y] hours
- Acceleration factor: [Z]x

## How to Navigate the Deliverables

| File | Content |
|---------|-----------|
| `deliverables/01-systematic-exploration.md` | 5 questions answered with prompts and analysis |
| `deliverables/02-mental-model.md` | Mental model in 3 levels with diagrams |
| `deliverables/03-onboarding-doc.md` | 6-section onboarding doc |
| `deliverables/04-validation-change.md` | Change to the codebase with prediction and verification |
| `deliverables/05-time-comparison.md` | Time comparison AI vs manual |

Example of Real Content (exploration fragment)

So you can see the difference between a minimal deliverable and a well-made one, here's an example of how Question 1 of the exploration should look for the httpx project:

## Question 1: What's the project's structure?

### Prompt used:

claude "Analyze the directory structure of httpx/. For each main directory and file, explain what type of code it contains. Exclude pycache and .git."


### Claude Code's answer:

httpx/ is the main package with the following structure:

httpx/ ├── init.py # Public API: re-exports Client, AsyncClient, get, post... ├── _api.py # Convenience functions (get(), post(), etc.) ├── _auth.py # Authentication handlers (Basic, Digest, custom) ├── _client.py # Client and AsyncClient (main classes) ├── _compat.py # Compatibility between Python versions ├── _config.py # Timeout, Limits, SSL configuration ├── _content.py # Encoding/decoding of request/response bodies ├── _decoders.py # Response decompression (gzip, deflate, brotli) ├── _exceptions.py # Exception hierarchy ├── _models.py # Request, Response, URL, Headers, Cookies ├── _multipart.py # Multipart form data encoding ├── _status_codes.py # HTTP status codes as constants ├── _transports/ # HTTP transport (sync and async) │ ├── default.py # HTTPTransport, AsyncHTTPTransport │ ├── mock.py # MockTransport for testing │ └── wsgi.py # WSGITransport for testing WSGI apps ├── _types.py # Type aliases └── _urls.py # URL parsing and construction


### My analysis:

**What I expected:** A typical Python library structure with a main
file and utilities. I was more or less right.

**What surprised me:**
- All the internal files have a `_` prefix (single underscore).
  This indicates they're "private" — the public API is ONLY what
  `__init__.py` re-exports. It's a very clean convention.
- There's a `_compat.py` file dedicated to compatibility. This suggests
  that supporting multiple Python versions is a priority.
- The `_transports/` directory has a `mock.py`. I'm not sure
  if it's for internal tests or if it's part of the public API so that
  users can mock httpx in their tests.

**What I didn't understand yet:**
- What's the difference between `_api.py` and `_client.py`? Both seem
  to be "the way to make requests." I need to investigate this.

This level of detail — exact prompt, complete answer, analysis with surprises and doubts — is what distinguishes a 10/10-point deliverable from a 5/10 one.

This example:

✅ Shows the expected structure of each deliverable
✅ Is functional as a starting point
✅ Shows the level of detail expected in the personal analysis
❌ Does NOT include real content for all sections (that's your job)
❌ Is NOT enough to earn points — you must complete it with real analysis

Common Errors

Error 1: Choosing a project that's too simple

Cause: You chose a project of <2K lines where onboarding takes 10 minutes with or without AI. Solution: Choose a project of 5K-10K lines minimum. The point is that the difference between manual and AI exploration is palpable. With a trivial project, the acceleration factor will be insignificant.

# Check the project's size
find . -name "*.py" -not -path "*/test*" -not -path "*/__pycache__/*" | \
  xargs wc -l | tail -1
# It should show at least 5,000 lines

Error 2: Copying Claude Code's answer without analysis

Cause: You pasted Claude Code's answer into the deliverable and didn't add anything of your own. Solution: For each Claude Code answer, add your analysis: what surprised you, what you expected, what wasn't clear, what you verified. Your value is in the analysis, not in the copy-paste.

# ❌ Incorrect:
## Question 1: Structure
[Claude Code's answer copied directly. The end.]

# ✅ Correct:
## Question 1: Structure
### Claude Code's answer:
[Complete answer]

### My analysis:
What surprised me: I didn't expect the project to have
a _compat/ directory dedicated to compatibility with old Python
versions. This suggests that supporting multiple versions
is a high priority for the project.

What I didn't understand: the _transports/ directory has a
mock.py file — I'm not sure if it's for tests or if it's a real
transport. I need to investigate this in Level 2.

Error 3: Mental model without diagrams

Cause: You described the architecture with text only, without any visual representation. Solution: Include at least one diagram. It can be ASCII (fast) or Mermaid (professional). A diagram communicates the structure in 5 seconds; text requires 5 minutes.

# Ask Claude Code to generate the diagram
claude "Generate a Mermaid diagram of this project's architecture.
graph TD showing the main components and
their dependencies."

Error 4: Trivial validation change (only fixing a typo in a comment)

Cause: You chose a change that doesn't validate your mental model because it doesn't touch any real functionality. Solution: The change must touch a file you analyzed in your mental model. Adding a test, improving the docstring of a critical function, or adding type hints are good candidates. Fixing a typo in a random comment doesn't demonstrate understanding.

# Ask Claude Code for a significant but safe change
claude "Suggest a change I can make to validate
my understanding of the _client.py module. The change must:
1. Touch a file I analyze in my mental model
2. Not break existing tests
3. Be useful (not trivial)
Suggestions: add a test, improve the docstring of a public
function, add type hints."

Error 5: Onboarding doc without real gotchas

Cause: The Gotchas section has generic items like "the project is complex" instead of gotchas specific to the codebase. Solution: Gotchas must be specific: file names, lines of code, concrete behavior. "The project is complex" isn't a gotcha. "The _config.py file uses lazy loading for SSL contexts, which means certificate errors don't appear until the first request" is a gotcha.

# Ask for specific gotchas
claude "Look for SPECIFIC gotchas in this project. I want:
- Concrete file and function names
- Behavior that surprises a new developer
- Non-obvious side effects
- Implicit undocumented configuration
I do NOT want generic observations like 'the project is large'."

Error 6: Made-up time comparison

Cause: You didn't track the real time and put numbers that "sound good." Solution: Track the time from the start. Use a timer (your phone, a pomodoro). The manual estimate can be subjective, but the time with Claude Code must be real.

# Tip: use your terminal's time command
time claude "Analyze this project's structure..."
# Shows how long the command took

Error 7: Not following the order of the 5 questions

Cause: You started with details ("how does this function work?") before understanding the big picture. Solution: Order matters: structure → entry points → data flow → patterns → tech debt. Each question builds on the previous one. If you jump to tech debt without understanding the structure, your observations will be decontextualized.

Error 8: Using a project you already know

Cause: You chose a project you use daily or that you've already contributed to. Solution: The point of the exercise is to practice onboarding to something unfamiliar. If you already know the project, you can't honestly evaluate the process. Choose something new.

Frequently Asked Questions

Can I use a project in a language other than Python?

Not for this module. The guide uses Python as the reference language, and the examples and prompts are designed for Python projects. In later modules you'll be able to apply the same techniques to other languages, but for this project you need a Python codebase so the experience is consistent with what you learned.

What if the project I chose has failing tests?

Document which ones fail and why (dependency on external services, Python version, etc.). If more than 20% of the tests fail, consider choosing another project. If it's a few tests with clear reasons (e.g., they require Redis running), exclude those tests from your baseline:

# Exclude tests that require external services
pytest --ignore=tests/integration/ -q --tb=short

Can I do the project as a team?

Yes, but each person must produce their own deliverables on a DIFFERENT project. You can compare results at the end — that's a valuable exercise. But if both do the same project, you're not practicing onboarding to something unfamiliar.

How much detail is expected in the onboarding doc?

Enough for a developer who doesn't know the project to read your doc and understand the architecture, patterns, and gotchas in 15-20 minutes. It's not exhaustive documentation of every function — it's an orientation guide. Think about what YOU would have wanted to read before exploring the project.

What do I do if Claude Code gives incorrect information?

Document it. It's part of the learning. In your analysis section, note: "Claude Code said X but on verifying I discovered it's Y." This demonstrates critical thinking and is more valuable than a perfect answer.

Can I use tools besides Claude Code (e.g., grep, tree, ctags)?

Yes, but the focus is Claude Code. You can use complementary tools to verify, but 80%+ of your exploration should be with Claude Code. If you use another tool, document why it was necessary in that case.

Resources for the Project

httpx — GitHub Repository https://github.com/encode/httpx HTTP client for Python. Ideal size (~10K LOC), well structured, good test coverage. Recommended as a first option.
typer — GitHub Repository https://github.com/tiangolo/typer CLI framework. Smaller (~5K LOC), created by the author of FastAPI. A good option if you prefer a simpler project.
rich — GitHub Repository https://github.com/Textualize/rich Terminal rendering library. Larger (~15K LOC). A good option if you want a bigger challenge with a more complex architecture.
Claude Code Documentation https://docs.anthropic.com/en/docs/claude-code Official reference for the Claude Code commands and capabilities you'll use during the project.
Mermaid Live Editor — https://mermaid.live/ Online editor to create and preview Mermaid diagrams. Useful for refining the diagrams Claude Code generates before including them in your documentation.
"Working Effectively with Legacy Code" — Michael Feathers Chapter 16 specifically. The concept of "seams" (points where you can make changes without modifying the structure) is relevant to your validation change.

Connection with the Next Module

What you built in this project establishes the base for Module 2: Agentic Research with the Explore Subagent.

In this module, you explored a codebase using Claude Code directly — writing manual prompts for each question, each level of the mental model, each section of the onboarding doc. It works, but it requires that you know what to ask and how to formulate each prompt.

In Module 2 you're going to learn to use the Explore subagent — a tool within Claude Code designed specifically for codebase investigation. It's read-only (it can't modify anything), it uses semantic search (it finds "where authentication is handled" without knowing the function's name), and it's optimized for exploring large projects.

The transition is:

Module 1: Manual exploration with Claude Code
           (you formulate each prompt, you decide the order)
              │
              ▼
Module 2: Assisted exploration with the Explore subagent
           (the tool optimizes the search for you)
              │
              ▼
Module 3: Deep architectural analysis
           (dependency maps, flow analysis, pattern identification)

What you did manually here, the Explore subagent can automate. But first you needed to understand the manual process to know when the automatic tool is doing a good job and when you need to step in.

Your onboarding doc and mental model from this project will serve as a reference when you compare the Explore subagent's results in Module 2 — you'll be able to see whether the tool discovers the same gotchas, the same hub files, and the same data flows you found manually.

Suggested Timeline

To complete this project in ~2 hours:

Block	Time	Activity
1	0:00 - 0:10	Setup: clone project, install deps, verify tests
2	0:10 - 0:30	Systematic exploration: 5 questions with Claude Code
3	0:30 - 0:50	Mental model: Level 1 (10 min) + Level 2 (10 min)
4	0:50 - 1:10	Mental model: selective Level 3 (20 min)
5	1:10 - 1:40	Onboarding doc: generate 6 sections with Claude Code
6	1:40 - 1:50	Validation change: predict, make, verify
7	1:50 - 2:00	Time comparison and final review

Time management tips:

✅ Don't perfect each section on the first pass. Generate everything first, refine later.
✅ If an exploration question takes more than 5 minutes, move on and come back later.
✅ Level 3 of the mental model is selective — don't analyze all the functions, only the 3-5 critical ones.
✅ The Gotchas section of the onboarding doc can grow as you discover things. Don't leave it for the end.
❌ Don't spend 45 minutes on the setup. If the dependencies give you trouble, continue with the source code analysis directly.

Final Checklist

Before submitting, verify:

Structure: The 5 deliverables are in deliverables/ with the correct names
01-exploration: The 5 questions have a prompt, answer, AND personal analysis
02-mental-model: The 3 levels are documented with at least 1 diagram
03-onboarding-doc: The 6 sections are complete, gotchas has 5+ items
04-change: The change is real, there's a prior prediction, tests pass post-change
05-comparison: Real times (not made up), personal reflection included
Tests: The project's tests pass after your change
README: There's a README.md with a summary and how to navigate the deliverables
Chosen project: It's 5K+ lines and you didn't know it previously

← PreviousDocumenting Findings with Claude Code Next →Module 2: Agentic Research with the Explore Subagent

Module Project: Onboarding to an Open-Source Codebase

Module Project: Onboarding to an Open-Source Codebase

Project description

Project Objective

Technical Specifications

Technology Stack

Open-Source Project to Choose

Initial Setup

Deliverables Structure

Mandatory Features

1. Systematic Exploration — The 5 Questions

2. Documented Mental Model — 3 Levels

3. Professional Onboarding Doc — 6 Sections

4. Validation Change

Learning:

Validations and Error Handling

Mandatory Validations

Handling Common Errors

Detailed Step-by-Step Guide

Phase 1: Setup and Verification (10 min)

Phase 2: Systematic Exploration (20 min)

Phase 3: Mental Model — Level 1 and 2 (20 min)

Phase 4: Mental Model — Level 3 (20 min)

Phase 5: Onboarding Doc (30 min)

Phase 6: Validation Change (10 min)

Phase 7: Comparison and Review (10 min)

Success Criteria

Evaluation Rubric (100 points)

Functionality (50 points)

Code (30 points)

Documentation (20 points)

Extra Credit (up to +10 points)

Minimal Implementation Example

deliverables/01-systematic-exploration.md (skeleton)

deliverables/02-mental-model.md (skeleton)

deliverables/03-onboarding-doc.md (skeleton)

Learning:

README.md (skeleton)

Example of Real Content (exploration fragment)

Common Errors

Error 1: Choosing a project that's too simple

Error 2: Copying Claude Code's answer without analysis

Error 3: Mental model without diagrams

Error 4: Trivial validation change (only fixing a typo in a comment)

Error 5: Onboarding doc without real gotchas

Error 6: Made-up time comparison

Error 7: Not following the order of the 5 questions

Error 8: Using a project you already know

Frequently Asked Questions

Can I use a project in a language other than Python?

What if the project I chose has failing tests?

Can I do the project as a team?

How much detail is expected in the onboarding doc?

What do I do if Claude Code gives incorrect information?

Can I use tools besides Claude Code (e.g., grep, tree, ctags)?

Resources for the Project

Connection with the Next Module

Suggested Timeline

Final Checklist

`deliverables/01-systematic-exploration.md` (skeleton)

`deliverables/02-mental-model.md` (skeleton)

`deliverables/03-onboarding-doc.md` (skeleton)

`README.md` (skeleton)