From 2fe5291a13203893ff02106add00a26255ebb954 Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 29 Oct 2026 13:00:58 +0100 Subject: [PATCH] feat(doctrine): architecture defaults move to lib/architecture-defaults.md, Web APIs to rules/rest-api.md --- .claude/rules/rules-maintenance.md | 21 ++++++----- CLAUDE.global.md | 28 ++------------ agents/interviewer.md | 2 +- agents/scaffolder.md | 3 +- agents/seo-analyzer.md | 4 +- lib/architecture-defaults.md | 49 +++++++++++++++++++++++++ lib/project-archetypes/rest-api-node.md | 2 +- rules/default-language.md | 23 ------------ rules/rest-api.md | 8 +++- skills/audit-delta/SKILL.md | 5 ++- skills/init-project/SKILL.md | 6 ++- skills/onboard/SKILL.md | 4 ++ skills/ship-feature/SKILL.md | 3 ++ 13 files changed, 92 insertions(+), 66 deletions(-) create mode 100644 lib/architecture-defaults.md delete mode 100644 rules/default-language.md diff --git a/.claude/rules/rules-maintenance.md b/.claude/rules/rules-maintenance.md index 9089601..8935a23 100644 --- a/.claude/rules/rules-maintenance.md +++ b/.claude/rules/rules-maintenance.md @@ -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, diff --git a/CLAUDE.global.md b/CLAUDE.global.md index fabc896..ae7f491 100644 --- a/CLAUDE.global.md +++ b/CLAUDE.global.md @@ -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. diff --git a/agents/interviewer.md b/agents/interviewer.md index 6cafcfd..e08acc6 100644 --- a/agents/interviewer.md +++ b/agents/interviewer.md @@ -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 | diff --git a/agents/scaffolder.md b/agents/scaffolder.md index 9d24a93..adfb05f 100644 --- a/agents/scaffolder.md +++ b/agents/scaffolder.md @@ -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 — `. Required: overview, stack+version, build/test/lint/docker commands (exact), folder tree, architecture, conventions, exceptions, deps, workflow. Write to `CLAUDE.md` at project root. diff --git a/agents/seo-analyzer.md b/agents/seo-analyzer.md index 7613567..f6a3b91 100644 --- a/agents/seo-analyzer.md +++ b/agents/seo-analyzer.md @@ -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 diff --git a/lib/architecture-defaults.md b/lib/architecture-defaults.md new file mode 100644 index 0000000..5866d39 --- /dev/null +++ b/lib/architecture-defaults.md @@ -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). diff --git a/lib/project-archetypes/rest-api-node.md b/lib/project-archetypes/rest-api-node.md index 239e484..2c5f71b 100644 --- a/lib/project-archetypes/rest-api-node.md +++ b/lib/project-archetypes/rest-api-node.md @@ -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) diff --git a/rules/default-language.md b/rules/default-language.md deleted file mode 100644 index 9eb15fe..0000000 --- a/rules/default-language.md +++ /dev/null @@ -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. diff --git a/rules/rest-api.md b/rules/rest-api.md index e971f83..e4e7a0f 100644 --- a/rules/rest-api.md +++ b/rules/rest-api.md @@ -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. diff --git a/skills/audit-delta/SKILL.md b/skills/audit-delta/SKILL.md index c0a6c3a..c2a2ee0 100644 --- a/skills/audit-delta/SKILL.md +++ b/skills/audit-delta/SKILL.md @@ -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 diff --git a/skills/init-project/SKILL.md b/skills/init-project/SKILL.md index 1fba43b..ec51f8a 100644 --- a/skills/init-project/SKILL.md +++ b/skills/init-project/SKILL.md @@ -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. diff --git a/skills/onboard/SKILL.md b/skills/onboard/SKILL.md index f8cc5d3..de4d4a4 100644 --- a/skills/onboard/SKILL.md +++ b/skills/onboard/SKILL.md @@ -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/.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 | diff --git a/skills/ship-feature/SKILL.md b/skills/ship-feature/SKILL.md index 1cf342c..850bee4 100644 --- a/skills/ship-feature/SKILL.md +++ b/skills/ship-feature/SKILL.md @@ -110,6 +110,9 @@ not the raw request alone: Existing code that bears: . 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).