Which Plan? The Honest Answer Before You Sign Up

Claude Code runs inside a paid subscription — it's not part of the Free plan. If you're going to use it seriously, the conclusion comes first: Max (5x) is the most balanced starting point for most people. Here's why, and here's when Pro is fine.

Source: Anthropic Pricing

The One-Line Guide by User Type

Let me lead with the conclusion. Detailed comparisons follow below.

Plans Side by Side

Prices change frequently. Confirm the exact numbers at claude.com/pricing. The table below is a comparison snapshot.

💡 How to enable 1M context: /model opus[1m] or /model sonnet[1m]. Max, Team, and Enterprise include Opus 1M automatically; on Pro, Opus 1M access is limited, so meaningful use starts at Max and above. Sonnet 1M counts as extra usage on every plan.

Three Honest Reasons I Recommend Max (5x)

1. Pro's hourly limit fills up faster than expected. During focused work I've hit it in under an hour. When that happens, the day's momentum breaks.
2. Opus 4.7 on Pro is theoretically possible but practically difficult. The quota burns too fast. On Max, Opus is just the default.
3. Long conversations, multiple files, repeated revisions — token usage accumulates quickly. Max (5x) gives most individual users comfortable headroom.

💡 One time, this happened. At a workshop, a student was on Pro and hit the limit in the middle of a live demo. The session was at its most interesting point — debugging a multi-file restructure. We had to wait out the window before continuing. That session convinced me to start every recommendation with Max (5x).

When Pro Is the Right Call

Pro isn't automatically wrong. If the following describes you, Pro is a fine place to start.

• You want to spend 10–20 minutes a day just learning the commands and the flow
• Your main use is small document cleanup, README edits, or occasional questions
• You're mostly touching one file at a time in light sessions

On the other hand, if these patterns sound familiar, Pro will start feeling tight quickly.

• Long focused sessions: development, research, or automation running for hours at a stretch
• Needing Opus for complex architecture or difficult debugging
• Reading entire codebases or many files every day

Signals That It's Time to Move to Max

If two or more of the following apply to you, the cost of interruption is likely higher than the cost of the plan upgrade.

□ Claude Code sessions run over an hour a day
□ You've already seen a "limit reached" message
□ You regularly load long documents, multiple files, or entire codebases
□ You need Opus for architecture decisions or hard debugging
□ You go through build → validate → revise cycles frequently
□ You've started connecting MCP or automation to real workflows

Claude Code is a tool that yields more the deeper you go. Available usage directly shapes the quality of what you get out of it.

How the Cost Structure Works

Monthly subscription → Use freely within your limit
Hit the limit       → Responses slow down (no surprise charges)

• No need to track individual token counts. Limits run on two windows: a 5-hour window and a weekly window.
• /usage shows session cost, plan limits, and activity stats in one view (/cost and /stats are aliases for the same command).
• On Max, when Opus usage crosses its threshold, it automatically switches to Sonnet — work continues without stopping.

Five Small Habits That Reduce Token Use

• /clear between tasks: drops stale context so you're not carrying extra weight.
• Sonnet first: enough for most work and lighter than Opus.
• Narrow your requests: "improve the codebase" costs more than pointing at a specific file or function.
• Trim unused MCP connections: disable external connections you're not actively using.
• Name the scope explicitly: @specific-file.ts instead of "all files" keeps context small.

Section 03 and Section 20: How They Split the Topic

This section covers what to buy. The operational side — reducing token use through CLAUDE.md diet, permissions.deny rules, and context compression — is covered in depth in 20. Cost Management & Saving Tips. Reading both sections together tends to flatten the cost curve noticeably.

For the latest pricing and plan details: https://claude.com/pricing

Before You Leave This Chapter

• Identified whether your usage pattern fits Pro or Max (5x)
• Understood that hitting the limit interrupts flow — not just pauses it
• Know how to check usage with /usage or /cost
• Have a plan for what to do if you hit the limit: /compact, /clear, or /model to switch to Sonnet

The next chapter (04 Installation & Auth) gets Claude Code actually running on your machine. The install itself is one command — but knowing what to check if something goes wrong saves a lot of time.

What Happened When I Ran That First Command: Installation to First Launch

One command to install, then a browser click. That's the whole setup. The goal of this chapter is to walk with you through "that first time" — because once it's done, it stays done.

Source: Set up Claude Code — Anthropic Docs

💡 New to the terminal? That's fine. Copy the commands below (Cmd+C or Ctrl+C), paste them (Cmd+V or Ctrl+V), and press Enter. You don't need to understand what each part means right now.

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

Before Installing: Three Things to Check

Which OS does it run on?

What hardware do I need?

• 4GB RAM or more is enough
• An active internet connection (required both during install and while running)

Do I need to install Node.js separately?

No. Claude Code uses a native installer with no Node.js dependency. The older npm install -g method still works, but it's not recommended because of permission issues — especially with sudo, which is risky. Start with the native commands below.

Installing: Every Path Leads to the Same Place

macOS · Linux · WSL

The simplest approach is a one-line installer:

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

If you're already using Homebrew, this works too:

brew install --cask claude-code

💡 One time, this happened. During a WSL2 workshop, a student ran the curl command and nothing came back. Turns out a proxy setting was blocking the request. Since then I've made a habit of checking curl -I https://claude.ai before the install command — if you get a response, internet connectivity is fine.

Windows: Four Entry Points

Windows users have multiple paths. Whichever you choose, the end result is the same.

Option 1 · WSL — Linux-like experience (recommended)

Smoothest feature parity. One extra step upfront.

# Open PowerShell as Administrator
wsl --install

After rebooting, Ubuntu sets itself up automatically. Then use the Linux command above inside the Ubuntu terminal.

Option 2 · PowerShell direct install

Start without WSL, but some features may be limited.

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

Option 3 · CMD

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Option 4 · WinGet

winget install Anthropic.ClaudeCode

For Windows local sessions, Git for Windows must be installed.

Choosing Between WSL and PowerShell

One of the most common questions from people starting on Windows. Here's the short version:

If you expect a lot of coding, go WSL. If "organize the Downloads folder" is your first use case, PowerShell is fine. Switching to WSL later isn't hard.

Linux Package Managers (apt · dnf · apk)

You can also install from your distro's repository. For key registration and detailed steps, see the official setup guide.

# Debian · Ubuntu
sudo apt install claude-code

# Fedora · RHEL
sudo dnf install claude-code

# Alpine
apk add claude-code

⚠️ Versions installed through package managers don't auto-update. Run sudo apt upgrade claude-code (or equivalent) manually to keep current.

Alpine Linux: Extra Packages

The native installer on Alpine also needs these:

apk add libgcc libstdc++ ripgrep

Logging In: Once After Install, That's It

Once installed, run it right away:

claude

On first launch, your browser opens automatically to an OAuth login page. Sign in with a Claude.ai account on Pro, Max, Team, or Enterprise — or with an Anthropic Console account. (Free plan does not include Claude Code.) Some environments also support external providers like Bedrock, Vertex, or Foundry.

The Login Flow in Diagram

If the browser doesn't open automatically, copy the URL printed in your terminal and paste it into a browser manually. Completing the login there will authenticate your terminal session.

Where Are My Credentials Stored?

• macOS: API keys and OAuth tokens go into the system keychain (encrypted storage)
• Other OS: stored in a protected location inside your user directory
• To re-authenticate: run claude, then type /login

Confirming It Worked: Two Commands

claude --version

If a version number appears, the install is good. For a detailed diagnosis:

claude doctor

claude doctor shows install type, version, and environment status in one view. When something feels off, this command is usually the fastest way to find out why.

How Updates Work

If you installed with the native installer, Claude Code downloads new versions in the background at startup and applies them silently on the next launch. Versions installed via Homebrew, WinGet, apt, dnf, or apk don't auto-update — you'll need to update manually.

claude update              # Native installer
brew upgrade claude-code   # Homebrew
winget upgrade Anthropic.ClaudeCode  # WinGet

Waiting too long to update can introduce subtle issues that only appear on older versions. Running claude update once a month is a good habit.

The First Wall: Three Common Situations

Situation 1 · curl: command not found

curl itself isn't installed — uncommon today, but happens on some minimal Linux setups.

# Ubuntu / Debian
sudo apt-get install curl

# Alpine
apk add curl

After installing curl, run the installer command again.

Situation 2 · claude: command not found

Installed, but the shell can't find the executable. It's a PATH registration issue.

# Reload PATH in the current shell
source ~/.bashrc          # bash
source ~/.zshrc           # zsh

If that doesn't fix it, close the terminal completely and reopen it. New PATH entries only take effect in a fresh shell.

