⌨️

How Claude Code Works

An agentic coding assistant that lives in your terminal, reads your entire project, and takes action autonomously.

10 sections·1 min read

01What Claude Code Is

In Plain English

Think of Claude Code like hiring a senior developer who sits inside your terminal. You describe what you want done in plain English, and they go off, read the relevant files, figure out a plan, write the code, run the tests, and come back with the finished result. You can interrupt them at any time to steer them in a different direction, just like tapping a colleague on the shoulder.

Traditional AI coding tools (like chatbots) are more like texting a consultant. You copy code into a chat window, they suggest changes, you copy the changes back. Claude Code skips all that. It already has access to your files, your terminal, and your git history. It acts directly.

Traditional AI Chat

How it sees your code

You paste snippets into a chat window

How changes happen

You copy suggestions back into your editor

Context

Limited to what you paste

Workflow

Copy, paste, copy, paste

Interruption

Start a new message

Claude Code (Agentic)

How it sees your code

It reads your entire project directly from disk

How changes happen

It edits files itself, runs commands, verifies results

Context

Full project: files, git history, terminal, CLAUDE.md instructions

Workflow

Describe the goal, review the result

Interruption

Type your correction mid-task; Claude adjusts immediately

💻

Write and Refactor Code

Describe features in plain English. Claude reads the codebase, creates or modifies files, and runs tests to verify.

🔍

Explore and Understand

Ask "how does the auth module work?" and Claude searches, reads, and explains your codebase with specific file references.

⚡

Run Commands

Claude runs build tools, git, package managers, test suites. Anything you can do from the command line, Claude can do.

🌐

Research and Fetch

Search the web, fetch documentation, look up error messages, and pull in external context without leaving your terminal.

📦

Git Workflows

Stage changes, write commit messages from diffs, create branches, open PRs via GitHub CLI or MCP integration.

🧩

Extend with Plugins

Connect to external services via MCP, create custom agents, automate workflows with hooks, and define reusable skills.

0K tokens

Context window (roughly 500 pages of text)

Parallel subagents for complex tasks

Visual block types for rich content

Step 1: Install via npm

Run npm install -g @anthropic-ai/claude-code in your terminal. Requires Node.js 18+.

Step 2: Authenticate

Run claude in any directory. It opens a browser window for Anthropic account authentication. API key or Claude subscription required.

Step 3: Start working

Navigate to any project directory and run claude. It reads your project structure and CLAUDE.md automatically. Start describing what you want done.

Step 4: (Optional) IDE Integration

Install the VS Code extension or JetBrains plugin for an integrated experience. The CLI still powers everything under the hood.

What Claude Code is NOT

Claude Code is not an IDE or a code editor. It does not replace VS Code, JetBrains, or Cursor. It is a terminal tool (and IDE extension) that works alongside your existing editor. Think of it as adding an autonomous teammate to your workflow, not replacing your tools. Your editor shows you the code; Claude Code writes and modifies it based on your instructions.

02Architecture

In Plain English

The core of Claude Code is a loop that works like a detective investigating a case. Step one: read the evidence (your code, error messages, test output). Step two: form a theory (decide what needs to change). Step three: take action (edit a file, run a command). Step four: check if the case is solved (run tests, verify output). If not, go back to step one with the new information. This loop keeps running until the task is done or you interrupt it.

The whole system has three layers. On top: you (the user) in a terminal, VS Code, or JetBrains. In the middle: the "agentic harness" (Claude Code itself) that manages tools, context, permissions, and the loop. At the bottom: the Claude model (Opus, Sonnet, or Haiku) that does the actual reasoning.

Step 1: Your prompt arrives

You type a request like "fix the failing tests in the auth module." Claude Code feeds it to the model along with system instructions and CLAUDE.md content.

Step 2: Gather context

The model decides what information it needs. It might search for relevant files with Grep, read specific files with Read, or run git log to understand recent changes.

Step 3: Take action

Based on what it learned, the model edits files, creates new ones, or runs shell commands. Before anything destructive, it snapshots files for undo capability and may ask for your permission.

Step 4: Verify results

The model checks its own work by running tests, reading the output, or comparing against expected behavior. If something is wrong, it goes back to step 2 with the new error information.

Step 5: Return or continue

When the model decides the task is complete, it presents the result. If more work is needed, the loop continues. You can interrupt at any point to steer it differently.

