# 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.*