Follow the opinions
Apply this repository's opinions and templates while you write or change code in a Rust crate or workspace. The opinions are the reference, and the project is where you write. Never write to this repository from this skill.
This skill changes only what the task asks for. To find where a project's existing code deviates, run review-project.
By default, it follows sourced community practice only. If the user or the project names a house profile, such as simon-mckenna, it follows that profile's house opinions too. For the profiles, see HOUSE-OPINIONS.md.
"This repository" in this skill means awesome-humans/rust. Each path in it, such as opinions/ or templates/Cargo.toml, is relative to the repository's root. Without a checkout, read an opinion, a template, a skill, the roster, or an agent instruction file from its copy at https://awesome-humans.net/rust/raw/none/<path>, with .txt added to a Markdown file's name and the leading dot dropped from a file or directory name. llms.txt links the opinions, templates, and skills. Any other file is at https://raw.githubusercontent.com/awesome-humans/rust/main/<path>.
Steps
- Work out what the task touches, before you read an opinion:
- Library code, binary code, or both, and whether the crate is
no_std. Cargo.toml,rust-toolchain.toml,rustfmt.toml,clippy.toml,deny.toml, or.cargo/config.toml.- Tests, and CI workflows.
- The areas: error handling, async code,
unsafe, or dependencies.
- Library code, binary code, or both, and whether the crate is
- Read the project's own decisions, in its agent instruction files, such as
AGENTS.md,CLAUDE.md, or.github/copilot-instructions.md, and in itsREADME.mdand contributing guide. Read every one the project holds, because your harness might load only its own:- Record the house profile the user or the project names, or that neither names one. Without one, skip every house block in
opinions/, and leave the house regions out of anything you copy fromtemplates/. With one, keep that profile's blocks and regions, and skip the others. Without a checkout, read a profile's copy of each file from the links inhttps://awesome-humans.net/rust/llms-<profile>.txt, because the copies underraw/none/have no house opinions. If the site has no such file, the profile holds no Rust house opinions: read the default copies thatllms.txtlinks. - Record each decision that departs from an opinion, such as a lint it allows or an MSRV policy. A recorded decision takes precedence: follow it, and don't change it back.
- Record the house profile the user or the project names, or that neither names one. Without one, skip every house block in
-
Read each opinion that covers the task, in full, from
opinions/:- rust.md, for every task.
- Every other opinion whose area step 1 found.
Read them each time. An opinion changes with each release, so don't write from what you remember of one. Don't read an opinion the task doesn't touch.
-
Start a new file from its template. When the task adds a file that
templates/holds, such asCargo.tomlorrustfmt.toml, copy the template and trim it:- Remove the header, which is the first line, starting
awesome-humans/rust template, and the lines under it that say where to copy the file. They describe the template, not the project's file. - Remove each setting and section the project doesn't use.
- Keep a comment that says why a setting is set.
In a file that already exists, change only what the task needs. Don't replace it with the template.
- Remove the header, which is the first line, starting
-
Write the code as the opinions recommend:
- Keep the versions the project targets. Don't raise an
edition, arust-version, a toolchainchannel, or a dependency version unless the task asks. A new crate in an empty repository targets the opinions'targets:. - Where an opinion gives a recommendation and an exception, apply the exception only when its stated condition holds.
- Where the code around your change follows another convention, write the new code as the opinion recommends, unless that leaves one file with two styles. Don't rewrite the code around it.
- Don't use a feature that an opinion marks as nightly-only or "Coming next".
- Where no opinion covers something, follow the project's existing convention. Don't present your own preference as an opinion.
- Keep the versions the project targets. Don't raise an
- Build, lint, and test what you wrote, with the commands the project documents. Without any, run
cargo clippy --workspace --all-targetsandcargo test, and fix every warning your change adds. Add--lockedto both when the project commits aCargo.lock: without the file,--lockedfails before Clippy runs. - Report, after the work:
- The opinions you read in full, and the templates you copied.
- The house profile you followed, and whether the user or the project named it.
- Each place where a decision of the project's took precedence over an opinion.
- Anything you noticed that deviates from an opinion and didn't change, in one line each. For a full comparison, suggest
review-project. - Anything the task needed that no opinion covers, as a possible opinion gap. The user can raise it in an issue.
Edge cases
- The project doesn't follow the opinions yet: Apply them to the code you write, and don't convert the rest as a side effect. Say so, and suggest
review-project. - The user's instruction conflicts with an opinion: Follow the user. Say once which opinion recommends otherwise, and why.
- A house block conflicts with the sourced text beside it, and the project follows that profile: Follow the house block.
no_stdor embedded crates: Follow the opinions that apply withoutstd. Don't apply astd-only convention, such as one that needs an allocator.- A library's
rust-version: It's the crate's minimum supported Rust version, a promise to its users. Don't use a language or library feature newer than it, even when the toolchain allows one. - The templates and opinions disagree: That's a bug in this repository. Follow the opinion text, which takes precedence, and report it against this repository.
- The project spells differently: Match the project's spelling in its identifiers, comments, and documentation. The spelling rule in AGENTS.md covers prose written here.