🔄

Master Loop

The core while loop that continues as long as the model's responses include tool calls. Deceptively simple code that produces sophisticated behavior.

📨

Message Queue

Async dual buffer queue that enables real time steering. You can inject corrections, constraints, or redirections while Claude is actively working.

📦

Compressor

Triggers at approximately 92% context utilization. Summarizes the conversation to free space while preserving critical instructions from CLAUDE.md.

⏪

Checkpoint System

Snapshots every file before editing. Press Esc twice to rewind. Separate from git. Covers file changes only (not remote API calls or database operations).

📄

File Operations

Read files, edit code, create new files, rename and reorganize. The foundation of all coding work.

🔎

Search

Find files by pattern (Glob), search content with regex (Grep), explore entire codebases. How Claude understands your project.

⚡

Execution

Run shell commands, start servers, run tests, use git. Anything available from your command line.

🌐

Web

Search the web, fetch documentation, look up error messages. Brings external knowledge into the loop.

Why context matters

The context window is Claude's "working memory." Everything lives there: your conversation history, file contents, command outputs, CLAUDE.md instructions, loaded skills, and system messages. When it fills up, Claude automatically compacts (summarizes older content to free space). But compaction is lossy; instructions from early in the conversation can be lost. That is why persistent rules belong in CLAUDE.md, not in chat messages. Run /context to see what is using space.

Context usage: precision starts degrading

Context usage: hallucination rate increases significantly

Context usage: automatic compaction triggers

What this means for you

You do not need to understand the internal architecture to use Claude Code effectively. The key takeaway: Claude reads your code, reasons about it, takes action, and verifies the result in a loop. Your job is to give clear instructions and steer when needed. Everything else happens automatically.

03CLAUDE.md (Project Memory)

In Plain English

Imagine hiring a new contractor every morning who has amnesia. Every day they arrive with no memory of your project, your code style, how to run tests, or what you discussed yesterday. CLAUDE.md is the briefing document you hand them when they walk in the door. It tells them everything they need to know: what the project is, how the code is organized, which commands to run, and what to watch out for.

Without it, Claude starts every session clueless and you waste time re-explaining the same things. With a well-maintained CLAUDE.md, Claude picks up exactly where you need it.

	Location	Scope	Shared With
Managed Policy	/Library/Application Support/ClaudeCode/CLAUDE.md (macOS)	Organization-wide, deployed by IT	All users in organization
User Memory	~/.claude/CLAUDE.md	Your personal defaults for all projects	Just you (all projects)
User Rules	~/.claude/rules/*.md	Modular personal rules by topic	Just you (all projects)
Project Memory	./CLAUDE.md or ./.claude/CLAUDE.md	Team-shared project instructions	Team via source control
Project Rules	./.claude/rules/*.md	Modular topic-specific project rules	Team via source control
Local Memory	./CLAUDE.local.md	Personal project preferences (auto-gitignored)	Just you (this project)
Auto Memory	~/.claude/projects//memory/	Claude's automatic notes and learnings	Just you (per project)
Subdirectory	src/api/CLAUDE.md	Loaded on demand when Claude reads files in that directory	Team via source control

Step 1: Project context (1 to 2 sentences)

"This is a Next.js 15 e-commerce app with Supabase auth and Stripe payments." Orients Claude immediately.

Step 2: Commands

How to build, test, lint, deploy. Include exact commands: npm run test, npm run build. Claude will use these instead of guessing.

Step 3: Code style and conventions

"Use single quotes. Prefer functional components. Name files kebab-case." Claude follows these in every edit.

Step 4: Architecture overview

Key directories and what lives where. "API routes are in app/api/, database models in lib/models/."

Step 5: Important warnings and gotchas

"NEVER import from the legacy utils/ directory; use lib/ instead." Use IMPORTANT: prefix sparingly for critical rules.

Step 6: What NOT to do

"Do not create new CSS files; use Tailwind classes." "Do not commit .env files." Explicit anti-patterns save time.

🔗

@imports System

Reference external files with @path/to/file syntax to keep CLAUDE.md concise. Imported files can recursively import others, up to 5 levels deep.

📂

Modular Rules (.claude/rules/)

Split instructions into focused files: testing.md, api-design.md, security.md. All .md files in rules/ auto-load. Supports path-specific scoping with YAML frontmatter.

🧠

Auto Memory

Claude automatically saves project patterns, debugging insights, and architecture notes. First 200 lines of MEMORY.md load every session.

🔒

CLAUDE.local.md (Private)

Personal project preferences auto-gitignored. Your sandbox URLs, preferred test data, individual workflow notes. Never shared with the team.

Scoped rules for monorepos and large projects

Rules in .claude/rules/ can target specific files using YAML frontmatter with a paths field. For example, a rule scoped to paths: ["src/api/**/*.ts"] only applies when Claude works with API TypeScript files. Supports standard glob patterns: **/*.ts for all TypeScript files, src/components/*.tsx for React components.

