---
title: "编写规则"
description: "基于 OpenCode 官方 Rules 文档，帮助新手理解 AGENTS.md、全局规则、Claude Code 兼容和外部指令文件。"
verifiedAt: "2026-05-09"
---

OpenCode 的 Rules 是给 Agent 的项目说明和行为约束。它的核心入口是 `AGENTS.md`：告诉 Agent 这个项目怎么启动、怎么验证、哪些目录重要、哪些事情不能做。

> [!NOTE]
> **这一篇用 8 分钟换什么**：你会知道 `AGENTS.md` 应该写什么、项目规则和全局规则怎么分、Claude Code 的 `CLAUDE.md` 如何兼容，以及什么时候用 `instructions` 拆外部规则文件。

## 先给结论：Rules 不是项目百科

规则文件不是越长越好。好的 `AGENTS.md` 只回答未来 Agent 会反复遇到的问题：

| 应该写 | 不应该写 |
| --- | --- |
| build / lint / test 命令 | 真实 API key、账号、token |
| 目录职责和关键入口 | 一次性任务目标 |
| 包管理器和运行方式 | README 已经讲清的长篇背景 |
| 修改边界和禁止操作 | 过期历史争论 |
| 验证顺序和常见坑 | 个人表达偏好 |
| 需要按需读取的外部规范 | 整个团队手册全文 |

> [!IMPORTANT]
> 判断标准：未来 10 次任务都应该遵守的内容，才值得进 Rules。只对当前任务有效的要求，留在对话里。

## 第一次怎么生成

官方提供 `/init` 命令。它会扫描仓库中的重要文件，必要时提出少量问题，然后创建或更新 `AGENTS.md`。

`/init` 重点关注这些内容：

- build、lint、test 命令。
- 命令顺序和必要的局部验证步骤。
- 文件名看不出来的架构和仓库结构。
- 项目特定约定、设置细节和运维坑。
- Cursor、Copilot、Claude Code 等已有规则来源。

如果仓库已经有 `AGENTS.md`，`/init` 会尝试原地改进，而不是盲目替换。

> [!WARNING]
> `/init` 生成后必须人工审查。重点看命令是否真实存在、目录说明是否准确、是否泄露敏感信息、是否写得太长。

## 项目规则和全局规则怎么分

项目规则服务当前仓库，全局规则服务你自己的所有 OpenCode 会话。

| 类型 | 路径 | 是否适合提交到 Git | 适合放什么 |
| --- | --- | --- | --- |
| 项目规则 | `AGENTS.md` | 是 | 团队共享的项目命令、目录、约定、验证顺序 |
| 全局规则 | `~/.config/opencode/AGENTS.md` | 否 | 个人偏好、个人常用工具习惯 |
| Claude 项目兼容 | `CLAUDE.md` | 视项目而定 | 没有 `AGENTS.md` 时的 fallback |
| Claude 全局兼容 | `~/.claude/CLAUDE.md` | 否 | 没有 OpenCode 全局规则时的 fallback |

不要把个人习惯写进项目规则，也不要把某个项目的命令写进全局规则。

## 规则读取优先级

OpenCode 启动时，会按规则来源找文件。可以把它理解成这条链：

```mermaid
flowchart LR
  CWD[当前目录] --> Up[向上查找本地规则]
  Up --> Local{找到本地规则?}
  Local -->|AGENTS.md 优先| Project[项目规则生效]
  Local -->|无 AGENTS.md<br/>有 CLAUDE.md| ClaudeProject[Claude 项目兼容]
  Local -->|没有| Global[读取全局规则]
  Global --> OpenCodeGlobal[~/.config/opencode/AGENTS.md]
  Global --> ClaudeGlobal[~/.claude/CLAUDE.md fallback]
```

同一位置同时有 `AGENTS.md` 和 `CLAUDE.md` 时，`AGENTS.md` 优先。全局规则里，`~/.config/opencode/AGENTS.md` 优先于 `~/.claude/CLAUDE.md`。

## Claude Code 兼容怎么理解

OpenCode 支持 Claude Code 的文件约定作为 fallback：

- 项目里没有 `AGENTS.md` 时，可以读取项目 `CLAUDE.md`。
- 没有 OpenCode 全局规则时，可以读取 `~/.claude/CLAUDE.md`。
- `.claude/skills` 的兼容细节在 Agent Skills 页面继续看。

