01 · The skill
Reading code is the job
Studies consistently show developers spend more time reading code than writing it. Claude Code flips that equation, but only if you ask it the right things.
"The best thing Claude Code does isn't write code. It's explain code I didn't write, and find the landmines before I step on them."
Senior engineer, on their first month with Claude CodeArchitecture mapping
Understand how a project is organized: which folders own which concerns, how modules depend on each other, what the entry points are, and where the main data lives.
Data flow tracing
Follow a request, a variable, or a user action from start to finish. Understand the chain of function calls, transformations, and side effects that happen along the way.
Legacy code decoding
Understand old, undocumented, or written-by-someone-who-left code. Find patterns, spot tech debt, and surface risk before touching anything.
The rule of three reads
Before Claude Code, reading an unfamiliar codebase took three passes: one to orient yourself, one to understand flow, one to feel confident making changes. Claude compresses all three into a single conversation, but you still need to know what questions to ask. That's what today is about.
01 / 05
02 · The big picture
Architecture mapping prompts
Start every new codebase session with these. They give Claude context and give you a map before you zoom in.
Starter: always use this first
All projects
"Map the architecture of this project. List the main directories, what each owns, the entry points, and how the major pieces connect. Keep it to a diagram-style summary: concise bullet points, not paragraphs."
Dependencies
Understand the tech stack
"Look at the package files and imports. What are the most important third-party dependencies? For each one, explain what it does in this project specifically, not generic descriptions."
Entry points
Server / CLI projects
"Where does execution start? Walk me through the startup sequence, from the moment this application is launched to the point where it's ready to handle requests."
Naming conventions
Before making changes
"Analyze the naming conventions used in this codebase: files, functions, variables, CSS classes. What patterns do you see? What should I follow to stay consistent?"
Effective asks
Ask for bullet points, not essays
Ask what something does "in this project"
Request diagrams described in plain text
Ask for the 3 most important things first
Avoid these
"Explain the whole codebase" (too broad)
Generic questions with generic answers
Skipping this step and diving into details
Accepting a wrong summary without probing
02 / 05
03 · Following the thread
Tracing data flow
Once you have the map, you trace the routes. These prompts follow a specific request, value, or action through the system end-to-end.
Request tracing
Web / API projects
"Trace a POST request to /api/users/login from the moment it hits the server to the moment a response is sent. Name every function, middleware, and database call in order."
Variable lifecycle
Debug & understand state
"Find every place the variable [name] is created, read, and mutated in this codebase. Are there any places where it could be in an unexpected state?"
Side effects
Before editing anything
"If I change [function name], what else could break? List every caller, every dependent module, and anything that relies on the current behavior."
Data transformation
APIs, ETL, pipelines
"Show me how the raw input from [source] gets transformed into the final output at [destination]. What shape does the data take at each step?"
Key technique Verify with a known-answer question
After Claude traces a flow, test its accuracy. Ask it something you already know the answer to, like where a specific function is defined or what a config value does. If it gets that right, you can trust the broader analysis. If it's wrong, say so and ask it to look again more carefully.
💡 You can paste Claude's trace into a comment block in your code as documentation. "Write this as a JSDoc comment" or "format this as a markdown section" turns its analysis into something that lives in the repo permanently.
03 / 05
04 · When the code is scary
Decoding legacy & unfamiliar code
Old code with no docs, cryptic variable names, and zero tests is where Claude Code genuinely earns its keep. These prompts surface what the code does before you risk changing it.
Plain-English explanation
Any confusing function
"Read [filename] and explain what it does in plain English. Assume I'm not familiar with the patterns used. What is its job? What does it output? What does it depend on?"
Risk assessment
Before touching anything
"Review this file for hidden risks. Look for: shared mutable state, timing dependencies, magic numbers, error-swallowing, or any logic that could silently fail. Rate the risk of each finding."
Tech debt inventory
Legacy projects
"Scan this codebase for tech debt. Categorize findings into: quick fixes (under 30 min), medium work (a day), and significant refactors (a week+). Flag anything that's a security or reliability risk."
The "what was the intent" prompt
Cryptic old code
"Looking at [specific function], what do you think the original developer was trying to accomplish? Is the current implementation actually achieving that goal, or does it have bugs?"
Best practice Generate tests before editing
When you find legacy code you need to change, have Claude write characterization tests first: tests that document the current behavior, even if that behavior is wrong. Then change the code. If the tests break, you'll know exactly what you changed and why. This is the safest way to refactor without docs.
Depth control Asking for more or less detail
Claude tends toward thoroughness. Guide the depth with phrases like "one paragraph only," "list the top 3," "skip the obvious stuff," or "go deeper on the database parts." Without guidance, long files can generate very long explanations. Precision in your request = precision in the answer.
04 / 05
05 · Your outcome
Your reading session today
Pick a real project: one you're working on, one you've inherited, or one from GitHub you want to learn from. Run through these prompts in order.
Session opener
Run this first, every time
"Before I start working, give me a 90-second briefing on this project. Cover: what it does, the tech stack, what the most complex part is, and anything I should know before changing code."
Find the oldest code
Spot technical debt quickly
"Look through the file structure and code patterns. What parts of this codebase look oldest or most out of step with the rest? Which files would you be most nervous to touch?"
Produce a README section
Documentation as a side effect
"Based on your understanding of this project, write a 'How It Works' section for the README. Cover the main components and how they fit together. Write it for a new developer joining the team."
What project did you read today?
Best discovery from the session
Day 03 checklist
- Ran the architecture mapping prompt on a real project
- Traced at least one request or data flow end-to-end
- Verified Claude's accuracy with a known-answer question
- Asked about risk or tech debt in at least one file
- Turned one Claude explanation into usable documentation
- Could describe this codebase to a colleague in 90 seconds, without looking
05 / 05
Day 03 complete
You now have a repeatable playbook for reading any codebase. Tomorrow is Day 04: Prompting Technique. You'll learn to write prompts that get precise, useful results every time, not just sometimes.
Bookmark these prompt categories; you'll use them every week.