CLAUDE.md best practices

Keep it under 300 lines. Context tokens are precious, and a bloated CLAUDE.md wastes them on every turn. Be specific: "Use 2-space indentation" beats "Format code properly." Add corrections organically as issues arise. Review every few weeks for obsolescence. Use IMPORTANT: sparingly for truly critical rules. For complex projects, split rules into .claude/rules/ instead of making one giant file. Run /init to bootstrap a starting CLAUDE.md.

📏Too long: Over 300 lines wastes context on every turn. Move detail to @imported files or .claude/rules/.

🎯Too generic: "Write clean code" teaches Claude nothing. Be specific about YOUR project.

🔧Missing commands: If Claude does not know how to run your tests, it will guess (often wrong).

📅Never updated: Outdated rules cause Claude to fight you. Delete rules for patterns you have moved away from.

⚠️No gotchas: The most valuable entries are the non-obvious things: "crypto.randomUUID() crashes on mobile over HTTP."

04Plan Mode

In Plain English

Plan mode is like asking an architect to draw blueprints before hiring the construction crew. Without it, Claude jumps straight into writing code, which works fine for small tasks but often goes sideways for complex ones. With plan mode, Claude explores your codebase, maps out the problem, and presents a plan. You review it, suggest changes, and only then does Claude start building.

Step 1: Activate plan mode

Press Shift+Tab twice (or cycle through permission modes) to enter Plan Mode. Claude switches to read-only tools: it can search and read files but cannot edit anything.

Step 2: Describe the task

"Add OAuth support to the auth module." Claude uses Glob, Grep, and Read to explore relevant files and understand the current architecture.

Step 3: Review the plan

Claude presents a structured plan: which files to change, what approach to take, and potential pitfalls. You can discuss, refine, or redirect.

Step 4: Approve and execute

Press Shift+Tab to exit plan mode and return to normal mode. Claude implements the plan, referencing what it learned during exploration.

Use Plan Mode

Task type

Multi-file refactors, new features, architectural changes

Uncertainty

You are not sure which files are involved or what approach to take

Risk

Changes could break multiple parts of the system

Complexity

Involves understanding how multiple modules interact

Skip Plan Mode

Task type

Single file fixes, quick edits, questions about code

Uncertainty

You know exactly what needs to change

Risk

Changes are isolated and easy to verify

Complexity

Straightforward and self-contained

The Explore, Plan, Code workflow

Anthropic's internal teams use a three-phase approach that consistently produces better results:

1. Explore: Have Claude read relevant files and understand the current state. Use plan mode or ask Claude to investigate before acting.
2. Plan: Discuss the approach, externalize the plan to a file (like SCRATCHPAD.md), and refine through conversation.
3. Code: Exit plan mode and let Claude implement. Because it already understands the codebase and the plan, implementation is faster and more accurate.

According to Anthropic's own documentation, "Shift+Tab twice before requesting features consistently produces superior outputs compared to direct requests."

What this means for you

For quick fixes and simple edits, just ask Claude directly. For anything that touches multiple files or requires architectural thinking, spend 30 seconds in plan mode first. The time you invest in planning saves multiples in avoided rework.

05Hooks

In Plain English

Hooks are like automatic triggers on a factory assembly line. When a product (code) comes off the editing station, a formatting machine (Prettier) automatically cleans it up. When someone tries to push a dangerous button (delete a protected file), an alarm blocks the action. When a batch finishes (Claude completes a task), a notification goes to your phone. You set up these triggers once, and they fire reliably every time, without relying on the AI to "remember" to do it.

	How It Works