💡 One time, this happened. During a class session, a student ran claude and got "command not found" — even though the install had definitely completed. I walked through three steps: which claude to check the path, node -v to verify the Node environment was correct (only if you chose npm install. The native installer doesn't need Node.), and then the last line of ~/.zshrc. The culprit was nvm switching to a different Node version that had dropped the PATH entry. Found and fixed in five minutes. That sequence is now my standard first check after any install issue.

Situation 3 · "Git not found" on Windows

Local sessions on Windows depend on Git. Install Git for Windows and try again.

Once Installation Is Done

All that's left is to pick a folder and go in.

# Navigate to your working folder, then run
cd ~/Desktop/my-project
claude

It doesn't have to be a code project. Documents, research, work files — any folder can be a starting point. Claude Code scans the folder once and waits for your next instruction.

If it just sits there silently when you first open it, that's correct. That's the input prompt. Type your first instruction there.

A Few More Things Worth Knowing Right Away

A Good First Instruction

If you're not sure what to type first, try this exactly:

Take a look at this folder and summarize what files are here.

An empty folder is fine too. Claude will say "this folder is empty — what would you like to start with?" and you can say "create a sample meeting notes file for me."

Making Mistakes in Your First Session Is Fine

Before Claude modifies a file, it shows you what it's about to change and asks for confirmation. You'll see "is it okay to do this?" — and you can always say "n" to skip. This confirmation step lets you watch what's happening while you're still learning the flow.

If something goes wrong, press Esc twice to revert, or say "undo what you just did" and Claude will reverse it.

Update Methods by Install Path

The update command depends on how you installed. Keep this somewhere handy to avoid hunting for it later.

Start a CLAUDE.md Right Now

Setting up a CLAUDE.md right after install is a good habit. Just ask Claude: "record my project rules and preferences in CLAUDE.md." It doesn't need much content to start — even a single line like "always reply in English" is enough. You'll fill it in as you go.

CLAUDE.md is read automatically at the start of every session. It's the core memo that keeps you from repeating the same explanations over and over.

If It Can't Connect: Network Troubleshooting Order

On corporate networks, VPNs, or behind firewalls, Claude Code may not be able to reach Anthropic's servers. Here's the order to check:

1. curl -I https://api.anthropic.com — if you get a response, server connectivity is OK
2. Turn off VPN and retry
3. If blocked by firewall policy, ask IT to allow api.anthropic.com:443
4. On a proxy setup, set the HTTPS_PROXY environment variable before running

Most cases resolve by disabling VPN or adding a proxy setting. In a corporate environment, a quick check with IT may be needed.

Before You Leave This Chapter

• Ran claude --version and saw a version number
• Ran claude doctor and reviewed the environment status
• Completed the browser login flow when launching claude for the first time
• Know which install method you used (affects which update command to run)

The next chapter (05 Beginner Workflow) walks through what to actually type in the terminal that just opened — six beats for your first session.

When You First Open the Terminal: A Workflow for People Who Don't Know Where to Start

Have you ever stared blankly at the terminal in your first session, not sure what to type? I have. The cursor blinked and I didn't know where to begin. Shortening that moment is what this chapter is about.

Six beats at a glance. Follow them exactly the first time, then bend the rhythm to your own pace as you get comfortable.

Your First Session: Six Beats

Follow these steps the first time through. Each beat is short.

① Go to your working folder

# Example: go to the my-project folder on your Desktop
cd ~/Desktop/my-project

Claude Code reads and writes files based on the current folder. Which folder you open it in determines your work scope for that session. If the folder doesn't exist yet, mkdir it and cd in.

Any folder is fine to start with. An empty folder is fine. You can even say to Claude "I'm not sure what to do in this folder" — you can figure it out together.

② Run Claude Code

claude

Type claude and press Enter. When the interactive mode appears, you're ready. The first time may briefly show a setup screen — themes, auto-update settings. The defaults are fine.

③ Ask Claude to scan the project

When entering a folder for the first time, having Claude scan the structure first cuts your setup time in half. Creating a CLAUDE.md at this stage means you won't have to repeat the same explanations in future sessions.

> Scan the whole project and create a CLAUDE.md

If you're working on an existing project, this shorter version works too:

> Describe the structure of this codebase

💡 CLAUDE.md is a memo where you keep project rules, tech stack, and important notes. Commit it to git and your teammates — or your future self — can start from the same context.

💡 One time, this happened. At a workshop, a student asked "do I really need to scan the project first?" I said it wasn't required. They immediately typed "build me a login feature." The code Claude generated was completely mismatched with the existing file structure — everything had to be redone. Five minutes of project scanning saves an hour of rework. Now I always scan before anything else in a new folder.

④ Give your instruction

Describe what you want in natural language.

> Build a login feature
> Find the bug in this code
> Translate README.md to English

Start small. Asking for too much at once scatters the results. "Login screen first" produces much better results than "build login, signup, forgot-password, email verification, and social login all at once."

⑤ Review and give feedback

When Claude modifies a file, it shows you what changed. If something's off, reply right away.

> Good, but change the error messages to English
> Let's try a different approach on this part — [explanation]

The more specific your feedback, the better the next result. "Make it better" is weaker than "this function is slow on 1000 records, bring it under 1 second."

⑥ Wrap up the session

> /quit

Ctrl+D does the same. When the session ends, the conversation is gone — but files and CLAUDE.md stay on disk. You can pick it up next session.

Five Habits for Better Prompts

Habit 1: Narrow the scope

The same request produces very different results depending on how specific you are.

• "Fix the code" → "Fix the TypeError on line 42 of login.js"
• "Add a feature" → "Add a feature that sends a password-reset link via email"
• "Make it better" → "This function takes 3 seconds on 1000 records — get it under 1 second"
• "Write tests" → "Unit tests for the login function in auth.js. Include success, failure, and invalid email cases"

The key is getting "what, where, and how" into the same sentence.

Habit 2: One thing per turn

Ask for multiple things at once and Claude loses priority, just like a person would.

# Results get scattered
> Build login, add signup, add forgot-password,
  add email verification, and add social login

# Results are clean
> Build just the email + password login feature first
(After confirming it's done)
> Now add the signup feature next

One at a time, then the next one. This counterintuitively speeds up the whole process — one big request leads to far more rework.

Habit 3: Specify the output format upfront

The same question gets different answers depending on the format you ask for.

> Explain this code           → text explanation
> Save this code to a file    → file creation
> Improve and overwrite this  → direct file modification
> List bugs as a table        → table format

Specifying the output format upfront reduces post-processing.

Habit 4: Use @ to reference files directly

Add a file path after @ and Claude reads that file immediately.

> @meeting-notes.txt extract only the action items
> @contract.pdf summarize the key clauses
> @prices.csv analyze and give me 3 insights
> @src/auth/login.js find bugs in this file

You can also reference entire folders:

> @docs/ read all files in this folder and build a table of contents
> @reports/2026/ compare monthly reports and analyze trends

💡 Type @ in the chat to get autocomplete. Korean filenames work fine.

Habit 5: When stuck, question the premise

When you're not getting the results you expected, don't repeat the same prompt. Instead, try: "Let's take another look at the assumptions here." The real cause often surfaces there.

You can also say "I don't understand why this isn't working — let's think through it from the beginning together." Claude will revisit the conversation and look for where the premise went wrong.

Real Scenarios by Domain

Documents and Business

> @meeting-notes-260225.txt
  Summarize today's meeting and list action items by owner in a table

> @report-draft.docx
  Review the logical flow. Flag anywhere that needs supporting data.

> There's a file at ~/Downloads/meeting-260225.mp3
  Convert it to text and summarize it

Claude Code installs and runs the STT tools itself. You don't need to know any Python libraries in advance.

Data and Analysis

> @apt-prices-2026Q1.csv
  Show average prices and year-over-year change for Seoul's 25 districts.
  Highlight the top 5 with the biggest increases.

> @competitor-a.html @competitor-b.html @competitor-c.html
  Compare the strengths and weaknesses of these three landing pages.
  Include design tone.

Development

> Build a user profile page.
  - Display nickname, email, and join date
  - Profile picture upload
  - Nickname editing

> npm test throws this error. Fix it.
  TypeError: Cannot read property 'id' of undefined
  at UserService.getUser (src/services/user.js:45)

Plan Mode: Safety Belt Before a Big Change

Plan Mode is a mode where Claude only plans — no files are touched. You can see the full picture before committing to a major change.

How to enable it

Shift+Tab twice    or    > /plan

When Plan Mode pays off

• When touching multiple files at the same time
• For hard-to-reverse operations like database migrations
• Before modifying a codebase you've never seen before
• For architectural changes

In Plan Mode, Claude explains "what will change and how" before doing anything. If the plan looks good, switch to normal mode and execute. If not, redirect at the planning stage. Far fewer mistakes this way.

Four Dangers in Your First Sessions

Don't paste sensitive information into the chat

# Never do this
> My AWS access key is AKIAXXXXXXXX and...
> My DB password is mypassword123 and...
> My SSH key is -----BEGIN RSA...

Keep API keys, passwords, and private credentials in environment variables or .env files. Don't type them into the chat directly. Information entered in a chat session stays in the conversation history.

Don't blindly approve permission requests

When Claude asks for sudo or system file modification: make it a habit to ask why first.

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

--dangerously-skip-permissions is only for isolated environments

This flag skips all permission checks. Don't use it outside containers or other isolated environments.

Always commit before big changes

The small habit of committing before refactoring or migrations is insurance that saves days of work. You can ask Claude: "commit the current state for me, message: [description]."

Session Management: Small Techniques That Make a Difference

Name long sessions

> /rename housing-price-analysis

Resume later:

claude --resume housing-price-analysis

Naming sessions keeps you from losing track of context when running multiple projects in parallel.

Compress when the session gets long

If responses slow down or Claude starts ignoring rules you agreed on, the context is getting full.

> /compact

Adding a specific instruction helps: "compact around decisions, changed files, and remaining tasks."

Clear before switching to unrelated work

> /clear

When starting a completely different topic, empty the context. It prevents residue from the previous task leaking into the new one.

Save reusable prompts as files

If you repeat the same kind of task, save the prompt to a file.

Store this in prompts/weekly-report.md:

Read this week's meeting notes in the meetings/ folder
and compile decisions, action items by owner, and next week's risks into weekly-report.md.
Always put the conclusion first, with details in collapsed sections.

Then every week: @prompts/weekly-report.md — run this. No need to retype the complex instructions. This is also the seed for a proper Skill.

Multi-Session: Running Multiple Tasks at Once

Claude Code defaults to one session per terminal, but you can open multiple terminal windows and run separate sessions simultaneously. Here's how I typically set it up:

• Terminal 1: code development session
• Terminal 2: document organization session
• Terminal 3: data analysis session

Each session has an independent context. A code change in session 1 doesn't affect the document session in session 2. But they share the filesystem. If both sessions try to modify the same file simultaneously, you'll get conflicts — keep an eye on that.

For more systematic parallel work, Git Worktrees let you run multiple Claude sessions on the same repository without conflicts. The worktree section covers this in detail later.

Handling Difficult Situations

When Claude keeps repeating the same mistake

Sometimes Claude makes the same mistake two or three times. In that case, resetting the context is usually more effective than tweaking the prompt.

> Stop. Let's pause the current work.
  Think from scratch.
  What I actually need is [clear description]. Does that direction make sense?

Or use /clear to fully reset and try a fresh approach.

When responses are too long

Asking for detailed explanations can generate overwhelming length. Constraining the output format helps.

> Summarize in 3 lines, just the key points
> Only tell me the executable commands, minimize explanations
> Conclusion first, I'll ask for reasons when I need them

Short, action-focused responses make the review-and-iterate cycle faster.

Choosing the Right Model

Claude Code lets you switch models depending on the task. Pro defaults to Sonnet, Max defaults to Opus 4.7. Switching between them is how you optimize both cost and quality.

> /model sonnet   # Fast and light tasks
> /model opus     # Complex design or reasoning
> /model opus[1m] # Handling long documents or full codebases

My typical usage:

• Sonnet: file organization, translation, small edits, document drafts
• Opus: architecture design, complex debugging, analysis requiring long context
• Opus 1M: full codebase reviews, processing dozens of files at once

The 1M context model consumes more usage. Reserve it for tasks that truly need it — Sonnet handles most everyday work fine.

The Shape of a Good Workflow

A workflow that runs well converges on this pattern:

1. Go to the folder and set context — tell Claude where you're working and what you're building.
2. Break it into small pieces — one at a time, confirm it's done, then move to the next.
3. Check the output yourself — look at and run what Claude produced.
4. Give specific feedback — not "make it better" but "change this part, for this reason, to do this."
5. Check in periodically — use /compact, commits, and TODO.md to stay oriented.

At first this flow can feel unfamiliar and cumbersome. But after a week of working this pattern, your hands will remember it. From that point on, you follow it without thinking consciously about the steps anymore.

Prompt Patterns: Ready-to-Use Sentences by Situation

Starting a session

Create a CLAUDE.md for this project that someone seeing it for the first time can understand.
Include tech stack, folder structure, and three core rules.

Analyzing a file

@[filename] Explain this file's main role and anything that could be improved.
Give me 3 actionable improvement suggestions in priority order.

Requesting a bug fix

This error occurred. Explain the cause and tell me how to fix it.
[paste error message]

Before fixing, tell me which files you'll need to touch.

Adding a new feature

I want to add [feature description].
First draft a plan in Plan Mode.
I'll say when to proceed after reviewing the plan.

Requesting a code review

@[filename] Review this file.
- Potential bugs
- Performance issues
- Security vulnerabilities
- Code quality improvements

Organize each item in a table with severity (high/medium/low).

Organizing documents

@[folder] Read the documents in this folder
and create index.md with a table of contents, 3-line summary per doc, and how they relate.

Analyzing data

@[data file] Analyze this data.
1. Overview (row count, columns, basic statistics)
2. Outlier detection
3. Three major patterns
4. Areas that need further investigation

Save the results to analysis-[date].md.

Bad Habits That Wreck a Workflow

A few traps that show up in every workshop. Knowing them up front lets you sidestep them from day one.

Trap ① Asking for too much in a single turn

The most common mistake. Throwing in something like "refactor the entire project" makes the result unpredictable because the scope is too wide.

Not good:

Upgrade this whole project to the latest versions,
improve code quality, add tests,
and update the docs.

Better:

In package.json, which three dependencies are the most outdated?

→ After checking: "Tell me what to watch out for when upgrading these three." → After checking: upgrade them one at a time.

Trap ② Pressing on without feedback

While Claude is working, repeatedly saying "yeah, keep going" means small drifts in direction add up unseen, and you end up rolling back a lot of work later. Checking in midway is actually the faster path.

During long sessions, a useful habit is to ask "summarize what you've done so far" every 10–15 minutes.

Trap ③ Putting off Git commits

"I'll commit when it's done" is a trap. Committing before starting a big task, and whenever a meaningful change lands, is the safer move.

Just tell Claude "commit the current state with the message [description]." Claude will write the commit message for you too.

Trap ④ Vague "make it better" feedback

"Make this better" hands Claude far too wide a permission. Claude will interpret "better" in its own way and may take the change somewhere unexpected.

Instead, write something like:

Improve the response speed of this function. It currently processes 1000 records in 3 seconds — bring it under 1 second.
Change the algorithm, but don't add external API dependencies.

What you want to improve, what the measurement is, and what the constraints are — when these are spelled out, the result is much better.

Common Slash Commands

Slash commands you'll use regularly. No need to memorize them all — come back here when you need one.

Type /help for the full command list. If you're not sure what a command does, ask Claude: > what is /[command] used for?

A note on /compact vs /clear: /compact summarizes the conversation but keeps it — good for staying in the same work thread but trimming the weight. /clear wipes the slate — use it when switching to a completely unrelated task. The distinction matters for how much Claude "remembers" about what you've been doing.

One Line Summary

Narrow your scope → one thing at a time → check the result yourself → give short feedback → repeat.

Before You Leave This Chapter

• Navigated to a working folder and ran claude
• Typed a first instruction and received a response
• Used /compact, /clear, and /quit at least once each
• Understand what CLAUDE.md is for
• Remember the principle: "one thing at a time"

The next chapter (06 Plugins) looks at plugins that make this workflow more convenient. Installing one line opens up new capabilities — you'll see what that feels like firsthand.

The Moment Plugins Changed Things: Features That Open With One Install

Claude Code is powerful on its own. But the day I installed the GitHub plugin in a workshop and said "summarize the five open issues in this repo," Claude called the GitHub API and brought back the results directly. Before that, I had to copy-paste issue content into the chat manually. That difference was bigger than I expected.

What Are Plugins? The Smartphone App Analogy

A phone does calls, messages, and camera out of the box. Install apps and new categories open up: budgeting, photo editing, weather alerts. Plugins work the same way — capability bundles that sit on top of Claude Code.

Each bundle usually contains one or two of four things:

• Skills — custom commands in the form /pluginname:command. You invoke them explicitly.
• Agents — AI with a defined role. Think reviewer, researcher — a named collaborator.
• Hooks — event handlers that react automatically to file saves, command runs, etc. No explicit call needed.
• MCP Servers — bridges to services like GitHub, Figma, and Notion. Required for Claude to directly read and write external service data.

You don't need to understand all four before you start. Install something, use it, and the categories become clear naturally.

Where to Find Them: The Official Marketplace First

The claude-plugins-official marketplace, run by Anthropic, is available from the moment you start Claude Code — no separate registration needed. Type /plugin inside Claude Code and the Discover tab opens. Browse the catalog and install whatever looks useful.

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

Top Plugins by Category

• External integrations — notion · slack · github: connect Notion, Slack, and GitHub directly to Claude. Read and write data without leaving the terminal.
• Output style — explanatory-output-style: reshape responses into summaries, checklists, step-by-step formats.
• Dev workflow — commit-commands: reads your staged changes and suggests appropriate commit messages.

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

Installing: Three Steps and Done

Step 1: Browse the marketplace and install

One line inside Claude Code:

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

For GitHub:

/plugin install github@claude-plugins-official

Or type /plugin and browse the Discover tab — categories make it easy to navigate.

ℹ️ Plugins install one at a time. Repeat for multiple plugins.

Step 2: Confirm the install

/plugin list

Or open the Installed tab in /plugin to see what's active and which versions.

Step 3: Update when new versions arrive

/plugin update

⚠️ After installing or updating, restart Claude Code once. New commands, hooks, and MCP connections need to be loaded into the running context.

The First Use Matters More Than the Install

Plugins earn trust in the first use, not the install. Don't give them important work right away. Start with read-only requests.

• GitHub → "Summarize issues closed in the last week in this repo"
• Notion → "Read the most recent meeting page and list only the decisions"
• Slack → "Compress today's main discussion in #general to five lines"
• commit-commands → "Suggest a commit message for the currently staged changes"

Only after read-only requests work smoothly should you expand to write and modify permissions — one step at a time.

💡 One time, this happened. Right after installing the GitHub plugin, I told Claude "close this issue and merge the PR." Claude ran it. A PR that hadn't been reviewed yet got merged. Since then, I always test a new plugin with read-only requests first. Write permissions come after I've confirmed the behavior is trustworthy.

Everyday Plugin Management

Five commands you'll use regularly:

• /plugin: open the plugin manager (Discover · Installed · Marketplaces · Errors tabs)
• /plugin list: see all installed plugins at once
• /plugin disable plugin-name: temporarily turn off (without uninstalling)
• /plugin enable plugin-name: turn back on
• /plugin uninstall plugin-name: fully remove

As plugins accumulate, checking the Errors tab periodically is good practice. MCP connection failures and misconfigured settings show up there.

Key Plugins, Looked at More Closely

GitHub Plugin

Install: /plugin install github@claude-plugins-official

With this plugin, Claude can access your repositories directly. You can say "check this PR and merge it if there are no issues" — without manually copy-pasting content back and forth.

Common request patterns:

Gather issues opened in the past 7 days and sort them by priority.
Prioritize by: label, comment count, author permissions.

Compare main branch to feature/login and summarize what changed
in language a non-developer can understand.

Collect issues closed this sprint and draft release notes.
Translate technical content into user-facing language.

💡 One caution with the GitHub plugin: start with read-only access. Write permissions (creating issues, merging PRs, pushing code) should come after you've built enough confidence. Fine-tune in /permissions.

Notion Plugin

Install: /plugin install notion@claude-plugins-official

If you use Notion for team docs or project management, this plugin turns Claude into a Notion editor. Not just reading — it can create new pages, update content, and add entries to databases.

Most useful scenario: weekly summary automation.

Read all Notion pages updated this week related to [project name]
and create a weekly update summary as a new page.
Post it to the team shared DB.

Meeting notes automation:

Write up today's meeting and add it as a new page in Notion's [meeting DB].
Match the format of existing pages.

Slack Plugin

Install: /plugin install slack@claude-plugins-official

If your team uses Slack, this plugin lets Claude read channel content or send messages. My most common use: channel monitoring.

Pull decisions and action items from #dev today.
Flag anything that involves me specifically.

Write a team standup message.
Yesterday: completed items from @TODO.md
Today: remaining items from @TODO.md
Blockers: none

commit-commands Plugin

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

Simple but you'll use it daily. Reads staged changes and suggests commit messages in Conventional Commits format (feat:, fix:, docs:, etc.).

/commit-commands:suggest

Or ask directly:

Look at the staged changes and suggest 3 commit messages.
Use Conventional Commits format.

For anyone who finds writing commit messages tedious, this alone justifies installing a plugin.

Plugin Combinations: Real Workflows

Using plugins individually is good. Combining them creates stronger automation. Here's my actual weekly wrap-up workflow:

1. Fetch closed issues and merged PRs from GitHub this week
2. Read this week's meeting notes from Notion
3. Extract key decisions from Slack #dev
4. Combine the three into a weekly report
5. Add to Notion weekly-report DB and share link in Slack #general

Handled in one conversation:

Combine GitHub, Notion, and Slack data to create this week's report.
GitHub: closed issues and merged PRs this week.
Notion: the [2026-W19 meeting notes] page.
Slack #dev: today's main discussion.
Compile into a unified report.
When done, add to Notion [weekly-report DB] and share the link in Slack #general.

Before this, the process took about 40 minutes. Now it's one command plus 5 minutes of review.

Plugins That Work Without External Services

Some plugins run locally with no MCP server or external authentication.

explanatory-output-style

Changes response style. After installing:

Explain this code. [output style: beginner-friendly step-by-step]

Or set it globally:

From now on, always format explanations as step-by-step for beginners.

Especially useful for documentation work or building teaching materials.

chrome-devtools (or playwright)

Lets Claude directly inspect a locally running web app.

Open localhost:3000 and check for console errors.
If any, tell me which file and line they come from.

A good starting point for test automation.

Permission Patterns When Using Plugins

Grant permissions in stages

1. Right after install: read-only only. Claude can read and analyze data.
2. After one week: add create permissions. Allow creating new issues, pages, messages.
3. After building confidence: add edit and delete. Allow modifying existing items.

Staging it this way means mistakes get caught before they cause big impact.

Set Deny rules first

It's safer to define what's forbidden before defining what's allowed.

/permissions

Set "never do this" actions to Deny. For example:

• Deny modifying production environment data
• Deny sending messages outside the organization
• Deny access to folders with sensitive information

These rules apply regardless of what the plugin tries to do.

I keep three Deny rules set at all times:

• Direct push to main or production branch — denied
• Sending email or messages outside the organization — denied
• Delete or modify on the production DB — denied

Just these three prevent most serious mistakes.

Before and After Plugins

Before: GitHub issue analysis without plugins

Workflow:
1. Open GitHub in browser
2. Click into each issue and read it
3. Copy content into Claude chat
4. Get analysis
5. Repeat for next issue

Time: 5–10 minutes per issue — 10 issues = 50–100 minutes

After: GitHub plugin for issue analysis

> Analyze all issues opened this week by priority.

Time: 30 seconds to 2 minutes

The difference is the time spent reading and copy-pasting. Plugins eliminate those steps.

Plugin Troubleshooting

When a plugin doesn't respond

Symptom: installed but no reaction, or "can't connect to service."

Steps to check:

1. /plugin list — confirm it shows Enabled
2. /plugin → Errors tab — check error messages
3. Check internet connection (especially with VPN or firewall)
4. Restart the plugin: /plugin disable [name] → /plugin enable [name]
5. If that fails: uninstall and reinstall

After reinstalling, restart Claude Code once. New settings need a fresh start to fully apply. Odd behavior without a restart does happen occasionally.

When an MCP server keeps disconnecting

Cause: usually expired auth token, service downtime, or network timeout.

Fix:

• GitHub: /github:reauth
• Notion: /notion:reconnect
• General: restarting Claude Code is the fastest fix

When a plugin does something unexpected

Most common: it creates or modifies items you didn't intend because write permissions were too broad.

Response:

1. Stop immediately: Ctrl+C
2. Check what changed: look at recently created/modified items
3. Review permissions: tighten the allow scope in /permissions

Using Plugins With a Team

Shared plugin setup

Recording shared plugin settings in CLAUDE.md cuts onboarding time for new team members.

## Team Plugin Setup

Required plugins (install right after joining):
- `/plugin install github@claude-plugins-official`
- `/plugin install notion@claude-plugins-official`
- `/plugin install commit-commands@claude-plugins-official`

GitHub plugin permissions:
- Repos: allow access only to [team repo name]
- Permission level: read + PR creation, issue creation
- Merge, delete: always confirm manually

Shared prompt management

Include frequently used team prompts in the repository for consistent usage across the team.

prompts/
  weekly-report.md      # Weekly report generation
  issue-triage.md       # Issue priority analysis
  pr-review.md          # PR review requests
  release-notes.md      # Release notes generation

Save prompt templates in each file, then call with @prompts/weekly-report.md — run this.

Plugins and Security

Security is the most important consideration when using plugins.

API key management

Plugins store auth API keys securely — macOS system keychain, for example. Never write them to files manually or put them in CLAUDE.md.

If anything asks you to enter an API key, only do it through Claude Code's official settings flow. Any other request should be treated with suspicion.

Data processing scope

Data processed through plugins may be sent to Anthropic servers via the Claude API. Things to verify:

• If connecting confidential company data through plugins to external services, check IT policy
• Consider excluding sensitive channels and repos from plugin access scope
• Enterprise plans have different contract terms for data processing

A Preview of Building Your Own Skills

Using the official marketplace isn't the only option. You can build Skills for tasks you repeat frequently.

Skills turn repeated prompt patterns into slash commands. If you build the GitHub issue analysis pattern into /triage:

/triage

One line runs it. A complex prompt executes internally but the usage point stays simple.

After 2–3 weeks of using plugins, you'll hit a moment where typing the same prompt again feels pointless. That's when you're ready to build a Skill. You'll know the moment naturally.

At first, just use what's there. As you get comfortable, repeating patterns become visible — and that's when you have something worth automating. Plugin use → pattern discovery → Skill creation: this progression flows on its own.

Skills are covered in detail in 17. Skills & Building Plugins.

Recommended Order for Getting Started

1. Learn the base workflow first. Spend 2–3 weeks with just Claude Code, no plugins. What you're missing becomes obvious on its own.
2. Add one at a time. Installing many at once makes it hard to tell which plugin does what.
3. Always test read-only first. Give write permissions only after verifying behavior.
4. Disable what you're not using. MCP servers maintain connections, so only activate them when needed. Unused MCP servers can slow Claude Code's startup and affect response speed. Check /plugin list periodically and disable what you're not actively using.

A Quick Recap

That covers the plugin fundamentals. Below we move into deeper material — real-world cases, security patterns, and team operations.

Real Problems Plugins Solved

Problem 1: Daily manual GitHub issue review was burning time

Before: every morning I opened GitHub, read through new issues, judged priority, assigned owners — 30 minutes gone. After installing the GitHub plugin, this is what I run each morning:

Fetch issues opened since yesterday and:
1. Classify each as bug or feature request
2. Assign priority (criteria: user impact, reproducibility, duplicate check)
3. Suggest which team member should handle each
Format the output as a table.

That work now takes 5 minutes. The rest of that time goes to actually fixing things.

Problem 2: Same meeting note format every time was tedious

Combined the Notion plugin with a meeting transcript flow:

Add this meeting to Notion [meeting DB] in this format:
- Title: [date] [topic]
- Attendees: [list]
- Decisions: (numbered list)
- Action items: (with owner tags)
- Things to check before next meeting: (checklist)
Match the format of existing pages exactly.

Meeting ends, paste the transcript, run the command. Two minutes.

Problem 3: Too many PR review comments made it hard to see the big picture

Using the GitHub plugin to analyze PR comments:

Read all comments on [PR number] and organize them into:
1. Core issues (points multiple reviewers raised in common)
2. Must-fix vs still-being-discussed
3. Quick fixes vs changes requiring design decisions
Summarize by category.

Even 20 reviews become clear in 3 minutes.

Connecting MCP Servers Directly (Without the Marketplace)

When the marketplace doesn't have the service you need, or you need to connect an internal system, you can configure MCP servers directly.

MCP (Model Context Protocol) is the standard protocol for connecting Claude to external services. Add server info to a config file.

In ~/.claude/settings.json:

{
  "mcpServers": {
    "my-internal-tool": {
      "command": "node",
      "args": ["/path/to/mcp-server.js"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

Many pre-built MCP servers already exist. GitHub, Slack, Notion, Jira, Figma, PostgreSQL, Google Drive — official and community MCP servers are available. Browse modelcontextprotocol/servers and the Anthropic Directory for a list.

import { Server } from '@modelcontextprotocol/sdk/server/index.js';

const server = new Server({ name: 'my-tool', version: '1.0.0' });

server.setRequestHandler('tools/list', async () => ({
  tools: [{
    name: 'get-data',
    description: 'Query internal DB',
    inputSchema: { type: 'object', properties: { query: { type: 'string' } } }
  }]
}));

server.setRequestHandler('tools/call', async (request) => {
  if (request.params.name === 'get-data') {
    const result = await internalDB.query(request.params.arguments.query);
    return { content: [{ type: 'text', text: JSON.stringify(result) }] };
  }
});

Plugins Worth Knowing That Have Nothing to Do With External Services

Not every plugin needs an external account or MCP server to be useful. Some work entirely in your local environment.

Why that matters

Local-only plugins have zero auth setup, no risk of API key leaks, and no latency from external calls. They're the fastest and safest category to try first.

The explanatory-output-style plugin is a good first install. You set it once and every response that touches explanation automatically gets formatted in a way that's readable to someone seeing the topic for the first time. If you ever explain Claude Code to a colleague using your terminal, or build tutorial content, this plugin removes the back-and-forth of "make this simpler."

The Chrome DevTools plugin is worth having if you build web apps. Instead of switching to a browser, opening DevTools, scrolling through the console, and copying errors back to Claude — you just say "check localhost:3000 for errors" and Claude does the browser inspection itself. The round trip disappears.

The Long-Term View on Plugins

Plugins aren't just about convenience. They gradually shift the shape of your work.

When I first started using Claude Code without plugins, I was the bridge between Claude and every external tool. I read GitHub, told Claude what was there. I checked Notion, summarized it for Claude. I fetched Slack threads, pasted them in.

After plugins, Claude is the bridge. I just describe the outcome.

The mental model shift is real: instead of "how do I get this data to Claude," the question becomes "what outcome do I want." The toolwork moves off your plate.

That shift doesn't happen on day one. It happens over weeks, as plugins become reliable, as you stop checking whether they did the right thing every single time, as muscle memory builds around a new way of working. The first plugin install is just the entry point.

What's Next: A Tour of Core Concepts

• Ran /plugin install github@claude-plugins-official, or at least typed /plugin to look at the Discover tab
• Have a rough sense of the difference between Skills, Agents, Hooks, and MCP Servers
• Remember the principle: "test read-only first"
• Ran /plugin list to check what's installed

The next chapter (07 Core Concepts) covers five concepts that explain how Claude Code works inside — Context, Tools, Permissions, Memory, and Session — one page each.

How Claude Code Works: The Concepts That Change How You Use It

Looking inside a tool's workings changes how you use it. When I first understood these concepts, a series of "so that's why" moments followed. It's not complicated — five diagrams.

Claude Code Is an Agent: Understanding the Flow at Once

Claude Code is not a chatbot. It's an Agent. Give it a task and it autonomously plans, reads files, makes changes, and checks results in a loop. This cycle is called the Agentic Loop.

One sentence from you
     ↓
① Understand the situation — read files, search code, check state
     ↓
② Act — modify files, run commands, search the web
     ↓
③ Verify — run tests, check for errors, revise
     ↓
Done (or back to ① and repeat)

Say "summarize the documents in reports/" and Claude checks the folder, reads the document content, drafts a summary, fills in anything missing — all in one breath without you directing each step.

This is how it differs from chat. Chat responds to each message in isolation. Claude Code runs steps autonomously until complete.

Five Core Concepts

① Context: Claude's Working Memory

Everything Claude currently holds in its head is context. Conversation history, files read, command results, CLAUDE.md instructions — all of it. This memory has a token limit, so when it fills up, older content gets trimmed automatically.

# Check context status
/context

# Compress by summarizing older content
/compact

# Focus-compress on a specific topic
/compact focus on API changes when compressing

💡 Write rules you reference often in CLAUDE.md. Claude follows them consistently without them consuming context every session.

Signs that context is full

When these symptoms appear, /compact or a new session helps:

• Breaks rules you agreed on a moment ago
• Keeps re-reading the same file but reaches different conclusions
• Responses get longer but actual edit speed slows down
• Retries approaches that already failed
• Asks you to "describe the current state again" more often

💡 One time, this happened. A workshop student was in a 3-hour session when "Claude started saying strange things." The context was full. Running /compact and saying "summarize around decisions, changed files, and remaining tasks" brought Claude back to normal. Context is memory with a capacity. Fill it up and performance drops.

Context management strategies

1. Periodic compression: run /compact every 30–60 minutes
2. Focused compression: specify "compress around this topic" when compressing
3. Session separation: use /clear to start fresh when the topic is completely different
4. Use CLAUDE.md: save rules you'd repeat every session to CLAUDE.md

② Tools: What Claude Can Actually Do

Claude Code doesn't just talk. It uses Tools to cause real actions. Five categories:

• File operations: read, edit, create new files, rename, delete
• Search: pattern matching, regex, codebase navigation, file search
• Execution: shell commands, server startup, testing, Git operations
• Web: search, look up official docs, find error messages
• Code analysis: detect type errors after edits, go-to-definition, find-references

Seeing these tools in action explains why Claude Code feels different from chat. Chat returns text. Claude Code creates files, runs commands, checks results, revises again.

Tool use happens with your permission. You decide which tools are used and to what extent. This leads directly to the next concept.

The range of available tools expands through plugins. The base tools handle most work, but installing the GitHub plugin adds "read and write GitHub repos." Installing the Notion plugin adds "read and write Notion pages." Plugins extend the toolset.

③ Permissions: Setting the Allowed Scope Yourself

Powerful tools need safety mechanisms. Claude Code lets you control which actions are allowed for each type of work.

Three rules:

• Allow: execute automatically without asking
• Ask: ask for approval each time
• Deny: never execute under any circumstances

# View and manage permission settings
/permissions

⚠️ Priority order: Deny > Ask > Allow. A Deny rule always overrides an Allow targeting the same path.

When starting out with Claude Code, the recommended setup is: file reading as Allow, file modification and shell commands as Ask. Expand the Allow scope as you get comfortable.

Permissions are managed at three levels:

• Global (~/.claude/settings.json): applies to all my projects
• Project (.claude/settings.json): applies to this project only
• Local (.claude/settings.local.json): this project, not committed to git

④ Memory: Long-Term Memory with CLAUDE.md

When a session ends, the conversation is gone. That's where CLAUDE.md comes in — an instruction file that's read automatically at the start of every session. A memo that persists.

Scope varies by location:

• ./CLAUDE.md: current project only (shareable with team)
• ~/.claude/CLAUDE.md: all my projects (global)
• ./CLAUDE.local.md: my project settings only (not committed to git)

What I recommend including when you first create a CLAUDE.md:

## Base rules
- Always reply in English
- Explain the change plan before modifying code
- Edit only one file at a time

## Project info
- Stack: Next.js 16, TypeScript, Tailwind CSS v4
- Deploy: Vercel
- Coding style: named exports, inline types

## Restrictions
- Do not directly modify package.json
- Do not push directly to main branch

Detailed writing guidance in chapter 08, where we go deep on the CLAUDE.md file itself.

⑤ Session: The Beginning and End of a Conversation

One complete run from open to close is a session.

• When a new session starts, the previous conversation disappears (CLAUDE.md stays)
• Files and settings created during a session remain on disk
• Name a session to resume it later in the same context

# Continue the most recent session
claude --continue

# Choose from previous sessions to resume
claude --resume

# Resume a named session
claude --resume project-a

# Try a different direction from the same point (fork)
claude --continue --fork-session

Small habits for managing sessions well:

• Use /rename to name long sessions
• Start each day with claude --continue to pick up where you left off
• Use /clear when switching to a completely different topic

Naming sessions well makes context switching easier when running multiple projects. "shopping-mall-redesign" and "api-refactor" as explicit names, then claude --resume shopping-mall-redesign when needed. People need notes to switch work contexts; Claude benefits from session names the same way.

The Pause-and-Confirm Pattern: Not a Bug

This is not a bug — it's a deliberate safety mechanism. A chance to double-check intent before modifying files or running commands. The value of this step grows with the irreversibility of the action (deletion, deployment, DB changes, etc.).

At first this confirmation feels like friction. But after three times of "wait, that's not what I meant" — you appreciate it. Especially mid-large-task when direction has drifted slightly, this check catches it.

Three Permission Modes: Cycle with Shift+Tab

One Shift+Tab cycles to the next mode.

• Default: confirms before every file modification and shell command. For beginners or important work.
• Auto-Accept: files modified automatically, shell commands still confirmed. After getting comfortable, for speed.
• Plan Mode: read and analyze only, no changes made. To see the full picture before a major change.

Same request, different modes

"Replace 'old phrase' with 'new phrase' across all documents in this folder"

Default     → Confirms before each file: is this modification approved
Auto-Accept → Files modified automatically, commands like git commit still confirmed
Plan        → Shows "which file, which line, what change" without making any changes

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

Default     → Confirms per file
Auto-Accept → Files automatic, only git commit-type commands confirmed
Plan        → Shows which files and lines will be deleted, then waits

Start with Default to develop a feel for what's being done. Move to Auto-Accept once you're comfortable.

Checkpoints: Undo Even If Something Goes Wrong

Right before modifying a file, Claude automatically saves a snapshot. Two ways to recover from a mistake:

• Press Esc twice in a row to revert to the previous state
• Or just say: "undo what you just did"

This feature lets you experiment boldly without "what if I mess up" anxiety. It's one of the core reasons experimentation speed is high. Without checkpoints, many people would use Claude Code more cautiously, in smaller increments.

That said, checkpoints don't replace Git commits. A checkpoint reverts "what just happened." Git protects "everything up to yesterday." Using both together is safest.

When These Concepts Show Up in Practice

Specific situations where each concept becomes tangible:

Context in Practice: When Claude Suddenly Misbehaves

Mid-long-session Claude breaking previously agreed rules or re-reading the same file repeatedly — context is full. Continuing without intervention causes drift.

Fix: run /compact and say "compress around decisions, remaining work, and changed files." Usually enough to get back on track.

Tools in Practice: Watching the Agentic Loop Run

The most surprising moment for first-time users. "Analyze everything in this folder" — and it opens every file, runs code, presents results. That reaction is common — it feels more like a coworker than a chatbot.

Yes. It uses tools. The Claude model doesn't read files itself — it calls a file-reading tool, then decides the next action based on the result. This tool-action cycle is the agentic loop.

Permissions in Practice: Before You Hit Y

When Claude asks for sudo access to change system settings — don't automatically say yes. Ask why.

> Explain why you need sudo. Tell me if there's a way to do this without it.

That one question prevents a fair number of unintended system changes.

Memory in Practice: Things Worth Writing Down

If you're saying "reply in English" every session, put it in CLAUDE.md. "Explain the plan before modifying code" too. Write it once and it applies to every session.

Starting with an empty CLAUDE.md is normal. Add things whenever you think "I keep having to say this." Over time it becomes your personal AI collaborator spec.

Session in Practice: Picking Up Yesterday's Thread

Yes. claude --continue resumes the most recent session, or claude --resume [name] for a named session. The conversation is gone when a session ends, but files and CLAUDE.md remain. Coming back the next day, the files tell you where things stand.

At the end of the workday, "summarize today's work, incomplete status, and what to continue tomorrow in TODO.md" makes context recovery the next morning much easier.

When to Come Back to These Concepts

No need to memorize everything now. But when these situations arise, revisit this chapter:

How the Concepts Connect

These five concepts don't exist independently — they connect into one flow in actual work, each supporting the others.

Claude receives a task (Session)
  → Checks the current context (Context)
  → Forms a plan and uses tools (Tools)
  → Only within permitted scope (Permissions)
  → Records what to remember next session in CLAUDE.md (Memory)

With this flow in mind, most of Claude's behavior during work becomes predictable. Less confusion about why it pauses. More ability to actively steer direction.

When Claude asks for permission to modify a file you'll now recognize it as the Permissions check step. When it slows down or starts losing context, you'll read it as "Context is getting full." The concepts become a language for the behavior.

These five concepts are reference points you'll return to throughout your time using Claude Code. You don't need to fully understand them right now. They get clearer with use.

Understanding them versus not — the gap grows over time. Knowing where to look when things break: that's the biggest value of this chapter.

Before You Leave This Chapter

• Can picture the four steps of the agentic loop (Read → Plan → Edit → Verify)
• Remember at least two of the five signs that context is full
• Have used at least one of /compact, /context, or /permissions in practice
• Understand the three CLAUDE.md locations (global, project, local)
• Can explain the difference between Default, Auto-Accept, and Plan Mode

The next chapter (chapter 08 on the CLAUDE.md file) goes deep on how to write and manage the long-term memory system. A direct extension of the Memory concept from this chapter.

08. CLAUDE.md — Ending the "Stranger Every Session" Problem

If it's been annoying that Claude forgets everything when a session ends, one file fixes that. Write it once properly, and you'll never have to introduce your project from scratch again.

Source: Memory & CLAUDE.md — Anthropic Docs

When I first saw this diagram, I stopped at "why do we need three levels?" After using it for a while, the reason became clear. Global preferences (language, code style) should follow you everywhere, project rules should stay in the project, and personal local settings shouldn't be visible to teammates. Without the hierarchy, you have no idea which rule wins.

"I Keep Repeating the Same Thing Every Session"

The moment students in my workshops connect with this most is when they realize how much time they spend re-explaining the project at the start of each session. "This project uses TypeScript," "commit messages should be in English," "we use pnpm" — repeated every single day. Three minutes of repetition daily adds up to over an hour a month.

CLAUDE.md breaks that loop. Claude Code reads it automatically at startup, so every session begins with Claude already knowing your context.

Here's what the difference looks like:

[Without CLAUDE.md]
"This project is built with Next.js, uses TypeScript.
 Two-space indentation, commit messages in English."
→ Explained again every session

[With CLAUDE.md]
↑ That info is baked into one file
→ Work starts with context already loaded

💡 Here's something that actually happened. One of my students was copy-pasting "This project is React + TypeScript, uses Tailwind, pnpm, commit messages in English" at the start of every single session. They thought that was just how it worked. After they made a CLAUDE.md, their first reaction was "I wish I'd known about this sooner." The rule that made the biggest difference for them was "before any modification, tell me what you're about to do." They'd been anxious about code changing unexpectedly, and that one line removed the anxiety.

Placement Determines Scope

Different locations mean different reach. Closer to the current folder means higher priority.

• ./CLAUDE.md: Current project only (shareable via Git). ./.claude/CLAUDE.md is also officially supported.
• ./CLAUDE.local.md: Your personal project settings. Running /init with the personal option adds it to .gitignore automatically.
• ~/.claude/CLAUDE.md: Applies to all your projects globally
• Managed policy (Enterprise): A CLAUDE.md deployed by your organization's IT (/Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux/WSL, C:\Program Files\ClaudeCode\CLAUDE.md on Windows). Users cannot opt out.

The most common starting point is ./CLAUDE.md in the project root. Two ways to create it:

# Create an empty file and write it yourself
touch CLAUDE.md

# Let Claude generate a draft
/init

/init scans your current folder and drafts the file automatically. Best cure for blank-page paralysis.

"What Should I Actually Write?" — What Tripped Me Up at First

There's no fixed format. It's free-form Markdown. Fill in these five categories and you'll see immediate results.

💡 "Project" here doesn't mean only code projects. Research folders, content folders, workflow automation folders — all of them work the same way.

Category ① Work Overview

One or two lines about what this folder is for. No need for detail — just enough for Claude to answer "what kind of project is this?"

## Work Overview
This folder is a competitor market research project.
Results go into the reports/ folder as Markdown files.

Category ② Tools & Environment

What tools, resources, and storage methods you use. Even one line is dramatically better than nothing.

## Work Environment
- Tools: Notion (planning), Google Docs (drafts), Canva (design)
- Storage: docs/ folder in Markdown format
- Language: Korean primary, English sources get translated summaries

Category ③ Working Rules

Guardrails for style, naming, sourcing. Vague instructions like "be friendly" don't work well. "No statistics without a source" is verifiable and works much better.

## Working Rules
- Tone: warm and clear (no exaggerated language)
- File names: YYYY-MM-DD_topic.md format
- No statistics or figures without a cited source
- Match the language of the prompt unless I specify otherwise

Category ④ Prohibited Actions

Explicitly listing what not to do prevents accidents. Whenever you experience a mistake, add it here immediately.

## Never Do This
- Cite statistics without a source
- State unverified information as fact
- Expose customer or partner names in documents
- Overwrite previous file versions (always include date in filename)

Category ⑤ Formats for Recurring Outputs

Bake in the skeleton of outputs you produce repeatedly. If Claude already knows what a meeting summary should look like when you say "write a meeting summary," everything goes smoother.

## Recurring Task Formats
- Research report: "Summary → 5 key insights → Source list"
- Meeting notes: "Decisions → Action items (owner + deadline) → Open issues"
- Document review: Lead with a summary, mark anything needing changes with a reason

Ready-to-Use Templates by Domain: Just Fill in the Blanks

Template A: Real Estate & Market Analysis Workspace

# Market Analysis Project Rules (CLAUDE.md)

## Project Purpose
- Goal: [Region, time period, and target in one line]
- Deliverables: report.md (summary), data.md (raw data), brief.md (1-page executive brief)

## Data & Folder Rules
- Raw sources go in sources/ (filename: YYYY-MM-DD_source_title.md)
- Processed data goes in data/ as csv/xlsx
- Personal notes and hypotheses go in notes/ (keep separate from source material)

## Source Reliability
- Every figure must include its source and measurement criteria
- Source tier: A (government/primary) / B (industry reports/secondary) / C (blogs/opinion)
- Estimates get labeled "estimated" with the calculation method

## Output Format
- Korean, keep sentences short
- Default structure: ① 5-line summary ② 5 key insights ③ 3 counter-scenarios/risks ④ 3 next actions

Template B: Content Creation Workspace

# Content Creation Rules (CLAUDE.md)

## Brand Tone
- Warm but no hype ("perfect," "revolutionary," "guaranteed" are banned)
- Audience: [Target reader in one line], jargon gets a short parenthetical explanation

## Format by Channel
- Blog: 3 title candidates → body (4–6 subheadings) → checklist → 1 CTA
- Instagram: 7–9 card slides (one sentence per card), final card has summary + link
- Newsletter: 3-line summary → 600–900 word body → preview of next topic

## Restrictions
- No competitor names (use "Company A" / "Company B" if needed)
- Numbers without sources get labeled "(example)"

## File Output
- Drafts: drafts/YYYY-MM-DD_topic_channel.md
- Final: final/ folder, top metadata includes version, reviewer, publish date

Template C: Business Operations Workspace

# Operations Rules (CLAUDE.md)

## Company & Product Context
- Product: [name] / Customers: [target] / Core value: [one line]
- Accumulate term definitions below: [term: definition]

## Communication Style
- Email/messages: formal, 3 paragraphs (summary → detail → next steps)
- Handling complaints: "1 empathy sentence → 2 clarifying questions → 2 resolution options"

## Document Templates
- Meeting notes: Purpose / Decisions / Action items (owner + deadline) / Issues
- Proposals: Problem → Solution → Timeline/scope → Cost → Risk

## Security & Sensitive Data
- Mask personal/payment info (e.g., 010-****-1234)
- Before sharing externally: print "confidentiality check + client name review list" first

# Project Instructions

## Project Overview
[1–2 lines]
Example: Inventory management SaaS for small businesses. Next.js 14 App Router + TypeScript + Supabase.

## Tech Stack
- Framework: Next.js 14 (App Router)
- Language: TypeScript (strict)
- Styles: Tailwind CSS
- Backend: Supabase
- Package manager: pnpm
- Deploy: Vercel

## Coding Rules
- Components: PascalCase
- Functions/variables: camelCase
- Constants: UPPER_SNAKE_CASE
- No `any`, all functions need explicit return types

## Common Commands
pnpm dev, pnpm build, pnpm test, pnpm lint

## Never Do This
- Use npm or yarn (pnpm only)
- any types
- Hardcode env vars in code

## Git Commit Rules
- English, "type: description" format (e.g., feat: add user login page)

Global Memory: Your Preferences, Any Project

Whatever you put in ~/.claude/CLAUDE.md applies automatically whenever you open Claude Code, regardless of folder.

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

The first line I added when setting this up on WSL2 was "always respond in Korean." English answers to Korean questions were happening occasionally, and that one line stopped it entirely. The second addition was "for changes that are hard to undo, ask for confirmation first." Those two lines cover about 70% of what I need from a global config.

# Global Settings (All Projects)

## Personal Preferences
- Always explain in Korean
- Before modifying anything, describe what you're about to do
- For hard-to-reverse changes, ask for confirmation

## Coding Style (Universal)
- Keep functions short (20 lines max)
- Variable names should be self-explanatory
- Code should read itself — minimize comments

Priority: The More Specific Rule Wins

When multiple CLAUDE.md files apply simultaneously, which one takes precedence? The answer is simple: the more specific one.

Load order: read top to bottom, concatenated. What loads later wins.
① Managed policy (Enterprise) — loaded first, cannot be turned off
② ~/.claude/CLAUDE.md (personal global settings)
③ ./CLAUDE.md (or ./.claude/CLAUDE.md) — shared project settings
④ ./CLAUDE.local.md — personal project settings (wins over everything)

If global says "2-space indentation" but the project CLAUDE.md says "use tabs," the project wins. Within the same directory, CLAUDE.md is read first and CLAUDE.local.md is appended after it.

💡 Managed policy is a "policy" — users can't disable it, but in load order it comes first, with everything else stacked on top.

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

Good CLAUDE.md vs Weak CLAUDE.md: Lessons from the Field

Verifiability, Not Length, Is What Matters

A good rule is one you can check was followed. Here's the difference between vague and verifiable:

💡 Here's something that actually happened. During a workshop CLAUDE.md review, I saw one that said "always write clean code." Good intention, but "clean" means something different to everyone — including Claude. After changing it to: "functions max 20 lines, 2-space indentation, variable names as verb+noun form" — all three lines are checkable. After that, nobody said "this function is too long" during code reviews.

Quick Edit with /memory

Want to edit CLAUDE.md during a session?

/memory

A file picker opens and you can edit right there.

Import Other Files with @

Rather than cramming everything into CLAUDE.md, split detailed content into separate files and reference them with @.

# Project Instructions

See @README.md for the project overview.
See @package.json for available npm scripts.

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

Starting a New Project: CLAUDE.md First

/init

Or just ask directly:

This folder is a competitor market research project.
Results go in the reports/ folder as Markdown.
Every claim needs a source. Write in Korean.
Create a CLAUDE.md based on this.

🖥️ For developers: "This project uses Next.js 14 + TypeScript + Tailwind, with pnpm. Create a CLAUDE.md."

The Top Things Added in the First Three Months

Looking at CLAUDE.md files that students build in workshops, certain content tends to accumulate over time. Start with these and skip the trial and error.

"Before any modification, tell me what you're planning to do" Unexpected file changes are unsettling. This one line removes the unease.

"Before fixing an error, explain the cause first" If Claude just fixes it, you never learn why. Adding "explain first" grows your own understanding alongside the work.

"Don't touch non-code files (images, config, env vars)" I learned this the hard way when .env.local got overwritten. Added it immediately after.

"Don't say 'done' without confirming the build passes" This dramatically reduces the "all done" + build error situation.

When the Team Uses CLAUDE.md Together

Working solo is straightforward, but conflicts emerge when teams get involved. Patterns I've seen and how to handle them.

Separate Shared (./CLAUDE.md) from Personal (./CLAUDE.local.md)

Rules everyone must follow go in ./CLAUDE.md. Personal preferences go in ./CLAUDE.local.md. The .local file is automatically excluded from Git.

./CLAUDE.md         # Team rules — included in Git
./CLAUDE.local.md   # Personal preferences — auto-excluded

When Rules Conflict

Global says 2-space indentation, project says tabs? The project wins. But when this conflict is hidden, it's hard to debug. When creating a project CLAUDE.md, add a brief "things that override global settings" note. Makes it easier to find later.

What If Someone Accidentally Overwrites It

Git history keeps everything. That's usually enough, but for teams with frequent changes, adding a rule that CLAUDE.md changes require a PR review is reasonable.

When CLAUDE.md Gets Too Long

At some point you'll cross 300 lines. Claude spends more context just reading it. Two strategies:

Split and reference

## Detailed Coding Rules
See @docs/coding-standards.md for details.

## API Design Principles
Follow @docs/api-design.md.

Keep the essentials in CLAUDE.md, move detailed content to separate docs, link with @ imports.

Most-used rules at the top, rarely-used at the bottom

Claude weighs content near the top more heavily. Put daily-use rules (commit format, language setting, prohibitions) at the top. Special-case rules go toward the bottom.

Summary at a Glance

Real-World Impact: With vs Without

Here's how the same first message plays out differently:

Without CLAUDE.md

User: Build me a login page
Claude: What tech stack are you using?
        React or Vue?
        Are you using TypeScript?
        ...

Three to five rounds of Q&A before any actual work.

With CLAUDE.md

# CLAUDE.md contents:
- Next.js 15 + TypeScript + Tailwind
- Components go in /components
- Pages go in app/ (App Router pattern)

User: Build me a login page
Claude: I'll create app/login/page.tsx.
        It'll include email/password fields and a submit button,
        with the form extracted to /components/LoginForm.tsx.
        Shall I proceed?

The first response is already an action plan.

The Best CLAUDE.md Is the One You Actually Have

Don't wait to make it perfect. A 5-line CLAUDE.md beats none, and one you write today beats a perfect one you plan to write someday. Wrong rules can be fixed. Missing ones can be added.

Start with the one thing that annoys you most right now. That's enough.

Top 10 Annoyances Solved by CLAUDE.md

Things that students in the workshops said were resolved after writing their CLAUDE.md:

1. Re-explaining the tech stack every session → "Tech environment" section
2. Commit messages coming out in the wrong language → Language rule
3. Files changing without warning → "Show plan before modifying" rule
4. "All done" with a broken build → "Confirm build before claiming done" rule
5. Answers that are way too long → "Just list changed files and results" rule
6. Repeating the same error → "Prohibited actions" section to record root causes
7. Folder structure getting rearranged → "No folder structure changes without asking" rule
8. Document format changing every time → "Output formats" section
9. Touching .env files → "Never touch environment config files" rule
10. Ignoring team conventions → Git-committed ./CLAUDE.md rules

If any of these is bothering you right now, put that one in your CLAUDE.md first. Don't try to fill the whole list — start with today's biggest pain point.

Appendix: Commands You'll Use with CLAUDE.md

# Auto-generate a CLAUDE.md draft for the current project
/init

# Quickly edit CLAUDE.md during a session
/memory

# Edit the global CLAUDE.md directly (macOS/Linux)
nano ~/.claude/CLAUDE.md
# or
code ~/.claude/CLAUDE.md

# Reference other files from within CLAUDE.md
@README.md
@docs/coding-rules.md
@package.json

# Request a CLAUDE.md when starting a folder from scratch
"Create a CLAUDE.md for this folder.
 Read the current file structure to understand the project, then write a draft."

CLAUDE.md Health Check

Quick checklist to verify your CLAUDE.md is actually working:

Open a new session and confirm:

□ Does Claude start without asking about the tech stack again?
□ Does it automatically follow the commit message format?
□ Are "Never Do This" rules actually being respected?
□ Does output match the format defined in CLAUDE.md?
□ Does it show a plan before making modifications (if that's configured)?

Any "no" means that rule needs to be more specific.

Run this check in week one of a new project, then again a month later. Verifying that rules actually work is the most efficient way to improve your CLAUDE.md over time.

How CLAUDE.md Changes the Relationship

When you work with someone for a long time, you learn their patterns. "This person always wants a 3-line summary first," "this person hates it when I suggest things without being asked." Picking that up normally takes months.

Claude Code starts every session as a stranger. CLAUDE.md is how you skip that learning curve. Write down how you work, what you want, what you don't — and every new session starts feeling like a three-month-old collaboration instead of a first meeting.

At first it might feel odd to "explain yourself to an AI." But when a new team member joins, we explain "here's how we work on this team." CLAUDE.md is that onboarding document. Instead of repeating the same onboarding every session, you write it once and let it apply automatically.

Evolving CLAUDE.md Over Time: The Feedback Loop

The most effective way to improve your CLAUDE.md is to run this at the end of a session:

"Look at our conversation today.
 What did I have to explain more than once?
 What did you do that I didn't want?
 Suggest additions to CLAUDE.md based on those patterns."

Claude scans the conversation history and proposes missing rules. Agree and add them; disagree and skip. Two minutes, tops. Maintain this loop for a month and your CLAUDE.md will naturally evolve to match your actual working patterns — no separate planning needed.

Monthly Review

Once a month, scan through your CLAUDE.md and ask: "Does this rule still make sense?" Projects change, and so should their rules. Old rules that conflict with new workflows are a hidden source of confusion.

For Teams: Quarterly Retrospective

For a shared ./CLAUDE.md, a quarterly review works well. Three questions: "Did this rule actually help?", "What should we add?", "What can we remove?" Fifteen minutes covers it.

CLAUDE.md Maturity Stages

Here are four stages I see when reviewing students' CLAUDE.md files. Find where yours is and see the path forward.

Stage A — Empty or missing Every session starts with re-explanation, or you keep a text file of prompts to paste. Fix: Run /init — five minutes to a working draft.

Stage B — Role description only "This is an e-commerce site, built with React + TypeScript." Context exists, but no rules. Fix: Add a "Never Do This" section. Pick three things that have annoyed you and ban them.

Stage C — Rules exist but are vague "Write good code," "respond quickly," "be helpful" — subjective criteria throughout. Fix: For each rule, ask "how would I verify this was followed?" Replace unverifiable ones with concrete standards.

Stage D — Rules are specific and verifiable Checkable criteria, prohibited actions, output formats — all defined. Sessions start well from the beginning. Fix: Check whether it's getting too long. Over 100 lines, consider splitting content into referenced files.

Before You Close This Chapter

• There is a CLAUDE.md file in your current working folder (or you created one with /init)
• You've written at least one item in the "Never Do This" section
• You've taken one vague instruction ("do it nicely") and turned it into a verifiable criterion
• You've added at least "respond in English" to the global settings (~/.claude/CLAUDE.md)
• You've run /memory once and confirmed the edit screen appears

The next chapter (09 Commands) covers which session commands work together with the CLAUDE.md you just created. If CLAUDE.md is the "memory," commands are the handles that retrieve and manage it.

09. Commands — The Handles That Get You Through the First Week

When you first open Claude Code and see the command list, "do I have to memorize all of this?" is a completely normal reaction. In practice, you'll use fewer than five commands in the first week. The rest you look up when you actually need them.

Source: Slash Commands — Anthropic Docs

Commands Come in Three Groups

Grouping them by where you type them clears up the confusion.

• CLI commands: Typed in the terminal outside Claude Code (claude, claude --version, etc.)
• Slash commands: Typed in the conversation inside Claude Code (/help, /compact, etc.)
• Keyboard shortcuts: Pressed with your fingers during conversation (Ctrl+C, Shift+Enter, etc.)

The Five Fingers for the First Week

Start with just these five. Trying to memorize the whole list at once means you end up using none of them. I made that mistake too — spent time organizing everything and ended up not actually running anything.

• claude: Start
• /compact: Tidy up when conversation gets long
• /clear: Switch to a completely different task
• Ctrl+C: When you want to stop
• /quit: When you're done

Find everything else with /help when you need it.

💡 Here's something that actually happened. On the first day of a workshop, one student typed claude and got no response at all. Turned out Claude Code wasn't properly installed due to a Node.js version conflict. The first check was claude --version — it came back "command not found." That's when I made this checklist: 1 — which claude, 2 — node -v, 3 — npm list -g to verify installation. Half of all install problems get caught in these three steps.

Group ①: CLI Commands (Typed in the Terminal)

These commands launch and control Claude Code. In order of how often you'll use them:

Starting, Stopping, Checking

• claude: Start interactive mode
• claude "question": Start and ask something immediately (e.g., claude "explain this project")
• claude -p "question": Print the answer and exit (great for scripts)
• claude -c: Resume the most recent session
• claude --version (or -v): Check version
• claude --help: View help
• claude update: Update to the latest version

Of these, claude is the one you use every day. --version is the first thing you check when something seems off. Everything else is for special situations.

Choosing a Model

# By full model ID
claude --model claude-opus-4-7
claude --model claude-sonnet-4-6

# Using short aliases
claude --model opus     # Opus 4.7 (Max/Team Premium default)
claude --model sonnet   # Sonnet 4.6 (Pro/Team Standard default)
claude --model haiku    # For lightweight tasks
claude --model opus[1m]    # Opus 4.7 with 1M context (for very large codebases)
claude --model sonnet[1m]  # Sonnet 4.6 with 1M context (for very large codebases)

My pattern: I usually just start with claude. On days with complex architecture work or tricky refactoring, I start with claude --model opus. For simple file conversions or repetitive tasks, haiku is more than enough. Switching models isn't just about cost — the right model for the task weight also affects response speed.

Options to Tuck In at Startup

# Start in Plan Mode (plan only, no file changes)
claude --permission-mode plan

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

# Pick from a list to resume
claude --resume

💡 Just claude is enough to start. Learn the options one at a time as you need them.

Group ②: Slash Commands (Typed During Conversation)

Start with / in the chat window and special features open up. Organized by how often you'll use them:

The Ones You'll Use Every Day

• /help: See all available commands
• /compact: Compress conversation (essential for long sessions)
• /clear: Completely reset the conversation
• /usage: Session cost, plan limits, activity stats (/cost and /stats are aliases)
• /model: Change the model mid-session
• /permissions: View and manage permissions
• /memory: Edit CLAUDE.md
• /quit or /exit: Exit

Looking back at two weeks of actual use, /compact and Ctrl+C account for 90%. Long conversation? /compact. Wrong direction? Ctrl+C. Building those two habits is step one.

The Ones You'll Need Occasionally

• /plan: Enter Plan Mode
• /init: Generate a CLAUDE.md draft for the project
• /doctor: Check installation health
• /config: Settings screen (theme, model, editor mode, etc.)
• /branch or /fork: Branch the conversation at the current point
• /context: Visualize context token usage
• /rename [name]: Name a session (resume with --resume name)
• /bug: Send a bug report to Anthropic
• /login / /logout: Log in or out of your account
• /rewind: Rewind conversation and code to an earlier point

Slash Commands Accept Arguments Too

> /compact
→ Standard compression

> /compact focus on code changes and decisions
→ You direct what to keep

> /model
→ Opens model selection menu

💡 Typing just / in the chat brings up autocomplete.

Small Tools for Branching and Experimenting

For changing conversation direction or safely testing risky ideas:

/branch (or /fork): Keep the Original, Make a Side Branch

Branch before big refactors or structural changes, and if it doesn't work out, come back with /resume.

> /branch
→ Start a new branch from the current point
→ Return to original with /resume

Best times to use it:

• When you want to try just one of several implementation approaches first
• When you want to try a change but are worried about failure
• When you want to compare two different approaches to the same problem

I first thought of branching as "undo insurance," but after using it, it feels more like an "idea lab." You can experiment boldly because the original is still there.

/compact: When You Need to Breathe Again

When responses start slowing down, compress to stay in the same session. If you need a completely fresh start, use /clear.

> /compact focus on changes made and decisions reached
→ Context gets lighter while the session continues

💡 Here's something that actually happened. A workshop student hit /compact too quickly and lost the context of a three-hour research session. After that, I always stress this in workshops: before running /compact, specify what to keep as an argument. Like /compact center on key findings so far and hypotheses still unverified. Directionless compression can cut your most important context.

/context: How Full Is the Context Right Now?

> /context
→ [■■■■■■■□□□] 70% (143,000 / 200,000 tokens)

If it's over 80%, compress with /compact or start fresh with /clear.

/rename: Label the Session

For important work, add a name so you can find it quickly next time.

> /rename housing-research-2026Q2

# Next day in terminal:
$ claude --resume housing-research-2026Q2

Group ③: Keyboard Shortcuts

A few keystrokes give you fast control over the conversation flow.

Core Shortcuts

• Ctrl+C: Cancel current work (instant stop when Claude goes off track)
• Ctrl+D: Exit Claude Code
• Ctrl+L: Clear terminal screen only (conversation stays)
• Ctrl+R: Search previous inputs
• Ctrl+G: Edit input in an external editor
• Ctrl+T: Show/hide task list

Input Helpers

• Shift+Enter: New line (for long instructions)
• Option+Enter (macOS): New line (macOS default)
• \ + Enter: New line (works in all terminals)
• ↑ / ↓ arrows: Navigate previous/next inputs
• Esc Esc (twice): Roll back to previous state

Mode Switching

• Shift+Tab: Plan Mode ↔ Normal mode
• Option+P (macOS) / Alt+P: Change model
• Option+T (macOS) / Alt+T: Toggle extended thinking mode
• Ctrl+B: Send current work to background, open new conversation window

Five for Day One: These Will Get You Through the Week

① /compact: Clear the Conversation

> /compact

Longer conversations get slower responses and start forgetting earlier content. Press it whenever the conversation starts feeling long. Making it a habit is the key.

② Ctrl+C: Stop Immediately

When the direction is wrong or a dangerous command slips in, don't hesitate — press it. Early on there's anxiety about "is it okay to stop?" Once you get comfortable pressing this quickly, Claude Code becomes much less stressful. Stopping a wrong direction fast is a core habit for good results.

③ /clear: Switch to a New Task

> /clear

When moving to a completely different topic, previous context following you around is more hindrance than help. Clear it and start clean.

④ Shift+Enter: Multi-line Requests

Requests that are hard to compress into one line get better results when you break them up across lines.

(Multi-line input with Shift+Enter)
Build a login page.
- Email and password fields
- Show/hide password button
- Login button (with loading state)

⑤ /usage: Check Cost and Limits

> /usage

Session cost, plan limits, and activity stats in one view. /cost and /stats are aliases for the same command. In the first month, check this occasionally to get a feel for how much you're using.

Two Mindsets That Matter More Than Memorizing Commands

The goal isn't to memorize commands. Two mindsets matter more.

First: Open /help without hesitation when you're stuck

You don't need to know specific commands in advance. Open /help when you need it. When you can do this naturally, you don't need to study commands separately.

Second: The instinct to reach for a command when something feels off

"Response is slowing down" → /compact. "Direction is wrong" → Ctrl+C. "Moving to a different task" → /clear. When this instinct develops, commands become real tools.

Once these two are in place, the rest of the commands will come to you naturally when needed.

Quick Reference by Situation

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

source ~/.zshrc

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

One-Page Cheat Sheet

[ Terminal ]
  claude                    → Start
  claude -v                 → Check version
  claude --help             → View help
  claude -c                 → Resume last session
  claude --resume [name]    → Resume named session
  claude --add-dir [path]   → Include additional directory

[ Aliases (after setup) ]
  cc / ccd / ccr            → Basic / auto-approve / resume+auto-approve

[ Chat window ]
  /help                → Full command list
  /compact             → Compress conversation (use often!)
  /clear               → Reset conversation
  /branch (/fork)      → Create branch
  /context             → Check context usage
  /usage               → Cost, limits, stats (/cost·/stats aliases)
  /model               → Change model
  /rename [name]       → Name the session
  /bug                 → Send bug report
  /quit                → Exit

[ Keyboard ]
  Ctrl+C               → Cancel work
  Ctrl+D               → Exit
  Ctrl+B               → Background / new window
  Shift+Enter          → New line
  ↑↓                   → Navigate previous inputs
  Esc Esc              → Roll back to previous state

Command Groupings: Why They're Separated This Way

"Why are slash commands and CLI commands separate?" is a question I hear in workshops regularly. There's a reason.

CLI commands control what happens before Claude Code starts — how to launch it, which model, which session to resume, what permission mode to use. These are pre-startup decisions.

Slash commands are tools for adjusting the conversation flow while Claude Code is already running. Cleaning up memory with /compact, switching models with /model, creating experiment space with /branch — these are mid-session needs.

Keyboard shortcuts replace typing. They perform common actions faster than typing commands.

Once you see the three groups this way, when you encounter an unfamiliar command you can identify "which group is this in?" before trying to understand it.

Using Slash Command Autocomplete

Typing / in the chat brings up the autocomplete list. This list contains two types of commands mixed together:

• Built-in commands: Claude Code's own features (/help, /compact, /model, etc.)
• Custom commands: Your own slash commands created in .claude/commands/

Custom commands turn frequently-used prompts into reusable slash commands like /report or /analyze. The details are covered in an advanced section. For now, just know "I can create my own slash commands in addition to the built-in ones."

Note: as of 2026, .claude/commands/ still works, but Skills (.claude/skills/<name>/SKILL.md) is the recommended path. See chapter 17.

Actual Command Journal: The First Three Days

Based on what came up in real workshop sessions, here's what commands actually appeared during the first three days.

Day 1 (Mostly Exploring)

claude               ×1  (first run)
claude --version     ×2  (version check, troubleshooting)
/help               ×5  (exploring what's available)
Ctrl+C              ×3  (when Claude went off track)
/quit               ×2  (ending sessions)

Mostly exploration. Looking at /help multiple times at this stage pays off later.

Day 2 (Starting Real Work)

claude               ×2
/compact            ×3  (conversation starting to get long)
/clear              ×1  (switching topics)
Shift+Enter         ×8  (multi-line input)
Ctrl+C              ×2

/compact appears for the first time. Starting to manage lengthening conversations.

Day 3 (Routine Taking Shape)

claude --continue    ×1  (continuing yesterday's work)
/compact            ×4
/rename             ×1  (discovering session naming)
/usage              ×1  (curiosity about cost)
Shift+Enter         ×15
Ctrl+C              ×1

By day three, /compact is becoming a habit and --continue starts picking up previous work. When this pattern settles in, Claude Code becomes a real work tool.

Reality Check: Command Usage Frequency

After six months of actual sessions, the distribution looks like this:

The top six cover 90%. That tells you what to practice.

Small Tips That Earn "Oh, That Exists?" Reactions

/ then Tab or arrow keys Navigate the autocomplete list with Tab or arrow keys. For frequent commands, first letter + Tab is faster than typing the full command.

Slash commands are case-insensitive /COMPACT, /Compact, and /compact all work.

--version and -v are identical claude -v is faster than claude --version.

/usage, /cost, and /stats all go to the same screen Three names because different people remember different ones.

Two Ctrl+Cs stop more forcefully Sometimes one doesn't stop it. Two in quick succession is more reliable.

/branch and /fork are the same command Two names for the same function.

--add-dir includes another folder

claude --add-dir /path/to/other/folder

Use this when referencing a folder outside your current working directory.

Before You Close This Chapter

• Typed claude --version and confirmed it outputs a version number
• Opened a conversation and typed /help to see the command list
• Ran /compact once and experienced the result
• Used Ctrl+C to cancel mid-execution (confirmed immediate stop)
• Typed / in the chat and confirmed autocomplete appears

The next chapter (10 Session & Context Management) covers how these commands fit together in actual session flow. When to press /compact, when opening a new session is the better call — the judgment beyond the commands.

10. Session & Context Management — Ending "I Already Said That"

Conversations get hazy for people and Claude alike. Once you understand what causes the haziness, the fix becomes clear.

The Context Window: There's No Infinite Notepad

Claude works by writing everything exchanged so far onto a notepad. That notepad has a finite size. As the conversation grows, the earliest content gets pushed to the margins. "I already told you that, why don't you know it?" has a precise cause — not forgetting, but content being cut off the notepad.

Technically: the context window is the maximum number of tokens the model can process at once. Claude Code uses a sliding window, so when the limit is reached, the oldest tokens are dropped first.

Both descriptions are the same picture.

As conversation grows:
  Early content starts getting cut
  → Work done earlier may be forgotten
  → Answer quality starts degrading
  → Same mistakes start repeating

Left alone, it compounds. Occasional manual cleanup is necessary.

💡 Here's something that actually happened. A workshop student said: "Claude perfectly followed my style at first, but after two hours it suddenly started answering in English and ignoring the format I'd set." They'd been doing research for four hours in one session and the context was completely full. Checking with /context showed 92%. One /compact fixed it. Ever since, I tell workshop students: "/compact is like wiping a window. When it gets foggy, wipe it."

/compact: Rewriting the Notepad Shorter

/compact

Summarizes the current conversation to reduce context. The core move: preserve what matters, trim the volume.

• Important decisions and results make it into the summary
• The session continues without interruption
• When to press it: when the rhythm slows, when answers start going vague

You can direct the compression:

/compact summarize around research findings and key discoveries
/compact focus on the structure and progress of the report I'm writing
/compact keep only conclusions, reasoning, and unresolved questions

Without an argument, Claude decides what's important to keep. But context you care about might get cut. For important sessions, providing an argument is worth the habit.

Timing /compact Well

"When should I press /compact?" is something almost every student asks. Watch for four signals.

Signal ①: Response speed noticeably slows

When responses are taking significantly longer than they did at the start of the conversation, the context has gotten heavy.

Signal ②: Being asked about things already covered

"I already told you this project uses Next.js and now it's asking again?" When that happens, check with /context.

/context
→ [■■■■■■■□□□] 73%

Over 70% is compact time.

Signal ③: Starting to break earlier agreements

"I told it to respond in English and it's suddenly writing in Korean" or "I set the commit message format and it's ignoring it" — early instructions have been cut off.

Signal ④: Repeating the same mistake

Fixed once, but the same pattern came back. The correction has likely been pushed out of context.

Two Ways to Resume an Interrupted Flow

--continue: Pick Up the Most Recent Session

claude --continue

Picks up exactly where the last session left off.

• Right after closing and reopening the terminal
• Morning, continuing yesterday's work

The first time I used this, "yesterday's work is just here" felt refreshingly good. I used to start a fresh session every morning, but after switching to --continue, picking up with the previous day's context turned out to be significantly more productive.

--resume: Choose From a List

claude --resume

Shows previous sessions and lets you pick one.

• When juggling multiple projects
• When you need to go back to a specific session from a few days ago

Name sessions with /rename and navigating the list gets much easier.

# Resume directly by name
claude --resume housing-analysis-2026Q2

A Template for Starting Fresh Without Losing Context

Rather than forcing a long session to continue, starting fresh with a core summary is often more accurate.

Current work:
- Project/folder:
- Goal:
- Completed so far:
- Still remaining:
- Rules to follow:
- Files to reference:

Based on the above, assess current state first,
then propose next steps before making any changes.

Paste this into a new session and Claude reads the summary to get context immediately rather than starting from scratch. Especially effective when the session has gotten messy or the same error keeps repeating.

New Session vs Continuing: Decision Table

Before Big Changes: Run Through Plan Mode First

When you're about to touch multiple files simultaneously or make a hard-to-reverse change, get the plan reviewed before execution.

Shift + Tab  →  Switch to Plan Mode

In Plan Mode, Claude:

1. Shows only the execution plan — doesn't touch any files
2. Asks "does this look right to you?"
3. Only executes after approval

Best situations for it: modifying multiple files at once, restructuring folders, mass replacements, anything hard to undo.

💡 Here's something that actually happened. A student asked "refactor the entire database schema" and Claude immediately started modifying 30 files. They stopped it midway, leaving some files changed and others not, and it took two hours to recover. With Plan Mode, they would have seen a list of which files would change and how, before anything was touched. After this incident, I teach in workshops: "anything that touches five or more files starts with Plan Mode."

Parallel Sessions: The Feeling of Extra Hands

Open multiple terminals and assign different tasks to each.

Terminal 1: claude (market statistics research)
Terminal 2: claude (writing the analysis report)
Terminal 3: claude (organizing summary slides)

Each session runs independently.

⚠️ Modifying the same file from two sessions at once will cause conflicts. Dividing files and roles in advance is the safe starting point.

Parallel sessions work especially well when:

• Research (session 1) and drafting (session 2) run simultaneously
• Multiple sections are distributed across sessions
• One session handles a long-running task while another does separate work

Two Habits for a Steady Conversation Rhythm

① One Thing at a Time

The most common beginner mistake is requesting everything at once.

# Tends to fall apart
> Build login, dashboard, DB connection, API, tests, and deployment

# Gets good results
> First, set up the project structure
(confirm)
> Now build the login feature
(confirm)
> Next, add the dashboard

One task per turn, confirm, then move on. It may feel slower, but the results are faster and more accurate.

② For Multi-Day Work: Track Progress in CLAUDE.md

# Current Progress
- Login feature: complete
- Dashboard: layout finished, data connection needed
- Next: connect real-time data to dashboard

Even with a new session, Claude reads CLAUDE.md and picks up context immediately.

Two Common Scenarios: Quick Responses

Scenario ①: Answers suddenly going wrong

1) Try /compact first
2) Still wrong → new session
3) In the new session, just the essentials:
   "Working on [project]. Done so far: [summary].
    Next: [task]."

Scenario ②: Need to stop and step away

Mid-task → Ctrl+C to pause
→ Close terminal
→ Next time: claude --continue

Claude holds the state from where it was interrupted.

Context and Cost: The Direct Connection

Context management is directly tied to cost. The longer the context, the more tokens each response consumes.

For example: maintaining 100,000 tokens of context means every response incurs the input cost of 100,000 tokens. Compress to 50,000 with /compact and subsequent responses cost half as much for input.

[/compact's effect from a cost perspective]
Context 100K → /compact → Context 30K
→ 70% reduction in per-response input cost from there on

So /compact isn't just "for when it gets slow" — it's also a cost-saving tool. More on cost management in chapter 20.

Session Strategy by Work Type

Research Work

Morning: claude --continue (or --resume)
Throughout: /compact to update summary as new findings emerge
End: "Add today's findings to the progress section in CLAUDE.md"

Code Work

Morning: claude (fresh session)
During: Break at feature boundaries, git commit completed work
Before big changes: claude --permission-mode plan or /branch
When session gets long: /compact or new session + re-deliver essentials

Writing & Content Work

Morning: claude --continue (continuing yesterday's work)
Break by section: Section done → save → /compact, or new section = new session
Big structural change: Plan Mode first

Session Management Summary

FAQ: Session Management Q&A

"New session or /compact — which is better?"

Depends on the situation. For continuing the same task, /compact is better. For corrupted context or switching to a completely different task, a new session is better. Unsure? If Claude is giving strange answers, new session. If it's just slow, /compact.

"Can I /compact too often?"

No hard limit, but doing it too often can cut important context. When context is under 50%, just continue instead of compacting. Once at 70%+ is the right balance.

"How should I name sessions?"

project-date pattern is practical. Like market-research-2026may or login-feature-may07. Having the date makes it easy to distinguish in the list later.

"What are the symptoms when the context limit hits?"

Watch for four things: slower responses, asking about things already covered, breaking earlier agreements, and repeating the same mistakes. If any of these appear, check with /context.

"Do parallel sessions cost double?"

Each session is billed independently. Two sessions running simultaneously each consume tokens. But with double the output in the same time, it's actually more efficient from a productivity-per-hour perspective.

What Changes When Session Management Becomes a Habit

It's natural to feel "why do I need to manage all this?" at first. But once session management becomes second nature:

• The "suddenly went wrong" phenomenon in long tasks disappears
• /compact as a habit means lower cost and maintained speed
• --continue daily creates a productive rhythm with yesterday's context
• Plan Mode means noticeably fewer hard-to-recover mistakes

When these four are in place, collaboration with Claude Code stabilizes.

Session management is one of the easiest skills to learn in Claude Code, and one of the fastest to show results. If you've run /compact once today, you've already started.

Before You Close This Chapter

• Ran /context and confirmed the context percentage shows as a number
• Ran /compact once and experienced how the conversation gets summarized
• Used claude --continue and confirmed a previous session resumes
• Cycled permission modes with Shift+Tab (default → acceptEdits → plan) and felt Claude showing plans without touching files in Plan Mode
• Remembered the four signals that mean /compact is needed

The next chapter (11 Getting Started with GitHub) covers a different dimension of safety net: Git and GitHub. If sessions manage memory, Git manages the history of your files.

11. Getting Started with GitHub — The Moment "Unrecoverable Mistakes" Disappear

🖥️ This section has the most impact for people writing code. If there's no coding in your work, reading through the Non-Developer File Safety Nets below and moving on to the next section is entirely fine. Git isn't about memorizing commands — it's about earning the peace of mind that comes from knowing you can undo anything.

Not a Developer? Three Safety Nets Without Git

Files getting accidentally deleted or overwritten happens to everyone, not just coders. These three options are solid protection without ever touching Git.

• Google Docs/Notion "Version History": Restore yesterday's or last week's version with one click
• Folder snapshot before working: Ask Claude "copy the reports/ folder to reports_backup_today's-date"
• Undo the last thing Claude did: While in a Claude Code session, press Esc Esc twice in a row

💡 Curious about Git now? Git works for any kind of file, not just code. Research materials, quarterly reports, planning documents — all of them get a safety net that lets you restore "what it looked like at midnight last night."

Why Git and GitHub?

Working with Claude Code means files change constantly. Without Git, certain moments come up regularly. You've probably experienced some of these:

• Yesterday's code worked fine; today it doesn't, and I don't know why
• Claude accidentally overwrote important code and there's no way to undo it
• A teammate and I were editing the same file and we wiped each other's work
• "I definitely fixed this yesterday" can't be proven

Git records every change so you can return to any past state at any time. GitHub backs up those records in the cloud and shares them with your team. The two come as a pair.

For Claude Code users, this pair isn't optional. Having a safety net is what lets you ask Claude to do bold things, and bold asks are what generate real productivity.

💡 Here's something that actually happened. In a workshop, one student lost two weeks of project work because Claude accidentally overwrote files. They were working without Git. The shock was understandable — but the real issue is that "the moment you need protection" always arrives without warning. Git exists for those unannounced moments. In the very next session we set up Git first, and nothing similar happened after that.

Google Drive vs Git: The One Difference That Explains Everything

This is the most confusing point for first-time Git users, and once you get it, it never confuses you again.

• Google Drive: Modify a file and it automatically syncs to the cloud
• Git: You have to save it yourself, and you have to upload it yourself

This one sentence unlocks how Git works. Git always moves in two beats:

1. Save (Commit): Record the change on your computer
2. Upload (Push): Send that record to GitHub

💡 Why two beats? Because it lets you save even when offline, and because you can bundle just the changes that are ready to go and upload them all at once. "Saved ≠ immediately public" is both a freedom and a safety mechanism.

5-Minute Setup: Natural Language with Claude Code

No need to memorize Git commands. One sentence in plain language handles most Git work. For a friendlier flow, look in /plugin for Git-related plugins.

Just Once to Get Started

"Set this folder up to be managed with Git and uploaded to GitHub"

Behind the scenes, this one line handles:

• Check if Git is installed (installs it if not)
• Check if GitHub CLI (gh) is installed
• GitHub login (browser opens automatically)
• Project folder setup: creates a new repository for new projects, pulls from GitHub for existing ones, or initializes the current folder as a repository

Steps already completed are skipped automatically. From start to finish takes about five minutes, and once done, you rarely need to think about setup again.

Three Actions You'll Use Every Day

Action ① · Save (Commit)

"save this"

Shows the list of changed files and asks for a short description (commit message). The message should be written so "my future self can read this line six months from now and know what it was about."

Examples:
  "Redesign login page layout"
  "Bug fix: password validation error"

After saving, a confirmation follows:

✅ Saved!
Still on your computer only.
Say "upload it" to send it to GitHub.

Action ② · Upload to GitHub (Push)

"upload it"

Sends the saved records to GitHub. When done, the repository link comes with it. Common errors are handled automatically:

• If a teammate already pushed conflicting changes, auto-merge with rebase
• SSH auth errors automatically switch to HTTPS
• First push to a new branch automatically sets the upstream

Action ③ · Request Review (Pull Request)

When you want teammates to review changes:

"request a review"

Automatic flow: create branch → save & upload → create PR → provide link → return to original working state. The PR body is automatically filled with a change summary, so you just add "what this change is about in one line."

Natural Language to Git Command Mapping

What you want to do                 How to say it
─────────────────────────────────────────────────────
First-time setup                    "start git for me"
Check current state                 "what's the current state?"
                                   "what changed?"
Save (Commit)                       "save this"
                                   "commit it"
Upload to GitHub (Push)             "upload it"
                                   "push it"
Request review (PR)                 "request a review"
                                   "I want to show this to my team"
Ask about terminology               "what is a commit?"
                                   "what's the difference between push and commit?"

💡 For a more structured Git onboarding, browse the Git-related plugins with /plugin. Some bundle this workflow into slash commands, or automate team conventions like branch naming and commit messages.

Git Terms Quick Reference: Learn by Analogy

When an unfamiliar term comes up, unfold this and look. Don't memorize it — come back and look each time is the faster habit.

• Repository: Project storage → "shared folder on GitHub"
• Commit: Save → "package the files and add a label"
• Push: Upload → "ship the packaged files via courier to GitHub"
• Pull: Download → "receive the latest from GitHub"
• Branch: Workspace → "personal workspace that doesn't touch the original"
• Pull Request: Review request → "Google Docs 'Suggest Edits' mode"
• Merge: Combine → "apply the suggested edits to the original"
• Clone: Copy and download → "download the shared folder to your computer"

When you hit an unfamiliar term, just ask right then and there:

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

Daily Routine: Follow This and You're Covered

[ Start ]
  Run claude → "start git for me"  (only on day one)

[ During work ]
  Edit files → "save this" → "upload it"
  Before big changes: "what's the current state?" to check first

[ Wrapping up ]
  "save this" → "upload it"   (both beats, every time)

[ Team collaboration ]
  Feature done → "request a review" → share PR link

This routine means everything you build with Claude Code gets safely preserved. If something breaks, you can return to midnight last night. "I definitely fixed this yesterday" becomes provable.

.gitignore: Keep API Keys Off GitHub

The most common and most expensive mistake in Git onboarding is uploading .env files containing API keys. A key that ends up in a public repository is essentially impossible to fully recover.

When you say "save this" to Claude Code, it detects the project type and automatically creates a .gitignore. If one already exists, it leaves it alone. If you're writing one yourself, this is a solid starting point:

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

⚠️ If you accidentally uploaded a key: rather than deleting it from the repository, immediately revoke the key in that service and issue a new one. Assume it's already scattered across caches, mirrors, and forks.

Dangerous Git Commands: Here's How to Ask Safely

Git is powerful, but some commands can wipe entire bodies of work. Building in this "safety briefing" habit with Claude is worth it:

• "revert everything" → "show me the changed files first, then ask which ones to revert"
• git checkout . → "use git restore . but show me git diff first"
• git reset --hard → "check for uncommitted changes, make a backup branch, then proceed"
• git push --force → "explain why force push is needed and which branches are affected first"

Modern Git uses git restore for file recovery because the intent is clearer. If the commands feel hard to remember, just speak to Claude plainly:

"I want to revert only src/auth/login.js to its previous state.
Show me the diff first, then confirm before proceeding."

When You Start Using Git, What Changes

The thing students say most often a month after starting with Git: "Now I can actually tell Claude to go bold." That one sentence captures Git's value.

Without a safety net, "completely change this feature" feels scary. If it goes wrong there's no recovery. But with a git commit, worst case is git revert in one line and you're back to yesterday. That peace of mind is what makes experimentation possible.

The most creative work happens when "failure is okay." Git and Claude Code together create that environment.

Common Git Mistakes to Avoid

Writing "fix," "change," "update" for every commit message

Six months from now, this tells you nothing. Write what and why changed.

Bad: "fix"
Good: "Add loading spinner to login button on click"

Bad: "update"
Good: "Add minimum 8-character password validation (security requirement)"

Committing an entire day's work at once

Smaller, per-feature commits make it easy to revert specific changes or trace when a problem was introduced. You don't need perfect granularity — feature units or meaningful chunks are enough.

Committing without pushing

A commit is still only on your computer. If the computer fails or is lost, it's gone. Pushing when important work is done creates the real backup.

Git + CLAUDE.md: Sharing Project Rules with the Team

Managing CLAUDE.md with Git means the whole team works under the same rules.

# Include the team's CLAUDE.md in the repository
./CLAUDE.md         # Included in Git → applies to the whole team

# Personal settings excluded via gitignore
./CLAUDE.local.md   # Auto-included in .gitignore → stays on your machine

When a new team member clones the repository, CLAUDE.md comes with it. They start with the team rules already applied. Onboarding time cuts in half.

Branches: How to Experiment Safely

A branch means keeping the original and creating a separate workspace.

"make a branch for working on a new feature"
→ Creates a branch named something like feature/login-page
→ Work in this branch without affecting the main branch

Branches are especially useful when:

• Building a new feature when an urgent bug fix comes up midway (switch to main)
• Multiple features being developed simultaneously on the same project
• An experimental change doesn't work out (just delete the branch)

"this branch work is done. merge it into main"
→ Either merge directly without PR, or create a PR for review first

Common Git Situations and How to Ask for Them

A collection of more specific situations and the natural-language requests that handle them.

Claude handles every action in this table. Knowing the commands gives you more precise control, but plain language already solves 90% of cases.

Before and After Adopting Git: What Changes in the Classroom

A summary of how things shift before and after introducing Git in a workshop.

Before

• "Something went wrong with Claude and I have no idea what changed"
• "Yesterday this feature worked, today it suddenly doesn't"
• "I can manage solo, but the moment a teammate touches the same file something gets wiped"
• "I'm scared to ask for any big change"

After

• Restoring a previous state: three lines in the terminal
• Tracking changes: "what changed yesterday?" in natural language
• Team work: branches separate work, conflicts resolved automatically
• Bold experimentation: after a commit, even "rewrite the whole thing" isn't scary

Without Git, Claude Code is powerful but precarious. With Git, it becomes powerful and reassuring.

GitHub Actions: Auto-run Tests Every Time You Push

After using Git for a while, the thought "it would be nice if tests ran automatically every time I push" tends to come up. GitHub Actions does exactly that.

"set this up so every push to GitHub runs the build tests automatically"

Claude Code creates a config file under .github/workflows/. After that, every push triggers GitHub to run the build, and the result shows up in the PR.

You don't need this right now. But knowing "this is also possible" lets you feel that Git is more than a backup tool.

Why Branches Are Useful Even When Working Solo

"Do I need branches if I'm working alone?" is a common question. Yes — for three reasons.

First, freedom to experiment. When a "what if I tried it this way" thought hits, making a branch keeps main untouched. If it works, merge. If not, delete the branch. Clean.

Second, parallel work. While building Feature A, an urgent bug surfaces — you can switch to main, fix the bug, and return to the Feature A branch. Conceptually similar to /branch in session management.

Third, tidy history. Per-feature branches leave a clean record of "this feature was finished at this point."

Git works without branches, but once you start using them, the thought becomes "why didn't I do this sooner?"

How Often Should You Commit?

No fixed rule, but two guidelines help:

Commit whenever "if this goes wrong, I'd have to start here again" happens.

Before starting a new feature, before making a major change, at the end of each day's work — these three moments are always commits.

Too often is fine too.

"Won't my history get messy if I commit too often?" Some people worry about this, but committing locally often and cleaning up before pushing is an option. For beginners, just commit often. Losing work by committing too rarely is far worse than having a long history from committing frequently.

💡 To use Git commands directly, just tell Claude: it will run git commit and git push right there. For people who find Git unfamiliar, the recommended path is starting with plain language ("save this," "upload it"), getting comfortable, then moving to the actual commands. Both paths arrive at the same place.

Before You Close This Chapter

• Ran "start git for me" in the current project folder and confirmed Git is set up
• Made the first commit with "save this" (wrote a meaningful commit message)
• Pushed to GitHub with "upload it" and received the repository link
• Confirmed .env is included in .gitignore
• Asked "what's the current state?" and saw the list of changed files

The next chapter (12 Common Mistakes & Fixes) covers the moments that still trip you up even with Git and sessions — the actual errors that come up often and how to handle them.

For First-Time Git Users: Sticking Points and How to Handle Them

"I don't have a GitHub account"

First, create an account at github.com. An email address is all you need. A free account lets you create both public and private repositories. Private repos are visible only to you, so you can use them without worrying about code leaking.

"It says Git isn't installed"

"install Git for me"

Claude Code walks you through the OS-appropriate installation. On macOS, Homebrew. On Ubuntu/WSL, apt. On Windows, Git for Windows. After installing, verify with git --version.

"It's asking for my password when I push"

Since 2021, GitHub uses tokens (Personal Access Tokens) instead of passwords. If issuing a token feels cumbersome, the GitHub CLI (gh auth login) handles it in one shot. Tell Claude "set up GitHub authentication" and it will walk you through.

"I pushed and got a conflict with a teammate's changes"

The most common situation. Tell Claude "resolve the conflict" and it will show which files conflicted and suggest how to resolve them. It feels alarming the first few times, but the pattern becomes familiar quickly.

12. Emergency-room Manual for the First Few Days

The walls you hit in the first week are mostly the same ones. This chapter collects them in one place — treat it like an ER, not a textbook. Don't read it cover to cover. Come here when you're stuck and search.

💡 I have gathered the 14 stumbles I've seen the most hands raised over in classrooms. Each case carries a short note from the time I hit that wall myself. The same error message stalls people in slightly different ways, and recognising the grain of your own stall helps. Steps are kept short on purpose so that, in front of the dark screen, you can find the next move within a minute.

Case ①: claude command not found

What you see

$ claude
zsh: command not found: claude

What just happened

It is installed, but the shell does not know where the executable is. One of the three below will untangle it.

Fix ㉠: Reinstall with the native installer (cleanest)

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

After installation, close the terminal window completely and open a fresh one.

Fix ㉡: Inspect PATH

which claude         # where it landed
echo $PATH           # current PATH

If ~/.local/bin is missing from PATH, add a line to .zshrc or .bashrc:

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

Reload with source ~/.zshrc.

Fix ㉢: Diagnostic command

claude doctor

This runs a combined diagnostic across install path, version, and shell environment. For first-timers, I recommend feeding the diagnostic output straight back to Claude — "look at this and tell me what's wrong."

💡 Here is something that happened. A student in a class typed claude and got command not found. They were on nvm, and each new shell would land on a different node version, so PATH kept shifting. The diagnostic order I built that day still holds: 1) which claude, 2) node -v, 3) the last line of ~/.zshrc. Those three cover ninety percent of first-day stumbles.

⚠️ On macOS and WSL alike, an empty which claude means a PATH issue, while seeing ~/.local/bin/claude but failing to run usually means a permissions issue (chmod +x). Different solutions for each.

Case ②: Login is blocked

How it shows up

• Browser doesn't open
• Auth screen hangs
• Logged in but still getting auth errors

Fix flow

Step ㉠ · Browser popup doesn't appear

After running claude, press the c key to copy the auth URL, and paste it into your browser yourself.

Step ㉡ · Log out, re-auth

# Inside Claude Code
> /logout

# Or from the terminal (session/config is stored in ~/.claude.json)
claude auth logout
claude

Step ㉢ · If that fails, run diagnostics first

> /doctor

Step ㉣ · Last resort (delete all settings)

# ⚠️ Only when the steps above don't unstick it
rm ~/.claude.json
rm -rf ~/.claude/
claude

⚠️ This wipes every setting, session, and plugin. Try /doctor first. If you must proceed, back up with cp ~/.claude.json ~/.claude.json.backup before deleting. Don't confuse the project's .claude/ with the home directory's ~/.claude/.

💡 Here is something that happened. A laptop kept demanding re-auth, and the cause turned out to be the company VPN blocking the OAuth callback URL. Switch VPN off, authenticate, switch it back on. Done. Roughly thirty percent of auth failures are network problems, not Claude problems. The first place to suspect is the network you're sitting in.

Case ③: Responses are too slow

The longer the conversation gets, the heavier Claude's load (context) becomes. It is normal, but disruptive to flow.

Four fixes, lightest first

• /compact: most effective. Compresses the conversation and recovers speed.
• /clear: when starting fresh is fine.
• Switch model: /model to Sonnet or Haiku. Opus isn't required for everything.
• Tidy MCP: in /mcp, disable connections you aren't using.

Telling apart kinds of "slow" helps

"Slow" is not one thing. Pin which of these three you're seeing.

• First response takes 30+ seconds — heavy context. /compact first.
• Tokens drip out one character at a time — network is shaky. Check Wi-Fi or tether.
• It's just stuck — a tool call has frozen. /doctor or Ctrl+C and restart.

💡 Here is something that happened. Same task, fast yesterday, slow today. The difference was simple — yesterday I ran /compact twice; today, not at all. Don't try to finish a long job in one breath. A rhythm of compacting every thirty minutes ends up faster overall.

Case ④: It doesn't do what I asked

Almost always one of three: vague instructions, missing project context, or a long messy thread that has accumulated confusion.

Fix ㉠ · Narrow the instruction

# Vague
> improve the code

# Narrowed
> in auth.js's login function, email validation is missing.
  Add a regex-based email format check after line 42.

Fix ㉡ · Lift repeats into CLAUDE.md

If you've said the same thing twice, that's the signal to move it to CLAUDE.md.

> /memory

# Code style
- error messages always in Korean
- JSDoc comment required on every function
- no var; only const and let

Fix ㉢ · If the same mistake repeats, new session

> /clear

Restart with a tighter instruction.

💡 Here is something that happened. "Refactor it" is the single line that produces the most accidents. One student turned a 100-line file into 280 lines from that one line. They retried with "don't refactor; just fix the bug in this function" and only five lines changed. "Improve," "refactor," "optimise" are vague and dangerous words. When they show up on your tongue, slice the sentence one more time.

Case ⑤: It looks like a file was edited wrongly

Fix ㉠ · Rewind inside Claude Code (fastest)

Esc Esc    or    > /rewind

Conversation and code roll back to the previous state together.

Fix ㉡ · Restore via git

git diff                                # what changed
git restore src/auth/login.js           # one file back
git restore .                           # all changes undone

Fix ㉢ · Make git commit a habit before big work

git add .
git commit -m "backup before work $(date +%Y%m%d-%H%M)"

💡 Here is something that happened. Skipped a git commit before a big change once and lost an hour of work in a single shot. The alias I made afterwards is gwip (git add . && git commit -m "wip $(date +%H%M)"). Once before a big task, once after — when this rhythm lands in your hand, ninety-nine percent of accidents recover within a minute.

Rewind vs git restore — which to grab first

Knowing which hand is faster per situation keeps you from hesitating.

Print this table and tape it next to the screen — the next move arrives within a second of an accident.

Case ⑥: Costs suddenly jumped

Start with the four common culprits.

• The conversation grew long; context thickened
• A whole large folder was loaded without trimming
• Opus was left on
• Multiple sessions or sub-agents were running at once

Look at the limit first

> /usage

Session cost, plan limit, activity stats — all at once. /cost and /stats are aliases.

Four ways to bring it down

• Use /compact like breathing: shorter context, lower cost
• Switch simple tasks to Sonnet or Haiku via /model
• Use @filename instead of dragging a whole folder in
• /clear between unrelated tasks

Budget cap when running automation

claude -p --max-budget-usd 1.00 "your prompt"

ℹ️ Official CLI option names can change between versions — confirm current flags with claude --help.

Three patterns that blow up costs — know them before they hit

Looking at the cases of people who got surprised by cost spikes, three patterns dominate.

1. One line that says "look at the entire codebase" — loading a whole folder into context jumps tokens by tens of thousands instantly. Narrow with @needed_file instead.
2. An automation left running overnight — infinite loops at 3 AM eating the monthly limit in a day are not unheard of. Always attach --max-budget-usd and an iteration cap.
3. Forgetting to switch off Opus mode — once raised, simple tasks under Opus cost five times more. Check /model often.

💡 Here is something that happened. Someone emailed me, "my limit is draining fast." We checked together — an automation script was stuck in an infinite loop, repeating the same task once per second for eight hours. A month's allowance gone in a day. Automation always wants both an exit condition and a budget ceiling.

Case ⑦: Permission prompts come up too often

Fix ㉠ · Always-allow your common tools

> /permissions

In the permissions screen, set specific tools to Always Allow.

Fix ㉡ · Auto-accept file edits

Shift+Tab → Auto-Accept Edit Mode

For the current session, file-edit prompts get auto-approved.

Fix ㉢ · Memorise the modes in a sentence

• Default (Ask): safest for first use or critical work
• Plan Mode: review the plan only, no file edits
• Auto-Accept: speed first for trusted work

⚠️ --dangerously-skip-permissions bypasses every permission check. Don't use it outside an isolated container. You can edit system files by accident.

💡 Here is something that happened. A user fed up with permission prompts kept running with --dangerously-skip-permissions and a month later asked me about "files that disappeared somewhere." Once you turn off the safety entirely, you can't trace what happened. The answer to "too many permission prompts" is not turning permissions off — it's adding the tools you commonly use to Always Allow.

A small table to pick a permission mode by situation

The three modes mapped onto situations so the hand doesn't fumble.

Pick once at the permission screen and the choice holds for the session. "Allow everything every time" is worse than "decide once per project."

Case ⑧: Korean text breaks (mojibake)

Happens when the terminal isn't using UTF-8.

macOS · Linux

In .zshrc or .bashrc:

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

Add and run source ~/.zshrc. Also check the terminal app's own setting:

• iTerm2: Preferences → Profiles → Terminal → Character Encoding → UTF-8
• macOS Terminal: Preferences → Profiles → Advanced → Text Encoding → Unicode (UTF-8)
• VS Code terminal: uses UTF-8 by default in most cases

Windows · WSL

sudo locale-gen ko_KR.UTF-8

💡 Here is something that happened. Spent an hour chasing broken Korean inside WSL until I added LANG to .bashrc. It snapped right after. Now it is the first line I add on any new machine. When Korean breaks, Claude's answer also looks broken — the terminal is to blame ninety-nine percent of the time, not the tool.

Case ⑨: When you lost the context

A session dropped or the terminal closed and reopened.

Fix ㉠ · Continue the previous session

claude --continue                       # the latest one
claude --resume                         # pick from a list
claude --resume housing-research-2026Q2 # straight to a name

Fix ㉡ · Name important sessions in advance

> /rename housing-research-2026Q2

Fix ㉢ · Information that must survive cuts goes to CLAUDE.md

# Current work
- Goal: 2026 Q1 market competition report
- Done: A and B company analysis
- In progress: C company analysis, comparison table
- Reference folder: research/competitors/

💡 Here is something that happened. A user mid-week-long project lost every session when the laptop died. But because they had the habit of writing progress into CLAUDE.md, opening a new session and saying "read CLAUDE.md and tell me where I left off" got them back in five minutes. Sessions are volatile memory; CLAUDE.md is disk memory.

A three-layer safety net for context

Run sessions, CLAUDE.md, and git commits together — any accident leaves a five-minute return path.

Leaving all three lines beats leaving none by roughly two-fold safety. The cost is under a minute per task.

Case ⑩: Code changed far more than expected

You said "small fix" and Claude touched unrelated files.

• ① Stop now: Ctrl+C or Esc
• ② Rewind: Esc Esc or /rewind
• ③ Inspect and restore via git

git status                # changed files
git diff                  # detailed diff
git restore path          # restore one file
git restore .             # undo everything

• ④ Use Plan Mode as prevention: before big work, Shift+Tab twice or claude --permission-mode plan
• ⑤ Narrow the instruction: "only touch the login function in auth.js, leave other files alone," "don't refactor — only fix the bug"

💡 Here is something that happened. A backend developer said "fix this one bug" and Claude said, "while we're at it let's tidy up too" and edited thirty files. Luckily git was clean, so git restore . rolled everything back in one line. "While we're at it" is a friendly phrase from Claude — and the start of an accident for the user. Keeping Plan Mode on is the safest preventative measure.

Case ⑪: Asked for partial edit, got a full rewrite

You asked for a small text edit and the document got rewritten from scratch. Three steps and it's resolved.

• Rewind immediately with Esc Esc or /rewind
• Narrow the scope and retry: "Only soften the sentence in the second paragraph that starts with 'However.' Don't touch anything else."
• For larger work, use Plan Mode first — get Claude to show "where and how" it would change before any file moves

Case ⑫: Searches in Korean only — results feel thin

State the search language explicitly.

"Search English and Korean sources and combine them"
"Search English first; summarise the gist in Korean"
"Global trends in English, domestic context in Korean"

If you don't specify, Claude tends to follow the Korean conversation context and search mostly Korean.

Recommended primary language by domain

The weight of information leans differently per field. Keep this table at hand and stop hesitating.

💡 Here is something that happened. "Summarise the latest React patterns" in Korean returned blog posts from two years ago. Switching to "search English first; only post-2025 articles" made the result a level deeper. "Language" affects the time axis of the search results too — Korean material trails the global conversation by 1–2 years.

Case ⑬: A package the AI recommended looks suspicious 🖥️ Developer

What is slopsquatting

When a model confidently recommends a non-existent package (hallucination), an attacker pre-publishes a malicious package under that exact name on npm or PyPI. Claude might recommend react-auth-helper, but it could not exist or might exist as a malicious lookalike.

Four checks before installing

• Inspect on npm first

npm info <package>   # download counts · last update · dependencies

If it was published days ago or has only a handful of downloads, pause and doubt.

• Ask for the source alongside

"Tell me whether this package really exists, with the npmjs.com link and GitHub repo URL alongside"

• Prefer well-known options: equivalent functionality? Pick the older, higher-star package. Prefer Anthropic, Microsoft, Vercel, Meta, and other vetted orgs.
• Inspect the entry point after install

cat node_modules/<package>/index.js | head -100

Five suspicion signals — check the moment you read the package name

If any of these five trips, pause the install and use a human eye.

1. A subtly similar real package exists — react-helmet is real, react-helment recommended. One-letter swaps are the classic slopsquatting pattern.
2. First registered within the last two weeks — npm info's first-publish date too recent? Suspect.
3. Single-digit or two-digit downloads — a genuinely useful library would not have that few.
4. Maintainer is one person with no history — click the maintainer on npm, see whether they have other packages.
5. README is empty or feels auto-generated — serious libraries have non-empty READMEs.

💡 Here is something that happened. In a class a student installed Claude's recommendation react-cool-loader. The real one is react-cool-onload. We caught it via npm info (12 downloads), uninstalled immediately. A one-minute npm info right after install is the first defensive line against slopsquatting.

Case ⑭: Worried about security after Claude has worked 🖥️ Developer

Eight checkpoints before you commit

Security checklist:
□ ① Any hardcoded secrets? (API keys, passwords, tokens)
□ ② User input validated? (SQL injection, XSS)
□ ③ No dynamic code execution? (eval-family)
□ ④ File paths don't pass user input through verbatim? (path traversal)
□ ⑤ Error messages don't leak internals?
□ ⑥ Outbound URL requests check the domain? (SSRF)
□ ⑦ Did dependency packages appear without notice?
□ ⑧ Existing auth/permission logic is not bypassed?

Review hunk by hunk with git add -p

git add . stages everything Claude touched in one go. Use git add -p instead and choose hunk by hunk what to bring in.

git add -p
# y → include  n → exclude  s → split smaller  d → exclude rest of this file  q → quit

Suspicious patterns to memorise

• Files you didn't ask about were also edited → unintended side effects possible
• Existing code was wholesale replaced without comments → hard to see what changed
• Config files like .env or package.json suddenly modified → check env vars and dependencies
• Tests deleted or disabled → existing checks may have been bypassed
• A package you've never seen added → suspect slopsquatting (see Case ⑬)
• Empty catch blocks wrapping errors → exceptions silently swallowed

⚠️ Principle: code Claude wrote deserves the same scrutiny as code from outside. AI authorship does not guarantee safety.

A 3-step flow for fast security review

The eight-item checklist all at once is heavy. When you're tight on time, this 3-step is enough to clear ninety percent of latent accidents before commit.

• Step 1 (30 seconds) — git diff once and ask, "did any file I didn't ask about change?" One unexpected line means stop.
• Step 2 (2 minutes) — open .env, config, and package.json separately. Secrets or new dependencies? Inspect.
• Step 3 (5 minutes) — let Claude check.

Re-review the changes you just made from a security angle.
Hardcoded secrets, injection points, eval-family calls,
direct path use, empty catch blocks, added dependencies — only those six.

This 3-step filters ninety percent of latent accidents pre-commit. Eight when you have time, three when you don't — pick by the weight of the day's work.

💡 Here is something that happened. Someone said "just one-line edit." Claude helpfully created a new .env, moved API keys into it. They committed without noticing. Caught at the git diff review before push. A one-minute git diff before commit is much cheaper than a secret leaked to GitHub.

Appendix A — Six side symptoms that often arrive with the main case

Beyond the 14 cases, six side symptoms come up in classes too. Not as central, but if you don't know them they will eat your flow.

A1. "It answers but the Korean feels off"

Conversation began in English then shifted to Korean? Claude tends to mix the two. Add this to CLAUDE.md.

# Output language
- All replies in Korean
- Code comments in Korean too
- Only commands and filenames stay in English

A2. "Folder auto-detection isn't working"

If claude was launched from outside the project root, the auto-detect range narrows. Always cd to the project root before starting. Starting one level above leaves Claude unsure what it's looking at.

A3. "Terminal colours look broken"

TERM is wrong.

echo $TERM    # not xterm-256color? suspect
export TERM=xterm-256color

A4. "Pasting doesn't paste"

Common in WSL or SSH. Clipboard tools (xclip, pbcopy, wl-copy) missing or unconfigured. macOS by default; WSL via clip.exe and friends.

A5. "MCP server keeps disconnecting"

> /mcp

If status reads disconnected, check that MCP's underlying stack (Node, Python, OS permissions). About half resolve via reconnect alone.

A6. "Skills or sub-agents aren't recognised"

Skill files must follow .claude/skills/<name>/SKILL.md. Folder name and file name must be exact, and frontmatter name must match the folder name.

💡 The six side symptoms aren't as common as the main 14, but they take longer when they hit. Bookmark this once and the next time the same symptom arrives, the branch jumps within a minute.

Appendix B — Environment-specific quirks

OS, terminal, and shell combinations make the same symptom appear in different shapes. Common environment-specific quirks gathered here.

B1. macOS

• Homebrew vs nvm conflict: with both, which node returns multiple, and shells land on different versions. Add nvm use to .zshrc, or remove the Homebrew node — cleanest.
• "Claude isn't responding" can be a system permissions issue. Add the terminal app to System Settings → Privacy & Security → "Full Disk Access."

B2. Windows + WSL2

• Path confusion is the most common accident. WSL /home/user is not the same as Windows C:\Users\user. When asking Claude to work, stay inside WSL paths (starting with ~) — fewer accidents.
• I/O speed: /mnt/c/ is roughly ten times slower than /home/. Big work belongs under /home/.
• WSL clock drift: after sleep, time can skew, breaking auth-token validation. sudo hwclock -s to sync.

B3. Linux desktop / server

• SSHing to a remote server to run Claude Code makes the auth flow trickier. Authenticate on a local machine and copy ~/.claude.json over via SSH — usually faster.
• Broken colours inside tmux/screen: add set -g default-terminal "screen-256color" to ~/.tmux.conf.

B4. Inside a Docker container

• Containers often miss node or carry an outdated version. Base on node:20 or newer in the Dockerfile. The native installer doesn't need Node, but Docker base images often include Node anyway for build tooling.
• If auth flow stalls inside the container, authenticate on the host first, then mount ~/.claude.json into the container as a volume.

B5. Corporate network / VPN

• A VPN blocking the OAuth callback URL is the most common cause of auth loops. Disable VPN to authenticate, then re-enable.
• With a corporate proxy, set HTTPS_PROXY and HTTP_PROXY env vars so Claude can reach external APIs.
• If npm/PyPI access is blocked by corporate policy, package install will hang indefinitely. Pinning a mirror registry URL into CLAUDE.md helps.

💡 Environment quirks could fill a book, but the five above account for about eighty percent of the questions I've seen in classrooms. Marking which environment you live in lets the next stumble jump straight to the right branch.

A one-line diagnostic tree across the 14 cases

Reopening the cases in the heat of a stall is too much. Use this tree to land a branch in one line.

What is stuck?
├─ The command itself doesn't run ───────── Case ①
├─ Login fails ──────────────────────────── Case ②
├─ Works, but very slow ─────────────────── Case ③
├─ Result is unsatisfying ───────────────── Case ④
├─ A file got changed wrongly ───────────── Case ⑤·⑩·⑪
├─ Cost / limit drops fast ──────────────── Case ⑥
├─ Worried about permissions / security ── Case ⑦·⑭
├─ Korean / encoding broken ─────────────── Case ⑧
├─ Lost session / context ───────────────── Case ⑨
├─ Search results feel thin ─────────────── Case ⑫
└─ A recommended package looks off ──────── Case ⑬

Print and tape it next to your screen, or drop a one-liner into CLAUDE.md — the next stall jumps to the right branch within a second.

A one-page prevention checklist

[ Before ]
□ Did I cd into the working folder? (cd ~/Documents/my-project)
□ For important work, did I git commit?
□ Does CLAUDE.md hold project rules?
□ Is the current model the right one? (/model)
□ Did I check the limit and budget? (/usage)

[ During ]
□ Is the instruction narrow enough?
□ Am I asking for too much in one go?
□ When the breath got long, did I /compact?
□ When something looked off, did I Ctrl+C right away?
□ Did I leave a git commit / name (`/rename`) before risky work?

[ After ]
□ Did I check what changed? (git diff)
□ Are the tests passing?
□ For an important session, did I name it? (/rename)
□ Did I add a one-liner to CLAUDE.md for the new rule I learned?
□ For security-sensitive change, did I clear Case ⑭'s checklist?

Seven habits one step beyond the ER

For people who survived the first few days in the ER, the next stage. Once these seven habits land, half of the 14 cases here are pre-empted. Don't try to acquire all seven at once. Pick one this week.

1. git commit right before big work — the one-line shield

The single most effective line. ER visits drop by half. Make it an alias and the hand catches it faster.

alias gwip='git add . && git commit -m "wip $(date +%H%M)"'

gwip once before each task is enough. Format broken, message thin — fine. As long as a rollback point exists, it's insurance.

2. /compact once every 30 minutes — a rhythm that doesn't break the breath

Keeps context light without snapping the breath. Press it too often and the core context flies away; too late and replies slow. Thirty-minute intervals were my balance point.

3. Replace "improve" / "refactor" with concrete verbs

"Improve," "refactor," "optimise" — three vague, dangerous words. Translate them.

• "Fix only the NullPointerException in this function. Don't touch anything else."
• "Replace the for-loop with forEach. Logic identical."
• "Translate only the error message strings to Korean. Leave error codes."

Concrete verb + scope limit + what stays — three beats, almost no accidents.

4. One progress line in CLAUDE.md

Disk memory that lets a fresh session return in five minutes. Add this at the end of each task.

# Current progress
- Last work: 2026-05-06 auth module refactor
- Next: token-expiry auto-refresh logic
- Stuck on: timezone handling in expiry comparison

5. Always a budget and exit condition for automation

Infinite-loop prevention. With claude -p automations, attach all three.

• --max-budget-usd 1.00 (budget cap)
• A maximum iteration count (explicit counter inside the script)
• Exit conditions (clear termination on both success and failure)

6. Run npm info once on every new package

First defensive line against slopsquatting. With Case ⑬'s five suspicion signals on hand, you'll judge safety in a minute.

7. Suspicious changes get reviewed line by line with git add -p

Treat code Claude wrote like outside code. Don't git add . everything in one shot. git add -p and pick hunks — this habit prevents the bigger accidents downstream.

💡 Here is something that happened. Last session of a course, someone said, "I rolled back about half of what Claude built this week with git." It sounded deflating at first, then they finished with, "but because I could roll back, I felt safe enough to keep trying." The goal isn't fewer mistakes — it's faster recovery from mistakes. That is why the ER manual exists.

Before you close this chapter

• Bookmarked the case I hit this week among the 14
• Copied the diagnostic tree onto my desk or into CLAUDE.md as a one-liner
• Skimmed the Before / During / After checklists
• Picked one of the seven ER habits to acquire this week

In chapter 13 Debugging: when an error appears we look at the first minute after meeting an error message — how to keep the breath before reaching the ER. The ER is the last line; the first minute is what keeps you from getting there.

💡 If nothing untangles: /doctor from inside Claude Code for an install diagnostic, /bug to report directly to Anthropic. In Korean communities, GitHub Discussions or local Slack channels tend to be the fastest path — someone who hit the same symptom probably has the answer already.

💡 One last line — visiting the ER often during the first few days is normal. People who have used Claude Code for a month or more rarely open this page anymore; instead, an "ER manual" of their own grows inside their CLAUDE.md. The ER is a chapter you graduate from.

13. When Errors Hit — Half Is Staying Calm, Half Is Having a Method

A three-step workflow for not falling apart when errors appear.

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

The First Thing to Do When an Error Hits

When an error appears, what you need to do is show it — not understand it. Understanding comes second.

Copy and paste the full error message

I'm getting this error:
TypeError: Cannot read property 'name' of undefined
at UserList.render (src/components/UserList.js:23:18)
at processChild (/node_modules/react-dom/cjs/react-dom-server.node.development.js:4019:14)
...

Key point: don't trim it. For long errors, the actual cause is often toward the bottom. Claude can handle length.

Show it as a screenshot

For UI breakage, layout problems, or anything that's hard to describe in words — capture the screen and paste it with Ctrl+V directly in the chat. Even for terminal errors, sometimes a full-screen screenshot is faster than copying text.

Describe the situation in words

When there's no error message and it's just "it doesn't work," include these three things:

Since when: "started after I added the login feature yesterday afternoon"
What triggers it: "when I click the login button"
What happens: "the screen goes white and nothing shows"

These three elements dramatically increase how fast Claude can narrow down the cause.

💡 Here's something that actually happened. A student next to me had been wrestling with a TypeScript error for two hours. They were searching Stack Overflow after reading the error message. I was watching from the side and said "just paste it into Claude." Thirty seconds later: "the type of this variable is string | undefined and there's no handling for when undefined comes in." A two-hour problem solved in thirty seconds. Their first reaction was "why didn't I do that from the start?"

When There's No Error Message: Only Symptoms

"It just doesn't work" is the hardest case. Especially "it worked yesterday, doesn't work today" — two approaches for finding the cause.

Approach ①: Check what changed most recently

Show me the diff for the files that were just changed.
Then estimate which of those changes could be causing the issue.

Knowing what changed just before the error started is the starting point for finding the cause. Even if you can't remember, Claude can read git diff or the change history.

Approach ②: Roll back to when it worked

/rewind

or

Esc Esc (twice)

Go back to the working state, then re-apply changes one at a time to find the point where it breaks.

Approach ③: Narrow the scope

If only the login function is broken, check whether registration works first.
Then add a console log to verify whether the login API call itself succeeds.

Narrowing the scope is the fastest path to finding the cause.

A Real Example: Walking Through a "White Screen" Bug

Here's how a debugging conversation actually flows.

Initial report

[Situation]
When I refresh the product list page, I get a white screen.
The dev server is running, and the browser console shows this error:

TypeError: Cannot read properties of undefined (reading 'map')
at ProductList (src/components/ProductList.tsx:23:19)

[Request]
Before making any changes, read the relevant files and summarize
the possible causes of this error in two or three hypotheses.

Asking for the analysis

Which of those hypotheses has the highest probability,
and what file or command would confirm it?

This is the step that makes Claude narrow down the cause before fixing. State values, API timing, and data structure problems tend to get caught here.

The minimal fix

Fix only the most likely cause.
Don't change the UI structure or do any refactoring.
Apply only the smallest change that stops the white screen.

"Smallest change" is key. Changing multiple things at once means you can't tell which fix worked.

Requiring verification

After the fix, confirm these three things:
1. The product list page renders correctly in the dev server
2. The error is gone from the browser console
3. It doesn't break when the product list is empty (empty array test)

The most important thing in a bug fix request isn't "fix it" — it's clearly stating what success looks like.

When the Same Error Keeps Coming Back

If an error was fixed but came back, the approach needs to change.

Record the pattern in CLAUDE.md

Add to CLAUDE.md why this error happened and how it was fixed,
so next time we run into the same situation we can avoid it immediately.

Example:

# CLAUDE.md addition
## Common Error Patterns
- Dates: always use dayjs library (moment.js banned)
- API responses: always use Optional Chaining (?.) before accessing
- Images: use '/images/...' path for public/ folder, not './images/...'

As this accumulates, CLAUDE.md becomes an error reference for the project.

New session + essential context only

When the conversation gets long, Claude can get stuck trying the same direction repeatedly.

/quit   # exit current session
claude  # start fresh

Read @CLAUDE.md.
I'm having a recurring token expiration error in src/auth/LoginForm.tsx.
Try a completely different approach from what's been tried before.

A fresh perspective from a new session is effective.

💡 Here's something that actually happened. A student tried to fix the same error across three sessions and it kept coming back. Looking at the conversation history, Claude was attempting the same direction every time. Opening a new session and saying "everything I've tried hasn't worked, look for a completely different cause" — it found a different root cause immediately. If the same direction appears for a third attempt, that's a signal there's a different underlying cause.

Common Debugging Mistakes to Avoid

Mistake 1: Spending time trying to understand the error first

There's a tendency to analyze the error message before asking Claude. Do the opposite. Show it before understanding it, then understand Claude's explanation afterward. Much faster.

Mistake 2: Summarizing the error message

"I'm getting a type error" is far less useful than the full error message. Summarizing loses information.

Mistake 3: Requesting new features while errors are active

Adding new code on top of broken code means new code piles on a broken foundation. Tracing the cause later becomes twice as hard. Fix errors first, then new features.

# Pattern to avoid
[error present]
→ "now add the payment feature"
→ "now add email notifications"
→ errors get mixed in, impossible to trace root cause

# Correct pattern
[error present]
→ "fix this error first"
[error resolved]
→ "now add the payment feature"

Mistake 4: Trying the same method more than twice

If the same method doesn't work twice, the third attempt should be different.

> This method didn't work twice.
  If there's a completely different approach, suggest it.
  Consider switching to a different library if needed.

Quick Error Reference by Type

Knowing common error patterns in advance speeds up the first response.

Error Types: Clear vs Silent

Errors come in two main forms.

Clear errors (red messages)

Red text in the terminal or browser console. They have information, so they're actually easier to handle. Copy the whole thing and paste it to Claude.

Here's the full error:
[paste full error message]

Before fixing it, explain the possible causes in 2-3 hypotheses.

Silent errors (symptoms only)

"The button click does nothing," "numbers look wrong," "it's slow" — symptoms without error messages. When this happens, describing the phenomenon precisely is the first step.

No error messages, but here's what's happening:
- Clicking login button produces no visible response
- Nothing in the console
- No API requests visible in the network tab

Check whether the click event is properly connected.

Observing the phenomenon from multiple angles and writing it out helps Claude narrow down the cause much faster.

The Power of Documenting Errors

The difference between moving on after fixing an error and leaving a one-line record shows up three months later.

How to document:

Now that this error is fixed, add to CLAUDE.md:
- Error type: [error name]
- Cause: [what caused it, one line]
- Fix: [how it was fixed, one line]
- Prevention: [how to avoid this error going forward]

Example:

# Common Errors
## undefined.map() error
- Cause: rendering attempted before API data loads
- Fix: add Optional Chaining or early return
- Prevention: always initialize array data with an empty array as default value

As this builds up, CLAUDE.md becomes the project's error guide. New sessions read this guide and the same errors happen less often.

Debugging Prompt Template

When stuck, fill this out and send it as-is.

[Symptoms]
- 

[Since when]
- 

[How to reproduce]
1. 
2. 
3. 

[Error message]
```
paste full error here
```

[Request]
First read the relevant files and summarize possible causes in max three hypotheses.
Then start with the most likely one, applying the smallest possible change first.
Include the verification steps after the fix.

Three Principles That Speed Up Debugging

Principle 1: Show first, understand later Trying to understand an error before asking Claude doubles the time. Show it first.

Principle 2: Ask scope-narrowing questions "Why doesn't it work?" vs "confirm that only the login is broken" — the second gets faster answers. Questions that narrow scope produce faster answers than broad questions.

Principle 3: Fix one thing at a time Changing multiple things simultaneously means you can't tell which fix worked. Slower-looking, but actually faster overall.

Before You Close This Chapter

• Practiced the habit of copying the full error message and sending it to Claude immediately
• Wrote an error description using all three elements: "since when / what triggers it / what happens"
• Bookmarked the debugging prompt template (ready to use when stuck)
• Left a one-line record in CLAUDE.md after fixing an error
• Tried the new session + essential context approach for a repeating error

The next chapter (14 Useful Features) covers features that make Claude Code more comfortable beyond error scenarios — image input, voice, auto-recovery, and permission settings.

What Claude Does Well vs What You Need to Do

Splitting responsibilities between Claude and yourself in debugging produces better outcomes than handing everything over.

What Claude does well

• Decoding and explaining error messages
• Recognizing the same error pattern across similar cases
• Listing possible causes
• Analyzing code in specific files
• Writing verification code after a fix

What you need to do

• Actually test "did this work?"
• Judge "is this fix the direction I want?"
• Explain the business context behind why this is the environment for this error
• Check "does this solution affect other parts?"

Throwing an error at Claude and saying "fix it" leads to repeating the same errors. Understanding the cause together means you're faster the next time.

Frequently Asked Questions

"The error message is too long to copy all of it"

Copy all of it anyway. In most errors, the real cause is in the middle or bottom. With only the first line, Claude has to guess — and guessing means more wrong turns.

"I fixed the error but it came back"

Two possibilities: the fix was incomplete, or there's a different underlying cause. Try opening a new session and saying "I fixed it this way but the error came back. Look for a different cause, not the approach tried before."

"I don't understand English error messages"

That's fine. Paste them in as-is. Claude handles the interpretation. Trying to understand them yourself before asking can actually lead to missing the point.

"Errors are piling up — which one do I fix first?"

When dozens of build or type errors appear at once, ask like this:

Too many errors. Here's the full list.
Analyze which order to fix them in, and which errors are caused by other errors.
Start with the most root-level cause.

Errors are often a chain reaction. Fixing one root cause can make twenty errors disappear simultaneously.

"The function works but behaves incorrectly"

"It works but it's wrong" is tricky because there's no error message. Use the "intended vs actual" format:

The login feature works but behaves incorrectly.
Intended: after successful login, redirect to /dashboard
Actual: after successful login, stays on /login page

Look at the code and find why the redirect isn't happening.

"Intended vs actual" is one of the fastest formats for Claude to locate a bug.

14. Useful Features to Know — Things That Get Easier the More You Use Them

No need to know all of these from day one. These are tools you pull out when the right moment comes — and over time, you start reaching for them naturally.

Source: Permission Modes — Anthropic Docs

Showing Images Directly

Screenshots and design mockups can be sent to Claude directly. Visual problems or visual requirements that are hard to describe in words work much faster as images.

Three ways to paste:

Ctrl+V          : paste image from clipboard directly
Drag and drop   : drag an image file into the terminal window
File path       : "@screenshot.png look at this and analyze it"

Supported formats: JPEG, PNG, GIF, WebP (max 5MB per file)

The first time I used this, the first thing I tried was pasting an error screen capture. Something that would take three lines of text to describe was handled with one image.

Patterns That Work Well for Image Requests

"Image only" vs "image + what to look for" produces dramatically different results.

Less effective:
[paste image with nothing else]

More effective:
[paste image]
"Find why the text overlaps on mobile in this screenshot.
 Explain the cause first before making any changes."

Three situations where images really shine:

• UI breakage: layout, overlap, and color misalignment are faster with images than text
• Error screens: error popups that are hard to copy can be sent as-is
• Design implementation requests: margins, font sizes, and color hierarchy all in one

💡 Here's something that actually happened. In a workshop, a student spent twenty minutes trying to describe a mobile layout issue in text. "The button overlaps" — and Claude kept asking follow-up questions because it didn't know how it overlapped. After taking a screenshot and pasting it, thirty seconds later: "the flex container is missing a min-width, causing overflow." Twenty minutes became thirty seconds.

Explaining with Your Voice

For long explanations where typing is a burden, you can speak instead. Voice input lives in the iOS Claude app and on the web (claude.ai/code) via the microphone button. (The terminal Claude Code has no dedicated /voice slash command.)

Tap the microphone → speak → it's transcribed and sent

Supports Korean and many other languages. Mixing voice and typing in the same message works too.

Where voice input shines: describing "what kind of feeling" you want without needing exact filenames or variable names. Then follow up with typing for precision.

By voice:
"The login screen looks too complicated. I want to move social logins to the bottom and keep only email at the top."

Follow up by typing:
"Scope: only src/app/login/page.tsx. Don't touch other files."

When You Don't Like What Just Changed: Esc Esc

Claude automatically saves a snapshot just before modifying files. Press Esc twice in a row to return to that pre-modification state.

Works automatically without any configuration. No need for Git.

Press it immediately when:

• Claude started modifying files you didn't ask it to touch
• The design change went in a direction you didn't want
• Trying to fix an error created more errors

Esc Esc goes back one step. For going back multiple steps, /rewind is the right tool.

Going Further Back: /rewind

Rewinds both the conversation history and file changes to any earlier point.

/rewind → view list of restore points → select the one you want

If Esc Esc is "just one step back," /rewind is "any point you choose."

After rewinding, check the current state before starting new work — don't jump straight to a new request.

> /rewind
(select point)
> Show me which files are currently in a modified state

Two Ways Context Gets Managed Automatically

Auto-compact

When context approaches its limit, Claude automatically trims older content. Works without any configuration.

But auto-compact leaves what Claude judges to be important. Context you care about might get cut. For important sessions, manually running /compact focus on [specific context] before hitting 70% is safer.

Auto Memory

During work, Claude automatically saves important-seeming information to memory. New sessions can read this memory to pick up context.

Check or edit saved memories with /memory.

But relying on Auto Memory for project rules is risky. Critical rules belong in CLAUDE.md where they're always in scope.

Controlling Thinking Depth: /effort

For difficult problems or complex design decisions, you can tell Claude to think more deeply.

/effort low     → simple tasks, fast answers
/effort high    → complex problems, deeper reasoning
/effort xhigh   → Opus 4.7 only, deepest thinking

Available levels: low · medium · high · xhigh (Opus 4.7 only) · max. Which levels are usable depends on the current model — run /effort once to see what your model exposes.

Running /effort without an argument opens an interactive slider to choose the level.

Deeper thinking isn't always better. Using xhigh for a simple text correction or file rename just makes things slower.

Permission Modes: Controlling What Claude Can Do

Controls how Claude asks for confirmation before modifying files or running commands.

How to apply:

# At session start
claude --permission-mode acceptEdits

# During a session
/permissions

💡 Here's something that actually happened. Working on a large project in WSL2, permission requests for every file broke my rhythm. Switching to acceptEdits mode meant file edits were auto-approved and only shell commands needed confirmation. Speed improved significantly. But for new projects or team environments, I still always start with default. The sequence is: first understand what's being allowed, get comfortable, then change modes.

Extended Features: Research Preview Stage

These features are still available to select users or in preview. You don't need them right now, but knowing "this is the direction things are heading" is useful.

Computer Use: Claude looks at your screen directly and operates the mouse and keyboard. Used for GUI testing and repetitive click automation. (Research Preview, macOS priority) · Note: Computer Use is a Claude API tool — it's a separate product from the Claude Code CLI itself.

Remote Control: Scan a QR code and you can continue the current Claude Code session from your phone. For sending instructions or checking results while on the move.

Chrome Integration: Claude controls the Chrome browser directly. Used for webpage testing, extracting specific data, and automated form filling.

Scheduled Execution (Routines · /schedule): A specified prompt runs automatically at a set time or interval. Used for scheduled checks, status monitoring, and recurring report generation. (/loop is not a built-in — it ships as part of some plugins, e.g. superpowers.)

Quick Reference: What to Use When

The question "what should I use right now?" answered directly.

Knowing what to reach for in a given situation matters more than memorizing all the features.

Usage Frequency from Real Experience

After six months of actual use, here's how each feature actually gets used:

Daily: image input, Esc Esc

A few times per week: manual /compact, adjusting /effort

As needed: /rewind, iOS/web voice input, permission modes

Special situations: Computer Use, Remote Control, Chrome integration, Routines (/schedule)

Trying to learn all of these from the start means ending up using none of them. Begin with image input and Esc Esc first — those cover the most common cases.

The Relationship Between Features

Two axes help sort out when to use what.

Axis 1: When something went wrong vs making good things better

For when something went wrong:

• Esc Esc: Claude just made a change you don't like
• /rewind: need to go back multiple steps
• Ctrl+C: need to stop something running right now

For making things that are already working better:

• Image input: communicate faster and more precisely
• Voice input on iOS / web: explain without typing
• /effort high: tackle harder problems more deeply

Axis 2: This session vs across sessions

Affects the current session:

• /compact, auto-compact: context management
• /effort: thinking depth
• Esc Esc, /rewind: mistake recovery

Persists across sessions:

• CLAUDE.md: project rules
• Auto Memory: automatic recall
• Git commits: code history

With these two axes in mind, when you encounter a new feature you can quickly classify "which side does this belong to?"

Before You Close This Chapter

• Tried pasting a screenshot with Ctrl+V into the chat
• Pressed Esc Esc and experienced returning to a pre-modification state
• Ran /rewind and saw the list of restore points appear
• Ran /permissions or /effort once to see current settings
• Scanned the quick reference table and picked a feature for a current situation

The core sections of this guide end here. The chapters ahead cover more advanced features — MCP, Hooks, Worktrees, and more. With the foundation you've built to here, the rest follows naturally.

15. When the Prompt is Wrong, the Model Doesn't Matter

When results disappoint, the instinct is to blame the model. Most of the time, it's the prompt.

In workshops, the first question I ask is: "Did you have a moment this week where Claude's output wasn't what you wanted?" Nearly everyone raises their hand. Then I ask: "Did you re-read your prompt?" Hands go down.

That moment is the most important learning point. A prompt is code. Just as a compiler won't ignore a missing semicolon, Claude fills gaps in context with guesses. When those guesses land, it looks like genius. When they miss, it looks like a failure. Neither is about the model — it's about information.

This section covers what belongs in a prompt, which patterns break results, and how the same request written differently produces entirely different outcomes.

The gap between someone new to Claude Code and someone two months in isn't model choice. It's whether they include those four elements — one line each.

The 4 Elements: Context · Scope · Examples · Verification

Context — "Why" are you doing this?

Claude doesn't know what project you're working on, where this function lives, or what background you bring. Without context, it produces the most generic answer. The most generic answer is rarely the one you need.

Context is where you put the "why." Why does this task exist, where is this code used, what constraints are you operating under.

Bad)  Fix this function.

Good) This function exists to reduce payment failures.
      Network timeouts are common, so we need retry logic.
      It touches external payment APIs, so side effects matter.

💡 Here's something that actually happened. During a session, a student typed "fix the login bug" and watched Claude rewrite the entire login function. What the student wanted was a single line of email validation. Claude, acting in good faith, decided to "improve" the password hashing logic while it was there. That day the student started writing every prompt with both "what I want" and "what I don't want." Results changed immediately.

Scope — How far may Claude go?

Without scope, Claude touches everything that "looks related." This is the most common reason a task spirals out of control. You ask to fix one file and three are modified. You ask to change logic and the file structure shifts.

Scope is more powerful when it's short and specific.

Good) Modify only validateEmail inside src/auth/login.ts.
      Do not touch any other file.
      Do not change the function signature.

This feels excessive at first. After experiencing scope creep twice, it becomes automatic.

Examples — One input/output pair beats a paragraph

"Make it look like this" over 100 lines of description loses every time to one input and one expected output. Claude is excellent at generalizing from patterns, and a single example pair replaces an entire explanatory paragraph.

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

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

Examples also handle edge cases faster than any description.

Verification — How will we know it worked?

Adding "write the test too" or "run lint until it passes" at the end raises output quality by a noticeable step. Claude includes a self-check in its process.

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

Or) After the change, show me two examples so I can verify myself.

Before / After: Same Request, Different Outcomes

The difference seems exaggerated until you try it.

Prompt Templates You'll Actually Reuse

These are structures I reach for repeatedly. Fill in the blanks.

Template 1 — Add a feature

[Context] This project is building ___ and
[Goal]    I want to add ___ now.
[Scope]   Modify only ___ files.
[Example] Input ___ should produce ___.
[Verify]  After adding, run ___ tests until they pass.

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 external interface (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: These Will Sink Your Output

💡 Here's something that actually happened. I once sent "refactor the auth module" and Claude replaced the JWT library and restructured the middleware. The result looked better but broke the interface other modules depended on, and it conflicted with a teammate's in-progress work. Fixing took 30 minutes. Since that day, refactoring prompts always start with what must NOT change. Listing prohibitions is more effective than listing permissions.

Reinforce with Inputs

When text isn't enough to describe what you need, attach other input types.

These connect naturally with the features from section 14.

Real Example — Same Task, Three Versions

Task: "I want to build a daily report of my stock holdings."

Vague (1/10)

Tidy up my stocks.

Claude doesn't know what "tidy up" means. The result could be a table, text summary, or a chart.

Average (5/10)

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

Format specified, but number of columns, sort order, and handling of empty fields are still unclear.

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 — the 9/10 version needs no post-processing. The 1/10 version needs three more rounds.

One Quick Check Before Sending

Two questions before you hit Enter:

1. "Could someone who only reads this prompt figure out what I want?"
2. "What happens if Claude goes too wide — and is there a constraint to prevent that?"

If both answers are yes, send it.

💡 Here's something that actually happened. At the end of a session a student said: "Writing prompts makes me think harder than writing email." Exactly. A good prompt is an act of clarifying what you actually want — not just for Claude but for yourself. People who write good prompts don't just get better results. They think more clearly about the work.

Before You Close This Chapter

• Pulled up a prompt you sent recently and checked whether it had context, scope, examples, and verification
• Added an explicit constraint ("do not touch X") to at least one prompt
• Wrote one prompt using the After column from the Before/After table
• When a result was unsatisfying, checked the prompt before blaming the model

The next chapter (16 Plan Mode & Safe Recovery) covers something distinct from good prompting: reviewing the plan before execution starts. Even a perfect prompt sometimes precedes a change large enough that you want a preview first. That's what Plan Mode is for.

16. How to Stop Once Before Pressing Execute

"Knowing you can undo" creates the safety to move faster. "Fearing you can't undo" stops experiments cold.

When I first started using Claude Code, I hesitated before large changes. "What if rearranging the folder structure goes too far? What if refactoring the payment module breaks all the tests?" That hesitation slowed experiments — and experiments are what produce results.

Later I understood: the hesitation wasn't a capability problem. It was the absence of a safety net. Now before any large change I use three things: pre-execution plan agreement (Plan Mode), step-by-step rewind (/rewind), and a recovery anchor that survives session gaps (git commit). After adopting all three, "what if this breaks?" stopped being the first thought. "Let's try it" became the first thought.

The reason people hesitate before large changes is almost always the same: "It feels hard to undo if something goes wrong." Plan Mode and Checkpoint make that feeling disappear.

Plan Mode: Plan First, Execute Later

What Plan Mode Does

A mode where Claude shows its plan without touching a single line of files. If you like the plan, you execute. If you don't, you adjust at the planning stage.

Why this matters: mid-execution course corrections require reverting already-modified files. Planning-stage course corrections require reverting nothing.

Activating It

Shift + Tab  (cycles through permission modes until you reach plan)

Or:

claude --permission-mode plan

Or within a session: /permissions → plan

Two Shift+Tabs usually does it initially. Watch the bottom-left indicator to confirm "plan" appears.

When to Turn It On

• Refactoring that modifies multiple files simultaneously
• Data migrations, schema changes (high revert cost)
• Introducing a library or framework for the first time
• Operations with many external API calls (hard-to-cancel side effects)
• Large structural changes on a team codebase

The Plan Mode Workflow

1) Activate Plan Mode (Shift+Tab)
2) "I want to add retry logic to the payment module — show me a plan first"
3) Claude outputs a step-by-step plan — which files, what changes
4) If the plan looks good → return to normal mode and execute
5) If something's missing → add instructions at the planning stage, re-review

