← Back to cards
Reference Card

Agent Files

Five positions for CLAUDE.md — and the settings layer that mirrors them.

Position · User

~/.claude/CLAUDE.md

Habits that travel with you across every project. Personal process, tooling preferences, conventions you carry into other people's repos.
Loaded byHarness · every session, every project
Always loaded
Position · Ancestor

./<ancestor>/CLAUDE.md

Conventions for a workspace above this project — typical of monorepo umbrellas. Picked up from any directory in the tree.
Loaded byHarness · every session under that path
Always loaded
Position · Project

./CLAUDE.md

The team contract. What every contributor must follow in this repo — architecture, run/test commands, code style. Checked in.
Loaded byHarness · every session in this repo
Always loaded
Position · Project-local

./CLAUDE.local.md

Personal preferences scoped to this repo only. Sandbox URLs, local-only env quirks, anything you don't want pushed to the team file.
Loaded byHarness · every session in this repo
Gitignored · personal
Position · Subdirectory

./<dir>/CLAUDE.md

Place-anchored conventions — testing patterns, blueprint wiring. Loaded only when Claude touches a file in that folder. The lazy rung.
Loaded byAgent (instructed; not always deterministic)
Lazy · on file touch

Settings — same team/personal split, applied to hooks & permissions

Where you register a hook decides who gets it. Lower wins — local overrides project overrides user; managed overrides everything.

File Scope Checked in
~/.claude/settings.json You · every project —
./.claude/settings.json Team · everyone on this repo ✓
./.claude/settings.local.json You · this repo only — (gitignored)
managed-settings.json Org · IT-controlled (rare for solo dev) — (OS policy)

Doesn't belong in CLAUDE.md

  • Anything Claude can figure out by reading the code
  • Don't inline (@) long docs, link them instead.
  • Long workflows or sometimes-relevant knowledge — make it a skill instead
  • Ephemeral / transient data (sandbox URLs, WIP notes) — keep out of any auto-loaded file
Size target — under 200 lines. Audit with /context; over ~2–3k tokens, adherence drops alongside the cost.