claude-memory

<objective> Master the creation of effective Claude Code memory systems using either CLAUDE.md files or the modular `.claude/rules/` directory. This skill covers file hierarchy, content structure, path-scoped rules, formatting, emphasis techniques, and common anti-patterns to avoid.

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>

Priority	Location	Purpose	Scope
1 (Highest)	/Library/Application Support/ClaudeCode/CLAUDE.md (macOS)	Enterprise policy (managed by IT)	All org users
2	./CLAUDE.md or ./.claude/CLAUDE.md	Project memory (git-tracked)	Team via git
2	./.claude/rules/*.md	Modular rules (git-tracked)	Team via git
3	~/.claude/CLAUDE.md	User preferences (global)	All your projects
3	~/.claude/rules/*.md	Personal modular rules (global)	All your projects
4 (Lowest)	./CLAUDE.local.md	Personal project prefs (auto-gitignored)	Just you
</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:

Pattern	Matches
**/*.ts	All TypeScript files in any directory
src/**/*	All files under src/ directory
src/components/*.tsx	React components in specific directory
src/**/*.{ts,tsx}	TypeScript and TSX files (brace expansion)
{src,lib}/**/*.ts	Files in multiple directories

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	Use For	Example
CRITICAL	Non-negotiable rules	**CRITICAL**: Never commit secrets
NEVER	Absolute prohibitions	NEVER: Push directly to main
ALWAYS	Mandatory behaviors	ALWAYS: Run tests before pushing
IMPORTANT	Significant guidance	IMPORTANT: Keep components under 300 lines
YOU MUST	Explicit requirements	YOU MUST: Use TanStack Form for forms

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

Ambiguous	Clear Alternative
"Try to..."	"Always..." or "Never..."
"Should probably..."	"Must..." or "May optionally..."
"Generally..."	"Always... except when [condition]"
"Consider..."	"If [condition], then [action]"

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

<examples> For complete examples, see reference files:

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

<workflow> <decision_point> **ALWAYS ASK FIRST: Storage Strategy**

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:

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

<maintaining> **Maintaining Memory Files**

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>

<troubleshooting> **Common Issues**

Problem	Solution
Claude ignores instructions	Reduce file size, add emphasis (CRITICAL, NEVER)
Context overflow	Use /clear, split into .claude/rules/ files
Outdated information	Review quarterly, remove stale content
Instructions conflict	Consolidate, use hierarchy (root vs subtree)
Rules not loading	Check file is .md, in correct directory
Path rules not applying	Verify glob pattern matches target files

</troubleshooting> </workflow>

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

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