From 1b38a64e159e424fe202056ef64d73aae9da0021 Mon Sep 17 00:00:00 2001 From: Illia Polosukhin Date: Sun, 15 Feb 2026 00:33:41 -0800 Subject: [PATCH] docs: add module specification rules to CLAUDE.md Any agent working on a module with a README.md spec must read it first, keep code and spec in sync, and treat the spec as the tiebreaker when they disagree. Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 5664469b..ff89c399 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -630,6 +630,22 @@ RUST_LOG=ironclaw::agent=debug cargo run RUST_LOG=ironclaw=debug,tower_http=debug cargo run ``` +## Module Specifications + +Some modules have a `README.md` that serves as the authoritative specification +for that module's behavior. When modifying code in a module that has a spec: + +1. **Read the spec first** before making changes +2. **Code follows spec**: if the spec says X, the code must do X +3. **Update both sides**: if you change behavior, update the spec to match; + if you're implementing a spec change, update the code to match +4. **Spec is the tiebreaker**: when code and spec disagree, the spec is correct + (unless the spec is clearly outdated, in which case fix the spec first) + +| Module | Spec File | +|--------|-----------| +| `src/setup/` | `src/setup/README.md` | + ## Code Style - Use `crate::` imports, not `super::`