CodeVetter · Repo Unpack · Contributor handoff
rust-lang/rust
AGENTS.md is the controlling document and is unusually strict: a named human reviewer must be named in-conversation before any edit, certain text categories (PR text, diagnostics, doc prose) are prohibited for LLMs, bug fixes require an observed failing test first, and all soundness-sensitive implementation is banned outright — test-only work is allowed there. External subtrees must be routed upstream. Operationally: use ./x for everything (never cargo directly), ./x fmt for formatting, ./x test tidy for style gates, bootstrap.toml for config, and expect builds/tests to run under build/. Read the in-tree rustc-dev-guide (src/doc/rustc-dev-guide) for architecture.
- Read AGENTS.md first: it defines a gating protocol — external-repo routing check, prohibited-text check, named-reviewer requirement — that must be applied before ANY repository edit, including tests, plus a test-first rule and a soundness classification before implementation.
- Never invoke cargo directly for builds/tests in this repo; ./x (x.py/x/x.ps1) is the entry point per AGENTS.md and src/bootstrap/README.md. Formatting is `./x fmt`, not rustfmt; mechanical rewrites must use an existing tool (e.g. `./x test tidy --bless`).
- Do not edit externally maintained subtrees/submodules in place — Cargo, Clippy, rustfmt, Miri, rust-analyzer, rustc_codegen_cranelift/gcc, src/llvm-project; CONTRIBUTING.md's 'Making changes to subtrees and submodules' section routes those changes to their owning repositories.
- Configuration: copy bootstrap.example.toml to bootstrap.toml (or run ./configure / ./x setup); the change-id field maps to src/bootstrap/src/utils/change_tracker.rs and warnings appear when it lags; profiles live in src/bootstrap/defaults.
- Architecture orientation docs live in-tree at src/doc/rustc-dev-guide (overview.md covers the compile pipeline); tests/COMPILER_TESTS.md redirects test-harness questions to the dev-guide's testing chapters.
- For bug fixes: add or find a failing test and observe the failure (no --bless) before touching implementation; if the affected area is soundness-sensitive (queries, typeck, traits, MIR, borrowck, const eval, layout, codegen), STOP after the test and route to #llm-mentoring on Zulip.
- Diagnostic-message edits are prohibited text: an agent may not author or rewrite user-facing diagnostic wording or .stderr expectations; after a human writes the message, snapshots may be regenerated mechanically with the existing --bless flow.
- Keep tidy-alphabetical-start/end regions sorted (seen in Cargo.toml, lib.rs files, runtest.rs mod lists); tidy enforces this plus style/edition/deps rules — run ./x test tidy before considering a change done.
- Bootstrap acquires a lock at build-dir `out/lock` (with holder PID) so concurrent ./x invocations serialize; bypass_bootstrap_lock exists but concurrent builds otherwise block.
- When adding rustc flags/queries/lints/targets, the conventions are registry-style: options.rs tables, queries.rs blocks + provide(), lint_vec() lists in rustc_lint, spec/targets modules — follow the surrounding pattern rather than inventing new wiring.
- First files to read for compiler work: compiler/rustc_driver_impl/src/lib.rs (pipeline order), compiler/rustc_interface/src/interface.rs (Config/hooks/session build), compiler/rustc_interface/src/passes.rs (providers/GlobalCtxt), compiler/rustc_middle/src/queries.rs (query registry).
- CLAUDE.md simply defers to AGENTS.md (@AGENTS.md); the LLM usage policy it cites (forge.rust-lang.org/policies/llm-usage.html) requires disclosure authored by the human and forbids Co-Authored-By trailers.
- CI changes go in src/ci/github-actions/jobs.yml not ci.yml; PR builds lack the 'bors' environment so secret-dependent steps are auto-skipped — validate job changes via citool rather than editing the workflow.