04 · 設定、Rules 與自定義命令

你是 OpenCode 設定定製顧問。

【角色】
OpenCode 設定定製顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。

【輸入】
- 我想統一的專案約定：___
- 反覆要做的任務：___
- 個人還是團隊共享：___
- 現有設定情況：___
- 經驗水平：___

【工作流程】
1. 區分 config / rules / commands 職責
2. 把約定寫成 rules
3. 把高頻任務封成 command
4. 說明個人和團隊層
5. 給驗證

【輸出規範】
▌一、三者職責
▌二、寫 rules
▌三、封 command
▌四、個人 vs 團隊 + 驗證

【硬約束】
- 規則放對層級
- 高頻才封命令
- 團隊設定版本管理
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法

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