Home › Blog › Article

Claude Code, GenAI

Claude Code: Zero to Hero – The Complete 2026 Field Guide

A complete field guide to Claude Code in 2026. Covers every primitive CLAUDE.md, skills, MCP, subagents, hooks, permissions – then advances into headless pipelines, git worktrees, multi-agent teams, model configuration, scheduling, plugins, and security best practices. Language and framework agnostic.

Prabhat Kashyap

Claude Code is not a coding assistant. It is a coding agent. The difference sounds subtle but the implications are enormous – you stop accepting suggestions line by line and start delegating tasks end to end. This guide covers everything: installation, the primitives that make Claude Code project-aware, workflows that compound over time, and the advanced configuration that most engineers never reach.

Whether you are exploring Claude Code for the first time or looking to unlock headless pipelines, multi-agent teams, and MCP integrations, this is the complete reference.

1. Introduction – the agent shift

Every wave of developer tooling has asked the same question differently: how do we get computers to write more of the code? Autocomplete answered at the character level. Copilot answered at the line level. Claude Code answers at the task level.

When you open a session in Claude Code, you are not prompted to accept a suggestion. You delegate: “fix the race condition in the auth service”, “write integration tests for the payment flow”, “refactor the data layer to use the repository pattern”. Claude reads the relevant files, plans its approach, executes changes, runs your build, checks test output, and iterates – without you touching the keyboard between steps.

The practical implication is not just speed. It is cognitive load. You stop context-switching between writing, reviewing, and fixing. You describe intent; Claude handles implementation. Your job becomes defining quality, reviewing outcomes, and raising the bar of what you delegate next.

Claude Code revenue grew 5.5× between Q1 and Q3 2025. Teams using it consistently report 40–70% reductions in time spent on routine engineering tasks – not by working less, but by delegating a different class of work.

Installation

Requires Node.js 18 or higher.

# Install globally
npm install -g @anthropic-ai/claude-code

# Verify
claude --version

# First run - authenticates via browser
claude

# Install globally
npm install -g @anthropic-ai/claude-code

# Verify
claude --version

# First run - authenticates via browser
claude

Bash

Authentication opens a browser tab linked to your Anthropic account (Pro plan or API key). Once authenticated, every subsequent claude invocation in a project directory starts an informed session – Claude knows your filesystem, your build system, and your CLAUDE.md from the first message.

2. Ways to use Claude Code

Claude Code has four distinct interaction modes. Knowing which to reach for – and when to combine them – is the first skill to build.

Interactive REPL (default)

The primary mode. Run claude from your project directory and you get a persistent conversation with full tool access: file reads and writes, shell command execution, web browsing, and MCP server calls.

# Start interactive session
claude

# Context persists across messages until you /clear or /compact

# Start interactive session
claude

# Context persists across messages until you /clear or /compact

Bash

Use interactive mode for exploratory tasks, multi-step refactors, debugging sessions, and any work where you want to review and steer Claude’s decisions as it goes.

Non-interactive one-shot (-p flag)

For scripted tasks, CI pipelines, and automation. Claude executes a single prompt and exits. Output goes to stdout – pipe it, log it, or discard it.

# One-shot execution
claude -p "write a CHANGELOG entry for commits since v2.0.0"

# Pipe output from another command
npm test 2>&1 | claude -p "diagnose the failing tests and suggest fixes"

# Pipe git diff for automated review
git diff HEAD~1 | claude -p "review this diff for bugs and security issues"

# Combine with shell conditionals
if ! npm test; then
  npm test 2>&1 | claude -p "fix all failing tests" && npm test
fi

# One-shot execution
claude -p "write a CHANGELOG entry for commits since v2.0.0"

# Pipe output from another command
npm test 2>&1 | claude -p "diagnose the failing tests and suggest fixes"

# Pipe git diff for automated review
git diff HEAD~1 | claude -p "review this diff for bugs and security issues"

# Combine with shell conditionals
if ! npm test; then
  npm test 2>&1 | claude -p "fix all failing tests" && npm test
fi

Bash

Print mode with output format

# Plain text (best for piping and logging)
claude -p "summarise this PR" --output-format text

# JSON (best for parsing in scripts)
claude -p "list all TODO comments in src/" --output-format json

# Markdown (default for most prose tasks)
claude -p "document the API endpoints in routes/" --output-format markdown

# Plain text (best for piping and logging)
claude -p "summarise this PR" --output-format text

# JSON (best for parsing in scripts)
claude -p "list all TODO comments in src/" --output-format json

# Markdown (default for most prose tasks)
claude -p "document the API endpoints in routes/" --output-format markdown

Bash

Headless / automated mode

# Skip interactive confirmations for fully automated environments
claude --dangerously-skip-permissions -p "run the test suite and fix any failures"

# Skip interactive confirmations for fully automated environments
claude --dangerously-skip-permissions -p "run the test suite and fix any failures"

Bash

Mode comparison

Mode	Best for	Context persists?
Interactive REPL	Exploratory work, complex multi-step tasks	Yes, within session
`-p` one-shot	Scripts, CI pipelines, automation	No (stateless)
Headless + `--dangerously-skip-permissions`	Fully automated environments	No (stateless)
Editor terminal	In-editor agentic workflows	Yes, within session

3. Understanding the key concepts

Claude Code has eight primitives that work together. Most engineers use two or three. Understanding all eight and how they interact is where the compounding gains come from.

CLAUDE.md vs CLAUDE.local.md

CLAUDE.md is your project’s shared instruction file. It lives in the project root and is committed to version control. Every team member’s Claude sessions load it automatically. Think of it as the AI equivalent of an onboarding document – stack, architecture decisions, coding conventions, build commands.

CLAUDE.local.md is your personal layer on top. It lives in the same directory but is gitignored. Use it for your own preferences, local tool paths, personal shortcuts, or anything you want Claude to know about your machine that is not relevant to the team.

