Engineering
You already know how to code. This is the part that's new — handing real work to an agent that reads the whole repo, writes the tests, and shows you the diff before anything lands.
Full worked systems, not one-off prompts — each walks the whole workflow end to end. Pick one and follow it.
Map a codebase you've never seen
Point Claude at an unfamiliar repo and get a grounded tour — the real modules, how a request flows, and where the scary parts live — in plain English, naming files that exist.
Write the CLAUDE.md that grounds every task
Build the project's `CLAUDE.md` once — the architecture, the real dev commands, and the conventions that live in people's heads — and every later task starts grounded instead of guessing, for everyone on the team.
Trace a bug to its root cause and prove the fix
Hand Claude the full stack trace and the failing input, get a ranked list of likely causes with file:line pointers, then a fix plus a test that fails on the old code and passes on the new.
Backfill the tests you never wrote
Take a module with no tests, have Claude list the behaviours worth pinning down — including the nasty edge cases — and write a suite that covers them, flagging any latent bugs it finds on the way.
Refactor safely behind a green suite
Clean up a gnarly file without changing behaviour — using the test suite as your seatbelt, running it before and after so you can prove nothing broke instead of hoping.
Ship a feature end to end — plan, build, test, commit
Run the full Stage-2 loop on one feature: write a crisp spec, get the plan before a line is written, let Claude implement behind your green suite, pin the new behaviour with tests, read the whole diff, and commit it in clean logical chunks.
Review a PR like a skeptical senior — before you approve
Use Claude as a fast adversarial first-pass reviewer on a diff or PR — correctness, edge cases, security, operability — then verify each finding against the code yourself, because it will flag a confident "bug" that isn't. You still own the approve.
Untangle the git mess and commit in clean, logical chunks
Turn a working tree with three unrelated concerns and a half-finished merge into a clean, reviewable history — Claude explains the current state in plain English before touching anything, then helps you stage and commit each concern separately with messages that say *why*.
Run a wide, boring migration without breaking things
The repo-wide change you've been dreading — swap a library, rename an API, bump a pattern across 80 files — done in one sweep, with a clear list of the cases it couldn't convert one-to-one for you to decide by hand.
Modernize a legacy subsystem with a plan and an agent team
The old subsystem everyone fears — auth, the payments adapter, the homegrown ORM — replatformed as a planned, staged, continuously-green campaign instead of a heroic big-bang rewrite. The big one that pulls every other engineering playbook into a single arc.
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.
Engineering with Claude, in depth
The playbooks above are single jobs. These are the long reads behind them — how the work fits together across a quarter, what good looks like, and the judgement calls the prompts assume you have already made. Read in any order.
- Codebase-in-a-Box — the Engineering capstone The Engineering track capstone — integrate M1–M5 into one complete engineering arc on a single codebase: map and document it, run a verified code review, ship a feature behind a green suite, refactor safely, and execute a migration with documented decisions. A pass means all five rubric dimensions at 'meets'.
- Engineering Foundation toolkit: CLAUDE.md template, ARCHITECTURE.md template, and the engineering prompt library The take-home asset pack for Engineering Module 1 — a production CLAUDE.md template, an ARCHITECTURE.md template, a commit convention note, and a saved-prompt library for the recurring mapping, review, and shipping tasks. Install once, inherit everywhere.
- Engineering Foundation: the codebase you can change with confidence Module 1 of the Engineering deep dives — go past the recipe to master the three artefacts every PR, refactor, and migration inherits: the architecture map, the project context file, and the commit discipline. Build them for a real codebase. Free to sample.
- Safe change: refactor behind a green suite, not faith Module 4 of the Engineering deep dives — master the refactor discipline that makes structural cleanup something you can stand behind in review: establish the green baseline, move in small reviewable steps, prove behaviour is unchanged. Gated.
- Shipping features: spec → plan → build → prove → commit, in that order Module 3 of the Engineering deep dives — master the full feature-shipping loop: a testable spec, a plan you critique before any code exists, an implementation proved by a green suite, and a diff you own line by line. Gated.
- The big move: migration at scale, with the hard cases named Module 5 of the Engineering deep dives — master the repo-wide migration that everyone's been avoiding: survey the blast radius, convert the mechanical majority, surface the judgment-requiring cases, and hand each decision to a human with options and tradeoffs. Gated.
- The code quality engine: review that catches the real bug and commits that explain why Module 2 of the Engineering deep dives — master the two moves that keep a codebase readable and reviewable: the adversarial first-pass that verifies every finding against the actual code, and the commit discipline that makes git blame worth reading. Gated.
The non-negotiables before any of this ships. Read the operating guide for the full data, brand, legal, and rollout playbook.
- You are the author of record. Read every diff before you approve it — treat Claude's output like a PR from a fast, eager junior: usually right, occasionally confidently wrong, never merged unread. A senior human owns the merge.
- Make it prove the fix. A change without a failing test it turned green is a guess, no matter how confident the explanation sounds — demand a test that fails on the old behaviour and passes on the new one. Confidence in the prose is not evidence.
- Plan before the diff on anything non-trivial. Get the approach in prose (or use plan mode) and read it before it writes a line — it's far cheaper to correct a wrong approach in a paragraph than in a 300-line change. Give it the real artifact too — the full stack trace, the failing output — not your paraphrase.
- Keep proprietary code and secrets where they belong. Open Claude in the repo so it reads your real files, but keep credentials, customer data, and anything under NDA out of the context — on Desktop the open folder is the boundary, and you approve each read in the 'Ask permissions' prompt.
- Let it run your real loop, then trust the red. Wire the test suite, type-checker, and linter so the agent sees its own failures and self-corrects — an agent that can see the red is worth ten that can only reason about the code. Reach for a subagent on the wide reads so the deep dig doesn't crowd out your working context.
- *Commit small, logical chunks that explain the why.* Have it stage and draft the message; you keep
git blamehonest and your history reviewable. Bilingual teams: code stays English, but design docs, ADRs, and PR descriptions are worth writing in the language the reviewer reads.
Questions people ask
- Does Claude write code without me reviewing it?
- No — you read every diff before you approve it, because you're still the author of record. Treat its output like a PR from a fast, eager junior: usually right, occasionally confidently wrong, always reviewed.
- How do I know a fix is real and not a guess?
- Make it prove the fix — ask for a test that fails on the old behaviour and passes on the new one. A change without a failing test it turned green is a guess, no matter how confident the explanation sounds.
- Is it safe to point Claude at our private repo?
- Open Claude Code in the project root so it reads your actual files, and keep proprietary code in an environment your company approves. Reviewing the diff before anything lands is your boundary, not the tool's.
- What's a realistic first task?
- Mapping an unfamiliar codebase: ask Claude to read the repo and explain how a request flows from route to database, naming real files. It's the fastest way to onboard onto code you didn't write — and a safe, read-only way to see the agent work.