Essential Guide to Writing CLAUDE.md for Claude Code

What is CLAUDE.md? CLAUDE.md is the configuration file automatically loaded by Claude Code at the start of each session, used to store project conventions, code style guidelines, and frequently used commands.

Core value: It eliminates repetitive instructions and ensures preferences persist across sessions.

Quick start

Run /init to generate the initial file.

"Trim aggressively" – keep only essential content because context space is precious.

Add your project's code style and specific conventions.

File locations

CLAUDE.md

in the project root – most common, committed to version control for team sharing. ~/.claude/CLAUDE.md – user‑level global default configuration. CLAUDE.local.md – personal preferences, added to .gitignore so it is not committed. subdirectory/CLAUDE.md – loaded only when Claude processes code in that directory.

Four mandatory sections

① Project positioning – a one‑sentence description, e.g., "E‑commerce app built with Next.js 14, Stripe, and Prisma ORM".

② Code style – concrete and executable, e.g., "TypeScript strict mode, forbid any, use named exports".

③ Common commands – list commands such as npm run test / npm run lint / npm run db:migrate.

④ Project pitfalls – examples like "Stripe webhook must verify signature" and "Never commit .env files".

Structuring tips

Keep the file under 300 lines, ensuring every line adds value. Use @引用 to stay concise, e.g.:

API 规范见 @docs/api-patterns.md
认证流程见 @docs/authentication.md

Place core content in the main file; detailed explanations go in separate files referenced with @. For large projects split rules into .claude/rules/:

.claude/rules/
├── code-style.md   # maintained by frontend team
├── testing.md      # maintained by QA team
└── security.md    # maintained by security team

These files are auto‑loaded, avoiding manual imports and merge conflicts.

Maintenance – let it grow naturally

Instant addition: when Claude makes a wrong assumption, simply tell it to "add this rule to CLAUDE.md".

Learn from PRs: if a review uncovers undocumented conventions, add them to avoid repeats.

Periodic review: let Claude audit the file every few weeks to clean redundant or conflicting rules.

Emphasize wisely: mark truly critical rules with "important" or "must", but avoid over‑marking.

Finally, you can send this article to Claude so it can review your CLAUDE.md for completeness and correctness.