Claude Code Guide: Features and Best Practices

Contents

1. Quick Reference Cheatsheet
2. Installation
3. Starting Claude Code
4. Using Claude Code
5. Models
6. CLAUDE.md - Providing Claude Code with Context
7. Prompting, Planning, and Execution
8. Checkpoints: Undoing Code and Context
9. Git and Version Control
10. Usage and Context Control
11. Settings and Permissions
12. Claude Plugins and Plugin Marketplaces
13. Claude Commands
14. Claude Skills
15. Claude Subagents
16. Claude MCP Servers
17. Custom Statuslines
18. Frequently Asked Questions
19. Conclusion

Quick Reference Cheatsheet

Prefixes

• ! - Bash mode prefix
• @ - Mention files/folders

Keyboard Shortcuts

• Esc+Esc - Open rewind menu (undo changes)
• Shift+Tab - Auto accept edits mode
• Shift+Tab+Tab - Plan mode

Slash Commands

• /init - Creates a CLAUDE.md file
• /login - Switch Claude accounts
• /model [model] - Sets model (optionally taking a model name)
• /usage - Spent and remaining usage
• /rewind - Open rewind menu (undo changes)
• /clear - Clears all context window
• /compact [instructions] - Compacts/summarises context (with optional compacting instructions)
• /config - Views current configuration settings
• /permissions - Views current allowed commands
• /review - Request code review
• /status - Shows status, including MCP connections
• /memory - Allows editing Claude's memory
• /plugin - Lists available and installed plugins
• /mcp - Lists connected and unconnected MCP servers
• /agents - Lists user and built-in agents, option to create new agent
• /doctor - Shows diagnostics and current Claude Code version
• /help - Shows help menu

Installation

To install Claude Code, refer to the official instructions at code.claude.com/docs/en/setup.

Starting Claude Code

Claude Code operates within the directory where you launch it, typically your project's root folder.

To start Claude Code in your terminal, run:

claude

Logging In

When first running Claude Code, you should be prompted to log in. This will open up a web browser. You will need to be on a paid plan, either "Pro", "Max", or "Team".

If you are not prompted to log in, you can type the following "slash" command:

/login

Using Claude Code

Prompts (instructions) for Claude Code are typed in the input bar. You can also paste into the terminal (Ctrl+Shift+v on Linux for example). You can paste in text and screenshot images. You can also drag and drop files and images into the terminal.

For example, if you are developing a website and have a visual bug, you can screenshot the website element and paste it (or drag and drop the screenshot file) into Claude Code and ask Claude to fix it.

!

! ls

Models

Claude Code supports three models:

1. Opus - highest capability model, slower response times, higher usage costs
2. Sonnet - balanced performance and cost, suitable for most development tasks
3. Haiku - fastest responses, lowest usage costs, ideal for straightforward tasks

You can switch between models in Claude Code by running the slash command:

/model

Which Models to Use

Opus

Opus offers the highest capability but consumes usage limits faster than other models.

Use Opus for planning complex features and implementing challenging functionality that requires deep reasoning.

Sonnet

Sonnet provides faster responses than Opus whilst consuming fewer usage limits.

Sonnet serves as an excellent default for most development tasks. Use it as your primary implementation model for writing and editing code.

Haiku

Haiku delivers the fastest responses and consumes the fewest usage limits of all three models.

Haiku excels at implementing standard features such as creating React components, writing Python scripts, or building conventional applications following established patterns.

Hybrid: Recommended Setup

Using Opus in Plan Mode, then executing the plan using Sonnet is a great default. Fortunately, there is a slightly hidden feature to have this occur automatically:

/model opusplan

This will automatically have Claude Code use Opus in Plan Mode, then implement the plan using Sonnet.

CLAUDE.md - Providing Claude Code with Context

The most effective way to optimise Claude Code performance is to provide a CLAUDE.md file in your project root.

The CLAUDE.md file serves as project documentation for Claude, outlining common development commands, project architecture, directory structure, and essential development practices. This context enables Claude to make informed decisions about code changes and follow your project's conventions.

/init

# CLAUDE.md

## Development Commands

