CLAUDE.md — Teaching Claude Your Codebase

Every time you start a Claude Code session without a CLAUDE.md file, you are onboarding a new engineer who knows nothing about your project. By the time you have explained the framework, the folder layout, the selector conventions, and the off-limits files, you have spent five minutes on context that will evaporate the moment the session ends. CLAUDE.md solves this permanently.

What CLAUDE.md is

A Markdown file at your project root that Claude Code reads automatically at the start of every session. It is your standing brief — the things that are true about your project that every session should know without asking. Run /init in interactive mode to generate a draft:

> /init

Claude reads the project and produces a starting CLAUDE.md. Edit it: add the constraints that matter, delete the generic content that doesn't.

What to put in it for a QA project

Here is a real example for a Playwright TypeScript project:

# MyApp Test Suite
 
## Stack
- Playwright Test 1.x with TypeScript
- Page Object Model — POMs live in src/pages/
- Allure Reports
- GitHub Actions for CI
 
## Locator conventions
Priority order:
1. getByTestId — preferred for stability
2. getByRole + getByLabel — for elements without test IDs
3. Never use CSS classes or XPath
 
## Test structure
- Tests: tests/<feature>/<scenario>.spec.ts
- POMs: src/pages/<Page>Page.ts (e.g. LoginPage.ts)
- Fixtures: tests/fixtures/
- Use describe for grouping, test for individual cases
- Test names: "should <do something> when <condition>"
 
## Test data
- Never hardcode credentials — use process.env
- Never hardcode IDs — use factories in src/factories/
 
## Commands
- npm test — full suite
- npm run test:smoke — smoke suite
- npm run test:headed — visible browser
 
## Constraints
- Do not edit files in src/components/
- Do not use page.waitForTimeout — use proper waits
- Do not commit .only or .skip without an explanatory comment
- The staging URL is https://staging.myapp.com
- The signup flow has an iframe — use frameLocator('iframe[src*="signup"]')

Every constraint in that file saves a correction later. "Do not use page.waitForTimeout" added to CLAUDE.md means you never have to type that instruction in a prompt again.

Project-specific gotchas are the most valuable entries

The generic entries (framework, folder layout) are helpful. The gotchas are what make CLAUDE.md genuinely valuable — the things that would surprise a knowledgeable outsider about your specific setup:

• "The payment form is in a third-party iframe"
• "API responses on staging can take 8+ seconds — default timeouts are insufficient"
• "Tests run in parallel with 4 workers; test data must be unique per test to avoid conflicts"
• "The admin section requires two-factor authentication — use the OTP helper in tests/helpers/otp.ts"

These are exactly the things you would tell a new engineer on day one. They are also exactly the things a session without CLAUDE.md will get wrong.

For teams and monorepos

Commit CLAUDE.md to version control. Every team member's Claude Code sessions benefit immediately, and the file evolves with the codebase via the normal review process.

For monorepos, create a root CLAUDE.md with project-wide conventions plus per-package CLAUDE.md files in each subdirectory. Claude Code reads both — the root file for global rules, the local file for package-specific conventions.

Keeping it maintained

CLAUDE.md is living documentation. When a convention changes, update it. When a new gotcha is discovered, add it. When you find yourself correcting Claude Code for the same mistake twice, that correction belongs in CLAUDE.md.

The failure mode is a stale CLAUDE.md — instructions that no longer reflect the project. Treat it like any other developer documentation: review it when onboarding someone new, and update it whenever conventions change.

⚠️ Common Mistakes

• Making it too long. A 200-line CLAUDE.md dilutes the important instructions with filler. If Claude Code needs to read an essay to start a session, the key rules get lost. Aim for a focused one-pager.
• Not committing it. A CLAUDE.md that lives only on one machine helps only one person. Commit it, review it in PRs like any other documentation.
• Forgetting to update it. A stale CLAUDE.md actively misleads. If it says "use data-testid" but the convention changed, Claude Code follows the wrong rule confidently. Schedule a CLAUDE.md review whenever conventions change significantly.

🎯 Practice Task

Write a CLAUDE.md for a real project. 20 minutes.

1. Run claude in a project you work on and use /init to generate a draft.
2. Edit the output: add your actual locator conventions, your off-limits files, and at least two project-specific gotchas that would trip up an outsider.
3. Delete anything generic that doesn't add real value.
4. Start a fresh Claude Code session and ask: "What conventions does this project follow for test organisation and selector strategy?" Confirm the answer comes from your CLAUDE.md.

The next lesson covers custom slash commands — packaging your recurring QA workflows into reusable shortcuts the whole team can share.