Skip to content
try reference course saved
English
← all Engineering playbooks

playbook

Onboard onto a strange codebase and ship your first fix

The full arc — week one on a repo you've never seen, a bug in production, the author long gone — to a reviewed, tested fix you understand. The big one that ties every other engineering playbook together.

advanced ~half a day

when to reach for this

New job, week one. There's a bug in production, the person who wrote the auth flow left two months ago, and the README is three rewrites out of date. Normally this is a day of grep, a day of guessing, and a commit you're not sure about. This system walks the whole arc — read the repo, diagnose from evidence, fix with a test that proves it, and commit cleanly — so you stay the engineer and Claude is the fast reader and the tireless pair. It pulls the read, debug, test, and commit playbooks into one motion.

gather this first

  • Claude Code open in the project root, so it reads your actual files — not its memory of how repos like this usually look.
  • The bug report and, if there is one, the **full** stack trace plus a way to reproduce it.
  • A clean working tree and the commands for your test suite, type-checker, and linter — so Claude can run your real loop and see the red.

the workflow

  1. Get the map before you go hunting

    Don't dive at the bug cold. Spend ten minutes getting oriented so you're debugging with a model of the system, not a flashlight in the dark.

    you ask 
    Read this repo and give me the map: the top-level modules, how a request flows from the route to the database, and where authentication lives. Plain English, name the real files — don't give me a generic framework lecture.

    what you get back A grounded tour — src/routes/ → middleware/auth.ts → the session store — naming files that exist. You now know where to put your hands.

    If it describes a generic version of your framework instead of your actual files, it hasn't read the repo. Confirm you opened Claude Code in the project root.

  2. Diagnose the bug from evidence, ranked

    Now point it at the symptom with the trace, and demand a ranked hypothesis list *before* any fix. You want to check the reasoning while it's cheap.

    you ask 
    Users report they get logged out at random. Here's the full stack trace. Trace the session-expiry logic end to end and give me the three most likely causes, ranked, with the file and line for each and the reasoning. Don't fix anything yet.

    what you get back A ranked list with auth/session.ts:142-style pointers and the why for each — a stale TTL, a race on refresh, a clock-skew check — so you debug from evidence, not vibes.

    "Don't fix anything yet" is the load-bearing phrase. The diagnosis is the part that most needs your own judgment before any code changes.

  3. Fix it, and make it prove itself with a test

    Once you've confirmed the cause, ask for the failing-then-passing test alongside the fix. The red-to-green test is your evidence the fix is real.

    you ask 
    Cause #2 is right. Fix it, and add a test that fails on the old behaviour and passes on the new one. Show me the diff before you touch anything else.

    what you get back A tight change plus a regression test that actually reproduces the bug — and a diff you read line by line before approving. The test is the receipt that the fix addresses the bug, not just the symptom you described.

  4. Run your real loop and read every line

    Let it run the suite, type-checker, and linter, feed back any red, and review the final diff yourself. You are the author of record.

    you ask 
    Run the full test suite, the type-checker, and the linter. Fix anything red and show me what changed. Then give me the final diff to review — be ready for me to push back on anything I don't follow.

    what you get back A green loop and a reviewed diff. An agent that can *see* the red and fix it is worth ten that can only reason about the code — but you still read it, because it's occasionally confidently wrong.

  5. Commit it in clean, honest chunks

    Finish by turning the change into a reviewable history — small commits with messages that explain *why*, so your git blame stays useful for the next person.

    you ask 
    Stage this as one focused commit (or split it if it covers more than one concern) and draft commit messages that explain why, not just what. Show me the messages before you commit, and don't run anything destructive without explaining it first.

    what you get back A clean commit (or a sensible split) with a message a reviewer will actually understand — your history stays reviewable and your git blame stays honest.

    Ask it to explain the git state *before* anything destructive, and never hand it a --force you don't understand.

make it your own

  • **Review someone else's PR instead:** point it at an incoming diff — "review this like a skeptical senior engineer: correctness, edge cases, security, and anything that'll page someone at 3am. Assume there's a bug and try to find it." Same rigor, pointed at code you didn't write.
  • **Untangle a messy working tree first:** if you've got uncommitted changes spanning three unrelated things and a half-finished merge, start with "explain the current state, then help me stage and commit each concern separately" — get clean before you start the fix.
  • **Plan mode for the big ones:** if the fix turns out to be a real reshape, switch to plan mode and approve the approach before any edits — see /features/plan-mode/.

watch out for

  • Give it the real artifact — the full stack trace, the failing test output, the actual error — not your paraphrase. The verbatim text is usually where the answer is.
  • Ask for the plan and the diagnosis *first*, and read them. It's far cheaper to correct a wrong approach in prose than in a 300-line diff.
  • Read every diff before you approve it and never skip the test. Treat its output like a PR from a fast, eager junior — usually right, occasionally confidently wrong, always yours to sign off on.

you'll end up with In an afternoon you go from "I've never seen this code" to a reviewed, tested fix you understand — plus a mental map of the codebase you'll keep using all week. You stayed the engineer; Claude was the fast reader and the tireless pair.