AGENTS.md 模式：真正改變代理程式行為的寫法

我的第一份 AGENTS.md，是把團隊風格指南整整 200 行原封不動貼上去。裡面有命名慣例、程式碼審查檢查表、部署流程，還有架構原則。代理程式幾乎全部略過。原因不是那些指示寫錯了，而是它們本質上是文件，不是操作規範。

AGENTS.md 應該寫成指令優先的指示，附上確切的呼叫方式、依任務劃分的章節（開發、審查、發布），以及代理程式能自行驗證的明確「完成」標準。 要寫的是操作準則，不是給人看的文件。把代理程式必須執行的 shell 指令、linter 設定與測試指令具體列出來。避免散文式段落、像「小心一點」這類模糊指令，也避免沒有明確排序的互相衝突的優先事項。AGENTS.md 是一項開放標準，已有超過 60,000 個專案採用，並可通用於 Codex、Cursor、Copilot 及其他代理工具。

這個區別，比本文提到的任何單一模式都重要。AGENTS.md 是給 AI 代理程式看的操作準則，不是給人看的 README。代理程式不需要理解您為什麼採用 conventional commits，它需要知道的是該執行哪一條確切指令，以及「完成」長什麼樣子。

TL;DR

大多數 AGENTS.md 的問題，都源自於寫成了給人看的文件，而不是給代理程式看的操作規範。有效的檔案具備三個特徵：指令優先（寫出確切呼叫方式，而非描述）、依任務劃分（開發、審查、發布章節），以及明確定義收尾條件（清楚的「完成」標準）。以下這些反模式必然會被略過：散文式段落、模糊指令（「小心一點」）、互相衝突的優先事項。AGENTS.md 是一項開放標準，已有超過 60,000 個專案採用 ¹，並可通用於 Codex、Cursor、Copilot、Amp、Devin Desktop 等工具 ²。

背景說明： AGENTS.md 由 Linux Foundation 底下的 Agentic AI Foundation 治理 ³，白金會員包含 Anthropic、Google、Microsoft 與 OpenAI。本文談的是實務模式。Codex 專屬的設定請參閱Codex 指南。Claude Code 的對應機制（CLAUDE.md）請參閱Claude Code 指南。

哪些寫法會被略過

以下這些模式，實測後在代理程式的行為上看不出任何改變。我的判斷方式是：同一批任務分別在有無該指示的情況下執行，再比較任務完成的正確率，每種模式至少跑 10 輪。GitHub 分析 2,500 多個含有 AGENTS.md 的儲存庫後也得到同樣結論：「Most agent files fail because they’re too vague」¹¹。以下模式在任何可量測的層面上都沒有提升正確率。

沒有指令的散文段落

<!-- BAD: Agent skips this -->
We value clean, well-tested code. Our team follows TDD principles
and believes in comprehensive test coverage. Please ensure all
changes are properly tested before submitting.

代理程式讀完這段，把它記成一個模糊的偏好，然後照樣寫出沒有測試的程式碼。這裡沒有可執行的指示、沒有要跑的指令、沒有要達到的門檻，也沒有定義什麼叫「充分測試」。

模糊的指令

<!-- BAD: "Careful" means nothing to an agent -->
- Be careful with database migrations
- Optimize queries where possible
- Handle errors gracefully

「小心」不是約束條件，「在可行時」不是觸發條件，「妥善地」也不是行為規格。這些是人對人的建議，不是給代理程式的指示。對照有效的寫法：「套用 migration 前先執行 alembic check。若缺少 downgrade 路徑就中止。」

互相衝突的優先事項

<!-- BAD: Which one wins? -->
- Move fast and ship quickly
- Ensure comprehensive test coverage
- Keep the runtime budget under 5 minutes
- Run the full integration test suite before every commit

這四項不可能同時滿足。當指示彼此衝突又沒有明確的優先順序時，模型會跳過驗證步驟，直接衝去產生程式碼。ICLR 2026 的研究（Ambig-SWE）發現：「without explicit prompting, models almost never interact, even for severely underspecified inputs」，也就是說，代理程式寧可默默做下去，也不會主動提出釐清問題；而在提示它進行互動之後，面對規格不足的任務，表現最多提升 74% ¹²。修正衝突指示的方法是替優先順序編號：「優先序 1：測試通過。優先序 2：控制在 5 分鐘內。優先序 3：快速交付。」

沒有強制手段的風格指南

