AGENTS.md 與 HUMAN.md：用途、差異與範本

AGENTS.md 的用途

AGENTS.md 是位於儲存庫根目錄的純 Markdown 檔案，用來告知 coding agent 如何處理該專案。官方網站將其描述為「供 agent 使用的 README：提供專屬且固定的位置，讓您提供協助 AI coding agent 處理專案所需的背景資訊和指示。」此格式由 Linux Foundation 旗下的 Agentic AI Foundation 維護。截至 2026 年 7 月，已有超過 20 個 agent 讀取此檔案，包括 Codex、Cursor、Jules、Devin 和 GitHub Copilot。

這項慣例存在的原因很實際。團隊的新成員會閱讀 README，猜測建置命令；猜錯時，再向他人詢問。Agent 無法提問。它會猜測，在使用 pnpm test 的專案上執行 npm test，讀取失敗結果，然後嘗試其他方式。每次嘗試都會消耗 token。只要將正確命令記錄一次，就能消除整類失敗。

沒有任何必填欄位。網站明確說明：「AGENTS.md 就是標準 Markdown。您可以使用任何偏好的標題；agent 只會解析您提供的文字。」這就是完整規格。其價值不在格式，而在於檔案位於每個工具都會檢查的路徑。

檔案放置位置與優先採用的檔案

將第一個檔案放在 repository 根目錄。在 monorepo 中，您可以在各個子專案內加入更多檔案，規則很簡單：「agents 會自動讀取目錄樹中最近的檔案，因此距離最近的檔案優先。」兩個檔案發生衝突時，以正在編輯的檔案所在位置為準；您在聊天中輸入的任何內容都會覆寫這兩個檔案的設定。

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

使用巢狀結構很有價值，因為這是表達某項規則在一個資料夾中成立、在下一個資料夾中不成立的唯一方式。「每個 endpoint 都會驗證輸入」這類規則應放在 endpoint 旁邊。若放在根目錄檔案中，該規則會載入到所有不相關的工作，沒有任何效益。

AGENTS.md 應包含的內容

記錄代理程式無法透過閱讀程式碼自行判斷的事項。先列出確切的建置、測試和 lint 指令，格式要能直接貼到終端機執行。也要加入執行單一測試的指令，因為只知道如何執行完整測試套件的代理程式，可能會把完整測試套件執行 40 次。列出不同於工具預設值的慣例，因為代理程式已經知道預設值，只需要知道你的例外規則。如果有提交訊息格式和 pull request 規則，也一併說明。

內容要具體到可以驗證。例如，「使用 2 個空格縮排」是可用的指示，因為可以確認是否確實如此。「正確格式化程式碼」則不可用，因為無法驗證其中的具體要求。位置說明也是如此：「API 處理常式位於 src/api/handlers/」優於「維持檔案組織良好」。

負面規則同樣值得記錄。「絕不編輯 dist/ 下的檔案，這些檔案由 npm run build 產生」可以避免一項特定錯誤。由於其中說明了原因，代理程式也能推導出未明確記載的相同情況。

絕不應放入其中的內容

絕對不要將機密資訊放入這些檔案。檔案會提交至 git、在每次工作階段開始時載入至內容中，並在每次請求時傳送給模型提供者。放在 AGENTS.md 中的 API key，也會出現在儲存庫歷程記錄和第三方的日誌中。請指向機密資訊的位置，不要直接貼上：「資料庫密碼位於 .env，該檔案已列入 gitignore；讀取前請先詢問。」更廣泛的規範請參閱讓認證資訊不在代理程式可存取的範圍內。

代理程式只要查看即可推導出的內容，都不要放入。貼上的目錄清單、複製的相依性清單、僅重述資料夾名稱的架構概覽：這些內容在撰寫後一週就會過時，同時卻會在每個工作階段消耗內容空間。保留陷阱及其原因。刪除清單。

CLAUDE.md 是 Claude Code 對應的相同概念

Claude Code 會讀取 CLAUDE.md，不會自行讀取 AGENTS.md。專案檔案位於 ./CLAUDE.md 或 ./.claude/CLAUDE.md；適用於每個專案的個人偏好設定放在 ~/.claude/CLAUDE.md；在 Linux 上，組織可以將全機器檔案推送至 /etc/claude-code/CLAUDE.md。系統會從檔案系統根目錄一路到工作目錄，依序串接所找到的檔案，因此距離啟動工作階段位置最近的檔案最後讀取。

如果您的儲存庫已經有 AGENTS.md，請不要維護第二份副本。請匯入它，然後只加入 Claude 專用的內容：

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

如果沒有其他內容要加入，可以使用符號連結：

ln -s AGENTS.md CLAUDE.md

成功時，此命令不會輸出任何內容。在下一個工作階段執行 /context，並確認 CLAUDE.md 出現在 Memory files 下方。如果該檔案不在清單中，表示檔案從未載入，因此其中的內容也未生效。若要產生初稿而不是手動撰寫，請執行 /init：它會讀取程式碼庫並產生起始檔案；如果 CLAUDE.md 已經存在，則會提出改進建議，而不會覆寫檔案。

