Progressive Disclosure: Why Isn't Claude Code Following My Instructions?

In a recent exploration of AI agent behavior, developer and Reporails creator explores why coding agents like Claude Code sometimes fail to follow specific project instructions. Through controlled experiments comparing 'named' versus 'vague' specifications, the author demonstrates that instruction quality is the primary driver of compliance. Vague language, such as using 'ideally' or failing to specify data sources, leads to inconsistent model output, whereas precise, directive-based instructions significantly improve reliability. The article highlights that even as context windows grow, the model's tendency to prioritize recent information can lead to instruction decay. To combat this, the author advocates for automated instruction auditing tools—such as the CLI tool Reporails—to analyze and improve the quality of project documentation and rule sets before they are fed into AI agents, ensuring that instructions are actionable and consistently followed by the model.