Claude Code Deep Dive: The Developer’s Guide

Published on Smartotics Blog — October 28, 2026

The last two weeks have been unusually instructive for anyone tracking agentic coding tools. Linus Torvalds merged a Claude Code-authored fix to the Linux page cache — and reviewers promptly found a race condition in it. A developer’s GitHub account was suspended with no working path to a support ticket. And a Show HN project called CleanCode demonstrated Claude Code and OpenAI’s Codex collaborating on a single canvas. Three data points, one conclusion: these tools are now load-bearing infrastructure, and the difference between using them casually and using them well is measured in merged PRs and reverted commits.

This guide is for developers who want the second outcome. It covers installation, configuration, the features that actually matter, and the workflows that separate a productive Claude Code setup from an expensive autocomplete.

What is Claude Code?

Origin and background

Claude Code is Anthropic’s agentic coding tool, launched in research preview in February 2025 and reaching general availability later that year. Unlike IDE plugins that predict the next line, Claude Code runs as a terminal-native agent: it reads your repository, executes shell commands, edits files, runs tests, and iterates on failures — with you approving or rejecting each action.

The tool’s design reflects Anthropic’s “agentic coding” thesis: the bottleneck in software development isn’t typing speed, it’s the loop of understand → change → verify. Claude Code automates that loop while keeping a human in the approval path.

Core value proposition

Three things distinguish it in practice:

  1. Repository-scale context. Claude Code builds a working model of your codebase through file reads and search, not just the file you have open. It can answer “where is authentication middleware applied?” by actually tracing the code.
  2. Execution, not suggestion. It runs npm test, reads the failure, edits the source, and re-runs — the same loop you’d do manually.
  3. Explicit permissioning. Every file write and shell command is surfaced for approval by default, with configurable allowlists for trusted operations.

What makes it different from alternatives

The Torvalds page-cache episode is the best illustration. Claude Code produced a plausible, working patch — and human reviewers still caught a race condition. That’s the correct division of labor: the agent handles the mechanical work of tracing call sites and drafting changes across a large codebase; humans own concurrency reasoning and correctness review. Tools that hide this distinction (auto-merge, “just trust the agent”) are the ones generating incident reports.

Compared with inline assistants, Claude Code is slower per-keystroke but dramatically faster per-task. Compared with fully autonomous agents, it’s more conservative — which, as the Linux example shows, is a feature.

🚀 Getting Started

Installation

Claude Code ships as an npm package and requires Node.js 18+.

# Verify Node version (18+ required)
node --version

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

# Verify installation
claude --version

# First run — authenticates via browser OAuth
claude

On first launch you’ll authenticate against your Anthropic account (Claude Pro/Max subscription or API billing). For CI or headless environments, set an API key instead:

export ANTHROPIC_API_KEY="sk-ant-..."

Configuration

Claude Code reads layered settings: project-level .claude/settings.json (committed), user-level ~/.claude/settings.json (personal), and an enterprise policy layer if your org manages it.

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

The allow list is where you reclaim time: pre-approving test and lint commands means the agent can iterate without interrupting you for every run. The deny list is where you prevent the kind of incident that generates Hacker News threads — block reads of .env and destructive commands outright.

The most important configuration file is CLAUDE.md, a project memory file that Claude Code loads into every session:

# CLAUDE.md

## Project
Payments service. Node 20, TypeScript strict, PostgreSQL 16.

## Commands
- Test: `npm test` (Jest; run single file with `npm test -- path`)
- Lint: `npm run lint -- --fix`
- Typecheck: `npm run typecheck`

## Conventions
- All DB access goes through `src/db/repositories/` — never raw SQL in handlers
- Errors: throw typed `AppError` subclasses from `src/errors.ts`
- Migrations: use `npm run db:migrate:create`, never hand-edit generated files

## Known gotchas
- `legacy/` directory is frozen — do not modify
- Integration tests require `docker compose up -d db` first

A good CLAUDE.md is worth more than any prompt you’ll write. It’s the difference between an agent that follows your conventions and one that invents a fourth error-handling pattern.