💡 Here's something that actually happened. I started a payment module retry logic task without Plan Mode. Claude not only added retry logic but rewrote the entire error handling pattern. The result looked better in isolation, but it changed interfaces other modules depended on, and it conflicted with a teammate's in-progress branch. That afternoon I added Plan Mode to my standard large-change procedure. Catching "oh, it wants to touch that file too" in the planning stage is far cheaper than catching it after execution.

opusplan: Design with Opus, Execute with Sonnet

/model opusplan is an official alias that automatically switches Plan phase to Opus and execution phase to Sonnet.

/model opusplan

Cost structure:

• Plan happens once, briefly (Opus pricing, fewer tokens used)
• Execution runs long (Sonnet pricing, many tokens used)
• Net result: well under half the cost of running Opus throughout

The name signals the intent: let the best model make the design decisions, then hand off execution to a lighter model.

💡 Note: opusplan's Plan phase uses 200K context. The 1M context window doesn't apply automatically. Very large codebases being analyzed may need a separate consideration.

Esc Esc: Undo the Last Thing Instantly

Claude automatically saves a snapshot just before modifying files. No configuration required.

Press Esc twice → restores the immediately previous state

Use this immediately when:

• Files start being modified in ways you didn't intend
• You changed a design and the previous version looked better
• You tried to fix an error and more errors appeared
• You notice the scope expanding beyond what you planned

