Claude Code

Claude Code is Anthropic's terminal-first coding agent. It excels when you want AI in SSH sessions, CI pipelines, or outside a GUI IDE.

Cursor vs Claude Code

Many teams use both: Cursor for day-to-day editing, Claude Code for batch jobs and CI.

Install

npm install -g @anthropic-ai/claude-code
# Set your API key
export ANTHROPIC_API_KEY=sk-ant-...

Official docs: Claude Code overview.

Session Walkthrough: Fix a Failing Test

The same Plan-before-implement discipline that applies in Cursor applies in the terminal.

cd my-project
claude

Step 1 — Plan first, no edits yet:

> Read src/utils/formatDate.test.ts and this test failure.
> Propose a plan limited to formatDate.ts and its test. Do not implement yet.
>
> Failure:
>   Expected "Jan 1, 2026"
>   Received "1/1/2026"

Claude Code will describe what it plans to change and why. Review it before proceeding.

Step 2 — Implement with a scope constraint:

> Implement the plan. Only edit src/utils/formatDate.ts.
> Run npm test -- formatDate when done. Stop if more than 2 files change.

Step 3 — If the agent touches unrelated files:

> Stop. Revert changes to files outside src/utils/formatDate*.
> Show git diff --stat only.

Step 4 — If tests still fail, paste only the new error:

> Still failing:
>   AssertionError: expected "Jan 1" received "January 1"
>
> Fix formatDate.ts only. Do not change the test file.

See Agentic Workflows for the full failure recovery playbook.

AGENTS.md and Project Context

Claude Code (and Cursor, Codex, and other agents) reads AGENTS.md at the repo root for persistent instructions:

# AGENTS.md

## Stack
- Next.js 15 App Router, React 19, TypeScript strict
- Drizzle ORM + Postgres, Zod for validation
- Tailwind CSS v4

## Conventions
- Named exports only (no default exports except page.tsx / layout.tsx)
- Server components by default; "use client" only when needed
- Colocate tests: src/lib/foo.test.ts alongside src/lib/foo.ts

## File Boundaries
- Do not modify: package-lock.json, .github/**, drizzle/migrations/**
- Test command: npm test
- Lint command: npm run lint

## Security
- Auth check required on all API routes: const session = await auth()
- Never hardcode API keys; use process.env

See Project Rules for team rollout, CODEOWNERS, and .cursor/rules/ templates.

Skills

Skills are reusable instruction packs for repeated tasks — code review, release notes, migration checklists. Store them where Claude Code expects skills in your environment and invoke by name.

Example skill file:

# skills/security-review.md

Review the diff for these security patterns:
1. SQL injection: parameterized queries only
2. Secrets: no API keys, passwords, or tokens in source
3. Auth: every mutation must call `await auth()` server-side
4. XSS: no dangerouslySetInnerHTML without sanitization
5. Prompt injection: user content wrapped, not mixed into system instructions

Output a checklist with pass/fail for each category and a severity rating.

Use skills for: team conventions, security review checklists, release workflows, onboarding runbooks.

Full authoring guide: Agent Skills (SKILL.md).

Hooks

Hooks run scripts at lifecycle points (before/after tool use, on commit). Use them to:

• Block edits to protected paths (CI configs, migration files)
• Auto-run linters after file writes
• Log agent actions for audit trails

Example hook (blocks edits to drizzle/migrations/):

{
  "hooks": {
    "before_file_write": {
      "command": "bash -c 'if echo \"$FILE_PATH\" | grep -q \"drizzle/migrations\"; then echo \"Protected path: migrations are not editable by agents\" && exit 1; fi'"
    }
  }
}

Hooks are defined in your Claude Code configuration. See Claude Code hooks docs for current config format.

SDK Automation

The Claude Code SDK (@anthropic-ai/claude-agent-sdk) lets you embed agents in scripts, bots, and CI:

// scripts/summarize-pr.ts
import { ClaudeCodeAgent } from "@anthropic-ai/claude-agent-sdk";

const agent = new ClaudeCodeAgent({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: "claude-haiku-4-20250514",
});

const diff = execSync("git diff origin/main...HEAD").toString().slice(0, 10000);

const { output } = await agent.run(
  `Summarize this PR diff in 3-5 bullet points for a code review description:\n\n${diff}`
);

console.log(output);

Keep API keys in CI secrets (${{ secrets.ANTHROPIC_API_KEY }}). See Agentic Workflows — CI Integration for full GitHub Actions examples.

When Claude Code Shines

• Remote servers: no GUI required
• Batch refactors: "update all imports from X to Y across 40 files"
• CI triage: parse failing logs, propose minimal fixes
• Scripted pipelines: repeatable prompts with exit codes
• Headless automation: GitHub Actions, cron jobs, deploy hooks

When to Prefer an IDE Agent

• Visual diff review across many files
• Debugging with breakpoints
• JSX/CSS work needing live preview
• Day-to-day feature development where seeing changes in context matters

Related

• OpenAI Codex
• Cursor
• Agentic Workflows
• Project Rules
• Choosing a Tool