# Instruction files in Claude Code

Give Claude Code the commands, layout and boundaries of ticket-service with CLAUDE.md, a directory-scoped CLAUDE.md and, for mixed-agent teams, a shared AGENTS.md.

Source: https://ai-sw-factory.mellicci.dev/fundamentals/instruction-files/claude-code

## At a glance

| | Claude Code |
|---|---|
| Term | `CLAUDE.md` (plus `.claude/rules/*.md`); Claude Code also reads `AGENTS.md` |
| Configured in | `./CLAUDE.md` or `./.claude/CLAUDE.md`, `~/.claude/CLAUDE.md`, `./CLAUDE.local.md`, `CLAUDE.md` in subdirectories, `.claude/rules/` |
| Loads / runs | At launch: the working directory and every parent directory. On demand: subdirectory files, when Claude reads a file there |
| Scope & precedence | Managed, user, project, local. Files are concatenated, not overridden; the file closest to the working directory is read last |

## Build the scenario

| Step | What you write or run | Where |
|---|---|---|
| 1 | Project file with commands, layout, conventions, boundary | `CLAUDE.md` at the repo root |
| 2 | Directory file with database rules | `src/db/CLAUDE.md` |
| 3 | Start `claude`, run `/context` | Root file listed under **Memory files** |
| 4 | Ask for a schema change | `src/db/CLAUDE.md` appears once Claude reads a file in `src/db/` |

`CLAUDE.md`:

```markdown
# ticket-service
Fastify + TypeScript API on PostgreSQL (Drizzle). Package manager: pnpm.
## Commands
- `pnpm install`, `pnpm dev`, `pnpm test` (Vitest), `pnpm lint`
- `pnpm db:generate` (new migration), `pnpm db:migrate` (apply)
## Layout
- `src/routes/` HTTP handlers · `src/db/` schema and migrations
- `test/` Vitest specs · `docs/` API notes
## Conventions
- Named exports only; every route change needs a test in `test/`.
- Never hand-edit `src/db/migrations/`; generate them with `pnpm db:generate`.
```

`src/db/CLAUDE.md`:

```markdown
# Database code
- Change `schema.ts`, then run `pnpm db:generate` to create the migration.
- Review the generated SQL before running `pnpm db:migrate`.
- Never edit or rename files in `migrations/`.
```

**Sharing with other agents.** If the team also uses agents that read `AGENTS.md`, keep the shared content there and add a `CLAUDE.md` next to it that imports it:

```markdown
@AGENTS.md

## Claude Code
- Use plan mode before changing `src/db/schema.ts`.
```

Claude reads the imported file first, then your Claude-specific lines.

## Specifics

### File names and locations

| Scope | Location | Shared with |
|---|---|---|
| Managed policy | Linux and WSL `/etc/claude-code/CLAUDE.md`; macOS `/Library/Application Support/ClaudeCode/CLAUDE.md`; Windows `C:\Program Files\ClaudeCode\CLAUDE.md` | Everyone on the machine |
| User | `~/.claude/CLAUDE.md`, `~/.claude/rules/*.md` | You, all projects |
| Project | `./CLAUDE.md` or `./.claude/CLAUDE.md`, `./.claude/rules/*.md` | Team, via git |
| Local | `./CLAUDE.local.md` (add to `.gitignore`) | You, this project |
| Directory | `CLAUDE.md` in any subdirectory | Team, via git |

Managed content can also go in the `claudeMd` key of managed settings. Run `/init` to generate a starter `CLAUDE.md`; it suggests improvements if one exists.

### How files load and combine

| Topic | Behavior |
|---|---|
| Combination | Everything found is concatenated. Order: managed first, then root down to the working directory; `CLAUDE.local.md` after `CLAUDE.md` in each directory |
| Conflicts | No file overrides another. The documentation says Claude may follow either of two contradicting instructions |
| Imports | `@path/to/file` in a `CLAUDE.md` loads that file at launch, up to four hops deep. Paths outside the working directory need a one-time approval |
| `AGENTS.md`, default | Read only when no `CLAUDE.md` or `CLAUDE.local.md` exists in or above the working directory. Needs v2.1.277 or later |
| `AGENTS.md`, with `CLAUDE.md` | Not read, unless imported with `@AGENTS.md` or **Project instructions** in `/config` is `claude-md-and-agents-md` |
| Symlink alternative | `ln -s AGENTS.md CLAUDE.md` works, but use the import if anyone works on Windows |

`AGENTS.md` support is recent (v2.1.277, September 2026). Some sessions, such as Amazon Bedrock or telemetry disabled, could not read it before v2.1.281; there, the `@AGENTS.md` import works. Claude Code does not read `AGENTS.local.md` or `AGENTS.override.md`.

### Scoping to paths

| Mechanism | Loads | Best for |
|---|---|---|
| Directory `CLAUDE.md` | On demand, when Claude reads a file in that directory | Rules owned by one part of the tree, versioned with its code |
| `.claude/rules/x.md` with `paths` | When Claude reads a matching file | Rules for a file type or several directories |
| `.claude/rules/x.md` without `paths` | At launch | Topic-split project rules |

`paths` is the only frontmatter field Claude Code reads in a rule. A path-scoped version of the database rules:

```markdown
---
paths:
  - "src/db/**"
---
Never hand-edit `src/db/migrations/`; generate them with `pnpm db:generate`.
```

### Size and context cost

| Topic | Behavior |
|---|---|
| Length | Target under 200 lines per file; longer files cost more context and reduce adherence |
| Hard limit | A file over 4 MiB is skipped |
| Imports | Organize a file but do not reduce its cost; imported files load at launch |
| Comments | Block-level HTML comments are stripped before loading |
| Compaction | Root `CLAUDE.md` and unscoped rules reload from disk. Directory files and `paths` rules reload only when Claude reads a matching file again |
| Skipping files | `claudeMdExcludes` (glob list, any settings layer) skips files by path; managed files cannot be excluded |

### See what loaded

| Command | Shows |
|---|---|
| `/context` | Loaded files under **Memory files**, with context-use suggestions |
| `/memory` | Your `CLAUDE.md` files and memory locations; opens one in your editor. Also lists an `AGENTS.md` Claude read |
| `/doctor prompt-audit` | Outdated or conflicting instructions, with proposed edits |
| `InstructionsLoaded` hook | Fires when a `CLAUDE.md` or rules file loads |

## Gotchas

- Instructions are context, not enforcement. The migration rule shapes what Claude tries but does not block an edit. For a guarantee, use a [hook](https://ai-sw-factory.mellicci.dev/fundamentals/hooks/claude-code) or a permission rule.
- The directory file is absent at launch. A rule that must hold from the first prompt belongs in the root file or an unscoped rule.
- A `CLAUDE.local.md` in a repository that relies on `AGENTS.md` makes Claude stop reading `AGENTS.md` for you. Import it, or set `claude-md-and-agents-md`.
- `--add-dir` directories load their memory files only with `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`.
- Multi-step procedures do not belong here. Move them into a [skill](https://ai-sw-factory.mellicci.dev/fundamentals/skills) so they load only when used.