編寫規則

OpenCode 的 Rules 是給 Agent 的專案說明和行為約束。它的核心入口是 AGENTS.md：告訴 Agent 這個專案怎麼啟動、怎麼驗證、哪些目錄重要、哪些事情不能做。

先給結論：Rules 不是專案百科

規則檔案不是越長越好。好的 AGENTS.md 只回答未來 Agent 會反覆遇到的問題：

第一次怎麼生成

官方提供 /init 命令。它會掃描儲存庫中的重要檔案，必要時提出少量問題，然後建立或更新 AGENTS.md。

/init 重點關注這些內容：

• build、lint、test 命令。
• 命令順序和必要的區域性驗證步驟。
• 檔名看不出來的架構和儲存庫結構。
• 專案特定約定、設定細節和運維坑。
• Cursor、Copilot、Claude Code 等已有規則來源。

如果儲存庫已經有 AGENTS.md，/init 會嘗試原地改進，而不是盲目替換。

專案規則和全域性規則怎麼分

專案規則服務當前儲存庫，全域性規則服務你自己的所有 OpenCode 會話。

不要把個人習慣寫進專案規則，也不要把某個專案的命令寫進全域性規則。

規則讀取優先順序

OpenCode 啟動時，會按規則來源找檔案。可以把它理解成這條鏈：

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 相容，可以用環境變數關閉：

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 引用外部檔案。

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

也可以引用遠端 URL：

{
  "$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 裡的檔案引用。你可以用兩種方式管理外部規則：

如果是大型規範庫，不要要求 Agent 一開始讀完所有檔案。規則應該幫助 Agent 少猜，而不是把上下文塞滿。

一個健康的 AGENTS.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。
• 個人規則在全域性檔案。
• 外部檔案按需引用，不一次性塞滿上下文。

規則檔案的目標是減少誤操作，不是證明專案文件很完整。

接下來去哪

官方資料

• OpenCode Rules
• OpenCode configuration
• OpenCode Agent Skills