The idea

A coding agent is more useful when it knows the stable facts of your repository: how to run tests, where a service lives, or which conventions matter. You could restate those facts in every chat. A CLAUDE.md is a better home for the facts that the whole team intentionally wants to keep.

CLAUDE.md is a human-maintained Markdown file containing persistent project instructions for Claude Code. Project-level files can be shared through version control. A personal CLAUDE.local.md is for project-specific settings that should stay out of the repository; the documentation says to add it to .gitignore. Source: Claude Code documentation

Plain English: Treat CLAUDE.md like a short, versioned onboarding note for an AI coding helper. It supplies guidance; it does not grant or remove permissions.

This distinction matters. Claude Code treats CLAUDE.md as context, not as a hard technical enforcement mechanism. Put desired behavior there, but do not rely on a sentence such as “never edit secrets” as a protection boundary. For rules that must be technically enforced, use a Hook or a managed setting where appropriate. Hooks run in response to lifecycle events and can, for example, block commands before they run. Source: Claude Code documentation

Keep shared instructions deliberately small and concrete. Good candidates are build and test commands, important directories, code conventions, and checks required for a common change. A long policy document is harder to maintain and gives the agent more competing instructions to interpret.

Do not confuse the file with Auto Memory. CLAUDE.md is written and reviewed by people. Auto Memory is written by Claude from corrections, preferences, and useful project-specific findings. Its files are machine-local rather than shared between machines or cloud environments. That makes Auto Memory a poor replacement for team standards. Source: Claude Code documentation

A small example

Example: Your team maintains a Node service. A compact CLAUDE.md might say:

Run `npm test` before proposing a change.
Run `npm run lint` for TypeScript changes.
API handlers are in src/api/.
New endpoints need input validation and tests.

Each line answers a question the agent would otherwise need to ask or rediscover. The file does not replace code review, tests, or access controls. It gives the agent a shared starting point.

Suppose your local machine also has a sandbox URL and throwaway test-account details. Those are personal project settings, so put them in CLAUDE.local.md and keep that file out of version control. This separates team context from a developer’s local setup. Source: Claude Code documentation

You may also encounter AGENTS.md. It is a Markdown format intended for instructions shared across coding agents and has no required fields. Claude Code can read it directly. By default, it uses AGENTS.md when it finds no applicable CLAUDE.md or CLAUDE.local.md; configuration can allow both file types to be read. Support and loading behavior in other tools can differ. Sources: Claude Code documentation AGENTS.md

For a detailed repeatable procedure, such as preparing a release, consider a Skill instead. Skills use SKILL.md files and their main instructions load when called or when Claude Code identifies them as relevant. That avoids making every session carry a procedure it does not need. Source: Claude Code documentation

Try it

Set a five-minute timer. Create or review your project’s CLAUDE.md and write four short bullets: one test command, one lint or build command, one important directory, and one change rule. Then ask two questions:

  1. Is every bullet useful to every teammate?
  2. Is any bullet actually a security or safety requirement?

Move private machine details into CLAUDE.local.md and add it to .gitignore. For each requirement that must not be bypassed, investigate a managed setting or a PreToolUse Hook rather than trusting prose alone. This is a classification exercise, not a request to deploy a Hook without review.

Watch out

CLAUDE.md can be misunderstood, contradicted, or ignored. It is guidance, not a guarantee. Check it in code review like other project documentation.

Also check which instruction files your installed Claude Code version and configuration load. AGENTS.md is useful as a cross-agent convention, but agent support is not universal. Finally, review Hooks carefully: they can offer more deterministic control than instructions, but they also execute configured actions and add operational responsibility. Sources: Claude Code documentation AGENTS.md