How to Read a Codebase You Didn't Write

repowise teamUpdated 9 min read
On this page

To read a codebase you didn't write, skip the file tree and read by lens: Surface (what it is), Shape (how it is organized), Risk (what hurts to change) and Health (what is rotting). Four hours is enough to produce a defensible map and a one-page memo. The goal is not mastery. It is knowing where control enters, which modules carry the weight, and which files you should not touch casually.

This method is one part of how to onboard engineers faster on any codebase.

What "good enough" looks like after four hours

A first pass is done when you can answer six questions without guessing.

  1. What is the product boundary: library, service, CLI, worker or monorepo?
  2. Where does control enter the system?
  3. What are the main modules or services?
  4. Which parts are risky to change?
  5. Which parts are already unhealthy?
  6. What should I verify before I ship a change?

The output is three artifacts: a one-page architecture summary, a ranked risk list and a short list of questions for whoever owns the code. That is enough to start work. It is not enough to sign off on a rewrite or a migration, which needs runtime data and more history.

Why the lens changes with the reason you opened the repo

The same four lenses apply everywhere, but the weight shifts by situation.

SituationWhat you need mostLens to lean on
Joining a teamModule boundaries and conventionsShape
Technical due diligenceDebt, ownership concentration, test gapsRisk and Health
Consulting engagementHighest-risk modules in the first hourRisk
Evaluating an open-source dependencyBus factor, circular dependencies, activityHealth

Scroll the table sideways to see every column.

For the due diligence case in depth, see the code audit checklist for technical due diligence.

The four lenses

LensQuestionOutput
SurfaceWhat is this thing?Product summary, entry points, runtime model
ShapeHow is it organized?Module map, dependency edges, boundaries
RiskWhat will hurt to touch?Hotspots, owners, co-change, dependents
HealthWhat is rotting?Dead code, test gaps, stale docs

Scroll the table sideways to see every column.

Read them in that order. Each lens narrows what the next one needs to examine.

Surface: what is this thing?

Read five things first: the README, the primary build file, the deployment manifests, one entry point, and any generated architecture docs. That is README.md, pyproject.toml or package.json or go.mod, a Dockerfile or compose file, and something like main.py, src/index.ts or cmd/server/main.go.

Answer four questions: is it a library, service, CLI, worker or plugin; what is the runtime; which external systems does it touch; what is the happy path. Write one sentence: "This repo is a ___ that does ___ for ___." If you cannot, keep reading the root files until you can.

With repowise indexed, the same pass is one call. get_overview returns the summary, key modules, entry points, layers, code and git health, and next actions, and is designed to be called once, first, in an unfamiliar repo.

repowise wiki overview page for the repowise repository, with project summary, architecture and key modules in the sidebar
repowise wiki overview page for the repowise repository, with project summary, architecture and key modules in the sidebar

Shape: how is it organized?

Chase boundaries, not folders. In most systems a small share of files explains most of the behavior, so find that spine: top-level packages, shared libraries, adapters to databases and third-party APIs, and the domain modules between them.

  1. List the top-level directories.
  2. Find the entry points and bootstrap code.
  3. Follow imports from the entry point into the core.
  4. Note where business logic lives and mark infrastructure edges separately.

The shape of the dependency graph tells a story. Edges flowing one way mean clear layering. Cycles, where A imports B and B imports A, point to a missing abstraction. A module imported by most of the codebase is a concentration of risk, especially with thin tests. repowise builds this graph with import and call resolution across 28 languages and groups files into communities so the spine is visible at once. Browse a real one in the FastAPI architecture graph.

repowise architecture graph of the repowise repository: module clusters for server, cli, ingestion, ui and analysis, with weighted edges between them
repowise architecture graph of the repowise repository: module clusters for server, cli, ingestion, ui and analysis, with weighted edges between them

When two distant files need connecting, repowise serve lets you pick two files in the graph and trace the path between them.

Risk: what will hurt to touch?

Risk is not size. It is churn, complexity, dependents and repeated co-change together. A small file that changes weekly, sits on the critical path and moves with many unrelated files deserves more attention than a large file nobody touches. CodeScene defines a hotspot the same way: complicated code that you have to work with often, found by combining a complexity proxy with change frequency mined from version control.

You can approximate this with plain git:

bash
# most-changed files in the last 6 months
git log --since="6 months ago" --name-only --pretty=format: | sort | uniq -c | sort -rn | head -20

repowise adds bug-fix history, dependents and ownership to the same signal. get_risk returns hotspot score, bug-fix record, owners, co-change partners and dependents for any file, and repowise context <files> prints the same triage card in the terminal.

bash
repowise risk --target src/auth/session.py   # owner, recent owner, bus factor

A good risk note reads like this:

  • payments/ledger.py: high churn, many dependents, test coverage unknown
  • auth/middleware.ts: central path, hard to mock, likely production impact
  • migrations/: rarely changed, large blast radius, check the deploy process

Health: what is rotting?

Health is what saves time later, so check it before you start changing things. Look for dead files and unused exports, hotspots with no tests, circular dependencies, large packages with no clear owner, and docs that disagree with the code.

Two social signals matter as much as the code. Bus factor counts how many people it takes to cover most of a file's history. repowise reports it per file, where 1 means one author wrote at least 80% of the commits. Doc freshness compares a doc's last edit to the code it describes: if the code moved fifty times since, the doc is a liability.

