OpenCode 规则配置详解：用 AGENTS.md 打造专属 AI 编程助手

OpenCode 规则配置详解：用 AGENTS.md 打造专属 AI 编程助手

引言

在使用 AI 编程助手时，你是否遇到过这样的困扰：AI 生成的代码不符合项目的编码规范，或者不理解项目的架构设计？OpenCode 通过 AGENTS.md 规则系统完美解决了这个问题。本文将详细介绍如何利用 AGENTS.md 和自定义指令文件，让 AI 助手真正理解你的项目。

什么是 AGENTS.md

AGENTS.md 是 OpenCode 的核心配置文件之一，类似于 Cursor 的 Rules 系统。它包含了一系列指令，这些指令会被注入到 LLM 的上下文中，用于定制 AI 的行为。

当你首次运行 /init 命令时，OpenCode 会自动分析你的项目结构，生成一份定制化的 AGENTS.md 文件。这个文件包含了项目特定的指导信息，如构建命令、测试方法、代码规范等。

快速开始

初始化生成

在项目根目录下运行 OpenCode，然后执行初始化命令：

/init

OpenCode 会扫描项目的重要文件，并可能提出几个针对性的问题。完成后，项目根目录下会生成一个 AGENTS.md 文件。

建议将 AGENTS.md 提交到 Git 仓库，这样团队成员都能受益于这些规则配置。

手动创建

如果不想使用自动初始化，也可以手动创建 AGENTS.md：

touch AGENTS.md

规则文件的层级结构

OpenCode 支持从多个位置读取规则文件，不同位置的规则有不同的作用范围：

| 文件位置 | 作用范围 | 用途 |
|---------|---------|------|
| 项目根目录/AGENTS.md | 当前项目 | 项目特定的规则，与团队共享 |
| ~/.config/opencode/AGENTS.md | 所有项目 | 个人偏好，不共享 |
| ~/.claude/CLAUDE.md | 所有项目 | Claude Code 兼容 |

项目级规则

在项目根目录创建 AGENTS.md，只会在该项目中生效。这是团队协作的最佳方式：

# 项目规则

## 项目结构
- src/ - 源代码目录
- tests/ - 测试文件
- docs/ - 文档

## 代码规范
- 使用 TypeScript strict 模式
- 遵循 ESLint 配置
- 提交信息遵循 Conventional Commits

全局规则

在 ~/.config/opencode/AGENTS.md 中设置的规则对所有项目生效。适合放置个人偏好设置：

# 个人偏好

## 代码风格
- 偏好使用 const 而非 let
- 优先使用箭头函数
- 字符串使用单引号

## 回复风格
- 解释要简洁明了
- 提供可运行的代码示例

自定义指令文件

除了 AGENTS.md，你还可以在 opencode.json 中指定额外的指令文件，实现更灵活的配置：

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

支持远程文件

你甚至可以从远程 URL 加载指令文件：

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

远程文件会在启动时获取，超时时间为 5 秒。

外部文件引用

通过 opencode.json 引用

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

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

在 AGENTS.md 中手动引用

你也可以在 AGENTS.md 中告诉 OpenCode 按需读取外部文件：

# TypeScript 项目规则

## 外部文件加载

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

## 开发指南
代码风格规范: @docs/typescript-guidelines.md
React 组件模式: @docs/react-patterns.md
API 设计标准: @docs/api-standards.md

实际案例

前端项目

# React + TypeScript 项目

## 技术栈
- React 18 + TypeScript
- Vite 构建工具
- Tailwind CSS 样式
- Jest + Testing Library 测试

## 代码规范
- 使用函数式组件和 Hooks
- 组件文件使用 PascalCase
- 工具函数文件使用 camelCase
- 样式优先使用 Tailwind 类名

## 目录结构
- src/components/ - 可复用组件
- src/pages/ - 页面组件
- src/hooks/ - 自定义 Hooks
- src/utils/ - 工具函数
- src/api/ - API 请求封装

后端项目

# Node.js API 项目

## 环境要求
- Node.js 18+
- PostgreSQL 14+
- Redis 7+

## API 规范
- RESTful 风格
- 使用 JSON 格式
- 错误码遵循 HTTP 状态码标准
- 认证使用 JWT Token

## 数据库规范
- 使用 Knex.js 作为查询构建器
- 所有表名使用复数形式
- 字段名使用 snake_case

最佳实践

保持简洁 - 规则文件不要过于冗长，重点突出项目特有信息

版本控制 - 将 AGENTS.md 提交到 Git，团队共享

模块化组织 - 使用 instructions 字段引用外部文件，保持主文件简洁

定期更新 - 随项目演进更新规则内容

测试验证 - 修改规则后测试 AI 行为是否符合预期

Claude Code 兼容性

如果你从 Claude Code 迁移过来，OpenCode 会自动读取 Claude Code 的配置文件作为回退：

• 项目规则: CLAUDE.md（如果 AGENTS.md 不存在）
• 全局规则: ~/.claude/CLAUDE.md（如果 ~/.config/opencode/AGENTS.md 不存在）

可以通过环境变量禁用兼容模式：

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 和自定义指令文件，你可以让 OpenCode 深度理解你的项目，生成更符合规范的代码。规则系统支持多层级配置、外部文件引用和远程加载，为个人开发者和团队协作都提供了灵活的解决方案。

掌握规则配置，让 AI 编程助手真正成为你的得力助手。更多配置详情，请参考官方文档：https://opencode.ai/docs/rules/