OpenCode: OpenCode规则（AGENTS.md）
最后更新：2026-08-31
AGENTS.md 是 OpenCode 的项目级规则文件，定义 AI 在当前项目中的行为约束。
1. 你将学到
- AGENTS.md 的作用与定位
- 文件创建方式
- 规则编写方法
- 最佳实践
2. AGENTS.md 是什么
AGENTS.md 是放置在项目根目录的 Markdown 文件，AI 在工作时会自动读取并遵循其中的规则。
核心定位： 给 AI 的项目说明书和行为规范。
| 特点 | 说明 |
|---|---|
| 位置 | 项目根目录 |
| 格式 | Markdown |
| 作用范围 | 仅当前项目 |
| 自动加载 | AI 开始工作时自动读取 |
3. 创建 AGENTS.md
(1) TUI 命令创建
TEXT
📖 仅展示
/init
OpenCode 会根据项目结构自动生成基础规则。
(2) 手动创建
在项目根目录创建 AGENTS.md 文件，编写自定义规则。
4. 规则编写方法
(1) 基本结构
MARKDOWN
# Project Rules
## 编码规范
- 使用 TypeScript 严格模式
- 遵循 ESLint 配置
- 函数最大长度 50 行
## 测试要求
- 所有新函数必须编写单元测试
- 测试覆盖率不低于 80%
## 提交规范
- 使用 Conventional Commits 格式
- 每次提交只做一件事
(2) 规则分类
| 类别 | 示例 |
|---|---|
| 编码规范 | 代码风格、命名规则、类型要求 |
| 架构约束 | 目录结构、模块划分、依赖方向 |
| 测试要求 | 覆盖率、测试类型、测试命名 |
| 提交规范 | Commit 格式、分支命名、PR 规则 |
| 安全规则 | 禁止硬编码密钥、输入验证要求 |
| 业务逻辑 | 领域规则、数据处理流程 |
5. 规则示例
(1) 前端项目
MARKDOWN
# Frontend Project Rules
## 代码风格
- 使用 React 函数组件 + Hooks
- 使用 Tailwind CSS 进行样式编写
- 组件文件使用 PascalCase 命名
- 工具函数文件使用 camelCase 命名
## 状态管理
- 全局状态使用 Zustand
- 组件本地状态使用 useState
- 异步操作使用 React Query
## 测试
- 使用 Vitest + Testing Library
- 每个组件至少一个快照测试
- 关键业务逻辑需要集成测试
(2) 后端项目
MARKDOWN
# Backend Project Rules
## API 规范
- RESTful API 设计
- 统一使用 JSON 响应格式
- 错误响应包含错误码和消息
## 数据库
- 使用 TypeORM 进行数据库操作
- 所有查询必须使用参数化
- 数据库迁移必须可回滚
## 安全
- 所有接口需要 JWT 认证
- 密码使用 bcrypt 加密
- 敏感数据不记录日志
6. 最佳实践
(1) 规则要具体
MARKDOWN
# ❌ 不好的规则
写好代码
# ✅ 好的规则
- 函数最大长度 50 行
- 圈复杂度不超过 10
- 所有公共函数需要 JSDoc 注释
(2) 规则要可执行
MARKDOWN
# ❌ 不好的规则
注意安全
# ✅ 好的规则
- 禁止硬编码 API Key
- SQL 查询必须参数化
- 用户输入必须验证和消毒
(3) 规则要分优先级
MARKDOWN
# 必须遵守
- 禁止提交 .env 文件
- 所有 API 需要 JWT 认证
# 推荐遵守
- 函数不超过 50 行
- 使用 TypeScript 类型定义
# 可选
- 添加代码注释
- 编写集成测试
(4) 与团队共享
- AGENTS.md 应该纳入 Git 版本控制
- 团队成员共同维护规则
- 定期 Review 和更新规则
7. AGENTS.md vs opencode.json
| 维度 | AGENTS.md | opencode.json |
|---|---|---|
| 格式 | Markdown | JSON |
| 读者 | AI + 人类 | OpenCode 程序 |
| 内容 | 行为规则、编码规范 | 配置参数、工具权限 |
| 作用 | 约束 AI 行为 | 控制程序行为 |
| 优先级 | 建议性 | 强制性 |
两者互补：AGENTS.md 告诉 AI "应该怎么做"，opencode.json 控制程序 "能做什么"。
❓ 常见问题
Q AGENTS.md 规则 AI 一定会遵守吗？
A 不一定。AGENTS.md 是建议性的，AI 会尽量遵守但不是强制的。需要强制执行的规则应在 opencode.json 中用 permission 配置。
Q AGENTS.md 放在子目录中有效吗？
A 只在项目根目录有效。AI 只读取根目录的 AGENTS.md。
Q Alice 的项目 AGENTS.md 有 100 行规则，Bob 的只有 5 行，谁的效果更好？
A 不一定越多越好。规则要具体、可执行、分优先级。5 条精确的规则可能比 100 条模糊的规则更有效。
📖 小节
- AGENTS.md 是给 AI 的项目规则文件
- 使用
/init或手动创建 - 规则要具体、可执行、分优先级
- 与 opencode.json 互补：前者约束行为，后者控制权限
- 纳入 Git 版本控制，团队共同维护
📝 作业
-
基础题：为你的项目创建 AGENTS.md，定义至少 5 条编码规范。
-
进阶题：编写 AGENTS.md 定义完整的开发流程规则（编码→测试→提交），并让 OpenCode 按规则执行一个任务。
-
挑战题：对比有无 AGENTS.md 时 OpenCode 的输出差异，量化规则对 AI 行为的影响。
