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 (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.

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.

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