CLAUDE.md with basic project info

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 (Delegated), 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.

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 shows up in the code rather than on the vendor dashboard: within the first week, suggestions stop violating project conventions and start following them, which reaches the team as fewer correction passes in review. Do not try to read that change off suggestion acceptance rate - DECODE's instrumented study of 53.6K in-IDE edits found 31% of accepted completions deleted outright, most of them within fifteen minutes, so the number rises whether or not the suggestions were worth keeping.

August produced the first large-sample evidence that committing the file is the part that counts, not merely writing one. A study of 441 repositories (arXiv 2608.25241, August 26) found that agents produced 28-38% more commits, and that repositories without committed AI configuration saw twice the cognitive-complexity increase - +53% against +27% - along with 1.7x the static-analysis warnings. The same study found that 73.8% of AI configuration files were committed once and never touched again, which is precisely the staleness failure this guide warns about below.

1. 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. For Codex and the growing set of tools that read AGENTS.md, a symlink keeps one file authoritative: Anthropic closed the native-support request on August 17 without adding native support, and the symlink is the accepted answer.
2. 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.
3. 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").
4. 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.
5. 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.
6. 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."

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.

Forgetting that committed agent config is executable. The ChainDrop compromise on August 4 planted persistence in .vscode/tasks.json (runOn: folderOpen) and .claude/settings.json (SessionStart), so opening the repository or starting an agent session ran the payload with no npm install involved. The moment you commit agent configuration, it joins the set of files that execute on someone else's machine. Put .claude/, .vscode/, .cursor/ and .gemini/ on a mandatory-diff path in code review, and disable auto-run hooks for workspaces you did not write.