feat(doctrine): architecture defaults move to lib/architecture-defaults.md, Web APIs to rules/rest-api.md

This commit is contained in:
bchanot committed 2026-10-29 13:00:58 +01:00
1 parent de6e51ce7a
commit 2fe5291a13
13 files changed
+92 -66

No files matched your search

+12 -9
View File
@@ -9,15 +9,18 @@ Modular instruction files loaded by Claude Code alongside the global memory.
projects). One rule = one file = one concern. projects). One rule = one file = one concern.
A rule WITH `paths:` YAML frontmatter (glob list) loads lazily — only when A rule WITH `paths:` YAML frontmatter (glob list) loads lazily — only when
Claude reads a file matching a glob; a rule WITHOUT it loads at session Claude Reads a file matching a glob (never on the Write of a new file;
start, same cost as the global memory. Extract from CLAUDE.global.md only sub-agents too); a rule WITHOUT it loads at session start, same cost as the
what can be path-scoped (the token win) or what is generated; always-on global memory. Doctrine leaves CLAUDE.global.md only for a carrier that fires
doctrine stays in CLAUDE.global.md. Exception: a standalone user-authored when it is needed (BDR-125 phase 1: a path rule, a hook, a lib our skills
rule set that would bust the 320-line density budget may live here WITHOUT Read), with one always-on line wherever plain chat still needs the rule.
`paths:` (always-on load) — writing-style.md (BDR-085), default-language.md Exception: a standalone user-authored rule set that would bust the 320-line
(BDR-118), secure-by-default.md (BDR-120). `paths:` globs match against the density budget may live here WITHOUT `paths:` (always-on load) —
CURRENT project's tree — a broad glob (e.g. `rules/**`) can fire in foreign writing-style.md (BDR-085), secure-by-default.md (BDR-120);
projects; keep rule bodies tiny. `lib/tests/user-rules.test.sh` locks that set. `paths:` globs match against
the CURRENT project's tree, gitignore-style (a pattern without an inner `/`
matches at any depth, hidden dirs included) — a broad glob (e.g. `rules/**`)
can fire in foreign projects; keep rule bodies tiny.
Docs: https://code.claude.com/docs/en/memory.md#path-specific-rules Docs: https://code.claude.com/docs/en/memory.md#path-specific-rules
Machine-owned: `rules/context7.md` is DELETED BY DESIGN (BDR-053, Machine-owned: `rules/context7.md` is DELETED BY DESIGN (BDR-053,
+4 -24
View File
@@ -140,30 +140,10 @@ their CAPITALIZE step. Session close (`/close` = `/capitalize --ritual`):
what was decided → decisions, learned → learnings, blocked → blockers. what was decided → decisions, learned → learnings, blocked → blockers.
# Architecture decisions # Architecture decisions
Override default framework/tooling choices at project creation, scaffolding, New project, scaffolding, stack brainstorm or whole-project rewrite: Rust
brainstorming. by default, a public site is never a SPA (Astro; Next.js when SSR is
needed), every web API versioned `/api/v1/` from day one. Read
## Public websites — never SPA `~/.claude/lib/architecture-defaults.md` before proposing a stack.
A public site meant to be indexed (landing, portfolio, blog, e-commerce,
docs) is never a pure SPA (CRA, Vite React, Vue SPA): the empty HTML shell
hides content from search and AI engines, SEO and GEO destroyed.
- **Astro** by default for informational sites: static HTML at build, zero
JS by default, React/Vue/Svelte islands for interactive parts.
- **Next.js** when dynamic SSR is needed (personalized content, server-side
auth, API routes, hybrid app).
- **React SPA** only for what needs no indexing: admin panels, dashboards,
auth-gated apps, internal tools. Mixed project: Astro/Next for public,
React island (`client:only`) for admin.
- At brainstorming (`/init-project`, `/ship-feature` STEP 1), public site
and no framework named → propose Astro, explain why not SPA. Never
silently pick React CRA.
## Web APIs — always versioned
Every endpoint versioned from day one: `/api/v1/...`, no bare `/api/`; the
router mirrors it (`api/v1/routes/`). Breaking change → `v2`, the old
version keeps working and clients migrate at their pace; non-breaking
additions → current version. Each version is a self-contained contract,
never bent to match a newer one.
## Version control — gitflow (universal) ## Version control — gitflow (universal)
Every git action follows gitflow, inside a skill or for an ad-hoc commit. Every git action follows gitflow, inside a skill or for an ad-hoc commit.
+1 -1
View File
@@ -23,7 +23,7 @@ Gather context. Produce complete PROJECT BRIEF as single source of truth.
| Answer vague/ambiguous | One targeted follow-up on that item only | Gap: record it in OPEN DECISIONS with the safest reading, marked `(assumed)` — never invent a confident value. Visible / public-name / scope item: one more targeted question instead, never `(assumed)` | | Answer vague/ambiguous | One targeted follow-up on that item only | Gap: record it in OPEN DECISIONS with the safest reading, marked `(assumed)` — never invent a confident value. Visible / public-name / scope item: one more targeted question instead, never `(assumed)` |
| "I don't know / you decide" | Propose ONE concrete default + why, ask yes/no | Take the default, mark `(assumed)`, list in OPEN DECISIONS | | "I don't know / you decide" | Propose ONE concrete default + why, ask yes/no | Take the default, mark `(assumed)`, list in OPEN DECISIONS |
| Contradictory answers (e.g. embedded runtime + managed cloud DB) | Name the contradiction, ask which side wins | Put BOTH options in OPEN DECISIONS; do not silently pick one | | Contradictory answers (e.g. embedded runtime + managed cloud DB) | Name the contradiction, ask which side wins | Put BOTH options in OPEN DECISIONS; do not silently pick one |
| Language not stated (new project / from scratch / whole-project rewrite) | Propose Rust + why (`rules/default-language.md`); name the contraindication if another language fits better (browser frontend, mandated platform, missing ecosystem) | Rust, marked `(assumed)`, listed in OPEN DECISIONS | | Language not stated (new project / from scratch / whole-project rewrite) | Propose Rust + why (`~/.claude/lib/architecture-defaults.md` § Default language); name the contraindication if another language fits better (browser frontend, mandated platform, missing ecosystem) | Rust, marked `(assumed)`, listed in OPEN DECISIONS |
| Project has an API, a database, messaging, cloud functions or a UI | Apply `rules/secure-by-default.md`: note under QUALITY which of the six guardrail domains apply, and whether the accessibility baseline (`rules/a11y.md`) applies, and list each dashboard-only item (spend cap, WAF, budget alert) in OPEN DECISIONS as manual | A domain applies and nothing is planned: list it in OPEN DECISIONS, never drop it silently | | Project has an API, a database, messaging, cloud functions or a UI | Apply `rules/secure-by-default.md`: note under QUALITY which of the six guardrail domains apply, and whether the accessibility baseline (`rules/a11y.md`) applies, and list each dashboard-only item (spend cap, WAF, budget alert) in OPEN DECISIONS as manual | A domain applies and nothing is planned: list it in OPEN DECISIONS, never drop it silently |
| Partial answer to the block | Re-ask ONLY the missing items in the follow-up round | Missing fields → `none stated` + OPEN DECISIONS entry | | Partial answer to the block | Re-ask ONLY the missing items in the follow-up round | Missing fields → `none stated` + OPEN DECISIONS entry |
| Feature list balloons (>10) | Keep the 10 the user ranks first as V1 | Overflow goes to OUT OF SCOPE with a `(deferred by budget)` tag | | Feature list balloons (>10) | Keep the 10 the user ranks first as V1 | Overflow goes to OUT OF SCOPE with a `(deferred by budget)` tag |
+2 -1
View File
@@ -16,6 +16,7 @@ Deliver a buildable skeleton: structure + config + empty entry points. No featur
2. Approved DESIGN (from brainstorming) 2. Approved DESIGN (from brainstorming)
3. `~/.claude/templates/project-CLAUDE.md` 3. `~/.claude/templates/project-CLAUDE.md`
4. `~/.claude/CLAUDE.md` 4. `~/.claude/CLAUDE.md`
5. `~/.claude/lib/architecture-defaults.md`
If any missing → STOP. If any missing → STOP.
@@ -31,7 +32,7 @@ Store: `DOCKER_RELEVANT = true/false`. If true → Docker is additional, project
## PHASE 1 — GENERATE CLAUDE.md ## PHASE 1 — GENERATE CLAUDE.md
Read `~/.claude/templates/project-CLAUDE.md` and `~/.claude/CLAUDE.md`. Read `~/.claude/templates/project-CLAUDE.md`, `~/.claude/CLAUDE.md` and `~/.claude/lib/architecture-defaults.md`.
Fill every section from BRIEF + DESIGN. No placeholders. Irrelevant sections → `N/A — <reason>`. Fill every section from BRIEF + DESIGN. No placeholders. Irrelevant sections → `N/A — <reason>`.
Required: overview, stack+version, build/test/lint/docker commands (exact), folder tree, architecture, conventions, exceptions, deps, workflow. Required: overview, stack+version, build/test/lint/docker commands (exact), folder tree, architecture, conventions, exceptions, deps, workflow.
Write to `CLAUDE.md` at project root. Write to `CLAUDE.md` at project root.
+2 -2
View File
@@ -539,8 +539,8 @@ it is.
**§0 line, mandatory when not server-rendered:** **§0 line, mandatory when not server-rendered:**
`Rendering: client-rendered — On-page NOT scored (content absent from served `Rendering: client-rendered — On-page NOT scored (content absent from served
HTML). Global score excludes it. Fix: SSR/SSG (CLAUDE.md: public sites are HTML). Global score excludes it. Fix: SSR/SSG
never SPAs).` (lib/architecture-defaults.md: public sites are never SPAs).`
This is the honest half of the R1/R2 call: we do not render JS (no Playwright, This is the honest half of the R1/R2 call: we do not render JS (no Playwright,
no Chromium), so we do not pretend to see what JS paints. Refusing is the no Chromium), so we do not pretend to see what JS paints. Refusing is the
+49
View File
@@ -0,0 +1,49 @@
# Architecture defaults — read before proposing a stack
Read at project creation, scaffolding, a stack brainstorm or a whole-project
rewrite (BDR-125 phase 1). The three defaults are named always-on in
`~/.claude/CLAUDE.md` § "Architecture decisions"; the detail lives here.
## Public websites — never SPA
A public site meant to be indexed (landing, portfolio, blog, e-commerce,
docs) is never a pure SPA (CRA, Vite React, Vue SPA): the empty HTML shell
hides content from search and AI engines, SEO and GEO destroyed.
- **Astro** by default for informational sites: static HTML at build, zero
JS by default, React/Vue/Svelte islands for interactive parts.
- **Next.js** when dynamic SSR is needed (personalized content, server-side
auth, API routes, hybrid app).
- **React SPA** only for what needs no indexing: admin panels, dashboards,
auth-gated apps, internal tools. Mixed project: Astro/Next for public,
React island (`client:only`) for admin.
- At brainstorming (`/init-project`, `/ship-feature` STEP 1), public site
and no framework named → propose Astro, explain why not SPA. Never
silently pick React CRA.
## Default language — Rust
Scope: a new project, a project from scratch, or a whole-project
refactor or rewrite the user asks for. Not a module refactor or a feature
inside an existing codebase: that keeps the codebase's language.
Rust is the default. Two candidates equal on features, security,
performance, reliability and ease of use or maintenance → Rust wins.
Where Rust can do the job, Rust does it.
Another language needs a demonstrated gain on one of those axes, stated
at the choice: a browser frontend (TypeScript, Astro per the web rules),
a platform that mandates its language (Swift, Kotlin), an ecosystem Rust
lacks (ML research → Python), a throwaway script where Rust's build
cycle costs more than it returns. "Rust is slower to write" alone is not
a gain.
At brainstorming (`/init-project`, `/ship-feature` STEP 1, `/refactor`
of a whole project): language not named → propose Rust, name the
contraindication if you pick something else. Never silently default to
Python, Node or Go. Mixed project: Rust for everything server-side,
CLI, systems and tooling; the exception stays scoped to the part that
earned it.
## Web APIs — always versioned
Every endpoint `/api/v1/...` from day one; breaking change → `v2`, the old
version keeps working. Full rule: `~/.claude/rules/rest-api.md` § Versioning
(loads on API files).
+1 -1
View File
@@ -55,7 +55,7 @@ API backend Node.js pure (Express / Fastify / Koa / Hapi / NestJS), sans fronten
- **UI/UX** : N/A - **UI/UX** : N/A
## Typical pain points ## Typical pain points
- Pas de versioning API (/api/v1/) — flag CLAUDE.md : "Web APIs — always versioned" - Pas de versioning API (/api/v1/) — flag `rules/rest-api.md` § Versioning
- Validation input absente (pas de Zod/Joi/class-validator) - Validation input absente (pas de Zod/Joi/class-validator)
- SQL injections (string concat dans queries brutes) - SQL injections (string concat dans queries brutes)
- Auth faible (pas de hash password, ou MD5/SHA1) - Auth faible (pas de hash password, ou MD5/SHA1)
-23
View File
@@ -1,23 +0,0 @@
# Default language — Rust
Scope: a new project, a project from scratch, or a whole-project
refactor or rewrite the user asks for. Not a module refactor or a feature
inside an existing codebase: that keeps the codebase's language.
Rust is the default. Two candidates equal on features, security,
performance, reliability and ease of use or maintenance → Rust wins.
Where Rust can do the job, Rust does it.
Another language needs a demonstrated gain on one of those axes, stated
at the choice: a browser frontend (TypeScript, Astro per the web rules),
a platform that mandates its language (Swift, Kotlin), an ecosystem Rust
lacks (ML research → Python), a throwaway script where Rust's build
cycle costs more than it returns. "Rust is slower to write" alone is not
a gain.
At brainstorming (`/init-project`, `/ship-feature` STEP 1, `/refactor`
of a whole project): language not named → propose Rust, name the
contraindication if you pick something else. Never silently default to
Python, Node or Go. Mixed project: Rust for everything server-side,
CLI, systems and tooling; the exception stays scoped to the part that
earned it.
+6 -2
View File
@@ -31,7 +31,7 @@ wait, or 202 + status URL. Retention outlives the longest retry
path, dead-letter replay included. path, dead-letter replay included.
## Naming ## Naming
Plural nouns for endpoints (`/api/tasks`), no verbs. camelCase query Plural nouns for endpoints (`/api/v1/tasks`), no verbs. camelCase query
params and response fields. UPPER_SNAKE enum values. Boolean fields params and response fields. UPPER_SNAKE enum values. Boolean fields
prefixed is/has/can. prefixed is/has/can.
@@ -40,4 +40,8 @@ Every observable behavior — undocumented quirks, error text, timing —
becomes a de facto contract once someone depends on it. becomes a de facto contract once someone depends on it.
## Versioning ## Versioning
CLAUDE.md § Web APIs — always versioned. Not repeated here. Every endpoint versioned from day one: `/api/v1/...`, no bare `/api/`; the
router mirrors it (`api/v1/routes/`). Breaking change → `v2`, the old
version keeps working and clients migrate at their pace; non-breaking
additions → current version. Each version is a self-contained contract,
never bent to match a newer one.
+3 -2
View File
@@ -273,8 +273,9 @@ Then offer to capitalize (per CLAUDE.md): recurring finding patterns →
errors, resource leaks (missing trap/close/finally). Improvements only errors, resource leaks (missing trap/close/finally). Improvements only
when concrete and local: simplification, dedup against an existing when concrete and local: simplification, dedup against an existing
helper, obvious perf. helper, obvious perf.
- **conformity** — read project `CLAUDE.md` (+ `~/.claude/CLAUDE.md`) - **conformity** — read project `CLAUDE.md` (+ `~/.claude/CLAUDE.md` and
FIRST, then check changed code against those norms. This repo's: `~/.claude/lib/architecture-defaults.md`) FIRST, then check changed code
against those norms. This repo's:
≤25 logic lines/function, ≤80 chars/line, ≤5 params, ≤5 locals, no ≤25 logic lines/function, ≤80 chars/line, ≤5 params, ≤5 locals, no
global state, intent-not-mechanics comments, explicit naming, versioned global state, intent-not-mechanics comments, explicit naming, versioned
APIs (`/api/v1/`), no-SPA-for-public-sites, security defaults. Foreign APIs (`/api/v1/`), no-SPA-for-public-sites, security defaults. Foreign
+5 -1
View File
@@ -71,6 +71,9 @@ Load `$HOME/.claude/agents/analyzer.md`. Analyze BRIEF: existing code, stack con
## STEP 3 — DESIGN ## STEP 3 — DESIGN
Invoke `brainstorming` (vendored superpowers skill) with BRIEF + ANALYSIS REPORT. Invoke `brainstorming` (vendored superpowers skill) with BRIEF + ANALYSIS REPORT.
Read `~/.claude/lib/architecture-defaults.md` first and pass it as binding
context: its defaults (Rust, never a SPA for a public site, `/api/v1/`) hold
unless the BRIEF names otherwise.
Produce DESIGN: stack+versions, full folder tree, module responsibilities, data flow, interfaces (signatures only), config+tooling, test strategy, resolved decisions, prereqs list. Produce DESIGN: stack+versions, full folder tree, module responsibilities, data flow, interfaces (signatures only), config+tooling, test strategy, resolved decisions, prereqs list.
Then run pass B of `$HOME/.claude/lib/contract-interview.md` against the DESIGN Then run pass B of `$HOME/.claude/lib/contract-interview.md` against the DESIGN
(minus what the BRIEF and the brainstorm settled): one batch before STEP 4; (minus what the BRIEF and the brainstorm settled): one batch before STEP 4;
@@ -102,7 +105,8 @@ BDR-077 : le design est CLOS au gate #1, le scaffold est de l'exécution,
plus jamais inline sur le modèle de session). Pass IN THE PROMPT (LRN-126 — plus jamais inline sur le modèle de session). Pass IN THE PROMPT (LRN-126 —
every field the scaffolder consumes crosses the dispatch): BRIEF (verbatim) every field the scaffolder consumes crosses the dispatch): BRIEF (verbatim)
+ DESIGN (verbatim) + paths `~/.claude/templates/project-CLAUDE.md` + + DESIGN (verbatim) + paths `~/.claude/templates/project-CLAUDE.md` +
`~/.claude/CLAUDE.md`. A STOP (missing input) comes back as its report — `~/.claude/CLAUDE.md` + `~/.claude/lib/architecture-defaults.md`. A STOP
(missing input) comes back as its report —
resolve here, re-dispatch. The ~30s liveness pings are THIS loop's job resolve here, re-dispatch. The ~30s liveness pings are THIS loop's job
while waiting. while waiting.
Creates: CLAUDE.md, `.claude/settings.json`, `.claudeignore`, `.gitignore`, `.env.example`, empty entry points. NO README, NO features. Creates: CLAUDE.md, `.claude/settings.json`, `.claudeignore`, `.gitignore`, `.env.example`, empty entry points. NO README, NO features.
+4
View File
@@ -371,6 +371,10 @@ Attendre la fin. Vérifier que `.onboard-audit/analyze.md` existe et est non vid
Lire le bloc `audit_stack:` du fichier `~/.claude/lib/project-archetypes/<archetype>.md`. Lire le bloc `audit_stack:` du fichier `~/.claude/lib/project-archetypes/<archetype>.md`.
Les audits jugent l'architecture contre `~/.claude/lib/architecture-defaults.md`
(site public jamais SPA, API `/api/v1/`, Rust par défaut pour une réécriture) :
passer ce chemin dans chaque brief d'audit.
**Mapping audit_stack entry → action :** **Mapping audit_stack entry → action :**
| Entry | Action | Livraison | | Entry | Action | Livraison |
+3
View File
@@ -110,6 +110,9 @@ not the raw request alone:
Existing code that bears: <ANALYSIS CONTEXT / KEY COMPONENTS from 0d>. Existing code that bears: <ANALYSIS CONTEXT / KEY COMPONENTS from 0d>.
Brainstorm WITHIN these — don't re-explore a direction an in-force BDR rejects or a Brainstorm WITHIN these — don't re-explore a direction an in-force BDR rejects or a
BLK already closed." BLK already closed."
When the feature picks a language, a framework or an API shape, Read
`~/.claude/lib/architecture-defaults.md` first and add its defaults to the
in-force constraints.
Inject ONLY what constrains: the NON-BINDING count does NOT enter the brainstorm input Inject ONLY what constrains: the NON-BINDING count does NOT enter the brainstorm input
(the injection inherits the OUTPUT filter — detail what binds, drop what doesn't). (the injection inherits the OUTPUT filter — detail what binds, drop what doesn't).
Consumption = INPUT INJECTION (we can't modify the external skill; we control its input). Consumption = INPUT INJECTION (we can't modify the external skill; we control its input).