CLAUDE.md Convention for Structuring Agent Instructions¶

Q: What happens when CLAUDE.md imports another file with @path?

The @path/to/file syntax pulls that file's contents into the instruction context. Relative and absolute paths both work, and imports nest up to five levels deep, so one root file can compose several smaller ones. Claude Code shows an approval dialog the first time it encounters an import, and imports you decline remain disabled.

CLAUDE.md is Claude Code's project-level instruction file -- a Markdown file that Claude Code reads at session start to understand project conventions, tooling, and behavioral rules.

Also known as: Instruction File Convention, Project Instruction Files

See Project Instruction File Ecosystem and copilot-instructions.md Convention.

What it does¶

Claude Code loads CLAUDE.md at session start into the context window (docs). Instructions are context, not enforced configuration -- specificity yields compliance.

File locations and scopes¶

Four scopes with different persistence models (docs):

Scope	Location	Shared with	Purpose
Managed policy	OS-specific system path	All users on machine	Organization-wide standards deployed via MDM/Group Policy
Project	`./CLAUDE.md` or `./.claude/CLAUDE.md`	Team (version-controlled)	Project architecture, conventions, build commands
User	`~/.claude/CLAUDE.md`	Just you (all projects)	Personal preferences across projects
Local	`./CLAUDE.local.md`	Just you (current project)	Personal project-specific settings, not checked in

Load order and precedence¶

Claude Code walks up the directory tree loading every CLAUDE.md and CLAUDE.local.md it finds (docs). Subdirectory files load on demand. More specific scopes win: directory overrides project root, project overrides user, user overrides policy.

Writing effective instructions¶

Effective instructions share these properties (docs):

Property	Guidance
Size	Under 200 lines -- longer files reduce adherence
Structure	Headers and bullets for scanning
Specificity	Verifiable: "Use 2-space indentation" not "Format code properly"
Consistency	Contradictions cause unpredictable behavior; audit regularly

What to include¶

A project CLAUDE.md should cover (docs):

Build and test commands -- build, test, lint, deploy commands
Coding standards -- naming conventions, formatting rules
Architecture -- where code lives, how modules interact
Workflows -- deployment steps, PR process
Navigation pointers -- link to deeper docs rather than embedding

Run /init to generate a CLAUDE.md from discovered conventions.

What not to include¶

Task-specific instructions -- these belong in the prompt
Discoverable knowledge -- directory structure, types, and test output that tools surface on demand (see Discoverable vs Non-Discoverable Context)
Full documentation -- link to it instead, because tokens spent here reduce the task budget
Generic advice -- "write clean code" is noise

Importing additional files¶

CLAUDE.md supports @path/to/file import syntax (docs). Relative and absolute paths work; imports nest five levels deep. See @import Composition Pattern for modular authoring patterns.

See @README for project overview and @package.json for available npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md

Claude Code shows an approval dialog on first encounter; declined imports remain disabled (docs).

Path-scoped rules with `.claude/rules/`¶

Place topic-specific Markdown files in .claude/rules/ (docs). Files without paths frontmatter load unconditionally; files with paths load when matching files are in scope.

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format

Rules files support symlinks for cross-repo sharing (docs).

CLAUDE.md compared with AGENTS.md¶

Both offer repo-level context but differ in audience and discovery:

Dimension	CLAUDE.md	AGENTS.md
Standard	Claude Code proprietary (docs)	Open standard
Read by	Claude Code only	Any AGENTS.md-compatible tool
Hierarchy	Directory traversal + imports + `.claude/rules/`	Directory traversal
Path scoping	`.claude/rules/` with `paths` frontmatter	Not in standard
Personal scope	`~/.claude/CLAUDE.md` and `CLAUDE.local.md`	Not in standard

Teams using multiple AI tools should maintain both or consolidate into AGENTS.md.

Auto memory: the companion system¶

Auto memory is what Claude writes back -- build commands, debugging insights, preferences (docs). Stored in ~/.claude/projects/<project>/memory/; first 200 lines load at session start. Toggle via /memory.

Example¶

A minimal project CLAUDE.md for a TypeScript monorepo:

# Project Instructions

## Build and Test

    npm run build        # compile all packages
    npm test             # run full test suite
    npm run lint         # ESLint + Prettier check

## Conventions

- Use 2-space indentation throughout
- All public functions must have JSDoc comments
- Place new utilities in packages/shared/src/

## Architecture

- packages/api/ -- Express REST API, connects to Postgres via Prisma
- packages/worker/ -- BullMQ job processors
- packages/shared/ -- types and utilities shared across packages

## Additional Rules

@.claude/rules/api-standards.md

With path-scoped rules in .claude/rules/api-standards.md:

---
paths:
  - "packages/api/**/*.ts"
---

# API Standards

- Validate all inputs with Zod before processing
- Return errors using the `ApiError` class from `shared/errors`

FAQ¶

What happens when CLAUDE.md imports another file with @path?

The @path/to/file syntax pulls that file's contents into the instruction context. Relative and absolute paths both work, and imports nest up to five levels deep, so one root file can compose several smaller ones. Claude Code shows an approval dialog the first time it encounters an import, and imports you decline remain disabled.

How do .claude/rules/ files differ from CLAUDE.md itself?

Rules files hold topic-specific Markdown that need not load every session. A rules file without paths frontmatter loads unconditionally; one carrying a paths glob loads only when matching files are in scope, so API conventions reach the agent when it works on API code and cost nothing otherwise. Rules files also support symlinks for cross-repo sharing.

What is auto memory, and how does it relate to CLAUDE.md?

Auto memory is the companion system — what Claude writes back rather than what you author: build commands, debugging insights, and preferences picked up during work. It is stored in ~/.claude/projects/<project>/memory/, and its first 200 lines load at session start alongside the instruction files you wrote. Toggle it with the /memory command.

Should a team using several AI tools write CLAUDE.md or AGENTS.md?

CLAUDE.md is proprietary to Claude Code and read only by it; AGENTS.md is an open standard that any compatible tool reads. Teams running multiple AI tools should maintain both or consolidate into AGENTS.md, accepting a feature trade-off: path scoping, imports, and personal scopes such as CLAUDE.local.md are not part of the AGENTS.md standard.

Key Takeaways¶

CLAUDE.md is context loaded into the session, not enforced configuration — specificity yields compliance.
Four scopes layer from managed policy down to local overrides; more specific scopes win on conflict.
Keep it under 200 lines of scannable headers and bullets; longer files erode adherence.
Link to deeper docs and use @path imports or .claude/rules/ for path-scoped content instead of inlining everything.
Omit discoverable knowledge and task-specific instructions — those belong in tools or prompts, not the instruction file.