CLAUDE.md and Agent Rules

CLAUDE.md is the single most important file in an agent-coded project. It is the onboarding document the agent reads at the start of every session — the place you write down what you would otherwise re-explain. No CLAUDE.md means the agent guesses, and guesses wrong in exactly the places you would catch in code review.

This page covers: where CLAUDE.md lives, how Claude Code loads it, how to write instructions that actually get followed, and the path-scoped .claude/rules/ system for larger projects.

Where CLAUDE.md files live

Claude Code walks up the directory tree from the working directory and concatenates every CLAUDE.md and CLAUDE.local.md it finds. More specific locations take precedence.

Scope	Location	Purpose	Shared via
Managed policy	`/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS), `/etc/claude-code/CLAUDE.md` (Linux), `C:\Program Files\ClaudeCode\CLAUDE.md` (Windows)	Org-wide instructions enforced by IT	MDM / Group Policy
Project	`./CLAUDE.md` or `./.claude/CLAUDE.md`	Team-shared project rules	Git
User	`~/.claude/CLAUDE.md`	Personal preferences across projects	Nobody
Local	`./CLAUDE.local.md`	Personal project preferences	Nobody (gitignored)

Within each directory, CLAUDE.local.md is appended after CLAUDE.md. When instructions conflict, your personal notes are the last thing Claude reads at that level.

Files in subdirectories under the working directory are not loaded at launch. They load on demand when Claude reads files in those subdirectories.

When to add something to CLAUDE.md

Add an instruction when:

Claude made the same mistake a second time.
A code review caught something Claude should have known about this codebase.
You typed the same correction into chat that you typed last session.
A new teammate would need the same context to be productive.

Don't add: one-off task details, information already derivable from the code, or step-by-step procedures that only matter for one part of the repo. Those belong in a skill, a path-scoped rule, or the PR description.

Write effective instructions

CLAUDE.md is loaded as a user message, not part of the system prompt. There is no guarantee of strict compliance — instructions that are vague, contradictory, or buried in prose get ignored. A few rules that consistently improve adherence:

Be specific enough to verify.

Bad: "format code properly"
Good: "use 2-space indentation"
Bad: "test your changes"
Good: "run npm test before committing"

Structure with headers and bullets. Claude scans the same way humans do. Dense paragraphs lose.

Keep it under 200 lines. Longer files consume more context and adherence drops. If your instructions are growing large, split them using imports or .claude/rules/.

Don't let instructions contradict each other. If two rules fight, Claude picks one arbitrarily. Review the full chain of loaded files periodically.

Starting a CLAUDE.md

Run /init inside a project. Claude analyzes the codebase and generates a starting CLAUDE.md with build commands, test instructions, and conventions it discovers. Refine from there. Setting CLAUDE_CODE_NEW_INIT=1 opens an interactive multi-phase flow that also proposes skills and hooks.

A reasonable CLAUDE.md starts with:

# Project: acme-api

## Commands
- `make build` — compile the binary
- `make test` — run the full test suite
- `make lint` — run golangci-lint

## Architecture
- HTTP handlers live in `internal/http/`
- Business logic in `internal/services/`
- No logic in handlers except parsing and response shaping

## Conventions
- Table-driven tests with `t.Run` subtests
- Errors wrapped with `fmt.Errorf("...: %w", err)`
- No panics outside of `main.go` initialization

Imports with @path

CLAUDE.md can pull in other files using @path/to/file syntax. Relative paths resolve from the file containing the import, not the working directory. Imports can nest up to 5 hops deep.

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

# Git workflow
@docs/git-instructions.md

# Personal preferences
@~/.claude/my-project-instructions.md

The first time Claude Code encounters external imports in a project, it shows an approval dialog. Declining disables imports for that project.

Path-scoped rules with .claude/rules/

For larger projects, split CLAUDE.md into topic files under .claude/rules/. Each file covers one topic; all .md files are discovered recursively.

your-project/
├── CLAUDE.md
└── .claude/
    └── rules/
        ├── code-style.md
        ├── testing.md
        └── api-design.md

Rules without paths frontmatter load at launch unconditionally. Rules with paths only load when Claude reads a matching file:

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

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

This is how you keep context lean: the API team's 500-line conventions only load when the agent touches API files.

AGENTS.md for multi-tool repos

If your repo already has AGENTS.md for Codex or Cursor, create a minimal CLAUDE.md that imports it:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Both tools read the same core instructions; Claude Code gets its own section below.

Debugging "Claude ignored my rule"

Run /memory to see which files are loaded this session. If yours is not listed, Claude never saw it.
Check for conflicting instructions across CLAUDE.md files further up the tree.
Make the instruction more concrete — "use 2-space indentation" beats "format nicely".
Use the InstructionsLoaded hook to log exactly which files load and when.
If the instruction must hit the system prompt level, use --append-system-prompt — but that must be passed on every invocation.

Next: Hooks and Policy-as-Code

CLAUDE.md and Agent Rules