每個檔案請控制在約 200 行以內。檔案過長會消耗更多上下文視窗，遵循程度也會下降。如果您想了解還有哪些內容會佔用這個空間，實際填滿代理程式上下文視窗的內容會逐項說明。

有一點需要特別強調。AGENTS.md 是指引，不是權限系統。其內容會以一般上下文的形式提供，因此模型會讀取並通常遵守，但它無法阻止違反指引的操作。對於每次都必須遵守的規則，例如「絕不推送至 main」，請使用 hook 或權限設定，因為這些機制以程式碼執行，不依賴模型自行決定是否遵守。

會替您寫入這些檔案的工具

2026 年 7 月 30 日 GitHub 趨勢榜上的 2 個專案，顯示了這項慣例的發展方向。

agent0ai/dox（截至 2026 年 7 月有 1,368 顆 stars）是一個用來維護 AGENTS.md 檔案樹的框架。它不提供套件，也不需要執行階段環境。您只需將其中 AGENTS.md 的內容複製到自己的根目錄 AGENTS.md，這就是安裝方式。對於已存在的專案，您可以告訴您的代理程式：

Initialize DOX tree for this project now.

接著，代理程式會建立子層級 AGENTS.md 檔案及其索引，在進行任何編輯前巡覽該檔案樹，並在變更完成後更新受影響的文件。其核心理念是：代理程式在執行工作時順帶維護的文件能保持正確，而由人員手動更新的文件則不然。

HUMAN.md，將相同技巧套用至使用者

Intuition-Lab/personal-model（截至 2026 年 7 月有 1,260 顆星）將這種模式套用至個人，而不是儲存庫。該專案將 HUMAN.md 定義為系統的輸出，而不是由您手動輸入的檔案：「目前重要事項、您通常如何做決策，以及注意力正移向何處的動態模型。」它可在 macOS 13 或更新版本上於本機執行。您授予 macOS 權限後，它會擷取活動，並透過 MCP（model context protocol）將結果提供給代理程式。簡短的安裝方式如下：

uv tool install personal-model
persome onboard
persome model open --after 30

若要取得大部分效益，您不需要使用上述工具。手寫的 HUMAN.md 約 20 行，內容包括您的角色、時區、實際使用的技術堆疊、已經做出的決策及不希望重新討論的事項，以及希望收到多少說明。它所省下的重複說明，與專案檔案所省下的相同，只是位於更高一層。

有一點需要注意。HUMAN.md 是個人設定檔，因此本質上包含敏感資訊。請勿將它放入公開儲存庫。請將它放在 ~/.claude/CLAUDE.md，或放在專案根目錄中已由 gitignore 排除的 CLAUDE.local.md；該檔案會與已提交的檔案一同載入，並以相同方式處理。

可複製的入門範本

這份範本刻意保持簡短。刪除不適用的區段，並避免加入無法持續更新的內容。

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

先寫下來，再直接在原處修正。當你在聊天中對相同內容輸入第2次修正時，就表示應該將該行加入檔案。這項規則能讓檔案持續實用，也能避免檔案逐漸膨脹成沒有人會讀取的文件，包括機器在內。內容穩定後，檔案會隨 repository 一起保存；當 agent 在筆記型電腦以外的位置執行時，這一點最為重要：在自己的 server 上執行 coding agent涵蓋該設定。

FAQ

AGENTS.md 與 CLAUDE.md 是相同的檔案嗎？

它們是相同概念的兩個檔名。Claude Code 會讀取 CLAUDE.md，除非建立連結，否則會忽略 AGENTS.md。請保留一個檔案作為唯一事實來源，並將另一個檔案連結至該檔案。您可以在 CLAUDE.md 頂端加入內容為 @AGENTS.md 的一行，或使用 ln -s AGENTS.md CLAUDE.md。若分別維護兩份完整副本，通常不到一個月就會產生差異。

撰寫 AGENTS.md 是否能保證代理程式遵循其中內容？

不能。檔案內容會作為上下文提供，因此模型會讀取並通常遵循其中指示，但沒有任何機制能阻止模型執行與其矛盾的操作。模糊的指示最不容易被可靠遵循，而兩個檔案提供相反指示時，代理程式可能任意選擇其中一個。對於每次都必須成立的規則，請使用 hook 或權限規則。無論模型如何決定，這些規則都會由用戶端強制執行。

AGENTS.md 是否應提交至 git？

是，凡是專案相關的固定資訊都應提交，例如建置命令、配置和慣例。這正是該檔案的用途，因為團隊成員的代理程式之後都會以與您的代理程式相同的上下文開始。個人資訊或特定於單一機器的內容，應放在獨立且列入 gitignore 的檔案中；憑證則不應放在這兩者之中。

HUMAN.md 是什麼？我需要建立一個嗎？

HUMAN.md 是描述個人的機器可讀設定檔，而不是描述專案的檔案。其中包含您的角色、限制，以及已經確定的決策，避免每次工作階段重新討論這些事項。開始使用不需要任何工具：在使用者層級的指示檔案中手寫 20 行內容，就能取得大部分效益。請將其視為個人資料，並避免將它放入您要推送的任何儲存庫。