### Local Development
- `bun run dev` - Start development server at http://localhost:5173
- `bun run build` - Build for production
- `bun run test` - Run Vitest tests
- `bun run format` - Format code with Biome (includes linting and fixing)

### Deployment
- `bun run deploy` - Build and deploy to production (Cloudflare Workers)

## Project Architecture

This is a personal website built with React Router v7, deployed on Cloudflare Workers.
The architecture follows modern React patterns with server-side rendering support.

### Key Architecture Components

**Framework**: React Router v7 with SSR enabled

**Styling**: Tailwind CSS v4 with custom animations

**Content Structure**:
- Each route is a self-contained TSX file with meta() exports for SEO
- Structured data (JSON-LD) implemented for rich snippets

**Components**:
- `NavBar` - Main navigation with hamburger menu
- `Footer` - Site footer with links
- `SocialLinks` - Social media icon links

### Key Development Patterns

**SEO**: Comprehensive meta tags, Open Graph, Twitter Cards, and JSON-LD structured data

**Accessibility**: Skip links, semantic HTML, proper heading hierarchy, and keyboard navigation support

Prompting, Planning, and Execution

Effective prompting and planning are key to Claude Code's performance.

@prompt.md

Plan the implementation of a new search feature. There should be a search icon in the website header which expands to take a search term input. The search functionality should search through the articles, guides, and blog posts on the website.

● Entered plan mode

Use parallel subagents to brainstorm 3 potential ways to implement a contact form that send an email to my email address when someone uses the form. The solution should be able to be run on Cloudflare workers.

Checkpoints: Undoing Code and Context

When Claude Code takes an unintended direction or implements changes you want to reverse, you can use checkpoints to restore previous states without starting a new session.

Checkpoints allow you to revert the conversation context, file changes, or both to any previous point in your session. Each prompt creates an automatic checkpoint.

/checkpoints

Note: Checkpoints are session-specific and temporary. They are not a replacement for Git version control. Always commit important changes to Git for permanent version history.

Git and Version Control

Look at the Git history for the `Header.tsx` file and explain who implemented the search functionality and what changes were made at the time

Usage and Context Control

/usage

/context

/clear

/compact

Settings and Permissions

To avoid repetitive permission prompts, you can configure command permissions and other settings in a .claude/settings.local.json file. Claude Code generates this file automatically, which you can then customise to control which commands run automatically, require confirmation, or are blocked entirely.

The .claude/settings.local.json should not be committed to a Git repository, for shared settings that can be committed to a Git repository use the file .claude/settings.json.

You can also have a "default" settings.json file which will be used by all Claude Code projects. On Linux and Mac this is located in your home directory, under ~/.claude/settings.json.

Here is an example ~/.claude/settings.json file covering common Bash commands and development tools, with some being explicitly allowed to run, some requiring asking each time, and some denied altogether.

{
  "permissions": {
    "allow": [
      "Bash(cat:*)",
      "Bash(pwd:*)",
      "Bash(head:*)",
      "Bash(tail:*)",
      "Bash(ls:*)",
      "Bash(touch:*)",
      "Bash(grep:*)",
      "Bash(awk:*)",
      "Bash(sed:*)",
      "Bash(find:*)",
      "Bash(type:*)",
      "Bash(which:*)",
      "Bash(locate:*)",
      "Bash(date:*)",
      "Bash(man:*)",
      "Bash(uname:*)",
      "Bash(du:*)",
      "Bash(make:*)",
      "Bash(mkdir:*)",
      "Bash(cd:*)",
      "Bash(npm run test:*)",
      "Bash(npm run build:*)",
      "Bash(npm run dev:*)",
      "Bash(npm run start:*)",
      "Bash(npm run lint:*)",
      "Bash(npm install:*)"
    ],
    "ask": [
      "Bash(rm:*)",
      "Bash(curl:*)",
      "Bash(wget:*)",
      "Bash(chmod:*)",
      "Bash(chown:*)",
      "Bash(git:*)",
      "Bash(docker:*)"
    ],
    "deny": [
      "Bash(ssh:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./.j2.*)"
    ],
    "env": {
      "CLAUDE_CODE_ENABLE_TELEMETRY": "0",
      "ANTHROPIC_MODEL": "opusplan"
    }
  }
}

