Memory files consume tokens from the context window. ~100-150 instruction slots available for your customizations. Keep files minimal — only include what the agent cannot discover on its own. Two approaches: CLAUDE.md — Single file, best for small projects (< 100 lines) .claude/rules/ — Modular files with optional path-scoping, best for large projects Run /init to auto-generate a CLAUDE.md. Or create manually:

Project Name

Tech Stack

[Primary framework]

[Key non-obvious libraries]

Commands

npm run dev - Dev server - npm test - Run tests - npm run build - Build

Rules

[2-3 critical project-specific rules] Press

during a session to add memory items quickly Use /memory to open CLAUDE.md in your editor Priority Location Scope 1 (Highest) Enterprise policy (managed by IT) All org users 2 ./CLAUDE.md or ./.claude/CLAUDE.md Team via git 2 ./.claude/rules/.md Team via git 3 ~/.claude/CLAUDE.md All your projects 3 ~/.claude/rules/.md All your projects 4 (Lowest) ./CLAUDE.local.md (auto-gitignored) Just you Claude recurses UP from current directory, loading all CLAUDE.md files found. Also discovers CLAUDE.md in subtrees when reading files in those directories. Monorepo strategy: Root file defines WHEN; subtree files define HOW. root/CLAUDE.md # Universal: tech stack, git workflow apps/web/CLAUDE.md # Frontend-specific apps/api/CLAUDE.md # Backend-specific The .claude/rules/ directory splits instructions into focused markdown files. Use .claude/rules/ when: many concerns, different rules for different file types, team maintains different areas. Use CLAUDE.md when: small project, universal rules, single source of truth. Path-scoped rules use YAML frontmatter:

paths : - "src/api/*/.ts"

API Rules

-

All endpoints must include input validation

Supported patterns:

*/.ts

,

src/*/

,

src/*/.{ts,tsx}

,

