Claude Code — The Complete Practical Guide

A hands-on guide to Claude Code, Anthropic's official CLI coding agent, for first-time users — all 30 chapters. From install and your first conversation to permissions, Git, models, Hooks, MCP, Subagents, and team operations.

1. Understanding what Claude Code is first

01Core Concept

Claude Code is not just a chat window. It's an agent-based CLI tool that can read code, execute commands, and modify files from within your project folder.

How Claude Code differs from typical AI chat:

Regular AI chat

Users copy and paste code themselves

Claude Code

Claude reads project files directly

Regular AI chat

Explanation-focused

Claude Code

Can explain, modify, execute, and review

Regular AI chat

Users manually edit files

Claude Code

Claude can propose edits or modify files directly

Regular AI chat

Hard to understand entire project context

Claude Code

Can explore codebase structure

02What is a CLI?

CLI is short for Command Line Interface. In other words, it's a program you use by typing commands in a terminal.

Claude Code is usually run like this:

cd ~/my-project
claude

Then Claude Code runs inside your current project folder.

In other words, Claude Code is not a tool you access from a website. It's a tool that works alongside you in the terminal and project folder where you actually develop.

03What Claude Code can do

Beginners don't need to learn all features at once. At first, understanding these 5 things is enough.

Read code

Analyzes project files (e.g., "Explain this project's structure to me.")

Search code

Finds the location of needed files or functions (e.g., "Where is the login logic?")

Modify code

Edits files directly or proposes changes (e.g., "Add signup input validation.")

Execute commands

Runs tests, builds, linting, etc. (e.g., "Run tests and analyze why they failed.")

Assist with Git

Reviews changes, writes commit messages, prepares PRs (e.g., "Review the git diff for me.")

The important thing is that Claude Code can work with real files and terminal commands. That makes it powerful, but it also means you need to use it carefully.

04Claude Code's 3-layer architecture

Claude Code is easier to understand when divided into 3 main layers.

Extension Layer
- MCP
- Hooks
- Skills
- Plugins

Delegation Layer
- Subagents

Core Layer
- Basic conversation
- Read files
- Modify files
- Execute commands

05Core Layer

This is the basic conversational space. Here, you ask Claude questions.

Explain the structure of this project to me.

Claude reads files, organizes relevant content, and responds.

Beginners can get far just by using the Core Layer well.

06Delegation Layer

This layer divides large tasks into smaller ones. For example, it's useful in situations like this.

Search the entire codebase for authentication-related files,
and summarize any security risks.

This kind of task has a wide scope. Claude Code can delegate exploration or analysis to separate subagents as needed.

Beginners don't need to understand this deeply right now. You can learn about it later when working on larger projects.

07Extension Layer

This layer connects Claude Code to external tools or automates tasks. Key features include:

MCP

Connect external tools like GitHub, databases, Sentry

Hooks

Automatically run commands in specific situations

Skills

Add specialized knowledge needed for specific tasks

Plugins

Deploy configuration and features as packages

Beginners don't need to set up MCP, hooks, or plugins from the start. It's better to first learn the basics: conversation, reading files, and the approval workflow for edits.

08Actual workflow

The most basic workflow for Claude Code looks like this:

Move to your project folder.
Run the claude command.
Ask Claude to read the project.
Receive an explanation.
If modifications are needed, request a plan first.
Review the plan, then ask Claude to make changes.
Verify changes using git diff.

In the terminal, you typically start like this:

cd ~/my-project
claude

Inside Claude Code, you can make requests like this:

Explain the overall structure of this project in a way beginners can understand.
Start by organizing the important folders and files.
Don't modify any files yet.

093 reasons a good first question matters

The request above is a good first question for beginners.

Start by understanding the project

Safe because you don't modify immediately

Identify important files first

Quickly understand the overall structure

Explicitly say "don't modify"

Reduces accidental file changes

10The most important principle for beginners

When starting with Claude Code, it's good to repeat this cycle:

1Request explanation

2Request a plan

3Approve modifications

4Review changes

5Run tests

11Bug fix example

For example, if you want to fix a bug, you'd say:

There's a login error.
Find the related files first and explain the cause.
Don't modify the code yet—just propose a fix plan.

Once you like the plan, you'd say:

Okay, go ahead with the plan you just proposed.
After making changes, summarize which files you modified.

After modifications, always verify like this:

Summarize the changes based on git diff.
Check for any risky or unintended changes too.

12Example prompts ① · ②

When viewing the project for the first time

Assume you're a developer seeing this project for the first time.
1. Project purpose
2. Main folder structure
3. Commands that seem to run it
4. Files to read first
Organize in this order.
Don't modify any files yet.

When searching for a specific feature

Find where the login feature is handled.
Organize the related files and function names.
Just explain the structure—don't modify anything yet.

13Example prompts ③ · ④

When getting a plan before modifying

I want to add signup input validation.
First check the current structure,
then just create a plan for which files to modify and how.
Don't modify files until I approve.

When reviewing after changes

Review what you just modified.
Based on git diff, summarize the modified files, reasons, and any risks.
Also let me know what tests to run if needed.

14Common beginner mistakes ①

Mistake 1. Saying "fix it" right away

Bad example:

Login doesn't work. Fix it.

Saying this makes Claude guess a very broad scope.

Good example:

There's a login error.
Find the related files first and explain the cause.
Don't modify anything yet—just propose a fix plan.

15Common beginner mistakes ②

Mistake 2. Not verifying after file modifications

You must always verify after Claude modifies files.

git status
git diff

Inside Claude Code, you can request this:

Summarize the changes based on git diff.
Check for any unintended changes too.

16Common beginner mistakes ③

Mistake 3. Exposing sensitive information

Be careful with these files:

.env
.env.local
credentials.json
private-key.pem
id_rsa
config/secrets.yml

It's a good habit to tell Claude like this:

Don't read sensitive files.
If needed, just describe what values are required.

17Common beginner mistakes ④

Mistake 4. Assigning large tasks all at once

Bad example:

Refactor the entire project and fix all tests.

Good example:

Find parts that need refactoring first.
Then organize priorities,
and just propose a stage 1 work plan.

Claude Code is powerful, but large tasks are safer when divided into stages.

18Checklist

When using Claude Code for the first time, check these items:

Claude Code is a CLI tool used in the terminal

□

Must run from inside your project folder

□

Claude can read and modify files

□

Always request a plan before modifying

□

Protect sensitive files

□

Check git status and diff after changes

□

Divide large tasks into stages

□

Section 01 · Summary

What to remember from this unit

Claude Code is not just a question-and-answer tool. It's a development agent that can read, modify, and execute commands on code within your project.

Beginners don't need to learn advanced features right away. Just start with this cycle:

Request explanation → Review plan → Approve modifications → Review changes

Following this cycle makes Claude Code much safer to use.

Next unit

Unit 2. Checking prerequisites before installation

2. Verify Pre-Installation Requirements

01Key Concepts

Before installing Claude Code, there are 5 things you should check first.

Operating System

Verify Claude Code can run in your environment

Terminal

Claude Code is a CLI tool by nature, so a terminal is required

Account or Authentication

Using Claude Code requires login or organizational authentication

Project Folder to Work On

Claude Code works best when run from inside a project folder

Safety Habits

Because files can be modified, commands can be executed, and costs may be incurred

02Why It's Needed

Claude Code is not like a regular app where you "install and click to run." You typically use it like this:

1Navigate to your project folder

2Run claude in the terminal

3Log in

4Claude reads your project files

5Claude modifies files or runs commands as needed

That's why checking your environment before installation is critical—skipping it can cause problems.

03Common Pre-Installation Issues

Unsupported Operating System

Outdated macOS, older Linux distributions

Unfamiliar with Terminal

Not knowing where to type commands

Authentication Not Ready

Missing login credentials or Console permissions

Project Folder Not Organized

Claude reads too many files

Sensitive Information Mixed In

Risk of exposing .env, API keys, private keys

Cost Structure Unknown

Failure to manage API usage or subscription limits

Installation itself is not difficult. However, insufficient pre-installation preparation can make your first experience more complicated.

04System Requirements

According to official documentation, Claude Code runs on the following environments.

macOS

macOS 13.0 or later

Windows

Windows 10 1809 or later, or Windows Server 2019 or later

Linux

Ubuntu 20.04 or later, Debian 10 or later, Alpine Linux 3.19 or later

Memory

4GB RAM or more

CPU

x64 or ARM64

Network

Internet connection required

Shell

Bash, Zsh, PowerShell, CMD

Region

Must be in an Anthropic-supported country

This information is current as of writing. Before actual installation, also check the official documentation and run claude --version and claude doctor.

05Checking Your Environment on macOS

On macOS, open your terminal and run the following commands.

sw_vers
uname -m

Expected output looks something like this:

ProductVersion: 14.x.x
arm64

If ProductVersion is 13.0 or higher, you meet the basic requirement. arm64 indicates Apple Silicon; x86_64 indicates an Intel Mac.

06Checking Your Environment in Windows PowerShell

On Windows, open PowerShell and run the following commands.

systeminfo | findstr /B /C:"OS Name" /C:"OS Version"
$PSVersionTable.PSVersion

On Windows, you can use either PowerShell or CMD. Official documentation provides separate installation methods for PowerShell and CMD. For native Windows, it's recommended to install Git for Windows so Claude Code can use Bash tools.

07Checking Your Environment on Linux / WSL

On Linux or WSL, run the following commands.

cat /etc/os-release
uname -m

On Ubuntu, you'll see output like this:

NAME="Ubuntu"
VERSION_ID="22.04"

Ubuntu 20.04 or later satisfies the basic requirement. Windows users can also choose to use WSL and follow Linux installation instructions.

08Preparing Your Terminal

Claude Code runs from your terminal by default. Common terminals include:

macOS

Terminal, iTerm2, Warp, and others

Windows

Windows Terminal, PowerShell, CMD, WSL

Linux

Default Terminal, GNOME Terminal, Konsole, etc.

IDE Users

VS Code Terminal, JetBrains Terminal

Claude Code works with most terminals by default without special configuration. Beginners don't need to set up anything complex at first.

09Basic Terminal Commands

As a beginner, you only need these 3 basic commands.

cd

Change directory

ls

List files in the current folder

pwd

Show current location

On Windows PowerShell, ls and cd work the same way.

10Preparing Your Account and Authentication

Using Claude Code requires authentication. Common authentication methods are:

Claude Pro / Max

Individual users

Claude Team / Enterprise

Team or company users

Claude Console

Users needing API-based billing or organization management

Amazon Bedrock / Google Vertex AI / Microsoft Foundry

Enterprise cloud environment users

For beginners, individual users typically use Claude Pro or Max; team users use their company-provided Team or Enterprise account; developers or organizational users use Claude Console.

11Understanding Cost Potential

Claude Code can incur costs or usage limit impacts depending on how you use it. The following activities can increase usage significantly:

Analyzing Large Codebases All at Once

Reading many files increases context

Long Session Maintenance

Conversation history and file contents accumulate

Analyzing Multiple Test Failures

Command output and retries multiply

Using Subagents, MCP, Plugins

Additional tools and agents consume tokens

Using High-Performance Models

Cost and usage limits vary by model

12Cost Optimization Habits

Beginners don't need to understand cost optimization deeply at first. Instead, develop these habits:

Start with small questions at first.
Don't have Claude read your entire project at once.
Check usage with /cost or /usage commands.
Plan big tasks before asking Claude to execute them.
Use automation features only after mastering the basics.

13Preparing Your Project Folder

Claude Code usually runs from your project root folder. For example, if your project structure looks like this:

my-project/
├── src/
├── tests/
├── package.json
├── README.md
└── .git/

You run it from inside that folder:

cd ~/my-project
claude

14Why Run from Project Root

Understand the Full Structure

Claude can easily find key folders and config files

Check Git Status

git status and git diff are available

Run Tests

Project commands run from the correct location

Clear File Modification Scope

It's clear which files are fair game to modify

Before installation, you can try running pwd, ls, and git status in your project folder. If git status doesn't work, your folder might not be a Git repository.

15Identifying Sensitive Information Files

Claude Code can read your project files. Before installation, check for sensitive files. Be especially careful with these:

.env
.env.local
.env.production
credentials.json
service-account.json
private-key.pem
id_rsa
id_rsa.pub
*.key
*.pem

Before installation, you can check your project using ls -a.

16Protecting Sensitive Information

If you have sensitive files, develop this habit when using Claude Code:

Don't read .env, API keys, private keys, or credentials files.
If needed, just describe what environment variables are required by name.

Claude Code starts with read-only permissions by default and asks for your approval when file editing or command execution is needed. You are responsible for reviewing proposed code and commands before approval.

17Preparing Git

Good Git habits are important for using Claude Code properly. Before installation, verify these commands work:

git --version
git status

If it's not a Git repository, you might see this message:

fatal: not a git repository

If your project is already managed by Git, that's great. If not, it's safer to back up important files or initialize a Git repository before using Claude Code.

18Safe Workflow

The safest workflow for beginners is:

1Check git status before working

2Request a modification plan from Claude

3Approve the modifications

4Review git diff

5Run tests

6Commit

19Pre-Installation Checklist ①

Check the items below, then proceed to the next unit for installation.

My OS is within Claude Code's supported range

□

I can open Terminal or PowerShell

□

I can use basic commands like cd, ls, pwd

□

I have a Claude account, subscription, Console, or company authentication ready

□

I have a project folder to work on

□

I know where my project root folder is

□

20Pre-Installation Checklist ②

Git is installed

□

I've run git status

□

I know where .env, API keys, and credentials files are located

□

I've decided not to let Claude read or paste sensitive information

□

I understand costs or usage limits may apply

□

21Common Beginner Mistakes ①

Mistake 1. Running from just any folder

Bad example:

cd ~
claude

Running from your home folder makes it hard for Claude to understand your project context.

Good example:

cd ~/my-project
claude

Always run from your project root folder.

22Common Beginner Mistakes ②

Mistake 2. Not checking for sensitive files

Bad request:

Read my .env file and fix the settings.

Good request:

Don't read the .env file.
Just estimate and describe what environment variables this project needs by name.

23Common Beginner Mistakes ③

Mistake 3. Modifying without checking Git status

Bad approach:

Clean up this entire project for me.

Good approach: First, in your terminal:

git status

Then, in Claude Code:

Check if there are any pending changes.
Then suggest a modification plan.
Don't modify files yet.

24Common Beginner Mistakes ④

Mistake 4. Assigning large tasks without understanding costs

Bad example:

Read the entire project and fix all problems.

Good example:

Just understand the project structure briefly.
Pick out and explain the 5 most important files.
Don't modify anything yet.

Break large tasks into smaller requests.

Section 02 · Summary

What to Remember from This Unit

Before installing Claude Code, check these 5 things first:

🖥️OS

⌨️Terminal

🔐Account

📁Project Folder

🔒Sensitive Info and Git Status

More important than installation itself is preparing to use it safely.

Core Principle

Run from project root · Protect sensitive info · Plan before modifying · Verify after modifying

3. Install Claude Code and Check Version

01Key Concept

In this section, you will install Claude Code for real.

Beginners should follow the steps below in order.

1. Choose an install command for your OS.
2. Paste the install command into your terminal.
3. Check the installation with claude --version.
4. Verify your environment with claude doctor.
5. Run claude and log in.

The official Claude Code documentation recommends installation via Native Install, Homebrew, or WinGet.

Caution

This information is current at time of writing. Installation commands, supported operating systems, and update methods may change, so consult the official documentation before installing.

02Why It Matters

Claude Code runs in the terminal. If you skip verification, you may run into problems in the next steps.

Command not found

command not found: claude

Wrong terminal type

PowerShell command entered in CMD

Outdated version

New features don't work

Can't verify authentication

Project execution fails

PATH or shell configuration issues

So after installing, don't jump straight into coding. First verify the version → environment → login status.

03Installation Methods at a Glance

macOS

Native Install or Homebrew / curl or brew

Linux

Native Install / curl

WSL

Native Install / curl inside WSL terminal

Windows PowerShell

Native Install / irm

Windows CMD

Native Install / curl + install.cmd

Windows Package Manager

WinGet / winget

The official documentation recommends Native Install as the preferred method. Native Install supports automatic updates, while Homebrew and WinGet installations need manual upgrades.

04Install on macOS

On macOS, you can use Native Install.

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

This command downloads and runs the official install script. Before pasting, verify it matches the command in the official documentation.

Homebrew users should use the stable channel.

brew install --cask claude-code

Homebrew offers a stable channel claude-code and a latest channel claude-code@latest. The stable channel is usually slightly behind the latest, which updates faster. For the latest channel:

brew install --cask claude-code@latest

Beginners typically benefit from the stable channel.

05Install on Linux / WSL

Linux and WSL use the same Native Install command as macOS.

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

If you're using WSL, install and run inside the WSL terminal, not PowerShell.

After installing, open a new terminal or restart your shell to refresh PATH.

exec "$SHELL"

Then verify:

claude --version

06Install on Windows PowerShell

On Windows PowerShell, use this command:

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

The PowerShell prompt typically looks like this:

PS C:\Users\YourName>

If the irm command is not recognized, you may have pasted a PowerShell command into CMD. After installing, open a new PowerShell and verify:

claude --version

07Install on Windows CMD

On CMD, use this command:

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

The CMD prompt typically looks like this:

C:\Users\YourName>

Mixing PowerShell and CMD commands can cause installation errors. For beginners, it's easier to open PowerShell from Windows Terminal and use PowerShell commands.

08Do I Need Git for Windows?

Not required, but recommended.

The official documentation recommends Git for Windows in native Windows environments. With Git for Windows, Claude Code can use Git Bash as its Bash tool; without it, it uses PowerShell. WSL users don't need Git for Windows.

Windows native

Recommended

PowerShell only

Works without it

WSL

Not needed

Want Git Bash commands

Installation recommended

09Verify Installation

After installation, first check the version.

claude --version

In PowerShell, it's the same:

claude --version

If installed correctly, you'll see the version number:

2.x.x

The official documentation recommends running claude doctor for detailed installation and configuration checks.

10Diagnose Your Environment

After checking the version, run the diagnostic command:

claude doctor

In Windows PowerShell, it's the same:

claude doctor

claude doctor checks installation status, environment configuration, and potential issues. Beginners benefit from running it right after installation.

If there are no issues, move to the next step:

claude

11Log In

When you first run Claude Code, it will prompt you to log in.

claude

If you need to log in again within Claude Code, use this command:

/login

The official documentation notes that you can log in with a Claude subscription, Claude Console account, or supported cloud provider.

To check authentication status from the terminal, use:

claude auth status

12Run in Your Project Folder

After installation and login, navigate to your project folder:

cd /path/to/your/project
claude

For example, on macOS or Linux:

cd ~/my-project
claude

On Windows PowerShell:

cd C:\Users\YourName\my-project
claude

Start your first question safely:

Explain the structure of this project.
Summarize the important folders and files first.
Don't modify any files yet.

13Update

If you installed via Native Install, Claude Code supports automatic updates. Homebrew and WinGet installations require manual upgrade commands.

For manual updates, use:

claude update

If you installed via Homebrew stable channel:

brew upgrade claude-code

If you installed via Homebrew latest channel:

brew upgrade claude-code@latest

If you installed via WinGet:

winget upgrade Anthropic.ClaudeCode

14Choose Stable or Latest Channel

Beginners typically benefit from using stable or the stable channel.

stable

Prioritizes stability / Beginners, production projects

latest

Gets new features faster / Users testing experimental features

With Native Install, you can specify the stable channel:

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

On Windows PowerShell:

& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable

15Install a Specific Version

Sometimes teams need a specific version to match.

For example, to install a specific version:

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

On Windows PowerShell:

& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 2.1.89

However, beginners should avoid pinning to a specific version unless there's a good reason. In team projects, follow your team lead or documentation instructions.

16Troubleshooting Installation Issues

Issue 1. `claude: command not found`

After installation, your terminal may not have reflected PATH yet.

On macOS / Linux / WSL, open a new terminal or run:

exec "$SHELL"

Then verify again:

claude --version

17Diagnose Issues 2 and 3

Issue 2. You mixed PowerShell and CMD commands

In PowerShell:

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

In CMD:

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

If irm is unrecognized, you put a PowerShell command in CMD. If you see && errors, you may have put a CMD command in PowerShell.

Issue 3. Bash-related errors on Windows

In native Windows environments, consider installing Git for Windows. With Git Bash, Claude Code can use Bash tools.

If Claude Code can't find Git Bash, you can specify the path in your settings file later:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

18Uninstall if Needed

Uninstall commands actually delete files. Only run them if you need to undo installation or reinstall.

To remove Native Install on macOS, Linux, or WSL:

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

On Windows PowerShell:

Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

If you installed via Homebrew:

brew uninstall --cask claude-code

If you installed via WinGet:

winget uninstall Anthropic.ClaudeCode

19Real Installation Example

Recommended flow for macOS beginners

curl -fsSL https://claude.ai/install.sh | bash
claude --version
claude doctor
cd ~/my-project
claude

Inside Claude Code:

Explain this project's structure.
Don't modify any files yet.

20Examples for Windows and WSL

Recommended flow for Windows PowerShell beginners

irm https://claude.ai/install.ps1 | iex
claude --version
claude doctor
cd C:\Users\YourName\my-project
claude

Recommended flow for WSL beginners

curl -fsSL https://claude.ai/install.sh | bash
claude --version
claude doctor
cd ~/my-project
claude

In WSL, you can work in Windows paths like /mnt/c/..., but if you use many Linux tools, it's simpler to work under /home/....

21Common Beginner Mistakes

Mistake 1. Asking for big work right after installation

Bad: Analyze the whole project and fix all the bugs.

Good: Explain just the project structure first. Don't modify any files yet.

Mistake 2. Skipping version checks

Always verify after installing: claude --version. If problems arise, run claude doctor.

Mistake 3. Not distinguishing PowerShell from CMD

If the prompt shows PS, it's PowerShell (PS C:UsersYourName>). Without PS, it's likely CMD (C:UsersYourName>).

22More Common Mistakes

Mistake 4. Running in the wrong folder

Bad:

cd ~
claude

Good:

cd ~/my-project
claude

Claude Code understands your project from the current folder. Always run from your project root.

Mistake 5. Running delete commands carelessly

These commands permanently delete files: rm -rf ~/.claude. They can remove settings, session history, and permissions. Beginners should avoid running them without official documentation or team guidance.

23Checklist

I chose the install command for my OS

□

I distinguished PowerShell from CMD

□

I verified the command matches official docs

□

I ran claude --version

□

I ran claude doctor

□

I ran claude and logged in

□

I ran it from the project root folder

□

I said "Don't modify files yet" in my first question

□

I know the update command

□

I understand delete commands need care

□

Section 03 · Summary

What to Remember from This Section

After installing Claude Code, don't ask it to code right away. Follow this order to verify:

1Install

2claude --version

3claude doctor

4claude

5Log in and ask your first question

The safest first question for beginners:

Explain this project's structure. Summarize important folders and files first. Don't modify any files yet.

Next Section

Section 4. Start Your First Session

4. Starting Your First Session

01Core Concept

In this section, you'll learn how to run Claude Code for the first time and ask your initial questions safely.

The goal of your first session is not to immediately modify code. The goal is to help Claude Code understand your project first.

1Navigate to project folder

2Run claude

3Verify login

4Ask about project structure

5Review important files

6Get explanations without edits

02Why It Matters

Claude Code understands your project based on the current folder. If you start your first session in the wrong location, Claude may not properly understand your project structure.

Bad start:

cd ~
claude

Good start:

cd ~/my-project
claude

When you run from your project directory, Claude Code can directly read your project files and understand the structure.

03Check Before Starting Your First Session

Before running Claude Code, execute these commands from your project folder first.

pwd
ls
git status

What each command does:

pwd

Check which folder you're currently in

List files in the current folder

git status

Check if there are any Git changes

04When There Are Many Changes

If git status shows many already-modified files, it's good to review what those changes are before starting Claude Code.

git diff

Follow this principle especially in your first session:

Check current state → Run Claude → Request explanation → Save edits for later

05Run Claude Code

From your project folder, run this command:

claude

If it works correctly, the Claude Code interface will open. If this is your first time, you may see a login prompt.

If you need to log in directly within Claude Code:

/login

06How to Ask Your First Question

Never start your first question with "Fix this". Instead, ask questions that help Claude understand your project first.

07Requests to Avoid in Your First Session

In your first session, Claude hasn't fully understood your project yet. These requests are too ambitious:

Bad examples

Refactor the entire project.
Find and fix all bugs.
Fix all failing tests.
Change all code style.

Good examples

First understand the project structure.
If you see areas that need fixing,
just list them as candidates—don't fix yet.

08What to Do After Claude Explains

After Claude explains your project structure, don't immediately ask for fixes. First, verify the explanation.

You can ask follow-up questions like:

In your explanation, separate what you guessed
from what you verified by looking at actual files.

Pick just 5 key files and explain
what role each one plays.
Don't modify them yet.

What commands do you see for running or testing this project?
List the candidates—don't run them yet.

This prevents Claude from moving too fast into fixes or execution.

09Run Your First Command Carefully

Claude Code can run tests, builds, and lint commands. But in your first session, don't let it run commands immediately—first review the candidates.

Good request

Find the command for running tests in this project.
List the candidates—don't run them yet.

Approval example

Good. Run npm test.
Summarize the results, and if tests fail, list possible causes.
Don't modify any files yet.

Request to avoid

Run tests and fix everything that fails.

Be extra careful with install, delete, deploy, and database migration commands.

10When Should You Make Your First Code Change

It's best not to make big changes in your first session. If you need to edit something, start very small.

Example: small documentation edit

I want to add one paragraph to README.md about how to run the project.
First show me a plan of what to add.
Don't modify it yet.

Plan approval

Good. Only modify README.md.
Don't touch any other files.
Summarize the changes after you're done.

For beginners, this workflow of checking each change individually is safest.

11Review Your Changes

If Claude modified files, always review them.

In the terminal

git status
git diff

Ask within Claude Code

Explain the changes you just made based on git diff.
1. Files changed
2. Why they changed
3. Possible unintended changes
4. Whether testing is needed
Organize it in this order.

Recommended workflow

1Request changes

2Get summary

3Review git diff

4Run tests

5Decide on commit

12Helpful Commands for Your First Session

Within Claude Code, you can type / to see available commands. Here are the ones beginners should know on day one:

/help

View available help

/login

/resume

Reopen a previous conversation

/clear

Clean up context unrelated to your current work

/compact

Compress a long conversation into a summary

/usage

Check your current usage

Command input examples

/help

/usage

/resume

13End Your Session

When you're done, exit Claude Code.

Exit command

Ctrl+C

Request before closing

Before exiting, it helps to ask this:

Summarize what you found and what you changed in this session.
Also organize what I should do first when I continue next time.

Git check before exit

If you modified files, always check before closing:

git status
git diff

14Continue a Previous Session

Claude Code saves sessions, so you can continue previous conversations.

Continue your most recent session

claude -c

Or use the long option:

claude --continue

Choose from a list of sessions

claude --resume

Within Claude Code

/resume

You can reopen your previous conversation.

15First Session Walkthrough (Steps 1–3)

Step 1: Navigate to your project folder

cd ~/my-project
pwd
ls
git status

Step 2: Run Claude Code

claude

Step 3: Type your first question

Treat this like you're seeing this project for the first time and explain it.
1. What is the project for
2. Main folder structure
3. Key files
4. Run or test command candidates
5. Files I should read first
Organize it in this order.
Don't modify any files yet.
Don't run any commands yet.

16First Session Walkthrough (Steps 4–7)

Step 4: Look deeper at key files

Pick just 5 key files and explain each one's role.
Only read them—don't modify them.

Step 5: Confirm run command candidates

Show me candidate commands for running or testing this project.
Don't run them yet, and explain which files you based that on.

Step 6: Get a session summary

Summarize what you found in this session.
Recommend 3 things I could do in the next session.

Step 7: Check Git before closing

git status

Your first session shouldn't have any changes since you didn't modify files.

17Common Mistakes Beginners Make ①

Mistake 1: Ask for edits in your very first question

Bad example:

Find all problems in this project and fix them.

Good example:

First explain the structure and key files of this project.
Don't modify anything yet.

Mistake 2: Dump all commands for Claude to run

Bad example:

Run all the setup commands you need.

Good example:

First list candidate install, run, and test commands.
Don't run them yet.

18Common Mistakes Beginners Make ②

Mistake 3: Exit without reviewing changes

If you modified files, always check before closing:

git status
git diff

Also ask Claude to summarize:

Organize the files you changed and why.

Mistake 4: Mix different tasks in one session

If you work on different tasks in one session, context gets mixed. It's better to use separate sessions for these:

Fix authentication bug
Add payment feature
Organize README documentation
Large refactoring

When you switch tasks, start a new session or consider /clear.

19Checklist

Navigated to project root folder

□

Checked pwd, ls, and git status

□

Started first session with claude command

□

Verified your login status

□

Asked for project structure explanation in first question

□

Explicitly said "don't modify any files yet"

□

Listed command candidates before asking to run them

□

If there were changes, reviewed git status and git diff

□

Asked for summary before ending session

□

Understand the difference between claude -c, claude --resume, and /resume

□

Section 04 · Wrap-up

What to Remember from This Section

The goal of your first session is understanding, not editing. It's important to make sure Claude Code understands your project well before you start changing code.

The safest first question is:

Explain what this project does. Organize the important folders and files first. Don't modify any files yet. Don't run any commands yet.

Always remember the basic flow of your first session:

1Navigate to project folder

2Check git status

3Run claude

4Request structure explanation

5Understand without edits

6Summarize session

Next section

Section 5. How to Talk to Claude Code Safely

5. How to Use Claude Code 300% Better

01Core Concept

The difference between people who use Claude Code well and those who don't comes down to how you ask questions.

Beginners usually make requests like this:

Fix this.

But people who use Claude Code well make requests like this:

First, find the relevant files and explain the root cause.
Don't modify anything yet—just propose a fix plan.
Once I approve, then make the minimal changes.

Claude Code is not just a question-answering tool—it's an agent-based CLI that can read your codebase, execute commands, and modify files. To use it effectively, you need to understand systems like settings, permissions, hooks, MCP, and subagents, and apply them to your real development workflow.

02Overview of 7 Best Practices

In this lesson, you'll learn 7 best practices that beginners can use immediately to get results.

1️⃣Break questions into task units

2️⃣Use the explain → plan → execute → review workflow

3️⃣Have Claude explore first

4️⃣Use good prompt templates

5️⃣Divide sessions by purpose

6️⃣Review changes using Git

7️⃣Delegate repetitive tasks to Claude

03Why It Matters

Using Claude Code is convenient. But using it correctly changes the results.

How You Use It

Result

"Fix this"

Claude guesses the scope

"Look at the whole project"

Cost and context bloat

"Handle it yourself"

Unintended changes increase

"Find relevant files and plan first"

Accuracy and stability increase

"Review changes by git diff"

Change review becomes easy

"Analyze only test failures"

Unnecessary changes decrease

Claude Code's power is not in giving it a big task all at once, but in breaking work into small pieces and directing Claude step by step.

04The 300% Mastery Formula

The most fundamental formula is this:

Explore → Plan → Execute → Review → Iterate

What you ask Claude to do at each stage differs.

Explore

Find relevant files — "Find relevant files. Don't modify yet."

Plan

Decide fix direction — "Just write a plan for which files and how to change them."

Execute

Minimal scope changes — "Make changes as planned. Don't touch other files."

Review

Verify changes — "Review changes based on git diff."

Iterate

Test and improve — "Analyze the failed test and propose the next fix."

Using this flow reduces the chances of Claude making unexpected large edits or touching wrong files.

05Best Practice 1. "Find First, Fix Later"

The most common mistake beginners make is asking Claude to fix things right away.

Bad approach:

Fix the login error.

Good approach:

There's a login error.
First, find only the login-related files and functions.
Don't modify the code yet.
List possible root causes with evidence.

This way, Claude first reads and understands your project. Then you ask for a fix plan.

06Request a Fix Plan and Get Approval

Plan request:

Good.
Based on the most likely root cause,
write only a plan for which files to modify and how.
Don't modify anything yet.

Final approval:

Good. Make the changes as planned.
Limit changes to related files only.
After modifications, summarize the changes.

07Best Practice 2. Assign Roles to Claude

Assigning Claude a role improves answer quality.

Simple request:

Look at this code.

Role assignment:

Review this code as a senior backend engineer would.
Find issues from security, error handling, and maintainability perspectives.
Just review—don't modify yet.

Example roles by situation:

Bug fixing

Senior debugging engineer

Code review

Senior code reviewer

Performance improvement

Performance optimization specialist

Security check

Security reviewer

Test writing

Test engineer

Documentation

Technical documentation editor

Refactoring

Architecture reviewer

08Role Assignment Example

Act as a test engineer.
First, list the test cases needed for this feature.
Don't write test files yet.

09Best Practice 3. Specify the Output Format

Specifying output format makes results easier to use immediately.

Bad approach:

Explain the project.

Good approach:

Explain this project in the format below.
1. Project purpose
2. Main folder structure
3. Top 5 core files
4. Possible run commands
5. Possible test commands
6. The order newcomers should read things
Don't modify files yet.

10Three Types of Output Format

Code review — table format:

Review the code from git diff.
Organize it in the table format below.
| File | Issue | Severity | Reason | Fix Suggestion |

Bug analysis — root cause format:

Analyze the error log.
Answer in the format below.
1. Most likely root cause
2. Evidence
3. Files to check
4. Commands to try
5. Precautions before fixing

Specifying output format makes Claude's answers less scattered.

11Best Practice 4. Break Large Tasks into "Work Packages"

Assigning a large task all at once increases failure risk.

Bad approach:

Add payment functionality.

Good approach:

I want to add payment functionality.
First, break this into 5 or fewer small work packages.
For each task, note which files change, risk level, and test methods.
Don't modify anything yet.

12Work Package Breakdown Example

Claude might break it down like this:

Explore current payment-related structure
Define payment API types
Add payment request function
Connect UI button
Add tests

Then proceed one by one:

Do task 1 only.
Find relevant files and explain the structure only.
Don't modify anything yet.

Benefits of this approach:

Failure scope gets smaller

Modify only one piece at a time

Review becomes easier

Changes are smaller

Cost management becomes easier

Unnecessary exploration decreases

Quality improves

Claude doesn't lose sight of the goal

13Best Practice 5. Demand "Evidence" from Claude

A good habit is to always demand evidence when Claude gives answers.

Bad approach:

Where should I fix it?

Good approach:

Tell me where to fix.
Explain the evidence for each judgment: file names, function names, code flow.

This is especially important for codebase analysis:

Explain the authentication flow in this project.
Don't guess—explain based on files and functions you actually checked.
Mark uncertain parts as "not confirmed."

This reduces Claude's tendency to assert vague assumptions.

14Best Practice 6. Divide Sessions by Purpose

Claude Code maintains conversation context within a session. But too many tasks in one session mixes context.

Weak session:

Analyze project structure ↓
Fix login bug ↓
Add payment feature ↓
Edit README ↓
Performance improvement

Strong session:

Session 1: Analyze project structure
Session 2: Fix login bug
Session 3: Add payment feature
Session 4: Organize README documentation

Dividing sessions by task improves Claude's focus.

15Session Management Commands

Continue session:

claude -c

Choose from session list:

claude --resume

Inside Claude Code:

/resume

It's also good to clean up context when moving to a new task:

/clear

16Best Practice 7. Use Git as Claude's Review Tool

To use Claude Code well, you need to use Git together.

Before work:

git status

After work:

git diff

Inside Claude Code, request like this:

Review changes based on git diff.
1. Files changed
2. Why changed
3. Unintended change possibility
4. Bug possibility
5. Additional test needs
Organize in that order.

17Commit Message Writing Request

You can also ask Claude to write commit messages:

Write a commit message based on the current git diff.
Use Conventional Commits format.
Include the reason for change briefly in the body.

Expected output:

fix(auth): handle missing access token

Modified to handle cases where access token is missing from login response.
Returns a clear error message on authentication failure.

18Best Practice 8. Turn Repetitive Tasks into Templates

Save frequently used requests as templates.

Bug fixing template:

Analyze the following bug.
Symptom: [enter symptom here]
Conditions:
- Find relevant files first.
- Don't modify anything yet.
- Organize possible root causes in order of likelihood.
- For each cause, note evidence files and how to verify.
- End with a fix plan suggestion.

19Template 2: Code Review & Feature Addition

Code review template:

Code review the current changes.
Criteria:
1. Bug possibility
2. Security issues
3. Exception handling
4. Performance issues
5. Maintainability
Output format: | File | Issue | Severity | Reason | Fix Suggestion |
Don't modify files yet.

Feature addition template:

I want to add the following feature.
Feature description: [enter feature here]
First, organize the following.
1. Relevant files
2. Current structure
3. Implementation plan
4. Modification scope
5. Test method
6. Risk factors
Don't modify anything yet.

20Template 3: Test Writing

Test writing template:

I want to write tests for this feature.
First, write only a list of test cases.
For each test case, organize purpose, inputs, and expected results.
Don't create test files yet.

21Real-World Example ① · Explore

Situation: Clicking the login button produces an error.

Step 1. Exploration request:

I'm getting an error when clicking the login button.
First, find files related to the login flow.
Don't modify anything yet.
Just organize relevant files and function roles.

Step 2. Root cause analysis request:

Good.
Now organize possible root causes for login failure in order of likelihood.
For each cause, note evidence files, how to verify, and expected modification scope.

22Real-World Example ② · Plan and Execute

Step 3. Plan request:

Based on the most likely root cause, write a fix plan.
Include which files to modify, what to change, and test method.
Don't modify anything yet.

Step 4. Execution approval:

Good.
Make the changes as just planned.
Minimize the modification scope,
and don't touch other files.

23Real-World Example ③ · Review and Test

Step 5. Review changes:

Review changes based on git diff.
Organize unintended changes, bug possibility, and test needs.

Step 6. Test request:

What tests should I run to verify this change?
Show candidates only—don't run commands yet.

Step 7. Test execution approval:

Good. Run the proposed test commands.
If they fail, analyze the cause only—don't make additional fixes yet.

24Value of Real-World Workflow

Using this workflow lets you use Claude Code not as a simple auto-fix tool, but as an analyst + developer + reviewer + test assistant.

Don't command immediately. Make it find first, plan, then review.

25Common Beginner Mistakes ①

Mistake 1. You say "handle it yourself"

Bad example:

Restructure it well yourself.

Good example:

First, propose only 3 improvement options.
For each option, explain pros, cons, and risk level.
Don't modify anything yet.

Mistake 2. You assign too large a task at once

Bad example:

Refactor the entire project.

Good example:

Find refactoring candidates.
Choose only the 3 highest-priority files,
and explain why each needs refactoring.
Don't modify anything yet.

26Common Beginner Mistakes ②

Mistake 3. You don't specify output format

Bad example:

Review it.

Good example:

Review in the table format below.
| File | Issue | Severity | Fix Suggestion |

Mistake 4. You don't check diff after modifications

After modifications, you must always check:

git status
git diff

Also ask Claude:

Summarize changes based on git diff,
and check for risky modifications.

27Common Beginner Mistakes ③

Mistake 5. You expose sensitive information

It's best not to read or paste these files:

🔒.env

🔒.env.local

🔒credentials.json

🔒private-key.pem

🔒id_rsa

🔒service-account.json

Good request:

Don't read the .env file.
Infer needed environment variable names and explain.

28Checklist

Verify you're using Claude Code correctly.

I explored first instead of requesting immediate fixes

□

I stated "don't modify yet" where needed

□

I broke tasks into small units

□

I assigned Claude a role

□

I specified desired output format

□

I requested judgment evidence based on files and functions

□

I got a plan before modifying

□

I checked git diff after modifying

□

I got test command candidates before running them

□

I didn't expose sensitive information files

□

I divided sessions by task

□

Section 05 · Wrap-up

What to Remember from This Lesson

The core of using Claude Code 300% better comes down to one line:

Don't command immediately. Make it find first, plan, then review.

The most powerful baseline prompt is:

First, find relevant files.
Don't modify anything yet.
Explain the root cause,
and propose a fix plan only.
Once I approve, make minimal changes.
After modifications, review changes based on git diff.

Once you master this workflow, Claude Code becomes not just an auto-completion tool, but a development partner that helps with project analysis, bug fixes, refactoring, tests, and code review.

Next Section

Section 6. How to Read Files and Make Claude Understand Your Codebase

6. How to read files and help Claude understand your codebase

01Key concept

To use Claude Code well, reading many files is less important than reading the right files accurately.

Beginners usually request like this:

Analyze the entire project for me.

But a good request starts like this:

First, find only files related to this feature.
Don't modify anything yet,
and explain which files you read and why.

The goal of this unit is to teach Claude to understand your codebase this way.

Blindly reading everything

Finding the files you need

Explaining with guesses

Explaining based on files you read

Modifying immediately

Planning after understanding structure

02Why you need this

As your codebase grows, asking Claude to read every file at once becomes inefficient.

Bad approach

"Analyze the whole project"

Too broad and time-consuming

"Read all files"

Wastes a lot of context

"What needs to be fixed?"

Claude likely to guess

"Find and fix whatever you think is wrong"

May touch unwanted files

Good approach

Find related file candidates first

Narrows search scope

Have them explain each file's role

Structure becomes clear

Have them mark source files as evidence

Increases answer credibility

Get only a plan before modifying

Reduces risky changes

03How Claude understands files

Beginners don't need to memorize all internal tool names. But knowing these concepts is helpful:

Reading files

Check specific file contents (e.g., read package.json, README.md)

Searching for files

Find files by name or pattern (e.g., find files related to auth, login, user)

Searching code

Search for function names, variable names, strings (e.g., search loginUser, JWT, TODO)

Grasping folder structure

Review entire project structure (analyzing unfamiliar projects)

Using guideline files

Remember project rules (CLAUDE.md creation)

At first, you can make requests like this:

First, get a light understanding of the project structure.
Explain which files you read and why.
Don't modify files yet.

04Making your first exploration request

With an unfamiliar project, rather than asking immediately about features or bugs, you should create a project map first.

Imagine you're a developer seeing this project for the first time and explain its structure.

Organize it in this order:

1. Project purpose
2. Main folder structure
3. Key configuration files
4. Files that appear to be execution entry points
5. Test-related files
6. Top 5 files to read first

Don't modify files yet.
Don't run any commands.

Advantages of this request

"Developer seeing it for the first time"

Explanations become simpler

"Organize in order"

Response becomes structured

"Top 5 key files"

Scope is reduced

"Don't modify"

Exploration is safe

"Don't run commands either"

Prevents unnecessary execution in first session

05Having files read by directly specifying them

If you already know which files you want to read, directly specifying them is best.

Read README.md and package.json,
and explain how to run this project and its main dependencies.
Don't modify files yet.

You can also specify multiple specific files:

Read the following files and compare their roles.

- src/app.ts
- src/server.ts
- src/routes/auth.ts

Organize in a table which responsibility each file has.
Don't modify yet.

It's even better to specify the output format:

Organize it in the following table format.

| File | Role | Important functions | Relationships with other files | Points to watch |

06Finding related files

When you don't know the filename, Claude should search for it first.

Example: Finding login functionality

Find where the login feature is implemented.

Conditions:
- Find candidate files first.
- Don't modify files.
- Explain what role each file plays in the login flow.
- Distinguish between guessed and actually confirmed parts.

Example: Finding payment functionality

Find where payment-related code is located.

Search based on these keywords:
- payment
- billing
- checkout
- invoice
- subscription

After finding related files,
explain each file's role and the overall payment flow.
Don't modify yet.

Example: Finding error messages

Find where this error message is generated.

"Invalid access token"

Organize related files, functions, and call flow.
Don't modify yet.

This approach makes Claude narrow down from related parts using keywords instead of blindly reading entire files.

07Requesting "evidence of what was read"

When having Claude explain your codebase, always request evidence.

Bad request

Explain the authentication structure.

Good request

Explain the authentication structure.
Base the explanation on actual filenames and function names you confirmed.
For parts you're unsure about, mark them "needs confirmation" instead of guessing.

Even better request

Organize the authentication structure in this format.

1. Overall flow
2. Related files
3. Key functions
4. Data flow
5. Evidence from actual files confirmed
6. Parts still needing confirmation

Don't modify files yet.

This way Claude's answers become more verifiable.

08Creating a codebase map

For mid-sized or larger projects, creating a "codebase map" first is helpful.

Create a codebase map for this project.

Organize it in this format.

1. App entry point
2. Routing structure
3. State management approach
4. API communication structure
5. Authentication structure
6. Database or storage access structure
7. Test structure
8. Build and deployment related files
9. Order of files for beginners to read first

Don't modify files yet.
Don't run commands.

Good output format looks like this:

App entry point

src/main.ts — app startup (high)

Routing

src/routes/* — request handling by URL (high)

Authentication

src/auth/* — login, token handling (high)

Tests

tests/* — test code (medium)

Configuration

package.json, .env.example — runtime environment (high)

Once you have this map, future work becomes much faster.

09Deciding the order to read files

When reviewing a codebase, order matters. Rather than blindly reading all of src, this order usually works well:

README.md
↓
package.json / pyproject.toml / go.mod etc.
↓
Environment example file
↓
App entry point
↓
Routing or main module
↓
Core domain code
↓
Test code

You can request from Claude like this:

Recommend a file reading order for understanding this project.

Conditions:
- Choose only up to 10 files.
- Explain why each file should be read first.
- Base it only on files that actually exist.
- Don't modify files yet.

This request is especially useful for beginners who don't know which files to start with.

10Saving project explanations in CLAUDE.md

If you don't want to repeat the same explanation every time, you can create CLAUDE.md in the project root.

CLAUDE.md is a Markdown file added to the project root, and Claude Code reads it at the start of each session and uses it as guidance for coding standards, architecture decisions, preferred libraries, review checklists, and so on.

Example CLAUDE.md for beginners:

# Project Guide

## Project Overview
This project is a web application that provides user login, signup, and payment features.

## Key Commands
- Run dev server: npm run dev
- Run tests: npm test
- Run linter: npm run lint

## Key Folders
- src/routes: routing
- src/components: UI components
- src/lib: common utilities
- tests: test code

## Work Rules
- Explain modification plans before modifying files.
- Don't read .env files.
- Break large refactoring into small steps.
- Summarize changes based on git diff after modification.

After writing it, you can tell Claude:

Refer to CLAUDE.md and explain the structure of this project.
If there's any missing content, only offer suggestions to supplement.
Don't modify yet.

However, CLAUDE.md is not a mandatory security measure. To block certain tasks, you need to use separate mechanisms like permissions or hooks.

11Preventing reading of sensitive files

While Claude Code being able to read files is convenient, be careful with sensitive information.

Example files that shouldn't be read

.env
.env.local
.env.production
credentials.json
service-account.json
private-key.pem
id_rsa
*.key
*.pem

It's good practice to always tell Claude like this:

Don't read .env, credentials, or private key files.
If needed, infer and explain only the environment variable names.

To block even more securely, you can deny read permissions in settings. You can block sensitive file access by putting rules in permissions.deny of .claude/settings.json.

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)"
    ]
  }
}

Beginners don't need to set up all complex permission rules from the start. But developing the habit of never pasting sensitive files to Claude is essential.

12Pointing to specific lines or files precisely

Using an IDE together lets you point specific files or code ranges to Claude more precisely.

When you have selected code in VS Code, Claude can see the highlighted code. On Mac use Option+K, on Windows/Linux use Alt+K to insert a mention that includes the file path and line numbers.

Example

Explain @app.ts#20-45.
Organize what inputs this function takes and what outputs it returns.
Don't modify yet.

If you don't use an IDE, you can write the filename and function name directly:

Explain the loginUser function in src/auth/login.ts file.
Also organize other functions this function calls.

13Tips for reading large files

Rather than analyzing large files all at once, you need to set a purpose.

Bad example

Explain the entire file.

Good example

In this file, explain only the parts related to authentication.
Organize based on this criteria.

1. Related functions
2. Input values
3. Return values
4. External dependencies
5. Exceptional situations to watch

Or you can request like this:

Don't summarize the entire file;
first scan the structure and tell me each section's role.
Then explain only the sections I choose in detail.

Step-by-step approach to large files reduces context waste.

14Following code flow

To understand a specific feature, "flow explanation" is more important than "file explanation".

Example: Login flow

Trace the flow from when a login request comes in until a response is returned.

Organize in this format.

1. Starting point
2. Function call order
3. What each function does
4. Database or external API calls
5. Points where errors can occur
6. Actually confirmed files and functions

Don't modify yet.

Example: API request flow

Trace the flow of the user info lookup API.
If there are route, controller, service, and repository layers, explain them in order.
Organize based on actual filenames and function names.

Example: Frontend button click flow

Trace what code runs when the login button is clicked.
Explain in order: component, state change, API call, error handling.
Don't modify yet.

15Understanding features using test files

Test files are excellent material for understanding features.

Find test files related to this feature.
Based on what the tests describe, organize the feature requirements.
Don't modify the tests yet.

Reading tests teaches you:

Expected behavior

What results the feature should produce

Exception handling

How failures and errors are handled

Input values

What data comes in

Boundary conditions

Empty values, wrong values, no permissions etc.

Missing tests

Parts not yet verified

Request to understand features based on tests:

Read the test files for the payment feature,
and reverse-engineer the current payment feature requirements.

Write in this format.

| Test name | Verified behavior | Input | Expected result | Potential gap |

16When documentation and code differ

README or documentation might differ from actual code. When that happens, have Claude compare the two.

Compare the execution method in README.md with the actual scripts in package.json.
If there are differences, organize in a table.
Don't modify files yet.

Or:

Check if the API paths in the documentation match the actual routes in the route file.
If there are mismatches, organize with source files.
Don't modify yet.

When documentation and code differ, it's better to organize the differences first rather than fix immediately.

17Prompts for understanding codebase

Grasping entire project structure

Explain the entire structure of this project.

Conditions:
- Cover only important folders and files.
- Explain based on files you actually confirmed.
- Don't modify files yet.
- At the end recommend a file reading order for beginners.

Finding specific features

Find where [feature name] is implemented.

Conditions:
- First organize related file candidates.
- Explain each file's role.
- Include actual confirmed function names.
- Don't modify yet.

Finding error location

Find where this error occurs.

Error message:
[error message input]

Conditions:
- Search for the error string.
- Distinguish direct occurrence from call flow.
- Don't modify; only organize problem candidates.

18Prompts for understanding codebase (continued)

Tracing code flow

Trace how [feature name] executes.

Organize in this format.

1. Starting point
2. Call order
3. Key functions
4. Data flow
5. Error handling
6. Confirmed files and functions

Recommending file reading order

Recommend a file reading order for understanding this project.
Choose only up to 10 files.
Explain why each file should be read.
Don't modify yet.

Comparing documentation and code

Check if the description in README.md matches the actual code.
If there are mismatches, organize in a table with source files.
Don't modify yet.

19Practical example: Understanding login functionality

Situation: You need to modify the login feature, but don't know where it is.

Step 1. Finding related files

Find where the login feature is implemented.

Search keywords:
- login
- auth
- token
- session
- password

Find related files,
and explain what role each plays in the login flow.
Don't modify yet.

Step 2. Tracing the flow

Trace the flow from login request to response.

Organize in this format.

1. Request starting point
2. Function call order
3. Token generation or session handling location
4. Error handling location
5. Actually confirmed files and functions

Step 3. Finding risky points

Find places in the login flow prone to bugs.

Criteria:
- Input validation
- Password validation
- Token generation
- Session saving
- Error messages
- Exception handling

Don't modify yet;
only organize problem candidates and evidence.

Step 4. Getting a modification plan

Choose the highest-priority problem and write a modification plan.

Include:
1. Files to modify
2. Why to modify
3. How to modify
4. How to test
5. Risk factors

Don't modify files yet.

Following this flow lets Claude sufficiently understand the codebase before modifying.

20Common beginner mistakes

Mistake 1. Trying to read the entire project at once

Bad example:

Read all files and explain.

Good example:

First understand the project structure,
then recommend the reading order for only the top 10 core files.
Don't modify yet.

Mistake 2. Receiving explanation without evidence

Bad example:

Explain authentication structure.

Good example:

Explain authentication structure.
Include actual confirmed filenames and function names as evidence.
Mark uncertain parts as "needs confirmation".

Mistake 3. Not providing search keywords

Bad example:

Find payment feature.

Good example:

Find the payment feature.
Search using these keywords: payment, billing, checkout, invoice, subscription.

21Common beginner mistakes (continued)

Mistake 4. Having Claude read sensitive files

Bad example:

Read .env file and explain the settings.

Good example:

Don't read .env file.
Instead, base on .env.example or README and explain only the needed environment variable names.

Mistake 5. Mixing reading and modification

Bad example:

Explain login structure and fix any problems you find.

Good example:

Explain only the login structure first.
If problems appear, don't fix them; organize only candidates.

22Checklist

When starting Claude Code for the first time, check the items below:

Didn't blindly read the entire project

□

Had them find related file candidates first

□

Provided specific search keywords

□

Explicitly stated "don't modify yet"

□

Had them explain read files and evidence

□

Had them distinguish actual confirmations from guesses

□

Requested they not read sensitive files

□

Had them read large files with a purpose

□

Had them trace code flow by execution order, not file units

□

When necessary, organized project rules in CLAUDE.md

□

Section 06 · Wrap up

What to remember from this unit

The key to making Claude understand your codebase is this:

Don't have them read everything; have them find the files you need, and have them explain based on evidence from files they read.

The most frequently used basic prompt is as follows:

First, find files related to this feature.
Don't modify yet.
Explain each file's role and the evidence you actually confirmed.
Mark uncertain parts as "needs confirmation".
Then, if modification is needed, propose only the plan.

Developing this habit helps Claude understand your project more accurately, reduces unnecessary file reading, and minimizes risky modifications.

Next unit

Unit 7. Creating a plan first before modifying with Plan Mode

7. Create Plans Before Making Changes with Plan Mode

01Core Concept

Plan Mode is a feature that tells Claude Code to investigate and create a plan first, rather than immediately making changes.

Flow difference between normal mode and Plan Mode:

Normal Mode

Request → Claude reads files → Suggest or execute changes

Plan Mode

Request → Claude investigates → Creates plan → User reviews → Approve before changes

In Plan Mode, Claude investigates and creates a plan before proposing changes, and does not edit files until approval. File reading for exploration and shell commands can be executed through permission prompts.

02Why It's Needed

Claude Code can modify files and execute commands. So assigning large tasks directly is risky.

Bad request:

Refactor the entire authentication structure for me.

Good request:

Use Plan Mode to create a refactoring plan for the authentication structure first.
Investigate the related files,
and organize the files to modify, reasons for changes, potential risks, and testing methods.
Don't make any changes yet.

02Why It's Needed (continued)

Situations where Plan Mode is necessary:

Multiple files need to be modified

Need to verify the scope of changes first

Unfamiliar codebase

Making changes without understanding the structure is risky

Refactoring

High likelihood of unintended behavior changes

Authentication, payment, permission features

Mistakes are costly

Complex test failure causes

Direct fixing mixes causes and symptoms

Team projects

Plans can be shared and reviewed first

03How to Enable Plan Mode ① Shift+Tab during session

You can switch modes by pressing Shift+Tab while Claude Code is running.

Basic mode cycle:

default → acceptEdits → plan

Three modes cycle:

default — Normal mode. Claude can freely modify files
acceptEdits — Claude only suggests, user manually approves
plan — Plan mode. Only investigates and creates plans

03How to Enable Plan Mode ② Add /plan

You can also use Plan Mode for a single request.

Add /plan before a specific request in Claude Code:

/plan Create a plan for refactoring the login feature.
Investigate the related files and write only the modification plan.

This method is useful when you mostly work in normal mode but want to use plan mode at specific moments.

03How to Enable Plan Mode ③ Start with Plan Mode

You can also start with Plan Mode from the terminal from the beginning.

claude --permission-mode plan

Or:

claude -p plan

Running this way starts the Claude Code session in Plan Mode from the beginning, so all requests are handled in Plan Mode.

04What Claude Does in Plan Mode

The basic flow in Plan Mode is as follows:

Finds related files.
Reads necessary content.
Understands current structure.
Clarifies change objectives.
Proposes files to modify and reasons why.
Organizes potential risks and testing methods.
Waits for user approval.

04Items to Verify in Plan Mode

Beginners should ensure Claude includes the following in Plan Mode:

Files to modify
Files not to modify
Reasons for changes
Expected impact
Potential risks
Testing methods
Rollback methods

Example of a good Plan Mode request:

/plan I want to add input validation to signup.
1. Related files / 2. Current behavior / 3. Files to modify
4. Modification content / 5. Files not to modify
6. Potential risks / 7. Testing methods
Don't modify files yet.

05Verifying Plan Quality

When Claude creates a plan, don't approve immediately. You must review it by these criteria.

Scope

Good plan: Files to modify are clear | Bad plan: Vague like "modify multiple files"

Reasons

Good plan: Explains why changes are made | Bad plan: Just says it will change

Risks

Good plan: Notes potential side effects | Bad plan: No risks identified

Testing

Good plan: Has verification commands | Bad plan: No testing plan

Rollback

Good plan: Can be verified with git diff | Bad plan: Unclear how to revert

Limitations

Good plan: Specifies files not to touch | Bad plan: Wants to touch entire project

05When the Plan Is Insufficient

If the plan is insufficient, request this way:

The plan is still too broad.
Narrow the modification scope.
1. Files that must be modified
2. Files not to modify
3. Smallest change unit
4. How to revert if it fails

06Understanding Options After Approval

When a plan is ready in Plan Mode, Claude Code asks how to proceed. Possible options:

Continue modifying the plan
Review each edit manually
Auto-approve edits
Proceed in Auto Mode

You can also directly edit the proposed plan in a text editor with Ctrl+G.

Recommended for beginners: Approve and review each edit manually

06Recommendation by Approval Method

Continue modifying plan

Recommendation: High | Safe when plan is unclear

Review each edit manually

Recommendation: High | Can verify changes one by one

Auto-approve edits

Recommendation: Medium | Recommended only for familiar projects

Proceed in Auto Mode

Recommendation: Low | May be difficult to control for beginners

07Real-World Example: Bug Fix ① Investigating Cause

Situation: Invalid access token error occurs at login.

Step 1. Request cause investigation in Plan Mode:

/plan I'm getting an "Invalid access token" error at login.
1. Where the error message is raised
2. Related files and functions
3. Possible causes
4. Most likely cause
5. Files to modify / 6. How to modify
7. Testing method / 8. Potential risks
Don't modify files yet.

07Real-World Example: Bug Fix ② Narrowing Plan

Step 2. Narrow the plan:

Good.
Make the modification scope smaller.
Based on the most likely cause only
rewrite the minimal modification plan.

Step 3. Approve:

Good.
Proceed with the plan as proposed.
Limit modification to only files mentioned in the plan.
Let me review each edit.

07Real-World Example: Bug Fix ③ Reviewing Changes

Step 4. Review changes:

Review the changes based on git diff.
1. Modified files
2. Reasons for changes
3. Bug possibility
4. Possibility of unintended changes
5. Tests to run

08Real-World Example: Adding Feature ① Creating Plan

Situation: I want to add a password confirmation field to the signup form.

/plan I want to add a password confirmation field to the signup form.
1. Current signup UI structure
2. Current validation structure
3. Components to modify
4. Validation logic to modify
5. Tests to add or modify
6. Error messages to show users
7. Potential risks / 8. Modification scope
Don't modify files yet.

08Real-World Example: Adding Feature ② Reviewing and Proceeding Step by Step

After the plan comes out, request in a more beginner-friendly way:

Explain the plan in a more beginner-friendly way.
For each modified file, explain why it's needed,
and let me know if there are alternatives that don't require modification.

Then proceed in steps:

Good.
Proceed with only step 1 UI modification first.
Don't modify validation and tests yet.
After modification, summarize based on git diff.

For large features, don't approve all at once. Break the plan into steps and execute.

09Real-World Example: Refactoring ① Bad Request

Refactoring is where Plan Mode is most needed.

Bad request:

Clean up this code structure with refactoring.

Good request:

/plan I want to refactor the auth module.
Goals:
- Don't change behavior.
- Reduce duplicate code.
- Make function names clearer.
- Keep tests from breaking.

09Real-World Example: Refactoring ② Creating Plan

Include the following in the plan:

1. Current auth module structure
2. Duplicate or complex parts
3. Refactoring candidates
4. Priorities
5. Smallest first task
6. Files to modify
7. Files not to modify
8. Testing method
Don't modify files yet.

Make sure to break refactoring plans into small steps:

Don't refactor everything at once,
pick only the safest first step.
Choose only tasks with no behavior changes.

10Difference Between Plan Mode and General Chat

Purpose

General chat: Answer immediately or work | Plan Mode: Investigate first then plan

Modification possibility

General chat: Can modify immediately per request | Plan Mode: No source edits until approval

Suitable tasks

General chat: Small questions, simple explanations | Plan Mode: Large modifications, refactoring, feature additions

Beginner safety

General chat: Depends on how you request | Plan Mode: Safer

Review flow

General chat: User must control directly | Plan Mode: Plan review flow feels natural

Plan Mode is not a "slower way to use Claude". Rather, on large tasks it's a feature that reduces failures and overall time.

11Things to Watch Out for Even in Plan Mode

Just because you use Plan Mode doesn't mean all risks disappear. In Plan Mode too, permission prompts apply the same as in normal mode, and file reading or shell command execution may occur during exploration.

Beginners should follow this:

Tell it not to read sensitive files.
Ask for command candidates before executing.
Narrow the plan if it's too broad.
Verify git diff even after approval.
Confirm test commands before running.

11Sensitive Information and Command Restrictions

Example request for sensitive information:

Investigate in Plan Mode, but
don't read .env, credentials, or private key files.
If needed, just describe environment variable names.

Example for command execution restrictions:

If commands are needed during exploration, don't run them immediately.
First tell me the command candidates and reasons.

12Questions to Make Plans Better

When the plan is too broad:

The plan is too broad.
Break it down into the smallest safe change unit.
Write the first step at an executable level.

When potential risks are insufficient:

Risks are insufficient.
Features that could break with this change,
affected tests,
and revert methods—add these.

12Testing and Evidence Enhancement

When test plan is insufficient:

Make the test plan more concrete.
Command candidates to run,
manual verification methods,
test cases to add—organize these separately.

When evidence is insufficient:

Mark the file names and function names that support each modification proposal.
Distinguish assumed parts with "needs verification".

13Recommended Prompts ① Bug Fixes and Feature Additions

For bug fixes:

/plan I want to fix the following bug.
Symptom: [enter symptom here]
Conditions:
- Investigate related files first.
- Don't modify files yet.
- List possible causes in order of likelihood.
- Propose the smallest modification plan.
- Distinguish files to modify from files not to modify.

13Recommended Prompts ② Feature Additions and Refactoring

For feature additions:

/plan I want to add the following feature.
Feature: [describe feature here]
Content to include in plan:
1. Related files / 2. Current structure / 3. Files to modify
4. New files to create / 5. Testing methods
6. Potential risks / 7. Step-by-step execution order
Don't modify yet.

13Recommended Prompts ③ Refactoring and Code Review

For refactoring:

/plan I want to refactor the following area.
Target: [target module or file]
Principles:
- Don't change behavior.
- Keep change scope small.
- Tests must not break.
- First write only step 1 plan.
Don't modify yet.

14Using Plan Mode with Git

It's good to check Git status before and after using Plan Mode.

Before work:

git status

After work:

git diff

When comparing plan and actual changes in Claude Code:

Compare the plan proposed in Plan Mode and the actual git diff.
1. Parts modified as planned
2. Parts that differ from the plan
3. Additionally modified files
4. Possibility of risky changes
5. Parts to revert

This question is very important. Because planned and actual modifications can differ.

15Setting Plan Mode as Default

If you use Plan Mode frequently, you can set it as the project default mode.

Example .claude/settings.json:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

Recommendation criteria:

Small practice project used alone

Optional

Production project

Recommended

Team repository

Strongly recommended

Operating code

Strongly recommended

Refactoring-focused work

Recommended

16Common Beginner Mistakes ① ②

Mistake 1. Approve the plan immediately after seeing it

You must review the plan:

Check if there are parts of this plan where the modification scope is too broad.
Point out the most risky changes first.

Mistake 2. Giving too large a goal in Plan Mode

Bad example: /plan Improve the entire project structure.

Good example:

/plan Create only step 1 plan for reducing duplicate code in the auth module.
Write it in a direction that doesn't change behavior.

16Common Beginner Mistakes ③ ④ ⑤

Mistake 3. Approve without a test plan

Add testing methods to verify this plan.
Separate automated tests and manual verification methods.

Mistake 4. Not restricting sensitive files

Don't read .env, credentials, or private key files.
If needed, just describe required environment variable names.

Mistake 5. Not checking diff after approval

Verify whether the plan and actual changes match based on git diff.

17Checklist

Enabled Plan Mode before large work

□

Understood how to use /plan or Shift+Tab

□

Had it investigate related files before modifying

□

Distinguished files to modify from files not to modify

□

Included potential risks in plan

□

Included testing methods in plan

□

Narrowed plan again if it was too broad

□

Explicitly told it not to read sensitive files

□

Reviewed each edit after approval

□

Compared plan and actual changes with git diff after modification

□

Section 07 · Closing

What to Remember from This Lesson

The essence of Plan Mode is:

Investigate first before making changes, review the plan, then approve in small steps.

Most commonly used basic prompt:

/plan Before doing this task, investigate related files and create a plan.
Include the following in the plan.
1. Related files / 2. Current structure / 3. Files to modify
4. Files not to modify / 5. Reasons for changes
6. Potential risks / 7. Testing methods
8. Smallest step 1 task
Don't modify files yet.

Plan Mode is a safety mechanism for using Claude Code securely, and at the same time a tool that elevates result quality. The larger the task, the more you should follow the order of Plan Mode → Review → Small approval → diff verification instead of executing immediately.

Next lesson

Lesson 8. Safely handle file modifications and command execution

8. How to efficiently control file modifications and command execution

01Core concept

The key to using Claude Code well is not blocking all tasks. The key is controlling the scope of modifications and command execution to be small while iterating quickly.

A formula beginners should remember:

Make small changes
↓
Verify immediately
↓
Execute only necessary commands
↓
Review the result and move to the next modification

A bad approach is "fix the entire project", a good approach is "modify only the src/auth/login.ts file and review with git diff".

02Why is this necessary

Claude Code is fast. But because it's fast, without control you might end up modifying files you didn't intend to.

Modify only this file

Reduces scope of change

Tell me command candidates first

You can control execution

Review based on git diff

You can quickly verify changes

Efficient users don't give all permissions to Claude at once. Instead, they create small approval units.

1 large task → 3-5 small modifications → verify diff for each → run only necessary tests

03Categorizing tasks Claude Code handles

Claude Code tasks can be divided into four main categories.

Reading

File analysis, structure understanding | Specify read scope

Modifying

File editing, code addition | Specify files to modify

Running commands

Testing, building, linting | Confirm candidates before execution

Git operations

Diff review, commit messages | Review before committing

The most dangerous flow is modify → run command → fail → auto re-modify → repeat. Beginners must always separate reading, modifying, and execution.

04Request file modifications in "minimum scope"

File modification requests must include four things.

File to modify
Files not to modify
Purpose of modification
How to verify after modification

Bad example: Fix the login bug.

Good example:

Fix the login bug.
Conditions:
- Modify only the src/auth/login.ts file.
- Do not modify any other files.
- Summarize changes based on git diff after modification.

05Specify both files to modify and files not to modify

If you only tell Claude "what to do", the scope can expand. You must also say "what not to do".

Advantages of this approach:

Specify files to modify

Reduces scope

Specify files not to modify

Reduces unintended changes

Specify purpose

Prevents unnecessary refactoring

Request summary after changes

Makes review easier

06Divide multi-file modifications into phases

If you need to modify multiple files, don't approve all at once.

Bad example: Complete the signup feature. You can modify all necessary files.

Good example: First divide the work into 3 phases, then for each phase list the files to modify, what to change, how to test, and potential risks. Then execute one phase at a time.

A good flow for multi-file modifications is:

1Fix types or validation

2Review diff

3Connect UI

4Review diff

5Add and run tests

07Handle command execution with "candidate → approval → execution"

Don't run commands immediately; get candidates first.

Bad example: Run tests and fix if they fail.

Good example: Ask for test command candidates to verify this change, have them explain what each command checks, then approve only one.

Command execution sequence:

Request command candidates
↓
Confirm command purpose
↓
Approve only one
↓
Summarize execution results
↓
Analyze failure cause
↓
Request fix plan

08Distinguish command risk levels

Not all commands have the same risk level.

Low

git status, git diff, ls | Relatively safe

Medium

npm test, npm run lint, npm run build | Confirm purpose before execution

High

npm install, pip install, brew install | Confirm if dependencies change

Very high

rm -rf, sudo, DB migration, deploy | Beginners must not approve immediately

Sensitive

.env output, API key check | Do not execute

09Git commands are safe to ask Claude frequently

After modifying files, the most frequently used commands should be Git verification commands.

git status
git diff

In Claude Code, request it like this:

Check git status and git diff, then summarize current changes.
Organize changed files, change contents, whether changes are intended, potential dangerous changes, and whether testing is needed.

For commit messages: Ask Claude to write a commit message in Conventional Commits format based on git diff.

10Reduce repeated approvals with permission settings

If you find it tedious to approve the same safe commands repeatedly, you can allow certain tools or commands.

Example of specifying permissions in project settings:

{
  "permissions": {
    "allow": [
      "Read",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(npm test)",
      "Bash(npm run lint)"
    ],
    "deny": [
      "Read(./.env)",
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(git push *)"
    ]
  }
}

For beginners, the recommended approach is to start with small allowed scope. Efficiency comes from "allowing only frequently used safe tasks and continuing to control dangerous ones".

11Beginners should not use dangerously-skip-permissions

The CLI has a --dangerously-skip-permissions option to skip permission prompts.

Bad example:

claude --dangerously-skip-permissions

This option seems convenient, but it allows Claude to proceed with file modifications and command execution too easily.

A better approach for beginners:

claude --permission-mode plan

Or in Claude Code, use /plan first to ask for a modification plan.

12What you must verify after modification

After file modification, in the terminal:

git status
git diff

Run tests if necessary.

Ask Claude to review the modifications in the following format:

Changed files
What changed in each file
Whether it matches the original goal
Potential unintended changes
Whether additional testing is needed
Whether any parts need to be reverted

13Specific items to verify after modification

Pay special attention to the following items.

Number of modified files

Check if too many files changed

lock file changes

Check for dependency changes

Configuration file changes

May affect execution environment

Test file changes

Check if only tests were fixed instead of actual functionality

Deleted code

Check if necessary logic was removed

.env-related changes

Risk of exposing sensitive information

14Don't immediately fix after test failure

When tests fail, don't immediately say "fix it". First, you need to isolate the cause.

Bad example: Tests failed. Fix it yourself.

Good example: Ask to analyze the test failure cause, but don't modify files yet. Ask to list the failed test names, explain failure causes in order of likelihood, and distinguish between code problems and test expectation problems.

Test failure response flow:

Summarize failure log → List cause candidates → Distinguish code/test problems
→ Fix plan → Minimal modification → Re-test

15Practical workflow: Small bug fix

Situation: The app crashes when there's no access token during login.

Step 1. Request modification plan

Find related files and ask to write a modification plan only. Don't modify files yet. Ask to distinguish between files to modify and files not to modify.

Step 2. Approve small modification

Modify only the src/auth/login.ts file to return a clear error when access token is missing. Don't modify other files.

Step 3. Review diff

Check git diff and ask to summarize changes.

Step 4. Confirm test candidates

Get test command candidates to validate this change, but don't run yet.

Step 5. Approve test execution

Run only 1 test command with the narrowest scope. If it fails, ask to analyze only the cause.

16Practical workflow: Auto-fix lint

Situation: There are multiple lint errors.

Bad request: Fix all lint errors.

Good request:

Ask for lint command candidates and don't run yet.
Approve running npm run lint, but if it fails, ask to categorize errors by file.
Fix only formatting issues that can be auto-fixed; don't fix issues requiring logic changes.
Review git diff and ask to distinguish between formatting changes and logic changes.

17Practical workflow: Build failure analysis

Situation: The build fails.

Ask to find build command candidates for this project and explain based on package.json or config files. Don't run commands yet.
Approve running npm run build, but if it fails, ask to summarize the failure log and list only cause candidates. Don't modify files yet.
Ask to organize build failure causes by: direct error message, related files, possible causes in likelihood order, code to check, minimal fix plan.
Fix only the highest likelihood cause, minimize modification scope, and summarize with git diff.

18Practical workflow: Package installation

Package installation can change lock files and dependency structure. Don't approve immediately.

Ask to decide if a new package is needed for this feature implementation. Ask to check if it's possible with existing dependencies first. Don't run install command yet.
Ask to explain what files might change if this package is installed, and what commands or git operations are needed to revert.
Approve running the install command, but after installation ask to check git diff and summarize changed files.

Beginners should ask whether to use existing code first before adding new packages if possible.

19Common beginner mistakes

Mistake 1. Modifying too many files at once

Bad example: Fix all type errors in the entire project.

Good example: Categorize type errors by file, and ask to make a modification plan for only 1 file with the smallest impact scope first.

Mistake 2. Running commands immediately

Bad example: Run all necessary commands.

Good example: Ask for command candidates first, have them explain the purpose and risk level of each command. Don't run yet.

20Common beginner mistakes (continued)

Mistake 3. Creating auto-fix loops after test failure

Bad example: Keep fixing until tests pass.

Good example: Analyze test failure causes and propose only the smallest fix plan. Don't modify until I approve.

Mistake 4. Not checking git diff

After modification, always check git status and git diff, and ask Claude to review changes.

Mistake 5. Approving dangerous commands

Commands like rm -rf, sudo, git reset --hard, npm publish, prisma migrate deploy should not be immediately approved by beginners. Ask for explanations first.

21Practical prompt collection

When modifying a single file:

Modify only [file path].
Goal: [modification goal]
Constraints: - Don't modify other files.
           - Summarize based on git diff after modification.

When getting only command candidates:

Tell me command candidates to verify this task.
- Don't run yet.
- Explain the purpose of each command.
- Mark high-risk commands.

When analyzing execution results:

Analyze the just-executed command results. Organize in the following format.
1. Success or failure  2. Key message  3. Failure cause candidates
4. Files to check next  5. Whether modification is needed
Don't modify files yet.

When getting plan only after test failure:

Analyze test failure cause.
- Don't fix yet.
- List failed tests.
- Distinguish between code and test problems.
- Propose minimal fix plan only.

When requesting diff review:

Review current git diff.
Criteria: Goal alignment, unintended changes, bug potential,
         Test sufficiency, parts to revert

22Checklist

Clearly specified files to modify

□

Also specified files not to modify

□

Approved only one purpose at a time

□

Got command candidates before running

□

Didn't immediately approve dangerous commands

□

Didn't auto-fix immediately after test failure

□

Checked git status after modification

□

Checked git diff after modification

□

Asked Claude for diff review

□

Checked lock file change before package install

□

Didn't read .env, credentials files

□

Considered permissions only for safe repetitive commands

□

Section 08 · Wrap-up

What to remember from this unit

The core of handling file modifications and command execution well is this:

Don't give big tasks, assign small ones, verify immediately, and repeat.

The basic prompts you'll use most frequently are:

First distinguish files to modify and files not to modify.
Show me the plan before modifying files.
Once I approve, modify only files in the plan.
If commands are needed, tell me candidates and reasons before running.
Review changes based on git diff after modification.

People who use Claude Code efficiently don't automate everything. They quickly allow frequently repeated safe tasks and control dangerous ones by breaking them down into smaller pieces.

Next unit

Unit 9. Teach project rules with CLAUDE.md

9. Tell Claude Code project rules with CLAUDE.md

01Key Concept

CLAUDE.md is a file that tells Claude Code the rules and context it should always know about in this project. In simple terms, it's a project guide for Claude Code.

CLAUDE.md contains content like the following.

Project structure
Build commands
Test commands
Coding rules
Verification procedures before making changes
Warnings about sensitive files
Team workflow

It is a persistent guideline file that Claude Code reads at the start of each session. Since each session starts with a fresh context, CLAUDE.md and auto memory are used to transfer project knowledge across sessions.

02Why It's Needed

Without CLAUDE.md, you would need to repeat the same explanation every session. For example, you might have to say these things every time.

This project uses pnpm.
Run tests with pnpm test.
Don't read the .env file.
Show me the plan first before making changes.
Check git diff before committing.

Benefits of having CLAUDE.md:

Reduce repeated explanations

You don't have to state the same rules every time

Speed up project understanding

Claude quickly grasps the structure and commands

Reduce mistakes

Prevents using the wrong package manager or test commands

Share team rules

Team members use Claude Code by the same standards

Improve edit quality

Easier to reflect architecture, naming, and testing rules

03What Should Go in CLAUDE.md

Beginners don't need to write it perfectly from the start. Adding these 7 items is enough.

1. Project overview
2. Main folder structure
3. Run commands
4. Test commands
5. Coding rules
6. Work procedures
7. Prohibitions or warnings

Even this much makes a difference in Claude Code's work quality.

04CLAUDE.md File Location

The most basic location is the project root. You can also place it inside the .claude folder.

Here's how location, purpose, and sharing differ:

./CLAUDE.md

Common project rules (team-shared)

./.claude/CLAUDE.md

Common project rules (team-shared)

./CLAUDE.local.md

Personal project notes (not shared)

~/.claude/CLAUDE.md

Personal preferences for all projects (personal)

Beginners can start with one CLAUDE.md at the project root.

05Automatically Start CLAUDE.md

If it's hard to write from scratch, you can have Claude Code generate a draft. Running the /init command inside Claude Code analyzes your codebase and generates a starter CLAUDE.md that includes build commands, test instructions, and project rules. If CLAUDE.md already exists, it suggests improvements rather than overwriting it.

This is the recommended workflow for beginners.

1Run /init command

2Review review generated CLAUDE.md, request only improvements

3Approve edits request clean and clear CLAUDE.md

06Principles for Writing Good CLAUDE.md

Good CLAUDE.md is not long. It is clear, specific, and contains only frequently used information. Aim for under 200 lines per file.

Good rules:

- This project uses pnpm.
- Run tests with pnpm test.
- Authentication code is in src/features/auth.
- Explain the modification plan first before making file changes.

Bad rules:

- Write code well.
- Organize it nicely.
- Test appropriately.
- Be secure on your own.

Bad expression

Good expression

Write code cleanly

First review that functions don't exceed 50 lines

Run tests well

After edits, first suggest pnpm test candidates

Be careful with security

Don't read .env, credentials, or *.pem files

Auto-refactor

Explain change scope and risk factors before refactoring

07CLAUDE.md Is Project Information, Not a Command

CLAUDE.md is a file that provides project context to Claude. It's better to write it fact-focused rather than as overly strong commands.

Good example:

## Project Information
- This repository uses pnpm.
- The default test command is pnpm test.
- Auth code is in src/features/auth.
- API client is in src/lib/api.ts.

Less good example:

You must always and absolutely only use pnpm.
Never make a mistake.
Follow my instructions unconditionally.

CLAUDE.md is not a mandatory security mechanism. CLAUDE.md and auto memory are context passed to Claude, not forced settings. To block certain behavior, you need to use permissions or hooks.

08CLAUDE.md Template for Beginners

# CLAUDE.md

## Project Overview
This project is an application for [project purpose].

## Tech Stack
- Language: [example: TypeScript]
- Framework: [example: Next.js]
- Package Manager: [example: pnpm]
- Testing Tool: [example: Vitest, Jest, Playwright]

## Main Commands
- Dev server: [example: pnpm dev]
- Test: [example: pnpm test]
- Lint: [example: pnpm lint]
- Build: [example: pnpm build]

## Main Folders
- src: application source code
- src/components: UI components
- src/features: feature-based code
- src/lib: common utilities
- tests: test code

## Work Rules
- Explain the modification plan first before editing files.
- Break large tasks into small steps.
- Distinguish between files to modify and files not to touch.
- Summarize changes based on git diff after edits.
- Explain test command candidates and reasons before running.

## Code Style
- Follow existing code style first.
- Don't do unnecessary large-scale refactoring.
- Separate functionality changes from formatting changes when possible.
- Before adding new packages, check if existing dependencies can solve it.

## Warnings
- Don't read .env, .env.local, credentials, or private key files.
- Don't output sensitive information like API keys, tokens, or passwords.
- Always explain deletion, deployment, or DB migration commands before running.
- Explain the reason before changing package.json or lock files.

After writing, ask Claude to review it.

09Examples by Project Type ① Web Frontend

This is an example for a web frontend project.

# CLAUDE.md

## Project Overview
This project is a React-based frontend application.

## Main Commands
- Dev server: pnpm dev
- Test: pnpm test
- Lint: pnpm lint
- Build: pnpm build

## Main Folders
- src/components: shared UI components
- src/pages or src/app: routing
- src/features: feature-based code
- src/lib: API client and utilities
- tests: test code

## Work Rules
- Find related components and usage locations first before UI changes.
- Separate style changes from logic changes when possible.
- Explain changes that may affect accessibility.
- After edits, suggest test command candidates if needed.

## Warnings
- Don't read .env files.
- Before adding new UI libraries, check if possible with existing components.

10Examples by Project Type ② Backend API

This is an example for a backend API project.

# CLAUDE.md

## Project Overview
This project is a REST API server.

## Main Commands
- Dev server: pnpm dev
- Test: pnpm test
- Lint: pnpm lint
- Build: pnpm build

## Main Folders
- src/routes: API routes
- src/controllers: request handling
- src/services: business logic
- src/repositories: data access
- tests: test code

## Work Rules
- Check routes, services, and tests together before API changes.
- If response format changes, check affected tests.
- Don't run DB migrations right away; explain the plan first.
- Follow existing error handling patterns.

## Warnings
- Don't read credentials, private key, or .env files.
- Don't run commands that may affect production databases.

11Examples by Project Type ③ Library

This is an example for a library project.

# CLAUDE.md

## Project Overview
This project is a reusable library package.

## Main Commands
- Test: pnpm test
- Type check: pnpm typecheck
- Build: pnpm build
- Release validation: pnpm lint && pnpm test && pnpm build

## Main Folders
- src: library source code
- examples: usage examples
- tests: test code
- docs: documentation

## Work Rules
- Explain whether public API changes are breaking changes.
- When changing type definitions, check usage examples and tests together.
- Always explain the reason before modifying release-related files.
- Verify that documentation matches code examples.

## Warnings
- Don't run npm publish commands.
- Don't change package.json version before approval.

12Separating Team CLAUDE.md and Personal CLAUDE.local.md

In team projects, you should separate rules everyone needs to follow from personal preferences.

Team common rules go in CLAUDE.md.

## Team Common Rules
- Use pnpm as the package manager.
- Run pnpm lint and pnpm test before PR.
- Put auth-related code in src/features/auth.

Personal preferences go in CLAUDE.local.md.

## Personal Work Preferences
- Receive explanations in English.
- Always request step-by-step plans before making changes.
- Approve test commands before running them.

It's good to add CLAUDE.local.md to .gitignore so it's not shared.

13What Shouldn't Go in CLAUDE.md

Putting everything in CLAUDE.md can actually lower quality.

Entire long architecture documents

Takes up too much context

Outdated commands

Claude may use wrong commands

Personal preferences

Unnecessary for team members

Passwords and API keys

Risk of exposing sensitive information

One-time task instructions

Unnecessary in the next session

Conflicting rules

Claude becomes unclear which rule to follow

Bad example:

## Secret Information
- DATABASE_URL=postgres://...
- API_KEY=sk-...

Good example:

## Environment Variables
- Refer to .env.example for needed environment variable names.
- Don't read the actual .env file.
- Don't output API key, token, or password values.

14Difference Between CLAUDE.md and Permission Settings

CLAUDE.md is a document you tell Claude about. Permission settings limit what Claude can do. This matters.

15Checking if CLAUDE.md Loads Properly

Inside Claude Code, you can check the CLAUDE.md, CLAUDE.local.md, and rules files loaded in the current session using the /memory command.

If Claude doesn't seem to be following CLAUDE.md, check it this way.

/memory

Then you can ask Claude.

Based on the CLAUDE.md content loaded in the current session,
summarize the work rules for this project.

If there's a problem, check the following.

Claude doesn't know the rules

Check if the file appears in /memory

Rules aren't being followed

Check if the wording is too vague

Conflicts with other rules

Check CLAUDE.md in parent/child folders

File is too long

Keep only core rules

Task that must be executed

Consider hooks or permission settings

16Splitting CLAUDE.md in Large Projects

At first, one CLAUDE.md is enough. But as projects grow, you can split rules.

my-project/
├── CLAUDE.md
├── frontend/
│   └── CLAUDE.md
├── backend/
│   └── CLAUDE.md
└── infra/
    └── CLAUDE.md

For beginners, start this way.

Small project → one root CLAUDE.md
Large project → add CLAUDE.md by large areas like frontend/backend
Team project → separate common and personal rules

One thing to watch for is rule conflicts. If there are conflicts like these, Claude can get confused, so it's good to regularly clean up outdated or conflicting guidelines.

17Import Other Documents

Instead of putting all content directly in CLAUDE.md, you can import other files. You can import other files using @path/to/import syntax, and both relative and absolute paths work.

Example:

# CLAUDE.md

## Project Rules
This repository uses pnpm.
Explain the plan first before making changes.

## Additional Documents
@docs/architecture.md
@docs/testing.md

The recommended approach for beginners is this:

Put only core rules in CLAUDE.md.
Put long documents in the docs/ folder.
Import only needed documents with @.

However, too many imports can increase context size, so it's better to start with one short CLAUDE.md.

18Operating CLAUDE.md in a Team

In a team, CLAUDE.md should be managed as an AI work guide, not just personal notes.

Team operation principles:

1. Put only common team rules in CLAUDE.md.
2. Put personal preferences in CLAUDE.local.md.
3. Update CLAUDE.md when commands change.
4. Review CLAUDE.md changes in PR.
5. Never put sensitive information in it.

Good things to put in team CLAUDE.md:

Package manager

Use pnpm

Test command

pnpm test

Check before PR

pnpm lint && pnpm test

Architecture rules

Feature-based folder structure

Prohibitions

Don't read .env, don't auto-run DB migrations

Review criteria

Check security, exception handling, missing tests

19When CLAUDE.md Needs Updating

If you leave the CLAUDE.md you created unchanged, it becomes outdated documentation. Update it in these cases.

Package manager change

npm → pnpm

Test command change

npm test → pnpm test

Folder structure change

src/pages → src/app

New rules introduced

import alias, naming conventions

Claude repeats the same mistake

Add that rule more clearly

Team members ask the same question

Enhance project description

Sensitive file structure changes

Add restricted file list

When Claude repeats the same mistake for the second time, or when code review finds something Claude should know, or when you repeat the same explanation every session, it's good to add it to CLAUDE.md.

20Common Beginner Mistakes

Mistake 1. Writing CLAUDE.md too long

Bad example: 500 lines of full architecture docs, all meeting notes, all API specs, old TODO lists

Good example: Core rules, package manager, test commands, plan-first rule, don't read .env

Mistake 2. Using vague language

Bad example: "Write good code", "test well"

Good example: "When adding features, first suggest related test candidates", "Summarize changes based on git diff after edits"

Mistake 3. Putting personal preferences in team files

Bad example: "Always explain in English", "Always be very detailed"

If it's not a rule all team members need, put it in CLAUDE.local.md.

Mistake 4. Including sensitive information

Bad example: "The real API key is sk-...", "DB password is ..."

Good example: "Don't read the actual .env file", "Check needed environment variable names based on .env.example"

Mistake 5. Confusing mandatory rules with guidance rules

Writing something in CLAUDE.md doesn't mean 100% enforcement. Use permission settings together if you want to enforce something.

21Checklist

Created CLAUDE.md in project root

☐

Wrote project purpose briefly

☐

Wrote main commands

☐

Wrote main folder structure

☐

Wrote plan-first rule

☐

Wrote git diff check rule

☐

Wrote test commands

☐

Wrote sensitive file warnings

☐

Separated personal preferences to CLAUDE.local.md

☐

Didn't include too long or outdated content

☐

Verified load status with /memory

☐

Considered permission settings for mandatory blocks

☐

Section 09 · Summary

What to Remember from This Section

CLAUDE.md is a file that stores content you'd otherwise explain to Claude Code repeatedly.

Here's the core idea.

Put frequently repeated explanations in CLAUDE.md, and use permission settings to block actions that must be prevented.

Beginners only need to remember these basic items.

Project overview
Main commands (dev server, test, lint, build)
Main folder structure
Work rules (plan first, check git diff, step-by-step progress)
Warnings (.env, credentials, delete/deploy commands, etc.)

A well-made CLAUDE.md means you don't have to educate Claude Code from scratch every time. As projects grow, the value of CLAUDE.md grows too.

Next Section

Section 10. Understanding Configuration File Structure

10. Understanding Configuration File Structure

01Core Concepts

Claude Code's settings are divided into user-wide settings, project-shared settings, project-personal settings, and enterprise-managed settings.

Beginners can understand it this way:

Settings to apply across all my projects

~/.claude/settings.json

Settings to apply to all team members on this project

.claude/settings.json

Settings I use alone on this project

.claude/settings.local.json

Settings the company or organization enforces

managed settings

02Why It Matters

If you don't understand the configuration file structure, several problems arise.

Putting settings in the wrong location

Putting personal settings in the shared team file

Unnecessary settings get shared with team members

My output style, my experimental settings get committed

Sensitive file blocking doesn't work

Missing the rule to deny access to .env

Permission settings get tangled

Not knowing which setting allowed what

Conflict with company policy

Not understanding why managed settings override yours

Claude behaves unexpectedly

Local settings override project settings

Understanding the configuration structure lets you control Claude Code more efficiently.

03Configuration File Locations at a Glance

The three most important configuration files are:

Configuration file

Location

User settings

~/.claude/settings.json

Project shared settings

.claude/settings.json

Project local settings

.claude/settings.local.json

Whether each file is included in Git:

User settings

No (outside project)

Project shared settings

Yes (for team sharing)

Project local settings

No (personal only)

04Folder Structure View

Configuration files in your project are organized like this:

my-project/
├── .claude/
│   ├── settings.json
│   └── settings.local.json
├── CLAUDE.md
├── package.json
└── src/

User-wide settings live outside the project.

~/.claude/settings.json

On Windows, ~/.claude is typically interpreted like this:

%USERPROFILE%.claude

05Understanding Configuration Priority

Claude Code settings follow a priority order when the same item exists in multiple places.

Priority 1

Managed settings (enforced by company or organization)

Priority 2

CLI flags (temporary, this run only)

Priority 3

.claude/settings.local.json (only for me on this project)

Priority 4

.claude/settings.json (all team members on this project)

Priority 5

~/.claude/settings.json (default for all my projects)

06Understanding Priority · Real-World Example

Even if user settings look like this:

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

If project settings look like this:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

On that project, the project settings take priority.

My global defaults are overridden by project rules. Project rules are overridden by my local settings. But enterprise-managed settings cannot be overridden by me.

07User Settings: `~/.claude/settings.json`

Put your personal settings you want applied across all projects here.

{
  "outputStyle": "Explanatory",
  "permissions": {
    "defaultMode": "plan"
  }
}

Personal output style

Use the same response style across all projects

Default permission mode

When you always want to start in Plan Mode

Tools you use frequently

Personal settings unrelated to projects

Personal environment variables

Values you need in every session

08Project Shared Settings: `.claude/settings.json`

Put settings your entire team must follow here.

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm -rf *)",
      "Bash(git push *)"
    ],
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(pnpm test)",
      "Bash(pnpm lint)"
    ],
    "defaultMode": "plan"
  }
}

Block access to sensitive files

Team-wide security rules

Allow project test commands

Reduce repeated approvals

Block dangerous commands

Prevent mistakes

Team-wide hooks

Same quality checks for everyone

Project plugins

Standardize tools across the team

09Project Local Settings: `.claude/settings.local.json`

Put settings that only you use on this project here.

{
  "outputStyle": "Explanatory",
  "env": {
    "DEBUG": "app:*"
  }
}

My experimental settings

No need to share with team members

My terminal environment variables

Different from others' environments

Personal output style

Not a team rule

Temporary permission allowance

Can be removed after testing

10Minimal Configuration Example for Beginners

You don't need complex configuration from the start. As a beginner, creating just one .claude/settings.json file in your project is enough.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "defaultMode": "plan",
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(pnpm test)",
      "Bash(pnpm lint)",
      "Bash(pnpm build)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(git push *)",
      "Bash(npm publish *)"
    ]
  }
}

11What the Minimal Configuration Does

The above configuration does three things:

defaultMode: "plan"

Makes planning happen before making changes

allow

Reduces repeated approvals for safe commands

deny

Blocks sensitive files and dangerous commands

Beginners don't need to create complex configurations all at once. Starting with just sensitive file blocking, dangerous command blocking, and Plan Mode defaults is enough.

12Why Include `$schema`

Adding $schema at the top of your configuration file lets your editor help with autocomplete and validation.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json"
}

With $schema, editors like VS Code and Cursor that support JSON Schema can provide autocomplete and inline validation.

Beginners should include $schema when creating configuration files.

13Understanding Permission Configuration Structure

The most commonly used setting is permissions. Its basic structure is:

{
  "permissions": {
    "allow": [],
    "deny": [],
    "ask": [],
    "defaultMode": "plan"
  }
}

allow

Tools or commands to permit

deny

Tools or commands to block

ask

Tools or commands to ask about before running

defaultMode

Default permission mode when Claude Code starts

14Permission Configuration · Real-World Example

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(pnpm test)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Bash(rm -rf *)",
      "Bash(git push *)"
    ],
    "ask": [
      "Bash(pnpm install *)",
      "Bash(docker *)"
    ],
    "defaultMode": "plan"
  }
}

With this setup, git status, git diff, and pnpm test run quickly, while .env reads and dangerous commands are blocked.

15Setting the Permission Mode

defaultMode determines which permission mode Claude Code starts in.

default

Standard approval flow

plan

Plan first before making changes (recommended)

acceptEdits

Allow edits more easily

bypassPermissions

Skip permission checks (not recommended)

If you want to run Plan Mode just once from the terminal:

claude --permission-mode plan

16When Configuration Files Are Applied

Claude Code detects configuration file changes and reloads most settings even in running sessions.

Permission settings change

Usually applies immediately

Hooks change

Usually applies immediately

Model change

Use /model or restart to confirm

outputStyle change

Use /clear or restart to confirm

After changing settings, confirm in Claude Code like this:

/status

17Checking Current Settings with `/status`

To confirm settings are applying correctly, use /status in Claude Code.

User settings

~/.claude/settings.json is loaded

Project settings

.claude/settings.json is loaded

Project local settings

.claude/settings.local.json is loaded

Enterprise managed settings

Enterprise settings are loaded

Error message

JSON syntax or validation issue

18Avoiding Configuration File Syntax Errors

settings.json is a JSON file. Watch out for commas, quotes, and comments.

Bad example (trailing comma):

{
  "permissions": {
    "defaultMode": "plan",
  }
}

Good example:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

JSON doesn't support comments either. If there are issues after editing settings, check errors with /status.

19Recommended Configuration Structure for Team Projects

On team projects, split configurations like this:

Rules for the entire team

.claude/settings.json

Personal experimental settings

.claude/settings.local.json

Default settings for all my projects

~/.claude/settings.json

Clear roles for each file reduce configuration conflicts among team members.

20The Difference Between `CLAUDE.md` and `settings.json`

This is what confuses beginners most.

File format

CLAUDE.md

Markdown

settings.json

JSON

Purpose

Explain project context to Claude

Configure Claude Code behavior

Enforcement

Low

High

Best for

Coding rules, architecture explanations

Permissions, environment variables, hooks

Use CLAUDE.md for explanations and rules, settings.json for actual permissions and blocking

21Where to Put Environment Variables

You can put env in Claude Code settings.

{
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "app:*"
  }
}

But be careful. Don't put real API keys or passwords in env.

Manage sensitive information in .env or secret management tools, and block Claude from reading them.

22Setting outputStyle

If you want to change your response style, you can set outputStyle.

{
  "outputStyle": "Explanatory"
}

To open the settings menu in Claude Code:

/config

Beginners should put output style in personal local settings rather than team shared settings.

Team-wide response style

Only in .claude/settings.json when needed

My personal response style

.claude/settings.local.json

23Temporarily Applying Settings as CLI Options

You can pass options just for this run without changing configuration files.

claude --permission-mode plan

This command starts only this session in Plan Mode.

The relationship between CLI options and file settings:

One-time experiment

CLI flag

Personal settings you'll keep using

~/.claude/settings.json

Settings to share with your team

.claude/settings.json

24How Settings Are Merged

Settings don't simply mean "a higher file completely overwrites a lower one."

For example, if user settings have an allow array:

"allow": ["Bash(git status)"]

And project settings have a different array:

"allow": ["Bash(pnpm test)"]

Both can be applied and merged.

List settings can be merged together. Single-value settings are won by higher priority.

25Don't Manually Edit the State File `~/.claude.json`

There's also a file called ~/.claude.json. But beginners shouldn't edit it directly.

~/.claude.json stores OAuth sessions, local scope MCP server configurations, per-project state, allowed tools, trust settings, caches, and more.

~/.claude/settings.json

OK to edit directly

.claude/settings.json

OK to edit directly

.claude/settings.local.json

OK to edit directly

~/.claude.json

Not recommended for beginners to edit

When changing settings, only modify the settings.json family.

26Common Mistakes Beginners Make ①

Mistake 1. Putting personal settings in shared team files

Bad example:

{
  "outputStyle": "my personal style",
  "env": {
    "MY_LOCAL_DEBUG": "1"
  }
}

Team-shared files like .claude/settings.json should only have settings the entire team needs. Put personal settings in .claude/settings.local.json.

27Common Mistakes Beginners Make ② · ③

Mistake 2. Putting sensitive information in `env`

Bad example:

{
  "env": {
    "API_KEY": "real-secret-key"
  }
}

Mistake 3. JSON syntax errors

Bad example (trailing comma):

{
  "permissions": {
    "defaultMode": "plan",
  }
}

28Common Mistakes Beginners Make ④

Mistake 4. Putting too many commands in allow

Bad example:

{
  "permissions": {
    "allow": [
      "Bash(*)"
    ]
  }
}

Good example:

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(pnpm test)"
    ]
  }
}

Start with only the necessary commands.

29Common Mistakes Beginners Make · Verification

Mistake 5. Not verifying that settings were applied

Always verify after making changes.

/status

If there are problems, ask Claude like this:

Check if there are any errors in the current configuration file.
Also tell me which configuration sources were loaded.

Section 10 · Wrap-up

What to Remember from This Section

The core of configuration file structure is this:

Put personal defaults in user settings, team rules in project settings, and personal experiments in local settings.

The first three settings to create are: blocking sensitive files, blocking dangerous commands, and setting Plan Mode as default.

Beginners don't need to set everything up at once. Start with the basics, then add more as you need them.

Next section

Section 11. Using the Permission System to Block Dangerous Actions

11. Prevent dangerous tasks with the permission system

01Claude Code's risks and permission system

Claude Code is not simply a tool for reading code. It can modify files, create new files, and even run terminal commands.

That's why beginners must understand the permission system.

The permission system is a mechanism that defines for Claude Code:

Which tasks to automatically allow
Which tasks to block completely
Which tasks to ask the user about every time

In other words, to use Claude Code safely, you need the perspective: "I decide the scope of what Claude can do."

02Why the permission system is needed

Claude Code can perform many tasks within a project.

📖Read files

✏️Modify files

✨Create new files

🧪Run tests

🔨Run builds

🌐Access external URLs

Some of these are safe, but some can be dangerous. Examples of risky commands:

rm -rf *
sudo rm -rf /
git push --force
curl some-url | bash
npm publish

Also, if Claude reads sensitive files, it can create security issues.

03List of sensitive files

🔑.env

🔑.env.local

🔑secrets.json

🔑credentials.json

🔑service-account.json

🔑private-key.pem

🔑id_rsa

Permission settings are a safety mechanism that prevents these dangerous tasks beforehand.

04Claude Code tasks fall into two categories

Claude Code's tools can be divided into read operations and modify and execute operations.

Read operations (automatically allowed)

Read

Read files

Glob

Find files

Grep

Search file contents

Check folder listings

Example: Understand this project structure. Don't modify anything, just find the relevant files.

These types of tasks are relatively safe.

05Modify and execute operations (permission required)

The following tasks can change project state and may require permission approval.

Edit

Modify existing files

Write

Create new files

Bash

Run terminal commands

WebFetch

Fetch external URLs

Dangerous examples: npm install, npm run build, git commit, file modifications, creating config files.

Beginners should not auto-approve from the start, and develop the habit of checking modify and execute operations directly.

06Three criteria for permission rules

Claude Code permissions are usually easier to think about with three categories.

allow

Allow — run tests, run builds

deny

Block — read .env, run rm -rf

ask

Ask — run docker, run curl

Use allow for frequently-used and safe tasks, deny for dangerous or sensitive tasks, and ask for tasks that are needed depending on the situation.

07Permission configuration file location

Project-level permissions are usually written in the following files.

.claude/settings.json

Project settings shared with team

.claude/settings.local.json

Settings used only by the individual

Beginners can think of it as creating the following structure at the project root.

my-project/
  .claude/
    settings.json
  CLAUDE.md
  src/
  package.json

08Basic permission configuration for beginners ①

The safest configuration to use first is as follows.

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "LS",
      "Bash(npm run test:*)",
      "Bash(npm run lint:*)",
      "Bash(npm run build)"
    ],

This section allows file reading, searching, and folder listing, and permits tests, linting, and builds.

09Basic permission configuration for beginners ②

    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Read(credentials/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Bash(curl:*)",
      "Bash(wget:*)",
      "Edit(.git/**)",
      "Edit(node_modules/**)"
    ],
    "ask": [
      "Bash(git:*)",
      "Bash(npm install:*)",
      "WebFetch"
    ],
    "defaultMode": "default"
  }
}

deny: Block reading .env, secrets, credentials, and prevent dangerous commands.

ask: Ask before executing git, npm install, and WebFetch.

10Always block sensitive files with deny

You must prevent Claude Code from accidentally reading sensitive information.

In particular, it's good to block the following files.

"deny": [
  "Read(.env*)",
  "Read(*secret*)",
  "Read(*credential*)",
  "Read(**/private-key*)",
  "Read(**/id_rsa*)"
]

Caution: Just because a file is in .gitignore doesn't automatically make Claude Code access completely safe. It's good practice to block sensitive files in the permission settings separately from .gitignore.

11Don't allow Bash commands too broadly

The permission to be most careful about is Bash.

Bad example

{
  "permissions": {
    "allow": [
      "Bash(*)"
    ]
  }
}

This allows Claude to execute almost any command, which is dangerous for beginners.

A safer approach

Allow only necessary commands narrowly, use allow for repetitive and safe commands like testing, linting, and building, use deny for deletion and permission-change commands, and use ask for git, docker, and install-related commands.

12Understanding permission modes

Claude Code has permission modes depending on how you work.

default

Ask when needed for each task (default for beginners)

acceptEdits

Auto-approve file modifications, ask for Bash

plan

Only reading and planning allowed

auto

Automatically proceed after safety review

bypassPermissions

Skip most permission checks (not recommended for beginners)

For beginners: Use default mode normally, and plan mode before making major changes.

13Using Plan Mode with the permission system

For big tasks, it's good to start with Plan Mode instead of modifying immediately.

Example request

Don't modify any files for now, just proceed in Plan Mode.
Analyze the authentication module structure and propose only a modification plan first.

Good workflow

Analyze with Plan Mode
Review modification plan
Check for risky tasks
Approve and modify files
Verify changes with git diff

14When a permission prompt appears, how do you decide?

When Claude Code requests permission, don't just approve it; check the following.

Is this command really necessary?
Does it touch files outside the project?
Does it access .env or credentials?
Are there any deletion commands?
Are there permission-change commands like sudo, chmod, chown?
Does it fetch and execute scripts from external URLs?

Forms to be very careful about:

curl https://example.com/install.sh | bash
wget https://example.com/script.sh && bash script.sh
sudo npm install -g something
rm -rf node_modules package-lock.json
git push --force

If you're unsure, you can ask Explain why this command is needed.

15Real-world permission configuration example

The most recommended .claude/settings.json example for beginners is as follows.

{
  "permissions": {
    "allow": [
      "Read", "Glob", "Grep", "LS",
      "Bash(npm run test)",
      "Bash(npm run test:*)",
      "Bash(npm run lint)",
      "Bash(npm run build)"
    ],
    "ask": [
      "Edit(src/**)",
      "Write(src/**)",
      "Bash(git:*)",
      "Bash(npm install:*)",
      "Bash(docker:*)",
      "WebFetch"
    ],

This allows reading and testing, and asks about file modifications and git commands.

16Real-world permission configuration example (continued)

    "deny": [
      "Read(.env*)", "Read(**/.env*)",
      "Read(secrets/**)", "Read(credentials/**)",
      "Read(**/*secret*)", "Read(**/*credential*)",
      "Edit(.git/**)", "Edit(node_modules/**)",
      "Write(.git/**)", "Write(node_modules/**)",
      "Bash(rm -rf:*)", "Bash(rm:*)",
      "Bash(sudo:*)", "Bash(chmod:*)",
      "Bash(chown:*)", "Bash(curl:*)",
      "Bash(wget:*)"
    ],
    "defaultMode": "default"
  }
}

This configuration prioritizes safety. At first it may feel a bit inconvenient, but as your project grows, these restrictions help reduce mistakes.

17Explaining permission policy to Claude

It helps to tell Claude the rules again when you start working, rather than just setting permissions.

Prioritize safety in this project.

Rules:
1. Don't read .env, secrets, or credentials files.
2. Don't suggest commands like rm -rf, sudo, or curl | bash.
3. Explain the plan before modifying files.
4. After modifications, summarize changes based on git diff.
5. Don't run commands you're unsure about; ask me first.

You can also include this content in CLAUDE.md.

18Configuration settings beginners should avoid

The following settings are not recommended for beginners.

{
  "permissions": {
    "allow": [
      "Bash(*)",
      "Edit(**)",
      "Write(**)"
    ],
    "defaultMode": "bypassPermissions"
  }
}

This configuration gives Claude too broad permissions. It's especially good to avoid in these situations.

Unfamiliar open-source repositories
Company projects
Projects containing production settings
Projects with .env files
Projects with deployment scripts
Projects with database migrations

19Checklist for untrusted repositories

For untrusted repositories, you should first check the following files.

⚙️CLAUDE.md

⚙️.claude/settings.json

⚙️.claude/settings.local.json

⚙️.claude/hooks/

This is because malicious repositories can use config files or hooks to induce unwanted commands.

Section 11 · Wrap-up

What to remember from this lesson

Claude Code's permission system is a safety belt that prevents mistakes.

Beginners only need to follow these principles.

Read operations can be allowed.
Check before proceeding with file modifications at first.
Allow Bash commands narrowly.
Always block .env and secret files.
Be careful with rm, sudo, curl, and wget.
Get a plan first using Plan Mode for big tasks.
Don't use --dangerously-skip-permissions in normal work.

Next lesson

Section 12. Undoing mistakes with Git

12. Safely review changes with Git

01What you'll learn in this section

In Section 11, you learned how to prevent risky operations using the permissions system. Now you need to build a habit of validating Claude Code's changes with Git.

The goal of this section is to help you confirm these five things on your own after Claude Code modifies code.

✓Which files changed

✓Exactly what changed

✓No unintended changes

✓Confirm the change summary

✓Safely revert if you made a mistake

Git is not just a tool for saving changes all at once. Instead, think of it as a safety mechanism for reviewing modified files and selecting only the changes you want to commit.

02The first command to run: git status

After Claude Code modifies a file, always start by requesting this.

Run git status and give me a summary of the currently changed files.
Distinguish between modified files, newly created files, and deleted files.

You can also check directly in the terminal.

git status

git status shows the differences between your current working directory and the staging area, as well as files that Git is not yet tracking.

As a beginner, you only need to watch for these three states when viewing git status output.

modified

An existing file has been changed — verify it's the file you intended

new file / untracked

A new file was created — verify Claude created it

deleted

A file has been deleted — always verify it wasn't an accidental deletion

One important thing to note: git status alone doesn't show you what changed. git status shows you "which files changed," while git diff (covered next) shows you "what changed within the files."

03Viewing actual changes: git diff

Once you've confirmed the list of changed files, next review the differences.

git diff

Here's how to ask Claude for help.

Review git diff and explain the changes in a way a beginner can understand.
For each file, describe what was added, what was deleted, and why this change is needed.

As a beginner, you only need to understand these symbols in the diff first.

- deleted line
+ added line

For example, if you see this diff:

- const timeout = 3000;
+ const timeout = 10000;

This means the timeout value was increased from 3 seconds to 10 seconds. At this point, you can ask Claude:

In this diff, pick out only the parts where behavior changes.
Distinguish between simple formatting changes and actual logic changes.

This question is important because when Claude modifies multiple files, functional changes and formatting changes can get mixed together.

04Distinguishing diff before and after staging

In Git, "changes in progress" and "changes to include in the commit" are separate.

The diff you see before running git add:

git diff

After staging, to see what will actually go into the commit:

git diff --staged

The recommended workflow for beginners is:

git status
git diff
git add <filename>
git diff --staged
git commit

Request it from Claude like this:

Don't git add yet; review git diff first.
If everything looks good, suggest which files I should stage.

After staging, verify again:

Review git diff --staged and summarize what will go into this commit.
Also check if any unnecessary files got included.

05Requesting a pre-commit review from Claude Code

Claude Code is directly connected to Git and can help with commit messages and PR creation. However, as a beginner, you should ask Claude to separate review from execution rather than asking to commit immediately.

A sample prompt to request review before committing:

Review the current changes before committing.
1. Check the list of changed files with git status.
2. Check the actual changes with git diff.
3. Look for unintended changes, risky changes, or possible sensitive data exposure.
4. Tell me which parts need testing.
5. Suggest a commit message, but don't commit yet.

The key is the last sentence.

Don't commit yet.

06Requesting a commit message

Once you've determined the changes are safe, request a commit message.

Propose 3 commit messages for this change.
First check if the project uses conventional commits,
and format them accordingly if it does.

Conventional commit examples:

fix: handle empty user profile response
feat: add validation for signup form
refactor: simplify auth token parsing

If you want to let Claude handle the commit directly, say:

Check git status and git diff --staged again,
and if everything is fine, commit with the suggested message.
Show me the list of files to be included before committing.

07Basic workflow for undoing mistakes

Reverting in Git can be risky, so beginners should first distinguish between different situations.

Undoing file modifications before committing

If you want to discard changes to a specific file:

git restore <filename>

Request it from Claude like this:

Check if there are any uncommitted changes that are safe to revert.
Suggest the revert command but don't execute it yet.

Canceling only git add

To keep file modifications but unstage them:

git restore --staged <filename>

This command removes files from the commit candidates, but does not delete the file contents.

08When you want to revert a recent commit

Adjusting the commit itself requires extra caution. For beginners, follow this principle.

Principle

Never reset commits that have been pushed to the remote repository on your own. First explain the situation to Claude and have them compare whether revert or reset is better.

Safe question example (if you haven't pushed yet):

I want to revert the commit I just made.
I haven't pushed it yet.
Explain which of reset, revert, or amend is safest,
and don't execute the command until I approve.

If you've already pushed:

I want to revert a commit that's already been pushed to the remote repository.
Prioritize safe methods that don't rewrite history.

09Connecting Claude Code permissions and Git safety lines

This section links to Section 11's permissions system. Claude Code starts with read-only permissions by default, and requests explicit approval for additional tasks like file editing, test execution, or command execution.

Also, the .git directory is included in protected paths, so dangerous Git commands are not auto-approved. The recommended principle for beginners is:

Auto-approved

git status, git diff, git log

Requires approval

git add, git commit, git push

Denied

git reset --hard, git clean -fd, git push --force

This configuration is for beginner learning. In real projects, adjust it to match your team's policies and branching strategy.

10Verifying before creating a PR

Claude Code can help create PRs too. Here's the beginner-friendly prompt for reviewing before creating a PR.

Review the current changes before creating a PR.
1. Check git status
2. Check git diff --staged
3. Verify if testing is needed
4. Suggest a PR title
5. Draft PR description
6. Summarize risks the reviewer should watch for
Don't create the PR yet.

A good PR description follows this structure.

## Summary of changes
-
## Testing
-
## Points for reviewer to verify
-
## Risk factors
-

11Beginner safety routine

After Claude Code modifies code, repeat this routine.

git status
git diff

Then ask Claude:

Review the current changes.
Separate intended changes from unintended ones and explain.

If everything looks good, stage the files.

git add <filename>

Verify again after staging.

git diff --staged

Finally, commit.

git commit -m "message"

The most important habit for a beginner is this one sentence.

Don't believe Claude's code just because they changed it. Verify with Git.

Section 12 · Wrap-up

Section 12 Key Takeaways

git status is the command to check which files changed.

git diff is the command to check what changed within files.

git diff --staged is the command to check what changes will actually go into the commit.

Even if you let Claude Code handle commits, you must always verify the list of changed files and a diff summary before committing.

Revert commands have different risk levels depending on the situation, so it's safest not to auto-approve reset --hard, clean -fd, and push --force at the beginner stage.

Next section

Section 13. Making model selection easy to understand

13. Understanding model selection easily

01Don't overthink model selection

Choosing a model in Claude Code can seem complicated at first. You encounter names like opus, sonnet, haiku, default, opusplan, sonnet[1m].

But as a beginner, you can understand it like this:

Haiku

Fast and affordable model — simple questions, file summaries, brief exploration

Sonnet

Balanced model — general coding, bug fixes, test writing

Opus

High-performance model — complex design, large refactoring, difficult root cause analysis

1M context

For long sessions and large codebases — working with many files over extended periods

opusplan

Plan with Opus, execute with Sonnet — efficient planning followed by implementation

sonnet is an alias for the latest Sonnet for everyday coding work, opus is an alias for the latest Opus for complex reasoning tasks, and haiku is an alias for a fast and efficient Haiku for simple work. opusplan is a special mode that uses Opus during plan mode and switches to Sonnet during execution.

02A sense of the main models as of now

As of the writing date, the official model comparison highlights Claude Opus 4.8, Claude Sonnet 4.6, and Claude Haiku 4.5 as the latest comparison models. Opus 4.8 is the strongest for complex reasoning and agentic coding, Sonnet 4.6 balances speed and intelligence, and Haiku 4.5 is the fastest.

For beginners, think of it this way:

Haiku

Fast helper — "Explain what this file does", "Find only the TODOs"

Sonnet

Default developer — "Fix this bug", "Add tests", "Modify this API logic"

Opus

Senior architect — "Refactor the auth structure", "Analyze this complex failure"

Model pricing also differs. Opus 4.8 costs $5 per 1M input tokens and $25 per 1M output tokens, Sonnet 4.6 is $3 input and $15 output, and Haiku 4.5 is $1 input and $5 output. Since prices change, this reflects the writing date only. In actual teaching, checking the official pricing table should become a habit.

03When you can use the default setting as-is

As a beginner, you don't need to change models frequently from the start. Claude Code has a default option, which is the recommended base model for your account type or environment.

According to official documentation:

Max, Team Premium, Enterprise pay-as-you-go, and Anthropic API default to Opus 4.8
Pro, Team Standard, and Enterprise subscription seats default to Sonnet 4.6
Bedrock, Vertex, and Foundry default to Sonnet 4.5

For beginners, this principle is the safest.

Start with default. If it's slow or expensive, downgrade to Sonnet or Haiku. If you get stuck on a hard problem, upgrade to Opus.

You can ask Claude like this:

Determine which model would be best for my current task.
Among fast, balanced, and high-performance models,
explain which would be good to use and why.

04Check and change your current model

To check or change your model in Claude Code, use this command in your session:

/model

If you want to switch to a specific model immediately, type:

/model sonnet
/model opus
/model haiku

When starting a session from the terminal, type:

claude --model sonnet

You can also set it via environment variable:

ANTHROPIC_MODEL=opus

However, when you change models, the new model will re-read your existing conversation history for the next response. In long sessions, this can increase cost and time, so it's best to switch models only when necessary.

05When is Haiku good to use

Haiku is a fast and cost-efficient model. In official model comparisons, Haiku 4.5 is classified as the fastest model.

Haiku is suitable for:

Just summarize what this file does
Find where the config file is in this folder
Read the README and summarize just the execution steps
Extract only key keywords from this error log

However, if you ask Haiku to make too complex a judgment, the quality of results may suffer. For example, with authentication structure changes, database migrations, or large refactoring plans—tasks where mistakes are costly—Sonnet or Opus is better than Haiku.

Reading, summarization, and brief exploration may be enough for Haiku. Code changes and design decisions should use Sonnet or higher.

06When is Sonnet good to use

Sonnet is the most well-balanced choice for everyday use in Claude Code. Official documentation describes the sonnet alias as the latest Sonnet model for routine coding work.

Sonnet is suitable for:

Find the cause of this bug and plan a fix
Add input validation to the signup form
Follow the existing test style and add tests
Analyze lint errors and propose safe fixes

Most beginners can think of Sonnet as their default development model.

General development work = Sonnet

Signs that Sonnet isn't enough:

Fixing the same issue multiple times still fails

Deeper root cause analysis is needed

Multiple modules' structures need to change at once

Architectural decisions are needed

Claude frequently changes the plan

A higher-performance model may help

Handling security, payments, or permissions logic

High cost of mistakes requires caution

In these cases, upgrading to Opus or using opusplan with plan mode is good.

07When do you need to use Opus

Opus is suited for complex reasoning and long-horizon tasks. The official model overview describes Opus 4.8 as the strongest for complex reasoning, long-horizon agentic coding, and tasks requiring high autonomy.

Opus is needed for:

Analyze the authentication structure of this codebase and plan a refactor
Reason about a failure cause by looking at logs, code, and configuration together
Review whether a payment logic change is secure
Compare multiple approaches and suggest the safest design

Typical situations where Opus is good:

Large refactoring

Multiple files and dependencies must be viewed at once

Architecture design

Not just code changes but structural decisions are needed

Difficult bugs

Symptoms and root causes may be far apart

Security, permissions, payments

High cost of mistakes makes reasoning quality critical

However, Opus may have higher costs. Especially with the latest Opus and Sonnet models, adjusting effort can be a better control tool than switching models.

08Divide planning and execution with opusplan

opusplan is a very useful option for beginners. In plan mode, it uses Opus for complex reasoning and architecture decisions, then switches to Sonnet in execution phase for implementation.

In other words, here's the idea:

Plan smartly, execute efficiently.

How to use:

claude --model opusplan

Or during a session:

/model opusplan

Recommended situations:

Use Plan mode to first create a refactoring plan, then after approval, implement step by step
This feature addition has broad impact. First investigate related files and create a plan, then implement after my approval

For beginners, opusplan is a good compromise between "always using expensive models" and "struggling with lightweight models from the start".

09When is 1M context needed

Models like sonnet[1m] and opus[1m] with [1m] are used for long sessions or large codebases. Opus 4.6+ and Sonnet 4.6 support a 1 million token context window, and availability depends on model and plan.

As a beginner, you can judge like this:

Modifying 1-3 files

Rarely needed

Small bug fix

Rarely needed

Analyzing overall project structure

Can be helpful

Continuing a long session

Can be helpful

Large refactoring

May be needed

Just because 1M context is available doesn't mean it's always better. Including more content means the model must read more, and costs and time can grow. It's safer to first have the model read only necessary files, and consider 1M context only if that's insufficient.

10Effort is an auxiliary to model selection

In the latest Claude Code, both model and effort matter. Effort level controls adaptive reasoning—low effort is fast and cheap for simple tasks, and high effort provides deeper reasoning for complex problems.

Opus 4.8 and Opus 4.7 support low, medium, high, xhigh, max, and Opus 4.6 and Sonnet 4.6 support low, medium, high, max.

By beginner standard:

low

Brief summaries, simple exploration

medium

General tasks when cutting costs

high

Basic coding work

xhigh

Complex design, difficult bugs

max

Very hard problems when deep analysis is needed

Configure like this:

/effort
/effort high

To set it when starting:

claude --model opus --effort xhigh

The key point is this:

Adjusting effort before changing models is also an option.

11Don't overuse ultrathink

Claude Code documentation mentions ultrathink as a way to request deeper reasoning in a single turn. Including ultrathink in your prompt requests deeper reasoning for that turn, but it doesn't change the effort level passed to the API.

Usage example:

ultrathink.
Analyze this bug's cause deeply based on logs and code flow.
Don't fix yet—list possible root causes by priority.

However, using ultrathink every time increases cost and time, and causes excessive reasoning for simple tasks. The principle to remember is:

Don't use it for simple tasks. Use it only for complex cause analysis or important design decisions.

12Don't memorize model names, verify them

Model names change frequently. Official documentation explains that aliases point to provider-recommended versions and can be updated over time. To fix a specific version, use the full model name or set an environment variable.

For example, at Anthropic API, opus currently resolves to Opus 4.8 and sonnet to Sonnet 4.6, but on Bedrock, Vertex, and Foundry, aliases may resolve to different versions.

So it's safer to write in educational guides like this:

Model names in this guide are based on the writing date.
Before actual use, verify with /model screen and official documentation.

For team documentation, it's better to write like this than hardcoding specific model names:

General development work

sonnet

Complex design/refactoring

opus or opusplan

Simple exploration/summarization

haiku

Long sessions/large codebases

opus[1m] or sonnet[1m]

Writing this way means guides age less quickly when model versions change.

13Model selection rules for beginners

As a beginner, you can get by with just these rules:

Start with the default.
Use Sonnet for general development.
Consider Haiku for simple exploration and summarization.
Use Opus for complex design and difficult bugs.
For large tasks, divide planning and execution with opusplan.
Model names can change, so always verify with /model.
If concerned about costs, check usage in the next unit with /usage.

Real-world prompt example:

Recommend a Claude Code model best for this task.

Task details:
- May need to modify multiple files
- Must first understand existing structure
- Must add tests too

Among haiku, sonnet, opus, opusplan, which fits best?
Compare from cost, speed, and accuracy perspectives.
Don't change models yet—just recommend.

14Real-world examples ①②

Example 1. Simple file summarization

/model haiku

Summarize what src/auth/session.ts does
in a way even a beginner can understand.
Don't make any changes.

Example 2. General bug fix

/model sonnet

Investigate the issue where login error messages don't show.
First explain the cause, then propose a fix plan.
If I approve, go ahead and fix it.

15Real-world examples ③④

Example 3. Large refactoring plan

/model opusplan

Use Plan mode to create an auth module refactoring plan.
Read related files and map impact scope and risk factors.
Don't modify files yet.

Example 4. Difficult failure analysis

/model opus
/effort xhigh

ultrathink.
Since the recent deployment, payment completion callbacks fail intermittently.
Look at logs, router, and payment service code together
and analyze possible causes by priority.
Don't fix yet.

Section 13 · Summary

Section 13 Key Takeaways

Model selection in Claude Code isn't about "choosing the single best model." It's about choosing the right model for your task's difficulty.

Model selection criteria

haiku is suited for fast exploration and summarization.

sonnet is suited for general coding work.

opus is suited for complex reasoning, design, and difficult bugs.

opusplan is a compromise that uses a high-performance model for planning and executes efficiently.

Use /model to check and change your current model.

/effort is an auxiliary tool to adjust reasoning strength within a model.

Model names and defaults can change, so always check official documentation and the /model screen.

In the next Section 14, we cover how to track costs and reduce waste.

14. How to check costs and reduce waste

01What causes costs

Claude Code costs are fundamentally based on token usage. Tokens are the units Claude uses to calculate input it reads, output it generates, information exchanged during tool use, and long conversation context.

For beginners, think of it this way:

Reading many large files

Claude has more to read

Continuing a long session

Previous conversation stays in context

Using high-performance models

Cost per token may be higher

Generating long responses repeatedly

Output tokens increase

Long test and log output

Terminal results go into context

Overusing MCP, subagent, agent team

Separate tools and contexts multiply

Cost grows based on "how much Claude reads, how much you make it think, and how much you make it output."

02Check current usage: /usage

To check costs and usage within a Claude Code session, use this command:

/usage

Three items matter for beginners:

Total cost

Estimated cost for the current session

Total duration

API call or actual work time

Total code changes

Actual code change volume

Important: the dollar amount from /usage is a local estimate. For actual billing, check the usage page in Claude Console.

03Reading /usage results

Here's how to understand example output:

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

A beginner-friendly follow-up prompt:

Looking at my current /usage results, explain
what caused cost growth in a way I can understand.
Among model, context, tool use, and long output,
which had the most impact?

04Use /usage, not /cost

Older guides or documentation may call cost checking /cost. However, the latest Claude Code cost management docs use /usage as the standard command.

In this guide, we standardize as follows:

In current Claude Code, check costs and usage
with /usage.
If older resources mention /cost,
check /usage first.

For educational documentation, write:

Check usage: /usage
Check or set credit limits: /usage-credits

05Situation 1: Having Claude read the entire project

A common beginner request:

Analyze this whole project for me.

This seems convenient but makes Claude read many files, increasing costs.

A better request:

Find files related to login first.
Don't modify code, just list the top 5
likely candidates with reasons.

Or narrow it down:

Don't read the whole project.
Check only package.json, README, and src/auth
first.

06Situation 2: Continuing a long session

As Claude Code sessions grow, previous messages, file contents, and tool results build up in context. When switching to unrelated work, use /clear to start fresh.

When switching tasks, do this:

/clear

But if you want to find the session later, name it first:

/rename auth-bugfix

The beginner rule is simple:

Continue the same task in the same session; start a new session when moving to different work.

07Situation 3: Very long logs and test output

Pasting entire test failure logs to Claude increases costs.

Bad example:

Analyze this entire test log for me.

Better request:

Analyze only the first failure cause in this log.
Skip duplicate stack traces and focus on
the actual error message and relevant files.

Build this habit early:

Don't read the entire log.
Just check lines containing ERROR, FAIL,
or Exception and their surroundings.

08Situation 4: Using high-performance models for everything

Opus and similar high-performance models excel at complex design and tough bugs, but not all tasks need them.

A beginner's sense of model costs:

File summary, short exploration

Haiku

General bug fixes, test writing

Sonnet

Complex design, large refactoring

Opus or opusplan

09Reduce costs through model selection

Revisiting Section 13's model selection through a cost lens:

simple tasks = haiku
general development = sonnet
hard judgments = opus
deep planning, efficient execution = opusplan

To switch models mid-session, use:

/model sonnet

/model haiku

A cost-conscious practical prompt:

I want to do this task cost-efficiently.
First, check if haiku or sonnet is enough.
Only explain why Opus is needed if it truly is.

10Reduce costs by lowering effort

Beyond changing models, /effort matters for cost management. medium works well for cost-sensitive tasks by reducing token use, high balances most coding work well, and xhigh and max accept more tokens in exchange for deeper reasoning.

Set it with:

/effort medium

/effort high

When cutting costs, ask:

I want to save cost on this task.
Try medium effort, and if accuracy
drops, we'll bump it to high.

11Build context-reduction habits

The most powerful way to cut costs is reducing what Claude reads.

Bad request

Look at the whole codebase and find issues.

Good request

Investigate only the login failure issue.
First find related file candidates, then
read the top 3 and estimate the cause.

Even better

Read only src/auth/login.ts and
src/auth/session.ts first.
If you don't find the cause, suggest
what to read next.

12Using /compact and /clear

Claude Code automatically summarizes conversation history when approaching context limits to optimize costs.

To summarize manually:

/compact

You can specify what to keep during summarization:

/compact keep only decisions so far, files
modified, and test results.

The difference:

/compact

Continuing same work but conversation is long

/clear

Switching to completely different work

/resume

Returning to a previous session

13Be careful with MCP and plugin costs

MCP is powerful, but more connections mean more tools Claude must consider. Disable MCP servers you aren't actively using via /mcp.

The beginner rule:

Don't connect many MCPs upfront.
Connect only what you need, and
turn off unused servers.

Check with:

/context

/mcp

14Don't make CLAUDE.md too long

CLAUDE.md is great for telling Claude project rules each session, but too long and it consumes context every time. Since CLAUDE.md loads into context at session start, excessive guidelines consume tokens even in unrelated work.

A beginner's CLAUDE.md principle:

Put only always-needed rules in CLAUDE.md.
Move task-specific long instructions to
skills later.

A good CLAUDE.md needs only this much:

14Good CLAUDE.md example

# Project Rules
## Commands
- Test: npm test
- Lint: npm run lint
- Build: npm run build

## Coding Rules
- Maintain TypeScript strict mode.
- Follow existing code style.
- Check related tests before modifying.

## Safety
- Never read or modify .env files.
- Summarize git diff before committing.

15Keep watching costs with statusline

To monitor costs frequently, configure the status line. Claude Code's status line appears at the bottom and can continuously show context usage, cost, git status, and more.

Start setup like this:

/statusline show model name, context percentage,
cost, and git branch

Four items beginners should display:

model

Check if you're stuck on an expensive model

context percentage

Check if the session grew too large

cost

Develop cost intuition

git branch

Prevent working on the wrong branch

16Team cost management

Individual users often need only /usage and model selection, but teams need spend limits and usage reports.

Good team documentation includes:

Default to sonnet for general development.

Use opus only for design, security, and incident analysis.

Use plan mode to narrow scope first on long tasks.

Enable MCP servers only for teams that need them.

Check monthly usage by Console or /usage.

17Understand background token usage

Claude Code may use tokens on background features even when you're not typing. Generally under $0.04 per session, but these habits help:

Clean up sessions when work finishes.
Don't hold onto old sessions unnecessarily.
Use /clear when moving to new work.

18Cost-saving practical routine

Before starting big work in Claude Code, request:

Let's do this work cost-efficiently.
Rules:
1. Don't blindly read the whole project.
2. First find related file candidates.
3. Propose a plan before editing.
4. For long logs, focus on error summaries.
5. Use sonnet as the baseline for general work.
6. Explain why Opus is needed if you suggest it.

Check usage mid-work:

/usage

19Cost-saving mid-point check and cleanup

During work, check like this:

Find cost factors in the current session.
Tell me what's costly: long context,
reading too many files, model choice,
or tool use?

If work gets long, compress:

/compact keep only goals, decisions,
modified files, and test results.

If tasks change, restart:

/clear

20Cost-reduction prompt examples

Reduce file exploration cost

Don't read the whole project.
First find files related to login.
Give me just 5 candidates with reasons.

Reduce diff review cost

Don't explain the entire git diff.
Summarize only behavior changes
and risky edits.
Separate formatting changes.

21More cost-reduction prompt examples

Reduce log analysis cost

Focus on the first failure cause only.
Skip duplicate stack traces and extract
just the error message and relevant paths.

Reduce model cost

I want to save cost.
If haiku or sonnet works, recommend it.
Only explain why opus is necessary
if it truly is.

22Clean up long sessions

Summarize what I'll need going forward
from our conversation.
Keep only goals, files modified,
remaining tasks, and warnings.
Then write a summary to put in /compact.

Section 14 · Wrap-up

Core takeaways for reducing costs

Claude Code costs depend mainly on token usage. Check session usage with /usage, but remember it's a local estimate—verify actual billing in Claude Console.

Costs spike from reading large files, long sessions, long logs, high-performance models, and overusing MCP or subagents. Use Sonnet for general development, Haiku for quick exploration, and Opus for complex design and tough bugs.

Use /compact for long work, /clear for switching tasks, and concrete prompts and plan mode to avoid wasteful exploration.

Next section

Section 15. How to manage context and use sessions longer

15. How to manage context and sustain long sessions

01What is context?

Context is the working memory space that Claude can refer to when generating your current answer. It contains your requests, Claude's responses, file contents that have been read, tool execution results, error logs, and previous decisions.

Here's how beginners can think about it.

Context = the workspace Claude is currently holding in memory

When the workspace has well-organized information, Claude gives good answers. Conversely, when old logs, completed tasks, and unrelated file contents keep accumulating, Claude starts to get confused.

02Problems that arise when context builds up

When you maintain a Claude Code session for a long time, the following issues can emerge.

Appears to forget decisions made earlier

Important information may be buried

Mentions completed tasks again

Older context remains

Responses become slower

Context to read through may have grown

Costs increase

More tokens to process with each request

Rereads the wrong files

Work focus may have blurred

The core point is this.

The ability to sustain long sessions is not about remembering longer, but about keeping only what's necessary.

03Check your current context status

To see context usage, use the following command.

/context

Then ask Claude like this.

Explain which elements take up the most space in the current context.
Let me know separately which of these is largest: files read, long logs, MCP, CLAUDE.md, or conversation history.

If context has grown too large, don't fix it immediately—first diagnose.

Determine whether I should continue this session.
Recommend whether to continue, run /compact, or start fresh with /clear.

04Compress only necessary content with /compact

/compact is a command to summarize long conversations so you can continue the session. Use it when you want to keep the work going but reduce unnecessary detailed exchanges and old output, keeping only the essentials.

/compact

For beginners, the recommended approach is not just to use /compact alone, but to clearly state what to keep.

/compact Preserve only the goals so far, decisions, modified files, test results, and remaining work.

If you're fixing a bug, write it this way; if you're refactoring, you might write it differently. /compact is best when continuing the same work.

05Criteria for deciding when to use compact

Continuing to fix the same bug

Use it

Continuing to implement the same feature

Use it

Refactoring has been long but the goal remains the same

Use it

Moving to a completely different task

/clear is more appropriate

06Start fresh work with /clear

/clear clears the current conversation context and starts anew. Use /clear when switching to unrelated work. Old context can waste tokens in all subsequent messages.

/clear

Beginners should use /clear in the following situations.

07Situations to use clear

After fixing a login bug, moving to payment functionality

Work topic differs

After frontend work, moving to backend deployment issues

Files and context needed are different

Previous conversation is too long and confusing

Fresh context is safer

Claude keeps mentioning previous work

Old information is getting in the way

Before switching tasks, it's good practice to name your session.

/rename auth-bugfix

Then move on to your new work.

08Rules for using clear

Same work: /compact; different work: /clear; work to come back to: /rename then /clear

09Resuming sessions 1 · The most recent session

You may not finish work in a day. Claude Code can resume previous conversations.

To resume the most recent session, use the following command.

claude -c

This command resumes the most recent conversation in the current directory.

10Resuming sessions 2 · Picking from the list

If you want to pick from the session list and resume, use the following.

claude --resume

If you want to pick a session from within Claude Code, use this.

/resume

The recommended session management approach for beginners is to name your session first, then use claude --resume or claude -c (for the most recent) when resuming later.

11Habits for logging work to sustain long sessions

To sustain long sessions, don't just ask Claude to "remember," but structure your work status periodically.

A good request looks like this.

Summarize the work status so far.
1. Goal
2. Files checked
3. Files modified
4. Problems not yet solved
5. Next tasks
6. Risk factors to watch

Then compact based on this summary.

12Long logs and test output ruin context

Test failure logs, build logs, and server logs can become very lengthy. If you paste entire long logs or keep having Claude read them, context grows rapidly.

A bad request looks like this.

Read all of this log and find the problem.

A better request looks like this.

Only look at the first failure cause in this log.
Ignore duplicate stack traces and summarize only the actual error message and relevant file paths.

Or filter it at the terminal first.

13Log handling approach

Then ask Claude like this.

Don't read the entire long log.
Analyze based only on lines related to the failure cause.
If you need more logs, tell me what part you need first.

The key to saving context is not "giving more," but "giving only what's needed."

14Read files incrementally too

Beginners often ask Claude like this.

Analyze the entire project for me.

This request can bloat context. A safer approach is incremental exploration.

Don't read the entire project.
First find only the candidate files related to the login feature.
Tell me the top 5 files and why.

Then read only the necessary files.

15Next step after file exploration

Read only src/auth/login.ts and src/auth/session.ts first.
If you can't find the cause, suggest which files to read next.

When exploring large codebases, using a subagent is also a good approach. Large codebase exploration can fill your main context with file reading, so delegating the investigation to a subagent lets the subagent read files in a separate context and return just a summary.

Use a subagent to investigate the token refresh flow in the authentication system.
Return to the main conversation only key files, a flow summary, and risk factors.

161M context is not a magic bullet

Some models and plans support a 1M context window. Opus 4.6+ and Sonnet 4.6 support a one-million-token context window for long sessions and large codebases.

/model opus[1m]

/model sonnet[1m]

But having 1M context doesn't mean you should read every file indiscriminately. A larger context is not always better, and as token count increases, accuracy and recall performance can degrade.

1M context is a safety net for large work, not a license to read files indiscriminately.

17Determining when 1M context is needed

Small bug fix

Low

Modify 1-3 files

Low

Analyze entire project structure

Medium

Large refactoring

High

Sustain sessions across multiple days

High

18Keep watching context with the status line

If you want to check context usage frequently, you can set a status line. Claude Code's status line is a custom bar displayed at the bottom of the screen and can show context window usage, cost, git status, and more.

To set it up simply, make a request like this.

/statusline show model name, context percentage, cost, and git branch

Here are the recommended status line items for beginners.

19Recommended status line items

Model name

Check if you're continuously using an expensive model

Context percentage

Check if the session has grown too large

Cost

Maintain awareness of usage

Git branch

Prevent working on the wrong branch

20When to start a new session

Sustaining a session indefinitely isn't always best. In these situations, a fresh session is safer.

Work topic changes completely

/clear

Claude keeps dragging up previous work

/clear

Long logs and file reading have accumulated

/compact then continue, or new session

Plans shift significantly

New session or plan mode

Resuming the same work the next day

/resume

Need to work on multiple features simultaneously

Separate sessions or worktree

For beginners, remember just one thing.

Keep one goal per session.

21Real-world context management routine 1

When starting work:

This session's goal is to analyze the login failure cause.
Don't read the entire project—just find candidate files first.

Narrowing down relevant files:

Suggest only the top 5 relevant files.
Explain in one line why each file should be reviewed.
Don't modify files yet.

22Real-world context management routine 2

Midway check-in:

Summarize what you've confirmed so far, files modified, and remaining questions.
Tell me if there's content unnecessarily taking up context.

When the session has grown long:

/compact Preserve goal, decisions, modified files, test results, and remaining work only.

23Real-world context management routine 3

When moving to different work:

/rename auth-login-debug

/clear

When resuming the next day:

claude --resume

24Beginner-friendly prompt collection 1

Context diagnosis

Determine if this session's context has grown too large.
Recommend whether to continue, /compact, or /clear, with reasons.

Organize before compact

Organize what needs to be preserved before /compact.
Keep only goal, decisions, modified files, test results, remaining work, and cautions.

25Beginner-friendly prompt collection 2

Run compact

/compact Preserve only the essential content just discussed.
Especially keep the files modified, failed tests, and next steps.

Organize before starting a new session

Before ending this session, create a work summary so I can resume later.
Write it so I can paste it directly as the first prompt in the next session.

26Beginner-friendly prompt collection 3

After resuming a session

Re-orient to the current state based on the previous session summary.
First check git status, then propose remaining tasks in order.

Section 15 · Wrap-up

Unit 15 key takeaways

Context is the working memory Claude currently references. As sessions lengthen, conversations, file contents, logs, and tool results accumulate. When context grows, costs increase and answer quality can suffer. When continuing the same work, use /compact to keep only essentials; when moving to different work, use /clear to start fresh. For work you'll return to later, use /rename to name it, then clean up. Resume previous work with claude -c, claude --resume, or /resume. For large codebase exploration, read necessary files incrementally or delegate to subagents. The 1M context helps with large work, but it doesn't mean you should include unnecessary information. Setting a status line lets you continuously check context percentage, cost, model, and git branch.

Next unit

Unit 16. When to use extended reasoning and effort

16. Ultra Think — 300% Better Analysis

01What is Ultra Think?

Ultra Think is a practical prompt pattern that tells Claude Code to analyze this request in greater depth.

Basic usage is simple.

ultrathink.

Analyze this problem deeply.
Don't fix it yet, just organize the possible causes and check order first.

Simply put, Ultra Think is:

Ultra Think = A mode that looks deeply at one important decision

02Three Key Points About Ultra Think

You must understand Ultra Think's three characteristics precisely.

Actual keyword

ultrathink

Scope of application

One prompt request only

What doesn't change

Session-wide effort setting

In other words, ultrathink is not a command that changes session settings like /effort xhigh. It's a request to examine one specific question more deeply.

03When to Use Ultra Think

Use Ultra Think not for simple tasks, but for tasks where mistakes are costly.

Bugs with unclear causes

The symptom and actual cause might be in different files

Refactoring with tangled files

Need to check hidden dependencies and side effects first

Auth and permission logic

Must be careful about permission bypass possibilities

Payment logic

Failure could cause financial and settlement issues

Security-related changes

Must review sensitive data exposure and access control

Outage cause analysis

Must examine logs, config, and recent changes together

For beginners, remember it this way:

Use Ultra Think not just for "code fixes" but for "tasks where the decision matters."

04When NOT to Use Ultra Think

It might seem good to add Ultra Think to everything, but it's not. Official documentation explains that effort and reasoning have trade-offs between token usage, speed, and capability.

Tasks that don't need Ultra Think:

README summary

"Summarize the essentials in 5 lines"

Finding file locations

"Find just 5 candidate files"

Simple diff explanation

"Summarize just the behavior changes"

Short code explanation

"Explain just what this function does"

Obvious typo fixes

"Fix just this typo"

Ultra Think is not a magic spell you add every time. It's a high-performance tool for critical moments.

05Ultra Think Basic Formula

To use Ultra Think well, don't just throw ultrathink at it. Provide situation, goals, constraints, and output format together.

The basic formula is:

ultrathink.

Situation:
- 

Goal:
- 

Constraints:
- Don't modify files yet.
- Don't run commands until I approve.
- Organize possible causes by priority.

Do first:
1. Summarize how you understand the problem.
2. Break down possible causes.
3. List files to check, by priority.
4. Warn about risky fix directions.
5. Suggest safe next steps.

The core of this formula is the last part. Ultra Think is a tool for thinking deeply, not for executing immediately. Use it in an Analyze → Plan → Approve → Execute flow.

06Ultra Think for Bug Analysis

Ultra Think is especially useful for bugs where the cause is hard to spot.

ultrathink.

Analyze the cause of this bug deeply.

Symptoms:
- Login says it succeeded but session doesn't persist
- Refresh redirects back to login page

Recent changes:
- Modified auth middleware
- Changed cookie options
- Changed HTTPS settings in deployment

Constraints:
- Don't modify files yet.
- First organize possible causes by priority.
- Also show how to check each cause.
- Suggest just the top 3 files to read first.

07Core Principle for Bug Analysis

The core principle when using Ultra Think for bugs is preventing immediate fixes.

Bad request:

ultrathink. Fix this bug.

Good request:

ultrathink.

Analyze the cause of this bug first.
Don't fix it, just suggest possible causes and check order.

It's even better to specify a good output format:

Output format:
1. Most likely cause
2. Evidence to check
3. Files to read
4. Commands to try
5. Cautions before fixing

08Ultra Think for Refactoring

Refactoring might look like "just changing code structure," but it can actually touch hidden dependencies. Especially when refactoring auth, state management, DB access, or API layers, it's safer to use Ultra Think to plan first.

ultrathink.

Analyze whether refactoring the auth module is safe.

Goals:
- Separate auth logic into service layer
- Remove token handling from controller
- Keep existing API response format

Check:
1. Files affected
2. Hidden dependencies
3. Parts that need testing
4. Changes that are hard to roll back
5. Step-by-step execution order

Constraints:
- Don't modify files yet.
- Just present the plan first.
- Mark high-risk changes separately.

09Additional Request for Refactoring Plan

For Ultra Think used in refactoring, prevent "changing everything at once."

It's good to add this request:

Don't refactor all at once.
Break it into small commit-sized chunks.
Plan so we can check each step with git diff.

10Ultra Think for Security, Permission, and Payment Logic

Security, permission, and payment logic are riskier than simple feature implementation. Even if something seems to work, permission bypasses, sensitive data exposure, duplicate charges, or wrong refunds can happen.

For these tasks, use Ultra Think strongly:

ultrathink.

This change touches permission/security logic.
Accuracy matters more than speed.

Review the following first:
1. Permission bypass possibility
2. Sensitive data exposure possibility
3. Risks existing tests don't catch
4. Outage scope if fixed wrong
5. Safe fix order
6. Tests that must be added

Constraints:
- Don't modify files until I approve.
- Don't run risky commands.
- Mark low-confidence areas as guesses.

11Prompt for Payment Logic Review

For payment logic, use it like this:

ultrathink.

Review the payment completion webhook handling logic.

Focus on:
1. Whether duplicate charges happen on duplicate webhooks
2. Whether payment success/failure state transitions are safe
3. Whether signature verification might be skipped
4. Whether DB transactions are needed anywhere
5. Edge cases to test

Don't fix yet, just analyze and suggest a fix plan.

The principle here is clear:

For security, permission, and payment work: "Don't break it" comes before "Make it work."

12Ultra Think for Outage Analysis

Outage analysis is different from simple bug fixes. You might need to look at logs, deployment history, environment variables, config, recent commits, and external service status all together.

ultrathink.

API response time spiked sharply after the recent deploy.
Analyze the outage cause deeply.

Current symptoms:
- Only a specific API is slow
- Can't reproduce locally
- Started right after deploy
- No errors, just timeout increase

Do first:
1. Break down possible causes by layer.
2. Organize logs and files to check first.
3. Warn about risky quick fixes.
4. Separate temporary fix from root cause fix.

13Core Point for Outage Analysis

For outage analysis, it's risky to pinpoint one single cause.

A good request looks like this:

Don't pinpoint a single cause.
Organize likely candidates by priority.
For each candidate, show both how to confirm and how to disprove it.

14Using Ultra Think with Plan Mode

Ultra Think enables deep judgment, and Plan Mode provides a safety check before editing. The official common workflows doc also recommends setting a plan before editing, to review changes before they touch disk, and delegating large codebase exploration to subagents to keep your main context clean.

The safest combination is:

ultrathink.

Start with Plan Mode.
Investigate related files, organize the fix plan and risks.
Don't modify files until I approve.

The core of this combination:

Ultra Think = Think deeply / Plan Mode = Stop before executing

15Ultra Think + Plan Mode for Large Tasks

For large tasks, make it more concrete:

ultrathink.

Use Plan Mode to organize an auth module refactoring plan.

Include in the plan:
1. Current structure summary
2. Files to change
3. Fix order
4. Risk level of each step
5. Required tests
6. How to rollback
7. Criteria for splitting commits

Don't modify files yet.

Using both together means: instead of "think deeply then fix immediately," you think deeply, show the plan, and get approval before executing.

16Ultra Think and Git Diff Review

You can use Ultra Think even after Claude Code modifies files. It's especially useful for deeply reviewing the current diff for safety before committing.

ultrathink.

Review the current git diff deeply.

Distinguish:
1. Intentional changes
2. Unintentional changes
3. Logic changes that alter behavior
4. Pure formatting changes
5. Changes that need testing
6. Risk factors before deploy
7. Files that shouldn't be in the commit

Don't git add, commit, or push yet.

17Additional Pattern for Diff Review Before Commit

After staging, request like this:

ultrathink.

Review what's going into this commit based on git diff --staged.
Suggest a commit message, but don't commit yet.

Good cases to use Ultra Think for Git review:

Many changed files

Unintended edits might be mixed in

Logic changes and formatting mixed

Need to isolate actual risky changes

Security/permission files included

Deeper review needed

Fixed without tests

Need to find missing tests

187 Elements That Strengthen Ultra Think Prompts

Ultra Think quality varies greatly with prompt structure.

1. Give situation

Happens after deploy, not local

2. Give goal

Narrow cause candidates, safe fix order

3. Give constraints

No file edits, no risky command runs

4. Demand priority

Organize by likelihood

5. Demand check method

Show how to confirm and disprove each

6. Demand risk factors

List must-watch risks separately

7. Block execution

No file edits or commands until approval

The real Ultra Think power is not "think more deeply," but specifying what criteria to think deeply about.

19Problems from Overusing Ultra Think

Overusing Ultra Think creates these problems:

Slower responses

Analyzes simple tasks too deeply

Cost increase

Thinking tokens might be included in costs

Over-analysis

Can see simple problems as complex

Rhythm slowdown

Gets stuck on quick tasks

Judgment blur

Distinction between important and simple work fades

For simple tasks, it's better to say:

Don't analyze deeply, just answer the essentials briefly.

20Difference Between Ultra Think and Effort

Now let's connect effort to understand both:

Nature

Prompt keyword / Claude Code setting

Scope

One request / Session or config scope

Actual input

ultrathink / /effort high, /effort xhigh, etc.

Purpose

One deep analysis / Adjust overall reasoning strength

Good use

Important single decision / Basic setting matched to task difficulty

Simply put:

Ultra Think = Analyze just this question deeply / Effort = Change this session's thinking intensity

21Effort Command and Setting

To change effort within a session:

/effort

You can also specify directly:

/effort low

/effort medium

/effort high

/effort xhigh

/effort max

To set it at startup, run in the terminal:

claude --effort high

claude --model opus --effort xhigh

22Effort Level Usage by Stage

Official docs explain effort as a balance between token usage and capability. For beginners, the standard is:

low

Find file locations, short summaries | Avoid code edits, design decisions

medium

Simple explanations, small change reviews | Avoid security, payment, permission

high

Regular bug fixes, test writing | Avoid very complex outage analysis

xhigh

Refactoring, hard bugs, agentic coding | Avoid simple summaries

max

Critical outages, complex design review | Avoid repeat use, simple tasks

23How to Combine Ultra Think and Effort

Ultra Think and effort aren't separate tools—they can combine:

General analysis

/effort high

Analyze this bug and suggest a fix plan.

One important decision

/effort high

ultrathink.

Review whether this fix direction is safe.
Focus on hidden side effects and missing tests.

24Large Refactoring and High-Risk Review

Large refactoring

/effort xhigh

ultrathink.

Use Plan Mode to organize a refactoring plan.
Include impact scope, risks, test strategy, and commit split criteria.
Don't modify yet.

High-risk security/payment review

/effort xhigh

ultrathink.

Review whether this payment webhook change is safe.
Check deduplication, signature verification, state transitions, transactions, and rollback.
Don't modify files yet.

The practical sense is:

Regular tasks = high / Complex tasks = xhigh / Important single decision = add ultrathink

25Use Max Carefully

max can provide the deepest reasoning possible, but it's not always the best choice. Official docs also note that max can improve performance on demanding tasks but has unbounded token spending, and diminishing returns and overthinking can occur, so test before applying widely.

For beginners, it's better to ask first before using max:

Does this problem need max effort first, judge for me.
If needed, explain why, expected cost increase, and why xhigh isn't enough.
Don't switch to max yet.

Situations worth considering max:

Can't identify outage cause at all

Consider possible

Security incident analysis

Consider possible

Large migration design

Consider possible

Payment data consistency issue

Consider possible

26Don't Confuse with Ultracode

You might also see ultracode in the /effort menu. But ultracode is not a model effort level.

According to official docs, ultracode is a Claude Code setting that sends xhigh to the model and orchestrates dynamic workflow for substantive tasks. It's also a session-only setting and not part of effortLevel, --effort, or CLAUDE_CODE_EFFORT_LEVEL.

The distinction is:

ultrathink

Analyze one prompt more deeply

/effort xhigh

Increase session reasoning strength

/effort max

Deepest effort, use carefully

ultracode

Claude Code orchestrates workflow more strongly

Beginners don't need to use ultracode by default from the start. It's enough to master ultrathink and /effort high, /effort xhigh first.

27Practical Prompt Collection ①

Bug cause analysis

ultrathink.

Analyze this bug cause deeply.

Symptom: (enter symptom)
Recent changes: (enter changes)

Constraints:
- No file edits yet
- Organize cause candidates by priority
- Include how to confirm and disprove each
- Suggest just top 3 files to read

Refactoring plan

ultrathink.

Organize this refactoring plan.

Goal: (enter refactoring goal)

Include:
1. Impact scope
2. Hidden dependencies
3. Step-by-step fix order
4. Test strategy
5. How to rollback
6. Commit split criteria

Don't modify files yet.

28Practical Prompt Collection ②

Security review

ultrathink.

Review whether this change is secure.

Focus:
1. Permission bypass possibility
2. Sensitive data exposure possibility
3. Auth/authz boundary
4. Values that shouldn't log
5. Missing tests
6. Safe fix order

Don't fix, just review.

Payment logic review

ultrathink.

Review payment handling logic deeply.

Check:
1. Duplicate payment possibility
2. Webhook retry handling
3. Signature verification
4. DB transaction
5. Failure state handling
6. Refund/cancel edge case

Just suggest plan before file edits.

29Practical Prompt Collection ③

Git diff review

ultrathink.

Review current git diff deeply.

Distinguish:
1. Intentional changes
2. Unintentional changes
3. Actual behavior changes
4. Pure formatting
5. Needs test items
6. Exclude from commit
7. Risk before deploy

Don't git add, commit, or push yet.

Determine if max effort needed

Does this problem need max effort?
Compare: is xhigh enough, is max needed, is there cost-benefit?
Don't change effort yet.

30Beginner Decision Table

Find file locations

No Ultra Think needed, low/medium

README summary

No Ultra Think needed, low

Regular bug fix

high

Bug with unclear cause

xhigh + ultrathink

Large refactoring

xhigh + ultrathink + Plan Mode

Security/permission review

xhigh or max review + ultrathink

Payment logic review

xhigh + ultrathink

Outage cause analysis

xhigh + ultrathink, max review if needed

Diff review before commit

ultrathink if large changes

Repetitive tasks

Avoid Ultra Think overuse, medium/high

Section 16 · Wrap-up

What to Remember from Section 16

The actual prompt keyword for Ultra Think is ultrathink. ultrathink is a keyword that makes Claude Code analyze one specific request more deeply, and it doesn't change the session-wide effort setting.

Use Ultra Think for tasks where judgment matters—unclear bugs, large refactoring, security, permission, payment, outage analysis. Don't use it for simple summaries, file location searches, or short diff explanations.

When using Ultra Think, include situation, goal, constraint, output format, and execution block together. Using it with Plan Mode lets you analyze deeply, review the plan first, before actually fixing it.

/effort controls your session's reasoning strength. low, medium, high, xhigh, max each balance cost, speed, and reasoning depth differently, and max isn't always the best choice—it can cause over-analysis and cost spikes.

Next section

Section 17. Creating a Bug Fix Workflow

17. Creating a Bug Fix Workflow

01Basic Flow of Bug Fixing

When fixing bugs with Claude Code, we use a 10-step process as the foundation.

1Describe the symptom explain precisely

2How to reproduce share the steps

3Error logs provide stack trace

4File exploration find related files

5Organize root causes by priority

Then the next steps:

Get a fix plan first.
Fix with minimal scope.
Add or run tests.
Review changes with git diff.
Check final risk factors before commit.

02Most Common Beginner Mistakes

The most common mistake beginners make is skipping these steps and requesting like this.

Fix this bug.

With this kind of request, Claude might guess too broad a scope.

A much better request looks like this.

There's a bug where the page redirects to the login page again after logging in and refreshing.
First, analyze the root cause.
Don't fix it yet,
organize the reproduction steps, related files, possible causes, and verification order.

Bug fixing is about identifying the root cause accurately first, not speed.

03How to Describe Symptoms Well

For Claude to fix a bug well, it needs to understand exactly "what went wrong."

Bad description:

Login seems broken.

Good description:

When I enter the correct email and password in the login form,
the server responds with 200,
but on the frontend the login state doesn't persist.
After refresh, it redirects to /login again.

A good bug description should include these items.

Expected behavior

Should stay on dashboard after login

Actual behavior

After refresh, redirects to login page

Location

/login, AuthProvider, session middleware

Conditions

Only happens in production environment

Recent changes

cookie options, middleware modifications

Error message

401 Unauthorized, Session expired

04Template for Requesting Bug Information

When sending organized bug information to Claude, use this template.

After reviewing the bug description below,
first ask if there's any missing information.
Don't fix it right away, organize the information needed for root cause analysis in a list.

Symptoms:
- (description)

Expected behavior:
- (description)

Actual behavior:
- (description)

Recent changes:
- (description)

Error messages:
- (description)

05Fix Reproduction Steps First

The most important thing in bug fixing is reproduction. If you can't reproduce it, it's hard to verify the fix is correct.

A good request looks like this.

First, organize the procedure to reproduce this bug.
If there's missing information in the symptoms I provided, ask.
Reduce it to the minimum reproducible steps.

Example reproduction steps:

1. Start local server: npm run dev
2. Go to /login in browser
3. Log in with test account
4. Confirm navigation to /dashboard
5. Refresh
6. Confirm it redirects to /login again

06Reproduction Commands and Intermittent Bugs

When there's a test command:

Reproduction command:
npm test -- auth

Failure log:
...

When it's an intermittent bug:

This bug doesn't always happen, it's intermittent.
Assume it's intermittent,
and suggest possible causes and where to add logs.
Don't modify files yet.

07Handling Error Logs and Stack Traces

Error logs are important, but very long ones waste context. Provide the key parts.

Bad request:

Look at all this log and fix it.

Good request:

Analyze the first failure cause from this log.
Ignore duplicate stack traces,
focus on the actual error message, related files, and the failing test.

When providing logs to Claude, it helps to include these.

First error

Later errors might be cascading failures

Top of stack trace

Likely the actual failure location

Failing test name

Shows what behavior broke

Recently changed files

Can narrow down the cause candidates

Run command

Increases reproducibility

08Log Analysis Request Template

When analyzing test failure logs, this template is efficient.

Analyze this test failure.

Run command:
npm test -- auth

First failure:
...

Stack trace:
...

Request:
1. Explain the most likely root cause.
2. Suggest only 3 related file candidates.
3. Organize what needs to be verified before fixing.
4. Don't modify files yet.

09Finding Related Files — Limit Scope

Beginners tend to read the entire project when a bug appears.

Bad request:

Look at the entire project and find the bug.

This approach greatly increases context and cost. A better request narrows the scope.

Don't read the entire project,
just find file candidates likely related to this bug.

Conditions:
- Files related to maintaining login state
- Files related to session, cookie, auth middleware
- If there are test files, suggest them too

Output:
1. File paths
2. Why they seem related
3. Priority order for reading

10Read Files Step by Step

After Claude suggests candidate files, don't read all of them at once, proceed step by step.

First, read only the top 1-3 priority files from your suggestions.
If you can't find the cause there, suggest the next files.

This approach has these advantages.

Fewer files read at once, so it's faster.
High probability of finding the answer in high-priority files.
Doesn't waste Claude's context.

11Organize Root Cause Candidates by Priority

A dangerous attitude in bug fixing is deciding too quickly "this must be the cause."

Always ask Claude to divide possible causes into multiple candidates with evidence and verification methods.

Organize possible causes by priority.

For each cause, include:
1. Why the possibility is high
2. Files to check
3. Code location to check
4. How to disprove it
5. Expected change scope if fixed

Don't fix it yet.

12Deep Analysis for Difficult Bugs

For difficult bugs, use Ultra Think from Unit 16 together.

ultrathink.

Analyze this bug's root cause deeply.
Don't pinpoint one cause,
organize high-probability candidates by priority.
For each candidate, present verification and disproof methods.

Example of root cause candidate table:

Priority 1

cookie secure setting issue — only happens in production

Priority 2

session storage mismatch — state disappears after refresh

Priority 3

frontend auth state initialization — server 200 but UI logs out

13Get a Fix Plan First

Once you've confirmed root cause candidates, don't fix immediately. Get a fix plan first.

Example request:

Suggest a fix plan first.

Include:
1. Files to modify
2. Function or code location to change
3. Why the change is needed
4. Expected side effects
5. Tests to add or modify
6. How to revert

Don't modify files yet.

Bug fixing is "set a verifiable plan then fix," not "fix as you think of it."

14Start Safely with Plan Mode

Plan Mode lets Claude read files and propose a plan, but won't edit until approved.

Method 1. In Claude conversation:

Use Plan Mode.
Verify the bug root cause and write a fix plan.
Don't modify files until I approve.

Method 2. From terminal:

claude --permission-mode plan

This gives you time to review before file modifications.

15Minimal Change Principle

Bug fixes should be as small as possible. If you mix refactoring, formatting, or naming changes while fixing a bug, review becomes hard.

Instruct Claude like this.

This fix should be minimal changes to solve the root cause.
Don't refactor, change formatting, or rename.
Only modify where behavior change is needed.

Good bug fix principles:

Minimal changes

Only modify what's needed to solve the cause

Behavior preservation

Don't change unrelated behavior

Tests first

If possible, add failing test first

Small diff

Keep it within reviewable scope

One commit, one purpose

Don't mix bug fixes and refactoring

16Execute Fix Step by Step

When delegating to Claude, break it into steps.

From the plan just suggested, apply only step 1.
Fix with minimal changes,
and summarize which files you modified after fixing.

Advantages of this approach:

Can roll back immediately if problems occur.
Can verify the effect of each step.
The entire fix process is transparent.

17Add Tests

The best test for a bug fix is one that fails before the fix and passes after the fix.

Request to add test:

First, add a test that reproduces this bug.
Review the existing test style,
and write a test that should fail before the fix.
Don't modify implementation code yet.

If already fixed:

Add a regression test so this bug doesn't happen again.
Follow the existing test pattern,
and separate success and failure cases.

18Bug Types That Need Testing

Test focus points differ by bug type.

Maintain auth after refresh

Input validation issue

Empty values, wrong format, boundary values

Permission issue

Allowed and denied users

Payment issue

Duplicate webhook, failed state, retries

API error handling

400, 401, 500 responses

If it's hard to add tests immediately, at least request this.

What tests should be added for this bug?
Also let me know if unit, integration, or E2E tests are appropriate.

19Run Tests and Analyze Failure Logs

After fixing, run tests.

Run all tests:

npm test

Run related tests only:

npm test -- auth

Request Claude like this.

Run related tests first.
If it fails, analyze only the first failure cause,
and suggest a revised fix plan.

Good requests when tests fail:

Analyze only the first failure from the test failure log.
Ignore cascading failures,
and suggest the root cause and fix scope first.

20Handling Long Failure Logs

With long failure logs, don't read all of it, just provide the key parts.

Don't read the entire log,
analyze based only on the first FAIL block and related stack trace.
If more logs are needed, tell me what part you need.

This approach:

Saves Claude's context.
The first failure likely causes others.
Answers are faster.

21Review git diff

Even if tests pass, it's not done. You must check changes with Git.

From terminal:

git status
git diff

Request Claude for review:

Review the current git diff.

Check:
1. Is the change directly related to the bug fix?
2. Are there unnecessary formatting changes?
3. Were unintended files modified?
4. Were tests added?
5. Are there risky behavior changes?
6. What to check before commit?

22Deep Review of Important Bugs

For important bugs, attach Ultra Think for deeper review.

ultrathink.

Deeply review the current git diff.
Does this change actually solve the root cause,
or just mask symptoms?
Are tests sufficient?
Don't commit yet.

23Distinguish Root Cause Solution vs Symptom Relief

The most dangerous thing in bug fixing is fixes that only hide symptoms.

For example, if you swallow all errors with try/catch, the screen quiets but actual data problems remain.

Request Claude like this.

Does this fix solve the root cause,
or is it just a workaround that hides symptoms?

Evidence:
1. What code path changed
2. How the failure condition is resolved
3. Conditions where this problem could recur
4. Additional tests needed

Good bug fix report:

Root cause

(description)

Fix

(description)

Verification

(description)

Remaining risks

(description)

Additional tests

(description)

24How to Handle Intermittent Bugs

Intermittent bugs are harder because they don't always reproduce.

Examples of intermittent bugs:

race condition, token expiry

Fails at certain times

timezone, cron, cache

Fails only in production

env, cookie secure, proxy

Fails for some users only

data state, permission differences

Tests fail sometimes

async handling, mock gaps

25Intermittent Bug Analysis Request

Example intermittent bug analysis request:

This bug happens intermittently.

ultrathink.

Analyze based on:
1. race condition possibility
2. cache or session issues
3. environment variable differences
4. timezone/timing problems
5. external API delays
6. test flakiness possibility

Don't fix right away,
first suggest what logs or tests to add for observability.

With intermittent bugs, increasing observability often comes before fixing.

26Use debugger subagent

When finding bug roots in large codebases, your main context can be filled with file reading. Delegating to a subagent lets it read files in separate context and return only a summary, keeping your main context clean.

Investigation request:

Use debugger subagent to investigate this bug.

Goals:
- Analyze error message and stack trace
- Verify reproduction steps
- Isolate failure location
- Organize possible cause candidates
- Suggest minimal fix plan

Return only key summary to main conversation.
Don't modify files yet.

When delegating the full fix:

After analyzing with debugger subagent,
if fix is needed, suggest only minimal changes.
Don't execute Edit until I approve.

27Add Bug Fix Rules to CLAUDE.md

Often-repeated bug fix rules work well written briefly in CLAUDE.md.

CLAUDE.md example:

# Bug Fix Workflow

- Always verify reproduction steps before fixing a bug.
- Don't pinpoint one cause; provide possible candidates and evidence.
- Show a fix plan before modifying files.
- Keep fixes minimal.
- Run related tests first, add regression tests if possible.
- Summarize git status and git diff before commit.
- Analyze security, permission, payment bugs with ultrathink first.

Keep it short and include only rules that always apply.

28Create Completion Criteria

Bug fixing shouldn't end at "the error is gone." You must create completion criteria.

Example completion criteria:

Reproduction procedure is documented
Root cause is explained with evidence
Minimal fix is applied
Related tests pass
Regression test is added or reason for skipping is explained
git diff review is complete
Remaining risks are organized

Request Claude for completion review:

Can we consider this bug fix complete?

Criteria:
1. Was it reproducible?
2. Was root cause confirmed?
3. Is it a minimal fix?
4. Are tests sufficient?
5. Is there unnecessary change in diff?
6. Are there remaining risks?

29Final Prompt Before Commit

Once the bug fix is complete, request this final check before committing.

Final review before commit.

Execute:
1. Check git status
2. Check git diff
3. Summarize list of modified files
4. Summarize bug cause and fix content
5. Summarize test run results
6. Confirm regression test addition or reasons
7. Confirm risks and remaining TODOs
8. Suggest 3 commit messages

Don't commit yet.

30Commit Message Examples

Good commit message examples:

fix: preserve session after login refresh

fix(auth): handle secure cookie settings in production

test(auth): add regression coverage for session persistence

Only commit after approval.

If review shows no issues,
commit using the first suggested message.
Show the file list again right before commit.

31Complete Real-World Prompt Template

This template can be pasted as-is when a bug occurs.

Use the bug fix workflow.

Symptoms:
- 

Expected behavior:
- 

Actual behavior:
- 

Reproduction steps:
1. 
2. 
3. 

Run command:
- 

Error log:
- 

Recent changes:
- 

Process rules:
1. Don't fix immediately.
2. First organize cause candidates by priority.
3. Suggest no more than 5 related file candidates.
4. Provide verification and disproof methods.
5. Present fix plan first.
6. Apply only minimal changes after my approval.
7. Add regression tests if possible.
8. Run tests and review git diff after fixing.

32Difficulty-Based Bug Analysis Options

For difficult bugs, add to the first line:

ultrathink.

To proceed more safely, start with Plan Mode:

Use Plan Mode.

You can also combine these two options.

ultrathink.
Use Plan Mode.

33Bug Type-Specific Prompt Examples ①

Login bug

There's an issue where after logging in and refreshing, the user is logged out.

First, analyze the root cause.
Organize possible causes by priority based on
cookie, session, auth middleware, and frontend auth state.
Don't fix yet.

Test failure

Auth tests fail when running npm test.

Analyze only the first failure cause.
Ignore cascading failures,
find the failing assertion and related code location.
Suggest a fix plan first.

34Bug Type-Specific Prompt Examples ②

Bug that only happens in production

This bug can't be reproduced locally, only happens in production.

ultrathink.

Organize possible causes based on
environment variables, cookie secure settings, proxy, HTTPS, and DB connection differences.
Don't fix yet, suggest verification order first.

Permission bug

There's a permission bug where regular users can access admin pages.

ultrathink.

Analyze focusing on permission bypass possibilities.
Check if authentication and authorization are separated,
and if server-side validation is missing anywhere.
Don't fix yet.

35Bug Type-Specific Prompt Examples ③

Payment bug

There's an issue where duplicate payment webhooks cause order state problems.

ultrathink.

Analyze based on duplicate webhooks, idempotency, DB transaction, and state transition order.
Suggest test cases and safe fix order before fixing.

36Beginner Bug Fix Checklist

Check this checklist whenever fixing a bug.

[ ]

Did you describe the symptoms specifically?

[ ]

Did you distinguish expected from actual behavior?

[ ]

Are there reproduction steps?

[ ]

Did you provide run commands and first error log?

[ ]

Did you avoid blindly reading the entire project?

[ ]

Did you get cause candidates and evidence first?

[ ]

Did you approve a fix plan before fixing?

[ ]

Did you make only minimal changes?

[ ]

Did you run related tests?

[ ]

Did you add or explain skipping regression tests?

[ ]

Did you check git status and git diff?

[ ]

Did you review risks before commit?

Section 17 · Wrap-Up

Bug fixing follows this order: reproduction → root cause analysis → plan → minimal fix → testing → diff review.

You must describe symptoms, expected behavior, actual behavior, reproduction steps, error logs, and recent changes specifically. Don't ask Claude to fix immediately; first request cause candidates and verification methods.

Read related files step by step by priority, not the entire project. Get a plan before fixing and use Plan Mode for risky work.

Keep fixes minimal and don't mix refactoring or formatting changes. Add regression tests that fail before the fix and pass after whenever possible.

For difficult, intermittent, or security/permission/payment bugs, use ultrathink.

In large codebases, use debugger subagent to delegate cause investigation. Add repeated bug fix rules briefly to CLAUDE.md.

Next Section

Section 18. Creating a Feature Addition Workflow

18. Creating a Feature Addition Workflow

Part 4 · Section 18

Feature Addition Workflow

Implementing new features safely by following an established process.

Requirements clarification → Related file exploration → Plan approval → Staged implementation → Testing → Documentation → diff review

01Basic Feature Addition Flow

Feature additions follow this basic sequence.

1. Describe the feature you want to build in concrete terms.
2. Clarify the behavior users expect.
3. Find the scope of changes first.
4. Investigate related files and existing patterns.
5. Get an implementation plan.
6. Review and approve the plan.
7. Implement in small stages.
8. Add or modify tests.
9. Check if documentation or README updates are needed.
10. Review final changes with git diff.

Bad Request vs. Good Request

Bad example:

Add a notification feature.

Good example:

I want to add a feature that shows notifications in a notification list when users receive comments.
Don't implement right away. First clarify requirements and find related files.
Then propose an implementation plan.

Finalize what you're going to build before building.

02Organizing Requirements First

Vague requirements lead to shaky results. Before assigning implementation to Claude, organize requirements first.

Before implementing the feature request below, organize it into requirements.

Feature:
- Show a notification in the notification list when a user receives a comment.

Organize:
1. User perspective behavior
2. Required screen changes
3. Required API changes
4. Data persistence requirements
5. Permission or security considerations
6. Test cases to verify

Don't modify files yet.

Requirements Organization Categories

User action

User receives notification when getting a comment

Screen

Display unread count on header notification icon

API

Add notification list query API

Data

Require notifications table or collection

Permission

Only own notifications can be queried

Testing

Verify notification is created when comment is added

Explaining with User Scenarios

User scenario:
1. User A comments on User B's post.
2. User B sees the new comment notification in the notification list.
3. When B clicks the notification, they go to that post.
4. Read notifications are excluded from the unread count.

03Making Claude Ask About Unclear Requirements

If Claude makes arbitrary decisions during feature implementation, fixes can become larger later. Therefore, unclear requirements should prompt questions first.

Before implementing this feature, ask about unclear requirements.
Don't guess; organize decisions needed as a list.

Items Claude Should Ask About

Should notifications be persisted to the database?

Do we need real-time notifications, or is querying after refresh enough?

How should marking as read work?

Do we need a delete notification feature?

Do we need to update the mobile UI?

Is there an existing notification model?

Good feature addition prioritizes fast requirement confirmation over quick implementation.

04Finding Related Files

Once requirements are clarified, find related files. Don't read the entire project aimlessly; identify only likely candidate files for this feature.

Don't read the entire project aimlessly.
Find only candidate files likely related to this feature.

Features:
- Create notification when comment is added
- Query notification list
- Display unread count

Output:
1. File paths
2. Why they seem related
3. Priority for reading first
4. Whether modifications are likely

Investigating Top Files

Read priority 1-5 files first.
Find existing patterns in them,
and explain where naturally adding the new feature fits.

Don't modify files yet.

Early in feature addition, understanding existing structure is more important than modifying many files.

05Following Existing Patterns First

New features must match the project's existing style. If API routers, service layers, test structures, and naming conventions already exist, Claude should follow those patterns.

Before implementing the new feature, investigate existing patterns.

Check:
1. Whether similar functionality already exists
2. API route structure
3. Service or repository layer structure
4. Test file location and writing style
5. Error handling approach
6. Naming conventions

Don't implement yet; only summarize patterns.

Example CLAUDE.md Feature Development Rules

# Feature Development Rules

- New features follow existing folder structure and naming conventions.
- Maintain existing API response format and error handling approach.
- Investigate related files and existing similar features before implementation.
- Present implementation plan before modifying files.
- Check if related tests and documentation updates are needed when adding features.

06Creating an Implementation Plan

Once related files and existing patterns are confirmed, don't implement immediately. Get a plan first.

Create an implementation plan for this feature.

Include:
1. Files to modify
2. New files to create
3. Data model changes
4. API changes
5. UI changes
6. Testing plan
7. Documentation update requirements
8. Risk factors
9. Step-by-step implementation order

Don't modify files yet.

Using Plan Mode

Create a feature addition plan in Plan Mode.
Investigate related files and organize implementation stages and risk factors.
Don't modify files until I approve.

Or when starting from the terminal:

claude --permission-mode plan

07Breaking Features into Small Stages

Feature addition is risky when trying to complete everything at once. Modifying DB, API, UI, tests, and documentation simultaneously creates large diffs and difficult reviews.

Divide this feature into small implementation stages.

Requirements:
- Each stage must be reviewable with git diff
- Don't modify too many files in one stage
- Divide into testable units
- Include completion criteria for each stage

Notification Feature Example (7 Stages)

Stage 1: Add notification data model

Stage 2: Create notification when comment is added

Stage 3: Add notification list query API

Stage 4: Add unread count API or response

Stage 5: Display unread count in header UI

Stage 6: Add mark as read functionality

Stage 7: Update tests and documentation

Implement stage 1 first.
After completing, show modified files and git diff summary.

08Features with Data Model Changes

Be extra careful when feature additions require database schema or data model changes.

Determine whether this feature requires data model changes first.

Check:
1. Whether existing models are sufficient
2. Whether new tables/collections are needed
3. Whether migration is required
4. Whether compatible with existing data
5. Whether rollback is possible
6. Whether test data is needed

Don't create migration files yet.

Reviewing with Ultra Think

ultrathink.

Review whether this feature's data model changes are safe.
Organize existing data compatibility, migration order, rollback strategy,
and test cases. Don't modify files yet.

Database changes are harder to revert than code changes. Plan first, apply small, and think about rollback.

09Features with API Changes

Features that add or modify APIs affect both client and server together.

Design the API changes needed for this feature.

Include:
1. endpoint
2. request format
3. response format
4. error response
5. authentication/permission requirements
6. compatibility with existing APIs
7. test cases

Don't implement yet.

API Design Example

GET /api/notifications
Response:
{
  "items": [...],
  "unreadCount": 3
}

API Permission Review

Who should be able to call this API?
Check if server-side permission verification is needed to ensure only personal data is queried.

If the API requires permissions, add Ultra Think.

ultrathink.
Review whether this API design is safe in terms of permissions.
Check for any bypass paths allowing query or modification of other users' notifications.

10Features with UI Changes

UI features must consider screen behavior, state management, error handling, and loading states.

Create a UI implementation plan for this feature.

Check:
1. Components to modify
2. State values needed
3. Loading state
4. Error state
5. Empty state
6. Accessibility considerations
7. Existing design patterns
8. Testing method

Don't modify files yet.

UI State Example

Loading notification list

empty

No notifications

error

Failed to fetch list

unread

Unread notification

read

Read notification

clicked

After clicking notification and navigating

Check existing UI component patterns first,
and create a plan to implement notification UI following that pattern.
Reuse existing components; don't create a new design system.

11Planning Tests

Feature additions must be accompanied by tests. Check existing test files and write tests matching the project's testing style, framework, and assertion patterns.

Create a test plan for this feature.

Categories:
1. Unit tests
2. Integration tests
3. E2E tests
4. Permission tests
5. Failure/error cases
6. Edge cases

Check existing test style first,
and propose what tests should be added.

Test Points by Feature Type

Notification feature

Create notification when comment added, mark as read

Search feature

Keywords, empty results, special characters

Permission feature

Allowed and denied users

Payment feature

Success, failure, duplicate requests, webhook retries

Upload feature

File size, extension, failure handling

Write Tests First (TDD)

Write tests for this feature first.
Follow existing test style,
and write tests that can fail before implementation.
Don't modify implementation code yet.

12Requesting Stage-by-Stage Implementation

Once the plan is approved, implement stage by stage. Review changes after each stage.

Implement only stage 1 of the plan.

Rules:
- Implement with minimal changes
- Don't refactor unrelated code
- Don't separate formatting-only changes
- Summarize modified files after changes
- Notify before running tests if needed

Review After Each Stage

Summarize the git diff of what was just changed.
Distinguish between intended and unintended changes.

Proceed to Next Stage

Now proceed to stage 2.
Maintain the structure set in stage 1,
and explain first if new design changes are needed.

Large features are safer with "implement small repeatedly" than "implement all at once".

13Pausing When Requirements Change During Implementation

During feature implementation, facts may emerge that differ from the original plan. Claude must not change direction arbitrarily.

If you discover facts differing from the existing plan during implementation,
don't fix immediately. Stop and notify me.

Report:
1. What was unexpected
2. Impact on the existing plan
3. Available alternatives
4. Recommendation
5. What I need to decide

Reviewing Existing Structure Reuse

If there's existing notification-related code, don't create a new structure.
First review whether existing structure can be reused.

When Claude discovers unexpected structure during implementation, the plan should be updated rather than continuing implementation.

14Confirming Documentation Updates

Feature additions may require documentation changes. After implementing the feature, check if documentation updates are needed.

Check if this feature addition requires documentation updates.

Documents to check:
1. README
2. API documentation
3. .env.example
4. Developer guide
5. changelog
6. User help

If needed, propose which documents to change and how.
Don't modify yet.

Documentation Updates by Feature Change

Add new API

API documentation

Add new environment variable

.env.example, README

Add new command

README

Change configuration method

Developer guide

Change user interface

User guide or release notes

Code changes are complete, so handle documentation updates as a separate stage.
Propose which documents to change before modifying.

15Reviewing Permissions and Security

New features can create security problems. Features related to user data, payments, permissions, admin functions, and file uploads must be carefully reviewed.

Review whether this feature addition is secure.

Check:
1. Whether the API requires authentication
2. Whether only personal data is accessible
3. Whether admin permission verification is needed
4. Whether sensitive information is exposed in responses or logs
5. Whether input validation is needed
6. Whether rate limiting is needed
7. Whether tests are sufficient

Don't make additional modifications yet. Only report review results.

Ultra Think Review for High-Risk Features

ultrathink.

This feature involves user permissions and personal information.
Deeply review possibilities of permission bypass, data exposure, and missing input validation.
Don't modify yet.

16Investigating Impact Scope with Subagent

Large features may have many related files. Reading all files in the main conversation expands context. Delegating to subagent keeps the main context clean by reading files in a separate context and returning only summaries.

Use subagent to investigate the impact scope of this feature.

Feature:
- Comment notification feature

Investigate:
1. Comment creation flow
2. Existing code related to user notifications
3. Authentication/permission handling
4. Test file locations
5. UI display locations

Return to main conversation with only key file list and implementation candidates summarized.
Don't modify files yet.

Additional Constraints for Subagent Investigation

Ignore vendor folders during investigation,
and if existing notification structure exists, don't create a new structure.
First check for reuse possibilities.

17Creating Feature Completion Criteria

Feature addition doesn't end at "showing on screen". Completion criteria must be created first.

Create completion criteria for this feature.

Include:
1. Whether user scenarios are met
2. Whether API or UI behavior is verified
3. Whether permission conditions are maintained
4. Whether tests are added
5. Whether documentation updates are needed
6. Whether git diff contains no unnecessary changes
7. Whether remaining risk factors are organized

Completion Criteria Example

Notification is created when a comment is added.

Only own notifications can be queried in the notification list.

Unread count decreases after marking as read.

Unauthorized users cannot see other users' notifications.

Related unit and integration tests pass.

README or API documentation is updated if needed.

18Running Tests and Reviewing Results

After implementation, run tests. Run related tests first and analyze failure causes.

npm test

You can also run only related tests first.

npm test -- notifications

Run related tests first.
If they fail, analyze only the first failure cause,
and distinguish cascading failures.

Review After Tests Pass

Based on test results, review whether this feature meets completion criteria.
Notify if there are insufficient tests or edge cases.

Commonly Missed Edge Cases

Notification

Zero notifications state

Empty search term, special characters

List

Pagination last page

Permission

Other user data access

Upload

Capacity exceeded, disallowed extension

Payment

Duplicate webhook, retry after failure

19Final Review with git diff

After features work and tests pass, check changes with Git.

git status
git diff

Review current git diff.

Check:
1. Whether changes are directly related to feature addition
2. Whether unintended files were modified
3. Whether formatting changes are mixed in
4. Whether enough tests are added
5. Whether documentation updates are needed but missing
6. Whether security or permission risks exist
7. Whether commits should be split

Dividing Changes into Commits

Divide this change into commits.
Propose whether separation by model/API/UI/test/docs is possible.
Don't git add or commit yet.

As features grow, diff review and commit separation become more important.

20Creating PR Description

Feature additions are typically reviewed via PR. Before creating a PR, draft a description that clarifies key points for reviewers.

Before creating a PR, draft a description.

Include:
1. Change summary
2. User-visible changes
3. Implementation details
4. Test results
5. Key areas for reviewers
6. Remaining risk factors
7. Related issues

PR Description Template

## Change Summary
-

## User-Visible Changes
-

## Implementation Details
-

## Testing
-

## Reviewer Checklist
-

## Risk Factors / Remaining TODOs
-

21Adding Feature Addition Rules to CLAUDE.md

If feature addition rules repeat, write them briefly in CLAUDE.md. However, since CLAUDE.md occupies context in every session, write concisely.

# Feature Development Workflow

- Organize requirements for new features before implementation.
- Investigate related files and existing similar features first.
- Present implementation plan before modifying files.
- Implement large features in small stages.
- Don't mix unrelated refactoring or formatting changes.
- Include permission checks for new APIs.
- Check whether related tests and documentation updates are needed when adding features.
- Summarize git status and git diff before commits.

CLAUDE.md should be written concisely, aiming for 200 lines or less.

22Real-World Complete Prompt Template

The template below can be used directly when adding new features.

Proceed with the feature addition workflow.

Feature description:
-

User scenarios:
1.
2.
3.

Expected behavior:
-

Constraints:
- Maintain existing API response format if possible
- Follow existing code style and folder structure
- Don't refactor unrelated code
- Present plan before modifying files

Progress sequence:
1. Organize requirements.
2. Ask about unclear points.
3. Find related file candidates.
4. Investigate existing similar features and patterns.
5. Propose staged implementation plan.
6. Create test plan.
7. Once I approve, implement stage 1 with minimal changes.
8. After each stage, summarize git diff.
9. At the end, check whether tests and documentation updates are needed.

Don't modify files yet.

Complex Feature Addition

For complex features, add on the first line.

ultrathink.

Using Plan Mode Together

To use Plan Mode together, start this way.

ultrathink.

Create a feature addition plan in Plan Mode.
Don't modify files until I approve.

23Prompt Examples by Feature Type

Notification Feature

I want to add a feature where post authors get notifications when comments are added.

First organize requirements,
and find the comment creation flow, user model, and any existing notification-related code.
Don't implement yet; only propose a plan.

Search Feature

I want to add a post search feature.

Requirements:
- Search in title and body
- Handle empty search term
- Maintain pagination
- Compatible with existing list API

First investigate related API and query structure,
then propose implementation plan and test cases.

Admin Feature

I want to add a feature where admins can deactivate users.

ultrathink.

Organize requirements and risk factors focusing on permission verification.
Need to ensure regular users can't bypass this feature.
Don't modify files yet.

File Upload Feature

I want to add a profile image upload feature.

First design:
1. Allowed file types
2. Maximum file size
3. Storage location
4. Security validation
5. Failure handling
6. Test cases

Proceed with implementation after my approval.

Payment Feature

I want to add a subscription payment feature.

ultrathink.

Organize requirements and implementation plan based on payment success, failure, webhook, duplicate requests, refunds, permissions, and DB consistency.
Don't modify files yet.

24Beginner Feature Addition Checklist

Confirm the checklist below each time you add a feature.

Feature descriptionConcrete?

User scenariosPresent?

Expected behaviorOrganized?

Unclear pointsAsked?

Related filesFound?

Existing patternsVerified?

Implementation planReceived?

Stage divisionDone?

Data modelVerified?

API designReviewed?

UI stateConsidered?

Test planCreated?

Documentation updateVerified?

git statusReviewed?

Commit divisionNeeded?

Section 18 · Conclusion

Unit 18 Key Summary

Feature addition isn't "just build it" but requirements clarification → related file exploration → plan approval → staged implementation → testing → documentation → diff review.

Describing user scenarios is better than feature names.
Claude should ask about unclear requirements rather than guessing.
Don't read entire project aimlessly; narrow to related file candidates first.
Investigate existing similar features, API structure, and test style first.
Before implementation, get plan in Plan Mode and implement in small stages after approval.
For features involving DB, APIs, permissions, payments, and personal information, review risk factors with Ultra Think.
New features require test planning, ideally writing failing tests before implementation.
After feature addition, check if documentation updates are needed.
At the end, review with git status, git diff for unintended changes.
For large codebases, investigate impact scope with subagent to maintain main context.

Next unit

Unit 19. Refactoring and Requesting Code Review

19. Refactoring and Requesting Code Reviews

01Distinguishing refactoring from feature additions

Refactoring is not about creating new features. It is improving code structure, removing duplication, clarifying names, separating concerns, and enhancing testability while preserving existing behavior.

Adding features

Creating new behavior

Bug fixing

Fixing incorrect behavior

Refactoring

Improving internal structure while preserving existing behavior

Code review

Finding risks and improvements in changes

Bad request:

Clean up this code for me.

Good request:

I want to refactor this code.
Goal: preserve existing behavior
Remove duplicate validation logic
Separate function responsibilities
Existing tests should still pass
First propose a refactoring plan without making changes.

First principle of refactoring: never change behavior

02Making a plan before refactoring

Refactoring scope can easily grow larger. So it is safer to start with Plan Mode first. The official common workflows documentation also recommends "Plan before editing," suggesting Plan Mode if you want to review changes before they touch disk. Also, exploring large codebases can be delegated to subagents to keep the main context clean.

Request example:

Create a refactoring plan using Plan Mode.
Target: src/auth folder
Goal: separate token parsing logic
Remove session validation duplication
Preserve existing API response format
Include in the plan:
1. Current structure summary
2. Files to refactor
3. Behavior that must not change
4. Step-by-step modification order
5. Testing method for each step
6. Risk factors
7. Rollback method
Don't modify files until I approve.

To start in plan mode from the beginning:

claude --permission-mode plan

Refactoring requires planning before implementation.

03Limiting the scope of changes

Refactoring often leads to situations where you intended to clean up a little but ended up changing the whole project. That is why scope must be clearly limited.

Bad request:

Refactor the entire codebase.

Good request:

Refactor only src/auth/session.ts file.
Constraints: don't change public function names
Preserve API response format
If tests break, stop and explain the reason
Don't make unrelated formatting changes.

File-based

Modify only src/auth/session.ts

Folder-based

Modify only within src/auth/**

Behavior-based

Preserve API response format

Test-based

Preserve existing test passing status

Commit-based

One purpose per step

Risk-based

Exclude DB migration

04Finding refactoring candidates

When you don't know what to refactor, start by finding candidates.

Request example:

Find refactoring candidates for me.
Criteria:
1. Duplicate code
2. Functions that are too long
3. Files with too many responsibilities
4. Functions with vague names
5. Error handling that repeats
6. Structures that are hard to test
Output: file path, problem description, refactoring difficulty, risk level, order
Don't modify files yet.

Priority 1

session.ts — token validation duplication, medium risk

Priority 2

authMiddleware.ts — too many responsibilities, high risk

Priority 3

validators.ts — vague function names, low risk

Beginners should start with low-risk items first.

05Clearly documenting behavior preservation conditions

The most important thing in refactoring is "preserving existing behavior". You must clearly communicate this condition to Claude.

Refactoring conditions:
- Preserve existing public API
- Don't change function inputs and outputs
- Preserve error message format
- All existing tests must pass
- Performance characteristics must not degrade
- Don't modify unrelated files

Especially for API or library code, be stricter:

This module is code that other modules import and use.
Don't change exported function names, types, or return values.
Only clean up the internal implementation.

For UI components:

Don't change UI behavior or visual results.
Only improve component separation and state management structure.

06Refactoring in small steps

Large refactoring all at once is hard to review. You should proceed in small, testable units.

Request to divide into steps:

Break this refactoring into small steps.
Conditions:
- Each step must be reviewable with git diff
- Don't modify too many files in one step
- Each step should be testable
- Don't mix behavior changes with structure changes

Step examples:

Step 1: Combine duplicate validation functions into one
Step 2: Separate token parsing function into its own file
Step 3: Change auth middleware to call session service
Step 4: Run existing tests
Step 5: Add necessary regression tests

Request one step at a time:

Apply only step 1 from the plan.
Make minimal changes,
and after completion show me the modified files and git diff summary.

07Running tests during refactoring

Testing is important in refactoring since you must not change behavior.

Finding test commands before refactoring:

Find relevant test commands before refactoring.
After confirming the test commands,
suggest which tests to run after modification.

Testing after modification:

Run relevant tests for me.
If they fail, analyze only the first failure reason,
and check if refactoring changed the behavior.

Claude can observe existing test files and match project test style, frameworks, and assertion patterns, and can suggest edge cases.

If tests are insufficient:

Check if there are insufficient tests for safe refactoring.
If regression tests following existing test style are needed, suggest them.
Don't modify test files yet.

08Reviewing git diff after refactoring

After refactoring, always check Git diff.

git status
git diff

Request Claude like this:

Review the current git diff for me.
Check for:
1. Whether behavior changes are mixed in
2. Whether files outside refactoring scope were modified
3. Whether unnecessary formatting changes are mixed in
4. Whether public API changed
5. Whether there are parts that need testing
6. Whether commits need to be split
Don't run git add or commit yet.

For large refactoring, use Ultra Think:

ultrathink.
Review the current git diff deeply.
Analyze whether this change is pure refactoring,
whether behavior changes are mixed in,
and whether there are unconfirmed risks by tests.

09When should you request code reviews?

Code review is not just something done at the end of work. You can request it at these moments.

Before implementation

Review plan safety

After step 1

Confirm direction is correct

After test failure

Check if failure is due to refactoring

Before commit

Final diff review

Before PR

Organize risk factors from reviewer perspective

Basic request:

Review my current changes for code review.
Review from security, performance, maintainability, and test coverage perspectives.
Don't make modifications yet, just provide review feedback.

Getting results by priority:

Organize review results in this format.
1. Critical: issues that must be fixed
2. Warning: issues that should be fixed
3. Suggestion: improvements to consider
4. Question: design questions needing clarification

10Using `/code-review`

Claude Code provides bundled skills like /code-review, /debug, /batch, /loop, and /claude-api in every session, callable directly in /skill-name format. /code-review is not a fixed-logic command but a prompt-based skill where Claude orchestrates tools to accomplish the work.

Basic usage:

/code-review

Request more specifically:

/code-review Review based on the current git diff.
Prioritize security, error handling, missing tests, and performance issues.

For beginners, read-only review is recommended as default:

/code-review
Just review.
Don't modify files.

Auto-fix is considered only under these conditions:

Started from a clean git status
Changes can be reverted
Review results are small and clear
Must review git diff after fix
Run tests

Safe request:

Show me code review results first.
Don't auto-fix.
Once I approve each item, fix them one at a time.

11Creating your own code review prompt

You can also request review without using /code-review.

Review my current changes from a senior engineer perspective.
Scope: based on git diff, focus on modified files, include new tests
Focus on:
1. Bug potential
2. Security issues
3. Missing permission validation
4. Error handling
5. Performance issues
6. Duplicate code
7. Missing tests
8. Maintainability
Format: Critical / Warning / Suggestion / Praise / Final judgment

More strictly:

Find only review-blocking-level issues first.
Put style preferences and minor naming aside for later.

More gently:

Review as if explaining to a beginner.
Explain not just problems but why they are problems and how to fix them.

12Security-focused code review

If the code includes permissions, authentication, payments, personal information, file uploads, or admin features, request a separate security review.

Review code from a security perspective.
Check:
1. Whether APIs requiring authentication have auth checks
2. Whether users can only access their own data
3. Whether admin permission bypass is possible
4. Whether input validation is sufficient
5. Whether sensitive information is exposed in logs or responses
6. Whether secrets, API keys, or tokens are included in code
7. Whether error messages expose internal information
8. Whether rate limit or abuse prevention is needed
Don't make modifications yet, just show review results.

For critical changes, add Ultra Think:

ultrathink.
This change is related to permission logic.
Review deeply focusing on permission bypass potential.
Don't make modifications yet.

13Performance-focused code review

Refactoring can also degrade performance. Especially when loops, DB queries, API calls, or rendering are involved, request performance review.

Review code from a performance perspective.
Check:
1. Unnecessary loops
2. N+1 query potential
3. Duplicate API calls
4. Parts that need caching
5. Async handling issues
6. Code that slows with large data
7. React re-render potential
8. Memory usage increase potential
Don't make modifications yet,
but report risk level and rationale.

Performance review should not end in speculation:

For suspected performance issues,
also suggest measurement methods or logs/tests to check.

14Maintainability-focused code review

The core goal of refactoring is improving maintainability.

Review code from a maintainability perspective.
Check:
1. Whether functions have too many responsibilities
2. Whether names clearly express intent
3. Whether there is duplicate logic
4. Whether abstraction is excessive or insufficient
5. Whether structure is easy to test
6. Whether new developers can easily understand it
7. Whether error handling patterns are consistent
8. Whether it matches existing project style

Don't immediately apply review results; examine them first:

Organize maintainability improvements by risk level.
Distinguish whether each suggestion has real value
or is just a style preference.

15Creating a code-reviewer subagent

If you do code reviews repeatedly, you can create a code-reviewer subagent. Design it as a read-only code reviewer.

Save location: .claude/agents/code-reviewer.md

Example file:

---
name: code-reviewer
description: Read-only code reviewer that examines code quality, security, and maintainability. Use immediately after code changes.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer.

Review procedure:
1. Run git diff to check recent changes.
2. Focus on modified files.
3. Do not modify code.
4. Provide review results only.

Review checklist:
- Is code clear and easy to read?
- Are function and variable names appropriate?
- Is there duplicate code?
- Is error handling adequate?
- Are there no exposed secrets, API keys, or tokens?
- Is input validation sufficient?
- Is test coverage sufficient?
- Are there performance issues?

Output format:
- Critical: issues that must be fixed
- Warning: issues worth fixing
- Suggestion: worthwhile improvements
- Good: things done well

Usage example:

Review my current changes with the code-reviewer subagent.
Just show review results without modifying.

16Review subagents are safer as read-only

Code reviewers should fundamentally not have modify permissions. If reviewers detect and fix simultaneously, changes can get mixed in before users review.

Good tool setup:

tools: Read, Grep, Glob, Bash

Setup to avoid:

tools: Read, Grep, Glob, Bash, Edit, Write

Separate review from modification:

code-reviewer finds problems
User chooses items to fix
Claude fixes only chosen items
Run tests
Review again

This workflow is safest for beginners.

17Connecting review results to fixes

After receiving review, don't immediately fix everything; prioritize first.

Choose only issues from review that absolutely need fixing.
Separate Critical from Warning,
and tell me each item's fix difficulty and risk level.

Then fix one at a time:

Fix only Critical item 1.
Don't touch other review items yet.
After fixing, summarize the git diff.

Verify after applying review:

Check whether the fix just made resolves the review item.
Also check if new issues appeared.

Bad request to auto-fix everything:

Fix all the review issues.

Safer request:

Organize review items by priority.
Fix only the items I approve, one at a time.

18Requesting PR review

Before creating a PR, review changes from a reviewer perspective.

Request example:

Before creating a PR, review changes from a reviewer perspective.
Check:
1. Whether PR purpose is clear
2. Whether scope is not too large
3. Whether test results are sufficient
4. What files reviewers should focus on
5. Risky changes
6. Whether commits need splitting
7. Content for PR description

PR description template:

## Change Summary
-

## Refactoring Goal
-

## Behavior Changes
- None / Yes

## Testing
-

## What Reviewers Should Focus On
-

## Risk Factors
-

For refactoring PRs, it is good to clearly note "no behavior changes."

19GitHub Actions-based code review

At team scale, you can automate Claude Code review with GitHub Actions. For the beginner guide, learning the local workflow first before automation is better.

Recommended order:

Review git diff locally
Use /code-review or code-reviewer subagent
Run tests
Write PR description
Review GitHub Actions automation once team is familiar

Even when adopting auto-review, people must make final judgments:

AI review is not a replacement for reviewers but an assisting tool that finds things reviewers might miss.

20Adding refactoring and review rules to CLAUDE.md

Keep repeated rules short in CLAUDE.md.

# Refactoring Rules

- Refactoring must preserve existing behavior.
- Don't change public API, response format, or error messages without explicit approval.
- Large refactoring should present plan in Plan Mode first.
- Divide changes into small steps and test after each step.
- Don't mix unrelated formatting or naming changes.
- Review git status and git diff before commit.

# Code Review Rules

- Reviews are based on git diff.
- Prioritize into Critical, Warning, and Suggestion.
- Prioritize reviewing security, permissions, error handling, and missing tests.
- Keep reviewer subagents read-only by default.
- Apply only user-approved review items.

21Practical template: refactoring workflow

Follow refactoring workflow.
Target:
- Goal:
- Behavior to preserve:
- What must not change:
  - Public API
  - Response format
  - Error messages
  - Existing test expectations
Workflow rules:
1. Don't modify immediately.
2. First summarize current structure.
3. Organize refactoring candidates and risk levels.
4. Create plan in small steps.
5. Once I approve, modify only step 1.
6. Run relevant tests after each step.
7. Review git diff to check for behavior changes.
8. Suggest commit split criteria.

For complex refactoring:

ultrathink.
Create refactoring plan in Plan Mode first.
Don't modify files until I approve.

22Practical template: code review workflow

Follow code review workflow.
Target: current git diff
Review perspectives:
1. correctness
2. security
3. permission/auth
4. error handling
5. performance
6. maintainability
7. test coverage
8. documentation needed
Output format:
- Critical: must fix
- Warning: should fix
- Suggestion: improvement idea
- Question: needs clarification
- Good: things done well
Rules:
- Don't modify files.
- Just provide review results.
- Include rationale and file location for each item.
- Make fix suggestions specific, but only apply after I approve.

23Refactoring prompts by type

Removing duplicate code

I want to refactor duplicate validation logic.
First find duplicate locations,
and analyze whether behavior is preserved when separating into a common function.
Don't modify files yet.

Separating long functions

This function is too long.
Create a plan to divide responsibilities while preserving behavior.
Also tell me test cases to run after function separation.

Type cleanup

I want to reduce any type usage.
First find where any is used,
and suggest type improvement plan ordered by risk level.
Don't change behavior.

24Refactoring prompts by type (continued)

Improving error handling

I want to make error handling patterns consistent.
First investigate existing error handling methods,
and create an improvement plan matching existing patterns, not creating new ones.

Performance refactoring

I want to improve this code's performance.
First analyze possible bottlenecks,
and suggest measurement methods.
Be careful not to change behavior under the guise of performance improvement.

Beginner refactoring and code review checklist:

Is refactoring goal clear?
Have you documented behavior preservation conditions?
Have you limited scope by file/folder criteria?
Have you received plan in Plan Mode?
Did you avoid modifying too many files at once?
Did you avoid changing public API, response format, or error messages?
Have you run related tests?
Have you checked git diff for mixed behavior changes?
Have you categorized review into Critical, Warning, Suggestion?
Have you checked security, permissions, error handling, and test coverage?
Did you avoid fixing all review items at once?
Have you checked whether commits need splitting?

Section 19 · Summary

What to remember from this unit

Refactoring is work that improves internal structure while preserving existing behavior. It is safer to create a plan in Plan Mode before refactoring.

Limit change scope by file, folder, public API, and test criteria. Divide large refactoring into small, testable steps.

After modification, always run related tests and review git diff. Code review can be requested not just before commit, but also at the planning stage, mid-stage, and before PR.

/code-review is a bundled skill in Claude Code available in every session, and beginners should use read-only review by default rather than auto-fix review.

Security, permissions, payments, and personal information changes require separate security review and Ultra Think. Repeated reviews can be separated into a code-reviewer subagent, and it is good to keep reviewer subagents read-only.

Next section

Section 20. Running tests, linting, and builds with Claude

20. Running Tests, Lint, and Builds with Claude

01What You'll Learn in This Section

The goal of this section is to safely delegate the following tasks to Claude Code.

1. Find the project's test, lint, and build commands.
2. Run only the relevant tests first.
3. Analyze the root cause from the failure log.
4. Fix lint errors safely.
5. Narrow down build failure causes step by step.
6. Get a plan before automatic fixes.
7. Run tests, lint, and build again after fixes.
8. Finally, review changes with git diff.

Tests, lint, and build are not "procedures to run once at the end," but verification routines to confirm that Claude Code's changes are safe.

02Document Commands in CLAUDE.md

For Claude to run tests, it needs to know what commands your project uses. The best approach is to document the commands in CLAUDE.md.

Example

# Project Commands

## Test
- Full test: npm test
- Auth test: npm test -- auth

## Lint
- npm run lint

## Build
- npm run build

## Type Check
- npm run typecheck

03Find Commands When Unknown

If you don't know the commands already, have Claude find them first.

Find the test, lint, and build commands for this project.

Files to check:
- package.json
- README
- Makefile
- pyproject.toml
- composer.json
- Cargo.toml
- docs folder

Don't run commands yet.
Just organize the candidate commands and their rationale.

After finding the commands, check safety before running.

Distinguish which commands are safe to run now.
Categorize tests, lint, build, and commands with deployment/deletion/external call potential separately.
Don't run them yet.

04Run Related Tests Before Full Tests

Beginners often run the full test suite right after fixing a feature. However, on large projects this takes time and produces long logs. Running related tests first is better.

Running Related Tests by Language

npm test -- auth

pytest tests/test_auth.py

go test ./internal/auth

Requesting from Claude

Run only tests related to this change first.
If full tests are needed, explain why,
and tell me which command you'll run before executing.

If the scope is small, restrict it further.

Find and run only tests directly related to the files you modified.
If no tests exist, suggest what tests should be added first.

05Analyze Test Failure Logs

When tests fail, don't blindly ask Claude to fix everything.

Bad Request

Tests failed. Fix everything.

Good Request

Analyze only the first failure cause from the test failure log.
Distinguish cascading failures separately,
and propose the root cause and fix plan first.
Don't modify files yet.

Important Principles

Look at the first failure.
Don't mistake cascading failures for root causes.

06Test Failure Analysis Template

This format is useful when analyzing test failure logs.

Analyze the test failure.

Run command:
- npm test -- auth

First failure:
- (failure message)

Related stack trace:
- (stack trace)

Request:
1. Explain what the failed test is validating.
2. Estimate the actual root cause.
3. Suggest up to 3 related file candidates.
4. Present a fix plan first.
5. Don't modify files yet.

If the log is long, limit like this.

Don't read the entire log.
Analyze based only on the first FAIL block and its surrounding stack trace.
Tell me what additional log sections you need, if any.

07Safe Workflow for Fixing Test Failures

Follow this sequence when fixing test failures.

Understand what the failed test is validating.
Distinguish whether the test is correct or the implementation is wrong.
Organize root cause candidates.
Get a fix plan first.
Make minimal changes to fix.
Run the same test again.
Expand to related tests.
Review changes with git diff.

Requesting from Claude

Before fixing this test failure,
determine first whether the test expectation is correct or the implementation is wrong.
If a fix is needed, present a minimal change plan.

The test itself may be wrong, so don't immediately change the implementation.

Compare cases where the test should be fixed vs. cases where the implementation should be fixed.
Explain which is more justified with reasoning.
Don't modify anything yet.

08Add Regression Tests

When you fix a bug, it's good to add a regression test so the same problem doesn't happen again.

Add a regression test so this bug doesn't happen again.

Conditions:
- Follow existing test style
- Should fail before the fix and pass after
- Test name should describe the bug scenario
- Propose the test plan first,
and modify the test file after my approval.

If the project lacks tests, ask like this.

This project seems to lack test structure.
Suggest the smallest test method to validate this change.
Tell me whether unit tests, integration tests, or manual verification is appropriate.

09Running Lint

Lint is a tool that catches code style, potential errors, and rule violations.

Common Commands

npm run lint

pnpm lint

ruff check .

eslint .

Requesting from Claude

First, confirm the command.

Confirm this project's lint command.
Find evidence in package.json or README,
and tell me only the command candidates without running yet.

Then run it.

Run the lint command.
If it fails, categorize errors by type,
and distinguish what can be auto-fixed from what requires human judgment.

10Categorizing Lint Error Types

Lint errors usually fall into these categories.

Formatting

Line breaks, semicolons — can be auto-fixed

Unused variables

unused variable — delete or verify usage

Type-related

no-explicit-any — requires design judgment

Import order

sort-imports — can be auto-fixed

Dangerous patterns

no-floating-promises — requires human review

11Be Careful with Auto-fix

Many projects have auto-fix commands.

npm run lint -- --fix

eslint . --fix

ruff check . --fix

However, auto-fix can change more files than expected. So always get a plan first.

Before running lint auto-fix,
explain which command you'll run and which files might be affected.
Don't run --fix yet.

After running, always review the diff.

After running lint --fix, review git diff.
Distinguish formatting changes, actual logic changes, and unintended changes.

--fix is convenient, but always confirm with git diff after running.

12Running Build

Build is a process to verify that code is in a deployable state.

Common Commands

npm run build

pnpm build

cargo build

go build ./...

Requesting from Claude

Find this project's build command.
Show command candidates and evidence first,
and run after my approval.

If build fails:

Analyze the build failure log.
Explain the root cause based on the first actual error,
and distinguish type errors, import errors, environment variable errors, and config errors.
Don't modify files yet.

13Analyzing Build Failure Types

Build failures usually fall into these categories.

Type error

TypeScript compile error — verify type definitions and return values

Import error

module not found — check path, export, alias

Environment variable error

missing env — check .env.example and config

Dependency error

package missing — check package.json and lockfile

Config error

bundler config error — check vite, webpack, tsconfig

Build with tests fails

build script runs tests — separate failure stages

14Run Type Check Separately

In projects using TypeScript, Python, Rust, Go, etc., it helps to run type checking separately before build.

Type Check by Language

npm run typecheck

tsc --noEmit

mypy .

cargo check

Requesting from Claude

Check if this project has a typecheck command.
If it does, suggest a workflow that runs typecheck before build.

Type errors can be more directly connected to actual behavior than lint errors.

Analyze type errors.
Don't mask them with simple type casting,
but verify first that actual data structures and function return values are correct.

Bad Fix

Change to any and pass.

Good Fix

Don't mask type errors with any,
but infer the correct type and propose a fix plan.

15Run Long Commands in the Background

Builds, full tests, E2E tests, and dev servers can take time. Claude Code supports background bash commands, allowing Claude to receive a task ID immediately and continue processing other requests.

Request Example

Full tests might take a while, so run them in the background.
While they're running, review related files,
and when done, read the result log and analyze only the first failure.

You can also run directly in shell mode by prefixing with !, which executes the shell command without Claude.

! npm test

However, long output consumes context, so for long tests, run only necessary ranges or request a summary.

16Decide Execution Order

A safe general verification order is usually this.

Related tests
Lint
Typecheck
Build
Full tests

But it can vary by project. Have Claude decide the order.

Suggest the command execution order to validate this change.

Consider:
1. Fastest verification first
2. Order that makes failure causes easy to narrow down
3. Long commands last
4. Full tests last if needed
5. Expected purpose of each command

Don't run yet.

Fast and narrow verification first, slow and broad verification last.

17Handling Multiple Failures

When tests, lint, and build all fail, it's easy to panic. Don't try to fix everything at once.

Even if there are multiple failures, don't fix them all at once.
First categorize failures by type,
and choose only the one with the most likely root cause.

Categorization Order Guide

compile/type error

Fix first

import/module error

Fix first

test assertion failure

After type errors are resolved

lint formatting error

Fix later

snapshot failure

After verifying change intent

E2E failure

After unit/build passes

Request to Claude

Categorize failure logs by type.
Organize by likelihood of root cause,
and propose a fix plan for only the first cause.
Don't modify files yet.

18Confirmation Before Auto-fix

When Claude tries to fix test or lint failures, always get a plan before auto-fixing.

Show the plan before auto-fixing.

Include:
1. Which failure you'll fix
2. Rationale for the root cause
3. Files to modify
4. How to fix
5. Expected side effects
6. Commands to run after the fix
7. How to revert

Don't modify files until I approve.

Even after approval, limit the scope.

Modify only item 1 from the plan.
Don't touch other failures yet.
Run only related tests after the fix.

19Don't Casually Update Snapshots

In frontend projects, snapshot tests can fail. Auto-updating snapshots can cause you to miss actual UI changes.

Bad Request

Update snapshot and make it pass.

Good Request

Analyze the snapshot failure cause first.
Distinguish whether it's an intended UI change, a bug, or a broken test.
If snapshot update is needed, explain why,
and don't update until I approve.

What to Check Before Updating Snapshots

Is the UI change intended?
Does the changed snapshot match the user-visible behavior?
Are related component tests sufficient?
Is this just hiding a failure with an update?

20Build Failures and Environment Variables

Build failures can be due to environment variable issues rather than code problems.

Example

Missing required environment variable: DATABASE_URL

Reading or modifying .env is risky. Sensitive files must be protected.

Requesting from Claude

Check if build failure is due to environment variables.
Don't read the .env file,
but estimate needed variable names from .env.example, README, and config schema.

Good Fix Request

Don't modify the .env file.
If needed, propose a plan to add only missing variable names and descriptions to .env.example.

21Be Careful with Package Lockfile Changes

While fixing tests or build, lockfiles like package-lock.json, pnpm-lock.yaml, yarn.lock can change.

Lockfile changes can be intentional, but dependency installs or version changes might be mixed in.

Check if the lockfile changed.
If it did, explain why,
and whether the change is necessary for this task.
Don't commit yet.

If dependency installation is needed:

Verify that installing a new dependency is really necessary.
Check if existing dependencies can solve it,
and if installation is needed, explain the reason and impact scope.

Before installing new packages to pass tests, always verify the reason.

22Automate with Hooks

Tests, lint, and formatting are repetitive. Hooks can automate recurring verifications.

Hooks are custom shell commands that run at specific points in the Claude Code lifecycle. For example, you can automate formatting after editing files, blocking commands before execution, or validating on completion.

Automate Formatting After File Modification

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Beginners should start with simpler hooks rather than complex ones.

1️⃣Run formatter after Edit/Write

2️⃣Run related lint before completion

3️⃣Block dangerous commands

4️⃣Notify when Claude waits for input

23Apply Hooks Carefully

Hooks are powerful but can ruin your workflow if configured wrong.

Dangerous Example

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm test"
          }
        ]
      }
    ]
  }
}

Running full tests on every file edit would be too slow.

Safer Approach

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --quiet"
          }
        ]
      }
    ]
  }
}

Or establish team rules like this.

Formatters can run automatically.
Full tests and build run only after user approval.

24Put Verification Rules in CLAUDE.md

Document recurring test, lint, and build rules in CLAUDE.md.

# Verification Workflow

## Commands
- Test related files first: npm test -- 
- Full test: npm test
- Lint: npm run lint
- Type check: npm run typecheck
- Build: npm run build

## Rules
- Run related tests first after modifications.
- Run full tests after related tests pass.
- Get user approval before running lint --fix.
- Explain snapshot updates and get approval before running.
- Start from the first actual error when analyzing build failures.
- Don't read or modify the .env file.
- Summarize git status and git diff before committing.

25Full Prompt Template

You can use this template directly after implementing features or fixing bugs.

Run the verification workflow.

This change:
- (modification description)

Progress order:
1. Find related test commands.
2. Run related tests first.
3. If failing, analyze only the first failure cause.
4. Confirm and run the lint command.
5. Divide lint failures into auto-fix/needs-judgment.
6. Run typecheck if available.
7. Confirm and run the build command.
8. Determine if full tests are needed.
9. Finally, review git status and git diff.

Rules:
- Tell me which command you'll run before executing.
- Don't auto-fix until I approve.
- Don't run lint --fix, snapshot update, or dependency install without approval.
- Don't read or modify .env.

26Beginner Checklist

Finally, here's Section 20's essentials as a checklist.

Did you document test, lint, and build commands in CLAUDE.md?

☐

Did Claude explain what commands will run before executing?

☐

Did you run related tests first?

☐

Did you analyze failure logs from the first failure?

☐

Did you categorize lint errors into auto-fix/manual judgment?

☐

Did you get approval before running lint --fix?

☐

Did you avoid casual snapshot updates?

☐

Did you run typecheck separately?

☐

Did you find the first actual error in build failures?

☐

Did you avoid reading or modifying .env?

☐

Did you verify lockfile change reasons?

☐

Did you run tests again after fixes?

☐

Did you check git status and git diff at the end?

☐

Section 20 · Summary

What to Remember from This Section

Tests, lint, and build are core verification routines that validate Claude Code's changes. Start by documenting your project's test, lint, and build commands in CLAUDE.md.

If you don't know the commands, have Claude check package.json, README, Makefile, etc., and get candidates and reasoning before running. Always run related tests first before full tests, analyze from the first actual failure, and distinguish cascading failures from root causes.

Categorize lint errors into auto-fixable and judgment-required types, and never run lint --fix, snapshot updates, or dependency installs without approval. Analyze build failures by categorizing into type, import, environment variable, dependency, and bundler configuration issues.

Run long tests and builds with background commands, automate through hooks, and always end with reviewing git status and git diff to catch unintended changes.

Next Section

Section 21. Speeding Up Work with Slash Commands and Keyboard Shortcuts

21. Work Faster with Slash Commands and Keyboard Shortcuts

01Slash Commands are "buttons for controlling Claude Code during conversation"

When people use Claude Code for the first time, they try to request everything using sentences.

The conversation seems to have gotten really long. Can you clean it up and keep only the important content?

But Claude Code has commands that accomplish the same goal much faster.

/compact

In other words, slash commands are shortcuts — they're like buttons that execute repeated operations quickly.

Regular Prompts vs Slash Commands

Purpose

Regular: Describe a task to Claude | Command: Execute Claude Code features directly

Example

Regular: "Change the current model for me" | Command: /model

Advantage

Regular: Flexible | Command: Fast and consistent

When to Use

Regular: Describe work | Command: Control sessions, settings, costs

Beginners don't need to memorize every command. Just learning /help, /usage, /model, /status, /context, /compact, /clear, /diff, /permissions, and /config is enough.

02The First 10 Commands to Learn

/usage is the central command that shows session costs, plan usage, and activity statistics. /cost and /stats are aliases for /usage that feel familiar to existing users.

/help

When you can't remember a command | View list of available commands

/status

Check current status | Verify version, model, account, and connection

/usage

Check costs and usage | View tokens, costs, and plan consumption

/model

Change model | Switch models based on task difficulty

/effort

Adjust reasoning depth | Control how deeply the model thinks

/context

Check context usage | See how full the conversation is

/compact

Compress conversation | Summarize key content to reduce context size

/clear

Start fresh conversation | Preserve previous sessions and clear current context

/config

Change settings | Adjust theme, model, output style, etc.

/permissions

Manage permissions | Change scope of Bash, Edit, Write access

03Session Management Commands

Claude Code works in "work sessions" rather than single chats. You need to know commands for continuing sessions, starting new ones, or rewinding.

/clear [name]

Start fresh conversation | Example: /clear auth-fix-before-refactor

/resume [session]

Return to previous conversation | Example: /resume

/rename [name]

Name current session | Example: /rename payment-bug-fix

/branch [name]

Branch current conversation | Example: /branch alternate-approach

/rewind

Go back to previous point | Example: /rewind

/export [filename]

Export conversation | Example: /export session-notes.md

/exit

End session | Example: /exit

For beginners, the most important are /clear and /resume. Use /clear to empty context when starting new work, and /resume when you need to go back to previous work.

Real-world Example

/rename login-bug-investigation
/context
/compact focus on login bug root cause and files already inspected
/clear payment-refactor-start

04Cost, Model, and Reasoning Depth Commands

As Claude Code sessions grow longer, context and costs can increase. You should use cost, model, and reasoning depth commands frequently.

/usage

Check usage and costs | Verify before and after long tasks

/cost

/usage alias | Use if you prefer this term

/model

Change model | Verify before complex design or debugging

/effort

Change reasoning depth | Increase for hard problems, lower for simple edits

/fast

Switch to fast response mode | Use when speed matters more

/context

Check context usage | Start paying attention when above 50%

Decision Guide for Beginners

Simple question → Keep current model as-is
Small edit → Current model + low effort
Complex bug → Better model + high effort
Large refactor → /plan first, then adjust model/effort if needed
Long session → Check /context then /compact or /clear

/model opens a model selector or switches to a specified model, while /effort is used to choose reasoning depth like low, medium, high, xhigh, max, or auto.

05Settings and Permissions Commands

Claude Code can read, modify, and execute commands on files. That's why "safe work" matters more than "fast work".

/config

Open full settings UI | Use when changing model, theme, output style

/settings

/config alias | Use to open settings

/permissions

Manage permission rules | Change scope of Bash, Edit, Write access

/allowed-tools

/permissions alias | Use when managing allowed tools

/status

Check current status | Verify account, model, connection, version

/doctor

Diagnose installation and environment | Check for issues, auth, settings

/terminal-setup

Set up terminal keys | Use when Shift+Enter and others don't work

Recommended Habits for Beginners

Starting new project → /status
Too many permission prompts → /permissions
Terminal input feels awkward → /terminal-setup
Installation or auth issues → /doctor

06Commands Frequently Used in Development

These connect with the testing, linting, building, and review workflows you learned earlier.

/plan [description]

Enter Plan Mode | Use before large modifications to plan first

/diff

View changes | Review after Claude makes edits

/code-review

Code review | Find bugs and accuracy issues in the diff

/code-review --fix

Apply review findings | Reflect findings in working tree

/security-review

Security review | Use before changes involving auth, input, sensitive data

/init

Initialize CLAUDE.md | Create project rules file

/memory

Manage memory | Manage CLAUDE.md and auto-memory

/mcp

Manage MCP connections | Use before connecting GitHub, DB, external tools

/hooks

Check hook settings | View automated formatting and checking workflow

Real-world Work Flow

/init
/plan add validation to signup form
/diff
/code-review high
/usage

07Fast Input Prefixes: `/`, `!`, `@`

In Claude Code, / isn't the only important prefix. There are prefixes you use frequently at the start or middle of input.

Prefix

Meaning and Example

Execute slash command | Example: /context

Execute shell command | Example: ! git status

Reference file path | Example: @src/auth.ts

Real-world Usage

If you want to include and check Git status in the Claude conversation:

! git status

To ask a question while pointing to a specific file:

@src/auth.ts Explain the authentication flow in this file in a way beginners can understand.

08Keyboard Shortcuts: "Flow Continuity" Matters More Than "Speed"

Shortcuts exist to reduce interruptions in your workflow, not just to type faster.

Ctrl+C

Stop current work or clear input | Halt Claude when it's going wrong

Esc

Stop response or tool call | Change direction mid-task

Ctrl+D

End session | Terminate with EOF

Ctrl+L

Redraw screen | When terminal display gets corrupted

Ctrl+O

Toggle transcript viewer | See tool usage history in detail

Ctrl+R

Search command history | Find previous prompts

Ctrl+B

Move running task to background | Send long task to background and continue

Ctrl+T

Toggle task list | View current work list

Shift+Tab / Alt+M

Cycle permission modes | Switch between normal, accept edits, plan, etc.

Alt/Option+P

Switch model | Change model without clearing prompt

Alt/Option+T

Toggle extended thinking | Deep reasoning for hard problems

Alt/Option+O

Toggle fast mode | Switch to fast response mode

Shortcuts vary by platform and terminal. On macOS, you may need to configure Option as Meta in your terminal for Option/Alt shortcuts to work properly.

09Prompt Editing Shortcuts

When writing long prompts, shortcuts for moving the cursor, deleting parts, and pasting are useful.

Ctrl+A

Move to start of current line

Ctrl+E

Move to end of current line

Ctrl+K

Delete from cursor to end of line

Ctrl+U

Delete from cursor to start of line

Ctrl+W

Delete previous word

Ctrl+Y

Paste deleted text

Alt+B

Move back one word

Alt+F

Move forward one word

On Windows, Ctrl+Backspace also works for deleting the previous word.

10Multi-line Input Methods

In Claude Code, Enter submits messages by default. To write multi-line prompts, you need alternative input methods.

Ctrl+J

Safe method for all terminals

+ Enter

Escape method that works on all terminals

Shift+Enter

Works on supported terminals

Option+Enter

Works on macOS after Option configuration

Shift+Enter works on most modern terminals, but on VS Code, Cursor, Windsurf, Alacritty, and Zed you may need to run /terminal-setup first.

Recommended Order for Beginners

Priority 1: Shift+Enter
If that doesn't work: Ctrl+J
If still confused: \ + Enter

11To Change Shortcuts, Use `/keybindings`

If default shortcuts don't fit your hands or conflict with your terminal, use /keybindings.

/keybindings

Custom keyboard shortcuts are available in Claude Code v2.1.18 and later. Running /keybindings lets you create or open ~/.claude/keybindings.json. Changes to this file are auto-detected and applied without restarting Claude Code.

As a beginner, it's better not to change many shortcuts at first. Get comfortable with the defaults first, and only customize shortcuts that truly conflict — this builds efficient finger memory.

12Custom Slash Commands Now Connect With Skills

Older materials often explain custom slash commands by creating them in .claude/commands/. In the latest official docs, custom commands have been unified with skills.

Both .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md create /deploy, and existing .claude/commands/ files still work. However, when creating new ones, the skills approach is more extensible.

Concept Clarification

Call repeated prompts quickly

slash command

Reuse team expertise and procedures

skill

Delegate large work separately

subagent

Slash commands are best for explicit tasks the user invokes directly, skills are for expert knowledge Claude applies automatically based on context, and subagents are for work to be handled in separate contexts.

13Essential Commands Quick Reference for Beginners

Situation

Command → Next Action

Can't remember command

/help → Search in the list

Current model, account, version

/status → If odd, run /doctor

Check costs

/usage → If high, run /compact or /clear

Conversation getting long

/context → If needed, run /compact

Starting new work

/clear → Name and save previous work

Before large modifications

/plan → Approve plan then execute

After modifications

/diff → Request review if issues arise

Check code quality

/code-review → Use --fix if needed

Security review

/security-review → Use when changing auth, permissions, input

Change settings

/config → Model, theme, output style

Too many permission prompts

/permissions → Adjust allow, ask, deny rules

Terminal input issues

/terminal-setup → Configure Shift+Enter etc.

Change shortcuts

/keybindings → Modify only conflicting keys

14Real-world Routine: From Start to Finish of a Work Day

Starting Work

/status
/usage
/context

Check current status, costs, and context.

Before Large Tasks

/plan implement password reset flow

Get the plan first and review the scope of file changes.

During Work

@src/auth.ts Check only the parts related to password reset flow.
! npm test

Reference only the files you need and include test results in the conversation.

After Changes

/diff
/code-review high

Review changes and request a review.

Wrapping Up

/usage
/compact focus on final implementation summary and remaining risks

Check costs and leave key takeaways for the next session.

Section 21 · Wrap-up

What to Remember From This Section

Slash commands are the command system for controlling Claude Code quickly. You don't need to memorize every command — start with the ones you use most often.

Use slash commands to control settings, costs, and context. Use regular prompts for work.

Shortcuts speed up work, but their real purpose is keeping your flow uninterrupted. Once you're comfortable with defaults, only customize the ones you truly need.

By current standards, cost checking centers on /usage, and /cost is presented as an alias. Custom slash commands are understood in connection with skills rather than as independent features, which aligns with the current official documentation.

Next Section

Section 22. Prompt Engineering Fundamentals — The Art of Asking Good Questions

22. Automating Repetitive Tasks with Hooks

01Hooks are not "asking Claude" but "rules that must run"

You can tell Claude something like this:

Always run prettier after modifying a file.

But this is a prompt. Claude must remember and execute it within the conversation flow. If sessions get long or context gets compressed, it might slip.

Hooks are different. Claude automatically runs prettier after editing a file. It's not about Claude "remembering to execute"—rather, Claude Code always runs it at a defined event.

The core advantage of Hooks: deterministic control that guarantees certain actions always happen, rather than hoping the LLM chooses to execute them

02Difference between prompts and hooks

Executor

Prompt: Claude's judgment | Hook: Claude Code's event system

Execution guarantee

Prompt: not guaranteed | Hook: automatic when conditions match

Suitable tasks

Prompt: explanation, planning, review, judgment | Hook: formatting, checking, logging, blocking, notifications

Example

Prompt: "run tests too" | Hook: auto-run npm test after file edit

Risk

Prompt: can be forgotten | Hook: if poorly made, might run every time and interfere

The rule is simple.

One-time request → Prompt | Must always run → Hook | Requires situational judgment → Prompt + Hook or agent hook

Beginners can start by learning command hooks that work with shell commands.

03Key moments when hooks execute

Hooks attach to specific Claude Code events. Beginners need to know just these 6 first.

SessionStart

When session starts or resumes → reinject project context

UserPromptSubmit

When user submits a prompt → add current branch info

PreToolUse

Before tool execution → block dangerous commands

PostToolUse

After successful tool execution → formatting, linting, logging

Notification

When Claude sends a notification → awaiting input notification

Stop

When Claude is about to finish a response → verify test success

The official hook reference offers more events. For example, PostToolUseFailure, PostToolBatch, SubagentStart, SubagentStop, ConfigChange, CwdChanged, FileChanged, PreCompact, PostCompact, SessionEnd, and more. But for a beginner's guide, it's best to focus learning around PreToolUse and PostToolUse.

04Where to configure hooks

Hooks for a project usually go in .claude/settings.json at the project root.

my-project/
├── .claude/
│   ├── settings.json
│   └── hooks/
│       └── protect-files.sh
├── src/
└── package.json

Here's the basic configuration structure.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'file edited'"
          }
        ]
      }
    ]
  }
}

You can view currently registered hooks read-only with the /hooks command. Make edits in the settings JSON file.

05How to read hook configuration

Let's interpret the following configuration line by line.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

PostToolUse

After a tool executes successfully

matcher: Edit|Write

Only when Claude modifies or writes a file

type: command

Execute a shell command

command

The actual command to run

The matcher is a filter that narrows down which hooks execute. Bash matches only the Bash tool, Edit|Write matches only file-edit tools, and mcp__github__.* matches only GitHub MCP tools. MCP tool names follow the format mcp__<server>__<tool>.

06Beginner's first hook: auto-format after file edit

The easiest hook is "automatically run a formatter when Claude edits a file."

Add the following to .claude/settings.json.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

This hook extracts the modified file path after Claude edits it and passes it to prettier --write. Note that jq is required. On macOS, install with brew install jq; on Ubuntu/Debian, use apt-get install jq.

07A safer formatting hook

For beginners, it's better to split the command into a separate script file rather than write it too long.

First, create the file.

mkdir -p .claude/hooks
touch .claude/hooks/format-edited-file.sh
chmod +x .claude/hooks/format-edited-file.sh

.claude/hooks/format-edited-file.sh

#!/usr/bin/env bash
set -euo pipefail

input="$(cat)"
file_path="$(echo "$input" | jq -r '.tool_input.file_path // empty')"

if [ -z "$file_path" ]; then
  exit 0
fi

case "$file_path" in
  *.js|*.jsx|*.ts|*.tsx|*.json|*.md|*.css)
    npx prettier --write "$file_path"
    ;;
esac

Then link it in .claude/settings.json.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format-edited-file.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

To reliably reference hook scripts relative to the project, use ${CLAUDE_PROJECT_DIR}.

08Security hook: block sensitive file edits

Hooks aren't just for automation; they're also safety guards. For example, you can prevent Claude from modifying files like .env, .git, or package-lock.json.

.claude/hooks/protect-files.sh

#!/usr/bin/env bash
set -euo pipefail

input="$(cat)"
file_path="$(echo "$input" | jq -r '.tool_input.file_path // empty')"

if [ -z "$file_path" ]; then
  exit 0
fi

case "$file_path" in
  *.env|*.env.*|.env|.git/*|package-lock.json|pnpm-lock.yaml|yarn.lock|*.pem|*.key)
    echo "Blocked by project hook: protected file cannot be edited: $file_path" >&2
    exit 2
    ;;
esac

exit 0

Give it execute permission.

chmod +x .claude/hooks/protect-files.sh

Then link it in .claude/settings.json.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/protect-files.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

Here we use PreToolUse because we need to check before modification happens, not after.

09Exit codes matter

Command hooks signal results to Claude Code via exit code.

Success → continue

Block → prevent this action

Other

Non-blocking error → recorded as hook error but action may continue

However, not all events block the same way. Exit code 2 in PreToolUse can block because it happens before tool execution. PostToolUse, on the other hand, runs after the tool has already executed, so you can't revert it the same way.

Here's how beginners can remember it:

Want to block? → PreToolUse | Want to handle after? → PostToolUse | Want to check before Claude stops? → Stop | Want notifications? → Notification

10Lint hook: check after edits

Formatting can auto-fix, but linting or typechecking can take time. Start with lightweight checks.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --quiet"
          }
        ]
      }
    ]
  }
}

But this config can be slow because full lint runs every time you edit a file.

Small project

Can run full lint after edit

Medium project

Format only changed files; lint manually

Large project

Async hook or delegate to separate CI

Team project

Minimize hooks, use CI as final arbiter

11Async hooks: run long tasks in the background

By default, hooks block Claude's execution until they complete. Long-running tasks like tests or external API calls can slow down your workflow.

That's when you use async: true.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/run-tests-async.sh",
            "args": [],
            "async": true,
            "timeout": 300
          }
        ]
      }
    ]
  }
}

Async hooks don't block Claude and run in the background. However, since the work already happened by the time it completes, you can't use them to block tool calls or return permission decisions.

Must finish before next step → no async | Notifications, logging, background tests → async OK | Block dangerous commands → always sync PreToolUse

12Notification hook: alert when Claude is waiting

You can set up hooks to send notifications when Claude is waiting for permission or input.

macOS example:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'"
          }
        ]
      }
    ]
  }
}

Linux example:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

If you leave Notification hook's matcher empty, it reacts to all notification types. For specific cases, you can use matchers like permission_prompt, idle_prompt, or auth_success.

13Context enrichment hook: reinjection after compression

As sessions grow, conversations get summarized via /compact or automatic compaction. Important project rules can weaken in the process.

For example, you can reinjection important content after each compression.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

Adding a compact matcher to SessionStart hooks lets you reinject critical context after compression. However, static project rules are better kept in CLAUDE.md than in hooks.

14Hook input is JSON

Hook scripts receive JSON from Claude Code on stdin.

For example, a Bash pre-execution hook might receive input like this:

{
  "session_id": "abc123",
  "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
  "cwd": "/home/user/my-project",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

That's why shell scripts usually start like this:

input="$(cat)"
tool_name="$(echo "$input" | jq -r '.tool_name // empty')"
command="$(echo "$input" | jq -r '.tool_input.command // empty')"
file_path="$(echo "$input" | jq -r '.tool_input.file_path // empty')"

15Block dangerous Bash commands

Here's a hook that blocks dangerous commands like rm -rf.

.claude/hooks/block-dangerous-bash.sh

#!/usr/bin/env bash
set -euo pipefail

input="$(cat)"
command="$(echo "$input" | jq -r '.tool_input.command // empty')"

if echo "$command" | grep -Eq 'rm[[:space:]]+-rf|sudo|chmod[[:space:]]+777|curl .* | sh|wget .* | sh'; then
  echo "Blocked by hook: dangerous bash command: $command" >&2
  exit 2
fi

exit 0

Link it in .claude/settings.json as a PreToolUse.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-dangerous-bash.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

The official reference also shows a structured JSON approach where PreToolUse hooks inspect Bash commands and return permissionDecision: "deny". For beginners, the exit code 2 approach is easier to understand; you can graduate to JSON output later when finer control is needed.

16Hooks and permissions work together

Hooks don't replace the permission system. Permissions manage "which tools Claude can use," while hooks manage "what runs automatically or blocks in specific situations."

Block .env reading itself

permissions deny

Block .env edit attempts too

PreToolUse hook

Auto-run prettier after file edit

PostToolUse hook

Check Bash commands before execution

PreToolUse hook

Auto-handle approval requests

PermissionRequest hook

Enforce team-wide policy

managed settings + permissions + hooks

Even with hooks in place, permission settings remain important.

17When to use prompt hooks and agent hooks

Most beginners only need command hooks. But some automation is hard to judge with simple shell conditions.

For example, "Claude said the work is done, but did they really finish everything requested?" is hard to judge with just grep. That's when prompt or agent hooks come in handy.

command

Execute shell command → learn first

prompt

Quick LLM judgment → simple yes/no decision

agent

Subagent with tool access → when files need inspection

http

Call external URL → notifications, webhooks, internal APIs

mcp_tool

Call connected MCP tool → for teams already using MCP

Agent hooks are experimental; prioritize command hooks in production workflows.

18Risks of misconfiguration

Hooks are powerful but risky. Command hooks especially run shell commands with your account privileges. Review and test before adding to settings.

Run full test suite on every file edit

Session becomes very slow

Put rm, mv, chmod directly in hooks

Risk file damage

Don't quote variables

Fails with spaces and special characters in paths

Print .env contents to stdout

Sensitive data can end up in transcript

Try to block in PostToolUse

Already executed, hard to prevent

Mix JSON output with other echo statements

JSON parsing can fail

Use personal paths in team-shared settings

Fails on others' machines

Add too many hooks at once

Hard to trace root cause of issues

The official security guidelines emphasize input validation, shell variable quoting, path traversal protection, absolute paths, and avoiding sensitive files.

19How to debug hooks

If a hook isn't working, first check registration with /hooks.

/hooks

Then enable debug logging.

claude --debug-file /tmp/claude.log

In another terminal, watch the log.

tail -f /tmp/claude.log

Hook execution details, matched hooks, exit codes, stdout, and stderr all appear in the debug log. Here's the debugging checklist:

Check if hook shows up in /hooks
Verify matcher is correct
Confirm script has execute permission
Verify jq is installed
Run command directly in terminal
Check stdout/stderr with claude --debug-file

20Recommended hook combination for beginners

Don't build complex automation from the start. Add hooks in this order:

Stage 1: Notifications only

{
  "hooks": {
    "Notification": [
      { "matcher": "", "hooks": [{ "type": "command", "command": "echo 'Claude Code needs attention' >&2" }] }
    ]
  }
}

Stage 2: Format after file edit

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format-edited-file.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

Stage 3: Protect sensitive files

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/protect-files.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

Stage 4: Block dangerous Bash commands

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-dangerous-bash.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

These four cover most automation beginners need.

21Real-world workflow example

Scenario: You ask Claude to add a feature

Add email format validation and error message to the signup form.
Find related files first, explain your plan, then proceed.

Without hooks

After Claude edits files, you manually run formatting, linting, tests, and check diffs.

npx prettier --write src/...
npm run lint
npm test
git diff

With hooks

1Claude Edit/Write

2PostToolUse hook runs automatically

3prettier auto-formats

4If needed manually run lint/test

If Claude tries to edit a protected file, the hook blocks it.

1Claude Edit .env

2PreToolUse hook → protect-files.sh

3exit 2 → edit blocked

This is hooks' core power: automate routine work, block dangerous operations before they happen.

Section 22 · Wrap-up

What to remember from this section

Hooks are Claude Code's automation layer. Prompts ask Claude to "do this", while hooks set rules that "always execute on specific events".

Beginners should start with PostToolUse to auto-format after edits, then PreToolUse to block sensitive file changes and dangerous Bash commands.

1. Auto-fix with PostToolUse | 2. Block danger with PreToolUse | 3. Long-running tasks need careful async | 4. Sensitive data and destructive commands require special care even in hooks

Hooks can become your automation layer when used well, aligning Claude Code with team rules. But since shell commands run with your privileges, start small and safe. Use /hooks to verify registration and claude --debug-file to troubleshoot.

23. Connecting External Tools with MCP

01What is MCP

MCP stands for Model Context Protocol. It's a protocol that standardizes how AI models connect to external tools, data, and APIs.

Without MCP, using only basic features:

Claude Code basic features
→ Read project files
→ Modify code
→ Run Bash commands

With MCP connected:

Claude Code with MCP connected
→ Read GitHub PRs
→ Check Sentry errors
→ Query PostgreSQL schemas
→ Check Jira tickets
→ Reference Figma design info
→ Call internal APIs

02Three Components of MCP

MCP servers provide three main capabilities.

Resource

External materials Claude can read (e.g., GitHub issues, DB schemas, API docs)

Tool

External functions Claude can execute (e.g., PR lookup, DB queries, Sentry error search)

Prompt

Task templates callable like slash commands (e.g., /mcp__github__pr_review 456)

03Why MCP is Needed

Real development work doesn't end with just reading code. Without MCP, you repeatedly copy and paste external information.

Which Jira ticket started this feature?
What reviews are on the current PR?
What errors are actually happening most in production?
What does this table schema look like?
Does the Figma design match the current implementation?

With MCP connected, Claude can fetch this information directly and integrate it into your workflow.

04Working Without MCP vs With MCP

Without MCP

1. User goes to Sentry.
2. Copies the error message.
3. Pastes it into Claude Code.
4. Claude infers the cause.
5. User goes back to Sentry to find more info.
6. Pastes again.

With MCP Connected

1. Ask Claude: "Check auth service errors from the last 24 hours"
2. Claude uses the Sentry MCP tool
3. Analyzes errors, stack traces, and deployment info together
4. Proposes a code fix plan

MCP transforms Claude Code from a "code editing tool" into a "task agent connected to a development tool chain."

05When Should You Use MCP

Beginners shouldn't think of MCP as "every cool external connection." Connect only when needed.

Info you check once

MCP not needed

Info you repeatedly copy and paste

MCP candidate

Frequently work with GitHub PRs and issues

GitHub MCP useful

Frequently analyze production errors

Sentry MCP useful

Frequently check DB schemas and data

DB MCP useful

Practical rule: If you repeatedly copy and paste external info, consider MCP

06MCP Connection Strategy

Beginners should start with read-only MCP servers.

Connections like "GitHub PR lookup, Sentry error lookup, DB schema lookup" that help just by reading are ideal.

Connection decision criteria:

You repeatedly copy and paste external info → Consider MCP
Claude querying directly saves work time → Consider MCP
Read-only permission is sufficient → Good time to start MCP
Write permission needed → Design permissions carefully before connecting

07What is an MCP Server

To connect external tools with MCP, you need an MCP server. Here, "server" doesn't necessarily mean a cloud server.

Claude Code
   ↓
MCP server
   ↓
GitHub / Sentry / DB / Jira / Internal APIs

The MCP server tells Claude Code "here's the list of tools I can provide." Claude sees the user's request and chooses the appropriate tool to call.

08Connection Methods: HTTP, stdio, SSE, WebSocket

Claude Code has several MCP server connection methods. Beginners only need to understand HTTP and stdio first.

HTTP

Connect to remote MCP server via URL (most common for cloud services)

stdio

Connect by running a local command (good for local tools, DB CLIs, custom servers)

SSE

Legacy remote connection method (prefer HTTP)

WebSocket

Bidirectional persistent connection (for when server needs to push events first)

Official docs recommend HTTP for remote MCP server connections.

09Most Basic MCP Connection Command

This is the basic format for adding a remote HTTP MCP server.

claude mcp add --transport http <name> <url>

Real example:

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

After connecting, verify status inside Claude Code.

/mcp

10MCP Management Commands

MCP servers are managed with terminal commands and the /mcp command inside Claude Code.

claude mcp list

View configured MCP servers

claude mcp get <name>

View server details

claude mcp remove <name>

Remove server

claude mcp reset-project-choices

Reset project-scoped server approval choices

/mcp

Check server status and authentication inside Claude Code

11Scope: local, project, user

When adding an MCP server, you decide "where it applies."

local

Only me in this project (~/.claude.json, not shared)

project

Entire team in this project (.mcp.json, can be shared)

user

All my projects (~/.claude.json, not shared)

Beginner guide:

First test → local
Whole team needs it → project
Personal tool for all projects → user
Contains API keys or personal tokens → Don't put directly in project scope

12Project Scope Example

If the whole team needs to use the same MCP server, use project scope.

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

This creates or updates .mcp.json at project root.

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

Approval is required before using a project-scoped server.

13Separating Sensitive Info with Environment Variables

Never put API keys or tokens directly in .mcp.json. Use environment variables instead.

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${INTERNAL_API_KEY}"
      }
    }
  }
}

This way, .mcp.json shares only the structure, and each person adds their own token via environment variables.

export INTERNAL_API_KEY="your-token"

14GitHub MCP Connection Example

Connecting GitHub MCP lets you handle PRs, issues, and review workflows inside Claude Code.

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

After connecting, you can request:

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

It's better not to give write permissions from the start. Start with read-only or minimal-permission tokens.

15Sentry MCP Connection Example

Sentry MCP is useful for analyzing production errors.

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

Authenticate inside Claude Code.

/mcp

Then make requests like:

What are the most common errors in the last 24 hours?
Show me the stack trace for error ID abc123.
Which deployment introduced these new errors?

16PostgreSQL MCP Connection Example

Databases are powerful but risky. Beginners must use read-only accounts.

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:[email protected]:5432/analytics"

After connecting, you can make requests like:

Show me the schema for the orders table.
Find customers who haven't made a purchase in 90 days.
What's our total revenue this month?

17Safety Principles for DB Connection

Always apply these principles to production databases.

Use read-only accounts
Minimize direct production DB connections
No queries without LIMIT
Restrict access to personal data columns
Don't connect write permissions at beginner stage

18OAuth Authentication is Handled in /mcp

Some remote MCP servers require OAuth authentication. After adding the server, run /mcp inside Claude Code to complete the browser authentication flow.

/mcp

Beginners should remember:

Need auth after adding server → /mcp
Browser opens → Log in
Claude Code manages the token
If stuck, check status with claude mcp get <name>

19Reference MCP Resources with @ Symbol

MCP servers provide resources that Claude can read. You can reference them like files with @.

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

When you type @, connected MCP server resources may appear in autocomplete alongside files.

20Use MCP Prompts Like Slash Commands

If an MCP server provides prompts, you can use them like slash commands in Claude Code.

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug in login flow" high

Regular slash commands are Claude Code's own, while MCP prompt commands are provided by connected external servers.

21MCP Output Limits and Context Management

Since MCP fetches external data, output can grow large. Default max output is 25,000 tokens.

export MAX_MCP_OUTPUT_TOKENS=50000
claude

But beginners shouldn't raise limits blindly.

Good request: Show me the top 5 errors in the auth service from the last 24 hours.

Bad request: Get me all Sentry logs.

Good request: Show me the columns and indexes of the orders table.

Bad request: Get me the entire database schema.

22Why MCP Tool Search Matters

When you connect many MCP servers, Claude has many tools to learn about. Claude Code uses Tool Search to manage this.

Tool Search loads only tool names at session start, then fetches relevant tool definitions when Claude actually needs them. It's enabled by default.

export ENABLE_TOOL_SEARCH=auto:5 claude

Or disable it completely:

export ENABLE_TOOL_SEARCH=false claude

23Always Preload Tools from Specific Servers

If you need a specific server's tools to always be preloaded, you can use alwaysLoad.

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

alwaysLoad: true loads all that server's tools at session start. Use it only for a small set of frequently-needed tools.

24Excessive Connections Beginners Should Avoid

MCP isn't a "more connected = better" feature. Wrong connections create cost, security, and confusion issues.

Connect GitHub, Jira, Sentry, DB, Slack, Figma all at once

Claude may confuse tool choices

Connect production DB with write permission

Risk of data corruption

Store personal tokens directly in .mcp.json

May leak to team repository

Install unverified MCP servers

Risk of prompt injection and data leaks

Beginner principle: Connect one at a time, start read-only.

25Differences Between MCP, Hooks, Skills, and Subagents

Part 6 features have different roles.

Slash command

User runs command quickly (/context, /model)

Hooks

Auto-run on specific events (prettier after file edit)

MCP

Connect external tools (GitHub, Sentry, DB)

Skills

Provide project-specific expertise (how to use company API)

Subagents

Split large tasks (security review agent, test agent)

26Real Workflow: Analyzing Sentry Errors

Step 1: Connect Sentry MCP

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

Step 2: Verify Authentication

/mcp

Step 3: Request Error Lookup

Check the top 5 errors in the auth service from the last 24 hours.

Step 4: Connect to Code

Find which files these errors relate to and propose a fix plan.

Step 5: Safe Review

/diff
/code-review high

27Real Workflow: Reviewing GitHub PRs

Step 1: Connect GitHub MCP

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer ${GITHUB_TOKEN}"

Step 2: Check Status

/mcp

Step 3: Request PR Review

Read PR #456 and review from bugs, security, testing, and maintainability perspectives.

Step 4: Fix Plan

Prioritize only the items that actually need fixing.

28Real Workflow: DB Schema-Based Implementation

Step 1: Connect Read-Only DB

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "${DATABASE_READONLY_URL}"

Step 2: Query Schemas

Based on @postgres:schema://users and @postgres:schema://orders,
suggest the API response structure needed for the order history screen.

Step 3: Implementation Plan

Find related files in the current codebase and create a fix plan.

Step 4: Safe Implementation

/plan implement order history API based on current DB schema

29MCP Troubleshooting Checklist

If MCP isn't working, check in this order:

Server not in list

claude mcp list

Need server details

claude mcp get <name>

Check status in Claude Code

/mcp

Need authentication

Complete OAuth in /mcp

Environment variable error

Verify ${VAR} is actually set

Output truncated

Adjust MAX_MCP_OUTPUT_TOKENS or narrow request scope

30Beginner MCP Adoption Order

Don't connect many MCPs from the start. Add them in this order:

Learn /mcp and claude mcp list
Connect either Sentry or GitHub, read-only focus only
Separate tokens into environment variables
Understand the difference between project and local scope
Always connect DB with read-only
Use .mcp.json only when team sharing is needed
If output grows, narrow request scope and check /context

The safest first practice is to start "read-only focused" like Sentry or GitHub.

Section 23 · Wrap-up

What to Remember from This Unit

MCP is a standard protocol that connects Claude Code to external tools. Connecting tools like GitHub, Sentry, PostgreSQL, Jira, Figma, and internal APIs means Claude doesn't just see code—it can also consider the context of your actual development environment.

Beginners should remember this one principle:

You repeatedly copy and paste external info → MCP connection candidate

MCP is powerful, but more connections aren't always better. The best approach is to start by connecting one safe server read-only to build a small success experience, then add only tools that match your team's workflow.

Next Section

Section 24. Managing Large Projects: Running Multiple Agents Simultaneously

24. Breaking down large tasks with Subagents

Section 24 · Definition

What is a Subagent

Subagents are a feature in Claude Code that breaks down large tasks into smaller, specialized subtasks. If the previous section's MCP was a bridge to connect external tools, subagents are a way to delegate work to a separate Claude instance.

By official documentation, a subagent is a specialized AI assistant that handles specific types of work. Each subagent runs in its own context window, can have custom system prompts, specific tool access permissions, and independent permission settings.

When Claude determines a task matches a subagent's description, it delegates. The subagent works independently and returns only a summary to the main conversation.

01Helper workers that divide the workload

As you use Claude Code longer, too much information accumulates in a single session. For example, here's asking everything at once.

Read the authentication code,
read the DB model,
read the API routes,
run the tests,
analyze the error logs,
make a fix plan,
and finally change the code.

When you do this, the context in the main conversation grows quickly. All the files you read, search results, test logs, and intermediate decisions pile up in the same chat window.

02Dividing with Subagents

With subagents, you can split like this.

Main conversation:
- Manage the overall goal.
- Make final decisions.
- Judge whether to approve changes.

Subagent 1: Find authentication-related files only.
Subagent 2: Analyze DB models only.
Subagent 3: Analyze API routes only.

Main conversation: Combine summaries from the three subagents.

Subagents start with a clean context, work with designated tools and models, and return only results to the main conversation, preventing context overflow.

03Why separate exploration from decision-making

Beginners typically ask Claude to read all files and fix them immediately. But in real development, it's safer to separate exploration from decision-making.

Exploration

Finding related files, reading error logs, collecting failure causes, searching for similar patterns

Decision

Selecting files to change, determining approach, limiting fix scope, deciding test strategy

Exploration consumes lots of context by reading many files and logs. Decision-making, meanwhile, only needs key summaries. Subagents are ideal for separating the two.

04When to use subagents ①

Not every task needs subagents. The criterion is: Does bulk information appear that has no value in the main conversation?

Explaining one file

Low — can be handled directly in the main conversation

Small bug fix

Low — many round trips and fast fixes are important

Analyzing hundreds of lines of test logs

High — no need to put all logs in the main context

Understanding a large codebase structure

High — better to receive just the exploration summary

05When to use subagents ②

Security review

High — enables focused review from a separate perspective

Parallel DB·API·UI analysis

High — can explore independent domains in parallel

Short questions on content already in conversation

Low — subagent startup cost is unnecessary

Repeated specialized review needed

High — can be reused via custom subagent

The main conversation suits frequent back-and-forth, iterative refinement, and quick small changes. Subagents suit tasks where detailed output isn't needed in the main context, tools must be restricted, or work can finish independently and return a summary.

06Built-in subagent types

Claude Code comes with built-in subagents you can use. Beginners just need to understand these three.

Explore

Fast read-only exploration — finding related files, understanding structure, searching patterns

Plan

Read-only investigation for planning — codebase investigation before implementation

General-purpose

Can both explore and modify — complex multi-step work

Explore is a fast read-only agent optimized for codebase search and analysis. Plan is for context collection during plan mode. General-purpose is for work that needs both exploration and modification, or multiple dependent steps.

07Easiest approach: delegate in natural language

You don't need to create custom subagents at first. Just tell the prompt explicitly to use a subagent.

Use an explore agent to find all authentication-related files.
Do not modify anything. Return only the important files and why they matter.

You can also be more explicit about which subagent to use.

Use the Explore subagent to find authentication-related files.
Don't modify them—just summarize each important file and its role.

When automatic delegation isn't enough, you can specify a name in natural language, use @ mention to guarantee a specific subagent runs, or use the --agent flag to run the entire session with a specific agent.

08Calling specific subagents with @ mention

If you want to use a specific subagent, use @ mention.

@"code-reviewer (agent)" look at the auth changes.

Or, typed out in full:

@agent-code-reviewer Review the recent auth changes.

@ mention fixes which subagent to run. But the specific task prompt delivered to the subagent is still written by Claude based on your current request.

09Foreground and background execution

Foreground

Main conversation waits until the subagent finishes — short, important analysis

Background

Runs in the background, user continues working — long-running reviews·tests·investigations

Foreground subagents block the main conversation until completion and forward permission prompts to the user. Background subagents run in parallel, work with already-granted permissions, and auto-deny tools they don't have. Running tasks can be sent to background with Ctrl+B.

Run a thorough security review in the background while I continue working on the frontend.

10Example: parallel exploration

The biggest advantage of subagents is being able to divide independent exploration into parallel work.

Investigate the following three domains in separate subagents in parallel.

1. Authentication flow
2. Payment model
3. API routes

Each subagent should not modify files,
and return only a summary of related files, core flow, and risky areas.
Finally, combine the three results and propose a fix plan.

Independent investigation works best when multiple subagents investigate in parallel and Claude combines the results. It works best when research paths don't depend on each other. For beginners, it's safer to include the condition don't modify.

11Subagent chains: delegating in sequence

Not all work suits parallel execution. Some tasks have the previous step's output become the next step's input.

1. Use the code-analyzer subagent to find performance issues.
2. Based on that result, have the optimizer subagent create a fix plan.
3. Before fixing, get my approval.

In multi-step workflows, use subagents sequentially so Claude receives the first result and passes it as context to the next subagent. For beginners, remember the chain like this.

Explore → Plan → Implement

12Cost and context savings

Subagents can save context, but cost doesn't automatically decrease. Each subagent also uses a model and consumes tokens. Subagents help in these cases.

When bulk exploration results don't need to stay entirely in the main conversation
When there are many files and only a summary is needed
When multiple perspectives need independent investigation
When you want to use a cheaper model for exploration and a better model for final decision

A subagent's model field can use sonnet, opus, haiku, a full model ID, or inherit. If not specified, the default is inherit.

13When to create custom subagents

If you repeatedly delegate the same role, it's good to create a custom subagent.

Every time you say "look at it from a security perspective"
Every time you say "find the cause of test failures"
Every time you say "check DB query performance"
Every time you say "review only the changed code"

Custom subagents are Markdown files with YAML frontmatter, created via the /agents command or by adding files directly. The /agents interface provides view, create, edit, delete, and duplicate-check functionality.

14Subagent storage location

.claude/agents/

Current project — project-specific agents to share with your team

~/.claude/agents/

Across all my projects — agents you use frequently personally

--agents CLI flag

Current session only — testing, automation scripts

plugin agents/

Provided by plugins — agents installed via plugins

managed settings

Organization-wide — deployed by company policy

If the same name exists in multiple scopes, the location with higher priority applies. Project subagents are suitable for sharing with your team via version control.

15Grant tool permissions minimally

The most important safeguard when creating a subagent is tool restriction. This way you can read and search files but can't modify them.

tools: Read, Grep, Glob

If you allow Bash, you can run tests or git diff. But Bash is powerful, so only add it when needed.

tools: Read, Grep, Glob, Bash

You can also remove just write tools from inherited tools.

disallowedTools: Write, Edit

Subagents inherit tools from the main conversation by default, but you can restrict them using tools as an allowlist or disallowedTools as a denylist. If both are used, disallowedTools applies first, then tools resolves from the remaining pool.

16Example: security reviewer subagent

It's safer to keep a security reviewer read-focused. Create file .claude/agents/security-reviewer.md like this.

---
name: security-reviewer
description: Expert security reviewer. Use proactively after changes to auth, data handling, payments, or API boundaries.
tools: Read, Grep, Glob, Bash
model: inherit
permissionMode: plan
---

You are a senior security engineer. Review only. Do not edit files.
Check for: hardcoded secrets, missing authorization, SQL injection, unsafe file handling, overbroad permissions.
Output: Severity / File / Risk / Evidence / Recommended fix.

This agent finds security issues but doesn't modify files. For beginners, it's safer to separate finding from fixing.

17Example: test runner subagent

Test logs consume lots of context. So running tests and summarizing failures is ideal to delegate to a subagent. Create .claude/agents/test-runner.md.

---
name: test-runner
description: Runs project tests and summarizes only failing tests and likely root causes.
tools: Read, Grep, Glob, Bash
permissionMode: default
maxTurns: 8
---

Identify the test command, run the smallest relevant test first.
If tests fail, summarize only: test name, exact error, likely cause, related files.
Avoid pasting huge logs. Keep output concise.

This way, long logs don't enter the main conversation entirely, and only failure summaries return.

18Example: DB analyst subagent

If you connected a DB via MCP in section 23, you can create a separate DB subagent. Here's .claude/agents/db-analyst.md.

---
name: db-analyst
description: Analyzes database schema, query patterns, and migration risks.
tools: Read, Grep, Glob
mcpServers:
  - postgres
model: inherit
permissionMode: plan
---

Inspect schema via MCP. Identify mismatch, missing indexes, unsafe migrations.
Never modify data. Never run destructive SQL.

The mcpServers field limits which MCP servers the subagent can use. This is useful when you want to hide MCP tool descriptions from the main conversation and only give tools to a specific subagent.

19Subagents used with Skills

As covered in detail in section 25, subagents can be used with skills.

---
name: api-developer
description: Implements API endpoints following team conventions.
tools: Read, Edit, Grep, Glob, Bash
skills:
  - api-conventions
  - error-handling-patterns
model: inherit
---

The skills field injects specific skill content into the subagent's context at startup. Rather than expecting it to find and load during execution, this way injects needed domain knowledge from the start. If you haven't created skills yet, beginners can leave this field empty.

20Subagent management commands

Subagents are managed with /agents. The Running tab shows currently-running subagents and lets you open or stop them. The Library tab shows built-in, user, project, and plugin subagents and lets you view, create, edit, delete, and check for duplicates.

/agents

Open subagent management UI

/agents create

Create a new subagent

/agents edit

Edit an existing subagent

/agents delete

Delete a subagent

claude agents

Check agent list in the terminal

21Defining temporary subagents from CLI

For quick tests or automation, you can define a subagent at session start via the --agents flag without creating a file.

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on quality and security.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

--agents accepts JSON with the same frontmatter fields as file-based subagents. Subagents defined this way exist only for that session and are not saved to disk. For beginners, file-based definitions are easier to understand.

22Difference between subagents and other methods

Main REPL

Quick questions·iterative fixes — same conversation context

Subagent

Isolate and delegate specific work — separate worker in a single session

Background agent

Long-running independent work — separate execution while user continues

Agent team

Multi-session collaboration — coordinated via messages and task lists

Dynamic workflow

Orchestration at dozens~hundreds of agents

Beginners can remember it this way. Small work uses Main REPL, isolated exploration uses Subagents, long-running work uses Background, multi-worker collaboration uses Agent teams, and large-scale repetition uses Workflow.

23Beginner delegation prompts ①

When delegating to a subagent, narrow the scope. Here's file exploration.

Use an Explore subagent to find files related to payment functionality.
- Do not modify files
- Extract only highly relevant files
- Explain each file's role in one line
- Separate uncertain files as "uncertain"

Here's bug cause investigation.

Use a subagent to investigate the cause of this test failure.
- Do not paste the entire test log
- Summarize only: test name, error, related files, cause candidates
- Do not make fixes

24Beginner delegation prompts ②

Here's how to use parallel exploration and code review.

Use three subagents in parallel for investigation.
1. Authentication code  2. DB model  3. API routes
Each: related files / core flow / risky areas / next steps to check only.
Finally combine and propose only a fix plan.

Use the code-reviewer subagent to review recent changes.
- Prioritize changed files by git diff
- Categorize as Critical / Warning / Suggestion
- Focus on actual bugs·security·missing tests, don't modify files

25What to check when receiving subagent results

Don't trust subagent results directly and fix immediately. You must review again in the main conversation.

Scope

Did it investigate only the requested scope

Evidence

Are file paths and specific evidence included

Uncertainty

Did it distinguish speculation from confirmed fact

Duplication·Gaps

Does it overlap with other results, or miss important areas

Implementation readiness

Is the plan concrete enough to implement immediately

26Common mistakes with subagents

Delegating all work to subagents

Slows down and increases cost → use only for large exploration·review

Granting write permissions too broadly

Risk of unwanted changes → start read-only

Vague description

Won't auto-delegate → clarify when to use it

Output format not specified

Summary is long and scattered → specify output format

Parallel work that's interdependent

Result conflicts·duplication → parallelize only independent domains

Returning entire logs

Main context bloats again → specify "return summary only"

When multiple subagents return detailed results, their results can again consume lots of main conversation context. It's important to request short, structured summaries.

27Real-world workflow: large bug investigation

The situation: login redirect sometimes fails. Bad request is too broad.

Fix the login redirect bug.

Good request splits exploration into parallel work and stops at fixing.

Investigate login redirect failures that happen intermittently.
Use three subagents in parallel:
1. Authentication flow  2. Routing/redirect  3. Session/cookie handling
Each: don't modify files, return related files·core flow·cause candidates.
After receiving results, propose only a fix plan in the main conversation.

28Real-world workflow: preparing large refactoring

Before refactoring the auth module into a new structure, use subagents to explore the separation.

I want to prepare for auth module refactoring. Use subagents to explore separation.
1. Current auth entry points and major flows
2. Token issue/verify/refresh logic
3. Permission checks and route protection approach
4. Related test structure
Each: return summaries only, no fixes. Finally propose risk level and step-by-step plan.

Later, connecting to Plan Mode lets subagents handle exploration while Plan Mode reviews the actual refactor plan.

/plan refactor auth module based on the subagent findings

29Real-world workflow: separating review from fix

A review subagent only finds, then the main Claude fixes only approved items — this is safer.

Use code-reviewer subagent to review recent changes.
Don't modify files, review strictly by git diff.

When review results arrive, decide in the main conversation.

Convert only Critical items to actual fix plans.
Exclude Warning and Suggestion from this PR scope.

Fix only the 2 Critical items in minimal scope and explain by /diff.

Section 24 · Summary

What to remember from this section

Subagents are a feature to break down large work into separate specialized workers. The biggest advantage is separating work that consumes lots of context like exploration and log analysis from the main conversation, and using only the summary for final decision.

Beginners just need to remember this principle. Use Explore for finding related files, Plan for pre-implementation investigation, test-runner for analyzing long logs, read-only custom subagents for security·review, parallel subagents for independent domains, chains when one step inputs the next, and get main conversation approval before actual fix.

Quick fixes in main conversation, only large exploration·bulk logs·specialized review·parallel analysis via subagent.

Next section

Section 25. When to use Skills and Plugins

25. When should you use Skills and Plugins

01Understanding Skills and Plugins in one sentence

First, let's distinguish their roles simply.

Skill = A unit that teaches Claude domain-specific knowledge or procedures
Plugin = A package that bundles and deploys skills, agents, hooks, MCP, etc.

In other words, skill is closer to "knowledge and procedure," and plugin is closer to "deployment unit."

Skill

Knowledge and procedures that Claude invokes when needed

API writing rules, deployment procedures, code review checklists

Examples

Plugin

An installable package bundling multiple extension features

GitHub plugin, Sentry plugin, internal team development plugin

Examples

According to the official documentation, in Claude Code's Extension Layer, MCP connects external services, hooks provide automation, skills provide domain expertise, and plugins package all of these into deployable form.

02When do you use Skill

Skill is a file separation of "task knowledge" that you repeatedly communicate to Claude.

For example, if you keep saying things like this, it's a skill candidate.

Our API always validates input values with Zod,
error responses use the { code, message } format,
and don't put business logic in controllers—put it in the service layer.

Writing this to every prompt is tedious, and putting too much in CLAUDE.md consumes context in every session. With a Skill, Claude loads it only for relevant tasks.

The official documentation also explains that skill content is only loaded when used, so long reference materials cost almost nothing until actually needed.

03Cases where you should create a Skill

Copying the same instructions repeatedly

High · Can reduce repeated prompts

There are team API rules

High · Claude can automatically reference when implementing

Deployment procedure has multiple steps

High · Reusable with commands like /deploy

There is a code review checklist

High · Keep review criteria consistent

There is a lot of domain-specific knowledge

High · Can be loaded only when needed

A prompt you'll only use once

Low · Just input in conversation

Simple one-line command

Low · A slash command or regular prompt is enough

Requires investigation in separate context

Low · Subagent is more suitable

The official documentation also recommends creating a skill if domain expertise should be automatically activated, multiple team members need the same knowledge, or you're repeatedly explaining the same patterns and rules. Conversely, if you want to control explicit invocation, use slash commands; if separate context is needed, use subagents; if it's one-time use, just input it directly.

04The difference between CLAUDE.md and Skill

CLAUDE.md is a file that tells Claude the basic rules of a project. Skill is a file that loads domain-specific procedures or knowledge only when needed for specific tasks.

Role

CLAUDE.md = project basic rules / Skill = specific task knowledge and procedures

Load timing

CLAUDE.md = default reference at session start / Skill = when related task or directly invoked

Suitable content

CLAUDE.md = build commands, test commands, coding rules summary / Skill = deployment procedures, review checklists, API writing

Length

CLAUDE.md = keep short / Skill = can expand with supporting files

Invocation method

CLAUDE.md = automatic reference / Skill = automatic or direct /skill-name invocation

The criterion is simple.

Always need to know short rules → CLAUDE.md
Procedures needed only in specific situations → Skill

05Examples suitable for CLAUDE.md

The following is suitable for CLAUDE.md.

## Project commands

- Test: npm test
- Lint: npm run lint
- Build: npm run build

## Rules

- Do not edit .env files.
- Use TypeScript strict mode.

On the other hand, the following is suitable for skill.

## How to add a new API endpoint

1. Create route file.
2. Add request validation.
3. Add service method.
4. Add test cases.
5. Update OpenAPI docs.

06The difference between Skill and slash command

According to the official documentation, custom commands have been integrated into skills. Both .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md create /deploy, and existing .claude/commands/ files continue to work. For new creation, the skill approach offers better extensibility.

For beginners, you can distinguish like this.

I want to invoke directly like /deploy myself

Skill with direct invocation

I want Claude to apply automatically based on context

Skill with automatic invocation

I only need a very simple command template

Slash command style skill

I want to bundle long reference docs and example files

Skill directory

In other words, in the current workflow, "creating a custom slash command" should be understood as "creating a skill and invoking it with /skill-name."

07Creating your first Skill

Let's create a "summarize changes skill" as an example.

mkdir -p .claude/skills/summarize-changes

.claude/skills/summarize-changes/SKILL.md

---
description: Summarizes uncommitted git changes and flags risky parts. Use when the user asks what changed, wants a commit summary, or asks to review the current diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes in 2-3 bullet points.

Then list risks, if any:
- missing tests
- hardcoded values
- error handling gaps
- security-sensitive changes
- files that should be reviewed manually

If there are no uncommitted changes, say so clearly.

There are two ways to use it.

What did I change?

Or invoke it directly.

/summarize-changes

The official documentation's first skill example also explains that SKILL.md consists of YAML frontmatter and Markdown instructions, the directory name becomes the command the user types, and description is the criterion Claude uses to decide whether to auto-load the skill.

08Skill file structure

The simplest skill needs only one SKILL.md file.

.claude/
└── skills/
    └── api-conventions/
        └── SKILL.md

When it grows a bit, add supporting files.

.claude/
└── skills/
    └── api-conventions/
        ├── SKILL.md
        ├── reference.md
        ├── examples.md
        └── checklists/
            └── endpoint-review.md

According to the official documentation, a skill can include multiple files, SKILL.md should contain only core overview and navigation, and long API docs or examples should be in separate files. The official documentation recommends keeping SKILL.md under 500 lines and moving detailed materials to supporting files.

09Skill storage location

The scope of a skill's application varies depending on where it's stored.

.claude/skills/<name>/SKILL.md

Current project · project-specific rules

~/.claude/skills/<name>/SKILL.md

All my projects · personal work habits

skills/ inside plugin

Where plugin is active · team or organization deployment

enterprise managed settings

Organization-wide · company policy

According to the official documentation, project skills apply only to the current project, and personal skills apply to all projects. If names collide, priority is applied in order: enterprise, personal, project. Plugin skills use plugin-name:skill-name namespace to avoid conflicts.

For beginners, the guideline is as follows.

My personal habits → ~/.claude/skills/
Current project rules → .claude/skills/
Feature bundle to deploy to team → plugin

10Understanding Skill frontmatter

The area at the top of a Skill between --- is called frontmatter.

---
name: api-conventions
description: API design patterns for this codebase. Use when creating or modifying API endpoints.
disable-model-invocation: false
allowed-tools: Read Grep
---

Skill instructions here.

The most important field is description. It's the criterion Claude uses to decide when to use this skill.

name

Display name · optional

description

Skill purpose and invocation timing · must write specifically

disable-model-invocation

Prevent Claude auto-invocation · use for direct-call-only skills

allowed-tools

Pre-allow tools in skill · minimize initially

disallowed-tools

Disallow tools in skill · use to block risky tools

context

inline or fork execution · advanced use

argument-hint

Invocation argument guidance · useful for skills like /deploy staging

The official documentation explains that all frontmatter fields are optional, but recommends description so Claude knows when to apply the skill. Also, description and when_to_use text are truncated to a certain length in listing to reduce context usage.

11Auto-invocation and direct invocation

A skill can be executed in two ways.

Auto-invocation:
Claude reads the conversation and auto-loads related skills.

Direct invocation:
User directly executes with /skill-name.

For example, an API rules skill works well with auto-invocation.

---
description: API design conventions for this codebase. Use when creating or modifying API routes, request validation, response formats, or service-layer code.
---

On the other hand, a deployment skill is safer for direct invocation only.

---
description: Deploy the application to production.
disable-model-invocation: true
---

The official documentation also explains that specific actions like deployment, commits, and code generation are appropriate for direct /skill-name invocation, and you can use disable-model-invocation: true to prevent Claude from auto-executing.

12Dynamic context injection

You can inject shell command results into a skill.

## Current branch

!`git branch --show-current`

## Current diff

!`git diff HEAD`

This way, when Claude views the skill, the command output is already included.

For example, a commit summary skill can be created like this.

---
description: Creates a commit summary from the current git diff. Use when the user asks for a commit message or change summary.
---

## Current branch

!`git branch --show-current`

## Current diff

!`git diff HEAD`

## Instructions

Create a concise commit summary.

Use this format:
- Type:
- Scope:
- Summary:
- Risk:
- Tests needed:

The official documentation also explains that with dynamic context injection in the form of !`git diff HEAD`, Claude Code executes the command, inserts the output into the skill content, and passes it to Claude.

One caution is sensitive data. Don't include commands that output env, secrets, tokens, or production data in skills.

13Project-specific expertise Skill example ① · API conventions

.claude/skills/api-conventions/SKILL.md

---
description: API design and implementation conventions for this codebase. Use when creating or modifying API endpoints, validation, service methods, or response formats.
---

# API conventions

When creating or modifying API endpoints:

1. Validate all request input before using it.
2. Keep business logic in the service layer.
3. Return errors in this format:
   - code
   - message
   - details, only when safe
4. Do not leak internal exception messages to API clients.
5. Add or update tests for success and failure cases.

## File patterns

- Routes: src/routes/**
- Services: src/services/**
- Validation schemas: src/schemas/**
- Tests: tests/api/**

## Output expectation

When you propose an API change, include:
- files to edit
- validation changes
- service changes
- tests to add
- security risks

14Project-specific expertise Skill example ② · Review checklist

.claude/skills/review-checklist/SKILL.md

---
description: Project-specific code review checklist. Use when reviewing diffs, pull requests, or completed feature changes.
---

# Review checklist

Review changes for:

## Correctness
- edge cases
- null or undefined handling
- async error handling
- regression risks

## Security
- missing authorization
- unsafe input usage
- hardcoded secrets
- sensitive data exposure

## Tests
- success path
- failure path
- boundary cases
- integration impact

## Maintainability
- duplicated logic
- unclear naming
- excessive file scope
- inconsistent patterns

Return findings by severity:
- Critical
- Warning
- Suggestion

15Project-specific expertise Skill example ③ · Deployment procedure

.claude/skills/deploy-checklist/SKILL.md

---
description: Deployment checklist for this project. Use only when the user explicitly asks to prepare or review a deployment.
disable-model-invocation: true
---

# Deployment checklist

Before deployment:

1. Confirm target environment.
2. Run tests.
3. Run lint.
4. Run build.
5. Check migration status.
6. Review environment variables.
7. Summarize rollback plan.

Do not run deployment commands unless the user explicitly approves.

For risky operations like deployment, it's good to prevent auto-invocation and maintain an explicit approval flow.

16Good way to use supporting files

When a skill gets long, don't put everything in SKILL.md—split into supporting files.

.claude/skills/security-review/
├── SKILL.md
├── SECURITY_PATTERNS.md
├── AUTH_CHECKLIST.md
└── EXAMPLES.md

SKILL.md

---
description: Security review guidance for authentication, authorization, data handling, and API boundary changes.
---

# Security review skill

Use this skill when reviewing security-sensitive changes.

For detailed vulnerability patterns, see [SECURITY_PATTERNS.md](SECURITY_PATTERNS.md).
For authentication and authorization review steps, see [AUTH_CHECKLIST.md](AUTH_CHECKLIST.md).
For examples of good and bad findings, see [EXAMPLES.md](EXAMPLES.md).

Return only actionable findings with file paths and severity.

This way, Claude doesn't read all the long documents from the start but can reference related files only when needed.

17Using Skill and Subagent together

Skill is knowledge, and subagent is a worker. Using them together is powerful.

For example, you can pre-load the security-review skill in the security-reviewer subagent created in unit 24.

.claude/agents/security-reviewer.md

---
name: security-reviewer
description: Reviews authentication, authorization, API, and data-handling changes for security issues.
tools: Read, Grep, Glob, Bash
skills:
  - security-review
permissionMode: plan
---

You are a senior security reviewer.

Use the loaded security-review skill as your checklist.
Do not edit files.
Return only actionable findings.

The official subagent documentation explains that you can inject specific skills into a subagent context at startup through the skills field in the subagent frontmatter. The latest version also clarifies that subagents inherit the entire skill graph available in the parent session.

18When do you use Plugin

A plugin bundles skills, agents, hooks, MCP servers, etc. into one installable package.

According to the official documentation, plugins extend Claude Code with skills, agents, hooks, MCP servers and allow sharing between projects and teams. It's recommended to start with .claude/ standalone configuration for quick experiments or personal setup, and transition to plugins when team sharing or version management is needed.

One skill to use only in my personal project

Low · .claude/skills/ is enough

One team uses the same rules across multiple projects

High · easy install and update

Deploy skills + agents + hooks together

High · can bundle into one package

Share internal MCP server configuration

High · standardize team-wide tool connections

Deploy to community

High · can deploy to marketplace

Experimental hook

Low · validate with standalone first

Need to avoid name conflicts

High · can use plugin namespace

The official documentation also summarizes plugins as Claude Code extension features for deployment that can include custom commands, subagents, skills, hooks, and MCP servers.

19The difference between Standalone configuration and Plugin

Storage location

Standalone = project or user .claude/ / Plugin = plugin directory

Suitable for

Standalone = personal experiments, project-specific configuration / Plugin = team sharing, version management, deployment

Skill name

Standalone = /deploy / Plugin = /plugin-name:deploy

Conflict possibility

Standalone = name conflict possible / Plugin = prevent conflict with namespace

Update

Standalone = Git or file copy / Plugin = marketplace, version management

Beginner recommendation

Standalone = start with this approach / Plugin = package later

The official documentation also explains that standalone is suitable for personal workflows, per-project customization, quick experiments, and short skill names, while plugins are suitable for team and community sharing, multi-project reuse, versioned releases, and marketplace deployment.

For beginners, the guideline is as follows.

Step 1: Create one skill in .claude/skills/
Step 2: Try using with .claude/agents/
Step 3: Need it repeatedly across team
Step 4: Package as plugin

20Basic Plugin structure

A plugin roughly has this structure.

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── api-conventions/
│       └── SKILL.md
├── agents/
│   └── code-reviewer.md
├── hooks/
│   └── hooks.json
├── commands/
│   └── legacy-command.md
└── .mcp.json

The official documentation's plugin structure similarly includes .claude-plugin/plugin.json, commands/, agents/, skills/, hooks/, and .mcp.json.

The official plugins reference also explains that plugin manifest can declare skills, commands, agents, hooks, MCP servers, output styles, LSP servers, dependencies, etc.

21Minimal plugin manifest

my-plugin/.claude-plugin/plugin.json

{
  "name": "team-dev-kit",
  "description": "Team development conventions, review agents, and automation for Claude Code.",
  "version": "1.0.0",
  "author": {
    "name": "Your Team"
  }
}

According to the official documentation, plugin manifest defines plugin identity, description, and version, and Claude Code displays this metadata in the plugin manager. The name is a unique identifier and is used as the skill namespace to create names like /my-first-plugin:hello.

22Adding skills to Plugin

Plugin structure:

team-dev-kit/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── api-conventions/
        └── SKILL.md

skills/api-conventions/SKILL.md

---
description: Team API conventions. Use when creating or modifying API endpoints.
---

# Team API conventions

- Validate inputs.
- Keep business logic in services.
- Return consistent error responses.
- Add tests for success and failure cases.

When the plugin is active, this skill is invoked with a namespace.

/team-dev-kit:api-conventions

Plugin namespace reduces name conflicts. Multiple teams can use common names like deploy, review, and api-conventions, and conflicts are reduced by prefixing the plugin name.

23Plugin example with agents and hooks

A plugin can include just one skill, but for teams, it often bundles multiple components.

team-dev-kit/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── api-conventions/
│   │   └── SKILL.md
│   └── security-review/
│       └── SKILL.md
├── agents/
│   ├── code-reviewer.md
│   └── security-reviewer.md
└── hooks/
    └── hooks.json

For example, a team plugin can provide:

api-conventions skill

API implementation rules

security-review skill

Security review criteria

code-reviewer agent

Review changes

security-reviewer agent

Review security-sensitive changes

hook

Run formatter after file edit or protect sensitive files

MCP server

Connect internal tools

The official plugin discovery documentation also explains that plugins extend Claude Code with skills, agents, hooks, and MCP servers.

24Plugin installation and management

Plugins are managed with /plugin.

/plugin

Frequently used commands are as follows.

/plugin

open plugin UI

/plugin install <name>@<marketplace>

install plugin

/plugin enable <name>@<marketplace>

enable plugin

/plugin disable <name>@<marketplace>

disable plugin

/plugin uninstall <name>@<marketplace>

uninstall plugin

/plugin marketplace add <source>

add marketplace

/plugin marketplace list

list marketplaces

/reload-plugins

reload plugin changes

According to the official discovery documentation, the official marketplace claude-plugins-official is automatically available at Claude Code startup, and you can explore it in the Discover tab of /plugin or install with /plugin install github@claude-plugins-official.

25Official marketplace and community marketplace

According to the official documentation, a plugin marketplace is a catalog of plugins created by someone. First, add a marketplace, then individually install desired plugins from it. The official marketplace is provided automatically, while community marketplaces must be added manually.

claude-plugins-official

Official marketplace curated by Anthropic

claude-community

Community plugin catalog that passed review

internal marketplace

Plugin catalog operated by a company or team

Example of adding a community marketplace:

/plugin marketplace add anthropics/claude-plugins-community

Example of installation:

/plugin install some-plugin@claude-community

The official documentation explains that plugins in community marketplaces pass automated validation and safety screening and are pinned to specific commit SHAs in the catalog.

26Things good to install as Plugin

The official marketplace contains various types of plugins.

Code intelligence

TypeScript, Python, Rust LSP / go to definition, find references, check type errors

External integrations

GitHub, GitLab, Jira, Figma, Sentry / connect external tools

Security review

security guidance / review changes for security

Development workflow

commit, PR review, SDK tools / support iterative development procedures

Output styles

learning, explanatory style / change response style

The official discovery documentation explains that code intelligence plugins provide Claude with LSP-based code navigation, diagnostics, type information, etc., and external integration plugins bundle MCP server configurations for tools like GitHub, GitLab, Jira, Figma, and Sentry.

Before creating your own plugins, beginners should first try installing necessary plugins from the official marketplace.

27Plugin dependency and version management

When you start creating team plugins, dependency management becomes important.

For example, suppose deploy-kit plugin depends on secrets-vault plugin. If secrets-vault changes MCP tool names in a new version, deploy-kit could break.

The official dependency documentation explains that plugins can declare other plugin dependencies in plugin.json or marketplace entry, by default follow the latest version, but version constraints can pin to a validated range.

Example:

{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Beginners don't need to handle dependencies from the start. However, when you start deploying team plugins, you must always consider "is it safe if updates come in automatically?"

28Selection criteria for Skill, Plugin, MCP, Hook, Subagent

Since we've learned many features, let's review the selection criteria.

I want to always tell Claude basic project rules

CLAUDE.md

I want to load specific task procedures only when needed

Skill

I want to execute directly with short commands myself

Direct Skill invocation

I want to always run formatter after editing

Hook

I want to connect external tools like GitHub, Sentry, DB

MCP

I want to delegate large exploration or review to separate context

Subagent

I want to deploy skill, agent, hook, MCP to team

Plugin

I want to change only response tone and format

Output style

The practical guideline is:

Knowledge → Skill
Auto-execute → Hook
External connection → MCP
Delegate work → Subagent
Team deployment → Plugin
Always read basic rules → CLAUDE.md

29Beginner-friendly areas you don't need to understand deeply from the start

The most important thing in unit 25 is understanding "when to separate." You don't need to create plugin marketplaces, design dependency version constraints, or write complex LSP plugins from the start.

At the beginner stage, this is enough:

1. Keep CLAUDE.md short.
2. When repeated procedures appear, separate into .claude/skills/.
3. Set risky operations to not auto-invoke.
4. If repeated across projects, consider plugin.
5. Before deploying to team, test thoroughly with local or plugin-dir.

Advanced areas you don't need to know right now:

Run your own plugin marketplace

Needed at team deployment stage

Plugin dependency version constraint

Needed when plugins grow in number

LSP plugin creation

Needed when directly connecting language servers

Background monitors

Needed when real-time event reaction is needed

Enterprise managed plugin policy

Needed at organization operation stage

Plugin submission

Needed at community deployment stage

30Practical workflow: Converting repeated prompts to skill

Step 1: Find repeated prompt

When creating API endpoints, make sure to handle input validation, error format, and tests.

Step 2: Create skill

mkdir -p .claude/skills/api-conventions

.claude/skills/api-conventions/SKILL.md

---
description: API endpoint implementation rules. Use when creating or modifying API routes, validation, services, or API tests.
---

# API endpoint rules

When implementing API endpoints:

1. Validate all external input.
2. Keep business logic in services.
3. Use consistent error response format.
4. Add tests for success and failure cases.
5. Avoid leaking internal details.

Before editing, list:
- files to change
- validation updates
- service updates
- tests to add

Step 3: Test

Add a new user profile update API.
Create a plan following project rules.

See if Claude auto-applies the skill. If not, invoke directly.

/api-conventions create a plan for adding a user profile update API.

31Practical workflow: Bundling multiple skills into plugin

As the project grows, you may end up with these files:

.claude/
├── skills/
│   ├── api-conventions/
│   ├── security-review/
│   ├── testing-strategy/
│   └── deploy-checklist/
├── agents/
│   ├── code-reviewer.md
│   └── security-reviewer.md
└── hooks/
    └── protect-files.sh

If this structure is only used in one project, leave as is.

But if repeated across multiple projects, bundle as a plugin.

team-dev-kit/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── api-conventions/
│   ├── security-review/
│   ├── testing-strategy/
│   └── deploy-checklist/
├── agents/
│   ├── code-reviewer.md
│   └── security-reviewer.md
└── hooks/
    └── hooks.json

The official documentation also explains that if you already have skills or hooks in .claude/, you can transition to a plugin to ease sharing and deployment.

32Checklist before deploying Plugin to team

Name

Is plugin name clear with low conflict potential

Description

Does description clearly show what problem it solves

version

Is there a version that serves as update baseline

skills

Have you distinguished auto-invocation skills from direct-invocation skills

agents

Are tool permissions minimized

hooks

Are there any risky shell commands

MCP

Are tokens and URLs handled safely

namespace

Is /plugin-name:skill format understandable to team

testing

Have you tested installation with --plugin-dir or local marketplace

security

Does it not contain sensitive information

Once installed, a plugin can affect every team member's Claude Code environment. Especially plugins with hooks and MCP servers should be reviewed more carefully.

33Common mistakes when using Skill and Plugin ① · ②

Putting all rules in CLAUDE.md

Wastes context / separate procedures into skill

Skill description is vague

Auto-invocation doesn't work well / write clearly "when to use" upfront

Skill content is too long

Increases cost every turn after load / separate into supporting files

Deployment skill gets auto-invoked

Risky operations might be proposed unintentionally / use disable-model-invocation: true

34Common mistakes when using Skill and Plugin ③ · ④

Using hook like skill

Mixes execution guarantee and knowledge provision / use hook for auto-execution, skill for knowledge

Creating plugin too early

Increases management burden / validate with standalone first

Including personal tokens in plugin

Security risk / use environment variables and MCP authentication

Leaving plugin dependency as unlimited latest

Can break from parent plugin changes / consider version constraint after stabilization

Installing official plugin without review

Hard to understand permission and MCP impacts / check components in /plugin

35Recommended order for beginners

Don't try to become a plugin developer from the start. Learn in this order:

Keep CLAUDE.md short.
Find one repeated instruction.
Separate into .claude/skills/<name>/SKILL.md.
Try direct invocation with /skill-name.
Adjust description for good auto-invocation.
Add supporting files if needed.
Try connecting skill to subagent.
If repeated across projects, bundle as plugin.
Before team deployment, review hooks, MCP, and permissions.

Section 25 · Summary

Core takeaways from this unit

Skills are a feature that provides Claude with project-specific expertise and repeated procedures. If you're repeatedly copying and pasting the same instructions, checklists, or work procedures, separate them into skills. Keep CLAUDE.md with only short basic rules always needed, and move long procedures specific to certain tasks into skills.

Plugins are packages that bundle skills, agents, hooks, and MCP servers for deployment to teams or multiple projects. Start with .claude/ standalone for personal experiments or project-specific configuration, and transition to plugins when you need to reuse across multiple projects or deploy to a team.

Finally, use this guideline:

Always-needed basic rules → CLAUDE.md / Repeated work knowledge → Skill / Procedure to execute explicitly → direct-call skill / Automation that should always run → Hook / External tool connection → MCP / Large work separation → Subagent / Team deployment and version management → Plugin

Beginners should start with creating one good skill. A plugin is the packaging stage when that skill, agents, and hooks are repeatedly needed across the entire team.

Guide complete

Claude Code guide unit 25 complete. Proceed to the next unit if available.

26. Using Claude Code with an IDE

01IDE integration is a way to use Claude Code more conveniently within your IDE

Claude Code's foundation is the terminal CLI.

cd my-project
claude

But in reality, most developers view code in IDEs like VS Code, Cursor, Windsurf, IntelliJ, PyCharm, and WebStorm. IDE integration connects Claude Code to your IDE and helps it better use the following information.

Currently open files
Selected code ranges
IDE diagnostics
diff viewer
File path @-mentions
Multiple session tabs
Plan review

In other words, IDE integration transforms Claude Code from a "terminal-only tool" into a development assistant that sits alongside your code editor.

02Differences Between Terminal and IDE Use (Part 1)

03Differences Between Terminal and IDE Use (Part 2)

04Recommended Workflow for Beginners

The best approach for beginners is as follows.

Learn Claude Code basics → Terminal CLI
Real code editing and review → IDE integration
Large logs, tests, Git commands → Terminal
Explain selected code, review diffs → IDE

05Installing Claude Code in VS Code

In VS Code, you can use Claude Code by installing the extension. Requirements are VS Code 1.98.0 or later and an Anthropic account. The extension includes the CLI, so if you need advanced features, you can run claude in VS Code's integrated terminal.

Follow these steps to install.

1. Open Extensions
   - macOS: Cmd+Shift+X
   - Windows/Linux: Ctrl+Shift+X
2. Search for "Claude Code"
3. Click Install
4. Open Claude Code with the Spark icon
5. Log in in the browser

06Ways to Open Claude in VS Code

Method

Description

Editor Toolbar Spark icon

Quickly open Claude while viewing the current file

Activity Bar Spark icon

View your session list

Command Palette

Search for "Claude Code" commands

Status Bar

Click the Claude Code indicator at the bottom

Integrated terminal

Run claude

07Asking about Selected Code in VS Code

The biggest advantage of IDE integration is that you can easily pass the code you're currently viewing to Claude.

For example, select lines 20-40 of a file and ask Claude a question.

Explain what this selected code does.

The VS Code extension automatically allows Claude to see the selected text. If you want to explicitly include file paths and line numbers in your prompt, press Option+K on macOS or Alt+K on Windows/Linux to insert a reference like @file.ts#5-10.

08Example of Asking about Selected Code

Here's a real-world example.

@src/auth/session.ts#15-80
Explain how session expiration handling works in this code.

@src/api/users.ts#30-120
Check if there's any missing input validation in this API.

09Reviewing Changes with IDE Diff Viewer

When Claude modifies files from the terminal, it's important to check them with git diff. Using IDE integration lets you review this process more visually.

With the VS Code extension, when Claude tries to modify a file, it shows you the original and proposed changes side-by-side in a diff view, and you can accept, reject, or provide additional instructions.

10IDE Diff Viewer Workflow

For beginners, this flow works well.

1. Request a modification plan from Claude
2. Check the Plan or diff
3. Review changed lines in the IDE diff viewer
4. Reject or request edits if something looks wrong
5. Run tests after approval
6. Do a final review with git diff

11Using Plan Mode in VS Code

Using Plan Mode inside your IDE makes it easy to review changes like reading a document before implementing them.

/plan refactor the authentication module

In the VS Code extension, Plan Mode shows what Claude will do, and no changes are made until you approve.

12Example Plan Mode Request

A good request example looks like this.

/plan add password reset flow

Conditions:
- First investigate only relevant files
- Check if DB migration is needed
- Include test plan
- Summarize security risks separately

13Common Features in VS Code Prompt Box

Feature

Description

Permission mode

Switch between normal, Plan, auto-accept, etc.

Command menu

Open command menu with /

Context indicator

Check context usage

Extended thinking

Toggle deep reasoning for difficult problems

Multi-line input

Add line breaks with Shift+Enter

File attachment

Attach files or use @-mentions

14Useful Shortcuts in VS Code

Shortcut

Purpose

Cmd+Esc / Ctrl+Esc

Switch focus between editor and Claude

Cmd+Shift+Esc / Ctrl+Shift+Esc

Open a new Claude conversation in an editor tab

Option+K / Alt+K

Insert @-mention for current file and selection

Cmd+Shift+T / Ctrl+Shift+T

Reopen the most recently closed Claude session tab

Shift+Enter

Multi-line input

15Using CLI Together with VS Code

Even if you use the IDE extension, there's no need to abandon the CLI. Just open VS Code's integrated terminal and run it normally.

claude

When you run claude in VS Code's integrated terminal, the CLI automatically integrates with the IDE so you can use features like diff viewing and diagnostic sharing. If you're using an external terminal, you can run /ide within Claude Code to connect to VS Code.

16Dividing Work Between VS Code CLI and IDE

In practice, you split work like this.

Line-by-line code questions → VS Code panel
Large commands, tests, builds → integrated terminal
Visual change review → IDE diff viewer
Full session control → Either CLI or panel

17VS Code Configuration: Separating Extension Settings and Claude Code Settings

Setting Type

Location

VS Code extension settings

VS Code Settings → Extensions → Claude Code

Claude Code settings

~/.claude/settings.json, .claude/settings.json

VS Code extension settings control behavior within VS Code, while Claude Code settings are used by both the CLI and extension.

18Key Points About Settings Separation

Beginners can remember it this way.

VS Code screen behavior → VS Code settings
Claude Code permissions, hooks, MCP → Claude Code settings.json

19Using Claude Code in JetBrains IDEs

If you use JetBrains-family IDEs, install the dedicated Claude Code plugin.

Supported IDEs are as follows.

IntelliJ IDEA
PyCharm
Android Studio
WebStorm
PhpStorm
GoLand

20JetBrains Installation Steps

1. Open Settings → Plugins
2. Search for "Claude Code"
3. Click Install
4. Restart IDE
5. Run claude in the IDE terminal

21How to Use Claude Code in JetBrains

In JetBrains, running claude from the IDE's integrated terminal activates integrated features.

claude

If you're running Claude Code from an external terminal, enter the following in your session.

/ide

22Key JetBrains Features

Feature

Description

Quick launch

Quickly open Claude Code from the IDE

Diff viewing

Review changes in the IDE diff viewer

Selection context

Share your current selection or tab with Claude

File reference shortcut

Insert current file range as @src/auth.ts#L1-99

Diagnostic sharing

Share IDE lint and syntax errors with Claude

23JetBrains Diff Configuration

If you want to see Claude's changes in the IDE diff viewer, check the diff tool setting in /config.

/config

Then set the diff tool to one of the following.

auto      → Use IDE diff viewer
terminal  → View diff in terminal

24Important Notes When Using WSL2 with JetBrains

When using WSL2 and JetBrains together on Windows, the IDE may not be detected in some cases.

Typical symptoms:

No available IDEs detected

The main cause is that WSL2's NAT networking or Windows Firewall blocks the connection between WSL2 and the IDE on the Windows host. You can specify the Claude command for WSL in the JetBrains plugin settings.

wsl -d Ubuntu -- bash -lic "claude"

25WSL2 Detection Issue — Method 1. Allow Windows Firewall

Check the IP inside WSL.

hostname -I

Open Windows PowerShell as administrator and create a firewall rule like the example below.

New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16

Adjust the IP range to match your WSL2 subnet.

26WSL2 Detection Issue — Method 2. Use Mirrored Networking

If you're on Windows 11 22H2 or later, you can add the following to .wslconfig.

[wsl2]
networkingMode=mirrored

Then restart WSL from PowerShell.

wsl --shutdown

27JetBrains ESC Key Issue

In JetBrains terminal, Esc may not work to stop Claude Code tasks. This is because the IDE takes Esc first as a shortcut to "move focus to editor".

Solution:

Settings → Tools → Terminal
→ Disable "Move focus to the editor with Escape"

28Exploring Code in an IDE

When using IDE integration, it's better to ask Claude about the file you're currently viewing and your selection rather than asking it to "search through the entire project".

Bad request:

Analyze the entire project structure for me.

Good request:

Based on the auth middleware I've selected,
find the flow that calls this function.
Look at a maximum of 5 related files,
and just summarize—don't make changes.

29Better Code Exploration Request

@src/middleware/auth.ts#20-88
Summarize the conditions under which this code rejects requests.
Then find test files connected to these conditions.
Don't make changes.

In an IDE, the flow of "selection → question → explore few related files → plan" is most reliable.

30Requesting Code Changes in an IDE

When requesting changes in the IDE, it's also good to limit the scope rather than immediately asking "fix this".

@src/api/login.ts#10-90

Add input validation to this function.

Conditions:
- Explain the plan before making changes
- Maintain existing response format
- No new dependencies
- Update related tests if they exist
- Explain changes based on the diff

31Checking Changes After Modification

After changes, review them in the IDE diff viewer, and if needed, request this way.

Check if the change scope in this diff is excessive.
Revert unnecessary refactoring and keep only what's needed for input validation.

Even if Claude made the changes, you should do a final review.

git diff
npm test
npm run lint

32Creating a Review Workflow in the IDE

The advantage of IDE integration is that you can review changes visually. Here's the recommended workflow.

1. Request a plan from Claude
2. Check changes in the IDE diff viewer
3. Review the full diff again with /diff or git diff
4. Run /code-review
5. Run tests and lint
6. Check git status again before committing

33IDE Review Prompt Example

Review the current changes.

Focus on:
- Actual bug potential
- Security issues
- Missing tests
- Excessive changes
- Maintainability

Skip stylistic preferences,
and categorize necessary fixes into Critical / Warning / Suggestion.

34Leveraging IDE Diagnostics

The JetBrains plugin can automatically share IDE diagnostic errors—like lint or syntax errors—with Claude. VS Code can also leverage diagnostic sharing when the IDE and CLI are integrated.

A good request looks like this.

Based on the TypeScript error shown in IDE diagnostics, explain the cause.
Before making fixes, tell me which files need to change.

35Resolving IDE Diagnostics

Fix the lint errors in the current file.
But minimize style changes and only modify lines necessary to fix the errors.

36Avoid Large Pastes Even in the IDE

A common beginner mistake is pasting large logs or entire files directly into Claude's prompt box.

If you paste more than 10,000 characters, Claude Code collapses it to a [Pasted text] placeholder to keep the input usable. VS Code's integrated terminal can also drop characters on very large pastes, so it's better to save large files or long logs to a file and have Claude read that file instead.

37How to Handle Log Files

Bad approach:

Paste 50,000 lines of logs here

Good approach:

npm test 2>&1 | tee test-output.log

Then request from Claude.

@test-output.log Read this and summarize only the failed test names, error messages, and root cause candidates.
Don't reprint the full log.

38IDE and Permission Settings

Even when using the IDE, Claude Code's permission system remains important. For example, .env, secrets, and credentials files should continue to be protected.

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)"
    ]
  }
}

39Use Auto-Accept Carefully in the IDE

Just because the IDE diff viewer is convenient doesn't mean you should auto-accept all changes. JetBrains official documentation warns that if the auto-edit permission is enabled and Claude Code can modify IDE configuration files, the risk increases when combined with configuration files that IDEs can auto-execute.

For beginners, the guideline is as follows.

Learning phase → Manual approval
Small, safe changes → Auto-accept possible
Large refactoring → Plan Mode + manual approval
IDE config file changes → Always manual review
Security, deployment, environment variable files → Never auto-accept

40What to Check When IDE Doesn't Connect

If problems occur, check in this order first.

Symptom

What to Check

VS Code extension not visible

Reload or restart VS Code

Repeated login screen

Browser authentication, environment variable inheritance

ANTHROPIC_API_KEY not recognized

Open VS Code with code . from terminal

Claude command not found in JetBrains

claude --version, plugin settings command path

41Troubleshooting IDE Connection Issues (Continued)

JetBrains IDE not detected

Plugin enabled, IDE restart, integrated terminal, WSL settings

Diff doesn't appear in IDE

Check diff tool in /config

Esc doesn't stop tasks

JetBrains terminal ESC settings

Large paste acts strange

Save to file and reference with @file

Settings don't apply

Check setting sources with /status

Cause unclear

/doctor or claude doctor

42Beginner IDE Usage Routine — Starting Work

When starting work:

cd my-project
code .

Opening VS Code from the terminal is more likely to pass environment variables properly to the IDE. If your API key is in the shell but the extension shows a login prompt, VS Code might not have inherited the shell environment, so running with code . or logging in with your Claude account is a good idea.

43Beginner IDE Usage Routine — Selecting Files and Asking Questions

@src/auth/session.ts#10-70
Explain the role of this code and any dangerous edge cases.
Don't make changes.

44Beginner IDE Usage Routine — Requesting a Plan

/plan fix session expiration handling

Conditions:
- Investigate only relevant files
- Present the plan before making changes
- Include test plan

45Beginner IDE Usage Routine — Reviewing Changes

Explain the changes based on this diff.
Check if there's any unintended refactoring.

46Beginner IDE Usage Routine — Testing and Final Review

Testing:

npm test
npm run lint

Final review:

/code-review high

47Choosing Between VS Code and JetBrains

Usage Context

Recommendation

Primarily VS Code, Cursor, Windsurf

VS Code extension

Primarily IntelliJ, PyCharm, WebStorm

JetBrains plugin

Working on remote servers

CLI first, IDE remote if needed

Heavy terminal automation

CLI + IDE as supplement

Visual diff review is critical

IDE integration

Early learning stages

Learn CLI fundamentals first, then IDE integration

48Good Prompt Patterns with IDE ① · ②

Explaining selected code

Explain the role of the selected code.
Organize it by input, output, exceptions, and calling relationships.
Don't make changes.

Small edits

Add only null handling to the selected function.
Don't change the existing structure and explain the changes based on the diff.

49Good Prompt Patterns with IDE ③ · ④

Plan before refactoring

Don't fix this file right away.
First, create just the refactoring plan.

Include:
- Files to change
- Files to keep unchanged
- Risky areas
- Test plan

Review

Review the current diff.
Only point out actual bugs, security issues, and missing tests.
Skip style preferences.

50Common IDE Usage Mistakes (Part 1)

Mistake

Problem

Ask "look at this" without selecting a range

Claude may pick the wrong range

Paste large logs in the prompt

Dropped characters, wasted context

Always leave auto-accept on

Risk approving dangerous changes

Lightly approve IDE config file changes

IDE auto-execution risk

51Common IDE Usage Mistakes (Part 2)

Mistake

Solution

Terminal and IDE project root differ

Run from the same project root

Don't check /config diff tool setting

Choose auto or terminal

Mistake WSL2 issues for Claude problems

Check WSL2 firewall or mirrored networking

Use without protecting .env

Set permissions.deny

52Core Takeaways: IDE Integration (Part 1)

IDE integration is a way to use Claude Code more conveniently, not a replacement for the terminal CLI. The terminal excels at running commands, testing, Git, and automation, while the IDE excels at file selection, visual diffs, code review, and diagnostic sharing.

Beginners can follow this workflow.

1. Select files and code ranges in the IDE.
2. Ask Claude questions based on your selection.
3. Use /plan before large changes.
4. Review changes in the IDE diff viewer.
5. Run tests and lint in the terminal.
6. Do a final check with /diff or git diff.
7. Never auto-accept sensitive or IDE config files.

53Core Takeaways: IDE Integration (Part 2)

To summarize:

Terminal CLI → Execution and automation
VS Code / JetBrains → Visual review and code context
/ide → Connect external terminal to IDE
/config → Check diff tool and default behaviors
/status or /doctor → Diagnose settings and connection issues

The most important principle when using IDE and Claude Code together is "don't skip review just because it's convenient." Using the IDE diff viewer, Plan Mode, permission settings, and test execution together creates a safe real-world workflow.

Section 26 · Summary

What to Remember from This Section

Claude Code and an IDE are most powerful when used together. But convenience should never replace safety.

Selection → Question → Plan Mode → IDE diff review → Test

Following this workflow reduces mistakes even in the IDE.

Next Section

Section 27. (Part 7 Continued)

27. Working with Images and Multimodal Input

01Multimodal input is a feature for situations hard to explain in words

Code and logs are easy to explain with text. But visual state, screen layout, error messages, and diagrams are hard to explain in words.

When you add an image, Claude can see and analyze the screen itself.

The button is pushed to the right.

The input field is cut off on the mobile screen.

An error modal appears, but I'm not sure exactly which part is the problem.

I need to create a Prisma model based on this ERD.

I want to create a Tailwind component like a Figma mockup.

02When you need multimodal input

As a beginner, you can remember it this way.

Can explain sufficiently with text

Ask with text

Visual state is important

Attach image

Design, layout, or diagram is important

Attach image

Text within the image is key

Check zoom/clarity before attaching

03Three ways to input images

There are three ways to add images in Claude Code.

Drag and drop

Drag an image file into the Claude Code window (saved screenshots, mockup files)

Paste from clipboard

Paste after capturing (error screens, UI bugs)

Provide file path

Write the image path in the prompt (images in project, design capture files)

Here's how to provide a file path.

Example

Analyze the UI issue in this image: /path/to/screenshot.png

04Example of using file paths

Various examples of the path-based approach.

@docs/screenshots/login-error.png
Find parts of this screen that might confuse users.

Or you can provide multiple images together.

Based on the [Image #1] I just pasted,
explain the layout issue in the current login form.

05Paste shortcut caveats

Image paste shortcuts differ by terminal and OS.

Regular terminal

Ctrl+V

iTerm2

Cmd+V also works

Windows / WSL

Alt+V available

Ctrl+V intercepted by terminal in WSL

Use Alt+V

06Paste shortcut tips

When you paste an image, it inserts as a [Image #N] chip at the cursor position.

Default is Ctrl+V. If the shortcut doesn't work, try in this order.

Try Ctrl+V default
If you use iTerm2, try Cmd+V
If you use Windows/WSL, try Alt+V
If the terminal intercepts the shortcut, try a different paste key

07How to reference attached images

When you paste an image, it appears in the Claude Code input like this.

[Image #1]

If you have multiple images, they're distinguished by number.

[Image #1] [Image #2] [Image #3]

You can use these numbers directly in your prompt.

Example

[Image #1] is the current screen and [Image #2] is the target design. Analyze the differences between the two screens and summarize the CSS changes needed for implementation.

08Situations where images are particularly useful

Analyze error screens

Explain what this error screen means and its cause.

Debug UI bugs

Guess why the button is cut off on mobile.

Implement design

Create a plan to implement this mockup as a React + Tailwind component.

Analyze diagrams

Explain the flow of this architecture diagram.

Analyze ERD

Suggest a Prisma schema that matches this ERD.

Accessibility review

Find parts of this screen that could be accessibility issues.

Visual regression review

Compare the differences between the previous and current screens.

09Asking about error screens by capture

When pasting an error screen, it's better to include context about the situation rather than simply asking "What is this?"

Bad example

What is this error?

Good example

[Image #1] is the error screen that appeared right after clicking the login button.

Context:
- Browser: Chrome
- Environment: local dev
- Previous work: modified auth middleware
- Expected behavior: navigate to /dashboard after login
- Actual behavior: error screen displayed

Request:
1. Interpret the key cause from the error message.
2. Guess the files most likely to be involved.
3. Suggest the order to check first, don't fix yet.

10Providing logs alongside error screens

An even better example is providing logs together.

[Image #1] is the browser error screen, and
@server.log is the server log from the same time.

Look at both pieces of information and organize the cause candidates by priority.
Don't fix it yet.

Looking at just the image, you understand the visual state but may not understand the code execution flow. So it's better to provide reproduction conditions, expected behavior, actual behavior, and related logs together.

11Requesting UI screenshot analysis · Bad example

UI screenshots are good at finding visible problems. However, you need to specify exactly what Claude should look at.

Bad example

What do you think of this screen?

12Requesting UI screenshot analysis · Good example

Good example

[Image #1] is the current mobile login screen.

Review it from the following perspectives.
1. Layout breakage
2. Button position
3. Input field spacing
4. Text readability
5. Accessibility issues
6. Implementation file candidates

Don't fix it, just organize the problem list and priorities.

13Providing implementation files alongside UI screenshots

When you want implementation, do it like this.

[Image #1] is the target design, and
the current implementation file is @src/components/LoginForm.tsx.

Request:
1. Compare the image with the current component structure.
2. Organize required changes focusing on Tailwind classes.
3. Create a plan first, don't fix it yet.

Image-based implementation is hard to get perfect on the first try. At first, follow the flow: difference analysis → plan → minimal fix → re-check screenshot.

14Requesting implementation based on mockup

When creating a component from a design mockup, it's good to provide multiple states together.

[Image #1] default state
[Image #2] hover state
[Image #3] loading state
[Image #4] error state

Write the prompt like this.

I want to implement a Button component based on these four images.

Conditions:
- React + TypeScript
- Use Tailwind
- States: default, hover, loading, disabled, error
- No new libraries
- Include accessibility attributes
- Suggest the component API first, then implement after I approve.

15Structure of a good image prompt

When adding an image, include these four things.

What this image is
The situation it came from
The perspective Claude should look from
The desired output format

The template is like this.

Structure template

[Image #1] is the _______ screen. / Context: / Analysis perspective: / Output format:

16Good image prompt template

A detailed template is like this.

[Image #1] is the _______ screen.

Context:
- User action taken:
- Expected behavior:
- Actual behavior:
- Related file:
- Related log:

Analysis perspective:
1. Cause candidates
2. Related code location
3. How to reproduce
4. What to check before fixing

Output format:
- Certain facts
- Estimates
- Needs further confirmation
- Fix plan

Using this structure makes it easier for Claude to not just describe the image but connect it to development work.

17Image quality determines results

For good results, images must be clear and important text must be readable. Supported formats are JPEG, PNG, GIF, and WebP. GIF animations use only the first frame even if supported.

Resolution

Clear enough for text to be readable

Cropping

Include the problem area but keep some surrounding context

Compression

Avoid very heavy JPEG compression

Text

Zoom in for small text

Dark mode

Capture so color contrast is visible

Multiple states

Attach before/after or normal/bug screens together

18Good and bad examples of image capture

Characteristics of bad capture:

Error message is too small and blurry
Only the problem area is cut, no surrounding context
Sensitive information is exposed as-is

Characteristics of good capture:

Problem area and surrounding UI are both visible
Error message is readable
Unnecessary personal info is masked
Before/after comparison images are included

19Images use tokens and cost too

Images aren't free context. Images use roughly width pixels × height pixels / 750 tokens, and image tokens are included in the model's input token cost.

Also, high-resolution images can use up to about 3 times as many image tokens compared to older models. It's good to reduce unnecessarily large images beforehand.

20Image cost efficiency standards

Beginner standards are like this.

Small UI issue

Capture focusing on problem area

Whole layout issue

Capture full screen

Text is key

Zoom so text is readable

Many image comparisons

Only 2-4 of what you need

Long session

Check /context and /usage

21How to add multiple images together

Claude can view and compare multiple images together.

Example is like this.

[Image #1] is the target design, and
[Image #2] is the current implementation screen.

Compare the differences between the two images by the following criteria.
1. spacing
2. typography
3. color
4. alignment
5. missing states
6. implementation priority

22Multiple image comparison example · Normal and bug

Or compare normal and bug screens like this.

[Image #1] is the normal screen,
[Image #2] is the screen where the bug occurred.

Compare the differences and guess what CSS or state condition might be the cause.
Tell me the file candidates to check before fixing.

23Providing images and code files together

If you only provide an image, Claude understands the screen but may not know the actual code location. Providing code files improves analysis quality.

[Image #1] is the broken mobile screen, and
@src/components/Header.tsx is the related component.

Request:
1. Explain the problem visible on the screen.
2. Find the parts in Header.tsx most likely to be involved.
3. Create a fix plan based on CSS/Tailwind classes.
4. Tell me the plan first, don't fix it yet.

24Image, file, and fix flow

A better flow is like this.

[Image #1] screen analysis
→ find related files
→ fix plan
→ approval
→ code modification
→ test/re-check screenshot

This flow connects with Plan Mode.

/plan fix the mobile header layout based on [Image #1]

25Using ERD and database schema images

ERD images are useful for DB model design.

[Image #1] is the ERD for the new payment feature.

Request:
1. Organize entities and relationships in a table.
2. Suggest a Prisma schema draft.
3. Mark relationships where cascade delete is risky.
4. Organize questions to ask before migration.

26Comparing ERD with current code

You can also compare with current code.

[Image #1] is the target ERD, and
@prisma/schema.prisma is the current schema.

Compare the two structures and organize missing models, fields, and relations.
Don't fix it, just create a migration plan.

Important note: Small text in ERD images may not be readable. If table and column names are key, provide enlarged images or the original PDF together.

27Architecture diagram analysis

Architecture diagrams are useful for understanding system structure.

[Image #1] is the current service architecture diagram.

Explain it in the following format.
1. Major components
2. Request flow
3. Data storage location
4. External dependencies
5. Failure points
6. Security boundaries to watch

28Connecting architecture diagram with codebase

When connecting with the codebase, ask like this.

Check if the architecture flow in [Image #1] matches the current codebase.

First find the related files, then
summarize only the parts where the diagram and actual code differ.
Don't fix it.

This case may have large exploration scope, so connecting a subagent is also good.

29Analyzing architecture with Subagent

Use the Explore subagent to
find files corresponding to the API gateway, auth service, billing service in [Image #1].
Return only a summary, don't modify anything.

30PDFs can also be treated as visual materials

Claude Code can read and analyze PDF documents page by page, and you can specify a specific page range.

Example is like this.

Analyze this PDF: /path/to/document.pdf

Or:

Read pages 1-5 of the PDF: /path/to/report.pdf

Claude can analyze not just text in PDFs but also figures, charts, and tables.

31Caveats when analyzing PDFs

PDFs use more context than you might think. Standard PDF has a max request size of 32MB and max 600 pages, and a 200K context model has a max 100 pages per request. However, PDFs with complex tables, small text, and lots of graphics may fill context before the page limit.

As a beginner, narrow the page range rather than putting the entire PDF in at once.

32PDF analysis request · Bad and good examples

Bad request

Analyze this entire 300-page PDF for me.

Good request

Read only pages 12-18 of this PDF and
summarize only the requirements related to the authentication flow.

Even better request

Read pages 12-18 of this PDF and organize them in the following format.

- Requirement ID
- Related screen
- API impact
- DB impact
- Questions before implementation

33Analyzing charts, tables, and images in PDFs

If a PDF is just a text document, text extraction alone may be sufficient. But if charts, tables, diagrams, and scanned images are important, visual analysis is needed.

Analyze the chart on page 5 of this PDF.
Not just a simple summary, but organize the trends the chart shows and parts that could impact implementation requirements.

Or:

Read the table on page 8 of this PDF and
suggest a list of fields that could be converted to an API response schema.

34Technical considerations for PDF analysis

The important thing in visual PDF analysis is that each page is also processed as an image, so questions about charts, diagrams, and non-text elements are possible.

However, in certain API environments (Bedrock Converse API), the citations option may be needed for complete visual PDF analysis, and without citations, it may be processed in basic text extraction mode.

35Always mask and attach sensitive information

Screenshots contain more sensitive information than you think.

Account information

Email, username, organization name

Authentication information

Tokens, API keys, session ids

Infrastructure information

Server addresses, internal domains, IPs

Customer information

Names, phone numbers, addresses, payment information

Code information

Private repo names, branch names

Operations information

Production URLs, admin panels, log IDs

36Security checklist before uploading images

Before uploading an image, check the following.

Are email addresses masked?
Are API keys/tokens/session ids masked?
Is customer personal information masked?
Are internal URLs/IPs/domains masked?
Are payment/order/contract information masked?
Is there no sensitive information in browser tabs and address bar?
Is username/server name not exposed in the terminal prompt?

In this section, "how to mask what should not be shown" is just as important as "how to use images well."

37How to prepare a safe screenshot

Before capturing, reduce unnecessary areas as much as possible.

Good order:

Reproduce the problem screen.
Check tabs, address bar, and sidebars with sensitive information.
Capture only the necessary area.
Mask tokens, emails, and customer information.
Check that text is readable.
Paste into Claude Code.

38Screenshot capture method by operating system

macOS: Use Cmd+Ctrl+Shift+4 to capture the selected area to clipboard, then paste into Claude Code.

Windows: Use Snipping Tool or Win+Shift+S to capture the selected area, then you can paste it in.

Learning each OS method in advance creates an efficient capture and paste workflow.

39Bad and good examples when masking sensitive information

Bad example

Using a black semi-transparent box to blur tokens
Leaving the browser address bar as-is
Masking only part of a customer email
Production host showing as-is in the terminal

Good example

Completely covering sensitive information areas
Checking address bar and tab titles
Completely removing emails, tokens, customer IDs
Replacing with sample values if needed

40Sensitive information masking prompt

You can also specify it in the prompt like this.

All sensitive information is masked in the screenshot.
Don't guess the actual values for masked parts, and
analyze based only on screen structure and error messages.

41What not to do in image-based requests · 1-3

Mistake 1. Throw just one image and "fix it"

Insufficient root cause identification → Add context, expected behavior, related files

Mistake 2. Using blurry screenshots

Possible text misrecognition → Zoom and high-resolution capture

Mistake 3. Always capturing the entire screen

Context waste, sensitive information exposure → Capture focusing on problem area

42What not to do in image-based requests · 4-8

Mistake 4. Not masking sensitive information

Security risk → Mask before/after capture

Mistake 5. Requesting code fixes directly from image

Over-estimation possible → Request analysis and plan first

Mistake 6. Attaching multiple images without order

Comparison confusion → Specify [Image #1], [Image #2] meanings

Mistake 7. Analyzing entire PDF at once

Cost/context increase → Specify page range

Mistake 8. Assuming 100% accuracy like OCR

Possible small text misrecognition → Provide important text separately

43Image-based debugging workflow · Step 1

Step 1: Capture screen

Capture the error screen, related UI, and some console messages.

Mask sensitive information.

44Image-based debugging workflow · Steps 2-3

Step 2: Explain context

[Image #1] is the error screen that appeared after clicking the payment button.

Context:
- local environment
- Stripe test mode
- Previous change: modified checkout API
- Expected behavior: create checkout session
- Actual behavior: error display

Step 3: Request cause candidates

Look at the error message in the image and screen state and
organize cause candidates by priority.
Don't fix it, suggest files and logs to check first.

45Image-based debugging workflow · Steps 4-5

Step 4: Provide related files

@src/api/checkout.ts
@src/components/CheckoutButton.tsx
Looking at these two files with [Image #1] and narrow down the cause.

Step 5: Plan then fix

/plan fix checkout error shown in [Image #1]

46UI implementation workflow · Steps 1-2

Step 1: Compare target image and current implementation

[Image #1] is the target design,
[Image #2] is the current implementation screen.

Analyze the differences.
Don't fix it, just organize the priorities.

Step 2: Connect related component

@src/components/ProfileCard.tsx
@src/components/ProfileCard.module.css

Comparing these files with the two images,
plan what style changes are needed.

47UI implementation workflow · Steps 3-4

Step 3: Minimal fix

Good. Fix only spacing and typography first, the parts with the biggest difference from the target design.
Don't change colors yet.

Step 4: Re-review

After fixing, paste the screenshot again.

[Image #3] is the screen after fixing.
Compare with the target design [Image #1] and organize the remaining differences.

48Using images for accessibility review

You can find accessibility issues with images too.

[Image #1] is the signup screen.

Review from an accessibility perspective.
1. Color contrast
2. label and input relationship
3. Button state distinction
4. Error message location
5. Parts where keyboard users might be confused
6. Parts that seem to need screen reader explanation

Don't fix code, just create a checklist.

49Accessibility review · Image and code together

Images alone can't show actual ARIA attributes or DOM structure. Accessibility review is better done with code files.

Look at [Image #1] and @src/components/SignupForm.tsx together and
organize visual issues and code accessibility issues separately.

50Connecting images with browser automation

If you learned MCP in section 23 and IDE integration in section 26, image input also connects with browser automation. For example, a workflow where you capture a screen with Playwright or Chrome integration, analyze the screenshot to find UI issues.

Open the signup page in a browser,
take a screenshot with mobile viewport, then
analyze layout breakage and accessibility issues.

This method is closer to automation than manually pasting images. But at beginner stage, it's better to learn direct capture → paste → request analysis first.

51Using image input and Plan Mode together

Image-based work can include estimates. So it's safer to use Plan Mode rather than fixing right away.

I want to fix the mobile layout issue based on [Image #1].

Use /plan to proceed first.

Conditions:
- Separate what's clearly visible in the image from estimates
- Find related files first
- Minimize fix scope
- Include test or verification method

52Using image input and Plan Mode separately

Or separate the commands.

/plan fix mobile layout issue shown in [Image #1]

Plan Mode enforces investigation and planning before file modification, so it reduces the risk of over-fixing that can happen from interpreting images.

53Verifying results after image input

If you've modified code based on an image, you must verify results.

Check the diff Claude made
Run the app
Capture the same screen again
Compare before/after images
Run tests and lint

54Verification prompt after image-based fix

Prompt example is like this.

[Image #1] is before the fix,
[Image #2] is after the fix.

Compare the two images and
check if the problem is resolved and if new UI issues appeared.

Also do code verification.

Based on git diff, review if this UI fix exceeded the scope needed to solve the target problem.

55Beginner prompt collection · Error screens

Error screens

[Image #1] is an error screen.

Context:
- Occurred after:
- Expected behavior:
- Actual behavior:
- Related file:
- Related log:

Request:
1. Interpret the error message
2. Cause candidates
3. Files to check
4. Verification order before fixing

56Beginner prompt collection · UI bugs

UI bugs

[Image #1] is a broken UI on mobile screen.

Analyze by the following criteria.
- Broken location
- Possible CSS cause
- Related component candidates
- Fix priority
- Verification method

Don't fix right away, just suggest a plan.

57Beginner prompt collection · Design implementation

Design implementation

[Image #1] is the target design.

Create a plan to implement with React + TypeScript + Tailwind.
Suggest component structure, props, state, and accessibility considerations first.
Don't modify files until I approve.

58Beginner prompt collection · Before/after comparison

Before/after comparison

[Image #1] is the old screen,
[Image #2] is the screen after change.

Separate intended changes from unintended changes and organize.

59Beginner prompt collection · ERD analysis

ERD analysis

[Image #1] is a database ERD.

Organize entities, relations, cardinality, nullable fields, and risky cascade relationships.
Then suggest a Prisma schema draft.

60Beginner prompt collection · PDF analysis

PDF analysis

Read only pages 10-15 of this PDF.

Goals:
- Extract implementation requirements
- API impact
- DB impact
- UI impact
- Organize questions to ask before development

61Problem-solving checklist · 1-4

Image paste doesn't work

Terminal intercepting shortcut → Try Ctrl+V, iTerm2 Cmd+V, Windows/WSL Alt+V

Image analyzed too small

Insufficient resolution → Zoom capture or provide original file path

Misreads text

Blur, compression, small text → Provide text separately

Results are generic

Question is vague → Specify context, perspective, output format

62Problem-solving checklist · 5-8

Cost is high

Large/many images → Crop necessary parts only, reduce image count

PDF is too heavy

Many pages/charts/tables → Specify page range, split document

Sensitive info exposure risk

Wide capture range → Mask then attach

Code fix is excessive

Much estimation from image → Use Plan Mode and manual approval

Section 27 · Wrap-up

Key takeaways from this section

Images and multimodal input are a way to accurately convey visual problems to Claude Code that are hard to explain in words. They are especially useful for tasks where the screen itself matters, like error screens, UI bugs, design mockups, architecture diagrams, ERDs, and PDFs.

Core standards

Image input method

Drag and drop, paste, file path

Paste default

Ctrl+V

iTerm2

Cmd+V also works

Windows/WSL

Alt+V also works

Multiple images

Specify meaning with [Image #1], [Image #2]

Core standards (continued)

Good questions

Context + perspective + output format

Sensitive information

Always mask and attach

Large images/PDFs

Watch cost and context

Before fix

Use Plan Mode

After fix

Verify with before/after images and diff

Images are powerful, but Claude seeing only a screen doesn't mean Claude knows all code context. The best use is image + context explanation + related files + logs + Plan Mode together.

Next section

Section 28. Connecting Claude Code with Browser Automation

28. How to debug when problems occur

01Goal of this section

This section covers how to narrow down problems step by step when you encounter issues with Claude Code, before blindly reinstalling or wiping your settings.

Section 28 in the uploaded comprehensive guide focuses on separating installation problems, authentication issues, permission issues, command execution failures, and MCP / hook / plugin issues.

According to the official documentation, if you don't know where a problem originated, run /doctor first while inside Claude Code, and if Claude Code itself won't start, run claude doctor in the terminal as your starting diagnostic point. /doctor checks installation status, configuration validity, MCP setup, and context usage all at once.

02First principle of debugging: "Separate which layer is blocked"

Most Claude Code problems fall into one of these categories:

Installation problems
Authentication problems
Network / proxy problems
Configuration problems
Permission problems
Command execution problems
Context / performance problems
Search / file discovery problems
MCP problems
Hook problems
Plugin problems
IDE integration problems

Don't try to fix everything at once; classify the problem first.

03Bad approach vs. good approach

Bad approach

Claude Code is acting weird. Should I reinstall?

Good approach

Does the claude command run?
Am I logged in?
Is the problem specific to one project?
Does the problem only appear when a specific MCP or hook is enabled?
Does it reproduce even with a fresh empty config?

The official troubleshooting documentation also recommends separating issues by symptom: installation and login problems, configuration not being applied, API errors, IDE problems, and performance/search problems.

04First diagnostic command to run

When you encounter problems, check in this order:

claude --version
claude doctor

If you're already inside Claude Code, run:

/status
/doctor
/context

For configuration and extension problems, also check:

/memory
/permissions
/hooks
/mcp
/skills
/agents
/plugin

05Basic diagnostic command table

claude --version

Check if Claude Code runs and what version / after installation or update

claude doctor

Installation and environment status / when Claude Code won't start

/doctor

Diagnose current session installation, settings, MCP, context / problems with unclear causes

/status

Active settings source, authentication status, managed settings / when configuration seems unexpected

06Basic diagnostic command table (continued)

/context

Current context composition / when conversations get long or instructions aren't working

/permissions

Current permission rules / Tool not permitted issues

/hooks

Hook registration status / when hooks aren't running

/mcp

MCP server connection status / when MCP tools don't appear

07Basic diagnostic command table (continued 2)

/debug [problem]

Session debug logging and diagnosis / complex problem analysis

claude --debug

Detailed debug output / plugin, hook, MCP loading problems

/debug [issue] enables debug logging in the current session and helps Claude diagnose the problem based on logs and configuration paths.

08Debugging installation problems

Installation problems typically show up as:

command not found: claude
'claude' is not recognized
Installation script returns HTML
TLS / SSL errors
EACCES or permission denied
npm or Node path issues in WSL

The official installation troubleshooting documentation separately covers command not found, PATH issues, permission issues, network problems, TLS errors, Windows shell command confusion, and WSL issues.

09When claude command is not found

First check the version:

claude --version

If that doesn't work, check your PATH:

macOS / Linux:

echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

If it's not there, add it:

10Adding PATH (Zsh)

echo 'export PATH="$HOME/.local/bin:$PATH"' » ~/.zshrc
source ~/.zshrc

11Adding PATH (Bash)

echo 'export PATH="$HOME/.local/bin:$PATH"' » ~/.bashrc
source ~/.bashrc

12Checking PATH (Windows PowerShell)

$env:PATH -split ';' | Select-String '\.local\\bin'

According to the official documentation, the native installer places Claude Code at ~/.local/bin/claude on macOS/Linux, and %USERPROFILE%.localinclaude.exe on Windows. If installation succeeded but the command isn't found, you need to check that this path is in your PATH.

13When multiple installations conflict

Installing Claude Code multiple times through npm, Homebrew, native installer, WinGet, etc., can cause version conflicts.

macOS / Linux:

which -a claude
ls -la ~/.local/bin/claude
ls -la ~/.claude/local/
npm -g ls @anthropic-ai/claude-code 2>/dev/null

Windows PowerShell:

where.exe claude
Test-Path "$env:USERPROFILE.localinclaude.exe"

14Removing unnecessary installations

The official documentation warns that having multiple Claude Code installations can cause version mismatch or unexpected behavior, so keep only one. The native installer location ~/.local/bin/claude or Windows %USERPROFILE%.localinclaude.exe is recommended.

Remove unnecessary npm global installation:

npm uninstall -g @anthropic-ai/claude-code

Remove legacy local npm installation:

rm -rf ~/.claude/local

15Network, proxy, and TLS problems

If installation fails at the download stage, first check if you can reach the download server:

curl -sI https://downloads.claude.ai/claude-code-releases/latest

If you get HTTP/2 200, access is working. If you get no output, timeout, or DNS errors, it could be a network, proxy, or firewall issue. The official documentation also notes that the installer downloads from downloads.claude.ai, so verify access to that URL.

16Proxy setup (macOS / Linux)

If you're behind a corporate proxy, set environment variables:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash

17Proxy setup (Windows PowerShell)

$env:HTTP_PROXY = 'http://proxy.example.com:8080'
$env:HTTPS_PROXY = 'http://proxy.example.com:8080'
irm https://claude.ai/install.ps1 | iex

If you encounter TLS errors, check your system CA certificates, corporate TLS inspection, and NODE_EXTRA_CA_CERTS settings. The official installation documentation explains that errors like unable to get local issuer certificate or SELF_SIGNED_CERT_IN_CHAIN can come from corporate proxy TLS inspection.

18WSL installation problems

If you used npm installation on WSL, it often picks up the wrong Windows npm:

which npm
which node

If the path starts with /mnt/c/, you're using Windows-side Node/npm. It's safer to use Linux paths like /usr/... or ~/.nvm/... from within WSL.

The uploaded documentation also notes that for WSL path issues, which npm should start with /usr, not /mnt/c.

19WSL npm platform issues

If npm-based installation encounters platform mismatch, you can try:

npm config set os linux
npm install -g @anthropic-ai/claude-code --force

However, the official documentation says to skip this WSL npm troubleshooting section if you used the native installer. npm installation issues only apply to npm-based installations.

20nvm loading setup

If nvm isn't loading, add it to your shell configuration:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. $NVM_DIR/nvm.sh
[ -s "$NVM_DIR/bash_completion" ] && \. $NVM_DIR/bash_completion

21Debugging authentication problems

Authentication problems typically show up as:

Not logged in
OAuth error
Invalid code
403 Forbidden
Token expired
Organization disabled message
Bedrock / Vertex / Foundry credential errors

First check your current authentication status:

claude auth status

Or inside Claude Code:

/status

22Login again

claude auth login

Or from within the session:

/login

According to the official documentation, if the login issue isn't clear, completely logging out with /logout, closing Claude Code, and then running claude again to complete authentication from scratch resolves most cases.

23Authentication reset flow

Basic re-login:

/logout

Then close and restart Claude Code:

claude

To switch accounts directly from the terminal:

claude auth logout
claude auth login

The uploaded documentation also notes to use claude auth logout && claude auth login when switching between accounts or organizations.

24When OAuth fails in WSL2, SSH, or containers

In WSL2, SSH, or container environments, the browser may open on a different host and the redirect can't return to Claude Code's local callback server. In this case, when the browser displays the code, paste it into the terminal prompt. The official documentation also instructs to copy the code and paste it into the terminal if the browser redirect doesn't return automatically in WSL2, SSH, or containers.

If the browser doesn't open, press c to copy the OAuth URL.

25Open Windows Chrome from WSL2

To open Windows Chrome directly from WSL2:

export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

26ANTHROPIC_API_KEY takes precedence over OAuth

If you're logged in but getting strange organization errors or acting like an old company account, an old API key may be left in environment variables:

echo $ANTHROPIC_API_KEY

If you want to use subscription login, unset it:

unset ANTHROPIC_API_KEY
claude

Also check permanent configuration files:

grep -n "ANTHROPIC_API_KEY" ~/.zshrc ~/.bashrc ~/.profile 2>/dev/null

27Debugging permission problems

Permission problems typically show up as:

Tool not permitted
Permission denied
Claude can't read files
Bash execution approval keeps appearing
Specific file edits are rejected

First check your current permission status:

/permissions
/status
/doctor

28Permission configuration file locations

According to the official debug configuration documentation, /permissions shows currently active allow/deny rules, and /status shows active settings sources and managed settings status.

Check permission configuration file locations:

User settings

~/.claude/settings.json

Project settings

.claude/settings.json

Local personal settings

.claude/settings.local.json

According to the official settings documentation, Claude Code configuration scope is divided into managed, user, project, and local; project settings are shared in the repository, and local settings apply only to the current user in that repository.

29When settings don't apply

If you added settings but Claude seems to ignore them, verify that the settings actually loaded:

/status
/doctor

And check the configuration file location again:

Common mistakes:

Putting permissions, hooks, env in ~/.claude.json

Correct locations:

~/.claude/settings.json
.claude/settings.json
.claude/settings.local.json

The official debug configuration documentation explains that ~/.claude.json contains app state and UI toggles, while permissions, hooks, and env should go in ~/.claude/settings.json.

30Debugging command execution failures

When Claude runs a Bash command and it fails, first separate "Claude issue" from "project command issue".

For example, npm test failure might not be a Claude Code problem but a project test failure.

Run directly in the terminal:

npm test

Don't paste full logs to Claude; save them to a file and let Claude read it:

npm test 2>&1 | tee test-output.log

31Handling command execution failures

Request Claude like this:

Read @test-output.log and summarize only the failed test names, key error messages, and suspected root causes.
Don't print the entire log again.

If a command seems stuck, press Ctrl+C to cancel. The official troubleshooting documentation explains that if Claude Code isn't responding, try Ctrl+C to cancel the current operation, and if that doesn't work, close the terminal and restart, then run claude --resume from the same directory to continue.

32Separating Bash permission issues from actual shell problems

Bash command failures fall into three categories:

Permission denied

Tool not permitted / Check /permissions

Shell environment problem

command not found: npm / Run directly in terminal

Project error

test/lint/build failure / Analyze logs

For example, if Claude can't run npm run test, first check:

which npm
npm --version
npm run test

33Requesting Bash problem classification

Request Claude like this:

Is this a Claude Code permission issue, a shell environment issue, or a project test failure? Separate them.
First propose just the verification commands to run.

34Debugging context and performance problems

As conversations grow long, these problems can occur:

Responses slow down
Forgets previous decisions
Editing direction wavers
Context length exceeded
Autocompact-related errors

First check:

/context
/usage

35Context problem resolution flow

Use /context to see what takes up space
Use /compact to preserve only essentials
Replace large logs and files with summaries
Use /clear for unrelated work
Move large searches to a subagent

The official troubleshooting documentation recommends using /compact regularly with high CPU or memory usage, restarting Claude Code between large tasks, and adding large build directories to .gitignore.

36Handling autocompact failures

If auto-compaction keeps failing, large files or tool output may immediately refill the context. The official documentation recommends having Claude read files in small line ranges or function units, specifying focus like /compact keep only the plan and the diff, moving large file work to a subagent, or using /clear if necessary.

37Debugging search and file discovery problems

If Claude can't find files, @file mention acts strange, or custom agents/skills can't find files, it might be a ripgrep issue.

Symptoms to watch for:

Search results are too few
@file autocomplete doesn't work
Grep returns empty
Custom skill or agent can't find files

Install system ripgrep:

38Installing ripgrep

macOS:

brew install ripgrep

Ubuntu / Debian:

sudo apt install ripgrep

Windows:

winget install BurntSushi.ripgrep.MSVC

Then set the environment variable:

export USE_BUILTIN_RIPGREP=0

The official troubleshooting documentation explains that the Search tool, @file mention, custom agents, and custom skills may not find files when bundled ripgrep doesn't run on the system. Install platform-specific ripgrep and set USE_BUILTIN_RIPGREP=0.

39WSL search problems

On WSL, project location also matters. Working under /mnt/c/ on the Windows file system can slow searches or return fewer results. The official documentation recommends moving projects to the Linux file system /home/ when possible on WSL and narrowing search scope by directory or file type.

40Debugging MCP problems

MCP problems show up as:

Server doesn't appear in /mcp
Server shows failed status
Shows connected but 0 tools
OAuth auth doesn't work
Project scope server not approved
MCP tool output is too large

First check status:

/mcp

Also check from the terminal:

claude mcp list
claude mcp get <name>

41MCP diagnostic information

The official debug configuration documentation explains that /mcp shows all configured servers, connection status, and current project approval status. Project-scoped servers require one-time approval, and if you closed the prompt, you need to re-approve in /mcp.

42Common reasons why MCP doesn't appear

.mcp.json exists but doesn't appear

Wrong file location / Place .mcp.json at repository root

mcpServers added to settings.json but doesn't appear

settings.json is not the place for MCP config / Use .mcp.json or claude mcp add --scope user

Project MCP server doesn't start

Closed approval prompt / Approve in /mcp

43Common reasons why MCP doesn't appear (continued)

Fails only in specific directory

Relative path interpreted relative to launch dir / Use absolute path

Env doesn't apply

settings.json env expected / Use per-server env in .mcp.json

Connected but 0 tools

Server doesn't return tool list / Reconnect in /mcp, check claude --debug mcp

The official debug configuration documentation explains that project MCP config should be in .mcp.json at the repository root, not inside .claude/, and that settings.json doesn't read the mcpServers key.

44When MCP server won't run

For local stdio MCP servers, try running directly:

npx -y some-mcp-server

Or test the command and args from .mcp.json directly in the terminal.

Check debug output:

claude --debug mcp

The official debug configuration documentation explains that if the server is connected but shows 0 tools, try reconnecting in /mcp, and if it stays at 0 tools, use claude --debug mcp to check the server's stderr output.

45MCP security considerations

If an MCP server fetches external content, also consider prompt injection risks. The official MCP documentation warns to verify that a server is trustworthy before connecting, and notes that servers fetching external content can create prompt injection risks.

46Debugging hook problems

Hook problems typically show up as:

Hook doesn't appear at all
Hook appears but doesn't run
Matcher doesn't match
Blocked by exit code
Script permission missing
JSON parsing fails

First check the current hook list:

/hooks

The official debug configuration documentation explains that /hooks shows all hooks registered in the current session, organized by event.

47Checklist when hook doesn't run

Configuration location

Good: "hooks" key in .claude/settings.json / Bad: standalone .claude/hooks.json file

Matcher type

Good: "Edit|Write" / Bad: ["Edit", "Write"]

Tool name capitalization

Good: "Bash" / Bad: "bash"

Script execute permission

Good: chmod +x script.sh / Bad: no execute permission

48Hook checklist (continued)

Shebang

Good: #!/usr/bin/env bash / Bad: missing

JSON parsing

Good: use jq -r / Bad: only echo for guessing

Debug check

Good: claude --debug hooks / Bad: fix by guessing

The official debug configuration documentation explains that if hook matcher is an array, it causes a schema error, and the matcher must be a single string like "Edit|Write". Tool names must match case: Bash, Edit, Write, Read.

49Hook debug mode

To watch real-time hook evaluation:

claude --debug hooks

According to the official documentation, debug logs record each event, checked matchers, and hook exit code and output.

50Test hook script itself

To check if the hook script itself is the problem, run it directly outside Claude Code.

For example, if protect-files.sh expects JSON stdin:

echo '{"tool_input":{"file_path":".env"}}' | .claude/hooks/protect-files.sh
echo $?

If exit code is 2, it may work as a blocking hook. The uploaded documentation clarifies that exit code 2 blocks tool calls as a blocking hook, while exit code 1 means a non-blocking hook failure.

51Debugging plugin problems

Plugin problems show up as:

Plugin installed but skill doesn't appear
Plugin agent doesn't appear
Plugin hook doesn't run
Plugin MCP server doesn't start
Change doesn't take effect
Plugin only fails in specific directory

First check plugin status:

/plugin

Or start with debug:

claude --debug

52Plugin debug output

The official plugin reference explains that claude --debug shows which plugins load, plugin manifest errors, skill/agent/hook registration, and MCP server initialization.

53When plugin changes don't take effect

Skill SKILL.md changes may reflect immediately in the current session, but other plugin components differ:

hooks/
.mcp.json
agents/
output-styles/

If you changed these components, run:

/reload-plugins

Or restart Claude Code:

The official plugin reference explains that changes to hooks/, .mcp.json, agents/, and output-styles/ don't reflect automatically; /reload-plugins or restarting Claude Code is needed.

54Project-scope skills loading problem

The project-scope skills-directory plugin only loads from .claude/skills/ in the current directory where you started Claude Code. If your plugin is at the repository root but you start Claude Code from a subdirectory, it may be missed. Run from the repository root or use /reload-plugins.

55When plugin structure is wrong

Good structure:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
├── agents/
├── hooks/
├── .mcp.json
└── scripts/

Bad structure:

my-plugin/
└── .claude-plugin/
    ├── plugin.json
    ├── skills/
    ├── agents/
    └── hooks/

The official plugin reference explains that only plugin.json goes inside .claude-plugin/, while components like commands, agents, and hooks should be at the plugin root level.

56Debugging IDE integration problems

IDE issues were covered in detail in section 26, but here's a quick checklist:

VS Code extension doesn't appear

Install extension, reload window, VS Code version

Claude won't connect to IDE

Run claude from IDE terminal or use /ide

Diff doesn't show in IDE

Check /config for diff tool

JetBrains not detected

Install plugin, restart IDE, check WSL2 firewall

57IDE problem checklist (continued)

ESC doesn't work

JetBrains terminal focus setting

API key not picked up by extension

Run with code . to inherit shell env

The official troubleshooting documentation directs you to separate troubleshooting for VS Code extension not connecting, JetBrains plugin, and IDE not detected issues on each surface.

58Test settings in clean state

To check if the problem is configuration-related, run in "clean settings":

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

This session starts without the usual user/project settings, hooks, MCP servers, plugins, or memory. The official debug configuration documentation recommends setting CLAUDE_CONFIG_DIR to an empty directory and running from a directory without .claude, .mcp.json, or CLAUDE.md to compare with a clean session when the root cause is hard to narrow down.

59Clean session judgment criteria

Judgment works like this:

Works in clean session → Problem with existing ~/.claude or project .claude settings
Fails in clean session too → Installation, network, authentication, managed settings, environment variable problem

If the problem is caused by existing settings, gradually restore files one by one to find the cause.

60Resetting configuration is the last resort

Wiping configuration is a last resort. Backup first:

mkdir -p ~/claude-backup
cp -R ~/.claude ~/claude-backup/claude-dir 2>/dev/null
cp ~/.claude.json ~/claude-backup/claude.json 2>/dev/null
cp -R .claude ~/claude-backup/project-claude-dir 2>/dev/null
cp .mcp.json ~/claude-backup/project-mcp.json 2>/dev/null

61Selective configuration reset

Reset user settings:

rm ~/.claude.json
rm -rf ~/.claude/

Reset project settings:

rm -rf .claude/
rm .mcp.json

The uploaded documentation also separates user settings reset from project settings reset commands. For beginners, clean session testing before full deletion is safer.

62Common error messages and responses ①

command not found: claude

PATH or installation problem / Check claude --version, PATH

Authentication failed

Token expired or bad auth / Check claude auth status, claude auth login

Not logged in

Tool not permitted

Blocked by permission rules / Check /permissions, settings

63Common error messages and responses ②

MCP server failed to start

MCP command/env/path problem / Check /mcp, claude mcp get <name>

Context length exceeded

Conversation/tool output too large / Use /context, /compact, /clear

Rate limit exceeded or 429

Usage limit or temporary throttling / Wait and retry, check /usage

529 Overloaded

Server overload / Auto-retries then retry later if continues

64Common error messages and responses ③

Request too large

Input too large / Narrow down files, images, PDFs

model not found

Model access or model name problem / Check /model, plan/account

The official error reference documents Claude Code runtime error messages by type and recovery method, including API 5xx, 529, 429, authentication, network, request size, and model access issues. Transient failures also auto-retry up to 10 times with exponential backoff before showing an error.

65When Claude "answers strangely"

Not always an error message. Sometimes Claude:

Ignores project rules
Forgets previous decisions
Looks for files you already showed
Uses wrong tools
Tries to edit too broadly

In this case, first check context and memory:

/context
/memory
/status

66Verifying CLAUDE.md loaded

Check if CLAUDE.md actually loaded:

/memory

The official debug configuration documentation explains that if the memory file doesn't appear in /memory, you should check the file location. Also, subdirectory CLAUDE.md loads on-demand when Claude reads files in that directory with the Read tool, not at session start.

Also, if CLAUDE.md instructions are too long, vague, or conflicting, compliance rates drop. Keep project rules short and specific, and use permissions or hooks to enforce things that must be blocked.

67Gathering information for problem reports

To ask someone or file an issue, gather:

claude --version
claude doctor

Inside Claude Code:

/status
/doctor
/context

For MCP issues:

claude mcp list
claude mcp get <name>

68Gathering information for problem reports (continued)

Hook issues:

claude --debug hooks

Plugin issues:

claude --debug

For performance/memory issues, you can use /heapdump. The official troubleshooting documentation explains that if memory usage stays high, /heapdump creates JavaScript heap snapshot and memory breakdown files in ~/Desktop or Linux home directory, and you should attach both files when reporting memory issues on GitHub.

69Removing sensitive information

Always remove sensitive information before sharing logs:

API key
OAuth token
Session ID
Internal URL
Customer information
.env contents
DB connection string

70Problem separation flow for beginners

When a problem occurs, move through this order:

claude --version
claude doctor
If Claude Code starts, /status
/doctor
/context
By problem type: permissions → /permissions / MCP → /mcp, claude mcp get / Hook → /hooks, claude --debug hooks / Plugin → /plugin, /reload-plugins, claude --debug / search → ripgrep install and USE_BUILTIN_RIPGREP=0 / performance → /compact, /clear, /heapdump
Check if issue reproduces in clean session
If still not resolved, use /feedback or GitHub issue

71Quick fixes by situation: Can't find after install

claude doesn't work after install:

claude --version
echo $PATH
which -a claude

Check PATH or duplicate installations.

Keeps asking to log in:

claude auth status
claude auth logout
claude auth login

Check if environment variable ANTHROPIC_API_KEY overrides OAuth.

72Quick fixes by situation: Can't find files

Claude can't find files:

brew install ripgrep        # macOS
sudo apt install ripgrep    # Ubuntu/Debian
winget install BurntSushi.ripgrep.MSVC  # Windows
export USE_BUILTIN_RIPGREP=0

On WSL, move your project under /home/.

73Quick fixes by situation: Permissions / MCP / Hook

Tool not permitted:

/permissions
/status
/doctor

Check priority of settings.json, settings.local.json, and managed settings.

MCP tool doesn't appear:

/mcp

claude mcp list
claude mcp get <name>
claude --debug mcp

Check .mcp.json location, approval status, relative paths, and env location.

74Quick fixes by situation: Hook / Plugin

Hook doesn't run:

/hooks

claude --debug hooks

Check if matcher is a string, tool name capitalization, and script execute permission.

Plugin change doesn't work:

/reload-plugins

Or restart:

claude --debug

75Debug request prompt: Configuration problem

Configuration problem:

My Claude Code config isn't working as expected.
Diagnose in this order.
1. Interpret /status results
2. Interpret /doctor results
3. Interpret /permissions results
4. Explain which config file takes priority
5. Before fixing, list suspected causes only

76Debug request prompt: MCP / Hook / Performance

MCP issue:

My MCP server shows failed status in /mcp.
Analyze only these based on claude mcp get results and .mcp.json:
- command problem
- args problem
- env problem
- authentication problem
- project approval problem
- relative path problem
Don't fix, just propose check order.

77Debug request prompt: Hook / Performance

Hook issue:

My PostToolUse hook isn't running.
Review settings.json based on these items:
- hooks key location
- event name
- matcher format
- tool name capitalization
- script path
- execute permission
- exit code meaning
List suspected causes by priority before fixing.

78Debug request prompt: Performance problem

Performance problem:

Claude Code session got slow.
First analyze /context results
to see what takes up space,
then separate what to keep and what to drop.
Next suggest a sentence to add to /compact.

79What not to do when debugging

Immediately reinstall everything

Can't find root cause, problem repeats / Start with claude doctor

Delete all config files

Lose personal settings/MCP/skills / Backup then compare clean session

Paste entire log

Waste context, expose secrets / Save to file, summarize key part

Solve all permission issues with allow

Security risk / Allow only what's needed

80What not to do when debugging (continued)

Save MCP token directly in .mcp.json

Leak risk / Use environment variables or OAuth

Blame Claude for hook error

Could be script path/matcher problem / Check /hooks, --debug hooks

Change plugin without reload

Changes don't apply / Use /reload-plugins

Search large repo from WSL /mnt/c

Slow/missing results / Move to /home/

81Final recovery routine

For complex problems, follow this routine exactly:

1. Basic check:

claude --version
claude doctor

2. Check for duplicate installations:

which -a claude 2>/dev/null || where.exe claude

3. Check authentication:

claude auth status

4. Compare with clean settings:

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

82Final recovery routine (inside Claude Code)

Inside Claude Code:

/status
/doctor
/context
/permissions
/mcp
/hooks
/plugin

Problem-specific debug:

claude --debug
claude --debug hooks
claude --debug mcp

If still not resolved, use /feedback or check GitHub issues. Prepare: version, OS, shell, install method, claude doctor results, relevant debug logs, and reproduction steps.

Section 28 · Summary

Core takeaways from this section

The core of Claude Code troubleshooting is separation diagnosis, not reinstall. First split: Does Claude Code run? Am I authenticated? Is it a project-specific setting? Is it an extension like MCP, hook, or plugin?

The most important commands are:

claude --version / claude doctor / /status / /doctor / /context / /permissions / /mcp / /hooks / /plugin / /debug

By problem type:

Core takeaways (continued)

Installation problem: Check PATH, duplicate installs, network, permissions
Authentication problem: claude auth status, logout/login, check ANTHROPIC_API_KEY
Permission problem: /permissions, check settings scope
Command failure: Separate Claude permission issue from project command issue
Performance problem: /context, /compact, /clear
Search problem: Check ripgrep and WSL file location
MCP problem: /mcp, claude mcp get, check .mcp.json location
Hook problem: /hooks, check matcher, exit code, --debug hooks
Plugin problem: /plugin, /reload-plugins, claude --debug
Unknown problem: Compare with clean session

Core

Good debugging isn't fixing every problem immediately — it's narrowing the problem scope quickly. As Claude Code grows more complex, /doctor, /status, /context, and clean session comparison become your most powerful fundamentals.

29. How to safely use Claude Code in a team

01Core concepts

This unit focuses on team operations, security, costs, and review systems rather than individual productivity. While personal use of Claude Code prioritizes convenience, team use emphasizes "who can execute what with which permissions," "what settings should be shared and what should remain personal," and "how should we review AI-generated changes."

Section 29 in the comprehensive guide is designed to cover separating shared and personal settings, permission policies, cost management, review and approval workflows, and writing team CLAUDE.md.

02"Consistency and safety," not "speed"

When individuals use Claude Code, these are important:

Finding files quickly
Editing quickly
Running tests quickly
Getting reviews quickly

In a team, these are added:

Do all team members follow the same rules?
Are sensitive files blocked from reading or modification?
Are dangerous bash commands restricted?
Are AI-generated code changes reviewed by humans?
Are costs and token usage monitored?
Are only trustworthy MCPs, hooks, and plugins used?

Official security documentation recommends reviewing proposed commands before approval when using Claude Code, confirming important file changes, and considering isolated environments like VMs when dealing with external web services or scripts. MCP servers should come from trusted providers or be self-written, and access can be restricted through permission settings.

03Five things to decide first in a team

When introducing Claude Code to a team, establish operating principles before enabling features.

Settings scope

What to enforce team-wide and what to leave as personal settings

Permission policy

Which files and commands to allow, ask about, or block

Review workflow

How and who reviews AI-generated changes

Cost criteria

How to manage model, context, subagent, and MCP usage

Extensions

Who reviews and deploys hooks, MCP, skills, and plugins

04Five minimum things to decide

Beginning teams don't need to build all enterprise-grade policies from the start. But at minimum, decide on these:

1. Never read or modify .env, credentials, or secrets.
2. Large changes always start with /plan.
3. AI-generated changes go through git diff and tests.
4. main branch pushes and production deploys are never auto-approved.
5. Team common rules go in CLAUDE.md and .claude/settings.json.

05Separating shared and personal settings ①

The first principle of team operations is separating what to share from what not to share.

According to official configuration documentation, Claude Code uses a hierarchical settings.json structure. User settings go in ~/.claude/settings.json, project settings shared with the team in .claude/settings.json, and personal experiments or preferences in .claude/settings.local.json. .claude/settings.local.json is automatically git-ignored on creation, making it ideal for personal settings. Organization-level managed settings cannot be overridden by user or project settings.

06Separating shared and personal settings ②

The scope and purpose of configuration files are as follows:

~/.claude/settings.json

User-wide, not committed, personal default settings

.claude/settings.json

Current project team-wide, committed, team common permission, hooks, environment rules

.claude/settings.local.json

Current project personal, not committed, personal experiments, local paths, preferences

managed settings

Organization-wide, deployed by admin, enforced company security policy

07Settings separation rules for beginning teams

Beginner teams can divide them this way:

All team members must follow → .claude/settings.json
Only I use → .claude/settings.local.json
I use in all projects → ~/.claude/settings.json
Security team must enforce → managed settings

The uploaded documentation also identifies anti-patterns: "putting all settings in user settings" and "committing personal preferences." Team standards should go in project settings and personal settings in settings.local.json.

08Team common .claude/settings.json example ①

It's important not to allow team common settings too broadly.

The basic structure of the .claude/settings.json file is as follows:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(npm test:*)",
      "Bash(npm run test:*)",
      "Bash(npm run lint:*)",
      "Bash(npm run build:*)",
      "Edit(src/**)",
      "Edit(tests/**)",
      "Write(src/**)",
      "Write(tests/**)"
    ],

09Team common .claude/settings.json example ②

    "ask": [
      "Bash(npm install:*)",
      "Bash(pnpm add:*)",
      "Bash(yarn add:*)",
      "Bash(docker:*)",
      "WebFetch"
    ],
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(secrets/**)",
      "Read(config/credentials*)",
      "Read(**/*secret*)",
      "Read(**/*token*)",
      "Edit(.env)",
      "Edit(.env.*)",
      "Edit(secrets/**)",
      "Edit(.git/**)",
      "Edit(package-lock.json)",
      "Write(.env)",
      "Write(.env.*)",
      "Write(secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Bash(chmod 777:*)",
      "Bash(git push --force:*)",
      "Bash(git push origin main:*)",
      "Bash(kubectl delete:*)",
      "Bash(terraform apply:*)"
    ]
  }
}

The goal of this configuration is "allow Claude to handle everyday development needs like reading, searching, testing, linting, and building, but block sensitive files and dangerous commands."

10What to put in personal settings

Don't put personal preferences in team common settings. For example, these are better in personal settings:

My preferred output style
My favorite model
My local machine paths
My personal MCP servers
My personal experimental hooks
My color and terminal display settings

.claude/settings.local.json example:

{
  "outputStyle": "Explanatory",
  "env": {
    "DEBUG": "app:*"
  }
}

11What should NOT go in configuration files

Examples of what should not go in team common settings:

{
  "env": {
    "DATABASE_URL": "postgres://user:password@localhost:5432/mydb",
    "GITHUB_TOKEN": "ghp_xxx"
  }
}

Sensitive information should not be placed directly in configuration files, but instead separated through shell environment, secret managers, OAuth, or MCP authentication flows.

12When is managed settings needed?

Small teams can start with .claude/settings.json alone. But managed settings are needed in these situations:

Developers cannot bypass security policy through local settings
MCP server allowlists must be managed centrally
Only approved hooks can be executed
Same permission policy must be enforced across the entire company
SSO, compliance, and audit requirements exist

According to official documentation, managed settings can be deployed through Anthropic servers, macOS MDM managed preferences, Windows registry, or file-based system directories, and user and project settings cannot override them.

13Organization managed settings example

Security or platform teams can establish minimum policies like this:

/etc/claude-code/managed-settings.json

{
  "permissions": {
    "deny": [
      "Read(**/.env*)",
      "Read(**/secrets/**)",
      "Read(**/credentials/**)",
      "Read(**/*.pem)",
      "Read(**/*.key)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Bash(git push --force:*)",
      "Bash(kubectl delete:*)",
      "Bash(terraform apply:*)"
    ]
  },
  "disableBypassPermissionsMode": true,
  "allowedMcpServers": ["github", "sentry", "linear"],
  "deniedMcpServers": ["untrusted-browser", "unknown-db"]
}

This example blocks files and commands the company will never allow at the organizational level and manages MCP servers with an allowlist-centric approach.

14Permission policy design: deny first

When creating team permission policies, start with "what must we absolutely block?" rather than "what should we allow?"

.env, .env.*

May contain API keys, DB URLs, tokens

secrets/**

May contain certificates, keys, credentials

.git/**

Risk of corrupting repository internals

package-lock.json and other lockfiles

Risk of unintended dependency changes

rm -rf, sudo, chmod 777

Destructive commands

git push --force

Corrupts remote history

Production deploy commands

Risk of operational failure

Cloud resource deletion commands

Risk of infrastructure damage

15Standards by permission mode

The situations for each permission mode in a team are as follows:

New employees, beginners

default

Small edits on familiar projects

acceptEdits possible

Large refactoring plans

plan

Sensitive code, payments, auth, infrastructure

plan or manual approval

CI automation

Limited headless execution

Operations deployment, DB migration

Never auto-approved

Teams can adopt these basic rules:

Large changes → plan
Sensitive areas → plan
File modifications → approve before execution
Bash execution → verify command before approval
Operational impact → never Claude alone

16Dangerous Bash command policy

Teams should not use overly broad Bash allowlist rules.

Bad example:

{
  "permissions": {
    "allow": ["Bash(*)"]
  }
}

Good example:

{
  "permissions": {
    "allow": [
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Bash(npm run build:*)"
    ],
    "ask": ["Bash(npm install:*)", "Bash(docker:*)"],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Bash(git push --force:*)",
      "Bash(kubectl delete:*)",
      "Bash(terraform apply:*)"
    ]
  }
}

17Creating team quality gates with hooks

In a team, automating with hooks is more stable than "asking Claude to format every time."

For example, run prettier after file modifications:

.claude/hooks/format-edited-file.sh

#!/usr/bin/env bash
set -euo pipefail

input="$(cat)"
file_path="$(echo "$input" | jq -r '.tool_input.file_path // empty')"

case "$file_path" in
  *.js|*.jsx|*.ts|*.tsx|*.json|*.md|*.css)
    npx prettier --write "$file_path"
    ;;
esac

18Setting up hooks in settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format-edited-file.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

Official hooks documentation notes that hooks scoped to .claude/settings.json apply to a single project, can be committed to the repo for sharing, and this enables team-wide automation.

19Monitoring setting changes with ConfigChange hook

Particularly important in teams is when settings change during a session. Official security documentation presents team security best practices as: using managed settings, sharing approved permission configurations through version control, training team members, monitoring usage through OpenTelemetry metrics, and using ConfigChange hooks to audit or prevent mid-session configuration changes.

For beginners, the policy is:

Team common setting changes → PR review
Personal setting changes → settings.local.json
Permission relaxation changes → security review
MCP server additions → team review
Hook additions → script content review
Plugin additions → component verification before install

20MCP operated as "allowlist"

MCPs are powerful but connect to external systems, so they require the most caution in team operations.

When adding an MCP to your team, document the following:

Server name

What MCP server is it

Provider

Official, internal, or verified community

Permissions

Read-only or write-capable

Data scope

Which repos, issues, DBs, logs it accesses

Authentication

OAuth, token, env, or secret manager

Storage location

Local, project, user, or managed

Removal method

How to disable if issues occur

21Team .mcp.json example

If you want your team to use only GitHub and Sentry, you can manage them at project scope:

.mcp.json

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

Don't put actual tokens in .mcp.json; separate them with environment variables. Share only the structure with the team repository, never commit personal tokens or operational credentials.

22Sharing skills and project knowledge

Instead of putting all repeated domain rules in CLAUDE.md, separate them as skills.

For example, create a skill for API implementation rules:

.claude/
└── skills/
    └── api-conventions/
        └── SKILL.md

The uploaded documentation notes that project skills are committed to git, so team members automatically get them with a pull, and this standardizes specialized knowledge across the entire team.

23Role separation between CLAUDE.md and skills

Good practice divides short basic rules in CLAUDE.md and specific task procedures in skills:

Always-needed short rules

CLAUDE.md

API implementation procedures

skill

Security review checklist

skill

Deployment procedures

Direct invocation skill only

Repeated review work

subagent

Team deployment package

plugin

24How to write CLAUDE.md for a team

Team CLAUDE.md is not better the longer it is. Since it's read every session, it must be short and clear.

Good CLAUDE.md structure looks like this:

# Project Guide for Claude Code

## Project overview
This repository contains the web application and API for the product.

## Commands
- Install: `npm install`
- Test: `npm test`
- Lint: `npm run lint`
- Build: `npm run build`

## Coding rules
- Use TypeScript strict mode.
- Keep business logic in `src/services`.
- Keep route handlers thin.
- Add tests for behavior changes.
- Do not introduce new dependencies without approval.

## Security rules
- Never read or edit .env, credentials, secrets, private keys.
- Do not print tokens, API keys, customer data.
- Ask before changing auth, billing, permissions, migrations, deployment.

## Workflow rules
- For large changes, use /plan before editing.
- After editing, run relevant tests and lint.
- Before final answer, summarize changed files and risks.

25What NOT to put in CLAUDE.md

Don't put these in CLAUDE.md:

API keys, tokens, passwords

Sensitive information exposure

Very long architecture documentation

Wastes context

Every style rule detail

Separate into skill or documentation link

Personal preferences

Enforced on team members

Uncertain rules

Claude may apply incorrectly

Deployment commands that should never run

May cause automation misunderstanding

The uploaded documentation also notes that putting all information in CLAUDE.md wastes session context every time, so keep it under 500 lines.

26Creating review and approval workflows

In a team, AI-generated code should be reviewed at the same level as human-written code. The basic flow is:

1. Clarify requirements
2. Write modification plan with /plan
3. Human approves plan
4. Claude makes minimal changes
5. Run tests, lint, build
6. Review changes with /diff or git diff
7. Run /code-review or security-review
8. Human reviews PR
9. Merge after CI passes

Large changes must maintain an "explain → plan → approve → execute → verify" flow.

27Team PR rule example

Add Claude Code usage and verification items to team PR template:

.github/pull_request_template.md

## Summary
Describe what changed.

## Claude Code usage
- [ ] Claude Code was not used
- [ ] Claude Code was used for exploration only
- [ ] Claude Code suggested code changes
- [ ] Claude Code generated or edited code

## Verification
- [ ] I reviewed the full diff manually
- [ ] I ran tests
- [ ] I ran lint
- [ ] I ran build, if relevant
- [ ] I checked for secrets or credentials
- [ ] I checked security-sensitive changes

## Risk areas
- Auth / permissions:
- Billing / payments:
- Database / migrations:
- Deployment / infrastructure:
- Customer data:

There's no need to automatically reject AI-generated code. But the procedure "AI changes reviewed by humans" must be clear.

28Separate approval for security-sensitive changes

The following areas always require additional review:

Authentication

Account hijacking, session handling issues

Authorization

Privilege escalation risk

Billing

Financial loss, regulatory issues

Personal information

Data breach risk

DB migration

Possible data loss

Infrastructure

Service disruption possible

Deployment scripts

Operational impact

Encryption, tokens

Security boundary damage

29Security-sensitive change prompt example

Clear prompts are important:

This change is about authentication code.

Conditions:
- Don't modify immediately, start with /plan
- Organize security risks in a separate section
- Check for missing permission checks
- Include test plan
- Don't modify files until I approve

30Cost management principles

In a team, Claude Code costs should be viewed as "which work patterns increase costs?" rather than "how much does one person use?"

Official cost documentation notes that Claude Code costs are based on API token consumption, and for team cost management, recommends /usage, context management, model selection, extended thinking adjustment, and reducing MCP overhead.

Common patterns that increase team costs are:

Continuing long sessions

Context cost increases

Pasting entire logs

Unnecessary token increase

Reading whole PDFs or large documents

Context explodes

Using highest model for every task

Cost increase

Spawning subagents/agent teams carelessly

Parallel token cost increases

Loading too many MCP server tools

Tool description uses context

CLAUDE.md is too long

Base cost increases every session

31Team cost monitoring method

Individual developers verify in their sessions:

/usage
/context

Team managers use analytics and monitoring. According to official analytics documentation, Claude for Teams and Enterprise provide usage metrics, contribution metrics, leaderboard, and CSV export.

Official monitoring documentation explains that the claude_code.cost.usage metric shows team or individual usage trends, high-usage sessions, and cost attribution by skill, plugin, and agent type.

32Team rules to reduce costs

1. Start new work with /clear.
2. Long sessions use /compact.
3. Save logs to files and request summaries only.
4. Read only the needed range from large documents.
5. Separate repeated rules as skills, not in CLAUDE.md.
6. Delegate test log analysis to subagents.
7. Connect only necessary MCP servers.
8. Use high effort and higher models only for difficult design.

The uploaded documentation also recommends aggressively using /compact in long sessions and using cheaper models for subagents and simple tasks.

33Team authentication and account operations

There are four main ways to use Claude Code in a team:

Claude for Teams

Small teams, central billing and team management needed

Claude for Enterprise

SSO, domain capture, role-based permissions, managed policy needed

Claude Console

Teams preferring API-based billing

Bedrock / Vertex AI / Foundry

Organizations using existing cloud governance

Official IAM documentation presents Claude Code access methods for teams and organizations. Teams are self-service plans suitable for collaboration, admin tools, and billing management, while Enterprise provides SSO, domain capture, and role-based permissions.

34Sharing data usage and security explanation

The most common team member question is "Is our code used for training?"

According to official data usage documentation, Free, Pro, and Max consumer plans allow users to opt in to model improvement data usage, but commercial users like Team, Enterprise, API, and third-party platforms do not have customer code or prompts sent to Claude Code used for generative model training unless customers separately choose to provide them for model improvement.

In team training materials, write it like this:

- Company code is used only under approved accounts and organization policy.
- Don't analyze company repos from personal accounts.
- Check transcripts for sensitive information before using /feedback.
- Block reading and modification of sensitive files with permissions.deny.
- Only use approved MCP servers from the allowlist.

35Team member onboarding checklist

Before new team members use Claude Code, verify:

1. Logged in with approved authentication method
2. claude --version verified
3. claude doctor verified
4. Running claude from repository root
5. /status shows correct settings source
6. /permissions shows expected permission policy
7. /mcp shows connected MCP servers
8. /usage shows cost display is understood
9. Read CLAUDE.md
10. First practice with small read-only task

36Onboarding first practice

Start first practice with read-only, not modification tasks:

Read this project structure and
summarize the main directories and test commands.
Don't modify files.

Then move to small edits:

/plan add a small validation test for the login form

37Team standard workflow example

Fix everyday development flow like this:

1. claude -c or start new session
2. /status
3. /context
4. Describe work
5. Large work → /plan
6. Approve then edit
7. Tests, lint, build
8. /diff
9. /code-review
10. Create PR

Prompt example:

I want to add login form validation.
Team rules:
- /plan before editing
- No new dependencies
- Keep existing response format
- Add related tests
- Run npm test and npm run lint after
- Summary of changed files and risks at the end

38How to handle auto-accept in a team

acceptEdits and auto-accept are convenient, but teams need clear standards.

Documentation typo fixes

Possible

Small test file additions

Possible

src code modifications

Case-by-case

Auth, billing, permission code

Not recommended

DB migration

Not recommended

Deployment, infrastructure code

Prohibited

Lockfile changes

Manual review

secrets, env, credentials

Prohibited

39AI-generated code attribution policy

Different teams may have different AI usage attribution policies. At minimum, it's good to keep this internally:

Claude Code usage in PR description
What work used it for
What humans reviewed
Test results
Security-sensitive areas

Whether to enforce AI usage labels in commit messages depends on team policy. What matters most is "attribution responsibility" not "labeling itself."

Even if AI suggested it, the merge responsibility is human.

40Standardizing review prompts for a team ①

Frequently used review prompts in a team should be standardized as skills or commands.

Example:

Review the current diff by team standards.

Focus on:
1. Actual bugs
2. Security issues
3. Missing tests
4. Excessive changes
5. Maintainability

Exclude:
- Personal preferences
- Simple style debates
- Issues lint already handles

Output:
- Critical
- Warning
- Suggestion
- Tests to add

41Standardizing review prompts for a team ②

This prompt can be separated as .claude/skills/review-checklist/SKILL.md:

---
description: Team code review checklist. Use when reviewing diffs, PRs, or completed code changes.
---

Review changes for correctness, security, tests, and maintainability.

Do not focus on style issues handled by lint.

Return findings in this format:
- Critical
- Warning
- Suggestion
- Tests to add

42Standardizing security review prompts

Security-sensitive changes need a separate review prompt:

Review this diff from a security perspective.

Focus on:
- Authentication bypass
- Missing permission checks
- Missing user input validation
- SQL injection possibility
- IDOR possibility
- Sensitive information in logs
- Token/session handling issues
- File upload risks
- Billing/permission boundary damage

Organize results by severity, file path, reasoning, and fix suggestions.
Don't modify files.

Teams can create this as a security-reviewer subagent or skill for reuse.

43Review criteria when deploying hooks in a team

Hooks can execute shell commands, so they're code review subjects.

Hook PR checklist:

- Which event triggers it
- Matcher not too broad
- Command is safe
- Doesn't print sensitive info to stdout/stderr
- File paths quoted
- Exit code 2 used intentionally
- Not overly dependent on local environment
- Doesn't excessively block dev workflow on failure

Official hooks documentation notes that matchers can be exact string lists or regex, and team hooks are safer when attached only to needed tools and events rather than broad matchers.

44Review criteria when installing plugins in a team

Plugins can include skills, agents, hooks, and MCPs, so verify components before installing.

Review items:

1. Which skills are added
2. Which agents are added
3. Which hooks execute
4. Which MCP servers connect
5. External network access
6. Shell command execution
7. Credential requirements
8. Conflicts with team policy

Instead of freely opening the plugin marketplace, teams should operate with an approved marketplace or internal marketplace focus.

45Cost and permission criteria for subagents and agent teams

Subagents are good for separating context and delegating exploration, but overuse in teams increases costs and review complexity.

The uploaded documentation notes that subagents suit focused work that just reports results, while agent teams where multiple teammates directly message and coordinate through shared task lists cost more.

Team rule examples:

- Log analysis, security review, test failure summary can use subagents
- 3+ parallel subagent executions need justification
- Agent teams only for large refactoring or PR review with clear purpose
- Subagents with edit permission restricted to least privilege
- Security review subagents read-only by default

46Policy by repository risk level

The same policy doesn't apply to every repository. Vary by risk level:

Documentation repo

Use relatively freely

Frontend app

Allow general code changes, manual deployment setting review

Backend API

Manual review of permission, DB, auth changes

Payment system

Plan Mode and security review required

Infrastructure repo

Never auto-approved

Data pipeline

Restrict data access and log output

Experimental repo

Sandbox or low permission policy

Production hotfix repo

Very strict change scope and approval

47Team policy document example ①

docs/claude-code-policy.md

# Claude Code Team Policy

## Allowed use
Claude Code may be used for:
- code exploration
- implementation planning
- test generation
- refactoring suggestions
- documentation updates
- code review assistance

## Restricted use
Do not use Claude Code to:
- read or modify secrets
- execute production deployment
- run destructive infrastructure commands
- change database migrations without review
- push directly to main
- bypass code review

48Team policy document example ②

## Required workflow
For non-trivial changes:
1. Start with /plan.
2. Review the plan.
3. Apply minimal changes.
4. Run tests and lint.
5. Review git diff.
6. Create a PR.
7. Get human approval before merge.

## Sensitive areas
Extra review is required for:
- authentication
- authorization
- billing
- customer data
- migrations
- infrastructure
- deployment

Reference this document from CLAUDE.md:

## Team policy
Follow `docs/claude-code-policy.md`.

49Minimum file structure for team operations

Beginning teams can start safely with this structure alone:

repo/
├── CLAUDE.md
├── docs/
│   └── claude-code-policy.md
├── .claude/
│   ├── settings.json
│   ├── skills/
│   │   ├── review-checklist/
│   │   │   └── SKILL.md
│   │   └── api-conventions/
│   │       └── SKILL.md
│   └── hooks/
│       ├── format-edited-file.sh
│       └── protect-files.sh
├── .mcp.json
└── .github/
    └── pull_request_template.md

Role of each component:

CLAUDE.md

Short project basic rules

docs/claude-code-policy.md

Team operations policy

.claude/settings.json

Team common permissions, hooks

.claude/skills/

Team repeated knowledge

.claude/hooks/

Auto formatting, security blocking

.mcp.json

Team common MCP structure

PR template

AI change review procedure

50Team adoption order

Don't enable all features from the start:

Phase 1: Write CLAUDE.md
Phase 2: .claude/settings.json blocks sensitive files
Phase 3: Add Claude Code usage to team PR template
Phase 4: Train /plan, /diff, /usage, /permissions
Phase 5: Pilot with 5-10 team members
Phase 6: Verify costs and review quality
Phase 7: Add formatter and protection hooks
Phase 8: Add read-focused MCPs like GitHub/Sentry
Phase 9: Standardize skills and subagents
Phase 10: Deploy managed settings and plugins if needed

The uploaded documentation also recommends starting a pilot with 5-10 developers before full deployment in the enterprise architect guide.

51Key commands for team member education

/status

Check current account, model, settings source

/permissions

Check which tools and commands are allowed

/usage

Check cost and usage

/context

Check if context is building up excessively

/compact

Clean up long sessions

/clear

Start new work

/plan

Plan before editing

/diff

Review changes

/code-review

Review changes

/mcp

Check external tool connection status

/hooks

Check automation hooks

/doctor

Diagnose issues

Start with these commands rather than teaching every advanced feature.

52Forbidden prompt examples in a team

These requests should be blocked or at least require manual review under team policy:

Forbidden prompts:

Fix everything automatically without permission.
If tests fail, fix everything and push automatically.
Read .env file, connect to DB, and find the root cause.
Deploy directly to production.
Run terraform apply.

Instead, change them like this:

Just plan before editing.
Don't read sensitive files.
Suggest related tests and verification method first.
Don't modify files until I approve.

53Recommended prompt examples for a team ①

Adding a feature

I want to add a new feature.

Start with /plan.
Conditions:
- Examine only relevant files
- Minimize change scope
- No new dependencies
- Include test plan
- Separate security impact
- Don't edit until I approve

54Recommended prompt examples for a team ②

Fixing a bug

Before fixing this bug, investigate possible root causes.

Conditions:
- No file modifications
- List only relevant files and evidence
- Show 1-3 most likely root causes
- Suggest test commands to verify

Review

Review the current diff by team standards.

Focus on:
- Actual bugs
- Security risks
- Missing tests
- Excessive changes
- Maintainability

Exclude style preferences.

55Incident response procedures

If incorrect changes from Claude Code are introduced or sensitive information exposure is suspected, immediately:

1. Stop the session
2. Check git status / git diff
3. Check if sensitive information was output, committed, or logged
4. Immediately rotate related tokens
5. Revert incorrect commits
6. Restrict PR or branch access
7. Check transcript for sensitive info before using /feedback
8. Review settings, hooks, permissions
9. Add policies to prevent recurrence

The important thing in security incident response is "why did Claude do that" less than "which permission and settings allowed it."

56Team maturity-based operations model

Phase 1

Individual use, basic permission, manual review

Phase 2

Team CLAUDE.md, project settings, PR template

Phase 3

Hooks, skills, MCP allowlist

Phase 4

Managed settings, analytics, OTel monitoring

Phase 5

Internal plugins, approved MCP catalog, enterprise rollout

Beginning teams only need to reach Phase 2:

CLAUDE.md
.claude/settings.json
PR template
/plan and /diff habits

These four things come first.

57Team operations checklist · Before adoption

Things to verify before adoption:

- Decide authentication method
- Write team CLAUDE.md
- Set sensitive file deny
- Set dangerous Bash command deny
- Update PR template
- Train /plan, /diff, /usage

Things to verify during pilot:

- Track costs
- Check frequently asked permissions
- Collect project rules Claude confuses frequently
- Remove excessive content from CLAUDE.md
- Separate repeated prompts as skills

58Team operations checklist · Before scaling and during operations

Things to verify before scaling:

- Finalize MCP allowlist
- Review hooks scripts
- Finalize plugin installation criteria
- Decide if managed settings needed
- Set up analytics or OTel monitoring

Things to regularly check during operations:

- /permissions regular check
- MCP server regular check
- Check cost spikes
- Sample review security-sensitive PRs
- Update team policy documentation

Section 29 · Wrap-up

How to safely use Claude Code in a team

To safely use Claude Code in a team, treat it not as a personal productivity tool but as team development infrastructure. The key is separating shared and personal settings, blocking sensitive files and dangerous commands, and creating a workflow where humans review AI-generated changes.

The most important standard is:

Team common rules → CLAUDE.md, .claude/settings.json / Personal preferences → .claude/settings.local.json / Organization enforcement → managed settings

The minimum set a beginning team needs when starting:

1. Short CLAUDE.md
2. Safe .claude/settings.json
3. PR template
4. /plan → edit → test → /diff → review workflow
5. Deny sensitive files and dangerous commands

Key point

Following these five practices alone allows you to use Claude Code much more safely and consistently in your team.

30. Advanced Features Roadmap and Quick Reference

01From now on it's not "learn everything" but "pull out when you need it"

The core fundamentals that beginners absolutely need to know to use Claude Code well have already been covered in previous sections. Below are the key areas we've learned so far.

Basic execution · Reading files · Plan Mode
Editing and running commands · CLAUDE.md · settings.json
permissions · Git diff · Model·cost·context
Testing·lint·build · slash command · hooks
MCP · subagents · skills/plugins
IDE · debugging · team management

Most of the features covered in Section 30 are in the "advanced entry" zone. You don't need to use all of them right now. Instead, you can understand them by the criteria below.

02Reference table for pulling up when you need it

The advanced features in Section 30 can be looked up "when needed" based on the following criteria.

I want to send long-running work outside the terminal

Background agents

I want to manage multiple Claude Code sessions on one screen

Agent View

I want to delegate coding tasks from web or mobile

Claude Code on the web

I need to run large-scale work with dozens to hundreds of agents

Dynamic workflows

I want to enforce company-wide policies and security

Enterprise deployment

I'm curious about the latest feature changes

/release-notes, changelog

I want to quickly see only the commands I use every day

Quick reference

03Advanced Features Roadmap

The natural progression from beginner to advanced user follows this order.

Stage 1: CLI basics
Stage 2: Plan Mode + Git diff + testing
Stage 3: CLAUDE.md + permissions
Stage 4: /usage + /context + /compact
Stage 5: hooks + MCP
Stage 6: subagents + skills
Stage 7: IDE + team management
Stage 8: background agents + Agent View
Stage 9: Claude Code on the web
Stage 10: dynamic workflows
Stage 11: enterprise managed settings + monitoring

You don't need to jump straight to stages 8-11. Most real productivity gains already come from stages 1-7. Stages 8 and beyond are expansion features you use when "your work scale grows."

04Background Agents: Sending Long-Running Work to the Background

Background agent is a feature that keeps a Claude Code session running in the background without tying it to your terminal. /background [prompt] or /bg detaches the current session as a background agent, freeing up your terminal, and you can monitor it later with claude agents. /exit detaches (rather than terminates) the session when you're attached to a background session, and /stop stops an attached background session.

Basic usage example:

/background Investigate the full test failure and summarize it for me.

Or start directly from terminal:

claude --bg "investigate the flaky test and summarize likely causes"

--bg starts the session as a background agent and immediately prints the session ID and management commands. Combined with --exec, you can run a shell command as a background job instead of a Claude session.

claude --bg --exec 'pytest -x'

05Distinguishing between background bash and background agent

They look similar but serve different purposes.

Background bash

Run long shell commands in the background — npm test, pytest, docker build

Background agent

Run entire Claude Code session in background — bug investigation, PR review, documentation generation

Claude Code can run bash commands in the background and returns a background task ID immediately. You can press Ctrl+B to send a running Bash tool invocation to the background. tmux users may need to press Ctrl+B twice due to prefix key conflicts.

Only long test commands in background → background bash
Delegate long investigation to Claude → background agent
Manage multiple tasks simultaneously → Agent View

06Agent View: Manage Multiple Background Sessions on One Screen

Agent View is an operations interface for viewing multiple Claude Code background sessions on one screen. Running claude agents opens Agent View, where you can see whether each session is running, waiting for input, or completed. Each background session continues to run as a single Claude Code conversation, even without being attached to a terminal.

claude agents

Dispatch new work

Enter a prompt in the input field to start a new background session

Check status

View Working, Needs input, Completed, etc.

peek

Check recent output without entering the full session

Provide only needed responses from within Agent View

attach

Enter the full conversation of a specific session

detach

Return to Agent View

Run shell job

Execute background shell job with ! <command>

When you enter a prompt, a new background session is created. If you enter another prompt, it doesn't send a follow-up to the existing session but starts a new session in parallel. You can send multiple tasks simultaneously, but each session uses quota independently.

07When to use Agent View

Agent View is suitable for these situations.

You want to investigate 3 bugs separately.
You want to delegate PR review, test failure analysis, and documentation updates simultaneously.
You want to throw a long task and just check status occasionally.
You want to manage background sessions without opening multiple terminal windows.

Example prompts:

Investigate why login tests are flaky.

Review the current PR for security risks.

Find outdated API docs and propose updates.

Agent View is a research preview that requires Claude Code v2.1.139 or later, and its interface and shortcuts may change as features evolve. Don't treat Agent View itself as a quality gate in team operations—final validation should still be based on tests, diff review, PR review, and hook results.

08Claude Code on the web: Delegate Coding Tasks to the Cloud

Claude Code on the web is a research preview feature for delegating coding tasks from your browser. Tasks run on Anthropic-managed cloud infrastructure and are available to Pro, Max, Team users and Enterprise premium seat or Chat + Claude Code seat users. Sessions persist even after closing the browser, and you can monitor them from the Claude mobile app.

Quick bug fixes on the go

Well-suited

Parallel processing of multiple repos' backlogs

Well-suited

Automatic GitHub PR generation

Well-suited

Local environment, custom hooks, MCP are critical

Terminal is better suited

Need access to sensitive local files

Terminal or approved enterprise environment

Complex architecture discussions

Terminal/IDE is more stable

Official web documentation covers cloud environment, setup scripts, network access, Docker, session management, PR auto-fix, and terminal-web transition features like --remote and --teleport.

09Moving Between Terminal and Web

/teleport or /tp brings a Claude Code on the web session to your current terminal, and /remote-control or /rc makes a local session remotely controllable from claude.ai. /web-setup connects your GitHub account to Claude Code on the web using your local gh CLI credentials.

Common workflow:

claude --remote "fix the failing CI on this branch"

/teleport

/remote-control

web

Delegate work from browser/mobile

terminal

Maximize local environment and extension layer

teleport

Bring web session to terminal

remote-control

Control local session from another device

10Dynamic Workflows: Orchestrating Dozens to Hundreds of Agents

Dynamic workflows are an advanced feature for orchestrating subagents at scale. A dynamic workflow is a JavaScript script written by Claude that coordinates multiple subagents, which the runtime executes in the background. It's ideal for tasks like codebase audits, large-scale migrations, and research that requires cross-validation, which would be difficult for a single conversation to directly coordinate.

Dynamic workflows are a research preview and require Claude Code v2.1.154 or later. They're available on all paid plans, Anthropic API access, Bedrock, Vertex AI, Microsoft Foundry, and on Pro you need to enable them in Dynamic workflows row of /config.

11Difference Between Workflow and Subagent

The difference between subagents, skills, and workflows can be explained by "who decides the next step."

Identity

Subagent=worker Claude calls · Skill=knowledge/procedure Claude follows · Workflow=script the runtime executes

Plan storage location

Subagent/Skill=Claude conversation flow · Workflow=workflow script

Intermediate results

Subagent=return to Claude context · Skill=stay in Claude context · Workflow=stay in script variables, only final result can be returned

Reusability

Subagent=reuse agent definition · Skill=reuse instruction · Workflow=rerun orchestration itself

Scale

Subagent=delegate a few tasks · Skill=per-task procedure · Workflow=dozens to hundreds of agents

Subagent and skill are coordinated turn-by-turn by Claude, but workflow runs scripts with loop, branching, and intermediate result handling. Therefore, only the final answer remains in Claude's context.

Small delegation → subagent · Repeated procedure → skill · Large-scale parallel orchestration → workflow

12Workflow Execution and Monitoring

Claude Code has a built-in /deep-research workflow, and during workflow execution you can view progress with /workflows. The /workflows view shows agent count per phase, token total, and elapsed time. You can drill down by phase or agent to see prompt, tool call, and result.

/deep-research What changed in the Node.js permission model between v20 and v22?

/workflows

If you want to create your own workflow, you can request it by including the word workflow in your prompt.

Create a workflow to audit all API endpoints for missing authorization checks. Do not edit files. Return a prioritized report with file paths and evidence.

Or you can enable /effort ultracode. ultracode is a setting that combines xhigh reasoning effort and automatic workflow orchestration. It uses more tokens and time, so when returning to routine work, it's good to lower it with /effort high.

13Cautions When Using Workflows

Workflows are powerful but shouldn't be overused by beginners.

Cost can grow

Many agents run simultaneously

Results need validation

Large-scale automated investigation can have errors

Mid-run user input limited

Separate workflow better for step-by-step approval

Need to read the script

Critical work requires reviewing raw script

Team policy enforcement needed

Enterprise can disable them

Overkill for small tasks

Subagent or regular conversation is faster

Workflows have limits like maximum 16 concurrent agents, up to 1,000 agents per run. The workflow itself doesn't directly access filesystem or shell—agents handle reading, writing, and execution. Also, since many agents are spawned, meaningful token usage can be significantly higher than processing the same task in conversation.

14Enterprise Deployment Roadmap

As team size grows, personal settings and project settings alone aren't enough. At the Enterprise stage, centralized policy, security controls, cost monitoring, and audit logs become important. Organization admins can set permission rules, sandboxing, managed policy CLAUDE.md, MCP server control, plugin marketplace control, customization lockdown, hook restrictions, Agent View disabling, and minimum version policy.

Authentication

SSO, organization accounts, provider choice

Policy

managed settings

Permissions

allow, ask, deny, block bypass

Sandbox

filesystem/network isolation

MCP

allow/block server list

Plugins

allowed marketplace and internal plugin

Hooks

whether to allow only managed hooks

Agent View

whether to allow background agents

Cost

OTel, analytics, usage dashboard

Data

retention, training, compliance

15Features That May Need to Be Disabled in Enterprise

Not all advanced features suit all organizations. The official settings documentation includes policy items like disableAgentView to turn off background agents and Agent View, disableRemoteControl to prevent remote control, disableSkillShellExecution to prevent skill shell execution, and disableWorkflows to turn off workflows.

{
  "disableAgentView": true,
  "disableRemoteControl": true,
  "disableWorkflows": true,
  "disableSkillShellExecution": true
}

Features difficult to control by company policy should be disabled first, then establish safety standards with a pilot team before gradually enabling them.

16Monitoring Usage and Cost

For organizations, /usage alone may not be enough. Claude Code can export metrics, logs/events, and optional traces through OpenTelemetry, which can be connected to your organization's monitoring backend to track session, tool, token, and cost usage.

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
claude

At the team stage, watching these is usually enough.

Who uses it the most
Which repo has the highest cost
Which MCP/plugin/subagent drives cost
Which tool has the most errors
Are workflows or background agents over-utilized

17How to Check the Changelog

Claude Code is a fast-moving tool. So guides should fix the "current moment" as reference, but inform readers how to check the latest.

Check within session:

/release-notes

Check version from terminal:

claude --version

Update:

claude update

/release-notes opens an interactive version picker so you can view release notes for a specific version or all versions. /usage shows session cost, plan usage limits, and activity stats, and /cost, /stats are aliases for /usage.

Model names, pricing, preview features, and command names always change.
Documentation should indicate "at time of writing."
Tell readers how to check /release-notes and claude --version.

18Criteria for Reflecting Latest Features

When reading changelog, don't include every item in the guide. Select by these criteria.

High

Command name changes, security policy, default model change, permission behavior change

Medium

UI improvements, performance improvements, new slash command

Low

Internal bug fixes, platform-specific edge cases

Special note

Research preview, gradual rollout, plan-specific limits

For example, changelog v2.1.157 added .claude/skills directory plugin auto-load, claude plugin init <name>, /plugin autocomplete, and v2.1.158 added Bedrock, Vertex, Foundry Opus 4.7/4.8 auto mode opt-in. These items affect feature descriptions and become guide update candidates.

19Command Cheat Sheet (1) · Starting and Sessions

Start in current folder

claude

Start with a question

claude "explain this project"

Single query then exit

claude -p "query"

Continue recent session

claude -c

Resume specific session

claude -r "<session>"

Exit session

/exit

Start new work

/clear [name]

Select previous session

/resume

Name session

/rename auth-refactor

Branch session

/branch [name]

20Command Cheat Sheet (2) · Work Control

Plan first

/plan [description]

Check changes

/diff

Code review

Apply review findings

/code-review --fix

Cleanup-only review

/simplify

Security review

/security-review

Verify app running

/run, /verify

Undo

/rewind

Quick side question

/btw <question>

/code-review performs review for correctness bugs and cleanup perspective, and can apply findings to working tree with --fix. Since v2.1.154, /simplify has been split off as a cleanup-only review rather than finding correctness bugs.

21Command Cheat Sheet (3) · Cost·Model·Context

Check usage and cost

/usage

Older aliases

/cost, /stats

Choose model

/model

Choose reasoning effort

/effort

Fast mode

/fast

Check context usage

/context

Compress context

/compact

Start with fresh context

/clear

Session recap

/recap

/usage shows session cost, plan usage limits, and activity stats. On Pro/Max/Team/Enterprise plans, it also includes usage breakdown by skill, subagent, plugin, and MCP server. /cost and /stats are aliases for /usage.

22Command Cheat Sheet (4) · Configuration·Extensions

Check settings

/status

Settings UI

/config, /settings

Manage permissions

/permissions

Manage CLAUDE.md

/memory

Check hooks

/hooks

Check MCP

/mcp

Manage subagents

/agents

List skills

/skills

Reload skills

/reload-skills

Manage plugins

/plugin

Reload plugins

/reload-plugins

Troubleshoot

/doctor, /debug

23Command Cheat Sheet (5) · Background·Agent View·Workflow

Send current session to background

/background, /bg

View background sessions

claude agents

Stop background session

/stop

View background tasks

/tasks, /bashes

Run shell job in background

claude --bg --exec 'pytest -x'

View workflows

/workflows

Built-in research workflow

/deep-research <question>

Bring web session

/teleport, /tp

Enable remote control

/remote-control, /rc

GitHub web setup

/web-setup

24Command Cheat Sheet (6) · Files·Directories·Git

Check Git status

! git status

Check diff

! git diff or /diff

Reference file

@src/file.ts

Access additional directory

/add-dir <path>

Initialize project

/init

PR review

/review [PR]

PR autofix

/autofix-pr [prompt]

Load PR session

claude --from-pr 123

/autofix-pr can detect open PRs on the current branch and spawn a web session to fix CI failures or review comments. /review reviews PRs in a local session.

25Command Cheat Sheet (7) · Keyboard Shortcuts

Ctrl+C

Cancel current work or clear input

Esc

Stop current response/tool invocation

Ctrl+D

Exit session

Ctrl+L

Redraw screen

Ctrl+R

Prompt history search

Ctrl+B

Send running Bash to background

Shift+Tab

Cycle permission mode

Alt/Option+P

Switch model

Alt/Option+T

Toggle thinking

Ctrl+J

Line break

Keyboard shortcuts help

Ctrl+R history search searches prompts from all projects by default. You can cycle through current session, current project, and all projects with Ctrl+S. Background bash can be sent to background with Ctrl+B.

26File Structure Quick Reference

CLAUDE.md

Project base rules

.claude/settings.json

Team common settings

.claude/settings.local.json

Personal local settings

~/.claude/settings.json

User global settings

.mcp.json

Project MCP servers

.claude/skills/

Project skills

~/.claude/skills/

Personal skills

.claude/agents/

Project subagents

~/.claude/agents/

Personal subagents

.claude/hooks/

Hook scripts

.claude/workflows/

Project workflows

~/.claude/workflows/

Personal workflows

Workflows saved in .claude/workflows/ become project shared commands, and workflows in ~/.claude/workflows/ become personal commands available across all projects. If names conflict, project workflow takes priority.

27Feature Selection Quick Decision Table (1)

Explain codebase

Regular prompt + Read/Glob/Grep

Plan before large edits

/plan

Session gets long

/context → /compact

Check cost

/usage

Reuse repeated knowledge

Skill

Automate always-run task

Hook

Connect external tools

MCP

28Feature Selection Quick Decision Table (2)

Separate large exploration

Subagent

Manage multiple background tasks

Agent View

Send long task outside terminal

Background agent

Large-scale parallel investigation

Workflow

Team deployment

Plugin

Enforce organization policy

Managed settings

Troubleshoot

/doctor, /debug

29Minimum Set Worth Memorizing for Beginners

If you only memorize the absolute minimum:

Slash commands to remember:

/help · /status · /usage · /context · /compact
/clear · /plan · /diff · /code-review
/permissions · /mcp · /hooks · /agents
/skills · /plugin · /doctor · /release-notes

Terminal commands to remember:

claude
claude --version
claude doctor
claude update
claude -c
claude -p "query"
claude agents
claude mcp list
claude mcp get <name>
claude plugin list

30How to Approach Advanced Features

When learning advanced features, always start with small experiments.

Background agent

Start with safe tasks like document summarization

Agent View

Start with 2-3 read-only investigations

Workflow

Get a feel first with /deep-research

Web

Start with small PR generation

MCP

Start with read-only GitHub/Sentry

Hooks

Start with echo or formatter

Enterprise

Start with pilot team

Don't immediately jump to production deploy, DB migration, or large-scale automated fixes. Advanced features of Claude Code are powerful, but the more powerful the feature, the more permission, cost, and validation are needed.

31Final Real-World Routine (1) · Basic Routine

The most stable routine for daily development.

/status
/context
Describe task
If large, use /plan
Approve edits
Test·lint·build
/diff
/code-review
/usage
/compact or /clear

32Final Real-World Routine (2) · Large Work and Teams

For large work, extend the basic routine this way.

Use Explore subagent to investigate related areas
Use /plan to outline edits
If needed, use background agent or Agent View for parallel investigation
If truly large scale, consider workflow
After edits, run tests, lint, build
Use /code-review or /security-review
PR review

For team work, standardize this way: Check CLAUDE.md → Verify .claude/settings.json permissions → Approve /plan → Edit minimum scope → CI and human review → Separate security review for sensitive changes.

33Core Summary of This Entire Integrated Guide

Claude Code is not just a chat-based coding assistant. It's an agent-based CLI that reads codebases, edits files, runs commands, and extends through hooks, MCP, subagents, skills, plugins, and workflows. Experienced users delegate exploration and specialized work to delegation layers and configure the extension layer to match their workflow.

Configuration determines behavior.
Permissions prevent risk.
CLAUDE.md teaches project rules.
Plan Mode is a safety mechanism before large edits.
Git diff is the starting point for final verification.
Cost is managed with /usage and /context.
Hooks automate repeated work.
MCP connects external tools.
Subagents separate large explorations.
Skills reuse repeated knowledge.
Plugins are the team deployment unit.
IDE assists visual review.
Agent View and workflows are for large-scale work.
Teams require policy, permissions, review, and cost management.

34Closing

By this point, you're ready to treat Claude Code not as "just a tool that fixes code," but as a work partner that operates alongside your development workflow.

Starting out, /plan, /diff, /usage, /context, and /permissions alone are enough. Once you're comfortable, automate repeated work with hooks, connect external tools with MCP, divide large work with subagents and skills, and in teams, standardize configuration and review flow.

Final Principle

Delegate to Claude, but keep final responsibility and judgment with the developer. Good tools don't replace people—they make us work more carefully and accurately. This guide is your starting point for using Claude Code safely and confidently.

Real-world AI tools,one page at a time

Claude Code — The Complete Practical Guide

1. Understanding what Claude Code is first

01Core Concept

02What is a CLI?

03What Claude Code can do

04Claude Code's 3-layer architecture

05Core Layer

06Delegation Layer

07Extension Layer

08Actual workflow

093 reasons a good first question matters

10The most important principle for beginners

11Bug fix example

12Example prompts ① · ②

When viewing the project for the first time

When searching for a specific feature

13Example prompts ③ · ④

When getting a plan before modifying

When reviewing after changes

14Common beginner mistakes ①

Mistake 1. Saying "fix it" right away

15Common beginner mistakes ②

Mistake 2. Not verifying after file modifications

16Common beginner mistakes ③

Mistake 3. Exposing sensitive information

17Common beginner mistakes ④

Mistake 4. Assigning large tasks all at once

18Checklist

What to remember from this unit

2. Verify Pre-Installation Requirements

01Key Concepts

02Why It's Needed

03Common Pre-Installation Issues

04System Requirements

05Checking Your Environment on macOS

06Checking Your Environment in Windows PowerShell

07Checking Your Environment on Linux / WSL

08Preparing Your Terminal

09Basic Terminal Commands

10Preparing Your Account and Authentication

11Understanding Cost Potential

12Cost Optimization Habits

13Preparing Your Project Folder

14Why Run from Project Root

15Identifying Sensitive Information Files

16Protecting Sensitive Information

17Preparing Git

18Safe Workflow

19Pre-Installation Checklist ①

20Pre-Installation Checklist ②

21Common Beginner Mistakes ①

Mistake 1. Running from just any folder

22Common Beginner Mistakes ②

Mistake 2. Not checking for sensitive files

23Common Beginner Mistakes ③

Mistake 3. Modifying without checking Git status

24Common Beginner Mistakes ④

Mistake 4. Assigning large tasks without understanding costs

What to Remember from This Unit

3. Install Claude Code and Check Version

01Key Concept

02Why It Matters

03Installation Methods at a Glance

04Install on macOS

05Install on Linux / WSL

06Install on Windows PowerShell

07Install on Windows CMD

08Do I Need Git for Windows?

09Verify Installation

10Diagnose Your Environment

11Log In

12Run in Your Project Folder

13Update

14Choose Stable or Latest Channel

15Install a Specific Version

16Troubleshooting Installation Issues

Issue 1. claude: command not found

17Diagnose Issues 2 and 3

Issue 2. You mixed PowerShell and CMD commands

Real-world AI tools,
one page at a time

Issue 1. `claude: command not found`