Study Challenges `claude.md` Effectiveness for AI Code Agents, Advocates for Streamlined Context Management

A new study, “Are repository-level context files really a help for code agents?” evaluates the effectiveness of common context files like claude.md or agent.md utilized by AI code agents such as claude Code, Open Code, GM Cli, GPT Codex, and others. The research concludes that these files, often generated by commands like /init, frequently introduce unnecessary or contradictory information, making it harder for AI models to efficiently process tasks. This issue contributes to higher token usage—claude Code, for instance, operates within a 200,000-token context window—and can lead to outdated project understanding as the AI relies on static, potentially stale descriptions rather than real-time project analysis.

To optimize AI agent performance and context utilization, the recommendation is to drastically simplify claude.md or similar files. Developers should limit their content to only essential, project-wide, and frequently repeated instructions, such as coding style conventions (e.g., using kebab-case for file names) or agent behavior directives (e.g., ‘do not execute build on every code modification’). For more elaborate or task-specific guidance, the adoption of ‘skills’ is advocated. These modular instruction sets, stored in a dedicated skills directory (e.g., skills/build/skill.md), are loaded on demand by the AI, providing relevant context only when needed for particular tasks like building the application or adhering to specific interface design patterns. General project documentation, such as architecture or deployment guides, should be moved to a separate doc folder, preventing unnecessary loading into the AI’s active context, while the AI can still reference actual project files like package.json or Prisma.cfg for up-to-date commands and data models.