Claude Code — Project Instructions (CLAUDE.md) · AI coding agents

CLAUDE.md files are Claude Code’s memory: markdown files loaded automatically into context at launch. Use them for conventions, architecture notes, and commands Claude should know without being told.

Locations and precedence

Type	Location	Notes
Enterprise policy	macOS `/Library/Application Support/ClaudeCode/CLAUDE.md`; Linux/WSL `/etc/claude-code/CLAUDE.md`; Windows `C:\ProgramData\ClaudeCode\CLAUDE.md`	Organization-wide instructions
Project	`./CLAUDE.md` or `./.claude/CLAUDE.md`	Commit to git — shared with the team
User	`~/.claude/CLAUDE.md`	Personal preferences across all projects
Project local	`./CLAUDE.local.md`	Deprecated — use `@` imports instead

Higher entries load first and take precedence. All memory files load into context at launch.

How lookup works

Claude Code recurses up from the current working directory to (but not including) /, reading every CLAUDE.md / CLAUDE.local.md it finds — so a session started in repo/services/api/ picks up the repo-root memory too.
Nested CLAUDE.md files in subtrees load on demand when Claude reads files in those subtrees.

Imports: `@path/to/file`

Pull other files into memory with @ imports:

See @docs/architecture.md for the system overview.
Follow the conventions in @~/.claude/my-project-instructions.md.

Relative and absolute paths both work, including @~/....
Imports recurse up to 5 hops.
@ is not evaluated inside code spans or code blocks.
View everything currently loaded with /memory.

Editing memory

/init — generate a starter project CLAUDE.md.
/memory — open memory files in the system editor.
# quick memory — start any input with # and you’re prompted to choose which memory file the line goes into:

> # Always run pnpm test before committing

Auto memory

Claude also accumulates learnings across sessions automatically. Disable with:

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

Example CLAUDE.md

# Acme Web App

Next.js 15 app with a Postgres backend. pnpm is the package manager — never use npm.

## Commands

- `pnpm dev` — start the dev server
- `pnpm test` — run the test suite (must pass before committing)
- `pnpm db:migrate` — apply database migrations

## Conventions

- TypeScript strict mode; no `any` without a comment explaining why.
- React Server Components by default; add `"use client"` only when needed.
- API routes live in `app/api/`; keep handlers thin, logic in `lib/services/`.
- Errors are reported via `lib/reportError.ts`, never swallowed.

## Workflow

- Make small, reviewable commits with conventional-commit messages.
- Run `pnpm test` and `pnpm lint` before finishing any task.
- Database changes require a migration file, never manual edits.

## Gotchas

- `lib/legacy/` is generated code — do not edit; regenerate with `pnpm gen:legacy`.
- Tests hit a real Postgres on `:5433`; see @docs/testing.md.

Last verified: 2026-09-07

Official sources:

AI coding tools evolve quickly. If you find outdated information, please open an issue or pull request.