Add CLAUDE.md coding standards for gold-standard Zig

[koko1123]

Summary

• Adds comprehensive CLAUDE.md encoding eth.zig's coding standards: 10-layer architecture, naming conventions, comptime discipline, memory management, error handling, testing, performance, crypto safety
• Documents known LLVM aarch64 traps (@intFromFloat/@floatFromInt with u256, u512 division) with workarounds
• Establishes hard rules: no external deps, no emojis, no layer violations, no hidden allocations, never push to main

Test plan

• make ci passes (build + fmt + test)
• Review CLAUDE.md for accuracy against actual codebase patterns

Summary by CodeRabbit

• Documentation
  • Added comprehensive architecture and development guidelines for the Ethereum client library covering project build/test commands, layered architecture and registration rules, coding/style conventions, comptime and allocator/ownership guidance, error-handling and testing practices, performance recommendations, cryptographic safety rules, and platform-specific hazard mitigations.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
eth-zig	Ready	Preview, Comment	Apr 8, 2026 6:25pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: fa7938e6-b4bd-4f2b-9497-c8a2126c17fa

📥 Commits

Reviewing files that changed from the base of the PR and between 5b11a20 and 7a813a6.

📒 Files selected for processing (1)

• CLAUDE.md

---

📝 Walkthrough

Walkthrough

Adds eth.zig, a 302-line design and documentation file specifying project build commands, layered architecture, Zig style and comptime conventions, allocator/ownership and error-handling rules, testing and benchmarking practices, cryptographic safety requirements, LLVM trap mitigations, and repository-wide coding prohibitions.

Changes

Cohort / File(s)

Summary

Zig Ethereum Client Library Design Documentation eth.zig

Added a comprehensive design/spec doc for a Pure Zig Ethereum client library covering build targets, layered architecture and dependency directions, style and naming conventions, comptime patterns, allocator and ownership documentation requirements, error-handling rules, testing guidelines, performance/benchmark workflow, cryptographic safety rules, and repository-wide prohibitions and recommendations.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐇
A zig of moonlight, small and spry,
I hop through specs beneath the sky,
Layers laid and rules in tow,
Keys kept secret, tests that grow,
A rabbit cheers: "Let code buds show!" 🥕

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The PR title refers to adding 'CLAUDE.md coding standards' but the actual file added is named 'eth.zig' according to the raw summary. The title is misleading about the actual filename.	Update the title to accurately reflect the file being added, such as 'Add eth.zig coding standards for gold-standard Zig' or 'Add CLAUDE.md with eth.zig coding standards'.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude-md

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

CLAUDE.md (1)

21-51: Add language specifier to fenced code block.

The architecture diagram is in a fenced code block without a language specifier. Add ```text to improve rendering and satisfy linters.

📝 Proposed fix

-```
+```text
 Layer 1:  Primitives     (zero deps, no allocator needed)
           primitives.zig, uint256.zig, hex.zig

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@CLAUDE.md` around lines 21 - 51, Change the fenced code block that begins
with "Layer 1:  Primitives     (zero deps, no allocator needed)" to include a
language specifier by replacing the opening ``` with ```text so the architecture
diagram renders as plain text and satisfies linters; the change should be made
around the triple-backtick block containing the Layer 1..Layer 10 diagram.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@CLAUDE.md`:
- Line 15: The line "Do NOT use Zig 0.16.0-dev (breaks std.Thread.Mutex)" is
misleading—update that sentence to clarify that the problem is not a stdlib bug
but unsafe user code patterns: change it to state that Zig 0.16.x may trigger
runtime safety checks when user code copies or moves structs containing
std.Thread.Mutex (e.g., storing mutex-containing values without stable
addresses), and recommend using Zig >= 0.15.2 or ensuring mutex-containing types
are not copied/moved (use pointers or arena allocation) instead of claiming the
stdlib is broken.

---

Nitpick comments:
In `@CLAUDE.md`:
- Around line 21-51: Change the fenced code block that begins with "Layer 1: 
Primitives     (zero deps, no allocator needed)" to include a language specifier
by replacing the opening ``` with ```text so the architecture diagram renders as
plain text and satisfies linters; the change should be made around the
triple-backtick block containing the Layer 1..Layer 10 diagram.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 31d81086-9924-41e3-bc83-ceeb9d02d8ff

📥 Commits

Reviewing files that changed from the base of the PR and between d369bd0 and 5b11a20.

📒 Files selected for processing (1)

• CLAUDE.md