CLAUDE.md Guide: What to Put in Your Project Instructions
CLAUDE.md is a project briefing for Claude Code. It is most useful when it captures stable facts and rules Claude would otherwise have to rediscover every session.
Quick answer
Include the commands Claude should run, architecture it must understand, code conventions it should follow, files or areas it should avoid, and the definition of done for common work. Keep instructions specific and update them as the project changes.
Good content for CLAUDE.md
Document build, test and lint commands; important architecture boundaries; naming and formatting rules; deployment constraints; and project-specific review expectations.
Use imports for modular instructions
Claude Code supports imports in CLAUDE.md, which helps keep the root briefing concise while making deeper instructions available from separate files.
Avoid generic advice
Instructions such as “write clean code” add little value. Prefer rules Claude can act on and verify.
CLAUDE.md starter example
# Project
Next.js application using the Pages Router.
## Commands
- npm test
- npm run build
## Rules
- Do not change public URLs without redirects.
- Run regression tests before opening a PR.
- Keep tool pages crawlable and server-rendered where practical.Official Claude documentation
Claude Code changes quickly. Use Anthropic’s documentation as the source of truth for current configuration fields and behavior.
Open Anthropic docs →Related Claude tools and guides
Frequently asked questions
Where should CLAUDE.md live?
A project CLAUDE.md can live in the repository. Claude Code also supports user-level instructions for preferences across projects.
Can CLAUDE.md import other files?
Yes. Claude Code supports imports so larger instruction sets can be modularized.
Should secrets go in CLAUDE.md?
No. Do not store secrets or credentials in project instruction files.