Anyone who doesn't know git can use this. It's the fastest recovery method available.

💡 Here's something that actually happened. In a class session, a student was changing navigation component styles when Claude started touching the shared layout. Two files had already been modified, and the student had forgotten what the originals looked like. Two presses of Esc brought everything back instantly. "Wait, it really works?" was the response. Since then, Esc Esc is the first shortcut I teach.

/rewind: Roll Back to a Chosen Point

If Esc Esc is "undo the last one action," /rewind rolls back both conversation and code to any point you choose.

/rewind
→ A list of checkpoints appears
→ Select the one you want

Natural language time references work: "before the login UI change," "before the tests were added."

After rewinding, check the current state once before starting new work. Jumping straight into the next task from an unclear state leads to doing things twice.

> Check whether there are remaining changes or a clean state right now

/checkpoint and /undo are aliases for the same command. All three do the same thing.

For moments when you know you want to return to a specific point: an explicit git commit at that moment is the safest bet.

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

Three Recovery Tools Compared

Using all three in combination is the standard practice. Esc Esc for spontaneous reversals, /rewind as an in-session time machine, git as permanent record across sessions.

The Three-Part Safety Net

Before a large task, recall this sequence.

1. git commit: The final safety net that survives even a disconnected session. With a commit in place, any situation is recoverable.
2. Plan Mode: Agree on the approach before execution — prevents big surprises from ever happening.
3. Checkpoint / /rewind: Small mistakes during execution get recalled immediately.

After having all three, the phrase "large change" stops feeling heavy. Experiment speed becomes result speed.

Full Workflow: Large Refactor from Start to Finish

1) Check git status → commit all changes
   "I'm starting changes from here. Commit to a clean state first."

2) Activate Plan Mode (Shift+Tab)
   "Refactor all of src/payment/ to include retry logic structure.
    Show me only the plan — what files, what changes."

3) Review plan → if scope is larger than expected, narrow it → return to normal mode

4) Begin execution → Claude modifies files
   If something feels off mid-way: Esc Esc to revert last step

5) Verify result → check tests, build

6) OK → git commit
   Not right → /rewind back to the starting point

Once this sequence is in your body, the phrase "large change" no longer triggers automatic hesitation.

Common Mistakes

Before You Close This Chapter

• Pressed Shift+Tab and confirmed the Plan Mode indicator appears at the bottom
• Started a small test change and pressed Esc twice to verify recovery works
• Typed /rewind and saw what a checkpoint list looks like
• Made a git commit before a large task at least once as deliberate practice

The next chapter (17 Statusline & Cost Visibility) covers something equally important alongside planning and recovery: making cost visible. Experimenting safely requires seeing what you're spending.

17. Costs Must Be Visible to Be Controlled

No one drives on the highway without a dashboard. The terminal is no different.

