mailks/AGENTS.md

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

// 标准库 → 第三方 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 错误日志格式

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

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.