# How to write a useful CLAUDE.md.

> A practical guide to keeping Claude Code instructions specific, verifiable and aligned with your repository.

Canonical page: https://prompterjack.com/guides/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.

```text
# 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.

## Should CLAUDE.md contain secrets?

No. Reference the names and purpose of required configuration without including credential values, tokens or private customer data.

## References

- [Claude Code: memory and instructions](https://code.claude.com/docs/en/memory)

## Next step

[Inspect your repository](https://prompterjack.com/codebase)