Systematic Exploration — What to Ask and In What Order

Capsule description

In the previous capsule you saw the numbers: manual onboarding costs $15K-$30K per developer and takes weeks. You saw how Claude Code can answer questions about a codebase in seconds. But there's a problem: if you ask questions at random, you get random answers. You understand fragments but not the system. It's like reading an encyclopedia by opening pages at random — you learn scattered facts but don't build comprehension.

This capsule gives you the method that turns those scattered questions into a systematic framework. The 5 initial questions — structure, entry points, data flow, patterns, tech debt — aren't an arbitrary list. They're ordered from the most general to the most specific, and each answer gives you the context you need for the next question. It's the difference between exploring a building starting from the floor plan vs starting from the third-floor bathroom.

By the end of this capsule you'll have a complete exploration framework you can apply to any codebase. You'll know exactly what to ask, in what order, and why that order matters. And you'll have the Claude Code prompts ready to copy and use starting tomorrow.

Why Order Matters

The random exploration trap

When a developer enters a new codebase without a method, the typical exploration looks like this:

1. Opens the file that sounds most interesting (payment_service.py)
2. Sees imports from 5 modules -> opens one at random (stripe_client.py)
3. Sees a complex class -> gets lost in the details
4. Remembers they wanted to understand payments -> goes back to payment_service.py
5. Sees an unfamiliar decorator -> looks up its definition
6. 30 minutes later: understands the decorator but lost the thread
7. Opens another interesting file (auth_middleware.py)
8. Repeats the cycle

After 2 hours, you have fragmented knowledge: you know Stripe is used for payments, that there's JWT for auth, and that a decorator caches results. But you can't answer basic questions: "how is the project organized?" or "how does the data flow?"

Systematic exploration

With a method, exploration looks like this:

1. Structure: what folders exist, how it's organized       (2 min)
2. Entry points: where execution starts, how requests come in (3 min)
3. Data flow: how data travels from input to output        (5 min)
4. Patterns: what conventions and designs repeat           (5 min)
5. Tech debt: where the problems and risks are             (5 min)

In 20 minutes you have a coherent mental model. Not fragments — a map. You can explain the project to another developer. You can identify where to dig deeper.

The GPS analogy

Imagine you arrive in a new city. There are two ways to get to know it:

Random: You walk down random streets. You discover a good restaurant, a nice park, a weird alley. After 3 hours, you know disconnected fragments.

Systematic: First you look at the map (structure). You identify the cardinal points and main avenues (entry points). You understand how the traffic flows (data flow). You notice there's a historic neighborhood and a modern one (patterns). You identify areas under construction (tech debt). After 30 minutes with the map, you know the city better than after 3 hours of walking at random.

The systematic method isn't slower — it's dramatically faster and produces better comprehension.

The 5 Initial Questions

These are the 5 questions you should ask every time you enter a new codebase, in this exact order. Each question builds on the answer to the previous one.

Question 1: Structure

What you ask: How is this project organized? What folders exist and what does each one do?

Why it's first: You need the map before exploring the territory. Without understanding the organization, every file you open will be an isolated data point without context.

Prompt for Claude Code:

claude

> I just cloned this project and I've never seen it. Describe the 
  directory structure to me: what main folders there are, what 
  each one contains, and what architecture pattern the project follows.

Expected output:

Project structure (FastAPI API for e-commerce):

src/
+-- api/              -> HTTP endpoints (organized by resource)
|   +-- v1/           -> API version 1
|   |   +-- products.py   -> Product CRUD
|   |   +-- orders.py     -> Order management
|   |   +-- users.py      -> Registration and profile
|   |   +-- auth.py       -> Login, tokens
|   +-- deps.py       -> Shared dependencies (DB session, auth)
+-- models/           -> SQLAlchemy models (ORM)
+-- schemas/          -> Pydantic schemas (input/output validation)
+-- services/         -> Business logic
+-- repositories/     -> Database access
+-- core/             -> Configuration, security, middleware
+-- migrations/       -> Alembic (DB migrations)
tests/                -> Tests with pytest
docker-compose.yml    -> Development setup (PostgreSQL, Redis)
pyproject.toml        -> Dependencies and config

