If you're running AI coding assistants like Claude or GPT in your development environment, you've probably created an AGENTS.md or CLAUDE.md file to give them context about your project. Maybe you wrote "setup is npm run build" or "the entry point is src/index.ts." Here's the problem: that documentation rots silently as your codebase evolves, and your agent believes every word of it.

How Instruction Files Go Stale

The scenario plays out like this: You write clear instructions for your AI assistant. Six months later, someone renames a script from "build" to "compile." Or the entry point gets moved to src/main.ts. Your AGENTS.md still says npm run build and src/index.ts. The agent reads those files on every session, trusts them implicitly, and then executes commands that fail—or worse, does something destructive because it was following outdated intel. This isn't a hypothetical edge case. It's happening in production right now across teams using AI agents for code reviews, refactoring, and autonomous coding tasks. The documentation looked accurate when you wrote it. Nobody flagged it as wrong. But the agent is working with lies.

Introducing Reflint

One developer got tired of watching this happen, so they built reflint: a linter that ignores wording and style entirely and actually checks whether your instruction files are telling the truth. "I kept seeing teams break their CI because an AGENTS.md file said npm run build when someone had renamed it to npm run compile months ago," the developer explained in a post on DEV.to. The tool works by cross-referencing documentation against actual codebase state: does npm run build actually work? Does src/index.ts exist as an entry point? "Instead of validating grammar or formatting, reflint validates reality—style guides don't break your builds. Outdated commands do," the developer noted.

Why This Matters for Agent Reliability

We talk a lot about making AI agents more capable, giving them better reasoning, improving their context windows. But here's an uncomfortable truth: even the most advanced agent will fail if you feed it stale data. AGENTS.md files are essentially configuration files for your agent's behavior, and they're being maintained like afterthought comments in legacy code. The implications extend beyond just build scripts. If you're using agents to understand your architecture, generate documentation, or make architectural decisions, they need ground truth—not whatever a file said six months ago before the great refactor of March.

Key Takeaways

  • AGENTS.md and CLAUDE.md files silently become lies as codebases change
  • AI agents trust these instruction files without verification, leading to broken builds and failed commands
  • Reflint tackles this by validating factual accuracy rather than style or wording
  • This is a fundamental reliability problem for any team deploying autonomous coding agents in production environments

The Bottom Line

We can obsess over model capabilities all day long, but if we're handing our agents corrupted instruction sets, we're building on sand. Documentation that doesn't validate itself against reality isn't documentation—it's liability waiting to bite you at 2 AM when your agent decides to refactor the wrong module because its instructions were three commits out of date.