From 94c2e3107c7a1f5b8dd2f957cbaae1972f9fc477 Mon Sep 17 00:00:00 2001 From: Nicolas CHAUVIN Date: Wed, 12 Aug 2026 11:03:53 +0200 Subject: [PATCH] docs: adopt shared ruleset rules in CLAUDE.md --- .claude/rules.lock | 40 ++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 20 +++++++++++++------- 2 files changed, 53 insertions(+), 7 deletions(-) diff --git a/.claude/rules.lock b/.claude/rules.lock index 2794757..4ec5f16 100644 --- a/.claude/rules.lock +++ b/.claude/rules.lock @@ -1,3 +1,43 @@ +# Shared rule adoptions for this repository. +# +# The rules themselves live in CLAUDE.md — this file only records which +# of them come from a ruleset shared with my other projects, when each +# was adopted, and a hash of its wording at that time. The hash lets a +# check tell a deliberate rewording from an accidental deletion, and +# flag a rule whose shared wording has moved on since. +# +# Nothing here changes how the repository behaves. + +rules_version = 1 + [rules.adr-lifecycle] adopted = "2026-08-04" hash = "aabd778ef08e" + +[rules.bugfix-evidence] +adopted = "2026-08-04" +hash = "9a65081d690c" + +[rules.design-first] +adopted = "2026-08-04" +hash = "6d93ba90db46" + +[rules.measurable-defect] +adopted = "2026-08-04" +hash = "268cf19aeb9d" + +[rules.memory-precedence] +adopted = "2026-08-04" +hash = "78dc260ec367" + +[rules.severe-opinion] +adopted = "2026-08-04" +hash = "da1ad3af8e04" + +[rules.stale-issue-audit] +adopted = "2026-08-04" +hash = "fca725ad312a" + +[rules.testing-guard] +adopted = "2026-08-04" +hash = "a09e99c6385f" diff --git a/CLAUDE.md b/CLAUDE.md index 85321b1..d841656 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,10 +13,13 @@ This file takes precedence over auto-memory. If an auto-memory entry contradicts - Never name a file path in a recommendation without verifying its existence (Read/ls/find) in the current session — mark explicitly as "to confirm" if unverified - All written artifacts (docs, code, comments, commit messages, issues, PRs) are in English — user-facing UI strings live in i18n resources - Responses ≤ 15 lines by default. Tables only when tabular beats prose. Background / rationale only on explicit request -- Quality over satisfaction — push back on over-engineering, incoherence, or unjustified additions, including when user-proposed -- Critique constructively: acknowledge the proposal's strong points first, cite established standards (RFCs, crypto guidance, WCAG) rather than personal preference, propose corrections — not just opposition -- If a debate cycles past 3 iterations on the same axis without convergence, propose to decide rather than continue +- When the user asks for an opinion, be severe, honest and challenging — the goal is code that meets professional standards, not the user's agreement. Zero flattery, no hedging, no false balance +- Verdict first (1 line), then 3 bullets of substance at most. Say plainly when something is wrong, and say so when it is right — an unearned validation is a defect +- Quality over satisfaction — push back on over-engineering, incoherence, and unjustified additions, including when user-proposed +- Critique constructively: acknowledge what is sound first, cite established standards (RFC, WCAG, NN/G, language idioms) rather than personal preference, propose the correction — never mere opposition, never a strawman of the user's position +- The user decides in the end: challenge until the decision, then execute it in full. If a debate cycles past 3 iterations on the same axis without converging, propose to decide rather than continue - Flag security, cryptographic, performance, and design issues immediately when noticed +- Never assume a produced artifact matches its request — a generation, a render or a transform routinely ignores or distorts instructions. Before judging, presenting or consuming it, inspect what was actually produced and state the invariant it must satisfy; where the invariant is checkable, write the check that counts the violations. Claiming "it now matches X" without having verified is a defect. ## Documentation @@ -25,8 +28,9 @@ This file takes precedence over auto-memory. If an auto-memory entry contradicts - `docs/design/` is source of truth: WHAT the system does, WHY when non-obvious - `docs//` describes HOW design is implemented; reference design, never restate - `docs/sync-protocol.md` is the canonical wire format — design must not paraphrase it -- Code is never source of truth — code/design disagreement = code is the bug, or design needs an explicit amendment, never both silently -- If design is silent on a needed behavior: write design first, then code +- Code is never source of truth — a code/design disagreement means the code is the bug, or the design needs an explicit amendment, never both silently +- If the design is silent on a needed behavior, write the design first, then the code +- Anchor a confirmed non-obvious decision — especially one where an alternative was rejected — in the design docs or an ADR before building on it - Group docs by single coherent concern — broad-keyword grab-bags (security, utils) are forbidden - ADR lifecycle: never delete an ADR; a reversal is a **new** ADR, and both sides carry the link — `Superseded by ADR-NNN` on the old, `Supersedes ADR-MMM` on the new. A one-sided link is how the chain rots - An ADR whose decision no longer applies, with no replacement, is marked `Deprecated` — never edited away or moved @@ -46,6 +50,7 @@ This file takes precedence over auto-memory. If an auto-memory entry contradicts - Before making changes, check branch — if on `main` or `develop`, propose a branch name and wait - Unrelated bug found during work: create a GitHub issue, never fix it in the current branch - No AI references (Co-Authored-By, Generated by, etc.) in commits or code +- Before implementing an issue older than ~1 month, audit it against current code and design: close with evidence if already delivered, post an audit comment refreshing stale references/scope if the architecture drifted, implement as-is only if still accurate ## Crates (`core/`, `cli/`, `relay/`, and future `gui/`, `android/`) @@ -71,5 +76,6 @@ This file takes precedence over auto-memory. If an auto-memory entry contradicts - If a test fails after code changes, report it instead of fixing it silently - Adding new tests is always allowed - When you add or modify user-observable code, propose the corresponding test in the same response as the code change -- Bug fixes start with a failing test that reproduces the bug (red → green): write the test first, then the fix -- Bug fixes must reproduce the failure from observed evidence (logs, repro steps); never invent the failure scenario from a hypothesis +- Bug fixes start with a failing test that reproduces the bug: write the test first and watch it fail, then fix, then re-run it green (red → green) +- That test stays as the regression test for this bug — reference the issue number in it, so a later reader knows what it guards and does not delete it as noise +- Bug fixes must reproduce the failure from observed evidence (logs, network capture, repro steps); never invent the failure scenario from a hypothesis