source-summary

AGENTS.md And CLAUDE.md Writing Guidelines

AGENTS.md And CLAUDE.md Writing Guidelines

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 才開始有正面效果，意思是大部分自動產生內容只是在「複述既有文件」。

Key Takeaways

• # 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
• 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 文件 (連結帶到外部就好) ▸ 只在特定情境才用到的指令 (應該分

Related: overview.