feat(doctrine): architecture defaults move to lib/architecture-defaults.md, Web APIs to rules/rest-api.md
This commit is contained in:
1 parent
de6e51ce7a
commit
2fe5291a13
13 files changed
+92
-66
No files matched your search
@@ -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
@@ -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.
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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).
|
||||
@@ -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)
|
||||
|
||||
@@ -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
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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).
|
||||
|
||||
Reference in new issue
Block a user