claude-memory

Memory files are automatically loaded at session startup, consuming tokens from your 200k context window. Every instruction competes with Claude Code's ~50 built-in instructions, leaving ~100-150 effective instruction slots for your customizations.

Two approaches available:

• •CLAUDE.md - Single file, simpler, best for small projects
• •.claude/rules/ - Modular files with optional path-scoping, best for large projects </objective>

<quick_start> <bootstrap_new_project> Run /init in Claude Code to auto-generate a CLAUDE.md with project structure.

Or create manually at project root:

# Project Name

## Tech Stack

- [Primary language/framework]
- [Key libraries]

## Commands

- `npm run dev` - Start development
- `npm test` - Run tests
- `npm run build` - Build for production

## Code Conventions

- [2-3 critical conventions]

## Important Context

- [1-2 architectural decisions worth knowing]

</bootstrap_new_project>

<quick_add_memory> Press # during a Claude Code session to quickly add new memory items without editing the file directly. </quick_add_memory>

<edit_memory> Use /memory command to open CLAUDE.md in your system editor. </edit_memory> </quick_start>

<file_hierarchy> Claude Code loads CLAUDE.md files in a specific order. Higher priority files are loaded first and take precedence.

<loading_order>

<recursive_loading> Claude recurses UP from current directory to root, loading all CLAUDE.md files found.

Running Claude in foo/bar/ loads:

1. •foo/bar/CLAUDE.md
2. •foo/CLAUDE.md
3. •Root-level files

Claude also discovers CLAUDE.md in SUBTREES when reading files in those directories. </recursive_loading>

<monorepo_strategy> For monorepos, use layered approach:

root/
├── CLAUDE.md              # Universal: tech stack, git workflow
├── apps/
│   ├── web/CLAUDE.md      # Frontend-specific patterns
│   └── api/CLAUDE.md      # Backend-specific patterns
└── packages/
    └── shared/CLAUDE.md   # Shared library conventions

Root file defines WHEN to use patterns; subtree files define HOW. </monorepo_strategy> </file_hierarchy>

<rules_directory> The .claude/rules/ directory provides a modular alternative to monolithic CLAUDE.md files. Instead of one large file, you organize instructions into multiple focused markdown files.

<when_to_use_rules> Use .claude/rules/ when:

• •Project has many distinct concerns (testing, security, API, frontend)
• •Different rules apply to different file types
• •Team members maintain different areas
• •You want to update one concern without touching others

Use CLAUDE.md when:

• •Project is small/simple
• •All rules are universal
• •You prefer a single source of truth </when_to_use_rules>

<rules_structure>

.claude/rules/
├── code-style.md      # Formatting and conventions
├── testing.md         # Test requirements
├── security.md        # Security checklist
├── frontend/
│   ├── react.md       # React-specific patterns
│   └── styles.md      # CSS conventions
└── backend/
    ├── api.md         # API development rules
    └── database.md    # Database conventions

Key points:

• •All .md files are discovered recursively
• •No imports or configuration needed
• •Same priority as CLAUDE.md
• •Supports symlinks for sharing rules across projects </rules_structure>

<path_scoped_rules> Rules can be scoped to specific files using YAML frontmatter:

---
paths:
  - "src/api/**/*.ts"
---
# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format

Path patterns supported:

Syntax note: The paths field must be a YAML array (list format with - prefix and quoted strings).

Rules without paths frontmatter load unconditionally for all files. </path_scoped_rules>

<user_level_rules> Create personal rules that apply to all your projects:

~/.claude/rules/
├── preferences.md    # Your coding preferences
├── workflows.md      # Your preferred workflows
└── git.md            # Your git conventions

User-level rules load before project rules, giving project rules higher priority for overrides. </user_level_rules>

<symlinks_support> Share common rules across multiple projects using symlinks:

# Symlink a shared rules directory
ln -s ~/shared-claude-rules .claude/rules/shared

# Symlink individual rule files
ln -s ~/company-standards/security.md .claude/rules/security.md

Circular symlinks are detected and handled gracefully. </symlinks_support> </rules_directory>

<content_framework> Structure your CLAUDE.md using the WHAT-WHY-HOW framework:

WHAT - Project Context: Tech stack, directory structure, architecture WHY - Purpose: Architectural decisions, why patterns exist HOW - Workflow: Commands, testing, git workflow, verification steps

## Tech Stack

- Next.js 15 with App Router
- PostgreSQL via Prisma ORM

## Architecture Decisions

- Server Components for data fetching
- All forms use TanStack Form

## Commands

- `pnpm dev` - Start dev server
- `pnpm test:ci` - Run tests
- `pnpm build` - Production build

## Git Workflow

- Branch: `feature/name` or `fix/name`
- Run tests before committing

See references/section-templates.md for complete templates. </content_framework>

<emphasis_techniques> Claude follows emphasized instructions more reliably. Use these techniques strategically for critical rules.

<keyword_hierarchy> Use emphasis keywords in order of severity:

