Skip to content
try reference course saved
English
← all Founders & PMs playbooks

playbook

Read your codebase in plain English

Point Claude at your own repo and ask what happens when a user signs up, which files run in what order, and where a new feature would live — no developer in the room.

medium ~30 min

when to reach for this

You don't write code, so every "how does this actually work?" question becomes a meeting with an engineer. But the code is right there, and Claude can read it. This system points Claude at your own repository and has it explain, in plain English, what happens when a user does X, which files run in what order, and roughly where a new feature would slot in. The payoff isn't to replace your engineers — it's to walk into the conversation with "here's the shape of it," so eng time is spent on judgment, not on narrating the codebase to you.

gather this first

  • The actual repository, open in Claude Code from the project's root folder — not a description of it, the real thing.
  • The one flow you want to understand, in user terms — "what happens when someone signs up," "where does a saved article get stored."
  • A notebook (or a notes.md) to capture the plain-English map Claude gives you, so the next eng conversation starts from it.

the workflow

  1. Get the lay of the land first

    Before tracing a specific flow, have Claude describe the whole repo's shape — the major folders and what each is for. Orientation first prevents Claude (and you) from getting lost in one file.

    you ask 
    This is our codebase. In plain English, give me a map: what are the main folders and what is each one responsible for? Where does the frontend live vs the backend vs the data? Keep it to a one-screen overview — no code yet, just the shape of it.

    what you get back A short structural map — "the app/ folder is the web UI, api/ handles requests, db/ is the data layer, auth/ handles login." Enough to know which neighbourhood any given question lives in.

    Ask for the *shape* before any detail. A map you understand makes every later answer land somewhere, instead of floating.

  2. Trace one real flow end to end

    Pick a concrete user action and have Claude follow it through the files in order. "What happens when a user signs up" turns abstract architecture into a story you can follow.

    you ask 
    Walk me through, in plain English, exactly what happens when a user signs up — step by step, naming the real files in the order they run, from the click on the button to where the new user's data ends up. Where would I look if signups were failing?

    what you get back A numbered trace naming real files — "1. the form in SignupForm.tsx posts to api/auth/register.ts; 2. that validates and calls createUser in db/users.ts; 3. the row lands in the users table; if signups fail, start in register.ts." A path you could actually follow.

  3. Ask the questions you'd be embarrassed to ask in a meeting

    This is the safe room. Claude won't judge a basic question, and getting these answered privately means your eng conversations operate at a higher level.

    you ask 
    Three plain questions: Where does a user's password actually get stored, and is it hashed? What happens to a user's saved articles if they delete their account? And which file would I change to alter the wording of the signup confirmation email?

    what you get back Direct answers grounded in the code — "passwords are hashed with bcrypt in register.ts, never stored raw; deleting an account cascades and removes saves via db/users.ts; the email copy lives in emails/welcome.ts." The basics, answered without a meeting.

  4. Find where a new feature would live

    Now point it forward. Asking where a feature *would* go turns the read-through into a scope you can take to eng — "here's roughly what it touches" instead of a blank page.

    you ask 
    If we built a "save articles to read later" feature, which existing files would an engineer most likely touch, and what new files would probably be needed? Just the rough shape of the work and what it connects to — I'll use this to scope the eng conversation, not to write it myself.

    what you get back A grounded scope — "likely touches the article list component and db/ for a new saved_articles table; needs a new Saved view and an API route to save/unsave." You walk into eng with the shape of the work, not a question mark.

    Capture this in your notes — it's the difference between asking eng "is this hard?" and asking "does touching these files match how you'd do it?"

make it your own

  • **Onboarding yourself:** new to a company or an inherited codebase? Run steps 1-3 across several flows to build your own mental model fast, before you've met the people who wrote it.
  • **Scoping a real feature:** chain this straight out of **Pressure-test an idea into a v1 spec** — the spec says *what*, this says *where it lives* and roughly *how big* — both feed the capstone, **From customer request to roadmap-ready**.
  • **Make it routine:** for a repo you'll keep returning to, a CLAUDE.md at the root (see the *Features* tab) teaches Claude the project's conventions so every future read-through is sharper.

watch out for

  • Claude explains the code; an engineer still owns whether it's *right*. A plain-English trace can be confidently wrong about a subtle bit — treat it as a map to verify with eng, not a verdict to act on.
  • Treat the codebase as confidential. If the repo holds secrets, keys, or customer data, you're reading proprietary material — keep it in your sanctioned environment and don't paste snippets into anywhere public.
  • A read-through is for understanding, not for editing live code. Ask Claude to *explain* and *scope*; let a developer own any actual change to the running system.

you'll end up with A plain-English map of your own codebase — how a real flow runs, the basics answered without a meeting, and a rough scope for a new feature — so eng conversations start from shared understanding instead of a blank page.