Skill refresh
This commit is contained in:
movq
557
claude-code/skills/claude-memory/patterns.md
Normal file
557
claude-code/skills/claude-memory/patterns.md
Normal file
@@ -0,0 +1,557 @@
|
||||
# Memory Optimization Patterns
|
||||
|
||||
Advanced techniques for token-efficient memory management.
|
||||
|
||||
## Pattern 1: Core + Imports Architecture
|
||||
|
||||
**Strategy**: Keep main CLAUDE.md minimal, import details on demand.
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
project/
|
||||
├── CLAUDE.md (100 lines - core)
|
||||
├── docs/
|
||||
│ ├── tech-stack.md
|
||||
│ ├── architecture.md
|
||||
│ ├── style-guide.md
|
||||
│ └── api-reference.md
|
||||
```
|
||||
|
||||
### CLAUDE.md (Core - Always Loaded)
|
||||
|
||||
```markdown
|
||||
# MyProject
|
||||
|
||||
Quick reference for AI coding assistant.
|
||||
|
||||
## Tech Stack
|
||||
- Backend: Node.js + Express + PostgreSQL
|
||||
- Frontend: React + TypeScript + Tailwind
|
||||
- Details: @docs/tech-stack.md
|
||||
|
||||
## Common Commands
|
||||
```bash
|
||||
npm run dev # Start dev server
|
||||
npm test # Run tests
|
||||
npm run build # Production build
|
||||
```
|
||||
|
||||
## Coding Standards
|
||||
- 2-space indentation
|
||||
- ESLint + Prettier
|
||||
- Full details: @docs/style-guide.md
|
||||
|
||||
## Architecture
|
||||
- Microservices pattern
|
||||
- See @docs/architecture.md
|
||||
|
||||
## IMPORTANT Rules
|
||||
- YOU MUST run tests before commits
|
||||
- Never commit secrets
|
||||
- Update API docs with endpoint changes
|
||||
```
|
||||
|
||||
**Token Cost**: ~400 tokens (loaded every conversation)
|
||||
|
||||
### docs/tech-stack.md (Detailed - Loaded on Demand)
|
||||
|
||||
```markdown
|
||||
# Technology Stack
|
||||
|
||||
## Backend
|
||||
- Node.js 20 LTS
|
||||
- Express 4.18
|
||||
- PostgreSQL 15
|
||||
- Sequelize ORM
|
||||
- Redis for caching
|
||||
- JWT authentication
|
||||
- bcrypt for passwords
|
||||
|
||||
[Extensive details, dependencies, versions, configuration...]
|
||||
```
|
||||
|
||||
**Token Cost**: ~1500 tokens (loaded only when discussing tech stack)
|
||||
|
||||
### Benefits
|
||||
|
||||
- **Main memory stays lean**: 100 lines vs 500+
|
||||
- **Details loaded contextually**: Only when needed
|
||||
- **Easy to update**: Each doc has single focus
|
||||
- **Team ownership**: Different people can own different docs
|
||||
|
||||
---
|
||||
|
||||
## Pattern 2: Subfolder Specialization
|
||||
|
||||
**Strategy**: Use subfolder memory for context-specific guidance.
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
myproject/
|
||||
├── CLAUDE.md # Root - shared context
|
||||
├── frontend/
|
||||
│ ├── CLAUDE.md # Frontend-specific
|
||||
│ └── src/
|
||||
├── backend/
|
||||
│ ├── CLAUDE.md # Backend-specific
|
||||
│ └── src/
|
||||
└── docs/
|
||||
├── architecture.md
|
||||
└── conventions.md
|
||||
```
|
||||
|
||||
### Root CLAUDE.md
|
||||
|
||||
```markdown
|
||||
# MyProject
|
||||
|
||||
Microservices e-commerce platform.
|
||||
|
||||
## Common Across All Areas
|
||||
- Git workflow: feature branches + PRs
|
||||
- Testing required before merge
|
||||
- See @docs/architecture.md
|
||||
|
||||
## Subprojects
|
||||
- `frontend/` - React app (see frontend/CLAUDE.md)
|
||||
- `backend/` - API server (see backend/CLAUDE.md)
|
||||
```
|
||||
|
||||
### frontend/CLAUDE.md (Loaded When Working in frontend/)
|
||||
|
||||
```markdown
|
||||
# Frontend Context
|
||||
|
||||
- React 18 + TypeScript strict mode
|
||||
- Component structure: Atomic Design
|
||||
- Styling: Tailwind utility-first
|
||||
- State: Redux Toolkit
|
||||
|
||||
## Component Patterns
|
||||
@../docs/ui-patterns.md
|
||||
|
||||
## Testing
|
||||
- Jest + React Testing Library
|
||||
- Coverage > 80%
|
||||
- Test user interactions, not implementation
|
||||
```
|
||||
|
||||
### backend/CLAUDE.md (Loaded When Working in backend/)
|
||||
|
||||
```markdown
|
||||
# Backend Context
|
||||
|
||||
- Express + TypeScript
|
||||
- Database: PostgreSQL + Sequelize
|
||||
- Auth: JWT + refresh tokens
|
||||
- Caching: Redis
|
||||
|
||||
## API Patterns
|
||||
@../docs/api-patterns.md
|
||||
|
||||
## Security
|
||||
- All endpoints have rate limiting
|
||||
- Input validation with Zod
|
||||
- SQL injection protection via ORM
|
||||
```
|
||||
|
||||
### When to Use
|
||||
|
||||
- Large monorepos
|
||||
- Different tech stacks per area
|
||||
- Team specialization (frontend/backend teams)
|
||||
- Different conventions per module
|
||||
|
||||
---
|
||||
|
||||
## Pattern 3: User + Project Separation
|
||||
|
||||
**Strategy**: Personal preferences globally, project specifics locally.
|
||||
|
||||
### ~/.claude/CLAUDE.md (Personal - All Projects)
|
||||
|
||||
```markdown
|
||||
# Personal Defaults
|
||||
|
||||
## Communication Style
|
||||
- Explain decisions before acting
|
||||
- Ask before destructive operations
|
||||
- Show diffs for large changes
|
||||
|
||||
## Code Preferences
|
||||
- Prefer functional programming
|
||||
- Avoid premature optimization
|
||||
- Comprehensive error handling
|
||||
|
||||
## Tools
|
||||
- Git commit format: Conventional Commits
|
||||
- Prefer `npm` over `yarn`
|
||||
```
|
||||
|
||||
**Applies To**: Every project you work on
|
||||
|
||||
### ./CLAUDE.md (Project - Overrides Personal)
|
||||
|
||||
```markdown
|
||||
# ProjectX
|
||||
|
||||
IMPORTANT: This legacy project uses OOP extensively (override FP preference).
|
||||
|
||||
Tech stack:
|
||||
- Java Spring Boot
|
||||
- MySQL
|
||||
- jQuery (legacy frontend)
|
||||
|
||||
Common commands:
|
||||
```bash
|
||||
mvn clean install
|
||||
mvn test
|
||||
```
|
||||
|
||||
Conventions:
|
||||
- CamelCase for classes
|
||||
- snake_case for database
|
||||
```
|
||||
|
||||
**Applies To**: Only this project, overrides personal preferences
|
||||
|
||||
### Benefits
|
||||
|
||||
- Consistent personal style across all projects
|
||||
- Project-specific overrides when needed
|
||||
- Easy onboarding to new projects
|
||||
- Maintain personal workflow preferences
|
||||
|
||||
---
|
||||
|
||||
## Pattern 4: Team Collaboration
|
||||
|
||||
**Strategy**: Shared standards in git, personal overrides local.
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
# Version control
|
||||
.claude/CLAUDE.md # Team standards (in git)
|
||||
.claude/settings.json # Team settings (in git)
|
||||
|
||||
# Local overrides
|
||||
.claude/CLAUDE.local.md # Personal (gitignored)
|
||||
.claude/settings.local.json # Personal (gitignored)
|
||||
```
|
||||
|
||||
### .gitignore
|
||||
|
||||
```gitignore
|
||||
# Personal overrides only
|
||||
.claude/CLAUDE.local.md
|
||||
.claude/settings.local.json
|
||||
|
||||
# Team files are tracked
|
||||
# .claude/CLAUDE.md
|
||||
# .claude/settings.json
|
||||
```
|
||||
|
||||
### .claude/CLAUDE.md (Team - In Git)
|
||||
|
||||
```markdown
|
||||
# Team Standards
|
||||
|
||||
IMPORTANT: All team members should follow these conventions.
|
||||
|
||||
## Git Workflow
|
||||
1. Create feature branch: `feature/description`
|
||||
2. PR to `develop` (not `main`)
|
||||
3. 2 approvals required
|
||||
4. Squash merge
|
||||
|
||||
## Code Review Checklist
|
||||
- Tests pass locally
|
||||
- Coverage > 80%
|
||||
- No linter warnings
|
||||
- Documentation updated
|
||||
|
||||
## Architecture Decisions
|
||||
@docs/adr/ # Architecture Decision Records
|
||||
|
||||
## NEVER
|
||||
- Commit directly to `main`
|
||||
- Merge without tests passing
|
||||
- Hardcode credentials
|
||||
```
|
||||
|
||||
### .claude/CLAUDE.local.md (Personal - Gitignored)
|
||||
|
||||
```markdown
|
||||
# My Personal Overrides
|
||||
|
||||
## Development Preferences
|
||||
- Use Neovim for editing
|
||||
- Prefer verbose logging during dev
|
||||
- Run tests in watch mode
|
||||
|
||||
[Preferences that don't affect team]
|
||||
```
|
||||
|
||||
### Benefits
|
||||
|
||||
- Consistent team standards
|
||||
- Personal customization allowed
|
||||
- Version-controlled team rules
|
||||
- Built-in onboarding documentation
|
||||
|
||||
---
|
||||
|
||||
## Token Management Strategies
|
||||
|
||||
### Strategy 1: Measure Current Usage
|
||||
|
||||
```bash
|
||||
# Estimate tokens (rough: chars ÷ 4)
|
||||
wc -c CLAUDE.md | awk '{print $1/4}'
|
||||
# Goal: < 5000 tokens (<20KB file)
|
||||
|
||||
# Count lines
|
||||
wc -l CLAUDE.md
|
||||
# Goal: 100-200 lines
|
||||
|
||||
# Find verbose sections (lines >100 chars)
|
||||
grep -n "." CLAUDE.md | awk -F: 'length($2) > 100 {print NR": "$0}'
|
||||
```
|
||||
|
||||
### Strategy 2: Lean Writing Techniques
|
||||
|
||||
#### Before (150 tokens)
|
||||
|
||||
```markdown
|
||||
The application uses a microservices architecture where each service is
|
||||
independently deployable and scalable. The services communicate via REST
|
||||
APIs and message queues. This allows for better separation of concerns
|
||||
and makes it easier to maintain and scale individual components.
|
||||
```
|
||||
|
||||
#### After (30 tokens)
|
||||
|
||||
```markdown
|
||||
Architecture: Microservices (REST + message queues)
|
||||
- Independent deployment/scaling
|
||||
- See @docs/architecture.md
|
||||
```
|
||||
|
||||
**Reduction**: 80%
|
||||
|
||||
### Compression Techniques
|
||||
|
||||
1. **Bullet Points > Paragraphs**
|
||||
- Lists are 50% more token-efficient
|
||||
- Easier to scan
|
||||
|
||||
2. **Commands > Explanations**
|
||||
- Show `npm test` instead of describing testing process
|
||||
- Code is self-documenting
|
||||
|
||||
3. **Imports > Embedding**
|
||||
- `@docs/api.md` costs 5 tokens
|
||||
- Embedding API docs costs 2000 tokens
|
||||
|
||||
4. **Examples > Theory**
|
||||
- One example worth 100 words
|
||||
- Concrete beats abstract
|
||||
|
||||
### Strategy 3: Strategic Importing
|
||||
|
||||
```markdown
|
||||
# Decision Tree
|
||||
|
||||
Is this info needed in 80%+ of sessions?
|
||||
→ YES: Keep in CLAUDE.md
|
||||
|
||||
Is this info needed occasionally?
|
||||
→ YES: Put in @docs/, reference from CLAUDE.md
|
||||
|
||||
Is this info needed rarely?
|
||||
→ NO: Don't include, use web search or direct file read
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md (Always Loaded - ~400 tokens)
|
||||
Core commands, key conventions, critical rules
|
||||
|
||||
# @docs/architecture.md (On Demand - ~1500 tokens)
|
||||
Loaded only when discussing architecture
|
||||
|
||||
# @docs/api-reference.md (On Demand - ~2000 tokens)
|
||||
Loaded only when working on APIs
|
||||
|
||||
# @docs/testing-guide.md (On Demand - ~800 tokens)
|
||||
Loaded only when writing tests
|
||||
|
||||
# @docs/deployment.md (On Demand - ~600 tokens)
|
||||
Loaded only when deploying
|
||||
```
|
||||
|
||||
**Total**: 400 tokens/conversation instead of 5300 tokens
|
||||
**Savings**: 92%
|
||||
|
||||
### Strategy 4: Regular Cleanup
|
||||
|
||||
Monthly review checklist:
|
||||
|
||||
```bash
|
||||
# 1. Find outdated content
|
||||
grep -i "deprecated\|old\|legacy\|TODO" CLAUDE.md
|
||||
|
||||
# 2. Check for redundant sections
|
||||
# Look for repeated information
|
||||
|
||||
# 3. Identify candidates for @imports
|
||||
# Sections >50 lines that aren't always needed
|
||||
|
||||
# 4. Verify all rules are current
|
||||
# Test: does Claude follow each rule?
|
||||
|
||||
# 5. Measure improvement
|
||||
# Before: X lines
|
||||
# After: Y lines
|
||||
# Reduction: Z%
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Patterns
|
||||
|
||||
### Dynamic Context Loading
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md
|
||||
|
||||
## Context Selection
|
||||
|
||||
When working on:
|
||||
- **Frontend**: Read @frontend/CLAUDE.md
|
||||
- **Backend**: Read @backend/CLAUDE.md
|
||||
- **DevOps**: Read @docs/devops.md
|
||||
- **Testing**: Read @docs/testing.md
|
||||
- **Documentation**: Read @docs/writing-guide.md
|
||||
|
||||
Ask yourself: "What am I working on?" and load that context.
|
||||
```
|
||||
|
||||
### Versioned Standards
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md
|
||||
|
||||
## Current Standards
|
||||
|
||||
API Version: v2
|
||||
See @docs/api-v2.md
|
||||
|
||||
## Migration Guides
|
||||
|
||||
Upgrading from v1? See @docs/migration-v1-to-v2.md
|
||||
|
||||
## Deprecated
|
||||
|
||||
v1 API (deprecated, remove by Q1 2024)
|
||||
Historical reference: @docs/api-v1-deprecated.md
|
||||
```
|
||||
|
||||
### Role-Based Memory
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md
|
||||
|
||||
## Available Roles
|
||||
|
||||
You can act as different roles depending on the task:
|
||||
|
||||
- **Full-Stack Developer**: @docs/role-fullstack.md
|
||||
- **Frontend Specialist**: @docs/role-frontend.md
|
||||
- **Backend Specialist**: @docs/role-backend.md
|
||||
- **DevOps Engineer**: @docs/role-devops.md
|
||||
- **QA Engineer**: @docs/role-qa.md
|
||||
|
||||
Switch roles: "Act as [role name]"
|
||||
```
|
||||
|
||||
### Conditional Instructions
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md
|
||||
|
||||
## Environment-Aware Behavior
|
||||
|
||||
### Development Environment
|
||||
- Verbose logging OK
|
||||
- Use local DB (localhost:5432)
|
||||
- Mock external APIs
|
||||
|
||||
### Staging Environment
|
||||
- Moderate logging
|
||||
- Use staging DB
|
||||
- Real external APIs (test keys)
|
||||
|
||||
### Production Environment
|
||||
- Minimal logging
|
||||
- Use RDS
|
||||
- NEVER commit with console.log
|
||||
- ALWAYS check deployment checklist
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Before Optimization
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md (1000 lines, 4000 tokens)
|
||||
[Everything embedded]
|
||||
|
||||
Average tokens per conversation: 4000
|
||||
Cost per 1000 conversations: ~$80 (input tokens)
|
||||
```
|
||||
|
||||
### After Optimization
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md (150 lines, 600 tokens)
|
||||
[Core + imports]
|
||||
|
||||
# Imported when needed:
|
||||
@docs/architecture.md (1500 tokens)
|
||||
@docs/api.md (1200 tokens)
|
||||
@docs/testing.md (800 tokens)
|
||||
|
||||
Average tokens per conversation: 600
|
||||
+ Architecture discussions: +1500 (20% of conversations)
|
||||
+ API work: +1200 (30% of conversations)
|
||||
+ Testing: +800 (15% of conversations)
|
||||
|
||||
Weighted average: 600 + (1500×0.2) + (1200×0.3) + (800×0.15) = 1380 tokens
|
||||
|
||||
Cost per 1000 conversations: ~$27 (input tokens)
|
||||
Savings: 66%
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary: Best Practices
|
||||
|
||||
1. **Target 100-200 lines** for main CLAUDE.md
|
||||
2. **Use imports liberally** for detailed docs
|
||||
3. **Write concisely**: bullets > paragraphs
|
||||
4. **Be specific**: concrete > vague
|
||||
5. **Emphasize critical rules**: IMPORTANT, YOU MUST, NEVER
|
||||
6. **Organize by scope**: user vs project vs subfolder
|
||||
7. **Measure regularly**: track token usage
|
||||
8. **Clean monthly**: remove outdated content
|
||||
9. **Test effectiveness**: verify Claude follows rules
|
||||
10. **Version control team files**: track changes
|
||||
|
||||
**Goal**: Minimum tokens for maximum effectiveness.
|
||||
Reference in New Issue
Block a user