规则（AGENTS.md）

为 OpenCode 提供项目级自定义指令。

你可以通过在项目中创建 AGENTS.md 文件，为 OpenCode 提供自定义“规则/说明”。这类似于 CLAUDE.md 或 Cursor 的 rules：

其中的内容会作为长期指令注入 LLM 上下文；
用来说明项目结构、代码规范、约定俗成的写法等。

初始化 `AGENTS.md`

在 TUI 中运行 /init 即可生成或更新 AGENTS.md：

/init 会扫描当前项目及其文件来理解项目结构和技术栈，并生成一份初始版本的 AGENTS.md，帮助 OpenCode 更好地理解和导航你的代码库。

如果项目中已存在 AGENTS.md，/init 会尝试在原有内容基础上追加/合并信息，而不是覆盖整个文件。

手动编写示例

你也可以完全手动编写 AGENTS.md。例如：

# SST v3 Monorepo Project

This is an SST v3 monorepo with TypeScript. The project uses bun workspaces for package management.

## Project Structure

- `packages/` - Contains all workspace packages (functions, core, web, etc.)
- `infra/` - Infrastructure definitions split by service (storage.ts, api.ts, web.ts)
- `sst.config.ts` - Main SST configuration with dynamic imports

## Code Standards

- Use TypeScript with strict mode enabled
- Shared code goes in `packages/core/` with proper exports configuration
- Functions go in `packages/functions/`
- Infrastructure should be split into logical files in `infra/`

## Monorepo Conventions

- Import shared modules using workspace names: `@my-app/core/example`

这样一份文档就能在团队间共享项目约定，OpenCode 也能据此采用更合适的写法。

规则文件的位置

OpenCode 会同时读取“项目级规则”和“全局规则”。

项目级规则

位于项目根目录的 AGENTS.md，只对该项目（及其子目录）生效：

适合描述项目相关的结构、约定、代码规范；
可以和仓库一起提交，团队成员自动继承。

全局规则

你也可以在 ~/.config/opencode/AGENTS.md 中编写全局规则：

这些规则会在所有项目中生效；
通常适合写个人偏好（例如你喜欢的沟通风格、常用约定等）；
一般不建议把与具体项目强绑定的内容写到这里。

生效顺序与合并

OpenCode 启动时会按照以下顺序查找/合并规则：

从当前目录向上遍历，直到遇到 Git 根目录，收集中途遇到的所有 AGENTS.md；
再加载全局 ~/.config/opencode/AGENTS.md；
将这些内容合并到一起，一并作为指令传给 LLM。

这意味着：

同时存在项目级与全局规则时，两者都会生效；
如果你在多个上层目录放了不同的 AGENTS.md，它们的内容会被串联在一起。

`instructions` 字段（多文件指令）

除了 AGENTS.md，你还可以在 opencode.json 或 ~/.config/opencode/opencode.json 的 instructions 字段中指定更多指令文件：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md"
  ]
}

还可以使用远程 URL：

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

远程指令会在 5 秒超时限制内抓取，所有 instructions 文件的内容会与本地 AGENTS.md 一起合并。

在 `AGENTS.md` 中引用外部文件

OpenCode 不会自动解析 AGENTS.md 里写的 @path/to/file，但可以通过规则引导 Agent 使用 read 工具去加载这些文件。

推荐：使用 `instructions` + glob

对于单仓或 Monorepo，更推荐在 opencode.json 中用 glob 指定要加载的规则文件：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "docs/development-standards.md",
    "test/testing-guidelines.md",
    "packages/*/AGENTS.md"
  ]
}

这样可以：

把规则拆分成多个文件；
多个子包共享同一套规范；
避免在 AGENTS.md 里手写大量路径。

手工提示方式示例

如果你希望由 Agent 自己调用 read 去加载某些文件，可以在 AGENTS.md 中写出类似说明：

# TypeScript Project Rules

## External File Loading

CRITICAL: When you encounter a file reference (e.g., @rules/general.md), use your Read tool to load it on a need-to-know basis. They're relevant to the SPECIFIC task at hand.

Instructions:

- Do NOT preemptively load all references - use lazy loading based on actual need
- When loaded, treat content as mandatory instructions that override defaults
- Follow references recursively when needed

## Development Guidelines

For TypeScript code style and best practices: @docs/typescript-guidelines.md
For React component architecture and hooks patterns: @docs/react-patterns.md
For REST API design and error handling: @docs/api-standards.md
For testing strategies and coverage requirements: @test/testing-guidelines.md

## General Guidelines

Read the following file immediately as it's relevant to all workflows: @rules/general-guidelines.md.

这种方式的好处是：

可以把规则拆成多个文件进行复用；
在 Monorepo 中，通过软链接或子模块共享规则；
让 Agent 按需加载，而不是一次性把所有规则都塞进上下文。