深入掌握 AGENTS.md 規則撰寫、自訂指令開發與三者間的協作關係
OpenCode 提供三種控制代理行為的機制，它們各自有不同的用途與影響範圍：
| 機制 | 檔案格式 | 影響範圍 | 主要用途 | 變更頻率 |
|---|---|---|---|---|
| 規則（Rules） | AGENTS.md |
全域 / 專案層級 | 定義行為邊界、編碼規範、安全政策 | 低（設定後少改） |
| 指令（Commands） | .opencode/commands/*.md |
專案層級 | 封裝重複性工作流程為一鍵執行 | 中（隨需求增加） |
| 技能（Skills） | SKILL.md |
全域 / 專案 / 工作階段 | 提供專業領域的步驟指引 | 高（持續擴充） |
這三種機制並非互斥，而是相輔相成。良好的 OpenCode 設定通常會同時使用三者：規則定義「可以做什麼」的界線，指令封裝「經常做」的流程，技能提供「怎麼做好」的專業知識。
最具體的規則總是獲勝（Most Specific Wins）。當多個規則同時存在時，OpenCode 會選擇與當前上下文最相關、限制最明確的那一條。
AGENTS.md 是 OpenCode 的核心規則檔案，位於專案根目錄或使用者設定目錄。它定義了代理在專案中應該遵循的行為準則。
在專案中執行 /init 指令可以快速產生初始的 AGENTS.md：
# 專案規則
## 語言與風格
- 使用 TypeScript，嚴格模式
- 使用 2 空格縮排
- 使用單引號而非雙引號
- 所有檔案末尾保留一個空行
## 測試規範
- 所有功能必須包含單元測試
- 測試檔案命名：`*.test.ts`
- 使用 Vitest 作為測試框架
- 測試覆蓋率目標：80% 以上
## 程式碼結構
- 元件放在 `src/components/` 目錄
- 頁面放在 `src/pages/` 目錄
- 工具函式放在 `src/utils/` 目錄
- 型別定義放在 `src/types/` 目錄
## 禁止事項
- 不要使用 `any` 型別
- 不要提交包含 `console.log` 的程式碼
- 不要使用已棄用的套件或 API
- 不要直接修改 `node_modules` 內容規則可以放在不同的層級，影響範圍各不相同：
| 層級 | 檔案位置 | 影響範圍 |
|---|---|---|
| 專案層級 | 專案根目錄/AGENTS.md |
僅限當前專案 |
| 使用者層級 | ~/.config/opencode/AGENTS.md |
所有專案 |
| Claude 相容 | 專案根目錄/CLAUDE.md |
與 Claude Code 共享的規則 |
將通用的編碼風格與安全規範放在使用者層級的 AGENTS.md，將專案特定的架構規則放在專案層級。這樣當你切換專案時，通用規則會自動套用，而專案規則則各司其職。
自訂指令讓你將多步驟的工作流程封裝為一個簡單的斜線指令。例如，輸入 /deploy 即可自動執行建置、測試、部署等一系列操作。
每個指令是一個放在 .opencode/commands/ 目錄下的 Markdown 檔案：
# 建立指令目錄
mkdir -p .opencode/commands
# 建立 deploy 指令
cat > .opencode/commands/deploy.md << 'EOF'
---
description: 執行完整部署流程 — 測試、建置、發布
agent: build
model: gpt-4o
---
# 部署流程
執行以下步驟來部署專案：
## 步驟 1：執行測試
\`\`\`bash
npm run test
\`\`\`
## 步驟 2：建置專案
\`\`\`bash
npm run build
\`\`\`
## 步驟 3：部署到生產環境
\`\`\`bash
npm run deploy:prod
\`\`\`
## 步驟 4：驗證部署
確認部署狀態並執行冒煙測試。
EOF| 欄位 | 說明 |
|---|---|
description |
指令功能的簡短描述，顯示在指令列表與自動補全中 |
agent |
指定執行此指令的代理（預設為目前代理） |
model |
指定執行的模型（可覆蓋預設模型） |
指令支援多種動態參數：
---
description: 執行客製化部署，支援版本標籤與環境選擇
---
# 部署指令
## 參數
- `{{version}}`：部署版本號（必填）
- `{{env}}`：部署環境（預設：staging）
- `{{branch}}`：來源分支（預設：main）
## 步驟
1. 切換到 {{branch}} 分支並更新
2. 建置版本 {{version}}
3. 部署到 {{env}} 環境
4. 執行 {{env}} 環境的冒煙測試執行時只需輸入：/deploy version=2.1.0 env=production
參數值也可以來自 shell 指令的輸出：{{shell:date +%Y%m%d}} 會自動填入當前日期。你也可以引用檔案內容：{{file:VERSION}} 會讀取 VERSION 檔案的內容作為參數值。
OpenCode 提供一系列實用的內建指令，無需任何設定即可使用：
| 指令 | 功能 | 使用時機 |
|---|---|---|
/init |
初始化專案設定，產生 AGENTS.md | 新專案開始時 |
/undo |
復原上一次代理操作 | 當代理做了你不想要的變更時 |
/redo |
重新套用已復原的操作 | 復原後改變主意時 |
/share |
產生目前對話的可分享連結 | 需要與團隊討論對話內容時 |
/help |
顯示可用指令與說明 | 忘記指令名稱或用法時 |
/compact |
壓縮對話上下文以節省 Token | 對話過長、回應變慢時 |
/models |
列出可用的語言模型與切換 | 需要更換模型時 |
/new |
開啟全新的對話 Session | 開始全新的任務時 |
/undo 和 /redo 僅能復原當前對話 Session 中的操作。如果你關閉並重新開啟了 OpenCode，這些操作歷史就無法再復原了。建議在進行重大變更前先使用版本控制（git）。
為了幫助你選擇最適合的控制機制，以下是三個維度的完整比較：
| 比較維度 | 規則（AGENTS.md） | 指令（Commands） | 技能（Skills） |
|---|---|---|---|
| 定義方式 | 自然語言規則 | 步驟 + 可執行命令 | 步驟指引 + 觸發詞 |
| 觸發方式 | 自動載入（始終有效） | 斜線指令手動觸發（/command） |
自動匹配觸發詞或手動要求 |
| 執行模型 | 被動制約（不執行，僅引導） | 主動執行（可包含 shell 命令） | 被動指引（提供步驟框架） |
| 動態性 | 靜態規則，變更頻率低 | 可包含動態參數 | 內容固定，可鏈式組合 |
| 適用場景 | 編碼規範、安全政策、架構原則 | 部署、測試、格式化、發布 | 程式碼審查、文件產生、UI 設計 |
| 共用性 | 可跨專案（使用者層級） | 僅限專案層級 | 可跨專案（多個安裝路徑） |
讓我們整合本節所學，建立一個完整的開發工作流程：
# 開發規則
## 程式碼規範
- 使用 ESLint + Prettier 維持程式碼品質
- 所有公開 API 必須有 JSDoc 註解
- 優先使用函式式程式設計，避免可變狀態
## 提交規範
- 使用 Conventional Commits 格式
- commit 類型：feat, fix, chore, docs, refactor, test
- 每個 commit 只包含一個邏輯變更
## 審查要求
- 合併請求至少需要 1 位 reviewer 核准
- 所有檢查必須通過才能合併---
description: 建立一個包含測試與文件的 feature branch
---
# Feature 開發指令
## 參數
- `{{name}}`：功能名稱（kebab-case，必填）
- `{{type}}`：類型（feature/hotfix，預設：feature）
## 步驟
1. 從 main branch 建立 {{type}}/{{name}} branch
2. 執行 \`\`\`npm run generate:component {{name}}\`\`\`
3. 建立對應的測試檔案
4. 更新文件搭配第五章的自訂代理技能，形成完整的開發閉環。
建議的學習路徑：先設定 AGENTS.md 規則 確保代理行為符合團隊標準，再建立常用的 指令 封裝重複性工作，最後根據需求逐步擴充 技能庫。
AGENTS.md 是 OpenCode 原生使用的規則檔案，而 CLAUDE.md 是 Claude Code 使用的規則檔案。OpenCode 同時支援兩者，如果你同時使用兩種工具，將規則寫在 CLAUDE.md 中可以保持相容性。建議優先使用 AGENTS.md 以獲得 OpenCode 的完整功能支援。{{shell:command}}）與檔案引用（{{file:path}}）。雖然不支援下拉選單，但你可以在指令步驟中透過條件判斷來模擬選擇行為，例如在步驟中寫出「如果 {{env}} 是 production，則執行 X；否則執行 Y」。description 來讓使用者了解使用時機，或在指令的前言加入使用條件的說明。如果某個指令不再需要，直接刪除對應的 .md 檔案即可。