</keyword_hierarchy>

<formatting_patterns> Bold + CRITICAL keyword:

**CRITICAL**: Always run tests before pushing code

Capitalized emphasis:

IMPORTANT: Do not commit environment variables
YOU MUST: Follow the git workflow outlined below
NEVER: Include API keys in code
ALWAYS: Use TypeScript strict mode

Strikethrough for forbidden options:

- `pnpm test:ci` - Run tests (use this)
- ~~`pnpm test`~~ - NEVER use (interactive mode)

Visual markers (use sparingly):

⚠️ WARNING: This affects production data
🔒 SECURITY: Never commit secrets to git

</formatting_patterns>

<placement_strategy> Order matters. Claude pays more attention to:

1. •First items in each section (put critical rules first)
2. •Repeated items across sections (repeat critical rules in context)
3. •Emphasized items with CRITICAL/NEVER/ALWAYS keywords

Structure your file with critical rules first:

## Code Conventions

### Critical Rules

- **NEVER** commit .env files
- **ALWAYS** run tests before pushing
- **CRITICAL**: Use TanStack Form for ALL forms

### General Guidelines

- Prefer Server Components
- Keep components under 300 lines

</placement_strategy>

<repetition_for_emphasis> For extremely important rules, repeat in multiple relevant contexts:

## Forms

**CRITICAL**: Use TanStack Form for ALL forms

## Before Editing

- **CRITICAL**: Use TanStack Form for forms

## Code Review Checklist

- [ ] Forms use TanStack Form (**CRITICAL**)

</repetition_for_emphasis> </emphasis_techniques>

<writing_effective_instructions> <golden_rule> Show your CLAUDE.md to someone with minimal project context. If they're confused, Claude will be too. </golden_rule>

<be_specific> Vague instructions cause inconsistent behavior:

❌ VAGUE:

- Format code properly
- Write good tests
- Follow best practices

✅ SPECIFIC:

- Run `pnpm lint` before committing (Prettier configured)
- Write tests in `__tests__/` using Vitest
- Use TanStack Form for all forms (see `src/features/form/`)

</be_specific>

<show_dont_tell> When format matters, show examples:

❌ TELLING:
Use conventional commits with type and description.

✅ SHOWING:

## Commit Format

feat(auth): implement JWT authentication

Add login endpoint and token validation

Types: feat, fix, refactor, docs, test, chore

</show_dont_tell>

<eliminate_ambiguity> Replace vague phrases with clear directives:

</eliminate_ambiguity>

<define_edge_cases> Anticipate questions and answer them:

❌ INCOMPLETE:
Run tests before pushing.

✅ COMPLETE:

## Testing

- Run `pnpm test:ci` before pushing
- If tests fail, fix before committing
- New features require tests in `__tests__/`
- Minimum 80% coverage for new code

</define_edge_cases>

<provide_decision_criteria> When Claude must make choices, give criteria:

## Component Choice

**Use Server Component when:**

- Data fetching only
- No user interaction needed

**Use Client Component when:**

- User interaction required
- Browser APIs needed (localStorage, window)

</provide_decision_criteria>

<separate_obligation_levels> Clearly distinguish requirements from suggestions:

## API Development

### Must Have

- Input validation with Zod
- Error handling for all endpoints

### Nice to Have

- Pagination for list endpoints
- Caching headers

### Must Not

- Expose internal errors to clients
- Log sensitive data

</separate_obligation_levels> </writing_effective_instructions>

<size_constraints> <limits>

• •Ideal: 100-200 lines maximum
• •Practical max: 300 lines before splitting
• •Universal items: Under 60 lines

Why these limits matter:

• •Claude reliably follows ~150-200 total instructions
• •Claude Code's system prompt uses ~50 instructions
• •Leaves ~100-150 slots for YOUR instructions
• •Irrelevant content degrades instruction-following </limits>

<scaling_strategy> When exceeding limits:

1. •Move task-specific details to separate files
2. •Link from CLAUDE.md with descriptions
3. •Use progressive disclosure pattern

## Detailed Guides

- **API Routes**: See [docs/api-patterns.md](docs/api-patterns.md)
- **Testing**: See [docs/testing-guide.md](docs/testing-guide.md)
- **Deployment**: See [docs/deployment.md](docs/deployment.md)

</scaling_strategy> </size_constraints>

<imports_feature> CLAUDE.md supports importing other markdown files:

## External References

@docs/coding-standards.md
@~/.claude/my-global-preferences.md
@./team-conventions.md

<import_rules>

• •Supports relative and absolute paths
• •Home directory expansion with ~
• •Recursive imports up to 5 levels deep
• •NOT evaluated inside code blocks or backticks </import_rules> </imports_feature>

<anti_patterns> <never_include> Code Style Rules - Use linters instead (LLMs are expensive, linters are free)

Secrets - NEVER include API keys, database URLs, tokens, credentials

Too Much Content - Link to docs instead of embedding 500+ lines

Extensive Code - Reference files instead (code examples become outdated)

