From 4181bdc9cf5039c39b70dec261cbfdc111656f59 Mon Sep 17 00:00:00 2001 From: bastien Date: Tue, 5 May 2026 23:46:15 +0200 Subject: [PATCH] docs(memory): mandate caveman format for registries MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add "Format — registries ALWAYS caveman" rule alongside existing English-only rule. All writes to .claude/memory/*.md (decisions, learnings, blockers, journal, evals) must drop articles/filler/hedging while preserving technical terms, IDs, dates, and code blocks exact. Rationale: registries load every session start — caveman cuts ~40% input tokens with zero loss of substance. Applies to direct writes and skill-driven CAPITALIZE steps (close, ship-feature, feat, bugfix, hotfix, commit-change). Existing entries: compress on demand via /caveman:compress . Self-applied: CLAUDE.md prose itself compressed in same pass. Co-Authored-By: Claude --- CLAUDE.md | 95 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 49 insertions(+), 46 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 2f34ff7..19a5dcf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -20,37 +20,37 @@ Apply unless repo-specific instructions override. ## Refactoring - Priority: safety → readability → consistency. - Remove dead code, stale comments, obsolete flags after changes. -- Non-trivial change: ask "more elegant solution exists?" Hacky fix → rebuild cleanly. Don't over-engineer. +- Non-trivial change: ask "more elegant solution exists?" Hacky fix → rebuild cleanly. No over-engineer. ## Session start -1. Read `.claude/memory/` — the 5 registries (decisions, learnings, blockers, journal, evals). Apply before touching anything. +1. Read `.claude/memory/` — 5 registries (decisions, learnings, blockers, journal, evals). Apply before touching anything. 2. Read `.claude/tasks/TODO.md` — understand current state. -3. If `.claude/memory/` or `.claude/tasks/TODO.md` is missing, create before starting (templates at `~/.claude/templates/memory/`). +3. If `.claude/memory/` or `.claude/tasks/TODO.md` missing, create before starting (templates at `~/.claude/templates/memory/`). ## Workflow -- Write/modify task touching logic (new behavior, control flow, state, API, dependencies): plan in `.claude/tasks/TODO.md` first, decomposed into subtasks. Task count doesn't matter — one complex task still requires a plan. When in doubt about complexity, skip the plan (be pragmatic). -- Confirm before implementing only when real trade-offs exist (multiple valid approaches, breaking change, destructive action) — otherwise proceed. +- Write/modify task touching logic (new behavior, control flow, state, API, dependencies): plan in `.claude/tasks/TODO.md` first, decomposed into subtasks. Task count irrelevant — one complex task still needs plan. When in doubt about complexity, skip plan (be pragmatic). +- Confirm before implementing only when real trade-offs exist (multiple valid approaches, breaking change, destructive action) — else proceed. - Exempt from `.claude/tasks/TODO.md`: pure reads, explanations, questions, typos, cosmetic CSS tweaks, single config-value changes. Aligns with `/hotfix` scope (≤2 files, obvious fix). - Minimal changes unless broader refactor requested. State trade-offs. - Use sub-agents to keep main context clean — one task per sub-agent. Invest more compute on hard problems. -- One question upfront if needed — never interrupt mid-task. *(Exception: orchestrators' mandatory validation gates — example, /init-project STEP 4/7, /ship-feature STEP 3 — are exempt.)* +- One question upfront if needed — never interrupt mid-task. *(Exception: orchestrators' mandatory validation gates — example, /init-project STEP 4/7, /ship-feature STEP 3 — exempt.)* - Bug received → fix directly: check logs, find root cause, resolve autonomously. -- If something goes wrong: STOP and re-plan — never push through. +- Something goes wrong: STOP and re-plan — never push through. - Report deviations: minor/justified → explain. Significant/unjustified → ask. -- Root causes only. No temporary fixes. Never assume — verify paths, APIs, variables before use. +- Root causes only. No temp fixes. Never assume — verify paths, APIs, variables before use. ## After code changes 1. Run tests, lint, build, type-check if available. -2. Report what was verified and what wasn't. +2. Report what verified, what not. 3. List remaining risks and surviving deviations. -4. Never mark complete without proof it works. Bar: "would a staff engineer approve this?" -5. After any correction or notable event, capitalize to the right registry in `.claude/memory/` (see "Memory registries" section below). +4. Never mark complete without proof it works. Bar: "would staff engineer approve this?" +5. After any correction or notable event, capitalize to right registry in `.claude/memory/` (see "Memory registries" below). ## Task tracking (`.claude/tasks/TODO.md`) -Applies to any write/modify task touching logic, regardless of task count. Skip for reads and trivial edits (see Workflow). +Applies to any write/modify task touching logic, regardless of count. Skip for reads and trivial edits (see Workflow). -1. Plan → write the task in `.claude/tasks/TODO.md` before touching code. +1. Plan → write task in `.claude/tasks/TODO.md` before touching code. 2. Decompose → split each complex task into subtasks (one subtask = one coherent change). 3. Track → check off subtasks as you go. 4. Summarize → high-level summary at each milestone. @@ -64,23 +64,26 @@ Five append-only registries persist across sessions. Read all at session start. | `decisions.md` | BDR-XXX | Design/architecture choices with rationale + alternatives + status | | `learnings.md` | LRN-XXX | Reusable patterns observed + context + future application (replaces LESSONS) | | `blockers.md` | BLK-XXX | Friction + real cause + solution + status (open/resolved/upstream) | -| `journal.md` | date heading | 3-5 lines/session — what was done, decided, blocked | +| `journal.md` | date heading | 3-5 lines/session — what done, decided, blocked | | `evals.md` | EVAL-XXX | Quality check of Claude's output + method + anomalies + action | -**Language — registries are ALWAYS written in English:** -All persisted entries (decisions, learnings, blockers, journal, evals) must be in English. Rationale: consistent vocabulary for re-read efficiency, lower token cost, easier cross-project reuse. User-facing CAPITALIZE prompts may mirror the user's language; only the final written entry is English. +**Language — registries ALWAYS English:** +All persisted entries (decisions, learnings, blockers, journal, evals) must be English. Rationale: consistent vocab for re-read efficiency, lower token cost, easier cross-project reuse. User-facing CAPITALIZE prompts may mirror user's language; only final written entry is English. + +**Format — registries ALWAYS caveman:** +All writes to `.claude/memory/*.md` (decisions, learnings, blockers, journal, evals) MUST use caveman style — drop articles (a/an/the), drop filler (just/really/basically/actually/simply), fragments OK, short synonyms (big not extensive, fix not "implement a solution for"). Keep technical terms exact, code blocks unchanged, error messages quoted exact, IDs (BDR-XXX, LRN-XXX, BLK-XXX, EVAL-XXX) and dates unchanged. Pattern: `[thing] [action] [reason]. [next step].` Rationale: registries loaded every session start — caveman cuts ~40% input tokens with zero loss of technical substance. Applies to direct writes AND skill-driven CAPITALIZE steps (close, ship-feature, feat, bugfix, hotfix, commit-change). Existing entries: compress on demand via `/caveman:compress `. **Routing — what goes where:** - Choice with tradeoffs you'd defend → `decisions.md`. - Pattern worth reusing → `learnings.md`. - Dead end with root cause identified → `blockers.md`. -- One-line log of the session → `journal.md`. +- One-line log of session → `journal.md`. - Did Claude's output actually work? → `evals.md`. **Proactive capitalization (Claude's responsibility):** -After any substantive work milestone (bug fix with real root cause, feature shipped, non-trivial commit, design choice, surprising discovery, dead end with lesson), **offer to capitalize inline** — do NOT wait for the user to remember. Use the appropriate registry; pre-fill the entry from conversation context; let the user approve/edit before writing. +After any substantive milestone (bug fix with real root cause, feature shipped, non-trivial commit, design choice, surprising discovery, dead end with lesson), **offer to capitalize inline** — do NOT wait for user. Use right registry; pre-fill entry from conversation context; let user approve/edit before writing. -Completion skills (`/ship-feature`, `/feat`, `/bugfix`, `/hotfix`, `/commit-change`) include a CAPITALIZE step that automates this. +Completion skills (`/ship-feature`, `/feat`, `/bugfix`, `/hotfix`, `/commit-change`) include CAPITALIZE step that automates this. **Session-close ritual** (invoke manually via `/close`, or answer inline when asked): 1. What did I decide? → `decisions.md` (if non-trivial). @@ -89,9 +92,9 @@ Completion skills (`/ship-feature`, `/feat`, `/bugfix`, `/hotfix`, `/commit-chan ## Context Navigation (graphify) - Use `/graphify query` ONLY for large-scope tasks: multi-file features, complex bug investigations, architectural changes, major refactors. -- For small tasks (hotfix, typo, single-file change, quick lookup): read files directly — do NOT invoke graphify. -- Before answering architecture/codebase questions, read `graphify-out/GRAPH_REPORT.md` for god nodes and community structure. If `graphify-out/wiki/index.md` exists, use it as navigation entrypoint. -- After modifying code files, run `/graphify --update` to keep the graph current (AST-only, no API cost for code-only changes). +- Small tasks (hotfix, typo, single-file change, quick lookup): read files directly — do NOT invoke graphify. +- Before answering architecture/codebase questions, read `graphify-out/GRAPH_REPORT.md` for god nodes and community structure. If `graphify-out/wiki/index.md` exists, use as navigation entrypoint. +- After modifying code files, run `/graphify --update` to keep graph current (AST-only, no API cost for code-only changes). --- @@ -101,28 +104,28 @@ Override default framework/tooling choices. Apply at project creation, scaffoldi ## Public websites — never SPA -When a project is a public-facing website meant to be indexed (landing page, portfolio, blog, e-commerce, docs): +When project is public-facing website meant to be indexed (landing page, portfolio, blog, e-commerce, docs): - **FORBIDDEN**: pure SPA (CRA, Vite React SPA, Vue SPA) for public pages. SPA sends empty HTML shell — search engines and AI engines (GEO) can't see content without executing JS. SEO and AI visibility destroyed. - **Astro** = default for informational sites (portfolio, docs, blog, landing). Static HTML at build, zero JS by default, React/Vue/Svelte islands for interactive parts. - **Next.js** = when dynamic SSR needed (personalized content, server-side auth, API routes, hybrid app). - **React SPA** = valid ONLY for: admin panels, dashboards, auth-gated apps, internal tools — anything that does NOT need indexing. - **Mixed project** (public + admin): Astro/Next for public, React island (`client:only`) for admin. -- At brainstorming (`/init-project` STEP 1, `/ship-feature` STEP 1): if project is a public website and user hasn't specified a framework, PROPOSE Astro and EXPLAIN why not SPA. Never silently pick React CRA. +- At brainstorming (`/init-project` STEP 1, `/ship-feature` STEP 1): if project is public website and user hasn't specified framework, PROPOSE Astro and EXPLAIN why not SPA. Never silently pick React CRA. ## Web APIs — always versioned All web API endpoints MUST be versioned from day one: `/api/v1/...`, `/api/v2/...`. - New project → start at `/api/v1/`. No bare `/api/` routes. -- Breaking changes → new version (`v2`). Old version stays functional — clients migrate at their own pace. +- Breaking changes → new version (`v2`). Old version stays functional — clients migrate at own pace. - Non-breaking additions (new fields, new endpoints) → keep in current version. -- Each version is a self-contained contract. Never modify existing version behavior to match a newer one. +- Each version is self-contained contract. Never modify existing version behavior to match newer one. - Router structure must reflect versioning explicitly (e.g. `api/v1/routes/`, `api/v2/routes/`). ## Security — non-negotiable defaults -Apply at every development step: design, scaffolding, implementation, review. +Apply at every dev step: design, scaffolding, implementation, review. ### Input & data - Never trust user input. Validate type, length, format, range before use. @@ -131,26 +134,26 @@ Apply at every development step: design, scaffolding, implementation, review. ### Secrets - Never hardcode credentials, tokens, keys, or URLs containing auth info — not even in comments. -- Always use environment variables. Provide `.env.example` with placeholder values only. -- If a secret appears in code during review, flag it and stop — do not proceed. +- Always use env vars. Provide `.env.example` with placeholder values only. +- If secret appears in code during review, flag and stop — do not proceed. ### Authentication & authorization -- AuthN (who you are) and AuthZ (what you can do) are separate. Never assume AuthN implies AuthZ. -- Check authorization on every sensitive endpoint/function — not just at the entry point. +- AuthN (who you are) and AuthZ (what you can do) separate. Never assume AuthN implies AuthZ. +- Check authorization on every sensitive endpoint/function — not just at entry point. - Default to deny. Explicit allowlist > implicit denylist. ### Dependencies -- Do not add a dependency without stating what it does and why it's needed. +- No dependency without stating what it does and why needed. - Prefer well-maintained, widely-used packages. Flag abandoned or single-maintainer packages. -- Never `npm install` or `pip install` a package found in a random code snippet without naming it explicitly. +- Never `npm install` or `pip install` package found in random code snippet without naming it explicitly. ### Error handling & logging - Never expose stack traces, internal paths, or DB errors to end users. Log internally, return generic message. - Never log secrets, passwords, tokens, or PII — even at DEBUG level. -- Fail closed: on unexpected error, deny access rather than granting it. +- Fail closed: on unexpected error, deny access rather than grant. ### Minimal privilege -- Functions, processes, and services request only the permissions they actually need. +- Functions, processes, services request only permissions actually needed. - Temporary elevated permissions must be scoped and reverted explicitly. --- @@ -158,9 +161,9 @@ Apply at every development step: design, scaffolding, implementation, review. # Communication mode: radical honesty - TRUTH OVER COMFORT — Point out flaws immediately. No sugarcoating, no "not bad but…". -- ZERO COMPLACENCY — Never validate an idea just because I proposed it. Evaluate arguments on merit. -- BLIND SPOT DETECTION — Actively look for what I'm missing: confirmation bias, hidden assumptions, ignored alternatives. Flag them without waiting for permission. -- ACTIVE RESISTANCE — When I make a weak point, push back until I correct it or solidly justify keeping it. +- ZERO COMPLACENCY — Never validate idea just because I proposed it. Evaluate arguments on merit. +- BLIND SPOT DETECTION — Actively look for what I'm missing: confirmation bias, hidden assumptions, ignored alternatives. Flag without waiting for permission. +- ACTIVE RESISTANCE — When I make weak point, push back until I correct it or solidly justify keeping it. - UNCERTAINTY TRANSPARENCY — If you don't know, say so. No invention, no vague answers to save face. ## Health Stack @@ -169,9 +172,9 @@ Apply at every development step: design, scaffolding, implementation, review. ## Skill routing -When the user's request matches an available skill, ALWAYS invoke it using the Skill -tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. -The skill has specialized workflows that produce better results than ad-hoc answers. +When user's request matches available skill, ALWAYS invoke via Skill +tool as FIRST action. Do NOT answer directly, do NOT use other tools first. +Skill has specialized workflows that produce better results than ad-hoc answers. Key routing rules: - Product ideas, "is this worth building", brainstorming → invoke office-hours @@ -179,7 +182,7 @@ Key routing rules: - Small feature (1-5 files, lightweight) → invoke feat - Quick fix (typo, CSS, config, max 2 files) → invoke hotfix - Ship, deploy, push, create PR → invoke ship, or ship-feature if no gstack -- QA, test the site, find bugs → invoke qa +- QA, test site, find bugs → invoke qa - Code review, check my diff → invoke review - Update docs after shipping → invoke document-release, or doc if no gstack - Stale docs audit, doc sync → invoke doc @@ -201,8 +204,8 @@ Key routing rules: - Onboard existing project (config + archetype detection + full audit pipeline + backlog) → invoke onboard Design gate (automatic): -All lightweight skills (feat, hotfix, bugfix) include a design gate that auto-detects -UI/style signals in the task. If design signals found and ui-ux-pro-max is inactive, -the agent asks the user whether to activate it before proceeding. +All lightweight skills (feat, hotfix, bugfix) include design gate that auto-detects +UI/style signals in task. If design signals found and ui-ux-pro-max inactive, +agent asks user whether to activate before proceeding. Gate spec: lib/design-gate.md. Orchestrators (ship-feature, init-project) already -handle this via their STEP 0 plugin-check. +handle via STEP 0 plugin-check. \ No newline at end of file