Claude Code Best Practices (2026)

Installation is one line: `npm install -g @anthropic-ai/claude-code` or via Homebrew (`brew install claude-code`). After install, `claude --version` confirms the binary is on your path.

**Auth decision: Max plan vs API key.** The Claude Max plan ($100/mo for ~5x Pro limits, $200/mo for ~20x) bundles Claude Code usage into your subscription — no per-token billing, no surprise invoice. The API-key path bills per-token at standard rates ($3/$15 per 1M for Sonnet, $15/$75 for Opus) directly to your Anthropic console account.

**When Max wins:** heavy daily users. The crossover is around $30-50/mo of equivalent API spend — anything above that, Max's flat fee comes out ahead. Most production Claude Code users land at $200/mo Max equivalent in API spend within 30-60 days of adoption.

**When API key wins:** very light users (a few hours per week of Claude Code), users who want exact per-task cost visibility, teams that need to chargeback usage to specific projects (API spend can be tagged per request).

**Auth flow.** For Max plan: `claude` (without args), follow the OAuth flow in browser, you're authenticated. For API key: `export ANTHROPIC_API_KEY=sk-ant-...` in your shell rc; Claude Code picks it up automatically.

**Workspace setup.** Claude Code respects your working directory — `cd` to your project, run `claude`, the session starts scoped to that directory. Claude Code reads CLAUDE.md / AGENTS.md from the working directory on session start (more on this in Phase 2). For multi-repo work, run `claude` from a parent directory that contains all the repos.

**Pre-flight sanity check:** in a project, type `claude` then ask 'list the top-level directories.' Claude should run `ls` and report. If it doesn't (or asks for permission you can't grant), check shell permissions and `claude doctor` for diagnostics.

Claude Code reads `CLAUDE.md` (or `AGENTS.md`) from the working directory on session start. This is the most underused leverage point in the entire tool. The file's content is injected into every prompt — your project's stack, conventions, and important caveats become part of Claude's working context for the entire session.

**CLAUDE.md vs AGENTS.md.** Both filenames work. `AGENTS.md` is the increasingly common cross-tool standard (also read by other AI tools), so we recommend it as the canonical file. `CLAUDE.md` is Claude-Code-specific. If you have both, Claude Code reads both — but most teams just maintain `AGENTS.md` and skip `CLAUDE.md`.

**What to put in AGENTS.md.** A starter template that works for most projects:

```markdown # Project: WaitlistPro ## Stack - Next.js 16 App Router + TypeScript - Tailwind + shadcn/ui - Supabase (Postgres + Auth + Storage) - Stripe Checkout for payments - Vitest + Playwright for testing - Deployed via Vercel ## Key directories - `app/` — App Router pages and layouts - `components/` — shared React components - `components/ui/` — shadcn primitives (do not hand-write replacements) - `lib/` — utilities, clients (supabase, stripe) - `lib/schemas/` — Zod schemas (single source of truth for types) - `supabase/migrations/` — SQL migrations (always include RLS) ## Conventions - Default to Server Components; mark Client Components with 'use client' - Server actions use `'use server'` directive; always validate input with Zod - Database access via typed Supabase client from `lib/supabase.ts` - All new tables get RLS policies in the same migration - Tests live alongside the file they test: `Button.tsx` + `Button.test.tsx` ## Anti-patterns (do not do) - Do not use `pages/` — fully on App Router - Do not use `unstable_cache` — use the `use cache` directive instead - Do not skip Zod validation on server actions - Do not write custom Button/Input/Modal — use shadcn primitives ## Important commands - `npm run dev` — local dev server - `npm run test` — Vitest unit tests - `npm run test:e2e` — Playwright E2E - `npm run typecheck` — strict TypeScript check - `npx supabase db push` — apply migrations ## Open questions for the AI If you're unsure about a convention not listed here, ASK before assuming. Better to clarify upfront than rewrite. ```

**Why this works.** Every Claude Code prompt now starts with this context baked in. The user prompts get shorter ('add a new server action for X') because Claude already knows the project. The output quality jumps because Claude is operating with team-specific defaults instead of generic defaults.

