Two independent studies of real-world Claude Code configuration files have reached the same conclusion: developers are writing terse, shallow, action-oriented manifests that look nothing like the open-ended guidance Anthropic provides. Between them, Thonglek et al. (arXiv:2509.14744) and Santos et al. (arXiv:2511.09268) analyzed 581 configuration files from open-source repositories. The patterns they document tell you what actually works, and the gap they expose tells you why the vendor’s own docs aren’t helping.
Shallow hierarchies, action-oriented content
Thonglek et al. collected 253 CLAUDE.md files from 242 repositories and found that developers converge on shallow hierarchies with one main heading and several subsections. These manifests are not design documents. The most common content categories are build and run commands, implementation details, and architecture descriptions, in that order. Actionable operational instructions, not abstract philosophy.
Santos et al., working independently with 328 configuration files, confirmed the pattern. Their finding: specifying the architecture the agent should follow is the single most important concern, and a wide range of co-occurring software engineering concerns must be defined alongside it for effective agent behavior. Architecture-first is not a best-practices recommendation dreamed up by a vendor. It is what developers who ship working configuration actually do.
The documentation gap
Both papers identify the same structural problem. Thonglek et al. note that “the lack of comprehensive and accessible documentation for creating these manifests presents a significant challenge for developers.” Anthropic’s own docs describe CLAUDE.md as a place to share project context but offer minimal guidance on what effective configuration looks like in practice. Developers are left to figure it out through trial and error.
The 253 CLAUDE.md files from 242 repositories that Thonglek et al. analyzed represent significant adoption for a configuration mechanism so recently introduced. That is rapid adoption with minimal vendor guidance on how to use the thing being adopted.
To be fair, Anthropic has expanded its documentation since the data for these papers was collected. The plugins reference now covers skills, agents, hooks, MCP, LSP, and monitors. But the expansion came after the adoption wave, not before it. The configuration patterns documented in both papers were discovered bottom-up.
How the ecosystem filled the void
The gap between what the vendor provides and what practitioners need has been filled by community resources operating without vendor coordination.
The claude-code-best-practices repository (v1.6, released May 12, 2026) offers 30-plus guides, 11 stack-specific CLAUDE.md templates, and four starter kits. Clarista’s 18-pattern guide recommends keeping CLAUDE.md under 500 words. That 500-word figure comes from a vendor blog, not from the academic studies, and should be treated accordingly. But the fact that a word-count ceiling even needs to be proposed from outside Anthropic tells you something about the state of the documentation.
Morph reports over 9,000 community plugins in active use across four extension types: MCP servers, Skills, Custom Agents, and Hooks. That figure comes from a company selling MCP tooling, so treat it as marketing-adjacent. The direction, though, is clear: an ecosystem has evolved faster than the vendor’s ability to prescribe best practices for it.
What practitioners should take away
The empirical evidence from both studies points to a consistent set of patterns:
- Keep it shallow. Flat hierarchies with H2 and H3 sections dominate production configurations. Deep nesting does not correlate with effectiveness.
- Lead with architecture. Describe the system structure, not the design philosophy. Agents perform better when they know where things live, not why they were designed that way.
- Prioritize build commands and operational details. The most common content in working manifests is the kind of thing you would put in a
READMEfor a new team member who needs to ship today. - Treat it like onboarding documentation for a junior engineer. Terse, operational, architecture-first. Not a manifesto.
Why this matters beyond Claude Code
The documentation gap is not an Anthropic-specific problem. Every agentic coding tool that relies on configuration files faces the same issue. Cursor rules, Aider conventions, OpenHands configuration: the vendor provides the mechanism, and the community discovers the effective patterns through iteration.
The two papers make a case that the industry should be publishing empirical usage telemetry rather than aspirational guidance. Right now, the best available data on how developers configure AI coding agents comes from two academic preprints scraping public GitHub repositories. The vendors themselves have access to far richer data and have published none of it.
The counter-argument is that usage telemetry raises privacy concerns and that aggregate patterns may not apply to individual projects. Fair. But the alternative is the current state: 9,000 community plugins, competing best-practices lists with no empirical grounding, and CLAUDE.md files that grow into unmaintainable wikis because nobody has published data on what an effective one actually looks like.
The Santos paper’s ICSE workshop acceptance gives this research its first foothold in the academic review process. If the findings hold up under further scrutiny, they will be useful not just for Claude Code users but for anyone designing configuration-driven agentic tooling. The patterns developers converge on when left to figure things out themselves tend to be more informative than the patterns vendors recommend when they have no usage data to ground those recommendations in.
Frequently Asked Questions
How many CLAUDE.md files exist versus how many these studies actually analyzed?
Thonglek et al.’s initial GitHub API search returned 838 CLAUDE.md files across 806 repositories before filtering down to 253 from 242 repos for analysis. Santos et al. examined 328 separately. The combined 581-file sample represents a fraction of total usage, and it is drawn exclusively from public GitHub, leaving private and enterprise repositories entirely uncounted.
Has equivalent empirical research been done for Cursor rules or Aider conventions?
No comparable study has systematically analyzed .cursorrules files, Aider configuration, or OpenHands setup documents at similar scale. The two CLAUDE.md papers are, as of May 2026, the only research-adjacent work on agentic coding configuration practices. Whether the shallow, action-oriented pattern generalizes beyond Claude Code or is an artifact of its specific configuration mechanism remains unknown.
Do the studies show that flat CLAUDE.md files actually perform better?
Neither paper measures whether a given CLAUDE.md structure correlates with fewer agent errors, faster task completion, or better output quality. They document what public-project maintainers wrote, not how well those configurations performed. The flat, terse pattern is an observation of common practice, not a validated performance predictor. Heading depth beyond H3 was rare in the dataset, but rarity is not evidence of ineffectiveness.
The data predates Claude Code’s newer extension types. Are these findings still relevant?
Thonglek et al. collected data between February and June 2025, a four-month window immediately following Claude MCP’s release. The Santos dataset covers a similar period. Since then, Claude Code has added Skills, Custom Agents, Hooks, and expanded MCP integration, any of which could shift what effective configuration looks like. The findings describe first-wave adoption patterns under a simpler tool surface. Whether they hold as the extension ecosystem grows is untested.