一、AGENTS.md 是什么

AGENTS.md 是 OpenCode 的自定义指令文件，类似于 Cursor 的 Rules。它的内容会在每次 LLM 请求时被注入到 System Prompt 中，用来约束 AI 的行为，使其适配你的项目。

核心作用：

• 弥补 AI 对工程全局缺乏感知的问题
• 把泛化的 LLM 约束为特定的技术领域专家
• 提供项目结构、编码规范、常用命令等上下文
• 约束 AI 的操作边界（哪些文件能改、哪些不能动）

二、创建方式

自动生成（推荐）

在 OpenCode 中运行 /init 命令：

• 扫描项目关键文件（package.json / go.mod 等）
• 识别项目特征，自动生成 AGENTS.md
• 如果已有 AGENTS.md，会在原有基础上补充改进

手动创建

直接在项目根目录创建 AGENTS.md 文件，用 Markdown 格式编写。

三、文件层级与作用域

OpenCode 支持多个位置的 AGENTS.md，分三层：

层级	路径	作用域	用途
全局	~/.config/opencode/AGENTS.md	所有项目	个人通用偏好，不提交 Git
项目	项目根目录/AGENTS.md	当前项目及子目录	项目总规范，提交 Git 共享团队
子目录	子目录/AGENTS.md	该子目录及其子目录	模块专属规范

加载机制

• 启动时从当前目录向上遍历查找 AGENTS.md
• 子目录规则只在该目录下的文件被操作时生效
• 各层叠加合并，冲突时更具体的层级优先

如果没有 AGENTS.md，OpenCode 会回退查找：

• 项目级：CLAUDE.md（项目根目录）
• 全局级：~/.claude/CLAUDE.md
• Skills：~/.claude/skills/

禁用兼容模式：

export OPENCODE_DISABLE_CLAUDE_CODE=1        # 完全禁用 .claude 支持
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1  # 只禁用 ~/.claude/CLAUDE.md
export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1  # 只禁用 .claude/skills

四、优先级规则

查找顺序：
本地文件 — 从当前目录向上遍历（AGENTS.md > CLAUDE.md）
全局文件 — ~/.config/opencode/AGENTS.md
Claude Code 文件 — ~/.claude/CLAUDE.md（未禁用时）
同层级：AGENTS.md 优先于 CLAUDE.md
跨层级：项目级优先于全局级，子目录优先于根目录

五、AGENTS.md 写什么

推荐结构

# 项目名称

项目简介（1-2句话说清项目是什么）

## 项目结构
- `src/` - 主要源码
- `packages/` - 子包
- `infra/` - 基础设施

## 技术栈
- 语言：TypeScript
- 框架：Vue3
- 构建：Vite
- 测试：Vitest

## 编码规范
- 变量/函数：camelCase
- 组件/类型：PascalCase
- 常量：UPPER_SNAKE_CASE
- 缩进：2 空格
- 禁止 any 类型

## 常用命令
- 开发：`bun run dev`
- 测试：`bun test`
- 构建：`bun run build`
- 代码检查：`bun run lint`

## 操作边界
- 允许修改：`src/views/`、`src/components/`
- 禁止修改：`src/main.ts`、`package.json`
- 所有 API 密钥必须放 .env 文件

## 注意事项
- 数据库操作必须通过 ORM，禁止裸 SQL
- 错误必须日志记录，返回给用户的消息要脱敏
 

篇幅建议

配置	行数	适合场景
最小	~60 行	小项目，只需项目概览+技术栈+常用命令
标准	~150 行	中等项目，加上目录结构+编码规范
详细	~300 行	大项目，加上架构模式+注意事项

超过 300 行建议拆分，用 opencode.json 的 instructions 引用外部文件。

六、引用其他 .md 文件的两种方式

方式一：opencode.json 的 instructions 字段（推荐）

在项目根目录创建 opencode.json：

支持 GLOB 模式：

模式	匹配
docs/**/*.md	docs 目录下所有 md 文件
.opencode/rules/*.md	rules 目录下的 md 文件
packages/*/AGENTS.md	各子包的 AGENTS.md
**/*.md	项目全部 md 文件（慎用，会占大量上下文）

支持远程 URL：

• 仅支持 HTTPS
• 5 秒超时
• 需要网络连接

所有 instructions 文件的内容会和 AGENTS.md 合并注入。

方式二：AGENTS.md 中写引导指令

对比

	opencode.json	AGENTS.md 引导
加载时机	启动时全部加载	按需懒加载
上下文占用	全部占	只占当前任务相关
适合	规则数量少、总量小	规则多、大部分场景不需要
维护	改 JSON 配置	改 Markdown 文本

七、分层 AGENTS.md 实践（Monorepo 示例）

根目录 AGENTS.md — 放"不管改哪个包都必须遵守"的规则：

子目录 AGENTS.md — 只放该模块特有的差异：

原则：
根目录说了的，子目录不重复
子目录只补充差异
冲突时子目录优先