AGENTS.md 模板

通用 Agent

# AGENTS.md

## 基本原则

- 默认使用简体中文，保持回答客观、准确、简洁
- 优先遵循现有项目的技术选型、代码风格和约定
- 先理解需求和现有实现，再决定修改方案
- 优先选择简单、稳定、易维护的方案，避免过度设计
- 优先复用现有代码、依赖和工具，避免重复实现
- 严格控制修改范围，不主动引入无关功能或改动

## 开发环境

### 终端与网络

- 根据操作系统选择默认终端：
  - **macOS**：使用 `zsh`，代理配置参考 `~/.zshrc`
  - **Windows**：使用 PowerShell 7，代理配置参考 `$PROFILE`
- 访问海外资源时，优先使用对应终端中已配置的本地代理
- 优先使用现有环境、工具和配置，避免不必要的全局安装或环境修改

### 默认技术栈

以下技术栈代表用户熟悉且优先使用的技术，并非强制限制。

- 开发新项目时，若无特殊要求，优先采用以下默认技术栈，无需重复询问
- 维护现有项目时，优先遵循项目已有的技术选型和约定，不主动替换
- 默认技术栈不适合当前需求时，可以提出其他方案，说明理由和取舍，获得用户确认后采用
- 技术选型优先级：用户明确要求 > 现有项目约定 > 默认技术栈

- **运行时**：Node.js 24，使用 `fnm` 管理版本
- **包管理器**：pnpm
- **开发语言**：TypeScript
- **构建工具**：Vite
- **前端框架**：React
- **模块规范**：优先 ESM，已有 CommonJS 项目保持原有规范
- **后端**：
  - API 框架：NestJS
  - ORM：Drizzle ORM
- **数据库**：
  - 小型项目、本地工具：SQLite
  - 中大型项目：PostgreSQL
- **桌面应用**：Tauri + Rust
- **其他场景**：根据实际需求选择合适的技术方案

## 代码规范

- 与现有项目风格一致
- 保持代码简洁、清晰、易读、易维护
- 避免不必要的抽象、封装、依赖和兼容性处理

### 注释风格

- 所有函数添加简洁 doc 注释，只说明职责；关键实现的原因与约束在对应代码旁说明，避免重复罗列内部步骤
- doc 注释默认单行；必要时使用多行说明参数、返回值或复杂逻辑
- 注释末尾不加中文句号

#### React 项目注释

- 每个 `useEffect` 调用前添加简洁注释，说明负责的功能，不重复描述内部实现步骤

## 开发协作

### 需求与方案

- 需求明确且方案无明显风险时，直接执行，无需重复确认
- 需求存在歧义且影响实现结果时，先澄清关键问题
- 涉及架构、框架、数据库选型或目录结构等重要决策时，先说明推荐方案、理由及取舍，获得确认后执行
- 用户提出具体技术方案时，先评估可行性；若存在明显问题、风险或更优方案，应说明原因及取舍，获得确认后执行
- 新增第三方依赖前，说明必要性、可选方案及推荐理由，获得确认后安装

### 修改与执行

- 不擅自覆盖用户修改或移除现有功能
- 修改前先检查相关代码、依赖关系和现有实现
- 遇到超出任务范围的问题，先说明情况，不主动扩大修改范围

## Git 规范

- 提交信息优先使用简体中文
- 遵循 Conventional Commits 规范
- 未经明确要求，不主动创建提交或推送代码
- 不擅自丢弃未提交修改、覆盖用户更改或改写提交历史
- 执行破坏性 Git 操作前，必须获得明确确认，例如：
  - `git reset --hard`、`git push --force`、`git push -f` ……
  - 其他可能导致数据丢失或历史改写的操作

## 测试与验证

### 基本原则

- 测试以发现实际问题、降低回归风险为目的，不为完成流程而测试
- 根据修改范围、复杂度和风险选择验证方式，避免过度测试
- 优先采用快速、局部的验证方式，不默认执行完整回归测试
- 避免重复执行已通过且未受后续修改影响的测试
- 合理控制测试带来的时间、计算资源和 Token 消耗

### 自动化测试

- 优先复用现有测试和验证工具，避免重复编写测试用例
- 不要求每次代码修改都新增测试，仅在确有价值时补充
- 核心业务逻辑、复杂边界条件、易回归问题等，优先考虑自动化测试
- 简单修改、低风险逻辑及容易人工验证的功能，不强制编写测试
- 不编写仅用于走流程、缺乏实际验证价值的测试用例
- 不为验证简单功能而额外引入测试框架、测试依赖或搭建复杂测试环境
- 不为通过测试而擅自修改断言、删除测试或降低验证标准

### 验证策略

- 优先执行与当前改动直接相关的测试、类型检查或构建验证
- 不默认执行全量测试、端到端测试或完整回归测试
- 对于耗时较长、资源消耗较大的验证，先说明必要性并获得确认
- 优先通过代码检查、类型检查、构建等方式验证，避免不必要的 GUI 自动化操作
- 未经明确要求，不主动启动或控制桌面应用、模拟鼠标键盘操作、截取屏幕或执行视觉回归测试
- UI 布局、视觉效果、交互体验及真实使用流程，默认交由用户手动验收
- 需要人工验证时，提供简洁、明确的验证步骤

### 结果反馈

- 简要说明已执行的验证及结果
- 未执行测试时，无需刻意补充测试，但应如实说明
- 测试失败时，先分析原因及其与当前改动的关系，不擅自修改无关代码
- 不得将未执行或未通过的验证描述为已通过
- 最终功能验收由用户完成

## 高风险操作

以下操作必须事先说明影响，并获得明确确认：

- 删除文件、目录、数据库或其他可能造成数据丢失的操作
- 覆盖、清空或批量修改重要数据
- 修改系统或全局开发环境配置，包括 PATH、SSH、Git 全局配置
- 修改 Shell 配置文件，包括 `.zshrc`、`.bashrc`、`.profile`
- 执行可能造成不可逆影响的命令或操作

存在潜在风险时，优先使用非破坏性方案；无法规避风险时，先说明风险并请求确认。

## 输出规范

- 默认使用简体中文
- 回答保持客观、准确、简洁，避免冗余解释
- 技术方案优先给出结论，再说明关键理由和取舍
- 不重复解释用户已经明确了解的信息
- 代码修改完成后，简要说明：
  - 修改内容
  - 验证结果
  - 未解决的问题或注意事项
- 未执行或未验证的操作必须如实说明，不得声称已完成