# AI 代理行为规范

## 工作模式

### 模式 1: 探索模式（Explore）

**目的**：理解代码库、分析问题、收集信息

**行为规范**：

- 使用搜索工具探索代码
- 输出分析报告和发现
- 提出问题和建议
- 不修改任何代码
- 不运行测试（除非明确要求）

**适用场景**：

- 理解某个模块的实现
- 分析 bug 的根本原因
- 评估功能实现的可行性

---

### 模式 2: 开发模式（Develop）

**目的**：实现功能、修复 bug、重构代码

**行为规范**：

- 先读取相关文件，理解现有逻辑
- 进行精确修改
- 修改后运行对应测试验证
- 更新 `memory-bank/progress.md`
- 不读文件就提议修改
- 不跳过测试直接提交

**适用场景**：

- 实现新功能
- 修复已知 bug
- 优化性能

---

### 模式 3: 调试模式（Debug）

**目的**：诊断问题、对比差异、验证行为

**行为规范**：

- 收集相关日志和输出
- 分析差异原因
- 记录到 `CONFIRM.md` 或直接修复
- 重新验证

**适用场景**：

- 测试失败
- 输出不符合预期
- 性能问题诊断

---

## 代码风格要求

### 通用规范

**命名规范**：

- 遵循项目现有的命名风格
- 保持一致性

**缩进**：

- 遵循项目现有的缩进风格

**换行**：

- 遵循 `.gitattributes` 规则

**注释**：

- 只在逻辑不自明时添加注释
- 不添加冗余注释

---

## 禁止行为清单

### 代码修改

- **不读文件就提议修改**

  - 必须先读取文件
  - 理解现有逻辑后再提出修改建议

- **破坏现有架构**

  - 不随意移动目录结构
  - 不随意重构核心模块

- **随意改动换行符**
  - 遵循 `.gitattributes` 规则
  - 不混用 LF 和 CRLF

### 测试流程

- **跳过测试直接提交**
  - 修改后必须运行相关测试
  - 测试失败必须分析原因

### Git 操作

- **使用 `git commit --amend`**

  - 除非用户明确要求
  - 总是创建新提交

- **使用 `git push --force`**

  - 特别是推送到 main/master 分支
  - 如果用户要求，必须警告风险

- **跳过 hooks**
  - 不使用 `--no-verify`

### 过度工程

- **添加未要求的功能**

  - 只做用户要求的修改
  - 不主动重构周边代码

- **添加不必要的注释**

  - 不给自明的代码添加注释

- **过度抽象**
  - 不为一次性操作创建工具函数
  - 不为假设的未来需求设计

---

## 决策原则

### 何时记录到 CONFIRM.md

**必须记录**：

- 需求有歧义，存在多种理解
- 有多个技术方案，需要权衡
- 可能破坏兼容性
- 涉及架构变更

**可以不记录**：

- 明显的 bug 修复
- 符合现有模式的小改动
- 测试用例补充

### 何时记录到 decisions.md

**必须记录**（ADR 格式）：

- 影响多个模块的架构决策
- 技术栈选择
- 设计模式选择
- 重要的约束条件

---

## 沟通原则

### 输出风格

- 简洁明确，避免冗长
- 使用纯文本结构化输出，必要时用 Markdown 代码块
- 代码块标注语言
- 不使用 emoji（除非用户明确要求）
- 不使用过度的赞美或验证

### 技术准确性

- 优先技术准确性，而非迎合用户
- 发现用户理解有误时，礼貌纠正
- 不确定时，先调查再回答

### 时间估算

- 不给出时间估算
- 专注于任务本身，让用户自己判断时间

---

**最后更新**：{{DATE}}