File	Committed?	Scope	Use for
`CLAUDE.md`	Yes	Team-wide	Stack, conventions, build commands, architecture
`CLAUDE.local.md`	No (gitignored)	Personal	Local paths, personal preferences, machine-specific config

Context

Claude’s context window is its working memory for a session. Every file it reads, every message exchanged, and every tool result consumes context. When context fills up, Claude’s performance degrades – it starts forgetting earlier decisions. Managing context deliberately (via /compact and /clear) is one of the highest-leverage habits to develop.

Modes

Claude Code has two interaction modes: interactive (conversational REPL) and non-interactive (-p flag for scripted one-shot execution). Within interactive mode, you can also trigger Plan Mode – Claude outlines its intended approach before taking any action, allowing you to approve or redirect before any files are touched.

Models

Two models are available. Claude Sonnet is the default – fast, capable, cost-effective for most tasks. Claude Opus is the flagship – slower and more expensive, but significantly better at complex reasoning, long multi-file refactors, and architecture-level decisions. Switch mid-session with /model.

Tools

Tools are Claude’s built-in capabilities: reading files, writing files, running bash commands, searching the web, and fetching URLs. These are always available without configuration. You can restrict which tools Claude may use via settings.json.

MCP (Model Context Protocol)

MCP is the open standard that connects Claude to external systems. Configure MCP servers in .mcp.json and Claude gains live access to GitHub, databases, Figma, Slack, and any other service with an MCP server. Unlike tools (built-in capabilities), MCP connections are project-specific and extensible.

Plugins

Plugins are packaged, shareable skill collections – community-built or enterprise-built capability extensions distributed through the Claude Marketplace. They are installed once and available across projects, unlike project-specific skills which live in .claude/skills/.

Hooks

Hooks are event-driven automation scripts that fire on Claude Code lifecycle events – after a file edit, before a commit, after tests run. They run outside Claude’s reasoning loop but can trigger Claude prompts, shell commands, or HTTP requests. Think of them as GitHub Actions that fire inside your local development cycle.

Subagents

Subagents are specialised Claude instances with their own system prompts, tool access, and context windows. The orchestrating Claude spawns them to handle parallel workstreams – one agent runs tests, another reviews code, another updates documentation – and then synthesises their results into a unified report.

4. Claude Code workflow

The daily delegation loop

Open a session with intent. Start with a clear task description, not an open question. “Fix the failing checkout test” outperforms “help me with tests”.
Let Claude read before it writes. Claude will scan relevant files before making changes. Don’t interrupt this – it’s building the context that makes its edits accurate.
Review at checkpoints, not continuously. Ask Claude to “pause and summarise what you’ve changed so far” after each major step.
Compact before context fills up. Run /compact every 10–15 exchanges. Claude summarises the session history and continues with no important context lost.
Iterate in layers. Get the skeleton working first. Then ask for error handling. Then tests. Then optimisation. Asking for everything at once produces mediocre results on all dimensions.

The pipe loop pattern

# Run tests → pipe failures → Claude fixes → repeat
npm test 2>&1 | claude -p "fix all failing tests"

# Or as a while loop until tests pass
until npm test; do
  npm test 2>&1 | claude -p "fix the failing tests"
done

# Run tests → pipe failures → Claude fixes → repeat
npm test 2>&1 | claude -p "fix all failing tests"

# Or as a while loop until tests pass
until npm test; do
  npm test 2>&1 | claude -p "fix the failing tests"
done

Bash

The review workflow

# Review a git diff before pushing
git diff HEAD~1 | claude -p "review this diff: correctness, edge cases, security"

# Review a specific file
claude -p "review src/payments/processor.ts for correctness and error handling"

# Generate a PR description
git diff main...feature-branch | claude -p "write a clear PR description for this diff"

# Review a git diff before pushing
git diff HEAD~1 | claude -p "review this diff: correctness, edge cases, security"

# Review a specific file
claude -p "review src/payments/processor.ts for correctness and error handling"

# Generate a PR description
git diff main...feature-branch | claude -p "write a clear PR description for this diff"

Bash

The documentation workflow

# Generate docs from code
claude -p "document all public functions in src/api/ as JSDoc / docstrings"

# Update CHANGELOG
git log v1.0.0..HEAD --oneline | claude -p "write a CHANGELOG entry for these commits"

# Write an ADR
claude -p "write an Architecture Decision Record explaining why we chose X over Y based on this codebase"

# Generate docs from code
claude -p "document all public functions in src/api/ as JSDoc / docstrings"

# Update CHANGELOG
git log v1.0.0..HEAD --oneline | claude -p "write a CHANGELOG entry for these commits"

# Write an ADR
claude -p "write an Architecture Decision Record explaining why we chose X over Y based on this codebase"

Bash

5. Best practices

Write specific prompts

Weak prompt	Strong prompt
“Improve the code”	“Refactor UserService to use the repository pattern, keeping the interface identical”
“Write tests”	“Write unit tests for PaymentValidator covering: null input, negative amounts, expired cards, and currency mismatch”
“Fix the bug”	“Fix the race condition in OrderProcessor.processQueue() that causes duplicate charges under concurrent load”

Use negative constraints

"Refactor the auth module.
 Do NOT change the public API surface.
 Do NOT introduce new dependencies.
 Do NOT touch any test files."

"Refactor the auth module.
 Do NOT change the public API surface.
 Do NOT introduce new dependencies.
 Do NOT touch any test files."

Plaintext

Other key practices

Scope your tasks. Smaller, well-defined tasks consistently outperform broad, open-ended ones. Break large tasks into steps and delegate one at a time.
Commit CLAUDE.md to version control. Treat it like code – review changes, update it when conventions evolve, and keep it precise. Every hour invested compounds across every future session.
Slow down on architecture, speed up on implementation. Use Plan Mode for any decision that touches multiple files. Use fast one-shot execution for routine implementation tasks.
Request reasoning first. “Before writing any code, explain your approach in three sentences.” This costs seconds and catches misunderstandings before they become wasted edits.

6. CLAUDE.md – deep dive

