HomeNews

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

Abhinav
Abhinav
•
Nov 14, 2026 6:58 PM
•
0
 min read
Select Emergent as your Preferred news source
Claude Code Skips AGENTS.md in 1 in 6 Repos, Study Finds

💡 TL;DR

  • Claude Code fails to load AGENTS.md instruction files in roughly 16% of repositories that contain both CLAUDE.md and AGENTS.md configuration files.
  • The study analyzed GitHub repositories to identify patterns in how Claude Code prioritizes and processes developer instruction files during initialization.
  • The finding raises questions about file loading hierarchy and suggests developers may need clearer guidance on instruction file best practices.

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.

About the writer

Abhinav is a Software Engineer at Emergent, contributing to the platform's AI-powered app building systems. He previously built products at Digital Product School by UnternehmerTUM and Eylo AI, and holds a Computer Science degree from BITS Pilani.

Start Building
on Emergent today
Try Emergent