AGENTS.md

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