！ 本篇文章將會介紹 AGENTS.md 的進階配置：多層 rules、引用外部文件、以及「規則要寫多少」的拿捏 :D

TL;DR: https://dev.benben.me/slides/s/ironman-12-rules

本篇目標

讀完這篇你會學到：

• global / project 多層 rules 的載入順序
• 用 instructions 引用外部文件（含 monorepo 與遠端 URL）
• 判斷 rules 太多或太少的平衡心法

複習：Rules 的三個層級

Day 04 介紹過 /init，今天把整張地圖補完。opencode 啟動時依這個順序找規則：

1. 專案層：從目前目錄往上爬，先找到 AGENTS.md 就用（沒有才退回 CLAUDE.md，對，你知道的 Claude Code 不要回讀 AGENTS.md）
2. 全域層：~/.config/opencode/AGENTS.md（個人的偏好寫這，不進 git）
3. Claude Code 相容：~/.claude/CLAUDE.md（前面都沒有才用）

每個類別都是先搶先贏：有 AGENTS.md 就不讀 CLAUDE.md。不想吃 Claude Code 相容設定的話，export OPENCODE_DISABLE_CLAUDE_CODE=1 一行關閉。

小提醒：全域層適合放「你這個人」的規則（例如「回覆用繁體中文」），專案層放「這個專案」的規則（build 指令、架構慣例）。放反了會出現「同事撿到你的個人偏好」的靈異現象。

引用外部文件：instructions 欄位

AGENTS.md 不是只能一個檔案寫到底。在 opencode.json 加上：

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

所有列出的檔案會與 AGENTS.md 合併載入。支援 glob —— 這對 monorepo 是救星：

"instructions": ["packages/*/AGENTS.md"]

每個 package 管自己的規則，root 統一引用，不用複製貼上。

instructions 也吃遠端 URL：

"instructions": ["https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"]

團隊把共用規範放一個 repo，各專案遠端引用，改一次全部生效（逾時 5 秒，抓不到就跳過，不會卡死啟動）。

另一招：教 AI 自己去讀

官方文件還示範了一種寫法——在 AGENTS.md 裡寫「當你看到 @docs/xxx.md 引用時，用 read tool 按需載入」：

## External File Loading

CRITICAL: 遇到檔案引用（如 @rules/general.md）時，用 Read tool 依需求載入。

- 不要預先全部載入，用到才讀（lazy loading）
- 讀入後視為必須遵守的指示

這招讓規則「用到的才進 context」，大型專案可以省不少 token。但一般情況官方更推薦 instructions + glob，好維護。

到底要寫多少規則？

這是最常被問的問題。先給判斷原則：

該寫的（AI 猜不到的）

• build / lint / test 指令與執行順序
• 從檔名看不出來的架構決策（「packages/core 是唯一能放共用邏輯的地方」）
• 團隊慣例（commit 格式、branch 命名、錯誤處理模式、其他 Naming Converation）

不該寫的

• AI 本來就會的事（「請寫乾淨的 code」——廢話等級）
• 一次性的任務描述（那是 prompt，不是 rule）
• 已經過時的內容——過時的說明書比沒有更可怕，AI 會很聰明地遵守錯的規則

太多的症狀

規則不是免費的：每一條都常駐 context。症狀是 AI 開始「撿了規則忘了任務」，或回答變得綁手綁腳。這時候動手砍——然後觀察哪條規則被砍掉後 AI 開始犯錯，再把它加回來。

實用心法：錯了再加

與其一開始就寫三十條，不如：

1. /init 生成基本盤
2. 正常工作
3. 每次 AI 犯同樣的錯，就加一條規則
4. 每季清一次，刪掉沒再發揮作用的

Rules 是活的文件，跟著專案長大，不是一次寫死的憲法。

常見問題

Q：我從 Claude Code 跳槽，.claude/skills/ 的技能會被吃到嗎？
A：會，opencode 會讀 ~/.claude/skills/ 與專案的 .claude/skills/，Day 15 講 skills 時會展開。

Q：AGENTS.md 該 commit 進 git 嗎？
A：該。專案層 rules 是團隊資產，讓每個人的 AI 都吃到同一份規則，這才是 rules 發揮最大價值的方式。

Q：/init 會蓋掉我手寫的 AGENTS.md 嗎？
A：不會，官方設計是「in place 改進」——它掃描 repo 後改善現有內容，不是無腦覆蓋。

小結

• 載入順序：專案 AGENTS.md → 全域 ~/.config/opencode/AGENTS.md → Claude Code 相容
• instructions 支援檔案、glob、遠端 URL，monorepo 用 packages/*/AGENTS.md 收納
• 規則品質 > 數量：錯了才加、定期修剪、過時就刪

明日預告

Day 13：Custom commands——把每天重複打的 prompt 變成一個斜線指令。

有任何疑問但沒有 iT 邦幫忙帳號，或是想匿名提問？
歡迎到 https://dev.benben.me/q/P3C5U6 提問或加油打氣，沒意外的話會在完賽之後一起回答 :D