H
Howardism
Plate IIAgent Systems機器翻譯 · machine-translated過時翻譯 · stale translationENHOWARDISM

Agent Context Files

PublishedMay 25, 2026FiledConceptDomainAgent SystemsTagsAgent EngineeringHarnessWorkflow DesignControl PlaneReading9 minSourceAI-synthesised

跨供應商的 markdown-as-control-plane 模式：存放於儲存庫版本控制中的 純文字檔案（CLAUDE.md / AGENTS.md / SOUL.md / WORKFLOW.md / SPEC.md / .cursorrules），依 project / personality / workflow / spec 層級按角色 設定代理程式行為

Agent Context Files 插圖

資料來源#

摘要#

在 2026 年各大代理程式生態系中，代理程式行為都以相同方式設定：儲存庫版本控制的純文字 markdown 檔案會在工作階段開始時讀入系統提示（或渲染至提示範本）。CLAUDE.md、AGENTS.md、SOUL.md、WORKFLOW.md、SPEC.md 和 .cursorrules 是同一種基礎原語，只是名稱不同。這種趨同已強烈到足以看似一項正在形成的標準：代理程式的行為契約是具版本控制、可檢視、同時可供人與機器讀取的文件，不是程式碼、資料庫，也不是聊天記錄。

本頁將此模式正式化，並比較不同供應商之間的角色分工。它是分層控制平面堆疊中的「政策平面」——情境檔案管理工作範圍內代理程式的行為方式，有別於工單層（執行什麼）以及迴圈／常駐程式層（執行）。

模式#

情境檔案同時滿足以下四項特性：

  • 具版本控制——存在於儲存庫（或 dotfile home）中，由 git 追蹤，像程式碼一樣接受審查。
  • 可檢視——人類可以閱讀它，並確切知道代理程式的設定方式。
  • 以確定性方式載入——每個工作階段自動注入（頂層），或按需求延遲載入（子目錄），因此行為可重現。
  • 雙重受眾——同時寫給代理程式（作為指示）與人類（作為先前沒有人記錄下來的隱性流程文件）。

這個模式之所以有效，最深層的原因正是最後一點：情境檔案捕捉了人類遵循、卻從未記錄的流程。Symphony 的說法——「處理一張工單、簽出儲存庫、將它移至進行中、加入 PR、移至 Review、附上影片——現在都記錄在簡單的 WORKFLOW.md 中」——是以提示作為政策的典型表述。編輯檔案就會在下一次渲染時編輯行為；不需要變更程式碼。

不同供應商的角色分工#

這些檔案可依四種角色分開——專案情境、個性、工作流程／程序與產品規格——但沒有任何單一供應商將四者完全分開存放。

