AGENTS.md 與 HUMAN.md 使用指南：AI 代理設定教學

什麼是 AGENTS.md

AGENTS.md 是一個位於儲存庫根目錄的純 Markdown 檔案，用於指導程式碼代理（coding agent）如何處理該專案。官方網站將其描述為「代理程式的 README：一個專屬且可預測的位置，提供背景資訊與指令，協助 AI 程式碼代理在您的專案上運作」。此格式由 Linux Foundation 下的 Agentic AI Foundation 所管理，截至 2026 年 7 月，已有超過 20 種代理程式支援讀取該檔案，包括 Codex、Cursor、Jules、Devin 與 GitHub Copilot。

此慣例的存在具有實務意義。團隊中的新成員會閱讀 README，猜測建置指令，並在猜錯時詢問他人。但代理程式無法詢問。它會進行猜測，在一個使用 pnpm test 的專案上執行 npm test，讀取錯誤訊息，然後嘗試其他方法。您必須為這些消耗的 token 付費。將正確的指令寫下來一次，即可消除這類錯誤。

此檔案沒有必填欄位。官方網站明確指出：「AGENTS.md 只是標準的 Markdown。您可以使用任何標題；代理程式只會解析您提供的文字。」這就是完整的規格。其價值不在於格式，而在於該檔案位於所有工具皆會自動檢視的路徑上。

檔案存放位置與優先順序

將第一個檔案放置於儲存庫根目錄。在單一儲存庫（monorepo）中，您可以在每個子專案內新增更多檔案，規則很簡單：「代理程式會自動讀取目錄樹中最近的檔案，因此最接近的檔案具有優先權。」若兩個檔案發生衝突，則以正在編輯的檔案為準，且您在對話中輸入的任何內容都會覆蓋上述兩者。

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

使用巢狀結構是值得的，因為這是唯一能針對特定資料夾設定規則的方法，讓規則在該資料夾內生效，而在其他資料夾則不適用。例如「每個端點皆須驗證輸入」這類規則，應放置於端點旁。若放在根目錄檔案中，它會在每個不相關的任務中載入，毫無效益。如果您的根目錄檔案已經針對每個服務擴充出獨立區段，將其拆分為巢狀配置即為解決方案，這涵蓋了哪些規則應下移，以及哪些規則應保留在頂層。

AGENTS.md 應包含的內容

請記錄代理程式無法透過閱讀程式碼得知的資訊。首先列出建置、測試與檢查語法的指令，格式應與直接貼入終端機執行的一致。請務必加入執行單一測試的指令，因為若代理程式只知道執行完整測試套件，它會重複執行四十次。請列出與工具預設值不同的慣例，因為代理程式已預設知曉標準規範，僅需了解您的特殊調整。若有規定，請加入提交訊息（commit message）的格式與合併請求（pull request）規則。

說明必須具體，以便驗證是否達成。例如「使用 2 空格縮排」是可執行的指令，因為結果非對即錯；而「妥善格式化程式碼」則無法驗證。位置說明亦同：「API 處理常式位於 src/api/handlers/」優於「保持檔案整潔」。

負面規則同樣重要。例如「切勿編輯 dist/ 下的檔案，它們由 npm run build 自動產生」能防止特定錯誤，且因明確指出原因，代理程式能自行推論出您未提及的類似情況。關於範圍的規則也應包含在此，因為若任由代理程式自行判斷，它可能會修改超出您要求的範圍：一項廣泛採用的技巧是堅持僅進行能達成目標的最小變更。

不應放入檔案的內容

切勿將機密資訊放入這些檔案中。該檔案會被提交至 git，在每次工作階段開始時載入至上下文，並在每次請求時傳送給模型供應商。若將 API key 寫入 AGENTS.md，該金鑰就會留在儲存庫歷史紀錄以及第三方的日誌中。請改為指向該機密而非直接貼上，例如：「資料庫密碼位於 .env，該檔案已加入 gitignore；讀取前請先詢問。」更廣泛的規範請參閱 讓憑證遠離代理程式的存取範圍。

