marketing-shibata50/claude-code-ultimate-guide
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
claude-code-ultimate-guide/english-ultimate-claude-code-guide.md
Florian BRUNIAUX afd9cb6f20 docs: add complete Claude Code ultimate guide content 
- Add comprehensive guide (4000+ lines) covering all Claude Code features
- Add printable cheatsheet for daily reference
- Add PDF versions (NotebookLM podcast, Kimi export)
- Update README with author context, inspiration sources, and contact info
- Change license from MIT to CC BY-SA 4.0 for content sharing

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-09 15:18:49 +01:00

4365 lines
119 KiB
Markdown
Raw Blame History

# The Ultimate Claude Code Guide
> A comprehensive, self-contained guide to mastering Claude Code - from zero to power user.
**Author**: Florian BRUNIAUX | Founding Engineer [@Méthode Aristote](https://methode-aristote.fr)
**Written with**: Claude (Anthropic)
**Reading time**: ~2.5 hours (full) | ~15 minutes (Quick Start only)
**Last updated**: January 2025
**Version**: 1.0
---
## TL;DR - The 5-Minute Summary
If you only have 5 minutes, here's what you need to know:
### Essential Commands
```bash
claude # Start Claude Code
/help # Show all commands
/status # Check context usage
/compact # Compress context when >70%
/clear # Fresh start
/plan # Safe read-only mode
Ctrl+C # Cancel operation
```
### The Workflow
```
Describe → Claude Analyzes → Review Diff → Accept/Reject → Verify
```
### Context Management (Critical!)
| Context % | Action |
|-----------|--------|
| 0-50% | Work freely |
| 50-70% | Be selective |
| 70-90% | `/compact` now |
| 90%+ | `/clear` required |
### Configuration Priority
```
~/.claude/CLAUDE.md → Global (all projects)
/project/CLAUDE.md → Project (committed)
/project/.claude/ → Personal (not committed)
```
### Power Features
| Feature | What It Does |
|---------|--------------|
| **Agents** | Specialized AI personas for specific tasks |
| **Skills** | Reusable knowledge modules |
| **Hooks** | Automation scripts triggered by events |
| **MCP Servers** | External tools (Serena, Context7, Playwright...) |
### The Golden Rules
1. **Always review diffs** before accepting changes
2. **Use `/compact`** before context gets critical
3. **Be specific** in your requests (WHAT, WHERE, HOW, VERIFY)
4. **Start with Plan Mode** for complex/risky tasks
5. **Create CLAUDE.md** for every project
### Quick Decision Tree
```
Simple task → Just ask Claude
Complex task → Use TodoWrite to plan
Risky change → Enter Plan Mode first
Repeating task → Create an agent or command
Context full → /compact or /clear
```
**Now read Section 1 for the full Quick Start, or jump to any section you need.**
---
## Table of Contents
- [1. Quick Start (Day 1)](#1-quick-start-day-1)
- [1.1 Installation](#11-installation)
- [1.2 First Workflow](#12-first-workflow)
- [1.3 Essential Commands](#13-essential-commands)
- [1.4 Permission Modes](#14-permission-modes)
- [1.5 Productivity Checklist](#15-productivity-checklist)
- [2. Core Concepts](#2-core-concepts)
- [2.1 The Interaction Loop](#21-the-interaction-loop)
- [2.2 Context Management](#22-context-management)
- [2.3 Plan Mode](#23-plan-mode)
- [2.4 Rewind](#24-rewind)
- [2.5 Mental Model](#25-mental-model)
- [3. Configuration](#3-configuration)
- [3.1 CLAUDE.md Files](#31-claudemd-files)
- [3.2 The .claude/ Folder](#32-the-claude-folder)
- [3.3 Settings & Permissions](#33-settings--permissions)
- [3.4 Precedence Rules](#34-precedence-rules)
- [4. Agents](#4-agents)
- [4.1 What Are Agents](#41-what-are-agents)
- [4.2 Creating Custom Agents](#42-creating-custom-agents)
- [4.3 Agent Template](#43-agent-template)
- [4.4 Best Practices](#44-best-practices)
- [4.5 Agent Examples](#45-agent-examples)
- [5. Skills](#5-skills)
- [5.1 Understanding Skills](#51-understanding-skills)
- [5.2 Creating Skills](#52-creating-skills)
- [5.3 Skill Template](#53-skill-template)
- [5.4 Skill Examples](#54-skill-examples)
- [6. Commands](#6-commands)
- [6.1 Slash Commands](#61-slash-commands)
- [6.2 Creating Custom Commands](#62-creating-custom-commands)
- [6.3 Command Template](#63-command-template)
- [6.4 Command Examples](#64-command-examples)
- [7. Hooks](#7-hooks)
- [7.1 The Event System](#71-the-event-system)
- [7.2 Creating Hooks](#72-creating-hooks)
- [7.3 Hook Templates](#73-hook-templates)
- [7.4 Security Hooks](#74-security-hooks)
- [7.5 Hook Examples](#75-hook-examples)
- [8. MCP Servers](#8-mcp-servers)
- [8.1 What is MCP](#81-what-is-mcp)
- [8.2 Available Servers](#82-available-servers)
- [8.3 Configuration](#83-configuration)
- [8.4 Server Selection Guide](#84-server-selection-guide)
- [9. Advanced Patterns](#9-advanced-patterns)
- [9.1 The Trinity](#91-the-trinity)
- [9.2 Composition Patterns](#92-composition-patterns)
- [9.3 CI/CD Integration](#93-cicd-integration)
- [9.4 IDE Integration](#94-ide-integration)
- [9.5 Tight Feedback Loops](#95-tight-feedback-loops)
- [9.6 Todo as Instruction Mirrors](#96-todo-as-instruction-mirrors)
- [9.7 Output Styles](#97-output-styles)
- [9.8 Vibe Coding & Skeleton Projects](#98-vibe-coding--skeleton-projects)
- [9.9 Batch Operations Pattern](#99-batch-operations-pattern)
- [10. Reference](#10-reference)
- [10.1 Commands Table](#101-commands-table)
- [10.2 Keyboard Shortcuts](#102-keyboard-shortcuts)
- [10.3 Configuration Reference](#103-configuration-reference)
- [10.4 Troubleshooting](#104-troubleshooting)
- [10.5 Cheatsheet](#105-cheatsheet)
- [10.6 Daily Workflow & Checklists](#106-daily-workflow--checklists)
- [Appendix: Templates Collection](#appendix-templates-collection)
- [A.8 Prompt Templates](#a8-prompt-templates)
- [A.9 Success Metrics & Maturity Model](#a9-success-metrics--maturity-model)
---
# 1. Quick Start (Day 1)
**Reading time**: 15 minutes
**Skill level**: Beginner
**Goal**: Go from zero to productive
## 1.1 Installation
Choose your preferred installation method:
### Option A: Shell Script (Recommended)
```bash
curl -fsSL https://claude.ai/install.sh | sh
```
### Option B: npm
```bash
npm install -g @anthropic-ai/claude-code
```
### Option C: Homebrew (macOS)
```bash
brew install claude-code
```
### Verify Installation
```bash
claude --version
```
### First Launch
```bash
cd your-project
claude
```
On first launch:
1. You'll be prompted to authenticate with your Anthropic account
2. Accept the terms of service
3. Claude Code will index your project (may take a few seconds for large codebases)
## 1.2 First Workflow
Let's fix a bug together. This demonstrates the core interaction loop.
### Step 1: Describe the Problem
```
You: There's a bug in the login function - users can't log in with email addresses containing a plus sign
```
### Step 2: Claude Analyzes
Claude will:
- Search your codebase for relevant files
- Read the login-related code
- Identify the issue
- Propose a fix
### Step 3: Review the Diff
```diff
- const emailRegex = /^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+ const emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
```
💡 **Critical**: Always read the diff before accepting. This is your safety net.
### Step 4: Accept or Reject
- Press `y` to accept the change
- Press `n` to reject and ask for alternatives
- Press `e` to edit the change manually
### Step 5: Verify
```
You: Run the tests to make sure this works
```
Claude will run your test suite and report results.
### Step 6: Commit (Optional)
```
You: Commit this fix
```
Claude will create a commit with an appropriate message.
## 1.3 Essential Commands
These 7 commands cover 90% of daily usage:
| Command | Action | When to Use |
|---------|--------|-------------|
| `/help` | Show all commands | When you're lost |
| `/clear` | Clear conversation | Start fresh |
| `/compact` | Summarize context | Running low on context |
| `/status` | Show session info | Check context usage |
| `/exit` or `Ctrl+D` | Exit Claude Code | Done working |
| `/plan` | Enter Plan Mode | Safe exploration |
| `/rewind` | Undo changes | Made a mistake |
### Quick Actions
| Shortcut | Action |
|----------|--------|
| `!command` | Run shell command directly |
| `@file.ts` | Reference a specific file |
| `Ctrl+C` | Cancel current operation |
| `Ctrl+R` | Retry last operation |
| `Esc` | Dismiss current suggestion |
## 1.4 Permission Modes
Claude Code has three permission modes that control how much autonomy Claude has:
### Default Mode
Claude asks permission before:
- Editing files
- Running commands
- Making commits
This is the safest mode for learning.
### Auto-accept Mode
```
You: Turn on auto-accept for the rest of this session
```
Claude will execute changes without asking. Use when you trust the operation and want speed.
⚠️ **Warning**: Only use auto-accept for well-defined, reversible operations.
### Plan Mode
```
/plan
```
Claude can only read and analyze - no modifications allowed. Perfect for:
- Understanding unfamiliar code
- Exploring architectural options
- Safe investigation before changes
Exit with `/execute` when ready to make changes.
## 1.5 Productivity Checklist
You're ready for Day 2 when you can:
- [ ] Launch Claude Code in your project
- [ ] Describe a task and review the proposed changes
- [ ] Accept or reject changes after reading the diff
- [ ] Run a shell command with `!`
- [ ] Reference a file with `@`
- [ ] Use `/clear` to start fresh
- [ ] Use `/status` to check context usage
- [ ] Exit cleanly with `/exit` or `Ctrl+D`
---
# 2. Core Concepts
**Reading time**: 20 minutes
**Skill level**: Day 1-3
**Goal**: Understand how Claude Code thinks
## 2.1 The Interaction Loop
Every Claude Code interaction follows this pattern:
```
┌─────────────────────────────────────────────────────────┐
│ INTERACTION LOOP │
├─────────────────────────────────────────────────────────┤
│ │
│ 1. DESCRIBE ──→ You explain what you need │
│ │ │
│ ▼ │
│ 2. ANALYZE ──→ Claude explores the codebas │
│ │ │
│ ▼ │
│ 3. PROPOSE ──→ Claude suggests changes (diff) │
│ │ │
│ ▼ │
│ 4. REVIEW ──→ You read and evaluate │
│ │ │
│ ▼ │
│ 5. DECIDE ──→ Accept / Reject / Modify │
│ │ │
│ ▼ │
│ 6. VERIFY ──→ Run tests, check behavior │
│ │ │
│ ▼ │
│ 7. COMMIT ──→ Save changes (optional) │
│ │
└─────────────────────────────────────────────────────────┘
```
### Key Insight
The loop is designed so that **you remain in control**. Claude proposes, you decide.
## 2.2 Context Management
🔴 **This is the most important concept in Claude Code.**
### What is Context?
Context is Claude's "working memory" for your conversation. It includes:
- All messages in the conversation
- Files Claude has read
- Command outputs
- Tool results
### The Context Budget
Claude has a **200,000 token** context window. Think of it like RAM - when it fills up, things slow down or fail.
### Reading the Statusline
The statusline shows your context usage:
```
Claude Code │ Ctx(u): 45% │ Cost: $0.23 │ Session: 1h 23m
```
| Metric | Meaning |
|--------|---------|
| `Ctx(u): 45%` | You've used 45% of context |
| `Cost: $0.23` | API cost so far |
| `Session: 1h 23m` | Time elapsed |
### Context Zones
| Zone | Usage | Action |
|------|-------|--------|
| 🟢 Green | 0-50% | Work freely |
| 🟡 Yellow | 50-75% | Start being selective |
| 🔴 Red | 75-90% | Use `/compact` or `/clear` |
| ⚫ Critical | 90%+ | Must clear or risk errors |
### Context Recovery Strategies
When context gets high:
**Option 1: Compact** (`/compact`)
- Summarizes the conversation
- Preserves key context
- Reduces usage by ~50%
**Option 2: Clear** (`/clear`)
- Starts fresh
- Loses all context
- Use when changing topics
**Option 3: Targeted Approach**
- Be specific in queries
- Avoid "read the entire file"
- Use symbol references: "read the `calculateTotal` function"
### What Consumes Context?
| Action | Context Cost |
|--------|--------------|
| Reading a small file | Low (~500 tokens) |
| Reading a large file | High (~5K+ tokens) |
| Running commands | Medium (~1K tokens) |
| Multi-file search | High (~3K+ tokens) |
| Long conversations | Accumulates |
### Context Depletion Symptoms
Learn to recognize when context is running out:
| Symptom | Severity | Action |
|---------|----------|--------|
| Shorter responses than usual | 🟡 Warning | Continue with caution |
| Forgetting CLAUDE.md instructions | 🟠 Serious | Document state, prepare checkpoint |
| Inconsistencies with earlier conversation | 🔴 Critical | New session needed |
| Errors on code already discussed | 🔴 Critical | New session needed |
| "I can't access that file" (when it was read) | 🔴 Critical | New session immediately |
### Context Inspection
Check your context usage in detail:
```
/context
```
Example output:
```
┌─────────────────────────────────────────────────────────────┐
│ CONTEXT USAGE 67% used │
├─────────────────────────────────────────────────────────────┤
│ System Prompt ████████░░░░░░░░░░░░░░░░ 12,450 tk │
│ System Tools ██░░░░░░░░░░░░░░░░░░░░░░ 3,200 tk │
│ MCP Tools (5 servers) ████████████░░░░░░░░░░░░ 18,600 tk │
│ Conversation ████████████████████░░░░ 89,200 tk │
├─────────────────────────────────────────────────────────────┤
│ TOTAL 123,450 tk │
│ REMAINING 76,550 tk │
└─────────────────────────────────────────────────────────────┘
```
💡 **The Last 20% Rule**: Reserve ~20% of context for:
- Multi-file operations at end of session
- Last-minute corrections
- Generating summary/checkpoint
### Context Poisoning (Bleeding)
**Definition**: When information from one task contaminates another.
**Pattern 1: Style Bleeding**
```
Task 1: "Create a blue button"
Claude: [Creates blue button]
Task 2: "Create a form"
Claude: [Creates form... with all buttons blue!]
↑ The "blue" bled into the new task
Solution: Use explicit boundaries
"---NEW TASK---
Create a form. Use default design system colors."
```
**Pattern 2: Instruction Contamination**
```
Instruction 1: "Always use arrow functions"
Instruction 2: "Follow project conventions" (which uses function)
Claude: [Paralyzed, alternating between styles]
Solution: Clarify priority
"In case of conflict, project conventions take precedence over my preferences."
```
**Pattern 3: Temporal Confusion**
```
Early session: "auth.ts contains login logic"
... 2h of work ...
You renamed auth.ts to authentication.ts
Claude: "I'll modify auth.ts..."
↑ Using outdated info
Solution: Explicit updates
"Note: auth.ts was renamed to authentication.ts"
```
**Context Hygiene Checklist**:
- [ ] New tasks = explicit markdown boundaries
- [ ] Structural changes = inform Claude explicitly
- [ ] Contradictory instructions = clarify priority
- [ ] Long session (>2h) = consider `/clear` or new session
- [ ] Erratic behavior = check with `/context`
### Sanity Check Technique
Verify that Claude has loaded your configuration correctly.
**Simple Method**:
1. Add at the top of CLAUDE.md:
```markdown
# My name is [Your Name]
# Project: [Project Name]
# Stack: [Your tech stack]
```
2. Ask Claude: "What is my name? What project am I working on?"
3. If correct → Configuration loaded properly
**Advanced: Multiple Checkpoints**
```markdown
# === CHECKPOINT 1 === Project: MyApp ===
[... 500 lines of instructions ...]
# === CHECKPOINT 2 === Stack: Next.js ===
[... 500 lines of instructions ...]
# === CHECKPOINT 3 === Owner: [Name] ===
```
Ask "What is checkpoint 2?" to verify Claude read that far.
| Failure Symptom | Probable Cause | Solution |
|-----------------|----------------|----------|
| Doesn't know your name | CLAUDE.md not loaded | Check file location |
| Inconsistent answers | Typo in filename | Must be `CLAUDE.md` (not `clause.md`) |
| Partial knowledge | Context exhausted | `/clear` or new session |
## 2.3 Plan Mode
Plan Mode is Claude Code's "look but don't touch" mode.
### Entering Plan Mode
```
/plan
```
Or ask Claude directly:
```
You: Let's plan this feature before implementing
```
### What Plan Mode Allows
- ✅ Reading files
- ✅ Searching the codebase
- ✅ Analyzing architecture
- ✅ Proposing approaches
- ✅ Writing to a plan file
### What Plan Mode Prevents
- ❌ Editing files
- ❌ Running commands that modify state
- ❌ Creating new files
- ❌ Making commits
### When to Use Plan Mode
| Situation | Use Plan Mode? |
|-----------|----------------|
| Exploring unfamiliar codebase | ✅ Yes |
| Investigating a bug | ✅ Yes |
| Planning a new feature | ✅ Yes |
| Fixing a typo | ❌ No |
| Quick edit to known file | ❌ No |
### Exiting Plan Mode
```
/execute
```
Or Claude will ask: "Ready to implement this plan?"
### Auto Plan Mode
**Concept**: Automatically trigger planning mode before any risky operation.
**Configuration File** (`~/.claude/auto-plan-mode.txt`):
```
Before executing ANY tool (Read, Write, Edit, Bash, Grep, Glob, WebSearch), you MUST:
1. FIRST: Use exit_plan_mode tool to present your plan
2. WAIT: For explicit user approval before proceeding
3. ONLY THEN: Execute the planned actions
Each new user request requires a fresh plan - previous approvals don't carry over.
```
**Launch with Auto Plan Mode**:
```bash
# Direct
claude --append-system-prompt "Before executing ANY tool..."
# Via file (recommended)
claude --append-system-prompt "$(cat ~/.claude/auto-plan-mode.txt)"
# Alias in .zshrc/.bashrc
alias claude-safe='claude --append-system-prompt "$(cat ~/.claude/auto-plan-mode.txt)"'
```
**Resulting Workflow**:
```
User: "Add an email field to the User model"
Claude (Auto Plan Mode active):
┌─────────────────────────────────────────────────────────────┐
│ 📋 PROPOSED PLAN │
│ │
│ 1. Read schema.prisma to understand current model │
│ 2. Add field email: String? @unique │
│ 3. Generate Prisma migration │
│ 4. Update TypeScript types │
│ 5. Add Zod validation in routers │
│ │
│ ⚠️ Impact: 3 files modified, 1 migration created │
│ │
│ Approve this plan? (y/n) │
└─────────────────────────────────────────────────────────────┘
User: "y"
Claude: [Executes the plan]
```
**Result**: 76% fewer tokens with better results because the plan is validated before execution.
## 2.4 Rewind
Rewind is Claude Code's undo mechanism.
### Using Rewind
```
/rewind
```
Or:
```
You: Undo the last change
```
### What Rewind Does
- Reverts file changes
- Restores previous state
- Works across multiple files
### Limitations
- Only works on Claude's changes (not manual edits)
- Works within the current session
- Git commits are NOT automatically reverted
### Best Practice: Checkpoint Before Risk
Before a risky operation:
```
You: Let's commit what we have before trying this experimental approach
```
This creates a git checkpoint you can always return to.
## 2.5 Mental Model
Understanding how Claude Code "thinks" makes you more effective.
### Claude's View of Your Project
```
┌─────────────────────────────────────────────────────────┐
│ YOUR PROJECT │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │
│ │ Files │ │ Git │ │ Config │ │
│ │ (.ts,.py) │ │ History │ │ Files │ │
│ └─────────────┘ └─────────────┘ └───────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Claude's Understanding │ │
│ │ - File structure & relationships │ │
│ │ - Code patterns & conventions │ │
│ │ - Recent changes (from git) │ │
│ │ - Project rules (from CLAUDE.md) │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
### What Claude Knows
1. **File Structure**: Claude can navigate and search your files
2. **Code Content**: Claude can read and understand code
3. **Git State**: Claude sees branches, commits, changes
4. **Project Rules**: Claude reads CLAUDE.md for conventions
### What Claude Doesn't Know
1. **Runtime State**: Claude can't see running processes
2. **External Services**: Claude can't access your databases directly
3. **Your Intent**: Claude needs clear instructions
4. **Hidden Files**: Claude respects .gitignore by default
### Communicating Effectively
**Good prompt**:
```
The login function in src/auth/login.ts isn't validating email addresses properly.
Plus signs should be allowed but they're being rejected.
```
**Weak prompt**:
```
Login is broken
```
The more context you provide, the better Claude can help.
---
# 3. Configuration
**Reading time**: 15 minutes
**Skill level**: Week 1
**Goal**: Customize Claude Code for your project
## 3.1 CLAUDE.md Files
CLAUDE.md files are persistent instructions that Claude reads at the start of every session.
### Three Levels of Configuration
```
┌─────────────────────────────────────────────────────────┐
│ CONFIGURATION HIERARCHY │
├─────────────────────────────────────────────────────────┤
│ │
│ ~/.claude/CLAUDE.md (Global - All projects) │
│ │ │
│ ▼ │
│ /project/CLAUDE.md (Project - This repo) │
│ │ │
│ ▼ │
│ /project/.claude/CLAUDE.md (Local - Personal prefs) │
│ │
│ Priority: Local > Project > Global │
│ │
└─────────────────────────────────────────────────────────┘
```
### Level 1: Global (~/.claude/CLAUDE.md)
Personal preferences that apply to all your projects:
```markdown
# Global Claude Code Settings
## Communication Style
- Be concise in responses
- Use code examples over explanations
- Ask clarifying questions before major changes
## Preferred Tools
- Use TypeScript over JavaScript
- Prefer pnpm over npm
- Use Prettier for formatting
## Safety Rules
- Always run tests before committing
- Never force push to main
- Check for secrets before committing
```
### Level 2: Project (/project/CLAUDE.md)
Shared team conventions checked into version control:
```markdown
# Project: MyApp
## Tech Stack
- Next.js 14 with App Router
- TypeScript 5.3
- PostgreSQL with Prisma
- TailwindCSS
## Code Conventions
- Use functional components
- Use `const` arrow functions
- File naming: kebab-case (my-component.tsx)
## Architecture
- API routes in /app/api
- Components in /components
- Database queries in /lib/db
## Commands
- `pnpm dev` - Start development
- `pnpm test` - Run tests
- `pnpm lint` - Check linting
```
### Level 3: Local (/project/.claude/CLAUDE.md)
Personal overrides not committed to git (add to .gitignore):
```markdown
# My Local Preferences
## Overrides
- Skip pre-commit hooks for quick iterations
- Use verbose logging during debugging
```
### CLAUDE.md Best Practices
| Do | Don't |
|-----|-------|
| Keep it concise | Write essays |
| Include examples | Be vague |
| Update when conventions change | Let it go stale |
| Reference external docs | Duplicate documentation |
## 3.2 The .claude/ Folder
The `.claude/` folder is your project's Claude Code configuration directory.
### Full Structure
```
.claude/
├── CLAUDE.md # Local instructions (gitignored)
├── settings.json # Hook configuration
├── settings.local.json # Personal permissions (gitignored)
├── agents/ # Custom agent definitions
│ ├── README.md
│ ├── backend-architect.md
│ ├── code-reviewer.md
│ └── ...
├── commands/ # Custom slash commands
│ ├── tech/
│ │ ├── commit.md
│ │ └── pr.md
│ ├── product/
│ │ └── problem-framer.md
│ └── support/
│ └── support-assistant.md
├── hooks/ # Event-driven scripts
│ ├── README.md
│ ├── auto-format.sh
│ └── git-context.sh
├── rules/ # Auto-loaded conventions
│ ├── code-conventions.md
│ └── git-workflow.md
├── skills/ # Knowledge modules
│ ├── README.md
│ └── security-guardian/
│ ├── SKILL.md
│ └── checklists/
└── plans/ # Saved plan files
```
### What Goes Where
| Content Type | Location | Shared? |
|--------------|----------|---------|
| Team conventions | `rules/` | ✅ Commit |
| Reusable agents | `agents/` | ✅ Commit |
| Team commands | `commands/` | ✅ Commit |
| Automation hooks | `hooks/` | ✅ Commit |
| Knowledge modules | `skills/` | ✅ Commit |
| Personal preferences | `CLAUDE.md` | ❌ Gitignore |
| Personal permissions | `settings.local.json` | ❌ Gitignore |
## 3.3 Settings & Permissions
### settings.json (Team Configuration)
This file configures hooks and is committed to the repo:
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash|Edit|Write",
"hooks": [
{
"type": "command",
"command": ".claude/hooks/security-check.sh",
"timeout": 5000
}
]
}
],
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": ".claude/hooks/auto-format.sh"
}
]
}
],
"UserPromptSubmit": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": ".claude/hooks/git-context.sh"
}
]
}
]
}
}
```
### settings.local.json (Personal Permissions)
Personal permission overrides (gitignored):
```json
{
"permissions": {
"allow": [
"Bash(git *)",
"Bash(pnpm *)",
"Bash(npm test)",
"Edit",
"Write",
"WebSearch"
],
"deny": [
"Bash(rm -rf *)",
"Bash(sudo *)"
],
"ask": [
"Bash(npm publish)",
"Bash(git push --force)"
]
}
}
```
### Permission Patterns
| Pattern | Matches |
|---------|---------|
| `Bash(git *)` | Any git command |
| `Bash(pnpm *)` | Any pnpm command |
| `Edit` | All file edits |
| `Write` | All file writes |
| `WebSearch` | Web search capability |
| `mcp__serena__*` | All Serena MCP tools |
### Permission Behavior
| Category | Behavior |
|----------|----------|
| `allow` | Auto-approve without asking |
| `deny` | Block completely |
| `ask` | Prompt for confirmation |
| (default) | Use default permission mode |
### allowedTools Configuration (Alternative)
For granular control, use `~/.claude.json`:
```json
{
"allowedTools": [
"Read(*)",
"Grep(*)",
"Glob(*)",
"WebFetch(*)",
"TodoRead",
"TodoWrite",
"Task(*)",
"Bash(git status:*)",
"Bash(git diff:*)",
"Bash(git log:*)",
"Bash(pnpm typecheck:*)",
"Bash(pnpm lint:*)",
"Bash(pnpm test:*)"
]
}
```
**Pattern Logic**:
| Pattern | Meaning | Example |
|---------|---------|---------|
| `Read(*)` | All reads | Any file |
| `Bash(git status:*)` | Specific command | `git status` allowed |
| `Bash(pnpm *:*)` | Command prefix | `pnpm test`, `pnpm build` |
| `Edit(*)` | All edits | ⚠️ Dangerous |
**Progressive Permission Levels**:
**Level 1 - Beginner (very restrictive)**:
```json
{
"allowedTools": ["Read(*)", "Grep(*)", "Glob(*)"]
}
```
**Level 2 - Intermediate**:
```json
{
"allowedTools": [
"Read(*)", "Grep(*)", "Glob(*)",
"Bash(git:*)", "Bash(pnpm:*)",
"TodoRead", "TodoWrite"
]
}
```
**Level 3 - Advanced**:
```json
{
"allowedTools": [
"Read(*)", "Grep(*)", "Glob(*)", "WebFetch(*)",
"Edit(*)", "Write(*)",
"Bash(git:*)", "Bash(pnpm:*)", "Bash(npm:*)",
"Task(*)", "TodoRead", "TodoWrite"
]
}
```
⚠️ **Never use `--dangerously-skip-permissions`**
Horror stories from r/ClaudeAI include:
- `rm -rf node_modules` followed by `rm -rf .` (path error)
- `git push --force` to main unintentionally
- `DROP TABLE users` in a poorly generated migration
- Deletion of `.env` files with credentials
**Always prefer granular `allowedTools` over disabling permissions entirely.**
### Dynamic Memory (Profile Switching)
**Concept**: Temporarily modify CLAUDE.md for specific tasks, then restore.
**Technique 1: Git Stash**
```bash
# Before modification
git stash push -m "CLAUDE.md original" CLAUDE.md
# Claude modifies CLAUDE.md for specific task
# ... work ...
# After task
git stash pop
```
**Technique 2: Profile Library**
```
~/.claude/profiles/
├── default.md # General config
├── security-audit.md # For security audits
├── refactoring.md # For major refactoring
├── documentation.md # For writing docs
└── debugging.md # For debug sessions
```
**Profile Switch Script**:
```bash
#!/bin/bash
# ~/.local/bin/claude-profile
PROFILE=$1
cp ~/.claude/profiles/${PROFILE}.md ./CLAUDE.md
echo "Switched to profile: $PROFILE"
```
Usage:
```bash
claude-profile security-audit
claude # Launches with security profile
```
**Technique 3: Parallel Instances**
```bash
# Terminal 1: Main project
cd ~/projects/myapp
claude # Loads myapp's CLAUDE.md
# Terminal 2: Worktree for isolated feature
cd ~/projects/myapp-feature-x
# Different CLAUDE.md, isolated context
claude
```
## 3.4 Precedence Rules
When configurations conflict, Claude Code uses this precedence:
### Configuration Precedence
```
Highest Priority
│
▼
┌──────────────────────────────────┐
│ settings.local.json │ Personal overrides
└──────────────────────────────────┘
│
▼
┌──────────────────────────────────┐
│ settings.json │ Project settings
└──────────────────────────────────┘
│
▼
┌──────────────────────────────────┐
│ ~/.claude/settings.json │ Global defaults
└──────────────────────────────────┘
│
▼
Lowest Priority
```
### CLAUDE.md Precedence
```
Highest Priority
│
▼
┌──────────────────────────────────┐
│ .claude/CLAUDE.md │ Local (personal)
└──────────────────────────────────┘
│
▼
┌──────────────────────────────────┐
│ /project/CLAUDE.md │ Project (team)
└──────────────────────────────────┘
│
▼
┌──────────────────────────────────┐
│ ~/.claude/CLAUDE.md │ Global (personal)
└──────────────────────────────────┘
│
▼
Lowest Priority
```
### Rules Auto-Loading
Files in `.claude/rules/` are automatically loaded and combined:
```
.claude/rules/
├── code-conventions.md ──┐
├── git-workflow.md ──┼──→ All loaded automatically
└── architecture.md ──┘
```
---
# 4. Agents
**Reading time**: 20 minutes
**Skill level**: Week 1-2
**Goal**: Create specialized AI assistants
## 4.1 What Are Agents
Agents are specialized sub-processes that Claude can delegate tasks to.
### Why Use Agents?
| Without Agents | With Agents |
|----------------|-------------|
| One Claude doing everything | Specialized experts for each domain |
| Context gets cluttered | Each agent has focused context |
| Generic responses | Domain-specific expertise |
| Manual tool selection | Pre-configured tool access |
### Agent vs Direct Prompt
```
Direct Prompt:
You: Review this code for security issues, focusing on OWASP Top 10,
checking for SQL injection, XSS, CSRF, and authentication vulnerabilities...
With Agent:
You: Use the security-reviewer agent to audit this code
```
The agent encapsulates all that expertise.
### Built-in vs Custom Agents
| Type | Source | Example |
|------|--------|---------|
| Built-in | Claude Code default | Explore, Plan |
| Custom | Your `.claude/agents/` | Backend architect, Code reviewer |
## 4.2 Creating Custom Agents
Agents are markdown files in `.claude/agents/` with YAML frontmatter.
### Agent File Structure
```markdown
---
name: agent-name
description: Clear activation trigger (50-100 chars)
model: sonnet
tools: Read, Write, Edit, Bash, Grep, Glob
skills:
- skill-name
disallowedTools:
- WebSearch
---
[Markdown instructions for the agent]
```
### Frontmatter Fields
| Field | Required | Description |
|-------|----------|-------------|
| `name` | ✅ | Kebab-case identifier |
| `description` | ✅ | When to activate this agent |
| `model` | ❌ | `sonnet` (default), `opus`, or `haiku` |
| `tools` | ❌ | Allowed tools (comma-separated) |
| `skills` | ❌ | Skills to inherit |
| `disallowedTools` | ❌ | Tools to block |
### Model Selection
| Model | Best For | Speed | Cost |
|-------|----------|-------|------|
| `haiku` | Quick tasks, simple changes | Fast | Low |
| `sonnet` | Most tasks (default) | Balanced | Medium |
| `opus` | Complex reasoning, architecture | Slow | High |
## 4.3 Agent Template
Copy this template to create your own agent:
```markdown
---
name: your-agent-name
description: Use this agent when [specific trigger description]
model: sonnet
tools: Read, Write, Edit, Bash, Grep, Glob
skills: []
---
# Your Agent Name
## Role Definition
You are an expert in [domain]. Your responsibilities include:
- [Responsibility 1]
- [Responsibility 2]
- [Responsibility 3]
## Activation Triggers
Use this agent when:
- [Trigger 1]
- [Trigger 2]
- [Trigger 3]
## Methodology
When given a task, you should:
1. [Step 1]
2. [Step 2]
3. [Step 3]
4. [Step 4]
## Output Format
Your deliverables should include:
- [Output 1]
- [Output 2]
## Constraints
- [Constraint 1]
- [Constraint 2]
## Examples
### Example 1: [Scenario Name]
**User**: [Example prompt]
**Your approach**:
1. [What you do first]
2. [What you do next]
3. [Final output]
```
## 4.4 Best Practices
### Do's and Don'ts
| ✅ Do | ❌ Don't |
|-------|----------|
| Make agents specialists | Create generalist agents |
| Define clear triggers | Use vague descriptions |
| Include concrete examples | Leave activation ambiguous |
| Limit tool access | Give all tools to all agents |
| Compose via skills | Duplicate expertise |
### Specialization Over Generalization
**Good**: An agent for each concern
```
backend-architect → API design, database, performance
security-reviewer → OWASP, auth, encryption
test-engineer → Test strategy, coverage, TDD
```
**Bad**: One agent for everything
```
full-stack-expert → Does everything (poorly)
```
### Explicit Activation Triggers
**Good description**:
```yaml
description: Use when designing APIs, reviewing database schemas, or optimizing backend performance
```
**Bad description**:
```yaml
description: Backend stuff
```
### Skill Composition
Instead of duplicating knowledge:
```yaml
# security-reviewer.md
skills:
- security-guardian # Inherits OWASP knowledge
```
## 4.5 Agent Examples
### Example 1: Code Reviewer Agent
```markdown
---
name: code-reviewer
description: Use for code quality reviews, security audits, and performance analysis
model: sonnet
tools: Read, Grep, Glob
skills:
- security-guardian
---
# Code Reviewer
## Role Definition
You are a senior code reviewer with expertise in:
- Code quality and maintainability
- Security best practices (OWASP Top 10)
- Performance optimization
- Test coverage analysis
## Activation Triggers
Use this agent when:
- Completing a feature before PR
- Reviewing someone else's code
- Auditing security-sensitive code
- Analyzing performance bottlenecks
## Methodology
1. **Understand Context**: Read the code and understand its purpose
2. **Check Quality**: Evaluate readability, maintainability, DRY principles
3. **Security Scan**: Look for OWASP Top 10 vulnerabilities
4. **Performance Review**: Identify potential bottlenecks
5. **Provide Feedback**: Structured report with severity levels
## Output Format
### Code Review Report
**Summary**: [1-2 sentence overview]
**Critical Issues** (Must Fix):
- [Issue with file:line reference]
**Warnings** (Should Fix):
- [Issue with file:line reference]
**Suggestions** (Nice to Have):
- [Improvement opportunity]
**Positive Notes**:
- [What was done well]
```
### Example 2: Debugger Agent
```markdown
---
name: debugger
description: Use when encountering errors, test failures, or unexpected behavior
model: sonnet
tools: Read, Bash, Grep, Glob
---
# Debugger
## Role Definition
You are a systematic debugger who:
- Investigates root causes, not symptoms
- Uses evidence-based debugging
- Never guesses - always verifies
## Methodology
1. **Reproduce**: Confirm the issue exists
2. **Isolate**: Narrow down to smallest reproducible case
3. **Analyze**: Read code, check logs, trace execution
4. **Hypothesize**: Form theories about the cause
5. **Test**: Verify hypothesis with minimal changes
6. **Fix**: Implement the solution
7. **Verify**: Confirm fix works and doesn't break other things
## Output Format
### Debug Report
**Issue**: [Description]
**Root Cause**: [What's actually wrong]
**Evidence**: [How you know]
**Fix**: [What to change]
**Verification**: [How to confirm it works]
```
### Example 3: Backend Architect Agent
```markdown
---
name: backend-architect
description: Use for API design, database optimization, and system architecture decisions
model: opus
tools: Read, Write, Edit, Bash, Grep
skills:
- backend-patterns
---
# Backend Architect
## Role Definition
You are a senior backend architect specializing in:
- API design (REST, GraphQL, tRPC)
- Database modeling and optimization
- System scalability
- Clean architecture patterns
## Activation Triggers
Use this agent when:
- Designing new API endpoints
- Optimizing database queries
- Planning system architecture
- Refactoring backend code
## Methodology
1. **Requirements Analysis**: Understand the business need
2. **Architecture Review**: Check current system state
3. **Design Options**: Propose 2-3 approaches with trade-offs
4. **Recommendation**: Suggest best approach with rationale
5. **Implementation Plan**: Break down into actionable steps
## Constraints
- Follow existing project patterns
- Prioritize backward compatibility
- Consider performance implications
- Document architectural decisions
```
## 4.6 Advanced Agent Patterns
### Tool SEO - Optimizing Agent Descriptions
The `description` field determines when Claude auto-activates your agent. Optimize it like SEO:
```yaml
# ❌ Bad description
description: Reviews code
# ✅ Good description (Tool SEO)
description: |
Security code reviewer - use PROACTIVELY when:
- Reviewing authentication/authorization code
- Analyzing API endpoints
- Checking input validation
- Auditing data handling
Triggers: security, auth, vulnerability, OWASP, injection
```
**Tool SEO Techniques**:
1. **"use PROACTIVELY"**: Encourages automatic activation
2. **Explicit triggers**: Keywords that trigger the agent
3. **Listed contexts**: When the agent is relevant
4. **Short nicknames**: `sec-1`, `perf-a`, `doc-gen`
### Agent Weight Classification
| Category | Tokens | Init Time | Optimal Use |
|----------|--------|-----------|-------------|
| **Lightweight** | <3K | <1s | Frequent tasks, workers |
| **Medium** | 10-15K | 2-3s | Analysis, reviews |
| **Heavy** | 25K+ | 5-10s | Architecture, full audits |
**Golden Rule**: A lightweight agent used 100x > A heavy agent used 10x
### The 7-Parallel-Task Method
Launch 7 specialized sub-agents in parallel for complete features:
```
┌─────────────────────────────────────────────────────────────┐
│ PARALLEL FEATURE IMPLEMENTATION │
│ │
│ Task 1: Components → Create React components │
│ Task 2: Styles → Generate Tailwind styles │
│ Task 3: Tests → Write unit tests │
│ Task 4: Types → Define TypeScript types │
│ Task 5: Hooks → Create custom hooks │
│ Task 6: Integration → Connect with API/state │
│ Task 7: Config → Update configurations │
│ │
│ All in parallel → Final consolidation │
└─────────────────────────────────────────────────────────────┘
```
**Example Prompt**:
```
Implement the "User Profile" feature using 7 parallel sub-agents:
1. COMPONENTS: Create UserProfile.tsx, UserAvatar.tsx, UserStats.tsx
2. STYLES: Define Tailwind classes in a styles file
3. TESTS: Write tests for each component
4. TYPES: Create types in types/user-profile.ts
5. HOOKS: Create useUserProfile and useUserStats hooks
6. INTEGRATION: Connect with existing tRPC router
7. CONFIG: Update exports and routing
Launch all agents in parallel.
```
### Split Role Sub-Agents
**Concept**: Multi-perspective analysis in parallel.
**Process**:
```
┌─────────────────────────────────────────────────────────────┐
│ SPLIT ROLE ANALYSIS │
│ │
│ Step 1: Setup │
│ └─ Activate Plan Mode + ultrathink │
│ │
│ Step 2: Role Suggestion │
│ └─ "What expert roles would analyze this code?" │
│ Claude suggests: Security, Performance, UX, etc. │
│ │
│ Step 3: Selection │
│ └─ "Use: Security Expert, Senior Dev, Code Reviewer" │
│ │
│ Step 4: Parallel Analysis │
│ ├─ Security Agent: [Vulnerability analysis] │
│ ├─ Senior Agent: [Architecture analysis] │
│ └─ Reviewer Agent: [Readability analysis] │
│ │
│ Step 5: Consolidation │
│ └─ Synthesize 3 reports into recommendations │
└─────────────────────────────────────────────────────────────┘
```
**Code Review Prompt**:
```
Analyze this PR with the following perspectives:
1. Senior Engineer: Architecture and patterns
2. Security Expert: Vulnerabilities and risks
3. Performance Engineer: Bottlenecks and optimizations
4. Junior Dev: Readability and documentation
5. QA Engineer: Testability and edge cases
```
**UX Review Prompt**:
```
Evaluate this interface with perspectives:
1. Designer: Visual consistency and design system
2. New User: Discoverability ease
3. Power User: Efficiency and shortcuts
4. Accessibility Expert: WCAG compliance
5. Mobile User: Responsive and touch
```
### Parallelization Decision Matrix
```
┌─────────────────────────────────────────────────────────────┐
│ PARALLELIZABLE? │
│ │
│ Non-destructive Destructive │
│ (read-only) (write) │
│ │
│ Independent ✅ PARALLEL ⚠️ SEQUENTIAL │
│ Max efficiency Plan Mode first │
│ │
│ Dependent ⚠️ SEQUENTIAL ❌ CAREFUL │
│ Order matters Risk of conflicts │
│ │
└─────────────────────────────────────────────────────────────┘
```
**✅ Perfectly parallelizable**:
```
"Search 8 different GitHub repos for best practices on X"
"Analyze these 5 files for vulnerabilities (without modifying)"
"Compare 4 libraries and produce a comparative report"
```
**⚠️ Sequential recommended**:
```
"Refactor these 3 files (they depend on each other)"
"Migrate DB schema then update models then update routers"
```
**❌ Needs extra care**:
```
"Modify these 10 files in parallel"
→ Risk: conflicts if files share imports/exports
→ Solution: Plan Mode → Identify dependencies → Sequence if needed
```
### Multi-Agent Orchestration Pattern
```
┌─────────────────────────────────────────────────────────────┐
│ ORCHESTRATION PATTERN │
│ │
│ ┌──────────────┐ │
│ │ Sonnet 4.5 │ │
│ │ Orchestrator │ │
│ └──────┬───────┘ │
│ │ │
│ ┌────────────┼────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Haiku │ │ Haiku │ │ Haiku │ │
│ │ Worker1 │ │ Worker2 │ │ Worker3 │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │
│ └────────────┼────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ Sonnet 4.5 │ │
│ │ Validator │ │
│ └──────────────┘ │
│ │
│ Cost: 2-2.5x cheaper than Opus everywhere │
│ Quality: Equivalent for 90% of tasks │
└─────────────────────────────────────────────────────────────┘
```
### Tactical Model Selection Matrix
| Task | Model | Justification |
|------|-------|---------------|
| Read and summarize a file | Haiku | Simple, fast |
| Write a standard component | Sonnet | Good balance |
| Debug complex issue | Sonnet + ultrathink | Depth needed |
| System architecture | Opus | Maximum reasoning |
| Critical security review | Opus | High stakes |
| Generate tests | Haiku | Repetitive pattern |
| Refactor 50 files | Sonnet orchestrate + Haiku workers | Optimized cost |
**Cost Optimization Example**:
```
Scenario: Refactoring 100 files
❌ Naive approach:
- Opus for everything
- Cost: ~$50-100
- Time: 2-3h
✅ Optimized approach:
- Sonnet: Analysis and plan (1x)
- Haiku: Parallel workers (100x)
- Sonnet: Final validation (1x)
- Cost: ~$5-15
- Time: 1h (parallelized)
Savings: 80-90%
```
---
# 5. Skills
**Reading time**: 15 minutes
**Skill level**: Week 2
**Goal**: Create reusable knowledge modules
## 5.1 Understanding Skills
Skills are knowledge packages that agents can inherit.
### Skills vs Agents vs Commands
| Concept | Purpose | Invocation |
|---------|---------|------------|
| **Agent** | Specialized role | Task tool delegation |
| **Skill** | Knowledge module | Inherited by agents |
| **Command** | Process workflow | Slash command |
### Why Skills?
Without skills:
```
Agent A: Has security knowledge (duplicated)
Agent B: Has security knowledge (duplicated)
Agent C: Has security knowledge (duplicated)
```
With skills:
```
security-guardian skill: Single source of security knowledge
Agent A: inherits security-guardian
Agent B: inherits security-guardian
Agent C: inherits security-guardian
```
### What Makes a Good Skill?
| Good Skill | Bad Skill |
|------------|-----------|
| Reusable across agents | Single-agent specific |
| Domain-focused | Too broad |
| Contains reference material | Just instructions |
| Includes checklists | Missing verification |
## 5.2 Creating Skills
Skills live in `.claude/skills/{skill-name}/` directories.
### Skill Folder Structure
```
skill-name/
├── SKILL.md # Required - Main instructions
├── reference.md # Optional - Detailed documentation
├── checklists/ # Optional - Verification lists
│ ├── security.md
│ └── performance.md
├── examples/ # Optional - Code patterns
│ ├── good-example.ts
│ └── bad-example.ts
└── scripts/ # Optional - Helper scripts
└── audit.sh
```
### SKILL.md Frontmatter
```yaml
---
name: skill-name
description: Short description for activation (100 chars)
allowed-tools: Read, Grep, Bash
context: fork
agent: specialist
---
```
| Field | Description |
|-------|-------------|
| `name` | Kebab-case identifier |
| `description` | Activation trigger |
| `allowed-tools` | Tools this skill can use |
| `context` | `fork` (isolated) or `inherit` (shared) |
| `agent` | `specialist` (domain) or `general` (broad) |
## 5.3 Skill Template
```markdown
---
name: your-skill-name
description: Expert guidance for [domain] problems
allowed-tools: Read, Grep, Bash
context: fork
agent: specialist
---
# Your Skill Name
## Expertise Areas
This skill provides knowledge in:
- [Area 1]
- [Area 2]
- [Area 3]
## When to Apply
Use this skill when:
- [Situation 1]
- [Situation 2]
## Methodology
When activated, follow this approach:
1. [Step 1]
2. [Step 2]
3. [Step 3]
## Key Concepts
### Concept 1: [Name]
[Explanation]
### Concept 2: [Name]
[Explanation]
## Checklists
### Pre-Implementation Checklist
- [ ] [Check 1]
- [ ] [Check 2]
- [ ] [Check 3]
### Post-Implementation Checklist
- [ ] [Verification 1]
- [ ] [Verification 2]
## Examples
### Good Pattern
```[language]
// Good example
```
### Anti-Pattern
```[language]
// Bad example - don't do this
```
## Reference Material
See `reference.md` for detailed documentation.
## 5.4 Skill Examples
### Example 1: Security Guardian Skill
```markdown
---
name: security-guardian
description: Security expertise for OWASP Top 10, auth, and data protection
allowed-tools: Read, Grep, Bash
context: fork
agent: specialist
---
# Security Guardian
## Expertise Areas
- OWASP Top 10 vulnerabilities
- Authentication & Authorization
- Data protection & encryption
- API security
- Secrets management
## OWASP Top 10 Checklist
### A01: Broken Access Control
- [ ] Check authorization on every endpoint
- [ ] Verify row-level permissions
- [ ] Test IDOR vulnerabilities
- [ ] Check for privilege escalation
### A02: Cryptographic Failures
- [ ] Check for hardcoded secrets
- [ ] Verify TLS configuration
- [ ] Review password hashing (bcrypt/argon2)
- [ ] Check data encryption at rest
### A03: Injection
- [ ] Review SQL queries (parameterized?)
- [ ] Check NoSQL operations
- [ ] Review command execution
- [ ] Check XSS vectors
[... more checklists ...]
## Authentication Patterns
### Good: Secure Password Hashing
```typescript
import { hash, verify } from 'argon2';
const hashedPassword = await hash(password);
const isValid = await verify(hashedPassword, inputPassword);
```
### Bad: Insecure Hashing
```typescript
// DON'T DO THIS
const hashed = md5(password);
const hashed = sha1(password);
```
## Secrets Management
### Never Commit Secrets
```
# .gitignore
.env
.env.local
*.pem
*credentials*
```
### Use Environment Variables
```typescript
// Good
const apiKey = process.env.API_KEY;
// Bad
const apiKey = "sk-1234567890abcdef";
```
### Example 2: TDD Skill
```markdown
---
name: tdd
description: Test-Driven Development methodology and patterns
allowed-tools: Read, Write, Bash
context: inherit
agent: specialist
---
# TDD (Test-Driven Development)
## The TDD Cycle
┌─────────────────────────────────────────────────────────┐
│ RED → GREEN → REFACTOR │
├─────────────────────────────────────────────────────────┤
│ │
│ 1. RED ──→ Write a failing test │
│ │ │
│ ▼ │
│ 2. GREEN ──→ Write minimal code to pass │
│ │ │
│ ▼ │
│ 3. REFACTOR ──→ Improve code, keep tests green │
│ │ │
│ └────────────→ Repeat │
│ │
└─────────────────────────────────────────────────────────┘
## Methodology
### Step 1: RED (Write Failing Test)
Write a test for the behavior you want BEFORE writing any code.
```typescript
// user.test.ts
describe('User', () => {
it('should validate email format', () => {
expect(isValidEmail('test@example.com')).toBe(true);
expect(isValidEmail('invalid')).toBe(false);
});
});
```
Run: `pnpm test` → Should FAIL (function doesn't exist)
### Step 2: GREEN (Minimal Implementation)
Write the MINIMUM code to make the test pass.
```typescript
// user.ts
export const isValidEmail = (email: string): boolean => {
return email.includes('@');
};
```
Run: `pnpm test` → Should PASS
### Step 3: REFACTOR (Improve)
Now improve the implementation while keeping tests green.
```typescript
// user.ts (improved)
export const isValidEmail = (email: string): boolean => {
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
return emailRegex.test(email);
};
```
Run: `pnpm test` → Should still PASS
## Test Structure: AAA Pattern
```typescript
it('should calculate order total', () => {
// Arrange - Set up test data
const items = [
{ price: 10, quantity: 2 },
{ price: 5, quantity: 3 }
];
// Act - Execute the code
const total = calculateTotal(items);
// Assert - Verify the result
expect(total).toBe(35);
});
```
---
# 6. Commands
**Reading time**: 10 minutes
**Skill level**: Week 1-2
**Goal**: Create custom slash commands
## 6.1 Slash Commands
Slash commands are shortcuts for common workflows.
### Built-in Commands
| Command | Action |
|---------|--------|
| `/help` | Show all commands |
| `/clear` | Clear conversation |
| `/compact` | Summarize context |
| `/status` | Show session info |
| `/plan` | Enter Plan Mode |
| `/rewind` | Undo changes |
| `/exit` | Exit Claude Code |
### Custom Commands
You can create your own commands in `.claude/commands/`:
```
/tech:commit → .claude/commands/tech/commit.md
/tech:pr → .claude/commands/tech/pr.md
/product:scope → .claude/commands/product/scope.md
```
## 6.2 Creating Custom Commands
Commands are markdown files that define a process.
### Command File Location
```
.claude/commands/
├── tech/ # Development workflows
│ ├── commit.md
│ └── pr.md
├── product/ # Product workflows
│ └── problem-framer.md
└── support/ # Support workflows
└── ticket-analyzer.md
```
### Command Naming
| File | Invocation |
|------|------------|
| `commit.md` in `tech/` | `/tech:commit` |
| `pr.md` in `tech/` | `/tech:pr` |
| `problem-framer.md` in `product/` | `/product:problem-framer` |
### Variable Interpolation
Commands can accept arguments:
```markdown
# My Command
You received the following arguments: $ARGUMENTS
Process them accordingly.
```
Usage:
```
/tech:deploy production
```
`$ARGUMENTS` becomes `production`.
## 6.3 Command Template
```markdown
# Command Name
## Purpose
[Brief description of what this command does]
## Process
Follow these steps:
1. **Step 1 Name**
[Detailed instructions]
2. **Step 2 Name**
[Detailed instructions]
3. **Step 3 Name**
[Detailed instructions]
## Arguments
If arguments provided ($ARGUMENTS): [How to handle them]
If no arguments: [Default behavior]
## Output Format
[Expected output structure]
## Examples
### Example 1
Input: `/command arg1`
Output: [Expected result]
## Error Handling
If [error condition]:
- [Recovery action]
```
## 6.4 Command Examples
### Example 1: Commit Command
```markdown
# Commit Current Changes
## Purpose
Create a well-formatted git commit following Conventional Commits.
## Process
1. **Check Status**
Run `git status` to see all changes.
2. **Analyze Changes**
Run `git diff` to understand what changed.
3. **Review History**
Run `git log -5 --oneline` to see recent commit style.
4. **Draft Message**
Create commit message following:
- `feat`: New feature
- `fix`: Bug fix
- `refactor`: Code restructuring
- `docs`: Documentation
- `test`: Test changes
- `chore`: Maintenance
5. **Stage and Commit**
```bash
git add [relevant files]
git commit -m "[type](scope): description"
```
6. **Verify**
Run `git status` to confirm commit succeeded.
## Arguments
If $ARGUMENTS provided:
- Use as commit message hint: "$ARGUMENTS"
## Output Format
Commit: [hash] [message]
Files: [number] changed
### Example 2: PR Command
```markdown
# Create Pull Request
## Purpose
Create a well-documented pull request on GitHub.
## Process
1. **Check Branch State**
- `git status` - Verify clean working directory
- `git branch` - Confirm on feature branch
- `git log main..HEAD` - Review all commits
2. **Analyze Changes**
- `git diff main...HEAD` - See all changes vs main
- Understand the full scope of the PR
3. **Push if Needed**
If branch not pushed:
```bash
git push -u origin [branch-name]
```
4. **Create PR**
```bash
gh pr create --title "[title]" --body "[body]"
```
## PR Body Template
```markdown
## Summary
[1-3 bullet points describing changes]
## Changes
- [Specific change 1]
- [Specific change 2]
## Testing
- [ ] Unit tests pass
- [ ] Manual testing completed
- [ ] No regressions
## Screenshots
[If UI changes]
```
## Arguments
If $ARGUMENTS provided:
- Use as PR title hint
## Error Handling
If not on feature branch:
- WARN: "Create a feature branch first"
If working directory dirty:
- ASK: "Commit changes first?"
### Example 3: Problem Framer Command
```markdown
# Problem Framer
## Purpose
Challenge and refine problem definitions before solution design.
## Process
1. **Capture Initial Problem**
Record the problem as stated by user.
2. **5 Whys Analysis**
Ask "Why?" 5 times to find root cause:
- Why 1: [First answer]
- Why 2: [Deeper answer]
- Why 3: [Even deeper]
- Why 4: [Getting to root]
- Why 5: [Root cause]
3. **Stakeholder Analysis**
- Who is affected?
- Who has decision power?
- Who benefits from solution?
4. **Constraint Identification**
- Technical constraints
- Business constraints
- Time constraints
- Resource constraints
5. **Success Criteria**
Define measurable outcomes:
- [Metric 1]: [Target]
- [Metric 2]: [Target]
6. **Reframe Problem**
Write refined problem statement:
"How might we [action] for [user] so that [outcome]?"
## Output Format
### Problem Analysis Report
**Original Problem**: [As stated]
**Root Cause**: [From 5 Whys]
**Refined Problem Statement**:
"How might we [X] for [Y] so that [Z]?"
**Success Criteria**:
1. [Measurable outcome 1]
2. [Measurable outcome 2]
**Constraints**:
- [Constraint 1]
- [Constraint 2]
```
---
# 7. Hooks
**Reading time**: 20 minutes
**Skill level**: Week 2-3
**Goal**: Automate Claude Code with event-driven scripts
## 7.1 The Event System
Hooks are scripts that run automatically when specific events occur.
### Event Types
| Event | When It Fires | Use Case |
|-------|---------------|----------|
| `PreToolUse` | Before any tool runs | Security validation |
| `PostToolUse` | After any tool runs | Formatting, logging |
| `UserPromptSubmit` | User sends a message | Context enrichment |
| `Notification` | Claude sends notification | Sound alerts |
| `SessionStart` | Session begins | Initialization |
| `SessionEnd` | Session ends | Cleanup |
| `Stop` | User interrupts | Graceful shutdown |
### Event Flow
```
┌─────────────────────────────────────────────────────────┐
│ EVENT FLOW │
├─────────────────────────────────────────────────────────┤
│ │
│ User types message │
│ │ │
│ ▼ │
│ ┌────────────────────┐ │
│ │ UserPromptSubmit │ ← Add context (git status) │
│ └────────────────────┘ │
│ │ │
│ ▼ │
│ Claude decides to run tool (e.g., Edit) │
│ │ │
│ ▼ │
│ ┌────────────────────┐ │
│ │ PreToolUse │ ← Security check │
│ └────────────────────┘ │
│ │ │
│ ▼ (if allowed) │
│ Tool executes │
│ │ │
│ ▼ │
│ ┌────────────────────┐ │
│ │ PostToolUse │ ← Auto-format │
│ └────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
## 7.2 Creating Hooks
### Hook Registration (settings.json)
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash|Edit|Write",
"hooks": [
{
"type": "command",
"command": ".claude/hooks/security-check.sh",
"timeout": 5000
}
]
}
]
}
}
```
### Configuration Fields
| Field | Description |
|-------|-------------|
| `matcher` | Regex pattern for which tools trigger hook |
| `type` | Always `"command"` |
| `command` | Path to hook script |
| `timeout` | Max execution time (ms) |
### Hook Input (stdin JSON)
Hooks receive JSON on stdin:
```json
{
"tool_name": "Bash",
"tool_input": {
"command": "git status"
},
"session_id": "abc123",
"cwd": "/project"
}
```
### Hook Output
Hooks can return JSON on stdout:
```json
{
"systemMessage": "Message shown to Claude",
"hookSpecificOutput": {
"additionalContext": "Extra information"
}
}
```
### Exit Codes
| Code | Meaning | Result |
|------|---------|--------|
| `0` | Success | Allow operation |
| `2` | Block | Prevent operation |
| Other | Error | Log and continue |
## 7.3 Hook Templates
### Template 1: PreToolUse (Security Blocker)
```bash
#!/bin/bash
# .claude/hooks/security-blocker.sh
# Blocks dangerous commands
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
# List of dangerous patterns
DANGEROUS_PATTERNS=(
"rm -rf /"
"rm -rf ~"
"rm -rf *"
"sudo rm"
"git push --force origin main"
"git push -f origin main"
"npm publish"
"> /dev/sda"
)
# Check if command matches any dangerous pattern
for pattern in "${DANGEROUS_PATTERNS[@]}"; do
if [[ "$COMMAND" == *"$pattern"* ]]; then
echo "BLOCKED: Dangerous command detected: $pattern" >&2
exit 2
fi
done
exit 0
```
### Template 2: PostToolUse (Auto-Formatter)
```bash
#!/bin/bash
# .claude/hooks/auto-format.sh
# Auto-formats code after edits
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
# Only run for Edit/Write operations
if [[ "$TOOL_NAME" != "Edit" && "$TOOL_NAME" != "Write" ]]; then
exit 0
fi
# Get the file path
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
# Skip if no file path
if [[ -z "$FILE_PATH" ]]; then
exit 0
fi
# Run Prettier on supported files
if [[ "$FILE_PATH" =~ \.(ts|tsx|js|jsx|json|md|css|scss)$ ]]; then
npx prettier --write "$FILE_PATH" 2>/dev/null
fi
exit 0
```
### Template 3: UserPromptSubmit (Context Enricher)
```bash
#!/bin/bash
# .claude/hooks/git-context.sh
# Adds git context to every prompt
# Get git information
BRANCH=$(git branch --show-current 2>/dev/null || echo "not a git repo")
LAST_COMMIT=$(git log -1 --format='%h %s' 2>/dev/null || echo "no commits")
STAGED=$(git diff --cached --stat 2>/dev/null | tail -1 || echo "none")
UNSTAGED=$(git diff --stat 2>/dev/null | tail -1 || echo "none")
# Output JSON with context
cat << EOF
{
"hookSpecificOutput": {
"additionalContext": "[Git] Branch: $BRANCH | Last: $LAST_COMMIT | Staged: $STAGED | Unstaged: $UNSTAGED"
}
}
EOF
exit 0
```
### Template 4: Notification (Sound Alerts)
```bash
#!/bin/bash
# .claude/hooks/notification.sh
# Plays sounds on notifications (macOS)
INPUT=$(cat)
TITLE=$(echo "$INPUT" | jq -r '.title // ""')
BODY=$(echo "$INPUT" | jq -r '.body // ""')
# Determine sound based on content
if [[ "$TITLE" == *"error"* ]] || [[ "$BODY" == *"failed"* ]]; then
SOUND="/System/Library/Sounds/Basso.aiff"
elif [[ "$TITLE" == *"complete"* ]] || [[ "$BODY" == *"success"* ]]; then
SOUND="/System/Library/Sounds/Hero.aiff"
else
SOUND="/System/Library/Sounds/Pop.aiff"
fi
# Play sound (macOS)
afplay "$SOUND" 2>/dev/null &
exit 0
```
## 7.4 Security Hooks
Security hooks are critical for protecting your system.
### Recommended Security Rules
```bash
#!/bin/bash
# .claude/hooks/comprehensive-security.sh
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
# === CRITICAL BLOCKS (Exit 2) ===
# Filesystem destruction
[[ "$COMMAND" =~ rm.*-rf.*[/~] ]] && { echo "BLOCKED: Recursive delete of root/home" >&2; exit 2; }
# Disk operations
[[ "$COMMAND" =~ ">/dev/sd" ]] && { echo "BLOCKED: Direct disk write" >&2; exit 2; }
[[ "$COMMAND" =~ "dd if=" ]] && { echo "BLOCKED: dd command" >&2; exit 2; }
# Git force operations on protected branches
[[ "$COMMAND" =~ "git push".*"-f".*"(main|master)" ]] && { echo "BLOCKED: Force push to main" >&2; exit 2; }
[[ "$COMMAND" =~ "git push --force".*"(main|master)" ]] && { echo "BLOCKED: Force push to main" >&2; exit 2; }
# Package publishing
[[ "$COMMAND" =~ "npm publish" ]] && { echo "BLOCKED: npm publish" >&2; exit 2; }
# Privileged operations
[[ "$COMMAND" =~ ^sudo ]] && { echo "BLOCKED: sudo command" >&2; exit 2; }
# === WARNINGS (Exit 0 but log) ===
[[ "$COMMAND" =~ "rm -rf" ]] && echo "WARNING: Recursive delete detected" >&2
exit 0
```
### Testing Security Hooks
Before deploying, test your hooks:
```bash
# Test with a blocked command
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' | .claude/hooks/security-blocker.sh
echo "Exit code: $?" # Should be 2
# Test with a safe command
echo '{"tool_name":"Bash","tool_input":{"command":"git status"}}' | .claude/hooks/security-blocker.sh
echo "Exit code: $?" # Should be 0
```
## 7.5 Hook Examples
### Example 1: Activity Logger
```bash
#!/bin/bash
# .claude/hooks/activity-logger.sh
# Logs all tool usage to JSONL file
INPUT=$(cat)
LOG_DIR="$HOME/.claude/logs"
LOG_FILE="$LOG_DIR/activity-$(date +%Y-%m-%d).jsonl"
# Create log directory
mkdir -p "$LOG_DIR"
# Clean up old logs (keep 7 days)
find "$LOG_DIR" -name "activity-*.jsonl" -mtime +7 -delete
# Extract tool info
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
SESSION_ID=$(echo "$INPUT" | jq -r '.session_id')
# Create log entry
LOG_ENTRY=$(jq -n \
--arg timestamp "$TIMESTAMP" \
--arg tool "$TOOL_NAME" \
--arg session "$SESSION_ID" \
'{timestamp: $timestamp, tool: $tool, session: $session}')
# Append to log
echo "$LOG_ENTRY" >> "$LOG_FILE"
exit 0
```
### Example 2: Linting Gate
```bash
#!/bin/bash
# .claude/hooks/lint-gate.sh
# Runs linter after code changes
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
# Only check after Edit/Write
if [[ "$TOOL_NAME" != "Edit" && "$TOOL_NAME" != "Write" ]]; then
exit 0
fi
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
# Only lint TypeScript/JavaScript
if [[ ! "$FILE_PATH" =~ \.(ts|tsx|js|jsx)$ ]]; then
exit 0
fi
# Run ESLint
LINT_OUTPUT=$(npx eslint "$FILE_PATH" 2>&1)
LINT_EXIT=$?
if [[ $LINT_EXIT -ne 0 ]]; then
cat << EOF
{
"systemMessage": "Lint errors found in $FILE_PATH:\n$LINT_OUTPUT"
}
EOF
fi
exit 0
```
---
# 8. MCP Servers
**Reading time**: 15 minutes
**Skill level**: Week 2-3
**Goal**: Extend Claude Code with external tools
## 8.1 What is MCP
MCP (Model Context Protocol) is a standard for connecting AI models to external tools and data sources.
### Why MCP?
| Without MCP | With MCP |
|-------------|----------|
| Limited to built-in tools | Extensible tool ecosystem |
| Claude guesses about external data | Claude queries real data |
| Generic code understanding | Deep semantic analysis |
### How It Works
```
┌─────────────────────────────────────────────────────────┐
│ MCP ARCHITECTURE │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ │
│ │ Claude Code │ │
│ └──────┬──────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────┐ │
│ │ MCP Protocol │ │
│ └──────────────────────┬──────────────────────┘ │
│ │ │
│ ┌───────────────┼───────────────┐ │
│ ▼ ▼ ▼ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ Serena │ │ Context7 │ │ Postgres │ │
│ │(Semantic) │ │ (Docs) │ │(Database) │ │
│ └───────────┘ └───────────┘ └───────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
## 8.2 Available Servers
### Serena (Semantic Code Analysis)
**Purpose**: Deep code understanding through semantic analysis.
**Tools**:
| Tool | Description |
|------|-------------|
| `find_symbol` | Find functions, classes, methods by name |
| `get_symbols_overview` | Get file structure overview |
| `search_for_pattern` | Regex search across codebase |
| `find_referencing_symbols` | Find all usages of a symbol |
| `replace_symbol_body` | Replace function/class body |
**Use when**:
- Navigating large codebases
- Understanding symbol relationships
- Refactoring across files
### Context7 (Documentation Lookup)
**Purpose**: Access official library documentation.
**Tools**:
| Tool | Description |
|------|-------------|
| `resolve-library-id` | Find library documentation |
| `query-docs` | Query specific documentation |
**Use when**:
- Learning new libraries
- Finding correct API usage
- Checking official patterns
### Sequential Thinking (Structured Reasoning)
**Purpose**: Multi-step analysis with explicit reasoning.
**Tools**:
| Tool | Description |
|------|-------------|
| `sequentialthinking` | Step-by-step reasoning |
**Use when**:
- Complex debugging
- Architectural analysis
- System design decisions
### Postgres (Database Queries)
**Purpose**: Direct database access for queries.
**Tools**:
| Tool | Description |
|------|-------------|
| `query` | Execute SQL queries |
**Use when**:
- Investigating data issues
- Understanding schema
- Debugging data problems
### Playwright (Browser Automation)
**Purpose**: Browser testing and automation.
**Tools**:
| Tool | Description |
|------|-------------|
| `navigate` | Go to URL |
| `click` | Click element |
| `fill` | Fill form field |
| `screenshot` | Capture screenshot |
**Use when**:
- E2E testing
- Visual validation
- Browser debugging
## 8.3 Configuration
### mcp.json Location
```
~/.claude/mcp.json # Global MCP configuration
/project/.claude/mcp.json # Project-specific (overrides)
```
### Example Configuration
```json
{
"servers": {
"serena": {
"command": "npx",
"args": ["serena-mcp"],
"env": {
"PROJECT_PATH": "${workspaceFolder}"
}
},
"context7": {
"command": "npx",
"args": ["@context7/mcp-server"]
},
"postgres": {
"command": "npx",
"args": ["@modelcontextprotocol/server-postgres"],
"env": {
"DATABASE_URL": "${env:DATABASE_URL}"
}
}
}
}
```
### Configuration Fields
| Field | Description |
|-------|-------------|
| `command` | Executable to run |
| `args` | Command arguments |
| `env` | Environment variables |
| `cwd` | Working directory |
### Variable Substitution
| Variable | Expands To |
|----------|------------|
| `${workspaceFolder}` | Current project path |
| `${env:VAR_NAME}` | Environment variable |
## 8.4 Server Selection Guide
### Decision Tree
```
What do you need?
│
├─ Deep code understanding?
│ └─ Use Serena
│
├─ Library documentation?
│ └─ Use Context7
│
├─ Complex reasoning?
│ └─ Use Sequential Thinking
│
├─ Database queries?
│ └─ Use Postgres
│
├─ Browser testing?
│ └─ Use Playwright
│
└─ General task?
└─ Use built-in tools
```
### Server Comparison
| Need | Best Server | Why |
|------|-------------|-----|
| "Find all usages of this function" | Serena | Semantic analysis |
| "How does React useEffect work?" | Context7 | Official docs |
| "Why is this failing?" | Sequential | Structured debugging |
| "What's in the users table?" | Postgres | Direct query |
| "Test the login flow" | Playwright | Browser automation |
### Combining Servers
Servers can work together:
```
1. Context7 → Get official pattern for auth
2. Serena → Find existing auth code
3. Sequential → Analyze how to integrate
4. Playwright → Test the implementation
```
---
# 9. Advanced Patterns
**Reading time**: 20 minutes
**Skill level**: Month 1+
**Goal**: Master power-user techniques
## 9.1 The Trinity
The most powerful Claude Code pattern combines three techniques:
```
┌─────────────────────────────────────────────────────────┐
│ THE TRINITY │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ │
│ │ Plan Mode │ Safe exploration without changes │
│ └──────┬──────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ Ultrathink │ Deep analysis with extended thinking │
│ └──────┬──────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ Sequential Thinking │ Structured multi-step reason │
│ └─────────────────────┘ │
│ │
│ Combined: Maximum understanding before action │
│ │
└─────────────────────────────────────────────────────────┘
```
### When to Use the Trinity
| Situation | Use Trinity? |
|-----------|--------------|
| Fixing a typo | ❌ Overkill |
| Adding a feature | Maybe |
| Debugging complex issue | ✅ Yes |
| Architectural decision | ✅ Yes |
| Legacy system modernization | ✅ Yes |
### Ultrathink Levels
| Flag | Thinking Depth | Token Usage | Best For |
|------|----------------|-------------|----------|
| `--think` | Standard | ~4K | Multi-component analysis |
| `--think-hard` | Deep | ~10K | Architectural decisions |
| `--ultrathink` | Maximum | ~32K | Critical redesign |
### Example: Using the Trinity
```
You: /plan
Let's analyze this legacy authentication system before we touch anything.
Use --ultrathink to understand all the implications.
[Claude enters Plan Mode and does deep analysis]
Claude: I've analyzed the auth system. Here's what I found:
- 47 files depend on the current auth module
- 3 critical security issues
- Migration path needs 4 phases
Ready to implement?
You: /execute
Let's start with phase 1
```
## 9.2 Composition Patterns
### Multi-Agent Delegation
Launch multiple agents for different aspects:
```
You: For this feature, I need:
1. Backend architect to design the API
2. Security reviewer to audit the design
3. Test engineer to plan the tests
Run these in parallel.
```
Claude will coordinate:
- Backend architect designs API
- Security reviewer audits (in parallel)
- Test engineer plans tests (in parallel)
### Skill Stacking
Combine multiple skills for complex tasks:
```yaml
# code-reviewer.md
skills:
- security-guardian
- performance-patterns
- accessibility-checker
```
The reviewer now has all three knowledge domains.
### The "Rev the Engine" Pattern
For quality work, use multiple rounds of critique:
```
You: Write the function, then critique it, then improve it.
Do this 3 times.
Round 1: [Initial implementation]
Critique: [What's wrong]
Improvement: [Better version]
Round 2: [Improved implementation]
Critique: [What's still wrong]
Improvement: [Even better version]
Round 3: [Final implementation]
Final check: [Verification]
```
### The "Stack Maximum" Pattern
For critical work, combine everything:
```
1. Plan Mode + Ultrathink → Deep exploration
2. Multiple Agents → Specialized analysis
3. Sequential Thinking → Structured reasoning
4. Rev the Engine → Iterative improvement
5. Code Review Agent → Final validation
```
## 9.3 CI/CD Integration
### Headless Mode
Run Claude Code without interactive prompts:
```bash
# Basic headless execution
claude --headless "Run the tests and report results"
# With timeout
claude --headless --timeout 300 "Build the project"
# With specific model
claude --headless --model sonnet "Analyze code quality"
```
### Git Hooks Integration
**Pre-commit hook**:
```bash
#!/bin/bash
# .git/hooks/pre-commit
# Run Claude Code for commit message validation
COMMIT_MSG=$(cat "$1")
claude --headless "Is this commit message good? '$COMMIT_MSG'. Reply YES or NO with reason."
```
**Pre-push hook**:
```bash
#!/bin/bash
# .git/hooks/pre-push
# Security check before push
claude --headless "Scan staged files for secrets and security issues. Exit 1 if found."
EXIT_CODE=$?
if [ $EXIT_CODE -ne 0 ]; then
echo "Security issues found. Push blocked."
exit 1
fi
```
### GitHub Actions Integration
```yaml
# .github/workflows/claude-review.yml
name: Claude Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Claude Code
run: npm install -g @anthropic-ai/claude-code
- name: Run Review
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
claude --headless "Review the changes in this PR. \
Focus on security, performance, and code quality. \
Output as markdown."
```
## 9.4 IDE Integration
### VS Code Integration
Claude Code integrates with VS Code:
1. **Install Extension**: Search "Claude Code" in Extensions
2. **Configure**: Set API key in settings
3. **Use**:
- `Ctrl+Shift+P` → "Claude Code: Start Session"
- Select text → Right-click → "Ask Claude"
### JetBrains Integration
Works with IntelliJ, WebStorm, PyCharm:
1. **Install Plugin**: Settings → Plugins → "Claude Code"
2. **Configure**: Tools → Claude Code → Set API key
3. **Use**:
- `Ctrl+Shift+A` → "Claude Code"
- Tool window for persistent session
### Terminal Integration
For terminal-native workflow:
```bash
# Add to .bashrc or .zshrc
alias cc='claude'
alias ccp='claude --plan'
alias cce='claude --execute'
# Quick code question
cq() {
claude --headless "$*"
}
```
Usage:
```bash
cq "What does this regex do: ^[a-z]+$"
```
## 9.5 Tight Feedback Loops
**Reading time**: 5 minutes
**Skill level**: Week 1+
Tight feedback loops accelerate learning and catch issues early. Design your workflow to validate changes immediately.
### The Feedback Loop Pyramid
```
┌─────────────┐
│ Deploy │ ← Hours/Days
│ Tests │
├─────────────┤
│ CI/CD │ ← Minutes
│ Pipeline │
├─────────────┤
│ Local │ ← Seconds
│ Tests │
├─────────────┤
│ TypeCheck │ ← Immediate
│ Lint │
└─────────────┘
```
### Implementing Tight Loops
#### Level 1: Immediate (IDE/Editor)
```bash
# Watch mode for instant feedback
pnpm tsc --watch
pnpm lint --watch
```
#### Level 2: On-Save (Git Hooks)
```bash
# Pre-commit hook
#!/bin/bash
pnpm lint-staged && pnpm tsc --noEmit
```
#### Level 3: On-Commit (CI)
```yaml
# GitHub Action for PR checks
- run: pnpm lint && pnpm tsc && pnpm test
```
### Claude Code Integration
Use hooks for automatic validation:
```json
// settings.json
{
"hooks": {
"PostToolUse": [{
"matcher": "Edit|Write",
"hooks": ["./scripts/validate.sh"]
}]
}
}
```
**validate.sh:**
```bash
#!/bin/bash
# Run after every file change
FILE=$(echo "$TOOL_INPUT" | jq -r '.file_path // .file')
if [[ "$FILE" == *.ts || "$FILE" == *.tsx ]]; then
npx tsc --noEmit "$FILE" 2>&1 | head -5
fi
```
### Feedback Loop Checklist
| Loop | Trigger | Response Time | What It Catches |
|------|---------|---------------|-----------------|
| Lint | On type | <1s | Style, imports |
| TypeCheck | On save | 1-3s | Type errors |
| Unit tests | On save | 5-15s | Logic errors |
| Integration | On commit | 1-5min | API contracts |
| E2E | On PR | 5-15min | User flows |
💡 **Tip**: Faster loops catch more bugs. Invest in making your test suite fast.
## 9.6 Todo as Instruction Mirrors
**Reading time**: 5 minutes
**Skill level**: Week 1+
TodoWrite isn't just tracking—it's an instruction mechanism. Well-crafted todos guide Claude's execution.
### The Mirror Principle
What you write as a todo becomes Claude's instruction:
```
❌ Vague Todo → Vague Execution
"Fix the bug"
✅ Specific Todo → Precise Execution
"Fix null pointer in getUserById when user not found - return null instead of throwing"
```
### Todo as Specification
```markdown
## Effective Todo Pattern
- [ ] **What**: Create user validation function
- [ ] **Where**: src/lib/validation.ts
- [ ] **How**: Use Zod schema with email, password rules
- [ ] **Verify**: Test with edge cases (empty, invalid format)
```
### Todo Granularity Guide
| Task Complexity | Todo Granularity | Example |
|-----------------|------------------|---------|
| Simple fix | 1-2 todos | "Fix typo in header component" |
| Feature | 3-5 todos | Auth flow steps |
| Epic | 10+ todos | Full feature with tests |
### Instruction Embedding
Embed constraints directly in todos:
```markdown
## Bad
- [ ] Add error handling
## Good
- [ ] Add error handling: try/catch around API calls,
log errors with context, return user-friendly messages,
use existing ErrorBoundary component
```
### Todo Templates
**Bug Fix:**
```markdown
- [ ] Reproduce: [steps to reproduce]
- [ ] Root cause: [investigation findings]
- [ ] Fix: [specific change needed]
- [ ] Verify: [test command or manual check]
```
**Feature:**
```markdown
- [ ] Design: [what components/functions needed]
- [ ] Implement: [core logic]
- [ ] Tests: [test coverage expectations]
- [ ] Docs: [if public API]
```
## 9.7 Output Styles
**Reading time**: 5 minutes
**Skill level**: Week 1+
Control how Claude responds to match your workflow preferences.
### Output Style Spectrum
```
← Minimal Verbose →
───────────────────────────────────────────────────────
Code only | Code + comments | Explanations | Tutorial
```
### Style Directives
Add to CLAUDE.md or prompt:
**Minimal (Expert Mode):**
```markdown
Output code only. No explanations unless asked.
Assume I understand the codebase.
```
**Balanced:**
```markdown
Explain significant decisions. Comment complex logic.
Skip obvious explanations.
```
**Verbose (Learning Mode):**
```markdown
Explain each step. Include alternatives considered.
Link to documentation for concepts used.
```
### Context-Aware Styles
```markdown
## In CLAUDE.md
### Output Preferences
- **Code reviews**: Detailed, cite specific lines
- **Bug fixes**: Minimal, show diff only
- **New features**: Balanced, explain architecture decisions
- **Refactoring**: Minimal, trust my review
```
### Format Control
**For code:**
```markdown
Format code output as:
- Full file with changes marked: // CHANGED
- Diff format for reviews
- Inline for small changes
```
**For explanations:**
```markdown
Explain using:
- Bullet points for lists
- Tables for comparisons
- Diagrams for architecture
```
### Output Templates
**Bug Fix Output:**
```markdown
**Root Cause**: [one line]
**Fix**: [code block]
**Test**: [verification command]
```
**Feature Output:**
```markdown
**Files Changed**: [list]
**Key Decisions**: [bullet points]
**Next Steps**: [if any]
```
## 9.8 Vibe Coding & Skeleton Projects
**Reading time**: 5 minutes
**Skill level**: Month 1
### Vibe Coding
"Vibe Coding" is rapid prototyping through natural conversation—exploring ideas before committing to implementation.
#### When to Vibe Code
- **Early exploration**: Testing if an approach works
- **Proof of concept**: Quick validation before full implementation
- **Learning**: Understanding a new library or pattern
#### Vibe Coding Session
```markdown
User: Let's explore how we could add real-time updates to the dashboard.
Don't write code yet, just brainstorm approaches.
Claude: Here are three approaches we could consider:
1. **WebSockets**: Full duplex, lowest latency
- Pro: Real-time push
- Con: Connection management complexity
2. **Server-Sent Events (SSE)**: One-way server push
- Pro: Simple, native browser support
- Con: One direction only
3. **Polling**: Periodic HTTP requests
- Pro: Simplest implementation
- Con: Not truly real-time, more server load
User: Let's vibe on option 2. Show me a minimal SSE setup.
Claude: [Provides minimal example for exploration]
```
#### Vibe Coding Rules
1. **No production code**: This is exploration only
2. **Throw away freely**: No attachment to vibe code
3. **Focus on learning**: Understand the approach
4. **Signal clearly**: "This is vibe code, not for production"
### Skeleton Projects
Skeleton projects are minimal, working templates that establish patterns before full implementation.
#### Skeleton Structure
```
project/
├── src/
│ ├── index.ts # Entry point (working)
│ ├── config.ts # Config structure (minimal)
│ ├── types.ts # Core types (defined)
│ └── features/
│ └── example/ # One working example
│ ├── route.ts
│ ├── service.ts
│ └── repo.ts
├── tests/
│ └── example.test.ts # One working test
└── package.json # Dependencies defined
```
#### Skeleton Principles
1. **It must run**: `pnpm dev` works from day 1
2. **One complete vertical**: Full stack for one feature
3. **Patterns, not features**: Shows HOW, not WHAT
4. **Minimal dependencies**: Only what's needed
#### Creating a Skeleton
```markdown
User: Create a skeleton for our new microservice. Include:
- Express setup
- One complete route (health check)
- Database connection pattern
- Test setup
- Docker configuration
Claude: [Creates minimal, working skeleton with these elements]
```
#### Skeleton Expansion
```
Skeleton (Day 1) → MVP (Week 1) → Full (Month 1)
────────────────────────────────────────────────────────────
1 route → 5 routes → 20 routes
1 test → 20 tests → 100+ tests
Basic config → Env-based → Full config
Local DB → Docker DB → Production DB
```
## 9.9 Batch Operations Pattern
**Reading time**: 5 minutes
**Skill level**: Week 1+
Batch operations improve efficiency and reduce context usage when making similar changes across files.
### When to Batch
| Scenario | Batch? | Why |
|----------|--------|-----|
| Same change in 5+ files | ✅ Yes | Efficiency |
| Related changes in 3 files | ✅ Yes | Coherence |
| Unrelated fixes | ❌ No | Risk of errors |
| Complex refactoring | ⚠️ Maybe | Depends on pattern |
### Batch Patterns
#### 1. Import Updates
```markdown
User: Update all files in src/components to use the new Button import:
- Old: import { Button } from "~/ui/button"
- New: import { Button } from "~/components/ui/button"
```
#### 2. API Migration
```markdown
User: Migrate all API calls from v1 to v2:
- Change: /api/v1/* → /api/v2/*
- Update response handling for new format
- Files: src/services/*.ts
```
#### 3. Pattern Application
```markdown
User: Add error boundaries to all page components:
- Wrap each page export with ErrorBoundary
- Use consistent error fallback
- Files: src/pages/**/*.tsx
```
### Batch Execution Strategy
```
1. Identify scope → List all affected files
2. Define pattern → Exact change needed
3. Create template → One example implementation
4. Batch apply → Apply to all files
5. Verify all → Run tests, typecheck
```
### Batch with Claude
```markdown
## Effective Batch Request
"Apply this change pattern to all matching files:
**Pattern**: Add 'use client' directive to components using hooks
**Scope**: src/components/**/*.tsx
**Rule**: If file contains useState, useEffect, or useContext
**Change**: Add 'use client' as first line
List affected files first, then make changes."
```
---
# 10. Reference
**Purpose**: Quick lookup for all Claude Code information
## 10.1 Commands Table
### Built-in Commands
| Command | Action | Category |
|---------|--------|----------|
| `/help` | Show all available commands | Navigation |
| `/clear` | Clear conversation history | Session |
| `/compact` | Summarize and compress context | Context |
| `/status` | Show session info (context, cost) | Info |
| `/plan` | Enter Plan Mode | Mode |
| `/execute` | Exit Plan Mode | Mode |
| `/rewind` | Undo recent changes | Edit |
| `/exit` | Exit Claude Code | Session |
| `Ctrl+D` | Exit Claude Code | Session |
### Quick Actions
| Action | Shortcut |
|--------|----------|
| Run shell command | `!command` |
| Reference file | `@filename` |
| Cancel operation | `Ctrl+C` |
| Retry last | `Ctrl+R` |
| Dismiss suggestion | `Esc` |
## 10.2 Keyboard Shortcuts
| Shortcut | Action |
|----------|--------|
| `Enter` | Send message |
| `Shift+Enter` | New line in message |
| `Ctrl+C` | Cancel current operation |
| `Ctrl+D` | Exit Claude Code |
| `Ctrl+R` | Retry last operation |
| `Ctrl+L` | Clear screen (keeps context) |
| `Tab` | Autocomplete file paths |
| `↑` / `↓` | Navigate command history |
| `Esc` | Dismiss current suggestion |
## 10.3 Configuration Reference
### CLAUDE.md Locations
| Location | Scope | Committed |
|----------|-------|-----------|
| `~/.claude/CLAUDE.md` | All projects | N/A |
| `/project/CLAUDE.md` | This project | ✅ Yes |
| `/project/.claude/CLAUDE.md` | Personal | ❌ No |
### Settings Files
| File | Purpose | Committed |
|------|---------|-----------|
| `settings.json` | Hook configuration | ✅ Yes |
| `settings.local.json` | Permission overrides | ❌ No |
### Permission Patterns
| Pattern | Matches |
|---------|---------|
| `Bash(git *)` | Any git command |
| `Bash(npm test)` | Exactly npm test |
| `Edit` | All file edits |
| `Write` | All file writes |
| `WebSearch` | Web search |
| `mcp__serena__*` | All Serena tools |
## 10.4 Troubleshooting
| Symptom | Cause | Solution |
|---------|-------|----------|
| "Context too long" | Used 100% context | `/clear` or `/compact` |
| Slow responses | High context usage | `/compact` |
| "Permission denied" | Security settings | Check `settings.local.json` |
| Hook not running | Registration error | Check `settings.json` matcher |
| MCP tool not found | Server not running | Check `mcp.json` config |
| Agent not found | File naming | Check `.claude/agents/` |
| Command not found | Path error | Check `.claude/commands/` |
### Context Recovery
| Context Level | Recommended Action |
|---------------|-------------------|
| 0-50% | Continue normally |
| 50-75% | Be more specific in queries |
| 75-90% | Use `/compact` |
| 90%+ | Use `/clear` |
### Common Errors
**"Tool execution failed"**
- Check tool permissions in `settings.local.json`
- Verify command syntax
- Check for missing dependencies
**"Agent not available"**
- Verify agent file exists in `.claude/agents/`
- Check YAML frontmatter syntax
- Restart Claude Code session
**"Hook blocked operation"**
- Check hook exit code (2 = blocked)
- Review hook error message
- Adjust hook rules if needed
## 10.5 Cheatsheet
### One-Page Quick Reference
```
╔══════════════════════════════════════════════════════════╗
║ CLAUDE CODE CHEATSHEET ║
╠══════════════════════════════════════════════════════════╣
║ ║
║ ESSENTIAL COMMANDS ║
║ ───────────────── ║
║ /help Show commands /clear Fresh start ║
║ /status Session info /compact Save context ║
║ /plan Safe mode /rewind Undo changes ║
║ /exit Quit Ctrl+C Cancel ║
║ ║
║ QUICK ACTIONS ║
║ ───────────── ║
║ !command Run shell @file Reference file ║
║ Ctrl+R Retry ↑/↓ History ║
║ ║
║ CONTEXT MANAGEMENT ║
║ ────────────────── ║
║ 🟢 0-50% Work freely ║
║ 🟡 50-75% Be selective ║
║ 🔴 75-90% /compact now ║
║ ⚫ 90%+ /clear required ║
║ ║
║ PERMISSION MODES ║
║ ──────────────── ║
║ Default Ask before changes ║
║ Auto-accept Execute without asking ║
║ Plan Mode Read-only exploration ║
║ ║
║ CONFIGURATION ║
║ ───────────── ║
║ ~/.claude/CLAUDE.md Global settings ║
║ /project/CLAUDE.md Project settings ║
║ .claude/settings.json Hooks config ║
║ .claude/settings.local.json Permission overrides ║
║ ║
║ .claude/ FOLDER ║
║ ─────────────── ║
║ agents/ Custom agents commands/ Slash commands ║
║ hooks/ Event scripts rules/ Auto-load rules ║
║ skills/ Knowledge modules ║
║ ║
║ ULTRATHINK LEVELS ║
║ ───────────────── ║
║ --think ~4K tokens Standard analysis ║
║ --think-hard ~10K tokens Deep analysis ║
║ --ultrathink ~32K tokens Maximum depth ║
║ ║
║ MCP SERVERS ║
║ ─────────── ║
║ Serena Semantic code analysis ║
║ Context7 Library documentation ║
║ Sequential Structured reasoning ║
║ Postgres Database queries ║
║ Playwright Browser automation ║
║ ║
║ HOOKS (events) ║
║ ────────────── ║
║ PreToolUse Before tool (security) ║
║ PostToolUse After tool (format, log) ║
║ UserPromptSubmit On message (enrich context) ║
║ ║
║ WORKFLOW ║
║ ──────── ║
║ Describe → Analyze → Review → Accept/Reject → Verify ║
║ ║
║ BEST PRACTICE: Always read the diff before accepting! ║
║ ║
╚══════════════════════════════════════════════════════════╝
```
## 10.6 Daily Workflow & Checklists
### Daily Workflow Pattern
```
┌─────────────────────────────────────────────────────────────┐
│ DAILY WORKFLOW │
├─────────────────────────────────────────────────────────────┤
│ │
│ MORNING (Setup) │
│ ─────────────── │
│ □ Git pull latest changes │
│ □ Review context with /status │
│ □ Load project memory (/sc:load if using Serena) │
│ □ Review yesterday's progress │
│ │
│ WORK SESSION │
│ ──────────── │
│ □ Define task clearly before starting │
│ □ Use TodoWrite for multi-step work │
│ □ Commit after each completed task │
│ □ /compact when context >70% │
│ □ Take breaks every 90 minutes │
│ │
│ END OF DAY │
│ ────────── │
│ □ Commit all work in progress │
│ □ Save session (/sc:save) │
│ □ Note blockers or next steps │
│ □ Push to remote │
│ │
└─────────────────────────────────────────────────────────────┘
```
### Task-Specific Checklists
#### Bug Fix Checklist
```
□ Reproduce the bug (confirm it exists)
□ Identify root cause (not just symptoms)
□ Write failing test (captures the bug)
□ Implement fix
□ Verify test passes
□ Check for regressions
□ Update documentation if needed
□ Commit with descriptive message
```
#### Feature Implementation Checklist
```
□ Requirements clear? (Ask if not)
□ Design approach documented
□ Break into small tasks (TodoWrite)
□ Implement core functionality first
□ Add tests alongside code
□ Handle error cases
□ Update types/interfaces
□ Run full test suite
□ Code review (self or peer)
□ Documentation updated
```
#### Code Review Checklist
```
□ Code compiles without errors
□ Tests pass (new and existing)
□ No security vulnerabilities
□ Performance implications considered
□ Error handling adequate
□ Code style consistent
□ No commented-out code
□ No debug statements left
□ Documentation updated
```
#### Refactoring Checklist
```
□ Tests exist before refactoring
□ All tests pass before starting
□ Small, incremental changes
□ Run tests after each change
□ No behavior changes (unless intended)
□ Remove dead code
□ Update imports and references
□ Final test run passes
```
### Prompt Quality Checklist
Use this before sending complex requests:
```
□ WHAT: Clear deliverable described?
□ WHERE: File paths/locations specified?
□ HOW: Constraints/approach mentioned?
□ WHY: Context for decision-making?
□ VERIFY: Success criteria defined?
```
**Example applying checklist:**
```
❌ Vague: "Add user authentication"
✅ Complete:
"Add JWT authentication to the /api/login endpoint.
- WHERE: src/api/auth/login.ts
- HOW: Use jsonwebtoken library (already in deps),
bcrypt for password comparison
- CONSTRAINTS: Token expires in 24h, include userId and role
- VERIFY: Test with wrong password, expired token, invalid token"
```
---
# Appendix: Templates Collection
## A.1 Agent Template
```markdown
---
name: your-agent-name
description: Use this agent when [specific trigger]
model: sonnet
tools: Read, Write, Edit, Bash, Grep, Glob
skills: []
---
# Agent Name
## Role Definition
You are an expert in [domain].
## Activation Triggers
Use this agent when:
- [Trigger 1]
- [Trigger 2]
## Methodology
1. [Step 1]
2. [Step 2]
3. [Step 3]
## Output Format
[Expected deliverables]
## Examples
[Concrete usage examples]
```
## A.2 Skill Template
```markdown
---
name: skill-name
description: Expert guidance for [domain]
allowed-tools: Read, Grep, Bash
context: fork
agent: specialist
---
# Skill Name
## Expertise Areas
- [Area 1]
- [Area 2]
## Methodology
1. [Step 1]
2. [Step 2]
## Checklists
- [ ] [Check 1]
- [ ] [Check 2]
## Examples
[Good and bad patterns]
```
## A.3 Command Template
```markdown
# Command Name
## Purpose
[What this command does]
## Process
1. **Step 1**: [Instructions]
2. **Step 2**: [Instructions]
## Arguments
$ARGUMENTS usage: [How to handle]
## Output Format
[Expected output]
```
## A.4 Hook Templates
### PreToolUse (Security)
```bash
#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
# Block dangerous patterns
[[ "$COMMAND" =~ "dangerous-pattern" ]] && { echo "BLOCKED" >&2; exit 2; }
exit 0
```
### PostToolUse (Formatting)
```bash
#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
# Auto-format
[[ "$FILE_PATH" =~ \.(ts|tsx)$ ]] && npx prettier --write "$FILE_PATH" 2>/dev/null
exit 0
```
### UserPromptSubmit (Context)
```bash
#!/bin/bash
CONTEXT="[Custom context here]"
cat << EOF
{"hookSpecificOutput":{"additionalContext":"$CONTEXT"}}
EOF
exit 0
```
## A.5 settings.json Template
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [{"type": "command", "command": ".claude/hooks/security.sh", "timeout": 5000}]
}
],
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [{"type": "command", "command": ".claude/hooks/format.sh"}]
}
],
"UserPromptSubmit": [
{
"matcher": "",
"hooks": [{"type": "command", "command": ".claude/hooks/context.sh"}]
}
]
}
}
```
## A.6 settings.local.json Template
```json
{
"permissions": {
"allow": [
"Bash(git *)",
"Bash(npm test)",
"Bash(pnpm *)",
"Edit",
"Write"
],
"deny": [
"Bash(rm -rf *)",
"Bash(sudo *)"
],
"ask": [
"Bash(npm publish)",
"Bash(git push --force)"
]
}
}
```
## A.7 CLAUDE.md Template
```markdown
# Project Name
## Tech Stack
- [Technology 1]
- [Technology 2]
## Code Conventions
- [Convention 1]
- [Convention 2]
## Architecture
- [Pattern 1]
- [Pattern 2]
## Commands
- `npm run dev` - Start development
- `npm test` - Run tests
```
## A.8 Prompt Templates
### Feature Request Prompt
```markdown
## Feature: [Name]
**Deliverable**: [Concrete output]
**Location**: [File paths]
**Requirements**:
1. [Requirement 1]
2. [Requirement 2]
**Constraints**:
- Must use [existing pattern/library]
- Must handle [edge case]
**Acceptance Criteria**:
- [ ] [Criterion 1]
- [ ] [Criterion 2]
**Verification**: [Commands to verify]
```
### Bug Fix Prompt
```markdown
## Bug: [Brief description]
**Observed**: [What happens]
**Expected**: [What should happen]
**Reproduce**: [Steps or file:line reference]
**Suspected Cause**: [If known]
**Files to Check**:
- [file1.ts]
- [file2.ts]
**Fix Should**:
- [ ] Resolve the issue
- [ ] Not break existing tests
- [ ] Include test for this case
```
### Refactoring Prompt
```markdown
## Refactor: [Component/Function name]
**Current State**: [What's wrong]
**Target State**: [What we want]
**Scope**: [Files affected]
**Approach**:
1. [Step 1]
2. [Step 2]
**Constraints**:
- No behavior change
- Keep API surface same
- [Other constraints]
**Verify**: [Test commands]
```
### Code Review Prompt
```markdown
## Review: [PR/Files description]
**Focus Areas**:
- [ ] Security vulnerabilities
- [ ] Performance concerns
- [ ] Code style compliance
- [ ] Test coverage
**Context**: [Why these changes]
**Questions**:
1. [Specific question about approach]
2. [Specific question about implementation]
```
### Architecture Discussion Prompt
```markdown
## Architecture: [Topic]
**Current State**:
[Describe current architecture]
**Problem**:
[What's not working or missing]
**Options Considered**:
1. **Option A**: [Description]
- Pro: [...]
- Con: [...]
2. **Option B**: [Description]
- Pro: [...]
- Con: [...]
**Constraints**:
- [Constraint 1]
- [Constraint 2]
**Questions**:
1. [What you need Claude to analyze]
```
## A.9 Success Metrics & Maturity Model
### Claude Code Maturity Model
| Level | Name | Characteristics | Typical Timeline |
|-------|------|-----------------|------------------|
| 1 | **Beginner** | Uses basic commands, accepts all changes, minimal config | Day 1-7 |
| 2 | **Competent** | Reviews diffs, uses /compact, basic CLAUDE.md | Week 1-2 |
| 3 | **Proficient** | Creates agents, uses hooks, Plan Mode mastery | Week 2-4 |
| 4 | **Advanced** | MCP servers, multi-agent workflows, full automation | Month 1-2 |
| 5 | **Expert** | Custom tooling, CI/CD integration, team patterns | Month 2+ |
### Success Metrics by Area
#### Productivity Metrics
| Metric | Beginner | Proficient | Expert |
|--------|----------|------------|--------|
| Tasks completed/day | 2-3 | 5-7 | 10+ |
| Context resets/day | 3+ | 1-2 | 0-1 |
| Rejected changes | <30% | <10% | <5% |
| Time to first commit | >1h | 30min | <15min |
#### Quality Metrics
| Metric | Target | Measure |
|--------|--------|---------|
| Test coverage | >80% | Coverage reports |
| Type errors | 0 | `tsc --noEmit` |
| Lint violations | 0 | Linter output |
| Security issues | 0 | Security scan |
#### Efficiency Metrics
| Metric | Baseline | Optimized |
|--------|----------|-----------|
| Context usage | ~90% | <70% |
| Parallel operations | None | 3-5 simultaneous |
| Agent delegation | Never | When appropriate |
| Hook automation | None | Full automation |
### Self-Assessment Checklist
#### Day 1 Proficiency
```
□ Can start Claude Code session
□ Know essential commands (/help, /clear, /status)
□ Understand permission prompts
□ Can describe tasks clearly
□ Know how to cancel operations (Ctrl+C)
```
#### Week 1 Proficiency
```
□ Use /compact to manage context
□ Review diffs before accepting
□ Have basic CLAUDE.md setup
□ Understand Plan Mode purpose
□ Can use file references (@filename)
```
#### Month 1 Proficiency
```
□ Created at least 1 custom agent
□ Use hooks for automation
□ Understand MCP server selection
□ Can manage multi-step tasks
□ Use appropriate think levels
```
### Improvement Tracking
```markdown
## Weekly Retrospective Template
**Week of**: [Date]
**Accomplishments**:
- [Major task completed]
- [Skill learned]
**Challenges**:
- [What was difficult]
- [Where Claude struggled]
**Improvements Made**:
- [Config change]
- [New pattern adopted]
**Next Week Goals**:
- [ ] [Improvement 1]
- [ ] [Improvement 2]
**Claude Usage Stats**:
- Sessions: [count]
- Avg context at reset: [%]
- Commands created: [count]
- Agents created: [count]
```
---
## About This Guide
**End of Guide**
---
**Author**: [Florian BRUNIAUX](https://github.com/florianb) | Founding Engineer [@Méthode Aristote](https://methode-aristote.fr)
**Written with**: Claude (Anthropic) - This guide was collaboratively written with Claude Code, demonstrating the tool's capabilities for technical documentation.
**Inspired by**: [Claudelog.com](https://claudelog.com/) - An excellent resource for Claude Code tips, patterns, and advanced techniques that served as a major reference for this guide.
**License**: MIT - Feel free to use, adapt, and share.
**Contributions**: Issues and PRs welcome.
**Last updated**: January 2025 | **Version**: 1.0
Reference in a new issue View git blame Copy permalink