<core_principle> 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 </core_principle>

<quick_start> 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 </quick_start>

<file_hierarchy>

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

</file_hierarchy>

<rules_directory> 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. </rules_directory>

<content_structure> 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. </content_structure>

<writing_rules> 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. </writing_rules>

<size_limits>

• 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
• 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). </size_limits>

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

<init_workflow>

/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 </init_workflow>

<optimize_workflow>

/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. </optimize_workflow>

<reference_guides>

• 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 </reference_guides>