2、OpenCode Rules 操作手册：从基础配置到高级应用

1. 简介与核心概念

OpenCode 的 Rules 功能通过自定义指令文件，为 AI 助手（编码代理）提供项目上下文、编码规范和工作流程指导。其核心是 AGENTS.md 文件，它将包含在大型语言模型（LLM）的上下文中，用于定制其在特定项目中的行为。

简而言之，你可以将 AGENTS.md 视为你项目的 AI 工作手册和流程规范，它能将项目特有的知识、约定和最佳实践传递给 AI，确保它像一个熟悉项目的老手一样工作，而不是一个需要从头学习的新人。

2. 快速开始：创建第一个规则文件

2.1 方法一：自动初始化（推荐）

在你项目的根目录下，运行 /init 命令。

cd /path/to/your/project
opencode /init

OpenCode 将自动扫描你的项目结构和内容，分析其技术栈和特点，并生成一个初始的 AGENTS.md 文件。如果文件已存在，此命令会尝试向其中添加新的、总结性的内容，而不会覆盖原有指令。

2.2 方法二：手动创建

你也可以直接在项目根目录手动创建一个名为 AGENTS.md 的 Markdown 文件。一个基础的示例如下：

# 我的项目规则

这是一个使用 React 18 和 TypeScript 构建的前端项目。

## 核心约定
- **代码风格**：使用 ESLint 和 Prettier，配置已存在于项目中。
- **组件规范**：所有 React 组件必须使用函数式组件和 TypeScript。
- **API 交互**：使用 `src/api` 目录下的封装函数，禁止在组件中直接使用 `fetch`。

## 对 AI 的指示
1. 修改文件前，请先分析相关文件和依赖。
2. 创建新组件时，请同时创建其对应的 `.test.tsx` 单元测试文件。
3. 遵循项目现有的目录结构和命名模式。

将此文件提交到 Git，可以与你的团队成员共享这些规则。

3. 规则的类型与应用场景

OpenCode 的规则系统分为三个层次，以满足不同范围的需求。它们遵循优先级顺序加载，避免了指令冲突。

3.1 项目规则

文件位置：项目根目录的 AGENTS.md。

作用域：仅在该项目目录及其子目录中生效。

核心用途：定义项目特定的编码标准、架构约定、工具配置和团队规范。这是最常用的一类规则。

共享性：强烈建议将此文件提交到 Git，以确保团队成员获得一致的 AI 辅助体验。

3.2 全局规则

文件位置：~/.config/opencode/AGENTS.md （用户主目录下的配置文件）。

作用域：在用户所有的 OpenCode 会话中生效。

核心用途：设定个人偏好、工作习惯和常用工具配置。例如，你个人偏好的代码注释风格、要求 AI 先解释再执行的安全习惯等。

注意：此文件不会被提交到 Git，仅限个人使用。

3.3 Claude Code 兼容性规则（用于迁移）

为从 Claude Code 迁移的用户提供平滑过渡。系统会按以下备选顺序查找规则文件：

项目规则：CLAUDE.md（当项目目录中没有 AGENTS.md 时使用）。
全局规则：~/.claude/CLAUDE.md（当没有 ~/.config/opencode/AGENTS.md 时使用）。

禁用兼容性：如需禁用此兼容功能，可以设置环境变量。

# 禁用所有 Claude Code 兼容支持
export OPENCODE_DISABLE_CLAUDE_CODE=1

# 仅禁用全局提示文件兼容
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1

4. 规则文件组织与引用策略

对于复杂项目，将所有规则堆砌在一个 AGENTS.md 文件中难以维护。OpenCode 提供了两种模块化管理规则的方式。

4.1 推荐方法：使用 opencode.json 配置文件

在项目根目录或全局配置目录（~/.config/opencode/）创建 opencode.json，通过 instructions 字段引用多个规则文件。

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "AGENTS.md", // 基础项目规则
    "docs/coding-style.md", // 详细的代码风格文档
    "docs/api-guidelines.md", // API设计规范
    "packages/*/AGENTS.md" // 对Monorepo各子包规则的引用
  ]
}

优点：

自动加载与合并：OpenCode 会自动读取并合并所有列出的文件内容。
支持远程规则：可以从 URL 加载共享规则，方便团队统一标准。

"instructions": ["https://your-company.com/shared-rules/frontend-base.md"]