Pattern: Layered Architecture with Service Layer + Repository Pattern

What you get: A mental map of the project. Now you know it's a FastAPI project, it uses layers (api -> services -> repositories), it has API versioning, and it uses Docker for development.

Question 2: Entry Points

What you ask: Where does execution start? How do requests enter the system?

Why it's second: You already know the structure (question 1). Now you need to know where information "enters" the system. Without this, you can't trace data flows.

Prompt for Claude Code:

> What's this application's entry point? How is it started? 
  How are the endpoints registered? Show me the flow from 
  startup to when an endpoint is ready to receive requests.

Expected output:

Entry point: src/main.py

Startup flow:
1. main.py creates the FastAPI() instance
2. Registers middleware:
   - CORSMiddleware (allowed origins from config)
   - RequestLoggingMiddleware (custom, in core/middleware.py)
   - ErrorHandlerMiddleware (custom, handles global exceptions)
3. Includes routers:
   - app.include_router(products.router, prefix="/api/v1/products")
   - app.include_router(orders.router, prefix="/api/v1/orders")
   - app.include_router(users.router, prefix="/api/v1/users")
   - app.include_router(auth.router, prefix="/api/v1/auth")
4. Startup event:
   - Connects to PostgreSQL (via SQLAlchemy async)
   - Connects to Redis (for cache and rate limiting)
   - Runs a health check
5. Started with: uvicorn src.main:app --host 0.0.0.0 --port 8000

The routers use Depends() to inject:
- get_db() -> database session
- get_current_user() -> authenticated user (JWT)

What you get: You know exactly where everything starts (main.py), how the pieces connect (routers, middleware, startup events), and how it's run. Now you can trace any data flow from its origin.

Question 3: Data Flow

What you ask: How does data travel from when it enters the system until it leaves?

Why it's third: You already know the structure (question 1) and the entry points (question 2). Now you can trace how data flows through the layers you identified. Without the two previous questions, this analysis would have no context.

Prompt for Claude Code:

> Take the most important flow in this application — creating 
  an order (or the main flow if there are no orders). Trace 
  step by step how the data travels from the HTTP request to 
  when it's persisted. Include validations, transformations, and 
  error handling at each step.

Expected output:

Flow: POST /api/v1/orders (create order)

1. REQUEST ENTRY (api/v1/orders.py:create_order)
   Input: OrderCreateSchema {
     product_ids: list[int],
     quantities: list[int], 
     shipping_address_id: int
   }
   -> Pydantic validates: correct types, non-empty lists
   -> Depends(get_current_user) verifies JWT and extracts user_id

2. SERVICE LAYER (services/order_service.py:create_order)
   -> Validates that all product_ids exist (via product_repo)
   -> Checks available stock for each product
   -> Computes total price (product.price * quantity for each item)
   -> Applies discounts if there's an active coupon (via coupon_service)
   -> Creates an OrderModel instance with status="pending"

3. REPOSITORY LAYER (repositories/order_repo.py:create)
   -> session.add(order)
   -> session.add_all(order_items)  # individual items
   -> session.commit()
   -> session.refresh(order)

4. POST-CREATION (services/order_service.py:_post_create)
   -> Decrements stock (via product_repo.decrement_stock)
   -> Sends an event to Redis (for async notifications)
   -> Audit log (via audit_service)

5. RESPONSE (api/v1/orders.py)
   -> Returns OrderResponseSchema (includes items, total price, status)

POSSIBLE ERRORS:
- 422: Pydantic validation (empty product_ids, incorrect types)
- 404: Product not found
- 409: Insufficient stock
- 401: Invalid or expired JWT token
- 500: DB error (handled by ErrorHandlerMiddleware)

What you get: You understand how data is transformed through the system. You see the complete chain: request -> validation -> business logic -> persistence -> side effects -> response. This is the knowledge that takes the most time to acquire manually.

Question 4: Patterns

What you ask: What design patterns and conventions are used consistently?

Why it's fourth: You already understand the structure (1), the entry points (2), and the data flow (3). Now you can identify the patterns because you have enough context to recognize what's a pattern vs what's an isolated case.

Prompt for Claude Code:

