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

Capsule description

You're going to learn the most fundamental skill for working with existing code: quickly understanding a codebase you didn't write. Without this skill, everything that comes later in this guide — refactoring, migration, modernization — is impossible or dangerous. Modifying code without understanding it is the number one source of bugs in development teams, and the main reason new developers take weeks to become productive.

The problem is economic and practical. A senior developer takes 2-4 weeks to understand a medium-sized codebase. Multiply that by every new team member, every project change, every open source contribution. With Claude Code and a systematic method, that time drops to hours — not because you skip steps, but because AI reads and processes code orders of magnitude faster than a human. Where you read one file at a time, Claude Code reads entire directories. Where you grep and lose context, Claude Code traces data flows across dozens of files in seconds.

This module gives you the method and the tools so that onboarding to any codebase stops being a bottleneck in your career. The 5 initial questions, the exploration order, and the documentation techniques you'll learn here apply to any project — from a 5K-line microservice to a 500K-line monorepo.

Module Context

Where are we?

This is Guide #8 of the Claude Code Agentic Development Path — "Refactoring & Legacy Code with Claude Code." It's the second guide in the "Quality and Maintenance" block within the Professional level of the path.

Prerequisites completed:

Guide	What you built
#1 — How Coding Agents Work	Conceptual base: how agents think, plan, and execute
#2 — Claude Code Foundations	Practical skill: mastery of Claude Code as a daily tool
#3 — Prompt Engineering with Claude Code	Professional communication: prompts that produce predictable results
#4 — AI Coding Tools Landscape	Strategic perspective: ecosystem evaluation, a justified toolkit
#5 — Claude Code & MCP	Custom integrations with the Model Context Protocol
#6 — Debugging & Code Review	Professional debugging and code review with agents
#7 — Testing with Claude Code	Testing strategy, TDD, tests as a safety net

Up to now you've worked mostly with new code: you created projects from scratch, applied TDD, generated fresh code. But professional reality is different: 80% of a developer's time is spent on code that already exists — understanding it, maintaining it, and improving it. This module marks that transition.

Where are we headed?

The guide has 3 progressive phases and 8 modules. Each phase builds on the previous one:

Phase 1: Understand Codebases (Modules 1-3)
+-- Module 1: Onboarding with AI — 5-10x Faster          <-- YOU ARE HERE
+-- Module 2: Agentic Research with the Explore Subagent
+-- 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

All of Phase 1 is about understanding codebases — not modifying them. The first 3 modules invest all the effort in comprehension because it's the fundamental principle of this guide: understand before you modify. Every minute invested in comprehension saves hours of debugging.

The progression within Phase 1:

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

Each module adds a layer of depth. In Module 1 you learn to explore. In Module 2 you use a tool designed specifically for exploration. In Module 3 you generate visual and textual representations of the architecture.

Why does this module matter?

The problem it solves

Think about the last time you joined an existing project. What did you do?

Day 1:  You open the repo. You see 200 files. You don't know where to start.
Day 2:  You read the README (if it exists). You try to run the project.
Day 3:  You start exploring random files. You open main.py, you see imports.
Day 5:  You start to vaguely understand the structure.
Day 10: You can now make small changes, fearfully.
Day 15: You understand the main data flow.
Day 20: You feel "productive" — but there are still modules you don't touch.

That timeline is optimistic. For large or legacy codebases, double the numbers. And multiply by every new person who joins the team.

Now imagine this:

Hour 0:  You open the repo with Claude Code.
Hour 1:  You have a full map of the structure and entry points.
Hour 2:  You understand the main data flow and the patterns used.
Hour 3:  You've identified tech debt and risk areas.
Hour 4:  You produce an onboarding doc another developer can use.
Hour 5:  You make a small change to validate your understanding.

That's the difference between manual onboarding and onboarding with AI: 5-10x faster, not because you skip steps, but because Claude Code reads and processes code orders of magnitude faster than a human.

The shift in perspective