The example above also sets the default model for new sessions, the opusplan model described earlier, as well as disabling telemetry.

More information can be found in the Claude Code documentation: code.claude.com/docs/en/settings.

Claude Plugins and Plugin Marketplaces

Plugins provide a distribution mechanism for installing Claude Skills and MCP servers from official and community sources.

View available plugins from default marketplaces and any external sources you've configured using the slash command:

/plugin

Exercise caution when installing plugins from external sources. Verify the publisher's identity and review the plugin's code before installation, as plugins have access to your development environment and files.

The official Claude plugins marketplace has "code intelligence" plugins available (code.claude.com/docs/en/discover-plugins#code-intelligence). These allow Claude Code to find code references and see type errors.

For example, to install the TypeScript code intelligence:

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

Note: the TypeScript code intelligence needs the TypeScript language server to be installed, this can be done in your terminal outside of Claude Code, or by using the Bash mode prefix ! in the Claude Code input:

npm install -g typescript-language-server typescript

More information can be found at code.claude.com/docs/en/discover-plugins.

Claude Skills

Claude Skills are a way of loading specialised knowledge into Claude Code. The main benefit is that unlike the CLAUDE.md file, SKILL.md file contents are not loaded into the context until the Skill is invoked.

Skills can be run either by asking Claude to use the Skill, or with a custom slash command. More information can be found at code.claude.com/docs/en/skills.

mkdir -p ~/.claude/skills/react-optimiser

---
name: react-optimiser
description: Analyses React components for performance issues and implements optimisations. Use when reviewing component performance, addressing re-render issues, or when asked to optimise React code.
---

When optimising React components:

1. **Analyse first**: Examine the component for:
   - Unnecessary re-renders (missing React.memo, useCallback, useMemo)
   - Expensive computations in render
   - Large inline objects/arrays in JSX
   - Props drilling and context overuse
   - Improper dependency arrays in hooks
   - Key prop issues in lists

2. **Create optimisation plan**: List specific issues found with:
   - Current problem and performance impact
   - Proposed solution
   - **Potential side-effects** (e.g., stale closures, reference equality assumptions)
   - Priority (critical/moderate/minor)

3. **Wait for approval**: Present the plan and ask which optimisations to implement.

4. **Implement carefully**: When requested:
   - Apply changes incrementally
   - Preserve existing functionality
   - Highlight any behavioural changes

Focus on React and TypeScript performance patterns only. Avoid project-wide configuration changes.

Use the React Optimiser skill to analyse the `Header.tsx` component

/react-optimiser ./components/Header.tsx

Claude Subagents

Custom subagents can be created to handle specific tasks.

For example, you might create a "Code Reviewer" subagent to review existing code, or a "Security Reviewer" subagent to specifically work on identifying potential security issues in your application.

More information can be found at code.claude.com/docs/en/sub-agents.

To create a subagent, the simplest way to get started is to have Claude Code create one for you based on your instructions.

First use the slash command:

/agents

Then select Create new agent and choose Personal to save the subagent in your home directory (~/.claude/agents/) so it can be used in multiple projects. If you have a project-specific requirement, select Project.

Select Generate with Claude and describe your requirement when asked. For example, for a Security Reviewer subagent:

A security reviewer agent that explores the code to highlight any potential security risks, vulnerabilities, or oversights. It should explain the risk or vulnerability and provide solutions or mitigations.

You will then be asked to select the tool required. For the Security Reviewer we likely only need Read-only tools, so deselect everything else using the Enter key.

You will then be asked to select a model. Unless your application is very specialised or unusual, Sonnet will be a good choice.

You will then be asked to select a colour. This will highlight when this agent is running in the terminal.

You can then run the subagent by asking Claude to use it:

Use the security-reviewer agent to explore the codebase and highlight any potential vulnerabilities

Claude MCP Servers

Model Context Protocol (MCP) is a standardised protocol that enables Claude to interact with external services and tools. MCP servers provide integrations with email providers (Gmail), project management platforms (Asana), communication tools (Slack), design applications (Canva), databases, and web browsers.

More information can be found at code.claude.com/docs/en/mcp.

Below are two examples of two popular MCP tools available from the official Claude plugins: Playwright and Context7.

/plugin install playwright@claude-plugins-official

Use Playwright to inspect my homepage and suggest layout changes to reduce bounce rates

/plugin install context7@claude-plugins-official

Custom Statuslines

You can configure a custom statusline that appears below the input box in Claude Code to display session information.

Statuslines can show the current Git branch, working directory, context window usage, active model, session ID, and other runtime information. This provides at-a-glance visibility into your Claude Code session state.

Example Custom Statusline

Here is how to add a custom statusline that looks like the following:

First, create a file in the Claude Code user settings directory: ~/.claude/statusline.sh with the following contents:

#!/bin/bash

# Read JSON input from stdin
input=$(cat)

# Extract values using jq
session_id=$(echo "$input" | jq -r '.session_id // "unknown"')
cwd=$(echo "$input" | jq -r '.workspace.current_dir // empty')
model_name=$(echo "$input" | jq -r '.model.display_name // "unknown"')
context_remaining=$(echo "$input" | jq -r '.context_window.remaining_percentage // empty')

# Truncate session ID to first 8 characters for brevity
session_short="${session_id:0:8}"

# Get directory basename for display
if [ -n "$cwd" ]; then
  dir_name="${cwd##*/}"
  [ -z "$dir_name" ] && dir_name="/"
else
  dir_name="~"
fi

# Change to working directory for git operations
cd "$cwd" 2>/dev/null || cd "$HOME"

# Get git branch (if in a git repository)
git_branch=""
git_status_icon=""
if git rev-parse --git-dir > /dev/null 2>&1; then
  branch=$(git branch --show-current 2>/dev/null)
  if [ -n "$branch" ]; then
    git_branch="$branch"
  else
    # Detached HEAD - show short commit hash
    git_branch=$(git rev-parse --short HEAD 2>/dev/null)
  fi

  # Check for uncommitted changes
  if [ -n "$(git status --porcelain 2>/dev/null)" ]; then
    git_status_icon=" ●"  # Indicates dirty working tree
  fi
fi

# Build progress bar for context remaining
build_progress_bar() {
  local percentage=$1
  local width=10
  local filled=$((percentage * width / 100))
  local empty=$((width - filled))
  local bar=""

  # Determine colour based on percentage
  if [ "$percentage" -gt 50 ]; then
    bar+="\\e[1;32m"  # Bright green
  elif [ "$percentage" -gt 25 ]; then
    bar+="\\e[1;33m"  # Bright yellow
  else
    bar+="\\e[1;31m"  # Bright red
  fi

  # Build the bar
  for ((i=0; i<filled; i++)); do bar+="█"; done
  bar+="\\e[0;90m"
  for ((i=0; i<empty; i++)); do bar+="░"; done
  bar+="\\e[0m"

  echo -e "$bar"
}

# Format context remaining with colour and progress bar
context_display=""
if [ -n "$context_remaining" ] && [ "$context_remaining" != "null" ]; then
  # Round to integer
  ctx_int=$(printf "%.0f" "$context_remaining")

  progress_bar=$(build_progress_bar "$ctx_int")

  # Colour for percentage text
  if [ "$ctx_int" -gt 50 ]; then
    ctx_colour="\\e[1;32m"  # Bright green
  elif [ "$ctx_int" -gt 25 ]; then
    ctx_colour="\\e[1;33m"  # Bright yellow
  else
    ctx_colour="\\e[1;31m"  # Bright red
  fi

  context_display="${progress_bar} ${ctx_colour}${ctx_int}%\\e[0m"
fi

C_RESET="\\e[0m"
C_DIM="\\e[0;90m"
C_WHITE="\\e[0;37m"
C_BLUE="\\e[1;34m"
C_MAGENTA="\\e[1;35m"
C_CYAN="\\e[1;36m"
C_ORANGE="\\e[38;5;208m"
C_PURPLE="\\e[38;5;141m"
C_PINK="\\e[38;5;213m"
C_GREEN="\\e[1;32m"
C_YELLOW="\\e[1;33m"

ICON_SESSION="💻"
ICON_FOLDER="📁"
ICON_GIT="🌳"
ICON_MODEL="🧠"
ICON_CONTEXT="🪟"
ICON_DIRTY="●"

output=""

# Session ID (abbreviated) with icon
output+="${C_DIM}${ICON_SESSION} ${C_PURPLE}${session_short}${C_RESET}"

# Separator
output+=" ${C_DIM}│${C_RESET} "

# Current directory with icon
output+="${C_ORANGE}${ICON_FOLDER} ${C_BLUE}${dir_name}${C_RESET}"

# Git branch (if available) with icon
if [ -n "$git_branch" ]; then
  output+=" ${C_DIM}(${C_PINK}${ICON_GIT} ${git_branch}${C_YELLOW}${git_status_icon}${C_DIM})${C_RESET}"
fi

# Separator
output+=" ${C_DIM}│${C_RESET} "

# Model name with icon
output+="${C_CYAN}${ICON_MODEL} ${model_name}${C_RESET}"

# Context remaining (if available) with icon and progress bar
if [ -n "$context_display" ]; then
  output+=" ${C_DIM}│${C_RESET} "
  output+="${C_DIM}${ICON_CONTEXT}${C_RESET} ${context_display}"
fi

printf "%b" "$output"

Save the file, and grant it executable permissions with:

chmod +x ~/.claude/statusline.sh

Then edit the user Claude Code settings JSON file ~/.claude/settings.json and include the following:

  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 0
  }

