The Engineering Foundation module teaches the judgment behind the three foundation artefacts. This is the asset pack: the fill-in templates and the prompt library your team installs once and inherits in every Claude session, every PR, and every new hire’s first week.
The production CLAUDE.md — fill in your stack
Copy this template into your project’s root as CLAUDE.md. Fill in the bracketed sections. The bilingual context section is optional for English-only teams and required for MENA-market products.
# [Project name] — engineering context
## Stack
- Runtime: [e.g. Node.js 22 / Python 3.12 / Go 1.22]
- Frontend: [e.g. Astro 6 / Next.js 14 / React 18]
- Database: [e.g. Supabase (PostgreSQL) / PlanetScale (MySQL)]
- Testing: [e.g. Vitest (unit) + Playwright (E2E)]
- Infra: [e.g. Cloudflare Workers / Vercel / Railway]
## Commands
[test-unit-command] # Unit tests (fast, no external deps)
[test-e2e-command] # End-to-end tests (requires running services)
[typecheck-command] # Type-checker (no emit)
[lint-command] # Linter
[dev-command] # Dev server
## Key conventions
- [e.g. All DB access goes through src/lib/queries/ — never call the ORM/SDK
directly from a route handler]
- [e.g. Error responses use { error: string, code: string } — no raw throws
that reach the client]
- [e.g. Async functions always have explicit return types]
- [e.g. Tests mirror the src/ structure — a test for src/lib/foo.ts lives at
tests/unit/lib/foo.test.ts]
## Do not touch
- [e.g. database/migrations/ — use the migration CLI to add new migrations;
never edit existing migration files]
- [e.g. src/lib/db.ts directly — extend the query helpers instead]
- [List other protected files and why]
## Bilingual context (MENA teams — delete if not applicable)
Product language: [EN + AR / EN only]
Arabic sections: [e.g. invoice PDFs, client-facing emails, src/content/ar/]
AR strings are authored in [Gulf Arabic / MSA] register — not translated.
RTL layout: [e.g. uses CSS logical properties throughout — never use physical
left/right in new styles]
Arabic-language review: flag changes to @[handle]The ARCHITECTURE.md template — the map a new hire fills in on day one
Copy this into the project root as ARCHITECTURE.md. The best time to fill it in is when you’re orienting a new hire or after a major restructuring — treating it as a live document, not a one-time snapshot.
# [Project name] — architecture
Last updated: [date], by [name].
## Top-level structure
[directory/] [what lives here — one line each]
[directory/] [...]
## [The most important flow] — end to end
[Entry point] (e.g. POST /invoices)
→ [file:function] ([what it does])
→ [file:function] ([what it does])
→ [file:function] ([what it does, what it writes])
→ [return shape]
## Landmines
- [Fragile part]: [why it's fragile, what breaks if you touch it wrong]
- [Implicit assumption]: [what the code assumes, where it breaks if wrong]
- [Uncovered path]: [what's missing from the test suite that looks load-bearing]
## Other notable flows (optional)
[Repeat the end-to-end trace section for any other flows worth documenting]The commit convention note — paste into CLAUDE.md or keep separate
## Commit convention
Format: type(scope): subject (50 chars max, imperative mood)
<blank line>
Body: why this change was needed (not what it does).
Wrap at 72 chars. Reference the ticket if one exists.
Types: feat / fix / refactor / test / chore / docs / perf
One concern per commit. Never mix a bug fix with a refactor.
Examples:
fix(invoice): correct AED rounding on totals above 10,000
Supabase stores amounts as integers (fils). The calculation rounded
before multiplying, introducing a 1-fil error on totals > AED 10,000.
Added a unit test for the boundary value.
feat(pdf): add invoice PDF export via @react-pdf/renderer
Closes #142. Renders the same data as the web invoice view into a
PDF, with the Mizan logo and the client's billing address. Arabic
invoice PDFs use the ar-invoice template (RTL, Gulf Arabic register).The engineering prompt library
Paste these directly into Claude Desktop chat with the project folder open. Each prompt is ready to use; the bracketed tokens are the only thing to fill in.
Map & orient
Map the codebase
Read this repo and give me the map: the top-level modules with their real
directory paths, how a request actually flows from the route to the database
for [the feature / flow you care about most], and where authentication lives.
Plain English — name the real files, not a generic framework lecture.Trace one flow end to end
Walk me through exactly what happens when [user action / API call]:
which files run, in what order, and which function in each. Flag anything
that surprised you — a hidden side effect, a queue, a second write.Find the landmines
If I had to change [the area you're about to touch] next week, what would bite
me? List the tightly-coupled parts, the implicit assumptions, the paths with
no tests, and anything that looks load-bearing but undocumented.Write ARCHITECTURE.md
Based on the map we just built, write an ARCHITECTURE.md for this repo:
top-level structure with real paths, the [main flow] traced end to end with
file:function pointers, and a landmines section. Keep it to one page —
a new hire should be able to read it in five minutes and know where to put
their hands.Review & commit
Adversarial code review
Here's the diff and what it's meant to do: [intent in one sentence].
Review it like a skeptical senior engineer, organized by dimension:
correctness, edge cases, security, and operability (what pages someone at 3am).
For each issue give me the file and line, why it's a problem, and the severity.
Then assume there's at least one real bug and find the worst one.Verify a finding
For the [finding] you flagged, show me the exact lines that prove it's real —
the code that creates the problem, not a description of it. If you can't show
me the lines, say so and we'll drop that finding.Clean commit
Stage these changes as [number] focused commits — one concern per commit.
For each commit draft a message: a subject line (50 chars, imperative mood)
plus a body that explains why the change was needed, not what it does.
Show me the messages before committing and don't run anything I haven't
approved.Ship & prove
Write the spec
I want to build: [feature description].
Turn this into a short spec: a one-paragraph summary, 4–6 acceptance criteria
phrased as testable statements, and an explicit "out of scope for now" list.
Don't write any code yet.Get the plan first
Use plan mode. Given this spec, lay out the implementation plan: which files
you'll touch and why, the order of changes, the types/interfaces involved,
and where the tests go. Don't write code — I want to review the approach first.Write tests that pin the behaviour
Write tests that cover every acceptance criterion we agreed on, plus the
obvious edge cases — empty input, boundary values, the error path.
Run the full suite and show me it's green.Safe change & migration
Refactor plan before any edit
Read [file / module] and tell me the three biggest structural problems and
how you'd fix each, in order, without changing behaviour. Don't refactor yet —
I want the plan in prose first.Migration survey
We're moving from [old thing] to [new thing].
Find every usage across the repo and group them: the straightforward one-to-one
conversions, the ones with no clean equivalent, and anything unusual.
Give me the counts and the file list. Don't change anything yet.Localize EN → Arabic (Gulf register)
Here is the English copy for [context — invoice PDF / error message /
onboarding email]. Author the Arabic version in Gulf Arabic (خليجي) register
— do not translate word for word. Use the term glossary in CLAUDE.md.
The Arabic must read as native to a Gulf-based professional, not as a
translation.