DEV Community

Mohammed Ali Chherawalla
Mohammed Ali Chherawalla

Posted on Edited on Originally published at wednesday.is

How to Understand a Codebase You Didn't Write (With Claude Code)

Map the codebase once, then ask questions against the map. Have AI write down what the code does, its modules, the riskiest files and the rules you mustn't break, in one file in the repo. Every answer after that comes with the file and line, so you can check it. The free AI starter kit we build our own products with makes that map for you.

Why reading the code from the top doesn't work

A real codebase has hundreds of files, and most of them don't matter for what you need today. Reading from the top teaches you the boring parts first. A map tells you where to look and what to leave alone.

Map it once

Ask your AI to write one file, CODEBASE.md, with these sections:

  • What it is, from the README, the package files and the entry points.
  • Modules, one line each on what every top-level folder owns and how they talk to each other.
  • Data, where state lives and the main flows through it.
  • Hot spots, the files changed most in the last 90 days, the largest files and the files with the most importers.
  • Tests, where they are, how to run them and which modules have none.
  • Rules, anything in the contributing guide, your AI instructions file, lint configs and CI you mustn't break.
  • Danger zones, like auth, payments, migrations, generated code and anything marked "do not edit".

It takes minutes, and everyone on the team gets the same starting point.

Ask questions against the map

Ask the way you'd ask a colleague. "Where does a new user get created?" "What happens when a payment fails?" "Which screens use this component?" The AI checks the map, confirms in the code and answers with the file and line. If the map was wrong, it fixes the map.

Find the risky files before you change anything

The hot spots are where changes go wrong. A file that changed thirty times this quarter, is imported by forty others and has no tests deserves a careful plan. Ask what a change there would break before you make it.

Signs you don't know the codebase yet

What you see What's missing Fix
Every question starts a new search A map Write CODEBASE.md once
A small change breaks something far away Knowing who imports what Check the importers first
You edited a generated file Danger zones marked List them in the map
CI fails on a rule you didn't know The project's rules Read them into the map

Get the codebase tool we use

The starter kit maps any codebase into one file, answers with the file and line, and shows what a change will break before you make it. It works with Claude Code and Codex. Get the starter kit free on GitHub.

Questions

What's the fastest way to understand a new codebase?

Have AI map it once: what it does, its modules, where data lives, the riskiest files and the rules not to break. Save that map in the repo, then ask questions against it.

How do I find the risky files in a codebase?

Look at the files changed most in the last 90 days, the largest files and the files the most other files import. Those are the riskiest to change.

Can Claude Code explain code with file and line references?

Yes. Ask it to answer from the map first, then confirm in the code and cite the file and line for every claim.

Originally published at wednesday.is.

Top comments (0)