Projects & Context
Configure project instructions, manage memory, and understand how Claude Code handles context.
CLAUDE.md — Project Instructions
Claude Code automatically loads CLAUDE.md files from a 3-tier hierarchy.
CLAUDE.md Hierarchy (loaded in order): 1. ~/.claude/CLAUDE.md → Personal, all projects 2. <repo-root>/CLAUDE.md → Shared with team (checked into git) 3. ~/.claude/projects/<hash>/CLAUDE.md → Personal, per-project override
All three levels are merged together at session start. Use the repo-root file for team-wide conventions and the personal files for your own preferences.
Write instructions in markdown. Include coding standards, architecture notes, preferred tools, and any project-specific context Claude should know about.
Keep It Concise
Focus on stable patterns, not session-specific context. Claude reads it every session.
Use Headings
Structure with markdown headings so Claude can quickly find relevant instructions.
Avoid Secrets
Never put API keys or credentials in CLAUDE.md. Use environment variables instead.
The .claude/ Directory
Project-level configuration lives in .claude/ at your repo root.
.claude/ ├── settings.json — Project settings (checked into git) ├── settings.local.json — Local overrides (gitignored) ├── rules/ — Additional instruction files (.md) ├── commands/ — Custom slash commands (.md) └── scripts/ — Automation scripts, hooks
settings.json — Shared project settings like allowed tools, permission modes, and MCP servers. Checked into version control so the whole team uses consistent configuration.
settings.local.json — Your personal overrides that stay local. Automatically gitignored.
rules/ — Topic-specific instruction files (e.g., development-rules.md, testing-guidelines.md). Claude loads them alongside CLAUDE.md.
commands/ — Custom slash commands written in markdown. Create commands/deploy.md and run it with /deploy.
scripts/ — Automation scripts and hook handlers for extending Claude Code behavior.
Auto-Memory System
Claude Code automatically remembers patterns and decisions across sessions.
Memory files live at ~/.claude/projects/<hash>/memory/MEMORY.md. The first 200 lines are loaded into every session automatically.
What It Saves
- Stable patterns confirmed across interactions
- Key architectural decisions and file paths
- User preferences for workflow and tools
- Solutions to recurring debugging problems
What It Avoids
- Session-specific context or temporary state
- Unverified or speculative conclusions
- Anything duplicating CLAUDE.md instructions
- Information from reading a single file
Auto-Written
Claude decides when to save memories — no manual management needed.
Topic Files
Create separate files like debugging.md or patterns.md for detailed notes.
Self-Correcting
Claude updates or removes memories that turn out to be wrong or outdated.
Context Management
~200K Token Window
Claude Code has a large context window. Long conversations are automatically compressed.
Auto-Compression
Prior messages compress as context approaches limits. Your conversation is never hard-capped.
/clear for Fresh Start
Use /clear between unrelated tasks to reset context and get faster, focused responses.