{src,lib}/*/.ts

Rules without

paths

frontmatter load unconditionally.

See

references/rules-directory-guide.md

for complete guide including symlinks, user-level rules, and migration.

Structure CLAUDE.md with only these sections:

Project purpose

(1-3 lines) — What the project is

Tech stack

(compact) — Only non-obvious technologies

Commands

— Non-obvious dev, build, and test commands

Important files

— Architecture-critical, non-obvious files only

Rules

— Prohibitions and constraints that prevent mistakes (highest-value lines)

Workflow

(optional) — Only if non-standard

Do NOT include:

Repository overviews (agent discovers structure itself)

Code style rules (linters enforce these)

Generic best practices ("write clean code", "DRY", "SOLID")

Redundant specs (copies of config files, env vars, schema descriptions)

Marketing/goals (vision statements, KPIs, roadmaps)

Verbose explanations (paragraphs where one line suffices)

See

references/section-templates.md

for ready-to-use templates.

See

references/project-patterns.md

for framework-specific patterns.

Golden rule:

If someone with zero project context reads your CLAUDE.md and gets confused, Claude will too.

Be specific, never vague:

❌ "Format code properly" / "Write good tests" / "Follow best practices"

✅ "Run pnpm lint before committing" / "Tests in __tests__/ using Vitest"

Prohibitions > positive guidance:

❌ "Try to use TanStack Form for forms"

✅ "NEVER use native form/useState for forms — ALWAYS use TanStack Form"

Show, don't tell:

When format matters, show a concrete example (3-5 lines max).

Emphasis hierarchy:

CRITICAL > NEVER > ALWAYS > IMPORTANT > YOU MUST

Put critical rules

first

in each section

Use

bold + keyword

for non-negotiable rules:

CRITICAL: Never commit secrets

See

references/prompting-techniques.md

for advanced techniques.

Ideal:

< 100 lines

Maximum:

150 lines before performance degrades

Over 200 lines:

directives start getting lost

When exceeding limits, split into

.claude/rules/

files or link to separate docs:

-

**

API patterns

**

See

[

docs/api-patterns.md

](

docs/api-patterns.md

)

-

**

Testing guide

**

See docs/testing-guide.md CLAUDE.md supports importing: @docs/coding-standards.md (relative/absolute paths, ~ expansion, up to 5 levels deep, not evaluated inside code blocks). Before creating or updating memory files, use AskUserQuestion: Option 1: Single CLAUDE.md — < 100 lines, simple project, universal rules Option 2: Modular .claude/rules/ — 100+ lines, different rules for different files Creating new memory: Start with /init or minimal template Add tech stack and commands first Add rules only as you encounter friction Test with real tasks, iterate based on Claude's behavior Maintaining: Review quarterly or when project changes significantly Remove outdated instructions Add patterns that required repeated explanation Use

for quick additions during work Troubleshooting: Problem Solution Claude ignores instructions Reduce file size, add emphasis (CRITICAL, NEVER) Context overflow Use /clear , split into .claude/rules/ Instructions conflict Consolidate, use hierarchy (root vs subtree) Path rules not applying Verify glob pattern matches target files /claude-memory init — Create Minimal CLAUDE.md When the user argument contains "init", execute this workflow to scaffold a CLAUDE.md with only the essential sections. Step 1: Detect project context Read package.json (or equivalent: pyproject.toml , Cargo.toml , go.mod , etc.) to detect: Project name Tech stack (framework, language) Available scripts/commands (dev, build, test) Also check for existing linter configs (ESLint, Biome, Prettier, tsconfig) — do NOT include rules they already enforce. Step 2: Identify important files Scan for non-obvious architecture-critical files. Look for: Auth config files Server action wrappers, API helpers Database schema files Custom middleware or shared utilities Skip standard framework files (package.json, tsconfig, next.config, etc.) Step 3: Generate CLAUDE.md Create the file with ONLY these sections. Each section should be compact — the whole file should be under 50 lines.

[Project Name] [One-line description of what this project is]

Tech Stack

[Only non-obvious technologies — skip deps detectable from config files]

Commands

[dev command] - Dev server - [build command] - Build - [test command] - Tests - [Any non-obvious commands like db:push, seed, etc.]

Important Files

[Only files the agent wouldn't discover naturally]

Rules

[Leave empty with a comment: "Add project-specific rules as you encounter friction"] Step 4: Present and write Show the generated file to the user. Write it to ./CLAUDE.md after approval. Rules: NEVER include directory structure, code style rules, generic best practices, or marketing text NEVER include anything a linter or TypeScript already enforces Target: 20-50 lines. If it's longer, you're including too much The Rules section starts empty — it gets populated over time as mistakes happen /claude-memory optimize — Deep CLAUDE.md Cleanup When the user argument contains "optimize", execute this workflow. CRITICAL — Step 0 is MANDATORY. Do NOT skip it. Do NOT start optimizing without reading the guide first. Step 0: Read the optimization guide (REQUIRED FIRST) YOU MUST use the Read tool on {SKILL_PATH}/references/optimize-guide.md BEFORE doing anything else. This file contains the research data (ETH Zurich study), the 6 bloat categories with specific examples, target metrics, and before/after examples. Without reading it, you will miss removal criteria and produce a subpar optimization. Step 1: Inventory Read every CLAUDE.md, CLAUDE.local.md, and .claude/rules/*.md in the project. Count total lines. Step 2: Read linter configs Read ESLint/Biome/Prettier/TypeScript configs. Any CLAUDE.md line duplicating an enforced rule → delete. Step 3: Apply the 6 bloat categories from the guide For each line ask: "Can the agent discover this by reading the project, or does a linter enforce this?" If yes → delete. Remove everything matching: Linter-enforced rules (ESLint, Prettier, Biome, TypeScript strict) Marketing / goals / vision (zero code value) Obvious info the agent discovers itself (directory structure, framework defaults, deps from package.json) Verbose explanations (paragraphs where 1 line suffices, tutorials, history) Redundant specs (copies of config files, schema descriptions, env var lists) Generic best practices ("write clean code", "DRY", "SOLID") Step 4: Keep only essentials Project purpose (1-3 lines) Tech stack (compact, non-obvious only) Core commands (non-obvious only) Testing commands Important files (non-obvious only) Project-specific rules (prohibitions + constraints) Workflow (only if non-standard) Step 5: Compress Paragraphs → bullet points 3-line rules → 1-line rules Zero filler words ("In order to", "It's important to note that") Merge related items Step 6: Present diff Show before/after with line counts. For each removal, cite which bloat category it falls under. Let user approve before applying changes. Target: < 100 lines ideal, < 150 max. Optimization guide : references/optimize-guide.md — Research-backed bloat checklist, 6 removal categories, before/after examples Rules directory : references/rules-directory-guide.md — Complete .claude/rules/ guide with path-scoping, YAML syntax, symlinks, migration Prompting techniques : references/prompting-techniques.md — Emphasis strategies, clarity techniques, constraint patterns Section templates : references/section-templates.md — Copy-paste templates for each section type Comprehensive example : references/comprehensive-example.md — Full production SaaS CLAUDE.md Project patterns : references/project-patterns.md — Next.js, Express, Python, Monorepo patterns