<!-- BAD: No way to verify compliance -->
Follow the Google Python Style Guide for all code.
Use numpy-style docstrings for public functions.

除非您把用來強制執行風格的確切檢查指令寫進去（ruff check --select D 或 pylint --rcfile=.pylintrc），否則代理程式根本沒有機制驗證自己是否合規。這裡的原則放諸四海皆準：沒有驗證指令的指示，只是建議，不是規則。

哪些寫法確實有效

以下這些模式，能在代理程式的行為上帶來穩定且可量測的改變。

指令優先的指示

## Build and Test Commands
- Install: `pip install -r requirements.txt`
- Lint: `ruff check . --fix`
- Format: `ruff format .`
- Test: `pytest -v --tb=short`
- Type check: `mypy app/ --strict`
- Full verify: `ruff check . && ruff format --check . && pytest -v`

指令沒有模糊空間。代理程式清楚知道要跑什麼、要帶哪些參數，也能靠檢查結束碼確認是否成功。AGENTS.md 裡的每一條指示，都應該能回答這個問題：「有哪一條指令能證明這件事做對了？」

收尾條件的定義

## Definition of Done
A task is complete when ALL of the following pass:
1. `ruff check .` exits 0
2. `pytest -v` exits 0 with no failures
3. `mypy app/ --strict` exits 0
4. Changed files have been staged and committed
5. Commit message follows conventional format: `type(scope): description`

明確的收尾定義能消除最常見的失敗模式：代理程式沒驗證就回報「完成」。當「完成」被定義成特定的結束碼，代理程式就會在回報前逐項執行檢查。少了這個定義，「完成」的意思就變成「我覺得我做完了」，而這正是代理程式引入 bug 的常見來源。

依任務劃分的章節

## When Writing Code
- Run `ruff check .` after every file change
- Add type hints to all new functions
- Test command: `pytest tests/ -v -k "test_<module>"`

## When Reviewing Code
- Check for security issues: `bandit -r app/`
- Verify test coverage: `pytest --cov=app --cov-fail-under=80`
- List changed files: `git diff --name-only HEAD~1`

## When Releasing
- Update version in `pyproject.toml`
- Run full suite: `pytest -v && ruff check . && mypy app/`
- Tag: `git tag -a v<version> -m "Release v<version>"`

依任務劃分的檔案，能讓代理程式根據當下在做的事挑出相關指示。扁平的清單則逼它不分情境地解析每一條指示。「When…」這個開頭，正好對應代理程式推理任務情境的方式。

呈報規則

## When Blocked
- If tests fail after 3 attempts: stop and report the failing test with full output
- If a dependency is missing: check `requirements.txt` first, then ask
- If you encounter merge conflicts: stop and show the conflicting files
- Never: delete files to resolve errors, force push, or skip tests

少了呈報規則，代理程式一旦卡住，就會採取越來越有創意的迂迴手段：刪掉 lock 檔、繞過檢查，或是默默忽略失敗。那份「Never」清單和呈報路徑一樣重要。明文禁止破壞性的補救手法，才能擋掉最糟的失敗情境。

Monorepo 的目錄範圍

AGENTS.md 支援階層式的範圍劃分，這是規格的核心功能之一 ²。離工作目錄越近的檔案，優先權越高：

/repo/AGENTS.md                        ← Project-wide rules
  └─ /repo/services/AGENTS.md          ← Service defaults
      ├─ /repo/services/api/AGENTS.md  ← API-specific rules
      └─ /repo/services/web/AGENTS.md  ← Frontend-specific rules

根目錄層級的指示會與更深層的檔案串接在一起。Codex 會從專案根目錄一路走到目前的工作目錄，把沿途找到的每一份 AGENTS.md 組合起來 ⁴；而規格本身定義的是最近檔案優先，因此其他工具解析階層的方式可能不同 ²。OpenAI 自家的 codex 儲存庫就是這麼做的：它在根層檔案底下另外放了一份巢狀的 AGENTS.md ⁴。

在 Codex 中，您還可以在任何層級放置 AGENTS.override.md，用來取代（而非擴充）上層指示 ⁴。這個 override 機制是 Codex 專屬的，其他工具並未實作。

<!-- /repo/services/payments/AGENTS.override.md (Codex only) -->
# Payment Service Rules (OVERRIDE)

This service has additional security requirements.
All changes require: `bandit -r . -ll` passing with zero findings.
No dependency updates without explicit approval.
Test with: `pytest -v --tb=long -x` (fail fast, full tracebacks)