**Token cost.** AGENTS.md typically runs 500-2000 tokens. Injected on every prompt. At Sonnet's $3/M input rate, that's $0.0015-$0.006 per prompt of overhead — negligible compared to the quality and time savings.

**Keep it focused.** Don't dump every convention into AGENTS.md. Aim for 100-300 lines. Anything that's per-directory or per-concern should live in a more targeted place (a SKILLS file for repeatable workflows, a Cursor rule for IDE-specific guidance). AGENTS.md is the top-level always-on context.

**Update it as the project evolves.** Stack migrations, new conventions, new key directories — all go in AGENTS.md in the same PR that introduces the change. A stale AGENTS.md is worse than a missing one because it pollutes prompts with outdated context.

Claude Code has two mechanisms for packaging reusable workflows: skills (richer, file-based) and slash commands (lighter, prompt-based). Both load on session start; both are user-invokable. The choice depends on complexity.

**Slash commands** are user-defined prompts you invoke with `/commandname` in the chat. Live in `~/.claude/commands/<name>.md` (user-level, available in every project) or `.claude/commands/<name>.md` (project-level, committed to repo). The file is a markdown body — when you type `/commandname`, Claude treats the body as the prompt.

**Example slash command** (`.claude/commands/audit.md`):

```markdown Do a security audit of this codebase. Look for: - Hardcoded secrets (API keys, passwords, tokens) - Missing RLS policies on Supabase tables - Server action handlers without Zod validation - Public API routes that don't check auth - Use of dangerouslySetInnerHTML - SQL injection vectors (user input concatenated into queries) - XSS vectors in user-rendered content Report findings as a markdown table with: file, line, severity (low/medium/high), description, suggested fix. ```

Invoke with `/audit` and Claude runs the audit immediately.

**Skills** are richer — they can include multiple files, scripts, and structured instructions. A skill is a directory under `~/.claude/skills/<name>/` containing a `SKILL.md` (the skill definition) plus any helper scripts or templates. Skills are invoked by Claude implicitly when the user's prompt matches the skill's trigger description, OR explicitly via `/skill <name>`.

**When to use skills vs slash commands.** Slash command = a single prompt you reuse. Skill = a multi-step workflow with logic (run tests, parse output, take action based on results). Skill = something that benefits from structured definition and helper scripts. Slash command = quick prompt template.

**Skill example: weekly-dep-bump.** A skill that runs `npm outdated`, parses the output, prompts you to confirm bumps, applies them, runs tests, opens a PR. Lives in `~/.claude/skills/weekly-dep-bump/` with a SKILL.md, an `apply.sh` helper, and a `pr-template.md`. Invokable via 'run the weekly dep bump' (trigger match) or explicitly via `/skill weekly-dep-bump`.

**Discoverability.** Both slash commands and skills appear in Claude Code's autocomplete when you type `/`. Skills also appear in the help output. Keep names short and descriptive — `/audit` not `/run-security-audit-of-codebase`.

Hooks are shell commands that fire automatically at specific points in Claude Code's execution. Configured in `~/.claude/settings.json` (global) or `.claude/settings.json` (project-level, committed to repo). The three main hook types: PreToolUse (before a tool fires), PostToolUse (after a tool completes), Stop (when Claude finishes a turn).

**Why hooks matter.** They're the only mechanism that gives you deterministic behavior in an AI tool. Skills and prompts are advisory — Claude might follow them or not. Hooks always fire. Use them for the things you absolutely need to happen regardless of what Claude does.

**Example hook config** (`.claude/settings.json`):

```json { "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [{ "type": "command", "command": "~/.claude/scripts/block-destructive.sh" }] } ], "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "~/.claude/scripts/auto-format.sh" }] } ], "Stop": [ { "hooks": [{ "type": "command", "command": "~/.claude/scripts/log-session.sh" }] } ] } } ```

