AGENTS.md 模式：哪些真正改變了代理行為

我的第一個 AGENTS.md 是一份200行的團隊風格指南貼上。它包含命名慣例、程式碼審查清單、部署程序和架構原則。代理忽略了其中大部分。不是因為指令有誤——而是因為它們是文件，不是操作。

這個區別比本文中任何特定模式都更重要。AGENTS.md 是給 AI 代理的操作策略，不是給人類的 README。代理不需要理解為什麼您使用約定式提交。它需要知道要執行的確切指令，以及「完成」是什麼樣子。

TL;DR

大多數 AGENTS.md 問題源於撰寫了人類文件而非代理操作。有效的檔案是以指令為先（確切的呼叫方式，而非描述）、以任務組織（編碼、審查、發布區段），以及定義明確的完成標準（明確的「完成」準則）。可靠地被忽略的反模式包括：散文段落、含糊的指示（「要小心」），以及矛盾的優先順序。AGENTS.md 是一個被超過60,000個專案採用的開放標準 ¹，可跨 Codex、Cursor、Copilot、Amp、Windsurf 等工具運作 ²。

背景： 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 檔案的儲存庫分析得出相同結論：「大多數代理檔案失敗是因為它們太模糊——不是因為技術限制」¹¹。以下模式在任何可衡量的方面都未能提高準確率。

沒有指令的散文段落

<!-- 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

「小心」不是約束條件。「盡可能」不是觸發條件。「優雅地」不是行為規格。這些讀起來像是人對人的指導，而非代理指令。與有效的做法相比：「在套用遷移之前執行 alembic check。如果缺少降級路徑則中止。」

矛盾的優先順序

<!-- 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）發現代理「在沒有明確鼓勵的情況下預設採用非互動行為」——靜默地繼續而非提出澄清問題，這使解決率從48.8%降至28% ¹²。透過編號優先順序來修正衝突的指令：「優先順序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.

除非您包含強制執行該風格的確切 lint 指令（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`

明確的完成定義消除了最常見的失敗模式：代理在未驗證的情況下回報「完成」。當「完成」被定義為特定的退出碼時，代理會在回報完成前執行每項檢查。如果沒有這個定義，「完成」意味著「我認為我完成了」——這是代理引入錯誤的常見來源。

以任務組織的區段

## 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

如果沒有升級規則，代理在受阻時會預設採用越來越有創意的變通方法——刪除鎖定檔案、繞過檢查，或靜默地忽略失敗。「永不」清單與升級路徑同樣重要。明確禁止破壞性恢復模式可以防止最糟糕的失敗模式。

單體儲存庫的目錄範圍界定

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

根層級指令與更深層的檔案串聯。工具從專案根目錄走訪到當前工作目錄，合併沿路徑找到的每個 AGENTS.md ⁴。OpenAI 自己的 Codex 儲存庫為其單體儲存庫使用了88個獨立的 AGENTS.md 檔案——每個服務和套件各一個 ⁴。

在 Codex 中，您也可以在任何層級使用 AGENTS.override.md 來取代（而非延伸）上層指令 ⁴。覆寫機制是 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)

何時使用覆寫： 發布凍結、事件模式，或任何具有超越專案範圍預設值的安全約束的服務。

跨工具相容性

AGENTS.md 被超過60,000個專案採用 ¹，並被每個主要 AI 編碼工具識別。以下是相同檔案在各生態系中的行為：

如果您的團隊使用多種工具： 將 AGENTS.md 作為權威來源。新增工具特定的檔案（CLAUDE.md、.cursorrules），它們匯入或映射相關區段。不要維護會逐漸分歧的平行指令集。

撰寫順序：首先新增什麼

如果您從頭撰寫 AGENTS.md，請按此優先順序新增區段。每一層都建立在前一層之上：

1. 建置和測試指令 ——代理在能做任何有用的事之前需要這些
2. 完成定義 ——防止「我認為我完成了」的虛假完成
3. 升級規則 ——防止代理卡住時的破壞性變通方法
4. 以任務組織的區段 ——減少每個任務的不相關指令解析
5. 目錄範圍界定（僅限單體儲存庫）——保持服務指令的隔離

在前四項運作之前，跳過風格偏好。大多數 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行以內 ¹³。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 作為唯一的真實來源。映射到工具特定的檔案，不要維護平行副本。
• 按任務組織（編碼、審查、發布），而非按類別（風格、測試、部署）。
• 包含升級規則。如果沒有，受阻的代理會以您不會喜歡的方式即興發揮。
• 在單體儲存庫中按目錄界定範圍。服務特定的規則不應汙染全域指示。

參考文獻