什麼時候該用 override： 發布凍結期、事故處理模式，或是任何安全性要求高於專案通用預設的服務。

跨工具相容性

AGENTS.md 已有超過 60,000 個專案採用 ¹，各大 AI 編碼工具也都認得它。同一份檔案在不同生態系中的行為如下（此表於 2026 年 8 月核實）：

如果團隊同時使用多種工具： 把 AGENTS.md 寫成唯一的正典來源，再加上工具專屬檔案（CLAUDE.md、.cursorrules），讓它們匯入或鏡射相關章節。切勿維護兩套會逐漸走樣的平行指示。

撰寫順序：先寫什麼

如果您要從零寫一份 AGENTS.md，請依這個優先順序加入章節，每一層都建立在前一層之上：

1. 建置與測試指令，代理程式得先有這些才能做任何有用的事
2. 完成的定義，避免「我覺得我做完了」這種假性完成
3. 呈報規則，避免代理程式卡住時採取破壞性的迂迴手段
4. 依任務劃分的章節，減少每項任務解析到無關指示的比例
5. 目錄範圍劃分（僅限 monorepo），讓各服務的指示彼此隔離

在前四項都運作良好之前，先別碰風格偏好。多數 AGENTS.md 之所以失敗，正是因為它們從風格指引開始寫，然後永遠寫不到指令。

測試您的 AGENTS.md

驗證代理程式是否真的讀了、也照著您的指示做：

# Codex: Show the full instruction chain
codex --ask-for-approval never "Summarize your current instructions"

# Codex: Generate a scaffold (slash command inside an active session)
# Type /init at the Codex prompt, not as a shell command
codex  # then type: /init

# Claude Code: Check active instructions
claude --print "What instructions are you following for this project?"

# Verify specific rules are active
codex --ask-for-approval never "What is your definition of done?"

關鍵測試： 請代理程式說明您的建置指令。如果它無法一字不差地複述出來，代表指示沒有被讀進去，或是太冗長而留不住上下文。過長的 AGENTS.md 會被上下文視窗截斷，因此每個章節請控制在 50 行以內，並把最關鍵的指示放在最前面。

常見問題

AGENTS.md 檔案應該多長？

我的經驗法則是：每個章節控制在 50 行以內，整份檔案不超過 150 行。背後的原則來自 Marmelab 的 agent experience 指引，該文主張這份檔案應該保持「short and to the point」，因為代理程式每次工作階段一開始就會讀它 ¹³；至於具體的行數則是我自己的標準，不是他們的。Codex 預設強制 32 KiB 的上限（project_doc_max_bytes）⁴。過長的檔案會被上下文視窗截斷，所以請把最關鍵的指示、指令與收尾定義放在風格偏好之前。

AGENTS.md 會取代工具專屬的指示檔案嗎？

不會。AGENTS.md 與 CLAUDE.md、.cursor/rules 及其他工具專屬檔案是並存的。請把 AGENTS.md 寫成正典來源，再把相關章節鏡射到工具專屬檔案。AGENTS.md 裡的這些模式（指令優先、明確定義收尾），放在任何工具的任何指示檔案裡都同樣適用。

如果代理程式無視我的 AGENTS.md 怎麼辦？

測試方法是請代理程式說明您的建置指令。如果它無法一字不差地複述，代表這份檔案不是太冗長（內容被擠出上下文），就是太模糊（代理程式抽不出可執行的指示），再不然就是根本沒被找到（請檢查檔案位置與工具文件）。GitHub 分析 2,500 多個儲存庫後也發現，多數代理指示檔案失敗的原因就是太過模糊 ¹¹。

重點整理

對個人開發者：

• 用指令取代散文。每一條指示都應該能靠執行某個東西來驗證。
• 明確定義收尾條件。「完成」指的是特定的結束碼，不是感覺。
• 請代理程式把 AGENTS.md 背一遍，藉此測試它。它背不出來的，就不會照做。

對團隊：

• 把 AGENTS.md 當成唯一的事實來源。鏡射到工具專屬檔案，而不是維護平行副本。
• 依任務（開發、審查、發布）而非依類別（風格、測試、部署）來組織內容。
• 記得寫呈報規則。少了它們，卡住的代理程式會用您不會喜歡的方式即興發揮。
• 在 monorepo 中依目錄劃分範圍。個別服務的規則不該汙染全域指示。

參考資料