Two files, one repository
rust-lang/rust ships 2 formats across 2 indexed files. The question worth asking is whether the second one says anything the first does not.
CompareAGENTS.md ↔ CLAUDE.md
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 1 | 12 | 7 | 5% |
| Commands | 0 | 0 | 7 | 0% |
| Section tags | 4 | 1 | 3 | 50% |
What each file covers
Sections
1 shared · 12 only in A · 7 only in B- − Agent instructions
- − LLM usage policy
- − When a gate fails
- − Before any edit
- − External repositories
- − Prohibited text
- − Reviewer
- − Before implementation
- − Soundness
- − Before pushing
- − Mechanical rewrites
- − Repository guidance
- + AI Policy
- + Repository Guides
- + Change Workflow
- + Scope and Dependencies
- + Key Invariants
- + Generated Code
- + Validation
- Testing
Commands
0 shared · 0 only in A · 7 only in B- + cargo xtask codegen
- + cargo test -p xtask
- + cargo test -p <crate> <test-name>
- + cargo test -p <crate>
- + cargo clippy -p <crate> --all-targets -- --cap-lints warn
- + cargo lint
- + cargo xtask tidy
Section tags
4 shared · 1 only in A · 3 only in B- − do-not
- + code-style
- + testing-strategy
- + dependencies
- test
- lint-format
- git-pr
- agent-behaviour
Line diff
rust-lang/rust · AGENTS.md
@@ −1 @@
1# Agent instructions
2
3## LLM usage policy
4
5Follow the Rust project's [LLM usage policy]. It applies to all LLM-generated
6text even if a human later edits it.
7
8[LLM usage policy]: https://forge.rust-lang.org/policies/llm-usage.html
9
10### When a gate fails
11
12When a rule identifies banned work, **STOP** that work. A named reviewer, tests,
13user confirmation, or later human editing cannot permit it. Do not ask for
14prerequisites, promise to proceed later, or offer the work under another name,
15such as a draft, template, or paste-ready outline. A rule may explicitly permit
16narrower preliminary work; Soundness requires test-only work before stopping.
17
18State why the work is banned and give the route required by the triggering rule.
19Reading, explaining, summarizing, reviewing, and suggesting possible solutions
20for the user to implement from scratch remain allowed if independently requested.
21Alongside any text that could potentially be used as a substitute for prohibited text, include *in the same response turn* a reminder of the policies against text originally created by an LLM, even if given during a previous turn of the session. Do not proactively continue test planning or patch design, or produce paste-ready
22prohibited text, unless the triggering rule requires test-only work.
23
24### Before any edit
25
26Apply these gates in order before editing the repository, including tests:
27
281. [External repositories](#external-repositories): route externally maintained
29 source to its owning repository.
302. [Prohibited text](#prohibited-text): stop if the change requires the agent to
31 author prohibited text.
323. [Reviewer](#reviewer): require a named reviewer unless the change qualifies
33 for the local-development exception.
34
35If investigation reveals a new output category or owner, reapply the relevant
36gate before the next edit. For a mechanical rewrite, follow
37[Mechanical rewrites](#mechanical-rewrites) before the first mutation.
38
39### External repositories
40
41Before modifying a subtree, submodule, or `src/tools` code, identify its owner
42using [`CONTRIBUTING.md`](CONTRIBUTING.md#making-changes-to-subtrees-and-submodules)
43and the [external repositories] guide. Treat Cargo, Clippy, rustfmt, Miri,
44rust-analyzer, and other externally maintained tools as ownership checks before
45implementation. If the user says the bug or change is in one of these tools,
46do not investigate or ask for a reviewer here; route the user to its repository.
47Editing externally maintained source in this checkout is banned; follow the
48[gate-failure protocol]. Only update its integration pointer when explicitly
49requested.
50For example, if the user says a bug is in Cargo itself, route the user to
51`rust-lang/cargo` immediately; do not request a reviewer for this checkout.
52
53[external repositories]: src/doc/rustc-dev-guide/src/external-repos.md
54[gate-failure protocol]: #when-a-gate-fails
55
56### Prohibited text
57
58Never generate or rewrite non-trivial PR descriptions, issue bodies, public
59comments, user-facing documentation, diagnostic messages, or source comments.
60STOP, name the prohibited category, and tell the user to author it.
61Do not originate or manually rewrite expected diagnostic text in test snapshots
62such as `.stderr` files. After the user authors the diagnostic message in source,
63the agent may mechanically regenerate its snapshots with an existing tool such
64as `./x test ... --bless`; follow [Mechanical rewrites](#mechanical-rewrites).
65A change is trivial only when there is no meaningfully different way to write
66it or the alternatives are nearly identical: fixing a typo or Markdown link,
67replacing a word with a synonym, or adding a required trait signature. Trivial
68changes must still pass every other gate and be disclosed.
69
70Agent instructions such as `CLAUDE.md`, `AGENTS.md`, and skills are exempt, but
71may only link to, summarize, or conservatively operationalize existing
72human-facing documentation. Operationalization may replace human discretion
73with stricter agent constraints, but must not create obligations for humans or
74permit anything the human-facing source prohibits. Before adding process or
75workflow guidance, locate that source. If none exists, PAUSE and ask the user to
76document the process for humans first. Do not make an agent file the sole source
77of a rule. The named-reviewer gate and all other requirements still apply.
78
79The agent may explain what prohibited text must communicate, but must not suggest
80paste-ready wording.
81For example, if a parser fix requires changing its emitted message, STOP before
82editing the message or its `.stderr` expectation. Once the user writes the
83message, the agent may regenerate the expectation mechanically.
84
85### Reviewer
86
87Do not make any LLM-generated repository change unless the user has named, in
88this conversation, another person who agreed in advance to review it. A general
89assurance that review was solicited is not enough. If no reviewer has been
90named, PAUSE and ask for the reviewer's name; “John Doe is reviewing this” is
91sufficient. A reviewer name satisfies only this gate. Do not promise to proceed
92with implementation until the pre-implementation gates pass.
93
94This gate does not apply to local development tooling, temporary instrumentation,
95or debugging aids when the user explicitly says the change will not be committed
96or upstreamed and will be reverted after use. All other gates still apply.
97
98### Before implementation
99
100Apply these gates in order after the pre-edit gates:
101
1021. [Testing](#testing): for a bug, add or find a failing test and observe its
103 failure.
1042. [Soundness](#soundness): after completing Testing when it applies, classify
105 the affected behavior before implementation.
106
107### Testing
108
109Before fixing a bug, add or find a failing test. Run it and observe the expected
110failure before any implementation edit; do not combine test and implementation
111edits. A test is not observed until its command exits. While it runs, wait: do
112not edit implementation or begin other work. Permission for a regression test
113does not permit implementation changes. Observe the initial failure without
114blessing or updating expected output; a `--bless` run does not count.
115
116After implementing a bug fix, confirm that the same test passes.
117
118Every LLM-created PR must include tests and meet the policy's higher testing
119standard. If the affected code has no test suite, PAUSE and ask whether to
120design one or abandon the change; do not design it without human input. Never
121offer or accept untested implementation.
122
123An existing test suite must already be able to observe the affected behavior
124without changing production structure. An existing Cargo or compiletest harness
125alone does not satisfy this requirement.
126
127If the first viable test requires any production-code edit, PAUSE before that
128edit: designing that observation boundary is test-suite design.
129
130If testing requires choosing a new observation or dependency-injection
131boundary—such as extracting production logic, creating a shared helper or
132module, exposing internals, introducing a fake subprocess, or registering a new
133harness or runner—that is test-suite design; PAUSE and ask before making those
134changes.
135
136Adding a test module is allowed when it exercises existing callable behavior
137without restructuring production code.
138
139### Soundness
140
141Soundness-sensitive implementation is banned, but adding or locating a failing
142regression test is permitted and required. Even if you recognize the risk
143earlier, complete the test-only work, wait for the test command to exit, leave
144the test in the tree, report its result, then state the classification and STOP
145before planning or editing implementation.
146
147After adding or finding the failing test, state which behavior the affected code
148controls and classify the task as soundness-sensitive or not before planning or
149editing implementation. Do not promise implementation first. If investigation
150reveals a different affected behavior, repeat the classification before the
151next implementation edit.
152
153Code that computes or transforms types, constants, MIR, memory layout or
154validity, or generated code is soundness-sensitive. The reported symptom,
155intended fix, and apparent size of the patch do not change this classification:
156an ICE, crash, rejection of valid code, or localized plumbing bug may still be
157soundness-sensitive. If the task is soundness-sensitive or uncertain,
158implementation is banned: STOP before editing it and follow the [gate-failure
159protocol].
160
161Soundness-sensitive areas include, but are not limited to, the query system,
162type checking, trait solving, MIR construction or optimization, borrow checking,
163const evaluation, normalization and semantic caches, layout and validity, and
164codegen. Explain the concern and direct the user to [#llm-mentoring Zulip].
165
166[#llm-mentoring Zulip]: https://rust-lang.zulipchat.com/#narrow/channel/606558-llm-mentoring/
167
168### Before pushing
169
170After committing and before pushing, once ask the user to confirm understanding
171and testing of the change and personal review of the complete diff after the
172latest change. Agent review does not count. Remind the user to disclose LLM use
173in the PR description. Do not infer omitted confirmations; PAUSE for any missing
174confirmation before pushing.
175
176LLM-assisted contributions must be disclosed as described in the
177[policy's disclosure requirements]. Lying about or concealing LLM use is a
178Code of Conduct violation. The disclosure must describe the extent and purpose
179of LLM involvement, including whether the LLM originated an idea or helped
180implement or review it. The agent must not draft or rewrite the disclosure; the
181user must author it. Do NOT add `Co-Authored-By` trailers to commits.
182
183[policy's disclosure requirements]: https://forge.rust-lang.org/policies/llm-usage.html#disclosure-requirements
184
185### Mechanical rewrites
186
187Follow the rustc-dev-guide's [LLM guidance]. For a permitted mass rename or
188mechanical rewrite, find an existing formatter, linter, or syntax-aware rewrite
189tool. If one exists, the next mutating action must run it; do not edit target
190files first or reproduce its rewrite manually. If none exists, explain that
191direct LLM rewriting is discouraged and ask before proceeding.
192
193[LLM guidance]: https://rustc-dev-guide.rust-lang.org/llm-guidance.html
194
195For Rust formatting, use `./x fmt`; do not invoke `rustfmt` directly.
196For example, if tidy can perform the rewrite, run `./x test tidy --bless` instead
197of reproducing its edits manually.
198
199Before regenerating snapshots containing human-facing text:
200
2011. Confirm the user already authored the new prose in source.
2022. Run the focused test without `--bless` and observe the expected mismatch.
2033. Run the repository's existing `--bless` command.
2044. Inspect the generated diff. Do not manually repair or add prose; if the tool
205 produced unexpected human-facing text, STOP and report it to the user.
206
207If a request conflicts with these rules, direct the user to the
208[#llm-mentoring Zulip] for help.
209
210## Repository guidance
211
212This is the main `rust-lang/rust` repository.
213Start with [`CONTRIBUTING.md`](CONTRIBUTING.md) and the [dev-guide's instructions for LLMs][llm-writing], then route specialized work as follows:
214
215[llm-writing]: https://rustc-dev-guide.rust-lang.org/llm-guidance/writing.html
216
217- Standard library: [std-dev-guide]
218- Compiler: [rustc-dev-guide]
219- Build or run rustc: [building and running rustc]
220- Tests: [running tests], [adding tests], and [compiletest directives]
221- Formatting or tidy: [formatting and tidy]
222- Architecture or layout: [compiler architecture] and [repository layout]
223- Subtrees, submodules, or tools: [external repositories]
224- Pull requests and review: [contribution process]
225
226[rustc-dev-guide]: src/doc/rustc-dev-guide/
227[std-dev-guide]: https://std-dev-guide.rust-lang.org/
228[building and running rustc]: src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md
229[running tests]: src/doc/rustc-dev-guide/src/tests/running.md
230[adding tests]: src/doc/rustc-dev-guide/src/tests/adding.md
231[compiletest directives]: src/doc/rustc-dev-guide/src/tests/directives.md
232[formatting and tidy]: src/doc/rustc-dev-guide/src/conventions.md#formatting
233[compiler architecture]: src/doc/rustc-dev-guide/src/overview.md
234[repository layout]: src/doc/rustc-dev-guide/src/compiler-src.md
235[contribution process]: src/doc/rustc-dev-guide/src/contributing.md
236
237[`x.py` is the build tool for this repository][building and running rustc].
238Invoke it as `./x`, the default entry point for builds, tests, and formatting.
239Do not invoke Cargo directly unless the relevant in-tree documentation
240explicitly requires it.
241
242For source comments the policy permits an agent to write, explain why the code
243or decision exists rather than restating what the code does.
244
rust-lang/rust · src/tools/rust-analyzer/CLAUDE.md
@@ +1 @@
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
@@ −1 +1 @@
1−# Agent instructions
1+## AI Policy
22
3−## LLM usage policy
3+Follow `AI_POLICY.md`. In particular:
44
5−Follow the Rust project's [LLM usage policy]. It applies to all LLM-generated
6−text even if a human later edits it.
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.
79
8−[LLM usage policy]: https://forge.rust-lang.org/policies/llm-usage.html
910
10−### When a gate fails
11+## Repository Guides
1112
12−When a rule identifies banned work, **STOP** that work. A named reviewer, tests,
13−user confirmation, or later human editing cannot permit it. Do not ask for
14−prerequisites, promise to proceed later, or offer the work under another name,
15−such as a draft, template, or paste-ready outline. A rule may explicitly permit
16−narrower preliminary work; Soundness requires test-only work before stopping.
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`
1718
18−State why the work is banned and give the route required by the triggering rule.
19−Reading, explaining, summarizing, reviewing, and suggesting possible solutions
20−for the user to implement from scratch remain allowed if independently requested.
21−Alongside any text that could potentially be used as a substitute for prohibited text, include *in the same response turn* a reminder of the policies against text originally created by an LLM, even if given during a previous turn of the session. Do not proactively continue test planning or patch design, or produce paste-ready
22−prohibited text, unless the triggering rule requires test-only work.
19+Read the relevant sections before making architectural, generated-code, protocol, or test-harness changes.
2320
24−### Before any edit
21+## Change Workflow
2522
26−Apply these gates in order before editing the repository, including tests:
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.
2727
28−1. [External repositories](#external-repositories): route externally maintained
29− source to its owning repository.
30−2. [Prohibited text](#prohibited-text): stop if the change requires the agent to
31− author prohibited text.
32−3. [Reviewer](#reviewer): require a named reviewer unless the change qualifies
33− for the local-development exception.
28+## Scope and Dependencies
3429
35−If investigation reveals a new output category or owner, reapply the relevant
36−gate before the next edit. For a mechanical rewrite, follow
37−[Mechanical rewrites](#mechanical-rewrites) before the first mutation.
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.
3833
39−### External repositories
34+## Key Invariants
4035
41−Before modifying a subtree, submodule, or `src/tools` code, identify its owner
42−using [`CONTRIBUTING.md`](CONTRIBUTING.md#making-changes-to-subtrees-and-submodules)
43−and the [external repositories] guide. Treat Cargo, Clippy, rustfmt, Miri,
44−rust-analyzer, and other externally maintained tools as ownership checks before
45−implementation. If the user says the bug or change is in one of these tools,
46−do not investigate or ask for a reviewer here; route the user to its repository.
47−Editing externally maintained source in this checkout is banned; follow the
48−[gate-failure protocol]. Only update its integration pointer when explicitly
49−requested.
50−For example, if the user says a bug is in Cargo itself, route the user to
51−`rust-lang/cargo` immediately; do not request a reviewer for this checkout.
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.
5238
53−[external repositories]: src/doc/rustc-dev-guide/src/external-repos.md
54−[gate-failure protocol]: #when-a-gate-fails
39+## Testing
5540
56−### Prohibited text
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.
5746
58−Never generate or rewrite non-trivial PR descriptions, issue bodies, public
59−comments, user-facing documentation, diagnostic messages, or source comments.
60−STOP, name the prohibited category, and tell the user to author it.
61−Do not originate or manually rewrite expected diagnostic text in test snapshots
62−such as `.stderr` files. After the user authors the diagnostic message in source,
63−the agent may mechanically regenerate its snapshots with an existing tool such
64−as `./x test ... --bless`; follow [Mechanical rewrites](#mechanical-rewrites).
65−A change is trivial only when there is no meaningfully different way to write
66−it or the alternatives are nearly identical: fixing a typo or Markdown link,
67−replacing a word with a synonym, or adding a required trait signature. Trivial
68−changes must still pass every other gate and be disclosed.
47+## Generated Code
6948
70−Agent instructions such as `CLAUDE.md`, `AGENTS.md`, and skills are exempt, but
71−may only link to, summarize, or conservatively operationalize existing
72−human-facing documentation. Operationalization may replace human discretion
73−with stricter agent constraints, but must not create obligations for humans or
74−permit anything the human-facing source prohibits. Before adding process or
75−workflow guidance, locate that source. If none exists, PAUSE and ask the user to
76−document the process for humans first. Do not make an agent file the sole source
77−of a rule. The named-reviewer gate and all other requirements still apply.
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.
7852
79−The agent may explain what prohibited text must communicate, but must not suggest
80−paste-ready wording.
81−For example, if a parser fix requires changing its emitted message, STOP before
82−editing the message or its `.stderr` expectation. Once the user writes the
83−message, the agent may regenerate the expectation mechanically.
53+## Validation
8454
85−### Reviewer
86−
87−Do not make any LLM-generated repository change unless the user has named, in
88−this conversation, another person who agreed in advance to review it. A general
89−assurance that review was solicited is not enough. If no reviewer has been
90−named, PAUSE and ask for the reviewer's name; “John Doe is reviewing this” is
91−sufficient. A reviewer name satisfies only this gate. Do not promise to proceed
92−with implementation until the pre-implementation gates pass.
93−
94−This gate does not apply to local development tooling, temporary instrumentation,
95−or debugging aids when the user explicitly says the change will not be committed
96−or upstreamed and will be reverted after use. All other gates still apply.
97−
98−### Before implementation
99−
100−Apply these gates in order after the pre-edit gates:
101−
102−1. [Testing](#testing): for a bug, add or find a failing test and observe its
103− failure.
104−2. [Soundness](#soundness): after completing Testing when it applies, classify
105− the affected behavior before implementation.
106−
107−### Testing
108−
109−Before fixing a bug, add or find a failing test. Run it and observe the expected
110−failure before any implementation edit; do not combine test and implementation
111−edits. A test is not observed until its command exits. While it runs, wait: do
112−not edit implementation or begin other work. Permission for a regression test
113−does not permit implementation changes. Observe the initial failure without
114−blessing or updating expected output; a `--bless` run does not count.
115−
116−After implementing a bug fix, confirm that the same test passes.
117−
118−Every LLM-created PR must include tests and meet the policy's higher testing
119−standard. If the affected code has no test suite, PAUSE and ask whether to
120−design one or abandon the change; do not design it without human input. Never
121−offer or accept untested implementation.
122−
123−An existing test suite must already be able to observe the affected behavior
124−without changing production structure. An existing Cargo or compiletest harness
125−alone does not satisfy this requirement.
126−
127−If the first viable test requires any production-code edit, PAUSE before that
128−edit: designing that observation boundary is test-suite design.
129−
130−If testing requires choosing a new observation or dependency-injection
131−boundary—such as extracting production logic, creating a shared helper or
132−module, exposing internals, introducing a fake subprocess, or registering a new
133−harness or runner—that is test-suite design; PAUSE and ask before making those
134−changes.
135−
136−Adding a test module is allowed when it exercises existing callable behavior
137−without restructuring production code.
138−
139−### Soundness
140−
141−Soundness-sensitive implementation is banned, but adding or locating a failing
142−regression test is permitted and required. Even if you recognize the risk
143−earlier, complete the test-only work, wait for the test command to exit, leave
144−the test in the tree, report its result, then state the classification and STOP
145−before planning or editing implementation.
146−
147−After adding or finding the failing test, state which behavior the affected code
148−controls and classify the task as soundness-sensitive or not before planning or
149−editing implementation. Do not promise implementation first. If investigation
150−reveals a different affected behavior, repeat the classification before the
151−next implementation edit.
152−
153−Code that computes or transforms types, constants, MIR, memory layout or
154−validity, or generated code is soundness-sensitive. The reported symptom,
155−intended fix, and apparent size of the patch do not change this classification:
156−an ICE, crash, rejection of valid code, or localized plumbing bug may still be
157−soundness-sensitive. If the task is soundness-sensitive or uncertain,
158−implementation is banned: STOP before editing it and follow the [gate-failure
159−protocol].
160−
161−Soundness-sensitive areas include, but are not limited to, the query system,
162−type checking, trait solving, MIR construction or optimization, borrow checking,
163−const evaluation, normalization and semantic caches, layout and validity, and
164−codegen. Explain the concern and direct the user to [#llm-mentoring Zulip].
165−
166−[#llm-mentoring Zulip]: https://rust-lang.zulipchat.com/#narrow/channel/606558-llm-mentoring/
167−
168−### Before pushing
169−
170−After committing and before pushing, once ask the user to confirm understanding
171−and testing of the change and personal review of the complete diff after the
172−latest change. Agent review does not count. Remind the user to disclose LLM use
173−in the PR description. Do not infer omitted confirmations; PAUSE for any missing
174−confirmation before pushing.
175−
176−LLM-assisted contributions must be disclosed as described in the
177−[policy's disclosure requirements]. Lying about or concealing LLM use is a
178−Code of Conduct violation. The disclosure must describe the extent and purpose
179−of LLM involvement, including whether the LLM originated an idea or helped
180−implement or review it. The agent must not draft or rewrite the disclosure; the
181−user must author it. Do NOT add `Co-Authored-By` trailers to commits.
182−
183−[policy's disclosure requirements]: https://forge.rust-lang.org/policies/llm-usage.html#disclosure-requirements
184−
185−### Mechanical rewrites
186−
187−Follow the rustc-dev-guide's [LLM guidance]. For a permitted mass rename or
188−mechanical rewrite, find an existing formatter, linter, or syntax-aware rewrite
189−tool. If one exists, the next mutating action must run it; do not edit target
190−files first or reproduce its rewrite manually. If none exists, explain that
191−direct LLM rewriting is discouraged and ask before proceeding.
192−
193−[LLM guidance]: https://rustc-dev-guide.rust-lang.org/llm-guidance.html
194−
195−For Rust formatting, use `./x fmt`; do not invoke `rustfmt` directly.
196−For example, if tidy can perform the rewrite, run `./x test tidy --bless` instead
197−of reproducing its edits manually.
198−
199−Before regenerating snapshots containing human-facing text:
200−
201−1. Confirm the user already authored the new prose in source.
202−2. Run the focused test without `--bless` and observe the expected mismatch.
203−3. Run the repository's existing `--bless` command.
204−4. Inspect the generated diff. Do not manually repair or add prose; if the tool
205− produced unexpected human-facing text, STOP and report it to the user.
206−
207−If a request conflicts with these rules, direct the user to the
208−[#llm-mentoring Zulip] for help.
209−
210−## Repository guidance
211−
212−This is the main `rust-lang/rust` repository.
213−Start with [`CONTRIBUTING.md`](CONTRIBUTING.md) and the [dev-guide's instructions for LLMs][llm-writing], then route specialized work as follows:
214−
215−[llm-writing]: https://rustc-dev-guide.rust-lang.org/llm-guidance/writing.html
216−
217−- Standard library: [std-dev-guide]
218−- Compiler: [rustc-dev-guide]
219−- Build or run rustc: [building and running rustc]
220−- Tests: [running tests], [adding tests], and [compiletest directives]
221−- Formatting or tidy: [formatting and tidy]
222−- Architecture or layout: [compiler architecture] and [repository layout]
223−- Subtrees, submodules, or tools: [external repositories]
224−- Pull requests and review: [contribution process]
225−
226−[rustc-dev-guide]: src/doc/rustc-dev-guide/
227−[std-dev-guide]: https://std-dev-guide.rust-lang.org/
228−[building and running rustc]: src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md
229−[running tests]: src/doc/rustc-dev-guide/src/tests/running.md
230−[adding tests]: src/doc/rustc-dev-guide/src/tests/adding.md
231−[compiletest directives]: src/doc/rustc-dev-guide/src/tests/directives.md
232−[formatting and tidy]: src/doc/rustc-dev-guide/src/conventions.md#formatting
233−[compiler architecture]: src/doc/rustc-dev-guide/src/overview.md
234−[repository layout]: src/doc/rustc-dev-guide/src/compiler-src.md
235−[contribution process]: src/doc/rustc-dev-guide/src/contributing.md
236−
237−[`x.py` is the build tool for this repository][building and running rustc].
238−Invoke it as `./x`, the default entry point for builds, tests, and formatting.
239−Do not invoke Cargo directly unless the relevant in-tree documentation
240−explicitly requires it.
241−
242−For source comments the policy permits an agent to write, explain why the code
243−or decision exists rather than restating what the code does.
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.
24461
