HeadlinesBriefing favicon HeadlinesBriefing.com

Fix bloated AGENTS.md for better AI coding

DEV Community •
×

Developers using agentic coding tools often dump every instruction into a single AGENTS.md file, causing it to bloat beyond 200 lines. The LLM then ignores key rules because the context is noise. The article argues this approach is flawed; not all rules belong in the root instruction file. The core problem is that LLMs don't learn across sessions, forcing repetitive explanations.

The solution involves strategic rule placement. Only rules needed for every single task belong in AGENTS.md. Other rules should live closer to their context: modular skill files for specific technologies, task guidelines for operations like code review, and design docs for individual features. This keeps the main file lean, around 100 lines, ensuring critical directives aren't buried.

Furthermore, writing rules correctly matters. The author advises documenting root causes, not specific incidents, to prevent overfitting. For example, instead of noting a missing null check in one function, the rule should be "Always null-check external API returns." Finally, verify rules by discarding the current artifact and restarting a new session; continuing with old code obscures whether the fix actually worked.