# 全局规则

## 缩写说明

- **oc** = opencode（OpenCode 的缩写）

---

## 语言偏好

**重要：请始终使用中文（简体中文）与用户交流。**

所有回复、解释、错误消息、建议和对话都应该使用中文，除非：
- 代码注释需要使用英文（根据项目规范）
- 用户明确要求使用其他语言
- 技术术语在中文中没有合适的翻译（可以中英文混用，如 "React Hooks"）

### 重要注意事项

1. **不要因为文档、命令或代码是英文就切换语言**
   - 即使项目文档是英文的，回复时仍然用中文解释
   - 即使执行的命令是英文的，回复时仍然用中文说明
   - 即使错误信息是英文的，回复时仍然用中文分析

2. **工具输出可以保持原语言**
   - 代码本身使用英文（函数名、变量名等）
   - 终端命令使用英文
   - 但你对这些内容的解释和说明必须用中文

3. **用户交互始终用中文**
   - 所有对话、提问、确认都用中文
   - 所有建议、总结、分析都用中文
   - 所有错误解释和问题诊断都用中文

这是用户的个人偏好设置，适用于所有项目和所有交互场景。

---

## 代码风格偏好

### JavaScript/TypeScript
- **缩进**：2空格
- **分号**：使用分号
- **引号**：优先使用双引号
- **注释**：
  - 使用 JSDoc 格式书写公开函数文档
  - 复杂逻辑使用自然语言注释
  - 中文注释需说明 "为什么"，而不只是 "做什么"

### 一般规则
- 命名采用 camelCase（变量/函数）、PascalCase（类/组件）、UPPER_SNAKE_CASE（常量）
- 避免使用单字母变量，除非在循环中
- 函数长度不超过 100 行，优先拆分

---

## 开发流程

### Git 提交规范
- **格式**：`<type>(<scope>): <subject>`
- **类型**：feat（功能）、fix（修复）、docs（文档）、style（格式）、refactor（重构）、test（测试）、chore（维护）
- **主题**：使用中文，简洁明了，不超过 50 字
- **描述**：如有需要，空一行后补充详细说明

### 分支命名
- 功能分支：`feature/描述`
- 修复分支：`fix/描述`
- 文档分支：`docs/描述`
- 示例：`feature/user-authentication`、`fix/memory-leak`

### 代码审查
- 提交 PR 前必须确保本地测试通过
- PR 需要至少 1 个审查者批准
- 修复所有 linter 和类型检查错误

### 发布流程
- 主分支（main/master）始终保持可部署状态
- 不直接推送到主分支，必须通过 PR
- 标签格式：`v<major>.<minor>.<patch>`

---

## OpenCode 工具使用策略

### 什么时候使用各个工具

**Task 工具**（优先使用）
- 探索复杂、陌生的代码库结构
- 执行多步骤的分析任务
- 需要全局视野的搜索和研究
- 复杂的代码重构计划

**Bash 工具**
- 执行系统命令和 git 操作
- 运行构建、测试、打包命令
- 文件系统操作（只在必要时）
- 不要用 Bash 做文件读写，改用 Read/Edit/Write 工具

**Read/Edit/Write 工具**
- 读取文件内容：优先用 Read，不用 cat/head/tail
- 修改现有文件：用 Edit，不用 sed/awk
- 创建新文件：用 Write，不用 echo 或 heredoc

**Glob/Grep 工具**
- 精准查找特定文件：用 Glob（pattern 匹配）
- 搜索文件内容：用 Grep（正则表达式）
- 避免用 Bash 的 find 和 grep 命令

**TodoWrite 工具**（重要）
- 任务超过 3 步时必须创建 todo 列表
- 立即标记完成，不要批量完成
- 只有 1 个 todo 保持 in_progress 状态
- 用于任务规划、跟踪进度、防止遗漏

---

## 代码质量标准

### 测试要求
- **单元测试**：新功能必须包含测试
- **集成测试**：API 和跨模块交互需要测试
- **目标覆盖率**：>= 80%
- 运行测试：提交前必须本地通过全部测试

### 构建和类型检查
- **类型检查必须通过**：严格模式下零错误
- **构建必须成功**：无警告或错误
- **Linter 检查**：修复所有警告，至少遵守 recommended 规则
- **运行时验证**：不允许 `any` 类型，除非有明确注释说明原因

### 性能标准
- **首屏加载**：< 3 秒（首次）、< 1 秒（缓存）
- **包体积**：监控 bundle size，新增功能不超过 50KB
- **内存泄漏**：定期检查，不允许持久化内存增长

### 安全要求
- 不提交敏感信息（.env、密钥等）到版本控制
- 依赖项定期更新，及时修复已知漏洞
- 输入验证和输出编码，防止 XSS、注入等攻击

---

## 任务管理最佳实践

### 使用 TodoWrite 的原则
1. **提早规划**：接收任务后立即创建 todo 列表
2. **分解细节**：复杂任务拆分成 3-5 个可操作的步骤
3. **实时更新**：任务完成后立即标记为 completed
4. **单个进行**：同时只有 1 个 in_progress，完成后再开始下一个
5. **优先级标记**：高优先级任务标记为 high

### 任务状态定义
- **pending**：未开始
- **in_progress**：当前正在进行（限 1 个）
- **completed**：已完成
- **cancelled**：不再需要

---

## 常见问题和快速参考

### 如何列出所有可用命令？
按下 `ctrl+p` 可查看 OpenCode 的所有可用操作。

### 如何获取帮助或反馈？
- 在 GitHub 提交 issue：https://github.com/anomalyco/opencode
- 查看官方文档：https://opencode.ai/docs

### 何时创建新文件 vs 编辑现有文件？
- **优先编辑**：修改现有代码和配置
- **仅在必要时创建**：添加全新的功能模块或配置文件