From f9671a2f5157e3954f6646b389fd16e3a5bd73d2 Mon Sep 17 00:00:00 2001 From: Ralf Biedert Date: Fri, 23 Jan 2026 13:22:04 +0100 Subject: [PATCH 1/2] Add claude file with ground rules. --- CLAUDE.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..7aea446 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,50 @@ +# 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 } + +Rationale for this guideline. +1.0 + +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 () 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. \ No newline at end of file From 1d0fc4a3b7f9310fc36430883835efa9e030ee91 Mon Sep 17 00:00:00 2001 From: Ralf Biedert Date: Fri, 23 Jan 2026 13:42:54 +0100 Subject: [PATCH 2/2] Update file. --- CLAUDE.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 7aea446..12087ac 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,3 +1,5 @@ + + # CLAUDE.md ## Repository Overview @@ -34,7 +36,6 @@ Content with code examples... - `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 @@ -43,8 +44,19 @@ Content with code examples... 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 () 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. \ No newline at end of file +- 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 () 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)