Command	Runs a shell command. Receives JSON on stdin, communicates via stdout/stderr and exit codes. The most common type.
Prompt	Sends the hook input to a Claude model (Haiku by default) for a yes/no judgment. Returns {"ok": true} or {"ok": false, "reason": "..."}.
Agent	Spawns a subagent that can read files, run commands, and verify conditions. Used when verification requires inspecting actual codebase state.

	When It Fires	Common Use
PreToolUse	Before a tool call executes (can block it)	Block edits to protected files, validate commands
PostToolUse	After a tool call succeeds	Auto-format code, log commands, run linters
Notification	When Claude sends a notification	Desktop alerts when Claude needs input
SessionStart	When a session begins, resumes, or compacts	Re-inject context after compaction
Stop	When Claude finishes responding	Verify all tasks complete before stopping
UserPromptSubmit	When you submit a prompt, before Claude processes it	Validate or enrich user input
PreCompact	Before context compaction	Save important state before summarization
SubagentStart / Stop	When subagents start or finish	Setup/teardown for subagent environments

🎨

Auto-format After Edits

PostToolUse hook on Edit or Write that runs Prettier on the changed file. Every file Claude touches is auto-formatted. No more reminding the AI to format.

🛡️

Block Protected Files

PreToolUse hook on Edit or Write that checks file paths against protected patterns (.env, package-lock.json, .git/). Exit code 2 blocks the action.

🔔

Desktop Notifications

Notification hook that runs osascript to display a macOS notification when Claude needs your attention. Switch to other tasks without losing prompts.

♻️

Context Recovery After Compaction

SessionStart hook with "compact" matcher that echoes critical reminders back into context after compaction loses them. "Reminder: use Bun, not npm."

Where to save hook configurations

Hooks are defined in settings JSON files. ~/.claude/settings.json for global hooks (all projects). .claude/settings.json for project hooks (committable to git). .claude/settings.local.json for personal project hooks (gitignored). Use /hooks in Claude Code for an interactive menu to create, view, and manage hooks.

✅Exit 0: Action proceeds. For SessionStart and UserPromptSubmit, stdout is added to Claude's context.

🚫Exit 2: Action is blocked. Stderr message is fed back to Claude as feedback so it can adjust.

⚠️Any other exit code: Action proceeds, but stderr is logged. Toggle verbose mode with Ctrl+O to see.

06MCP (Model Context Protocol)

In Plain English

MCP is like USB ports on a computer. Your computer (Claude) is powerful on its own, but USB lets you plug in a printer, a camera, an external drive, a game controller. Each device adds a new capability. MCP works the same way: you "plug in" an MCP server, and suddenly Claude can talk to GitHub, query your database, send Slack messages, or create Jira tickets. The protocol is standardized, so any MCP-compatible server works with any MCP-compatible AI tool.

Remote (HTTP/SSE)

Where it runs

On the internet (cloud hosted)

Setup command

claude mcp add --transport http <name> <url>

Authentication

OAuth 2.0 or API key in headers

Best for

Cloud services (GitHub, Notion, Sentry, Slack)

Local (STDIO)

Where it runs

On your machine (local process)

Setup command

claude mcp add --transport stdio <name> -- <command>

Authentication

Environment variables

Best for

Local tools, databases, custom scripts

🐙

GitHub

PRs, issues, code search, repository management. The most popular MCP server. URL: api.githubcopilot.com/mcp/ (OAuth).

🗄️

PostgreSQL

Query databases naturally: "What is our total revenue this month?" Via @bytebase/dbhub with connection string.

🐛

Sentry

"What are the most common errors in the last 24 hours?" Debug production errors directly from your coding session.

💬

Slack

Read channels, send messages, search conversations. Bring team communication into Claude's context.

📋

Notion

Access pages, databases, and wikis. URL: mcp.notion.com/mcp (OAuth). Connect your team's knowledge base.

🎨

Figma

Read designs and implement them directly. Turn design specs into code without manual translation.

	Storage Location	Visibility
Local (default)	~/.claude.json under project path	Just you, current project only
User	~/.claude.json global mcpServers	Just you, all projects
Project	.mcp.json in project root	Team (committable to git)
Managed	managed-mcp.json in system directory	All users in organization (admin deployed)

Step 1: Add a remote server

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

Step 2: Authenticate (if needed)

Run /mcp in Claude Code, select the server, and follow the browser OAuth flow.

Step 3: Verify

claude mcp list shows all configured servers. /mcp inside Claude Code shows status and context cost.

