There's a skill nobody talks about when they discuss Claude Code.
Not generating code. Not building features. Not fixing bugs.
Reading code you didn't write. Understanding it well enough to extend it, integrate with it, and not break it.
This is actually where I use Claude Code most. And it's where it's most useful.
The problem with unfamiliar codebases
Every developer knows this feeling. You open a project you didn't write — or one you wrote six months ago and have completely forgotten — and you need to add something to it.
You could read through every file. Trace the call stack. Map the data flow manually. That works. It takes hours.
Or you can bring Claude Code in and do it in minutes.
But there's a right way and a wrong way to do this.
The wrong way: asking Claude Code to just "look at this"
The most common mistake is treating Claude Code like a search engine.
// Wrong
"Look at this codebase and tell me how it works"
You'll get a surface-level summary. File names, rough structure, maybe a flowchart of the main components. Technically correct, practically useless for actually working with the code.
The problem is the question is too broad. Claude Code doesn't know what you're trying to do, so it can't tell you what you need to know.
The right way: task-first analysis
The right approach is to lead with what you're trying to accomplish, then ask for the specific understanding you need to get there.
// Right
"I need to integrate nexus-pulse into nexus-hub so that Hub
can poll Pulse's health endpoint and display its metrics.
Before writing any code, read:
- nexus-hub/backend/src/services/poller.js
- nexus-hub/backend/src/routes/registry.js
- nexus-hub/backend/src/store.js
- nexus-watcher/backend/server.js (Watcher is already integrated
— use it as the reference)
Then tell me:
1. How does Hub currently register and poll a tool?
2. What does a tool need to expose for Hub to integrate it?
3. What would need to change to add Pulse following the same pattern?
Do not write any code yet."
Now Claude Code has a goal. It reads the right files. It compares against an existing working example. And it tells you exactly what you need to know to make the change safely.
A real session: integrating five services into a hub
Here's a concrete example from building NEXUS Ecosystem. I had a working Hub with two integrated tools (NEXUS and Watcher). I needed to integrate three more: Pulse, Security, and Notify.
Each tool had its own backend, its own auth, its own data model. I hadn't touched some of them in weeks.
Rather than re-reading all of it, I gave Claude Code this analysis prompt:
Analyze the project at E:\Claude\NEXUS before writing anything.
Read completely:
- nexus-hub/backend/server.js
- nexus-hub/backend/src/store.js
- nexus-hub/backend/src/services/poller.js
- nexus-hub/backend/src/routes/ (all files)
- nexus-watcher/backend/server.js
- Nexus/backend/hub.js
- nexus-pulse/ (full structure — most recent tool)
Identify and document:
1. How a tool registers itself with Hub (endpoint, payload, frequency)
2. What Hub stores per tool in the registry
3. How Hub polls tool health and what it expects back
4. The SSO pattern — how Hub opens a tool with the user already logged in
5. Any inconsistencies between how Watcher and NEXUS are integrated
6. What nexus-pulse is missing to be Hub-compatible
Do not write any code until you report your findings."
The report came back in about two minutes. It found:
- The exact registration pattern (POST to
/api/registry/registerwithX-Api-Key, heartbeat every 60s) - The health polling interval (every 30s from poller.js)
- The SSO flow (Hub calls
/api/auth/sso-hub, tool returns a short-lived URL) - A bug: Watcher's
registerWithHub()usedsetIntervalbut didn't retry on failure. NEXUS's version did. Inconsistency I'd never have spotted without the comparison. - What Pulse was missing: the
registerWithHub()call inserver.jsand the/api/auth/sso-hubendpoint
With that report in hand, I could write the integration prompt with confidence. No guessing. No surprises.
The patterns that work
After dozens of these sessions, here are the patterns I rely on.
The comparison pattern
Always give Claude Code a working example to compare against. "This already works — use it as reference" is worth more than any amount of documentation.
"nexus-watcher is already integrated into Hub and working correctly.
Read its backend/server.js and the Hub's poller.js.
Then read nexus-pulse/backend/server.js.
Tell me what Pulse is missing compared to Watcher."
Claude Code excels at diff-style analysis. It will find exactly what's different and why.
The data flow pattern
When you need to understand how data moves through a system:
"Trace the complete data flow for this scenario:
A user clicks 'Open' on a tool card in the Hub dashboard.
Start from the React onClick handler in Dashboard.jsx.
Follow it through the backend, through the tool's auth,
until the user lands on the tool's homepage already logged in.
List every file touched, every function called, every
network request made. Don't skip steps."
This gives you a complete map of the interaction. Invaluable when something breaks in the middle of a flow and you're not sure which layer is failing.
The "what could go wrong" pattern
Before making a change to code you don't fully understand:
"I'm going to change the auth middleware in nexus-pulse/backend/server.js
to add API key bypass support (same as nexus-security already has).
Read both files. Then tell me:
1. What does this change affect?
2. What else in the codebase depends on this middleware?
3. What could break?
4. Is there anything in nexus-security's implementation I should
adapt rather than copy directly?"
This is defensive programming with AI assistance. You make the change knowing the blast radius.
The "why is this broken" pattern
Debugging unfamiliar code:
"The Hub's Pulse panel shows 0 monitors even though Pulse has active monitors.
Here's what I know:
- GET http://localhost:9092/api/monitors returns data when called directly
- The Hub panel shows empty
- The auth fix from yesterday is in the running container
Read:
- nexus-hub/frontend/src/components/Dashboard.jsx (PulsePanel section)
- nexus-hub/backend/src/routes/proxy.js
- nexus-pulse/backend/src/routes/ (all files)
Diagnose the issue. Don't fix it yet — tell me what you find first."
The key phrase: "don't fix it yet." You want the diagnosis before the prescription.
What Claude Code actually does when it reads code
It's worth understanding what's happening under the hood, because it changes how you prompt.
Claude Code doesn't just read files sequentially. It builds a model of the relationships between files — what calls what, what depends on what, what shares state with what. This is why the comparison pattern works so well: it can hold two implementations in context and reason about their differences.
But context has limits. On a very large codebase, if you ask it to read everything, it will read everything — and by the time it gets to the tenth file, the first files are farther back in context. The quality of analysis drops.
The fix: be surgical. Tell it exactly which files to read. "Read the three files most relevant to X" beats "read the whole codebase."
The CLAUDE.md shortcut
If you're working on the same codebase regularly, invest in a CLAUDE.md that documents the architecture decisions you've already figured out.
Every time Claude Code analyzes something you'll want to know again — how the event bus works, what the store schema looks like, which services need the API key bypass — add it to CLAUDE.md.
The next session starts with that context already loaded. You skip the analysis phase entirely and go straight to the work.
This compounds over time. A project with a well-maintained CLAUDE.md after six months of development is a project where Claude Code almost never needs to re-derive things you've already figured out.
The skill that actually matters
People talk about prompt engineering like it's a trick. Write the magic words, get better output.
It's not that. It's systems thinking applied to how you communicate intent.
When you ask Claude Code to read code, you're not asking it to summarize. You're asking it to build a specific mental model that lets it help you accomplish a specific goal. The quality of the model depends on the quality of the question.
That's not a Claude Code skill. That's a thinking skill. Claude Code just makes it visible.
NEXUS Ecosystem is open source — all the prompts and patterns above come from real sessions building it.
- GitHub: github.com/Alvarito1983
- Docker Hub: hub.docker.com/u/afraguas1983
Top comments (0)