agents-md-claude-md-guidelines.txt

# Mobile Capture 20260510T131118+0000-local-3f083b7367be

Captured: 2026-05-10T13:11:18+00:00
Source: local
From: macbook

Original files:
- Recordings-57-.txt

## Content

# Recordings-57-.txt

Recordings
📌 AGENTS.md / CLAUDE.md 該寫什麼、不該寫什麼?

最近 AGENTS.md (在 Claude Code 是 CLAUDE.md) 怎麼寫的討論變多。二月初蘇黎世聯邦理工學院出了篇論文，在 X 上被放大講成「AGENTS.md 反而會害你」 — 但實際比這更微妙。整理一下研究結論、作者的澄清，跟社群歸納的「該寫／不該寫」。

——

🔬 反直覺研究結果

蘇黎世聯邦理工學院 LogicStar 團隊在 SWE-bench Lite + 自建 AgentBench 上測試 Claude Code、Codex、Qwen Code 三套 agent:

▸ LLM /init 自動生成的: 降 3% 成功率、增 20% 推論成本
▸ 開發者手寫的: 只有微弱 ~4% 正向效果，但同樣會增加成本
▸ 不論模型、不論 prompt，結論一致

不是 agent 不聽話，是它太聽話 — 被寫進去的工具使用率高 160 倍，但「不必要的指令」反而讓任務變複雜，推理 token 多 22%。最諷刺的發現: 把 repo 裡所有 .md 跟 docs/ 刪掉之後，LLM 自動產生的 AGENTS.md 才開始有正面效果，意思是大部分自動產生內容只是在「複述既有文件」。

——

✅ 該寫什麼? WHAT / WHY / HOW

Phil Schmid 從研究歸納出三塊:

▸ WHAT: 技術棧、專案結構 (monorepo 特別重要)
▸ WHY: 關鍵元件存在的理由，幫 agent 理解意圖而不只是結構
▸ HOW: 建置、測試指令，特別是非預期工具鏈 — uv 而不是 pip、bun 而不是 npm

精確判準: 如果這件事 agent 自己讀程式碼就能發現，那就不用寫。值得寫的反過來都是 agent 沒辦法從程式碼推出來的 — 工具鏈選擇、歷史包袱、團隊共識、踩過的雷。

——

❌ 不該寫什麼? 大多數人塞進去的其實沒幫助

▸ 重述 README 跟既有文件 (最大宗的浪費)
▸ 大段架構概覽 / 目錄列表 (100% 自動 init 都包，但對 agent 找對檔案的速度沒任何幫助)
▸ 看得到的技術棧細節 (package.json 已經寫過了)
▸ 程式風格規定 (交給 linter / formatter)
▸ 空泛標語「寫 clean code」、「good naming」
▸ 詳細 API 文件 (連結帶到外部就好)
▸ 只在特定情境才用到的指令 (應該分到子檔)
▸ 自動 /init 出來不修就放著

研究最後的 takeaway 句子蠻一針見血: 「人寫的 context file 應該只描述最低限度的需求」。多寫不會加分，反而扣分。

——

💬 但別誤讀: 作者本人的澄清

論文紅了之後，作者 Thibaud Gloaguen 在 LinkedIn 上親自打臉 Theo、Matt Pocock 等大 V 在 X 上的誤讀: 真正的反派是 /init 跟「塞越多越好」的心態，不是 AGENTS.md 本身。簡潔的、人寫的 AGENTS.md 是可以幫到 coding agent 的。

幾個補充意見:

▸ 研究樣本偏向小型「隨興開發」專案，大型私有專案的 AGENTS.md 價值會更高
▸ 只測測試通過率，沒測程式風格／慣例遵循 — 換指標可能整個結論都不一樣
▸ Vercel 在「教 agent 訓練資料沒有的最新 Next.js 知識」這個情境效果非常顯著
▸ 寫 AGENTS.md 的副效果: 逼你把腦袋裡的隱性知識講清楚，agent 拿到了，新人也拿到了

——

🪝 真正的紅線要靠 hooks，不能只靠 CLAUDE.md

CLAUDE.md 規則順從率大約 70%。「絕對不能做的事」用 hooks (PreToolUse 回 exit code 2) 寫才會真的攔下，不要只在 CLAUDE.md 裡許願。

——

💡 最有啟發的一句

寫 CLAUDE.md 的本質，是在跟一個「每次都失憶但會完全相信文件」的 agent 工作。你不是在寫給未來會加入團隊的工程師看，是在設計一個 agent 在開始工作前的記憶植入。視角換過來，什麼該寫什麼不該寫自然就清楚了。

更多完整版請見 Blog 文章。(相關文章連結都放在留言)