> What design patterns and conventions are used in this project? 
  Include: architecture patterns, naming conventions, how 
  errors are handled, how tests are organized, and any convention 
  a new developer should follow. Note whether there are inconsistencies.

Expected output:

DESIGN PATTERNS:

1. Repository Pattern
   - Each entity has its repository in repositories/
   - Interface: create(), get(), get_by_id(), update(), delete(), list()
   - Example: UserRepository, ProductRepository, OrderRepository

2. Service Layer
   - Business logic in services/
   - Endpoints NEVER access repositories directly
   - Example: OrderService validates stock before creating an order

3. DTO Pattern (via Pydantic)
   - schemas/ contains Create, Update, Response per entity
   - Naming: {Entity}CreateSchema, {Entity}ResponseSchema
   - Response schemas NEVER expose sensitive fields (password, tokens)

4. Dependency Injection (native FastAPI)
   - Depends(get_db) for the DB session
   - Depends(get_current_user) for authentication
   - Depends(get_pagination) for pagination parameters

NAMING CONVENTIONS:
- Files: snake_case (user_service.py, product_repo.py)
- Classes: PascalCase (UserService, OrderCreateSchema)
- Functions: snake_case (create_order, get_by_email)
- Constants: UPPER_SNAKE (MAX_PAGE_SIZE, DEFAULT_TIMEOUT)

ERROR HANDLING:
- Custom exceptions in core/exceptions.py
- NotFoundError, ConflictError, PermissionError
- ErrorHandlerMiddleware converts them to HTTP responses

TESTING:
- tests/ mirrors src/ (tests/services/test_order_service.py)
- Shared fixtures in conftest.py
- Factory pattern to create test data (tests/factories/)

INCONSISTENCIES DETECTED:
- reports/ module doesn't follow service->repository pattern
- 2 endpoints in users.py access the DB directly (no service)

What you get: The project's "rules of the game." When you make your first change, you'll know which patterns to follow, what naming to use, and where the inconsistencies you should avoid replicating are.

Question 5: Tech Debt

What you ask: Where are the problems, risks, and technical debt?

Why it's last: You need to understand how the system works (questions 1-4) before you can evaluate what's wrong. Without that context, you can't tell the difference between "this is tech debt" and "this is an intentional design decision."

Prompt for Claude Code:

> Identify tech debt and possible problems in this codebase. Look for: 
  pending TODOs, duplicated code, inconsistent patterns, 
  outdated dependencies, code smells, and anything a 
  new developer should know to avoid surprises.

Expected output:

TECH DEBT IDENTIFIED:

1. PENDING TODOs (9 found):
   - services/payment.py:45  "# TODO: add retry logic for Stripe"
   - services/email.py:12    "# TODO: make async"
   - models/user.py:8        "# TODO: migrate to UUID as PK"
   - api/v1/products.py:67   "# TODO: add real pagination"
   ... (5 more)

2. DUPLICATED CODE:
   - Pagination logic copied across 4 endpoints
     (products.py, orders.py, users.py, reviews.py)
     -> Should be a shared dependency or utility
   - Permission validation repeated in 3 services
     -> Should be a decorator or middleware