CLAUDE.md is loaded automatically into every session’s system context. It is the single most impactful file in your Claude Code setup. A well-written CLAUDE.md turns Claude from a capable generalist into a specialist who knows your project as well as a senior engineer would after a month of onboarding.

The anatomy of a great CLAUDE.md

# Project: [Name]
# Purpose: [One sentence description]

## Stack
Language:   [Language + version]
Framework:  [Primary framework + version]
Database:   [DB + ORM/query layer]
Test runner:[Framework]
Build tool: [Build system]
Lint/format:[Tool + config file]

## Architecture
[2-3 sentences on the high-level architecture.
E.g.: "Three-layer: routes → services → repositories.
Business logic lives exclusively in services/.
No database queries outside of repositories/."]

## Conventions - ALWAYS
- [Specific pattern your team uses]
- [Naming convention]
- [Error handling pattern]

## Conventions - NEVER
- [Anti-pattern #1]
- [Anti-pattern #2]
- [Anti-pattern #3]

## Build and Run
build:  [command]
test:   [command]
dev:    [command]
lint:   [command]
format: [command]

## Testing
[Framework and patterns - e.g. "Vitest for unit, Playwright for e2e.
Every new function needs at least one happy path and one error path test."]

## Security
[Key security requirements specific to your domain]

# Project: [Name]
# Purpose: [One sentence description]

## Stack
Language:   [Language + version]
Framework:  [Primary framework + version]
Database:   [DB + ORM/query layer]
Test runner:[Framework]
Build tool: [Build system]
Lint/format:[Tool + config file]

## Architecture
[2-3 sentences on the high-level architecture.
E.g.: "Three-layer: routes → services → repositories.
Business logic lives exclusively in services/.
No database queries outside of repositories/."]

## Conventions - ALWAYS
- [Specific pattern your team uses]
- [Naming convention]
- [Error handling pattern]

## Conventions - NEVER
- [Anti-pattern #1]
- [Anti-pattern #2]
- [Anti-pattern #3]

## Build and Run
build:  [command]
test:   [command]
dev:    [command]
lint:   [command]
format: [command]

## Testing
[Framework and patterns - e.g. "Vitest for unit, Playwright for e2e.
Every new function needs at least one happy path and one error path test."]

## Security
[Key security requirements specific to your domain]

Plaintext

CLAUDE.md for subdirectories

You can place CLAUDE.md files at any level of the directory tree. Claude loads all CLAUDE.md files in the ancestry of the files it is working on – project-level provides defaults, subdirectory files provide specifics.

your-project/
  CLAUDE.md               # Project-wide rules
  src/
    api/
      CLAUDE.md           # API-specific rules (REST conventions, auth patterns)
    workers/
      CLAUDE.md           # Worker-specific rules (queue handling, retry logic)

your-project/
  CLAUDE.md               # Project-wide rules
  src/
    api/
      CLAUDE.md           # API-specific rules (REST conventions, auth patterns)
    workers/
      CLAUDE.md           # Worker-specific rules (queue handling, retry logic)

Plaintext

Importing other files with @

# CLAUDE.md
## Stack
See @docs/architecture.md for full stack documentation.

## API conventions
See @docs/api-guidelines.md

## Current sprint focus
See @.claude/sprint-context.md

# CLAUDE.md
## Stack
See @docs/architecture.md for full stack documentation.

## API conventions
See @docs/api-guidelines.md

## Current sprint focus
See @.claude/sprint-context.md

Plaintext

7. Skills – deep dive

Skills are SKILL.md files that give Claude a specialised playbook for a specific class of task. They are the difference between Claude applying generic best practices and Claude applying your team’s best practices, encoded once and available forever.

Where skills live

~/.claude/skills/skill-name/SKILL.md – personal, available in all projects
.claude/skills/skill-name/SKILL.md – project-specific, committed to version control

Anatomy of a SKILL.md

---
name: pr-review
description: |
  Perform a thorough code review. Auto-invoke when the user asks to
  "review", "check", or "audit" code changes or a pull request.
trigger: "/review"
effort: medium
version: 1.0
---

## Review checklist

### Correctness
- Does the logic match the stated intent?
- Are all edge cases handled?
- Are there off-by-one errors or boundary issues?

### Security
- Is all external input validated?
- Are there injection risks (SQL, command, path)?
- Are secrets handled correctly?

### Code quality
- Is the naming clear and consistent with CLAUDE.md?
- Are functions focused on a single responsibility?
- Is error handling consistent with project conventions?

## Output format
For each issue: file + line, severity (Critical / High / Medium / Low),
description, and a concrete fix with example code.
Conclude with an overall assessment: Approve / Request Changes.

---
name: pr-review
description: |
  Perform a thorough code review. Auto-invoke when the user asks to
  "review", "check", or "audit" code changes or a pull request.
trigger: "/review"
effort: medium
version: 1.0
---

## Review checklist

### Correctness
- Does the logic match the stated intent?
- Are all edge cases handled?
- Are there off-by-one errors or boundary issues?

### Security
- Is all external input validated?
- Are there injection risks (SQL, command, path)?
- Are secrets handled correctly?

### Code quality
- Is the naming clear and consistent with CLAUDE.md?
- Are functions focused on a single responsibility?
- Is error handling consistent with project conventions?

## Output format
For each issue: file + line, severity (Critical / High / Medium / Low),
description, and a concrete fix with example code.
Conclude with an overall assessment: Approve / Request Changes.

YAML

Skills with supporting files

.claude/skills/api-generator/
  SKILL.md               # Core instructions
  templates/
    endpoint.ts          # Template file Claude uses
    test.spec.ts         # Test template
  references/
    openapi-conventions.md

.claude/skills/api-generator/
  SKILL.md               # Core instructions
  templates/
    endpoint.ts          # Template file Claude uses
    test.spec.ts         # Test template
  references/
    openapi-conventions.md

Bash

8. Permissions

Claude Code’s permissions system controls what Claude is allowed to do in a given session. By default Claude has broad access – read files, write files, run commands. You narrow this to match your risk tolerance and environment.

The settings.json file

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git *)",
      "Read(**)",
      "Write(src/**)",
      "Write(tests/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Write(.env*)",
      "Write(*.pem)",
      "Write(*.key)"
    ]
  }
}

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git *)",
      "Read(**)",
      "Write(src/**)",
      "Write(tests/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Write(.env*)",
      "Write(*.pem)",
      "Write(*.key)"
    ]
  }
}

JSON

Permission patterns

Pattern	What it controls
`Read(**)`	Read any file in the project
`Write(src/**)`	Write only inside src/
`Bash(npm run *)`	Allow any npm run command
`Bash(git add *)`	Allow git add only
`WebFetch(https://docs.example.com/*)`	Allow fetching specific domains

Model-level permissions

{
  "model": "claude-sonnet-4-6",
  "maxTokensPerSession": 100000,
  "disabledTools": ["WebFetch", "WebSearch"]
}

{
  "model": "claude-sonnet-4-6",
  "maxTokensPerSession": 100000,
  "disabledTools": ["WebFetch", "WebSearch"]
}

JSON

9. Subagents

Subagents are the architecture that makes Claude Code scale beyond single-developer tasks. Each subagent is a specialised Claude instance with its own system prompt, context window, tool permissions, and model configuration. The orchestrating agent spawns them, coordinates their work, and synthesises results.

Creating subagents

---
name: test-agent
description: |
  Test reliability specialist. Spawn me when code changes need test
  coverage verification or when the test suite has failures to fix.
model: claude-sonnet-4-6
tools: [bash, read_file, write_file]
maxTurns: 20
---

You are a test reliability specialist.

Your workflow:
1. Run the test command from CLAUDE.md and capture complete output
2. For each failure: identify root cause, plan minimal fix
3. Apply the fix, re-run affected tests to verify
4. If a test was wrong (not the code), fix the test and explain why
5. Report: tests fixed / still failing / coverage before and after

---
name: test-agent
description: |
  Test reliability specialist. Spawn me when code changes need test
  coverage verification or when the test suite has failures to fix.
model: claude-sonnet-4-6
tools: [bash, read_file, write_file]
maxTurns: 20
---

You are a test reliability specialist.

Your workflow:
1. Run the test command from CLAUDE.md and capture complete output
2. For each failure: identify root cause, plan minimal fix
3. Apply the fix, re-run affected tests to verify
4. If a test was wrong (not the code), fix the test and explain why
5. Report: tests fixed / still failing / coverage before and after

YAML

Orchestrating subagents

You: I'm shipping the payment gateway refactor in 2 hours.
     Run all quality checks in parallel and give me one report.

Claude: Spawning three parallel agents:
  → test-agent: running full test suite
  → reviewer-agent: checking payment module for correctness
  → security-agent: scanning for injection risks and exposed secrets

Consolidated report:
  test-agent: 142/144 tests pass, 2 flaky tests (not regressions)
  reviewer-agent: 1 high severity - missing idempotency check on charge()
  security-agent: 1 medium - raw card number logged in error handler, line 47

You: I'm shipping the payment gateway refactor in 2 hours.
     Run all quality checks in parallel and give me one report.

Claude: Spawning three parallel agents:
  → test-agent: running full test suite
  → reviewer-agent: checking payment module for correctness
  → security-agent: scanning for injection risks and exposed secrets

Consolidated report:
  test-agent: 142/144 tests pass, 2 flaky tests (not regressions)
  reviewer-agent: 1 high severity - missing idempotency check on charge()
  security-agent: 1 medium - raw card number logged in error handler, line 47

Bash

Subagent coordination patterns

Parallel review: Test agent + reviewer agent + security agent run simultaneously on the same changeset.
Sequential pipeline: Build agent → test agent → doc agent → deploy agent, each picking up where the previous left off.
Specialist delegation: Orchestrator handles architecture decisions, delegates all implementation to specialist agents.
Fan-out synthesis: Orchestrator sends a task to multiple agents with different configurations and compares their outputs.

10. Hooks

Hooks are event-driven scripts that fire automatically at specific points in the Claude Code lifecycle. They run independently of Claude’s conversation – they are not prompts to Claude, they are automation scripts triggered by Claude’s actions.

Hook types

Type	What it does
`command`	Runs a shell command
`http`	Makes an HTTP request
`prompt`	Sends a follow-up prompt to Claude
`agent`	Spawns a subagent

Post-edit quality hook

---
event: PostFileEdit
type: prompt
---

After editing this file, verify:
1. No hardcoded credentials or API keys introduced
2. All functions have error handling consistent with CLAUDE.md
3. No debug statements left in production code (console.log, print, debugger)
4. If any issues found: fix them immediately and state what was corrected.

---
event: PostFileEdit
type: prompt
---

After editing this file, verify:
1. No hardcoded credentials or API keys introduced
2. All functions have error handling consistent with CLAUDE.md
3. No debug statements left in production code (console.log, print, debugger)
4. If any issues found: fix them immediately and state what was corrected.

YAML

Pre-commit linting hook

---
event: PreCommit
type: command
---

#!/bin/bash
npm run lint && npm run format
exit $?

---
event: PreCommit
type: command
---

#!/bin/bash
npm run lint && npm run format
exit $?

YAML

Security enforcement hook

---
event: PreToolCall
tool: Bash
type: command
---

#!/bin/bash
COMMAND="$1"
DANGEROUS_PATTERNS=("rm -rf /" "DROP TABLE" "DELETE FROM" "> /dev/sda")
for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if echo "$COMMAND" | grep -q "$pattern"; then
    echo "BLOCKED: Command matches dangerous pattern: $pattern"
    exit 1
  fi
done
exit 0

---
event: PreToolCall
tool: Bash
type: command
---

#!/bin/bash
COMMAND="$1"
DANGEROUS_PATTERNS=("rm -rf /" "DROP TABLE" "DELETE FROM" "> /dev/sda")
for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if echo "$COMMAND" | grep -q "$pattern"; then
    echo "BLOCKED: Command matches dangerous pattern: $pattern"
    exit 1
  fi
done
exit 0

YAML

11. Managing context

The context window is Claude’s working memory. Everything in a session – your messages, Claude’s responses, file contents it has read, tool call results – accumulates in the context window. When it fills, Claude’s performance degrades. Managing it deliberately is one of the highest-leverage skills in Claude Code.

The context hierarchy

System context (always loaded): CLAUDE.md, active skills, settings. Always present and cannot be cleared.
Conversation history: All messages exchanged since the last /clear. Grows with every exchange.
File contents: Every file Claude reads is added to context. Large files consume significant context budget.
Tool results: Output from bash commands, web fetches, MCP calls – all consumes context.

Context management commands

# Compress history - use every 10–15 exchanges
/compact

# Clear all history - fresh start, system context remains
/clear

# Check current token usage
/status

# Compress history - use every 10–15 exchanges
/compact

# Clear all history - fresh start, system context remains
/clear

# Check current token usage
/status

Bash

Context-efficient patterns

Task isolation: Start a new session for each distinct task. Don’t accumulate context across unrelated work.
Targeted file reads: Ask Claude to read only files relevant to the current task, not the whole codebase.
Compact early, compact often: Run /compact proactively, not after Claude has already started forgetting.
Use skills to offload instructions: Instructions in SKILL.md load lazily (only when triggered), keeping the base context lighter.
Pipe, don’t paste: cat error.log | claude -p "diagnose" uses a fresh context window instead of polluting your current session.

Cross-session context via a sprint file

# .claude/sprint-context.md (referenced in CLAUDE.md)
## Current sprint (Week of April 7)
Working on: Payment gateway v2 refactor
Blocked on: PCI compliance review - do not touch src/payments/card-vault/
Completed: Order service migration to repository pattern
Next: Notification service refactor after gateway ships

# .claude/sprint-context.md (referenced in CLAUDE.md)
## Current sprint (Week of April 7)
Working on: Payment gateway v2 refactor
Blocked on: PCI compliance review - do not touch src/payments/card-vault/
Completed: Order service migration to repository pattern
Next: Notification service refactor after gateway ships

Bash

12. Advanced Claude Code

12.1 Customize the status line

// .claude/settings.json
{
  "statusLine": {
    "show": true,
    "items": ["model", "tokens", "cost", "activeSkills", "gitBranch"]
  }
}

// .claude/settings.json
{
  "statusLine": {
    "show": true,
    "items": ["model", "tokens", "cost", "activeSkills", "gitBranch"]
  }
}

JSON

---
event: SessionStart
type: command
---

#!/bin/bash
echo "CLAUDE_STATUS_EXTRA=ENV:$(git branch --show-current) | $(date +%H:%M)"

---
event: SessionStart
type: command
---

#!/bin/bash
echo "CLAUDE_STATUS_EXTRA=ENV:$(git branch --show-current) | $(date +%H:%M)"

YAML

12.2 Connecting tools with MCP

Project MCP configuration

// .mcp.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "postgresql://localhost:5432/${DB_NAME}"]
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": { "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}" }
    }
  }
}

