规则

为 opencode 设置自定义指令。

您可以通过创建 AGENTS.md 文件为 opencode 提供自定义指令。这类似于 Cursor 的规则。它包含将被纳入大型语言模型 (LLM) 上下文的指令，以根据您的特定项目自定义其行为。

初始化

要创建新的 AGENTS.md 文件，您可以在 opencode 中运行 /init 命令。

/init 会扫描您仓库中的重要文件，在代码库无法回答时可能会提出几个有针对性的问题，然后创建或更新 AGENTS.md，提供简洁的项目特定指导。

它侧重于未来代理会话最可能需要的事项

构建、Linter 和测试命令
命令顺序和重要的重点验证步骤
仅凭文件名无法明确的架构和仓库结构
项目特定约定、设置怪癖和操作陷阱
对现有指令源（如 Cursor 或 Copilot 规则）的引用

如果您已经有 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 还支持从多个位置读取 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 则使用）
技能: ~/.claude/skills/ — 详见代理技能获取详细信息

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

export OPENCODE_DISABLE_CLAUDE_CODE=1        # Disable all .claude support
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1 # Disable only ~/.claude/CLAUDE.md
export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # Disable only .claude/skills

优先级

当 opencode 启动时，它会按以下顺序查找规则文件

本地文件 通过从当前目录向上遍历 (AGENTS.md, CLAUDE.md)
全局文件 位于 ~/.config/opencode/AGENTS.md
Claude Code 文件 位于 ~/.claude/CLAUDE.md （除非禁用）

每个类别中第一个匹配的文件优先。例如，如果您同时拥有 AGENTS.md 和 CLAUDE.md，则只使用 AGENTS.md。同样，~/.config/opencode/AGENTS.md 优先于 ~/.claude/CLAUDE.md。

自定义指令

您可以在您的 opencode.json 或全局 ~/.config/opencode/opencode.json 中指定自定义指令文件。这使您和您的团队可以重用现有规则，而无需将它们复制到 AGENTS.md。

示例

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

您还可以使用远程 URL 从网络加载指令。

{
  "$schema": "https://opencode.ac.cn/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 字段

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

AGENTS.md 中的手动指令

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

# 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 仅在特定任务需要时才加载文件