DEV Community

Discussion on: I built a linter that proves 74% of your AGENTS.md is wasting your AI agent's time

Collapse
 
automate-archit profile image
Archit Mittal

The signal-to-noise ratio framing is the right way to think about this. I've been maintaining CLAUDE.md files across multiple automation projects and the drift problem is real — you refactor a module, rename a directory, and the context file becomes a source of hallucination fuel rather than guidance.

The stale-command rule is the one that would save me the most pain. I've watched agents burn 3-4 tool calls trying to run a script that was renamed two sprints ago, then "discover" the correct command and act like nothing happened. That's not just token waste — it's latency in interactive sessions where you're waiting on the agent.

One thing I'd push back on slightly: the no-inferable-stack rule needs nuance. Declaring "this project uses n8n workflows with Claude API calls" in a context file isn't redundant even if package.json has the deps listed — it's telling the agent the architectural intent, not just the dependency graph. The agent knowing you chose n8n over Temporal for orchestration changes how it reasons about your error handling patterns. Raw deps don't convey that.

Would love to see the diff command expanded into a pre-commit hook that blocks PRs when context files reference paths changed in the diff. That would catch staleness at the source instead of during lint.