Rules and long-term memory — so Claude knows how you work.

What it is

CLAUDE.md gets loaded on EVERY message — it decides how Claude Code works with you: language, rules, conventions, workflow. A good CLAUDE.md is the difference between "Claude does whatever" and "Claude does exactly what I need". Memory is the layer underneath: markdown files that give long-term memory without getting loaded on every turn.

Install / Setup

Option 1 — Terminal:

# Global CLAUDE.md (applies everywhere)
nano ~/.claude/CLAUDE.md

# Project CLAUDE.md (this project only)
nano ./CLAUDE.md

Or just run /init inside the project in the Claude Code chat — it creates a template.

Option 2 — Prompt Claude Code:

Build me a global CLAUDE.md at ~/.claude/CLAUDE.md. Ask me first: language, coding conventions, workflow preferences (plan mode, subagents, verification). Keep the file under 100 lines. Show it to me before writing.

The 7 sections of a clean CLAUDE.md

1. Basics — Who are you?

Basics

• Language: English, casual
• Replies: short and direct, no filler
• When you learn something important: tell me which memory file you'd update

### 2. Coding conventions

```markdown
## Coding conventions
- Python preferred
- Variables in English, comments in English
- Flask for simple APIs, FastAPI when performance matters
- SQLite for simple data
- Tests only for critical logic

3. Force plan mode

## Workflow
- For ANY non-trivial task, plan mode first
- If something breaks: STOP, replan — don't keep pushing

4. Subagent strategy

## Subagents
- Default is subagent — any task that takes more than a quick Grep/Edit
- Code changes → subagent reads, understands, edits. Main context stays clean.
- Multi-file edits → multiple subagents in parallel
- Main context is for: planning, decisions, short status updates

5. Self-improvement loop

## Self-improvement loop
- Correction → save to lessons.md immediately
- "no", "not like that" → lessons.md
- Before code changes, check relevant error patterns
- Never make the same mistake twice

6. Verify before shipping

## Verification
- Never mark as done without proof it works
- Run tests, check logs, demonstrate correctness

7. Core principles

## Core principles
- Simplicity first: every change as simple as possible
- No laziness: find root causes, no temp fixes
- Minimal impact: only touch what's needed

Use cases

• Starting a new project — /init in the project, then extend CLAUDE.md with your framework/stack.
• Enforce a workflow rule — Add "force plan mode" and Claude sticks to it.
• Persist corrections — "Correction → lessons.md" rule makes Claude learn from mistakes.
• Team setup — Commit the project CLAUDE.md, everyone on the team gets the same Claude style.
• Bootstrap a memory system — ~/.claude/memory/MEMORY.md as the index, detail files per topic.

Pro tip

Every line in CLAUDE.md costs tokens on EVERY message. Rules of thumb:

• Global CLAUDE.md: under 100 lines
• Project CLAUDE.md: under 150 lines
• If it gets longer: move into separate files and just reference them

Memory files (except the MEMORY.md index) don't auto-load — Claude reads them on demand. No duplicates. Clean them out regularly.

🚀 CLAUDE.md and memory are the foundation. But writing the right rules that actually work — that's the craft.

In the community I share my full CLAUDE.md and show how I tuned it over months.

→ Join the Claude Code Mastery Community

Updated regularly — follow @vine.codes for more.