代理程式上下文載入器
概覽
自動發現並載入專案目錄階層中的 AGENTS.md 檔案,供 AI 編碼代理程式使用。此技能會掃描目前工作區及其父目錄,以定位代理程式指令檔案,然後將其內容載入,使活躍的代理程式工作階段擁有完整的操作上下文。
先決條件
- 包含一個或多個
AGENTS.md檔案的專案工作區(檔案可存在於任何目錄深度) - 具有讀取和 Glob 權限,可遍歷目錄樹
- 具有 Grep 存取權限,可在存在多個候選檔案時搜尋檔案內容
指令
- 掃描目前工作目錄及所有上層目錄(直到檔案系統根目錄或儲存庫根目錄),尋找名為
AGENTS.md或agents.md的檔案。 - 搜尋目前工作區的子目錄,尋找可能適用於子專案或模組的其他
AGENTS.md檔案。 - 決定載入順序:靠近儲存庫根目錄的檔案優先載入(全域上下文),位於較深目錄的檔案稍後載入(覆蓋或補充)。
- 讀取每個發現的
AGENTS.md檔案,並萃取其指令區塊、工作流程定義和約束宣告。 - 將指令合併為統一的上下文,注意各層級之間的任何衝突(例如,子目錄代理程式覆蓋根層級的規則)。
- 以結構化摘要呈現已載入的上下文:來源檔案路徑、指令數量,以及任何偵測到的衝突。
- 快取目前工作階段的發現結果,以避免在後續啟用時重複掃描檔案系統。
輸出
- 發現的
AGENTS.md檔案路徑及其目錄深度的有序列表 - 結合所有發現的代理程式上下文的合併指令集
- 衝突報告,標明各層級之間任何矛盾的指示
- 工作階段快取狀態,指示結果是新鮮的還是重複使用的
錯誤處理
| 錯誤 | 原因 | 解決方案 |
|---|---|---|
找不到 AGENTS.md | 工作區沒有代理程式指令檔案 | 確認目前工作目錄是否正確;如有需要,在專案根目錄建立一個 AGENTS.md |
| 目錄遍歷權限被拒 | 工作區上方的父目錄受到限制 | 將掃描深度限制在儲存庫根目錄(透過 .git/ 是否存在來偵測) |
| 偵測到循環符號連結 | 符號連結的目錄造成無限遍歷迴圈 | 在掃描期間跳過符號連結的目錄;記錄包含符號連結路徑的警告 |
| 跨層級指令衝突 | 子目錄 AGENTS.md 與根層級檔案矛盾 | 在輸出中標記衝突;預設情況下套用更具體(較深層)的指令 |
| 檔案編碼錯誤 | AGENTS.md 使用非 UTF-8 編碼 | 嘗試使用 latin-1 後備方案;回報檔案路徑和編碼問題 |
範例
範例 1:每個套件皆有代理程式指令的 Monorepo
- 結構:根目錄
AGENTS.md設定全域慣例;packages/api/AGENTS.md新增 API 特定的工具規則。 - 結果:兩個檔案按順序載入。API 特定規則補充全域上下文,沒有衝突。
範例 2:提交政策衝突的巢狀工作區
- 結構:根目錄
AGENTS.md規定「一律簽署提交」;services/legacy/AGENTS.md規定「跳過提交簽署」。 - 結果:偵測到衝突並回報。較深層(legacy)的指示被套用,同時附上一個說明此覆蓋的警告。
範例 3:沒有代理程式檔案的全新設定
- 結構:一個全新複製的儲存庫,沒有任何
AGENTS.md檔案。 - 結果:掃描完成,找到零個檔案。輸出包含一個建議,提示在儲存庫根目錄建立內含最小範本的
AGENTS.md。
資源
- Claude Code AGENTS.md 規格:https://docs.anthropic.com/en/docs/agents
- 代理程式設定的 Monorepo 工作區模式:https://docs.anthropic.com/en/docs/claude-code
- 階層式設定載入的檔案發現最佳實踐:https://docs.anthropic.com/en/docs/claude-code