CLAUDE.md

1## AI Policy
2 
3Follow `AI_POLICY.md`. In particular:
4 
5- Do not use AI to author issue/PR comments or replies to maintainers.
6- Do not autonomously open issues or pull requests.
7- Do not author code for issues labeled both `E-easy` and `E-has-instructions`.
8- The human contributor must understand the changes and disclose AI use as required by the policy.
9 
10 
11## Repository Guides
12 
13- Architecture and crate ownership: `docs/book/src/contributing/architecture.md`
14- Rust style: `docs/book/src/contributing/style.md`
15- Testing conventions and fixture syntax: `docs/book/src/contributing/testing.md`
16- Contributor workflows: `docs/book/src/contributing/README.md`
17- AI restrictions: `AI_POLICY.md`
18 
19Read the relevant sections before making architectural, generated-code, protocol, or test-harness changes.
20 
21## Change Workflow
22 
23- Find the nearest existing implementation and its tests before adding new code.
24- Extend existing helpers and test harnesses instead of creating parallel abstractions.
25- Keep changes focused and prefer the smallest change that fits the existing design.
26- When fixing a bug, add the smallest fixture that reproduces it and test the behavior through the existing interface.
27 
28## Scope and Dependencies
29 
30- Treat new `pub` items, public re-exports, and Cargo dependencies as architectural changes, not routine implementation details.
31- Prefer keeping functionality inside the crate that owns the relevant data.
32- Be conservative with crates.io dependencies. Reuse existing dependencies or `stdx`; do not add small helper crates without strong justification.
33 
34## Key Invariants
35 
36- User-provided Rust code, malformed syntax, broken builds, and proc-macro failures must not cause ordinary IDE features to panic.
37- Assert invariants liberally. For impossible conditions from which the server can recover, prefer `stdx::never!` or `stdx::always!` and return a safe fallback instead of panicking.
38 
39## Testing
40 
41- Many feature tests use Rust-code fixtures and `expect-test` snapshots. Follow the nearest existing test helper and fixture convention rather than introducing a new test harness.
42- Before planning or writing fixture-based tests, review `docs/book/src/contributing/testing.md` for fixture annotations, `minicore`, and multi-file/multi-crate syntax.
43- Keep Rust fixtures minimal; remove syntax unrelated to the behavior under test.
44- Use unindented multiline raw strings, matching nearby tests.
45- For regressions, first reproduce the failure with a focused test, then implement the fix.
46 
47## Generated Code
48 
49- Generated files are committed. Edit the generator rather than generated output.
50- Run `cargo xtask codegen` after changing grammar, generated AST definitions, configuration schemas, or other codegen inputs.
51- After adding parser inline tests (`// test name`), run `cargo test -p xtask`, update the relevant expectations, and inspect the generated diff.
52 
53## Validation
54 
55- Start with the narrowest relevant test: `cargo test -p <crate> <test-name>` or `cargo test -p <crate>`.
56- After Rust changes, run the affected crate's tests and `cargo clippy -p <crate> --all-targets -- --cap-lints warn`; broaden validation when the change crosses crates.
57- Use `cargo lint` to run Clippy on all workspace targets.
58- Run `cargo xtask tidy` for repository-wide structural or generated-code changes.
59- When updating snapshots with `UPDATE_EXPECT=1`, inspect the expectation diff rather than accepting it blindly.
60- Use `RUN_SLOW_TESTS=1 cargo test` when the affected area has slow tests.
61