Claude Memory

Two approaches:

• CLAUDE.md — Single file, best for small projects (< 100 lines)
• .claude/rules/ — Modular files with optional path-scoping, best for large projects

# 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

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

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.

1. Project purpose (1-3 lines) — What the project is
2. Tech stack (compact) — Only non-obvious technologies
3. Commands — Non-obvious dev, build, and test commands
4. Important files — Architecture-critical, non-obvious files only
5. Rules — Prohibitions and constraints that prevent mistakes (highest-value lines)
6. 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.

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.

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](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:

1. Start with /init or minimal template
2. Add tech stack and commands first
3. Add rules only as you encounter friction
4. Test with real tasks, iterate based on Claude's behavior

Maintaining:

1. Review quarterly or when project changes significantly
2. Remove outdated instructions
3. Add patterns that required repeated explanation
4. Use # for quick additions during work

Troubleshooting:

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

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:

1. Linter-enforced rules (ESLint, Prettier, Biome, TypeScript strict)
2. Marketing / goals / vision (zero code value)
3. Obvious info the agent discovers itself (directory structure, framework defaults, deps from package.json)
4. Verbose explanations (paragraphs where 1 line suffices, tutorials, history)
5. Redundant specs (copies of config files, schema descriptions, env var lists)
6. 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.