The full ~/.claude/settings.json file may now look something like this:

{
  "permissions": {
    "allow": [
      "Bash(cat:*)",
      "Bash(grep:*)"
    ]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline-command.sh",
    "padding": 0
  }
}

Exit Claude Code and go back into it, and you should see the new statusline below the input box.

Frequently Asked Questions

What is the difference between Skills and Subagents?

Skills are reusable prompt templates that load specialised instructions when invoked, without consuming context until used. They're ideal for specific workflows like code reviews or optimisation tasks. Subagents are independent Claude instances that can run in parallel or background, with their own context windows and tool access permissions. Use Skills for repeatable workflows and Subagents for complex, multi-step tasks requiring isolation.

How much does Claude Code cost?

Claude Code requires a paid Claude subscription: Pro (individual use), Max (higher usage limits), or Team (collaborative features). Usage counts against your plan's monthly limits based on the model used (Haiku consumes fewer tokens than Sonnet, which consumes fewer than Opus). Check your current usage with the /usage command.

Can I use Claude Code offline?

No. Claude Code requires an active internet connection as it communicates with Anthropic's API servers to process requests. All AI inference happens on Anthropic's infrastructure, not locally on your machine.

How do I prevent Claude Code from reading sensitive files like environment variable files?

Add deny rules to your ~/.claude/settings.json or .claude/settings.json file. For example:"deny": ["Read(./.env)", "Read(./.env.*)", "Read(**/*.key)"]. This prevents Claude from accessing environment files, private keys, or other sensitive data.

What are MCP servers and why would I use them?

Model Context Protocol (MCP) servers extend Claude Code's capabilities by connecting it to external services like Gmail, Slack, databases, or design tools like Canva. They enable Claude to interact with tools beyond your local filesystem. For example, the Playwright MCP allows Claude to view and interact with websites, whilst Context7 provides access to up-to-date documentation for frameworks and libraries.

Conclusion

Claude Code transforms software development by bringing AI assistance directly into your terminal whilst maintaining full control over your codebase. The key to maximising its effectiveness lies in proper configuration: create a comprehensive CLAUDE.md file, use plan mode for complex features, configure appropriate model selection (opusplan for most workflows), and leverage advanced features like Skills and MCP servers where appropriate.

Start with the basics: installation, CLAUDE.md creation, and model selection. Then progressively adopt advanced features as your workflow matures. Use checkpoints to experiment safely, configure permissions to balance convenience with security, and create custom Skills for repetitive tasks in your domain.

For the latest documentation and updates, refer to the official Claude Code documentation at code.claude.com/docs.