Agent instruction files（AGENTS.md / CLAUDE.md）

Agent instruction files 指的是 repo 內每次 coding agent session 都會讀取的專案使用手冊，例如 Codex / Copilot 的 AGENTS.md、Claude Code 的 CLAUDE.md、Cursor 的 .cursorrules。它們屬於 harness-engineering-for-ai-coding 的 feedforward 層：先告訴 agent 專案慣例、非預期工具鏈、驗證方式與安全邊界，但不能取代測試、hooks、linter 等 feedback / sensor。

核心判準

AIHAO 整理 ETH Zurich LogicStar 的實驗與社群實務後，給出的主張很 ponytail：不要把 AGENTS.md 當成 README 複製品，也不要直接接受 /init 自動生成的長檔。研究顯示自動生成的 context file 平均讓成功率下降約 3%、推論成本增加約 20%；原因不是 agent 不聽，而是它太聽話，會被不必要指令帶去多跑測試、多讀檔、多花 token。

值得寫的是 agent 從程式碼與既有文件推不出來、但不寫就容易做錯的資訊：非預期工具鏈（例如 uv 不是 pip、bun 不是 npm）、歷史包袱、團隊共識、外部約束、踩過的雷、以及可執行的 build / test / verify 指令。已經由 formatter、linter、type checker 或 README 表達的內容不該重複塞進主指令檔，否則會增加 agentic-ai-cost-management 的 repeated context 成本，也會稀釋模型可靠遵守的指令配額。

寫法規則

• 前面放可執行檢查：npm test、pytest -v、lint/typecheck 指令比長篇架構說明更有用。
• 寫 WHY / HOW，不重述 WHAT：目錄結構與 package 檔 agent 自己能看；專案目的、特殊工具鏈、驗證方式與不能做的事才值得常駐。
• 大專案分層：主檔只放常駐路標，子目錄用自己的 AGENTS.md，任務特定細節拆到 agent_docs/ 或 lazy-load 文件。
• 紅線交給 hooks：不能 push main、不能外洩 secrets、修改後必跑 lint 這類硬規則，不要只寫在 CLAUDE.md 裡許願，要用 PreToolUse / PostToolUse hook、CI 或權限控制強制。
• 定期刪除過期規則：每一行最好能追溯到真實失敗；當 model-harness-fit 改變、模型已不再犯同樣錯時，就刪掉那條 scaffolding。

Skills 與寫給 agent 的文件

AIHAO 2026-07-25 整理 Matt Pocock 的觀點，補充 Skill 與 AGENTS.md / CLAUDE.md 共用的文件工程原則：文字的目標是改變 agent 行為，不是讓人讀起來更慎重。description 應只保留觸發條件；本體則按 branch 做 progressive disclosure，刪除 no-op、重複、沉積與過長內容。leading word 可作為共通術語，但完成標準與實際 trace 仍需驗證，不能只靠語氣或禁止句。

這讓 agent-skills 與本頁形成清楚邊界：instruction file 放 session 常駐、專案層級且不寫就會錯的背景；skill 放可重複任務的 steps / references；harness-engineering-for-ai-coding 的 hooks、tests 與 review 負責不可只靠文件保證的紅線。

Claude 5 世代的精簡化方向

BusinessNext 2026-07-29 引述 Anthropic 對 Claude 5 context engineering 的整理，建議把 CLAUDE.md 當成短路標，而不是百科全書：保留建置／測試指令、特殊慣例、專案陷阱與硬邊界，刪除 agent 讀檔即可推導的目錄或風格資訊。官方報導同時提醒，這個方向建立在新模型判斷力較強的前提上，不能直接套用到所有模型與高風險任務。

可操作的分工是：常駐規則只解決「每個 session 都不能忘、且模型不易自行發現」的問題；branch-specific 流程、團隊觀點與示範輸出移到 agent-skills 的 progressive disclosure；不可違反的安全條件仍交給 harness-engineering-for-ai-coding 的 hooks、tests、權限與 review。更新前先用 model-harness-fit 做小型任務級比較，避免把刪 prompt 當成無條件優化。

AGENTS.md 是 guide，不是安全邊界

BusinessNext 整理 Jason Liu 的 Codex 示範，進一步區分 AGENTS.md 的行為指引與系統層控制：前者可以保存工作規範、專案記憶與不可忽略的提醒，但不能阻止模型繞過連接器限制；真正的硬邊界要由 sandbox、權限核准政策、網路規則、管理設定與 review agent 強制。這個分工與 agent-sandbox-architecture、harness-engineering-for-ai-coding 的 guides／sensors 邊界一致。

因此，對長駐 thread、computer use 或 background automation，AGENTS.md 應只寫模型無法自行發現的工作脈絡與停止提醒；不可逆的寄信、付款、簽署或敏感資料傳送，仍應落在可否決的權限 gate。這也把 context-engineering 的常駐 context 與 loop-engineering 的停止條件接起來：文件負責 feedforward，系統與測試負責 feedback。

定期刪除與最小回填

BusinessNext 2026-07-30 整理 Boris Cherny 的建議：每隔一段時間刪除自己的 CLAUDE.md、Skills 與 hooks，觀察模型在沒有歷史 scaffold 時的行為；只有重複失敗被觀察到，才把最小規則加回。這把「短指令檔」從靜態最佳實務改成 model-harness-fit 的遷移實驗，也呼應 agent-skills 的 no-op pruning。

這個刪除實驗不能碰掉真正的安全邊界：秘密、權限、不可逆動作、deterministic tests 與 CI 應由 hooks、sandbox、測試與治理設定強制，而不是寄望模型讀懂文件後自律。每次回填都應留下失敗案例與驗證證據，否則長檔案只是在累積 repeated context 成本；來源為 BusinessNext 對公開對談的整理，不能推成所有模型都適用的無條件規則。

對 AI Ark loop 的含意

AI Ark 的 wiki loop 不需要再新增複雜 registry 才能改善品質；目前更高槓桿的做法是維持一份短、可驗證、可追溯的操作規則：先 orient、raw capture、derived page、index/log、queue sanity、raw hash、wikilink 檢查。這也呼應 ponytail-loop-review-gate：指令檔是最小可行 harness 的一部分，但真正防腐化的是驗證步驟，而不是把更多願望寫進長 prompt。

相關頁面

• harness-engineering-for-ai-coding — instruction files 是 guides / feedforward，不是 deterministic feedback
• model-specific-system-prompts — 不同模型與工具 harness 對指令格式敏感
• ai-collaboration-compounding-workflow — CLAUDE.md / skills / guides 作為團隊偏好與 workflow 的持久化層
• agentic-ai-cost-management — 長指令檔會增加 repeated context 與 cache miss 成本