04 · 配置、Rules 與自定義命令

OpenCode 的長期價值不在“這次回答得不錯”，而在“這次沉澱下來的經驗，下次能自動生效”。配置、Rules 和 Commands 就是三種沉澱方式。

這一篇先把三者分清：配置決定 OpenCode 怎麼執行，Rules 決定 agent 在專案裡應該遵守什麼，自定義命令把重複流程變成 /xxx 入口。分不清這三者，後面 agents、skills、plugins 會越寫越亂。

沉澱層級圖

從一次性提示詞到執行時擴充套件，維護成本會逐層上升。先用最低層解決問題。

flowchart LR
  Prompt["一次性提示詞"] --> Rules["Rules / AGENTS.md<br/>長期專案約束"]
  Rules --> Config["Config<br/>模型 / 許可權 / share / formatter"]
  Rules --> Commands["Commands<br/>重複流程入口"]
  Commands --> Agents["Agents<br/>角色和許可權邊界"]
  Agents --> Skills["Skills<br/>跨專案流程包"]
  Skills --> Plugins["Plugins / custom tools<br/>執行時或工具擴充套件"]

  style Rules fill:#dbeafe,stroke:#3b82f6
  style Commands fill:#dcfce7,stroke:#22c55e,stroke-width:2px
  style Plugins fill:#fee2e2,stroke:#ef4444

同一條提醒說了三次，才值得沉澱；沉澱前先判斷它是執行策略、長期約束，還是重複流程。

1. 三者先分工

先用一句話拆開：

Config      机器怎么运行
Rules       Agent 在这个项目里怎么做事
Commands    重复任务怎么一键触发

2. Config 管執行，不管任務

OpenCode 支援 JSON / JSONC 配置。官方文件說明配置會按多個來源合併，後面的配置覆蓋前面的衝突項，但非衝突項會保留。

你最常用的配置位置：

專案級 opencode.json 的優先順序高於全域性配置，適合放團隊共識。但不要把 API key、token、cookie 寫進去。

一個專案級配置的思路示例：

{
  "$schema": "https://opencode.ai/config.json",

  // 模型号请按官方当前推荐 + `/models` 命令为准，不要把"今天最强"硬编码到团队配置里
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",

  "permission": {
    "*": "ask",
    "read": "allow",
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git status*": "allow",
      "git diff*": "allow",
      "rm *": "deny",
      "git push*": "deny"
    }
  },
  "share": "manual",
  "instructions": ["CONTRIBUTING.md", "docs/development.md"]
}

這段配置的重點不是推薦你原樣複製，而是展示分層：模型、許可權、分享和額外 instructions 都屬於“執行時策略”，不屬於某一次任務。具體可用模型號會隨 provider 上新和淘汰漂移，團隊配置裡寫一個當前還在的、穩定可用的模型即可，但要把"看 官方 models 頁" 這條核驗路徑寫進 README 或 AGENTS.md，讓下一個接手的人知道怎麼自己更新。

3. Rules 不是百科，是專案約束

OpenCode 的 Rules 文件核心是 AGENTS.md。你可以用 /init 建立或更新它。官方建議把專案級 AGENTS.md 提交到 Git，因為它是團隊共享的 agent 專案說明。

適合寫進 AGENTS.md 的內容：

• 專案技術堆疊和目錄結構。
• build、lint、test 命令。
• 包管理器約定，例如只用 pnpm 或只用 bun。
• 修改前必須閱讀的專案文件。
• 禁止修改的目錄和檔案。
• 錯誤處理、命名、測試、釋出邊界。
• 已有 Cursor / Copilot / Claude Code 規則的引用方式。

不適合寫進去的內容：

• 一次性任務目標。
• 真實 API key 或內部賬號。
• 長篇專案百科。
• 已經過期的歷史爭論。
• 可以透過檔案結構自動看出來的廢話。

4. AGENTS.md 和 CLAUDE.md 的關係

OpenCode 支援 AGENTS.md，也相容 Claude Code 的 CLAUDE.md 約定。官方 Rules 文件說明：

• 專案規則優先讀當前目錄向上查詢的 AGENTS.md / CLAUDE.md。
• 如果同一位置同時有 AGENTS.md 和 CLAUDE.md，AGENTS.md 優先。
• 全域性規則優先使用 ~/.config/opencode/AGENTS.md，再相容 ~/.claude/CLAUDE.md。
• OpenCode 還會相容 .claude/skills/ 當成 Skills 來源（詳見 05 篇）。

