|
| 1 | +# Agent instructions |
| 2 | + |
| 3 | +## LLM usage policy |
| 4 | + |
| 5 | +Follow the Rust project's [LLM usage policy]. It applies to all LLM-generated |
| 6 | +text 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 | + |
| 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. |
| 17 | + |
| 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. |
| 23 | + |
| 24 | +### Before any edit |
| 25 | + |
| 26 | +Apply these gates in order before editing the repository, including tests: |
| 27 | + |
| 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. |
| 34 | + |
| 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. |
| 38 | + |
| 39 | +### External repositories |
| 40 | + |
| 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. |
| 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 | + |
| 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. |
| 69 | + |
| 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. |
| 78 | + |
| 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. |
| 84 | + |
| 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. |
0 commit comments