04 AGENTS.md：教會 Agent 你的專案規矩

2026 iThome 鐵人賽

DAY 4

自我挑戰組

自我耍廢組：全自動化の鐵人系列第 4 篇

18th鐵人賽自動化測試 ai agent opencode

benben6515

團隊賽博枕頭 X 躺平夥伴 X 快樂 AI

2026-09-14 20:00:25

114 瀏覽

分享至

！本篇文章將會介紹 AGENTS.md：教會 Agent 你的專案規矩，期望大家都能讓 agent 不用三催四請就自動守規矩，輸出穩定可預期 :D

昨天的結尾我留了一個問題：generate.sh 的 prompt 只點名「請閱讀三個檔案」，agent 就真的守規矩了，但為什麼它連沒被點名的慣例都會自動遵守？例如不管我在哪個資料夾開 opencode，它都自動講台灣繁體中文。答案有兩層：一層是 prompt 裡的明文規定，另一層是你看不到、卻每次都在場的幕後功臣——AGENTS.md。今天不只揭曉它怎麼運作，還要回答一個更重要的設計問題：哪些規矩該放 AGENTS.md，哪些不該。

本篇目標

讀完這篇你會學到：

AGENTS.md 的運作原理：opencode 什麼時候讀它、讀到之後放在哪裡
Project 與 Global 兩層規則的分工，以及 CLAUDE.md 的相容與優先順序
本系列的三層規則架構：為什麼我到今天還故意不在專案裡放 AGENTS.md

環境準備

昨天裝好的 opencode（opencode --version 跑得動即可）
一個拿來練習的專案資料夾（別拿公司專案開刀）

# 建一個練習用的沙盒，順便讓它進 git（AGENTS.md 之後要 commit）
mkdir -p ~/playground/agents-lab && cd ~/playground/agents-lab
git init

主要內容

步驟一：第一份 AGENTS.md——讓 /init 代勞

AGENTS.md 是一個約定俗成的檔名：opencode 每次啟動 session 時，會自動把它讀進 LLM 的 context，等於每次開工前先幫 agent 做一次行前簡報。你不必在每個 prompt 裡重複交代「請用繁體中文」「改完先跑測試」——寫一次，永久生效。

最快的上手方式是讓 agent 自己寫。在專案資料夾開 opencode，輸入 /init：

# 進 TUI 後輸入 /init，它會掃過 repo 自動生成（或就地改良）AGENTS.md
opencode
> /init

/init 會掃過 repo 裡的重要檔案，把 agent 最需要知道的東西濃縮成規則：build / lint / test 指令、目錄結構、光看檔名猜不到的專案慣例與坑，必要的時候還會反問你幾個問題。生成之後記得 commit——AGENTS.md 是寫給「未來每一次 session」的交接文件，進版本控制才能被團隊（和被未來的你）共享。不想用 /init，自己手寫也完全沒問題，它就是一份普通的 markdown。

步驟二：兩層規則——Project 與 Global

opencode 會從兩個地方讀規則：

專案層：專案根目錄的 AGENTS.md，只在這個專案（含子目錄）生效，適合放 build 指令、程式碼慣例，跟著 git 走、跟著團隊走
全域層：~/.config/opencode/AGENTS.md，所有 session 都吃得到，適合放個人偏好，例如語言

來揭曉昨天的伏筆：我的全域 AGENTS.md 裡有一條「只用台灣繁體中文或英文」的語言規則，所以任何資料夾裡的 opencode 都自動講台灣繁體中文——就算 prompt 隻字未提。「沒被點名卻自動遵守」的真相是：規則不是不存在，只是你沒看見它被載入。

# 全域規則：所有 opencode session 都會吃到
mkdir -p ~/.config/opencode
$EDITOR ~/.config/opencode/AGENTS.md

# 進階玩法：一份規則檔餵兩套工具（symlink 給 Claude Code 共用）
ln -s ~/.config/opencode/AGENTS.md ~/.claude/CLAUDE.md

