Engineering Foundation: the codebase you can change with confidence

Your team already has the map-the-codebase, code-review, and git-workflow playbooks — the worked recipes for getting a tour, reviewing a diff, and committing cleanly. This module is the layer above the recipe. It’s where you master the three artefacts every pull request, refactor, and migration inherits — the real map of the codebase, the project context that makes Claude a sharper engineering partner, and the commit discipline that keeps git blame worth reading — build them for a real codebase, and prove, against a real rubric, that you can.

It’s Module 1 of the certifiable Engineering track, and it’s the one we leave open. Read it, do the assignment, and you’ll know exactly what the depth is worth before you put a team through the rest.

Every downstream engineering decision — the PR review, the refactor, the migration, the debugging session — is a withdrawal from three accounts: whether you actually understand the system before you touch it, whether Claude has the project-specific context to help you instead of giving generic advice, and whether the history you’re leaving behind is readable to the engineer who inherits it in a year. Most teams skip funding all three, so every code review re-explains the conventions, Claude gives a framework lecture instead of naming your actual file paths, and git blame is a wall of “fix stuff” nobody can act on. The foundation is where you fund all three once.

Why the foundation is the highest-leverage investment in the engineering track

Software breaks quietly, one undocumented assumption at a time. A new engineer opens a repo and has to guess which files matter, because the README describes the old architecture and nobody wrote down what changed. A Claude session starts with a wide prompt and gets back a generic framework description, because the project has no CLAUDE.md telling it which files, which conventions, and which commands are the real ones. A PR arrives for review and nobody can tell why a line changed, because the commit message is “update auth” and the body is blank — and six months later when that change breaks something, the git blame is the only breadcrumb and it leads nowhere.

Three artefacts fix all three. An ARCHITECTURE.md decides what the codebase actually is — the top-level modules, how a request flows from the route to the database, where the load-bearing complexity lives, and the landmines to know about before touching anything. A CLAUDE.md decides what Claude knows about your project — the stack, the conventions, the test commands, what not to touch, and the context a fresh conversation needs to give you project-specific advice instead of a textbook lecture. A commit convention decides what the history says — a subject plus a body that explains why the change was needed, so a future engineer reading git blame can understand intent, not just chronology.

Build them once and every later task inherits them: feed the ARCHITECTURE.md into a debugging session and Claude traces the actual call path instead of guessing at it; put the CLAUDE.md in the project root and every review, refactor, and feature prompt immediately gets project-specific instead of generic; follow the commit convention and the next person who bisects a bug to your commit can actually act on what they find. That’s why this is Module 1. Skip it and Claude helps you move faster in a system you don’t understand — which is worse, not better, because the mistakes compound downstream.

The architecture map — real files or a framework lecture

The playbook gives you the prompts to get a map. Mastery is the judgment that separates a map you actually use from one you read once and file — and the failure mode is almost always the same: a map that describes your framework instead of your codebase.

• Real files or it didn’t happen. “The application routes incoming requests through a middleware layer to the business logic and then to the database” is a description of every Node.js app ever written. A real map names the files: “src/routes/invoices/create.ts handles the POST /invoices path; it validates the payload in src/lib/invoice-validate.ts, calls src/lib/invoice.ts to generate the document, writes to Supabase via src/lib/db.ts, and queues an email via src/lib/mailer.ts.” That’s a trace a new engineer can hold in their head and navigate from. Anything shorter is a framework lecture.
• One real flow, end to end. The most valuable section of an ARCHITECTURE.md is not the module list — it’s the trace of one representative request from the entry point to the response. Pick the flow that matters most (the signup, the invoice creation, the report generation) and walk every file and every function it touches, in order. That trace is what turns a map into something you use when debugging.
• Name the landmines. Every codebase has them: the function that’s synchronous and will block, the implicit assumption that user.id is an integer, the table with no foreign-key constraints that’s kept consistent only by the application layer. An ARCHITECTURE.md that names these before anyone has to discover them the hard way is paying forward the week of debugging it just saved.
• The map is what Claude inherits downstream. Feed ARCHITECTURE.md into a debugging session — “here’s the architecture; users report a session expiry bug, trace the session-expiry logic” — and Claude traces your actual paths, not a generic framework’s. One file, written once, makes every diagnostic session start from the real system instead of a reconstruction.

The CLAUDE.md — the project context that makes every conversation sharper

The playbook mentions CLAUDE.md as a variation. Mastery is the judgment that distinguishes a CLAUDE.md that actually changes how Claude helps you from one that restates the README in a different format — and the failure mode is almost always ambition without specificity.

