Turn AI appendix into actual guide M-DESIGN-FOR-AI

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)

src/designing_for_ai/README.md → src/guidelines/ai/M-DESIGN-FOR-AI.md

@@ -1,27 +1,32 @@
 <!-- Copyright (c) Microsoft Corporation. Licensed under the MIT license. -->
 
-# 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.
+<why>To maximize the utility you get from letting agents work in your code base.</why>
+<version>0.1</version>
+
+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.

src/guidelines/ai/README.md

@@ -0,0 +1,5 @@
+<!-- Copyright (c) Microsoft Corporation. Licensed under the MIT license. -->
+
+# AI Guidelines
+
+{{#include M-DESIGN-FOR-AI.md}}

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])
 
 <!-- Universal  -->
 [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
+
+<!-- AI -->
+[M-DESIGN-FOR-AI]: ../ai/#M-DESIGN-FOR-AI

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