kara: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code (claude.ai/code) in this repository. This is the v2 version, written at M3, when the legacy pipeline was deleted. The pre-M3 file, with every rule's measured history, is kept verbatim at docs/legacy/CLAUDE-legacy.md; read the matching section there before relaxing a rule here.

The gate

Four legs, all clean before any commit lands:

cargo fmt --all -- --check                                       # first action of every session
cargo clippy --all --all-targets -- -D warnings                  # CI's leg, the one easiest to miss
cargo clippy --all --all-targets --features llvm -- -D warnings  # the backend surface
cargo test --all                                                 # every workspace crate: front end, MIR, kernel, lsp, runtime
cargo test --features llvm                                       # everything, including the compiled backend

• fmt first. If --check fails on a fresh checkout, land cargo fmt --all as a standalone chore: cargo fmt cleanup commit before feature work. Never fold drift into a feature commit.
• Both clippy legs. --features llvm is not a superset: each cfg has code the other cannot see. --all-targets, never --tests, for the same reason.
• Wasm cfgs are invisible to native clippy. When touching runtime code under a wasm cfg: cargo clippy -p karac-runtime --target wasm32-wasip1 --no-default-features and cargo clippy -p karac-runtime --target wasm32-wasip1-threads --no-default-features --features wasm-threads.
• --all on the default test leg. Bare cargo test tests only the root package, so the kernel, lsp and runtime crates' tests never run; CI runs --all (measured at M3: two kernel reds reached main this way).
• cargo test lexer runs one test file; cargo test -- <name> runs one test.

LLVM 22

--features llvm builds against LLVM 22 (inkwell llvm22-1, llvm-sys 221). A cloud container cannot reach apt.llvm.org and Ubuntu's archive stops at 20, so once per container, before any --features llvm build: