developmentL2 GuidedCoding Agent Usage

CLAUDE.md / .cursorrules in repo

How to write an agent instruction file that teaches AI tools about your project's conventions, patterns, and constraints - the single highest-leverage action at L2.

·At least one agentic IDE (Cursor, Windsurf, or Claude Code) is used by 50%+ of the team
·CLAUDE.md, .cursorrules, or equivalent agent instruction file exists in 100% of active repositories
·Agents operate in agentic/YOLO mode (multi-step edits without per-step approval)

·Developers use two or more AI tools in parallel (e.g., Copilot + Claude Code)
·Agent instruction files are reviewed and updated at least quarterly

Evidence

·Agent instruction files committed in repository root
·IDE telemetry or license dashboard showing agentic mode usage
·PR descriptions referencing agent-assisted development

What It Is

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.

Why It Matters

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.

Tip

Start by listing the three most common corrections you make to AI-generated code. Each of those corrections represents a convention the AI doesn't know about. Write those three rules first. A three-rule CLAUDE.md is dramatically better than none.

Getting Started

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.
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.
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/."
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."
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.
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.

Tip

Ask your AI tool to review its own CLAUDE.md after you write it. Prompt: "Read this CLAUDE.md and tell me what questions you still have about the project that would help you give better suggestions." The AI will often identify the gaps you missed.

6 steps to get from here to the next level

Common Pitfalls

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.

Mistakes teams actually make at this stage - and how to avoid them

How Different Roles See It

BobHead of Engineering

Bob's team has been using AI tools for months with inconsistent results. Some developers love it; others think it's a distraction. Bob suspects the inconsistency is related to how different developers interact with the AI, but he can't pinpoint why.

What Bob should do: The inconsistency is almost certainly a context gap problem, and CLAUDE.md is the fix. Bob should identify his team's most effective AI user - likely someone like Victor - and have them lead a 2-hour session to write the first CLAUDE.md for one repository. Commit it, have the whole team use it for two weeks, then run a before/after comparison on AI output quality. Bob's goal: make this a standard part of repository creation, like adding a README. Every new repo gets a CLAUDE.md in the initial setup commit. This policy alone moves the team from L1 to L2 in measurable ways.

What Bob should do - role-specific action plan

SarahProductivity Lead

Sarah needs to show that the AI tooling investment is delivering value. Her previous L1 metrics (acceptance rate, developer sentiment) weren't convincing stakeholders. She needs a more concrete story.

What Sarah should do: Sarah's L2 story is: "we added a CLAUDE.md to our three most active repositories, and here's what changed." Measure three things before and after: (1) the number of AI suggestions that were accepted vs. rejected with corrections in code review, (2) the time from PR open to merge for AI-assisted features vs. manually written features, and (3) developer satisfaction scores for AI tool usefulness. The CLAUDE.md is a controlled intervention - before/after comparisons are credible because the only variable that changed is the instruction file. This is Sarah's cleanest measurement opportunity in the entire maturity journey.

What Sarah should do - role-specific action plan

VictorStaff Engineer - AI Champion

Victor already has a personal .cursorrules file he maintains locally. It's comprehensive, specific, and explains exactly why certain patterns are used in the codebase. His AI-assisted code is consistently better than what the team gets without it - but because it's local, nobody else benefits.

What Victor should do: Victor needs to convert his personal rules file into a team resource. The process: audit his local .cursorrules for anything project-specific vs. personal preference, extract the project-specific rules into a CLAUDE.md in the repo root, and PR it with a clear explanation of each rule. Victor should also propose a governance model: who can add rules, how are conflicting rules resolved, how often is the file reviewed? Making CLAUDE.md a first-class team artifact - with ownership and maintenance process - is what distinguishes L2 from L3. Victor is the natural person to establish this standard.

What Victor should do - role-specific action plan