Most developers use Claude Code like this:

"Generate an authentication endpoint for me"
"Write tests for this function"
"Create a data model for users"

It's all output: generate, write, create. But Claude Code is just as powerful — maybe more — as an input tool:

"Explain the structure of this project to me"
"What does this function do and why is it implemented this way?"
"What's the data flow from when a request arrives to the response?"
"Where's the most critical tech debt in this codebase?"

You're going to learn to use Claude Code as a reader, not just as a writer. And that fundamentally changes how you work with existing codebases.

The data is clear

The statistics back up this shift:

80% of a developer's time is spent reading and understanding code, not writing it
2-4 weeks is the average onboarding time to a medium codebase for a senior developer
$15K-$30K in lost productivity for every developer who does manual onboarding
5-10x is the measured acceleration when a systematic method with AI is applied

These aren't theoretical numbers — they're the result of measuring real onboardings across development teams of different sizes.

The Industry Context

Why now?

Onboarding was always a problem. But until recently, there was no alternative: you read code, asked colleagues, and eventually built a mental model. That changed:

2022: GitHub Copilot leaves beta -> developers experiment with AI to write code
2023: ChatGPT/Claude generate complex code -> mass adoption in companies
2024: AI generates 30%+ of new code in teams that use these tools
2025: Claude Code launches 200K context windows -> analyzing full codebases becomes possible
2026: Claude Code with Opus reaches 1M tokens -> onboarding medium codebases in one session

AI's ability to read code evolved as fast as its ability to write it. But most developers didn't notice because they were focused on the writing side.

The emerging skill gap

There are two types of developers in 2026:

Type A	Type B
Uses AI only to generate code	Uses AI to read AND generate code
Onboarding: 2-4 weeks	Onboarding: 2-4 hours
Depends on mentors to understand codebases	Autonomous with Claude Code
Productivity starts in week 4	Productivity starts on day 1
Individual understanding (doesn't document)	Shared understanding (generates docs)

Type B isn't a "better developer." It's a developer with the same talent who uses a tool more effectively. This module moves you from Type A to Type B.

Real use cases

These are scenarios where onboarding with AI has immediate impact:

Consulting and freelancing. You enter a new project every 1-3 months. Your onboarding speed is directly proportional to your income. A consultant who understands the codebase in 2 hours vs 2 weeks can charge for value delivered, not for time sitting there.
Open source contributions. You want to contribute to a project but the barrier to entry is understanding the codebase. With Claude Code, you can understand a project like httpx or FastAPI in an hour and make your first informed PR.
Team rotation. In large companies, developers rotate between teams every 6-12 months. Without a method, each rotation is a reset. With a method, each rotation is a predictable process of a few hours.
Technical due diligence. You need to evaluate the technical state of a codebase (acquisition, hiring a team, refactor vs rewrite decision). With Claude Code, you can have an assessment in hours.
Incident response. A service fails at 3am. It's not your service. You need to understand the codebase enough to diagnose and mitigate. With Claude Code, you can do emergency onboarding in minutes.

Self-diagnosis: Where Are You Today?

Before moving on, ask yourself these questions honestly. There are no right answers — the goal is to know your starting point.

Quick 5-question test

1. When you're assigned a new codebase, what do you do first?

(a) I open random files and start reading
(b) I read the README and the documentation
(c) I have a systematic method (questions in order)
(d) I ask a colleague to explain it to me

2. How long did it take you last time to understand a new project?

(a) Days
(b) 1-2 weeks
(c) 3-4 weeks
(d) I never felt I understood it completely

3. Do you use Claude Code to understand existing code?

(a) No, only to generate new code
(b) Sometimes, for specific questions
(c) Yes, regularly to explore codebases
(d) I don't use Claude Code

4. When you finish exploring a codebase, what do you produce?

(a) Nothing — the understanding is in my head
(b) Some personal notes
(c) A document another developer could use
(d) I hadn't thought about producing anything

5. Can you explain your current project's data flow without looking at the code?

(a) More or less — the main flows, yes
(b) Yes, in detail
(c) I'm not sure about some flows
(d) No, I'd have to review it

Interpretation

Mostly (a) or (d): You're starting out. This module will give you a complete method you didn't have.
Mostly (b): You have intuition but no structure. The 5-question framework will give it shape.
Mostly (c): You already have a solid base. This module will formalize it and speed it up with Claude Code.

It doesn't matter where you are — what matters is that by the end of this module you'll have a concrete, proven method.

The common denominator

Regardless of your answers, there's something that applies to everyone: nobody taught you a systematic method to explore codebases. You learned it by trial and error, copied what you saw others do, or simply dove into the code and hoped for the best.

This module gives you what university, bootcamps, and most tutorials leave out: a structured framework for understanding someone else's code. It isn't intuitive — it's methodical. It doesn't depend on your experience — it works for juniors and seniors. And with Claude Code, it's dramatically faster than doing it manually.

Key Vocabulary

Before moving on, these are the terms you'll use throughout the module:

Term	Definition
Onboarding	The process of getting familiar with a new codebase — understanding its structure, patterns, data flow, and conventions
Mental model	Your internal representation of how a system works — what components it has, how they interact, where the boundaries are
Entry point	The file or function where the program's execution begins (main.py, app.py, index.js) or where requests come in
Data flow	How data travels through the system — from input to output, passing through transformations
Tech debt	Shortcuts or technical decisions that speed up development today but create problems tomorrow
Codebase exploration	The process of navigating and understanding a code repository in a systematic way
Architecture patterns	Recurring structures for organizing code: MVC, service layer, repository pattern, etc.
Onboarding doc	A document that summarizes the understanding of a codebase so others can understand it faster
Tribal knowledge	Knowledge about the codebase that only exists in people's heads, not in documentation

You don't need to memorize everything now. You'll internalize them as you use them in the hands-on capsules.

Professional Objective

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

Apply a systematic onboarding method using the 5 initial questions: structure, entry points, data flow, patterns, tech debt — in that order, from the big picture to the details.
Explore an unfamiliar codebase with Claude Code by asking in the right sequence: directory structure first, entry points next, data flow, patterns, and finally tech debt.
Build a mental model of the codebase that includes layers, main modules, key dependencies, and the data flow — all in under an hour for a medium codebase.
Document findings by producing an "onboarding doc" that includes a structure overview, key patterns, gotchas, and entry points — a tangible artifact another developer could read.
Validate your understanding by making a small change (fix a typo, add a test, document a function) and verifying that your mental model is correct.
Measure the difference by comparing how long it took you with Claude Code vs how long it would have taken manually, with concrete metrics.

The shift in perspective

You enter this module knowing how to use Claude Code to generate new code. You leave knowing that Claude Code is just as powerful — maybe more — for reading and analyzing existing code. This shift in perspective is the central insight: Claude Code isn't just a writer, it's an exceptional reader.

Why this matters for your career

Understanding existing code isn't a "junior" skill. It's the skill that consumes the most time for developers at any level:

Junior: Joins a team, needs to understand the codebase to be productive
Mid-level: Changes projects every 6-12 months, needs fast onboarding
Senior: Reviews others' PRs, needs to understand the context quickly
Tech Lead: Evaluates the architecture of projects they didn't write
Consultant: Enters unfamiliar projects constantly, charges for speed

In every case, onboarding speed determines the speed of everything else. If you can understand a codebase in hours instead of weeks, you're 5-10x more effective from day one.

Module Progression

Module Map

Capsule	Topic	What you'll learn
02	The Cost of Manual Onboarding	Why onboarding takes 2-4 weeks, how much it costs in productivity, and how AI transforms the equation. First demo with Claude Code
03	Systematic Exploration with Claude Code	The 5 initial questions, why order matters, practical prompts for each question. Complete exploration framework
04	Building the Mental Model	How to build your mental model: layers, modules, dependencies, data flow. Techniques to visualize and validate understanding
05	Documenting Findings — The Onboarding Doc	Producing a tangible artifact: structure overview, patterns, gotchas, entry points. Documentation others can use
06	Project: Onboarding to an Open-Source Codebase	Integrative mini-project: explore a real project, document, make a small change, measure the difference

Learning flow

Capsule 02: The Problem          Capsule 03: The Method
(why it's slow)              ->  (5 questions, order, prompts)
        |                                 |
        v                                 v
Capsule 04: The Mental Model     Capsule 05: The Document
(layers, dependencies, flow) ->  (tangible onboarding doc)
        |                                 |
        +----------------+---------------+
                         v
                 Capsule 06: The Project
           (all together in a real codebase)

Each capsule builds on the previous one. Capsules 02-03 establish the "why" and the "how." Capsules 04-05 produce concrete outputs. Capsule 06 integrates everything into real practice.

The module's narrative

First you'll understand the problem with real numbers — how much manual onboarding costs and why it's so slow (capsule 02). Then you'll learn the systematic method: the 5 questions you need to ask and in what order (capsule 03). With that method, you'll build a mental model of the codebase — not just "you understand it," but you have a clear representation in your head (capsule 04). Then you'll turn that mental model into a tangible document others can use (capsule 05). Finally, you integrate everything into a real project with an open-source codebase (capsule 06).

The progression is intentional: you can't document what you don't understand, you can't understand without a method, and you can't appreciate the method without knowing the cost of not having it.

Connection with the Project

Module mini-project: Onboarding to an open-source codebase

In capsule 06 you're going to take a real open-source project (suggested: a medium-sized Python project like httpx, typer, FastAPI, or similar), explore it with Claude Code using the systematic method, document your understanding, and make a small change (fix a typo, add a test, document a function).

The focus isn't the change — it's the speed and depth of the onboarding.

What you'll deliver:

✅ A complete onboarding doc for the chosen codebase
✅ A documented mental model (structure, patterns, data flow)
✅ A small change that demonstrates understanding
✅ A measurement: real time vs estimated manual time

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

Module 8 is a Full Migration of a Legacy Project. The onboarding you learn here is the mandatory first step of that migration. You can't migrate what you don't understand. The pattern for the whole guide is established in this module: understand first, modify later.

Module 1: Onboarding -> understand the codebase          -+
Module 2: Explore -> investigate in depth                 |
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                   -+

Limits: What We WON'T Do

To stay focused and avoid scope creep, this module has clear limits:

❌ You won't modify code significantly. The change in capsule 06 is deliberately small. Modifying code comes in modules 4-7.
❌ You won't use the Explore subagent. That's Module 2. Here you use Claude Code directly.
❌ You won't generate dependency maps or formal architecture diagrams. That's Module 3. Here you build a more informal mental model.
❌ You won't work with extremely large codebases (100K+ lines). Context management comes in Module 6. Here you work with medium codebases (5K-30K lines).
❌ You won't cover UI or frontend refactoring. The scope of the guide is backend/Python.
❌ You won't set up CI/CD or pipelines. That's covered in Guide #10 of the path.

What we do cover in depth:

✅ A systematic exploration method with the 5 questions
✅ Claude Code as a reading and analysis tool
✅ Documentation as the output of onboarding
✅ Validating understanding with small changes
✅ Measuring the impact (AI vs manual time)

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 list the 5 initial questions in order	Without looking at notes, you recite: structure, entry points, data flow, patterns, tech debt
You can explore an unfamiliar codebase in < 1 hour	Timer from zero to a documented mental model on a medium codebase
You produce an onboarding doc with the right sections	The document includes: overview, structure, entry points, patterns, data flow, gotchas
You make a small change informed by your understanding	The change demonstrates that you understand where and why to modify
You can articulate the AI vs manual difference	You have a concrete number: "It took me X minutes with Claude Code; it would have taken Y hours manually"

Excellence criteria (optional):

✅ Your onboarding doc is good enough for another developer to read it and understand the codebase
✅ You identified at least one gotcha or quirk of the codebase that isn't obvious in the official documentation
✅ Your small change includes a test or documentation improvement, not just a typo fix

What success looks like in practice

Before this module:

New codebase -> Open random files -> Read README
-> Try to run it -> Get confused -> 2-4 weeks

After this module:

New codebase -> Claude Code: structure? -> Entry points?
-> Data flow? -> Patterns? -> Tech debt?
-> Mental model in 1-2 hours -> Onboarding doc -> Validate with a change

The difference isn't just speed — it's depth. With the systematic method, you don't miss things that random exploration skips. And with the onboarding doc, your understanding benefits the whole team.

The final validation question:

If someone gives you a 10K-line codebase you've never seen and says "you have one hour to understand it and explain it to me," can you do it with confidence?

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

How to measure your progress

Keep a log during your first 3 codebase explorations after completing the module. For each one, record:

Metric	What to measure
Total time for the 5 questions	From the first question to having a basic mental model
Onboarding doc quality	Ask a colleague to read it — do they understand the project?
Change validation	Did your small change work on the first try? (Yes = good mental model)
Comparison with manual	How long would it have taken you without Claude Code? Estimate honestly

After 3 explorations, you'll see your personal pattern: where you're faster, what kind of questions give you the best information, and where you need to dig deeper. That calibration is the real output of this module.

Module Prerequisites

Required knowledge:

✅ Basic Claude Code (guides #1-6 of the path): knowing how to invoke Claude Code, write prompts, work in the terminal
✅ Testing with Claude Code (guide #7): understanding what tests are and how to run them (you'll use them to validate)
✅ Intermediate Python: reading Python code without difficulty (you don't need to be an expert, but you should be fluent)
✅ Basic Git: cloning repos, viewing history, creating branches

You don't need:

❌ Experience with the codebase you're going to explore — the point is that it's unfamiliar
❌ Knowledge of every framework — they're explained in context
❌ Previous refactoring experience — that comes later
❌ A project of your own — you'll use open-source projects

Technical setup:

Tool	What for
Claude Code installed and configured	Code exploration and analysis
Terminal with Git access	Cloning repos, viewing history
Text editor	Creating documentation (onboarding doc)
Internet connection	Cloning open-source projects

Quick setup check

# Check Python
python --version
# Expected: Python 3.10+

# Check Claude Code
claude --version
# Expected: installed version

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

# Check that you can clone
git clone --depth 1 https://github.com/encode/httpx /tmp/httpx-test
# Expected: clones without errors

If something doesn't work, review Guides 1-4 before continuing. This module assumes your environment is ready.

The Core Principle

Understand before you modify

This principle should stick from the very first capsule. It isn't a suggestion — it's a professional imperative:

Every minute invested in comprehension saves hours of debugging.

The most expensive mistake in software development isn't a syntax bug or a failing test. It's modifying code you don't understand. You produce a fix that seems to work, but it breaks something three levels down that you didn't know existed. You spend hours debugging a problem you created yourself because you didn't understand the system.

With Claude Code, comprehension is no longer a bottleneck. You can ask "how does data flow from the /users endpoint to the database?" and get an answer that maps the whole flow in seconds. You can ask "what patterns are used in this codebase?" and get an analysis that would have taken you days to discover manually.

Claude Code is an exceptional reader

Most developers only use Claude Code to write code. That's a legitimate use, but an incomplete one. Claude Code is just as powerful — maybe more — for reading code:

Claude Code as Writer	Claude Code as Reader
Generates new code	Analyzes existing code
Creates functions and classes	Explains functions and classes
Writes tests	Identifies which tests are missing
Produces documentation	Discovers undocumented patterns

This module teaches you to use Claude Code in its reader role. When you master both roles — writer and reader — you'll have a tool that covers the full cycle of software development.

The method matters more than the tool

The 5 initial questions you'll learn work with or without AI. They're an onboarding framework any developer should follow. But with AI, they go 5-10x faster. The method is portable: if tomorrow you use another tool, the questions are still the same. What changes is the speed of getting answers.

What Comes After This Module

Module 2: Agentic Research with the Explore Subagent

The direct transition: "You already know how to explore a codebase with Claude Code directly. Now learn the tool designed specifically for investigation: the Explore subagent."

The Explore subagent has features that make it ideal for exploration:

Read-only: It can't modify anything. You can investigate without fear of breaking something.
Semantic search: It finds code by meaning, not just by text. "Where is authentication handled?" without knowing the function's name.
Optimized for investigation: It's designed to search, read, and answer questions about code.

The method you learn in Module 1 is amplified by the tool in Module 2. First the mental framework, then the specialized tool.

Module 3: Understand an Existing Architecture

After the Explore subagent, the next step is to deepen the understanding to the architectural level. Module 3 teaches you to generate visual and textual representations of the architecture:

Dependency maps: Which module depends on which. Dependency graphs generated by Claude Code.
Flow analysis: Follow a request from the entry point to the response, with all the intermediate steps.
Pattern identification: Recognize MVC, repository pattern, service layer, and other common patterns.
Anti-pattern detection: Identify circular dependencies, god objects, and spaghetti code.

The progression of all of Phase 1:

Module 1: "I understand the codebase" (fast onboarding)
    |
    v
Module 2: "I can investigate in depth" (explore subagent)
    |
    v
Module 3: "I can visualize and explain the architecture" (maps + diagrams)

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

Estimated Time Distribution

Capsule	Estimated time	Main activity
01 (this one)	10-15 min	Reading: module objectives and context
02	15-20 min	Reading + exercises: the cost of manual onboarding
03	20-25 min	Reading + exercises: systematic exploration
04	15-20 min	Reading + exercises: building a mental model
05	15-20 min	Reading + exercises: documenting findings
06	30-45 min	Project: onboarding to an open-source codebase
Total	~1.75-2.5 hrs

The module is designed to be completed in one long session or two short ones. If you need to split it, the natural pause point is after capsule 03 (the 5 initial questions).

Summary

✅ This module opens the guide because understanding existing code is the most fundamental skill for refactoring
✅ Manual onboarding takes 2-4 weeks; with Claude Code and a systematic method, it drops to hours
✅ The 5 initial questions: structure, entry points, data flow, patterns, tech debt — in that order
✅ Claude Code isn't just a writer — it's an exceptional reader that analyzes full codebases
✅ The core principle: understand before you modify. Every minute of comprehension saves hours of debugging
✅ The output isn't "now I understand it" — it's a tangible onboarding doc others can use
✅ The module project: onboarding to an open-source codebase with a measurement of AI vs manual time
✅ This module establishes the pattern for the whole guide: understand first, modify later

Additional Resources

Working Effectively with Legacy Code — Michael Feathers — The reference book on working with legacy code. Establishes the principle of tests before changes.
Claude Code Documentation — Anthropic — Official Claude Code documentation with code analysis features.
The Pragmatic Programmer — Hunt & Thomas — Chapters on understanding existing systems and the importance of domain knowledge.
Refactoring — Martin Fowler — The catalog of refactoring patterns. Conceptual context for what's coming in later modules.
Software Design X-Rays — Adam Tornhill — Codebase analysis using VCS data. Complements analysis with AI.
Understanding Legacy Code — Nicolas Carlo — A blog with practical techniques to understand and improve legacy code.
Awesome Onboarding — GitHub — Resources on onboarding developers to software projects.

Next capsule: The Cost of Manual Onboarding and Why AI Transforms It — why we take weeks to understand a codebase, how much it costs in productivity, and how Claude Code changes the equation.

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

Next →The Cost of Manual Onboarding and Why AI Transforms It