這對從 Claude Code 遷移的人很重要。不要同時維護兩份不同規則。更穩的做法是選一個主入口，再讓另一個相容引用或保持一致。

如果你想完全關掉對 Claude Code 檔案的相容，OpenCode 提供了三個環境變數，按需選粒度：

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

5. Instructions 適合複用已有規範

如果專案已經有 CONTRIBUTING.md、docs/development.md、.cursor/rules/*.mdc，不要複製一份到 AGENTS.md。OpenCode 支援在 config 裡用 instructions 引用這些檔案：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/development-standards.md",
    ".cursor/rules/*.mdc",
    // 也支持 https URL，5 秒超时拉取
    "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"
  ]
}

這樣做的好處是減少重複維護，跨專案共享規則也容易（團隊公共規則放一個 git 儲存庫，多專案透過 raw URL 引用）。但引用要剋制：不要一次性塞 20 個規則檔案。規則越多，模型越容易抓不住真正關鍵的約束。遠端 URL 引用還要承擔拉取失敗和被改動的風險——OpenCode 給的超時是 5 秒，如果遠端不可達，那次會話就會少這條規則。

6. Commands 把重複流程做成入口

當一個提示詞反覆用三次以上，就可以考慮做成 command。

官方 Commands 文件支援兩種方式：

• 在 opencode.json 裡寫 command 配置。
• 建立 markdown command 檔案，例如 .opencode/commands/review-diff.md。

專案裡更推薦 markdown 檔案，因為更易讀、易 review、易版本化。

---
description: Review current git diff for bugs and regressions
agent: build
---

请审查当前 git diff：

1. 先读取当前 diff，不要修改文件。
2. 优先找 bug、行为回归、安全风险和缺失测试。
3. 输出按严重程度排序。
4. 如果没有问题，明确说没有发现阻断问题。

檔名就是命令名：

/review-diff

frontmatter 裡的 agent 欄位指向 OpenCode 內建或你自己定義的 agent（如預設 build / plan，或自定義的 review / security-audit）。如果不寫 agent 就沿用當前會話的 agent。詳見 05 篇。

Command 的價值不是少打幾個字，而是把任務邊界、檢查順序和輸出格式固定下來。

7. Command 引數、檔案和 shell 輸出

OpenCode command 支援 $ARGUMENTS、$1、$2 這類引數，也支援在 prompt 中引用檔案和注入 shell 輸出。

例子：

---
description: Explain one module with risks
---

请解释 $ARGUMENTS 这个模块：

1. 先阅读相关入口文件。
2. 说明它解决什么问题。
3. 画出调用链。
4. 列出最可能出错的 3 个点。

執行：

/explain-module src/auth

再比如把 git diff 注入 command：

---
description: Review current diff
---

当前改动如下：

!`git diff --stat`
!`git diff`

请只做审查，不要修改文件。

frontmatter 還有兩個有用但容易被忽略的選項：

例如讓一條體量大的程式碼審查走 subagent + 更強模型：

---
description: Deep audit of recent changes
agent: build
model: anthropic/claude-opus-4-5
subtask: true
---

请深度审查最近 50 个 commit：
...

8. 推薦沉澱順序

不要第一天就配置滿。更穩的順序是：

普通提示词
  ↓  同一提醒出现 3 次
AGENTS.md / instructions
  ↓  同一流程出现 3 次
.opencode/commands/*.md
  ↓  需要不同角色和权限
agents
  ↓  跨项目复用能力
skills
  ↓  需要运行时扩展
plugins / custom tools

每往下一層，維護成本都更高。OpenCode 的開放配置不是為了堆滿所有目錄，而是讓真實經驗逐步沉澱。

9. 新手常見坑

10. 怎麼驗收

你可以用 5 個問題檢查這一層是否過關：

• 每一條 AGENTS.md 規則是否未來多次任務都需要？
• 專案配置裡是否沒有真實金鑰？
• 能否用一個 command 穩定完成重複任務？
• 規則、配置、命令是否各司其職，沒有互相汙染？
• 刪除某條 rule 或 command 時，是否知道會影響哪些流程？

接下來去哪

官方資料

• Config：https://opencode.ai/docs/config
• Rules：https://opencode.ai/docs/rules
• Commands：https://opencode.ai/docs/commands
• Permissions：https://opencode.ai/docs/permissions