支持 Glob 模式：如 *.md 或 packages/*/AGENTS.md，非常适合 Monorepo 项目。

4.2 灵活方法：在 AGENTS.md 中手动引用

如果你需要更动态、按需加载的规则，可以在 AGENTS.md 中明确指示 AI 助手去读取特定文件。

# 项目规则
## 外部引用指南
请根据当前任务需要，使用 Read 工具加载以下相关文件：

- **代码风格**：参考 `@docs/typescript-style-guide.md`
- **组件库使用**：参考 `@ui-library/usage-rules.md`
- **状态管理**：参考 `@docs/redux-patterns.md`

## 通用指令
1. 不要预先加载所有引用文件。
2. 仅在任务明确相关时才去加载对应文件。
3. 加载后的文件内容具有最高优先级。

优点：非常灵活，可以实现条件加载，避免不必要的上下文占用。

5. 进阶实践：Monorepo项目与团队协作

5.1 Monorepo 项目最佳实践

对于包含多个子包（packages）的 Monorepo 项目，推荐以下结构：

monorepo/
├── opencode.json
├── AGENTS.md (顶层通用规则)
├── docs/
│   └── global-standards.md
├── packages/
│   ├── web-app/
│   │   └── AGENTS.md (前端特定规则)
│   ├── api-server/
│   │   └── AGENTS.md (后端特定规则)
│   └── shared-lib/
│       └── AGENTS.md (库开发规则)

顶层 opencode.json 配置可以这样写：

{
  "instructions": [
    "AGENTS.md",
    "docs/global-standards.md",
    "packages/*/AGENTS.md"
  ]
}

5.2 团队协作策略

建立模板：为不同类型项目（如前端、后端、库）创建规则模板，新项目可以直接复制使用。

定期评审：将 AGENTS.md 和规则文件纳入代码评审流程，确保其与项目发展同步更新。

统一远程规则库：将公共规范（如公司安全准则、通用代码风格）存放在内部 Git 仓库，通过 opencode.json 的 URL 引用，实现一处修改，处处更新。

6. 实际示例：一个SST v3 Monorepo项目的规则

以下是来自官方文档的一个综合示例，展示了 AGENTS.md 如何清晰地指导 AI：

# SST v3 Monorepo 项目规则

这是一个使用 Bun 工作区的 TypeScript Monorepo 项目。

## 🏗️ 项目结构
- `packages/` - 所有内部包（functions, core, web等）
- `infra/` - SST 基础设施定义（storage.ts, api.ts等）
- `sst.config.ts` - 包含动态导入的主配置文件

## 📝 代码标准
- **TypeScript**：启用严格模式（`strict: true`）。
- **共享代码**：必须放在 `packages/core/` 目录下，并使用 `package.json` 正确导出。
- **函数**：所有 Lambda 函数应置于 `packages/functions/` 目录中。
- **基础设施**：应按逻辑功能拆分到 `infra/` 目录的不同文件中（如 `auth.ts`, `database.ts`）。

## 🔗 Monorepo 工作区约定
- **导入方式**：始终使用工作区名称导入，例如 `import { util } from "@my-app/core";`。
- **版本管理**：遵循语义化版本控制（SemVer），确保依赖版本在包间保持一致。

## 🤖 对 AI 的操作指示
1. 创建新包时，请先检查现有的 `packages/` 结构以保持一致性。
2. 修改基础设施时，请在 `infra/` 目录下寻找并更新对应的逻辑文件。
3. 避免直接修改 `sst.config.ts` 中的动态导入逻辑，除非你完全理解其作用。

7. 故障排查与常见问题

| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 规则未生效 | 1. 文件命名或位置错误。
2. 存在更高优先级的规则覆盖。 | 1. 确认文件名为 AGENTS.md，且位于项目根目录。
2. 检查当前目录及所有上级目录，以及全局目录。使用 /init 查看合并结果。 |
| 指令冲突 | 不同来源（项目 vs 全局）的规则内容矛盾。 | 理解"就近优先"原则，项目规则优先级最高。简化全局规则，或使用更明确的措辞。 |
| AI 未读取外部引用文件 | AGENTS.md 中的 @引用未被自动解析。 | 改用 opencode.json 的 instructions 字段进行自动加载。或在 AGENTS.md 中给 AI 明确的读取指令。 |

8. 总结

OpenCode Rules 功能为团队协作和项目维护提供了强大的标准化工具。通过合理使用 AGENTS.md 文件和规则系统，你可以：

确保一致性：所有团队成员（包括 AI 助手）遵循相同的编码标准和项目约定。
提高效率：减少重复解释项目规范的时间，让 AI 助手更快上手。
促进知识共享：将项目特有的最佳实践文档化，便于新成员快速融入。
支持复杂项目：通过模块化规则管理，轻松应对 Monorepo 等复杂项目结构。

开始使用 OpenCode Rules，让你的 AI 助手成为真正的项目专家，而不是需要不断指导的新手。