一份 AGENTS.md 給三個 AI 命令列工具：Codex CLI、Gemini CLI 和 Claude Code

想像你同時請了三個家教，教同一個小孩。三個都很厲害，但每個人習慣不一樣：一個會自己去翻你留在桌上的注意事項，一個要你明講「桌上有一張紙你看一下」，一個會看紙但只看你貼在冰箱上的那張。如果你想讓三個人教出同一套規矩，你會怎麼做？

答案大概不是寫三張紙。是寫一張，然後在冰箱上、桌上、門口各貼一張小紙條寫「規矩在那張紙上」。

在終端機裡用 AI 寫程式的工具現在有三個常見選擇：OpenAI 的 Codex CLI、Google 的 Gemini CLI、Anthropic 的 Claude Code。前兩個是 Apache-2.0 的開源專案，第三個不是。同一個專案輪流用它們的時候，第一個問題就是：專案的規則寫在哪裡，才不會每個工具拿到不同版本？

三個工具讀的檔案不同

Codex CLI 原生讀 AGENTS.md，這是 2025 年幾家公司一起推的開放慣例，檔案格式就是 Markdown，沒有什麼特殊語法，你想怎麼寫就怎麼寫。Gemini CLI 預設讀 GEMINI.md，但可以在專案的 .gemini/settings.json 裡把要讀的檔名改成 AGENTS.md。Claude Code 讀 CLAUDE.md。

我的做法是規則只寫在 AGENTS.md，把它當唯一的真實來源。CLAUDE.md 和 GEMINI.md 都只是薄薄的指標，第一行寫「讀 AGENTS.md」，後面只補那個工具特有的一兩件事。改規則一律改 AGENTS.md，否則其他工具會拿到過期的指示。

這種錯很難發現，因為每個工具都在乖乖照著自己那份做，沒有人會報錯。你只會在某天發現某個工具寫出來的東西「怪怪的」，追了半天才發現它讀的是三個星期前的規則。就像三個家教裡有一個一直在教舊版的課綱，小孩沒說，因為小孩以為那就是對的。

能力的差異

同樣一套規則，三個工具執行的方式不同，值得知道哪些是自動的、哪些要人推一下。

記憶層，也就是專案規則和慣例：三個都會自動讀指示檔。這一層沒有問題，紙條貼對地方就好。

知識層，也就是可重用的技能文件：Claude Code 會依描述自動載入，Gemini 和 Codex 要在對話裡明講「讀這個檔」。所以同一份技能文件，在一個工具裡是背景知識，在另外兩個裡是你要記得提醒的事。

護欄層，也就是寫完一段內容自動跑檢查器：Claude Code 有 hook，可以在工具呼叫前後自動攔截；Gemini 和 Codex 沒有對應機制，檢查器要人手動跑，或者寫進規則裡要求它自己跑。這一層的差異最大，因為「自動攔截」和「規則裡寫著要跑」是兩種完全不同的可靠度。前者是門口的警衛，後者是牆上的告示。

委派層，也就是把一個子任務交給另一個代理：Claude Code 有真正的子代理；另外兩個等價的做法是開一個新對話。

這四層的差異決定了 AGENTS.md 要寫得多明確。在 Claude Code 裡靠 hook 自動發生的事，在另外兩個工具裡要寫成規則裡的一個步驟，並且假設它有時會被忘記。

規則怎麼寫才對三個都有效

寫成可以檢查的句子，不寫成期望。「每次改完執行 tools/check.py，未通過不得提交」比「注意品質」有用得多，因為前者三個工具都能照做，後者三個工具會各自詮釋，而且三個詮釋都不會是你想的那個。

把工序寫成順序，把底線寫成清單，把不能做的事寫得比能做的事更具體。「不要」比「要」好寫也好檢查，因為「要」有無限種做法，「不要」只有一種違反方式。

架構跟作品分開。規則、工序、檢查器放在架構層，跨專案共用；每個具體專案只放它自己的設定。做第二個專案的時候，架構層一個檔案都不用改，你只是換了一個小孩，三個家教還是同一套規矩。

小劇場：為什麼要同時用三個

「你為什麼不挑一個用就好？三個很累吧。」

「每個都有擅長的事。有的很會找 bug，有的寫長篇東西比較穩，有的便宜。」

「那規則寫三份不就好了？」

