feat: enhance AGENTS.md with detailed style, linting, and organization guidelines

Author: kosiew

AGENTS.md

@@ -2,7 +2,23 @@
 
 ## Style and Linting
 - Python formatting and linting is handled by **ruff**.
-- Rust code must pass `cargo fmt`, `cargo clippy`, and `cargo tomlfmt`.
+- Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) and these key
+  ruff rules:
+  - Use double quotes for string literals
+  - Use explicit relative imports such as `from .module import Class`
+  - Limit lines to 88 characters
+  - Provide type hints for parameters and return values
+  - Avoid unused imports
+  - Prefer f-strings over other string formatting
+  - Avoid `else` blocks after `return`
+  - Use `isinstance()` instead of direct type comparison
+  - Keep docstrings concise in Google format
+  - Assign exception messages to variables before raising
+- All modules, classes, and functions should include docstrings.
+- Tests must use descriptive function names, pytest style assertions, and be
+  grouped in classes when appropriate.
+- Rust code must pass `cargo fmt`, `cargo clippy`, and `cargo tomlfmt` and
+  should omit unnecessary parentheses around `if` conditions.
 - Install the pre-commit hooks with `pre-commit install` and run them with
   `pre-commit run --files <file1> <file2>` or `pre-commit run --all-files`.
 - The same checks can be run manually using the scripts in `ci/scripts`:
@@ -11,6 +27,19 @@
   - `./ci/scripts/rust_clippy.sh`
   - `./ci/scripts/rust_toml_fmt.sh`
 
+## Code Organization
+- Keep functions focused and under about 50 lines.
+- Break complex tasks into well-named helper functions and reuse existing
+  helpers when possible.
+- Prefer adding parameters to existing functions rather than creating new
+  versions with similar behavior.
+- Avoid unnecessary abstractions and follow established patterns in the
+  codebase.
+
+## Comments
+- Add meaningful comments for complex logic and avoid obvious comments.
+- Start inline comments with a capital letter.
+
 ## Running Tests
 1. Ensure submodules are initialized:
    ```bash