AGENTS.md 與規則系統

摘要

AGENTS.md 是 opencode 專案中最重要的設定檔之一。它定義了 AI 在該專案中的行為規則、編碼風格、架構慣例與注意事項。如同一個專案的「憲法」，AGENTS.md 確保 opencode 在協助開發時能遵循你的期望。本章將教你從 /init 自動產生到手動撰寫，再到進階規則管理。

學習目標

• 理解 AGENTS.md 的角色與重要性
• 學會使用 /init 自動產生 AGENTS.md
• 學會手動撰寫與自訂規則
• 理解規則的優先順序系統
• 了解 opencode 與 Claude Code 規則的相容性
• 學會在 opencode.json 中使用 instructions 欄位

什麼是 AGENTS.md？

AGENTS.md 是一個放置在專案根目錄的 Markdown 檔案，用來指導 opencode 如何與你的專案互動。它包含了：

• 專案概述：專案的目的、技術棧、架構
• 編碼慣例：命名規則、檔案結構、設計模式
• 行為約束：哪些開源授權、哪些目錄不能動、哪些工具偏好
• 工作流程：測試規範、建置步驟、部署流程
• 注意事項：常見陷阱、安全性考量、特殊需求

你可以把 AGENTS.md 想像成一個專屬的 onboarding 文件，讓每次啟動 opencode 時，AI 都能快速掌握專案的全貌。

使用 /init 自動產生

最快的入門方式是使用 /init 指令自動產生 AGENTS.md：

執行步驟

# 1. 在專案目錄中啟動 opencode
opencode

# 2. 在 TUI 中輸入
/init

opencode 會分析你目前專案的內容（如 package.json、目錄結構等），自動產生一份初步的 AGENTS.md，內容包含：

• 專案名稱與技術棧推測
• 常用的 npm 指令
• 程式碼風格建議
• 通用的開發規則

自動產生的檔案是一個很好的起點，你可以在此基礎上逐步修改與擴充。

產生的範例

# Project Rules

You are an expert in TypeScript, Node.js, and web development.

## 技術棧
- TypeScript
- Express.js
- Prisma ORM

## 指令
- 建置：`npm run build`
- 測試：`npm test`
- 開發：`npm run dev`

## 程式碼風格
- 使用 arrow function 而非 function 宣告
- 遵循 ESLint 與 Prettier 設定
- 使用 async/await 而非 Promise chain

手動撰寫 AGENTS.md

若要更精細地控制規則，你需要手動撰寫或編輯 AGENTS.md。以下是一個完整的範本：

# 專案規則

你是這個專案的資深開發者，擁有完整的技術決策權。

## 核心原則
- 優先使用 TypeScript，嚴格模式
- 所有公開 API 都必須有 JSDoc 註解
- 測試涵蓋率目標：90% 以上

## 目錄結構
- `src/`：原始碼
- `src/api/`：API 路由
- `src/services/`：商業邏輯
- `src/db/`：資料庫相關
- `tests/`：測試檔案（對應 src/ 結構）

## 禁止事項
- 不要修改 `src/config/` 中的設定檔，除非我明確要求
- 不要使用 `any` 型別
- 不要引入新的大型依賴，除非先討論

## 工作流程
1. 先閱讀相關檔案了解上下文
2. 提出計畫讓我確認
3. 實作並確保測試通過
4. 執行 lint 檢查

## 安全注意事項
- 永遠不要將 API Key 寫入程式碼
- 使用環境變數管理機敏資訊
- SQL 查詢必須使用參數化查詢

規則類型與優先順序

opencode 的規則系統分為多個層級，從全域到專案，越具體的規則優先順序越高：

全域規則

如果你有一些通用規則（例如「永遠使用繁體中文回覆」、「不要使用 console.log」），可以寫在全域的 AGENTS.md 中：

# 建立全域 AGENTS.md
mkdir -p ~/.config/opencode
code ~/.config/opencode/AGENTS.md

如此一來，每個專案啟動時都會自動載入這些全域規則，再疊加專案特定的 AGENTS.md。

opencode.json 中的 instructions

你也可以在 opencode.json 設定檔中使用 instructions 欄位來嵌入規則：

{
  "model": "claude-sonnet-4-20250514",
  "instructions": [
    "使用繁體中文回覆所有訊息",
    "在開始修改前，先閱讀相關檔案的完整內容",
    "優先使用函式式程式設計風格",
    "所有錯誤必須有適當的錯誤處理"
  ]
}

instructions 陣列中的每一條都是對 opencode 的行為指示，適合存放簡短、明確的規則。

與 Claude Code 的相容性

如果你之前使用過 Claude Code，你可能已經有 CLAUDE.md 檔案。好消息是：opencode 完全相容 CLAUDE.md 格式！

• opencode 會同時讀取 AGENTS.md 和 CLAUDE.md
• 兩個檔案的規則會合併生效
• 如果同一個規則在兩個檔案中衝突，以 AGENTS.md 為準
• 你可以沿用現有的 CLAUDE.md 無需修改

這讓從 Claude Code 遷移的使用者可以無縫轉換，不需重新撰寫所有規則。

最佳實踐

1. 從簡單開始，逐步擴充

不需要一開始就想寫出完美的規則。先用 /init 產生基礎版本，每次遇到重複問題時再逐步加入對應規則。

2. 規則要具體、可執行

「寫出好程式碼」太模糊；「使用箭頭函式而非 function 宣告，所有函式必須有回傳型別」才是有效的規則。

3. 負面規則（禁止事項）很重要

明確告訴 opencode 哪些事情不要做，往往比正面規則更有效。例如：「不要移除註解」、「不要改動 API 回應格式」。

4. 定期檢視與更新

隨著專案演進，規則也需要更新。建議每個 sprint 結束時檢視一次 AGENTS.md。

5. 團隊共享

將 AGENTS.md 納入版本控制，讓團隊成員共享統一的開發規則。新人加入時也能快速上手。

實戰練習