From c17791bdb75eab1df1a3cfd31a1304e08d0ad996 Mon Sep 17 00:00:00 2001 From: Bronek Kozicki Date: Fri, 21 Aug 2026 18:16:14 +0100 Subject: [PATCH 1/4] Update CLAUDE.md --- CLAUDE.md | 52 ++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 42 insertions(+), 10 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 01b5051e..6f573231 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,18 +1,17 @@ # CLAUDE.md -Guidance for working in **silver** — gattaca's high-performance Ethereum consensus client. +Guidance for working on **silver** — Gattaca's high-performance Ethereum consensus client. ## Philosophy Two principles drive every rule below: -- **Simplicity.** Simplicity is the foundation of capability, not the opposite of it. Lines - of code matter — the best code is the code you didn't write. Favour fewer abstractions, - fewer layers, fewer traits, fewer macros. Reach for the language's existing tools before - inventing new ones. -- **Performance.** Performance is a feature, not an afterthought. Hot paths (state apply, - finalization, hashing, gossip) are measured. When two designs are equally clear, pick the - faster one; when the fast one is less clear, justify it and measure it. +- **Simplicity.** Simplicity is the foundation of capability, not the opposite of it. + Favour fewer abstractions, fewer layers, fewer traits, fewer macros. Reach for + the language's existing tools before inventing new ones. +- **Performance.** Performance is a feature, not an afterthought. Hot paths (state transitions, + finalization, hashing, gossip ingestion and propagation) are measured. When two designs are equally clear, + pick the faster one; when the fast one is less clear, justify it and measure it. These reinforce each other: a smaller, flatter, well-named codebase is both simpler to reason about and faster to run. @@ -20,7 +19,7 @@ reason about and faster to run. ## Project shape - Binary is `crates/bin`; everything else is a `silver_*` library crate. -- Crates are organised as **tiles** — independent components that communicate over channels. +- Most crates are organised as **tiles** — independent components that communicate over channels. - The beacon state is **not** a monolith: it's a bag of per-tier *groups* (validators, balances, participation, …), each a finalized base + a ring of per-fork deltas. - Read `docs/beacon-state-architecture.md` and `docs/delta-rebase-invariant.md` before @@ -149,4 +148,37 @@ boundaries — not the same implementation sprinkled across more files. - **Minimal diff.** Don't "improve" working code outside the task. But code the *current diff introduced* is in scope to fix even when the fix is larger/non-local (extracting a new - module, rewiring imports) — edit size is not a scope test. + module, rewiring imports) — edit size is not a scope test. Performance and avoidance of + undue coupling (e.g. between tiles) take priority over this rule. + +## Communication + +Applies to prose you write into: + +- commit messages +- GitHub issues, and comments on issues +- pull request descriptions, and review comments +- code comments +- documentation committed to the repository + +Rules: + +- Default to sentences under 25 words. + - Write a longer sentence when splitting it would hide how the parts relate. + - Use a list if the content does not fit in one sentence. +- Do not split a sentence into fragments to meet the limit. +- One main clause per sentence. Subordinate clauses are fine. +- Use the active voice. +- Use no more than three nouns in a noun cluster. +- Use one term per concept, and one concept per term. +- State uncertainty and untested assumptions in reviews, issues, and pull request descriptions. + - Do not drop them for brevity. +- Reproduce commands, code, identifiers, paths, and quotations verbatim. + - These rules do not apply to them. +- Do not try to fix the language produced by others to follow these rules. + - For example, this document. + +## Issue tracking + +Track project work in GitHub issues. Only use Linear or other platforms when +explicitly asked. From 9007e6a54c1f59ec2c0d8902cc0b7980ca967949 Mon Sep 17 00:00:00 2001 From: Bronek Kozicki Date: Fri, 21 Aug 2026 18:36:55 +0100 Subject: [PATCH 2/4] Drop 'Use the active voice' rule --- CLAUDE.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 6f573231..740ccbf0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -168,7 +168,6 @@ Rules: - Use a list if the content does not fit in one sentence. - Do not split a sentence into fragments to meet the limit. - One main clause per sentence. Subordinate clauses are fine. -- Use the active voice. - Use no more than three nouns in a noun cluster. - Use one term per concept, and one concept per term. - State uncertainty and untested assumptions in reviews, issues, and pull request descriptions. From 68c9541a521beeec3f890057d48acbc05021be95 Mon Sep 17 00:00:00 2001 From: Bronek Kozicki Date: Mon, 24 Aug 2026 09:59:38 +0100 Subject: [PATCH 3/4] More communication rules --- CLAUDE.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 740ccbf0..d660a405 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -166,10 +166,12 @@ Rules: - Default to sentences under 25 words. - Write a longer sentence when splitting it would hide how the parts relate. - Use a list if the content does not fit in one sentence. + - Use a table if the content warrants it. - Do not split a sentence into fragments to meet the limit. - One main clause per sentence. Subordinate clauses are fine. - Use no more than three nouns in a noun cluster. - Use one term per concept, and one concept per term. +- Use markdown where it can be rendered e.g. documentation, GitHub. Otherwise use ASCII. - State uncertainty and untested assumptions in reviews, issues, and pull request descriptions. - Do not drop them for brevity. - Reproduce commands, code, identifiers, paths, and quotations verbatim. From ff4c638c9660287226966d1cf6e4d86c3ae493bc Mon Sep 17 00:00:00 2001 From: Bronek Kozicki Date: Mon, 24 Aug 2026 10:52:08 +0100 Subject: [PATCH 4/4] Split Communication rules into hard rules and defaults Four rules are hard: the 25-word cap, verbatim reproduction, the unless-asked clause, and the ban on contorting sentences. The six remaining rules are defaults, and drift on them is allowed. Content selection gets its own default: write what the reader needs. The scope list gains log, panic, and assertion messages. Term choice now prefers the established local term. The anti-fragment guard is gone; splitting a sentence is always legal. Assisted-by: Claude Code:claude-fable-5 Assisted-by: Claude Code:claude-opus-5 --- CLAUDE.md | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d660a405..7972a5fe 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -159,25 +159,24 @@ Applies to prose you write into: - GitHub issues, and comments on issues - pull request descriptions, and review comments - code comments +- log, panic, and assertion messages - documentation committed to the repository -Rules: - -- Default to sentences under 25 words. - - Write a longer sentence when splitting it would hide how the parts relate. - - Use a list if the content does not fit in one sentence. - - Use a table if the content warrants it. -- Do not split a sentence into fragments to meet the limit. -- One main clause per sentence. Subordinate clauses are fine. -- Use no more than three nouns in a noun cluster. -- Use one term per concept, and one concept per term. -- Use markdown where it can be rendered e.g. documentation, GitHub. Otherwise use ASCII. -- State uncertainty and untested assumptions in reviews, issues, and pull request descriptions. - - Do not drop them for brevity. +Hard rules: + +- Keep sentences under 25 words, carrying one idea each. - Reproduce commands, code, identifiers, paths, and quotations verbatim. - - These rules do not apply to them. -- Do not try to fix the language produced by others to follow these rules. - - For example, this document. +- Unless asked, do not fix the language produced by others to follow these rules. +- Never contort a sentence you produced to satisfy any of the rules or defaults. + +Defaults (not a checklist, drift is allowed): + +- Choose content by what the reader needs, not by how you got there. +- Break out content that does not fit in a sentence, as a list or as a table. +- Keep noun clusters to about three nouns. +- Use one term per concept, and one concept per term, preferring the established local term. +- Use markdown where it can be rendered e.g. documentation, GitHub. +- State uncertainty and untested assumptions, and do not drop them for brevity. ## Issue tracking