**Hook example 1: block destructive commands** (`block-destructive.sh`). Reads the tool input from stdin (JSON), checks if it's a destructive command (`rm -rf`, `git push --force`, `DROP TABLE`), exits with non-zero to block. Claude sees the block and either tries a different approach or asks the user.

**Hook example 2: auto-format on edit** (`auto-format.sh`). Reads which file was edited, runs the project's formatter (prettier, eslint --fix), and silently fixes any formatting drift. The user never sees the formatter run; the file just ends up clean.

**Hook example 3: log to a daily journal** (`log-session.sh`). On Stop (session end), appends a summary of what Claude did to `~/.claude/journal/YYYY-MM-DD.md`. Builds up a record of AI-assisted work over time — useful for retros, audit trails, billing.

**Hook example 4: cost ceiling.** A PreToolUse hook that checks a running token-count file; if today's cost is over $X, exit with non-zero and force a model downgrade or block the request. Prevents runaway agent spend.

**Hook safety.** Hooks run with your shell permissions. Don't give Claude Code access to a hook script that does dangerous things — the agent can't modify hook scripts itself (they're read at session start), but malicious prompts could try to influence what the hook does indirectly. Keep hook scripts simple and safe.

Claude Code can spawn child agents that run in parallel. The parent agent receives the children's results and synthesizes. This unlocks tasks that would take hours sequentially — codebase audits, multi-repo work, fan-out research.

**The subagent mechanism.** You ask Claude something big ('audit every microservice in this monorepo for outdated dependencies'). Claude decides whether to fan out — typically yes for tasks that decompose into N independent subtasks. Each child agent gets the same project context (CLAUDE.md, model, MCPs) and works on its slice in parallel.

**Where subagents shine.** Codebase-wide audits (security, accessibility, performance), multi-file refactors where files can be processed independently, parallel research (fetch 10 URLs in parallel and synthesize), test-generation across many modules. Tasks with clear independence — child A's work doesn't depend on child B's.

**Where subagents don't help.** Sequential tasks (each step depends on the prior step's output), small tasks (overhead of spawning children isn't worth it), tasks where consistency between children matters (style decisions made independently won't match).

**Cost implication.** Each subagent is a full inference cost. A 5-way fan-out costs 5x a single-agent task. The wall-clock saving is real (5 minutes vs 25 minutes), but the dollar cost is higher. For a daily-driver workflow, parallelize when the time savings matter; sequentialize when cost matters more.

**How to invoke explicitly.** Prompt with 'spawn N parallel agents to do X for each Y' — Claude understands the pattern and decomposes. Or use a skill that has the parallel-fan-out logic encoded.

**Sonnet vs Opus for subagents.** Subagents inherit the parent's model by default. For fan-out work, prefer Sonnet — Opus is overkill for most child-agent slices, and the cost multiplier from running N Opus agents in parallel adds up fast.

**Synthesis quality.** The parent agent receives all child outputs and synthesizes. Synthesis quality depends on parent model — even if children are Sonnet, you may want the parent to be Opus for the final synthesis pass. Set parent vs child models explicitly when this matters.

MCP (Model Context Protocol) servers are external capability extensions. They add tools Claude doesn't have natively. The community has hundreds of MCP servers; the practical 5-pack covers 90% of real-world value.

**Filesystem MCP** (`@modelcontextprotocol/server-filesystem`). Exposes file operations beyond Claude's working directory. Useful for cross-project work, reading config from `~/.config/`, accessing reference repos. Install: `claude mcp add filesystem npx @modelcontextprotocol/server-filesystem ~/repos`.

**GitHub MCP** (`@modelcontextprotocol/server-github`). Read/write GitHub issues, PRs, comments, releases. Killer feature: 'summarize this PR's discussion' and 'compose a PR description from the diff.' Install: `claude mcp add github npx @modelcontextprotocol/server-github` (requires GITHUB_TOKEN env var).

**Slack MCP** (`@modelcontextprotocol/server-slack`). Send messages, read channels, post threaded updates. Useful for posting deploy notifications, summarizing thread discussions for context. Install: `claude mcp add slack npx @modelcontextprotocol/server-slack` (requires SLACK_BOT_TOKEN).