如果你不希望使用 Claude Code 兼容，可以用环境变量关闭：

```bash
export OPENCODE_DISABLE_CLAUDE_CODE=1
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1
export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1
```

迁移期可以利用 fallback，但不要长期维护两套互相冲突的规则。更稳的做法是选一个主入口，另一个只做兼容引用或保持同步。

## 外部指令怎么放

如果规则很多，不要把所有内容塞进 `AGENTS.md`。OpenCode 支持在 `opencode.json` 或全局配置里用 `instructions` 引用外部文件。

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/development-standards.md",
    ".cursor/rules/*.md"
  ]
}
```

也可以引用远程 URL：

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

远程 instructions 会有 **5 秒超时**：拉不到就跳过，那次会话就没有这条规则。所以网络抖动、对方仓库挂掉、CDN 慢都会让 agent 行为不稳定。来源必须可信，且不要把生死攸关的硬约束放在远程——核心边界还是要进项目自己的 `AGENTS.md`。

## 外部文件引用要按需加载

官方文档提醒：OpenCode 不会自动解析 `AGENTS.md` 里的文件引用。你可以用两种方式管理外部规则：

| 方式 | 适合场景 |
| --- | --- |
| `opencode.json` 的 `instructions` | 稳定、全局都需要加载的规则 |
| 在 `AGENTS.md` 明确说明按需读取 | 任务相关时才需要的细分规范 |

如果是大型规范库，不要要求 Agent 一开始读完所有文件。规则应该帮助 Agent 少猜，而不是把上下文塞满。

## 一个健康的 `AGENTS.md` 长什么样

可以按这个骨架写：

```md
# Project Instructions

## What This Project Is

One short paragraph describing the product and stack.

## Common Commands

- `pnpm run build`
- `pnpm run lint`
- `pnpm run test`

## Important Paths

- `src/app/`: routes and page entry points
- `src/components/`: shared UI components
- `content/docs/`: production documentation source

## Working Rules

- Do not edit generated files by hand.
- Keep content changes in the matching product directory.
- Run quality audits before build.

## Verification

1. Run the focused check for the changed area.
2. Run the project audit.
3. Build before deployment.
```

这不是固定模板，而是提醒你：规则文件要短、可执行、能指导下一步。

## 新手常见坑

- `/init` 后不审查就提交。
- `AGENTS.md` 写成完整项目文档，太长且没有优先级。
- 项目规则混入个人偏好。
- 全局规则写入某个项目的命令。
- 同时存在 `AGENTS.md` 和 `CLAUDE.md`，但团队不知道谁生效。
- 远程 instructions 来自不可信地址。
- 规则只写“不要做什么”，没有写验证顺序。

## 怎么判断规则健康

一个健康的规则文件应该满足：

- 新人读完能知道项目怎么启动、怎么验证。
- Agent 能知道哪些目录和命令最重要。
- 规则短而明确，没有复述 README。
- 团队共享规则在项目 `AGENTS.md`。
- 个人规则在全局文件。
- 外部文件按需引用，不一次性塞满上下文。

规则文件的目标是减少误操作，不是证明项目文档很完整。

## 接下来去哪

<Cards>
  <Card title="使用 Agent Skills" href="/docs/opencode/official/02-agents-skills/skills">
    Rules 是长期约束；可复用流程应该沉淀成 Skill。
  </Card>
  <Card title="配置 Agents" href="/docs/opencode/official/02-agents-skills/agents">
    规则告诉 Agent 怎么做事，Agent 决定谁来做、能做什么。
  </Card>
  <Card title="配置、Rules 与自定义命令" href="/docs/opencode/understanding/04-config-rules-commands">
    用更完整的分层理解 config、rules、instructions 和 commands。
  </Card>
  <Card title="安装插件" href="/docs/opencode/official/02-agents-skills/plugins">
    如果你需要运行时扩展，再继续看 Plugin。
  </Card>
</Cards>

## 官方资料

- [OpenCode Rules](https://opencode.ai/docs/rules/)
- [OpenCode configuration](https://opencode.ai/docs/config/)
- [OpenCode Agent Skills](https://opencode.ai/docs/skills/)
