d17564a9f2
Created a professional SVG logo for the project featuring: - Modern gradient design with code brackets symbol - Book/guide icon representing learning and documentation - "Claude How To" branding with subtitle - Decorative elements and professional color scheme Added logo to all major documentation files: - README.md - INDEX.md - QUICK_REFERENCE.md - claude_concepts_guide.md The logo provides consistent branding across the project and improves visual appeal on GitHub and other markdown viewers. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
3041 lines
76 KiB
Markdown
3041 lines
76 KiB
Markdown
|
|
|
|
# Complete Guide to Claude Concepts
|
|
|
|
A comprehensive reference guide covering Slash Commands, Subagents, Memory, MCP Protocol, and Agent Skills with tables, diagrams, and practical examples.
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
1. [Slash Commands](#slash-commands)
|
|
2. [Subagents](#subagents)
|
|
3. [Memory](#memory)
|
|
4. [MCP Protocol](#mcp-protocol)
|
|
5. [Agent Skills](#agent-skills)
|
|
6. [Plugins](#plugins)
|
|
7. [Hooks](#hooks)
|
|
8. [Checkpoints and Rewind](#checkpoints-and-rewind)
|
|
9. [Advanced Features](#advanced-features)
|
|
10. [Comparison & Integration](#comparison--integration)
|
|
|
|
---
|
|
|
|
## Slash Commands
|
|
|
|
### Overview
|
|
|
|
Slash commands are user-invoked shortcuts stored as Markdown files that Claude Code can execute. They enable teams to standardize frequently-used prompts and workflows.
|
|
|
|
### Architecture
|
|
|
|
```mermaid
|
|
graph TD
|
|
A["User Input: /command-name"] -->|Triggers| B["Search .claude/commands/"]
|
|
B -->|Finds| C["command-name.md"]
|
|
C -->|Loads| D["Markdown Content"]
|
|
D -->|Executes| E["Claude Processes Prompt"]
|
|
E -->|Returns| F["Result in Context"]
|
|
```
|
|
|
|
### File Structure
|
|
|
|
```mermaid
|
|
graph LR
|
|
A["Project Root"] -->|contains| B[".claude/commands/"]
|
|
B -->|contains| C["optimize.md"]
|
|
B -->|contains| D["test.md"]
|
|
B -->|contains| E["docs/"]
|
|
E -->|contains| F["generate-api-docs.md"]
|
|
E -->|contains| G["generate-readme.md"]
|
|
```
|
|
|
|
### Command Organization Table
|
|
|
|
| Location | Scope | Availability | Use Case | Git Tracked |
|
|
|----------|-------|--------------|----------|-------------|
|
|
| `.claude/commands/` | Project-specific | Team members | Team workflows, shared standards | ✅ Yes |
|
|
| `~/.claude/commands/` | Personal | Individual user | Personal shortcuts across projects | ❌ No |
|
|
| Subdirectories | Namespaced | Based on parent | Organize by category | ✅ Yes |
|
|
|
|
### Features & Capabilities
|
|
|
|
| Feature | Example | Supported |
|
|
|---------|---------|-----------|
|
|
| Shell script execution | `bash scripts/deploy.sh` | ✅ Yes |
|
|
| File references | `@path/to/file.js` | ✅ Yes |
|
|
| Bash integration | `$(git log --oneline)` | ✅ Yes |
|
|
| Arguments | `/pr --verbose` | ✅ Yes |
|
|
| MCP commands | `/mcp__github__list_prs` | ✅ Yes |
|
|
|
|
### Practical Examples
|
|
|
|
#### Example 1: Code Optimization Command
|
|
|
|
**File:** `.claude/commands/optimize.md`
|
|
|
|
```markdown
|
|
---
|
|
name: Code Optimization
|
|
description: Analyze code for performance issues and suggest optimizations
|
|
tags: performance, analysis
|
|
---
|
|
|
|
# Code Optimization
|
|
|
|
Review the provided code for the following issues in order of priority:
|
|
|
|
1. **Performance bottlenecks** - identify O(n²) operations, inefficient loops
|
|
2. **Memory leaks** - find unreleased resources, circular references
|
|
3. **Algorithm improvements** - suggest better algorithms or data structures
|
|
4. **Caching opportunities** - identify repeated computations
|
|
5. **Concurrency issues** - find race conditions or threading problems
|
|
|
|
Format your response with:
|
|
- Issue severity (Critical/High/Medium/Low)
|
|
- Location in code
|
|
- Explanation
|
|
- Recommended fix with code example
|
|
```
|
|
|
|
**Usage:**
|
|
```bash
|
|
# User types in Claude Code
|
|
/optimize
|
|
|
|
# Claude loads the prompt and waits for code input
|
|
```
|
|
|
|
#### Example 2: Pull Request Helper Command
|
|
|
|
**File:** `.claude/commands/pr.md`
|
|
|
|
```markdown
|
|
---
|
|
name: Prepare Pull Request
|
|
description: Clean up code, stage changes, and prepare a pull request
|
|
tags: git, workflow
|
|
---
|
|
|
|
# Pull Request Preparation Checklist
|
|
|
|
Before creating a PR, execute these steps:
|
|
|
|
1. Run linting: `prettier --write .`
|
|
2. Run tests: `npm test`
|
|
3. Review git diff: `git diff HEAD`
|
|
4. Stage changes: `git add .`
|
|
5. Create commit message following conventional commits:
|
|
- `fix:` for bug fixes
|
|
- `feat:` for new features
|
|
- `docs:` for documentation
|
|
- `refactor:` for code restructuring
|
|
- `test:` for test additions
|
|
- `chore:` for maintenance
|
|
|
|
6. Generate PR summary including:
|
|
- What changed
|
|
- Why it changed
|
|
- Testing performed
|
|
- Potential impacts
|
|
```
|
|
|
|
**Usage:**
|
|
```bash
|
|
/pr
|
|
|
|
# Claude runs through checklist and prepares the PR
|
|
```
|
|
|
|
#### Example 3: Hierarchical Documentation Generator
|
|
|
|
**File:** `.claude/commands/docs/generate-api-docs.md`
|
|
|
|
```markdown
|
|
---
|
|
name: Generate API Documentation
|
|
description: Create comprehensive API documentation from source code
|
|
tags: documentation, api
|
|
---
|
|
|
|
# API Documentation Generator
|
|
|
|
Generate API documentation by:
|
|
|
|
1. Scanning all files in `/src/api/`
|
|
2. Extracting function signatures and JSDoc comments
|
|
3. Organizing by endpoint/module
|
|
4. Creating markdown with examples
|
|
5. Including request/response schemas
|
|
6. Adding error documentation
|
|
|
|
Output format:
|
|
- Markdown file in `/docs/api.md`
|
|
- Include curl examples for all endpoints
|
|
- Add TypeScript types
|
|
```
|
|
|
|
### Command Lifecycle Diagram
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant User
|
|
participant Claude as Claude Code
|
|
participant FS as File System
|
|
participant CLI as Shell/Bash
|
|
|
|
User->>Claude: Types /optimize
|
|
Claude->>FS: Searches .claude/commands/
|
|
FS-->>Claude: Returns optimize.md
|
|
Claude->>Claude: Loads Markdown content
|
|
Claude->>User: Displays prompt context
|
|
User->>Claude: Provides code to analyze
|
|
Claude->>CLI: (May execute scripts)
|
|
CLI-->>Claude: Results
|
|
Claude->>User: Returns analysis
|
|
```
|
|
|
|
### Best Practices
|
|
|
|
| ✅ Do | ❌ Don't |
|
|
|------|---------|
|
|
| Use clear, action-oriented names | Create commands for one-time tasks |
|
|
| Document trigger words in description | Build complex logic in commands |
|
|
| Keep commands focused on single task | Create redundant commands |
|
|
| Version control project commands | Hardcode sensitive information |
|
|
| Organize in subdirectories | Create long lists of commands |
|
|
| Use simple, readable prompts | Use abbreviated or cryptic wording |
|
|
|
|
---
|
|
|
|
## Subagents
|
|
|
|
### Overview
|
|
|
|
Subagents are specialized AI assistants with isolated context windows and customized system prompts. They enable delegated task execution while maintaining clean separation of concerns.
|
|
|
|
### Architecture Diagram
|
|
|
|
```mermaid
|
|
graph TB
|
|
User["👤 User"]
|
|
Main["🎯 Main Agent<br/>(Coordinator)"]
|
|
Reviewer["🔍 Code Reviewer<br/>Subagent"]
|
|
Tester["✅ Test Engineer<br/>Subagent"]
|
|
Docs["📝 Documentation<br/>Subagent"]
|
|
|
|
User -->|asks| Main
|
|
Main -->|delegates| Reviewer
|
|
Main -->|delegates| Tester
|
|
Main -->|delegates| Docs
|
|
Reviewer -->|returns result| Main
|
|
Tester -->|returns result| Main
|
|
Docs -->|returns result| Main
|
|
Main -->|synthesizes| User
|
|
```
|
|
|
|
### Subagent Lifecycle
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant User
|
|
participant MainAgent as Main Agent
|
|
participant CodeReviewer as Code Reviewer<br/>Subagent
|
|
participant Context as Separate<br/>Context Window
|
|
|
|
User->>MainAgent: "Build new auth feature"
|
|
MainAgent->>MainAgent: Analyze task
|
|
MainAgent->>CodeReviewer: "Review this code"
|
|
CodeReviewer->>Context: Initialize clean context
|
|
Context->>CodeReviewer: Load reviewer instructions
|
|
CodeReviewer->>CodeReviewer: Perform review
|
|
CodeReviewer-->>MainAgent: Return findings
|
|
MainAgent->>MainAgent: Incorporate results
|
|
MainAgent-->>User: Provide synthesis
|
|
```
|
|
|
|
### Subagent Configuration Table
|
|
|
|
| Configuration | Type | Purpose | Example |
|
|
|---------------|------|---------|---------|
|
|
| `name` | String | Agent identifier | `code-reviewer` |
|
|
| `description` | String | Purpose & trigger terms | `Comprehensive code quality analysis` |
|
|
| `tools` | List/String | Allowed capabilities | `read, grep, diff, lint_runner` |
|
|
| `system_prompt` | Markdown | Behavioral instructions | Custom guidelines |
|
|
|
|
### Tool Access Hierarchy
|
|
|
|
```mermaid
|
|
graph TD
|
|
A["Subagent Configuration"] -->|Option 1| B["Inherit All Tools<br/>from Main Thread"]
|
|
A -->|Option 2| C["Specify Individual Tools"]
|
|
B -->|Includes| B1["File Operations"]
|
|
B -->|Includes| B2["Shell Commands"]
|
|
B -->|Includes| B3["MCP Tools"]
|
|
C -->|Explicit List| C1["read, grep, diff"]
|
|
C -->|Explicit List| C2["Bash(npm:*), Bash(test:*)"]
|
|
```
|
|
|
|
### Practical Examples
|
|
|
|
#### Example 1: Complete Subagent Setup
|
|
|
|
**File:** `.claude/agents/code-reviewer.md`
|
|
|
|
```yaml
|
|
---
|
|
name: code-reviewer
|
|
description: Comprehensive code quality and maintainability analysis
|
|
tools: read, grep, diff, lint_runner
|
|
---
|
|
|
|
# Code Reviewer Agent
|
|
|
|
You are an expert code reviewer specializing in:
|
|
- Performance optimization
|
|
- Security vulnerabilities
|
|
- Code maintainability
|
|
- Testing coverage
|
|
- Design patterns
|
|
|
|
## Review Priorities (in order)
|
|
|
|
1. **Security Issues** - Authentication, authorization, data exposure
|
|
2. **Performance Problems** - O(n²) operations, memory leaks, inefficient queries
|
|
3. **Code Quality** - Readability, naming, documentation
|
|
4. **Test Coverage** - Missing tests, edge cases
|
|
5. **Design Patterns** - SOLID principles, architecture
|
|
|
|
## Review Output Format
|
|
|
|
For each issue:
|
|
- **Severity**: Critical / High / Medium / Low
|
|
- **Category**: Security / Performance / Quality / Testing / Design
|
|
- **Location**: File path and line number
|
|
- **Issue Description**: What's wrong and why
|
|
- **Suggested Fix**: Code example
|
|
- **Impact**: How this affects the system
|
|
|
|
## Example Review
|
|
|
|
### Issue: N+1 Query Problem
|
|
- **Severity**: High
|
|
- **Category**: Performance
|
|
- **Location**: src/user-service.ts:45
|
|
- **Issue**: Loop executes database query in each iteration
|
|
- **Fix**: Use JOIN or batch query
|
|
```
|
|
|
|
**File:** `.claude/agents/test-engineer.md`
|
|
|
|
```yaml
|
|
---
|
|
name: test-engineer
|
|
description: Test strategy, coverage analysis, and automated testing
|
|
tools: read, write, bash, grep
|
|
---
|
|
|
|
# Test Engineer Agent
|
|
|
|
You are expert at:
|
|
- Writing comprehensive test suites
|
|
- Ensuring high code coverage (>80%)
|
|
- Testing edge cases and error scenarios
|
|
- Performance benchmarking
|
|
- Integration testing
|
|
|
|
## Testing Strategy
|
|
|
|
1. **Unit Tests** - Individual functions/methods
|
|
2. **Integration Tests** - Component interactions
|
|
3. **End-to-End Tests** - Complete workflows
|
|
4. **Edge Cases** - Boundary conditions
|
|
5. **Error Scenarios** - Failure handling
|
|
|
|
## Test Output Requirements
|
|
|
|
- Use Jest for JavaScript/TypeScript
|
|
- Include setup/teardown for each test
|
|
- Mock external dependencies
|
|
- Document test purpose
|
|
- Include performance assertions when relevant
|
|
|
|
## Coverage Requirements
|
|
|
|
- Minimum 80% code coverage
|
|
- 100% for critical paths
|
|
- Report missing coverage areas
|
|
```
|
|
|
|
**File:** `.claude/agents/documentation-writer.md`
|
|
|
|
```yaml
|
|
---
|
|
name: documentation-writer
|
|
description: Technical documentation, API docs, and user guides
|
|
tools: read, write, grep
|
|
---
|
|
|
|
# Documentation Writer Agent
|
|
|
|
You create:
|
|
- API documentation with examples
|
|
- User guides and tutorials
|
|
- Architecture documentation
|
|
- Changelog entries
|
|
- Code comment improvements
|
|
|
|
## Documentation Standards
|
|
|
|
1. **Clarity** - Use simple, clear language
|
|
2. **Examples** - Include practical code examples
|
|
3. **Completeness** - Cover all parameters and returns
|
|
4. **Structure** - Use consistent formatting
|
|
5. **Accuracy** - Verify against actual code
|
|
|
|
## Documentation Sections
|
|
|
|
### For APIs
|
|
- Description
|
|
- Parameters (with types)
|
|
- Returns (with types)
|
|
- Throws (possible errors)
|
|
- Examples (curl, JavaScript, Python)
|
|
- Related endpoints
|
|
|
|
### For Features
|
|
- Overview
|
|
- Prerequisites
|
|
- Step-by-step instructions
|
|
- Expected outcomes
|
|
- Troubleshooting
|
|
- Related topics
|
|
```
|
|
|
|
#### Example 2: Subagent Delegation in Action
|
|
|
|
```markdown
|
|
# Scenario: Building a Payment Feature
|
|
|
|
## User Request
|
|
"Build a secure payment processing feature that integrates with Stripe"
|
|
|
|
## Main Agent Flow
|
|
|
|
1. **Planning Phase**
|
|
- Understands requirements
|
|
- Determines tasks needed
|
|
- Plans architecture
|
|
|
|
2. **Delegates to Code Reviewer Subagent**
|
|
- Task: "Review the payment processing implementation for security"
|
|
- Context: Auth, API keys, token handling
|
|
- Reviews for: SQL injection, key exposure, HTTPS enforcement
|
|
|
|
3. **Delegates to Test Engineer Subagent**
|
|
- Task: "Create comprehensive tests for payment flows"
|
|
- Context: Success scenarios, failures, edge cases
|
|
- Creates tests for: Valid payments, declined cards, network failures, webhooks
|
|
|
|
4. **Delegates to Documentation Writer Subagent**
|
|
- Task: "Document the payment API endpoints"
|
|
- Context: Request/response schemas
|
|
- Produces: API docs with curl examples, error codes
|
|
|
|
5. **Synthesis**
|
|
- Main agent collects all outputs
|
|
- Integrates findings
|
|
- Returns complete solution to user
|
|
```
|
|
|
|
#### Example 3: Tool Permission Scoping
|
|
|
|
**Restrictive Setup - Limited to Specific Commands**
|
|
|
|
```yaml
|
|
---
|
|
name: secure-reviewer
|
|
description: Security-focused code review with minimal permissions
|
|
tools: read, grep
|
|
---
|
|
|
|
# Secure Code Reviewer
|
|
|
|
Reviews code for security vulnerabilities only.
|
|
|
|
This agent:
|
|
- ✅ Reads files to analyze
|
|
- ✅ Searches for patterns
|
|
- ❌ Cannot execute code
|
|
- ❌ Cannot modify files
|
|
- ❌ Cannot run tests
|
|
|
|
This ensures the reviewer doesn't accidentally break anything.
|
|
```
|
|
|
|
**Extended Setup - All Tools for Implementation**
|
|
|
|
```yaml
|
|
---
|
|
name: implementation-agent
|
|
description: Full implementation capabilities for feature development
|
|
tools: read, write, bash, grep, edit, glob
|
|
---
|
|
|
|
# Implementation Agent
|
|
|
|
Builds features from specifications.
|
|
|
|
This agent:
|
|
- ✅ Reads specifications
|
|
- ✅ Writes new code files
|
|
- ✅ Runs build commands
|
|
- ✅ Searches codebase
|
|
- ✅ Edits existing files
|
|
- ✅ Finds files matching patterns
|
|
|
|
Full capabilities for independent feature development.
|
|
```
|
|
|
|
### Subagent Context Management
|
|
|
|
```mermaid
|
|
graph TB
|
|
A["Main Agent Context<br/>50,000 tokens"]
|
|
B["Subagent 1 Context<br/>20,000 tokens"]
|
|
C["Subagent 2 Context<br/>20,000 tokens"]
|
|
D["Subagent 3 Context<br/>20,000 tokens"]
|
|
|
|
A -->|Clean slate| B
|
|
A -->|Clean slate| C
|
|
A -->|Clean slate| D
|
|
|
|
B -->|Results only| A
|
|
C -->|Results only| A
|
|
D -->|Results only| A
|
|
|
|
style A fill:#e1f5ff
|
|
style B fill:#fff9c4
|
|
style C fill:#fff9c4
|
|
style D fill:#fff9c4
|
|
```
|
|
|
|
### When to Use Subagents
|
|
|
|
| Scenario | Use Subagent | Why |
|
|
|----------|--------------|-----|
|
|
| Complex feature with many steps | ✅ Yes | Separate concerns, prevent context pollution |
|
|
| Quick code review | ❌ No | Not necessary overhead |
|
|
| Parallel task execution | ✅ Yes | Each subagent has own context |
|
|
| Specialized expertise needed | ✅ Yes | Custom system prompts |
|
|
| Long-running analysis | ✅ Yes | Prevents main context exhaustion |
|
|
| Single task | ❌ No | Adds latency unnecessarily |
|
|
|
|
---
|
|
|
|
## Memory
|
|
|
|
### Overview
|
|
|
|
Memory enables Claude to retain context across sessions and conversations. It exists in two forms: automatic synthesis in claude.ai, and filesystem-based CLAUDE.md in Claude Code.
|
|
|
|
### Memory Architecture
|
|
|
|
```mermaid
|
|
graph TB
|
|
A["Claude Session"]
|
|
B["User Input"]
|
|
C["Memory System"]
|
|
D["Memory Storage"]
|
|
|
|
B -->|User provides info| C
|
|
C -->|Synthesizes every 24h| D
|
|
D -->|Loads automatically| A
|
|
A -->|Uses context| C
|
|
```
|
|
|
|
### Memory Hierarchy in Claude Code
|
|
|
|
```mermaid
|
|
graph TD
|
|
A["Project Root"] -->|searches up| B["CLAUDE.md"]
|
|
B -->|highest priority| B1["Global instructions"]
|
|
A -->|searches down| C["Subdirectory CLAUDE.md"]
|
|
C -->|specific overrides| C1["Directory-specific rules"]
|
|
H["User Home"] -->|fallback| D["~/.claude/CLAUDE.md"]
|
|
D -->|personal preferences| D1["Personal settings"]
|
|
|
|
B1 -->|imports| E["@docs/architecture.md"]
|
|
E -->|imports| F["@docs/api-standards.md"]
|
|
```
|
|
|
|
### Memory Locations Table
|
|
|
|
| Location | Scope | Priority | Shared | Access | Best For |
|
|
|----------|-------|----------|--------|--------|----------|
|
|
| `./CLAUDE.md` | Project | High | Team | Git | Team standards, shared architecture |
|
|
| `./.claude/CLAUDE.md` | Project | High | Team | Git | Alternative project location |
|
|
| `./subdir/CLAUDE.md` | Directory | Medium | Team | Git | Directory-specific rules |
|
|
| `~/.claude/CLAUDE.md` | Personal | Low | Individual | Filesystem | Personal preferences |
|
|
| `~/.claude/my-project.md` | Personal | Low | Individual | Import | Project-specific personal notes |
|
|
|
|
### Memory Update Lifecycle
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant User
|
|
participant Claude as Claude Code
|
|
participant Editor as File System
|
|
participant Memory as CLAUDE.md
|
|
|
|
User->>Claude: "Remember: use async/await"
|
|
Claude->>User: "Which memory file?"
|
|
User->>Claude: "Project memory"
|
|
Claude->>Editor: Open ~/.claude/settings.json
|
|
Claude->>Memory: Write to ./CLAUDE.md
|
|
Memory-->>Claude: File saved
|
|
Claude->>Claude: Load updated memory
|
|
Claude-->>User: "Memory saved!"
|
|
```
|
|
|
|
### Practical Examples
|
|
|
|
#### Example 1: Project Memory Structure
|
|
|
|
**File:** `./CLAUDE.md`
|
|
|
|
```markdown
|
|
# Project Configuration
|
|
|
|
## Project Overview
|
|
- **Name**: E-commerce Platform
|
|
- **Tech Stack**: Node.js, PostgreSQL, React 18, Docker
|
|
- **Team Size**: 5 developers
|
|
- **Deadline**: Q4 2025
|
|
|
|
## Architecture
|
|
@docs/architecture.md
|
|
@docs/api-standards.md
|
|
@docs/database-schema.md
|
|
|
|
## Development Standards
|
|
|
|
### Code Style
|
|
- Use Prettier for formatting
|
|
- Use ESLint with airbnb config
|
|
- Maximum line length: 100 characters
|
|
- Use 2-space indentation
|
|
|
|
### Naming Conventions
|
|
- **Files**: kebab-case (user-controller.js)
|
|
- **Classes**: PascalCase (UserService)
|
|
- **Functions/Variables**: camelCase (getUserById)
|
|
- **Constants**: UPPER_SNAKE_CASE (API_BASE_URL)
|
|
- **Database Tables**: snake_case (user_accounts)
|
|
|
|
### Git Workflow
|
|
- Branch names: `feature/description` or `fix/description`
|
|
- Commit messages: Follow conventional commits
|
|
- PR required before merge
|
|
- All CI/CD checks must pass
|
|
- Minimum 1 approval required
|
|
|
|
### Testing Requirements
|
|
- Minimum 80% code coverage
|
|
- All critical paths must have tests
|
|
- Use Jest for unit tests
|
|
- Use Cypress for E2E tests
|
|
- Test filenames: `*.test.ts` or `*.spec.ts`
|
|
|
|
### API Standards
|
|
- RESTful endpoints only
|
|
- JSON request/response
|
|
- Use HTTP status codes correctly
|
|
- Version API endpoints: `/api/v1/`
|
|
- Document all endpoints with examples
|
|
|
|
### Database
|
|
- Use migrations for schema changes
|
|
- Never hardcode credentials
|
|
- Use connection pooling
|
|
- Enable query logging in development
|
|
- Regular backups required
|
|
|
|
### Deployment
|
|
- Docker-based deployment
|
|
- Kubernetes orchestration
|
|
- Blue-green deployment strategy
|
|
- Automatic rollback on failure
|
|
- Database migrations run before deploy
|
|
|
|
## Common Commands
|
|
|
|
| Command | Purpose |
|
|
|---------|---------|
|
|
| `npm run dev` | Start development server |
|
|
| `npm test` | Run test suite |
|
|
| `npm run lint` | Check code style |
|
|
| `npm run build` | Build for production |
|
|
| `npm run migrate` | Run database migrations |
|
|
|
|
## Team Contacts
|
|
- Tech Lead: Sarah Chen (@sarah.chen)
|
|
- Product Manager: Mike Johnson (@mike.j)
|
|
- DevOps: Alex Kim (@alex.k)
|
|
|
|
## Known Issues & Workarounds
|
|
- PostgreSQL connection pooling limited to 20 during peak hours
|
|
- Workaround: Implement query queuing
|
|
- Safari 14 compatibility issues with async generators
|
|
- Workaround: Use Babel transpiler
|
|
|
|
## Related Projects
|
|
- Analytics Dashboard: `/projects/analytics`
|
|
- Mobile App: `/projects/mobile`
|
|
- Admin Panel: `/projects/admin`
|
|
```
|
|
|
|
#### Example 2: Directory-Specific Memory
|
|
|
|
**File:** `./src/api/CLAUDE.md`
|
|
|
|
```markdown
|
|
# API Module Standards
|
|
|
|
This file overrides root CLAUDE.md for everything in /src/api/
|
|
|
|
## API-Specific Standards
|
|
|
|
### Request Validation
|
|
- Use Zod for schema validation
|
|
- Always validate input
|
|
- Return 400 with validation errors
|
|
- Include field-level error details
|
|
|
|
### Authentication
|
|
- All endpoints require JWT token
|
|
- Token in Authorization header
|
|
- Token expires after 24 hours
|
|
- Implement refresh token mechanism
|
|
|
|
### Response Format
|
|
|
|
All responses must follow this structure:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": { /* actual data */ },
|
|
"timestamp": "2025-11-06T10:30:00Z",
|
|
"version": "1.0"
|
|
}
|
|
```
|
|
|
|
Error responses:
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": {
|
|
"code": "VALIDATION_ERROR",
|
|
"message": "User message",
|
|
"details": { /* field errors */ }
|
|
},
|
|
"timestamp": "2025-11-06T10:30:00Z"
|
|
}
|
|
```
|
|
|
|
### Pagination
|
|
- Use cursor-based pagination (not offset)
|
|
- Include `hasMore` boolean
|
|
- Limit max page size to 100
|
|
- Default page size: 20
|
|
|
|
### Rate Limiting
|
|
- 1000 requests per hour for authenticated users
|
|
- 100 requests per hour for public endpoints
|
|
- Return 429 when exceeded
|
|
- Include retry-after header
|
|
|
|
### Caching
|
|
- Use Redis for session caching
|
|
- Cache duration: 5 minutes default
|
|
- Invalidate on write operations
|
|
- Tag cache keys with resource type
|
|
```
|
|
|
|
#### Example 3: Personal Memory
|
|
|
|
**File:** `~/.claude/CLAUDE.md`
|
|
|
|
```markdown
|
|
# My Development Preferences
|
|
|
|
## About Me
|
|
- **Experience Level**: 8 years full-stack development
|
|
- **Preferred Languages**: TypeScript, Python
|
|
- **Communication Style**: Direct, with examples
|
|
- **Learning Style**: Visual diagrams with code
|
|
|
|
## Code Preferences
|
|
|
|
### Error Handling
|
|
I prefer explicit error handling with try-catch blocks and meaningful error messages.
|
|
Avoid generic errors. Always log errors for debugging.
|
|
|
|
### Comments
|
|
Use comments for WHY, not WHAT. Code should be self-documenting.
|
|
Comments should explain business logic or non-obvious decisions.
|
|
|
|
### Testing
|
|
I prefer TDD (test-driven development).
|
|
Write tests first, then implementation.
|
|
Focus on behavior, not implementation details.
|
|
|
|
### Architecture
|
|
I prefer modular, loosely-coupled design.
|
|
Use dependency injection for testability.
|
|
Separate concerns (Controllers, Services, Repositories).
|
|
|
|
## Debugging Preferences
|
|
- Use console.log with prefix: `[DEBUG]`
|
|
- Include context: function name, relevant variables
|
|
- Use stack traces when available
|
|
- Always include timestamps in logs
|
|
|
|
## Communication
|
|
- Explain complex concepts with diagrams
|
|
- Show concrete examples before explaining theory
|
|
- Include before/after code snippets
|
|
- Summarize key points at the end
|
|
|
|
## Project Organization
|
|
I organize my projects as:
|
|
```
|
|
project/
|
|
├── src/
|
|
│ ├── api/
|
|
│ ├── services/
|
|
│ ├── models/
|
|
│ └── utils/
|
|
├── tests/
|
|
├── docs/
|
|
└── docker/
|
|
```
|
|
|
|
## Tooling
|
|
- **IDE**: VS Code with vim keybindings
|
|
- **Terminal**: Zsh with Oh-My-Zsh
|
|
- **Format**: Prettier (100 char line length)
|
|
- **Linter**: ESLint with airbnb config
|
|
- **Test Framework**: Jest with React Testing Library
|
|
```
|
|
|
|
#### Example 4: Memory Update During Session
|
|
|
|
**Session Interaction:**
|
|
|
|
```markdown
|
|
User: Remember that I prefer using React hooks instead of class components
|
|
for all new components.
|
|
|
|
Claude: I'm adding that to your memory. Which memory file should this go in?
|
|
1. Project memory (./CLAUDE.md)
|
|
2. Personal memory (~/.claude/CLAUDE.md)
|
|
|
|
User: Project memory
|
|
|
|
Claude: ✅ Memory saved!
|
|
|
|
Added to ./CLAUDE.md:
|
|
---
|
|
|
|
### Component Development
|
|
- Use functional components with React Hooks
|
|
- Prefer hooks over class components
|
|
- Custom hooks for reusable logic
|
|
- Use useCallback for event handlers
|
|
- Use useMemo for expensive computations
|
|
```
|
|
|
|
### Memory in Claude Web/Desktop
|
|
|
|
#### Memory Synthesis Timeline
|
|
|
|
```mermaid
|
|
graph LR
|
|
A["Day 1: User<br/>Conversations"] -->|24 hours| B["Day 2: Memory<br/>Synthesis"]
|
|
B -->|Automatic| C["Memory Updated<br/>Summarized"]
|
|
C -->|Loaded in| D["Day 2-N:<br/>New Conversations"]
|
|
D -->|Add to| E["Memory"]
|
|
E -->|24 hours later| F["Memory Refreshed"]
|
|
```
|
|
|
|
**Example Memory Summary:**
|
|
|
|
```markdown
|
|
## Claude's Memory of User
|
|
|
|
### Professional Background
|
|
- Senior full-stack developer with 8 years experience
|
|
- Focus on TypeScript/Node.js backends and React frontends
|
|
- Active open source contributor
|
|
- Interested in AI and machine learning
|
|
|
|
### Project Context
|
|
- Currently building e-commerce platform
|
|
- Tech stack: Node.js, PostgreSQL, React 18, Docker
|
|
- Working with team of 5 developers
|
|
- Using CI/CD and blue-green deployments
|
|
|
|
### Communication Preferences
|
|
- Prefers direct, concise explanations
|
|
- Likes visual diagrams and examples
|
|
- Appreciates code snippets
|
|
- Explains business logic in comments
|
|
|
|
### Current Goals
|
|
- Improve API performance
|
|
- Increase test coverage to 90%
|
|
- Implement caching strategy
|
|
- Document architecture
|
|
```
|
|
|
|
### Memory Features Comparison
|
|
|
|
| Feature | Claude Web/Desktop | Claude Code (CLAUDE.md) |
|
|
|---------|-------------------|------------------------|
|
|
| Auto-synthesis | ✅ Every 24h | ❌ Manual |
|
|
| Cross-project | ✅ Shared | ❌ Project-specific |
|
|
| Team access | ✅ Shared projects | ✅ Git-tracked |
|
|
| Searchable | ✅ Built-in | ✅ Through `/memory` |
|
|
| Editable | ✅ In-chat | ✅ Direct file edit |
|
|
| Import/Export | ✅ Yes | ✅ Copy/paste |
|
|
| Persistent | ✅ 24h+ | ✅ Indefinite |
|
|
|
|
---
|
|
|
|
## MCP Protocol
|
|
|
|
### Overview
|
|
|
|
MCP (Model Context Protocol) is a standardized way for Claude to access external tools, APIs, and real-time data sources. Unlike Memory, MCP provides live access to changing data.
|
|
|
|
### MCP Architecture
|
|
|
|
```mermaid
|
|
graph TB
|
|
A["Claude"]
|
|
B["MCP Server"]
|
|
C["External Service"]
|
|
|
|
A -->|Request: list_issues| B
|
|
B -->|Query| C
|
|
C -->|Data| B
|
|
B -->|Response| A
|
|
|
|
A -->|Request: create_issue| B
|
|
B -->|Action| C
|
|
C -->|Result| B
|
|
B -->|Response| A
|
|
```
|
|
|
|
### MCP Ecosystem
|
|
|
|
```mermaid
|
|
graph TB
|
|
A["Claude"] -->|MCP| B["Filesystem<br/>MCP Server"]
|
|
A -->|MCP| C["GitHub<br/>MCP Server"]
|
|
A -->|MCP| D["Database<br/>MCP Server"]
|
|
A -->|MCP| E["Slack<br/>MCP Server"]
|
|
A -->|MCP| F["Google Docs<br/>MCP Server"]
|
|
|
|
B -->|File I/O| G["Local Files"]
|
|
C -->|API| H["GitHub Repos"]
|
|
D -->|Query| I["PostgreSQL/MySQL"]
|
|
E -->|Messages| J["Slack Workspace"]
|
|
F -->|Docs| K["Google Drive"]
|
|
```
|
|
|
|
### MCP Setup Process
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant User
|
|
participant Claude as Claude Code
|
|
participant Config as Config File
|
|
participant Service as External Service
|
|
|
|
User->>Claude: Type /mcp
|
|
Claude->>Claude: List available MCP servers
|
|
Claude->>User: Show options
|
|
User->>Claude: Select GitHub MCP
|
|
Claude->>Config: Update configuration
|
|
Config->>Claude: Activate connection
|
|
Claude->>Service: Test connection
|
|
Service-->>Claude: Authentication successful
|
|
Claude->>User: ✅ MCP connected!
|
|
```
|
|
|
|
### Available MCP Servers Table
|
|
|
|
| MCP Server | Purpose | Common Tools | Auth | Real-time |
|
|
|------------|---------|--------------|------|-----------|
|
|
| **Filesystem** | File operations | read, write, delete | OS permissions | ✅ Yes |
|
|
| **GitHub** | Repository management | list_prs, create_issue, push | OAuth | ✅ Yes |
|
|
| **Slack** | Team communication | send_message, list_channels | Token | ✅ Yes |
|
|
| **Database** | SQL queries | query, insert, update | Credentials | ✅ Yes |
|
|
| **Google Docs** | Document access | read, write, share | OAuth | ✅ Yes |
|
|
| **Asana** | Project management | create_task, update_status | API Key | ✅ Yes |
|
|
| **Stripe** | Payment data | list_charges, create_invoice | API Key | ✅ Yes |
|
|
| **Memory** | Persistent memory | store, retrieve, delete | Local | ❌ No |
|
|
|
|
### Practical Examples
|
|
|
|
#### Example 1: GitHub MCP Configuration
|
|
|
|
**File:** `.claude/mcp.json`
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"github": {
|
|
"command": "npx",
|
|
"args": ["@modelcontextprotocol/server-github"],
|
|
"env": {
|
|
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Available GitHub MCP Tools:**
|
|
|
|
```markdown
|
|
# GitHub MCP Tools
|
|
|
|
## Pull Request Management
|
|
- `list_prs` - List all PRs in repository
|
|
- `get_pr` - Get PR details including diff
|
|
- `create_pr` - Create new PR
|
|
- `update_pr` - Update PR description/title
|
|
- `merge_pr` - Merge PR to main branch
|
|
- `review_pr` - Add review comments
|
|
|
|
Example request:
|
|
```
|
|
/mcp__github__get_pr 456
|
|
|
|
# Returns:
|
|
Title: Add dark mode support
|
|
Author: @alice
|
|
Description: Implements dark theme using CSS variables
|
|
Status: OPEN
|
|
Reviewers: @bob, @charlie
|
|
```
|
|
|
|
## Issue Management
|
|
- `list_issues` - List all issues
|
|
- `get_issue` - Get issue details
|
|
- `create_issue` - Create new issue
|
|
- `close_issue` - Close issue
|
|
- `add_comment` - Add comment to issue
|
|
|
|
## Repository Information
|
|
- `get_repo_info` - Repository details
|
|
- `list_files` - File tree structure
|
|
- `get_file_content` - Read file contents
|
|
- `search_code` - Search across codebase
|
|
|
|
## Commit Operations
|
|
- `list_commits` - Commit history
|
|
- `get_commit` - Specific commit details
|
|
- `create_commit` - Create new commit
|
|
```
|
|
|
|
#### Example 2: Database MCP Setup
|
|
|
|
**Configuration:**
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"database": {
|
|
"command": "npx",
|
|
"args": ["@modelcontextprotocol/server-database"],
|
|
"env": {
|
|
"DATABASE_URL": "postgresql://user:pass@localhost/mydb"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Example Usage:**
|
|
|
|
```markdown
|
|
User: Fetch all users with more than 10 orders
|
|
|
|
Claude: I'll query your database to find that information.
|
|
|
|
# Using MCP database tool:
|
|
SELECT u.*, COUNT(o.id) as order_count
|
|
FROM users u
|
|
LEFT JOIN orders o ON u.id = o.user_id
|
|
GROUP BY u.id
|
|
HAVING COUNT(o.id) > 10
|
|
ORDER BY order_count DESC;
|
|
|
|
# Results:
|
|
- Alice: 15 orders
|
|
- Bob: 12 orders
|
|
- Charlie: 11 orders
|
|
```
|
|
|
|
#### Example 3: Multi-MCP Workflow
|
|
|
|
**Scenario: Daily Report Generation**
|
|
|
|
```markdown
|
|
# Daily Report Workflow using Multiple MCPs
|
|
|
|
## Setup
|
|
1. GitHub MCP - fetch PR metrics
|
|
2. Database MCP - query sales data
|
|
3. Slack MCP - post report
|
|
4. Filesystem MCP - save report
|
|
|
|
## Workflow
|
|
|
|
### Step 1: Fetch GitHub Data
|
|
/mcp__github__list_prs completed:true last:7days
|
|
|
|
Output:
|
|
- Total PRs: 42
|
|
- Average merge time: 2.3 hours
|
|
- Review turnaround: 1.1 hours
|
|
|
|
### Step 2: Query Database
|
|
SELECT COUNT(*) as sales, SUM(amount) as revenue
|
|
FROM orders
|
|
WHERE created_at > NOW() - INTERVAL '1 day'
|
|
|
|
Output:
|
|
- Sales: 247
|
|
- Revenue: $12,450
|
|
|
|
### Step 3: Generate Report
|
|
Combine data into HTML report
|
|
|
|
### Step 4: Save to Filesystem
|
|
Write report.html to /reports/
|
|
|
|
### Step 5: Post to Slack
|
|
Send summary to #daily-reports channel
|
|
|
|
Final Output:
|
|
✅ Report generated and posted
|
|
📊 47 PRs merged this week
|
|
💰 $12,450 in daily sales
|
|
```
|
|
|
|
#### Example 4: Filesystem MCP Operations
|
|
|
|
**Configuration:**
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"filesystem": {
|
|
"command": "npx",
|
|
"args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Available Operations:**
|
|
|
|
| Operation | Command | Purpose |
|
|
|-----------|---------|---------|
|
|
| List files | `ls ~/projects` | Show directory contents |
|
|
| Read file | `cat src/main.ts` | Read file contents |
|
|
| Write file | `create docs/api.md` | Create new file |
|
|
| Edit file | `edit src/app.ts` | Modify file |
|
|
| Search | `grep "async function"` | Search in files |
|
|
| Delete | `rm old-file.js` | Delete file |
|
|
|
|
### MCP vs Memory: Decision Matrix
|
|
|
|
```mermaid
|
|
graph TD
|
|
A["Need external data?"]
|
|
A -->|No| B["Use Memory"]
|
|
A -->|Yes| C["Does it change frequently?"]
|
|
C -->|No/Rarely| B
|
|
C -->|Yes/Often| D["Use MCP"]
|
|
|
|
B -->|Stores| E["Preferences<br/>Context<br/>History"]
|
|
D -->|Accesses| F["Live APIs<br/>Databases<br/>Services"]
|
|
|
|
style B fill:#e1f5ff
|
|
style D fill:#fff9c4
|
|
```
|
|
|
|
### Request/Response Pattern
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant App as Claude
|
|
participant MCP as MCP Server
|
|
participant DB as Database
|
|
|
|
App->>MCP: Request: "SELECT * FROM users WHERE id=1"
|
|
MCP->>DB: Execute query
|
|
DB-->>MCP: Result set
|
|
MCP-->>App: Return parsed data
|
|
App->>App: Process result
|
|
App->>App: Continue task
|
|
|
|
Note over MCP,DB: Real-time access<br/>No caching
|
|
```
|
|
|
|
---
|
|
|
|
## Agent Skills
|
|
|
|
### Overview
|
|
|
|
Agent Skills are reusable, model-invoked capabilities packaged as folders containing instructions, scripts, and resources. Claude automatically detects and uses relevant skills.
|
|
|
|
### Skill Architecture
|
|
|
|
```mermaid
|
|
graph TB
|
|
A["Skill Directory"]
|
|
B["SKILL.md"]
|
|
C["YAML Metadata"]
|
|
D["Instructions"]
|
|
E["Scripts"]
|
|
F["Templates"]
|
|
|
|
A --> B
|
|
B --> C
|
|
B --> D
|
|
E --> A
|
|
F --> A
|
|
```
|
|
|
|
### Skill Loading Process
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant User
|
|
participant Claude as Claude
|
|
participant System as System
|
|
participant Skill as Skill
|
|
|
|
User->>Claude: "Create Excel report"
|
|
Claude->>System: Scan available skills
|
|
System->>System: Load skill metadata
|
|
Claude->>Claude: Match user request to skills
|
|
Claude->>Skill: Load xlsx skill SKILL.md
|
|
Skill-->>Claude: Return instructions + tools
|
|
Claude->>Claude: Execute skill
|
|
Claude->>User: Generate Excel file
|
|
```
|
|
|
|
### Skill Types & Locations Table
|
|
|
|
| Type | Location | Scope | Shared | Sync | Best For |
|
|
|------|----------|-------|--------|------|----------|
|
|
| Pre-built | Built-in | Global | All users | Auto | Document creation |
|
|
| Personal | `~/.claude/skills/` | Individual | No | Manual | Personal automation |
|
|
| Project | `.claude/skills/` | Team | Yes | Git | Team standards |
|
|
| Plugin | Via plugin install | Varies | Depends | Auto | Integrated features |
|
|
|
|
### Pre-built Skills
|
|
|
|
```mermaid
|
|
graph TB
|
|
A["Pre-built Skills"]
|
|
B["PowerPoint (pptx)"]
|
|
C["Excel (xlsx)"]
|
|
D["Word (docx)"]
|
|
E["PDF"]
|
|
|
|
A --> B
|
|
A --> C
|
|
A --> D
|
|
A --> E
|
|
|
|
B --> B1["Create presentations"]
|
|
B --> B2["Edit slides"]
|
|
C --> C1["Create spreadsheets"]
|
|
C --> C2["Analyze data"]
|
|
D --> D1["Create documents"]
|
|
D --> D2["Format text"]
|
|
E --> E1["Generate PDFs"]
|
|
E --> E2["Fill forms"]
|
|
```
|
|
|
|
### Practical Examples
|
|
|
|
#### Example 1: Custom Code Review Skill
|
|
|
|
**Directory Structure:**
|
|
|
|
```
|
|
~/.claude/skills/code-review/
|
|
├── SKILL.md
|
|
├── templates/
|
|
│ ├── review-checklist.md
|
|
│ └── finding-template.md
|
|
└── scripts/
|
|
├── analyze-metrics.py
|
|
└── compare-complexity.py
|
|
```
|
|
|
|
**File:** `~/.claude/skills/code-review/SKILL.md`
|
|
|
|
```yaml
|
|
---
|
|
name: Code Review Specialist
|
|
description: Comprehensive code review with security, performance, and quality analysis
|
|
version: "1.0.0"
|
|
tags:
|
|
- code-review
|
|
- quality
|
|
- security
|
|
when_to_use: When users ask to review code, analyze code quality, or evaluate pull requests
|
|
---
|
|
|
|
# Code Review Skill
|
|
|
|
This skill provides comprehensive code review capabilities focusing on:
|
|
|
|
1. **Security Analysis**
|
|
- Authentication/authorization issues
|
|
- Data exposure risks
|
|
- Injection vulnerabilities
|
|
- Cryptographic weaknesses
|
|
- Sensitive data logging
|
|
|
|
2. **Performance Review**
|
|
- Algorithm efficiency (Big O analysis)
|
|
- Memory optimization
|
|
- Database query optimization
|
|
- Caching opportunities
|
|
- Concurrency issues
|
|
|
|
3. **Code Quality**
|
|
- SOLID principles
|
|
- Design patterns
|
|
- Naming conventions
|
|
- Documentation
|
|
- Test coverage
|
|
|
|
4. **Maintainability**
|
|
- Code readability
|
|
- Function size (should be < 50 lines)
|
|
- Cyclomatic complexity
|
|
- Dependency management
|
|
- Type safety
|
|
|
|
## Review Template
|
|
|
|
For each piece of code reviewed, provide:
|
|
|
|
### Summary
|
|
- Overall quality assessment (1-5)
|
|
- Key findings count
|
|
- Recommended priority areas
|
|
|
|
### Critical Issues (if any)
|
|
- **Issue**: Clear description
|
|
- **Location**: File and line number
|
|
- **Impact**: Why this matters
|
|
- **Severity**: Critical/High/Medium
|
|
- **Fix**: Code example
|
|
|
|
### Findings by Category
|
|
|
|
#### Security (if issues found)
|
|
List security vulnerabilities with examples
|
|
|
|
#### Performance (if issues found)
|
|
List performance problems with complexity analysis
|
|
|
|
#### Quality (if issues found)
|
|
List code quality issues with refactoring suggestions
|
|
|
|
#### Maintainability (if issues found)
|
|
List maintainability problems with improvements
|
|
```
|
|
## Python Script: analyze-metrics.py
|
|
|
|
```python
|
|
#!/usr/bin/env python3
|
|
import re
|
|
import sys
|
|
|
|
def analyze_code_metrics(code):
|
|
"""Analyze code for common metrics."""
|
|
|
|
# Count functions
|
|
functions = len(re.findall(r'^def\s+\w+', code, re.MULTILINE))
|
|
|
|
# Count classes
|
|
classes = len(re.findall(r'^class\s+\w+', code, re.MULTILINE))
|
|
|
|
# Average line length
|
|
lines = code.split('\n')
|
|
avg_length = sum(len(l) for l in lines) / len(lines) if lines else 0
|
|
|
|
# Estimate complexity
|
|
complexity = len(re.findall(r'\b(if|elif|else|for|while|and|or)\b', code))
|
|
|
|
return {
|
|
'functions': functions,
|
|
'classes': classes,
|
|
'avg_line_length': avg_length,
|
|
'complexity_score': complexity
|
|
}
|
|
|
|
if __name__ == '__main__':
|
|
with open(sys.argv[1], 'r') as f:
|
|
code = f.read()
|
|
metrics = analyze_code_metrics(code)
|
|
for key, value in metrics.items():
|
|
print(f"{key}: {value:.2f}")
|
|
```
|
|
|
|
## Python Script: compare-complexity.py
|
|
|
|
```python
|
|
#!/usr/bin/env python3
|
|
"""
|
|
Compare cyclomatic complexity of code before and after changes.
|
|
Helps identify if refactoring actually simplifies code structure.
|
|
"""
|
|
|
|
import re
|
|
import sys
|
|
from typing import Dict, Tuple
|
|
|
|
class ComplexityAnalyzer:
|
|
"""Analyze code complexity metrics."""
|
|
|
|
def __init__(self, code: str):
|
|
self.code = code
|
|
self.lines = code.split('\n')
|
|
|
|
def calculate_cyclomatic_complexity(self) -> int:
|
|
"""
|
|
Calculate cyclomatic complexity using McCabe's method.
|
|
Count decision points: if, elif, else, for, while, except, and, or
|
|
"""
|
|
complexity = 1 # Base complexity
|
|
|
|
# Count decision points
|
|
decision_patterns = [
|
|
r'\bif\b',
|
|
r'\belif\b',
|
|
r'\bfor\b',
|
|
r'\bwhile\b',
|
|
r'\bexcept\b',
|
|
r'\band\b(?!$)',
|
|
r'\bor\b(?!$)'
|
|
]
|
|
|
|
for pattern in decision_patterns:
|
|
matches = re.findall(pattern, self.code)
|
|
complexity += len(matches)
|
|
|
|
return complexity
|
|
|
|
def calculate_cognitive_complexity(self) -> int:
|
|
"""
|
|
Calculate cognitive complexity - how hard is it to understand?
|
|
Based on nesting depth and control flow.
|
|
"""
|
|
cognitive = 0
|
|
nesting_depth = 0
|
|
|
|
for line in self.lines:
|
|
# Track nesting depth
|
|
if re.search(r'^\s*(if|for|while|def|class|try)\b', line):
|
|
nesting_depth += 1
|
|
cognitive += nesting_depth
|
|
elif re.search(r'^\s*(elif|else|except|finally)\b', line):
|
|
cognitive += nesting_depth
|
|
|
|
# Reduce nesting when unindenting
|
|
if line and not line[0].isspace():
|
|
nesting_depth = 0
|
|
|
|
return cognitive
|
|
|
|
def calculate_maintainability_index(self) -> float:
|
|
"""
|
|
Maintainability Index ranges from 0-100.
|
|
> 85: Excellent
|
|
> 65: Good
|
|
> 50: Fair
|
|
< 50: Poor
|
|
"""
|
|
lines = len(self.lines)
|
|
cyclomatic = self.calculate_cyclomatic_complexity()
|
|
cognitive = self.calculate_cognitive_complexity()
|
|
|
|
# Simplified MI calculation
|
|
mi = 171 - 5.2 * (cyclomatic / lines) - 0.23 * (cognitive) - 16.2 * (lines / 1000)
|
|
|
|
return max(0, min(100, mi))
|
|
|
|
def get_complexity_report(self) -> Dict:
|
|
"""Generate comprehensive complexity report."""
|
|
return {
|
|
'cyclomatic_complexity': self.calculate_cyclomatic_complexity(),
|
|
'cognitive_complexity': self.calculate_cognitive_complexity(),
|
|
'maintainability_index': round(self.calculate_maintainability_index(), 2),
|
|
'lines_of_code': len(self.lines),
|
|
'avg_line_length': round(sum(len(l) for l in self.lines) / len(self.lines), 2) if self.lines else 0
|
|
}
|
|
|
|
|
|
def compare_files(before_file: str, after_file: str) -> None:
|
|
"""Compare complexity metrics between two code versions."""
|
|
|
|
with open(before_file, 'r') as f:
|
|
before_code = f.read()
|
|
|
|
with open(after_file, 'r') as f:
|
|
after_code = f.read()
|
|
|
|
before_analyzer = ComplexityAnalyzer(before_code)
|
|
after_analyzer = ComplexityAnalyzer(after_code)
|
|
|
|
before_metrics = before_analyzer.get_complexity_report()
|
|
after_metrics = after_analyzer.get_complexity_report()
|
|
|
|
print("=" * 60)
|
|
print("CODE COMPLEXITY COMPARISON")
|
|
print("=" * 60)
|
|
|
|
print("\nBEFORE:")
|
|
print(f" Cyclomatic Complexity: {before_metrics['cyclomatic_complexity']}")
|
|
print(f" Cognitive Complexity: {before_metrics['cognitive_complexity']}")
|
|
print(f" Maintainability Index: {before_metrics['maintainability_index']}")
|
|
print(f" Lines of Code: {before_metrics['lines_of_code']}")
|
|
print(f" Avg Line Length: {before_metrics['avg_line_length']}")
|
|
|
|
print("\nAFTER:")
|
|
print(f" Cyclomatic Complexity: {after_metrics['cyclomatic_complexity']}")
|
|
print(f" Cognitive Complexity: {after_metrics['cognitive_complexity']}")
|
|
print(f" Maintainability Index: {after_metrics['maintainability_index']}")
|
|
print(f" Lines of Code: {after_metrics['lines_of_code']}")
|
|
print(f" Avg Line Length: {after_metrics['avg_line_length']}")
|
|
|
|
print("\nCHANGES:")
|
|
cyclomatic_change = after_metrics['cyclomatic_complexity'] - before_metrics['cyclomatic_complexity']
|
|
cognitive_change = after_metrics['cognitive_complexity'] - before_metrics['cognitive_complexity']
|
|
mi_change = after_metrics['maintainability_index'] - before_metrics['maintainability_index']
|
|
loc_change = after_metrics['lines_of_code'] - before_metrics['lines_of_code']
|
|
|
|
print(f" Cyclomatic Complexity: {cyclomatic_change:+d}")
|
|
print(f" Cognitive Complexity: {cognitive_change:+d}")
|
|
print(f" Maintainability Index: {mi_change:+.2f}")
|
|
print(f" Lines of Code: {loc_change:+d}")
|
|
|
|
print("\nASSESSMENT:")
|
|
if mi_change > 0:
|
|
print(" ✅ Code is MORE maintainable")
|
|
elif mi_change < 0:
|
|
print(" ⚠️ Code is LESS maintainable")
|
|
else:
|
|
print(" ➡️ Maintainability unchanged")
|
|
|
|
if cyclomatic_change < 0:
|
|
print(" ✅ Complexity DECREASED")
|
|
elif cyclomatic_change > 0:
|
|
print(" ⚠️ Complexity INCREASED")
|
|
else:
|
|
print(" ➡️ Complexity unchanged")
|
|
|
|
print("=" * 60)
|
|
|
|
|
|
if __name__ == '__main__':
|
|
if len(sys.argv) != 3:
|
|
print("Usage: python compare-complexity.py <before_file> <after_file>")
|
|
sys.exit(1)
|
|
|
|
compare_files(sys.argv[1], sys.argv[2])
|
|
```
|
|
|
|
## Template: review-checklist.md
|
|
|
|
```markdown
|
|
# Code Review Checklist
|
|
|
|
## Security Checklist
|
|
- [ ] No hardcoded credentials or secrets
|
|
- [ ] Input validation on all user inputs
|
|
- [ ] SQL injection prevention (parameterized queries)
|
|
- [ ] CSRF protection on state-changing operations
|
|
- [ ] XSS prevention with proper escaping
|
|
- [ ] Authentication checks on protected endpoints
|
|
- [ ] Authorization checks on resources
|
|
- [ ] Secure password hashing (bcrypt, argon2)
|
|
- [ ] No sensitive data in logs
|
|
- [ ] HTTPS enforced
|
|
|
|
## Performance Checklist
|
|
- [ ] No N+1 queries
|
|
- [ ] Appropriate use of indexes
|
|
- [ ] Caching implemented where beneficial
|
|
- [ ] No blocking operations on main thread
|
|
- [ ] Async/await used correctly
|
|
- [ ] Large datasets paginated
|
|
- [ ] Database connections pooled
|
|
- [ ] Regular expressions optimized
|
|
- [ ] No unnecessary object creation
|
|
- [ ] Memory leaks prevented
|
|
|
|
## Quality Checklist
|
|
- [ ] Functions < 50 lines
|
|
- [ ] Clear variable naming
|
|
- [ ] No duplicate code
|
|
- [ ] Proper error handling
|
|
- [ ] Comments explain WHY, not WHAT
|
|
- [ ] No console.logs in production
|
|
- [ ] Type checking (TypeScript/JSDoc)
|
|
- [ ] SOLID principles followed
|
|
- [ ] Design patterns applied correctly
|
|
- [ ] Self-documenting code
|
|
|
|
## Testing Checklist
|
|
- [ ] Unit tests written
|
|
- [ ] Edge cases covered
|
|
- [ ] Error scenarios tested
|
|
- [ ] Integration tests present
|
|
- [ ] Coverage > 80%
|
|
- [ ] No flaky tests
|
|
- [ ] Mock external dependencies
|
|
- [ ] Clear test names
|
|
```
|
|
|
|
## Template: finding-template.md
|
|
|
|
```markdown
|
|
# Code Review Finding Template
|
|
|
|
Use this template when documenting each issue found during code review.
|
|
|
|
---
|
|
|
|
## Issue: [TITLE]
|
|
|
|
### Severity
|
|
- [ ] Critical (blocks deployment)
|
|
- [ ] High (should fix before merge)
|
|
- [ ] Medium (should fix soon)
|
|
- [ ] Low (nice to have)
|
|
|
|
### Category
|
|
- [ ] Security
|
|
- [ ] Performance
|
|
- [ ] Code Quality
|
|
- [ ] Maintainability
|
|
- [ ] Testing
|
|
- [ ] Design Pattern
|
|
- [ ] Documentation
|
|
|
|
### Location
|
|
**File:** `src/components/UserCard.tsx`
|
|
|
|
**Lines:** 45-52
|
|
|
|
**Function/Method:** `renderUserDetails()`
|
|
|
|
### Issue Description
|
|
|
|
**What:** Describe what the issue is.
|
|
|
|
**Why it matters:** Explain the impact and why this needs to be fixed.
|
|
|
|
**Current behavior:** Show the problematic code or behavior.
|
|
|
|
**Expected behavior:** Describe what should happen instead.
|
|
|
|
### Code Example
|
|
|
|
#### Current (Problematic)
|
|
|
|
```typescript
|
|
// Shows the N+1 query problem
|
|
const users = fetchUsers();
|
|
users.forEach(user => {
|
|
const posts = fetchUserPosts(user.id); // Query per user!
|
|
renderUserPosts(posts);
|
|
});
|
|
```
|
|
|
|
#### Suggested Fix
|
|
|
|
```typescript
|
|
// Optimized with JOIN query
|
|
const usersWithPosts = fetchUsersWithPosts();
|
|
usersWithPosts.forEach(({ user, posts }) => {
|
|
renderUserPosts(posts);
|
|
});
|
|
```
|
|
|
|
### Impact Analysis
|
|
|
|
| Aspect | Impact | Severity |
|
|
|--------|--------|----------|
|
|
| Performance | 100+ queries for 20 users | High |
|
|
| User Experience | Slow page load | High |
|
|
| Scalability | Breaks at scale | Critical |
|
|
| Maintainability | Hard to debug | Medium |
|
|
|
|
### Related Issues
|
|
|
|
- Similar issue in `AdminUserList.tsx` line 120
|
|
- Related PR: #456
|
|
- Related issue: #789
|
|
|
|
### Additional Resources
|
|
|
|
- [N+1 Query Problem](https://en.wikipedia.org/wiki/N%2B1_problem)
|
|
- [Database Join Documentation](https://docs.example.com/joins)
|
|
- [Performance Optimization Guide](./docs/performance.md)
|
|
|
|
### Reviewer Notes
|
|
|
|
- This is a common pattern in this codebase
|
|
- Consider adding this to the code style guide
|
|
- Might be worth creating a helper function
|
|
|
|
### Author Response (for feedback)
|
|
|
|
*To be filled by the code author:*
|
|
|
|
- [ ] Fix implemented in commit: `abc123`
|
|
- [ ] Fix status: Complete / In Progress / Needs Discussion
|
|
- [ ] Questions or concerns: (describe)
|
|
|
|
---
|
|
|
|
## Finding Statistics (for Reviewer)
|
|
|
|
When reviewing multiple findings, track:
|
|
|
|
- **Total Issues Found:** X
|
|
- **Critical:** X
|
|
- **High:** X
|
|
- **Medium:** X
|
|
- **Low:** X
|
|
|
|
**Recommendation:** ✅ Approve / ⚠️ Request Changes / 🔄 Needs Discussion
|
|
|
|
**Overall Code Quality:** 1-5 stars
|
|
```
|
|
|
|
## Usage Example
|
|
|
|
```markdown
|
|
User: Review this React component code
|
|
|
|
Claude: I'll conduct a comprehensive code review using my Code Review Skill.
|
|
|
|
[Loads SKILL.md]
|
|
[Analyzes code against checklist]
|
|
[Runs Python metrics script]
|
|
[Applies templates]
|
|
|
|
## Code Review Results
|
|
|
|
### Summary
|
|
Quality Score: 3.5/5
|
|
Key Findings: 7 items
|
|
Priority Areas: Performance optimization, error handling
|
|
|
|
### Critical Issues: 1
|
|
|
|
**Issue**: N+1 Query Problem
|
|
**Location**: UserComponent.tsx, lines 45-52
|
|
**Impact**: Renders 100+ database queries for list of 20 users
|
|
**Severity**: High
|
|
**Fix**:
|
|
```javascript
|
|
// Before: N+1 queries
|
|
const users = fetchUsers();
|
|
users.forEach(user => fetchUserPosts(user.id)); // 20+ queries
|
|
|
|
// After: Single query with JOIN
|
|
const users = fetchUsersWithPosts(); // 1 query
|
|
```
|
|
|
|
### Performance Findings
|
|
- Missing pagination on large lists
|
|
- Recommendation: Use React.memo() for items
|
|
- Database query: Could be optimized with index
|
|
|
|
### Quality Findings
|
|
- Function in line 20 is 127 lines (max: 50)
|
|
- Missing error boundary
|
|
- Props should have TypeScript types
|
|
```
|
|
|
|
#### Example 2: Brand Voice Skill
|
|
|
|
**Directory Structure:**
|
|
|
|
```
|
|
.claude/skills/brand-voice/
|
|
├── SKILL.md
|
|
├── brand-guidelines.md
|
|
├── tone-examples.md
|
|
└── templates/
|
|
├── email-template.txt
|
|
├── social-post-template.txt
|
|
└── blog-post-template.md
|
|
```
|
|
|
|
**File:** `.claude/skills/brand-voice/SKILL.md`
|
|
|
|
```yaml
|
|
---
|
|
name: Brand Voice Consistency
|
|
description: Ensure all communication matches brand voice and tone guidelines
|
|
tags:
|
|
- brand
|
|
- writing
|
|
- consistency
|
|
when_to_use: When creating marketing copy, customer communications, or public-facing content
|
|
---
|
|
|
|
# Brand Voice Skill
|
|
|
|
## Overview
|
|
This skill ensures all communications maintain consistent brand voice, tone, and messaging.
|
|
|
|
## Brand Identity
|
|
|
|
### Mission
|
|
Help teams automate their development workflows with AI
|
|
|
|
### Values
|
|
- **Simplicity**: Make complex things simple
|
|
- **Reliability**: Rock-solid execution
|
|
- **Empowerment**: Enable human creativity
|
|
|
|
### Tone of Voice
|
|
- **Friendly but professional** - approachable without being casual
|
|
- **Clear and concise** - avoid jargon, explain technical concepts simply
|
|
- **Confident** - we know what we're doing
|
|
- **Empathetic** - understand user needs and pain points
|
|
|
|
## Writing Guidelines
|
|
|
|
### Do's ✅
|
|
- Use "you" when addressing readers
|
|
- Use active voice: "Claude generates reports" not "Reports are generated by Claude"
|
|
- Start with value proposition
|
|
- Use concrete examples
|
|
- Keep sentences under 20 words
|
|
- Use lists for clarity
|
|
- Include calls-to-action
|
|
|
|
### Don'ts ❌
|
|
- Don't use corporate jargon
|
|
- Don't patronize or oversimplify
|
|
- Don't use "we believe" or "we think"
|
|
- Don't use ALL CAPS except for emphasis
|
|
- Don't create walls of text
|
|
- Don't assume technical knowledge
|
|
|
|
## Vocabulary
|
|
|
|
### ✅ Preferred Terms
|
|
- Claude (not "the Claude AI")
|
|
- Code generation (not "auto-coding")
|
|
- Agent (not "bot")
|
|
- Streamline (not "revolutionize")
|
|
- Integrate (not "synergize")
|
|
|
|
### ❌ Avoid Terms
|
|
- "Cutting-edge" (overused)
|
|
- "Game-changer" (vague)
|
|
- "Leverage" (corporate-speak)
|
|
- "Utilize" (use "use")
|
|
- "Paradigm shift" (unclear)
|
|
```
|
|
## Examples
|
|
|
|
### ✅ Good Example
|
|
"Claude automates your code review process. Instead of manually checking each PR, Claude reviews security, performance, and quality—saving your team hours every week."
|
|
|
|
Why it works: Clear value, specific benefits, action-oriented
|
|
|
|
### ❌ Bad Example
|
|
"Claude leverages cutting-edge AI to provide comprehensive software development solutions."
|
|
|
|
Why it doesn't work: Vague, corporate jargon, no specific value
|
|
|
|
## Template: Email
|
|
|
|
```
|
|
Subject: [Clear, benefit-driven subject]
|
|
|
|
Hi [Name],
|
|
|
|
[Opening: What's the value for them]
|
|
|
|
[Body: How it works / What they'll get]
|
|
|
|
[Specific example or benefit]
|
|
|
|
[Call to action: Clear next step]
|
|
|
|
Best regards,
|
|
[Name]
|
|
```
|
|
|
|
## Template: Social Media
|
|
|
|
```
|
|
[Hook: Grab attention in first line]
|
|
[2-3 lines: Value or interesting fact]
|
|
[Call to action: Link, question, or engagement]
|
|
[Emoji: 1-2 max for visual interest]
|
|
```
|
|
|
|
## File: tone-examples.md
|
|
```
|
|
Exciting announcement:
|
|
"Save 8 hours per week on code reviews. Claude reviews your PRs automatically."
|
|
|
|
Empathetic support:
|
|
"We know deployments can be stressful. Claude handles testing so you don't have to worry."
|
|
|
|
Confident product feature:
|
|
"Claude doesn't just suggest code. It understands your architecture and maintains consistency."
|
|
|
|
Educational blog post:
|
|
"Let's explore how agents improve code review workflows. Here's what we learned..."
|
|
```
|
|
|
|
#### Example 3: Documentation Generator Skill
|
|
|
|
**File:** `.claude/skills/doc-generator/SKILL.md`
|
|
|
|
```yaml
|
|
---
|
|
name: API Documentation Generator
|
|
description: Generate comprehensive, accurate API documentation from source code
|
|
version: "1.0.0"
|
|
tags:
|
|
- documentation
|
|
- api
|
|
- automation
|
|
when_to_use: When creating or updating API documentation
|
|
---
|
|
|
|
# API Documentation Generator Skill
|
|
|
|
## Generates
|
|
|
|
- OpenAPI/Swagger specifications
|
|
- API endpoint documentation
|
|
- SDK usage examples
|
|
- Integration guides
|
|
- Error code references
|
|
- Authentication guides
|
|
|
|
## Documentation Structure
|
|
|
|
### For Each Endpoint
|
|
|
|
```markdown
|
|
## GET /api/v1/users/:id
|
|
|
|
### Description
|
|
Brief explanation of what this endpoint does
|
|
|
|
### Parameters
|
|
|
|
| Name | Type | Required | Description |
|
|
|------|------|----------|-------------|
|
|
| id | string | Yes | User ID |
|
|
|
|
### Response
|
|
|
|
**200 Success**
|
|
```json
|
|
{
|
|
"id": "usr_123",
|
|
"name": "John Doe",
|
|
"email": "john@example.com",
|
|
"created_at": "2025-01-15T10:30:00Z"
|
|
}
|
|
```
|
|
|
|
**404 Not Found**
|
|
```json
|
|
{
|
|
"error": "USER_NOT_FOUND",
|
|
"message": "User does not exist"
|
|
}
|
|
```
|
|
|
|
### Examples
|
|
|
|
**cURL**
|
|
```bash
|
|
curl -X GET "https://api.example.com/api/v1/users/usr_123" \
|
|
-H "Authorization: Bearer YOUR_TOKEN"
|
|
```
|
|
|
|
**JavaScript**
|
|
```javascript
|
|
const user = await fetch('/api/v1/users/usr_123', {
|
|
headers: { 'Authorization': 'Bearer token' }
|
|
}).then(r => r.json());
|
|
```
|
|
|
|
**Python**
|
|
```python
|
|
response = requests.get(
|
|
'https://api.example.com/api/v1/users/usr_123',
|
|
headers={'Authorization': 'Bearer token'}
|
|
)
|
|
user = response.json()
|
|
```
|
|
|
|
## Python Script: generate-docs.py
|
|
|
|
```python
|
|
#!/usr/bin/env python3
|
|
import ast
|
|
import json
|
|
from typing import Dict, List
|
|
|
|
class APIDocExtractor(ast.NodeVisitor):
|
|
"""Extract API documentation from Python source code."""
|
|
|
|
def __init__(self):
|
|
self.endpoints = []
|
|
|
|
def visit_FunctionDef(self, node):
|
|
"""Extract function documentation."""
|
|
if node.name.startswith('get_') or node.name.startswith('post_'):
|
|
doc = ast.get_docstring(node)
|
|
endpoint = {
|
|
'name': node.name,
|
|
'docstring': doc,
|
|
'params': [arg.arg for arg in node.args.args],
|
|
'returns': self._extract_return_type(node)
|
|
}
|
|
self.endpoints.append(endpoint)
|
|
self.generic_visit(node)
|
|
|
|
def _extract_return_type(self, node):
|
|
"""Extract return type from function annotation."""
|
|
if node.returns:
|
|
return ast.unparse(node.returns)
|
|
return "Any"
|
|
|
|
def generate_markdown_docs(endpoints: List[Dict]) -> str:
|
|
"""Generate markdown documentation from endpoints."""
|
|
docs = "# API Documentation\n\n"
|
|
|
|
for endpoint in endpoints:
|
|
docs += f"## {endpoint['name']}\n\n"
|
|
docs += f"{endpoint['docstring']}\n\n"
|
|
docs += f"**Parameters**: {', '.join(endpoint['params'])}\n\n"
|
|
docs += f"**Returns**: {endpoint['returns']}\n\n"
|
|
docs += "---\n\n"
|
|
|
|
return docs
|
|
|
|
if __name__ == '__main__':
|
|
import sys
|
|
with open(sys.argv[1], 'r') as f:
|
|
tree = ast.parse(f.read())
|
|
|
|
extractor = APIDocExtractor()
|
|
extractor.visit(tree)
|
|
|
|
markdown = generate_markdown_docs(extractor.endpoints)
|
|
print(markdown)
|
|
```
|
|
### Skill Discovery & Invocation
|
|
|
|
```mermaid
|
|
graph TD
|
|
A["User Request"] --> B["Claude Analyzes"]
|
|
B -->|Scans| C["Available Skills"]
|
|
C -->|Metadata check| D["Skill Description Match?"]
|
|
D -->|Yes| E["Load SKILL.md"]
|
|
D -->|No| F["Try next skill"]
|
|
F -->|More skills?| D
|
|
F -->|No more| G["Use general knowledge"]
|
|
E --> H["Extract Instructions"]
|
|
H --> I["Execute Skill"]
|
|
I --> J["Return Results"]
|
|
```
|
|
|
|
### Skill vs Other Features
|
|
|
|
```mermaid
|
|
graph TB
|
|
A["Extending Claude"]
|
|
B["Slash Commands"]
|
|
C["Subagents"]
|
|
D["Memory"]
|
|
E["MCP"]
|
|
F["Skills"]
|
|
|
|
A --> B
|
|
A --> C
|
|
A --> D
|
|
A --> E
|
|
A --> F
|
|
|
|
B -->|User-invoked| G["Quick shortcuts"]
|
|
C -->|Auto-delegated| H["Isolated contexts"]
|
|
D -->|Persistent| I["Cross-session context"]
|
|
E -->|Real-time| J["External data access"]
|
|
F -->|Auto-invoked| K["Autonomous execution"]
|
|
```
|
|
|
|
---
|
|
|
|
## Claude Code Plugins
|
|
|
|
### Overview
|
|
|
|
Claude Code Plugins are bundled collections of customizations (slash commands, subagents, MCP servers, and hooks) that install with a single command. They represent the highest-level extension mechanism—combining multiple features into cohesive, shareable packages.
|
|
|
|
### Architecture
|
|
|
|
```mermaid
|
|
graph TB
|
|
A["Plugin"]
|
|
B["Slash Commands"]
|
|
C["Subagents"]
|
|
D["MCP Servers"]
|
|
E["Hooks"]
|
|
F["Configuration"]
|
|
|
|
A -->|bundles| B
|
|
A -->|bundles| C
|
|
A -->|bundles| D
|
|
A -->|bundles| E
|
|
A -->|bundles| F
|
|
```
|
|
|
|
### Plugin Loading Process
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant User
|
|
participant Claude as Claude Code
|
|
participant Plugin as Plugin Marketplace
|
|
participant Install as Installation
|
|
participant SlashCmds as Slash Commands
|
|
participant Subagents
|
|
participant MCPServers as MCP Servers
|
|
participant Hooks
|
|
participant Tools as Configured Tools
|
|
|
|
User->>Claude: /plugin install pr-review
|
|
Claude->>Plugin: Download plugin manifest
|
|
Plugin-->>Claude: Return plugin definition
|
|
Claude->>Install: Extract components
|
|
Install->>SlashCmds: Configure
|
|
Install->>Subagents: Configure
|
|
Install->>MCPServers: Configure
|
|
Install->>Hooks: Configure
|
|
SlashCmds-->>Tools: Ready to use
|
|
Subagents-->>Tools: Ready to use
|
|
MCPServers-->>Tools: Ready to use
|
|
Hooks-->>Tools: Ready to use
|
|
Tools-->>Claude: Plugin installed ✅
|
|
```
|
|
|
|
### Plugin Types & Distribution
|
|
|
|
| Type | Scope | Shared | Authority | Examples |
|
|
|------|-------|--------|-----------|----------|
|
|
| Official | Global | All users | Anthropic | PR Review, Security Guidance |
|
|
| Community | Public | All users | Community | DevOps, Data Science |
|
|
| Organization | Internal | Team members | Company | Internal standards, tools |
|
|
| Personal | Individual | Single user | Developer | Custom workflows |
|
|
|
|
### Plugin Definition Structure
|
|
|
|
```yaml
|
|
---
|
|
name: plugin-name
|
|
version: "1.0.0"
|
|
description: "What this plugin does"
|
|
author: "Your Name"
|
|
license: MIT
|
|
|
|
# Plugin metadata
|
|
tags:
|
|
- category
|
|
- use-case
|
|
|
|
# Requirements
|
|
requires:
|
|
- claude-code: ">=1.0.0"
|
|
|
|
# Components bundled
|
|
components:
|
|
- type: commands
|
|
path: commands/
|
|
- type: agents
|
|
path: agents/
|
|
- type: mcp
|
|
path: mcp/
|
|
- type: hooks
|
|
path: hooks/
|
|
|
|
# Configuration
|
|
config:
|
|
auto_load: true
|
|
enabled_by_default: true
|
|
---
|
|
```
|
|
|
|
### Plugin Structure
|
|
|
|
```
|
|
my-plugin/
|
|
├── plugin.yaml
|
|
├── commands/
|
|
│ ├── task-1.md
|
|
│ ├── task-2.md
|
|
│ └── workflows/
|
|
├── agents/
|
|
│ ├── specialist-1.md
|
|
│ ├── specialist-2.md
|
|
│ └── configs/
|
|
├── mcp/
|
|
│ ├── mcp-config.json
|
|
│ └── servers/
|
|
├── hooks/
|
|
│ ├── pre-deploy.js
|
|
│ └── post-merge.js
|
|
├── templates/
|
|
│ └── issue-template.md
|
|
├── scripts/
|
|
│ ├── helper-1.sh
|
|
│ └── helper-2.py
|
|
├── docs/
|
|
│ ├── README.md
|
|
│ └── USAGE.md
|
|
└── tests/
|
|
└── plugin.test.js
|
|
```
|
|
|
|
### Practical Examples
|
|
|
|
#### Example 1: PR Review Plugin
|
|
|
|
**File:** `plugin.yaml`
|
|
|
|
```yaml
|
|
---
|
|
name: pr-review
|
|
version: "1.0.0"
|
|
description: Complete PR review workflow with security, testing, and docs
|
|
author: Anthropic
|
|
tags:
|
|
- code-review
|
|
- quality
|
|
- security
|
|
|
|
components:
|
|
- type: commands
|
|
path: commands/
|
|
- type: agents
|
|
path: agents/
|
|
- type: mcp
|
|
path: mcp/
|
|
- type: hooks
|
|
path: hooks/
|
|
---
|
|
```
|
|
|
|
**File:** `commands/review-pr.md`
|
|
|
|
```markdown
|
|
---
|
|
name: Review PR
|
|
description: Start comprehensive PR review with security and testing checks
|
|
---
|
|
|
|
# PR Review
|
|
|
|
This command initiates a complete pull request review including:
|
|
|
|
1. Security analysis
|
|
2. Test coverage verification
|
|
3. Documentation updates
|
|
4. Code quality checks
|
|
5. Performance impact assessment
|
|
```
|
|
|
|
**File:** `agents/security-reviewer.md`
|
|
|
|
```yaml
|
|
---
|
|
name: security-reviewer
|
|
description: Security-focused code review
|
|
tools: read, grep, diff
|
|
---
|
|
|
|
# Security Reviewer
|
|
|
|
Specializes in finding security vulnerabilities:
|
|
- Authentication/authorization issues
|
|
- Data exposure
|
|
- Injection attacks
|
|
- Secure configuration
|
|
```
|
|
|
|
**Installation:**
|
|
|
|
```bash
|
|
/plugin install pr-review
|
|
|
|
# Result:
|
|
# ✅ 3 slash commands installed
|
|
# ✅ 3 subagents configured
|
|
# ✅ 2 MCP servers connected
|
|
# ✅ 4 hooks registered
|
|
# ✅ Ready to use!
|
|
```
|
|
|
|
#### Example 2: DevOps Plugin
|
|
|
|
**Components:**
|
|
|
|
```
|
|
devops-automation/
|
|
├── commands/
|
|
│ ├── deploy.md
|
|
│ ├── rollback.md
|
|
│ ├── status.md
|
|
│ └── incident.md
|
|
├── agents/
|
|
│ ├── deployment-specialist.md
|
|
│ ├── incident-commander.md
|
|
│ └── alert-analyzer.md
|
|
├── mcp/
|
|
│ ├── github-config.json
|
|
│ ├── kubernetes-config.json
|
|
│ └── prometheus-config.json
|
|
├── hooks/
|
|
│ ├── pre-deploy.js
|
|
│ ├── post-deploy.js
|
|
│ └── on-error.js
|
|
└── scripts/
|
|
├── deploy.sh
|
|
├── rollback.sh
|
|
└── health-check.sh
|
|
```
|
|
|
|
#### Example 3: Documentation Plugin
|
|
|
|
**Bundled Components:**
|
|
|
|
```
|
|
documentation/
|
|
├── commands/
|
|
│ ├── generate-api-docs.md
|
|
│ ├── generate-readme.md
|
|
│ ├── sync-docs.md
|
|
│ └── validate-docs.md
|
|
├── agents/
|
|
│ ├── api-documenter.md
|
|
│ ├── code-commentator.md
|
|
│ └── example-generator.md
|
|
├── mcp/
|
|
│ ├── github-docs-config.json
|
|
│ └── slack-announce-config.json
|
|
└── templates/
|
|
├── api-endpoint.md
|
|
├── function-docs.md
|
|
└── adr-template.md
|
|
```
|
|
|
|
### Plugin Marketplace
|
|
|
|
```mermaid
|
|
graph TB
|
|
A["Plugin Marketplace"]
|
|
B["Official<br/>Anthropic"]
|
|
C["Community<br/>Marketplace"]
|
|
D["Enterprise<br/>Registry"]
|
|
|
|
A --> B
|
|
A --> C
|
|
A --> D
|
|
|
|
B -->|Categories| B1["Development"]
|
|
B -->|Categories| B2["DevOps"]
|
|
B -->|Categories| B3["Documentation"]
|
|
|
|
C -->|Search| C1["DevOps Automation"]
|
|
C -->|Search| C2["Mobile Dev"]
|
|
C -->|Search| C3["Data Science"]
|
|
|
|
D -->|Internal| D1["Company Standards"]
|
|
D -->|Internal| D2["Legacy Systems"]
|
|
D -->|Internal| D3["Compliance"]
|
|
```
|
|
|
|
### Plugin Installation & Lifecycle
|
|
|
|
```mermaid
|
|
graph LR
|
|
A["Discover"] -->|Browse| B["Marketplace"]
|
|
B -->|Select| C["Plugin Page"]
|
|
C -->|View| D["Components"]
|
|
D -->|Install| E["/plugin install"]
|
|
E -->|Extract| F["Configure"]
|
|
F -->|Activate| G["Use"]
|
|
G -->|Check| H["Update"]
|
|
H -->|Available| G
|
|
G -->|Done| I["Disable"]
|
|
I -->|Later| J["Enable"]
|
|
J -->|Back| G
|
|
```
|
|
|
|
### Plugin Features Comparison
|
|
|
|
| Feature | Slash Command | Skill | Subagent | Plugin |
|
|
|---------|---------------|-------|----------|--------|
|
|
| **Installation** | Manual copy | Manual copy | Manual config | One command |
|
|
| **Setup Time** | 5 minutes | 10 minutes | 15 minutes | 2 minutes |
|
|
| **Bundling** | Single file | Single file | Single file | Multiple |
|
|
| **Versioning** | Manual | Manual | Manual | Automatic |
|
|
| **Team Sharing** | Copy file | Copy file | Copy file | Install ID |
|
|
| **Updates** | Manual | Manual | Manual | Auto-available |
|
|
| **Dependencies** | None | None | None | May include |
|
|
| **Marketplace** | No | No | No | Yes |
|
|
| **Distribution** | Repository | Repository | Repository | Marketplace |
|
|
|
|
### Plugin Use Cases
|
|
|
|
| Use Case | Recommendation | Why |
|
|
|----------|-----------------|-----|
|
|
| **Team Onboarding** | ✅ Use Plugin | Instant setup, all configurations |
|
|
| **Framework Setup** | ✅ Use Plugin | Bundles framework-specific commands |
|
|
| **Enterprise Standards** | ✅ Use Plugin | Central distribution, version control |
|
|
| **Quick Task Automation** | ❌ Use Command | Overkill complexity |
|
|
| **Single Domain Expertise** | ❌ Use Skill | Too heavy, use skill instead |
|
|
| **Specialized Analysis** | ❌ Use Subagent | Create manually or use skill |
|
|
| **Live Data Access** | ❌ Use MCP | Standalone, don't bundle |
|
|
|
|
### When to Create a Plugin
|
|
|
|
```mermaid
|
|
graph TD
|
|
A["Should I create a plugin?"]
|
|
A -->|Need multiple components| B{"Multiple commands<br/>or subagents<br/>or MCPs?"}
|
|
B -->|Yes| C["✅ Create Plugin"]
|
|
B -->|No| D["Use Individual Feature"]
|
|
A -->|Team workflow| E{"Share with<br/>team?"}
|
|
E -->|Yes| C
|
|
E -->|No| F["Keep as Local Setup"]
|
|
A -->|Complex setup| G{"Needs auto<br/>configuration?"}
|
|
G -->|Yes| C
|
|
G -->|No| D
|
|
```
|
|
|
|
### Publishing a Plugin
|
|
|
|
**Steps to publish:**
|
|
|
|
1. Create plugin structure with all components
|
|
2. Write `plugin.yaml` manifest
|
|
3. Create `README.md` with documentation
|
|
4. Test locally with `/plugin install ./my-plugin`
|
|
5. Submit to plugin marketplace
|
|
6. Get reviewed and approved
|
|
7. Published on marketplace
|
|
8. Users can install with one command
|
|
|
|
**Example submission:**
|
|
|
|
```markdown
|
|
# PR Review Plugin
|
|
|
|
## Description
|
|
Complete PR review workflow with security, testing, and documentation checks.
|
|
|
|
## What's Included
|
|
- 3 slash commands for different review types
|
|
- 3 specialized subagents
|
|
- GitHub and CodeQL MCP integration
|
|
- Automated security scanning hooks
|
|
|
|
## Installation
|
|
```bash
|
|
/plugin install pr-review
|
|
```
|
|
|
|
## Features
|
|
✅ Security analysis
|
|
✅ Test coverage checking
|
|
✅ Documentation verification
|
|
✅ Code quality assessment
|
|
✅ Performance impact analysis
|
|
|
|
## Usage
|
|
```bash
|
|
/review-pr
|
|
/check-security
|
|
/check-tests
|
|
```
|
|
|
|
## Requirements
|
|
- Claude Code 1.0+
|
|
- GitHub access
|
|
- CodeQL (optional)
|
|
```
|
|
|
|
### Plugin vs Manual Configuration
|
|
|
|
**Manual Setup (2+ hours):**
|
|
- Install slash commands one by one
|
|
- Create subagents individually
|
|
- Configure MCPs separately
|
|
- Set up hooks manually
|
|
- Document everything
|
|
- Share with team (hope they configure correctly)
|
|
|
|
**With Plugin (2 minutes):**
|
|
```bash
|
|
/plugin install pr-review
|
|
# ✅ Everything installed and configured
|
|
# ✅ Ready to use immediately
|
|
# ✅ Team can reproduce exact setup
|
|
```
|
|
|
|
---
|
|
|
|
## Comparison & Integration
|
|
|
|
### Feature Comparison Matrix
|
|
|
|
| Feature | Invocation | Persistence | Scope | Use Case |
|
|
|---------|-----------|------------|-------|----------|
|
|
| **Slash Commands** | Manual (`/cmd`) | Session only | Single command | Quick shortcuts |
|
|
| **Subagents** | Auto-delegated | Isolated context | Specialized task | Task distribution |
|
|
| **Memory** | Auto-loaded | Cross-session | User/team context | Long-term learning |
|
|
| **MCP Protocol** | Auto-queried | Real-time external | Live data access | Dynamic information |
|
|
| **Skills** | Auto-invoked | Filesystem-based | Reusable expertise | Automated workflows |
|
|
|
|
### Interaction Timeline
|
|
|
|
```mermaid
|
|
graph LR
|
|
A["Session Start"] -->|Load| B["Memory (CLAUDE.md)"]
|
|
B -->|Discover| C["Available Skills"]
|
|
C -->|Register| D["Slash Commands"]
|
|
D -->|Connect| E["MCP Servers"]
|
|
E -->|Ready| F["User Interaction"]
|
|
|
|
F -->|Type /cmd| G["Slash Command"]
|
|
F -->|Request| H["Skill Auto-Invoke"]
|
|
F -->|Query| I["MCP Data"]
|
|
F -->|Complex task| J["Delegate to Subagent"]
|
|
|
|
G -->|Uses| B
|
|
H -->|Uses| B
|
|
I -->|Uses| B
|
|
J -->|Uses| B
|
|
```
|
|
|
|
### Practical Integration Example: Customer Support Automation
|
|
|
|
#### Architecture
|
|
|
|
```mermaid
|
|
graph TB
|
|
User["Customer Email"] -->|Receives| Router["Support Router"]
|
|
|
|
Router -->|Analyze| Memory["Memory<br/>Customer history"]
|
|
Router -->|Lookup| MCP1["MCP: Customer DB<br/>Previous tickets"]
|
|
Router -->|Check| MCP2["MCP: Slack<br/>Team status"]
|
|
|
|
Router -->|Route Complex| Sub1["Subagent: Tech Support<br/>Context: Technical issues"]
|
|
Router -->|Route Simple| Sub2["Subagent: Billing<br/>Context: Payment issues"]
|
|
Router -->|Route Urgent| Sub3["Subagent: Escalation<br/>Context: Priority handling"]
|
|
|
|
Sub1 -->|Format| Skill1["Skill: Response Generator<br/>Brand voice maintained"]
|
|
Sub2 -->|Format| Skill2["Skill: Response Generator"]
|
|
Sub3 -->|Format| Skill3["Skill: Response Generator"]
|
|
|
|
Skill1 -->|Generate| Output["Formatted Response"]
|
|
Skill2 -->|Generate| Output
|
|
Skill3 -->|Generate| Output
|
|
|
|
Output -->|Post| MCP3["MCP: Slack<br/>Notify team"]
|
|
Output -->|Send| Reply["Customer Reply"]
|
|
```
|
|
|
|
#### Request Flow
|
|
|
|
```markdown
|
|
## Customer Support Request Flow
|
|
|
|
### 1. Incoming Email
|
|
"I'm getting error 500 when trying to upload files. This is blocking my workflow!"
|
|
|
|
### 2. Memory Lookup
|
|
- Loads CLAUDE.md with support standards
|
|
- Checks customer history: VIP customer, 3rd incident this month
|
|
|
|
### 3. MCP Queries
|
|
- GitHub MCP: List open issues (finds related bug report)
|
|
- Database MCP: Check system status (no outages reported)
|
|
- Slack MCP: Check if engineering is aware
|
|
|
|
### 4. Skill Detection & Loading
|
|
- Request matches "Technical Support" skill
|
|
- Loads support response template from Skill
|
|
|
|
### 5. Subagent Delegation
|
|
- Routes to Tech Support Subagent
|
|
- Provides context: customer history, error details, known issues
|
|
- Subagent has full access to: read, bash, grep tools
|
|
|
|
### 6. Subagent Processing
|
|
Tech Support Subagent:
|
|
- Searches codebase for 500 error in file upload
|
|
- Finds recent change in commit 8f4a2c
|
|
- Creates workaround documentation
|
|
|
|
### 7. Skill Execution
|
|
Response Generator Skill:
|
|
- Uses Brand Voice guidelines
|
|
- Formats response with empathy
|
|
- Includes workaround steps
|
|
- Links to related documentation
|
|
|
|
### 8. MCP Output
|
|
- Posts update to #support Slack channel
|
|
- Tags engineering team
|
|
- Updates ticket in Jira MCP
|
|
|
|
### 9. Response
|
|
Customer receives:
|
|
- Empathetic acknowledgment
|
|
- Explanation of cause
|
|
- Immediate workaround
|
|
- Timeline for permanent fix
|
|
- Link to related issues
|
|
```
|
|
|
|
### Complete Feature Orchestration
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant User
|
|
participant Claude as Claude Code
|
|
participant Memory as Memory<br/>CLAUDE.md
|
|
participant MCP as MCP Servers
|
|
participant Skills as Skills
|
|
participant SubAgent as Subagents
|
|
|
|
User->>Claude: Request: "Build auth system"
|
|
Claude->>Memory: Load project standards
|
|
Memory-->>Claude: Auth standards, team practices
|
|
Claude->>MCP: Query GitHub for similar implementations
|
|
MCP-->>Claude: Code examples, best practices
|
|
Claude->>Skills: Detect matching Skills
|
|
Skills-->>Claude: Security Review Skill + Testing Skill
|
|
Claude->>SubAgent: Delegate implementation
|
|
SubAgent->>SubAgent: Build feature
|
|
Claude->>Skills: Apply Security Review Skill
|
|
Skills-->>Claude: Security checklist results
|
|
Claude->>SubAgent: Delegate testing
|
|
SubAgent-->>Claude: Test results
|
|
Claude->>User: Complete system delivered
|
|
```
|
|
|
|
### When to Use Each Feature
|
|
|
|
```mermaid
|
|
graph TD
|
|
A["New Task"] --> B{Type of Task?}
|
|
|
|
B -->|Repeated workflow| C["Slash Command"]
|
|
B -->|Need real-time data| D["MCP Protocol"]
|
|
B -->|Remember for next time| E["Memory"]
|
|
B -->|Specialized subtask| F["Subagent"]
|
|
B -->|Domain-specific work| G["Skill"]
|
|
|
|
C --> C1["✅ Team shortcut"]
|
|
D --> D1["✅ Live API access"]
|
|
E --> E1["✅ Persistent context"]
|
|
F --> F1["✅ Parallel execution"]
|
|
G --> G1["✅ Auto-invoked expertise"]
|
|
```
|
|
|
|
### Selection Decision Tree
|
|
|
|
```mermaid
|
|
graph TD
|
|
Start["Need to extend Claude?"]
|
|
|
|
Start -->|Quick repeated task| A{"Manual or Auto?"}
|
|
A -->|Manual| B["Slash Command"]
|
|
A -->|Auto| C["Skill"]
|
|
|
|
Start -->|Need external data| D{"Real-time?"}
|
|
D -->|Yes| E["MCP Protocol"]
|
|
D -->|No/Cross-session| F["Memory"]
|
|
|
|
Start -->|Complex project| G{"Multiple roles?"}
|
|
G -->|Yes| H["Subagents"]
|
|
G -->|No| I["Skills + Memory"]
|
|
|
|
Start -->|Long-term context| J["Memory"]
|
|
Start -->|Team workflow| K["Slash Command +<br/>Memory"]
|
|
Start -->|Full automation| L["Skills +<br/>Subagents +<br/>MCP"]
|
|
```
|
|
|
|
---
|
|
|
|
## Summary Table
|
|
|
|
| Aspect | Slash Commands | Subagents | Memory | MCP | Skills | Plugins |
|
|
|--------|---|---|---|---|---|---|
|
|
| **Setup Difficulty** | Easy | Medium | Easy | Medium | Medium | Easy |
|
|
| **Learning Curve** | Low | Medium | Low | Medium | Medium | Low |
|
|
| **Team Benefit** | High | High | Medium | High | High | Very High |
|
|
| **Automation Level** | Low | High | Medium | High | High | Very High |
|
|
| **Context Management** | Single-session | Isolated | Persistent | Real-time | Persistent | All features |
|
|
| **Maintenance Burden** | Low | Medium | Low | Medium | Medium | Low |
|
|
| **Scalability** | Good | Excellent | Good | Excellent | Excellent | Excellent |
|
|
| **Shareability** | Fair | Fair | Good | Good | Good | Excellent |
|
|
| **Versioning** | Manual | Manual | Manual | Manual | Manual | Automatic |
|
|
| **Installation** | Manual copy | Manual config | N/A | Manual config | Manual copy | One command |
|
|
|
|
---
|
|
|
|
## Quick Start Guide
|
|
|
|
### Week 1: Start Simple
|
|
- Create 2-3 slash commands for common tasks
|
|
- Enable Memory in Settings
|
|
- Document team standards in CLAUDE.md
|
|
|
|
### Week 2: Add Real-time Access
|
|
- Set up 1 MCP (GitHub or Database)
|
|
- Use `/mcp` to configure
|
|
- Query live data in your workflows
|
|
|
|
### Week 3: Distribute Work
|
|
- Create first Subagent for specific role
|
|
- Use `/agents` command
|
|
- Test delegation with simple task
|
|
|
|
### Week 4: Automate Everything
|
|
- Create first Skill for repeated automation
|
|
- Use Skill marketplace or build custom
|
|
- Combine all features for full workflow
|
|
|
|
### Ongoing
|
|
- Review and update Memory monthly
|
|
- Add new Skills as patterns emerge
|
|
- Optimize MCP queries
|
|
- Refine Subagent prompts
|
|
|
|
---
|
|
|
|
## Hooks
|
|
|
|
### Overview
|
|
|
|
Hooks are event-driven shell commands that execute automatically in response to Claude Code events. They enable automation, validation, and custom workflows without manual intervention.
|
|
|
|
### Hook Types
|
|
|
|
| Hook Type | Event | Use Cases |
|
|
|-----------|-------|-----------|
|
|
| **Tool Hooks** | PreToolUse:*, PostToolUse:* | Auto-formatting, validation, logging |
|
|
| **Session Hooks** | UserPromptSubmit, SessionStart, SessionEnd | Input validation, initialization, cleanup |
|
|
| **Git Hooks** | PreCommit, PostCommit, PrePush | Testing, linting, notifications |
|
|
|
|
### Common Hooks
|
|
|
|
```bash
|
|
# Pre-commit hook - run tests
|
|
PreCommit: "npm test"
|
|
|
|
# Post-write hook - format code
|
|
PostToolUse:Write: "prettier --write ${file_path}"
|
|
|
|
# Pre-tool-use hook - validate
|
|
PreToolUse:Edit: "eslint ${file_path}"
|
|
|
|
# User prompt validation
|
|
UserPromptSubmit: "~/.claude/hooks/validate-prompt.sh"
|
|
```
|
|
|
|
### Hook Variables
|
|
|
|
- `${file_path}` - Path to file being edited/written
|
|
- `${command}` - Command being executed (Bash hooks)
|
|
- `${tool_name}` - Name of tool being used
|
|
- `${session_id}` - Current session identifier
|
|
|
|
### Best Practices
|
|
|
|
✅ **Do:**
|
|
- Keep hooks fast (< 1 second)
|
|
- Use hooks for validation and automation
|
|
- Handle errors gracefully
|
|
- Use absolute paths
|
|
|
|
❌ **Don't:**
|
|
- Make hooks interactive
|
|
- Use hooks for long-running tasks
|
|
- Hardcode credentials
|
|
|
|
**See**: [07-hooks/](07-hooks/) for detailed examples
|
|
|
|
---
|
|
|
|
## Checkpoints and Rewind
|
|
|
|
### Overview
|
|
|
|
Checkpoints allow you to save conversation state and rewind to previous points, enabling safe experimentation and exploration of multiple approaches.
|
|
|
|
### Key Concepts
|
|
|
|
| Concept | Description |
|
|
|---------|-------------|
|
|
| **Checkpoint** | Snapshot of conversation state including messages, files, and context |
|
|
| **Rewind** | Return to a previous checkpoint, discarding subsequent changes |
|
|
| **Branch Point** | Checkpoint from which multiple approaches are explored |
|
|
|
|
### Commands
|
|
|
|
```bash
|
|
# Create checkpoint
|
|
/checkpoint save "Before refactoring"
|
|
|
|
# List checkpoints
|
|
/checkpoint list
|
|
|
|
# Rewind to checkpoint
|
|
/checkpoint rewind "Before refactoring"
|
|
|
|
# Compare checkpoints
|
|
/checkpoint diff checkpoint-1 checkpoint-2
|
|
|
|
# Delete checkpoint
|
|
/checkpoint delete checkpoint-1
|
|
|
|
# Export checkpoint
|
|
/checkpoint export "name" ~/checkpoints/backup.json
|
|
```
|
|
|
|
### Use Cases
|
|
|
|
| Scenario | Workflow |
|
|
|----------|----------|
|
|
| **Exploring Approaches** | Save → Try A → Save → Rewind → Try B → Compare |
|
|
| **Safe Refactoring** | Save → Refactor → Test → If fail: Rewind |
|
|
| **A/B Testing** | Save → Design A → Save → Rewind → Design B → Compare |
|
|
| **Mistake Recovery** | Notice issue → Rewind to last good state |
|
|
|
|
### Configuration
|
|
|
|
```json
|
|
{
|
|
"checkpoints": {
|
|
"autoCheckpoint": true,
|
|
"autoCheckpointInterval": 30,
|
|
"maxCheckpoints": 20,
|
|
"compressionEnabled": true
|
|
}
|
|
}
|
|
```
|
|
|
|
**See**: [08-checkpoints/](08-checkpoints/) for detailed examples
|
|
|
|
---
|
|
|
|
## Advanced Features
|
|
|
|
### Planning Mode
|
|
|
|
Create detailed implementation plans before coding.
|
|
|
|
**Activation:**
|
|
```bash
|
|
/plan Implement user authentication system
|
|
```
|
|
|
|
**Benefits:**
|
|
- Clear roadmap with time estimates
|
|
- Risk assessment
|
|
- Systematic task breakdown
|
|
- Opportunity for review and modification
|
|
|
|
### Extended Thinking
|
|
|
|
Deep reasoning for complex problems.
|
|
|
|
**Activation:**
|
|
```bash
|
|
/think Should we use microservices or monolith?
|
|
```
|
|
|
|
**Benefits:**
|
|
- Thorough analysis of trade-offs
|
|
- Better architectural decisions
|
|
- Consideration of edge cases
|
|
- Systematic evaluation
|
|
|
|
### Background Tasks
|
|
|
|
Run long operations without blocking the conversation.
|
|
|
|
**Usage:**
|
|
```bash
|
|
User: Run tests in background
|
|
|
|
Claude: Started task bg-1234
|
|
|
|
/task list # Show all tasks
|
|
/task status bg-1234 # Check progress
|
|
/task show bg-1234 # View output
|
|
/task cancel bg-1234 # Cancel task
|
|
```
|
|
|
|
### Permission Modes
|
|
|
|
Control what Claude can do.
|
|
|
|
| Mode | Description | Use Case |
|
|
|------|-------------|----------|
|
|
| **Unrestricted** | Full access (default) | Active development |
|
|
| **Confirm** | Ask before actions | Learning, pair programming |
|
|
| **Read-only** | Analysis only | Code review |
|
|
| **Custom** | Granular permissions | Fine-tuned control |
|
|
|
|
**Commands:**
|
|
```bash
|
|
/permission readonly # Code review mode
|
|
/permission confirm # Learning mode
|
|
/permission unrestricted # Full automation
|
|
```
|
|
|
|
### Headless Mode
|
|
|
|
Run Claude Code without interactive input for automation and CI/CD.
|
|
|
|
**Usage:**
|
|
```bash
|
|
# Run specific task
|
|
claude-code --headless --task "Run all tests"
|
|
|
|
# From script file
|
|
claude-code --headless --script ./deploy.claude
|
|
|
|
# CI/CD integration (GitHub Actions)
|
|
- name: AI Code Review
|
|
run: claude-code --headless --task "Review PR"
|
|
```
|
|
|
|
### Session Management
|
|
|
|
Manage multiple work sessions.
|
|
|
|
**Commands:**
|
|
```bash
|
|
/session list # Show all sessions
|
|
/session new "Feature" # Create new session
|
|
/session switch "Bug" # Switch sessions
|
|
/session save # Save current state
|
|
/session load "name" # Load saved session
|
|
```
|
|
|
|
### Interactive Features
|
|
|
|
**Keyboard Shortcuts:**
|
|
- `Ctrl + R` - Search command history
|
|
- `Tab` - Autocomplete
|
|
- `↑ / ↓` - Command history
|
|
- `Ctrl + L` - Clear screen
|
|
|
|
**Multi-line Input:**
|
|
```bash
|
|
User: \
|
|
> Long complex prompt
|
|
> spanning multiple lines
|
|
> \end
|
|
```
|
|
|
|
### Configuration
|
|
|
|
Complete configuration example:
|
|
|
|
```json
|
|
{
|
|
"planning": {
|
|
"autoEnter": true,
|
|
"requireApproval": true
|
|
},
|
|
"extendedThinking": {
|
|
"enabled": true,
|
|
"showThinkingProcess": true
|
|
},
|
|
"backgroundTasks": {
|
|
"enabled": true,
|
|
"maxConcurrentTasks": 5
|
|
},
|
|
"permissions": {
|
|
"mode": "unrestricted"
|
|
},
|
|
"headless": {
|
|
"exitOnError": true,
|
|
"verbose": true
|
|
}
|
|
}
|
|
```
|
|
|
|
**See**: [09-advanced-features/](09-advanced-features/) for comprehensive guide
|
|
|
|
---
|
|
|
|
## Resources
|
|
|
|
- [Claude Documentation](https://docs.claude.com)
|
|
- [MCP GitHub Servers](https://github.com/modelcontextprotocol/servers)
|
|
- [Skills Cookbook](https://github.com/anthropic-ai/skills)
|
|
- [Claude Code Guide](https://docs.claude.com/en/docs/claude-code/overview)
|
|
|
|
---
|
|
|
|
*Last updated: November 8, 2025*
|
|
*For Claude Haiku 4.5, Sonnet 4.5, and Opus 4.1*
|
|
*Now includes: Hooks, Checkpoints, Planning Mode, Extended Thinking, Background Tasks, Permission Modes, Headless Mode, and Session Management*
|