bash
repowise health      # KPIs and lowest-scoring files
repowise dead-code   # unreachable files and unused exports, by confidence tier
repowise doc-drift   # documentation the code no longer supports

The same data is available to an agent through get_health and get_dead_code. See the code health feature for how scores are built.

The four-hour workflow

If you only have thirty minutes, run the same four phases at five to ten minutes each and lean on generated overviews.

HourPhaseDoWrite down
1OrientRead README, build file, entry point; note external servicesThe one-sentence summary
2Map the spineFollow imports into the core; trace the request or job path; mark validation, side effects and error handlingTop five internal modules, critical paths
3Rank riskReview git history, dependents and co-change; look for low-test, high-churn overlapsOne or two "do not touch casually" areas
4Health and memoList dead code, duplication, test and doc gaps, trendsThe memo, plus open questions

Scroll the table sideways to see every column.

End hour four by writing, not reading. The memo should fit in a PR description or a ticket comment.

The memo template

Vague notes are worthless, so use a fixed template.

  1. System summary: "A Python API service that ingests events, normalizes them and writes results to Postgres and S3."
  2. Entry points: exact files and commands (src/main.py, make dev, uvicorn app:app).
  3. Critical paths: the three flows that matter most, such as validation, persistence and notification dispatch.
  4. Risk list: ranked by probable blast radius, not by gut feel.
  5. Health list: rot, not style: no tests under billing/, dead exports in shared/, a cycle between api/ and domain/.
  6. Questions for the owner: which module is safest to change first, which path has the most incidents, what is intentionally untested, which directories are stale.

The last item is the most valuable. A good question to a person is worth an hour of reading.

Red flags and green flags

Red flagWhat it usually means
Circular dependenciesA missing abstraction
High churn in complex filesA recurring source of bugs
Docs far behind the codeMaintenance has lapsed
One contributor wrote the coreKnowledge loss risk

Scroll the table sideways to see every column.

Green flagWhat it usually means
Heavily reused utility modulesShared logic is centralized
Little dead codeThe team prunes regularly
Consistent conventionsEngineering discipline
Fresh, generated docsVisibility is maintained deliberately

Scroll the table sideways to see every column.

When to narrow the scope

Switch from a full audit to targeted investigation when the repo is too large to map in an afternoon. Signs: too many services, an entry point that fans out into several subsystems at once, no tests and no docs, business logic that depends on systems you cannot run, or mostly generated or vendored code.

In those cases write a partial memo and ask for the missing artifact: logs, an architecture doc, an ownership list or staging access. If you can name the top three risk zones and the top three health issues, proceed. If not, narrow scope.

Doing the pass with an AI agent

An agent can run the same four lenses if it can query the repo instead of grepping it. repowise serves ten tools over the Model Context Protocol, the open standard for connecting AI applications to external systems. The default tools map to the lenses:

LensToolReturns
Surfaceget_overviewSummary, key modules, entry points, layers, health
Shapeget_context, search_codebaseFile and symbol cards, dependents, matches
Riskget_risk, get_change_riskHotspots, owners, co-change, blast radius
Healthget_health, get_dead_codeScores, findings, unreachable code
Whyget_why, get_answerDecisions, history, cited answers

Scroll the table sideways to see every column.

Start with repowise init --yes --no-prose: it builds the graph, git analysis, health and dead-code layers with no API key. Then repowise serve runs the dashboard and the MCP server. See the live examples to compare the outputs against a real repository.

A minimal checklist

  1. Identify the entry point.
  2. Read the README and build files.
  3. Map the module spine.
  4. Trace the happy path.
  5. Inspect history for churn.
  6. Rank hotspots by impact.
  7. Find dead code.
  8. Note test gaps.
  9. Write the open questions.
  10. Decide whether the repo is safe to change.

FAQ

How do I read a codebase I didn't write without reading every file?
Start at the entry point, follow imports into the core, then inspect git history for the files that change most. You want the shape of the system, not a catalog of every file. A dependency graph and generated docs cut the search space sharply.
What is the fastest way to explore a new codebase?
Read the README, the build file and one entry point, then follow the hottest path through the code rather than the alphabet. For a large repo, an indexed overview such as repowise get_overview gives you the modules, entry points and health in one call.
How do I know which files are risky?
Combine churn, complexity, dependents and co-change. A file that changes often and sits on a central path is riskier than a large file that rarely moves. Hotspot analysis, including CodeScene's, is built on that idea.
What belongs in a legacy code review checklist?
Entry points, runtime dependencies, churn, hotspots, dead code, test gaps and ownership. The checklist should show where change is dangerous, not just where code exists.
What is bus factor and why check it?
Bus factor is how many people it takes to cover most of a file's commit history. A bus factor of 1 on a critical file means one person holds the knowledge, which is a risk if they leave.
When should I stop and ask for help?
When you cannot explain the system in one sentence, the entry point is unclear, or the blast radius is too large for one afternoon. Ask for architecture notes, test fixtures or ownership data before digging further.
Can MCP help with codebase audits?
Yes. MCP is a standard way for AI clients to call external tools, so an agent can query the dependency graph, risk and health data directly instead of reading files one by one.