# AGENTS.md — 开发规范 / Development Guidelines

> 本文件为所有 AI 编码助手（Claude Code、pi、Cursor 等）提供统一的开发指导。
> This file provides unified development guidelines for all AI coding assistants.

**最后更新 / Last Updated**: 2026-06-11

---

## 1. 语言 / Language

**Always respond in Chinese (中文).** Use the user's language for all conversations and explanations. Code, commands, and technical terms can remain in English.

始终使用中文回复。代码、命令和技术术语可以保留英文。

---

## 2. 代码风格 / Code Style

### 2.1 基本原则 / Basic Principles

| 规则 / Rule | 说明 / Description |
|-----------|-------------------|
| 遵循现有风格 | 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 最佳实践 / Rust Best Practices

| 规则 / Rule | 说明 / Description |
|-----------|-------------------|
| 错误传播 | Use `?` operator; never use `unwrap()` in non-test code |
| `unsafe` | Avoid; if necessary, add `// SAFETY:` comment |
| `clone()` | Minimize usage; prefer references |
| 魔法数字 | No magic numbers; use named constants |
| 硬编码字符串 | No hardcoded strings; use enums or constants |

### 2.3 导入规范 / Import Guidelines

```rust
// 标准库 → 第三方 crate → 本地模块
use std::collections::HashMap;

use serde::{Deserialize, Serialize};

use crate::error::{AppError, AppResult};
```

---

## 3. 禁止模式 / Forbidden Patterns

以下代码模式在项目中严格禁止：

| 禁止项 / Forbidden | 说明 / Reason |
|-------------------|--------------|
| `// ── xxxx ──────────` | 禁止使用此类分隔线注释 |
| `unwrap()` / `expect()` (非测试) | 使用 `?` 或安全替代 |
| `panic!()` / `unreachable!()` | 使用错误类型替代 |
| 未处理的 `todo!()` | 必须有对应的 issue 追踪 |
| 注释掉的代码 | 使用 Git 历史追溯 |
| 过深嵌套 (≥4层) | 使用 early return 扁平化逻辑 |
| 过长函数 (>50行) | 拆分为更小的函数 |
| 魔法数字 | 使用 `const` 定义命名常量 |
| 硬编码字符串 | 使用枚举或常量 |

---

## 4. 错误处理 / Error Handling

### 4.1 错误处理原则

| 原则 / Principle | 说明 / Description |
|----------------|-------------------|
| 显式处理 | Handle all errors explicitly; no silent failures |
| 用户友好 | Internal errors are logged; user-facing messages should be helpful |
| 错误上下文 | Use `.context()` or `.map_err()` to add context |

### 4.2 错误日志格式

```rust
tracing::error!(
    error = %err,
    operation = "operation_name",
    "Failed to perform operation"
);
```

---

## 5. 安全规范 / Security

| 规则 / Rule | 说明 / Description |
|-----------|-------------------|
| 密钥管理 | Never hardcode secrets or API keys |
| 输入验证 | Always validate and sanitize user input |
| SMTP 安全 | Use TLS for SMTP connections |
| 密码安全 | Use proper hashing (Argon2, bcrypt) |

---

## 6. 工作流程 / Workflow

### 6.1 开发流程

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 助手工作规范

| 规则 / Rule | 说明 / Description |
|-----------|-------------------|
| 先读后写 | 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 check
cargo test                       # 运行测试 / Run tests
cargo clippy                     # Lint 检查 / Lint checks
cargo fmt                        # 格式化 / Format code
```

---

## 7. Git 规范 / Git Workflow

### 7.1 提交信息格式

```
<type>(<scope>): <subject>

[optional body]

[optional footer]
```

| Type | 说明 / Description |
|------|-------------------|
| `feat` | 新功能 / New feature |
| `fix` | Bug 修复 / Bug fix |
| `refactor` | 重构 / Code refactoring |
| `docs` | 文档 / Documentation |
| `test` | 测试 / Tests |
| `chore` | 构建/工具 / Build/tooling |

### 7.2 提交原则

| 原则 / Principle | 说明 / Description |
|----------------|-------------------|
| 原子提交 | Each commit should address one concern |
| 完整性 | Each commit should leave the codebase in a working state |
| 禁止强制推送 | Never force push to main branch |

---

## 附录 / Appendix

### 项目架构速查 / Quick Architecture Reference

```
emailks — 邮件发送服务 / Email Sending Service

email.rs       → 邮件发送核心 / Email sending core
server.rs      → gRPC 服务 / gRPC server
queue.rs       → 邮件队化 / Email queue
status.rs      → 状态管理 / Status management
error.rs       → 错误类型 / Error types
config.rs      → 配置管理 / Configuration
proto/         → Protobuf 定义 / Protobuf definitions
```

---

*This document is maintained by the development team. For questions or suggestions, please open an issue.*