The definitive guide to CLAUDE.md

CLAUDE.md is Claude Code's native memory and instruction file. At the start of every session, Claude Code reads this file to boot up its context—learning your project's commands, conventions, architecture patterns, and gotchas.

Unlike general readme files, CLAUDE.md is designed specifically for an AI coding agent. It holds standing instructions that tell Claude Code what style to write, what linters to run, and what commands to execute when building or testing.

Claude Code checks for instructions at multiple levels, allowing you to separate personal, project, and team preferences:

1. Global/User Scope: Stored in your home directory (e.g., ~/.claude.json or ~/.claude.md). This holds your personal editor preferences and system-wide styles.

2. Project/Repo Scope: Stored at your repository root (e.g., repo/CLAUDE.md). This holds project-specific build/test commands and team coding guidelines. This file is committed to git.

3. Local Scope: Stored in the local workspace (.git/info/exclude or local-only configurations) for workspace-specific parameters you don't commit.

If your team uses multiple AI coding agents (such as Cursor, Codex, and Claude Code), maintaining duplicate rules files like AGENTS.md and CLAUDE.md is a recipe for documentation drift.

The recommended pattern is to keep your core conventions and build commands in AGENTS.md (which is read by Cursor and other open tools), and make your CLAUDE.md import it using an @AGENTS.md directive or a symlink. You can then add Claude-specific command configurations below the import, maintaining a single source of truth for the core rules.

Like any documentation, CLAUDE.md can go stale. If a developer changes the test runner command or refactors the folder layout but forgets to update CLAUDE.md, Claude Code will confidently execute the wrong commands.

Tying CLAUDE.md updates to your CI/CD pipeline or pull request reviews is the best way to prevent drift. You can run automated checks that verify if the documented build and test commands still match what is defined in your package.json or config files.

There is no fixed schema, but most working files converge on the same shape: commands, conventions, and hard guardrails. A short, accurate file beats a long, stale one.

# Project: Acme API

## Commands
- Install: `npm install`
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

## Conventions
- TypeScript strict mode; no `any`
- Errors: return `Result<T, E>`, never throw across module boundaries
- Tests live next to source as `*.test.ts`

## Do not
- Do not edit generated files in `src/generated/`
- Do not commit directly to `main`

@AGENTS.md