Behavioural rules for any LLM working in this codebase. These complement Philosophy and apply regardless of which tool or model is running.
Read on trigger, not just upfront. You will not always know at the start of a session which rules apply. As soon as you recognise you are entering a governed area — about to write code, edit notes, or change infrastructure — consult TRIGGERS and read the mapped note(s) before acting, even if you are already mid-task. Re-reading mid-task is expected and correct; the mistake is pressing on once relevance has become clear.
These rules exist because LLMs have predictable failure modes: silent assumptions, over-engineering, collateral edits, and vague success criteria. Every rule below targets one of those.
Read PROGRAMMING_RULES/philosophy before writing or reviewing any code. In particular: we follow The Right Thing (Gabriel’s MIT approach) — correctness is non-negotiable, interface simplicity matters more than implementation simplicity, and exceptions are never silently swallowed. If you catch an exception and suppress it, you must log the full context thoroughly at that point. Silence is not an option.
State your assumptions explicitly before writing code or making changes. If the request is ambiguous, name the ambiguity and ask — do not pick one interpretation silently and run with it. If a simpler approach exists, say so and push back. If you are confused mid-task, stop, name what is unclear, and surface it rather than blundering forward.
The failure mode this prevents: confident wrong output that wastes more time to unpick than if you had asked upfront.
Write the least code that solves the stated problem. No speculative features. No abstractions for single-use code. No 'flexibility' or 'configurability' that was not requested. If you write 200 lines and 50 would do, rewrite it.
Self-check: would a senior engineer call this overcomplicated? If yes, simplify before delivering.
This also applies to the notes system: update only the specific blocks that need changing. Do not rewrite entire notes to make a small correction.
Touch only what was asked. Do not improve adjacent code, fix unrelated style, or refactor things that are not broken. Match the existing style even if you would do it differently. If you notice unrelated dead code or problems, mention them — do not silently fix them.
The test: every changed line must trace directly to the request. If it cannot, undo it.
Convert vague instructions into verifiable criteria before writing anything. 'Fix the bug' becomes 'write a test that reproduces it, then make it pass'. 'Add validation' becomes 'write tests for invalid inputs, then make them pass'. For multi-step tasks, state a brief plan with a verification step for each stage.
Strong success criteria let you loop to completion independently. Weak criteria ('make it work') create a back-and-forth that is slower than asking once upfront.
Always fetch a note with include_block_ids: true before patching it. Block IDs change between revisions — stale IDs silently target the wrong block. Use if_rev for concurrency safety. Prefer a single notes:put rewrite over a long sequence of patches when restructuring.
Read MEMORY at the start of any non-trivial session. Read the relevant project note before touching project code.
Research (ETH Zurich, 2026) shows that bloated context files degrade agent performance — overly long instructions cause models to ignore them selectively or wholesale. Every line here should pass this test: would removing it cause a mistake the agent cannot recover from? If not, it does not belong here.
Keep project-specific CLAUDE.md files under 100 lines. Behavioural rules (this note) are generic and load once; project notes carry project-specific context.