CLAUDE.md: Make AI Truly Understand Your Project
One file to permanently store your project specs, architecture decisions, and team conventions — Claude reads it at every session start
Updated 2026-10-08
What is CLAUDE.md?
CLAUDE.md is a special file in your project root that Claude Code reads automatically at startup. It's a 'project briefing' for AI — containing tech stack, code conventions, directory structure, and key commands, so Claude understands your context without repeated explanations. As of 2026-10-07: if a repository has an AGENTS.md but no CLAUDE.md, Claude Code 2.1.277 and later reads the AGENTS.md instead.
The official docs frame it as the place where you write down what you would otherwise keep re-explaining: only facts every session needs belong inside, one-off task detail stays in the conversation (checked 2026-09-21).
A Plain Text File
It is a plain markdown file in the repo: you write it, commit it, read and diff it like anything else. Per the docs you write it and Claude Code reads it at the start of every session (checked 2026-09-21).
Loaded at Launch
CLAUDE.md in the working directory and every level above it loads at launch; subdirectory files load once Claude reads files there (checked 2026-09-21).
Context, Not Config
It loads into the context window every session and consumes tokens alongside your conversation, with no guarantee of strict obedience — the docs call it context, not enforced configuration (checked 2026-09-21).
Why CLAUDE.md?
The payoff is threefold: no more background typing at the start of each session, the same shape of output whoever asks, and onboarding that does not depend on oral tradition.
Eliminate Repetition
No more explaining 'we use TypeScript' or 'tests run with Jest' every session — write once, effective forever
Consistent Output
Define coding style, naming conventions, and architecture constraints to ensure Claude's output always matches project standards
Team Knowledge Sharing
When new members join, CLAUDE.md serves as both AI configuration and a human-readable project onboarding guide
Recommended Template
A good CLAUDE.md typically contains these sections
# Project Overview
- Order center backend, REST API for web and mini program
- New joiners read this file, then the onboarding guide
- Before an API change, check if clients need syncing
## Tech Stack
- Language TypeScript on Node.js, pnpm for packages
- PostgreSQL for data, hot reads served from Redis
- Vitest for tests, coverage gated in CI
## Directory Layout
- src/api: HTTP entry and arg checks, no business rules
- src/domain: business rules, no framework imports
- tests: mirrors the src tree, quick to locate failures
## Code Conventions
- Two-space indent, single quotes, keep semicolons
- Names spelled out, no abbreviations
- No framework types in the domain layer, that is a defect
## Common Commands
- npm run dev: start locally
- npm test: full unit suite, must pass before you stop
- npm run lint: once before committing
## Important Notes
- No secrets or internal URLs here, use env vars
- Run database migrations on a shadow database first
- Unclear edge case: ask, do not invent a defaultAdvanced Tips
These five points decide whether the file gets followed or becomes noise nobody rereads; each one gives a test you can run against your own file.
Only Recurring Facts
The test is blunt: is this line still useful next session? Build commands, naming rules and past pitfalls qualify; directory listings and dependency lists do not — Claude derives those from the code (checked 2026-09-21).
Stay Under 200 Lines
The reference line in the docs is under 200 lines per file; past that it eats more context and gets followed less often (checked 2026-09-21). If it does not fit, split into path-scoped rules that load only when Claude touches matching files.
Make It Verifiable
'Format code nicely' carries no information; 'two-space indent, single quotes, run npm test before committing' can be obeyed. Group lines under subheadings and bullets — Claude scans structure the way a reader does (checked 2026-09-21).
Generate, Then Trim
Do not start from a blank page: /init analyzes the codebase and drafts build commands, test setup and conventions it finds; then cut the filler the way /doctor does, keeping pitfalls and rationale; finish with /context to confirm the file loaded (checked 2026-09-21).
No Secrets Inside
This file lands in Git and is read by everyone in every session. Keep secrets, internal URLs and test accounts in environment variables; put personal preferences in CLAUDE.local.md and gitignore it so the team copy stays clean (checked 2026-09-21).
Team Collaboration Standards
Best practices for maintaining CLAUDE.md in multi-person projects
Review It as Code
The project copy is a team asset, not private notes: change it in the same PR as the code, explain why, and have the owner of that directory review it. The docs: project instructions are shared through version control (checked 2026-09-21).
Order and Conflicts
Files above load into context first, subdirectory ones on demand — content is concatenated, nothing overrides anything. If two files phrase the same behavior differently, Claude may pick either at random, so unify the wording or delete one (checked 2026-09-21).
Split by Module
In a big repo do not stuff the root file: module-specific notes go into a subdirectory CLAUDE.md or a path-scoped rule, which enters context only when Claude works there — cheaper and sharper than one huge root file (checked 2026-09-21).
Automate the Check
Make two things routine: CI checks that the root CLAUDE.md exists and stays inside the agreed size, and every architecture PR re-reads the existing entries. The docs likewise ask for periodic removal of stale and conflicting instructions (checked 2026-09-21).
Common Mistakes
All four turn the file from leverage into noise, and none of them needs a rewrite to fix.
Task Notes Not Rules
Pasting one bug's repro steps or one refactor's interim notes means they still occupy context next session while no general rule was written. That belongs in an issue or the PR description (checked 2026-09-21).
It Only Grows
The docs put the line at 200 lines: beyond it the file costs more context and gets obeyed less (checked 2026-09-21). Curing bloat by adding one more rule does not work — move what only matters in some directories out of it.
Rules Contradict
Root says pnpm, a subdirectory says npm — Claude may follow whichever it settled on (checked 2026-09-21). Keep one authoritative statement per topic and reference it from elsewhere instead of copying a second version.
Nobody Maintains It
The stack changed, the layout got refactored, the commands in the file are still the old ones. The docs ask for periodic review of every level, dropping outdated and conflicting entries (checked 2026-09-21) — easiest to trigger from the architecture PR.
FAQ
Feed CLAUDE.md Each Session?
No. A CLAUDE.md in your working directory or any directory above it loads automatically at session start; subdirectory files join when Claude reads code there. Run /context and check the Memory files list to see what actually loaded (checked 2026-09-21).
How Big Is Too Big?
The documented reference is under 200 lines per file; past that the context cost rises and adherence drops (checked 2026-09-21). Move per-module content into path-scoped rule files so it loads only when Claude touches the matching files.
What About AGENTS.md?
The default is either/or: any CLAUDE.md in your working directory or above it stops AGENTS.md from loading. To get both, set Project instructions in the /config panel to load both, or import the file from CLAUDE.md with @AGENTS.md (checked 2026-09-21). Added 2026-10-07: this behavior arrived in Claude Code 2.1.277 (released 2026-09-18), whose changelog reads “Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead”; since 2.1.281 (2026-09-23) it also works in LLM gateway sessions.
Who Maintains It?
Same workflow as code: the project copy lives in version control and is reviewed with the change that motivated it, whoever touches the architecture updates it. Personal preferences go into a separate local file under gitignore, and the docs ask for periodic cleanup of stale entries (checked 2026-09-21).
Team Practices with QCode.cc
One QCode.cc API key + unified CLAUDE.md = consistent and efficient AI coding for your entire team
One Key per Team
The team shares one QCode.cc key and usage is recorded under a single account, instead of a key per person (checked 2026-09-21).
Swap Models, Keep File
CLAUDE.md is read by the client inside the project and does not depend on which model answers, so switching models needs no rewrite.
One Starting Point
Everyone starts from the same place: a newcomer and a senior engineer ask with the same project premises in context, so output stops depending on who typed it.
Three Project Shapes
The same template should not produce the same file. These three repository shapes need different things spelled out; cut whatever is left.
Team Backend
Spell out build and migration commands, hard API compatibility rules and which directories are off limits; here the expensive part is what everyone repeats.
Open-Source Library
Contribution flow, test requirements, what counts as breaking: outside contributors and maintainers work from the same text, so each line must be verifiable.
Solo Tooling
Skip the full section list. Keep how to run it, the dependency version policy and hard constraints like 'do not reformat the whole file' — nothing more.
Write Better CLAUDE.md, Code Smarter
Project memory + QCode.cc plan = team AI coding best practices