---
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="/zh-Hant/docs/opencode/official/02-agents-skills/skills">
    Rules 是長期約束；可複用流程應該沉澱成 Skill。
  </Card>
  <Card title="配置 Agents" href="/zh-Hant/docs/opencode/official/02-agents-skills/agents">
    規則告訴 Agent 怎麼做事，Agent 決定誰來做、能做什麼。
  </Card>
  <Card title="配置、Rules 與自定義命令" href="/zh-Hant/docs/opencode/understanding/04-config-rules-commands">
    用更完整的分層理解 config、rules、instructions 和 commands。
  </Card>
  <Card title="安裝外掛" href="/zh-Hant/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/)
