What is CLAUDE.md?
CLAUDE.md is a Markdown file used by Claude Code to provide persistent project instructions and context.
CLAUDE.md as a project briefing for Claude Code.
What is CLAUDE.md used for?
A project-level CLAUDE.md can describe information Claude should know when working with your codebase.
Typical content can include:
- Project architecture
- Development commands
- Testing workflows
- Coding conventions
- Repository structure
- Important project-specific instructions
CLAUDE.md example
# CLAUDE.md ## Project Overview This project is a SaaS application built with TypeScript, React and Node.js. ## Development Install dependencies: npm install Start development: npm run dev ## Testing Run the test suite before submitting changes: npm test ## Coding Guidelines - Use TypeScript strict mode - Prefer small, focused functions - Follow existing project patterns - Add tests for new functionality - Avoid unnecessary dependencies ## Architecture Frontend: React application in /src Backend: Node.js API in /server Tests: /tests ## Working Guidelines Before implementing a feature: 1. Inspect the existing implementation 2. Reuse existing patterns 3. Keep changes focused 4. Run relevant tests
Where does CLAUDE.md go?
For project-wide instructions, a CLAUDE.md file can be stored at the root of the repository.
my-project/ ├── CLAUDE.md ├── PROJECT-GOALS.md ├── README.md ├── package.json └── src/
CLAUDE.md vs PROJECT-GOALS.md
| File | Purpose |
|---|---|
CLAUDE.md |
Instructions and context for Claude Code working on the project. |
PROJECT-GOALS.md |
Defines what the project should achieve, its requirements and scope. |
The distinction is useful:
- PROJECT-GOALS.md: What are we building and why?
- CLAUDE.md: How should Claude work within this project?
CLAUDE.md vs AGENTS.md
Both files can provide instructions to coding agents, but CLAUDE.md is specifically associated with Claude Code, while AGENTS.md is designed as a more general agent-instruction format.
A repository may therefore use different files depending on which coding agents and workflows it supports.
A practical project structure
my-project/ │ ├── README.md ├── PROJECT-GOALS.md ├── CLAUDE.md ├── AGENTS.md │ └── src/
Each file answers a different question:
README.md— What is this project?PROJECT-GOALS.md— What are we trying to achieve?CLAUDE.md— How should Claude work on it?AGENTS.md— How should coding agents work on it?
Create a PROJECT-GOALS.md file that defines your project's objectives, requirements and boundaries.
Generate PROJECT-GOALS.md