💡 Core Features

Feature 1: Agentic task execution with permission modes

Claude Code operates in several permission modes, cycled with Shift+Tab:

Plan mode is the underrated one. For any non-trivial change, start there:

claude
> /plan Refactor the webhook delivery system to add exponential backoff
  with a dead-letter queue. Don't write code yet.

The agent will trace the current implementation, identify every call site, and produce a step-by-step plan. You review the plan — catching the architectural mistake before it’s 400 lines of diff — then exit plan mode and let it execute.

Real-world application: This is precisely the workflow the Linux page-cache patch needed. Plan mode forces the agent to enumerate concurrency assumptions before writing code, making the race condition visible at review time rather than in a bisect two weeks later.

Feature 2: Custom slash commands

Slash commands are reusable prompts stored as Markdown files in .claude/commands/. They’re the mechanism for encoding team workflows.

<!-- .claude/commands/review-pr.md -->
Review the current branch's diff against main.

1. Run `git diff main...HEAD` and read every changed file in full context.
2. Check for: SQL injection, missing input validation, unhandled promise
   rejections, and N+1 queries in repository methods.
3. Verify every new function has a test; if not, list the gaps.
4. Output a table: File | Severity | Issue | Suggested fix.

Do not modify any files. This is a review only.

Invoke it with /review-pr. Commit the file, and every developer on the team gets the same review standard.

# List available commands
> /help

# Run a custom command
> /review-pr

Real-world application: A payments team I spoke with runs /review-pr in CI via headless mode, posting the output as a PR comment before human review begins. Reviewers report spending their time on design rather than catching missing null checks.

Feature 3: MCP integrations

The Model Context Protocol (MCP) lets Claude Code connect to external systems — databases, issue trackers, monitoring — as first-class tools.

# Add an MCP server (example: GitHub)
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# Add a Postgres server for schema-aware queries
claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres \
  "postgresql://localhost:5432/app_dev"

# List configured servers
claude mcp list

Once connected, the agent can query your actual database schema instead of guessing column names, or read the linked GitHub issue for context:

> The bug in issue #4821 says checkout fails for orders over $10k.
  Pull the issue, check the orders table schema, and find the validation
  path that rejects it.

Real-world application: Schema-aware agents eliminate an entire class of hallucinated-column errors. The agent queries information_schema and writes migrations against real types — a meaningful accuracy gain over pasting schema dumps into a chat window.

🛠️ Advanced Workflows

Workflow 1: Test-driven bug fixing with git safety

The pattern that survives contact with production code: isolate, reproduce, fix, verify — with a clean rollback point.

# 1. Create a safety branch
git checkout -b fix/webhook-retry

# 2. Start Claude Code and reproduce first
claude
> The webhook retry test in tests/webhooks/retry.test.ts is failing
  intermittently. Run it 20 times, capture the failure mode, and
  explain the root cause before proposing any fix.

# 3. After diagnosis, request the fix with constraints
> Fix the root cause. Constraints:
  - No changes outside src/webhooks/
  - Add a regression test that fails on the current code
  - Run the full webhook test suite 50 times to confirm stability

# 4. Verify independently
> /review-pr

# 5. Exit and review the diff yourself

# After exiting Claude Code
git diff main...HEAD
npm test -- tests/webhooks/
git commit -m "fix(webhooks): eliminate retry race on concurrent delivery"

The key discipline: reproduce before fixing, and stress-test after. An intermittent failure “fixed” without a reproduction is a guess. Running the suite 50 times is cheap; discovering the fix didn’t work in production is not.

Workflow 2: Headless CI integration

Claude Code runs non-interactively with -p (print mode), making it scriptable:

#!/usr/bin/env bash
# scripts/ci-review.sh — run in CI on every PR

set -euo pipefail

# Generate diff and pipe to Claude Code in headless mode
git diff origin/main...HEAD > /tmp/pr.diff

claude -p "Review this diff for security issues and logic errors. \
Output only findings as a markdown table with columns: \
File | Line | Severity | Issue. If no issues, output 'LGTM'." \
  --allowedTools "Read" \
  < /tmp/pr.diff > /tmp/review.md

# Post as PR comment (requires gh CLI authenticated)
gh pr comment "$PR_NUMBER" --body-file /tmp/review.md

# .github/workflows/claude-review.yml
name: Claude Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm install -g @anthropic-ai/claude-code
      - run: ./scripts/ci-review.sh
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          PR_NUMBER: ${{ github.event.pull_request.number }}

Note the --allowedTools "Read" flag: in CI, the agent gets read-only access. It cannot modify files or execute commands. This is the correct trust boundary for automated review — the same lesson the page-cache patch teaches at a larger scale.

Workflow 3: Multi-agent collaboration

The CleanCode Show HN project points at the emerging pattern: Claude Code and a second agent working the same problem from different angles. You can approximate this today with parallel sessions:

# Terminal 1: Claude Code implements
cd ~/projects/api && claude
> Implement rate limiting middleware per the spec in docs/rate-limit.md

# Terminal 2: second session reviews independently
cd ~/projects/api && claude
> Read the uncommitted changes in src/middleware/rate-limit.ts.
  Assume the author is wrong. Find the failure mode under
  concurrent requests from the same IP.

Two sessions, two contexts, adversarial framing. The reviewer session has no memory of the implementation rationale — which is exactly what makes its review useful.

📊 Comparison with Alternatives

FeatureClaude CodeCursor (Agent Mode)GitHub Copilot (Workspace)
InterfaceTerminal-native CLIIDE fork (VS Code)IDE plugin
Repository-scale context✅ Full repo traversal✅ Full repo indexing✅ Workspace indexing
Shell execution & test iteration✅ Native, permissioned✅ With approval⚠️ Limited
Headless / CI mode✅ -p flag, scriptable❌⚠️ Limited
Custom reusable commands✅ Slash commands in repo✅ Rules files⚠️ Limited
MCP integrations✅ Full support✅ Supported⚠️ Partial
Project memory file✅ CLAUDE.md✅ .cursorrules✅ Instructions files
Plan-before-execute mode✅ Explicit plan mode⚠️ Implicit❌
Works without IDE✅❌❌
Audit trail of agent actions✅ Full transcript⚠️ Partial⚠️ Partial

The honest summary: Cursor offers a more polished in-editor experience; Copilot has the deepest IDE integration and enterprise footprint. Claude Code wins where the work is outside the editor — CI pipelines, multi-repo scripts, terminal-driven workflows — and where you want the agent’s actions logged and permissioned at the command level.

🎯 Pro Tips

  1. Write CLAUDE.md before your first prompt. Every session starts cold; the memory file is how you avoid re-explaining your stack, conventions, and forbidden directories. Update it whenever you correct the agent twice on the same thing — that’s a signal the instruction belongs in the file, not in your prompt.

  2. Use plan mode for anything touching concurrency, migrations, or auth. These are the categories where a wrong first step costs hours. The page-cache race condition is the canonical example: a plan that enumerated locking assumptions would have surfaced the flaw before the diff existed.

  3. Deny-list destructive commands and secrets at the project level. Put Bash(rm -rf:*) and Read(./.env) in .claude/settings.json and commit it. Your teammates’ agents inherit the guardrails automatically — and the GitHub suspension saga is a reminder that platform-level safety nets are not something to rely on.

  4. Stress-test fixes, don’t just run the suite once. For any bug involving timing, concurrency, or retries, ask the agent to run the relevant tests 50+ times. A single green run proves nothing about a race.

  5. Keep agent sessions short and scoped. Context degrades over long sessions. When a task is done, exit and start fresh for the next one — /clear inside a session works too. A focused 20-minute session outperforms a meandering two-hour one.

  6. Use headless mode with read-only tools in CI. Automated review is valuable; automated writes in CI are an incident waiting to happen. --allowedTools "Read" is your friend.

🔗 Resources

The through-line across this month’s news: agentic tools have graduated from novelty to infrastructure, and the developers getting value from them are the ones treating them like junior engineers with root access — capable, fast, and always in need of review.

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