How to write a useful CLAUDE.md.

What is CLAUDE.md?

CLAUDE.md is a Markdown instruction file used by Claude Code to learn project-specific guidance. Its value comes from accurate commands, conventions and constraints that help the tool work in this repository.

Include facts an agent can verify

Document the package manager, working directory, useful checks, module boundaries and error-handling conventions. Include a short explanation of why an important constraint exists. Do not fill the file with generic advice that hides the project-specific details.

Make commands concrete

Check each command in the actual checkout before adding it. For a hypothetical npm application, an instruction could distinguish the build from the test suite and explain which workspace owns each command.

# Project instructions

## Validation
- Install from the lockfile: npm ci
- Run application tests: npm run test:run
- Build the frontend: npm run build

## Changes
- Follow nearby naming and error-handling conventions.
- Never put credentials in source or generated examples.
- Review the diff before proposing a change.

Maintain it when the code changes

Treat the file as maintained documentation. Review it when moving directories, replacing frameworks or changing validation commands. Use a context scan to identify possible gaps, then verify every proposed change yourself.