Claude Code Skips AGENTS.md in 1 in 6 Repos, Study Finds

A new study examining Claude Code's behavior across GitHub repositories has revealed a significant gap in how Anthropic's AI coding assistant processes instruction files. According to research published by Hrbr, Claude Code fails to load AGENTS.md files in approximately one out of every six repositories that contain both CLAUDE.md and AGENTS.md configuration files, potentially leaving developers without critical project context.
The Dual-File Loading Problem
The study specifically examined repositories where developers had created both CLAUDE.md and AGENTS.md files to provide instructions and context to AI coding assistants. While CLAUDE.md has become a standard convention for Anthropic-specific guidance, AGENTS.md emerged as a broader specification intended to work across multiple AI tools. The research found that in 16% of these dual-file scenarios, Claude Code processes only the CLAUDE.md file and never loads the AGENTS.md file during initialization.
This behavior creates a potential gap in project understanding. Developers who invest time writing comprehensive AGENTS.md files may unknowingly operate with Claude Code that lacks access to critical architectural decisions, coding standards, or project-specific requirements documented in those files.
File Priority and Loading Hierarchy
The findings suggest Claude Code employs a file loading hierarchy that isn't fully transparent to users. When both instruction files exist, the system appears to prioritize CLAUDE.md in most cases, but the inconsistency in AGENTS.md loading raises questions about the decision logic. According to the study, no clear pattern emerged to explain why some repositories experienced the loading failure while others successfully processed both files.
- CLAUDE.md files loaded successfully in 100% of examined repositories
- AGENTS.md files loaded in 84% of dual-file repositories
- No correlation found between repository size and loading behavior
- File location within the repository structure showed no impact on results
Implications for Developer Workflows
The study's authors note that this loading gap could have practical consequences for teams relying on AGENTS.md as their primary instruction mechanism. Organizations adopting a multi-tool AI strategy often standardize on AGENTS.md to maintain consistent guidance across different coding assistants. When Claude Code silently skips these files, it may generate code that violates team standards or overlooks project-specific requirements clearly documented in the unloaded file.
Developers using Claude Code in repositories with both file types should verify which instruction files are actually being processed. The research suggests adding explicit logging or confirmation mechanisms to ensure critical guidance reaches the AI system during coding sessions.
Release Date and Availability
The study findings were officially released on November 14, 2026, through Hrbr's blog and subsequently discussed on Hacker News. The research represents one of the first systematic examinations of instruction file loading behavior across major AI coding assistants.
What This Means
This research highlights the need for greater transparency in how AI coding tools process developer instructions. As projects increasingly rely on standardized instruction files to guide AI behavior, consistent and predictable loading becomes essential. The 16% failure rate, while not catastrophic, represents a meaningful gap that could lead to suboptimal code generation or missed requirements. Anthropic has not yet publicly commented on the findings, but the study provides clear data for future improvements in Claude Code's file handling logic.
on Emergent today





