メニュー
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/tools-only/X-Skills --skill plannerコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
Index of Build Systems Skills
Coordination patterns for distributed dataflow systems including barriers, epochs, and distributed snapshots
Windowing, sessionization, time-series aggregation, and late data handling for streaming systems
SOC 職業分類に基づく
SKILL.md を表示中
| title | The Ultimate Claude Code Guide |
| description | Comprehensive self-contained guide to mastering Claude Code from zero to power user |
| tags | ["guide","reference","workflows","agents","hooks","mcp","security"] |
A comprehensive, self-contained guide to mastering Claude Code - from zero to power user.
Author: Florian BRUNIAUX | Founding Engineer @Méthode Aristote
Written with: Claude (Anthropic)
Reading time: ~30-40 hours (full) | ~15 minutes (Quick Start only)
Last updated: January 2026
Version: 3.29.0
This guide is not official Anthropic documentation. It's a community resource based on my exploration of Claude Code over several months.
What you'll find:
What you won't find:
Use critically. Experiment. Share what works for you.
⚠️ Note (Jan 2026): If you've heard about ClawdBot recently, that's a different tool. ClawdBot is a self-hosted chatbot assistant accessible via messaging apps (Telegram, WhatsApp, etc.), designed for personal automation and smart home use cases. Claude Code is a CLI tool for developers (terminal/IDE integration) focused on software development workflows. Both use Claude models but serve distinct audiences and use cases. More details in Appendix B: FAQ.
If you only have 5 minutes, here's what you need to know:
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
Describe → Claude Analyzes → Review Diff → Accept/Reject → Verify
| Context % | Action |
|---|---|
| 0-50% | Work freely |
| 50-70% | Be selective |
| 70-90% | /compact now |
| 90%+ | /clear required |
These thresholds are based on my experience. Your optimal workflow may differ depending on task complexity and working style.
~/.claude/CLAUDE.md → Global (all projects)
/project/CLAUDE.md → Project (committed)
/project/.claude/ → Personal (not committed)
| 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...) |
| Plugins | Community-created extension packages |
/compact before context gets criticalSimple 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.
Quick jump: Installation · First Workflow · Essential Commands · Permission Modes · Productivity Checklist · Migrating from Other Tools · Beginner Mistakes
Reading time: 15 minutes
Skill level: Beginner
Goal: Go from zero to productive
Choose your preferred installation method based on your operating system:
/*──────────────────────────────────────────────────────────────*/
/* Universal Method */ npm install -g @anthropic-ai/claude-code
/*──────────────────────────────────────────────────────────────*/
/* Windows (CMD) */ npm install -g @anthropic-ai/claude-code
/* Windows (PowerShell) */ irm https://claude.ai/install.ps1 | iex
/*──────────────────────────────────────────────────────────────*/
/* macOS (npm) */ npm install -g @anthropic-ai/claude-code
/* macOS (Homebrew) */ brew install claude-code
/* macOS (Shell Script) */ curl -fsSL https://claude.ai/install.sh | sh
/*──────────────────────────────────────────────────────────────*/
/* Linux (npm) */ npm install -g @anthropic-ai/claude-code
/* Linux (Shell Script) */ curl -fsSL https://claude.ai/install.sh | sh
claude --version
Keep Claude Code up to date for the latest features, bug fixes, and model improvements:
# Check for available updates
claude update
# Alternative: Update via npm
npm update -g @anthropic-ai/claude-code
# Verify the update
claude --version
# Check system health after update
claude doctor
Available maintenance commands:
| Command | Purpose | When to Use |
|---|---|---|
claude update | Check and install updates | Weekly or when encountering issues |
claude doctor | Verify auto-updater health | After system changes or if updates fail |
claude --version | Display current version | Before reporting bugs |
claude auth login | Authenticate from the command line | CI/CD, devcontainers, scripted setups |
claude auth status | Check current authentication state | Verify which account/method is active |
claude auth logout | Clear stored credentials | Shared machines, security cleanup |
Update frequency recommendations:
claude doctor to verify health| Platform | Global Config Path | Shell Config |
|---|---|---|
| macOS/Linux | ~/.claude/ | ~/.zshrc or ~/.bashrc |
| Windows | %USERPROFILE%\.claude\ | PowerShell profile |
Windows Users: Throughout this guide, when you see
~/.claude/, use%USERPROFILE%\.claude\orC:\Users\YourName\.claude\instead.
cd your-project
claude
On first launch:
Note: Claude Code requires an active Anthropic subscription. See claude.com/pricing for current plans and token limits.
Let's fix a bug together. This demonstrates the core interaction loop.
You: There's a bug in the login function - users can't log in with email addresses containing a plus sign
Claude will:
- 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.
y to accept the changen to reject and ask for alternativese to edit the change manuallyYou: Run the tests to make sure this works
Claude will run your test suite and report results.
You: Commit this fix
Claude will create a commit with an appropriate message.
These 7 commands are the ones I use most frequently:
| 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 |
| Shortcut | Action | Example |
|---|---|---|
!command | Run shell command directly | !git status, !npm test |
@file.ts | Reference a specific file | @src/app.tsx, @README.md |
Ctrl+C | Cancel current operation | Stop long-running analysis |
Ctrl+R | Search command history | Find previous prompts |
Esc | Stop Claude mid-action | Interrupt current operation |
!Execute commands immediately without asking Claude to do it:
# Quick status checks
!git status
!npm run test
!docker ps
# View logs
!tail -f logs/app.log
!cat package.json
# Quick searches
!grep -r "TODO" src/
!find . -name "*.test.ts"
When to use ! vs asking Claude:
Use ! for... | Ask Claude for... |
|---|---|
Quick status checks (!git status) | Git operations requiring decisions |
View commands (!cat, !ls) | File analysis and understanding |
| Already-known commands | Complex command construction |
| Fast iteration in terminal | Commands you're unsure about |
Example workflow:
You: !git status
Output: Shows 5 modified files
You: Create a commit with these changes, following conventional commits
Claude: [Analyzes files, suggests commit message]
@Reference specific files in your prompts for targeted operations:
# Single file
Review @src/auth/login.tsx for security issues
# Multiple files
Refactor @src/utils/validation.ts and @src/utils/helpers.ts to remove duplication
# With wildcards (in some contexts)
Analyze all test files @src/**/*.test.ts
# Relative paths work
Check @./CLAUDE.md for project conventions
Why use @:
Example:
# Without @
You: Fix the authentication bug
Claude: Which file contains the authentication logic? [Wastes time searching]
# With @
You: Fix the authentication bug in @src/auth/middleware.ts
Claude: [Reads file on-demand and proposes fix]
Claude Code supports direct image input for visual analysis, mockup implementation, and design feedback.
How to use images:
Paste directly in terminal (macOS/Linux/Windows with modern terminal):
Cmd+Shift+4 on macOS, Win+Shift+S on Windows)Cmd+V / Ctrl+VDrag and drop (some terminals):
Reference with path:
Analyze this mockup: /path/to/design.png
Common use cases:
# Implement UI from mockup
You: [Paste screenshot of Figma design]
Implement this login screen in React with Tailwind CSS
# Debug visual issues
You: [Paste screenshot of broken layout]
The button is misaligned. Fix the CSS.
# Analyze diagrams
You: [Paste architecture diagram]
Explain this system architecture and identify potential bottlenecks
# Code from whiteboard
You: [Paste photo of whiteboard algorithm]
Convert this algorithm to Python code
# Accessibility audit
You: [Paste screenshot of UI]
Review this interface for WCAG 2.1 compliance issues
Supported formats: PNG, JPG, JPEG, WebP, GIF (static)
Best practices:
Example workflow:
You: [Paste screenshot of error message in browser console]
This error appears when users click the submit button. Debug it.
Claude: I can see the error "TypeError: Cannot read property 'value' of null".
This suggests the form field reference is incorrect. Let me check your form handling code...
[Reads relevant files and proposes fix]
Limitations:
/status to monitor context usage after pasting images💡 Pro tip: Take screenshots of error messages, design mockups, and documentation instead of describing them textually. Visual input is often faster and more precise than written descriptions.
When designing UI before implementation, low-fidelity wireframes help Claude understand intent without over-constraining the output. Here are recommended tools that work well with Claude Code:
| Tool | Type | Price | MCP Support | Best For |
|---|---|---|---|---|
| Excalidraw | Hand-drawn style | Free | ✓ Community | Quick wireframes, architecture diagrams |
| tldraw | Minimalist canvas | Free | Emerging | Real-time collaboration, custom integrations |
| Pencil | IDE-native canvas | Free* | ✓ Native | Claude Code integrated, AI agents, git-based |
| Frame0 | Low-fi + AI | Free | ✓ | Modern Balsamiq alternative, AI-assisted |
| Paper sketch | Physical | Free | N/A | Fastest iteration, zero setup |
Excalidraw (excalidraw.com):
github.com/yctimlin/mcp_excalidrawtldraw (tldraw.com):
Frame0 (frame0.app):
Pencil (pencil.dev):
.pen JSON, git-versionnable with branch/merge support⚠️ Note: Launched January 2026, strong traction (1M+ views, FAANG adoption) but still maturing. Currently free; pricing model TBD. Recommended for early adopters comfortable with rapid iteration.
Paper + Photo:
Recommended export settings: PNG format, 1000-1200px on longest side, high contrast
Figma provides an official MCP server (announced 2025) that gives Claude direct access to your design files, dramatically reducing token usage compared to screenshots alone.
Setup options:
# Remote MCP (all Figma plans, any machine)
claude mcp add --transport http figma https://mcp.figma.com/mcp
# Desktop MCP (requires Figma desktop app with Dev Mode)
claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp
Available tools via Figma MCP:
| Tool | Purpose | Tokens |
|---|---|---|
get_design_context | Extracts React+Tailwind structure from frames | Low |
get_variable_defs | Retrieves design tokens (colors, spacing, typography) | Very low |
get_code_connect_map | Maps Figma components → your codebase | Low |
get_screenshot | Captures visual screenshot of frame | High |
get_metadata | Returns node properties, IDs, positions | Very low |
Why use Figma MCP over screenshots?
Recommended workflow:
1. get_metadata → Understand overall structure
2. get_design_context → Get component hierarchy for specific frames
3. get_variable_defs → Extract design tokens once per project
4. get_screenshot → Only when visual reference needed
Example session:
You: Implement the dashboard header from Figma
Claude: [Calls get_design_context for header frame]
→ Returns: React structure with Tailwind classes, exact spacing
Claude: [Calls get_variable_defs]
→ Returns: --color-primary: #3B82F6, --spacing-md: 16px
Claude: [Implements component matching Figma exactly]
Prerequisites:
MCP config file (examples/mcp-configs/figma.json):
{
"mcpServers": {
"figma": {
"transport": "http",
"url": "https://mcp.figma.com/mcp"
}
}
}
Understanding Claude's image processing helps optimize for speed and accuracy.
Resolution guidelines:
| Range | Effect |
|---|---|
| < 200px | Loss of precision, text unreadable |
| 200-1000px | Sweet spot for most wireframes |
| 1000-1568px | Optimal quality/token balance |
| 1568-8000px | Auto-downscaled (wastes upload time) |
| > 8000px | Rejected by API |
Token calculation: (width × height) / 750 ≈ tokens consumed
| Image Size | Approximate Tokens |
|---|---|
| 200×200 | ~54 tokens |
| 500×500 | ~334 tokens |
| 1000×1000 | ~1,334 tokens |
| 1568×1568 | ~3,279 tokens |
Format recommendations:
| Format | Use When |
|---|---|
| PNG | Wireframes, diagrams, text, sharp lines |
| WebP | General screenshots, good compression |
| JPEG | Photos only—compression artifacts harm line detection |
| GIF | Avoid (static only, poor quality) |
Optimization checklist:
/status after pasting to monitor context usage💡 Token tip: A 1000×1000 wireframe uses ~1,334 tokens. The same information as structured text (via Figma MCP) might use 200-400 tokens. Use screenshots for visual context, structured data for implementation.
Claude Code allows you to continue previous conversations across terminal sessions, maintaining full context and conversation history.
Two ways to resume:
Continue last session (--continue or -c):
# Automatically resumes your most recent conversation
claude --continue
# Short form
claude -c
Resume specific session (--resume <id> or -r <id>):
# Resume a specific session by ID
claude --resume abc123def
# Short form
claude -r abc123def
Link to a GitHub PR (--from-pr <number>, v2.1.49+):
# Start a session linked to a specific PR
claude --from-pr 123
# Sessions created via gh pr create during a Claude session
# are auto-linked to that PR — use --from-pr to resume them
gh pr create --title "Add auth" --body "..."
# Later:
claude --from-pr 123 # Resumes the session context for this PR
Useful for continuing work on a feature exactly where you left off relative to a specific PR — no need to remember session IDs.
Finding session IDs:
# Native: Interactive session picker
claude --resume
# Native: List via Serena MCP (if configured)
claude mcp call serena list_sessions
# Recommended: Fast search with ready-to-use resume commands
# See examples/scripts/session-search.sh (bash, zero dependencies, 15ms list, 400ms search)
# See examples/scripts/cc-sessions.py (Python, incremental index, partial resume, branch filter)
cs # List 10 most recent sessions
cs "authentication" # Full-text search across all sessions
# Sessions are also shown when you exit
You: /exit
Session ID: abc123def (saved for resume)
Session Search Tools: For fast session search, see session-search.sh (bash, lightweight) and cc-sessions.py (Python, advanced features: incremental index, partial ID resume, branch filter). Also: Observability Guide.
Common use cases:
| Scenario | Command | Why |
|---|---|---|
| Interrupted work | claude -c | Pick up exactly where you left off |
| Multi-day feature | claude -r abc123 | Continue complex task across days |
| After break/meeting | claude -c | Resume without losing context |
| Parallel projects | claude -r <id> | Switch between different project contexts |
| Code review follow-up | claude -r <id> | Address review comments in original context |
Example workflow:
# Day 1: Start implementing authentication
cd ~/project
claude
You: Implement JWT authentication with refresh tokens
Claude: [Analysis and initial implementation]
You: /exit
Session ID: auth-feature-xyz (27% context used)
# Day 2: Continue the work
cd ~/project
claude --continue
Claude: Resuming session auth-feature-xyz...
You: Add rate limiting to the auth endpoints
Claude: [Continues with full context of Day 1 work]
Best practices:
/exit properly: Always exit with /exit or Ctrl+D (not force-kill) to ensure session is saved/status and use research-backed thresholds:
Resume vs. fresh start:
| Use Resume When... | Start Fresh When... |
|---|---|
| Continuing a specific feature/task | Switching to unrelated work |
| Building on previous decisions | Previous session went off track |
| Context is still relevant (<75%) | Context is bloated (>90%) |
| Multi-step implementation in progress | Quick one-off questions |
Limitations:
/clear)Context preservation:
When you resume, Claude retains:
Combining with MCP Serena:
For advanced session management with project memory and symbol tracking:
# Initialize Serena memory for the project
claude mcp call serena initialize_session
# Work with full session persistence
You: Implement user authentication
Claude: [Works with Serena tracking symbols and context]
# Exit and resume later with full project memory
claude -c
Claude: [Resumes with Serena's persistent project understanding]
💡 Pro tip: Use
claude -cas your default way to start Claude Code in active projects. This ensures you never lose context from previous sessions unless you explicitly want a fresh start withclaude(no flags).
Claude Code has five permission modes that control how much autonomy Claude has:
Claude asks permission before:
This is the safest mode for learning.
acceptEdits)You: Turn on auto-accept for the rest of this session
Claude auto-approves file edits but still asks for shell commands. Use when you trust the edits and want speed.
⚠️ Warning: Only use auto-accept for well-defined, reversible operations.
/plan
Claude can only read and analyze, no modifications allowed. Perfect for:
Exit with /execute when ready to make changes.
dontAsk)Auto-denies tools unless pre-approved via /permissions or permissions.allow rules. Claude never interrupts with permission prompts: if a tool isn't explicitly allowed, it's silently denied.
Use for restrictive workflows where you want tight control over which tools run, without interactive confirmation.
bypassPermissions)Auto-approves everything, including shell commands. No permission prompts at all.
⚠️ Warning: Only use in sandboxed CI/CD environments. Requires --dangerously-skip-permissions to enable from CLI. Never use on production systems or with untrusted code.
You're ready for Day 2 when you can:
!@/clear to start fresh/status to check context usage/exit or Ctrl+DSwitching from GitHub Copilot, Cursor, or other AI assistants? Here's what you need to know.
| Feature | GitHub Copilot | Cursor | Claude Code |
|---|---|---|---|
| Interaction | Inline autocomplete | Chat + autocomplete | CLI + conversation |
| Context | Current file | Open files | Entire project |
| Autonomy | Suggestions only | Edit + chat | Full task execution |
| Customization | Limited | Extensions | Agents, skills, hooks, MCP |
| Cost Model | $10-20/month flat | $20/month flat | Pay-per-use ($0.10-$0.50/hour) |
Key mindset shift: Claude Code is a structured context system, not a chatbot or autocomplete tool. You build persistent context (CLAUDE.md, skills, hooks) that compounds over time — see §2.5.
Use Copilot for:
Use Claude Code for:
Workflow example:
# Morning: Plan feature with Claude Code
claude
You: "I need to add user authentication. What's the best approach for this codebase?"
# Claude analyzes project, suggests architecture
# During coding: Use Copilot for inline completions
# Type in VS Code, Copilot autocompletes
# Afternoon: Debug with Claude Code
claude
You: "Login fails on mobile but works on desktop. Debug this."
# Claude systematically investigates
# End of day: Review with Claude Code
claude
You: "Review my changes today. Check for security issues."
# Claude reviews all modified files
Stick with Cursor if:
Switch to Claude Code if:
You can use both tools simultaneously:
# Cursor for editing and quick changes
# Claude Code in terminal for complex tasks
# Example workflow:
# 1. Use Cursor to explore and make quick edits
# 2. Open terminal: claude
# 3. Ask Claude Code: "Review my changes and suggest improvements"
# 4. Apply suggestions in Cursor
# 5. Use Claude Code to generate tests
□ Complete Quick Start (Section 1)
□ Understand context management (critical!)
□ Try 3-5 small tasks (bug fixes, small features)
□ Learn when to use /plan mode
□ Practice reviewing diffs before accepting
□ Create project CLAUDE.md file
□ Set up 1-2 custom commands for frequent tasks
□ Configure MCP servers (Serena, Context7)
□ Define your hybrid workflow (when to use Claude Code vs. other tools)
□ Track costs and optimize based on usage
□ Create custom agents for specialized tasks
□ Set up hooks for automation (formatting, linting)
□ Integrate into CI/CD if applicable
□ Build team patterns if working with others
□ Refine CLAUDE.md based on learnings
Issue 1: "I miss inline suggestions"
Issue 2: "Context switching is annoying"
Issue 3: "I don't know when to use which tool"
Issue 4: "Claude Code is slower than autocomplete"
Issue 5: "Costs are unpredictable"
/compact, be specific in queriesStrategy 1: Gradual (Recommended)
Week 1: Use Claude Code 1-2 times/day for specific tasks
Week 2: Use Claude Code for all debugging and reviews
Week 3: Use Claude Code for feature implementation
Week 4: Full workflow integration
Strategy 2: Cold Turkey
Day 1: Disable Copilot/Cursor, force yourself to use only Claude Code
Day 2-3: Frustration period (learning curve)
Day 4-7: Productivity recovery
Week 2+: Full proficiency
Strategy 3: Task-Based
Use Claude Code exclusively for:
- All new features
- All debugging sessions
- All code reviews
Keep Copilot/Cursor for:
- Quick edits
- Autocomplete
You know you've successfully migrated when:
Subjective productivity indicators (your experience may vary):
AI-generated code requires proportional verification based on risk level. Blindly accepting all output or paranoidly reviewing every line both waste time. This section helps you calibrate your trust.
Research consistently shows AI code has higher defect rates than human-written code:
| Metric | AI vs Human | Source |
|---|---|---|
| Logic errors | 1.75× more | ACM study, 2025 |
| Security flaws | 45% contain vulnerabilities | Veracode GenAI Report, 2025 |
| XSS vulnerabilities | 2.74× more | CodeRabbit study, 2025 |
| PR size increase | +18% | Jellyfish, 2025 |
| Incidents per PR | +24% | Cortex.io, 2026 |
| Change failure rate | +30% | Cortex.io, 2026 |
Key insight: AI produces code faster but verification becomes the bottleneck. The question isn't "does it work?" but "how do I know it works?"
Nuance on downstream maintainability: A 2-phase blind RCT (Borg et al., 2025, n=151 professional developers) found no significant difference in the time needed for downstream developers to evolve AI-generated vs. human-generated code. The defect rates above are real — but they do not systematically translate into higher maintenance burden for the next developer. The risk is more narrowly scoped than commonly assumed. (arXiv:2507.00788)
Not all code needs the same scrutiny. Match verification effort to risk:
| Code Type | Verification Level | Time Investment | Techniques |
|---|---|---|---|
| Boilerplate (configs, imports) | Light skim | 10-30 sec | Glance, trust structure |
| Utility functions (formatters, helpers) | Quick test | 1-2 min | One happy path test |
| Business logic | Deep review + tests | 5-15 min | Line-by-line, edge cases |
| Security-critical (auth, crypto, input validation) | Maximum + tools | 15-30 min | Static analysis, fuzzing, peer review |
| External integrations (APIs, databases) | Integration tests | 10-20 min | Mock + real endpoint test |
Solo Developer Strategy:
Without peer reviewers, compensate with:
Solo workflow:
Generate → Vibe Review → Tests pass? → Ship
↓
Tests fail? → Deep review → Fix
Team Strategy:
With multiple developers:
Team workflow:
Generate → AI Review → Human Review → Merge
↓ ↓
Flag issues Final approval
Before shipping AI-generated code, verify:
Functional correctness:
Security baseline:
password, secret, key)Integration sanity:
Code quality:
| Anti-Pattern | Problem | Better Approach |
|---|---|---|
| "It compiles, ship it" | Syntax ≠ correctness | Run at least one test |
| "AI wrote it, must be secure" | AI optimizes for plausible, not safe | Always review security-critical code manually |
| "Tests pass, done" | Tests might not cover the change | Check test coverage of modified lines |
| "Same as last time" | Context changes, AI may generate different code | Each generation is independent |
| "Senior dev wrote the prompt" | Seniority doesn't guarantee output quality | Review output, not input |
| "It's just boilerplate" | Even boilerplate can hide issues | At minimum, skim for surprises |
Your verification strategy should evolve:
Mental model: Think of AI as a capable junior developer. You wouldn't deploy their code unreviewed, but you also wouldn't rewrite everything they produce.
┌─────────────────────────────────────────────────────────┐
│ TRUST CALIBRATION FLOW │
├─────────────────────────────────────────────────────────┤
│ │
│ AI generates code │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ What type? │ │
│ └──────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ Boiler Business Security │
│ -plate logic critical │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ Skim Test + Full review │
│ only review + tools │
│ │ │ │ │
│ └──────┴────────┘ │
│ │ │
│ ▼ │
│ Tests pass? ──No──► Debug & fix │
│ │ │
│ Yes │
│ │ │
│ ▼ │
│ Ship it │
│ │
└─────────────────────────────────────────────────────────┘
"AI lets you code faster—make sure you're not also failing faster." — Adapted from Addy Osmani
Attribution: This section draws from Addy Osmani's "AI Code Review" (Jan 2026), research from ACM, Veracode, CodeRabbit, and Cortex.io.
Common pitfalls that slow down new Claude Code users:
Mistake: Jumping straight into "fix this bug" without explaining context.
Fix: Use the WHAT/WHERE/HOW/VERIFY format:
WHAT: Fix login timeout error
WHERE: src/auth/session.ts
HOW: Increase token expiry from 1h to 24h
VERIFY: Login persists after browser refresh
Mistake: Working until context hits 95% and responses degrade.
Fix: Watch Ctx(u): in the status line. /compact at 70%, /clear at 90%.
Mistake: "Make this code better" or "Check for bugs"
Fix: Be specific: "Refactor calculateTotal() to handle null prices without throwing"
Mistake: Hitting "y" without reading the diff.
Fix: Always review diffs. Use "n" to reject, then explain what's wrong.
Mistake: Making large changes without commits.
Fix: Commit before big changes. Use feature branches. Claude can help: /commit
Mistake: Setting Bash(*) or --dangerously-skip-permissions
Fix: Start restrictive, expand as needed. Use allowlists: Bash(npm test), Bash(git *)
Mistake: "Fix the auth bug AND refactor the database AND add new tests"
Fix: One focused task per session. /clear between different tasks.
Mistake: Typing ad-hoc instructions every session. Repeating project conventions, re-explaining architecture, manually enforcing quality checks.
Fix: Build structured context that compounds over time:
/review, /deploy) for consistent executionStart with CLAUDE.md in Week 1. See §2.6 Mental Model for the full framework.
Before your next session, verify:
/status)Tip: Bookmark Section 9.11 for detailed pitfall explanations and solutions.
Quick jump: The Interaction Loop · Context Management · Plan Mode · Rewind · Model Selection · Mental Model · Config Decision Guide · Data Flow & Privacy
What you'll learn: The mental model and critical workflows for Claude Code mastery.
Ctx(u): — /compact at 70%, /clear at 90%Always check context % before starting complex tasks. High context = degraded quality.
Read this section if: You want to avoid the #1 mistake (context overflow) Skip if: You just need quick command reference (go to Section 10)
Reading time: 20 minutes
Skill level: Day 1-3
Goal: Understand how Claude Code thinks
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) │
│ │
└─────────────────────────────────────────────────────────┘
The loop is designed so that you remain in control. Claude proposes, you decide.
🔴 This is the most important concept in Claude Code.
The zones:
/compact now/clear requiredWhen context is high:
/compact (saves context, frees space)/clear (fresh start, loses history)Prevention: Load only needed files, compact regularly, commit frequently
Context is Claude's "working memory" for your conversation. It includes:
Claude has a 200,000 token context window. Think of it like RAM - when it fills up, things slow down or fail.
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 |
The default statusline can be enhanced with more detailed information like git branch, model name, and file changes.
Option 1: ccstatusline (recommended)
Add to ~/.claude/settings.json:
{
"statusLine": {
"type": "command",
"command": "npx -y ccstatusline@latest",
"padding": 0
}
}
This displays: Model: Sonnet 4.6 | Ctx: 0 | ⎇ main | (+0,-0) | Cost: $0.27 | Session: 0m | Ctx(u): 0.0%
Option 2: Custom script
Create your own script that:
{
"statusLine": {
"type": "command",
"command": "/path/to/your/statusline-script.sh",
"padding": 0
}
}
Use /statusline command in Claude Code to auto-generate a starter script.
| 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 |
When context gets high:
Option 1: Compact (/compact)
Option 2: Clear (/clear)
Option 3: Summarize from here (v2.1.32+)
/rewind (or Esc + Esc) to open the checkpoint list/compactOption 4: Targeted Approach
calculateTotal function"When approaching the red zone (75%+), /compact alone may not be enough. You need to actively decide what information to preserve before compacting.
Priority: Keep
| Keep | Why |
|---|---|
| CLAUDE.md content | Core instructions must persist |
| Files being actively edited | Current work context |
| Tests for the current component | Validation context |
| Critical decisions made | Architectural choices |
| Error messages being debugged | Problem context |
Priority: Evacuate
| Evacuate | Why |
|---|---|
| Files read but no longer relevant | One-time lookups |
| Debug output from resolved issues | Historical clutter |
| Long conversation history | Summarized by /compact |
| Files from completed tasks | No longer needed |
| Large config files | Can be re-read if needed |
Pre-Compact Checklist:
/compact to summarize and free spacePro tip: If you know you'll need specific information post-compact, tell Claude explicitly: "Before we compact, remember that we decided to use Strategy A for authentication because of X." Claude will include this in the summary.
Claude Code has two distinct memory systems. Understanding the difference is crucial for effective long-term work:
| Aspect | Session Memory | Persistent Memory |
|---|---|---|
| Scope | Current conversation only | Across all sessions |
| Managed by | /compact, /clear | /memory command, CLAUDE.md files |
| Lost when | Session ends or /clear | Explicitly deleted from files |
| Use case | Immediate working context | Long-term decisions, patterns |
Session Memory (short-term):
/compact (compress) and /clear (reset)Persistent Memory (long-term):
write_memory("key", "value")Pattern: End-of-Session Save
# Before ending a productive session:
"Save our authentication decision to memory:
- Chose JWT over sessions for scalability
- Token expiry: 15min access, 7d refresh
- Store refresh tokens in httpOnly cookies"
# Claude calls: write_memory("auth_decisions", "...")
# Next session:
"What did we decide about authentication?"
# Claude calls: read_memory("auth_decisions")
When to use which:
Research shows LLM performance degrades significantly with accumulated context:
Instead of managing context within a session, you can restart with a fresh session per task while persisting state externally.
# Canonical "Ralph Loop" (Geoffrey Huntley)
while :; do cat TASK.md PROGRESS.md | claude -p ; done
State persists via:
TASK.md — Current task definition with acceptance criteriaPROGRESS.md — Learnings, completed tasks, blockersVariant: tasks/lessons.md
A lightweight alternative for interactive sessions (no loop required): after each user correction, Claude updates tasks/lessons.md with the rule to avoid the same mistake. Reviewed at the start of each new session.
tasks/
├── todo.md # Current plan (checkable items)
└── lessons.md # Rules accumulated from corrections
The difference from PROGRESS.md: lessons.md captures behavioral rules ("always diff before marking done", "never mock without asking") rather than task state. It compounds over time — the mistake rate drops as the ruleset grows.
| Traditional | Fresh Context |
|---|---|
| Accumulate in chat history | Reset per task |
/compact to compress | State in files + git |
| Context bleeds across tasks | Each task gets full attention |
| Situation | Use |
|---|---|
| Context 70-90%, staying interactive | /compact |
| Context 90%+, need fresh start | /clear then continue |
| Long autonomous run, task-based | Fresh Context Pattern |
| Overnight/AFK execution | Fresh Context Pattern |
Good fit:
Poor fit:
Variant: Session-per-Concern Pipeline
Instead of looping the same task, dedicate a fresh session to each quality dimension:
This combines Fresh Context (clean 200K per phase) with OpusPlan (Opus for review/strategy sessions, Sonnet for implementation). Each session generates progress artifacts that feed the next.
Option 1: Manual loop
# Simple fresh-context loop
for i in {1..10}; do
echo "=== Iteration $i ==="
claude -p "$(cat TASK.md PROGRESS.md)"
git diff --stat # Check progress
read -p "Continue? (y/n) " -n 1 -r
[[ ! $REPLY =~ ^[Yy]$ ]] && break
done
Option 2: Script (see examples/scripts/fresh-context-loop.sh)
./fresh-context-loop.sh 10 TASK.md PROGRESS.md
Option 3: External orchestrators
# TASK.md
## Current Focus
[Single atomic task with clear deliverable]
## Acceptance Criteria
- [ ] Tests pass
- [ ] Build succeeds
- [ ] [Specific verification]
## Context
- Related files: [paths]
- Constraints: [rules]
## Do NOT
- Start other tasks
- Refactor unrelated code
/compact preserves conversation flow. Fresh context maximizes per-task attention at the cost of continuity.
Sources: Chroma Research - Context Rot | Ralph Loop Origin | METR - Long Task Capability | Anthropic - Context Engineering
| 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 |
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 |
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:
Claude Code isn't free - you're using API credits. Understanding costs helps optimize usage.
The default model depends on your subscription: Max/Team Premium subscribers get Opus 4.6 by default, while Pro/Team Standard subscribers get Sonnet 4.6. If Opus usage hits the plan threshold, it auto-falls back to Sonnet.
| Model | Input (per 1M tokens) | Output (per 1M tokens) | Context Window | Notes |
|---|---|---|---|---|
| Sonnet 4.6 | $3.00 | $15.00 | 200K tokens | Default model (Feb 2026) |
| Sonnet 4.5 | $3.00 | $15.00 | 200K tokens | Legacy (same price) |
| Opus 4.6 (standard) | $5.00 | $25.00 | 200K tokens | Released Feb 2026 |
| Opus 4.6 (1M context beta) | $10.00 | $37.50 | 1M tokens | Requests >200K context |
| Opus 4.6 (fast mode) | $30.00 | $150.00 | 200K tokens | 2.5x faster, 6x price |
| Haiku 4.5 | $0.80 | $4.00 | 200K tokens | Budget option |
Reality check: A typical 1-hour session costs $0.10 - $0.50 depending on usage patterns.
Model deprecations (Feb 2026):
claude-3-haiku-20240307(Claude 3 Haiku) was deprecated on February 19, 2026 with retirement scheduled for April 20, 2026. If your CLAUDE.md, agent definitions, or scripts hardcode this model ID, migrate toclaude-haiku-4-5-20251001(Haiku 4.5) before April 2026. Source: platform.claude.com/docs/model-deprecations
The 1M context window (beta, API + usage tier 4 required) is a significant capability jump — but community feedback consistently frames it as a niche premium tool, not a default.
Retrieval accuracy at scale (MRCR v2 8-needle 1M variant)
| Model | 256K accuracy | 1M accuracy | Source |
|---|---|---|---|
| Opus 4.6 | 93% | 76% | Anthropic blog + independent analysis (Feb 2026) |
| Sonnet 4.5 | — | 18.5% | Anthropic blog (Feb 2026) |
| Sonnet 4.6 | Not yet published | Not yet published | — |
The benchmark is the "8-needle 1M variant" — finding 8 specific facts in a 1M-token document. Opus 4.6 drops from 93% to 76% when scaling from 256K to 1M; Sonnet 4.5 collapses to 18.5%. Community validation: a developer loaded ~733K tokens (4 Harry Potter books) and Opus 4.6 retrieved 49/50 documented spells in a single prompt (HN, Feb 2026). Sonnet 4.6 MRCR not yet published, but community reports suggest it "struggles with following specific instructions and retrieving precise information" at full 1M context.
Cost per session (approximate)
Above 200K input tokens, all tokens in the request are charged at premium rates — not just the excess. Applies to both Sonnet 4.6 and Opus 4.6.
| Session type | ~Tokens in | ~Tokens out | Sonnet 4.6 | Opus 4.6 |
|---|---|---|---|---|
| Bug fix / PR review (≤200K) | 50K | 5K | ~$0.23 | ~$0.38 |
| Module refactoring (≤200K) | 150K | 20K | ~$0.75 | ~$1.25 |
| Full service analysis (>200K, 1M beta) | 500K | 50K | ~$4.13 | ~$6.88 |
For comparison: Gemini 1.5 Pro offers a 2M context window at $3.50/$10.50/MTok — significantly cheaper for pure long-context RAG. Community advice: use Gemini for large-document RAG, Claude for reasoning quality and agentic workflows.
When to use which
| Scenario | Recommendation |
|---|---|
| Bug fix, PR review, daily coding | Sonnet 4.6 @ 200K — fast and cheap |
| Full-repo audit, entire codebase load | Opus 4.6 @ 1M — worth the cost for precision |
| Cross-module refactoring | Sonnet 4.6 @ 1M — but weigh cost vs. chunking + RAG |
| Architecture analysis, Agent Teams | Opus 4.6 @ 1M — strongest retrieval at scale |
| Large-document RAG (PDFs, legal, books) | Consider Gemini 1.5 Pro — cheaper at this scale |
Key facts
anthropic-beta: context-1m-2025-08-07 header, usage tier 4 or custom rate limits| Action | Tokens Consumed | Estimated Cost |
|---|---|---|
| Read a 100-line file | ~500 | $0.0015 |
| Read 10 files (1000 lines) | ~5,000 | $0.015 |
| Long conversation (20 messages) | ~30,000 | $0.090 |
| MCP tool call (Serena, Context7) | ~2,000 | $0.006 |
| Running tests (with output) | ~3,000-10,000 | $0.009-$0.030 |
| Code generation (100 lines) | ~2,000 output | $0.030 |
The expensive operations:
/compact - Context accumulatesStrategy 1: Be specific in queries
# ❌ Expensive - reads entire file
"Check auth.ts for issues"
# ~5K tokens if file is large
# ✅ Cheaper - targets specific location
"Check the login function in auth.ts:45-60"
# ~500 tokens
Strategy 2: Use /compact proactively
# Without /compact - conversation grows
Context: 10% → 30% → 50% → 70% → 90%
Cost per message increases as context grows
# With /compact at 70%
Context: 10% → 30% → 50% → 70% → [/compact] → 30% → 50%
Frees significant context space for subsequent messages
Strategy 3: Choose the right model
# Use Haiku for simple tasks (4x cheaper input, 3.75x cheaper output)
claude --model haiku "Fix this typo in README.md"
# Use Sonnet (default) for standard work
claude "Refactor this module"
# Use Opus only for critical/complex tasks
claude --model opus "Design the entire authentication system"
Strategy 4: Limit MCP servers
// ❌ Expensive - 5 MCP servers loaded
{
"mcpServers": {
"serena": {...},
"context7": {...},
"sequential": {...},
"playwright": {...},
"postgres": {...}
}
}
// ~10K tokens overhead per session
// ✅ Cheaper - load only what you need
{
"mcpServers": {
"serena": {...} // Only for this project
}
}
// ~2K tokens overhead
Strategy 5: Batch operations
# ❌ Expensive - 5 separate prompts
"Read file1.ts"
"Read file2.ts"
"Read file3.ts"
"Read file4.ts"
"Read file5.ts"
# ✅ Cheaper - single batched request
"Read file1.ts, file2.ts, file3.ts, file4.ts, file5.ts and analyze them together"
# Shared context, single response
Strategy 6: Use prompt caching for repeated context (API)
If you call the Anthropic API directly (e.g., for custom agents or pipelines), prompt caching cuts costs by up to 90% on repeated prefixes.
# Mark stable sections with cache_control
response = client.messages.create(
model="claude-sonnet-4-6-20250514",
max_tokens=1024,
system=[
{
"type": "text",
"text": "<your large system prompt / codebase context>",
"cache_control": {"type": "ephemeral"} # Cache this prefix
}
],
messages=[{"role": "user", "content": "Fix the bug in auth.ts"}]
)
Prompt caching economics:
| Operation | Cost multiplier | TTL |
|---|---|---|
| Cache write | 1.25x base price | 5 minutes (default) |
| Cache write (extended) | 2x base price | 1 hour |
| Cache read (hit) | 0.1x base price | — |
| Latency reduction | Up to 85% for long prompts | — |
Break-even: 2 cache hits with 5-minute TTL. After that, pure savings.
Rules:
Docs: prompt caching
Real-time tracking:
The status line shows current session cost:
Claude Code │ Ctx(u): 45% │ Cost: $0.23 │ Session: 1h 23m
↑ Current session cost
Advanced tracking with ccusage:
The ccusage CLI tool provides detailed cost analytics beyond the /cost command:
ccusage # Overview all periods
ccusage --today # Today's costs
ccusage --month # Current month
ccusage --session # Active session breakdown
ccusage --model-breakdown # Cost by model (Sonnet/Opus/Haiku)
Example output:
┌──────────────────────────────────────────────────────┐
│ USAGE SUMMARY - January 2026 │
├──────────────────────────────────────────────────────┤
│ Today $2.34 (12 sessions) │
│ This week $8.91 (47 sessions) │
│ This month $23.45 (156 sessions) │
├──────────────────────────────────────────────────────┤
│ MODEL BREAKDOWN │
│ Sonnet 3.5 85% $19.93 │
│ Opus 4.6 12% $2.81 │
│ Haiku 3.5 3% $0.71 │
└──────────────────────────────────────────────────────┘
Why use ccusage over /cost?
For a full inventory of community cost trackers, session viewers, config managers, and alternative UIs, see Third-Party Tools.
Monthly tracking:
Check your Anthropic Console for detailed usage:
Cost budgeting:
# Set a mental budget per session
- Quick task (5-10 min): $0.05-$0.10
- Feature work (1-2 hours): $0.20-$0.50
- Deep refactor (half day): $1.00-$2.00
# If you're consistently over budget:
1. Use /compact more often
2. Be more specific in queries
3. Consider using Haiku for simpler tasks
4. Reduce MCP servers
Perspective on costs: If Claude Code saves you meaningful time on a task, the API cost is usually negligible compared to your hourly rate. Don't over-optimize for token costs at the expense of productivity.
When to optimize:
When NOT to optimize:
For solo developers on a budget:
1. Start with Haiku for exploration/planning
2. Switch to Sonnet for implementation
3. Use /compact aggressively (every 50-60% context)
4. Limit to 1-2 MCP servers
5. Be specific in all queries
6. Batch operations when possible
Monthly cost estimate: $5-$15 for 20-30 hours
For professional developers:
1. Use Sonnet as default (optimal balance)
2. Use /compact when needed (70%+ context)
3. Use full MCP setup (productivity matters)
4. Don't micro-optimize queries
5. Use Opus for critical architectural decisions
Monthly cost estimate: $20-$50 for 40-80 hours
For teams:
1. Shared MCP infrastructure (Context7, Serena)
2. Standardized CLAUDE.md to avoid repeated explanations
3. Agent library to avoid rebuilding patterns
4. CI/CD integration for automation
5. Track costs per developer in Anthropic Console
Monthly cost estimate: $50-$200 for 5-10 developers
| Indicator | Cause | Fix |
|---|---|---|
| Sessions consistently >$1 | Not using /compact | Set reminder at 70% context |
| Cost per message >$0.05 | Context bloat | Start fresh /clear |
| >$5/day for hobby project | Over-using or inefficient queries | Review query specificity |
| Haiku failing simple tasks | Using wrong model tier | Use Sonnet for anything non-trivial |
Note: Anthropic's plans evolve frequently. Always verify current pricing and limits at claude.com/pricing.
How Subscription Limits Work
Unlike API usage (pay-per-token), subscriptions use a hybrid model that's deliberately opaque:
| Concept | Description |
|---|---|
| 5-hour rolling window | Primary limit; resets when you send next message after 5 hours lapse |
| Weekly aggregate cap | Secondary limit; resets every 7 days. Both apply simultaneously |
| Hybrid counting | Advertised as "messages" but actual capacity is token-based, varying by code complexity, file size, and context |
| Model weighting | Opus consumes 8-10× more quota than Sonnet for equivalent work |
Approximate Token Budgets by Plan (Jan 2026, community-verified)
| Plan | 5-Hour Token Budget | Weekly Sonnet Hours | Weekly Opus Hours | Claude Code Access |
|---|---|---|---|---|
| Free | 0 | 0 | 0 | ❌ None |
| Pro ($20/mo) | ~44,000 tokens | 40-80 hours | N/A (Sonnet only) | ✅ Limited |
| Max 5x ($100/mo) | ~88,000-220,000 tokens | 140-280 hours | 15-35 hours | ✅ Full |
| Max 20x ($200/mo) | ~220,000+ tokens | 240-480 hours | 24-40 hours | ✅ Full |
Warning: These are community-measured estimates. Anthropic does not publish exact token limits, and limits have been reduced without announcement (notably Oct 2025). The 8-10× Opus/Sonnet ratio means Max 20x users get only ~24-40 Opus hours weekly despite paying $200/month.
Why "Hours" Are Misleading
The term "hours of Sonnet 4" refers to elapsed wall-clock time during active processing, not calendar hours. This is not directly convertible to tokens without knowing:
Tier-Specific Strategies
| If you have... | Recommended approach |
|---|