Skip to content
awesome-humansPublic

About

An agentic take on awesome lists: distilled, opinionated guidance for building with Rust, thanks to awesome humans.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

115 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Awesome Humans of Rust

An agentic take on awesome-rust: opinionated guidance for your coding agent, distilled from the writing of awesome humans. Instead of a list of links, it gives one recommendation per question, and each opinion cites its sources. It documents current best practice in Rust code, and changes as Rust evolves.

The writers are listed in AWESOME-HUMANS.md: people and publications with at least two years of accurate, independent writing on Rust.

Agents: Fetch llms.txt and every file it links as raw text. It links the opinions, templates, and skills.

Note

The Rust ecosystem is currently being bootstrapped. See Research, the research branches, and the plan. Review by 2027-01-17.

Usage

  • Point your agent at it. Tell your coding agent to follow the opinions when it writes code:

    Follow the conventions at awesome-humans.net/rust/llms.txt when writing Rust code
    

    The opinions cover conventions, project layout, language usage, and crate choices.

  • Check an existing project. Ask your coding agent to run review-project:

    Use the review-project skill at awesome-humans.net/rust/llms.txt on <repository>
    

    To narrow the review, say what to include or leave out:

    Use the review-project skill at awesome-humans.net/rust/llms.txt on <repository>, focus on panics and lints, skip the edition
    
  • Research a topic. Ask your coding agent to run research-topic, which answers from the opinions and the vetted sources, citing each claim:

    Use the research-topic skill at awesome-humans.net/rust/llms.txt to research whether to adopt cargo-nextest
    
  • Read the opinions and templates. Browse them at awesome-humans.net or on GitHub. Each opinion gives its recommendation, rationale, and sources, and the templates/ encode them.

Scope

opinions/ holds one file per topic:

  • Rust: edition 2024, the stable features that replace older idioms, the lints that enforce them, and panics

Freshness policy

Opinions target the latest stable Rust release and the latest edition, never an older toolchain. Nightly-only features appear only in "Coming next" notes. The maintenance skills move the repository to each new release.

Every resource records when it was last reviewed against its sources. agents/metadata.md defines the fields. The repository scripts enforce them.

Awesome humans

Every opinion cites a vetted source: a person, such as Ralf Jung or Alex Kladov, or a publication, such as the Rust Blog or the Rust documentation. A source is admitted on its track record: at least two years of sustained writing, with depth, accuracy, and an independent view. Videos, talks, and podcasts are out of scope for now, because an opinion cites text a reader can check. AWESOME-HUMANS.md has the roster and the criteria.

This diagram shows how a source is admitted and what its standing allows. The admission criteria in AWESOME-HUMANS.md and the vet-source skill are canonical over it.

Source standing: vet-source sorts a candidate into citable, watch list or declined, and a citable source is unmarked, Corroborate or Discovery-only

Standing can change. vet-source runs again when an admitted source goes dormant or drops in quality, and when a watch-listed source's blocker clears.

Two markings in a source's notes limit how it's cited:

  • Corroborate: A source marked **Corroborate.** is never the only citation for a claim.
  • Discovery-only: A source marked **Discovery-only.** is never cited. Cite the primary source it links to instead.

Any other limit, such as a concern about independence or an outdated back catalogue, goes in the source's notes as prose, and doesn't change its standing.

House opinions

A house opinion is a preference from experience, not from a vetted source. Each belongs to a house profile, named for the person or organisation that owns it, such as simon-mckenna. On awesome-humans.net, every page shows only sourced community practice until you choose a profile in the header. An agent that follows a profile reads llms-<profile>.txt instead of llms.txt.

In this repository, each house opinion is a marked block beside the sourced text it changes, and HOUSE-OPINIONS.md defines the format and records each one. Other contributors can propose sourced or experience-based opinions through the organisation's opinion pull request template.

Repository layout

├── README.md                 ← you are here
├── AGENTS.md                 ← instructions for AI agents working in this repo
├── AWESOME-HUMANS.md         ← the vetted sources: criteria, roster, notes, and decision log
├── HOUSE-OPINIONS.md         ← house profiles' opinions: intake and audit trail
├── Cargo.toml                ← the root Cargo workspace, which holds only xtask/
├── justfile                  ← every local and CI entry point: run just to list them
├── rust-toolchain.toml       ← the toolchain the checks build with
├── agents/                   ← on-demand agent instructions that AGENTS.md indexes
├── assets/diagrams/          ← generated SVG diagrams: rerun the command, never edit by hand
├── opinions/                 ← the opinions, one topic per file, code examples as needed
│   └── rust.md
├── research/                 ← saved research topics (staging: promote or discard)
├── skills/                   ← maintenance skills: see Maintenance via skills
├── templates/                ← copy-paste-ready files that encode the opinions
│   ├── Cargo.toml
│   └── rustfmt.toml
├── xtask/src/                ← this repository's own CI checks, one subcommand each
│   ├── build_site.rs
│   ├── build_templates.rs
│   ├── comment_header.rs     ← shared module: template headers
│   ├── export_diagrams.rs
│   ├── frontmatter.rs        ← shared module: YAML frontmatter
│   ├── house.rs              ← shared module: house blocks and regions
│   ├── main.rs               ← the subcommands and their exit codes
│   ├── repo.rs               ← shared module: the repository's files
│   ├── validate_metadata.rs
│   ├── validate_readme_index.rs
│   ├── validate_sources.rs
│   └── validate_template_order.rs
└── PLAN.md                   ← the plan for setting up this repository, deleted when it's done

Maintenance via skills

