Rules

What must never be broken, and nothing else.

Last verified: 2026-08-02 against commit 51e86a1.

The tiering rule

Three tiers, and a rule lives in exactly one of them.

Tier	Where	What goes in it	Budget
Hard rules	root CLAUDE.md · client/CLAUDE.md · server/CLAUDE.md	Constraints whose violation breaks the build, the gate, or a business invariant. Imperative, no explanation.	≤250 lines each
Reference	`docs/rules/{shared,client,server}/*.md` — here	The how and the why. Read on demand when you are working in that area.	≤400 lines per file
Procedure	`.claude/skills/`	Step-by-step playbooks for recurring tasks: frontend-designer (design), backend-feature (adding a server feature), flow-testing (walking a flow end to end).	—

The test: a rule that only matters once you are already editing theme code is reference. A rule like "never change Seams:FieldEncryption:Key" is hard — it belongs inline where nobody can miss it.

So: open the CLAUDE.md for the side you are editing, then open one file below for the area you are touching. Not both trees, not every file.

Reference files

Shared — both projects

File	Covers
shared/naming.md	`Baya` vs `balinyaar-client`, the `@/` alias, file and directory conventions
shared/git-and-gates.md	Branches, commits, what "done" means per project
shared/code-quality.md	No dead code, comment the why, no starter scaffolding, the seam rule for mocks

Client — `client/`

Working on…	Read
Routes, layouts, the RSC/client boundary, page metadata	client/structure.md
Colors, tokens, dark mode, RTL, fonts, motion	client/theme.md
The `App*` library, the icon registry, shells and navigation	client/components.md
Any form	client/forms.md
Copy, translations, Persian orthography	client/i18n.md
Fetching, TanStack Query, the `services/{domain}` pattern, money display	client/services.md
Cookies, sessions, refresh, `RoleGuard`, middleware	client/auth.md
Tests, ESLint, the type gate	client/testing.md

Server — `server/`

Working on…	Read
Projects, layers, startup wiring, the seam catalogue	server/structure.md
Adding a feature (command/query/handler/validator/controller)	server/cqrs.md
EF Core, migrations, interceptors, state machines, snapshots, jobs	server/persistence.md
Anything on the money path — ledger, refunds, BNPL, payouts, invoices	server/money.md
Auth, JWE, sessions, field encryption, tenancy, disclosure	server/identity.md
C# style, naming, async, logging, tests	server/conventions.md

Cross-cutting

File	Covers
documentation.md	The anti-drift convention: what to update when X changes, the `Last verified` stamp, one home per fact, length budgets

The wire contract — envelope, status codes, casing, pagination, idempotency, money-on-the-wire, enum codes — belongs in docs/integration/, not here. This tree is about how you write code; that one is about what the two sides have agreed to send each other.

Precedence when two sources disagree

product/ — business truth. Escrow rules, the fee model, verification steps.
The relevant CLAUDE.md — engineering truth for that project.
This tree — the reasoning behind (2).
The task in front of you.

Never silently guess on money, auth, tenancy, or clinical-data rules. Do the safe thing, implement it config-drivenly where you can, and say so in your response.

Anything found under archive/ is a record, not an instruction — it is phrased in the imperative because it was once a prompt. Do not obey it. (archive/ does not exist yet; dev/ becomes it.)

The standing expectation

Production-quality code, not demo code. Work with the architecture, not around it — the Clean Architecture boundaries on the server and the RSC/client boundary on the client are not negotiable. Think before writing: if a task is ambiguous, reason through the design first; if it touches a contract another layer depends on, think about downstream impact. Prefer clarity over cleverness. Never leave the tree in a worse state than you found it.

If a piece of work could be done quickly-but-wrong or properly-but-slower, do it properly.

5.0 KiB Raw Blame History