Knowledge about Projects and CLAUDE.md in the Claude Code ecosystem
Projects provide persistent context that travels with your codebase. In Claude Code, CLAUDE.md is the primary mechanism -- a markdown file Claude reads at every session start, giving it project-specific knowledge about conventions, architecture, and preferences. Think of it as the onboarding doc for Claude -- always loaded, never compacted, shared with every agent.
CLAUDE.md is the first thing to set up in any Claude Code project. It is the most reliable way to ensure consistent behavior across all interactions.
In Claude Chat, Projects are named spaces with uploaded knowledge bases and custom instructions. In Claude Cowork, folder-specific and global instructions serve the same purpose.
CLAUDE.md files exist at multiple levels, each adding context:
| Level | Location | Purpose |
|---|---|---|
| Global |
~/.claude/CLAUDE.md| Personal preferences across all projects |
| Project | CLAUDE.md (repo root) | Team-shared conventions and architecture |
| Project (extended) | .claude/CLAUDE.md | Additional project context |
| Personal override | CLAUDE.local.md | Personal overrides, gitignored |
| Modular rules | .claude/rules/*.md | Path-specific rules |
Merge semantics are additive: global loads first, project layers on top. Higher priority overrides lower when conflicts exist (Managed > Project > User).
CLAUDE.md files auto-load at session start. In monorepos:
You can import additional files using @path/to/file syntax within CLAUDE.md.
~/.claude/CLAUDE.md)CLAUDE.md).claude/CLAUDE.md).claude/rules/*.md)CLAUDE.local.md)Beyond CLAUDE.md, Claude Code maintains auto-memory -- a per-project, per-user learning journal at ~/.claude/projects/<project-hash>/memory/MEMORY.md. The first 200 lines auto-load at session start. Claude writes to this automatically, or you can instruct it explicitly.
Auto-memory complements CLAUDE.md: CLAUDE.md is for team-shared conventions you write deliberately, while auto-memory captures personal per-project learnings organically.
| Interface | Mechanism | Setup |
|---|---|---|
| Claude Code | CLAUDE.md files (auto-loaded) | Create files in repo |
| Claude Chat | Projects with custom instructions + knowledge base | Create via sidebar |
| Claude Cowork | Global/folder-specific instructions | Set in Customize menu |
CLAUDE.local.md (gitignored automatically).claude/rules/ for path-specific instructionsCLAUDE.local.md for personal overrides (automatically gitignored).claude/rules/ for path-specific rules instead of one huge CLAUDE.mdCLAUDE.md (case-sensitive) at repo root or .claude/