Skill refresh
This commit is contained in:
movq
254
claude-code/skills/claude-memory/SKILL.md
Normal file
254
claude-code/skills/claude-memory/SKILL.md
Normal file
@@ -0,0 +1,254 @@
|
||||
---
|
||||
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.
|
||||
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.
|
||||
406
claude-code/skills/claude-memory/templates.md
Normal file
406
claude-code/skills/claude-memory/templates.md
Normal file
@@ -0,0 +1,406 @@
|
||||
# Memory File Templates
|
||||
|
||||
Ready-to-use CLAUDE.md templates for different project types.
|
||||
|
||||
## Template 1: Minimal Project
|
||||
|
||||
For simple projects with straightforward requirements.
|
||||
|
||||
```markdown
|
||||
# ProjectName
|
||||
|
||||
Brief description.
|
||||
|
||||
## Tech Stack
|
||||
- Language/Framework
|
||||
- Database
|
||||
- Key libraries
|
||||
|
||||
## Common Commands
|
||||
```bash
|
||||
start-command
|
||||
test-command
|
||||
build-command
|
||||
```
|
||||
|
||||
## Conventions
|
||||
- Code style rule 1
|
||||
- Code style rule 2
|
||||
- Naming convention
|
||||
|
||||
## IMPORTANT
|
||||
- Critical rule 1
|
||||
- Critical rule 2
|
||||
```
|
||||
|
||||
**Target Size**: ~50 lines
|
||||
**Use For**: Small projects, prototypes, personal projects
|
||||
|
||||
---
|
||||
|
||||
## Template 2: Team Project
|
||||
|
||||
For collaborative projects with extensive documentation.
|
||||
|
||||
```markdown
|
||||
# ProjectName
|
||||
|
||||
@docs/overview.md
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Tech Stack
|
||||
@docs/tech-stack.md
|
||||
|
||||
### Common Commands
|
||||
```bash
|
||||
npm run dev
|
||||
npm test
|
||||
npm run build
|
||||
```
|
||||
|
||||
### Coding Standards
|
||||
- 2-space indentation
|
||||
- ESLint + Prettier
|
||||
- Full guide: @docs/style-guide.md
|
||||
|
||||
### Architecture
|
||||
@docs/architecture.md
|
||||
|
||||
## IMPORTANT Team Rules
|
||||
|
||||
- YOU MUST create PR for all changes
|
||||
- Tests must pass before merge
|
||||
- Update docs with code changes
|
||||
|
||||
## Git Workflow
|
||||
@docs/git-workflow.md
|
||||
|
||||
## NEVER
|
||||
- Commit to main directly
|
||||
- Merge without review
|
||||
- Commit secrets
|
||||
```
|
||||
|
||||
**Target Size**: ~100 lines
|
||||
**Use For**: Team projects, open source, enterprise applications
|
||||
|
||||
---
|
||||
|
||||
## Template 3: Monorepo
|
||||
|
||||
For multi-package repositories.
|
||||
|
||||
```markdown
|
||||
# MonorepoName
|
||||
|
||||
Multi-package repository.
|
||||
|
||||
## Structure
|
||||
- `packages/frontend/` - React app → See frontend/CLAUDE.md
|
||||
- `packages/backend/` - API server → See backend/CLAUDE.md
|
||||
- `packages/shared/` - Common code
|
||||
|
||||
## Global Standards
|
||||
- Node.js 20+
|
||||
- pnpm workspaces
|
||||
- Shared ESLint config
|
||||
|
||||
## Commands (from root)
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm test
|
||||
pnpm run build
|
||||
```
|
||||
|
||||
## Cross-Package
|
||||
- Import from `@myapp/shared`
|
||||
- See @docs/package-deps.md
|
||||
|
||||
## IMPORTANT
|
||||
- Changes affecting multiple packages need full test suite
|
||||
```
|
||||
|
||||
**Target Size**: ~80 lines
|
||||
**Use For**: Monorepos, microservices, multi-tier applications
|
||||
|
||||
---
|
||||
|
||||
## Template 4: Personal Defaults
|
||||
|
||||
For ~/.claude/CLAUDE.md (applies to all your projects).
|
||||
|
||||
```markdown
|
||||
# Personal Preferences
|
||||
|
||||
Applied to all my projects unless overridden.
|
||||
|
||||
## Communication
|
||||
- Explain reasoning before acting
|
||||
- Confirm before destructive ops
|
||||
- Show diffs for large changes
|
||||
|
||||
## Code Style
|
||||
- Functional programming preferred
|
||||
- Descriptive variable names
|
||||
- Comments for "why", not "what"
|
||||
|
||||
## Git
|
||||
- Conventional Commits format
|
||||
- Squash feature branches
|
||||
|
||||
## Testing
|
||||
- Write tests alongside code
|
||||
- Aim for 80%+ coverage
|
||||
```
|
||||
|
||||
**Target Size**: ~50 lines
|
||||
**Use For**: Personal global settings
|
||||
|
||||
---
|
||||
|
||||
## Template 5: Frontend Project
|
||||
|
||||
```markdown
|
||||
# Frontend App
|
||||
|
||||
React/TypeScript application.
|
||||
|
||||
## Tech Stack
|
||||
- React 18 + TypeScript
|
||||
- Tailwind CSS
|
||||
- State: Redux Toolkit
|
||||
- Router: React Router v6
|
||||
|
||||
## Commands
|
||||
```bash
|
||||
npm run dev # Dev server (localhost:3000)
|
||||
npm test # Jest + RTL
|
||||
npm run build # Production build
|
||||
npm run lint # ESLint
|
||||
```
|
||||
|
||||
## Structure
|
||||
- `src/components/` - React components
|
||||
- `src/hooks/` - Custom hooks
|
||||
- `src/store/` - Redux slices
|
||||
- `src/utils/` - Helper functions
|
||||
|
||||
## Conventions
|
||||
- Functional components only
|
||||
- Custom hooks for logic reuse
|
||||
- 2-space indentation
|
||||
- Import order: external → internal → styles
|
||||
|
||||
## IMPORTANT
|
||||
- All components need tests
|
||||
- Accessibility: WCAG AA minimum
|
||||
- No inline styles (use Tailwind)
|
||||
```
|
||||
|
||||
**Target Size**: ~100 lines
|
||||
**Use For**: React, Vue, Angular, or other SPA projects
|
||||
|
||||
---
|
||||
|
||||
## Template 6: Backend API
|
||||
|
||||
```markdown
|
||||
# Backend API
|
||||
|
||||
Node.js/Express REST API.
|
||||
|
||||
## Tech Stack
|
||||
- Express + TypeScript
|
||||
- PostgreSQL + Sequelize
|
||||
- Redis for caching
|
||||
- JWT authentication
|
||||
|
||||
## Commands
|
||||
```bash
|
||||
npm run dev # Dev server (localhost:4000)
|
||||
npm test # Jest
|
||||
npm run migrate # Run migrations
|
||||
npm run seed # Seed database
|
||||
```
|
||||
|
||||
## Structure
|
||||
- `src/routes/` - API endpoints
|
||||
- `src/controllers/` - Business logic
|
||||
- `src/models/` - Database models
|
||||
- `src/middleware/` - Express middleware
|
||||
- `src/utils/` - Helper functions
|
||||
|
||||
## Environment
|
||||
- See `.env.example` for required vars
|
||||
- Never commit `.env`
|
||||
|
||||
## IMPORTANT
|
||||
- All endpoints need rate limiting
|
||||
- Input validation required
|
||||
- Error handling middleware
|
||||
- Log security events
|
||||
```
|
||||
|
||||
**Target Size**: ~110 lines
|
||||
**Use For**: API servers, backend services
|
||||
|
||||
---
|
||||
|
||||
## Template 7: Python Project
|
||||
|
||||
```markdown
|
||||
# Python Project
|
||||
|
||||
Python application using modern tooling.
|
||||
|
||||
## Tech Stack
|
||||
- Python 3.11+
|
||||
- uv for dependency management
|
||||
- pytest for testing
|
||||
- ruff for linting
|
||||
|
||||
## Commands
|
||||
```bash
|
||||
uv run python main.py # Run application
|
||||
uv run pytest # Run tests
|
||||
uv run ruff check . # Lint
|
||||
```
|
||||
|
||||
## Structure
|
||||
- `src/` - Application code
|
||||
- `tests/` - Test files
|
||||
- `pyproject.toml` - Project config
|
||||
|
||||
## Conventions
|
||||
- Type hints required
|
||||
- Docstrings for public APIs
|
||||
- Follow PEP 8
|
||||
- Max line length: 100
|
||||
|
||||
## IMPORTANT
|
||||
- All functions need type hints
|
||||
- Test coverage > 80%
|
||||
- No bare `except:` clauses
|
||||
```
|
||||
|
||||
**Target Size**: ~90 lines
|
||||
**Use For**: Python applications, CLI tools, data science projects
|
||||
|
||||
---
|
||||
|
||||
## Customization Tips
|
||||
|
||||
### Adding Project-Specific Rules
|
||||
|
||||
```markdown
|
||||
## IMPORTANT Project Rules
|
||||
|
||||
- YOU MUST [mandatory action]
|
||||
- NEVER [forbidden action]
|
||||
- ALWAYS [required practice]
|
||||
```
|
||||
|
||||
### Adding Tech Stack Details
|
||||
|
||||
```markdown
|
||||
## Tech Stack
|
||||
- Backend: Node.js + Express
|
||||
- Auth: JWT + refresh tokens
|
||||
- ORM: Sequelize
|
||||
- Validation: Zod
|
||||
- Frontend: React + TypeScript
|
||||
- State: Zustand
|
||||
- Styling: Tailwind
|
||||
- Forms: React Hook Form
|
||||
```
|
||||
|
||||
### Adding Team Workflow
|
||||
|
||||
```markdown
|
||||
## Git Workflow
|
||||
1. Branch from `develop`
|
||||
2. Name: `feature/description` or `fix/description`
|
||||
3. PR requires 2 approvals
|
||||
4. Squash merge to develop
|
||||
5. Weekly releases to main
|
||||
```
|
||||
|
||||
### Referencing External Docs
|
||||
|
||||
```markdown
|
||||
## Documentation
|
||||
- Architecture: @docs/architecture.md
|
||||
- API Reference: @docs/api.md
|
||||
- Contributing: @CONTRIBUTING.md
|
||||
- Deployment: @docs/deployment.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
### ❌ Too Verbose
|
||||
|
||||
```markdown
|
||||
# Bad: 500 lines
|
||||
This project is a comprehensive e-commerce platform that provides
|
||||
users with the ability to browse products, add them to their cart,
|
||||
and complete purchases securely. The architecture follows a microservices
|
||||
pattern with separate services for user management, product catalog,
|
||||
shopping cart, payment processing, and order fulfillment...
|
||||
|
||||
[400 more lines of detailed explanation]
|
||||
```
|
||||
|
||||
### ✓ Concise with Imports
|
||||
|
||||
```markdown
|
||||
# Good: 100 lines
|
||||
E-commerce platform with microservices architecture.
|
||||
|
||||
Tech Stack: @docs/tech-stack.md
|
||||
Architecture: @docs/architecture.md
|
||||
Conventions: @docs/conventions.md
|
||||
|
||||
## Quick Start
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
```
|
||||
|
||||
### ❌ Vague Instructions
|
||||
|
||||
```markdown
|
||||
# Bad
|
||||
- Write clean code
|
||||
- Follow best practices
|
||||
- Be secure
|
||||
```
|
||||
|
||||
### ✓ Specific Instructions
|
||||
|
||||
```markdown
|
||||
# Good
|
||||
IMPORTANT:
|
||||
- All API endpoints MUST have rate limiting (100 req/min)
|
||||
- Passwords MUST be hashed with bcrypt (min 10 rounds)
|
||||
- Input validation MUST use Zod schemas
|
||||
- SQL queries MUST use parameterized statements
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Selection Guide
|
||||
|
||||
| Project Type | Template | Target Size |
|
||||
|-------------|----------|-------------|
|
||||
| Personal/Small | Minimal | ~50 lines |
|
||||
| Team Project | Team | ~100 lines |
|
||||
| Monorepo | Monorepo | ~80 lines |
|
||||
| Frontend SPA | Frontend | ~100 lines |
|
||||
| Backend API | Backend | ~110 lines |
|
||||
| Python App | Python | ~90 lines |
|
||||
| Global Settings | Personal Defaults | ~50 lines |
|
||||
|
||||
**General Rule**: Start with the appropriate template, customize for your needs, keep under 200 lines.
|
||||
513
claude-code/skills/claude-memory/troubleshooting.md
Normal file
513
claude-code/skills/claude-memory/troubleshooting.md
Normal file
@@ -0,0 +1,513 @@
|
||||
# Memory Troubleshooting Guide
|
||||
|
||||
Detailed problem-solution reference for CLAUDE.md issues.
|
||||
|
||||
## Problem 1: Memory File Not Loading
|
||||
|
||||
**Symptoms**: Claude doesn't seem to remember project context, no awareness of CLAUDE.md contents.
|
||||
|
||||
### Diagnosis
|
||||
|
||||
```bash
|
||||
# Check if file exists
|
||||
ls -la CLAUDE.md
|
||||
ls -la .claude/CLAUDE.md
|
||||
ls -la ~/.claude/CLAUDE.md
|
||||
|
||||
# Check file permissions
|
||||
ls -l CLAUDE.md
|
||||
|
||||
# Check current directory
|
||||
pwd
|
||||
```
|
||||
|
||||
### Common Causes & Solutions
|
||||
|
||||
#### Cause 1: Wrong Location
|
||||
|
||||
```bash
|
||||
# ❌ Bad: Random location
|
||||
/some/random/path/CLAUDE.md
|
||||
|
||||
# ✓ Good: Project root
|
||||
./CLAUDE.md
|
||||
# or
|
||||
./.claude/CLAUDE.md
|
||||
```
|
||||
|
||||
**Solution**: Move file to project root or `.claude/` directory.
|
||||
|
||||
#### Cause 2: Wrong Filename (Case-Sensitive!)
|
||||
|
||||
```bash
|
||||
# ❌ Bad
|
||||
claude.md
|
||||
Claude.md
|
||||
CLAUDE.MD
|
||||
README.md
|
||||
|
||||
# ✓ Good
|
||||
CLAUDE.md
|
||||
```
|
||||
|
||||
**Solution**: Rename to exactly `CLAUDE.md` (all caps).
|
||||
|
||||
#### Cause 3: Syntax Errors in Imports
|
||||
|
||||
```markdown
|
||||
# ❌ Bad: Broken import
|
||||
@docs/nonexistent.md
|
||||
|
||||
# ✓ Good: Valid path
|
||||
@docs/architecture.md
|
||||
```
|
||||
|
||||
**Solution**: Verify all imported paths exist and are correct.
|
||||
|
||||
#### Cause 4: File Permissions
|
||||
|
||||
```bash
|
||||
# Check permissions
|
||||
ls -l CLAUDE.md
|
||||
|
||||
# If not readable, fix it
|
||||
chmod 644 CLAUDE.md
|
||||
```
|
||||
|
||||
### Verification Test
|
||||
|
||||
Add a temporary marker to CLAUDE.md:
|
||||
|
||||
```markdown
|
||||
**MEMORY LOADED: This is a test marker**
|
||||
```
|
||||
|
||||
Ask Claude: "What's the first line of your memory?"
|
||||
If Claude sees the marker, memory is loading correctly.
|
||||
Remove marker after test.
|
||||
|
||||
---
|
||||
|
||||
## Problem 2: Bloated Memory (Token Waste)
|
||||
|
||||
**Symptoms**: Context fills up quickly, slow responses, high costs, frequent compaction.
|
||||
|
||||
### Diagnosis
|
||||
|
||||
```bash
|
||||
# Check file size
|
||||
wc -l CLAUDE.md
|
||||
# Goal: 100-200 lines max
|
||||
|
||||
# Count characters (rough token estimate: chars ÷ 4)
|
||||
wc -c CLAUDE.md
|
||||
# Goal: < 20KB
|
||||
```
|
||||
|
||||
### Solution: Trim and Split
|
||||
|
||||
#### Before (Bloated - 500 lines)
|
||||
|
||||
```markdown
|
||||
# Project Overview
|
||||
|
||||
This project is a comprehensive e-commerce platform built with React, Node.js,
|
||||
Express, PostgreSQL, Redis, and Docker. The frontend uses React 18 with TypeScript
|
||||
in strict mode, Tailwind CSS for styling, React Router for navigation, Redux Toolkit
|
||||
for state management, and Axios for API calls. The backend uses Express.js with
|
||||
TypeScript, Sequelize ORM for database access, JWT for authentication, bcrypt for
|
||||
password hashing, and Redis for session management...
|
||||
|
||||
[400 more lines of verbose content]
|
||||
```
|
||||
|
||||
#### After (Lean - 150 lines)
|
||||
|
||||
```markdown
|
||||
# Tech Stack
|
||||
|
||||
- Frontend: React 18 + TypeScript + Tailwind
|
||||
- Backend: Express + PostgreSQL + Redis
|
||||
- Architecture: Microservices
|
||||
- Details: @docs/tech-stack.md
|
||||
|
||||
## Common Commands
|
||||
|
||||
```bash
|
||||
npm run dev # Local development
|
||||
npm test # Run all tests
|
||||
npm run build # Production build
|
||||
```
|
||||
|
||||
## Key Conventions
|
||||
|
||||
- 2-space indentation
|
||||
- Functional components only
|
||||
- ESLint + Prettier
|
||||
- 80% test coverage minimum
|
||||
|
||||
## IMPORTANT Rules
|
||||
|
||||
- YOU MUST run tests before committing
|
||||
- Never commit .env files
|
||||
- Always update API docs when adding endpoints
|
||||
```
|
||||
|
||||
**Result**: 70% token reduction
|
||||
|
||||
### Compression Techniques
|
||||
|
||||
1. **Use Bullet Points, Not Paragraphs**
|
||||
2. **Use Imports for Details**
|
||||
3. **Show Commands, Not Explanations**
|
||||
4. **Prefer Tables Over Text**
|
||||
|
||||
---
|
||||
|
||||
## Problem 3: Claude Not Following Instructions
|
||||
|
||||
**Symptoms**: Claude ignores rules in CLAUDE.md, doesn't follow conventions.
|
||||
|
||||
### Diagnosis
|
||||
|
||||
Check instruction specificity:
|
||||
|
||||
```markdown
|
||||
# ❌ Too Vague (ignored)
|
||||
- Write clean code
|
||||
- Follow best practices
|
||||
- Be careful with security
|
||||
|
||||
# ✓ Specific (followed)
|
||||
- Use 2-space indentation (not tabs)
|
||||
- All API endpoints must have rate limiting
|
||||
- Hash passwords with bcrypt (min 10 rounds)
|
||||
```
|
||||
|
||||
### Solution: Add Emphasis
|
||||
|
||||
#### Weak Instruction (Often Ignored)
|
||||
|
||||
```markdown
|
||||
Use functional components in React.
|
||||
Run tests before committing.
|
||||
```
|
||||
|
||||
#### Strong Instruction (Followed)
|
||||
|
||||
```markdown
|
||||
IMPORTANT: ALL React components MUST be functional (no class components).
|
||||
|
||||
YOU MUST run `npm test` and ensure all tests pass before any git commit.
|
||||
```
|
||||
|
||||
### Emphasis Hierarchy
|
||||
|
||||
1. `ALL CAPS` - Maximum attention
|
||||
2. `IMPORTANT:` - Critical rules
|
||||
3. `YOU MUST` - Mandatory actions
|
||||
4. `NEVER` - Forbidden actions
|
||||
5. **Bold** - Standard emphasis
|
||||
6. Regular text - General info
|
||||
|
||||
### Example: Strong Rules Section
|
||||
|
||||
```markdown
|
||||
## IMPORTANT Project Rules
|
||||
|
||||
YOU MUST:
|
||||
- Run full test suite before every commit
|
||||
- Get 2 PR approvals before merging
|
||||
- Update API documentation when adding endpoints
|
||||
|
||||
NEVER:
|
||||
- Commit directly to main branch
|
||||
- Merge code with failing tests
|
||||
- Hardcode API keys or secrets
|
||||
|
||||
ALWAYS:
|
||||
- Use environment variables for config
|
||||
- Include error handling in all async functions
|
||||
- Write tests for new features
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Problem 4: Memory Updates Not Reflected
|
||||
|
||||
**Symptoms**: Changes to CLAUDE.md don't take effect in current session.
|
||||
|
||||
### Solutions
|
||||
|
||||
#### Method 1: Quick Add (# Shortcut)
|
||||
|
||||
```bash
|
||||
# At input prompt, press # first
|
||||
# Type: Use snake_case for Python functions
|
||||
# Claude auto-adds to appropriate CLAUDE.md
|
||||
```
|
||||
|
||||
**Best For**: Quick single-line updates
|
||||
|
||||
#### Method 2: /memory Command
|
||||
|
||||
```bash
|
||||
/memory
|
||||
# Opens memory management interface
|
||||
```
|
||||
|
||||
**Best For**: Reviewing and editing existing memory
|
||||
|
||||
#### Method 3: Direct Edit + Reload
|
||||
|
||||
```bash
|
||||
# Edit the file
|
||||
vim CLAUDE.md
|
||||
|
||||
# Then explicitly ask Claude
|
||||
"Please re-read CLAUDE.md"
|
||||
```
|
||||
|
||||
**Best For**: Major updates or reorganization
|
||||
|
||||
#### Method 4: Session Restart (Most Reliable)
|
||||
|
||||
```bash
|
||||
# Close and reopen Claude Code
|
||||
# Or Ctrl+C to exit CLI
|
||||
```
|
||||
|
||||
**Best For**: When other methods don't work
|
||||
|
||||
---
|
||||
|
||||
## Problem 5: Too Many Memory Files
|
||||
|
||||
**Symptoms**: Conflicting instructions, unclear hierarchy, unexpected behavior.
|
||||
|
||||
### Diagnosis
|
||||
|
||||
```bash
|
||||
# Find all CLAUDE.md files
|
||||
find . -name "CLAUDE.md"
|
||||
find ~ -name "CLAUDE.md"
|
||||
|
||||
# Check which directory you're in
|
||||
pwd
|
||||
```
|
||||
|
||||
### Understanding Priority
|
||||
|
||||
Higher priority wins on conflicts:
|
||||
|
||||
```
|
||||
1. ~/.claude/enterprise/CLAUDE.md # Organization policy (highest)
|
||||
↓
|
||||
2. ./CLAUDE.md # Current project
|
||||
↓
|
||||
3. ~/.claude/CLAUDE.md # Your personal defaults
|
||||
↓
|
||||
4. ./subfolder/CLAUDE.md # Subfolder overrides
|
||||
```
|
||||
|
||||
### Solution: Organize Properly
|
||||
|
||||
#### Global Personal (~/.claude/CLAUDE.md)
|
||||
|
||||
```markdown
|
||||
# Personal Defaults
|
||||
|
||||
## Communication Style
|
||||
- Explain decisions before acting
|
||||
- Ask before destructive operations
|
||||
|
||||
## Code Preferences
|
||||
- Prefer functional programming
|
||||
- Avoid premature optimization
|
||||
```
|
||||
|
||||
**Use For**: Universal personal preferences
|
||||
|
||||
#### Project Root (./CLAUDE.md)
|
||||
|
||||
```markdown
|
||||
# MyProject
|
||||
|
||||
@docs/tech-stack.md
|
||||
@docs/conventions.md
|
||||
|
||||
IMPORTANT: This project uses OOP (override personal FP preference).
|
||||
|
||||
Tech Stack: Java + Spring Boot
|
||||
```
|
||||
|
||||
**Use For**: Project-specific standards (overrides personal)
|
||||
|
||||
#### Subfolder (./frontend/CLAUDE.md)
|
||||
|
||||
```markdown
|
||||
# Frontend Context
|
||||
|
||||
- React 18 + TypeScript
|
||||
- Component structure: Atomic Design
|
||||
- See @../docs/ui-patterns.md
|
||||
```
|
||||
|
||||
**Use For**: Directory-specific context (loaded when in that directory)
|
||||
|
||||
---
|
||||
|
||||
## Problem 6: Import Loops or Errors
|
||||
|
||||
**Symptoms**: "Import depth exceeded", circular import error, or infinite loading.
|
||||
|
||||
### Import Rules
|
||||
|
||||
```markdown
|
||||
# ❌ Bad: Too Deep
|
||||
CLAUDE.md
|
||||
→ @docs/a.md (depth 1)
|
||||
→ @docs/b.md (depth 2)
|
||||
→ @docs/c.md (depth 3)
|
||||
→ @docs/d.md (depth 4)
|
||||
→ @docs/e.md (depth 5)
|
||||
→ @docs/f.md (depth 6 - FAILS!)
|
||||
|
||||
# ✓ Good: Flat Structure
|
||||
CLAUDE.md
|
||||
→ @docs/architecture.md
|
||||
→ @docs/conventions.md
|
||||
→ @docs/testing.md
|
||||
→ @docs/deployment.md
|
||||
|
||||
# ❌ Bad: Circular Import
|
||||
CLAUDE.md → @docs/a.md → @docs/b.md → @docs/a.md (LOOP!)
|
||||
|
||||
# ✓ Good: No Circles
|
||||
CLAUDE.md → @docs/a.md → @docs/c.md
|
||||
→ @docs/b.md → @docs/c.md
|
||||
```
|
||||
|
||||
### Solution: Restructure Imports
|
||||
|
||||
**Before (Deep Chain)**:
|
||||
```markdown
|
||||
# CLAUDE.md
|
||||
@docs/main.md
|
||||
|
||||
# docs/main.md
|
||||
@project/overview.md
|
||||
|
||||
# project/overview.md
|
||||
@details/architecture.md
|
||||
|
||||
# details/architecture.md
|
||||
[content]
|
||||
```
|
||||
|
||||
**After (Flat)**:
|
||||
```markdown
|
||||
# CLAUDE.md
|
||||
@docs/overview.md
|
||||
@docs/architecture.md
|
||||
@docs/conventions.md
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
|
||||
- **Max depth**: 5 levels
|
||||
- **No circular references**
|
||||
- **Prefer flat over deep**
|
||||
- **Use relative paths** for project files: `@docs/file.md`
|
||||
- **Use absolute paths** for global files: `@~/.claude/shared.md`
|
||||
|
||||
---
|
||||
|
||||
## Problem 7: Conflicting Team Instructions
|
||||
|
||||
**Symptoms**: Different team members get different behavior from Claude.
|
||||
|
||||
### Diagnosis
|
||||
|
||||
```bash
|
||||
# Check for local overrides
|
||||
ls .claude/CLAUDE.local.md
|
||||
ls .claude/settings.local.json
|
||||
|
||||
# Check git-tracked files
|
||||
git ls-files | grep -i claude
|
||||
```
|
||||
|
||||
### Solution: Proper Separation
|
||||
|
||||
#### Team-Shared (.claude/CLAUDE.md - in git)
|
||||
|
||||
```markdown
|
||||
# Team Standards
|
||||
|
||||
IMPORTANT: All team members follow these conventions.
|
||||
|
||||
## Git Workflow
|
||||
1. Branch from `develop`
|
||||
2. PR requires 2 approvals
|
||||
3. Squash merge
|
||||
|
||||
## Coding Standards
|
||||
@docs/style-guide.md
|
||||
|
||||
## NEVER
|
||||
- Commit directly to main
|
||||
- Merge without tests
|
||||
```
|
||||
|
||||
#### Personal (.claude/CLAUDE.local.md - gitignored)
|
||||
|
||||
```markdown
|
||||
# My Personal Preferences
|
||||
|
||||
[Individual customizations that don't affect team]
|
||||
```
|
||||
|
||||
#### .gitignore Setup
|
||||
|
||||
```gitignore
|
||||
# Personal files (not shared)
|
||||
.claude/CLAUDE.local.md
|
||||
.claude/settings.local.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: Diagnostic Checklist
|
||||
|
||||
When memory isn't working, check:
|
||||
|
||||
```markdown
|
||||
- [ ] File named exactly "CLAUDE.md" (case-sensitive)
|
||||
- [ ] File in project root or .claude/ directory
|
||||
- [ ] File has read permissions (chmod 644)
|
||||
- [ ] Valid markdown syntax
|
||||
- [ ] Imports use correct paths
|
||||
- [ ] No circular import loops
|
||||
- [ ] Import depth ≤ 5 levels
|
||||
- [ ] File size < 20KB (~200 lines)
|
||||
- [ ] Instructions are specific, not vague
|
||||
- [ ] Used emphasis for critical rules
|
||||
- [ ] No syntax errors in code blocks
|
||||
- [ ] Tried session restart
|
||||
- [ ] Verified loading with test marker
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
If problems persist:
|
||||
|
||||
1. **Verify File Loading**: Add test marker, ask Claude to read it
|
||||
2. **Check Hierarchy**: Understand which files are being loaded
|
||||
3. **Review Syntax**: Ensure valid markdown and imports
|
||||
4. **Simplify First**: Start with minimal CLAUDE.md, add back gradually
|
||||
5. **Restart Session**: Most reliable way to reload changes
|
||||
|
||||
For further assistance, see [Official Documentation](https://docs.claude.com/en/docs/claude-code/memory).
|
||||
624
claude-code/skills/claude-memory/workflows.md
Normal file
624
claude-code/skills/claude-memory/workflows.md
Normal file
@@ -0,0 +1,624 @@
|
||||
# Team Collaboration Workflows
|
||||
|
||||
Strategies for using CLAUDE.md in team environments.
|
||||
|
||||
## Workflow 1: Onboarding New Developer
|
||||
|
||||
### Goal
|
||||
Get new team members productive immediately using CLAUDE.md as primary documentation.
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
# Project repository structure
|
||||
myproject/
|
||||
├── .claude/
|
||||
│ └── CLAUDE.md # Team standards
|
||||
├── docs/
|
||||
│ ├── architecture.md
|
||||
│ ├── conventions.md
|
||||
│ └── getting-started.md
|
||||
└── README.md
|
||||
```
|
||||
|
||||
### Process
|
||||
|
||||
#### Step 1: Clone Repository
|
||||
|
||||
```bash
|
||||
git clone repo
|
||||
cd myproject
|
||||
```
|
||||
|
||||
#### Step 2: Claude Reads Memory Automatically
|
||||
|
||||
New developer opens Claude Code - memory loads automatically.
|
||||
|
||||
#### Step 3: Ask Claude for Orientation
|
||||
|
||||
```
|
||||
New Dev: "What's this project about?"
|
||||
|
||||
Claude (using CLAUDE.md): "This is an e-commerce platform using:
|
||||
- Tech Stack: React + Node.js + PostgreSQL
|
||||
- Architecture: Microservices pattern
|
||||
- Key directories: src/api, src/components, src/services
|
||||
- Start with: npm install && npm run dev
|
||||
- See docs/getting-started.md for detailed setup"
|
||||
```
|
||||
|
||||
#### Step 4: Productive Immediately
|
||||
|
||||
New developer can:
|
||||
- Ask Claude about any convention
|
||||
- Get help with setup issues
|
||||
- Understand architecture decisions
|
||||
- Follow team standards automatically
|
||||
|
||||
### Benefits
|
||||
|
||||
- **Zero onboarding docs to read**: Claude explains everything
|
||||
- **Consistent answers**: Same info for all team members
|
||||
- **Always up to date**: Update CLAUDE.md, everyone gets it
|
||||
- **Interactive learning**: Ask questions, get context-aware answers
|
||||
|
||||
---
|
||||
|
||||
## Workflow 2: Updating Team Standards
|
||||
|
||||
### Goal
|
||||
Change team conventions and have all developers adopt them immediately.
|
||||
|
||||
### Scenario
|
||||
Team decides to switch from npm to pnpm.
|
||||
|
||||
### Process
|
||||
|
||||
#### Step 1: Update CLAUDE.md
|
||||
|
||||
```bash
|
||||
# Edit .claude/CLAUDE.md
|
||||
sed -i 's/npm run/pnpm run/g' .claude/CLAUDE.md
|
||||
sed -i 's/npm test/pnpm test/g' .claude/CLAUDE.md
|
||||
sed -i 's/npm install/pnpm install/g' .claude/CLAUDE.md
|
||||
```
|
||||
|
||||
Update commands section:
|
||||
|
||||
```markdown
|
||||
## Common Commands
|
||||
```bash
|
||||
pnpm run dev # Start development server
|
||||
pnpm test # Run test suite
|
||||
pnpm run build # Production build
|
||||
```
|
||||
|
||||
IMPORTANT: This project uses pnpm, not npm.
|
||||
```
|
||||
|
||||
#### Step 2: Commit Change
|
||||
|
||||
```bash
|
||||
git add .claude/CLAUDE.md
|
||||
git commit -m "docs: switch package manager from npm to pnpm"
|
||||
git push
|
||||
```
|
||||
|
||||
#### Step 3: Team Pulls Update
|
||||
|
||||
```bash
|
||||
# Each developer
|
||||
git pull
|
||||
```
|
||||
|
||||
#### Step 4: Claude Uses New Standard
|
||||
|
||||
Next time anyone asks Claude to run a command, it uses pnpm automatically.
|
||||
|
||||
### Benefits
|
||||
|
||||
- **Immediate adoption**: No need to notify team
|
||||
- **No context switching**: Claude reminds developers
|
||||
- **Version controlled**: Track convention changes
|
||||
- **Rollback if needed**: Git history
|
||||
|
||||
---
|
||||
|
||||
## Workflow 3: Feature-Specific Context
|
||||
|
||||
### Goal
|
||||
Provide context for specific feature areas without bloating root memory.
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
project/
|
||||
├── CLAUDE.md # Root context
|
||||
├── features/
|
||||
│ ├── auth/
|
||||
│ │ ├── CLAUDE.md # Auth-specific context
|
||||
│ │ └── src/
|
||||
│ ├── payments/
|
||||
│ │ ├── CLAUDE.md # Payment-specific context
|
||||
│ │ └── src/
|
||||
│ └── notifications/
|
||||
│ ├── CLAUDE.md # Notification-specific context
|
||||
│ └── src/
|
||||
```
|
||||
|
||||
### Root CLAUDE.md
|
||||
|
||||
```markdown
|
||||
# MyProject
|
||||
|
||||
## Feature Areas
|
||||
|
||||
Each feature has specific context:
|
||||
- `features/auth/` - Authentication (see auth/CLAUDE.md)
|
||||
- `features/payments/` - Payment processing (see payments/CLAUDE.md)
|
||||
- `features/notifications/` - Notification system (see notifications/CLAUDE.md)
|
||||
|
||||
When working in a feature directory, Claude loads that context automatically.
|
||||
```
|
||||
|
||||
### features/auth/CLAUDE.md
|
||||
|
||||
```markdown
|
||||
# Authentication Feature
|
||||
|
||||
## Implementation
|
||||
- JWT + refresh tokens
|
||||
- Token lifetime: 15min access, 7d refresh
|
||||
- Password requirements: min 12 chars, bcrypt rounds: 12
|
||||
|
||||
## Key Files
|
||||
- `src/auth.service.ts` - Core auth logic
|
||||
- `src/jwt.util.ts` - Token generation/validation
|
||||
- `src/password.util.ts` - Password hashing
|
||||
|
||||
## IMPORTANT Security Rules
|
||||
- Passwords MUST be hashed with bcrypt (min 12 rounds)
|
||||
- Tokens MUST have expiration
|
||||
- MFA required for admin accounts
|
||||
- Log all authentication failures
|
||||
|
||||
## Testing
|
||||
- Unit tests: `tests/auth.test.ts`
|
||||
- Integration: `tests/auth.integration.test.ts`
|
||||
- All auth changes need security review
|
||||
```
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
# Developer working on auth feature
|
||||
cd features/auth
|
||||
|
||||
# Claude now has both root context + auth-specific context
|
||||
# Can answer auth-specific questions with full context
|
||||
```
|
||||
|
||||
### Benefits
|
||||
|
||||
- **Contextual memory**: Right info at right time
|
||||
- **No bloat**: Root memory stays lean
|
||||
- **Feature ownership**: Each team owns their feature docs
|
||||
- **Isolated changes**: Update feature context independently
|
||||
|
||||
---
|
||||
|
||||
## Workflow 4: Architecture Decision Records (ADR)
|
||||
|
||||
### Goal
|
||||
Document why decisions were made and have Claude reference them.
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
project/
|
||||
├── .claude/
|
||||
│ └── CLAUDE.md
|
||||
└── docs/
|
||||
└── adr/
|
||||
├── 001-use-postgresql.md
|
||||
├── 002-microservices-architecture.md
|
||||
├── 003-graphql-over-rest.md
|
||||
└── template.md
|
||||
```
|
||||
|
||||
### CLAUDE.md Reference
|
||||
|
||||
```markdown
|
||||
# MyProject
|
||||
|
||||
## Architecture Decisions
|
||||
|
||||
All architectural decisions are documented in ADRs.
|
||||
|
||||
See @docs/adr/ for all decisions.
|
||||
|
||||
When making architectural changes:
|
||||
1. Propose via ADR
|
||||
2. Get team review
|
||||
3. Update CLAUDE.md if needed
|
||||
```
|
||||
|
||||
### ADR Format (docs/adr/003-graphql-over-rest.md)
|
||||
|
||||
```markdown
|
||||
# 3. Use GraphQL Instead of REST
|
||||
|
||||
Date: 2024-01-15
|
||||
Status: Accepted
|
||||
|
||||
## Context
|
||||
Need API design pattern for new features.
|
||||
|
||||
## Decision
|
||||
Use GraphQL for new APIs, maintain REST for legacy.
|
||||
|
||||
## Consequences
|
||||
**Positive:**
|
||||
- Flexible queries
|
||||
- Reduced over-fetching
|
||||
- Strong typing
|
||||
|
||||
**Negative:**
|
||||
- Learning curve
|
||||
- More complex caching
|
||||
|
||||
## Implementation
|
||||
See @docs/graphql-guide.md
|
||||
```
|
||||
|
||||
### Usage
|
||||
|
||||
Developer asks Claude: "Why do we use GraphQL?"
|
||||
|
||||
Claude references ADR and explains the decision context.
|
||||
|
||||
### Benefits
|
||||
|
||||
- **Historical context**: Understand past decisions
|
||||
- **Onboarding**: New devs understand "why"
|
||||
- **Consistency**: Reference when making new decisions
|
||||
- **Change tracking**: Git history of decisions
|
||||
|
||||
---
|
||||
|
||||
## Workflow 5: Code Review Automation
|
||||
|
||||
### Goal
|
||||
Use CLAUDE.md to establish review standards, have Claude enforce them.
|
||||
|
||||
### .claude/CLAUDE.md
|
||||
|
||||
```markdown
|
||||
# MyProject
|
||||
|
||||
## Code Review Checklist
|
||||
|
||||
Before approving PRs, verify:
|
||||
|
||||
### Functionality
|
||||
- [ ] Tests pass locally
|
||||
- [ ] New features have tests
|
||||
- [ ] Coverage > 80%
|
||||
|
||||
### Code Quality
|
||||
- [ ] Follows style guide
|
||||
- [ ] No linter warnings
|
||||
- [ ] Functions < 50 lines
|
||||
- [ ] Clear variable names
|
||||
|
||||
### Security
|
||||
- [ ] No hardcoded secrets
|
||||
- [ ] Input validation present
|
||||
- [ ] SQL uses parameterized queries
|
||||
- [ ] Auth checks on protected routes
|
||||
|
||||
### Documentation
|
||||
- [ ] API changes documented
|
||||
- [ ] Complex logic has comments
|
||||
- [ ] README updated if needed
|
||||
|
||||
## NEVER Approve PRs With
|
||||
- Failing tests
|
||||
- Linter errors
|
||||
- Hardcoded credentials
|
||||
- console.log statements
|
||||
```
|
||||
|
||||
### Usage in Review
|
||||
|
||||
```
|
||||
Reviewer: "Review this PR: #123"
|
||||
|
||||
Claude (reads PR, checks against CLAUDE.md):
|
||||
"Reviewing PR #123 against team standards:
|
||||
|
||||
✓ Tests pass
|
||||
✓ Coverage maintained (85%)
|
||||
✗ Found console.log in auth.ts:42
|
||||
✗ Missing input validation in user.controller.ts:67
|
||||
✗ API changes not documented
|
||||
|
||||
Recommendation: Request changes before approval.
|
||||
|
||||
Specific issues:
|
||||
1. auth.ts:42 - Remove console.log (violates standards)
|
||||
2. user.controller.ts:67 - Add Zod validation for email field
|
||||
3. Missing: Update API.md with new /users/profile endpoint
|
||||
```
|
||||
|
||||
### Benefits
|
||||
|
||||
- **Consistent reviews**: Same standards for all reviewers
|
||||
- **Automated checks**: Claude catches issues
|
||||
- **Teaching tool**: Shows reviewers what to look for
|
||||
- **Living standards**: Update CLAUDE.md as standards evolve
|
||||
|
||||
---
|
||||
|
||||
## Workflow 6: Multi-Repository Consistency
|
||||
|
||||
### Goal
|
||||
Maintain consistent standards across multiple repositories.
|
||||
|
||||
### Setup
|
||||
|
||||
```
|
||||
~/.claude/CLAUDE.md # Personal + org standards
|
||||
|
||||
org-repo-1/
|
||||
└── .claude/
|
||||
└── CLAUDE.md # Repo-specific (imports personal)
|
||||
|
||||
org-repo-2/
|
||||
└── .claude/
|
||||
└── CLAUDE.md # Repo-specific (imports personal)
|
||||
```
|
||||
|
||||
### ~/.claude/CLAUDE.md (Shared Across All Repos)
|
||||
|
||||
```markdown
|
||||
# Organization Standards
|
||||
|
||||
Applied to all our repositories.
|
||||
|
||||
## Git Workflow
|
||||
- Branch from main
|
||||
- Squash merge PRs
|
||||
- Conventional commits
|
||||
|
||||
## Code Quality
|
||||
- Tests required
|
||||
- Linting enforced
|
||||
- 80% coverage minimum
|
||||
|
||||
## Security
|
||||
- No hardcoded secrets
|
||||
- Input validation required
|
||||
- Security review for auth changes
|
||||
|
||||
## Documentation
|
||||
@~/docs/org-standards.md
|
||||
```
|
||||
|
||||
### org-repo-1/.claude/CLAUDE.md
|
||||
|
||||
```markdown
|
||||
# Repo 1
|
||||
|
||||
Frontend React application.
|
||||
|
||||
## Repo-Specific
|
||||
- React 18 + TypeScript
|
||||
- Tailwind for styling
|
||||
- Jest + RTL for testing
|
||||
|
||||
## Tech Stack
|
||||
@docs/tech-stack.md
|
||||
|
||||
All organization standards apply (see ~/.claude/CLAUDE.md)
|
||||
```
|
||||
|
||||
### Benefits
|
||||
|
||||
- **DRY**: Don't repeat org standards in each repo
|
||||
- **Consistency**: Same standards everywhere
|
||||
- **Easy updates**: Change once, applies to all
|
||||
- **Repo specifics**: Each repo adds its unique context
|
||||
|
||||
---
|
||||
|
||||
## Workflow 7: Gradual Migration
|
||||
|
||||
### Goal
|
||||
Migrate existing documentation to CLAUDE.md progressively.
|
||||
|
||||
### Phase 1: Start Small (Week 1)
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md (50 lines)
|
||||
|
||||
## Common Commands
|
||||
```bash
|
||||
npm run dev
|
||||
npm test
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Key Conventions
|
||||
- 2-space indentation
|
||||
- ESLint + Prettier
|
||||
```
|
||||
|
||||
### Phase 2: Add Core Info (Week 2-3)
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md (100 lines)
|
||||
|
||||
[Previous content]
|
||||
|
||||
## Tech Stack
|
||||
- Backend: Node.js + Express
|
||||
- Frontend: React + TypeScript
|
||||
- Database: PostgreSQL
|
||||
|
||||
## Architecture
|
||||
@docs/architecture.md
|
||||
|
||||
## IMPORTANT Rules
|
||||
- Tests required before merge
|
||||
- No commits to main
|
||||
```
|
||||
|
||||
### Phase 3: Import Existing Docs (Week 4)
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md (150 lines)
|
||||
|
||||
[Previous content]
|
||||
|
||||
## Detailed Documentation
|
||||
- Architecture: @docs/architecture.md
|
||||
- API Reference: @docs/api.md
|
||||
- Style Guide: @docs/style-guide.md
|
||||
- Testing: @docs/testing-guide.md
|
||||
```
|
||||
|
||||
### Phase 4: Optimize (Ongoing)
|
||||
|
||||
- Move inline content to imports
|
||||
- Compress verbose sections
|
||||
- Test with team
|
||||
- Gather feedback
|
||||
- Iterate
|
||||
|
||||
### Benefits
|
||||
|
||||
- **Low risk**: Start small, grow gradually
|
||||
- **Learn as you go**: Discover what works
|
||||
- **Team adoption**: Give team time to adjust
|
||||
- **Continuous improvement**: Iterate based on usage
|
||||
|
||||
---
|
||||
|
||||
## Workflow 8: Cross-Team Collaboration
|
||||
|
||||
### Goal
|
||||
Enable multiple teams to work on shared codebase with team-specific context.
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
monorepo/
|
||||
├── .claude/
|
||||
│ └── CLAUDE.md # Shared standards
|
||||
├── packages/
|
||||
│ ├── frontend/
|
||||
│ │ └── .claude/
|
||||
│ │ └── CLAUDE.md # Frontend team context
|
||||
│ └── backend/
|
||||
│ └── .claude/
|
||||
│ └── CLAUDE.md # Backend team context
|
||||
```
|
||||
|
||||
### Root .claude/CLAUDE.md (Shared)
|
||||
|
||||
```markdown
|
||||
# Monorepo Standards
|
||||
|
||||
## Shared Across All Teams
|
||||
- pnpm workspaces
|
||||
- Conventional commits
|
||||
- Test coverage > 80%
|
||||
- Code review required
|
||||
|
||||
## Team-Specific Context
|
||||
- Frontend: packages/frontend/CLAUDE.md
|
||||
- Backend: packages/backend/CLAUDE.md
|
||||
|
||||
When in a package directory, team-specific context loads automatically.
|
||||
```
|
||||
|
||||
### packages/frontend/.claude/CLAUDE.md
|
||||
|
||||
```markdown
|
||||
# Frontend Team Context
|
||||
|
||||
**Team**: Frontend (React specialists)
|
||||
|
||||
## Our Stack
|
||||
- React 18 + TypeScript
|
||||
- Tailwind + shadcn/ui
|
||||
- Zustand for state
|
||||
- React Query for data
|
||||
|
||||
## Our Conventions
|
||||
- Atomic design pattern
|
||||
- Mobile-first responsive
|
||||
- Dark mode support required
|
||||
|
||||
## Our PR Process
|
||||
- 2 frontend developers must approve
|
||||
- Accessibility check required
|
||||
- Browser testing checklist
|
||||
|
||||
## Contact
|
||||
- Lead: @alice
|
||||
- Questions: #frontend-team
|
||||
```
|
||||
|
||||
### packages/backend/.claude/CLAUDE.md
|
||||
|
||||
```markdown
|
||||
# Backend Team Context
|
||||
|
||||
**Team**: Backend (API specialists)
|
||||
|
||||
## Our Stack
|
||||
- Node.js + Express + TypeScript
|
||||
- PostgreSQL + Prisma
|
||||
- Redis caching
|
||||
- JWT authentication
|
||||
|
||||
## Our Conventions
|
||||
- RESTful API design
|
||||
- OpenAPI documentation
|
||||
- Rate limiting all endpoints
|
||||
|
||||
## Our PR Process
|
||||
- 2 backend developers must approve
|
||||
- Security review for auth changes
|
||||
- Load testing for perf-critical paths
|
||||
|
||||
## Contact
|
||||
- Lead: @bob
|
||||
- Questions: #backend-team
|
||||
```
|
||||
|
||||
### Benefits
|
||||
|
||||
- **Team autonomy**: Each team defines their standards
|
||||
- **Shared foundations**: Common org-wide rules
|
||||
- **Context switching**: Right context automatically
|
||||
- **Cross-team awareness**: See other team's standards
|
||||
|
||||
---
|
||||
|
||||
## Summary: Team Success Patterns
|
||||
|
||||
1. **Start Simple**: Begin with 50-100 lines, grow organically
|
||||
2. **Version Control**: Track changes, review updates
|
||||
3. **Team Buy-In**: Get feedback, iterate together
|
||||
4. **Clear Ownership**: Assign responsibility for updates
|
||||
5. **Regular Reviews**: Monthly check for outdated content
|
||||
6. **Measure Impact**: Track onboarding time, review consistency
|
||||
7. **Document Decisions**: Use ADRs for architecture
|
||||
8. **Progressive Disclosure**: Core in CLAUDE.md, details in imports
|
||||
9. **Feature Contexts**: Use subfolders for feature-specific guidance
|
||||
10. **Cross-Repo Standards**: Share common standards across projects
|
||||
|
||||
**Goal**: Make CLAUDE.md the single source of truth for team development practices.
|
||||
Reference in New Issue
Block a user