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.
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
start, same cost as the global memory. Extract from CLAUDE.global.md only
what can be path-scoped (the token win) or what is generated; always-on
doctrine stays in CLAUDE.global.md. Exception: a standalone user-authored
rule set that would bust the 320-line density budget may live here WITHOUT
`paths:` (always-on load) — writing-style.md (BDR-085), default-language.md
(BDR-118), secure-by-default.md (BDR-120). `paths:` globs match against the
CURRENT project's tree — a broad glob (e.g. `rules/**`) can fire in foreign
projects; keep rule bodies tiny.
Claude Reads a file matching a glob (never on the Write of a new file;
sub-agents too); a rule WITHOUT it loads at session start, same cost as the
global memory. Doctrine leaves CLAUDE.global.md only for a carrier that fires
when it is needed (BDR-125 phase 1: a path rule, a hook, a lib our skills
Read), with one always-on line wherever plain chat still needs the rule.
Exception: a standalone user-authored rule set that would bust the 320-line
density budget may live here WITHOUT `paths:` (always-on load) —
writing-style.md (BDR-085), secure-by-default.md (BDR-120);
`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
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.
# Architecture decisions
Override default framework/tooling choices at project creation, scaffolding,
brainstorming.
## 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.
## 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.
New project, scaffolding, stack brainstorm or whole-project rewrite: Rust
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
`~/.claude/lib/architecture-defaults.md` before proposing a stack.
## Version control — gitflow (universal)
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)` |
| "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 |
| 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 |
| 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 |
+2 -1
View File
@@ -16,6 +16,7 @@ Deliver a buildable skeleton: structure + config + empty entry points. No featur
2. Approved DESIGN (from brainstorming)
3. `~/.claude/templates/project-CLAUDE.md`
4. `~/.claude/CLAUDE.md`
5. `~/.claude/lib/architecture-defaults.md`
If any missing → STOP.
@@ -31,7 +32,7 @@ Store: `DOCKER_RELEVANT = true/false`. If true → Docker is additional, project
## 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>`.
Required: overview, stack+version, build/test/lint/docker commands (exact), folder tree, architecture, conventions, exceptions, deps, workflow.
Write to `CLAUDE.md` at project root.
+2 -2
View File
@@ -539,8 +539,8 @@ it is.
**§0 line, mandatory when not server-rendered:**
`Rendering: client-rendered — On-page NOT scored (content absent from served
HTML). Global score excludes it. Fix: SSR/SSG (CLAUDE.md: public sites are
never SPAs).`
HTML). Global score excludes it. Fix: SSR/SSG
(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,
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
## 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)
- SQL injections (string concat dans queries brutes)
- 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.
## 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
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.
## 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
when concrete and local: simplification, dedup against an existing
helper, obvious perf.
- **conformity** — read project `CLAUDE.md` (+ `~/.claude/CLAUDE.md`)
FIRST, then check changed code against those norms. This repo's:
- **conformity** — read project `CLAUDE.md` (+ `~/.claude/CLAUDE.md` and
`~/.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
global state, intent-not-mechanics comments, explicit naming, versioned
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
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.
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;
@@ -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 —
every field the scaffolder consumes crosses the dispatch): BRIEF (verbatim)
+ 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
while waiting.
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`.
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 :**
| 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>.
Brainstorm WITHIN these — don't re-explore a direction an in-force BDR rejects or a
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
(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).