gitks/AGENTS.md

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

// 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

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

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.