• Commands are the most valuable lines. “Use Vitest for unit tests and Playwright for end-to-end tests. The test command is npm run test:unit for unit tests and npm run test:e2e for Playwright. The type-checker is npm run typecheck.” That’s a CLAUDE.md line that saves a conversation from starting with “how do I run the tests?” — Claude already knows. Most project context files have everything except the commands.
• Conventions over principles. “Don’t use any in TypeScript” is a convention Claude can follow. “Write good TypeScript” is a principle Claude already knows. The CLAUDE.md is for the specific decisions your project made: the error handling pattern, the naming convention, the module structure. If it wouldn’t appear in a project-specific linting rule, it probably doesn’t need to be in the CLAUDE.md.
• What not to touch is as valuable as what to do. “Don’t modify src/lib/db.ts directly — database access goes through the query helpers in src/lib/queries/.” These are the landmines in instruction form — naming them in the CLAUDE.md means Claude doesn’t walk into them in a refactor.
• The bilingual section is project context, not a translation request. For a MENA-market codebase, the CLAUDE.md names which parts of the product are Arabic-first, what register the Arabic-language strings use, which client-facing strings need authoring (not translating), and which team members own Arabic-language review. That’s the context that makes Claude a sharper partner in a bilingual product; without it, every Arabic-language output is guesswork.

The commit discipline — why the message body is the most valuable line in your history

The playbook gives you the steps to stage and commit in clean chunks. Mastery is the judgment that distinguishes a commit history a future engineer can navigate from one that’s archaeology — and the failure mode is always the same: messages that describe what changed instead of why.

• The subject line is the headline; the body is the story. “Fix session expiry bug” is a headline. “Fix session expiry bug: the TTL was read in milliseconds from config but compared in seconds in session.ts:142, causing sessions to expire 1000× faster than intended. No test covered this comparison — adding one.” That’s a commit someone can act on when they bisect a regression to this line six months from now. The body answers why, not what.
• One concern, one commit, always. A commit that fixes a bug, updates a config, and cleans up three function names is a commit nobody can read. When the next engineer bisects a bug to that commit, they have to read 200 lines to find which of the three things was the relevant change. One concern per commit costs two minutes; it saves an afternoon every time someone has to understand what changed and why.
• The convention is the standard. Pick a format — type(scope): subject with a why body, or a simpler scope: subject — and apply it consistently. The format matters less than the consistency: a convention is something a new engineer can read two commits from and derive the next. If the messages don’t follow a pattern, they’re not a convention; they’re a collection of messages.
• Commit messages are documentation you write in motion. The CLAUDE.md you write in this module tells Claude what the convention is; after that, Claude drafts messages that follow it, and you approve them. The discipline is knowing what to require, not typing every character yourself.

Your assignment

Build the three foundation artefacts for one real codebase — your own (recommended: the output is real infrastructure your whole team inherits) or the sample company Mizan, a UAE-registered GCC bookkeeping SaaS worked through this module below. Open the project folder in Claude Desktop, approve each read in the “Ask permissions” prompt, and work in the chat — no terminal needed.

Module 1 deliverable — the engineering foundation

1. ARCHITECTURE.md  (one page)
   - the top-level modules with their real directory paths
   - one representative flow traced end-to-end: which files run, in what order,
     naming the function at each step
   - the landmines: the fragile parts, the implicit assumptions, the things with
     no tests that look load-bearing

2. CLAUDE.md  (one page)
   - the stack and the exact test / typecheck / lint / dev-server commands
   - the key conventions (error handling, naming, module structure)
   - what not to touch and why
   - for MENA teams: the Arabic-language context (which sections are RTL, which
     strings need authoring, what Gulf Arabic register to use)

3. Commit convention note  (half a page)
   - the format you're committing to (type + scope + subject + body)
   - two worked examples: one message with just a subject, one with a subject
     and a body that explains why
   - the one-concern-per-commit rule with a demonstrable example

The Engineering Foundation toolkit gives you fill-in templates for each of these and the prompts that build them.

How it’s graded — the rubric

This is the part the free playbook doesn’t have. Your three artefacts are scored against five criteria. Each is meets / nearly / not yet — and “nearly” on any one is a revise, not a pass.

Foundation rubric

1. The map names        ARCHITECTURE.md traces one real flow with actual file
   real files           paths and function names — not a framework lecture.
                        The landmines section names specific risks.

2. The CLAUDE.md        Includes the exact commands to run tests, typecheck,
   makes prompts        and lint. Conventions are specific enough to follow.
   sharper              The do-not-touch list names real files.

