From a41582f4696e0c8e644f8a62456a369e6572ac21 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=BE=90=E6=B6=9B?= <midnite@outlook.com>
Date: Thu, 7 May 2026 10:40:03 +0800
Subject: [PATCH] docs: add Rust module organization guidelines to AGENTS.md

---
 AGENTS.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 5450450..4f3041d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -87,6 +87,23 @@ For multi-step tasks, state a brief plan:
 - 优先使用 `Result` 处理错误，避免 `unwrap()`
 - 所有权规则：不使用 `&mut` 时不用，引用必须合法
 
+**模块组织**
+- 按功能领域组织模块（一个模块一个职责）
+- 功能相关和相似的代码归入同一模块
+- 使用 Rust 新风格模块结构：`foo.rs` 作为模块根，子模块在 `foo/bar.rs`，**不使用 `mod.rs`**
+- 示例：
+  ```
+  src/
+    lib.rs                # crate 根
+    types.rs              # mod types
+    provider.rs           # mod provider (根)
+    provider/
+      openai.rs           # provider::openai
+    cycle.rs              # mod cycle (根)
+    cycle/
+      retry.rs            # cycle::retry
+  ```
+
 **测试文件**: 内联测试（`#[cfg(test)] mod tests {}`）或 `tests/` 目录
 
 **依赖管理**: `Cargo.toml`，语义化版本