中文
文档
规则

规则

为 opencode 设置自定义指令。

你可以通过创建一个 AGENTS.md 文件来为 opencode 提供自定义指令。这类似于 Cursor 的规则。它包含的指令会被纳入 LLM 的上下文,从而为你的特定项目定制其行为。


初始化

要创建一个新的 AGENTS.md 文件,你可以在 opencode 中运行 /init 命令。

提示: 你应当将项目的 AGENTS.md 文件提交到 Git。

/init 会扫描你仓库中的重要文件,在代码库无法回答某些问题时可能会提出几个有针对性的问题,然后创建或更新 AGENTS.md,给出简洁的项目专属指引。

它聚焦于未来的 agent 会话最可能需要的内容:

  • 构建、lint 和测试命令
  • 命令的执行顺序,以及在重要时的针对性验证步骤
  • 无法仅凭文件名看出的架构和仓库结构
  • 项目专属的约定、设置上的特殊之处和操作上的坑
  • 对现有指令来源(如 Cursor 或 Copilot 规则)的引用

如果你已经有了 AGENTS.md/init 会就地改进它,而不是盲目替换。


示例

你也可以手动创建这个文件。下面是一个示例,展示你可以在 AGENTS.md 文件中放入哪些内容。

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 也支持从多个位置读取 AGENTS.md 文件。它们各自服务于不同的目的。

项目

AGENTS.md 放在你的项目根目录中,用于项目专属规则。这些规则仅在你于该目录或其子目录中工作时生效。

全局

你也可以在 ~/.config/opencode/AGENTS.md 文件中设置全局规则。它会应用于所有 opencode 会话。

由于该文件不会被提交到 Git,也不会与你的团队共享,我们建议用它来指定 LLM 应当遵循的任何个人规则。

Claude Code 兼容性

对于从 Claude Code 迁移过来的用户,OpenCode 支持将 Claude Code 的文件约定作为回退:

  • 项目规则:你项目目录中的 CLAUDE.md(在不存在 AGENTS.md 时使用)
  • 全局规则~/.claude/CLAUDE.md(在不存在 ~/.config/opencode/AGENTS.md 时使用)
  • 技能(Skills)~/.claude/skills/ — 详见 Agent 技能

要禁用 Claude Code 兼容性,请设置以下环境变量之一:

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.mdCLAUDE.md
  2. 全局文件,位于 ~/.config/opencode/AGENTS.md
  3. Claude Code 文件,位于 ~/.claude/CLAUDE.md(除非已禁用)

在每个类别中,第一个匹配到的文件胜出。例如,如果你同时拥有 AGENTS.mdCLAUDE.md,则只会使用 AGENTS.md。同理,~/.config/opencode/AGENTS.md 的优先级高于 ~/.claude/CLAUDE.md


自定义指令

你可以在你的 opencode.json 或全局的 ~/.config/opencode/opencode.json 中指定自定义指令文件。这让你和你的团队能够复用现有规则,而不必把它们重复抄录到 AGENTS.md 中。

示例:

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

你也可以使用远程 URL 从网络加载指令。

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

远程指令的抓取有 5 秒超时。

所有指令文件都会与你的 AGENTS.md 文件合并。


引用外部文件

虽然 opencode 不会自动解析 AGENTS.md 中的文件引用,但你可以通过两种方式实现类似的功能。

使用 opencode.json

推荐的方式是使用 opencode.json 中的 instructions 字段:

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

在 AGENTS.md 中手动给出指令

你可以通过在 AGENTS.md 中提供明确的指令,来教会 opencode 读取外部文件。这是一个实用的示例:

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.

这种方式让你可以:

  • 创建模块化、可复用的规则文件
  • 通过符号链接或 git 子模块在多个项目间共享规则
  • 在引用详细指南的同时保持 AGENTS.md 简洁
  • 确保 opencode 仅在特定任务需要时才加载文件

提示: 对于 monorepo 或拥有共享标准的项目,使用带 glob 模式的 opencode.json(如 packages/*/AGENTS.md)比手动给出指令更易于维护。