Each new session starts with an empty head. Claude doesn't remember that last time you told him to use 2 spaces instead of tabs. CLAUDE.md and skills close this gap — giving Claude a persistent context that survives a reboot and a weekend.
What is CLAUDE.md and why is it important
CLAUDE.md is a special markdown file that Claude reads at the beginning of each session. It contains instructions that you would otherwise repeat over and over again:
✅ Suitable contents
- Bash commands that Claude won't guess
- Code style different from default
- Test instructions and preferences
- Git workflow (branch naming, PR convention)
- Environment quirks (required env vars)
❌ Inappropriate contents
- Standard language conventions (Claude knows them)
- File-by-file code description
- Detailed API documentation (link to docs)
- Information that changes frequently
Where to put CLAUDE.md
| Location | Applies to | Sharing |
|---|---|---|
~/.claude/CLAUDE.md | All projects | Only you |
./CLAUDE.md | This project | Team (git) |
./CLAUDE.local.md | This project | Only you (.gitignore) |
How to write effective CLAUDE.md
Most common error: excessively long file. The goal is under 200 lines. Each sentence eats tokens in each session.
# Code style
- Use ES modules (import/export), not CommonJS
- 2-space indentation
# Workflow
- Run `npm run lint` before committing
- Prefer single tests, not the whole suite
# Architecture
- API handlers live in src/api/handlers/
- Shared components use PascalCase filenames💡 Efficiency Test
Ask: "If I deleted this sentence, would Claude make a mistake?" If not, delete it.
Auto memory — Claude writes notes himself
Since version 2.1.59, Claude automatically saves notes in ~/.claude/projects/<projekt>/memory/MEMORY.md.
💡 Auto memory limitation
It is local — not shared between computers. Only the first 200 rows are loaded. It is better to write important rules by hand in CLAUDE.md.
Skills — repetitive workflow on demand
While CLAUDE.md is always loaded, skills are only loaded when they are relevant or when you invoke them. This saves tokens.
---
name: api-conventions
description: REST API design conventions
---
# API Conventions
- Use kebab-case for URL paths
- Always include pagination for list endpoints
- Version APIs in the URL path (/v1/, /v2/)Save as .claude/skills/api-conventions/SKILL.md. You call with /api-conventions.
Rules in .claude/rules/
For large projects, split the instructions into topic files. Rules can be scoped — they only apply to certain files:
---
paths:
- "src/api/**/*.ts"
---
# API Development Rules
- All endpoints must include input validation
- Use the standard error response formatGit integration
Claude Code can work with git:
- Switch branches: "switch to a new branch called feature-auth"
- Commit: “commit with a descriptive message”
- Create PR: “create a pr” — automatically uses
gh pr create - Resolve conflicts: "resolve the merge conflict in user.ts"
💡 Linking to PR
Once a PR is created, the session will automatically link to it. You will return later with claude --from-pr 42.
Exercise
Task 1: Run /init in your project. Claude analyzes the structure and designs the CLAUDE.md starter. Edit it to less than 100 lines.
Task 2: Create a skill .claude/skills/refactor/SKILL.md that defines your preferred refactoring procedure.
Task 3: Tell Claude: "Always use single quotes in JavaScript". Close the session, open a new one and ask about the string style. Make sure you remember it.
Lesson summary
- CLAUDE.md gives Claude standing instructions for each session — keep them brief, under 200 lines.
- Skills are loaded on demand and save tokens vs. bloated CLAUDE.md.
- Auto memory is written by Claude himself, but it has a limit of 200 lines and is local.
- Claude knows how to work with git — branches, commits, PR and conflicts.