CLAUDE.md: teaching Claude your world

The highest-return file in the system

You leave this lesson with a committed CLAUDE.md under 200 lines that provably changes Claude's behavior. It is a plain markdown file that loads into context at the start of every session - how you stop re-explaining your world. Who you are, how you name files, what your ICP is, what Claude should never touch: written once, applied every session, for everyone who shares the file.

Last lesson you learned that context is the constraint. CLAUDE.md is you choosing what fills the first slice of it - which is exactly why it must stay short and dense. Every line costs context in every session.

The scopes: where the file lives decides who it affects

• Project: CLAUDE.md at the project root (or .claude/CLAUDE.md), checked into git. Loads for everyone who works in that folder. This is the main one.
• User: ~/.claude/CLAUDE.md - your personal preferences, loads in every project you open. Keep it tiny.
• Local: CLAUDE.local.md - project-specific but personal, gitignored, never shared. Fully supported.
• Managed: a policy-level CLAUDE.md that admins push to every machine in the org. Users cannot exclude it. Covered in the rollout track.

They load broad to specific: managed, then user, then project, then local. Files in parent directories load at launch; a CLAUDE.md inside a subfolder loads on demand when Claude works there. You can also split content across files and pull it in with imports - @path/to/file inside the markdown - up to four hops deep.

Write yours with /init, then make it yours

1. Open Claude Code at your workspace root (or your main project) and run: /init
2. It studies the folder and drafts a CLAUDE.md - it also picks up existing files like AGENTS.md or .cursorrules if you have them.
3. Treat the draft as scaffolding. Now feed it your week-one conventions file: "Merge in @naming-conventions.md, keep it terse."
4. Add the sections the generator cannot know: who your company is in two lines, your ICP in three, the things Claude must never do.
5. Cut ruthlessly to under 200 lines. Read every line and ask: does this change behavior in most sessions? If not, it goes.
6. Commit it to git so the whole team inherits it.

# Acme Agency - Workspace Guide

## Who we are
B2B growth agency, 12 people. We sell outbound systems to SaaS
companies, 10-50 employees, US/EU.

## Layout
- brain/ - company knowledge. Read brain/CLAUDE.md before client work.
- projects/ - one folder per client. Work inside the client folder.
- inbox/ - unsorted drops. Propose destinations, don't leave files here.

## Conventions
- Files: lowercase-with-hyphens, dates as YYYY-MM-DD prefix.
- Drafts end -draft.md; remove the suffix only after human review.
- All client-facing copy follows brain/reference/voice.md.
- ICP lives in brain/reference/icp.yaml. Read it; never copy it.
- Before building anything new, check the 'Current best' table
  in brain/CLAUDE.md and copy the nearest prior work.

## Never
- Never email or message anyone without explicit approval.
- Never put API keys in any file except .env.
- Never edit anything in archive/.
- A key being available is not permission to spend it. State
  per-unit cost x units before any batch run and wait for a yes.

Overflow goes to rules/

When CLAUDE.md wants to grow past its budget, split it into .claude/rules/ - a folder of small modular rule files. Each can carry a paths: setting in its frontmatter with glob patterns, so it only loads when Claude touches matching files. CSV-handling rules load when working on CSVs, and cost nothing the rest of the time.

---
paths:
  - "**/*.csv"
---

# CSV rules
- Always report row count and column list before transforming.
- Never overwrite a source CSV; write -cleaned.csv alongside.
- Dedupe by the domain column unless told otherwise.

This is the current answer to "my CLAUDE.md is too big": core identity and hard rules in CLAUDE.md, situational guidance in rules/ with path gates. There is a user-level ~/.claude/rules/ as well for personal rules across projects. Two helpers for the trim: /doctor now proposes cuts to an oversized CLAUDE.md, and /doctor prompt-audit flags instructions written for older models that the current ones no longer need.

CLAUDE.md as the index of a company brain

The shape we run internally and install at every client: one repo is the company brain, and its root CLAUDE.md is an index, not an essay. Who we are in five lines, how we engineer, and a hand-maintained 'current best' table that says which prior build to copy per dimension: cleanest code, outbound pipeline, deploy setup, cost engineering. A new project starts by reading that table and copying the nearest neighbor, never from a blank page. Week one's brain/ folder is the seed of this.

• Every folder self-describes. Each project ends with its own short CLAUDE.md header saying what it is and what it proved. The root index never needs a central list to maintain, and Claude loads the subfolder's file on demand when it works there (the loading rule above).
• ICP, voice and rules are files, written once. Our signal ICP lives in one YAML file read by two different engines; both refuse to run if it is missing, and neither keeps a copy. A second copy is a guarantee the two will disagree within a month.
• Skills live in the brain, not in people's heads. A foundation skill pack (engineering standard, agent patterns, verification, deploy) is installed into every new project's .claude/skills/ by one script. Improve a skill once and every project inherits it on its next install (week three builds the team version).
• Search, not scrolling. Once the brain holds hundreds of call transcripts and case files, put local hybrid search on it (keyword plus vector, no API call, re-indexed in seconds) and wrap it in a skill that tells Claude to search before answering from memory. The ops track builds this.
• Auto memory sits beside all of it as Claude's private notebook. When a memory note turns out to matter to the team, promote it: move the fact into CLAUDE.md or the brain, then it is versioned and shared.

CLAUDE.md vs auto memory: who writes what

Two memory systems now coexist, and the line between them is simple. CLAUDE.md is the file you write and your team shares - deliberate, versioned, reviewed. Auto memory is what Claude writes for itself on your machine - automatic, personal, unshared.

• Say "remember X" in a session - it goes to auto memory, personal to you.
• Say "add X to CLAUDE.md" - Claude edits the shared file, and it ships to the team via git.
• Team rule of thumb: if a teammate would benefit, it belongs in CLAUDE.md, not memory.

Do this now

Sources and further reading

• Claude Code documentation
• The .claude directory reference