**Playwright MCP** (`@modelcontextprotocol/server-playwright`). Drives a real browser. Useful for E2E test generation, debugging UI bugs visually (Claude can take screenshots and reason about them), scraping reference data from the web. Install: `claude mcp add playwright npx @modelcontextprotocol/server-playwright`.

**Web Fetch MCP** (built-in or `@modelcontextprotocol/server-fetch`). Lets Claude read documentation URLs. When you reference a library Claude doesn't have priors on, Claude can fetch the docs and use them in context. Install: most builds include this by default; if not, `claude mcp add fetch npx @modelcontextprotocol/server-fetch`.

**MCP configuration lives in** `~/.claude/mcp.json` (user-level) or `.claude/mcp.json` (project-level, committed). Format:

```json { "mcpServers": { "filesystem": { "command": "npx", "args": ["@modelcontextprotocol/server-filesystem", "/Users/me/repos"] }, "github": { "command": "npx", "args": ["@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "..." } } } } ```

**Discovery.** `claude mcp list` shows installed servers and their status. `claude mcp` (no args) opens an interactive UI for browse/install. The marketplace at modelcontextprotocol.io has hundreds of community servers; quality varies — stick to official/well-known ones for production.

**Security note.** MCP servers run with your shell permissions and have access to whatever the server's API does. A malicious MCP server is a serious threat. Only install from sources you trust (official Anthropic, well-known open-source maintainers). Review the server's code before installing if it's not widely known.

Claude Code lets you set the model per-session. The right model choice cuts your bill 60-80% without quality loss on most tasks. The wrong choice — defaulting to Opus for everything — burns money on work Sonnet handles fine.

**The 3-tier model heuristic.**

- **Opus 4.7 ($15/$75 per 1M):** for hard refactors, complex multi-file changes, architecture decisions, anything where one mistake costs hours. Reserve for ~10-20% of work.

- **Sonnet 4.6 ($3/$15 per 1M):** for general feature work, medium-complexity bug fixes, code reviews, most agent-mode runs. The default — ~70-80% of work.

- **Haiku 4.5 ($1/$5 per 1M):** for trivial work, read-only tasks (search the codebase, list files, summarize a function), parallel subagent slices. ~10-15% of work.

**Per-session model setting.** Start Claude with `claude --model claude-sonnet-4-6` to set the default for that session. Switch mid-session with `/model claude-opus-4-7`. The conversation history carries forward.

**Auto-routing.** Claude Code supports per-task model routing — Claude itself decides the model based on perceived task complexity. Decent default; sometimes routes Opus when Sonnet would suffice. Heavy users find explicit-model-picking saves 30-50% vs auto-routing.

