Codebase-in-a-Box — the Engineering capstone

You’ve completed the five modules. You’ve built the foundation artefacts, run an adversarial review with verified findings, shipped a feature behind a green suite, refactored safely with a before/after proof, and executed a migration with documented decisions. The capstone is where you run all five on one codebase, in one project, so they become a single coherent arc rather than five separate skills.

This is not a quiz. It’s a complete engineering project — five deliverables that demonstrate both the artefacts and the judgment behind them, on a codebase that’s either yours or Mizan’s.

The capstone project — one codebase, the full arc

The Codebase-in-a-Box capstone runs the five engineering moves end to end on a single codebase. Each deliverable inherits the artefacts of the one before it: the CLAUDE.md from the foundation sharpens the review and the feature prompt; the commit convention from the review applies to the feature and refactor commits; the test suite from the feature shipping is the seatbelt for the refactor; the clean working tree from the refactor is the prerequisite for the migration.

Bring your own codebase — that’s the recommendation for teams, because the artefacts you produce are real infrastructure your team keeps using after the capstone. The ARCHITECTURE.md becomes the document your next hire reads; the CLAUDE.md becomes the context every subsequent Claude session inherits; the PR review is a real PR you already needed to review; the feature is a real ticket you were going to ship; the refactor is a file everyone on the team quietly routes around; the migration is the change that’s been in the backlog for a quarter. The capstone is designed so it’s day-one ROI.

Mizan Engineering is the sample codebase if you’d rather learn on neutral ground first. The full scenario is worked through in the model answer section of this guide: a UAE-registered GCC bookkeeping SaaS whose engineering team is running a billing-module modernization — documenting the repo for a new hire, reviewing the Stripe webhook PR, shipping the invoice PDF feature, refactoring the invoice generation function, and migrating from moment.js to date-fns.

Your deliverable bundle

Five artefacts, one codebase. Open the project folder in Claude Desktop with your CLAUDE.md in place, approve each read in the “Ask permissions” prompt, and work in the chat — no terminal needed for the foundation, review, and planning steps; running tests and git commands are the Power Track steps.

Codebase-in-a-Box deliverable bundle

1. ARCHITECTURE.md + CLAUDE.md  (M1 — the foundation)
   - ARCHITECTURE.md: top-level structure with real paths, one representative
     flow traced end-to-end with file:function names, landmines named
   - CLAUDE.md: stack, exact commands, key conventions, do-not-touch list;
     bilingual context section for MENA-market codebases

2. Verified PR review  (M2 — the code quality engine)
   - a structured review organized by dimension (correctness, edge cases,
     security, operability)
   - each material finding verified against specific lines; false positives
     explicitly dropped
   - one failing test per confirmed bug
   - the change committed in clean chunks with why bodies

3. Shipped feature  (M3 — shipping features)
   - a spec with testable acceptance criteria and an out-of-scope list
   - a plan reviewed before the first line was written
   - implementation with tests that map to the criteria
   - clean commits with why bodies

4. Safe refactor with proof  (M4 — safe change)
   - green suite before; refactor in discrete steps; green suite after
   - each step as a separate diff and commit
   - no behaviour change mixed in
   - PR description explaining the structural problem fixed

5. Migration with documented decisions  (M5 — the big move)
   - blast-radius survey grouped by complexity
   - mechanical conversion separate from the decided cases
   - each hard case with options, tradeoffs, and the actual reasoning behind
     the decision made
   - suite green at the end

6. Reflection  (half a page)
   - one paragraph: where Claude helped and what it made faster
   - one paragraph: where your engineering judgment was the essential input —
     the moment the tool's output was wrong and you caught it, or the
     decision that required domain context Claude couldn't have
   - one thing you'd do differently next time

The master rubric

Five dimensions. Each is meets / nearly / not yet on the five criteria. “Nearly” on any one is a revise, not a pass. All five at “meets” earns the credential.

Master rubric — Certified Engineering with Claude

1. Foundation        ARCHITECTURE.md traces a real flow with file paths and
   artefacts         function names. CLAUDE.md includes exact commands, real
   are real          conventions, and what-not-to-touch. For MENA teams: the
                     bilingual context is named. Both documents are artefacts
                     a team installs and keeps, not documents written for
                     the exercise.

2. Review quality    The adversarial framing was used. Every material finding
   is demonstrated   is verified against specific lines. False positives are
                     explicitly dropped. One failing test per confirmed bug.
                     Commit history is navigable: one concern per commit with
                     a why body.

3. Feature was       Spec has testable acceptance criteria (observable outcomes,
   spec-first        not aspirational descriptions). Plan was reviewed before
                     code was written. Tests map one-to-one to the criteria.
                     The full diff was read before landing.

4. Refactor is       Green before, green after — both shown, not asserted.
   provably safe     Discrete steps, each reviewed before the next started.
                     No behaviour change mixed in. PR description explains
                     structural intent, not the diff.

5. Migration is      Blast-radius survey groups usages by complexity. Hard
   honest            cases are flagged, not silently converted. Every flagged
                     case has a documented decision with reasoning — not just
                     a TODO. Suite green at the end.