角色Claude CodeHermes (Hermes Agent)Codex / Symphony
專案情境CLAUDE.mdAGENTS.md (cwd)AGENTS.md
個性／語調（隱含於 CLAUDE.md）SOUL.md（全域，~/.hermes/）—
工作流程／程序hooks + CLAUDE.md 規則—WORKFLOW.md（每個團隊的提示範本，含 YAML front matter）
產品規格——SPEC.md（定義協調器本身）
編輯器相容性—.cursorrules / .cursor/rules/*.mdc—
記憶（相關但非政策）conversation + CLAUDE.md有界的 MEMORY.md（約 2,200 個字元）+ USER.md（約 1,375 個字元）由檔案系統驅動

關鍵觀察：

  • Hermes 的分工最鮮明：AGENTS.md（專案）對上 SOUL.md（全域個性）。Claude Code 將兩者都整合進單一 CLAUDE.md；個性／專案的區別在實務上是隱含的，但從未分開存放。這種分工值得複製——它讓穩定的語調能跨專案持續存在，同時讓專案情境維持在儲存庫本地。
  • Symphony 在工作階段之上引入兩個新層級：WORKFLOW.md（協調時的程序，在使用者儲存庫中受版本控制，解析為執行時設定 + Liquid 提示範本本文）以及 SPEC.md（產品定義——開啟 Symphony 儲存庫時，第一個看到的是規格，而不是原始碼）。這些是位於協調層而非工作階段層的情境檔案。
  • .cursorrules 是相容性介面——Hermes 會從 cwd 自動載入它，因此使用者不必重複既有的 Cursor 設定。

載入紀律：考量預算的注入#

情境檔案會爭用情境視窗，因此載入方式日益分層：

  • 頂層、主動載入：根目錄的 CLAUDE.md / AGENTS.md 會在每個工作階段注入系統提示。
  • 子目錄、延遲載入：Hermes 會在工具呼叫期間（subdirectory_hints.py）發現巢狀的 AGENTS.md 檔案，並只在相關時將它們注入工具結果——只有代理程式確實在該目錄工作時，才支付 token 成本。這就是「AGENTS.md 作為目錄」的紀律：頂層是地圖，巢狀情境則按需求擷取。
  • 快取穩定：在工作階段內保持情境檔案不變，可以保留系統提示前綴快取。Hermes 明確警告，基於這個原因，不要在工作階段中變更情境檔案或模型。

相應的紀律是修剪：CLAUDE.md 應只包含代理程式無法從程式碼推斷的內容。隨著模型進步，檔案會縮小——請參閱模型進步時的 Harness 縮減。過度規範的情境檔案是已知的失敗模式（將確定性規則轉換為 hooks；刪除模型已能正確處理的任何內容）。

情境檔案在控制平面中的位置#

情境檔案是政策，不是工作圖譜。它們非常適合表達不變條件、慣例、角色邊界與流程；不適合編碼工作的即時狀態。SPEC.md 可以定義 Symphony，卻無法告訴常駐程式目前哪張工單已解除阻塞；AGENTS.md 可以告訴 Hermes 儲存庫如何運作，卻不會挑選下一個客戶請求。控制平面分析 將它們精確地放置如下：

  • 工單是持久的工作圖譜（執行什麼、什麼遭到阻塞、什麼已完成）。
  • 迴圈／常駐程式是執行引擎。
  • 情境檔案是政策平面——具版本控制的行為契約。
  • 記憶檔案是有界的回憶（供參考，不具權威性）。

以提示作為政策的脆弱之處，在於它無法強制執行——只能指示。Symphony 的答案是將硬性不變條件保留在提示之外（工作區路徑驗證、並行上限、終端狀態清理、重試退避、憑證代理），同時讓 WORKFLOW.md 提示說明代理程式應該做什麼。規格說明該做什麼；協調器強制執行不可違反的事項。這與「強制執行不變條件，而非實作」是相同的分工——情境檔案是建議性的一半；hooks／協調器不變條件則是機械性的一半。

規格即文件，再深入一層#

這個模式可以向上泛化。同一種「純文字規格作為承重構件」的直覺，會出現在對齊層（Model Spec / Constitution），甚至也出現在訓練輸入（model-spec-midtraining）。Symphony 的規格模糊測試技術——將 SPEC.md 編譯成六種語言，並利用跨實作差異來暴露歧義——就是將LLM 作為編譯器的想法應用於情境檔案。貫穿其中的主線是：隨著程式碼變得廉價，文件成為產品本身，而代理程式的工作就是將它編譯出來。

開放問題#

  • 角色分工會趨向 Hermes 明確的專案／個性分離，還是會像 Claude Code 一樣整合在單一檔案中？對多專案使用者而言，獨立的 SOUL.md 式個性層似乎嚴格更好，但也增加了一個需要維護的檔案。
  • 分層（專案 → 工作流程 → 規格 → 憲章）是否存在自然上限，還是每個新的自主介面都會產生另一層情境檔案？
  • 當情境檔案與有界記憶檔案互相矛盾時，兩者應如何互動？記憶會遺失資訊且快取延遲；情境檔案具權威性但保持靜態。何者勝出，以及何時勝出？

相關連結#

  • Claude Code 最佳實務——CLAUDE.md 慣例與毫不留情地修剪的紀律；此模式在工作階段層的典型實例
  • Hermes Agent——最鮮明的角色分工（AGENTS.md 專案對上 SOUL.md 個性），加上延遲的子目錄注入與有界記憶檔案
  • Symphony——引入協調層檔案：WORKFLOW.md（以提示作為政策）與 SPEC.md（產品就是規格）
  • 以工單驅動的代理程式協調——完整呈現 WORKFLOW.md 的以提示作為政策模式；情境檔案是工單層所呼叫的政策平面
  • 代理程式 Harness 工程——情境檔案是「強制執行不變條件，而非實作」的建議性一半；AGENTS.md 作為目錄是 Harness 紀律
  • 模型進步時的 Harness 縮減——為何情境檔案會隨每次模型發布而縮小；每次啟動時都進行修剪
  • 迴圈工程——skills（SKILL.md）是其五個基礎原語之一——意圖「寫在外部」，讓迴圈能累積成果，而不是每個週期重新推導專案；狀態／記憶檔案是迴圈的第六個基礎原語（在執行之間存續的骨幹）；Osmani 的「skill 是撰寫格式，plugin 是交付方式」進一步釐清了這項區別
  • 代理程式工作系統化——使用資料證據顯示這種外部化情境原語正大規模採用：skills／plugins 是 Codex 使用者編碼持久程序情境的方式，從每週活躍使用者的 5.4% 攀升至 26.6%
  • 未知數是代理程式的瓶頸——模式的反轉：Thariq Shihipar 的 implementation-notes.md 是一份由代理程式為人類撰寫的情境檔案，其中的 Deviations 區段記錄迫使它偏離計畫的邊界案例（「選擇保守選項、記錄下來，然後繼續前進」）
  • 情境優勢，而非品味——令人不適的解讀：如果人類的必要性是一種資訊不對稱，那麼每次撰寫情境檔案都會消耗其中一點
  • AI 原生組織——將模式從設定單一代理程式提升為編碼整家公司：Tan 的 skill-file-as-employee／resolver-table-as-org-chart 對映，是將情境檔案視為組織設計
  • 潛在空間與確定性空間——情境檔案是 Tan 雙面架構中潛在半部的引導機制

衍生內容#

資料來源#

§ end
About this piece

Articles in this journal are synthesised by AI agents from a curated wiki and are refreshed automatically as new concepts arrive. Topics, framing, and editorial direction are curated by Howardism.

Cited by 38
Related articles
  • Open Questions Backlog

    _456 actionable open questions across 205 pages · 107 predictions · 9 notes · 147 in progress · 69 watching (entities),…

  • Agent Harness Engineering

    Patterns for scaffolding long-running LLM agents: environment design, progressive context disclosure, mechanical archit…

  • Claude Code

    Anthropic's agentic coding product; created by Boris Cherny late 2024; TypeScript/React on Bun (itself Claude-rewritten…

  • Harness Shrinkage as Models Improve

    Prompt scaffolding shrinks each model release; Cat Wu's pruning discipline; Boris Cherny "100 lines of code a year from…

  • Client-Side Agent Optimization

    AgentOpt's framing of developer-controlled agent optimization (model-per-role, budget, routing) as distinct from server…