Step 4: Use naturally

Just ask Claude: "Create a GitHub issue for this bug" or "Show me open PRs assigned to me." Claude selects the right MCP tool automatically.

Scaling with many MCP servers

When you have many MCP servers, their tool definitions can consume significant context. Claude Code has an automatic "Tool Search" feature that activates when MCP tool descriptions exceed 10% of the context window. Instead of preloading all tools, Claude searches for relevant ones on demand.

MCP context cost

Every MCP server adds tool definitions to every request, consuming context before you start working. A few heavyweight servers can eat 10 to 20% of your context window. Run /mcp regularly to check per-server costs. Remove servers you are not actively using.

07Custom Agents (Subagents)

In Plain English

Subagents are like specialized departments in a company. The CEO (your main Claude session) does not do everything personally. When a code review needs doing, they send it to the QA department (a code-reviewer subagent). When research is needed, they send it to the research team (an Explore subagent). Each department works in their own office (isolated context window), uses only the tools they need (scoped permissions), and sends a summary report back to the CEO. The CEO's desk does not get cluttered with all the department's internal paperwork.

	Model	Tools	Purpose
Explore	Haiku (fast)	Read-only (no Write/Edit)	File discovery, code search, codebase exploration
Plan	Inherits from main	Read-only (no Write/Edit)	Research during plan mode; gathers context before presenting a plan
General-purpose	Inherits from main	All tools	Complex multi-step tasks requiring both exploration and action
Bash	Inherits from main	Bash only	Running terminal commands in separate context

Step 1: Create the file

Save a Markdown file at ~/.claude/agents/agent-name.md (user level, all projects) or .claude/agents/agent-name.md (project level). The YAML frontmatter must start on line 1. A blank line before it causes silent failure.

Step 2: Define frontmatter

Required fields: name (kebab-case) and description (when Claude should use this agent). Optional: tools, model, permissionMode, color, hooks, memory, skills, maxTurns.

Step 3: Write the system prompt

The Markdown body after frontmatter becomes the agent's system prompt. Be specific about what the agent should do and how to format output.

Step 4: Test it

"Use the code-reviewer agent to review my recent changes." Or use /agents to manage all agents interactively.

# ~/.claude/agents/code-reviewer.md
---
name: code-reviewer
description: Expert code review specialist. Use after code changes.
tools: Read, Glob, Grep, Bash
model: sonnet
color: green
---

You are a senior code reviewer. When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Review for quality, security, and maintainability

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

⚡

Parallel Research

"Research the authentication, database, and API modules in parallel." Each explores independently; Claude synthesizes findings. Up to 7 simultaneous subagents.

📦

Background Tasks

Subagents can run in the background while you continue working. Press Ctrl+B to background a running task. Claude prompts for needed permissions upfront.

🌿

Worktree Isolation

Set isolation: "worktree" to run the subagent in a temporary git worktree, giving it an isolated copy of the repository. Cleaned up automatically.

🧠

Persistent Memory

Set memory: user to give a subagent a persistent directory that builds knowledge across conversations. "Check your memory for patterns you have seen before."

Use Subagents

Context

Task produces verbose output you do not need cluttering your main session

Isolation

You want to enforce specific tool restrictions or permissions

Speed

The task is self-contained and can return a summary

Use Main Conversation

Context

Task needs frequent back-and-forth or iterative refinement

Isolation

Multiple phases share significant context (plan, implement, test)

Speed

You are making a quick, targeted change

Subagent limitations

Subagents cannot spawn other subagents (no nesting). If your workflow needs nested delegation, chain subagents from the main conversation or use skills. Also: when multiple subagents complete, their results all return to your main context, so many verbose subagents can fill it up quickly.

08Skills & Slash Commands

In Plain English

Skills are like recipe cards in a chef's kitchen. Each card has instructions for a specific dish. The chef (Claude) can look at the card titles and descriptions to decide which recipe is relevant to the order. When a customer orders pasta, the chef grabs the pasta card. You can also walk into the kitchen and say "use the pasta recipe" directly. Some recipes are only triggered by you (the sous chef); others the head chef can decide to use on their own.

Slash commands have been merged into skills. If you have files in .claude/commands/, they still work. Skills add optional features: supporting files, invocation control, and automatic loading.

Step 1: Create the directory

