OpenCode 规则（AGENTS.md）
在 OpenCode 中，规则（Rules）是控制 AI 行为的核心机制。
我们可以通过 AGENTS.md 文件，为 OpenCode 提供自定义指令，让它按照你的项目规范进行开发。
工具决定 AI 能做什么，AGENTS.md 决定 AI 应该怎么做。
AGENTS.md = 给 AI 制定团队开发规范。
一、什么是 AGENTS.md
AGENTS.md 是一个规则文件，用于：
- 定义项目结构
- 约束代码风格
- 规范开发流程
- 指导 AI 如何执行任务
这些内容会被加入到 LLM 的上下文中。
效果：
- AI 更懂你的项目
- 生成的代码更符合规范
- 减少反复修改
二、快速初始化
在 OpenCode 中运行：
bash
/init该命令会：
- 扫描你的项目结构
- 分析代码组织方式
- 自动生成 AGENTS.md
建议：
- 将 AGENTS.md 提交到 Git
- 作为团队统一规范
三、示例结构
bash
# 项目说明
这是一个基于 TypeScript 的 monorepo 项目。
## 项目结构
- packages/ 核心模块
- infra/ 基础设施
- web/ 前端应用
## 代码规范
- 使用 TypeScript 严格模式
- 公共代码放在 packages/core
- 所有函数必须添加注释
## 开发约定
- 使用 workspace 方式引用模块
- API 必须统一错误处理本质：把团队规范"写给 AI 看"
四、规则的作用范围
1、项目级规则
路径：
bash
./AGENTS.md作用：
- 仅当前项目生效
- 团队共享
2、全局规则
路径：
bash
~/.config/opencode/AGENTS.md作用：
- 对所有项目生效
- 个人使用
建议用途：
- 个人编码习惯
- 输出风格控制
五、Claude Code 兼容性
OpenCode 兼容 Claude Code 的规则体系：
- 项目规则：CLAUDE.md
- 全局规则：~/.claude/CLAUDE.md
- 技能目录：~/.claude/skills/
如果不想使用，可以关闭：
bash
export OPENCODE_DISABLE_CLAUDE_CODE=1六、规则加载优先级（重要）
OpenCode 启动时按以下顺序加载：
- 当前目录向上查找 AGENTS.md
- 如果没有 → 查找 CLAUDE.md
- 全局规则 ~/.config/opencode/AGENTS.md
- Claude 全局规则 ~/.claude/CLAUDE.md
关键点：
- AGENTS.md 优先级最高
- 同级只会使用第一个匹配文件
七、扩展规则（instructions）
可以在 opencode.json 中加载额外规则文件：
json
{
"instructions": [
"CONTRIBUTING.md",
"docs/guidelines.md",
".cursor/rules/*.md"
]
}优点：
- 复用已有文档
- 避免重复维护
支持远程规则
json
{
"instructions": [
"https://raw.githubusercontent.com/xxx/rules/main/style.md"
]
}说明：
- 支持 URL 加载
- 超时：5 秒
八、模块化规则（高级）
推荐方式（使用 instructions）
json
{
"instructions": [
"docs/dev.md",
"test/rules.md",
"packages/*/AGENTS.md"
]
}适合：
- monorepo
- 大型项目
方式二：在 AGENTS.md 中手动引用
bash
# 规则加载说明
当遇到 @xxx 文件时，请使用 read 工具加载。
- 不要一次性加载全部文件
- 按需加载
- 加载后必须遵守示例：
bash
TypeScript 规范：@docs/typescript.md
React 规范：@docs/react.md
API 规范：@docs/api.md实现"按需加载规则"
九、最佳实践（重点）
1、规则要具体
❌ 不要写：
bash
代码要规范✅ 应该写：
bash
所有函数必须添加 JSDoc 注释2、规则要可执行
AI 只能执行明确规则，而不是抽象描述。
3、不要写太长
建议：
- 核心规则写在 AGENTS.md
- 详细规则拆到 instructions 文件
4、团队统一维护
- 纳入 Git 管理
- 作为开发规范的一部分
AI 思考中...