From b06c7a51bd052cd6a92990172e7c079a271840e9 Mon Sep 17 00:00:00 2001 From: Ralf Biedert Date: Fri, 5 Sep 2025 17:50:39 +0200 Subject: [PATCH] Turn AI appendix into actual guide M-DESIGN-FOR-AI --- src/SUMMARY.md | 2 +- .../ai/M-DESIGN-FOR-AI.md} | 34 +++++++++++-------- src/guidelines/ai/README.md | 5 +++ src/guidelines/checklist/README.md | 5 +++ .../universal/M-UPSTREAM-GUIDELINES.md | 3 +- 5 files changed, 31 insertions(+), 18 deletions(-) rename src/{designing_for_ai/README.md => guidelines/ai/M-DESIGN-FOR-AI.md} (53%) create mode 100644 src/guidelines/ai/README.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index d44e410..fc1ba13 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -14,9 +14,9 @@ - [Safety](./guidelines/safety/README.md) - [Performance](./guidelines/performance/README.md) - [Documentation](./guidelines/docs/README.md) +- [AI](./guidelines/ai/README.md) --- -[Designing for AI](./designing_for_ai/README.md) [Agents & LLMs](./agents/README.md) [FAQ](./FAQ/README.md) diff --git a/src/designing_for_ai/README.md b/src/guidelines/ai/M-DESIGN-FOR-AI.md similarity index 53% rename from src/designing_for_ai/README.md rename to src/guidelines/ai/M-DESIGN-FOR-AI.md index 5ffb0b1..6924c7e 100644 --- a/src/designing_for_ai/README.md +++ b/src/guidelines/ai/M-DESIGN-FOR-AI.md @@ -1,27 +1,32 @@  -# Designing for AI +## Design with AI use in Mind (M-DESIGN-FOR-AI) { #M-DESIGN-FOR-AI } -It's becoming increasingly important to design APIs and components that can easily be understood and programmed -using AI coding agents. As a general rule, making APIs easier to use for humans also makes them easier to use by -AI, so if you're following the guidelines in this book, you'll be in good shape. +To maximize the utility you get from letting agents work in your code base. +0.1 + +As a general rule, making APIs easier to use for humans also makes them easier to use by AI. +If you follow the guidelines in this book, you should be in good shape. + +Rust's strong type system is a boon for agents, as their lack of genuine understanding can often be +counterbalanced by comprehensive compiler checks, which Rust provides in abundance. With that said, there are a few guidelines which are particularly important to help make AI coding in Rust more effective: * **Create Idiomatic Rust API Patterns**. The more your APIs, whether public or internal, look and feel like the majority of -Rust code in the world, the better it is for AI. Follow the guidelines from the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/checklist.html) -along with the guidelines from [Library / UX](../guidelines/libs/ux). +Rust code in the world, the better it is for AI. Follow the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/checklist.html) +along with the guidelines from [Library / UX](../libs/ux). -* **Provide Thorough Docs**. AI agents love good detailed docs. Include docs for all of your modules and all the public items in your crates. -Assume the reader has a solid, but not expert, level of understanding of Rust and that the reader understands the standard library. +* **Provide Thorough Docs**. Agents love good detailed docs. Include docs for all of your modules and public items in your crate. +Assume the reader has a solid, but not expert, level of understanding of Rust, and that the reader understands the standard library. Follow [C-CRATE-DOC](https://rust-lang.github.io/api-guidelines/checklist.html#c-crate-doc), [C-FAILURE](https://rust-lang.github.io/api-guidelines/checklist.html#c-failure), [C-LINK](https://rust-lang.github.io/api-guidelines/checklist.html#c-link), and -[M-MODULE-DOCS](../guidelines/docs/#M-MODULE-DOCS) -[M-CANONICAL-DOCS](../guidelines/docs/#M-CANONICAL-DOCS). +[M-MODULE-DOCS](../docs/#M-MODULE-DOCS) +[M-CANONICAL-DOCS](../docs/#M-CANONICAL-DOCS). -* **Provide Thorough Examples**. Your documentation should have many directly usable examples, and the repository should include additional fuller examples. +* **Provide Thorough Examples**. Your documentation should have directly usable examples, the repository should include more elaborate ones. Follow [C-EXAMPLE](https://rust-lang.github.io/api-guidelines/checklist.html#c-example) [C-QUESTION-MARK](https://rust-lang.github.io/api-guidelines/checklist.html#c-question-mark). @@ -30,10 +35,9 @@ Follow Follow [C-NEWTYPE](https://rust-lang.github.io/api-guidelines/checklist.html#c-newtype). -* **Use Errors Instead of Panicking**. Panics should be reserved for programming error and not be part of the normal -control flow for a production application. Parsers should usually not panic, I/O failures should not lead to a panic. -Instead, use return robust errors following the normal Rust conventions. - * **Make Your APIs Testable**. Design APIs which allow your customers to test their use of your API in unit tests. This might involve introducing some mocks, fakes, or cargo features. AI agents need to be able to iterate quickly to prove that the code they are writing that calls your API is working correctly. + +* **Ensure Test Coverage**. Your own code should have good test coverage over observable behavior. +This enables agents to work in a mostly hands-off mode when refactoring. diff --git a/src/guidelines/ai/README.md b/src/guidelines/ai/README.md new file mode 100644 index 0000000..bd01803 --- /dev/null +++ b/src/guidelines/ai/README.md @@ -0,0 +1,5 @@ + + +# AI Guidelines + +{{#include M-DESIGN-FOR-AI.md}} diff --git a/src/guidelines/checklist/README.md b/src/guidelines/checklist/README.md index 9fc8f63..88366ab 100644 --- a/src/guidelines/checklist/README.md +++ b/src/guidelines/checklist/README.md @@ -58,6 +58,8 @@ - [ ] Has Module Documentation ([M-MODULE-DOCS]) - [ ] Documentation Has Canonical Sections ([M-CANONICAL-DOCS]) - [ ] Mark `pub use` Items with `#[doc(inline)]` ([M-DOC-INLINE]) +- **AI** + - [ ] Design with AI use in Mind ([M-DESIGN-FOR-AI]) [M-UPSTREAM-GUIDELINES]: ../universal/#M-UPSTREAM-GUIDELINES @@ -118,3 +120,6 @@ [M-MODULE-DOCS]: ../docs/#M-MODULE-DOCS [M-CANONICAL-DOCS]: ../docs/#M-CANONICAL-DOCS [M-DOC-INLINE]: ../docs/#M-DOC-INLINE + + +[M-DESIGN-FOR-AI]: ../ai/#M-DESIGN-FOR-AI diff --git a/src/guidelines/universal/M-UPSTREAM-GUIDELINES.md b/src/guidelines/universal/M-UPSTREAM-GUIDELINES.md index 386b467..5764ef9 100644 --- a/src/guidelines/universal/M-UPSTREAM-GUIDELINES.md +++ b/src/guidelines/universal/M-UPSTREAM-GUIDELINES.md @@ -12,8 +12,7 @@ The guidelines in this book complement existing Rust guidelines, in particular: - [Rust Design Patterns](https://rust-unofficial.github.io/patterns//intro.html) - [Rust Reference - Undefined Behavior](https://doc.rust-lang.org/reference/behavior-considered-undefined.html) -We recommend you read through these as well, and apply them in addition to this book's guidelines. Pay special attention to these -guidelines, as they are frequently forgotten: +We recommend you read through these as well, and apply them in addition to this book's items. Pay special attention to the ones below, as they are frequently forgotten: - [ ] [C-CONV](https://rust-lang.github.io/api-guidelines/naming.html#ad-hoc-conversions-follow-as_-to_-into_-conventions-c-conv) - Ad-hoc conversions follow `as_`, `to_`, `into_` conventions