3. INCONSISTENT PATTERNS:
   - reports/ accesses the DB directly (doesn't use repository)
   - 2 endpoints in users.py bypass the service layer
   - Some responses use dict, others use schemas

4. OUTDATED DEPENDENCIES:
   - SQLAlchemy 1.4.x (current: 2.0) — non-trivial migration
   - pydantic v1 (current: v2) — significant migration
   - fastapi 0.95 (current: 0.110+)

5. SECURITY CONCERNS:
   - Rate limiting only on auth endpoints (should be global)
   - No upload size validation in the files endpoint
   - CORS accepts * in development (verify production)

6. DEAD CODE:
   - utils/legacy_helpers.py — no file imports it
   - models/deprecated_user.py — not referenced
   - tests/test_old_auth.py — tests for a removed auth system

SUGGESTED PRIORITY:
High: #5 (security), #4 (pydantic v1 → v2)
Medium: #2 (duplication), #3 (inconsistencies)
Low: #1 (TODOs), #6 (dead code)

What you get: A map of risks. You know what NOT to touch carelessly (security concerns), what areas need improvement (duplication), and what you can ignore for now (dead code). This knowledge prevents you from accidentally making the existing tech debt worse.

The Difference: Random vs Systematic

Side-by-side comparison

Why random exploration fails

Random exploration has three fundamental problems:

1. Bias toward the interesting. You open the files that sound most interesting, not the most important ones. payment_service.py sounds exciting, but main.py gives you more information about the system.

2. Rabbit holes. Each file leads you to another, which leads you to another. You never return to the big picture level. It's like trying to understand a country by visiting a single neighborhood in depth.

3. No frame of reference. Without knowing the general structure, every fact you learn is a floating point with no connection. You know that "Stripe is used" but you don't know in what layer, how it connects with the rest, or whether it's the only way to process payments.

Advanced Prompts for Each Question

Structure — variations by context

For a new project you just cloned:

claude

> I just cloned this project and I've never seen it. Describe the 
  complete structure to me. For each main directory, tell me:
  1. What it contains
  2. What responsibility it has
  3. Which other directories it depends on

For a project where you've already spent a few minutes:

> I already saw this project uses FastAPI with SQLAlchemy. Go deeper 
  into the structure: how are the modules organized within each 
  layer? Are there non-obvious sub-modules or internal packages?

For a monorepo or large project:

> This project has many folders. Before getting into details, 
  give me an overview of the top-level directories. What are the 
  main components and how do they relate to each other?

Entry Points — variations by project type

For an API/web app:

claude

> How do requests enter this application? Show me the flow 
  from when an HTTP request arrives to when the handler runs. 
  Include middleware, authentication, and any prior processing.

For a CLI tool:

> What's the entry point of this command-line tool? 
  How are commands registered? Show me the flow from when the 
  user runs the command to when the output is produced.

For a library:

> How is this library used? What's the main public API? 
  What classes or functions does it export and how do they connect to each other?

Data Flow — variations by complexity

Basic flow (CRUD):

claude

> Trace the complete flow of the most common operation in this app 
  (probably a CRUD). From the request to the response, 
  including every file and function involved.

Complex flow (with side effects):

> Trace the flow of the most complex operation in this app. 
  In addition to the main flow, include: side effects (emails, 
  notifications, logs), asynchronous operations, and error 
  handling at each step.

Data flow between services:

> How do the different services in this project communicate? 
  Are there synchronous calls, events, message queues? Show 
  an example of a flow that involves multiple services.

Patterns — variations by depth

Basic identification:

claude

> What design patterns are used in this project? Give me concrete 
  examples with files and lines. Include architectural patterns 
  and code patterns.

Team conventions:

> Beyond the design patterns, what conventions does this 
  team follow? Naming, file structure, how tests are organized, 
  how functions are documented, how configurations are handled.

Consistency:

> Analyze whether the patterns are applied consistently across the whole 
  project. Are there modules that don't follow the general conventions? 
  If there are inconsistencies, which files are they in?

Tech Debt — variations by urgency

General scan:

claude

> Identify tech debt in this project: TODOs, duplicated code, 
  outdated dependencies, code smells, dead code. Prioritize 
  by impact (what should be fixed first).

Security-focused:

> Analyze this project looking for security problems: 
  unvalidated inputs, possible SQL injection, hardcoded secrets, 
  weak authentication, misconfigured CORS, dependencies with 
  known vulnerabilities.

Maintainability-focused:

> What would make this codebase hard to maintain long-term? 
  Look for: excessive coupling, lack of abstractions, functions 
  that are too long, mixed responsibilities, lack of tests.

Adapting the Questions to Different Types of Projects

The 5 questions are universal, but the details change depending on the project type:

For monorepos, add a "Step 0" before the 5 questions:

claude

> Step 0: This is a monorepo. How many packages/services does it contain? 
  What's the relationship between them? Are there shared dependencies?

Then apply the 5 questions to each package/service separately.

The Visual Framework

To help you internalize the method, here's the complete framework in a single view:

Total time: 15-20 minutes. Result: a coherent mental model of the complete codebase.

Connection with the Project

In the module mini-project (capsule 06):

• You'll apply the 5 questions in sequence to a real open-source codebase
• You'll document the answers as part of your onboarding doc
• You'll measure the total time of the 5 questions
• You'll compare it with how long you would have taken manually

In the capstone project (Module 8):

• The 5 questions will be the first step of your legacy project migration
• The onboarding doc you generate will be the base for planning the refactoring
• The quality of your comprehension will determine the quality of the migration

Everything you learn today is used directly in capsule 04 (mental model) and capsule 05 (onboarding doc).

Troubleshooting

Problem 1: "Claude Code gives answers that are too long for the structure questions"

Cause: The project has many subdirectories or Claude Code includes details of individual files.

Solution:

# Limit the scope:
> Describe ONLY the top-level directories of this project 
  (no subdirectories). For each one, one line describing 
  its responsibility.

Problem 2: "I can't find an obvious entry point"

Cause: Some projects don't have an obvious main.py or app.py. It might be a library, a package, or a project with multiple entry points.

Solution:

# Ask for help finding the entry point:
> I don't see an obvious main.py or app.py. Where does execution 
  start in this project? Check pyproject.toml, setup.py, or Makefile 
  to find how it's run.

Problem 3: "The 5 questions give incomplete information for my codebase"

Cause: Very specialized codebases (machine learning, infrastructure, gaming) may need additional questions.

Solution: Add domain-specific questions after the 5 basics:

# For ML projects:
> In addition to the general questions: where are the models? 
  How are they trained? Where are the datasets? How is 
  inference done in production?

# For infrastructure:
> In addition to the general questions: what cloud resources 
  are provisioned? How is deploy done? What monitoring is there?

Problem 4: "Claude Code identifies tech debt that's intentional"

Cause: What looks like tech debt may be a conscious design decision.

Solution:

# Ask for additional context:
> You said reports/ doesn't follow the repository pattern. Is it possible 
  it's intentional? Check whether there are comments, documentation, 
  or commits that explain why it's different.

Problem 5: "The answers to question 3 (data flow) are superficial"

Cause: The question may be too broad, or the flow is complex and Claude Code summarizes too much.

Solution:

# Break it into sub-questions:
> The create-order flow has 5 steps according to your previous answer. 
  Go deeper into step 2 (service layer): what exact validations 
  are done? What exceptions are raised? Show me the relevant code.

Exercises

Exercise 1: Order the questions (Easy)

The following questions are out of order. Order them according to the 5-initial-questions framework and explain why that order is correct:

• "What pending TODOs does this project have?"
• "How does data flow from the endpoint to the DB?"
• "What's the directory structure?"
• "What design patterns are used?"
• "Where's the entry point?"

Exercise 2: Write specific prompts (Easy)

For each of the 5 questions, write a customized prompt for a Django project (instead of FastAPI). Include Django terminology.

# Question 1 — Structure (adapted to Django):
> Describe the structure of this Django project. What apps are there? 
  How are the models, views, URLs, and templates organized? 
  Does it follow the app-per-feature pattern or a different structure?

# Question 2 — Entry Points (adapted to Django):
> What's the entry point? Where's the main urls.py? 
  How are the apps registered in INSTALLED_APPS? Show me 
  the flow from settings.py to when a URL pattern is ready.

# Question 3 — Data Flow (adapted to Django):
> Trace the flow of a POST request to this app's most important 
  form: from the URL, through the view, the form, 
  the model, and until it's saved in the DB. Include signals 
  if any are involved.

# Question 4 — Patterns (adapted to Django):
> What patterns does this project use? CBVs or FBVs? Django REST Framework? 
  Are there custom mixins? How are the serializers organized? What 
  naming conventions are followed? Does it use management commands?

# Question 5 — Tech Debt (adapted to Django):
> What tech debt do you see? Pending migrations? Models with 
  deprecated fields? Views that don't use the ORM correctly (N+1 queries)? 
  Hardcoded settings that should be in env vars?

Exercise 3: Real exploration with the 5 questions (Medium)

Clone an open-source project you've never seen and apply the 5 questions in order. Time each question.

Suggested projects:

• httpx — HTTP client (medium)
• typer — CLI framework (small)
• rich — Terminal formatting (medium-large)

git clone https://github.com/encode/httpx.git
cd httpx
claude

Record your results in this format:

Project: [name]
Date: [date]
Question 1 (Structure): [time] — [main finding]
Question 2 (Entry Points): [time] — [main finding]
Question 3 (Data Flow): [time] — [main finding]
Question 4 (Patterns): [time] — [main finding]
Question 5 (Tech Debt): [time] — [main finding]
Total: [total time]

Project: httpx
Date: 2026-04-05
Question 1 (Structure): 2 min — Library organized in httpx/ with 
  modules by responsibility (_client.py, _transports/, _models.py).
  Comprehensive tests in tests/. Docs in docs/.
Question 2 (Entry Points): 2 min — The public API is httpx.Client (sync) 
  and httpx.AsyncClient (async). __init__.py exports the main classes.
  There are also convenience functions: httpx.get(), httpx.post(), etc.
Question 3 (Data Flow): 4 min — httpx.get(url) creates a temporary Client,
  builds a Request object, passes it to the transport layer (httpcore),
  httpcore handles the connection/HTTP, returns a Response that httpx wraps
  in httpx.Response with convenience methods (.json(), .text, etc.)
Question 4 (Patterns): 4 min — Transport abstraction (pluggable backends),
  context manager pattern (with Client()), builder pattern for requests,
  sync/async mirror (same API, different implementation).
Question 5 (Tech Debt): 3 min — Low technical debt (well-maintained 
  project). Some minor TODOs. Complexity in handling 
  HTTP/2 vs HTTP/1.1. _decoders.py has complex logic that could
  be simplified.
Total: 15 minutes

Equivalent manual estimate: 3-5 hours of reading code
Acceleration factor: ~12-20x

Exercise 4: Detect random exploration (Medium)

A colleague describes their onboarding session to a new project:

"First I opened the Stripe configuration file because I was assigned a payments bug. I saw it imported from payment_processor.py so I opened that. I saw a TODO about retry logic and started investigating retry patterns. After an hour I looked into how to implement the circuit breaker pattern because it seemed interesting. By the end of the day, I understood the payment system well but I don't know how the rest of the project is organized."

Identify: what did they do wrong? How would you apply the 5-questions framework to them?

# Before touching Stripe, ask the 5 questions:

# 1. Structure
> How is this project organized? What modules are there?
# Result: "Ah, payments is just 1 of 8 modules."

# 2. Entry points
> How do requests enter? Where's the main router?
# Result: "Payments start from the checkout endpoint."

# 3. Data flow
> How does a payment flow from when the user clicks to when 
  it's confirmed? Include all the services involved.
# Result: "Checkout -> payment_service -> stripe_client -> webhook handler."

# 4. Patterns
> What patterns are used for external integrations like Stripe?
# Result: "They use the adapter pattern. Stripe is swappable."

# 5. Tech debt
> What problems are there in the payments module specifically?
# Result: "The retry logic TODO is the only critical tech debt."

# AFTER the 5 questions, now yes: 
# dig into the specific bug with complete context.

Exercise 5: Create prompt variations (Advanced)

For Question 3 (Data Flow), write 3 prompt variations for different levels of depth:

1. Surface level: Overview of the main flow
2. Intermediate level: Detailed flow with validations and errors
3. Deep level: Complete flow with code, side effects, and edge cases

# SURFACE LEVEL (quick overview, 1-2 min):
> Give me a high-level overview: when a user creates an order, 
  which services are involved and in what order? Just names of 
  files and main functions, no implementation details.

# Expected output: "orders.py -> order_service.py -> product_repo.py 
# -> order_repo.py. It involves stock validation and price calculation."


# INTERMEDIATE LEVEL (detailed, 3-5 min):
> Trace the complete order creation flow: from the HTTP request 
  to the commit in the DB. For each step include: what function is 
  called, what validations are done, what errors can occur, and 
  what data transformations happen.

# Expected output: Each step with validations, transformations, 
# and possible errors. ~15-20 lines of detail.


# DEEP LEVEL (complete, 5-10 min):
> I need to understand in depth how order creation 
  works. For each step of the flow, show me: the relevant code 
  (not the whole file, only the key lines), the side effects 
  (emails, notifications, logs, events), the edge cases that 
  are handled, and the ones that are NOT handled but should be. Also 
  include how rollback is done if something fails mid-process.

# Expected output: Real code interleaved with explanation.
# Edge cases documented. Gaps in error handling identified.

Exercise 6: Custom framework (Advanced)

Design your own extension of the 5-questions framework by adding 2-3 additional questions specific to your work domain. For each additional question, define:

1. The question
2. Why you need it in your context
3. After which of the 5 original questions you'd ask it
4. The prompt you'd use with Claude Code

# Extensions to the 5-questions framework for fintech

additional_questions = {
    "6_compliance": {
        "question": "How does this system handle compliance and auditing?",
        "why": "In fintech, every transaction must be auditable. "
               "I need to know where the audit logs are, how "
               "transactions are tracked, and which regulations apply.",
        "after": "Question 4 (Patterns) — I need to know the "
                 "general patterns to understand whether compliance "
                 "is integrated or is an add-on.",
        "prompt": "How does this project handle auditing and compliance? "
                  "Are there audit logs? How are transactions tracked? "
                  "Is it recorded who did what and when? Is there "
                  "encryption of sensitive data (PII, PCI)?"
    },
    "7_error_recovery": {
        "question": "What happens when something fails mid-transaction?",
        "why": "In fintech, a partial transaction can mean "
               "lost money. I need to know what recovery "
               "mechanisms exist.",
        "after": "Question 3 (Data Flow) — I need to understand the "
                 "complete flow to evaluate where it can fail.",
        "prompt": "What error recovery mechanisms are there for "
                  "financial transactions? Are there sagas, compensating "
                  "transactions, or idempotency keys? What happens if "
                  "the process fails mid-payment?"
    },
    "8_testing_critical_paths": {
        "question": "How are the critical flows (payments, transfers) tested?",
        "why": "Bugs in money flows are the most expensive. "
               "I need to know how well they're covered by tests.",
        "after": "Question 5 (Tech Debt) — to know whether the lack "
                 "of tests in critical areas is known tech debt.",
        "prompt": "What test coverage do the payment and transfer flows "
                  "have? Are there integration tests? Is it tested "
                  "against the Stripe/processor sandbox? Which edge "
                  "cases are covered and which aren't?"
    }
}

for key, question in additional_questions.items():
    number = key.split("_")[0]
    print(f"\nQuestion {number}: {question['question']}")
    print(f"  Why: {question['why'][:80]}...")
    print(f"  After: {question['after'][:60]}...")

Summary

In this capsule you learned:

• ✅ Random exploration produces fragmented knowledge; systematic exploration produces coherent comprehension
• ✅ The 5 initial questions are: structure, entry points, data flow, patterns, tech debt — in that order
• ✅ Order matters: each question needs the previous answers as context
• ✅ Claude Code accepts specific prompts and produces detailed answers for each question
• ✅ The 5 questions adapt to different types of projects (APIs, libraries, CLIs, monorepos)
• ✅ The total time of the complete framework is 15-20 minutes — vs 1-2 weeks manually
• ✅ Prompts can be varied in depth (surface, intermediate, deep) depending on the need
• ✅ The framework is extensible: you can add questions specific to your domain

Next capsule: Building the Mental Model — how to turn the answers of the 5 questions into a coherent mental model of the codebase you can consult and share.

Additional Resources

1. Claude Code Documentation — Anthropic — Official documentation with code analysis examples
2. The Art of Reading Code — Felienne Hermans — A book on the science of reading and understanding code
3. Code Reading: The Open Source Perspective — Systematic techniques for reading codebases
4. Working Effectively with Legacy Code — Michael Feathers — The chapter on "understanding the system" is directly relevant
5. httpx — GitHub — Suggested project to practice the 5 questions
6. Design Patterns — Refactoring.Guru — A visual reference of design patterns for question 4
7. Technical Debt — Martin Fowler — A framework for thinking about tech debt (question 5)
8. Software Architecture Patterns — O'Reilly — A reference for identifying architectural patterns

Next capsule: Building the Mental Model — how to build a mental representation of the codebase with Claude Code, including layers, modules, dependencies, and data flow.

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