The Role of CLAUDE.md

Explains what CLAUDE.md does in Claude Code, what to write as project memory, and how to operate imports and hierarchical rules.

Overview

CLAUDE.md is a memory file that Claude Code reads when it starts working on a project. It stores information that is hard to repeat in every prompt, such as the repository purpose, main commands, coding rules, test procedures, and areas that must not be modified.

Claude Code can read the codebase and understand the current state, but it does not automatically know a team’s implicit rules or operational constraints. CLAUDE.md explicitly provides this background knowledge and improves consistency in answers and work style.

When CLAUDE.md Is Useful

It is useful when a project has defined build, lint, test, and local run commands; directories that must not be changed without approval; procedures for adding packages or migrations; team-specific frontend, backend, or test rules; required verification commands; or rules for secrets, customer data, and .env files.

When multiple people use Claude Code in the same repository, shared team rules should be written in the repository’s CLAUDE.md, not in each person’s private prompt.

Types of Memory Files

Claude Code can use memory files in several locations.

Type	Location	Main use	Scope
Organization memory	macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md` Linux: `/etc/claude-code/CLAUDE.md` Windows: `C:\ProgramData\ClaudeCode\CLAUDE.md`	Company standards, security policy, compliance	Organization users
Project memory	`./CLAUDE.md`	Repository structure, commands, team rules	Team sharing the repository
User memory	`~/.claude/CLAUDE.md`	Personal preferences and tools	Individual
Project local memory	`./CLAUDE.local.md`	Personal project settings	Individual

In practice, team rules belong in ./CLAUDE.md, while personal preferences should be separated into ~/.claude/CLAUDE.md or a private imported file.

Loading and Priority

Claude Code reads memory files as context at startup. It can also discover CLAUDE.md files while moving upward from the current working directory. In a monorepo, common rules can be placed at the root and more specific rules under each service directory.

repo/
  CLAUDE.md
  services/
    api/
      CLAUDE.md
    web/
      CLAUDE.md

Rules should not be split excessively. Separate common rules from exceptions clearly so it remains traceable which instructions apply.

Creating It

Claude Code can create a draft with the /init command.

/init

After generating a draft, revise it based on the real project. Check README, package settings, build settings, and test settings before writing commands. Include project purpose, working commands, restricted areas, approval-required tasks, concrete style rules, sensitive file patterns, and remove outdated instructions.

Basic Template

# Project Instructions

## Project Overview

- This repository is a [service/library/site] for [target users].
- Main stack: [language/framework/runtime].
- Application code lives in `[path]`.
- Tests live in `[path]`.

## Common Commands

- Install dependencies: `[command]`
- Run locally: `[command]`
- Lint: `[command]`
- Type check: `[command]`
- Unit test: `[command]`
- Build: `[command]`

## Working Rules

- Keep changes scoped to the requested task.
- Do not modify `[path]` without explicit approval.
- Do not add dependencies unless the task requires it.
- After code changes, run the smallest relevant verification command first.

Good and Bad Rules

Good rules are specific. Instead of abstract rules such as “write clean code” or “be careful with security,” include commands, paths, and conditions.

- Put React shared components in `src/components`, and page-only components in `src/pages/*/_components`.
- After changing API routers, run `npm run test:api`.
- Do not read or print `.env`, `.env.*`, `secrets/`, or `credentials/`.

Using Imports

CLAUDE.md can import other files with the @path/to/file syntax. This is useful for separating long background documents from always-needed rules.

# Project Instructions

See @README.md for project overview.
See @docs/architecture.md for architecture decisions.
See @package.json for available npm scripts.

Markdown code blocks and inline code do not trigger imports. Imported files can import other files, but excessive recursion should be avoided. Use /memory to check which memory was loaded.

Team Operation

Manage CLAUDE.md like code. If project structure or commands change but the memory file remains old, Claude Code may follow outdated instructions. Update the memory file in the same pull request when build, test, or deployment commands change. Do not store personal preferences as team rules. Explain the reason and scope for prohibited actions.

Checklist

The project purpose and folder structure are described.
Install, run, test, and build commands really exist.
Restricted files and approval-required work are concrete.
Sensitive files are not to be read or printed.
Team rules and personal preferences are separated.
Rules use commands, paths, and conditions.
Imports are not too deep or broad.

Summary

CLAUDE.md is an operational document that tells Claude Code how to work in a project. A good CLAUDE.md is not a long explanation, but a concise set of concrete commands and constraints that Claude Code can apply directly.