A recent study showing a 3% performance decrease in AI agent tasks on repos with AGENTS.md files has been misrepresented in headlines. The full picture reveals that human-written AGENTS.md files actually improve AI agent performance by 4%. The key distinction is between auto-generated files (created via /init commands) that add noise with redundant information, and manually maintained files that document non-obvious project conventions, architectural decisions, and business logic quirks. Best practices include writing these files by hand, focusing on knowledge that can't be inferred from the codebase, and keeping them updated to avoid stale references.
Table of contents
What are AGENTS.md and CLAUDE.md filesWhat the study actually saysWhy auto-generated files can hurtThe concept is not perfectWhat I take from this284 Impressions