255 lines
6.0 KiB
Markdown
255 lines
6.0 KiB
Markdown
---
|
|
name: Claude Code Memory Specialist
|
|
description: Optimize and troubleshoot Claude Code memory files (CLAUDE.md) for efficiency, token management, and team collaboration. Use PROACTIVELY when memory isn't loading, context is bloated, optimizing existing memory files, or when users mention "CLAUDE.md", "memory file", or "project context". NOT for initial setup - use /init command first.
|
|
---
|
|
|
|
# Claude Code Memory Optimization & Troubleshooting
|
|
|
|
## When to Use This Skill
|
|
|
|
Use this skill when:
|
|
- Troubleshooting memory files that aren't loading
|
|
- Optimizing bloated CLAUDE.md files (>200 lines)
|
|
- Managing token consumption in project memory
|
|
- Setting up memory hierarchy (project/user/subfolder)
|
|
- Debugging why Claude isn't following instructions
|
|
- Organizing memory for team collaboration
|
|
|
|
Do NOT use this skill for:
|
|
- **Initial setup** - Use `/init` command instead
|
|
- Creating slash commands (use claude-command-expert skill)
|
|
- General Claude Code issues
|
|
|
|
**Important**: Always start with `/init` for initial project memory setup.
|
|
|
|
## Quick Reference: Memory Hierarchy
|
|
|
|
```
|
|
1. Enterprise Policy ~/.claude/enterprise/CLAUDE.md (highest priority)
|
|
2. Project Memory ./CLAUDE.md or ./.claude/CLAUDE.md
|
|
3. User Memory ~/.claude/CLAUDE.md
|
|
4. Subfolder Memory ./subfolder/CLAUDE.md
|
|
```
|
|
|
|
**Lookup Order**: Claude searches upward from current directory, loading all CLAUDE.md files found.
|
|
|
|
## Core Principles
|
|
|
|
### 1. Target Size: 100-200 Lines
|
|
|
|
**Why**: Each CLAUDE.md loaded consumes tokens in every conversation.
|
|
|
|
```markdown
|
|
# ❌ Bad (500+ lines)
|
|
Extensive documentation embedded inline
|
|
|
|
# ✓ Good (150 lines)
|
|
Core info + imports for details
|
|
```
|
|
|
|
### 2. Progressive Disclosure Pattern
|
|
|
|
```markdown
|
|
# CLAUDE.md (Core - always loaded)
|
|
Quick reference, critical rules, imports
|
|
|
|
# docs/architecture.md (Loaded on demand)
|
|
Detailed architecture information
|
|
|
|
# docs/style-guide.md (Loaded on demand)
|
|
Comprehensive coding standards
|
|
```
|
|
|
|
### 3. Use Specific, Emphatic Language
|
|
|
|
```markdown
|
|
# ❌ Weak
|
|
Use functional components
|
|
|
|
# ✓ Strong
|
|
IMPORTANT: ALL React components MUST be functional (no class components).
|
|
```
|
|
|
|
## Essential Structure
|
|
|
|
### Minimal Template (100 lines)
|
|
|
|
```markdown
|
|
# ProjectName
|
|
|
|
Brief description.
|
|
|
|
## Tech Stack
|
|
- Key technologies
|
|
- See @docs/tech-stack.md for details
|
|
|
|
## Common Commands
|
|
```bash
|
|
npm run dev # Start development
|
|
npm test # Run tests
|
|
```
|
|
|
|
## Conventions
|
|
- 2-space indentation
|
|
- ESLint + Prettier
|
|
- See @docs/style-guide.md
|
|
|
|
## IMPORTANT Rules
|
|
- YOU MUST run tests before commits
|
|
- Never commit secrets
|
|
- Update docs with code changes
|
|
```
|
|
|
|
For complete templates, see [templates.md](templates.md)
|
|
|
|
## Common Problems (Quick Fixes)
|
|
|
|
| Problem | Quick Fix |
|
|
|---------|-----------|
|
|
| Memory not loading | Check filename case: `CLAUDE.md` |
|
|
| Claude ignores rules | Add `IMPORTANT:` or `YOU MUST` |
|
|
| Too many tokens | Move details to @docs/ imports |
|
|
| Updates not working | Restart session or use `/memory` |
|
|
| Conflicting memories | Project wins over user (check hierarchy) |
|
|
|
|
For detailed troubleshooting, see [troubleshooting.md](troubleshooting.md)
|
|
|
|
## Optimization Quick Win
|
|
|
|
**Before (bloated)**:
|
|
```markdown
|
|
This project is a comprehensive platform built with React, Node.js, Express,
|
|
PostgreSQL... [extensive paragraph explaining everything]
|
|
```
|
|
|
|
**After (lean)**:
|
|
```markdown
|
|
Tech Stack: React + Node.js + PostgreSQL
|
|
See @docs/architecture.md for details
|
|
```
|
|
|
|
**Result**: 80% token reduction
|
|
|
|
For optimization patterns, see [patterns.md](patterns.md)
|
|
|
|
## File Locations
|
|
|
|
### Project (Team-Shared)
|
|
```bash
|
|
.claude/CLAUDE.md # Team standards (in git)
|
|
.claude/settings.json # Team configuration
|
|
```
|
|
|
|
### Personal (Not Shared)
|
|
```bash
|
|
.claude/CLAUDE.local.md # Personal overrides (gitignored)
|
|
~/.claude/CLAUDE.md # Global defaults
|
|
```
|
|
|
|
## Import Best Practices
|
|
|
|
### ✓ Do
|
|
```markdown
|
|
# CLAUDE.md
|
|
Quick reference content
|
|
|
|
For detailed architecture: @docs/architecture.md
|
|
For API reference: @docs/api-reference.md
|
|
```
|
|
|
|
### ❌ Don't
|
|
```markdown
|
|
# CLAUDE.md
|
|
@docs/a.md → @docs/b.md → @docs/c.md → @docs/d.md → @docs/e.md → @docs/f.md
|
|
# Max depth is 5, avoid deep chains
|
|
```
|
|
|
|
**Rules**:
|
|
- Max import depth: 5 levels
|
|
- No circular references
|
|
- Use relative paths for project files
|
|
- Keep import chains flat, not deep
|
|
|
|
## Quick Update Methods
|
|
|
|
### Method 1: # Shortcut (Fastest)
|
|
```bash
|
|
# Press # at input start
|
|
# Type your update
|
|
# Auto-adds to appropriate CLAUDE.md
|
|
```
|
|
|
|
### Method 2: /memory Command
|
|
```bash
|
|
/memory
|
|
# Opens memory management interface
|
|
```
|
|
|
|
### Method 3: Direct Edit
|
|
```bash
|
|
vim CLAUDE.md
|
|
# Then ask Claude to reload
|
|
```
|
|
|
|
## Emphasis Techniques
|
|
|
|
For critical rules:
|
|
|
|
```markdown
|
|
IMPORTANT: [Critical rule]
|
|
YOU MUST [mandatory action]
|
|
NEVER [forbidden action]
|
|
**Bold** for emphasis
|
|
ALL CAPS for maximum attention
|
|
```
|
|
|
|
## Testing Memory Effectiveness
|
|
|
|
### Quick Test
|
|
```markdown
|
|
# Add temporary marker to CLAUDE.md
|
|
**MEMORY TEST: If you see this, memory loaded correctly**
|
|
|
|
# Ask Claude: "What's the first line of your memory?"
|
|
# Should see marker, then remove it
|
|
```
|
|
|
|
## Team Setup Example
|
|
|
|
```bash
|
|
# .gitignore
|
|
.claude/CLAUDE.local.md # Personal only
|
|
.claude/settings.local.json # Personal settings
|
|
|
|
# .claude/CLAUDE.md (in git)
|
|
# Team Standards
|
|
|
|
@docs/architecture.md
|
|
@docs/conventions.md
|
|
|
|
IMPORTANT: All team members follow these standards.
|
|
|
|
## Git Workflow
|
|
1. Feature branch from develop
|
|
2. PR requires 2 approvals
|
|
3. Squash merge
|
|
|
|
## NEVER
|
|
- Commit directly to main
|
|
- Merge without tests passing
|
|
```
|
|
|
|
For team workflows, see [workflows.md](workflows.md)
|
|
|
|
## Resources
|
|
|
|
- [Memory File Templates](templates.md) - Ready-to-use CLAUDE.md templates
|
|
- [Troubleshooting Guide](troubleshooting.md) - Detailed problem-solution guide
|
|
- [Optimization Patterns](patterns.md) - Advanced token-saving techniques
|
|
- [Team Workflows](workflows.md) - Collaboration strategies
|
|
- [Official Documentation](https://docs.claude.com/en/docs/claude-code/memory)
|
|
|
|
---
|
|
|
|
**Remember**: Practice what we preach - keep memory lean (100-200 lines), be specific not vague, use imports for details, emphasize critical rules, test effectiveness.
|