// .mcp.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "postgresql://localhost:5432/${DB_NAME}"]
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": { "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}" }
    }
  }
}

JSON

CLI registration

export GITHUB_TOKEN="ghp_your_token"
claude mcp add github -- npx -y @modelcontextprotocol/server-github

claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres \
  postgresql://localhost:5432/yourdb

claude mcp add playwright -- npx -y @playwright/mcp

export FIGMA_ACCESS_TOKEN="your_token"
claude mcp add figma -- npx -y @figma/mcp-server

# Verify connections
claude /mcp

export GITHUB_TOKEN="ghp_your_token"
claude mcp add github -- npx -y @modelcontextprotocol/server-github

claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres \
  postgresql://localhost:5432/yourdb

claude mcp add playwright -- npx -y @playwright/mcp

export FIGMA_ACCESS_TOKEN="your_token"
claude mcp add figma -- npx -y @figma/mcp-server

# Verify connections
claude /mcp

Bash

MCP power stack

MCP Server	What it unlocks	Setup time
GitHub	Create PRs, review issues, check CI without leaving your terminal	5 min
PostgreSQL / MySQL	Query schemas, validate migrations, generate type-safe queries	5 min
Playwright	Browser automation, E2E testing, screenshot verification	5 min
Figma	Read designs, extract design tokens, generate components from specs	10 min
Slack	Post summaries, notify channels, fetch thread context	5 min
Google Workspace	Drive, Gmail, Calendar, Sheets from a single MCP server	15 min

