OpenCode 通过 AGENTS.md 文件为 AI 提供项目特定的上下文和行为规则，作用类似 Cursor 的 .cursorrules。用 /init 命令自动扫描项目并生成 AGENTS.md，或手动创建。支持项目级（提交到 Git 与团队共享）和全局级（个人偏好）两种规则文件。从 Claude Code 迁移的用户：OpenCode 会自动识别 CLAUDE.md 作为兼容 fallback。

OpenCode Rules（AGENTS.md）

OpenCode 通过 AGENTS.md 文件为 AI 提供项目特定的指令和上下文，类似 Cursor 的 .cursorrules 或 Claude Code 的 CLAUDE.md。

建议将项目的 AGENTS.md 提交到 Git，方便团队成员共享同一套规则。

---

快速创建：/init

用 /init 命令让 OpenCode 自动生成 AGENTS.md：

/init

/init 会扫描仓库中的重要文件，必要时问几个针对性问题，然后创建或更新 AGENTS.md，内容聚焦于 agent 会话最常需要的信息：

• 构建、lint、测试命令
• 有执行顺序要求的关键命令
• 不能从文件名直接看出的架构和目录结构
• 项目特定的约定、配置怪癖和注意事项
• 已有的 Cursor/Copilot 等规则文件引用

已有 AGENTS.md 时，/init 会在原有内容基础上改进，不会直接替换。

快捷键：ctrl+x i

---

AGENTS.md 示例

# SST v3 Monorepo 项目

基于 SST v3 和 TypeScript 的 monorepo，使用 bun workspaces 管理包。

## 项目结构

- `packages/` — 所有 workspace 包（functions、core、web 等）
- `infra/` — 基础设施定义（按服务拆分：storage.ts、api.ts、web.ts）
- `sst.config.ts` — 主 SST 配置（使用动态导入）

## 代码规范

- TypeScript strict 模式
- 共享代码放在 `packages/core/`，配置正确的 exports
- Functions 放在 `packages/functions/`
- 基础设施按逻辑拆分到 `infra/` 下各文件

## Monorepo 约定

- 导入共享模块用 workspace 名称：`@my-app/core/example`

---

规则文件类型

项目级规则

在项目根目录放 AGENTS.md，只对该目录及子目录生效。提交到 Git 可与团队共享。

your-project/
└── AGENTS.md

全局规则

在 ~/.config/opencode/AGENTS.md 存放个人全局规则，对所有 OpenCode 会话生效。

因为不提交到 Git，建议只在这里写个人偏好（如首选的代码风格、个人工作习惯）。

---

Claude Code 兼容性

从 Claude Code 迁移的用户不需要立即重命名文件。OpenCode 会自动识别 Claude Code 的文件约定作为 fallback：

类型	首选文件	Fallback
项目规则	AGENTS.md	CLAUDE.md
全局规则	~/.config/opencode/AGENTS.md	~/.claude/CLAUDE.md
Skills	.opencode/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

---

规则优先级

OpenCode 启动时按以下顺序查找规则文件：

1. 从当前目录向上遍历（AGENTS.md、CLAUDE.md）
2. ~/.config/opencode/AGENTS.md（全局文件）
3. ~/.claude/CLAUDE.md（兼容 fallback，除非禁用）

同类型文件以第一个找到的为准。例如同时存在 AGENTS.md 和 CLAUDE.md 时，只用 AGENTS.md。

---

通过 opencode.json 引用外部文件

除了 AGENTS.md，还可以在 opencode.json 中用 instructions 字段指定额外的规则文件（支持 glob 和远程 URL）：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md",
    "packages/*/AGENTS.md",
    "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"
  ]
}

所有引用的文件与 AGENTS.md 合并后一起加载。远程 URL 请求超时为 5 秒。

Monorepo 推荐做法：用 packages/*/AGENTS.md glob 模式统一加载各子包的规则，比在每个子包手动维护更省事。

---

在 AGENTS.md 中引用外部文件

也可以直接在 AGENTS.md 里写指令，让 OpenCode 在需要时按需读取其他文件：

# TypeScript 项目规则

## 外部文件加载

重要：遇到文件引用（如 @rules/general.md）时，用 Read 工具按需加载。
只在实际需要时加载，不要预先加载所有引用文件。

## 开发规范

TypeScript 代码风格和最佳实践：@docs/typescript-guidelines.md
React 组件架构和 Hooks 模式：@docs/react-patterns.md
REST API 设计和错误处理：@docs/api-standards.md

这种方式适合规则文件很多、希望按需加载的场景。

---

常见问题

Q: AGENTS.md 应该写什么内容？

A: 聚焦在 AI 无法从代码本身推断出的信息：项目特有的构建命令、不直观的目录约定、团队编码规范、已知的坑点。不要写"使用 TypeScript"这种从 tsconfig.json 就能看出来的内容。

Q: 项目 AGENTS.md 和全局 AGENTS.md 会同时生效吗？

A: 是的，两者都会加载并合并。全局规则是个人偏好的基础，项目规则在此基础上叠加项目特定的约定。

Q: 从 Cursor 迁移过来，.cursorrules 文件还能用吗？

A: 不能直接识别，但可以通过 opencode.json 的 instructions 字段引用它：

{ "instructions": [".cursor/rules/*.md"] }

也可以将内容手动迁移到 AGENTS.md。