zhenyi
162 lines
3.5 KiB
Markdown
162 lines
3.5 KiB
Markdown
# 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.*
|
|
|