Unnamed repository; edit this file 'description' to name the repository.
internal: Define rules for LLMs
rust-analyzer allows AI usage (see #21314), but requires contributors
to declare usage. This adds a rule file that improves LLM output
quality and instructs the LLM to declare usage in commit messages.
I've written the rules in CLAUDE.md, but also symlinked it to
AGENTS.md so other LLM tools pick it up.
## Rules file contents
(1) Instructions for both humans and AIs to declare AI usage.
(2) Relevant commands for testing, linting and codegen.
Note that I deliberately didn't include an overview of the project
structure on a folder-by-folder basis. This can go stale, and there's
some evidence that project structure can hurt LLM output quality
overall.
See the following paper:
> Evaluating AGENTS.md:
> Are Repository-Level Context Files Helpful for Coding Agents?
> https://arxiv.org/pdf/2602.11988
## Testing
I exercised this change with the following contrived prompt. Note that
in practice rust-analyzer is hitting review scaling limits for new
code actions, but it was easy to test end-to-end.
> Add a new code action that replaces the content of a string literal
> with the text "banana".
...
> commit it
This produced a functional code action with both Codex and Claude, and
in both cases the commit message mentioned that it was AI
generated. Example commit message:
Add "Replace string with banana" code action
Add a new assist that replaces a string literal's content with "banana"
when the cursor is on a STRING token.
AI: Generated with Claude Code (claude-opus-4-6).
I confirmed that the code action worked by testing a rust-analyzer
build in Emacs, and also confirmed that the generated tests looked
sensible.
## AI Usage Disclosures
I wrote the first draft of the rules file with Opus 4.6, manually
reviewed everything.
| l--------- | AGENTS.md | 1 | ||||
| -rw-r--r-- | CLAUDE.md | 40 |
2 files changed, 41 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md new file mode 120000 index 0000000000..681311eb9c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1 @@ +CLAUDE.md
\ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..e8f699d928 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,40 @@ +**Reminder: All AI usage must be disclosed in commit messages, see +CONTRIBUTING.md for more details.** + +## Build Commands + +```bash +cargo build # Build all crates +cargo test # Run all tests +cargo test -p <crate> # Run tests for a specific crate (e.g., cargo test -p hir-ty) +cargo lint # Run clippy on all targets +cargo xtask codegen # Run code generation +cargo xtask tidy # Run tidy checks +UPDATE_EXPECT=1 cargo test # Update test expectations (snapshot tests) +RUN_SLOW_TESTS=1 cargo test # Run heavy/slow tests +``` + +## Key Architectural Invariants + +- Typing in a function body never invalidates global derived data +- Parser/syntax tree is built per-file to enable parallel parsing +- The server is stateless (HTTP-like); context must be re-created from request parameters +- Cancellation uses salsa's cancellation mechanism; computations panic with a `Cancelled` payload + +### Code Generation + +Generated code is committed to the repo. Grammar and AST are generated from `ungrammar`. Run `cargo test -p xtask` after adding inline parser tests (`// test test_name` comments). + +## Testing + +Tests are snapshot-based using `expect-test`. Test fixtures use a mini-language: +- `$0` marks cursor position +- `// ^^^^` labels attach to the line above +- `//- minicore: sized, fn` includes parts of minicore (minimal core library) +- `//- /path/to/file.rs crate:name deps:dep1,dep2` declares files/crates + +## Style Notes + +- Use `stdx::never!` and `stdx::always!` instead of `assert!` for recoverable invariants +- Use `T![fn]` macro instead of `SyntaxKind::FN_KW` +- Use keyword name mangling over underscore prefixing for identifiers: `crate` → `krate`, `fn` → `func`, `struct` → `strukt`, `type` → `ty` |