In my first month on the Max plan, a limit-warning email was the first moment I asked "how much have I used today?" Working deep in a task, you don't notice tokens accumulating. Then one day responses slow down, or the end-of-month bill surprises you. Both happen because things were invisible.

The fix is simpler than any optimization strategy. Put the current model, token usage, and session cost on a single line at the bottom of the terminal. That one line means you glance at it unconsciously before starting a big task. That unconscious glance, repeated every day, reshapes the monthly bill.

You can only control what you can see. To control cost, start by making it visible.

The Statusline: A Cost Dashboard at the Bottom of Your Terminal

The persistent one-line status display at the bottom of the Claude Code terminal is the Statusline. You might not consciously notice it at first, but once you start looking, it becomes automatic.

Default items:

It appears automatically. No setup required.

What Happens When You Stop Looking

Pairing "ignoring the Statusline" with "watching it" makes the difference concrete:

The difference is simple: what you see, you act on. What you don't see, you let slide.

💡 Here's something that actually happened. During a class session, a student realized — after two hours of work — that the model had been Opus the entire time, not Sonnet. It was a subscription plan so there was no direct extra cost, but the realization that the model had been running without any awareness was unsettling. After that, the first thing the student checked at the start of each session was the model indicator. Deliberate choices require visible information.

/statusline: Customize What You See

If the defaults aren't enough, or you want to add more, open the interactive menu with /statusline.

/statusline

You can toggle which items to display:

• Model · token usage · session cost · current mode
• Current directory · git branch · elapsed time
• 5-hour usage window · 7-day usage window

Color and emphasis settings are also available. Settings persist in ~/.claude/settings.json or the project .claude/settings.json.

Plugins can also define subagentStatusLine to render a separate statusline for subagents.

/usage: When You Want the Full Picture

/usage (alias: /cost, /stats) is an on-demand detailed report command. Statusline is always-on; /usage is called when needed.

The standard flow: Statusline signals something unusual → /usage for precise diagnosis. Statusline gives you the sense that "something looks high" — /usage shows you exactly where and how much.

A Cost-Reduction Workflow

Responding to these four triggers while watching the Statusline eliminates 90% of token waste.