順帶處理優先順序。opencode 啟動時，先從目前目錄往上找 AGENTS.md（或 CLAUDE.md），再讀全域的 ~/.config/opencode/AGENTS.md，最後才輪到 Claude Code 的 ~/.claude/CLAUDE.md 當備援。同一層裡 AGENTS.md 和 CLAUDE.md 同時存在時，AGENTS.md 勝出。所以從 Claude Code 遷移過來完全不用刪檔案，放著就相容。

小小小測驗：你知道到今天為止，本系列的專案資料夾裡根本還沒有 AGENTS.md 嗎？不是忘了放，是故意不放。為什麼？看下一步。

步驟三：AGENTS.md 不是冰箱，什麼都塞就完蛋

打開 /Users/benben/ai/automations/ironman/ 數一數，這個系統的規則其實分成三層：

全域 AGENTS.md：語言偏好這種「跨專案永遠為真」的事
prompts/generate.md + templates/article-template.md + outline.md：每天的生成規範，由 generate.sh 的 prompt 明確點名載入（昨天解剖過了）
專案 AGENTS.md：不存在

為什麼任務規則不塞進 AGENTS.md？三個理由：

token 預算：AGENTS.md 每個 session 都常駐注入。把一長串寫作規則放進去，等於每次叫 agent 做任何小事都要付一次全文的錢；由 prompt 點名載入，則是按需付費。
可控性：明確點名載入的規則，就是可測試的輸入。我改一行 generate.md，重跑 generate.sh 就能驗證效果；混在常駐層裡，反而容易跟其他規則互相干擾。
變更頻率：寫作規則還在迭代——d02 就發生過生成被品質判準誤殺、事後調整流程的事。常駐層該放「穩定不變」的規則，會動的集中在一個檔案，改起來才不會牽一髮動全身。

分工原則一句話：常駐的 AGENTS.md 放「每次 session 都對」的事，任務級規則放檔案、由 prompt 點名載入。AGENTS.md 是行前簡報，不是冰箱；什麼都塞的結果，是每一條規則都被稀釋。讀到這裡，你已經比九成使用者更懂「分層」這件事 :D

步驟四：規則檔引用外部檔案的正確姿勢

規則一多，全擠在 AGENTS.md 會很肥。opencode 不會自動解析檔案引用，但官方給了兩個解法。第一，用 opencode.json 的 instructions 欄位，把外部檔案（支援 glob）正式接進來：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["docs/style-guide.md", "packages/*/AGENTS.md"]
}

所有 instructions 會跟你的 AGENTS.md 合併注入，也支援遠端 URL（五秒 timeout），團隊可以把共用規則掛一個 URL 統一管理。第二招是在 AGENTS.md 裡教 agent 自己讀：寫明「看到 @docs/foo.md 就用 read 工具按需載入」，讓它 lazy load，不必每次全讀。

常見問題 / 踩坑記錄

Q：規則寫了一堆，agent 卻挑著遵守？
A：兩個常見原因。第一，context 是有限預算，AGENTS.md 越長，單條規則的存在感越低——寫短、寫具體、放對層級（回顧步驟三的分工）。第二，規則互相矛盾，例如一邊說「先跑測試再改」、另一邊說「直接改快一點」，LLM 遇到矛盾不會報錯，只會擲骰子挑一邊，輸出自然時好時壞。整理時把重複的合併、矛盾的刪掉一邊。
Q：在 AGENTS.md 裡寫 @docs/style.md，agent 根本沒讀？
A：opencode 不會自動解析檔案引用，那對它來說只是普通文字。正解是步驟四的兩招：opencode.json 的 instructions，或在 AGENTS.md 裡明確教它「遇到 @file 引用就用 read 工具載入」。
Q：改了 AGENTS.md，agent 行為卻沒變？
A：規則是 session 啟動當下注入的，開到一半的對話不會自動重讀。新開一個 session（headless 就是重新 opencode run）才吃得到新版。自動化場景更要小心：改完規則記得手動重跑一次驗證，別被舊 session 的記憶騙了。