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.
متى تلجأ إلى هذا
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.
جهّز هذا أولًا
- 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.
الـ workflow
-
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.
أنت تطلب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.ما تحصل عليه 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.
-
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.
أنت تطلب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.ما تحصل عليه 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.
-
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.
أنت تطلب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.ما تحصل عليه 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.
-
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.
أنت تطلب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.ما تحصل عليه 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.
-
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 blamestays useful for the next person.أنت تطلب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.ما تحصل عليه A clean commit (or a sensible split) with a message a reviewer will actually understand — your history stays reviewable and your
git blamestays honest.Ask it to explain the git state *before* anything destructive, and never hand it a
--forceyou don't understand.
اجعله ملكك
- **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/.
انتبه إلى
- 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.
ستحصل في النهاية على 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.