developmentL2 GuidedContext Engineering

CLAUDE.md with basic project info

Adding a CLAUDE.md to your repository root is the single highest-leverage context engineering investment - it gives every AI agent the minimum viable information about what your project is and how it works.

·CLAUDE.md or equivalent exists with project description, tech stack, and top conventions
·Written coding conventions document exists and is referenced from agent instruction files
·Agent instruction files are committed to the repository (not local-only)

·CLAUDE.md includes explicit prohibitions (banned libraries, anti-patterns)
·Agent instruction files are reviewed as part of the standard PR process

Evidence

·CLAUDE.md, .cursorrules, or .github/copilot-instructions.md in repository root
·Coding conventions document accessible from agent instruction files
·Commit history showing agent instruction file updates

What It Is

CLAUDE.md is a special file that Claude Code reads automatically when it starts a session in your repository. It's the AI equivalent of the onboarding document you wish you'd had on your first day: it tells the agent what the project is, how to run it, what the tech stack looks like, and what conventions to follow. Other tools have their own equivalents: .cursorrules for Cursor, .github/copilot-instructions.md for GitHub Copilot, AGENTS.md for OpenAI Codex.

The concept is simple: a markdown file in your repository root that provides project-level context to any AI agent that reads it. Before this file exists, every agent session starts from zero - the agent knows nothing about your project beyond the file currently open. After this file exists, every session starts with the minimum viable context: what this project is, how it fits together, and what the agent needs to know to not make obvious mistakes.

At L2 (Guided), the CLAUDE.md file typically contains basic project information: the tech stack, how to install and run the project, a brief architectural overview, key directories and their purposes, and the most important do's and don'ts. It doesn't need to be comprehensive to be valuable - even a 200-line CLAUDE.md dramatically improves suggestion quality compared to no file at all.

The transition from L1 to L2 is largely defined by the creation of this file. It's the first act of intentional context engineering: the team explicitly decides what information the agent needs and writes it down in a form the agent can use.

Why It Matters

The impact of a CLAUDE.md file is disproportionate to its size. A few hundred lines of well-chosen content can prevent thousands of wrong suggestions across the team:

Eliminates the most common class of wrong suggestions - tech stack mismatches, wrong import paths, missing required configuration, use of deprecated APIs
Applies to all developers on the team - unlike a developer's personal "context preamble" habit, a committed CLAUDE.md benefits everyone who opens the repo
Persists across sessions - context you've written down doesn't disappear when you close the chat window
Scales with the team - new developers get better AI suggestions from day one, without learning what manual context to provide
Creates a foundation for L3 - the CLAUDE.md file is the substrate on which more sophisticated context engineering builds

The measurable impact: teams that add a well-crafted CLAUDE.md typically report a 30-50% improvement in AI suggestion acceptance rates within the first week. The suggestions stop violating project conventions and start following them.

Tip

Write your CLAUDE.md as if you're briefing a capable contractor who is starting work on your codebase tomorrow. They're smart and experienced, but they know nothing about your project. What do they absolutely need to know in the first 10 minutes?

Getting Started

Create the file - Add CLAUDE.md to your repository root. For Cursor users, add .cursorrules instead (or in addition). For GitHub Copilot, add .github/copilot-instructions.md.
Write the project overview section - One paragraph: what this project does, what problem it solves, what kind of application it is. Include the primary language and framework.
Document the tech stack - List the key dependencies with a one-line description of each. Include version constraints if they matter (e.g., "We use React 18 - do not suggest React 19 features").
Add setup and run instructions - The commands needed to install dependencies, run tests, and start the development server. Keep these in sync with the README.
Capture the top 5 conventions - What are the most important rules that aren't enforced by linters? Architecture patterns, naming conventions, module boundaries, state management rules. These are the ones agents most commonly violate.
Add a "what not to do" section - Explicit don'ts prevent agents from confidently suggesting patterns you've rejected. "Do not use any types in TypeScript." "Do not add new npm dependencies without team discussion." "Do not write SQL queries outside of the repository layer."

6 steps to get from here to the next level

Common Pitfalls

Making it too long too fast. The temptation is to document everything at once. A 3,000-line CLAUDE.md that takes weeks to write and never gets committed is worse than a 200-line file committed today. Start minimal: project overview, tech stack, setup instructions, top 5 conventions. Add to it as you discover what's missing.

Letting it go stale. A CLAUDE.md that describes the wrong tech stack is worse than no CLAUDE.md - it gives agents incorrect context confidently. Add a "last updated" date and a team norm that architecture changes require a CLAUDE.md update alongside the code change.

Treating it as a style guide. Style guide content (use 2-space indentation, sort imports alphabetically) belongs in linter configuration, not CLAUDE.md. The CLAUDE.md is for semantic conventions the linter can't enforce: when to use a service vs. a repository, how to structure feature modules, what belongs in shared utilities vs. domain logic.

Not committing it to the repo. CLAUDE.md files stored locally on one developer's machine don't help the team. Commit it to version control so every developer - and every agent session - benefits.

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 complaining that AI suggestions are inconsistent - they work great for some developers and not others. He suspects it has to do with the senior engineers' habit of providing detailed context in their prompts, while junior engineers just describe the immediate task. He's right, but he doesn't know how to systematize it.

What Bob should do: Bob should sponsor a "CLAUDE.md sprint" - one dedicated afternoon where one senior engineer per team produces the first version of a CLAUDE.md for their primary repository. Bob's goal for this sprint is not perfection; it's existence. A basic CLAUDE.md committed to every main repository within the quarter. He should then track acceptance rates before and after for teams that complete the sprint, which gives him the ROI data he needs to continue investing in context engineering.

What Bob should do - role-specific action plan

SarahProductivity Lead

Sarah has been trying to understand why AI adoption is so uneven across teams. She runs a survey and finds that developers in teams without shared context files (CLAUDE.md, .cursorrules) rate AI tools much lower than developers in teams that have them. The pattern is clear, but she hasn't been able to make the business case for investing time in these files.

What Sarah should do: Sarah should calculate the "context tax" - the time each developer spends per week manually providing project context in prompts before the agent can help effectively. Even if the estimate is rough (say, 15 minutes per developer per day in a team without CLAUDE.md), the math quickly justifies the one-time investment of writing the file. A 10-person team spending 15 minutes/day = 2.5 engineer-hours per day = 600+ engineer-hours per year spent on a problem a 200-line file could fix.

What Sarah should do - role-specific action plan

VictorStaff Engineer - AI Champion

Victor has been the unofficial "AI whisperer" on his team - developers come to him when they're getting bad suggestions, and he shows them the right context to provide. He's been doing this for months and realizes he's essentially teaching the same 10 things over and over.

What Victor should do: Victor's teaching material is the content of a CLAUDE.md file. He should take the 10 things he consistently explains, write them up as a structured context file, commit it to the main repositories, and point developers to it instead of repeating himself. Then he should go further: write a brief guide for the team on how to interpret and extend the CLAUDE.md file, and propose a quarterly review process where the team discusses what should be added based on recent agent errors. Victor is the right person to drive this from technical judgment; Bob should provide the organizational mandate.

What Victor should do - role-specific action plan