12.3 Scheduling jobs

Cron-based scheduling

# Weekday standup summary at 9am
0 9 * * 1-5 cd /path/to/project && \
  git log --since="yesterday" --oneline | \
  claude -p "write a standup summary from these commits" \
  > .claude/standup-$(date +\%Y-\%m-\%d).md

# Nightly security audit → open GitHub issue
0 2 * * * cd /path/to/project && \
  npm audit --json | \
  claude -p "analyse these vulnerabilities and create a prioritised fix plan" | \
  gh issue create --title "Nightly security audit $(date +%Y-%m-%d)" --body-file -

# Weekday standup summary at 9am
0 9 * * 1-5 cd /path/to/project && \
  git log --since="yesterday" --oneline | \
  claude -p "write a standup summary from these commits" \
  > .claude/standup-$(date +\%Y-\%m-\%d).md

# Nightly security audit → open GitHub issue
0 2 * * * cd /path/to/project && \
  npm audit --json | \
  claude -p "analyse these vulnerabilities and create a prioritised fix plan" | \
  gh issue create --title "Nightly security audit $(date +%Y-%m-%d)" --body-file -

Bash

CI/CD integration – automated PR review

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  claude-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Review PR
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          git diff origin/main...HEAD | \
          claude --dangerously-skip-permissions \
                 -p "Review this PR. Flag bugs, security issues, and convention violations. Be specific - file + line + fix." \
                 --output-format text > review.txt

      - name: Post review comment
        uses: actions/github-script@v7
        with:
          script: |
            const review = require('fs').readFileSync('review.txt', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## Claude Code Review\n\n${review}`
            });

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  claude-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Review PR
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          git diff origin/main...HEAD | \
          claude --dangerously-skip-permissions \
                 -p "Review this PR. Flag bugs, security issues, and convention violations. Be specific - file + line + fix." \
                 --output-format text > review.txt

      - name: Post review comment
        uses: actions/github-script@v7
        with:
          script: |
            const review = require('fs').readFileSync('review.txt', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## Claude Code Review\n\n${review}`
            });

