我懶得寫 CLAUDE.md——結果反而做對了

每次 timeline 出現關於 CLAUDE.md（或者 AGENTS.md）嘅帖子，我都話自己「遲啲先搞」，然後繼續碌落去。睇住其他人建構精心設計嘅 AGENTS.md 配置，心裡頭其實有少少擔心——係咪落後咗？

直到最近有新嘅 benchmark 數據出咗，我呢份擔憂即刻消散。原來我嘅懶惰，係幾理性嘅工程決定。

LLM 自動生成嘅 context 檔案只會幫倒忙

「多啲 context 應該有幫助㗎嘛？」我之前都係咁諗。

但研究人員喺 SWE-bench Lite 測試 LLM 自動生成嘅 context 時，成功率反而跌咗 0.5%。AgentBench 上頭再跌多 2%。就算係人手細心寫嘅檔案，都只係改善咗 4%。我會叫呢個現象做「context 過擬合」。

• SWE-bench Lite 上，LLM 生成 context 令成功率跌 0.5%
• AgentBench 再額外跌 2%
• 推理成本上升 20–23%
• 唯一有正面效果（2.7%）嘅情況，係完全冇文件嘅 repo

Gloaguen 等人嘅論文 “Evaluating AGENTS.md” 已確認：context 檔案往往令任務成功率低過完全唔提供 repo 背景嘅情況。

Agent 跟指令跟得太盡——問題就喺度

問題唔係 agent 唔聽你話。恰恰相反。

你喺 context 檔案入面寫一行叫 agent 用 uv，佢就算喺完全唔需要嘅情況下，都會裝晒、跑晒 uv，每次都多幾個多餘步驟。

用 GPT-5.2 測試，有 context 檔案嘅時候推理 token 增加咗 14–22%。Agent 忙住跟指令，反而唔專心解決問題本身。

• 唔必要嘅 pytest 執行次數增加
• grep 同 read 工具使用量遠超實際需要

叫 agent「唔好做 X」，佢反而更加諗住 X

我之前寫過 SKILL.md 正文內容喺特定時機先被讀取嘅問題，AGENTS.md 都有類似情況。

佢坐喺 system prompt 同 user prompt 之間嘅「developer message」層。呢個位置對 agent 推理嘅束縛好大。

你寫「唔好動呢個檔案」，agent 就會多花一次心思喺呢個檔案上面。研究人員將呢個稱為「粉紅大象效應」——叫人唔好諗粉紅大象，腦海裡第一樣浮現嘅偏偏就係粉紅大象。

• 優先順序：provider 指令 → system prompt → AGENTS.md → user prompt
• 人手維護嘅檔案根本追唔上代碼改動速度，資訊好快就過時

非寫不可，就愈短愈好

如果你嘅 repo 完全冇任何文件，context 檔案確實有幫助——數據顯示呢種情況有 2.7% 嘅正面效果。但若果真係要寫，請盡量精簡。

一行寫 repo 專用嘅 build 工具。 一行糾正 agent 反覆犯嘅錯誤模式。

加一個「如果發現結構上有古怪，立即報告」嘅 hack，agent 就變成專門舉報代碼庫漏洞嘅工具。超出呢個範圍，令代碼結構更直觀，遠比寫一大堆指引來得有效。

• 加強 unit test 同 type check，勝過依賴 context 檔案
• 如果檔案位置令人困惑，直接搬走檔案好過寫路徑說明

寫得一份好嘅 context 檔案，唔一定係有本事嘅表現。真正有本事，係理解 context 檔案嘅結構，圍繞佢設計 meta-system。而有時候，「懶得去做」，先係最好嘅工程決定。