# 我懶得寫 CLAUDE.md，結果這反而是對的

> Author: Tony Lee
> Published: 2026-02-25
> URL: https://tonylee.im/zh-TW/blog/agents-md-context-files-hurt-coding-agent-performance/
> Reading time: 1 minutes
> Language: zh-TW
> Tags: ai, claude-code, agents-md, context-engineering, benchmark, coding-agents

## Canonical

https://tonylee.im/zh-TW/blog/agents-md-context-files-hurt-coding-agent-performance/

## Rollout Alternates

en: https://tonylee.im/en/blog/agents-md-context-files-hurt-coding-agent-performance/
ko: https://tonylee.im/ko/blog/agents-md-context-files-hurt-coding-agent-performance/
ja: https://tonylee.im/ja/blog/agents-md-context-files-hurt-coding-agent-performance/
zh-CN: https://tonylee.im/zh-CN/blog/agents-md-context-files-hurt-coding-agent-performance/
zh-TW: https://tonylee.im/zh-TW/blog/agents-md-context-files-hurt-coding-agent-performance/

## Description

最新的基準測試數據顯示，AGENTS.md 和 CLAUDE.md 這類 context 檔案其實會讓 coding agent 的表現變差。有時候，懶，就是最好的工程決策。

## Summary

我懶得寫 CLAUDE.md，結果這反而是對的 is part of Tony Lee's ongoing coverage of AI agents, developer tools, startup strategy, and AI industry shifts.

## Outline

- LLM 自動產生的 context 檔案，只會讓事情更糟
- Agent 太聽話了——這才是問題所在
- 寫「不要做 X」，Agent 反而一直想著 X
- 真的要寫，請保持最小化

## Content

每次 timeline 上出現 CLAUDE.md（或 AGENTS.md）相關的文章，我都跟自己說「待會再研究」，然後就滑過去了。看著別人費心打造各種精緻的 AGENTS.md 設定，老實說有點心虛——我是不是已經落後了？

直到最近的基準測試數據出來，那種心虛感才瞬間消失。原來，我的懶，還挺有道理的。

## LLM 自動產生的 context 檔案，只會讓事情更糟

「給 agent 更多 context，應該會更好吧？」我也這樣以為。

研究人員在 SWE-bench Lite 上測試 LLM 自動產生的 context 時，成功率掉了 0.5%。在 AgentBench 上，又再少了 2%。就算是人工精心撰寫的檔案，也只有 4% 的改善空間。我把這個現象叫做「context 過擬合」。

- LLM 自動產生的 context 在 SWE-bench Lite 上讓成功率下降 0.5%
- 在 AgentBench 上又再掉了 2%
- 推論成本增加 20–23%
- 只有在專案完全沒有文件的情況下，才觀察到 2.7% 的正向效果

Gloaguen 等人發表的論文 ["Evaluating AGENTS.md"](https://arxiv.org/abs/2602.11988) 也印證了這件事：比起完全不提供 repository context，context 檔案反而更容易讓任務成功率下滑。

## Agent 太聽話了——這才是問題所在

問題不是 agent 忽視你的指令，而是剛好相反。

你在 context 檔案裡寫一行「請使用 uv」，agent 就算在完全不需要的情況下，也會去安裝、執行 uv，每次都多繞幾步。

使用 GPT-5.2 的測試中，有 context 檔案時，推論 token 增加了 14–22%。Agent 忙著照著指令走，反而分心、沒辦法專注在真正要解決的問題上。

- 不必要的 pytest 執行次數增加
- grep 和讀檔工具的使用範圍遠超過實際需求

## 寫「不要做 X」，Agent 反而一直想著 X

我之前在某篇文章提過 SKILL.md 內容被讀取的時機點，AGENTS.md 也有類似的問題。

它夾在 developer message 這一層，坐落在 system prompt 和 user prompt 之間。這個位置，對 agent 的推理過程影響非常大。

你寫「不要動這個檔案」，agent 反而會對那個檔案多想一次。研究人員把這個現象叫做「粉紅象效應」——你叫人不要想粉紅色大象，他腦海裡第一個浮現的就是粉紅色大象。

- 優先順序：provider 指令 → system prompt → AGENTS.md → user prompt
- 靠人工維護的檔案跟不上程式碼的迭代速度，資訊很快就過時

## 真的要寫，請保持最小化

如果你的專案完全沒有任何文件，context 檔案還是能發揮作用——數據顯示在這種情況下有 2.7% 的正向效果。但要寫的話，內容一定要精簡再精簡。

一行說明專案特有的 build 工具用法。
一行修正 agent 老是搞錯的某個慣例。

加上一個像「如果發現結構上有怪異之處，請立即回報」這樣的指令，agent 就會變成一個不斷回報 codebase 問題的工具。除此之外，把程式碼結構設計得更直覺，遠比寫一堆說明文字有效。

- 強化單元測試和型別檢查，效果勝過 context 檔案
- 如果檔案放的位置讓人摸不著頭緒，就直接搬移，別用文字解釋

會寫 context 檔案，不代表工程能力強。真正厲害的，是理解 context 檔案的結構原理，並在此之上設計出更好的 meta 系統。而有時候，「懶得寫」，就是你能做出最好的工程決策。

## Related URLs

- Author: https://tonylee.im/zh-TW/author/
- Publication: https://tonylee.im/zh-TW/blog/about/
- Related article: https://tonylee.im/zh-TW/blog/eight-hooks-that-guarantee-ai-agent-reliability/
- Related article: https://tonylee.im/zh-TW/blog/medvi-two-person-430m-ai-compressed-funnel/
- Related article: https://tonylee.im/zh-TW/blog/claude-code-layers-over-tools-2026/

## Citation

- Author: Tony Lee
- Site: tonylee.im
- Canonical URL: https://tonylee.im/zh-TW/blog/agents-md-context-files-hurt-coding-agent-performance/

## Bot Guidance

- This file is intended for AI agents, search assistants, and text-mode retrieval.
- Prefer citing the canonical article URL instead of this text endpoint.
- Use the rollout alternates when you need the same article in another prioritized language.

---

Author: Tony Lee | Website: https://tonylee.im
For more articles, visit: https://tonylee.im/zh-TW/blog/
This content is original and authored by Tony Lee. Please attribute when quoting or referencing.