00. Before You Start

The four questions that come up most often when people start with Claude Code. Sorting them out before installing makes the first week far smoother.

I remember the first time I opened Claude Code and just sat in front of the empty terminal, not sure where to start. It didn't come to me through an ad — it crept in naturally while I was running my business and looking for ways to move faster. Three questions kept circling in my head: How do I actually plug this into my work? People say it lifts productivity — does it, really? And where do I even begin? If you're in the same spot, this guide started as the notes I wrote to climb out of that fog. So we'll begin with the four questions that come up most often in the first week.

Q1. What's the difference between Claude Code and Cowork?

One line: Claude Code is a building tool. Cowork is a task-processing tool.

Cowork's sandbox — safe, but slow and expensive

Cowork runs inside an isolated virtual environment (a local VM). Safe, but every screen action triggers a screenshot and the AI has to read the image — tokens pile up and each step waits for the next render. Routing through a GUI costs both money and time, even for the same end result.

Claude Code reads and writes files as text directly, with full access to your machine. Same job, a fraction of the tokens, far faster. The output isn't "what someone saw on a screen" — it's "what actually changed in code and files," which means it's reproducible.

💡 What surfaces from running both side by side: Cowork is great for email, scheduling, and repetitive office tasks. The moment you're "creating something new," Claude Code pulls ahead by a wide margin. They're not competitors — keep them as different drawers in the same toolbox.

Q2. The desktop app and VS Code extension exist — do I really need the terminal?

When the desktop app and VS Code extension first shipped, the natural reaction was "great, no more terminal." A surprising number of people who tried them seriously for a week or two ended up back on the terminal. As of April 2026, feature parity is close, but measured by actual time-to-finish, the terminal is still the fastest tool.

Multi-session — where the real productivity comes from

Claude Code's true power shows up when several sessions run in parallel. Picture four terminal windows open at once.

• Window 1: frontend work
• Window 2: backend API
• Window 3: tests on a watch loop
• Window 4: docs and README writing

Four Claude Code instances work on their own tasks at the same time. When one finishes, you hand it the next instruction and check the others. The phrase that comes naturally the first time you feel this flow is "alone, but it feels like a team."

You can spin up multiple sessions in the desktop app or VS Code as well. But seeing them all side-by-side in a single view only works in a terminal. With tmux, four panels sit in front of you at once — you can tell at a glance which session stalled and which just dropped a result.

What only the terminal can do

It's not just "faster." Some things are only possible in the terminal.

• Pipe scripting: cat error.log | claude -p "analyze the cause" — feed any tool's output straight in
• Scheduled automation: generate a morning summary from saved inputs
• Scheduled automation: cron-triggered checks and anomaly detection every morning
• Shell composition: weave it naturally into aliases, functions, and scripts

These doors are structurally closed in a GUI-only environment. The more your work leans on automation and repetition, the bigger the gap.

Stability

Feature convergence is moving fast, but stability still differs in clear ways.

The gap is closing, but today the most stable and responsive place to work is the terminal.

💡 In the AI era, the terminal isn't a developer-only tool anymore. You just say what you want in plain language. Clear that one hurdle and the next view opens up entirely.

Q3. I installed Claude Code — what do I do first?

Most-asked question, hardest to answer. Honestly — the question itself is a trap.

It's not "what to do first." It's "what do I want to make". Without that, no tutorial sticks. The almost-universal beginner experience: copy a To-Do app from the official docs, finish it, then think "why did I build this?" and delete the folder. The tool was learned; the motivation was empty.

Two things that work:

1. Browse what other people are shipping first. Social, YouTube, vibe-coding communities — eventually something hits you with "I want to make that." That's your starting point. The trick isn't a vague "I should study"; it's one concrete output scene that sticks in your head.

2. Once you have a fuzzy idea, don't say "build it." Ask Claude first.

"I want to do something like X — what can you do for me?"
"What would I need to build this kind of project?"
"Are there similar examples or reference structures I could look at?"

Claude Code isn't an order-taker. It's a partner that thinks with you and points directions. Through the conversation, what's possible and what isn't — and which path is shorter — surfaces on its own. Spending the first hour or two asking instead of building is, paradoxically, the fastest onboarding route.

Install, basic commands, and CLAUDE.md are covered from Section 1 on. No rush — come back once you know what you want to build.

Q4. Is Pro ($20) enough?

Most-asked question, shortest answer. If you plan to use it seriously, no.

What Pro ($20) actually feels like

Pro's 5-hour window fills faster than you'd expect. Deep work can hit the cap inside an hour, and once you're blocked the day's flow is broken. Pro defaults to Sonnet 4.6, and the strongest model — Opus 4.7 — is effectively off-limits on Pro; the quota burns too fast.

Max makes Opus 4.7 the default and includes the 1M-token context window automatically. The first real shift is escaping the "afraid to use the good model because of the cap" state.

Try Max ($100) for at least a month

Claude Code's real productivity shows up when you can keep a real task moving without hitting the cap. Beginners can start with one session, but real project work burns usage faster than expected.

• Long conversations: files and context accumulate token usage
• Repeated revisions: build, verify, and refine loops add up
• Opus model: useful for complex design and debugging, but expensive

If that happens often, Max $100, which gives you 5x Pro's usage, becomes the practical tier. At C0, Pro is fine for exploration; Max is worth testing when practice keeps getting interrupted by limits.

If Pro's cap has been frustrating, run Max for a month. With the cap gone, you'll hit the "wait, it can do this much?" moment. After that, the call to fall back to Pro is yours to make.

Plan guide

⚠️ Treat Pro $20 as a trial. It's enough to see the potential. Real productivity needs Max. Instead of hesitating another month, run Max for one month — the answer is on the other side of that month.

01. What Is Claude Code?

An AI agent that reads, organizes, and produces results directly from your computer's files. No coding required.

Source: Claude Code overview — Anthropic Docs

One-Line Definition

Claude Code is an AI that reaches into your computer's folders and works there. It reads dozens of files at once, organizes what's inside, and leaves the finished output in place.

Unlike Claude.ai, which lives in a browser chat, Claude Code works inside your machine.

How Is It Different from Claude.ai?

The core difference: Claude.ai shows answers in a chat window. Claude Code walks into your folder and leaves the output there.

How Does It Work? Real Examples

Example 1: Batch document processing (marketer / PM)

"Read the 30 meeting notes in my Downloads folder,
 sort them by date, pull out this month's decisions,
 and save the result as monthly_decisions.md"

What Claude Code does:
1. Reads all 30 files in the folder
2. Identifies and sorts by date
3. Extracts only the decision items
4. Saves the result as a new file

Example 2: Data analysis (researcher / analyst)

"Analyze the survey CSV in my data folder
 and write a summary report on the key metrics"

No Python needed. Describe the outcome — Claude Code does the rest.

Example 3: Code development (developer)

"My tests are failing — find the cause and fix it"
→ Runs tests → finds the error → fixes the code → re-runs

Who Is Claude Code For?

A great fit

Also worth a try if…

• "I want to organize data without Python or Excel formulas"
• "I want to process dozens of documents without opening each one"
• Terminal not your thing? No problem — a desktop app is available

Claude.ai web is probably the better fit if…

• You only need writing, translation, or Q&A
• You work exclusively inside a single IDE → consider Cursor or the VS Code extension

Where Can You Run Claude Code?

One-Line Summary

Claude Code = "an AI that walks into your computer's folders, reads your files, organizes them, and builds the result you asked for"

No coding. No Python. Just describe the outcome.

The next section covers which plan to start with.

02. What You Can Do with Claude Code

Despite the name "Code," this isn't a coding-only tool. It's a general-purpose AI agent that happens to live in a terminal.

First: How Is It Different from Claude.ai?

In short: Claude.ai is a conversation partner. Claude Code is an AI colleague working inside your computer.

In a Development Context

Code Writing and Management

Writing code, fixing bugs, refactoring, testing, reviewing — describe it in plain language and Claude handles it.

Vibe Coding — Build Software Without Writing Code

"Coding by vibe." You give the AI natural-language instructions instead of typing code yourself. Andrej Karpathy (former Tesla AI Director) coined the term in 2025.

The most important skill isn't syntax. It's explaining what you want to build.

What you can realistically build: prototypes, MVPs, personal tools, websites, simple apps, data-processing automation. This guide itself was built with vibe coding.

Honest limits: large-scale production services still need expert review. For security, payments, and other sensitive logic, get a professional to check it. Start with vibe coding, then bring in developers as the service grows.

Tips for Better Vibe Coding

1. Planning is half the battle. "Build me an app" gives worse results than "Build a web app that organizes photos by date." Ask Claude to draft a requirements doc before coding.
2. Start small. Don't demand a finished product all at once. Login screen first, then the list page. Go in steps.
3. Check the output yourself. Always run and verify what the AI built.
4. Don't fear mistakes. Git saves let you roll back anytime.

In a Non-Development Context

Claude Code does far more than vibe coding. Anything a computer can do, you can describe in plain language.

Research and Analysis

• Read multiple web pages at once and organize them as markdown
• Competitor analysis, market research, tech trend tracking
• Batch-summarize dozens of PDFs and documents

The deep-research plugin runs multi-agent investigations in parallel and produces full reports.

Documents and Content

• Blog posts, newsletters, social drafts
• Proposals, reports, presentation outlines
• Korean ↔ English translation saved straight to files

Data Processing

• Analyze and convert CSV or Excel files — no Python needed
• Batch-process hundreds of files (rename, convert, reorganize)
• Parse and transform JSON or XML

Learning Assistant

• Structure and summarize lecture materials or books
• Auto-generate quizzes and flashcards
• Concepts, examples, and practice problems in one pass

Business Workflows

• Meeting transcripts turn into summaries, decisions, and owner-tagged action items
• Weekly and monthly reports automated
• Email drafts and customer-response templates

Personal AI Workspace

Define roles and rules in CLAUDE.md and you have your own AI agent system — not just a chat tool. Covered in depth in the workspace design section.

Real Example: How This Guide Was Built

Not a single line of code was written by hand.

Planning. "I want a Korean Claude Code beginner guide." The workspace clarified the section structure, UX, and stack. A 23-section outline emerged.

Content. 57 official docs collected. Claude pulled the key points and structured them into Korean and English markdown.

Development. The entire Next.js codebase was written by Claude Code. Dark and light mode, language toggle, mobile support — all through conversation.

Deployment. Vercel, Cloudflare DNS, domain setup — handled by Claude Code.

Refinement. After the first draft, the author reviewed and improved the content through conversation. This very turn is one of those updates.

Real Non-Developer Use Case

Situation: writing up team meeting notes every week

Old way:
  Meeting ends → 30 min organizing → 10 min email → share

Claude Code way:
  Paste meeting transcript
  → "Summarize, list decisions, sort action items by person"
  → Markdown saved + email draft generated
  Total time: 3 minutes

One-Line Summary

Claude Code is a general-purpose AI agent. Coding is just one of many things it can do.

03. Pricing Guide

Claude Code requires a paid subscription (the Free plan does not include it). For serious use, Max (5x) is the recommended starting point.

Source: Anthropic Pricing

Pro vs Max

Check the latest at claude.com/pricing. The table below is a reference.

Confirm exact pricing (especially the Max 20x tier) and current usage policy at claude.com/pricing. The Free plan does not include Claude Code.

Activate 1M context with /model opus[1m] or /model sonnet[1m]. Max·Team·Enterprise include Opus 1M automatically; Sonnet 1M is billed as extra usage on every plan.

Why We Recommend Max (5x)

If you plan to use Claude Code seriously, Max (5x, From $100) is the starting point.

• Pro's cap fills up fast, which breaks focused work
• Opus runs on Pro, but its quota burns fast enough that we don't recommend it
• Long conversations, multi-file analysis, and repeated revisions burn tokens quickly
• Max (5x) covers most individuals without drama

How Billing Works

Pay monthly → Use freely within your limit
If you hit the limit → Responses throttle (no surprise charge)

• You don't track token counts
• Limits run on two windows: a 5-hour window and a weekly window. See the Anthropic usage limit guide for the current policy
• Run /usage for session cost, plan limits, and activity stats (/cost and /stats are aliases of the same command — only the opening tab differs)
• On Max, Opus auto-falls back to Sonnet when its threshold is reached so work doesn't stop

Tips to Reduce Costs

Which Plan Should You Start With?

One-Line Summary

Pro is the trial. Real productivity starts at Max (5x).

Latest details: claude.com/pricing.

04. Installation and Authentication

One command to install, then a browser login. That's the whole setup.

Source: Set up Claude Code — Anthropic Docs

💡 New to the terminal? Copy the command, paste it (Cmd+V or Ctrl+V), and press Enter. You don't need to understand every line.

• macOS: Cmd+Space → search "terminal" → Enter
• Windows: Win+R → type "powershell" → Enter

Before You Install

Supported Operating Systems

Hardware Requirements

• RAM: 4 GB or more
• Active internet connection

Do I Need Node.js?

No. The native install is the recommended path and runs without Node.js. The npm global install (npm install -g @anthropic-ai/claude-code) is still supported, but avoid sudo npm install -g because of permission issues. Use the native commands below when possible.

Installation

macOS / Linux / WSL

Open your terminal and paste:

curl -fsSL https://claude.ai/install.sh | bash

Or with Homebrew:

brew install --cask claude-code

Windows

Option 1 — WSL (recommended).

WSL (Windows Subsystem for Linux) gives you full feature parity.

# 1. Install WSL (run PowerShell as Administrator)
wsl --install

After rebooting, Ubuntu sets itself up. In the Ubuntu terminal:

# 2. Install Claude Code (same as Linux)
curl -fsSL https://claude.ai/install.sh | bash

Option 2 — PowerShell direct install.

Works without WSL, but some features may be limited.

irm https://claude.ai/install.ps1 | iex

Option 3 — WinGet.

winget install Anthropic.ClaudeCode

