Most people open an unfamiliar repo and immediately ask Claude Code: "what does this codebase do?" Then they watch it read 15 files, fill the context with raw file contents, and produce a vague summary that contaminates every subsequent turn.
There's a better workflow. It comes directly from understanding how Claude Code's subagent architecture works.
Here's the exact sequence.
Why Most Onboarding Goes Wrong
When you run exploration in the main thread, the results stay in the main context. Every file read, every grep result, every intermediate summary — all of it piles up. By the time you're ready to do actual work, you're 50K tokens in, the model is getting fuzzy on early instructions, and you've burned budget on exploration residue.
The source reveals why: LLM quality degrades as context grows longer. The authors knew this. So they built the AgentTool specifically to isolate exploration in subagents that can't write to the main AppState. Results come back as summaries only.
That's the whole workflow in one sentence: exploration in subagents, synthesis in main, implementation delegated again.
The 4-Phase Breakdown
Phase 1: 0–5 min — Session Setup
Open a new terminal. Start Claude Code from the project root. Before you do anything else, front-load your goal, constraints, and verification criteria into the first prompt. This block becomes the cache prefix — every subsequent call in this session can read it at 10% of base price.
[goal] Understand this repo's architecture. Produce a one-paragraph mental model
I can carry into a README rewrite.
[constraints] Don't modify any files. Read only.
[verification] Must be able to explain: main entry points, core data flow,
external dependencies.
This is not a long prompt. It's a structured one. The difference matters for caching.
While the session is starting, read README.md and CLAUDE.md yourself if they exist. Main thread, two files maximum. This gives you enough orientation to write better subagent prompts in the next phase.
Phase 2: 5–15 min — Parallel Explore Agents
Don't ask "figure out the project structure" in the main thread. That's the mistake. Instead, split exploration into three parallel subagents targeting different questions:
Agent A — Entry Points
Find the main entry points for this codebase. Look for files named
main, index, app, server, or cmd. Read them and return: what is the
top-level execution path? One paragraph.
Agent B — Data Models
Find the core data models. Look for type definition files, schema files,
or model directories. Read the 3–5 most central ones and return: what are
the primary entities and their relationships? One paragraph.
Agent C — Dependencies
Read package.json (or go.mod, requirements.txt, Cargo.toml — whatever's
present). Return: what are the 5–10 most significant external dependencies
and what does each one suggest about the architecture?
Why three separate agents instead of one? Two reasons. First, they run in parallel — you get all three answers in the time it takes the slowest one to finish. Second, each agent gets a fresh context: no cross-contamination, no agents getting confused by each other's intermediate tool calls.
The 3-file rule applies to the main thread here: while the subagents are running, main reads at most 2–3 files directly. Any more than that and you're doing exploration in the wrong place.
Phase 3: 15–25 min — Drawing the Map
When the subagent results come back, synthesize in the main thread. Write one paragraph — literally one paragraph — that captures the mental model:
"Entry point is
src/server.ts. Requests flow through the middleware stack insrc/middleware/to route handlers insrc/routes/, with data access abstracted behind repositories insrc/repos/. External dependencies: Express for routing, Prisma for DB access, Zod for validation. The repo is a REST API with no frontend — all rendering is client-side."
That's the mental model. Write it out explicitly. When you delegate implementation to a subagent in Phase 4, you'll paste this paragraph into the delegation prompt as context. A well-specified delegation prompt is the difference between a subagent that nails it in one shot and one that wanders.
Run /compact now. Ten minutes of parallel exploration has piled up tool call results in context. Clean it before starting actual work. Manual /compact right at this seam is the right pattern.
Phase 4: 25–30 min — First Task
With the mental model in place, start the actual work. The key move: don't implement in the main thread. Delegate to an implementation subagent.
[context] This is a REST API. Entry: src/server.ts. Data access via Prisma
repositories in src/repos/. Validation with Zod.
[goal] Rewrite README.md to accurately describe the architecture.
Use the mental model above as the basis.
[constraints] Only modify README.md. Don't touch source files.
[verification] README must cover: what it is, how to run it, the request
flow, and the main endpoints.
Main thread's job from here: judgment, verification, and iteration. Not execution.
When the implementation subagent finishes, review the output in main. If something is off, give a precise correction: "Section 2 is wrong — the auth middleware runs before logging, not after. Fix that paragraph." One turn, one correction. Don't restate the whole task.
The Core Rule
Exploration in subagents. Synthesis in main. Implementation delegated again.
Every time you violate this — running a broad "read everything" exploration in the main thread — you're piling tokens into a context that needs to stay clean for judgment. The main thread's job is to hold the mental model and make decisions, not to do the reading itself.
The authors built AgentTool specifically so that setAppState is a no-op inside subagents. Results come back as messages only. The architecture is telling you something: the main context is precious. Protect it.
Why This Workflow Transfers
This isn't just a "new repo" workflow. The same pattern applies whenever you're starting a new feature in a codebase you know well but haven't touched in three weeks. Or picking up a PR someone else wrote. Or debugging a module you've never been inside.
Anytime you'd normally start by reading a bunch of files yourself — that's when you send parallel explore agents instead.
The 30-minute window is a forcing function. It keeps you from falling into open-ended exploration that burns an hour and leaves the context a mess. Set a timer. By minute 25, you should be doing actual work.
This post is part of Claude Code: 80K Lines Dissected — a 14-chapter ebook reverse-engineered from Claude Code's TypeScript source. The full ebook covers all 14 chapters: streaming architecture, token economics, plan mode, memory structure, hook internals, delegation strategy, debugging cheat sheets, and the complete 15 design intents with source evidence.
If any of this post changed how you think about Claude Code, the ebook has 10x more.
Top comments (0)