CLAUDE.md is a Markdown instruction file for Claude Code. It describes how to work in your project: which commands to run, which conventions matter, and which mistakes to avoid. It is different from a Markdown report that Claude generated for you. If you only want to read such a report, start with opening an MD file.
This guide helps you write a small project briefing, inspect its formatting, and check that Claude Code loads it.
For shared project instructions, place CLAUDE.md at the repository root. Claude Code also supports .claude/CLAUDE.md. Personal instructions can live in ~/.claude/CLAUDE.md; subdirectory files serve narrower parts of a project. See Anthropic's instruction-file documentation for loading details.
Use the exact filename, including capitalization on case-sensitive systems. A file accidentally saved as CLAUDE.md.txt is a different file. The MD file creation guide explains how to avoid hidden-extension mistakes.
The following is an illustrative briefing for a small web application, not a configuration for every repository. Replace the paths and commands with ones you have checked in your own project.
# Project instructions
## What this application does
A browser application for reviewing technical documents.
## Commands
- Install dependencies: `npm ci`.
- Run the relevant existing tests: `npm test`.
- Check the production build: `npm run build`.
## Code conventions
- Use the existing component and naming patterns in nearby files.
- Keep input validation at the API boundary.
- Explain any change to a public response field.
## Working with changes
- Read the current Git diff before editing.
- Preserve unrelated local edits.
- Report which checks ran and any checks that could not run.
- Deployment requires an explicit request from the project owner.Before adopting the example, look at your package manifest. If there is no test script or no npm lockfile, these commands are not ready to copy. Replace the application description with one accurate sentence. Remove rules that add no information beyond the surrounding code.
CLAUDE.md in its root./context and inspect the memory-file list for the expected path.Claude Code's /init can generate a starting file; review its proposed commands against the repository. A plausible command is not evidence that it exists. A harmless first task, such as explaining a module, is a useful way to check whether the briefing communicates what you intended.
Write the facts you would otherwise repeat to a teammate. For example, replace “follow our testing process” with the actual relevant command and when to run it. Keep instructions consistent and focused. Anthropic recommends short files and explains that these instructions provide context, not an enforced permission boundary. Put access controls in the tools and environment as well. Official guidance
Do not use a shared briefing as storage for credentials, customer data, or copied production logs. Prefer a reference to the established secret-management process. Review its Git diff before committing it, just as you would review an application change.
| File | Main purpose |
|---|---|
CLAUDE.md |
Instructions you maintain for Claude Code |
README.md |
Documentation for people using or contributing to the project |
Auto-memory MEMORY.md |
Notes Claude Code maintains across work sessions |
Avoid maintaining two conflicting copies of the same command. A README can explain the full development workflow while the instruction file points to it and records a few project-specific constraints. Anthropic's context guide explains the role of the project briefing.
Open the file in mdview.io to inspect headings, lists, links, and fenced examples. Previewing checks how the document reads; it does not prove that Claude Code loaded it or will follow every instruction. Use the session checks above for that.
Before sharing, confirm that examples render as code, links lead to the intended documentation, and the briefing contains no private values. For source inspection without leaving your shell, see terminal Markdown readers.