Bash

12.4 Model configuration – Opus & Plan mode

When to use Opus

Architecture decisions spanning multiple systems or services
Complex refactors touching 10+ files with deep interdependencies
Debugging subtle concurrency issues, memory leaks, or performance problems
Security threat modelling and penetration test planning
Writing CLAUDE.md, Skills, and system-level documentation

Model configuration

# Switch model for a session
claude --model claude-opus-4-6

# Switch mid-session
/model claude-opus-4-6

# Per-project default in settings.json
{
  "model": "claude-sonnet-4-6",
  "taskModels": {
    "architecture": "claude-opus-4-6",
    "security": "claude-opus-4-6",
    "implementation": "claude-sonnet-4-6",
    "tests": "claude-sonnet-4-6"
  }
}

# Switch model for a session
claude --model claude-opus-4-6

# Switch mid-session
/model claude-opus-4-6

# Per-project default in settings.json
{
  "model": "claude-sonnet-4-6",
  "taskModels": {
    "architecture": "claude-opus-4-6",
    "security": "claude-opus-4-6",
    "implementation": "claude-sonnet-4-6",
    "tests": "claude-sonnet-4-6"
  }
}

Bash

Plan Mode

# Enable Plan Mode
claude --plan
# Or mid-session:
/plan

# Claude responds before touching any files:
Claude: Here is my plan:
  1. Read UserService.ts to understand current structure
  2. Create UserRepository.ts with interface: [...]
  3. Refactor UserService.ts to inject UserRepository
  4. Update 3 call sites: OrderService.ts, AuthController.ts, AdminPanel.ts
  5. Run tests to verify nothing broke

  Shall I proceed? [yes / modify plan / cancel]

# Enable Plan Mode
claude --plan
# Or mid-session:
/plan

# Claude responds before touching any files:
Claude: Here is my plan:
  1. Read UserService.ts to understand current structure
  2. Create UserRepository.ts with interface: [...]
  3. Refactor UserService.ts to inject UserRepository
  4. Update 3 call sites: OrderService.ts, AuthController.ts, AdminPanel.ts
  5. Run tests to verify nothing broke

  Shall I proceed? [yes / modify plan / cancel]

Bash

12.5 Output styles

# Default markdown
claude -p "document the API"

# Plain text - best for piping
claude -p "list all functions in src/" --output-format text

# JSON - best for scripted parsing
claude -p "analyse the codebase and return metrics" --output-format json

# Streaming JSON - for real-time processing
claude -p "analyse all 200 files" --output-format stream-json

# Default markdown
claude -p "document the API"

# Plain text - best for piping
claude -p "list all functions in src/" --output-format text

# JSON - best for scripted parsing
claude -p "analyse the codebase and return metrics" --output-format json

# Streaming JSON - for real-time processing
claude -p "analyse all 200 files" --output-format stream-json

Bash

Define output structure in skill files so Claude always returns results in a consistent, parseable format:

---
name: dependency-audit
---

## Output format (ALWAYS use this structure - no prose before or after)

[
  {
    "package": "package-name",
    "version": "1.2.3",
    "severity": "critical|high|medium|low",
    "cve": "CVE-YYYY-NNNNN",
    "description": "Brief description",
    "fix": "Upgrade to version X.Y.Z"
  }
]

---
name: dependency-audit
---

## Output format (ALWAYS use this structure - no prose before or after)

[
  {
    "package": "package-name",
    "version": "1.2.3",
    "severity": "critical|high|medium|low",
    "cve": "CVE-YYYY-NNNNN",
    "description": "Brief description",
    "fix": "Upgrade to version X.Y.Z"
  }
]

YAML

12.6 Plugins

# Install from Claude Marketplace
npx skills add https://marketplace.claude.ai/skills/frontend-design
npx skills add https://marketplace.claude.ai/skills/security-audit

# Install a private org plugin
npx skills add https://skills.yourcompany.internal/deployment-runbook

# List and update
npx skills list
npx skills update

# Install from Claude Marketplace
npx skills add https://marketplace.claude.ai/skills/frontend-design
npx skills add https://marketplace.claude.ai/skills/security-audit

# Install a private org plugin
npx skills add https://skills.yourcompany.internal/deployment-runbook

# List and update
npx skills list
npx skills update

Bash

Org-wide plugin deployment via settings.json:

{
  "plugins": {
    "sources": ["https://skills.yourcompany.internal/registry"],
    "required": [
      "@yourcompany/security-baseline",
      "@yourcompany/deployment-runbook"
    ],
    "autoUpdate": true
  }
}

{
  "plugins": {
    "sources": ["https://skills.yourcompany.internal/registry"],
    "required": [
      "@yourcompany/security-baseline",
      "@yourcompany/deployment-runbook"
    ],
    "autoUpdate": true
  }
}

JSON

12.7 Scaling Claude – headless mode, git worktrees, agent teams

Headless mode

# Headless - skips all permission prompts
claude --dangerously-skip-permissions -p "run the full test suite and fix any failures"

# With hard timeout (prevent runaway sessions)
timeout 300 claude --dangerously-skip-permissions \
  -p "generate unit tests for all untested functions in src/"

# Headless - skips all permission prompts
claude --dangerously-skip-permissions -p "run the full test suite and fix any failures"

