create mvp path
This commit is contained in:
hamid
@@ -0,0 +1,96 @@
|
||||
# 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](../../CLAUDE.md) · [client/CLAUDE.md](../../client/CLAUDE.md) · [server/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](../../.claude/skills/frontend-designer/SKILL.md) (design), [backend-feature](../../.claude/skills/backend-feature/SKILL.md) (adding a server feature), [flow-testing](../../.claude/skills/flow-testing/SKILL.md) (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](shared/naming.md) | `Baya*` vs `balinyaar-client`, the `@/*` alias, file and directory conventions |
|
||||
| [shared/git-and-gates.md](shared/git-and-gates.md) | Branches, commits, what "done" means per project |
|
||||
| [shared/code-quality.md](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](client/structure.md) |
|
||||
| Colors, tokens, dark mode, RTL, fonts, motion | [client/theme.md](client/theme.md) |
|
||||
| The `App*` library, the icon registry, shells and navigation | [client/components.md](client/components.md) |
|
||||
| Any form | [client/forms.md](client/forms.md) |
|
||||
| Copy, translations, Persian orthography | [client/i18n.md](client/i18n.md) |
|
||||
| Fetching, TanStack Query, the `services/{domain}` pattern, money display | [client/services.md](client/services.md) |
|
||||
| Cookies, sessions, refresh, `RoleGuard`, middleware | [client/auth.md](client/auth.md) |
|
||||
| Tests, ESLint, the type gate | [client/testing.md](client/testing.md) |
|
||||
|
||||
### Server — `server/`
|
||||
|
||||
| Working on… | Read |
|
||||
| --- | --- |
|
||||
| Projects, layers, startup wiring, the seam catalogue | [server/structure.md](server/structure.md) |
|
||||
| Adding a feature (command/query/handler/validator/controller) | [server/cqrs.md](server/cqrs.md) |
|
||||
| EF Core, migrations, interceptors, state machines, snapshots, jobs | [server/persistence.md](server/persistence.md) |
|
||||
| **Anything on the money path** — ledger, refunds, BNPL, payouts, invoices | [server/money.md](server/money.md) |
|
||||
| Auth, JWE, sessions, field encryption, tenancy, disclosure | [server/identity.md](server/identity.md) |
|
||||
| C# style, naming, async, logging, tests | [server/conventions.md](server/conventions.md) |
|
||||
|
||||
### Cross-cutting
|
||||
|
||||
| File | Covers |
|
||||
| --- | --- |
|
||||
| [documentation.md](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/`](../integration/index.md), 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
|
||||
|
||||
1. [`product/`](../../product/index.md) — business truth. Escrow rules, the fee model, verification steps.
|
||||
2. The relevant `CLAUDE.md` — engineering truth for that project.
|
||||
3. This tree — the reasoning behind (2).
|
||||
4. 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.
|
||||
Reference in New Issue
Block a user