「三份會分岔。第一天一樣，第十天就不一樣了，第三十天你會不知道哪一份是對的。」

「所以你寧可花時間搞這個 AGENTS.md 的架構。」

「花一次時間搞架構，之後每次改規則只改一個地方。這筆帳很好算。」

「聽起來像是你在管理員工。」

「有時候我覺得我在當一個小型公司的人資，而員工都不會累，只會忘記。」

我對這件事的看法

三個工具都會進步，能力差異幾個月後可能就不一樣，今天要手動的事明天可能就自動了。不變的是那個原則：規則只有一份，其他都是指標。這跟寫程式時避免重複邏輯是同一件事，只是這次重複的是給 AI 看的文字。

回到三個家教。最好的情況不是三個人都變成一樣的人，是三個人都讀同一張紙，然後各自用自己擅長的方式教。紙只有一張，這件事比什麼都重要。

這三個工具是怎麼在一年內冒出來的

2025 年是這類工具爆發的一年。Claude Code 在 2 月以研究預覽的形式出現，Codex CLI 在 4 月開源，Gemini CLI 在 6 月開源，三個都是「在終端機裡跟 AI 一起寫程式」，三個都能讀你的檔案、跑你的指令、改你的程式碼。半年前這種東西還是聊天視窗裡的貼上貼下，半年後它們住進了終端機。

AGENTS.md 這個慣例是 2025 年 8 月推出來的，網站就叫 agents.md，背後是 OpenAI 和幾間公司。它的想法很簡單：與其每個工具發明自己的指示檔格式，不如大家讀同一個檔名。Markdown，沒有 schema，沒有特殊語法，就是一份給 AI 看的 README。Codex 原生支援，Gemini 可以設定，Claude Code 目前還是讀自己的檔名，所以指標檔那一招現在還需要。

指示檔這個概念比工具老。README 是給人看的，.editorconfig 是給編輯器看的，CONTRIBUTING.md 是給貢獻者看的，現在多一份給 AI 看的，其實是同一個傳統的延伸：把「這個專案怎麼運作」寫在專案裡，而不是某個人的腦袋裡。

常見的三個誤會

第一個誤會是「指示檔寫越長越好」。太長的指示檔會被工具截斷或忽略，而且人也不會維護。寫規則，不寫教學；寫「要做什麼」，不寫「為什麼這個語言很棒」。

第二個誤會是「AI 會嚴格遵守指示檔」。它會盡力，但它會忘、會誤解、會在長對話後面漂移。指示檔是提高機率，不是保證。真的不能錯的事，要有工具層的檢查，例如 hook 或提交前的腳本，不能只靠一句「請務必」。

第三個誤會是「三個工具的差異會一直存在」。它們每個月都在互相追趕，今天只有 A 有的功能，下個月 B 大概也會有。所以指示檔要寫成工具無關的規則，工具特有的東西放在那個薄薄的指標檔裡，換工具的時候只換那一頁。

一個週末可以試的小練習

找一個你自己的小專案，寫一份 AGENTS.md，只寫三條規則，每一條都要是可以檢查的：例如「所有 Python 檔案要通過 ruff check」、「不要修改 data/ 目錄下的任何檔案」、「每次改完程式跑 python -m unittest」。再寫兩個指標檔 CLAUDE.md 和 GEMINI.md，各一行「規則在 AGENTS.md」。

然後用你手上有的任何一個 AI 命令列工具開一個對話，請它做一個會違反其中一條規則的小改動，例如「幫我在 data/ 裡加一個檔案」。看它會不會拒絕、會不會提醒你、還是直接做了。三個工具都試的話你會得到三種反應，那三種反應就是這篇講的「能力差異」的現場版。這半小時比讀任何比較文章都能讓你知道自己在跟什麼東西合作。

後記

三個家教的比喻，我後來想到一個沒講的地方：家教會走，小孩會長大。這些工具明年大概會長得很不一樣，甚至可能不叫這些名字。但那張紙不會變，因為紙上寫的是「這個專案怎麼運作」，那是你的東西，不是工具的東西。把力氣花在紙上，工具換幾次都沒關係。這大概是我在這一年的工具爆發裡，唯一敢說會一直對的話。

專案頁面：github.com/openai/codex、github.com/google-gemini/gemini-cli、agents.md