Add AI assistant guidance

[ivy]

Hey team! I'm trying to see how we can use tools like Claude Code and Cursor to make our Rust projects (pks and codeowners-rs) easier for contributors who are productive in other languages already, but haven't used Rust extensively.

What's Changed

I added an AGENTS.md file to serve as agent-agnostic guidance for writing idiomatic Rust. I'm not an expert here so I want to invite some feedback.

Key Areas for Alignment

1. Error Handling Philosophy: "Panic for Programming Bugs, Result for Recoverable Errors"

My back-and-forth with Claude Code and some Googling led to a "principled approach" to error handling that I'd like some feedback on:

When to panic (.expect() / .unwrap()):

• Programming bugs that should never happen if code is correct
• Use descriptive panic messages with context
• Add debug_assert! for development-time invariant checking

When to use Result and ?:

• External factors like file I/O, network, malformed input
• Graceful degradation scenarios
• Data that could be corrupted

Decision framework:

"If this fails, is it because my code has a bug (panic) or external factors beyond my control (Result)?"

Alternative:
No-Panic Rust: A Nice Technique for Systems Programming or at least, almost no-panic Rust sounds applicable for projects intended to be used as libraries, like with codeowners-rs which we now embed into a Ruby gem (I can see us shipping libraries for other languages too).

2. Rust Idioms We Emphasize

As I worked on #20, I asked Claude Code to expand on AGENTS.md based on the feedback I gave it as well as feedback from the PR review. I further asked it to expand on Rust idioms and best practices and it distilled this down to:

• Iterator chains over manual loops - More functional, composable code
• Exhaustive pattern matching - Use match instead of if-else chains when handling all variants
• Borrowing over ownership - Only take ownership when necessary
• if let for single pattern matching - Cleaner than verbose match statements
• Rayon parallel iterators - Leverage our performance focus

Questions for the Team

1. Error handling approach - Do you agree with the "panic for bugs, Result for external errors" philosophy? Any exceptions or refinements?
2. Rust idioms & priority - Are there other Rust patterns we should emphasize or de-emphasize for AI assistance?

Benefits

• Consistent AI-generated code that follows our established patterns
• Reduced code review overhead by setting clear expectations upfront
• Faster onboarding for new AI tools and team members
• Documentation of tribal knowledge about our architectural decisions
• Better debugging through descriptive error messages and assertions

---

Looking forward to your feedback! 💛 ✨

[perryqh]

I've been avoiding panic and instead propagating errors with Result return types. I could see the packs gem wrapping pks in the future. It would be a benefit for clients to decide how they want to handle errors.

[perryqh]

This is a good start. Thanks!

I just have the comment regarding panicking.

A nice to have would be for the AI assistant to be aware of https://rust-unofficial.github.io/patterns/patterns/index.html. These patterns are useful and I find myself needing to frequently review them. It'd be nice to get some AI assistance.