# Guides — 跨模块开发指南

> 本文件定义跨前后端的通用指南。适用于所有模块和子 Agent。
> 按项目实际情况修改内容。

## 架构原则

- 单一职责: 每个模块/函数只做一件事
- 依赖方向: 高层依赖低层，禁止循环
- 接口优先: 跨模块通过接口通信，不直接访问内部

## Git 提交规范

- 格式: Conventional Commits (`feat:`, `fix:`, `refactor:`, `docs:`, `chore:`)
- 原子提交: 一个逻辑变更一个 commit
- 不提交: `.env`, `node_modules/`, 编译产物, IDE 配置

## 代码审查清单

- [ ] 变更是否符合需求？
- [ ] 是否有测试覆盖？
- [ ] 是否引入安全风险？
- [ ] 是否有性能影响？
- [ ] 命名是否清晰？

## 文档要求

- 公共 API 必须有类型注释
- 复杂逻辑加注释说明 WHY（不是 WHAT）
- 新模块需要 README