**Prompt caching for free savings.** When you're iterating in a long session on the same files, Claude Code's built-in prompt caching kicks in automatically (Anthropic's cached input rate is 10% of standard input — 90% savings on cache hits). For session length > 30 min on the same files, caching can save 40-60% on the input portion of the bill.

**Max plan vs API: when each is cheaper.** Max $100/mo covers ~$200-300/mo of equivalent API spend at heavy use. Max $200/mo covers ~$500-700/mo. If your monthly API bill is consistently >$150, switching to Max usually saves. If under $50, API stays cheaper.

**Budget alerting.** Set up a PreToolUse hook that reads a running spend ledger and refuses to fire if today's spend is over your cap. Prevents runaway agent burn. Anthropic also surfaces spend in the Console — review weekly during heavy-use periods.

**Antipattern 1: prompting Claude Code like ChatGPT.** ChatGPT prompts are stateless — every message is full context. Claude Code is session-stateful with persistent project context. Long, fully-contextualized prompts waste tokens on stuff Claude already knows from AGENTS.md. Short, intent-focused prompts work better.

**Antipattern 2: not having AGENTS.md.** The single biggest leverage point in Claude Code. Without it, every session starts cold — Claude doesn't know your stack, conventions, or anti-patterns. Most users skip this step and never realize they're operating at 50% of Claude Code's potential.

**Antipattern 3: running Opus for everything.** Opus is 5x more expensive than Sonnet for ~5pp better benchmark on most tasks. Default to Sonnet; reserve Opus for the 10-20% of work where the quality lift matters.

**Antipattern 4: no hooks.** Hooks are the only deterministic guardrail in an AI tool. At minimum: a PostToolUse hook on Edit/Write that runs your formatter, and a PreToolUse hook on Bash that blocks destructive commands. Five minutes of setup, prevents whole categories of mistakes.

**Antipattern 5: 50+ MCP servers installed.** Each MCP server adds to startup time and context overhead. Stick to the 5-pack for most work; add more only when you have a specific need.

**Antipattern 6: not using subagents for fan-out work.** Codebase audits, multi-file generations, parallel research — all are 5-10x faster with subagents. Many users never invoke this capability and waste hours on sequential work.

**Antipattern 7: ignoring the session log.** Claude Code logs every session by default. Reviewing logs after a heavy session shows you which prompts worked, which models were over-used, which hooks fired (or didn't). 10 minutes of review per week sharpens your usage substantially.

**Antipattern 8: skipping the Max plan when you're heavy.** If you're spending >$150/mo on API, you're leaving $50-100/mo on the table by not switching to Max $100. Check your Anthropic Console monthly and migrate when the math says so.

Here are the four files we drop into every new Claude Code project. Adjust for stack specifics; ship.

**1. AGENTS.md** — the project memory. Template covered in Phase 2 above. ~150 lines, takes 30 minutes to write the first time.

**2. .claude/settings.json** — hooks config:

```json { "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [{ "type": "command", "command": "~/.claude/scripts/block-destructive.sh" }] } ], "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "~/.claude/scripts/auto-format.sh" }] } ], "Stop": [ { "hooks": [{ "type": "command", "command": "~/.claude/scripts/log-session.sh" }] } ] } } ```

**3. .claude/mcp.json** — MCP server config:

```json { "mcpServers": { "filesystem": { "command": "npx", "args": ["@modelcontextprotocol/server-filesystem", "."] }, "github": { "command": "npx", "args": ["@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" } }, "playwright": { "command": "npx", "args": ["@modelcontextprotocol/server-playwright"] } } } ```

**4. .claude/commands/audit.md** — a starter slash command for security audits (full template in Phase 3 above).

**Commit all four to your repo.** New team members clone, run `claude`, get the same configured experience. The 'one shared brain' across the team.

Claude Code and Cursor/Copilot are complements, not competitors. Each excels at different shapes of work.

**Claude Code wins for:** multi-hour autonomous tasks (write a script that runs Claude Code on a cron), multi-repo work (Cursor is one-window-one-repo; Claude Code can hop between repos in one session), terminal-native workflows (SSH'd into a server, no GUI available), CI/CD integration (Claude Code is invokable from GitHub Actions), tasks that benefit from agentic loops (run tests, see what fails, fix, run again — Claude Code handles this loop natively).

**Cursor/Copilot wins for:** ambient autocomplete (Claude Code doesn't do tab-completion in your editor), short-task IDE work (faster to invoke `cmd+K` in Cursor than to context-switch to a terminal), visual diff review (IDE diff UIs are nicer than terminal diff for big changes), MCP-server-light workflows (Cursor's MCP integration is good; for less-common MCPs, Claude Code's CLI surface is more flexible).

**Common pairing: Cursor for IDE work + Claude Code for terminal/agent work.** The two tools share project context via AGENTS.md (both read it), so conventions stay consistent. Total cost ~$120/mo (Cursor Pro $20 + Claude Max $100) — comparable to running just Cursor Pro + Copilot Pro+ ($60), with substantially more agent capability for the price delta.

**Don't try to make Claude Code do Cursor's job (or vice versa).** Tab-completion in your terminal is awkward; Cursor handles it natively. Running a long autonomous refactor in Cursor's Composer ties up your IDE; Claude Code in a terminal frees the IDE for other work.