# With hard timeout (prevent runaway sessions)
timeout 300 claude --dangerously-skip-permissions \
  -p "generate unit tests for all untested functions in src/"

Bash

Safety rule: Always pair --dangerously-skip-permissions with a restrictive settings.json allow-list. The flag bypasses interactive prompts, not your allow/deny rules.

Git worktrees for parallel agent work

# Create worktrees for parallel agent work
git worktree add ../project-feature-auth feature/auth-refactor
git worktree add ../project-feature-api feature/api-v2
git worktree add ../project-bugfix bugfix/payment-race-condition

# Run Claude agents in each worktree simultaneously (one terminal each)
cd ../project-feature-auth && claude -p "implement the auth refactor"
cd ../project-feature-api  && claude -p "implement the API v2 endpoints"
cd ../project-bugfix        && claude -p "fix the payment race condition"

# Each agent works independently - no merge conflicts until you merge

# Create worktrees for parallel agent work
git worktree add ../project-feature-auth feature/auth-refactor
git worktree add ../project-feature-api feature/api-v2
git worktree add ../project-bugfix bugfix/payment-race-condition

# Run Claude agents in each worktree simultaneously (one terminal each)
cd ../project-feature-auth && claude -p "implement the auth refactor"
cd ../project-feature-api  && claude -p "implement the API v2 endpoints"
cd ../project-bugfix        && claude -p "fix the payment race condition"

# Each agent works independently - no merge conflicts until you merge

Bash

Orchestration shell script

#!/bin/bash
git worktree add /tmp/agent-tests   tests/agent-$(date +%s)
git worktree add /tmp/agent-docs    docs/agent-$(date +%s)
git worktree add /tmp/agent-refactor refactor/agent-$(date +%s)

# Launch agents in background
cd /tmp/agent-tests && claude --dangerously-skip-permissions \
  -p "write comprehensive tests for the new payment module" \
  --output-format text > /tmp/agent-tests.log &

cd /tmp/agent-docs && claude --dangerously-skip-permissions \
  -p "document all public APIs added in the last sprint" \
  --output-format text > /tmp/agent-docs.log &

cd /tmp/agent-refactor && claude --dangerously-skip-permissions \
  -p "refactor the data layer to use the repository pattern" \
  --output-format text > /tmp/agent-refactor.log &

wait  # Wait for all three to complete

# Synthesise with orchestrator
cat /tmp/agent-tests.log /tmp/agent-docs.log /tmp/agent-refactor.log | \
  claude -p "summarise these parallel agent results and create PRs for each branch"

# Cleanup
git worktree remove /tmp/agent-tests
git worktree remove /tmp/agent-docs
git worktree remove /tmp/agent-refactor

#!/bin/bash
git worktree add /tmp/agent-tests   tests/agent-$(date +%s)
git worktree add /tmp/agent-docs    docs/agent-$(date +%s)
git worktree add /tmp/agent-refactor refactor/agent-$(date +%s)

# Launch agents in background
cd /tmp/agent-tests && claude --dangerously-skip-permissions \
  -p "write comprehensive tests for the new payment module" \
  --output-format text > /tmp/agent-tests.log &

cd /tmp/agent-docs && claude --dangerously-skip-permissions \
  -p "document all public APIs added in the last sprint" \
  --output-format text > /tmp/agent-docs.log &

cd /tmp/agent-refactor && claude --dangerously-skip-permissions \
  -p "refactor the data layer to use the repository pattern" \
  --output-format text > /tmp/agent-refactor.log &

wait  # Wait for all three to complete

# Synthesise with orchestrator
cat /tmp/agent-tests.log /tmp/agent-docs.log /tmp/agent-refactor.log | \
  claude -p "summarise these parallel agent results and create PRs for each branch"

# Cleanup
git worktree remove /tmp/agent-tests
git worktree remove /tmp/agent-docs
git worktree remove /tmp/agent-refactor

Bash

Scaling tiers

Scale	Pattern	When to use
1 developer	Interactive REPL + `/compact`	Daily work
Small team	Shared CLAUDE.md + project skills	Consistent quality across team
CI pipeline	Headless `-p` with permission allow-list	Automated review and quality gates
Parallel features	Git worktrees + parallel agents	Multiple large features simultaneously
Enterprise	Agent teams + orchestrator + MCP	System-wide automated workflows

12.8 Security best practices

Default-deny permissions

// .claude/settings.json - production-safe baseline
{
  "permissions": {
    "allow": [
      "Read(**)",
      "Write(src/**)",
      "Write(tests/**)",
      "Write(docs/**)",
      "Bash(npm run lint)",
      "Bash(npm run test)",
      "Bash(npm run build)",
      "Bash(git add *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Write(.env*)",
      "Write(*.pem)",
      "Write(*.key)",
      "Write(secrets/**)",
      "Write(infrastructure/**)",
      "Write(*.tf)",
      "Bash(rm -rf *)",
      "Bash(curl * | bash)",
      "Bash(sudo *)"
    ]
  }
}

// .claude/settings.json - production-safe baseline
{
  "permissions": {
    "allow": [
      "Read(**)",
      "Write(src/**)",
      "Write(tests/**)",
      "Write(docs/**)",
      "Bash(npm run lint)",
      "Bash(npm run test)",
      "Bash(npm run build)",
      "Bash(git add *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Write(.env*)",
      "Write(*.pem)",
      "Write(*.key)",
      "Write(secrets/**)",
      "Write(infrastructure/**)",
      "Write(*.tf)",
      "Bash(rm -rf *)",
      "Bash(curl * | bash)",
      "Bash(sudo *)"
    ]
  }
}

Bash

Secrets management rules

Never put secrets in CLAUDE.md, skills, or any file Claude reads. Claude’s context can be logged by Anthropic for safety review.
Use environment variables for all credentials and reference them in .mcp.json as ${VAR_NAME}.
Add .env*, *.pem, *.key to both .gitignore and your Claude permission deny-list.
Use a PreToolCall hook to scan for credential patterns before any file write completes.

Credential leak detection hook

