An agent instruction file in every repository

CLAUDE.md (for Claude Code), .cursorrules (for Cursor), and .github/copilot-instructions.md (for GitHub Copilot) are instruction files committed to your repository root that tell AI tools about your project. When an AI agent reads your codebase, it reads these files first and uses their contents to filter and shape every subsequent suggestion, edit, and decision.

These files are the simplest, highest-leverage form of context engineering. A well-written CLAUDE.md transforms an AI agent from a generic code generator into something that knows your project: your tech stack, your naming conventions, your architectural decisions, your forbidden anti-patterns, and your preferred libraries. The same model that was suggesting Redux patterns in your Zustand project will now correctly use Zustand - because you told it to.

The concept has spread rapidly. As of 2025, over 60,000 repositories on GitHub contain a .cursorrules file, and the practice of committing agent instruction files is becoming a standard part of repository setup alongside .gitignore and README.md. This is not a tool-specific feature - it's an emerging best practice for AI-assisted development.

What makes this an L2 capability rather than a personal habit is coverage. One excellent instruction file in the flagship repository, and nothing in the forty others people actually work in, is not the same capability at a smaller scale - it is a different thing entirely, because an agent's behaviour is only as good as the worst-instructed repository it is pointed at. The bar is that every active repository ships one, in the same way every active repository ships a README: not necessarily a good one on day one, but present, committed and owned.

Active is doing real work in that sentence. Archived repositories, one-off experiments and things nobody has touched in two years do not need instruction files, and pretending otherwise turns a useful standard into a compliance exercise. The list that matters is the repositories people and agents open this quarter.

At L2 (Delegated), a single root-level file per repository is the starting point. At L3 (Systematic), teams evolve to per-team and per-directory files with more precision. But the root-level file is where every team begins, and even a 100-line version produces immediately visible improvement in AI output quality.

The instruction file is the bridge between L1's context blindness and L3's systematic context engineering:

• Immediate improvement in suggestion quality - the AI stops recommending patterns you've banned and starts following your conventions
• Team-wide benefit from individual effort - one developer writes the file; every developer's AI quality improves when it's committed
• Coverage is what turns it into a capability - agents move between repositories constantly, and one uninstructed repository is where the bad suggestions come from; the value is in the least-covered repository, not the best one
• Captures tribal knowledge - conventions that exist only in senior developers' heads become queryable, enforceable context for the entire team
• Reduces review friction - when the AI follows your conventions, reviewers spend less time correcting style issues and more time reviewing logic
• Low cost, high return - a half-day investment to write a CLAUDE.md typically improves AI output quality enough to save multiple hours per week per developer

Without an instruction file, AI agents are at their worst in established codebases - the more decisions your team has made about patterns and conventions, the more opportunities there are for the AI to violate them. The instruction file directly addresses this inverse relationship.

1. Create the file - Add CLAUDE.md to your repository root (or .cursorrules for Cursor-first teams, or .github/copilot-instructions.md for Copilot teams). Commit it with an initial commit to establish the pattern.
2. Start with project basics - First section: what the project does, the primary tech stack, and the language/framework versions. The AI needs to know it's in a Next.js 14 + TypeScript project vs. a Django + Python project before any other context matters.
3. Document your must-follow conventions - Naming patterns, file structure, import conventions, state management approach. "We use Zustand for state management, not Redux or Context API. All stores are in /src/stores/."
4. Document your explicit prohibitions - Libraries you've decided against, patterns you've banned, anti-patterns that caused incidents. "Do not use any in TypeScript. Do not use console.log for logging - use the logger from @/lib/logger."
5. Add architecture notes - Key decisions that explain why the codebase is structured the way it is. These prevent the AI from "helpfully" refactoring things in ways that break implicit contracts.
6. Iterate based on AI misfires - After committing the initial file, watch for AI suggestions that still violate your conventions. Each misfire is a missing rule. Add it. The file improves continuously.
7. Make coverage measurable, then close the gap - List every repository with a commit in the last quarter and check which ones have an instruction file. The proportion is the metric for this level. Add the file to your repository template so new repositories start with one, and work the backlog of existing repositories in order of how much agent traffic they see rather than alphabetically.

Writing it once and never updating it. CLAUDE.md is a living document. As your project evolves - new libraries, deprecated patterns, architectural decisions - the instruction file must keep pace. Stale instructions are worse than no instructions because they tell the AI to do things you've moved away from. Assign someone to review and update it quarterly.

Making it too long. There's a temptation to document everything. Resist it. A 2,000-line CLAUDE.md dilutes the signal with noise. AI models have attention limits; the most important instructions should be near the top, and everything should be genuinely actionable. If a rule doesn't affect AI behavior, cut it.

Being vague about conventions. "Follow best practices" is not a convention. "Use functional components with TypeScript interfaces for props, not classes or PropTypes" is a convention. The more specific and example-driven the instruction, the more reliably the AI follows it.

One great file, forty repositories without one. The usual shape of failure at this level is not a bad instruction file but a missing one. A team invests heavily in the main service's file, gets a visible improvement, and stops - while agents continue producing generic, convention-violating code everywhere else, which is then blamed on the model. Track coverage across active repositories, not the quality of your best example.

Not sharing it with the team. CLAUDE.md is worthless if it lives on one developer's fork. It must be committed to the main repository, included in onboarding docs, and treated with the same importance as linting configuration. Run a team session to review and add to it when it's first created.