From ef3ab9a73bfcde3e4789030efe8c2ab78cdd66f0 Mon Sep 17 00:00:00 2001
From: Wilfred Hughes <me@wilfred.me.uk>
Date: Mon, 2 Mar 2026 11:32:20 +0000
Subject: [PATCH] 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.
---
 AGENTS.md |  1 +
 CLAUDE.md | 40 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 41 insertions(+)
 create mode 120000 AGENTS.md
 create mode 100644 CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 120000
index 000000000000..681311eb9cf4
--- /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 000000000000..e8f699d92813
--- /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`