mkdir -p ~/.claude/skills/my-skill for personal (all projects) or .claude/skills/my-skill for project-level.

Step 2: Write SKILL.md

YAML frontmatter with name and description, followed by Markdown instructions. The name becomes the /slash-command.

Step 3: (Optional) Add supporting files

Templates, scripts, examples, reference docs. Keep SKILL.md under 500 lines; move detail to supporting files.

Step 4: Test it

Type /my-skill to invoke directly, or ask Claude something that matches the description to see automatic loading.

Skills

Context

Runs in your main conversation context (shared history)

Best for

Reusable instructions, reference knowledge, guided workflows

Invocation

/skill-name or auto-detected by Claude

Nesting

Can be injected into subagents via skills field

Subagents

Context

Runs in isolated context (separate from main)

Best for

Verbose tasks, enforced tool restrictions, parallel work

Invocation

Claude delegates, or you request explicitly

Nesting

Cannot spawn other subagents

	You Can Invoke	Claude Can Invoke	Use Case
Default			Most skills. Both human and Claude can trigger it.
disable-model-invocation: true			Skills with side effects: /deploy, /commit. You control timing.
user-invocable: false			Background knowledge Claude should know when relevant but is not a meaningful user action.

🔀

String Substitutions

$ARGUMENTS gets replaced with whatever follows the skill name. $ARGUMENTS[0], $1 for positional access. /fix-issue 123 becomes the issue number in the prompt.

⚡

Dynamic Context Injection

The !`command` syntax runs shell commands before sending content to Claude. !`gh pr diff` inserts the actual PR diff into the skill prompt.

🌿

Fork to Subagent

Add context: fork to run the skill in an isolated subagent context. Combine with agent: Explore for read-only research skills.

🛡️

Tool Restrictions

allowed-tools: Read, Grep, Glob limits Claude to read-only operations when the skill is active. Safety for sensitive workflows.

What this means for you

Skills turn repeated prompts into one-command workflows. Instead of typing "run the tests, check for lint errors, and generate a commit message" every time, create a /pre-commit skill that does it all. Share skills with your team via .claude/skills/ in your repo.

09Context Management

In Plain English

Claude's context window is like a whiteboard in a meeting room. As you work, the whiteboard fills up with notes, diagrams, and to-do lists. At some point, there is no room left. Compacting is like taking a photo of the whiteboard and erasing it, keeping only a summary. Clearing is wiping the entire whiteboard and starting fresh. The key insight: important information should not only live on the whiteboard. Put it on permanent signs on the wall (CLAUDE.md), so it survives any cleanup.

	What It Does	When to Use
/clear	Wipes the entire conversation. Fresh start with no history.	Switching to a completely different task. Context is degraded beyond recovery.
/compact [focus]	Summarizes the conversation to free space. Optional focus phrase preserves specific topics.	Context meter is at 70%+. You want to continue the same work but need space.
/context	Shows what is using space: conversation, files, MCP tools, system messages.	Diagnosing why context is filling up. Checking MCP server costs.
/memory	Opens memory files in your editor for review and editing.	Checking or updating CLAUDE.md, auto-memory, or rules files.

📝

SCRATCHPAD.md

Ask Claude to write plans, findings, or progress to a SCRATCHPAD.md file. This survives /clear and compaction. Resume later by asking Claude to "read SCRATCHPAD.md and continue."

🧠

Auto Memory

Claude automatically writes notes to ~/.claude/projects/<project>/memory/. MEMORY.md (first 200 lines) loads every session. Topic files load on demand.

📌

CLAUDE.md for Persistent Rules

Instructions that matter across sessions belong in CLAUDE.md, not in conversation. Conversation instructions get lost during compaction; CLAUDE.md survives.

🔄

Session Management

claude --continue resumes the most recent session. claude --resume <id> resumes a specific one. --fork-session branches off without affecting the original.

Context health by usage level

🟢

IDEAL

0 to 50%

Full performance

🟡

50 to 70%

Still good

🟠

70 to 85%

Use /compact

🔴

DEGRADED

85%+

Use /clear

🎯One conversation per feature. Do not mix unrelated tasks in the same session.

💾Save before clearing. Tell Claude to "save your findings to SCRATCHPAD.md" before /clear.

🔌Remove unused MCPs. They add tool definitions to every request, eating context silently.

📦Use subagents for verbose tasks. They get their own fresh context and do not bloat your main conversation.

