Install and authenticate.
Claude Code is a terminal-native agent. Install it once, then run it from any repo root.
# npm (macOS / Linux / WSL) npm install -g @anthropic-ai/claude-code # Homebrew (macOS) brew install --cask claude-code # First run — opens browser OAuth or prompts for API key cd my-app && claude # Verify model access claude --version
Two auth paths: a Claude subscription (Pro/Max/Team) for bundled agent usage, or an Anthropic API key for pay-per-token billing. Web teams on a subscription often still add an API key for CI automations where OAuth is awkward.
Global config lives under ~/.claude/. Project overrides go in .claude/settings.json (committed) and .claude/settings.local.json (gitignored, machine-specific).
CLAUDE.md vs AGENTS.md.
Claude Code looks for project context the same way every modern agent does: a markdown file at the repo root loaded into every turn. Historically that file was CLAUDE.md; the cross-vendor standard is now AGENTS.md.
Our recommendation: maintain one canonical AGENTS.md (use the AGENTS.md guide's generator) and add a one-line symlink or note in docs if your Claude Code version prefers CLAUDE.md. Never maintain two different files with diverging rules.
Claude Code also reads, in order:
AGENTS.mdorCLAUDE.mdat repo root.claude/rules/*.md— always-on constraints (glob-scoped when possible).claude/skills/or projectskills/— on-demand capabilities- Nested
AGENTS.mdin subdirectories when editing inside them
---
paths:
- "src/components/**"
- "src/app/**"
---
# Styling rules
- Use design tokens from `src/styles/tokens.css`.
- No inline `style={{ }}` except for truly dynamic values (transforms, calculated widths).
- Prefer native CSS over runtime CSS-in-JS.Model and mode picker.
Claude Code defaults to Sonnet for good reason. The token cost guide math applies directly: Opus on a 50-turn refactor session adds up fast. Switch models inside a session with /model.
| Task | Model | Notes |
|---|---|---|
| Feature work across 3–8 files | Sonnet 4.6 | Default. Best cost-to-quality for tool-heavy loops. |
| Flaky test / race condition hunt | Opus 4.7 | Extended thinking pays off when the bug is non-obvious. |
| Read-only security or a11y audit | Opus 4.7 | Pair with a read-only permission profile (see widget below). |
| Mechanical migration (rename API, update imports) | Sonnet 4.6 | High volume, low ambiguity. Don't burn Opus on grep-shaped work. |
| Quick one-file tweak | Haiku 4.5 | When the change is obvious and you want a cheap second opinion. |
Auto mode (when enabled) picks Sonnet vs Opus from request shape. Fine once your AGENTS.md is stable; on a brand-new repo, manually pick Sonnet for the first dozen turns so Auto has signal about complexity.
Permissions and sandbox.
Claude Code's permission system is the difference between "helpful pair programmer" and "ran npm install evil-package while I was at lunch." Every tool call (read, edit, bash) can be allow-listed, denied, or prompted.
Three profiles web teams actually use:
| Profile | When | Shell | Writes |
|---|---|---|---|
| Cautious | Production repos, client work, first week on a codebase | npm run *, pnpm *, git status only |
Prompt on every edit outside src/ |
| Balanced | Daily feature development | Test/lint/dev scripts; deny install, push, curl |
Auto-approve edits under repo root; deny .env* |
| Full agent | Throwaway branches, scaffolding, trusted sandboxes | Broader bash; still deny secrets and git push |
Auto-approve with post-turn review discipline |
{
"permissions": {
"allow": [
"Read(**/*)",
"Edit(**/*)",
"Bash(npm run *)" ,
"Bash(pnpm *)" ,
"Bash(git status)",
"Bash(git diff *)"
],
"deny": [
"Read(.env*)",
"Read(**/*.pem)",
"Bash(npm install*)" ,
"Bash(pnpm add *)" ,
"Bash(git push*)" ,
"Bash(curl *)" ,
"Bash(wget *)"
]
}
}Match this with the security guide: disable auto package install in the UI and deny install commands in permissions. Belt and suspenders.
MCP servers.
Claude Code was the first major agent to ship MCP support at scale. Config lives in ~/.claude.json or project .mcp.json depending on version; the shape matches Cursor and OpenCode.
The same seven servers from the MCP guide earn their keep here: Playwright, Postgres, GitHub, Linear, Sentry, Figma, Filesystem. Start with two, not seven.
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["-y", "@playwright/mcp"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
}
}
}Subagents and session forking.
Claude Code's subagent model is the most polished in the terminal-CLI category. The agent can spawn focused workers (test writer, doc updater, reviewer) that inherit context but run with narrower tools.
Session forking (branch sessions) lets you explore an approach without polluting the main conversation. Reach for it when you want two competing implementations: fork, run both, merge the winner back. Don't fork every turn; each fork still costs tokens to re-establish context.
For true parallelism across four agents, graduate to git worktrees or Conductor as described in the parallel agents guide. Subagents handle delegation inside one session; worktrees handle delegation across machines and editors.
| Pattern | Tooling | Best for |
|---|---|---|
| Delegate a subtask inside one feature | Claude Code subagent | "Write tests while I finish the component" |
| Try two approaches, pick one | Session fork | API design spikes, refactor strategies |
| Four unrelated tasks at once | Worktrees + Conductor | Sprint crunch with review discipline |
Hooks worth setting up.
Hooks fire on agent lifecycle events. Three that pay off for web repos (same philosophy as the Cursor hooks section):
- PostToolUse (Edit) — run Prettier on the touched file.
- Stop — run
eslint --fixon changed paths only. - PreToolUse (Bash) — block commands matching
npm install,curl, orgit pushunless you explicitly override.
Keep hook runtime under two seconds or the agent loop feels broken.
{
"hooks": {
"PostToolUse": [{
"matcher": "Edit|Write",
"command": "pnpm exec prettier --write $CLAUDE_FILE_PATHS"
}],
"Stop": [{
"command": "pnpm exec eslint --fix $(git diff --name-only -- '*.ts' '*.tsx')"
}]
}
}Live: permission profile builder.
Pick a baseline profile and toggle the rules your repo needs. Copy the generated .claude/settings.json into your project. Runs entirely in your browser.
Common pitfalls.
Claude Code makes Opus feel effortless. That doesn't mean it's cheap. Run Sonnet until you hit a wall you can name; then escalate.
Edit(**/*) includes infra/terraform, .github/workflows, and prisma/migrations. Deny or prompt on paths that should never be agent-edited without human review.
Three subagents writing in the same directory produces the same conflicts as three human devs. Scope each worker to a folder or file set before spawning.