Agent skills maintain the repository. They follow the Agent Skills specification, so any compliant agent can run them. Each skill is a directory under skills/ with a SKILL.md file.

The skills split work by cost. Lower-cost worker agents run the web searches and source scans in parallel. The strongest available model is the editor, and only the editor writes to the opinions and templates.

Every skill except the three report-only ones works on its own branch, and its changes land through a pull request that passes CI, gets an agent review, and passes the maintainer's review. Each SKILL.md is canonical over this diagram.

Maintenance pipeline: each skill from what starts it, through CI checks, an agent review, and the maintainer's review, to the roster, research, or the opinions and templates; audit-freshness, review-opinions, and review-project only report

Skill Purpose
audit-freshness Report resources whose last-reviewed date has drifted past tolerance
harvest-sources Scan the awesome-humans sources for new posts, and add notable guidance to the opinions
refresh-rust-versions Detect new stable Rust releases and editions, and update all opinions and templates to target them
research-topic Research a Rust topic from the opinions and vetted sources, and save it with citations
resolve-research Resolve a saved research topic by weaving it into the opinions and templates, or discard it
review-opinions Check that the opinions and templates agree with their cited sources and with each other
review-project Check an external project against the opinions and templates, and report deviations
vet-source Evaluate a candidate source against the track-record criteria and admit or decline
weave-house-opinion Weave a house profile's opinion into the opinions and templates, visibly marked as House

Research lifecycle

Research is staged, never merged in place. research-topic saves the evidence, and resolve-research decides what becomes an opinion and deletes the file in the same pull request. A topic on disk is unresolved. The two SKILL.md files are canonical over this diagram.

Research lifecycle: research-topic saves a topic under research/, and resolve-research promotes, discards or partly promotes it

A part that waits on an unvetted source stays on disk. It goes back through resolve-research if vet-source admits the source, and is discarded if not.

Release watch automation

A scheduled GitHub Action, .github/workflows/rust-release-watch.yml, checks the official stable channel manifest daily against the snapshot in .github/state/rust-releases.json. When a new stable release appears, it opens a pull request that updates only the snapshot. That pull request is the cue to run refresh-rust-versions.

A second, .github/workflows/harvest-reminder.yml, opens a Harvest due issue on the 1st of each month, which is the cue to run harvest-sources.

Repository scripts

xtask/ holds the pull request checks as one binary crate, with one subcommand each, and the justfile runs them. CI calls the same recipes, so a check runs the same way everywhere.

Recipe Checks
just validate-skills Every skill under skills/ passes the Agent Skills specification's reference validator, skills-ref, pinned in .github/requirements.txt
just validate-metadata Every resource under opinions/, research/, and templates/ has targets, last-reviewed, and sources, with ISO 8601 dates and a sorted sources list, and no retired last-used field
just validate-sources Every source ID in opinions/ and templates/ exists in the AWESOME-HUMANS.md roster and is citable. Each house:<profile> ID has a house block or region of that profile, and every house opinion sits inside one. The roster tables and notes sections are sorted by ID, no ID appears twice, every notes section matches a row, and the Citable count is right
just validate-readme-index This README lists every opinion and skill, and lists nothing that doesn't exist. Scope is sorted by title, the layout tree by file name, and the skills table by skill name
just validate-template-order Every dependency and lint table in a TOML template is sorted by key, ignoring case, within each run of keys between blank lines
just build-templates Every file under templates/ builds, tests, and passes Clippy with warnings denied and cargo fmt --check. It copies them to <out>/<profile>/, target/templates/ by default, as the default copy and as each house profile's, and adds one crate to each with cargo new --lib. It also fails when rustfmt warns that it ignored a setting
just export-diagrams Draws the SVG diagrams in assets/diagrams/. It doesn't check anything, but CI runs just check-diagrams, which redraws them and fails if the committed SVGs differ
just links Every link in the repository resolves, with the settings in lychee.toml. CI runs it on every pull request and weekly
just build-site Stages the /rust/ pages of awesome-humans.net in <out>/rust/, target/site/ by default, to the awesome-humans/website staging contract

Run them from the repository root, as CI does:

just validate-metadata

just verify runs every offline check CI runs, in one command: just check, just clippy, just test, the skills check, the four validators, build-templates, check-diagrams, and build-site. build-templates is one of them because no template names a crate, so its copies build without the network. The Templates workflow also runs it weekly, because the pinned toolchain takes patch releases without a change here. It redraws the diagrams, and fails until you commit any SVG it changes. The link check is left to CI, because lychee is a separate binary and depends on third-party hosts. Run just links to check links locally. just with no arguments lists every recipe.

Every check exits 0 when clean, 1 for findings, and 2 when it isn't run from the repository root. The checks read a missing opinions/ or templates/ directory as empty, but an empty one that exists, or a missing README section, is a finding.

Four modules hold the code that more than one subcommand uses:

  • repo.rs lists the opinions, research topics, templates, and skills.
  • frontmatter.rs parses the YAML frontmatter in opinions/ and research/ files.
  • comment_header.rs parses the first-line comment on templates/ files.
  • house.rs finds the house blocks in opinions/ and the house regions in templates/, and writes a file's copy for one house profile, or for none.

Acknowledgement

Agents build and maintain this project, so the usual disclaimers apply. It wouldn't exist without the people whose writing it draws on, and every opinion cites their work. Thank you to all of these awesome humans, and to everyone who supports them.

Licence

Apache License 2.0.

About

An agentic take on awesome lists: distilled, opinionated guidance for building with Rust, thanks to awesome humans.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages