Claude Code Deep Dive: The Developer’s Guide - 2026-11-04

The agentic coding market has shifted dramatically over the past year. What started as autocomplete-on-steroids has matured into terminal-native agents that read your repository, run your tests, and commit code. Anthropic’s Claude Code sits at the center of that shift — and as of late 2026, it’s also the most contested tool in the category. Revolut’s decision to swap Claude for the open-weight GLM model and cut its AI coding bill by 90% made headlines on Hacker News this week, a reminder that cost discipline now matters as much as raw capability. This guide covers what Claude Code actually is, how to configure it properly, and the workflows that separate teams getting real leverage from teams burning tokens on chat.

What is Claude Code?

Claude Code launched in early 2025 as a research preview and has since become Anthropic’s flagship developer product. Unlike IDE plugins that live in a sidebar, Claude Code is a terminal-first agent: you run claude inside a project directory, and it operates directly on your filesystem, shell, and git history. It reads files on demand rather than stuffing your whole repo into context, executes commands with your permission, and iterates against real test output.

The core value proposition is agentic execution with a tight feedback loop. You describe an outcome — “migrate this Express app to Fastify and keep the tests green” — and the agent plans, edits, runs npm test, reads failures, and fixes them. Anthropic reports that Claude Code now accounts for a meaningful share of code committed inside Anthropic itself, and the pattern has spread: the tool is designed to be scriptable, so it slots into CI pipelines and headless automation as naturally as it does into interactive use.

What differentiates it from alternatives:

The counterpoint from this week’s news: Claude Code is a premium product, and token costs compound fast on large repos. Revolut’s GLM migration is a signal that teams should measure cost-per-merged-PR, not just capability. We’ll cover cost controls below.

🚀 Getting Started

Installation

Claude Code ships as an npm package and also has a native installer. Node.js 18+ is required for the npm route.

# Option 1: npm (global install)
npm install -g @anthropic-ai/claude-code

# Option 2: native installer (no Node dependency)
curl -fsSL https://claude.ai/install.sh | bash

# Verify
claude --version

# Authenticate (opens browser for OAuth, or use an API key)
claude
# On first run, follow the login prompt. For headless/CI use:
export ANTHROPIC_API_KEY="sk-ant-..."

Start a session inside any project:

cd ~/projects/payments-service
claude

You’ll get an interactive REPL. Try a scoped first task to validate the setup:

> Summarize the architecture of this repo and list the three files most likely
  to need changes if I add a refund endpoint. Don't edit anything yet.

Configuration

Claude Code reads settings from three layers, in increasing precedence: user (~/.claude/settings.json), project (.claude/settings.json, committed), and local (.claude/settings.local.json, gitignored).

// .claude/settings.json — project-level, shared with the team
{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Read(./src/**)",
      "Read(./tests/**)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(git push:*)",
      "Read(./.env*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "NODE_ENV": "test"
  }
}

The deny list is the important half. Denying Read(./.env*) prevents the agent from ever pulling credentials into context — a real risk when an agent decides to “helpfully” debug a connection string.

The second configuration surface is CLAUDE.md, a markdown file at the repo root that Claude Code loads into every session. Treat it as a persistent system prompt for your codebase:

# CLAUDE.md

## Commands
- Test: `npm test` (Jest; run single file with `npm test -- path`)
- Lint: `npm run lint` — must pass before any commit
- Typecheck: `npm run typecheck`

## Conventions
- TypeScript strict mode; no `any` without a comment explaining why
- All new API routes go through `src/middleware/auth.ts`
- Database migrations live in `migrations/` and are never edited after merge
- Prefer composition over inheritance; see `src/services/refund/` for the pattern

## Gotchas
- The test suite requires a local Postgres on port 5433 (`docker compose up -d db`)
- `src/legacy/` is frozen — do not modify

Teams that invest fifteen minutes in a good CLAUDE.md consistently report fewer wrong-file edits and shorter sessions. It’s the highest-leverage configuration in the tool.

💡 Core Features

Feature 1: Agentic Edit-Test-Fix Loops

The defining capability. Claude Code doesn’t just propose a diff — it applies it, runs your verification commands, and repairs failures.

> The /refunds endpoint returns 500 when the amount exceeds the original
  charge. Reproduce it with a test, fix it, and make sure the full suite passes.

Claude Code will locate the handler, write a failing test, run it, read the stack trace, patch the validation logic, and re-run until green. Because it executes real commands, it catches things static analysis misses — a mocked clock, a missing index, a race in an async test.

Real-world application: bug-fix triage. Point it at a Sentry issue with the stack trace pasted in, and it will trace the failure path, write a regression test, and open a PR. The test-first instruction matters: it forces the agent to prove the bug exists before “fixing” it, which kills a common failure mode where the model patches a symptom.

Feature 2: Subagents for Context Isolation

Long sessions degrade as context fills with exploration noise. Subagents — spawned with the Task tool — run in isolated context windows and return only a summary.

> Use a subagent to map how authentication flows through the codebase:
  entry points, middleware chain, token refresh, and session storage.
  Return a concise summary with file:line references. Don't modify anything.

The subagent burns its own context reading twenty files; your main session receives a paragraph. You can define custom subagents in .claude/agents/ with their own prompts and tool restrictions:

<!-- .claude/agents/security-reviewer.md -->
---
name: security-reviewer
description: Reviews diffs for injection, authz, and secret-handling issues
tools: Read, Grep, Glob
model: opus
---
You review code changes for security defects only. Check for: SQL/command
injection, missing authorization checks, secrets in logs, unsafe deserialization,
and SSRF. Report findings as a list with severity and file:line. Do not suggest
style changes.

Real-world application: a pre-commit gate. Run the reviewer subagent against git diff --staged before every commit; because it’s read-only (tools: Read, Grep, Glob), it can’t accidentally “fix” anything mid-review.

Feature 3: Hooks for Deterministic Policy

Prompts are advisory; hooks are enforcement. Claude Code fires shell commands on lifecycle events — PreToolUse, PostToolUse, Stop, and others — and a non-zero exit blocks the action.

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/protect-frozen.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write --ignore-unknown $(echo \"$CLAUDE_FILE_PATHS\")" }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/protect-frozen.sh — block edits to frozen paths
set -euo pipefail
for f in $CLAUDE_FILE_PATHS; do
  case "$f" in
    src/legacy/*|migrations/*)
      echo "Blocked: $f is frozen. See CLAUDE.md." >&2
      exit 2   # exit 2 blocks the tool call and feeds stderr back to the model
      ;;
  esac
done
exit 0

Exit code 2 is special: it blocks the operation and returns stderr to Claude as feedback, so the agent learns the constraint instead of retrying blindly.

Real-world application: regulated environments. A PreToolUse hook on Bash can reject any command matching kubectl delete|terraform apply|aws iam — policy enforced in code, auditable in git, not dependent on the model’s judgment.

🛠️ Advanced Workflows

Workflow 1: Headless CI Triage

Claude Code runs non-interactively with -p (print mode), which makes it a CI primitive. Here’s a GitHub Actions job that triages failing tests on every PR:

# .github/workflows/ai-triage.yml
name: AI Test Triage
on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]
jobs:
  triage:
    if: github.event.workflow_run.conclusion == 'failure'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - name: Diagnose failure
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npm test 2>&1 | tail -100 > /tmp/test-output.txt || true
          claude -p "Read /tmp/test-output.txt and the relevant source files. \
            Diagnose the root cause of the test failures. Do not modify any files. \
            Output: (1) root cause in two sentences, (2) the minimal fix as a diff, \
            (3) confidence level." \
            --allowedTools "Read,Grep,Glob,Bash(npm test:*)" \
            --output-format json > /tmp/triage.json
      - name: Comment on PR
        uses: actions/github-script@v7
        with:
          script: |
            const t = require('/tmp/triage.json');
            await github.rest.issues.createComment({
              ...context.repo,
              issue_number: context.payload.workflow_run.pull_requests[0].number,
              body: `### 🤖 CI Triage\n\n${t.result}`
            });

Note the --allowedTools restriction: in CI, the agent gets read access and test execution only. No writes, no network. The --output-format json flag returns structured output with token usage, which you can log to track spend per run.

Workflow 2: Parallel Worktrees for Multi-Task Sessions

The single biggest productivity unlock for power users is running multiple Claude Code instances against separate git worktrees, so tasks don’t contend for the same files or context:

# One-time setup
git worktree add ../svc-refunds -b feat/refunds
git worktree add ../svc-ratelimit -b feat/rate-limit

# Terminal 1
cd ../svc-refunds && claude -p "Implement the refund endpoint per docs/refunds-spec.md. \
  Write tests first. Run the full suite before finishing." &

# Terminal 2
cd ../svc-ratelimit && claude -p "Add per-tenant rate limiting to the API gateway. \
  Use Redis sliding window. Update the OpenAPI spec." &

wait
# Review both branches, then merge independently

For longer autonomous runs, use --permission-mode acceptEdits to auto-approve file edits while keeping shell commands gated, or run the whole thing inside a container with a bind-mounted worktree if you want full autonomy with blast-radius control.

A cost note, given this week’s Revolut news: these parallel sessions multiply token spend. Track it with --output-format json and aggregate the usage fields. If your workload is dominated by high-volume, low-complexity tasks (lint fixes, test scaffolding, docstring generation), that’s exactly the profile where a cheaper open-weight model behind an MCP-compatible harness can make sense — route the expensive model to architecture and debugging, the cheap one to mechanical edits.

📊 Comparison with Alternatives

FeatureClaude CodeCursorGitHub Copilot
Terminal-native / SSH / headless CI✅❌⚠️ (CLI exists, limited agentic scope)
Agentic edit-test-fix loop✅✅✅ (agent mode)
Deterministic policy hooks✅❌❌
Subagent context isolation✅⚠️ (limited)❌
MCP server support✅✅✅
IDE GUI with inline diffs❌✅✅
Works inside containers / remote boxes✅⚠️⚠️
Multi-model flexibility❌ (Claude only)✅✅
Scriptable via CLI flags✅❌⚠️
Cost per heavy agentic sessionHighMediumMedium

The honest read: Cursor remains the better editing experience — inline diffs and tab-complete are genuinely superior for tight iteration. Copilot wins on seat price and enterprise procurement simplicity. Claude Code wins on automation, policy enforcement, and anywhere the work happens outside a GUI. Many teams run two: Cursor for interactive work, Claude Code in CI and for large refactors.

🎯 Pro Tips

  1. Front-load context, then compact deliberately. Start sessions with the specific files and constraints that matter (Read src/refunds/*.ts and docs/refunds-spec.md first), then run /compact at natural checkpoints — after exploration, before implementation. Compacting mid-implementation loses the thread; compacting after exploration keeps the map and drops the noise.

  2. Write CLAUDE.md like onboarding docs for a smart contractor. Commands, conventions, and gotchas — especially the gotchas. “The test DB is on port 5433” saves more tokens than any prompt trick. Update it whenever you correct the agent twice on the same thing.

  3. Enforce with hooks, not instructions. If a rule matters (never touch main, always run the formatter, block terraform apply), put it in a PreToolUse/PostToolUse hook. Prompt-level rules get forgotten under context pressure; hooks don’t.

  4. Scope permissions per environment. Interactive local sessions can allow broad reads and test runs. CI and autonomous runs should get --allowedTools down to the minimum and ideally a container. The permission config is your security boundary — treat deny on .env and secrets directories as non-negotiable.

  5. Measure cost per merged PR, not per token. Log --output-format json usage across sessions, attribute it to branches, and review monthly. If mechanical tasks dominate your spend, that’s your signal to route them to a cheaper model or a scripted formatter instead of an agent.

🔗 Resources

The through-line for 2026: the agent is no longer the differentiator — every major vendor ships one. The differentiators are context discipline, deterministic guardrails, and cost control. Claude Code gives you strong primitives for all three, provided you spend the fifteen minutes on CLAUDE.md and the hour on hooks.

Have questions? Join our Discord community or follow us on X.