CLAUDE.md / .cursorrules in repo

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.

At L2 (Guided), a single root-level CLAUDE.md 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
• 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.

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.

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.