Vague Instructions - Be specific (see <writing_effective_instructions>) </never_include>

<examples_what_to_avoid>

❌ BAD:

- Use 2-space indentation (use Prettier instead)
- DATABASE_URL=postgresql://... (never include secrets)
- [500 lines of API docs] (link to external file)
- Format code properly (too vague)

✅ GOOD:

- ESLint/Prettier configured (see .eslintrc)
- Credentials in `.env` (never committed)
- API guide: See [docs/api.md](docs/api.md)
- Run `pnpm lint` before committing

</examples_what_to_avoid> </anti_patterns>

• •Minimal example: references/section-templates.md (templates section)
• •Comprehensive SaaS: references/comprehensive-example.md
• •Project-specific: references/project-patterns.md (Next.js, Express, Python, Monorepo) </examples>

Before creating or updating memory files, ask the user:

Do you want to use a single CLAUDE.md file or split into separate .claude/rules/ files?

Option 1: Single CLAUDE.md - All instructions in one file (simpler, best for small projects) Option 2: Modular .claude/rules/ - Split by concern with optional path-scoping (better for large projects)

Use AskUserQuestion to present these options before proceeding.

Decision guide:

• •Choose CLAUDE.md if: < 100 lines of instructions, simple project, universal rules
• •Choose .claude/rules/ if: 100+ lines, multiple file types with different rules, team maintains different areas </decision_point>

<creating_new> Creating New Memory (CLAUDE.md approach)

1. •Start with /init or minimal template
2. •Add tech stack and commands first
3. •Add conventions as you encounter friction
4. •Test with real tasks
5. •Iterate based on Claude's behavior </creating_new>

<creating_rules> Creating New Memory (.claude/rules/ approach)

1. •Create .claude/rules/ directory
2. •Start with one file per major concern:
   • •general.md - Universal project rules
   • •testing.md - Testing conventions
   • •code-style.md - Code conventions
3. •Add path-scoped rules as needed:
   yaml

   ---
   paths:
     - "src/api/**/*.ts"
   ---
   # API rules here
   

4. •Test with real tasks in different file contexts
5. •Split or merge files based on usage patterns </creating_rules>

1. •Review quarterly (or when project changes significantly)
2. •Remove outdated instructions
3. •Add patterns that required repeated explanation
4. •Keep CLAUDE.md under 200 lines (or split to .claude/rules/)
5. •Use # for quick additions during work </maintaining>

<migrating_to_rules> Migrating from CLAUDE.md to .claude/rules/

When CLAUDE.md exceeds 200 lines:

1. •Identify distinct sections (testing, API, frontend, etc.)
2. •Create .claude/rules/ directory
3. •Move each section to its own file
4. •Add paths frontmatter where rules are file-type specific
5. •Keep only universal essentials in CLAUDE.md (or delete it)
6. •Test to ensure rules load correctly </migrating_to_rules>

<advanced_features> <local_overrides> Use CLAUDE.local.md for personal preferences (auto-gitignored):

• •Personal shortcuts and aliases
• •Editor-specific settings
• •Local testing commands </local_overrides>

<settings_integration> CLAUDE.md works alongside settings.json:

• •settings.json: Permissions, allowed tools, environment variables
• •CLAUDE.md: Context, conventions, workflow instructions </settings_integration>

<progressive_disclosure> For complex projects, link to detailed docs. Claude only loads when relevant:

## References

- **Database**: See [docs/database.md](docs/database.md)
- **API**: See [docs/api.md](docs/api.md)

</progressive_disclosure> </advanced_features>

<success_criteria> A well-crafted Claude memory system:

For CLAUDE.md approach:

• •Loads in under 200 lines
• •Contains only project-specific context (not general knowledge)
• •Uses emphasis for critical rules (CRITICAL, NEVER, ALWAYS)
• •Avoids code style rules (use linters)
• •Contains NO secrets or credentials
• •Provides clear commands for common tasks
• •Follows WHAT-WHY-HOW structure

For .claude/rules/ approach:

• •Each file focused on one concern (testing, API, security, etc.)
• •Path-scoped rules use accurate glob patterns
• •No duplicate rules across files
• •Files organized in logical subdirectories
• •Symlinks used for shared rules across projects

Both approaches:

• •Gets updated as project evolves
• •Improves Claude's first-try accuracy on tasks
• •User was asked which approach they prefer before implementation </success_criteria>

<reference_guides> For deeper topics:

• •Rules directory guide: references/rules-directory-guide.md - Complete guide to .claude/rules/ with official documentation, path-scoping, YAML syntax, and examples
• •Prompting techniques: references/prompting-techniques.md - Master guide for writing effective instructions, emphasis strategies, clarity techniques
• •Comprehensive example: references/comprehensive-example.md - Full production SaaS CLAUDE.md
• •Section templates: references/section-templates.md - Copy-paste templates for each section
• •Common patterns by project type: references/project-patterns.md - Next.js, Express, Python, Monorepo patterns </reference_guides>