AGENTS-md

Properties2
tags狀態/草稿, 領域/ai, 領域/開發
aliasesAGENTS.md, AGENTS md

閱讀時間約 5 分鐘

AGENTS-md

一句話定義

Natural Language Harness 的常駐配置檔——把專案的環境、工具、命名慣例、可做與不可做的事寫進一份 markdown，讓 agent 每次 session 啟動就自動載入；OpenCode / Cursor / 多家第三方 harness 預設讀此檔（vs Claude-Code 預設讀 CLAUDE.md）。檔名是各家 harness 的差異點，內容結構大致同源。

核心要點

是什麼層級的東西

  • 常駐配置層：每次 session 啟動就進 prompt，相當於專案內的「法律」
  • Natural Language Harness 的可見部分：Harness-Engineering 三大手段中「認知框架」這軸的代表實作（其他兩軸 = 能力邊界 / 行為，由工具設定與工作流承擔）
  • 跨 host 同源：AGENTS.md（OpenCode / 多家）/ CLAUDE.md（Claude Code）/ .cursorrules（Cursor）名字不同、結構同類

OpenAI 的核心紀律：地圖而非六法全書

OpenAI 2025-02 Harness Engineering blog 的關鍵警語：

「AGENTS.md 應該是地圖、不是六法全書」——百科全書式塞滿規則的版本表現很差，因為 context 全被吃掉。

正確心法：告訴 agent「想知道什麼去哪裡找」（pointer 而非規則本身），不是把所有規則塞進去。

→ 這條原則同精神於 Agentic-Context-Engineering 的「可動 vs 不可動的部分要分清楚」。

推薦結構（李宏毅 元實驗萃取）

Claude-Code（Opus 4.6）改 Haiku 3.5 的 AGENTS.md 打 PinchBench，從 13.5 → 85 分；最終形成的具普適性結構：

  1. 環境與工具列表前置——讓 agent 一開始就知道手上有什麼
  2. 第一步永遠 exec_dir 看資料夾——不要憑想像，先看現實
  3. 開工前先讀題目提到的所有檔案——資訊蒐集前置於行動
  4. 不要 hallucinate 不存在的東西——明示性約束

→ 這四條在不到 80 字的工作原則篇幅內，可讓小模型（Gemma 4 2B 級）從幻想變正常 agent。

反模式

  • 百科全書式塞滿規則——context 被吃掉、agent 表現反而下降
  • 規則細節 vs 找規則的指引混雜——agent 該知道規則在哪、不該強記每條規則
  • 缺環境與工具列表——agent 不知道手上有什麼工具、第一步就 hallucinate

與 CLAUDE.md 的關係（vault 自我參照）

本 vault 根目錄的 CLAUDE.md 即此模式的具體實現——把 vault 維護契約寫成一份規範檔，讓 LLM 每次 ingest / lint / query 啟動時自動載入。

與其他概念的關係

  • 母概念：Harness-Engineering — AGENTS.md 是「認知框架」手段下的具體實作
  • Prompt-Engineering — AGENTS.md 內容本質是 prompt-engineering 在「常駐配置層」的應用；OpenAI 的「地圖而非六法全書」是 prompt-engineering 在這層的關鍵紀律
  • Context-Engineering — 對位「百科全書式 AGENTS.md 失敗」即是 context window 被吃掉的具體案例
  • Lifelong-AI-Agent — meta-harness 自我演化的兩種路徑之一是「模型自己改 AGENTS.md」（另一條是寫 skill 檔）
  • Agentic-Context-Engineering — 「可動 vs 不可動」的精神同源
  • 程式碼風格指南 — 「給 LLM 讀的 style guide」即是 AGENTS.md 的程式碼專屬子集
  • Claude-Code / OpenCode / Cursor / Cline — 各家 harness 是此檔的具體 host

相關來源

備註

vault 內第一個明確處理 Natural Language Harness 常駐配置檔的概念頁。CLAUDE.md / AGENTS.md / .cursorrules 各家 host 的細部差異（觸發時機、是否支援子目錄繼承、能否被工具讀寫）尚未在 vault 中有獨立處理，待未來 ingest 補強。

未來累積方向：

  • (a) AGENTS.md / CLAUDE.md 的具體 prompt 設計範例集（各家社群的範本與 anti-pattern 蒐集）
  • (b) Skill / Plugin 系統與 AGENTS.md 的分工（按需加載 vs 常駐）
  • (c) 多層級 AGENTS.md（global / repo / sub-dir）的繼承與覆寫規則
  • (d) AGENTS.md 自我演化的具體 paper（Meta-harness paper 跨 LLM 跨 task 結果）
  • (e) 多家 harness 的 AGENTS.md 規格 spec 是否最終會收斂或繼續分歧

反向連結