3. Commit messages      The format is consistent. The body answers "why was
   explain why          this needed" — not "what does it do." One commit per
                        concern, demonstrable.

4. The bilingual        For a MENA-market codebase, the CLAUDE.md names the
   context is named     Arabic-language sections, the register standard, and
                        which strings are authored vs translated.

5. The convention is    A new engineer can read two commits and derive the
   derivable            next one's format without asking. Consistent, not
                        aspirational.

The bar, shown — a worked model answer (Mizan)

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

ARCHITECTURE.md — Mizan Engineering (excerpt)

## Top-level structure

src/routes/         API handlers (one file per route group)
src/lib/            Business logic (invoice.ts, mailer.ts, db.ts, queries/)
src/components/     Astro UI components
supabase/           Schema + migration files
tests/unit/         Vitest unit tests (mirrors src/lib/)
tests/e2e/          Playwright end-to-end tests

## Invoice creation — the representative flow

POST /invoices
  → src/routes/invoices/create.ts    (validates auth header, calls handler)
  → src/lib/invoice-validate.ts      (checks required fields, client exists)
  → src/lib/invoice.ts               (generates document, calculates totals)
  → src/lib/db.ts → queries/invoices.ts  (writes to Supabase invoices table)
  → src/lib/mailer.ts                (queues notification email via Resend)
  → returns { id, status: 'created' }

## Landmines

- mailer.ts sends email synchronously inside the route handler — a Resend
  timeout will block the HTTP response. No test covers the timeout case.
- invoice.ts assumes client.currency is 'AED'. Multi-currency is in the DB
  schema but not handled in the calculation logic.
- The invoices table has no soft-delete. audit log in invoice_events is the
  only recovery path.

CLAUDE.md — Mizan Engineering (excerpt)

## Commands

npm run test:unit     # Vitest unit tests (fast, no DB)
npm run test:e2e      # Playwright E2E (requires dev server)
npm run typecheck     # tsc --noEmit
npm run dev           # Astro dev server at localhost:4321

## Conventions

- All DB access goes through src/lib/queries/ — never call supabase directly
  from a route handler or component
- Error responses use { error: string, code: string } — no raw throws that
  reach the client
- Async functions always have explicit return types

## Do not touch

- supabase/migrations/ — use `supabase migration new` to add migrations.
  Never edit existing migration files.
- src/lib/db.ts directly — extend queries/ instead

## Bilingual context

Product is bilingual EN + AR. Arabic sections: invoice PDFs, client emails,
src/content/ar/ UI strings.
AR strings are authored in Gulf Arabic register — not translated from English.
Flag Arabic-language changes to @bilal-dev for review.
RTL layout: src/styles/global.css uses logical CSS properties — never use
physical left/right in new styles.

Commit convention — Mizan Engineering (excerpt)

Format: type(scope): subject (50 chars max)
        <blank line>
        Body: why this change was needed (not what it does).
        One concern per commit — never mix bug fix with refactor.

Example 1 (subject only, for a trivial change):
  chore(deps): bump Resend SDK to 2.1.0

Example 2 (with body, for anything a reviewer would question):
  fix(invoice): correct AED rounding on totals above 10,000

  Supabase stores amounts as integers (fils). The calculation rounded
  before multiplying by 100, introducing a 1-fils error on totals
  above AED 10,000. Fixed order-of-operations and added a unit test
  for the boundary value.

What you’ve proven — and what’s next

Clear the rubric and you’ve done something the free path can’t certify: you’ve built a real, professional-grade engineering foundation and demonstrated the judgment behind it. That’s the Foundation stage of “Certified Engineering with Claude.”

From here the track turns the foundation into a working engineering practice, each module assessed the same way:

• Module 2 — the code quality engine: the adversarial code review and the clean commit discipline — the two moves that keep a codebase readable and reviewable.
• Module 3 — shipping features: the spec-first, plan-before-diff loop that ships features behind a green suite without surprises.
• Module 4 — safe change: the refactor discipline that makes structural cleanup something you can stand behind in review.
• Module 5 — the big move: the migration approach that converts the mechanical 90% and surfaces the hard 10% for your judgment.

First, make what you built reusable. Grab the Engineering Foundation toolkit — the CLAUDE.md template, the ARCHITECTURE.md template, and the prompt library your team installs and inherits. And if you’re rolling this across an engineering team, the Engineering with Claude operating guide is the permissions, boundary, and review layer that goes underneath all of it.