ع
Start Topics Teams Reference What's new Saved
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. This is the capstone of the staged path: it ties every earlier engineering playbook into one motion — the map (map-the-codebase), the project context (project-context), the evidence-led diagnosis (debug-from-trace), the test that proves the fix (backfill-tests), the behaviour-preserving cleanup (safe-refactor), and the small, honest commit (git-workflow). The reading, diagnosis, and fix live entirely in Claude Desktop as a chat plus visual diffs you accept or reject; running your real loop and committing are the Power Track steps (a terminal-enabled session).

gather this first
  • The project's root folder open in Claude Desktop, so Claude reads your actual files — not its memory of how repos like this usually look. (Power Track: claude in the project root from a terminal does the same.)
  • The bug report and, if there is one, the full stack trace plus a way to reproduce it — paste it straight into the chat.
  • A clean working tree and the commands for your test suite, type-checker, and linter — so Claude (in a terminal-enabled session) can run your real loop and see the red, or so you can run it yourself and paste the output back.
the workflow

  1. Get the map before you go hunting

    Open the folder in Claude Desktop and ask in the chat — mapping a repo needs no terminal. 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 the project's root folder is the one open in Claude Desktop (or that you launched claude from 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. In Claude Desktop the change comes back as a visual diff you accept or reject in the file pane — read it line by line before you accept.

    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 in the file pane 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 (Power Track)

    Let it run the suite, type-checker, and linter, feed back any red, and review the final diff yourself. Running your project's loop needs a terminal-enabled session (Claude Code in the terminal, or Desktop with command-running turned on) — this is the Power-Track step. No terminal session? Run the loop yourself and paste any red back into the Desktop chat; Claude fixes from the real output the same way. 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 (Power Track)

    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. Driving git is a Power Track step that wants a terminal-enabled session; if you're staying on Desktop, accept the diffs there and make the commits yourself with the messages Claude drafts.

    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 are the author of record on every line that lands.
  • Keep proprietary code, secrets, and customer data in-boundary. Open Claude in the actual repo so it reads your real files, but on Desktop the open folder is the boundary — approve each read in the 'Ask permissions' prompt, and keep credentials and anything under NDA out of the context.

you'll end up with This is the capstone, so the payoff is the whole arc at once: in an afternoon you go from "I've never seen this code" to a reviewed, tested fix you understand — map, diagnosis, test, and commit pulled into one motion — plus a mental map of the codebase you'll keep using all week. You stayed the engineer and the author of record; Claude was the fast reader and the tireless pair.

Questions people ask

What do I need to have ready before starting — can I begin with just a bug report?
You need four things: the project's root folder open in Claude Desktop (not a parent directory), the full stack trace verbatim (not a paraphrase), a way to reproduce the bug, and a clean working tree with the test suite, type-checker, and linter commands available. The map, diagnosis, and fix run entirely in Desktop; running the loop and committing are the Power-Track steps that want a terminal-enabled session. The full trace is critical — "it crashes on login" throws away the exact frame that holds the answer.
How long does the full arc take on week one?
Budget roughly half a day for the complete workflow — about 15 minutes to map the codebase, 15-20 minutes for diagnosis and confirmation, 20-30 minutes for the fix and test, and time for the final loop and commit. The map step is the one most people skip and the one that saves the most debugging time.
Why does the playbook insist on \"don't fix anything yet\" during diagnosis?
Because the diagnosis is the step most likely to be wrong, and it's far cheaper to catch a wrong hypothesis in prose than after it's been turned into a 300-line diff. Reading the ranked cause list and confirming the right one before any code changes is what keeps you from spending an hour on the wrong fix.
What if the fix turns out to be a much larger reshape than expected?
Switch to plan mode before any edits are made. Ask Claude for the full approach and approve it explicitly — see the `plan-mode` variation in this playbook. A small bug fix that reveals a structural problem is exactly the scenario plan mode was designed for; don't let it start rewriting without your sign-off.