chore: add AGENTS.md

AGENTS.md

@@ -0,0 +1,161 @@
+# AGENTS.md — Development Guidelines
+
+> Unified development guidelines for all AI coding assistants (Claude Code, Cursor, etc.)
+
+**Last Updated**: 2026-06-11
+
+---
+
+## 1. Language
+
+Always respond in **Chinese (中文)**. Code, commands, and technical terms remain in English.
+
+---
+
+## 2. Code Style
+
+### 2.1 Basic Principles
+
+- Follow existing project conventions
+- Use meaningful variable names
+- Keep functions under **50 lines**
+- Maximum nesting depth: **3 levels**
+- Add comments for complex logic only
+
+### 2.2 Rust Best Practices
+
+- Use `?` operator; never use `unwrap()` in non-test code
+- Avoid `unsafe`; if necessary, add `// SAFETY:` comment
+- Minimize `clone()`; prefer references
+- No magic numbers; use named constants
+- No hardcoded strings; use enums or constants
+
+### 2.3 Import Order
+
+```rust
+// std → third-party crates → local modules
+use std::collections::HashMap;
+
+use serde::{Deserialize, Serialize};
+
+use crate::error::{AppError, AppResult};
+```
+
+---
+
+## 3. Forbidden Patterns
+
+- `// ── xxxx ──────────` — no divider comments
+- `unwrap()` / `expect()` in non-test code — use `?` instead
+- `panic!()` / `unreachable!()` — use error types instead
+- Untracked `todo!()` — must have a corresponding issue
+- Commented-out code — use Git history instead
+- Nesting depth ≥ 4 — flatten with early return
+- Functions > 50 lines — split into smaller functions
+- Magic numbers — define named `const`
+- Hardcoded strings — use enums or constants
+
+---
+
+## 4. Error Handling
+
+### 4.1 Principles
+
+- Handle all errors explicitly; no silent failures
+- Log internal errors; keep user-facing messages helpful
+- Add context with `.context()` or `.map_err()`
+
+### 4.2 Log Format
+
+```rust
+tracing::error!(
+    error = %err,
+    operation = "operation_name",
+    "Failed to perform operation"
+);
+```
+
+---
+
+## 5. Security
+
+- Never hardcode secrets or API keys
+- Always validate and sanitize user input
+- Use parameterized queries (no SQL injection)
+- Use proper password hashing (Argon2, bcrypt)
+
+---
+
+## 6. Workflow
+
+### 6.1 Development Flow
+
+1. **Read before write** — understand context first
+2. **Minimal changes** — don't refactor unrelated code
+3. **Verify after changes** — run tests or check output
+
+### 6.2 AI Assistant Rules
+
+- Always read existing code before making changes
+- Make minimal changes
+- Run `cargo check` or `cargo test` after changes
+- Explain what you changed and why
+
+### 6.3 Common Commands
+
+```bash
+cargo build    # Build
+cargo check    # Quick syntax check
+cargo test     # Run tests
+cargo clippy   # Lint
+cargo fmt      # Format
+```
+
+---
+
+## 7. Git Workflow
+
+### 7.1 Commit Message Format
+
+```
+<type>(<scope>): <subject>
+
+[optional body]
+
+[optional footer]
+```
+
+Types: `feat` · `fix` · `refactor` · `docs` · `test` · `chore`
+
+### 7.2 Commit Principles
+
+- Each commit addresses one concern (atomic)
+- Each commit leaves the codebase in a working state
+- Never force push to `main`
+
+---
+
+## Appendix: Architecture Overview
+
+```
+gitks — Git Repository Operations Service
+
+actor/       → Actor model
+archive/     → Archive operations
+blame/       → Blame operations
+blob/        → Blob objects
+branch/      → Branch operations
+commit/      → Commit operations
+diff/        → Diff operations
+merge/       → Merge operations
+pack/        → Pack operations
+refs/        → Reference management
+remote/      → Remote operations
+repository/  → Repository operations
+server/      → gRPC server
+```
+
+---
+
+*For questions or suggestions, please open an issue.*
+