A conversation brewing on Hacker News is cutting through the hype around AI coding agents to ask an uncomfortable question: are all those hours spent maintaining CLAUDE.md and AGENTS.md files actually worth it? User david_d8912 posted the thread on May 16, 2026, asking whether developers who use coding agents regularly still invest significant time in these instruction files—and the responses suggest many are hitting diminishing returns.

The Core Complaint

The original poster wasn't shy about their frustration. They noted that rules specified in agent instruction files often go unfollowed even when making changes involving fewer than 100 lines of code—a threshold where you'd expect maximum consistency and adherence to project standards. Yet despite this apparent unreliability, the practice persists, with prominent developers like Andrej Karpathy continuing to publish detailed behavioral rules for their projects that rack up hundreds of GitHub stars.

What Developers Are Saying

The thread reveals a meaningful split in how people approach these configuration files. The original poster drew a crucial distinction: instruction files work great when they contain factual information—project directory structures, important documentation references, build commands—but become questionable territory when focused on behavioral rules like coding standards, comment styles, and prescriptive do-this/don't-do-that guidelines. This framing suggests the problem isn't with agent instruction files themselves, but rather with unrealistic expectations about what behavioral directives can accomplish.

The Behavioral Rules Problem

Several factors likely contribute to why behavioral rules get ignored. Modern AI agents have strong baked-in preferences shaped by their training that may conflict with custom instructions. Context window limitations mean lengthy rule sets get truncated or deprioritized. And the models themselves evolve—rules written for one version of an agent may be suboptimal or contradictory under newer versions. The result is that developers who spend hours crafting perfect AGENTS.md documents often end up with files the agent treats as suggestions rather than requirements.

Key Takeaways

  • Factual instructions (paths, commands, docs) remain genuinely useful and worth maintaining
  • Behavioral rules face significant adoption problems even in small changes
  • Model training preferences may override custom developer instructions
  • Lengthy rule sets risk being deprioritized due to context constraints

The Bottom Line

The writing's been on the wall for a while—spend your time documenting facts, not philosophy. If you're crafting elaborate behavioral guidelines expecting an AI agent to follow them like a junior dev reading a style guide, you're probably just creating documentation theater that makes you feel productive without actually improving outcomes.