The bar, shown — Mizan Engineering worked summary

You don’t have to guess what “meets” looks like. Here’s the capstone summary for the sample company — yours doesn’t need to look like this, it needs to clear the same bar.

Mizan Engineering — Codebase-in-a-Box capstone summary

Codebase: Mizan (UAE GCC bookkeeping SaaS), billing-module modernization.
New hire orientation: Bilal Al-Mansouri, backend engineer joining for
the migration and the PDF feature.

Deliverable 1 — Foundation artefacts
  ARCHITECTURE.md produced by opening the repo in Claude Desktop and running
  the map-the-codebase prompt from Module 1. The invoice creation flow is
  traced end to end: POST /invoices → invoice-validate.ts → invoice.ts →
  queries/invoices.ts → mailer.ts. Three landmines named: synchronous mailer,
  assumed AED currency, no soft-delete on the invoices table.

  CLAUDE.md: stack (Node.js 22 / Astro 6 / Supabase / Vitest / Playwright),
  four exact commands, six conventions including "all DB access via queries/,"
  two do-not-touch entries (migrations/, db.ts), bilingual section (Arabic
  invoice PDFs authored in Gulf Arabic — not translated; flag to @bilal-dev).

Deliverable 2 — PR review: Stripe webhook integration
  Review organized by dimension. One confirmed bug: payload processed before
  signature verification (stripe.ts:84 before :94) — replay attack vector.
  Verified against the lines. Failing test drafted. One false positive dropped
  (event type allowlist exists at :31–35). Change committed as three logical
  commits: the signature-verification fix, the missing payment_failed tests,
  and the extracted constants.

Deliverable 3 — Shipped feature: invoice PDF export
  Spec: POST /invoices/:id/pdf returns PDF within 3 seconds; duplicate
  requests return cached PDF; failures return PDF_ERR and no email is sent;
  Arabic invoices render RTL with Gulf Arabic register. Plan reviewed before
  implementation: two new files (src/lib/pdf-generator.ts, src/routes/
  invoices/pdf.ts), one updated route (invoices/index.ts), six new tests.
  Plan approved with one change (caching moved to the route layer, not the
  generator). Implementation matched the plan. Suite green. Five acceptance
  criteria, five corresponding tests.

Deliverable 4 — Safe refactor: invoice.ts (380 lines → four modules)
  Baseline: 47 unit tests green, 62% coverage. Refactored in four discrete
  steps (validation, calculation, PDF, email extracted). Each step a separate
  diff, reviewed and committed before the next. Suite after: 67 tests green,
  same 4 original tests unchanged. No E2E test changed. PR description:
  structural problem named (four responsibilities, untestable in isolation),
  what each extraction fixed, explicit statement that green before + green
  after was the proof.

Deliverable 5 — Migration: moment.js → date-fns
  Blast-radius survey: 74 usages, grouped (62 mechanical / 9 hard timezone
  cases / 3 unusual). Mechanical pass: 62 conversions in one commit, all
  matching the hand-done .format() example. Hard cases: 9 utcOffset() usages
  flagged; each documented with options (date-fns-tz vs manual offset math)
  and the decision made (manual UTC+4 arithmetic with reasoning: GST has no
  DST, date-fns-tz is unnecessary complexity for a fixed offset). 3 unusual
  cases: SQL comment left as-is (no logic), dynamic import moved to top level,
  Playwright test updated to use date-fns format. Suite green after all.

Reflection:
  Claude made the blast-radius survey — finding and grouping 74 usages across
  23 files — something that would have taken half a day of grep and review;
  it took 20 minutes. The adversarial review framing surfaced the signature-
  verification ordering issue that I wouldn't have caught in a polite first
  pass. And on the PDF feature, the plan it proposed initially put the PDF
  generation inside the route handler (missing the separation of concerns
  the CLAUDE.md convention required) — that's the moment I caught the plan
  wrong and revised it before any code existed.

  The engineering judgment I needed to supply: the utcOffset() migration
  decision. The reasoning that Gulf Standard Time has no DST and the manual
  UTC+4 arithmetic is correct required knowing the business context (Gulf
  billing is GST+4 permanently) — not something Claude could know without
  the domain context. That's the decision the rubric is checking.

  Next time: write the CLAUDE.md before the first Claude session on the
  codebase, not after the orientation. The foundation module's output is
  most useful when it's in place from the very first prompt.

What completing this earns

Clear all five rubric dimensions and you’ve earned “Certified Engineering with Claude” — a verifiable credential at /cert/[your-id] that says you ran the full engineering arc:

• You can orient a new hire (or yourself) in an unfamiliar codebase and produce the artefacts that orient the next person faster.
• You can run an adversarial code review that catches the real bug and drops the false positives, leaving a history the next engineer can navigate.
• You can ship a feature that’s spec-first, plan-reviewed, test-proved, and cleanly committed.
• You can refactor safely — with a before/after proof — rather than hopefully.
• You can run a repo-wide migration that converts what’s mechanical and surfaces what needs judgment, with documented decisions rather than silent guesses.

That’s the engineering practice this track teaches. The credential says you can demonstrate it, not just describe it.