On Windows, Git for Windows must be installed for local sessions to work.

Alpine Linux Extras

apk add libgcc libstdc++ ripgrep

Authentication

Once installed, run:

claude

On first launch, your browser opens an OAuth login page automatically. Sign in with your Claude.ai account (Pro or Max) and authentication finishes on its own.

Authentication Flow

Credential Security

• macOS: API keys and OAuth tokens are stored in the encrypted macOS Keychain.
• To re-authenticate: run claude, then /login.

Verify Your Installation

claude --version

A version number means you're in. For a full health check:

claude doctor

It reports install type, version, and environment status in one shot.

Automatic Updates

Claude Code updates itself. It checks at startup, downloads in the background, and applies the new version next launch.

Manual update:

claude update

Common Install Problems

Problem 1: curl: command not found

Cause: curl isn't installed (rare, mostly minimal Linux).

Fix:

# Ubuntu/Debian
sudo apt-get install curl

# Alpine
apk add curl

Re-run the install command afterward.

Problem 2: claude: command not found after install

Cause: the install path isn't in your shell's PATH.

Fix:

# Reload your shell config
source ~/.bashrc
# zsh
source ~/.zshrc

If that doesn't work, close the terminal completely and reopen it.

Problem 3: Git not found on Windows

Cause: local sessions need Git.

Fix: install Git for Windows and try again.

Next Steps

Once you're installed and logged in, go to any folder and start:

# Navigate to your working folder, then run
claude

Any folder works. Code, documents, research — Claude Code launches anywhere and analyzes what's there.

The next section walks through the beginner workflow.

05. Beginner Workflow

Start your first session and work effectively from day one.

Six beats at a glance. Follow them as-is the first time, then bend the rhythm to your own pace.

Your First Session, Step by Step

Follow these when you start out.

Step 1. Navigate to Your Project Folder

cd ~/Desktop/my-project

Claude Code reads and edits files relative to your current directory. Always move into the project folder first.

No folder yet? Create one: mkdir ~/Desktop/my-project && cd ~/Desktop/my-project.

Step 2. Start Claude Code

claude

Type claude and press Enter. The interactive session starts.

Step 3. Let Claude Learn the Project

At the start, ask Claude to understand the project or generate a CLAUDE.md.

> Read through this project and create a CLAUDE.md file for it

For an existing project:

> Give me an overview of this codebase

Why CLAUDE.md matters: it stores your project rules, stack, and context. Claude reads it automatically at the start of every session, so you don't re-explain each time. Commit it to git and the whole team benefits.

Step 4. Give Instructions

Say what you want in plain language.

> Add a user login feature
> Find the bug in this code
> Write unit tests for the auth module

Step 5. Review and Give Feedback

Claude shows what it changed. If something's off, say so right away.

> Good, but show error messages in plain English instead
> Not quite — can you try [explanation] instead?

Step 6. End the Session

> /quit

Or press Ctrl+D.

How to Write Effective Prompts

Specific Beats Vague

One Request at a Time

Stacking too many asks makes Claude lose the thread.

# Not recommended
> Add login, signup, password reset, email verification,
  and social login all at once