---
event: PreToolCall
tool: Write
type: command
---

#!/bin/bash
FILE_CONTENT="$1"
PATTERNS=(
  "password\s*=\s*['\"][^'\"]{4,}"
  "api_key\s*=\s*['\"][^'\"]{8,}"
  "AKIA[0-9A-Z]{16}"        # AWS access key
  "sk-[a-zA-Z0-9]{48}"      # OpenAI key
  "ghp_[a-zA-Z0-9]{36}"     # GitHub personal access token
)
for pattern in "${PATTERNS[@]}"; do
  if echo "$FILE_CONTENT" | grep -qiE "$pattern"; then
    echo "BLOCKED: Potential credential detected in file write"
    exit 1
  fi
done
exit 0

---
event: PreToolCall
tool: Write
type: command
---

#!/bin/bash
FILE_CONTENT="$1"
PATTERNS=(
  "password\s*=\s*['\"][^'\"]{4,}"
  "api_key\s*=\s*['\"][^'\"]{8,}"
  "AKIA[0-9A-Z]{16}"        # AWS access key
  "sk-[a-zA-Z0-9]{48}"      # OpenAI key
  "ghp_[a-zA-Z0-9]{36}"     # GitHub personal access token
)
for pattern in "${PATTERNS[@]}"; do
  if echo "$FILE_CONTENT" | grep -qiE "$pattern"; then
    echo "BLOCKED: Potential credential detected in file write"
    exit 1
  fi
done
exit 0

YAML

Headless mode security checklist

Always run headless Claude in a Docker container or sandboxed environment – never directly on a production server.
Set explicit permission allow-lists before enabling --dangerously-skip-permissions.
Log all Claude actions in CI: pipe output to a timestamped log file.
Set a hard timeout on all automated Claude invocations.
Never commit settings.local.json – it may contain personal tokens or local paths.
Rotate API keys used for automated pipelines on the same schedule as other CI credentials.

Team security rules file

# .claude/rules/security.md
## Security non-negotiables for Claude Code sessions

1. Never ask Claude to read files outside the project directory
2. Never paste credentials, tokens, or keys directly into the conversation
3. Always review Claude's proposed changes to infrastructure-as-code files
4. Use Plan Mode for any task that modifies the database schema
5. Run security-agent before merging any PR touching auth, payments, or PII
6. Report any unexpected Claude behaviour to the security team

# .claude/rules/security.md
## Security non-negotiables for Claude Code sessions

1. Never ask Claude to read files outside the project directory
2. Never paste credentials, tokens, or keys directly into the conversation
3. Always review Claude's proposed changes to infrastructure-as-code files
4. Use Plan Mode for any task that modifies the database schema
5. Run security-agent before merging any PR touching auth, payments, or PII
6. Report any unexpected Claude behaviour to the security team

Plaintext

Summary: the Claude Code maturity model

Stage	What you have set up	What you can do
Foundations	Install + CLAUDE.md	Bug fixes, refactors, test generation, code review
Automation	Skills + Hooks + Permissions	Consistent quality gates, project-specific workflows, automated enforcement
Integration	MCP servers	GitHub, database, Figma, Slack – Claude reasons about your whole system
Scale	Subagents + Headless + Worktrees	Parallel workstreams, CI automation, scheduled jobs, agent teams

You do not need to reach Stage 4 to get value. Stage 1 alone – a working install and a well-written CLAUDE.md – delivers meaningful productivity gains in the first week. Build each stage incrementally, ship real work at each level, and invest the time saved into the next level of configuration.

The teams winning with Claude Code are not the ones with the most sophisticated setup. They are the ones who built their setup iteratively – shipping at each stage, learning from real usage, and compounding gains over time.

Share: LinkedIn X / Twitter

Prabhat Kashyap

Senior Technical Architect @ HCL Tech · working with Leonteq Security AG

10+ years building distributed systems and fintech platforms. I write about the things I actually debug at work — the messy, non-obvious parts that don't make it into official docs.

Full bio → LinkedIn X / Twitter

AI Engineering Series

Rust Fundamentals Series

Cats Effect & fs2 Series

AI Engineering Series

Rust Fundamentals Series

Cats Effect & fs2 Series

Claude Code: Zero to Hero – The Complete 2026 Field Guide

1. Introduction – the agent shift

Installation

2. Ways to use Claude Code

Interactive REPL (default)

Non-interactive one-shot (-p flag)

Print mode with output format

Headless / automated mode

Mode comparison

3. Understanding the key concepts

CLAUDE.md vs CLAUDE.local.md

Context

Modes

Models

Tools

MCP (Model Context Protocol)

Plugins

Hooks

Subagents

4. Claude Code workflow

The daily delegation loop

The pipe loop pattern

The review workflow

The documentation workflow

5. Best practices

Write specific prompts

Use negative constraints

Other key practices

6. CLAUDE.md – deep dive

The anatomy of a great CLAUDE.md

CLAUDE.md for subdirectories

Importing other files with @

7. Skills – deep dive

Where skills live

Anatomy of a SKILL.md

Skills with supporting files

8. Permissions

The settings.json file

Permission patterns

Model-level permissions

9. Subagents

Creating subagents

Orchestrating subagents

Subagent coordination patterns

10. Hooks

Hook types

Post-edit quality hook

Pre-commit linting hook

Security enforcement hook

11. Managing context

The context hierarchy

Context management commands

Context-efficient patterns

Cross-session context via a sprint file

12. Advanced Claude Code

12.1 Customize the status line

12.2 Connecting tools with MCP

Project MCP configuration

CLI registration

MCP power stack

12.3 Scheduling jobs

Cron-based scheduling

CI/CD integration – automated PR review

12.4 Model configuration – Opus & Plan mode

When to use Opus

Model configuration

Plan Mode

12.5 Output styles

12.6 Plugins

12.7 Scaling Claude – headless mode, git worktrees, agent teams

Headless mode

Git worktrees for parallel agent work

Orchestration shell script

Scaling tiers