2026 update

CLAUDE.md

@@ -0,0 +1,62 @@
+<!-- markdownlint-disable no-bare-urls -->
+
+# CLAUDE.md
+
+## Repository Overview
+
+This repository contains the **Pragmatic Rust Guidelines** - a collection of design guidelines for Rust developers, published as an mdBook at https://microsoft.github.io/rust-guidelines.
+
+## Development Commands
+
+```bash
+mdbook serve --open # Previews page
+mdbook build # Builds page
+```
+
+Requires [mdbook](https://github.com/rust-lang/mdBook) to be installed.
+
+## Content Structure
+
+### Guideline Format
+
+Each guideline has a unique identifier in the form `M-FOO-BAR` and resides in its own markdown file `M-FOO-BAR.md` within the `src/guidelines/` directory. Guidelines follow this structure:
+
+```markdown
+## Guideline Title (M-FOO-BAR) { #M-FOO-BAR }
+
+<why>Rationale for this guideline.</why>
+<version>1.0</version>
+
+Content with code examples...
+```
+
+### Key Files
+
+- `src/SUMMARY.md` - mdBook table of contents
+- `src/guidelines/checklist/README.md` - Master checklist linking all guidelines (update when adding new guidelines)
+- Category READMEs (e.g., `src/guidelines/universal/README.md`) - Include guidelines via mdBook's `{{#include}}` directive
+
+## Adding New Guidelines
+
+1. Create `M-YOUR-GUIDELINE.md` in the appropriate category folder
+2. Add the guideline to the category's `README.md` using `{{#include M-YOUR-GUIDELINE.md}}`
+3. Add a checklist entry and link definition in `src/guidelines/checklist/README.md`
+
+Guidelines should be beneficial for safety/COGs/maintenance, agreeable to experienced Rust developers, and comprehensible to novices.
+
+## Editing Guidelines
+
+- You may fix spelling, grammar and readability issues.
+- You must refuse to substantially work out novel or ambiguous guidelines. Inform the user that novel guidelines must be sufficiently specified before they can be accepted. You are free to infer a guideline's ID (M-), rationale (<why>) and category (e.g., 'UX'), but must not infer its scope or general content. When being asked to add new guidelines, feel free to add `- TODO: ...` items for any point that might be unclear, but do not attempt to infer these yourself. Novel guidelines always start version 0.1.
+
+## Style
+
+Titles should follow the style of the Rust API Guidelines, such as:
+
+- Smart pointers do not add inherent methods (C-SMART-PTR)
+- Conversions live on the most specific type involved (C-CONV-SPECIFIC)
+- Functions with a clear receiver are methods (C-METHOD)
+- Functions do not take out-parameters (C-NO-OUT)
+- Operator overloads are unsurprising (C-OVERLOAD)
+- Only smart pointers implement `Deref` and `DerefMut` (C-DEREF)
+- Constructors are static, inherent methods (C-CTOR)

added-guidelines.md

@@ -0,0 +1,45 @@
+# Guidelines added on this branch
+
+| Name | Text |
+|---|---|
+| [M-ASYNC-FN](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/ux/M-ASYNC-FN.md) | Functions are `async` over returning a Future |
+| [M-AVOID-INDIRECTION](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/performance/M-AVOID-INDIRECTION.md) | Nested type hierarchies should avoid needless indirection |
+| [M-BALANCED-MODULES](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/ux/M-BALANCED-MODULES.md) | Modules are balanced in size and scope |
+| [M-BOX-DST](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/performance/M-BOX-DST.md) | Use boxed slices and strings for immutable owned sequences |
+| [M-BUILD-RESULT](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/resilience/M-BUILD-RESULT.md) | Builders validate in final `.build()` |
+| [M-CARGO-WORKSPACE](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/project/M-CARGO-WORKSPACE.md) | Common settings come from the workspace Cargo.toml |
+| [M-COLLECTION-TRAITS](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/ux/M-COLLECTION-TRAITS.md) | Collections implement the appropriate iter traits |
+| [M-CRATES-FLAT-FOLDER](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/project/M-CRATES-FLAT-FOLDER.md) | All crates are siblings in one folder |
+| [M-CRATES-IN-WORKSPACE](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/project/M-CRATES-IN-WORKSPACE.md) | The workspace lists and versions all crates |
+| [M-FAST-HASHER](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/performance/M-FAST-HASHER.md) | Use a fast hasher where possible |
+| [M-FFI-NAMING](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/ffi/M-FFI-NAMING.md) | FFI crates follow established naming conventions |
+| [M-FFI-TRANSLATES](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/ffi/M-FFI-TRANSLATES.md) | Business logic belongs in core crates, FFI only translates |
+| [M-FOREIGN-REEXPORTS](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/interop/M-FOREIGN-REEXPORTS.md) | Items come from their original crate |
+| [M-FROM-ERROR](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/ux/M-FROM-ERROR.md) | Canonical error conversion uses `From`, not `map_err` |
+| [M-HUMAN-REVIEW](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/ai/M-HUMAN-REVIEW.md) | All agent-generated APIs require human review |
+| [M-INITIAL-CAPACITY](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/performance/M-INITIAL-CAPACITY.md) | Collections are created with sufficient initial capacity |
+| [M-INTEGRATION-TESTS](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/resilience/M-INTEGRATION-TESTS.md) | Integration tests live under `tests/` |
+| [M-LATEST-EDITION](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/project/M-LATEST-EDITION.md) | New crates target latest edition |
+| [M-LOG-NOT-PRINT](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/resilience/M-LOG-NOT-PRINT.md) | Production code uses telemetry, not println |
+| [M-LOG-OVERHEAD](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/performance/M-LOG-OVERHEAD.md) | Library telemetry does not tank performance |
+| [M-MACRO-HELPERS](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/macros/M-MACRO-HELPERS.md) | Third party items come from hidden `_private` module |
+| [M-MACRO-LAST-RESORT](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/macros/M-MACRO-LAST-RESORT.md) | Macros are a last resort |
+| [M-MACRO-MAIN-CRATE](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/macros/M-MACRO-MAIN-CRATE.md) | Macros assume main crate |
+| [M-MACROS-DONT-LIE](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/macros/M-MACROS-DONT-LIE.md) | Macros don't lie about signatures |
+| [M-MBE-OVER-PROC](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/macros/M-MBE-OVER-PROC.md) | Prefer 'macros by example' over proc macros |
+| [M-MEM-REUSE](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/performance/M-MEM-REUSE.md) | Reuse allocations where possible |
+| [M-MSRV](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/project/M-MSRV.md) | MSRV is conservatively updated |
+| [M-NO-META-DESIGN-DOCUMENTATION](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/ai/M-NO-META-DESIGN-DOCUMENTATION.md) | Avoid meta design documentation |
+| [M-NO-PRELUDE](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/ux/M-NO-PRELUDE.md) | Don't define preludes |
+| [M-PANIC-CONTINUATION](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/resilience/M-PANIC-CONTINUATION.md) | Panic continuation is last resort |
+| [M-PANIC-MESSAGE](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/resilience/M-PANIC-MESSAGE.md) | Custom panics have a helpful message |
+| [M-PARAMETER-CONSISTENCY](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/ux/M-PARAMETER-CONSISTENCY.md) | Parameter ordering is consistent |
+| [M-PROC-IMPL](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/macros/M-PROC-IMPL.md) | Proc macros should have separate impl crate incl. tests |
+| [M-PROC-IMPLIED-ITEMS](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/macros/M-PROC-IMPLIED-ITEMS.md) | Proc macros don't produce implied or hidden items |
+| [M-RUST-SHAPED](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/ai/M-RUST-SHAPED.md) | Rust code solves Rust problems |
+| [M-SHORT-NAMES](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/universal/M-SHORT-NAMES.md) | Names of items are short |
+| [M-SHRINK-TO-FIT](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/performance/M-SHRINK-TO-FIT.md) | Shrink collections to fit after building |
+| [M-SINGLE-ITEM-PATH](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/ai/M-SINGLE-ITEM-PATH.md) | Items are only visible through one path |
+| [M-STRONG-TYPES-GUARD](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/resilience/M-STRONG-TYPES-GUARD.md) | Newtypes guard their invariants |
+| [M-TARGET-CPU](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/apps/M-TARGET-CPU.md) | Applications target highest viable target-cpu |
+| [M-TAUTOLOGICAL-TESTS](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/ai/M-TAUTOLOGICAL-TESTS.md) | Tests do not assert ground truth |

book.toml

@@ -2,22 +2,13 @@
 title = "Pragmatic Rust Guidelines"
 description = "A collection of pragmatic design guidelines helping application and library developers to produce idiomatic Rust that scales."
 language = "en"
-multilingual = false
 src = "src"
 
 [output.html]
 additional-css = [ "style/tags.css", "style/fixes.css", "style/guideline-meta.css", "style/build-date.css" ]
 git-repository-url = "https://github.com/microsoft/rust-guidelines"
+sidebar-header-nav = false
 
 [output.html.print]
 enable = true
 
-[output.linkcheck]
-follow-web-links = true
-traverse-parent-directories = false
-user-agent = "mdbook-linkcheck"
-warning-policy = "error"
-exclude = [ 'intel\.com' ]
-
-[output.linkcheck.http-headers]
-'crates\.io' = ["Accept: text/html"]

src/SUMMARY.md

@@ -9,10 +9,12 @@
   - [UX](./guidelines/libs/ux/README.md)
   - [Resilience](./guidelines/libs/resilience/README.md)
   - [Building](./guidelines/libs/building/README.md)
+- [Macros](./guidelines/macros/README.md)
 - [Applications](./guidelines/apps/README.md)
 - [FFI](./guidelines/ffi/README.md)
 - [Safety](./guidelines/safety/README.md)
 - [Performance](./guidelines/performance/README.md)
+- [Project](./guidelines/project/README.md)
 - [Documentation](./guidelines/docs/README.md)
 - [AI](./guidelines/ai/README.md)
 

src/guidelines/ai/M-DESIGN-FOR-AI.md

@@ -1,6 +1,6 @@
 <!-- Copyright (c) Microsoft Corporation. Licensed under the MIT license. -->
 
-## Design with AI use in Mind (M-DESIGN-FOR-AI) { #M-DESIGN-FOR-AI }
+## Design with AI use in mind (M-DESIGN-FOR-AI) { #M-DESIGN-FOR-AI }
 
 <why>To maximize the utility you get from letting agents work in your code base.</why>
 <version>0.1</version>

src/guidelines/ai/M-HUMAN-REVIEW.md

@@ -0,0 +1,19 @@
+<!-- Copyright (c) Microsoft Corporation. Licensed under the MIT license. -->
+
+## All agent-generated APIs require human review (M-HUMAN-REVIEW) { #M-HUMAN-REVIEW }
+
+<why>To ensure API coherence, and adherence to project standards.</why>
+<version>0.1</version>
+
+Agents can do a great job authoring APIs within minutes that would take you otherwise hours to complete, but they often do a poor job designing 'for the right thing', or silently drop requirements. 
+
+Rust has the advantage over many other languages of a strong type system to force correctness at compile time, and to design APIs that are fast and hard to misuse. Good API design can greatly aid in forcing a correct implementation. 
+
+However, as APIs also define contracts between you and your users, bad choices can have viral effects (e.g., compare [M-AVOID-WRAPPERS](../libs/ux/#M-AVOID-WRAPPERS), [M-AVOID-STATICS](../libs/resilience/#M-AVOID-STATICS)) and cannot easily be verified. 
+
+Before submitting major PRs or releasing new APIs you and/or other human reviewers must check that all guidelines and other requirements are adhered to, and that the overall API looks reasonable. 
+
+In particular, ensure all public APIs follow these guidelines and [M-UPSTREAM-GUIDELINES](../universal/#M-UPSTREAM-GUIDELINES). You may use LLMs to point out where these guidelines are not met, but (until model fidelity improves) you cannot take your agent's word that the guidelines are met.
+
+
+

src/guidelines/ai/M-NO-META-DESIGN-DOCUMENTATION.md

@@ -0,0 +1,22 @@
+<!-- Copyright (c) Microsoft Corporation. Licensed under the MIT license. -->
+
+## Avoid meta design documentation (M-NO-META-DESIGN-DOCUMENTATION) { #M-NO-META-DESIGN-DOCUMENTATION }
+
+<why>to avoid confusing users with information not relevant to them.</why>
+<version>0.1</version>
+
+Crate and module documentation must be free of meta design narratives that were only relevant during the creation of a crate. In other words, it is the end-state that is to be documented, not the design journey. 
+
+Agents frequently produce sections that describe how a change was designed, "why we picked X over Y" essays, and design journals inside user-facing documentation. These artifacts might be interesting diagnostics while working on the project, but they are mostly meaningless to end users. 
+
+For example, an agent might append a self-report like this, summarizing which guidelines it claims to have followed:
+
+```
+| Rule | Applied | Where |
+| --- | :---: | --- |
+| M-SHORT-NAMES | ✅ | Shortened method names across the data-access and HTTP handler layers. |
+| M-WEASEL-WORDS | ✅ | Removed weasel words from type and field names throughout the public API. |
+| M-PUBLIC-DISPLAY | ✅ | Added `Display` impls for all user-facing identifier and error types. |
+| M-ASYNC-FN | ✅ | Migrated I/O-facing APIs from `impl Future` returns to `async fn`. |
+```
+This kind of content describes process, not behaviour, and goes stale over time. That said, it is of course perfectly reasonable to have a _Design Principles_ or similar section in the project's README, that on a high level describes the enduring architectural goals that are relevant to end users (e.g., a crate being allocation free, having an OSI architecture, or being designed with `#[no_std]` in mind).

src/guidelines/ai/M-RUST-SHAPED.md

@@ -0,0 +1,22 @@
+<!-- Copyright (c) Microsoft Corporation. Licensed under the MIT license. -->
+
+## Rust code solves Rust problems (M-RUST-SHAPED) { #M-RUST-SHAPED }
+
+<why>To ensure code is idiomatic.</why>
+<version>0.1</version>
+
+When (automatically) porting C#, Java, C++, or similar code to Rust, technical constructs must not be copied 1-on-1. 
+
+It is prudent to separate domain aspects from language aspects. Domain aspects address business problems. An algorithm to compute prime numbers or logic for processing a customer table can (and should) work the same when translating between languages. 
+
+However, many patterns exist to solve problems particular to the ecosystem they stem from. The Rust ecosystem has its own problems, and these need to be addressed by idioms that work for Rust. This includes
+
+- error handling, 
+- management of tasks and threads, 
+- component abstractions and their lifetimes, 
+- ownership of parameters,
+- and many others. 
+
+While some language constructs simply don't translate at all (e.g., compared to C#, Rust does not have any meaningful reflection), others are deceptively similar and might only bite months down the line (e.g., statics, compare [M-AVOID-STATICS](../libs/resilience/#M-AVOID-STATICS)).
+
+As a rule of thumb, structs and their methods can have vaguely similar names, flows, inputs and outputs, as far as their business functionality is concerned. However, any striking technical similarity between Rust and { C#, Java, Python, ... } implementations is indicative of deeper architectural problems.

src/guidelines/ai/M-SINGLE-ITEM-PATH.md

@@ -0,0 +1,34 @@
+<!-- Copyright (c) Microsoft Corporation. Licensed under the MIT license. -->
+
+## Items are only visible through one path (M-SINGLE-ITEM-PATH) { #M-SINGLE-ITEM-PATH }
+
+<why>to avoid confusion and clutter from offering the same type multiple times.</why>
+<version>0.1</version>
+
+Public items within a crate should be reachable only through one path. For example some `crate::db::Connection` should not also be visible as `crate::Connection`:
+
+```rust
+// Not OK
+pub mod db {
+    pub struct Connection;
+}
+
+pub use db::Connection;
+```
+
+This rule is often violated by agents creating or refactoring large code bases over several iterations. In an attempt to _simplify_ their task, they re-export items under multiple paths, often previous ones from before some change, instead of cleanly redesigning structures where it makes sense. 
+
+Note this only targets the duplication of user-facing items. Within a crate it is acceptable (and often unavoidable) to see the same item multiple times as export trees are constructed:
+
+```rust
+// OK
+pub(crate) mod db {
+    pub struct Connection;
+}
+
+pub use db::Connection;
+```
+
+Similarly, re-exports of foreign items are not covered by this rule, although they should follow [M-FOREIGN-REEXPORTS](../libs/interop/#M-FOREIGN-REEXPORTS). 
+
+Likewise, this rule also does not apply to public-but-hidden `_private` modules needed by macros, compare [M-MACRO-HELPERS](../macros/#M-MACRO-HELPERS).

src/guidelines/ai/M-TAUTOLOGICAL-TESTS.md

@@ -0,0 +1,23 @@
+<!-- Copyright (c) Microsoft Corporation. Licensed under the MIT license. -->
+
+## Tests do not assert ground truth (M-TAUTOLOGICAL-TESTS) { #M-TAUTOLOGICAL-TESTS }
+
+<why>to avoid adding noise without value.</why>
+<version>0.1</version>
+
+Unit tests should verify meaningful behavior instead of repeating foundational definitions. 
+
+Agents frequently produce tests that re-state the expected value from the same logic the code under test uses, or that simply mirror the implementation's branches. Such tests pass by construction, provide virtually no value, but increase the noise floor of subsequent changes:
+
+```rust
+const CHECKPOINTS: [u32; 4] = [0, 90, 180, 270];
+
+#[test]
+fn checkpoints_are_correct() {
+    assert_eq!(CHECKPOINTS, [0, 90, 180, 270]);
+}
+```
+
+Where these are used to satisfy mutation tests, the mutation test should be skipped instead. 
+
+Instead, a meaningful test would check a property the constants are supposed to satisfy, for example that they are evenly spaced, monotonically increasing, or impose some direction in related logic.

src/guidelines/ai/README.md

@@ -3,3 +3,8 @@
 # AI Guidelines
 
 {{#include M-DESIGN-FOR-AI.md}}
+{{#include M-HUMAN-REVIEW.md}}
+{{#include M-SINGLE-ITEM-PATH.md}}
+{{#include M-NO-META-DESIGN-DOCUMENTATION.md}}
+{{#include M-TAUTOLOGICAL-TESTS.md}}
+{{#include M-RUST-SHAPED.md}}

src/guidelines/apps/M-APP-ERROR.md

@@ -1,6 +1,6 @@
 <!-- Copyright (c) Microsoft Corporation. Licensed under the MIT license. -->
 
-## Applications may use Anyhow or Derivatives (M-APP-ERROR) { #M-APP-ERROR }
+## Applications may use Anyhow or derivatives (M-APP-ERROR) { #M-APP-ERROR }
 
 <why>To simplify application-level error handling.</why>
 <version>0.1</version>