# Recommended
> First, implement email/password login only
(after it's done)
> Now add the signup flow

Specify the Output Format

> Explain this code          → a written explanation
> Save this to a file        → Claude writes the file
> Rewrite this in place      → Claude edits the file directly
> List the bugs as a table   → a formatted table

Reference Files with @

> Find bugs in @src/auth/login.js
> Read @README.md and explain the project structure

Common Use Cases

Adding a New Feature

> Add a user profile page with:
  - Display nickname, email, and join date
  - Profile photo upload
  - Nickname editing

Fixing a Bug

> I get this error when I run npm test — please fix it:
  TypeError: Cannot read property 'id' of undefined
  at UserService.getUser (src/services/user.js:45)

Code Review

> Review the code in @src/payment/ for security
  vulnerabilities and suggest improvements

Code Explanation

> Explain what @src/utils/tokenizer.js does in simple terms

Writing Tests

> Write tests for all functions in @src/services/auth.js.
  Follow the style in @tests/services/user.test.js

Documentation

> Add JSDoc comments to all functions in @src/api/

Plan Mode

What it is: Claude analyzes code and proposes a plan without making changes. Use it before risky or complex work to review the approach first.

Enable It

Press Shift+Tab twice
or type:
> /plan

When to Use It

• Before modifying many files at once
• Before database migrations or other hard-to-reverse ops
• When exploring unfamiliar code before editing
• For large architectural changes where direction matters first

Plan Mode Example

# Start directly in Plan Mode
claude --permission-mode plan

# Or toggle during a session
> Shift+Tab (twice)

# Ask Claude to plan
> Create a detailed migration plan for moving our auth system from JWT to OAuth2

# Review, then switch back to normal mode to execute

Things You Should Never Do

Never Paste Secrets

# Never
> My AWS access key is AKIAXXXXXXXX and...
> The database password is mypassword123...
> Here's my private SSH key: -----BEGIN RSA...

Keep API keys, passwords, and private credentials out of chat. Use environment variables or .env files.

Don't Auto-Approve Sudo

When Claude asks for sudo or wants to touch system files, ask why first.

> Why do you need sudo for this? Is there another way?

Be Careful with --dangerously-skip-permissions

This flag skips every permission check. Only use it inside an isolated container or VM — never on your main machine.

Back Up Before Big Work

Before heavy refactors or DB migrations, run git commit or make a backup.

Session Management Tips

Name Important Sessions

> /rename auth-refactor

Resume later:

claude --resume auth-refactor

Compact Long Sessions

When replies feel slow or partial:

> /compact

Clear Between Unrelated Tasks

> /clear

A clean context stops old threads from confusing new work.

One-Line Summary

Be specific, one request at a time, review, give feedback, repeat.

The next section covers common mistakes and how to fix them.

06. Recommended Plugin Installation

Extend Claude Code by installing plugins.

What Are Plugins?

Claude Code ships strong out of the box. Plugins let you go further.

Think of them like apps on a phone — install what you need, and Claude Code gains new abilities.

A single plugin can bundle:

Official Plugin Marketplace

Anthropic runs an official marketplace (claude-plugins-official) that's registered automatically when you start Claude Code.

Type /plugin and open the Discover tab to browse.

Installing from the Official Marketplace

/plugin install plugin-name@claude-plugins-official

Categories

/plugin install typescript-lsp@claude-plugins-official
/plugin install pyright-lsp@claude-plugins-official

Installing a Plugin

Step 1: Open the Plugin Manager

Inside Claude Code:

/plugin

This opens the manager. The Discover tab lists the official marketplace, which is registered automatically.

Step 2: Install

From the official marketplace:

/plugin install commit-commands@claude-plugins-official

Or pick interactively:

/plugin install

One plugin installs at a time. Repeat for more.

Step 3: Verify

/plugin list

Or type /plugin and open the Installed tab.

Step 4: Update

/plugin update

Restart Claude Code after installing or updating.

Managing Plugins

One-Line Summary

Plugins are how Claude Code grows with your workflow.

If one official plugin works in read-only mode, that is enough for a beginner setup. Next up: how Claude Code actually works under the hood.

07. Understanding Core Concepts

Knowing how Claude Code works makes every session more effective.

How Does Claude Code Work?

It's not just a chatbot. When you give it a task, Claude Code acts as an agent — it plans, reads files, edits code, and verifies on its own.

This is the Agentic Loop.

Your instruction
     ↓
1. Gather Context
   - Read files, search code, understand current state
     ↓
2. Take Action
   - Edit files, run commands, search the web
     ↓
3. Verify Results
   - Run tests, check errors, revise if needed
     ↓
Task complete (or loop back to step 1)

Say "fix the failing tests" and Claude Code will:

1. Run the test suite to see what's failing
2. Find and read the relevant source files
3. Edit the code to fix the issue
4. Run the tests again to confirm they pass

All of this happens automatically.

5 Core Concepts

1. Context — Claude's Working Memory

Context is everything Claude is holding in mind right now: conversation, files read, command outputs, CLAUDE.md.

Context has a token limit. Long conversations or huge files can fill it up. Claude Code handles this automatically by summarizing older content.

# See what's using context
/context

# Compact (summarize older parts)
/compact

# Compact with focus
/compact focus on the API changes

💡 Tip: Put important rules and project info in CLAUDE.md. It loads at the start of every session without eating your active context.

2. Tools — What Claude Can Actually Do

Claude Code doesn't just talk. It uses tools to act.

3. Permissions — Control What Claude Can Do

Claude Code is powerful, so you control what it's allowed to do.

Reading files is allowed by default. Editing files or running shell commands requires approval.

There are three rule types:

# Manage permissions
/permissions

Priority order: Deny > Ask > Allow. Deny always wins.

4. Memory — Remembering Projects with CLAUDE.md

Claude Code doesn't recall past sessions. A CLAUDE.md file fixes that — Claude reads it automatically at the start of every session.

Think of CLAUDE.md as a standing instruction sheet.

CLAUDE.md is covered in depth in Section 8 of this guide.

5. Session — Start to Finish

A session is one continuous conversation from launch to exit.

• A new session clears previous history (CLAUDE.md still loads)
• Everything done during a session is saved

# Resume the most recent session
claude --continue

# Choose from recent sessions
claude --resume

# Fork a session to try a different approach
claude --continue --fork-session

Why Does Claude Pause to Ask?

When Claude stops and asks for approval, that's an intentional safety feature.

Before modifying files or running commands, it confirms the action matches your intent — especially for hard-to-reverse ops like deleting files or deploying.

3 Permission Modes to Know

Press Shift+Tab to cycle through modes.

How to Switch

# Press Shift+Tab in the terminal to cycle:
# Default → Auto-Accept → Plan Mode → Default → ...

# Or enter Plan Mode directly
/plan

Example

"Delete all console.log statements from every JavaScript file"

Default mode:
  → Asks "Can I modify this file?" before each edit

Auto-Accept mode:
  → Edits files automatically; still asks before git commit

Plan mode:
  → Shows "I plan to remove line 42 in src/utils.js" — no actual changes

Start with Default to watch Claude work. Switch to Auto-Accept once you're comfortable.

Checkpoints: You Can Always Undo

Before editing a file, Claude Code takes a snapshot.

If something goes wrong:

• Press Esc twice to rewind
• Or just say "undo what you just did"

One-Line Summary

Context, tools, permissions, memory, session — five words that explain every Claude Code behavior.

Next up: mastering CLAUDE.md, Claude Code's long-term memory.

08. Mastering CLAUDE.md

CLAUDE.md is the single most important file for giving Claude Code long-term memory. Let's master it.

Source: Memory & CLAUDE.md — Anthropic Docs

What Is CLAUDE.md?

Claude Code forgets everything when a session ends. Start a new one and it's back to zero — no memory of your project.

CLAUDE.md solves that.

Every time Claude Code starts, it automatically reads your CLAUDE.md and begins work with full context and rules in hand.

Think of it as a standing instruction sheet you hand Claude at the start of every session.

Instead of saying every time:
"This is a Next.js project, use TypeScript,
 use 2-space indentation, commit messages in English..."

→ Write it once in CLAUDE.md and Claude remembers forever.

Where Should You Create It?

The file's location controls its scope.

Most common location: CLAUDE.md at the project root.

# Create CLAUDE.md manually
touch CLAUDE.md

# Or let Claude Code draft one
/init

/init analyzes your project and drafts a CLAUDE.md for you.

What Should You Write?

There's no required format. CLAUDE.md is just Markdown. These sections work especially well.

Essential Sections

1. Project Description

Help Claude understand what this project is.

## Project Overview
An inventory management web app for small business owners.
Next.js 14 + TypeScript + Supabase.

2. Tech Stack

List languages, frameworks, and libraries.

## Tech Stack
- **Frontend**: Next.js 14 (App Router), TypeScript, Tailwind CSS
- **Backend**: Next.js API Routes
- **Database**: Supabase (PostgreSQL)
- **Package Manager**: pnpm (never npm)

3. Coding Style and Rules

Code style, naming, comment language.

## Coding Rules
- Indentation: 2 spaces (no tabs)
- Quotes: single quotes ('')
- Component filenames: PascalCase (e.g., UserCard.tsx)
- Function names: camelCase (e.g., getUserData)
- No `any` types — always explicit
- All comments in English

4. What Never to Do

Explicit don'ts prevent repeated mistakes.

## Never Do This
- Do not leave `console.log` in production code
- Use `pnpm`, never `npm` or `yarn`
- Never hardcode `.env` secrets into source
- No `any` types
- Do not use `pages/` directory (App Router only)

5. Common Commands

Save yourself and Claude the lookup.

## Common Commands
- Dev server: `pnpm dev`
- Build: `pnpm build`
- Tests: `pnpm test`
- Lint: `pnpm lint`
- Type check: `pnpm type-check`
- DB migration: `pnpm db:migrate`

Real Example: Next.js + TypeScript Template

A practical template you can copy and customize.

# Project Instructions

## Project Overview
[Write 1–2 sentences here]

Example: an inventory SaaS for small business owners.
Next.js 14 App Router + TypeScript + Supabase.

---

## Tech Stack
- **Framework**: Next.js 14 (App Router)
- **Language**: TypeScript (strict mode)
- **Styles**: Tailwind CSS
- **DB / Backend**: Supabase
- **Package Manager**: pnpm
- **Deployment**: Vercel

---

## Directory Structure
\`\`\`
src/
├── app/          # Next.js App Router pages
├── components/   # Reusable UI components
│   ├── ui/       # Base UI (Button, Input, etc.)
│   └── features/ # Feature-specific components
├── lib/          # Utilities, Supabase client, etc.
└── types/        # TypeScript definitions
\`\`\`

---

## Coding Rules

### Style
- Indentation: 2 spaces
- Quotes: single quotes ('')
- Semicolons: always
- No trailing whitespace

### Naming
- Components: PascalCase (UserCard.tsx)
- Functions / variables: camelCase (getUserData)
- Constants: UPPER_SNAKE_CASE (MAX_RETRY_COUNT)
- Types / interfaces: PascalCase (UserProfile)

### TypeScript
- No `any` types
- Always annotate return types
- Define Props as interfaces

---

## Common Commands
\`\`\`bash
pnpm dev          # Dev server (localhost:3000)
pnpm build        # Production build
pnpm test         # Run tests
pnpm lint         # ESLint
pnpm type-check   # TypeScript check
\`\`\`

---

## Never Do This
- Use `npm` or `yarn` (always `pnpm`)
- Use `any` types
- Use `pages/` directory (App Router only)
- Hardcode env vars into source
- Leave `console.log` in production

---

## Git Commit Rules
- Format: `type: description`
- Types: feat, fix, docs, style, refactor, test, chore
- Example: `feat: add user login page`
- Concise, imperative mood

Global Memory for All Projects

Create ~/.claude/CLAUDE.md to apply rules to every project.

# Edit global CLAUDE.md
nano ~/.claude/CLAUDE.md

Good candidates for the global file:

# Global Settings (all projects)

## My Preferences
- Explain what you're about to do before changes
- Confirm before large or risky operations
- Keep explanations concise

## Universal Coding Style
- Short functions (under 20 lines where possible)
- Meaningful variable names
- Readable code over clever code

Memory Priority

When multiple CLAUDE.md files exist, the more specific one wins.

Priority (high → low):
1. CLAUDE.local.md (personal project overrides)
2. ./CLAUDE.md (project-level)
3. ~/.claude/CLAUDE.md (global / user memory)
4. Enterprise-managed settings (pushed by IT policy)

Use the @path/to/file import syntax to pull other files in dynamically (@README.md, @~/.claude/personal.md, etc.).

If global says "2 spaces" but the project says "4 spaces," the project wins.

Useful Tips

Use /memory

Edit CLAUDE.md mid-session:

/memory

A picker opens so you can edit directly.

File Imports

Reference other files from inside CLAUDE.md:

# Project Instructions

For the overview, see @README.md.
For scripts, see @package.json.

## Additional Rules
- Git workflow: @docs/git-guide.md

Start Every New Project with CLAUDE.md

First thing in any new project, create CLAUDE.md.

# Let Claude generate it
/init

Or ask Claude directly:

"I'm building a Next.js 14 + TypeScript + Tailwind project.
 I use pnpm and want all comments and commits in English.
 Create a CLAUDE.md based on these preferences."

Summary at a Glance

One-Line Summary

One CLAUDE.md removes the need to re-explain your project every session.

Next, let's cover the commands that make daily work faster.

09. Command Reference

A complete quick-reference for the commands you'll actually use.

Source: Slash Commands — Anthropic Docs

Three Types of Commands

Claude Code commands fall into three buckets.

CLI Commands

Launch or control Claude Code from the terminal.

Basic Launch

Specifying a Model

# Start with a specific model (full IDs)
claude --model claude-opus-4-7
claude --model claude-sonnet-4-6

# Short aliases also work
claude --model opus     # Opus 4.7 (default for Max and Team Premium)
claude --model sonnet   # Sonnet 4.6 (default for Pro and Team Standard)
claude --model haiku    # for lightweight tasks

Useful Startup Options

# Start in Plan Mode (read-only)
claude --permission-mode plan

# Resume a named session
claude --resume my-session-name

# Pick a session from a list
claude --resume

💡 Tip: just type claude to start. Learn the flags as you need them.

Slash Commands

Type / at the prompt inside Claude Code to access built-ins.

Most Useful

How to Use Them

> /compact
→ Compresses the conversation to free context

> /compact focus on code changes only
→ You can steer the compaction

> /model
→ Opens the model picker

💡 Tip: type / alone for an autocomplete list of every command.

Keyboard Shortcuts

Control Claude Code without leaving the keyboard.

Essentials

Input Shortcuts

Mode Switching

Top 5 for Beginners

Memorize these five first.

1. /compact — The Most Important

> /compact

Long sessions slow Claude down and push earlier context out. /compact compresses and restores performance. Use it often.

2. Ctrl+C — Stop Immediately

Press this the moment Claude heads the wrong direction. It halts immediately.

3. /clear — Start Fresh

> /clear

Use when switching to a completely different task. All prior conversation is erased.

4. Shift+Enter — Multi-Line Prompts

For detailed instructions that don't fit on one line.

(Example of multi-line input with Shift+Enter)
Create a login page with:
- Email and password fields
- Show/hide password toggle
- Login button with loading state
- Form validation with error messages

5. /usage — Check Cost and Limits

> /usage

Shows session cost, plan limits, and activity stats. /cost and /stats are aliases of the same command (only the opening tab differs).

Terminal Aliases

Short commands beat long ones.

macOS / Linux (zsh)

Add to ~/.zshrc:

alias cc='claude'
alias ccd='claude --dangerously-skip-permissions'
alias ccr='claude --resume --dangerously-skip-permissions'

Apply:

source ~/.zshrc

Windows (PowerShell)

Add to $PROFILE:

function cc { claude @args }
function ccd { claude --dangerously-skip-permissions @args }
function ccr { claude --resume --dangerously-skip-permissions @args }

Restart PowerShell to apply.

What Each Alias Does

⚠️ Warning: --dangerously-skip-permissions approves every action without asking. Use only in trusted projects and controlled environments.

Quick Reference Card

Terminal (before starting):
  claude              → Start
  claude -v           → Version
  claude --help       → Help
  claude -c           → Continue last
  claude --resume     → Pick from list

Aliases:
  cc                  → claude (basic)
  ccd                 → auto-approve all
  ccr                 → resume + auto-approve

Inside a session:
  /help               → All commands
  /compact            → Compress (use often)
  /clear              → Reset
  /branch (/fork)     → Branch the conversation
  /usage              → Cost · limits · stats (/cost · /stats alias)
  /model              → Change model
  /quit               → Exit

Keyboard:
  Ctrl+C              → Cancel current action
  Ctrl+D              → Exit
  Shift+Enter         → New line
  ↑↓                  → History
  Esc Esc             → Rewind

One-Line Summary

Know /compact, Ctrl+C, /clear, Shift+Enter, /usage. The rest you'll pick up as you go.

10. Session and Context Management

How to work longer sessions efficiently — compress, resume, and add safety nets before complex tasks.

What Is the Context Window?

Like every AI, Claude Code has a limit on how much it can hold at once. That limit is the context window.

As conversations grow:
  Earlier content gets pushed out
  → Claude may forget prior work
  → Response quality starts to drop

Analogy: when your desk fills up, old papers get shoved off. Tidy up occasionally.

Managing context before it fills keeps quality steady.

/compact — Compress the Conversation

/compact

Summarizes the current conversation and frees context.

• Important content stays in the summary
• The session keeps going without interruption
• When to use: the conversation feels long, or answers start getting odd

Resuming Sessions

--continue — Resume the Last One

claude --continue

Picks up exactly where you left off.

• Closed the terminal and came back
• Continuing the next day

--resume — Pick a Session

claude --resume

Shows a list of previous sessions.

• Juggling multiple projects
• Returning to a specific session from days ago

When to Start a New Session

Plan Mode Before Complex Tasks

Before big changes, turn on Plan Mode.

Shift + Tab  →  Toggle Plan Mode

In Plan Mode, Claude will:

1. Show only the execution plan (no file changes)
2. Ask "Does this look right?" first
3. Execute only after you approve

When to use it: modifying many files at once, restructuring folders, changing DB schemas — anything hard to undo.

Parallel Sessions

Open multiple terminals and run different work in parallel.

Terminal 1: claude (frontend)
Terminal 2: claude (backend API)
Terminal 3: claude (writing docs)

Each runs independently.

⚠️ Warning: two sessions editing the same file at once can conflict.

Effective Conversation Strategies

Don't Ask for Everything at Once

The most common beginner mistake is stuffing every request into one prompt.

# Not recommended — scope too broad
> Build the login, dashboard, DB connection, API, tests, and deployment all at once

# Recommended — step by step, check along the way
> First, set up the project structure
(review)
> Now build the login feature
(review)
> Next, add the dashboard

One task per turn, review, move on. Feels slower, finishes faster.

Split vs. Continue

Track Progress in CLAUDE.md

For multi-day projects, record state in CLAUDE.md.

# Current Progress
- Login: complete
- Dashboard: layout done, needs data integration
- Next: connect live data to dashboard

A new session reads CLAUDE.md and picks up fast.

Common Situations

Answers Suddenly Get Weird

1. Try /compact
2. Still odd? Start a new session
3. In the new session, re-provide only the key context: "I'm working on [project], have done [summary], and now need to [next task]."

Need to Stop Mid-Task

During work → Ctrl+C to interrupt
→ Close terminal
→ Next time: claude --continue

Claude remembers the state and picks up.

One-Line Summary

Compact often, resume deliberately, plan before big moves.

Longer context also means more tokens, so /compact quietly saves money too. Costs are covered in the Cost Management section of this guide.

11. Getting Started with GitHub

🖥️ This section is mostly for people who write code. If you're not coding, the Non-Developer File Versioning tips below are enough — feel free to move to the next section after that. No commands to memorize either way: plain language is the starting point.

Not a developer? Three ways to version your files

Even without code, files get accidentally overwritten or deleted. These options work without ever touching Git.

💡 Curious about Git? Git versions any file, not just code. Research notes, plans, quarterly reports — anything you'd want to roll back to "how it looked at midnight today" gets a real safety net. If that sounds useful, keep reading.

Why Git and GitHub?

With Claude Code, files change constantly. Without Git, situations like these come up fast:

• You can't tell why yesterday's code doesn't work today
• If Claude accidentally deletes something important, recovery is hard
• Collaborators overwrite each other's work
• "I definitely fixed this yesterday" can't be proven

Git records every change and lets you revert to any prior state. GitHub backs those records up in the cloud and enables collaboration.

For Claude Code users, Git and GitHub aren't optional. The safety net has to be in place before you can give bold instructions, and bold instructions are where the real productivity lives.

The one key difference from Google Drive

This is where first-time Git users get tripped up — and once you understand it, you never get tripped up again.

That one line is the whole mental model.

Git is always two steps:

1. Save (Commit) — record changes locally
2. Upload (Push) — send commits to GitHub

💡 Why two steps? You can save offline, and you pick exactly which changes are "ready to ship" before pushing. "Save = instant publish" isn't the rule, and that's both the freedom and the safety guard.

5-minute setup with Claude Code

No Git commands to memorize. Tell Claude Code in plain language and it handles most Git work for you. If you want a more guided onboarding, there are Git-related plugins under /plugin worth checking.

One-time setup

Just say:

"Start Git for this folder so I can push to GitHub"

What gets handled automatically:

1. Verify Git is installed (with install guidance if missing)
2. Verify GitHub CLI (gh) is installed
3. Log into GitHub (browser opens automatically)
4. Configure the project folder
   • New project → create folder + GitHub repo
   • Existing project → clone from GitHub
   • Current folder → initialize as a repo

Anything already done is skipped. The whole flow takes about five minutes, and you rarely have to think about setup again afterward.

Three things you do every day

1. Save your work (Commit)

"Save this"

Claude Code shows which files changed and asks for a short description. The trick with messages: write them so that you, six months later, can tell what you did from a single line.

Examples: "Update login page design"
          "Fix: password validation error"

After saving, Claude reminds you the changes are still only on your computer.

2. Upload to GitHub (Push)

"Upload it to GitHub"

Pushes commits and sends back the repo link. Claude handles common snags:

• Conflicts with a teammate's earlier push are merged automatically (--rebase)
• SSH auth errors fall back to HTTPS
• First push of a branch sets upstream automatically

3. Request review (Pull Request)

When a teammate should review:

"Open a pull request for review"

Claude creates a branch, commits, pushes, opens the PR, sends the link, and returns you to where you started. The PR body is pre-filled with a change summary, so you only need to add a single line about what this change is for.

Plain-language command reference

What you want                  Say something like
─────────────────────────────────────────────────
First-time setup               "Start Git for this project"
Check current status           "What's the current Git status?"
                               "What changed?"
Save (Commit)                  "Save this"
                               "Commit these changes"
Upload to GitHub (Push)        "Upload it to GitHub"
                               "Push it"
Request review (PR)            "Open a pull request for review"
                               "I want a teammate to review this"
Explain a term                 "What does commit mean?"
                               "What's the difference between push and commit?"

💡 Tip: For more structured Git onboarding, browse the Git plugins under /plugin. Several offer the same flow as slash commands, and some go further by codifying team conventions (branch naming, commit format) into automation.

Git terminology

Skim this when an unfamiliar word shows up.

When an unfamiliar word shows up, ask right then. Don't try to memorize — asking on demand is the faster path.

"What's the difference between push and commit?"

A daily routine with Claude Code

Start of day:
  Run claude → "Start Git for this project" (first day only)

While working:
  Edit files → "Save this" → "Upload it to GitHub"
  (Before risky changes: "What's the current Git status?")

End of session:
  "Save this" → "Upload it to GitHub" (always both steps)

Team collab:
  Finish feature → "Open a pull request for review" → share the link

Stick to this routine and everything you build with Claude Code stays safe. Even if the code breaks, you can roll back to any prior point — and you can always prove "I fixed this yesterday."

.gitignore — keep API keys off GitHub

The most common — and most expensive — beginner mistake is pushing a .env with API keys to GitHub. Once a key hits a public repository, treat it as effectively unrecoverable.

Claude Code auto-detects your project type on first save and creates a .gitignore. Existing ones are left alone.

Manual example:

# .gitignore example
.env
.env.local
node_modules/
.DS_Store

⚠️ Already pushed a key by accident? First, revoke and rotate the key from the issuing service immediately. Removing it from the repository isn't enough — by then it's likely cached in mirrors, forks, and crawlers.

💡 Prefer raw Git commands? Just say them to Claude Code — it runs git commit and git push for you. If Git feels foreign, start with plain language ("Save this", "Upload it to GitHub"), then graduate to formal commands once you're comfortable. The two paths produce identical results and end at the same place.

12. Common Mistakes and How to Fix Them

Ten beginner problems in Q&A form, with clear fixes.

Q1. "command not found: claude"

Symptom

$ claude
zsh: command not found: claude

Cause and Fix

Claude Code is installed, but the terminal can't find it.

Option 1: native installer (most reliable).

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

Close the terminal and open a fresh one.

Option 2: check PATH.

# Where is claude installed?
which claude

# Current PATH
echo $PATH

If ~/.local/bin is missing, add this to your shell config (.zshrc or .bashrc):

export PATH="$HOME/.local/bin:$PATH"

Then source ~/.zshrc or open a new terminal.

Option 3: health check.

claude doctor

It diagnoses common install issues automatically.

Q2. Login / Authentication Isn't Working

Symptoms

• Browser doesn't open during login
• Auth screen hangs
• Still getting errors after logging in

Fixes

Browser popup doesn't open.

During claude startup, press c to copy the OAuth URL, then paste it into your browser manually.

Log out and re-authenticate.

# Inside Claude Code
> /logout

# Or from the terminal (auth and session data live in ~/.claude.json)
claude auth logout
claude

Run the health check first.

# Inside Claude Code
> /doctor

Full reset (last resort).

# ⚠️ Only if the above didn't help
rm ~/.claude.json
rm -rf ~/.claude/
claude

⚠️ Warning: this erases settings, history, and plugin config. Try /doctor first.

Q3. Claude Code Is Too Slow

Cause

A long session means more context per message. Performance drops as the window fills.

Fixes

Option 1: /compact — the most effective.

> /compact

Compresses history and restores speed.

Option 2: /clear — start fresh.

If you don't need the current conversation:

> /clear

Option 3: switch models.

Haiku and Sonnet are faster than Opus for most tasks.

> /model

Option 4: disable idle MCP servers.

> /mcp

Turn off servers you're not actively using.

Q4. Claude Isn't Doing What I Asked

Cause

The request was vague, Claude lacks project context, or repeated corrections have muddled the state.

Fixes

Option 1: be specific.

# Vague
> Improve the code

# Specific
> In the login function in auth.js, add email format validation
  using a regex. Insert it on line 42, right before the
  password check.

Option 2: put rules in CLAUDE.md.

For recurring requirements, make them permanent.

> /memory

Or edit CLAUDE.md directly:

# Code style rules
- All error messages must be in English
- Every function requires a JSDoc comment
- Never use var — use const or let only

Option 3: clear after two failed tries.

> /clear

Restart with a better prompt.

Q5. Claude Modified the Wrong Files

Fixes

Option 1: rewind (fastest).

Press Esc twice in a row
or:
> /rewind

Restores both the conversation and the code.

Option 2: recover with git.

# See what changed
git diff

# Restore a single file
git checkout -- src/auth/login.js

# Discard everything
git checkout .

Option 3: build the commit habit.

Before any significant session:

git add .
git commit -m "checkpoint before Claude session $(date +%Y%m%d-%H%M)"

Q6. My Bill Spiked Unexpectedly

Causes

• Session context got huge (more context = more tokens per message)
• Asked Claude to read the whole codebase with no focus
• Left Opus running on simple tasks
• Ran multiple sessions or sub-agents at the same time

Fixes

Check current usage.

> /usage

Shows session cost, plan limits, and activity stats. /cost and /stats are aliases of the same command (only the opening tab differs).

Reduce costs.

1. Use /compact often to keep context small
2. Switch to Sonnet or Haiku for routine work (/model)
3. Don't ask Claude to scan huge directories aimlessly
4. Run /clear between unrelated tasks

Set a budget for automation.

claude -p --max-budget-usd 1.00 "your query here"

Q7. Too Many Permission Prompts

Situation

Claude asks before every file edit or command.

Fixes

Option 1: allow frequent tools permanently.

> /permissions

In the UI, set specific tools to Always Allow.

Option 2: Auto-Accept for the session.

Press Shift+Tab to cycle into Auto-Accept Edit Mode

File edits are auto-approved for the session.

Option 3: understand the modes.

About --dangerously-skip-permissions.

It disables every check. Use only in isolated containers or VMs. On your main machine it can delete or modify system files by accident.

Q8. Garbled Text or Encoding Issues

Cause

The terminal isn't using UTF-8.

Fixes

macOS / Linux.

Add to .zshrc or .bashrc:

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

Then source ~/.zshrc or open a new terminal.

Check terminal settings.

• iTerm2: Preferences → Profiles → Terminal → Character Encoding → UTF-8
• macOS Terminal: Preferences → Profiles → Advanced → Character Encoding → Unicode (UTF-8)
• VS Code terminal: UTF-8 by default, usually fine

Windows (WSL).

sudo locale-gen en_US.UTF-8

Q9. Claude Lost Context

Situation

• Claude doesn't remember what it did earlier
• Session was interrupted
• Terminal was closed and reopened

Fixes

Option 1: resume.

# Most recent session
claude --continue

# Pick from a list
claude --resume

# By name (if you named it)
claude --resume auth-refactor

Option 2: name sessions in advance.

At the start of important work:

> /rename login-feature-dev

Option 3: store critical context in CLAUDE.md.

Anything that must survive a restart belongs there.

> /memory

# Current Work in Progress
- Goal: OAuth2 authentication
- Done: basic login / logout
- In progress: social login (Google, GitHub)
- Stack: Next.js, Prisma, NextAuth.js

Q10. Claude Changed Way More Than Expected

Situation

You asked for a small fix. Claude rewrote unrelated files.

Fixes

Option 1: stop immediately.

If Claude is still working:

Ctrl+C

Or press Esc to interrupt.

Option 2: rewind.

Press Esc twice
or:
> /rewind

Option 3: review with git.

# See which files changed
git status

# Review the diff
git diff

# Restore a file
git checkout -- path/to/file

# Discard everything
git checkout .

Option 4: use Plan Mode for big tasks.

Shift+Tab (twice to enter Plan Mode)

Or start a session there:

claude --permission-mode plan

Review before any changes happen.

Option 5: scope your instructions.

# Limit scope
> Only modify the login function in auth.js — do not touch any other files

# Exclude explicitly
> Fix the bug only — don't refactor or clean up

Prevention Checklist

Before a session:
□ Navigated to the project folder? (cd my-project)
□ git commit on important changes?
□ CLAUDE.md has up-to-date rules?

During:
□ Instructions specific enough?
□ One thing at a time?
□ Using /compact as it gets long?
□ Ctrl+C the moment something looks wrong?

After:
□ Reviewed changes? (git diff)
□ Tests still pass?
□ Named the session if you'll resume? (/rename)

One-Line Summary

Most problems resolve with /doctor, /compact, or a rewind. When in doubt, commit often.

If your problem isn't here, run /doctor or type /bug to report it to Anthropic.

13. Debugging — When You Hit an Error

A three-step workflow for resolving errors without panic.

We've all stared at a terminal full of red text and gone blank. In my first few days I jumped to a search engine after reading only the top line of an error — turns out the actual answer was usually further down the screen. Half the work is staying calm; the other half is just trusting the rhythm of reproduce → hypothesize → verify. Once that rhythm clicks, errors stop feeling like alarms and start reading like the next instruction in a manual.

Step 1: Show the Error Immediately

When you get an error, show it to Claude as-is. You don't need to understand it.

Method 1: Copy and Paste

> I'm getting this error:
  TypeError: Cannot read property 'name' of undefined
  at UserList.render (src/components/UserList.js:23)

Method 2: Paste a Screenshot

Capture the error and paste it with Ctrl+V (Mac: Cmd+V) into the chat. Claude reads images.

Method 3: Describe It in a Sentence

> I just got an error, fix it
> I ran npm run dev and it won't start
> When I click the button the screen freezes

Claude reads your current folder, finds the cause, and fixes it.

💡 Tip: long English error messages aren't scary. Paste the whole thing. Claude handles the rest.

Step 2: "It's Broken and I Don't Know Why"

No error message, nothing works. That's the most frustrating case. Try these.

Rewind to Find the Cause

> /rewind

Goes back to a working point. If "it worked before," this is the fastest fix.

Restore with a Checkpoint

Press Esc twice to revert to the state right before Claude's last edit.

Check What Changed

> Show me what you just changed

Claude shows the diff, which often reveals where things broke.

Narrow It Down Step by Step

> Undo changes one by one and find where it breaks

Claude reverts in order to find the breaking change. Especially useful after editing several files at once.

Step 3: "You Fixed It but the Same Problem Is Back"

When an error keeps coming back, change your approach.

Record It in CLAUDE.md

> Add to CLAUDE.md: "Always use dayjs for dates in this project"

Noting the cause in CLAUDE.md stops Claude from repeating the mistake. You're building project rules over time.

Compare with the Previous Error

> I had a similar error before — check if this is the same cause

Same symptoms can have different causes. Ask for a comparison.

Start Fresh in a New Session

Long conversations pull Claude back to earlier approaches.

# End current session
/quit

# Start a new session
claude

In the new one, hand over only the key context:

> Read @CLAUDE.md, then fix the recurring token expiration error in src/auth/login.js

Common Mistakes Non-Developers Make

"Fix Everything"

Too broad, Claude gets lost. Narrow it.

Ignoring Errors and Asking for More Features

Stacking new code on broken code compounds the problem. Fix errors first.

# Not recommended
> (ignoring the error) Now build the payment feature

# Recommended
> Fix this error first
(after it's resolved)
> Now build the payment feature

Repeating the Same Failed Approach

If Claude tries the same fix two or three times, redirect.

> This approach isn't working. Try a different method
> Solve it with a completely different library

One-Line Summary

Error? Show it. No cause? Rewind. Keeps repeating? Record it and restart.

Useful Features to Know

A collection of features that make Claude Code more convenient.

Source: Permission Modes — Anthropic Docs

Easier Input

Image Input

Show Claude error screenshots, UI mockups, and more.

• Ctrl+V — paste an image from the clipboard (on macOS too, use Ctrl+V, not Cmd+V)
• Drag and drop — drag an image file into the terminal
• File path — "Analyze this image: /path/to/image.png"
• Formats: JPEG, PNG, GIF, WebP (max 5MB)

> Find the error in this screenshot [paste with Ctrl+V]
> @design-mockup.png Build this according to the mockup

Voice Input (/voice)

Speak instead of typing.

• Type /voice, hold the spacebar, and speak
• Supports 20 languages, including Korean
• You can mix voice and typed input
• Beta, rolling out gradually

💡 Tip: useful for long explanations you don't feel like typing.

Undo Mistakes

Checkpoint (Esc Esc)

Claude snapshots state before modifying files.

• Press Esc twice to revert
• Works automatically, no setup
• Fastest undo, even without git

/rewind

Rewinds both conversation and code.

• Good for stepping back several moves
• If Esc Esc is one-step, /rewind lets you pick the point to return to

> /rewind
→ A list of checkpoints appears — choose one to return to

When Sessions Get Long

Auto-Compact

Long conversations get tidied automatically.

• Automatic, no setup
• Rules in CLAUDE.md are always preserved
• You can trigger manually with a focus:

> /compact Summarize focusing on API changes

Auto Memory

Claude remembers important information during work.

• Independent of CLAUDE.md
• Retains context even when switching sessions
• Use /memory to view and edit

Extended Thinking (/effort)

Tells Claude to think harder on hard problems.

• On by default
• /effort high — deep thinking (slower, more accurate)
• /effort low — quick answers for simple questions
• Adding "ultrathink" to a prompt maxes thinking depth for that turn only

Staying Safe

Permission Modes

Claude asks before modifying files or running commands.

• During a session: switch with /permissions
• At launch: claude --permission-mode plan (or acceptEdits, etc.)
• Start with default and get comfortable before loosening

More Things You Can Do

Computer Use — Claude sees your screen and drives mouse and keyboard. Useful for app testing and GUI automation. (Research Preview, macOS.)

Remote Control — continue terminal work from your phone or another device. Connect with a QR scan.

Chrome Integration — Claude drives Chrome directly. Great for web tests, data extraction, form automation.

Scheduled Tasks (/loop) — run a prompt at set intervals. Useful for monitoring and periodic checks.

One-Line Summary

Images, voice, checkpoints, auto-compact — small features that add up to a much smoother workflow.

15. Writing Effective Prompts

80% of the result quality comes from the prompt. The model is secondary.

You've probably had days where the same model nails a task in one shot, and other days where five rounds of revision still miss the mark. I spent weeks blaming model versions and luck before realizing the real variable is information density in the prompt. Add one line each for context · scope · output format · examples, and the same model behaves like a different colleague entirely. Nothing to memorize — just keep the picture below in your head.

The difference between someone new to Claude Code and someone two months in isn't model choice — it's a single line of prompt. This section is about that line.

The 4 Elements of a Good Prompt

1) Context — why and what for

Claude can't read your mind. The same code gets different answers depending on who's reading it.

Bad)  Fix this function.
Good) This function exists to reduce payment failures.
      Timeouts are common, so we need retry logic.

2) Scope — how far you may go

Without scope, Claude touches everything that "looks related". That's the most common reason a task drifts off course.

Good) Modify only validateEmail in src/auth/login.ts.
      Do not touch any other file.

3) Examples — input and expected output

One input + one output beats a hundred lines of description.

Input:    "kim.user@example.com"
Expected: { valid: true, domain: "example.com" }

Input:    "wrong@email"
Expected: { valid: false, reason: "missing TLD" }

4) Verification — how we know it worked

Adding "write the test too" or "run lint until it passes" at the end raises quality by a noticeable level.

Good) After the fix, run npm test until it passes.
      If anything fails, tell me where and why.

Before / After

Common Templates

Template 1 — Add a feature

[Context] This project is a ___.
[Goal]    I want to add ___.
[Scope]   Modify only ___.
[Example] Input ___ should produce ___.
[Verify]  Run ___ tests after the change.

Template 2 — Fix a bug

[Symptom] When I do ___, ___ happens.
[Expected] It should ___.
[Reproduce] Steps: ___.
[Constraint] Fix only inside ___. No unrelated refactors.

Template 3 — Refactor

[Target] Only ___ in ___ file.
[Goal]   Readability / performance / testability — pick one.
[Forbid] Do not change the public function signature.
[Verify] Existing tests pass unchanged.

Template 4 — Docs / research (non-coding)

[Context] I'm researching ___ in the field of ___.
[Input]   Use @file1.pdf and @file2.md as sources.
[Format]  Output as a table / paragraphs / slide outline.
[Filter]  Exclude ___, keep only ___.
[Length]  Under ___ words.

Anti-patterns

Reinforce with Inputs

When prose isn't enough, attach inputs. This connects naturally with the features in section 14.

Real Example — Same Task, Three Versions

Task: build a daily report of my stock holdings.

Vague (1/10)

Tidy up my stocks.

Average (5/10)

Read @portfolio.csv and summarize my holdings as a table.

4-Element Version (9/10)

[Context] I want to scan my holdings each morning quickly.
[Input]   @portfolio.csv has ticker and quantity.
[Scope]   No external API calls. Use only the file.
[Format]  One Markdown table:
          | Name | Ticker | Qty | Avg Cost | Note |
          Sort by ticker alphabetically.
[Filter]  Skip rows with quantity 0.
[Verify]  Add a "Total positions: N" line below the table
          so I can sanity-check at a glance.

Same tool, same model — vastly different results.

One-Line Summary

Claude is a smart new hire. Brief it like a new hire and you get new-hire-level work — clear, scoped, verifiable.

16. Plan Mode & Safe Recovery

Knowing you can undo is what gives you the speed to experiment.

Early on I'd toss a big change at Claude with a "go ahead, you'll figure it out" — and end up sighing at a tangled folder structure an hour later. The fix turned out to be simple: one alignment before execution, one checkpoint just before the change. With those two beats in place, the same task gets noticeably bolder. Plan Mode is the "are we still on the same page?" moment; checkpoints are the "if this goes sideways, here's where we come back" promise. Used together, they actually speed experimentation up rather than slow it down.

People hesitate before big changes for one reason — "if it goes wrong, rolling back is painful." Plan Mode and Checkpoint nearly eliminate that fear.

Plan Mode — Agree First, Execute Later

What it is

Claude shows you a plan without touching a single file. You only execute when satisfied.

How to enable

Shift + Tab   (cycles permission modes until you reach plan)
or
claude --permission-mode plan
or
inside a session: /permissions → plan

Two presses of Shift+Tab is the common path, but it depends on your starting mode. Watch the indicator at the bottom-left to confirm.

When to use it

• Multi-file changes
• Data migrations or schema edits
• First-time integration with an unfamiliar library
• Expensive operations (long builds, many external API calls)

Flow

1) Enable Plan Mode
2) "I want to add retry logic to the payment module.
    Show me your plan first."
3) Claude outputs a step-by-step plan
4) Like it? → switch back to normal mode and run
5) Don't? → refine the plan and review again

opusplan — Smart Planning, Light Execution

/model opusplan is the official alias that uses Opus during planning and switches to Sonnet for execution.

/model opusplan

Cost wins:

• Plan once, briefly (Opus rates, low tokens)
• Execute long (Sonnet rates, high tokens)
• Often less than half the cost of all-Opus work

💡 The plan phase of opusplan uses the standard 200K context. The 1M auto-upgrade does not apply, so plan accordingly for very large codebases.

Checkpoint — Esc Esc to Roll Back

Claude auto-snapshots before edits. No setup needed.

Press Esc twice → restore to the moment before the last edit

Use it the moment you notice:

• Files getting modified you didn't want
• A redesign you don't like
• A fix that introduced more bugs

It's the fastest recovery for people who don't know git yet.

/rewind — Go Back Multiple Steps

If Esc Esc is "one step back," /rewind is back to any chosen point.

/rewind
→ a list of points appears
→ pick the one you want

Conversation and code rewind together. Natural-language anchors like "before the login UI change" or "before adding the test" are recognized too.

After rewinding, inspect current state first before issuing a new task — otherwise you double-do work unintentionally.

> Show me what files are still modified now and confirm the working tree is clean.

/checkpoint — Explicit Save Point

/checkpoint and /undo are aliases of /rewind. Same command.

If you want a save point that survives session boundaries, drop a real git commit at that moment.

> Commit the current state with the message:
  'checkpoint: before payment refactor'

Three Tools Compared

Stack them — that's the standard practice.

The Three-Layer Safety Net

Before any large task, recall this order:

1. git commit — the final safety net that survives session crashes
2. Plan Mode — prevents the disaster before it happens
3. Checkpoint / /rewind — instant recovery for small mistakes

People with this trio don't hesitate on big changes. Speed of experimentation = speed of results.

Real Workflow — A Big Refactor

1) Check git status → commit everything pending
   "Commit the current state cleanly before I start changing things."

2) Enable Plan Mode (Shift+Tab)
   "Refactor src/payment/ to include retry logic.
    Show me only the plan: which files, what changes."

3) Review the plan → switch back to normal mode if good

4) Execute → Claude edits files
   Anything off? Esc Esc to back up one step.

5) Verify → run tests, build

6) OK → git commit
   Not OK → /rewind back to the start

Once this is muscle memory, "big change" stops feeling heavy.

Common Mistakes

One-Line Summary

A safety net is what makes experimentation cheap. Plan, Checkpoint, Git — that's all you need.

17. Statusline & Cost Visibility

Costs you cannot see are costs you cannot control. Make the bottom of your terminal a cost dashboard.

In my first month on the Max plan, I only started asking "how much have I burned today?" after I hit a limit warning. I had basically been driving on the highway with no dashboard. The fix is simple: put model, tokens, and session time on a single line you can glance at. With even a one-line statusline visible, you instinctively glance down before kicking off a big task — and that one glance, repeated daily, reshapes your monthly bill more than any optimization will.

Most cost incidents happen in the moment you didn't notice what was going on. The Statusline removes that moment.

What Is the Statusline?

A single line that always sits at the bottom of your terminal. By default it shows:

It appears automatically — no setup.

Why Keep It Visible

/statusline — Customization

If the defaults aren't enough, open the interactive menu with /statusline:

/statusline

• Toggle items (model · tokens · cost · mode · directory · git branch · time)
• Color / emphasis
• 5-hour / 7-day usage windows

Settings save to ~/.claude/settings.json or the project's .claude/settings.json.

How It Differs from /usage

/usage (aliases /cost, /stats) is a detailed report you summon. The Statusline is always on. They complement each other.

Anomaly on the Statusline → drill down with /usage. That's the standard flow.

A Cost-Saving Workflow

Watching the Statusline and reacting to these triggers prevents most token waste:

5-Hour / 7-Day Window Awareness

Subscribers' Claude Code usage is bound to 5-hour and 7-day windows. Approaching the limits slows or pauses responses.

Show both on the Statusline to know "do I have headroom today" at a glance.

/statusline → enable "5h limit" and "7d limit"

💡 These limits are meaningful for Pro / Max / Team plans. API users won't see them.

Real Scenarios — Visibility Helps Non-Coding Too

Equity research session

9:00 AM) 'sonnet · 12% · $0.04 · default'
         → start summarizing news for 10 holdings.

10:30)   'sonnet · 78% · $0.31 · default'
         → near 80%. Fire /compact:
         "Keep only the per-ticker conclusions, drop article bodies."

11:00)   'sonnet · 22% · $0.31 · default'
         → fresh context, switch to financial-statement analysis.

Without the Statusline, by 11 the answers would slow down and you'd miss what got truncated.

Real-estate listing comparison

Many listings = tokens fill fast.
Statusline 50% → split listings into groups, run a fresh
session per group, then merge the comparison at the end.

Common Mistakes

Recommended Layouts

One-Line Summary

You can only control what you can see. The token-cost gap between people who keep the Statusline on and those who don't is double-digit percent.

15. MCP and External Tool Integrations

The standard that lets Claude operate GitHub, Slack, databases, and browsers directly.

Source: MCP & Integrations — Anthropic Docs

What Is MCP?

MCP (Model Context Protocol) is an open standard that connects Claude Code to external tools and data sources.

By default, Claude Code works with your local files and terminal. Plug in an MCP server and Claude can open GitHub PRs, read Slack threads, query your database, and touch the outside world — no copy-paste required.

Analogy: MCP is a USB port for Claude. Plug in a compatible tool and Claude uses it natively.

Manual Work MCP Eliminates

What You Can Do with MCP

GitHub — PRs and Issues Directly

# Add the GitHub MCP server
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# Once connected
> "Review PR #456 and suggest improvements"
> "Create a new issue for the bug we just found"
> "Show me all open PRs assigned to me"

Sentry — Production Error Analysis

# Add Sentry
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# After authenticating with /mcp
> "What are the most common errors in the last 24 hours?"
> "Show me the stack trace for error ID abc123"
> "Which deployment introduced these new errors?"

PostgreSQL — Query the Database

# Add the DB server (read-only recommended)
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

# Once connected
> "What's our total revenue this month?"
> "Show me the schema for the orders table"
> "Find customers who haven't purchased in 90 days"

Slack — Read and Send

With Slack integration, Claude gets the full thread context. A bug report lands in a channel, Claude reads the thread, and starts coding with the context in hand.

Notion, Asana, Figma, and More

The MCP registry lists hundreds of servers. You can also build your own with the open-source MCP SDK.

Installing MCP Servers

Option 1: Remote HTTP Server (recommended)

# Basic syntax
claude mcp add --transport http <name> <url>

# Example: Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# With a Bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Option 2: Local stdio Server

Runs as a local process. Ideal for tools needing direct system access or custom scripts.

# Basic syntax
claude mcp add [options] <name> -- <command> [args...]

# Example: Airtable
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

Option 3: SSE Server (Server-Sent Events)

Use for streaming-friendly remote servers.

claude mcp add --transport sse <name> <URL> \
  --header "Authorization: Bearer <TOKEN>"

Option 4: Register with raw JSON

Drop the full configuration in JSON when you need a more exact setup.

# HTTP server with pre-configured OAuth credentials
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

# stdio server with env vars
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

--client-secret keeps the OAuth client secret in a separate secure store.

Managing Servers

# List all
claude mcp list

# Details
claude mcp get github

# Remove
claude mcp remove github

# Status inside Claude Code
/mcp

Configuration Scopes

Settings live in one of three places.

# Project scope (shared with team)
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

# User scope (all your projects)
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

For team projects, commit .mcp.json so everyone picks up the same servers.

Top 3 Starter MCP Servers

Recommended by practical value.

1. GitHub MCP

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

Eliminates: copying PRs, browsing issues, assembling review context.

2. PostgreSQL / DB MCP

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://user:pass@localhost:5432/mydb"

Eliminates: explaining schema, copying query results, running queries separately.

3. Sentry MCP

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Eliminates: copying stack traces, correlating errors to deploys by hand.

Official Claude Code Connectors

Sign into Claude Code with a Claude.ai account and any MCP servers configured at claude.ai/settings/connectors are automatically available.

Officially supported:

• Slack: read and write channel messages
• Google Chrome: browser automation (Playwright-based)

OAuth-Protected Servers

Many cloud MCP servers need OAuth:

# Step 1: add the server
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# Step 2: authenticate
> /mcp

# A browser opens → log in → done

Tokens are stored securely and refresh automatically.

MCP Prompts as Slash Commands

When an MCP server exposes prompts, run them as /mcp__servername__promptname:

> /mcp__github__list_prs
> /mcp__github__pr_review 456
> /mcp__jira__create_issue "Login bug" high

MCP Resources with @

MCP servers can expose resources you reference with @:

> Can you analyze @github:issue://123 and suggest a fix?
> Compare @postgres:schema://users with @docs:file://database/user-model

Type @ in a prompt to see all resources from connected servers.

⚠️ Security Warning

⚠️ Warning: Don't install MCP servers from untrusted sources.

• MCP servers can access your filesystem, databases, and external services through Claude
• Servers that fetch external content can expose you to prompt injection
• Anthropic only verifies servers in the official registry
• Review unfamiliar source code before installing

# Project-scoped servers prompt teammates for approval before use
# (a built-in safety check for shared configurations)

One-Line Summary

MCP is Claude's plug-in port. Connect GitHub, databases, and Slack so Claude operates them directly.

Next up: automating Claude Code behavior with Hooks.

16. Hooks — Protect Your Work

What if AI runs rm -rf or git push --force and wipes your history? With Hooks, that can't happen.

Source: Hooks — Anthropic Docs

Why You Need Hooks

Claude Code is powerful. It creates, edits, deletes files, and runs Git commands. Vibe coding sees these happen in the wild:

• rm -rf wipes your entire project folder
• git reset --hard destroys uncommitted work
• git push --force overwrites teammates' code
• DROP TABLE drops the database

Hooks block dangerous commands before Claude runs them. Not trusting the LLM's judgment — blocking in code.

What Are Hooks?

Hooks are shell commands that run automatically on specific Claude Code events.

Cadence: once per session (SessionStart/SessionEnd), once per turn (UserPromptSubmit/Stop), every tool call (PreToolUse/PostToolUse). Key: exit 0 = allow, exit 2 = block (the stderr message is sent to Claude).

Where to Configure

/hooks gives you interactive setup, but copy-pasting the examples below is faster.

Essential Hook 1: Safety — Block Dangerous Commands

This one hook prevents most disasters.

Step 1: Create the Script

Create ~/.claude/hooks/block_dangerous.py:

#!/usr/bin/env python3
"""Safety Hook — automatically block dangerous commands"""
import json, re, sys

BLOCKED_PATTERNS = [
    # Block file deletion — use trash instead (recoverable)
    (r"\brm\s+", "Use trash instead of rm (brew install trash)"),
    (r"\bunlink\s+", "Use trash instead of unlink"),

    # Block Git history destruction
    (r"git\s+reset\s+--hard", "git reset --hard destroys uncommitted work"),
    (r"git\s+push\s+.*--force", "git push --force overwrites remote history"),
    (r"git\s+push\s+.*-f\b", "git push -f overwrites remote history"),
    (r"git\s+clean\s+-.*f", "git clean -f permanently deletes untracked files"),
    (r"git\s+checkout\s+\.\s*$", "git checkout . discards all changes"),
    (r"git\s+stash\s+drop", "git stash drop permanently deletes a stash"),
    (r"git\s+branch\s+-D", "git branch -D force-deletes a branch"),

    # Block database destruction
    (r"DROP\s+(DATABASE|TABLE)", "DROP permanently deletes data"),
    (r"TRUNCATE\s+TABLE", "TRUNCATE deletes all data"),
]

data = json.load(sys.stdin)
if data.get("tool_name") != "Bash":
    sys.exit(0)

command = data.get("tool_input", {}).get("command", "")
for pattern, reason in BLOCKED_PATTERNS:
    if re.search(pattern, command, re.IGNORECASE):
        print(f"Blocked: {reason}", file=sys.stderr)
        sys.exit(2)

sys.exit(0)

Step 2: Make It Executable

chmod +x ~/.claude/hooks/block_dangerous.py

Step 3: Register the Hook

Add to ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/block_dangerous.py"
          }
        ]
      }
    ]
  }
}

How It Works

When Claude tries rm -rf node_modules:

1. PreToolUse fires → block_dangerous.py runs
2. The command matches the rm pattern
3. Script exits with 2 → blocked, "Use trash instead" returned to Claude
4. Claude runs trash node_modules instead

trash sends files to the system trash so you can recover. Install with brew install trash (macOS) or npm install -g trash-cli.

Adding More Patterns

Append to BLOCKED_PATTERNS:

# Example: block chmod 777
(r"chmod\s+777", "chmod 777 is a security risk"),

# Example: block SSH to production
(r"ssh\s+.*prod", "Production server access blocked"),

Essential Hook 2: Completion Notification

Get a sound when Claude finishes. Never miss it while vibe coding in another window.

macOS — System Sounds

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Frog.aiff"
          }
        ]
      }
    ]
  }
}

Use different sounds for Stop vs Notification so you can hear "done" vs "needs attention."

Browse the options:

ls /System/Library/Sounds/

macOS — Desktop Popup

Swap sound for a popup, or add both:

{
  "type": "command",
  "command": "osascript -e 'display notification \"Task complete\" with title \"Claude Code\"'"
}

Linux

{
  "type": "command",
  "command": "notify-send 'Claude Code' 'Task complete'"
}

Combined Setup

Safety Hook + completion notification in one settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/block_dangerous.py"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Frog.aiff"
          }
        ]
      }
    ]
  }
}

Already have a settings.json? Merge the hooks key. Use /hooks to verify.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "FILE=\"$(jq -r '.tool_input.file_path // empty')\"; if [[ \"$FILE\" == customers/* || \"$FILE\" == invoices/* ]]; then echo \"Blocked: sensitive folder\" >&2; exit 2; fi"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "cat ~/work-rules.txt"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, continue working."
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/pre-tool-use",
            "timeout": 30,
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

Troubleshooting

Debug: claude --debug or Ctrl+O for hook execution logs.

One-Line Summary

Safety Hook plus Completion Notification — two hooks make vibe coding dramatically safer.

Next section: package repeatable workflows into Skills.

17. Skills and Building Plugins

Turn repetitive workflows into a single /command — reusable, shareable, always consistent.

Source: Skills — Anthropic Docs

What Are Skills?

Skills are reusable workflows that add capabilities to Claude Code. Create a SKILL.md file and Claude treats it as a tool — run it explicitly with /skill-name, or let Claude activate it when context fits.

In short: document a procedure you use often, then execute it with a single word.

The older .claude/commands/ custom slash commands are now part of Skills. Existing .claude/commands/ files still work.

Skills vs. Regular Conversation

Manual Work Skills Eliminate

Creating Your First Skill

Step 1: Create the Directory

# Personal skill (all your projects)
mkdir -p ~/.claude/skills/commit

# Project skill (this project only)
mkdir -p .claude/skills/commit

Step 2: Write SKILL.md

.claude/skills/commit/SKILL.md:

---
name: commit
description: Analyzes staged changes and creates a well-formed commit. Use when committing code changes.
disable-model-invocation: true
---

Analyze the currently staged changes and create a commit using Conventional Commits format:

1. Run `git diff --staged` to review changes
2. Identify the change type (feat/fix/docs/refactor/test/chore)
3. Write a title under 50 characters
4. Add a body with more detail if needed
5. Run `git commit -m "..."`

Step 3: Run It

# Direct invocation
/commit

# Or natural language — Claude auto-detects
"commit the changes"

Skill File Structure

my-skill/
├── SKILL.md           # Main instructions (required)
├── template.md        # Template for Claude to fill in (optional)
├── examples/
│   └── sample.md      # Example output (optional)
└── scripts/
    └── validate.sh    # Script Claude can execute (optional)

💡 Tip: keep SKILL.md under 500 lines. Move reference material to separate files.

Key Frontmatter Options

---
name: my-skill                    # Skill name (default: directory name)
description: What it does         # How Claude decides when to use this
disable-model-invocation: true    # true = only you can run it, no auto-trigger
user-invocable: false             # false = hidden from / menu, Claude-only trigger
allowed-tools: Read, Grep, Glob   # Restrict tools while the skill runs
context: fork                     # Run in an isolated subagent context
model: sonnet                     # Model to use for this skill
---

Three Practical Examples

Example 1: Automated Code Review

.claude/skills/review/SKILL.md:

---
name: review
description: Reviews code for quality, security, and performance. Use when reviewing code changes or PRs.
---

Review the code in the following order:

1. Analyze `git diff HEAD~1` or the file specified in $ARGUMENTS
2. Check for:
   - Readability and naming conventions
   - Missing error handling
   - Security vulnerabilities (SQL injection, XSS, hardcoded secrets)
   - Duplicate code
   - Test coverage
3. Organize findings by priority:
   - 🔴 Critical (must fix)
   - 🟡 Warning (should fix)
   - 🔵 Suggestion (consider)

Run:

/review src/auth/login.ts

Example 2: GitHub Issue Handler

.claude/skills/fix-issue/SKILL.md:

---
name: fix-issue
description: Implements a GitHub issue end-to-end. Pass an issue number to analyze, implement, test, and commit.
disable-model-invocation: true
allowed-tools: Bash(gh *), Read, Edit, Write
---

Handle GitHub issue $ARGUMENTS:

1. Run `gh issue view $ARGUMENTS` to read the issue
2. Understand requirements and plan the implementation
3. Find relevant files and write the code
4. Write and run tests
5. Commit the changes and run `gh issue close $ARGUMENTS`

Run:

/fix-issue 123

Example 3: Translation Automation

.claude/skills/translate/SKILL.md:

---
name: translate
description: Translates a file or text into the target language.
argument-hint: [file-path or text] [target-language]
---

Translate $ARGUMENTS[0] into $ARGUMENTS[1].

- Preserve technical terms as-is (code, commands, proper nouns)
- Keep Markdown structure intact
- Save the translation with the language code appended to the original filename

Run:

/translate README.md ko

Dynamic Context Injection (reference)

The !`command` syntax runs a shell command before the skill reaches Claude, injecting live data:

---
name: pr-summary
description: Writes a PR summary based on actual diff and comments.
context: fork
allowed-tools: Bash(gh *)
---

## PR context
- Diff: !`gh pr diff`
- Comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

Based on the above, write a clear and concise PR summary.

When the skill runs:

1. Each !`command` executes immediately, before Claude sees anything
2. Real output replaces the placeholder
3. Claude writes the summary with live PR data in context

Where Skills Are Stored

When the same name exists in multiple places, priority is enterprise > personal > project.

Packaging Skills as a Plugin

To share across teams or the community, package skills as a plugin.

Plugin Structure

my-plugin/
├── .claude-plugin/
│   └── plugin.json        # Plugin metadata
├── skills/
│   ├── review/
│   │   └── SKILL.md
│   └── commit/
│       └── SKILL.md
└── hooks/
    └── hooks.json         # Plugin-scoped hooks

plugin.json

{
  "name": "my-plugin",
  "description": "Shared team workflows",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

Local Testing

# Launch Claude Code with the plugin loaded
claude --plugin-dir ./my-plugin

# Run skills with the plugin namespace
/my-plugin:review
/my-plugin:commit

Standalone vs. Plugin

How Claude Auto-Detects Skills

Claude reads the description to decide when a skill fits:

# Good
description: Reviews code for quality, security, and performance. Use when reviewing PRs or analyzing code changes.

# Too vague
description: review tool

• The clearer the "when," the better the match
• Add disable-model-invocation: true to prevent auto-activation entirely

Passing Arguments

You and Claude can pass arguments:

---
name: migrate-component
description: Migrate a component from one framework to another
---

Migrate the $ARGUMENTS[0] component from $ARGUMENTS[1] to $ARGUMENTS[2].
Preserve all existing behavior and tests.

Run:

/migrate-component SearchBar React Vue

Shorthand: $0, $1, $2 instead of $ARGUMENTS[0].

Troubleshooting

One-Line Summary

Skills turn what you do often into a /command. Package them into a plugin to share.

Next up: sub-agents for parallel work on complex tasks.

18. Sub-Agents

Claude delegating to other Claudes — parallel processing for complex work.

Source: Sub-agents — Anthropic Docs

What Are Sub-Agents?

Sub-agents are specialized Claude instances the main Claude delegates specific tasks to. Each runs in its own context window, with a custom system prompt, restricted tools, and independent permissions.

When a task is delegated, the sub-agent works alone and returns only a summary — your main context stays clean.

Architecture Overview

Main Claude (Orchestrator)
    │
    ├──► Sub-agent A: Explore (read-only)
    │         └── File reading and code search only
    │
    ├──► Sub-agent B: general-purpose
    │         └── Read + write files
    │
    └──► Sub-agent C: custom test runner
              └── Bash execution only

Each sub-agent runs in an isolated context
→ Main context stays clean
→ Only result summaries return to main

When Sub-Agents Help

Use sub-agents when

Stick with the main conversation when

Built-In Sub-Agents

Claude Code ships with three.

When Claude searches a codebase, it delegates to Explore automatically. Thousands of lines stay in Explore's context — only the findings return.

Creating Your Own Sub-Agent

Option 1: /agents Menu (recommended)

/agents

1. Select Create new agent
2. Choose User-level (all projects) or Project-level (this project)
3. Select Generate with Claude and describe the role
4. Pick allowed tools
5. Pick a model (Haiku / Sonnet / Opus)
6. Save — available immediately, no restart

Option 2: Write the File

.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Reviews code for quality, security, and performance. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer focused on code quality and security.

When invoked:
1. Run `git diff` to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code clarity and naming conventions
- No duplicated logic
- Proper error handling
- Security vulnerabilities (exposed secrets, missing input validation)
- Test coverage

Format feedback by priority:
- 🔴 Critical (must fix)
- 🟡 Warning (should fix)
- 🔵 Suggestion (consider)

Sub-Agent Options

---
name: my-agent              # lowercase + hyphens (required)
description: When to use    # how Claude decides to delegate (required)
tools: Read, Grep, Glob     # allowed tools (inherits all if omitted)
disallowedTools: Write      # tools explicitly blocked
model: haiku                # haiku / sonnet / opus / inherit (default)
permissionMode: default     # default / acceptEdits / dontAsk / bypassPermissions
maxTurns: 20                # max agentic turns before stopping
memory: user                # persistent memory: user / project / local
background: false           # true = always run as background task
isolation: worktree         # worktree = run in an isolated git worktree
---

Where Sub-Agents Are Stored

Project agents are ideal for codebase-specific roles. Commit them so your team can improve them collaboratively.

User agents are personal, available everywhere.

Practical Examples

Example 1: Parallel Codebase Exploration

"Research the authentication, database, and API modules in parallel using separate sub-agents"

→ Three Explore sub-agents run simultaneously → Each returns a focused summary → Main Claude synthesizes all three

Example 2: Chained Review and Fix

"Use the code-reviewer sub-agent to find performance issues, then use the optimizer sub-agent to fix them"

→ code-reviewer returns issues → optimizer receives the list and applies fixes → Main context stays uncluttered

Example 3: Isolating Verbose Test Output

"Use a sub-agent to run the full test suite and report only the failing tests with their error messages"

→ Thousands of lines stay in the sub-agent → Only failures and errors return

Example 4: Requesting a Specific Agent

"Use the code-reviewer sub-agent to review the authentication module"
"Have the debugger sub-agent fix the failing tests"

Persistent Memory Across Sessions

Set memory to give a sub-agent a directory that survives sessions:

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

As you review, update agent memory with codebase patterns, conventions,
and recurring issues. In future sessions, consult memory before beginning.

Foreground vs. Background

• Foreground: blocks until done; permission prompts pass through to you
• Background: runs concurrently while you keep working

# Request background
"Run this in the background"

# Switch a running task to background
Ctrl+B

Background sub-agents cannot use MCP tools.

If a background sub-agent fails on permissions, resume it in the foreground to retry with prompts.

⚠️ Cost Awareness

⚠️ Warning: each sub-agent is an independent Claude instance. Every agent consumes tokens separately.

• 3 parallel sub-agents = significantly more tokens
• Results returning to main consume extra tokens
• Unnecessary spawning compounds costs fast

Cost-saving tips:

• Use Haiku for read-only exploration
• Limit how much each sub-agent returns
• Keep simple work in the main conversation

Advice for Beginners

You don't need sub-agents when you're starting out.

Bring them in when these specific problems show up:

1. Main context overflows and compacts repeatedly
2. You run the same exploration work over and over
3. You need a tool-restricted reviewer that can't modify files

One-Line Summary

Sub-agents are Claude delegating to Claude. Isolated context, parallel power, real token cost — use when the problem calls for it.

19. Designing Your Personal AI Workspace

You've learned CLAUDE.md, Skills, and Hooks. Now let's combine them into an automated office, not just an AI tool.

What Is a Workspace?

Typical AI use: question in, answer out, starting from scratch every time.

Workspace: a system where an AI with a defined role operates consistently on your rules.

Components:

CLAUDE.md        → AI role, rules, and knowledge (long-term memory)
Folder structure → Work accumulates systematically
Skills           → Automation for repeats (/commands)
Hooks            → Automatic quality checks

Core Design Philosophy

Don't put everything in CLAUDE.md. Distribute to Skills, enforce with Hooks.

• CLAUDE.md: unchanging role and principles
• Skills: recurring task workflows
• Hooks: quality standards that must never slip

Workspace Examples

Research Workspace

CLAUDE.md essentials:
  - No claims without sources
  - Tag all information with source grade (A~E)
  - Auto-save research to /reports

Folder structure:
  inbox/      → Reference materials
  reports/    → Completed research
  sources/    → Source collection

Skills:
  /research [topic]  → web search → organize → save
  /summary [file]    → summarize document

Content Creation Workspace

CLAUDE.md essentials:
  - Brand tone (friendly and practical, minimal jargon)
  - Target audience
  - Content format templates

Folder structure:
  drafts/     → Drafts
  published/  → Published content
  templates/  → Reusable formats

Skills:
  /blog [topic]         → blog draft
  /newsletter [content] → newsletter format
  /sns [content]        → Instagram / Twitter version

Business Workflow

CLAUDE.md essentials:
  - Company/team info, current project status
  - Email style (formal vs. friendly)
  - Report format templates

Skills:
  /meeting [transcript] → summary + decisions + per-person action items
  /report [topic]       → weekly report draft
  /email [situation]    → email draft

Real Case Study: The Ideation Workspace

The actual workspace where this guide was built.

Core CLAUDE.md

# Ideation Workspace

## Role
AI partner for discovering, validating, and executing ideas

## Core Principles
- Korean only
- No claims without research (prevent hallucination)
- Source grades on all information (A~E)
- No "probably will work" without validation
- All ideas documented (prevent loss)

## Validation Method
4-Persona Council:
- Visionary: potential and vision
- Pragmatist: feasibility and resources
- Critic: risks and weaknesses
- User Advocate: user value

## Folder Structure
10-inbox/      → Reference materials
20-sparks/     → Idea capture
30-research/   → Research results
40-foundry/    → Validation results
50-blueprints/ → MVP design
60-ventures/   → Active projects
70-playbook/   → Accumulated experience
90-shelf/      → On-hold ideas

Skills in Use

/spark [idea]       → capture idea + ICE score evaluation
/research [topic]   → 7-step deep research
/validate           → 4-persona Council validation
/insight [content]  → save lesson to Playbook

What Was Built Here

• Idea capture and validation for this guide
• 3-AI section-structure debate (agent-council)
• 57 official docs researched
• Next.js site developed and deployed
• Ongoing improvements through continued conversation

Building Your Own — 4 Steps

Step 1: Define Your Purpose

Ask yourself:
□ What tasks do I repeat regularly?
□ What role should the AI play?
□ What rules do I want enforced?
□ Where should output accumulate?

Step 2: Write CLAUDE.md

Minimum template:

# [Workspace Name]

## Role
[Role and purpose — 1–2 sentences]

## Core Rules
- [Always do 1]
- [Always do 2]
- [Never do]

## Folder Structure
- [folder]/  → [purpose]
- [folder]/  → [purpose]

## Main Workflow
[Description of recurring workflow]

Step 3: Set Up Folders

Number prefixes keep them in order:

mkdir -p 01-inbox 02-work 03-output 04-archive

Step 4: Turn Repeats into Skills

Doing the same task three or more times? Make it a Skill. Creating Skills is covered in the Skills section of this guide.

Combining with MCP

Adding MCP makes a workspace dramatically stronger:

MCP connections are covered in the MCP section of this guide.

One-Line Summary

A workspace is never finished. Feels awkward? Update CLAUDE.md. Notice a repeat? Add a Skill. Over time it fits you perfectly.

20. Cost Management and Saving Tips

Use Claude Code smarter and cheaper.

Source: Customize your status line — Anthropic Docs

Cost Structure at a Glance

Claude Code has two main pricing models.

Pro/Max subscribers: Claude Code usage is included. Run /usage (alias /cost·/stats) to see session cost, plan limits, and activity stats in one place.

API users: charged on usage. Check the latest token rates at claude.com/pricing.

What Is a Token?

A token is the unit Claude uses to process text.

• English: roughly 1 word = 1–2 tokens
• Rule of thumb: ~4 characters ≈ 1 token

Tokens are consumed every time Claude reads a file, receives your message, or sends a response. Longer context = more tokens per turn.

When Costs Run High

1. Repeatedly Reading Large Files

Every read costs tokens. A 10,000-line log can burn tens of thousands in one shot.

2. Keeping Context Open Too Long

Everything prior stays in context. Mixing unrelated tasks piles up irrelevant data and drives up cost.

3. Using Heavy Models for Simple Tasks

Opus is more capable than Sonnet, but costs more per token. Routine tasks don't need it.

4. Uncontrolled Automation

Claude Code running without human oversight can burn tokens quietly.

5 Tips to Save

Tip 1: Compress with /compact

Long conversation? Summarize and shrink.

/compact Focus on code changes and test results

Important info is preserved; unnecessary history drops.

Set defaults in CLAUDE.md:

# Compact instructions

When you are using compact, please focus on test output and code changes

💡 Tip: /clear resets context entirely. Great when switching topics.

Tip 2: Avoid Unnecessary File References

Vague requests make Claude read too much.

Specific asks mean Claude reads only what it needs.

Tip 3: Use Haiku for Simple Tasks

Not every task needs the biggest model.

Switch mid-session:

/model haiku

Or at startup:

claude --model haiku

opusplan mode: hybrid that uses Opus for planning and Sonnet for execution.

/model opusplan

Tip 4: Use Fast Mode Wisely

/fast makes Opus 4.6 respond about 2.5x faster.

/fast

Fast Mode has higher per-token pricing. Use it for rapid iteration or live debugging. Turn it off for long autonomous tasks.

⚠️ Warning: Fast Mode is billed as extra usage and isn't included in your subscription's standard rate limits.

Tip 5: Check Costs with /usage

Run /usage for session cost, plan limits, and activity stats. /cost and /stats are aliases of the same command (only the opening tab differs).

/usage

Example output:

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    0 lines added, 0 lines removed

You can also configure the status line to show context usage in real time.

Model Cost Comparison

Exact pricing: Anthropic pricing.

The Advantage of Claude.ai Max

Pro and Max subscribers use Claude Code without API pay-as-you-go.

• Usage included in the subscription
• No API key required
• Freedom to experiment without watching per-token costs
• Max has higher usage limits

Fast Mode and context beyond 200K tokens (1M context window) can bill as extra usage even on subscription plans.

Team Cost Management

For teams on the API:

• Workspace spend limits: set team-wide caps in the Anthropic Console
• Usage dashboard: per-member cost and usage
• Parallel work warning: running multiple Claude sessions or sub-agents at once can increase token use quickly

Cost-Saving Checklist

✅ Run /clear between unrelated tasks
✅ Start a new session when switching topics
✅ Name exact files and functions in prompts
✅ Use Haiku for simple tasks
✅ Enable Fast Mode only when speed matters
✅ Check /usage regularly (/cost · /stats are aliases)
✅ Set compact instructions in CLAUDE.md

One-Line Summary

Smaller context, right-sized model, specific prompts. That's 90% of the savings.

21. Headless Mode and Automation Reference

Run Claude Code automatically without a human in the loop.

Source: Claude Code GitHub Actions — Anthropic Docs

What Is Headless Mode?

Normally Claude Code runs interactively — you ask, Claude responds, you feedback.

Headless mode runs Claude Code automatically from scripts, like any other CLI tool.

Headless = automated execution without human interaction.

The feature was called "headless mode" and is now part of the Agent SDK CLI. The -p flag and CLI options work the same.

When to Use It

Basic Usage

Add -p (or --print) to run non-interactively.

Simplest Form

claude -p "What does this project do?"

Allow Tools

Let Claude read and edit by specifying tools:

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

Structured JSON Output

For easy script parsing:

claude -p "Summarize this project" --output-format json

Output formats:

• text (default): plain text
• json: structured with result, session ID, metadata
• stream-json: real-time streaming JSON

Practical Example: Automated Commit

claude -p "Review my staged changes and create a commit with an appropriate message" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

Continue a Conversation

# First request
claude -p "Review this codebase for performance issues"

# Resume the most recent session automatically
claude -p "Now focus on the database queries" --continue

# Or pick from a list of previous sessions
claude --resume

--continue jumps back into the latest session; --resume opens a picker. With --output-format json, Claude returns the answer in result and the session ID in metadata, so your automation script can hand it to the next call.

⚠️ Cost Warning

⚠️ Warning: automation burns tokens.

• Unattended automation compounds costs quietly
• Cap turns with --max-turns
• Set workflow-level timeouts for runaway jobs
• Don't trigger workflows unnecessarily

claude_args: "--max-turns 5 --model sonnet"

Security Best Practices

• Never put API keys in code. Use safe environment variables or a secrets store.

# Correct
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

# Never
anthropic_api_key: "sk-ant-api03-..."

• Always review Claude's suggestions before merging.
• Grant only the minimum permissions the action needs.

A Note for Beginners

You don't need this yet.

Headless mode fits after you're comfortable with interactive Claude Code, CLAUDE.md, and MCP. Bookmark this for later.

Quick Reference

Headless mode:    claude -p "task description" --output-format json
Trigger:          cron or a local script
Cost control:     --max-turns, timeout, model selection
Security:         Never store API keys in code

One-Line Summary

Automation scales Claude Code. Also scales cost. Cap turns, pick smaller models, guard your keys.

23. Parallel Work with Git Worktrees

The clean way to run multiple Claude sessions on one repo. Same code, separate context, no conflicts.

If you've ever juggled two or three threads of work in the same repo, you know the moment when you stare at the screen wondering "wait, what was I doing here?" For a while I'd just copy the whole folder to fake a split — then worktrees changed how I work. The same repo, unfolded into multiple directories, with a different Claude living in each one. No conflicts, just clean context separation: design in one window, API in another, docs in a third — all running in parallel without stepping on each other.

Trying to run two Claude sessions in the same directory is risky. Worktrees solve this cleanly.

What Is a Git Worktree?

A first-class Git feature: check out one repository into multiple directories simultaneously.

# Default: one repo = one directory = one branch
~/repos/my-repo  (main branch)

# With worktrees: more directories, same repo
~/repos/my-repo        (main)
~/repos/my-repo-feat   (feature-A)
~/repos/my-repo-fix    (bugfix-X)

All three directories share the same .git, but each works on its own branch.

Why It Fits Claude Code

Same codebase, separate context, no conflicts — that's the whole pitch.

Basic Commands

Create a worktree

# Run from inside the main repo
cd ~/repos/my-repo

# Create directory ~/repos/my-repo-feat with branch feature-A
git worktree add ../my-repo-feat -b feature-A

List

git worktree list

# Example output
# /home/me/repos/my-repo        abc1234 [main]
# /home/me/repos/my-repo-feat   def5678 [feature-A]

Clean up

# Remove a finished worktree (the directory must be clean)
git worktree remove ../my-repo-feat

# If you deleted the directory by hand
git worktree prune

Recommended Flow

1. Keep the main tree on main — for deployment, syncs, quick spot checks
2. Do work in worktrees — one directory per feature-X or bugfix-Y
3. Run claude inside each worktree → separate sessions
4. After PR merge, remove the worktree

cd ~/repos/my-repo-feat
claude

# In another terminal:
cd ~/repos/my-repo-fix
claude

Both Claudes know the same codebase but never step on each other.

Cautions

What about CLAUDE.md?

Each worktree reads its own directory's CLAUDE.md.

• Repo-wide rules → in main repo's CLAUDE.md (committed → identical in every worktree)
• Worktree-specific rules → uncommitted CLAUDE.md in that directory
• User-wide → ~/.claude/CLAUDE.md

Non-Coding Uses — Same Source, Different Lenses

Worktrees aren't just for code. The same pattern works for research repositories.

Scenario 1 — Investment research

# Main repo: ~/research/markets
git worktree add ../markets-macro  -b macro-thesis
git worktree add ../markets-stocks -b stocks-deep-dive

• Main tree: macro indicators, news clippings, market structure
• macro-thesis tree: macro hypothesis, draft reports
• stocks-deep-dive tree: per-ticker financials, sector analysis

Each tree's Claude sees only its folder, so context never leaks.

Scenario 2 — Real-estate listings

git worktree add ../listings-seoul   -b seoul
git worktree add ../listings-bundang -b bundang

Keep listings and price data per region in separate trees. Final synthesis happens in the main tree. Because trees are isolated, the comparison stays objective.

Scenario 3 — A book in chapters

git worktree add ../book-ch3 -b chapter-3
git worktree add ../book-ch7 -b chapter-7

Drive each chapter forward in parallel. Different Claude sessions can experiment with tone or structure without spilling into each other.

Common Mistakes

One-Line Summary

When you only need to separate context inside one repo, no other answer is as clean as a worktree.

24. Custom Slash Commands & Output Styles

Done it twice? Make it a slash command. Need the same format every time? Lock it in an output style.

You'll catch yourself typing the same instruction for the third time and think, "wait, I keep writing this." That's the exact moment to make a slash command. It's just a one-line nickname, but that one line shrinks a daily five-minute prompt into a zero-second keystroke. Output styles work the same way — if a project always needs answers in a specific shape, write it down once and stop thinking about it. Each one becomes a small reusable asset, sometimes even worth sharing.

If you're typing the same prompt or expecting the same shape of answer every week, it's time to move it out of muscle memory and into a file.

Custom Slash Commands

Save frequent prompts as /your-command and call them in one shot. This is the same mechanism as Skills (section 17 — Custom Commands have been merged into Skills).

Where they live:

💡 For full Skills authoring, see 17. Skills & Building Plugins. This section focuses on non-coding patterns.

Simplest Form

.claude/skills/morning-brief/SKILL.md:

---
name: morning-brief
description: Daily briefing on tracked tickers
---

Read @portfolio.csv and brief me in this format:

| Ticker | Code | Change vs prev close | Note |
|---|---|---|---|

- Sort by ticker alphabetically
- Format change as +x.x% / -x.x%
- Leave Note column empty for me to fill

Now in any session:

/morning-brief

Same shape, every time.

Output Styles

Lock the tone, length, and shape of every response, per project. Slash commands say what to do, output styles say how to answer.

Where they live:

.claude/output-styles/
├── concise.md      # short and direct
├── tutorial.md     # step-by-step explanations
└── research.md     # cited paragraphs

Activate:

/output-style concise

All replies follow the style until you do /output-style default.

Sample Output Style — Concise

.claude/output-styles/concise.md:

---
name: concise
description: Short and accurate. Default for coding work.
---

# Concise Style

- Lead with the answer. No greeting or preamble.
- One-line summary, then details only if needed.
- Show only changed lines of code, not whole files.
- One clarifying question max — don't stack assumptions.
- English replies; keep code/commands as-is.

Non-Coding Examples — Four Patterns

Code isn't the only thing you can formalize. Daily ops and research benefit just as much.

1) Daily stock report

.claude/skills/daily-stock/SKILL.md:

---
name: daily-stock
description: Yesterday's news + volume change for tracked tickers
---

For each ticker in @watchlist.md:

1) 1-2 main news items from yesterday (cite source if available)
2) Yesterday's volume vs average
3) Output table:

| Ticker | News summary | Volume change | Flag |
|---|---|---|---|

Flag column: "⚠" if volume is +50% or news is negative.

Call with /daily-stock.

💡 For external data, attach inputs via @ or use an MCP server (see section 15-mcp).

2) Real-estate listing comparison

.claude/output-styles/listings.md:

---
name: listings
description: Always render listings as a fixed-column table
---

# Listings Style

Whenever you discuss listings, output this Markdown table:

| Listing | Location | Size | Price | Floor/Aspect | Notes |

- Use price units like "$X,XXX/mo" or "$XX,XXX deposit"
- Floor as "5/15" (current/total)
- Notes: furnished / pet-friendly / parking — one line
- Below the table, print "Total N listings, average price ___"

Activate: /output-style listings.

3) Weekly economic digest

.claude/skills/weekly-econ/SKILL.md:

---
name: weekly-econ
description: Monday digest of key macro indicators
---

For each entry in @indicators.md, write:

## [Indicator name]
- Previous: ___
- Consensus: ___ (if any)
- This release: ___ (or "TBD")
- One-line meaning: ___

End with the single most-watched indicator this week, in bold.

Call: /weekly-econ.

4) Meeting notes cleanup

.claude/skills/meeting-notes/SKILL.md:

---
name: meeting-notes
description: Clean meeting notes, action-items first
---

Read @$ARGUMENTS and structure as:

1) ## Action Items (owner + due date)
2) ## Decisions
3) ## Discussion summary (max 3 lines)
4) ## Open / Next-meeting topics

Preserve speaker labels as "Name:".
Drop chitchat, greetings, side conversations.

Call: /meeting-notes meeting-2026-04-30.md.

Slash Command vs Output Style — When to Use Which

They combine freely. With "Listings" output style active, calling /daily-stock automatically applies the table rules.

Dynamic Context — ! + Backticks

In a Skill body, prefix ! with backticks to inject command output as context at call time.

Today: !`date +%Y-%m-%d`

Files in current directory:
!`ls -la`

Live system state lands in context every call. (Security options and full usage in 17-skills.)

Common Pitfalls

One-Line Summary

Done twice? Make it a slash command. Same format always? Make it an output style.

25. Voice, Mobile, and Sandbox in Practice

No keyboard. Risky code. Both, handled safely.

If Claude Code only works at your desk, you're getting half of it. The idea you have on the subway tends to evaporate by the time you arrive, and running an unverified command straight on your real system is always a quiet stress. Dictate it by voice, continue from mobile, and cage the risky parts in a sandbox — once these three lanes are wired up, the tool finally starts moving at the rhythm of your full day, not just the hours you spend at a keyboard.

Claude Code isn't a desk-only tool anymore. You can use it on your phone, in transit, and around code you don't trust yet.

/voice — Speak Instead of Type

/voice
→ Hold space and talk

• Multilingual support including Korean
• Can mix voice and typing (Beta)
• Better for long descriptions than short commands

💡 Voice works best as a draft input. Reinforce file paths, command names, and code with typing.

Good fit

• Brain-dumping a long requirement
• When you can't use the keyboard (commuting, eating)
• Narrating while reading the screen

Bad fit

• Exact English function names or paths
• Short, simple commands
• Noisy environments

/mobile — Continue on Your Phone via QR

Move the live session to your phone.

/mobile
→ QR code is shown
→ Scan with your phone
→ Same session opens on the phone

The desktop can lock; work continues on the phone. Output syncs back when you return.

⚠️ Mobile auth tokens expire quickly. Re-issue the QR if the session drops.

Good fit

• Last-minute work before a meeting
• Quick monitoring or approvals during commute
• A fast check during external meetings

Bad fit

• Long manual coding (small screen)
• Wide context that doesn't fit phone width
• Anything sensitive on public Wi-Fi

/sandbox — Run Risky Code in Isolation

Untested scripts, first-time external API calls, or system-level commands belong in a sandbox first.

/sandbox
→ command runs in an isolated environment
→ only the result returns to the main session

Anything inside the sandbox can't touch your host filesystem.

When to use

💡 Security-sensitive code calls for the trio: sandbox + Plan Mode + a git commit before running.

Three Non-Coding Scenarios

Scenario 1 — Real estate during commute

07:50 (subway)
On phone: /mobile QR scan → reopens yesterday's listings session.

08:00
Throw three listing URLs into chat, then via voice (/voice on phone):
"Build a comparison table — price, size, floor —
and rank for weekend visits."

08:15
Arrive at work, open desktop: a clean comparison table is waiting.
Continue deeper analysis at the desk.

Scenario 2 — Mid-day stock memo

12:30 (post-lunch walk)
Voice memo:
/voice "Ticker A is trading 2x average volume but I don't see news.
Check disclosures and note any similar patterns in the last month."

18:00 (back at desk)
Open the session: disclosures checked, prior patterns flagged.
Decisions and trades stay with the human.

Scenario 3 — Safe data-scraping experiment

You want to grab 50 public records from a site you've never used.
The script came from another LLM and isn't verified.

1) /sandbox
2) "Run this script in the sandbox. Pull only 5 records.
   Stop and tell me if anything throws."
3) 5 records back, clean.
4) Copy only the validated approach to the main session.
   Scale to 50.

If the script had a runaway loop or hostile command, the host stays clean.

Combined Workflow — All Three at Once

Commute (/mobile) + voice (/voice) + risky work (/sandbox)

Example: in transit, on phone, by voice — "Try this new data source. Stay in the sandbox. Pull just 5 records safely."

Three commands, one flow.

Security & Privacy Checklist

Common Mistakes

One-Line Summary

Off the desk, in front of code you don't trust — Claude Code can still come along, safely.

22. Next Steps and Resources

You've finished the guide. The real journey starts here.

Source: Claude Code overview — Anthropic Docs

You Made It

You've walked through the Claude Code basics. The goal now is not memorizing more features; it is giving Claude Code small real tasks, checking the result, and narrowing the next request.

A quick look at what you covered:

• What Claude Code is and how it works
• Installation and authentication
• Customizing projects with CLAUDE.md
• Core commands and workflows
• What MCP is for
• When Hooks and Skills become useful
• How to test official plugins carefully
• Managing and optimizing costs
• Where later automation topics fit

This isn't just learning a new tool. You've practiced a working loop: delegate, verify, narrow, and repeat.

Learning Path

Beginner Complete (You Are Here)

✅ Install & authenticate Claude Code
✅ Write a CLAUDE.md file
✅ Core commands (/help, /usage, /compact, /model)
✅ Read files, edit code, run tests
✅ Basic plugin usage

Intermediate Goals

Build Your Own Workflow Automation. Combine CLAUDE.md + Hooks + Skills and turn repeats into a single command. Examples: weekly report draft, meeting notes cleanup, repeated document formatting.

Small Project Pipeline — Idea to First Result. A typical beginner pipeline:

1. Define goal   write what you want in one sentence
2. Gather inputs collect files, links, and examples in one folder
3. First output  build the smallest useful version
4. Verify        run it, read it, or inspect the screen
5. Refine        ask for one narrow change at a time
6. Record        save lessons in CLAUDE.md or notes

• Ground requests in official docs or current project files for more stable results.
• Keep a small note of prompts that worked and prompts that failed.

• Start with one terminal and one task.
• Editing the same file from multiple sessions can create conflicts.
• Try parallel work only after Git and recovery flows feel familiar.

MCP Setup. Connect Claude Code to external services.

# Add an MCP server
claude mcp add

Recommended MCP integrations:

• GitHub: PRs, issues, code search
• Slack: team notifications
• Notion / Linear: project management
• Figma: read design specs

Customizing Hooks. Automate things that must happen every time.

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit",
      "hooks": [{
        "type": "command",
        "command": "npm run lint -- $FILE"
      }]
    }]
  }
}

This example runs lint automatically every time Claude edits a file.

# Open the plugin manager
/plugin

# Install from the official marketplace
/plugin install commit-commands@claude-plugins-official

Recommended:

• commit-commands: Git workflow automation
• pyright-lsp / typescript-lsp: code intelligence

Reference: Later Topics

You do not need to implement these at C0. Know what they are, then come back when a real need appears.

Official Resources

Docs and Repositories

Using Claude Code Well — and Anti-Patterns

Now that you know the tool, when and how to use it is the next question.

Great Fit (use freely)

Requires Caution (review carefully)

5 Principles to Follow

1. Git commit before starting — always have a rollback
2. Be specific about scope — "only this function in this file"
3. Read generated code yourself — don't ship what you don't understand
4. Review security and payment code separately
5. Use Plan Mode for big tasks to agree on direction first (Shift+Tab)

Recommended First Real Projects

Jump in. These work whether you code or not.

1. Meeting Notes Automation

Hand off weekly note-taking.

"I have a file ~/Downloads/meeting-250225.mp3.
Transcribe it, then summarize + sort action items by person.
Save as meeting-250225.md"

Claude handles everything from installing transcription tools to organizing the output.

2. Build Your Own Skills

Turn weekly repeats into one /command.

"Create a Skill that generates a weekly report every Monday.
Based on GitHub commit history and my notes file,
draft a weekly summary."

3. Competitor Analysis Report

Analyze competitors in any field you care about.

"Analyze competitor websites A, B, C.
Compare features, pricing, target customers, differentiators.
Save as competitor-analysis.md"

4. Build a Portfolio Site (for developers)

"Build a developer portfolio site using HTML/CSS/JS.
Sections: intro, tech stack, projects, contact.
Keep it minimal with a dark theme."

5. Refactor Existing Code (for developers)

"Review and improve this file.
Focus on readability, performance, and error handling.
@src/utils/dataProcessor.js"

When You're Stuck

Step 1: Check the Official Docs

https://code.claude.com/docs

Or ask for help inside Claude Code:

/help

Step 2: Ask Claude Code Directly

Claude Code itself is the best help resource.

"How do I add an MCP server in Claude Code?"
"What does this error message mean: [paste error]"

Step 3: Community

• GitHub Issues: github.com/anthropics/claude-code/issues

Step 4: Anthropic Support

For account or billing issues, contact support via the Anthropic Console.

One Last Thing

Claude Code moves fast. What you learned today will look different in a few months. Understanding the underlying principles is what lasts.

Developing with AI isn't about writing code faster. It's a new collaboration — AI's strengths (broad knowledge, pattern recognition, repetitive work) paired with yours (judgment, creativity, domain expertise).

You've taken the first step. The rest is practice.

Quick Reference Card

Official Docs:       https://code.claude.com/docs
GitHub:              https://github.com/anthropics/claude-code
Official Plugins:    https://github.com/anthropics/claude-plugins-official
Console:             https://platform.claude.com

Next targets:
  Beginner     → CLAUDE.md, core commands, one official plugin test
  Intermediate → Small real project, basic MCP setup, one useful Hook
  Reference    → Skills, headless runs, and scheduled automation only when needed

One-Line Summary

You have the foundation. Pick one project this week and build it with Claude Code.

29. Updates

Read it like a book, but know it's a living one.

This guide is a rewrite based on what I've learned from using Claude Code myself, grounded in the official Anthropic documentation. It's meant to be read once, calmly, before you open the terminal — hopefully sparing you a few rounds of trial and error.

I'll keep updating it as new features ship and as I learn more along the way.

How to stay in the loop

There's no RSS or email list yet. To keep up:

• Email: lee.kkhwan@gmail.com
• Site: revisit sionlab.co.kr

Feedback, typos, and new-chapter requests are all welcome.