Agent instruction files in repo (60k+ repos on GitHub)

Agent instruction files are project-specific configuration documents that tell AI agents how to behave in a given codebase. They go by different names depending on the tool: CLAUDE.md for Claude Code, .cursorrules for Cursor, .github/copilot-instructions.md for GitHub Copilot, AGENTS.md for OpenAI Codex. But they share the same purpose: providing AI agents with the context they need to make useful, convention-respecting suggestions.

As of 2025, these files have proliferated dramatically. Over 60,000 repositories on GitHub contain CLAUDE.md or .cursorrules files - a number that grew by an order of magnitude in 18 months as AI coding tools moved from early adoption to mainstream use. The open-source community has effectively standardized on the concept: when you create a project that uses AI tools, you add an instruction file. It's become as natural as adding a .gitignore or a README.md.

The ecosystem is currently fragmented. Each tool has its own file format and discovery mechanism. Cursor reads .cursorrules from the repository root and project-level .cursor/rules/ directories. Claude Code reads CLAUDE.md files at the root and in subdirectories, and merges them hierarchically. GitHub Copilot reads .github/copilot-instructions.md. Projects serious about AI tooling often maintain multiple files or a single canonical file that they reference from the tool-specific locations.

What these files contain ranges from minimal (tech stack + run commands) to comprehensive (architectural patterns, forbidden practices, per-module conventions, test requirements). The most effective instruction files are neither too short (missing critical context) nor too long (agents struggle to attend to instructions buried in thousands of lines of text).

The proliferation of agent instruction files reflects a broader shift in how software projects are organized. Documentation used to be for humans; agent instruction files are documentation for AI. As AI agents become standard collaborators, projects without instruction files are at a structural disadvantage - their agents make more mistakes, require more correction, and produce less consistent code.

• 60k+ repos demonstrates this is now a standard practice, not an experimental edge case
• Open-source examples provide templates - you can study how successful projects structure their instruction files before writing your own
• Tool ecosystem is converging - despite different file names, the structure and content of effective instruction files is becoming standardized
• First-mover effect in your organization - teams with good instruction files pull ahead of teams without them; the gap compounds over time as agents generate more code
• Cross-tool compatibility matters - as developers switch tools or use multiple AI tools, a well-structured instruction file that can be referenced from multiple locations reduces maintenance burden

The 60k+ number also serves as a practical benchmark. If you're evaluating whether to invest in writing a CLAUDE.md file, the answer from the open-source community is clear: organizations that take AI-assisted development seriously have already made this investment.

1. Choose your primary file - If your team uses Claude Code as the primary tool, start with CLAUDE.md. If Cursor is dominant, start with .cursorrules. You can always add the others later; start with what your team will benefit from immediately.
2. Study open-source examples - Search GitHub for filename:CLAUDE.md or filename:.cursorrules filtered to your language or framework. Look at highly-starred repositories in your tech stack. Notice the structure and content patterns that appear repeatedly.
3. Write the minimum viable file - Project overview (2-3 sentences), tech stack (bulleted list), setup commands (literal commands that work), top 5 conventions (specific, actionable rules). Commit this within a week of deciding to write it.
4. Add a subdirectory structure for complex projects - For monorepos or projects with distinct domains, create subdirectory-level instruction files. Claude Code reads CLAUDE.md files in subdirectories and merges them with the root file, which allows per-module conventions to coexist with project-wide standards.
5. Establish a review process - Assign a team member to review and update the instruction file quarterly. Add "update CLAUDE.md if this changes the architecture" to your PR template.
6. Measure the impact on something that survives review - Compare how often AI-assisted changes need a correction pass before they merge, in the weeks before and after the instruction file landed. Do not use suggestion acceptance rate for this: it moves whether or not the suggestions were any good. In most cases, the improvement is significant enough to be obvious without formal measurement.

Writing for humans, not agents. Instruction files read by agents should be explicit, structured, and unambiguous. Human-readable narrative documentation is good for READMEs. Agent instruction files benefit from clear section headers, bulleted lists, and precise directives. "Never use any types" is better agent instruction than "We try to maintain strong typing where possible."

Putting everything in one flat file. For large repositories, a single long CLAUDE.md becomes unwieldy. Agents' ability to attend to instructions degrades as file length increases. Use a hierarchical structure: root CLAUDE.md for project-wide context, subdirectory CLAUDE.md files for domain-specific conventions.

Treating tool-specific files as equivalent. .cursorrules and CLAUDE.md are read by different tools with different behaviors. A .cursorrules file that works well for Cursor autocomplete may not be appropriately structured for a Claude Code agent undertaking a multi-step task. Maintain tool-specific files that are optimized for each tool's behavior.

Not benefiting from the open-source ecosystem. The open-source community has done significant experimentation with agent instruction files. Don't start from scratch when there are thousands of public examples in your tech stack. Borrow liberally, adapting to your specific context.