省略代理程式可透過觀察自行推導出的內容。例如貼上的目錄列表、依賴套件清單的副本，或是僅重述資料夾名稱的架構概覽：這些內容在撰寫後一週內就會過時，且在此期間會持續佔用每次工作階段的上下文空間。請保留陷阱與原因說明，並捨棄清單內容。將原因獨立出來是有價值的，因為若代理程式無法理解為何存在特殊的架構設計，可能會在重構時將其移除，這正是需要 在該檔案旁放置 DESIGN.md 的原因。

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/`.

當您沒有額外內容要新增時，可以使用符號連結（symlink）：

ln -s AGENTS.md CLAUDE.md

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

請將每個檔案控制在約 200 行以內。檔案過長會佔用更多視窗空間，且遵循度會下降。如果您想了解還有什麼內容會競爭該空間，代理程式內容視窗的實際佔用分析 提供了詳細說明。

有一點值得強調。AGENTS.md 是指引，而非權限系統。內容會以一般上下文形式傳入，因此模型會讀取並通常會遵守，但沒有任何機制能阻擋與其衝突的操作。當您撰寫的規則被默默忽略且無法得知原因時，請在第三次重寫語句前，先排查 指令被忽略的原因。對於必須每次都嚴格執行的規則（例如「禁止推送到 main」），請使用 hook 或權限設定，因為這些是以程式碼形式執行，不依賴模型是否決定遵守。

自動產生這些檔案的工具

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

agent0ai/dox（截至 2026 年 7 月擁有 1,368 顆星）是一個用於維護 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 大約只需二十行：包含您的角色、時區、您實際使用的技術堆疊、您已做出且不希望重新討論的決策，以及您希望獲得的解釋程度。它與專案檔案節省重複說明的作用相同，只是層級更高。

一個提醒。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.

先寫下內容，再原地修正。若您在對話中針對同一行輸入兩次修正，即代表該行需要新增。這項規則能確保檔案維持實用性，並防止檔案膨脹成無人閱讀（包含機器）的文件。一旦檔案穩定，請將其隨儲存庫一併移動；當代理程式在您的筆記型電腦以外的環境執行時，這點尤為重要：在自有伺服器上執行程式碼代理程式 涵蓋了該設定方式。

FAQ

AGENTS.md 與 CLAUDE.md 是同一個檔案嗎？

它們是基於相同概念但檔名不同的檔案。Claude Code 會讀取 CLAUDE.md，除非您手動連結，否則會忽略 AGENTS.md。請將其中一個檔案作為唯一事實來源（source of truth），並將另一個檔案連結至該處；您可以在 CLAUDE.md 的開頭加入一行 @AGENTS.md，或是使用 ln -s AGENTS.md CLAUDE.md。若同時維護兩份完整副本，一個月內兩者內容就會產生分歧。

撰寫 AGENTS.md 能保證代理程式一定會遵守嗎？

不能。內容是以上下文（context）形式傳遞，模型會讀取並通常會遵守，但沒有機制能阻擋與其衝突的操作。模糊的指令最難被可靠執行，若兩個檔案提供相反的指引，代理程式會隨機選擇其中一個。若有必須嚴格遵守的規則，請使用 hook 或權限規則，這些機制由客戶端強制執行，不受模型決策影響。

AGENTS.md 應該提交到 git 嗎？

是的，任何關於專案的真實資訊都應該提交，例如建置指令、目錄結構與開發規範。這正是該檔案的目的，能確保團隊成員的代理程式在開始時擁有與您相同的上下文。任何個人化或特定於單一機器的設定應放在另一個被 gitignore 的檔案中，而憑證則絕對不應放入任何檔案。

什麼是 HUMAN.md？我需要它嗎？

HUMAN.md 是針對「個人」而非「專案」的機器可讀設定檔。它記錄了您的角色、限制條件以及已定案的決策，避免在每次對話中重複討論。您不需要任何工具即可開始：在使用者層級的指令檔中手動寫下 20 行內容，就能發揮大部分價值。請將其視為個人資料，並確保不要將其推送到任何儲存庫中。