📊Run /context regularly. See exactly what is consuming space and where you can save.

What this means for you

Context management is the difference between Claude feeling sharp and Claude feeling confused. Keep sessions focused on one task, externalize important state to files, and use /compact or /clear when things feel sluggish. These habits compound over time.

10Best Practices & Workflow

In Plain English

Claude Code is powerful out of the box, but a few habits and configurations separate casual users from power users. This section covers the patterns that matter most: how to integrate with your IDE, how to handle git safely, how to run Claude in CI/CD pipelines, how to work with multiple Claude instances in parallel, and how to prompt effectively.

VS Code Extension

Installation

Search "Claude Code" in VS Code marketplace, click Install

Interface

Native graphical panel with multiple conversation tabs

Key features

Review/edit plans before accepting, auto-accept edits, @-mention files

Under the hood

Same Claude Code engine, same tools

JetBrains Plugin

Installation

Install from JetBrains Marketplace: "Claude Code [Beta]"

Interface

Plugin wrapping the CLI with IDE diff viewer integration

Key features

Chat experience, file references, conversation history, diff viewer

Under the hood

Same Claude Code engine, same tools

	How to Activate	Behavior
Default	Starts automatically	Claude asks before file edits and shell commands
Auto-accept edits	Press Shift+Tab once	Claude edits files freely, still asks for shell commands
Plan mode	Press Shift+Tab twice	Read-only. Claude creates a plan you approve before execution

Step 1: Basic headless usage

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash" runs Claude non-interactively with specific tool permissions.

Step 2: Structured output

claude -p "Summarize this project" --output-format json returns JSON with session ID and metadata. Add --json-schema for typed output.

Step 3: Streaming

--output-format stream-json --verbose streams tokens as newline-delimited JSON events for real time processing.

Step 4: CI/CD integration

Works natively in GitHub Actions, GitLab CI, and Jenkins. Exit code 0 on success, non-zero on error. Combine with --allowedTools for safe auto-approval.

🧪

Auto-generate Tests

Run "claude -p Write tests for auth.py" in CI. AI-generated tests cover on average 72% of untested code branches.

🔍

Automated Code Review

Pipe PR diffs to Claude with --append-system-prompt "Review for security vulnerabilities." Catches issues beyond what linters find.

🏷️

PR Labeling

Automatically classify and label pull requests based on the diff content. One-line script in your CI pipeline.

Git best practices with Claude Code

Connect Claude to git immediately. Access to commit history significantly reduces hallucinations. Use Test-Driven Development: "Write tests, commit them, let Claude implement until they pass" (Anthropic's internal recommendation). For parallel work, use git worktrees: git worktree add ../feature-branch feature-branch creates a separate directory where you can run a second Claude instance. Each worktree gets its own session and auto-memory.

🌿

Git Worktrees

Run parallel Claude instances in separate worktrees. One writes code, another reviews. Separate directories, separate sessions, no conflicts.

🖥️

Web + CLI

Boris (Claude Code creator) runs 5 to 10 Claudes on claude.ai/code in parallel with local CLI instances, moving between them for different tasks.

⚡

Background Agents

Subagents with background: true run concurrently while you keep working. Press Ctrl+B to background any running task.

🔐

Shared Permissions

Pre-approve safe commands via /permissions and store in shared .claude/settings.json. Reduces friction without bypassing safety.

🎯Be specific upfront: "Fix the checkout flow for users with expired cards. Check src/payments/, especially token refresh."

✅Give Claude something to verify against: Include test cases, expected output, or screenshots. Claude performs better when it can check its own work.

🚫Tell Claude what NOT to do: "Do not overengineer this. Do not create new files unless necessary."

📸Use images: Claude has excellent vision. Paste screenshots for debugging, UI comparison, or design implementation.

🤝Delegate, do not dictate: Give context and direction, trust Claude to figure out the details. "The checkout flow is broken for expired cards. Investigate and fix."

Community resources and skill marketplaces

Agent Skills Marketplace (skillsmp.com): Nearly 60,000 Claude skills for browsing and installation. Awesome Claude Skills (github.com): Community curated collection with 5.5k+ stars, organized by category. Awesome Claude Code (github.com): Resource collection for slash commands and configurations. MCP Tools (modelcontextprotocol.io): Complete documentation for the Model Context Protocol with hundreds of available servers.