Foundations

The single biggest gap in 2026 isn't prompt quality — it's thinking about Claude Code as a chatbot instead of as infrastructure. A chatbot is a thing you type at. A piece of infrastructure is a thing you configure, shape, and build guardrails around. Claude Code is the latter.

Treat it like software you're setting up for your team. The outputs you get out are bounded by the context you put in — the CLAUDE.md, the .gitignore rules Claude respects, the permissions.deny list, the hooks you wire into file-write events, the skills and subagents you've defined, the MCP servers you've connected. None of those exist by default. Setting them up is the job.

Context architecture > prompt cleverness

People obsess over prompt phrasing when the real leverage is further upstream:

• Is Claude reading a 400-line CLAUDE.md on every turn when only 50 lines are load-bearing? That's wasted context.
• Is it loading node_modules tree output because your .gitignore doesn't cover it (or because you explicitly pointed at the path)? That's wasted context.
• Is it re-reading package.json on every message because there's no tool memory between calls? That's wasted context.

Fix those three and the prompts you were worried about start working.

Claude Code is two things fused together: a harness that runs on your machine, and the Claude model that runs in Anthropic's data centers. Everything you think of as "intelligence" lives in the model. Everything you think of as "capability" — reading files, running shells, editing code, executing hooks — lives in the harness.

When you type a message, the harness packages up a request: your message, the conversation history, the system prompt, the CLAUDE.md, the list of available tools, and ships it to the model. The model replies with either text for you or a tool call. If it's a tool call, the harness executes it locally, captures the result, and sends that back to the model for the next turn. This loop continues until the model produces a final answer. That loop is the agentic loop, and it's where most of the interesting behavior comes from.

Tools: read-only vs write

The harness exposes tools in two flavors. Read-only tools (Read, Glob, Grep, WebFetch) never modify your system — they just return information. Write tools (Edit, Write, Bash) change state. In Plan Mode (covered in Workflows), only read-only tools are available, which is why it's safe to let Claude explore without supervision.

Claude's context window is 200K tokens. Sounds huge. It fills faster than you'd think, and it's the single most important resource you manage.

The system prompt plus tool definitions take ~30–50K tokens before you've typed anything. Add a 5K CLAUDE.md, a few file reads, a couple of command outputs, and you're at 80K before the real work begins. Once the window crosses ~70–80% full, performance degrades visibly: Claude forgets earlier instructions, ignores CLAUDE.md rules, repeats itself, and makes more mistakes. More mistakes mean more rework, more rework means more tokens burned — a vicious cycle.

Monitor what's actually in there

Two commands tell you where your tokens went:

/cost       # total tokens used this session, in dollars
/context    # breakdown: system prompt, CLAUDE.md, tools, conversation, files

For continuous visibility, configure the StatusLine to show the current token percentage as you work. Most people discover after one week of watching it that half their "Claude is being weird" complaints were really "my context was at 90% full."

Drop this into ~/.claude/settings.json (create it if it doesn't exist):

{
  "statusLine": {
    "type": "command",
    "command": "npx ccusage statusline"
  }
}

ccusage is a community tool that reads your session and prints tokens used, percentage of window, and cost. Any command that prints a single line to stdout works here — you can swap in your own script later.

Claude Code ships in five surfaces. They share the same underlying engine — pick based on where you already live.

Terminal (the primary one)

# macOS / Linux
curl -fsSL https://claude.ai/install.sh | sh

# npm (any platform)
npm install -g @anthropic-ai/claude-code

# First run — will walk you through auth
claude

On first run you'll be prompted to authenticate (browser OAuth or API key depending on your plan). The terminal CLI is the one every other surface is built on — features land here first.

VS Code extension

Install "Claude Code" from the Extensions marketplace. Opens a Claude panel inside VS Code with the same engine and settings as the CLI. The editor surface adds in-file diffs, inline diagnostics, and IDE-native approvals. Your CLAUDE.md, settings, and skills apply identically.

Desktop app

A native Mac/Windows app at claude.ai/download. Same engine, but designed for people who don't live in a terminal. Useful for sharing Claude Code with non-CLI folks on your team.

Web

claude.ai/code runs Claude Code in a cloud sandbox — no local install, spawns VM-isolated environments. Good for one-off tasks, reviewing PRs, and "I'm on a Chromebook" scenarios.

JetBrains

Plugin available for IntelliJ, WebStorm, PyCharm, GoLand, and the rest of the JetBrains family. Install from the Plugin Marketplace.

CLAUDE.md is your project's memory — a markdown file at the repo root that Claude loads into every session as system context. It's the difference between "Claude who learned your codebase the hard way" and "Claude who already knows your conventions."

The WHAT–WHY–HOW framework

Good CLAUDE.md entries answer three questions in order:

• WHAT — the rule. "All API errors are thrown as typed exceptions from errors.ts."
• WHY — the reason. "So callers don't have to check status codes; the router catches and formats at the edge."
• HOW — the concrete application. "Use throw new ApiError(...); don't return error objects from service functions."

Without the WHY, Claude follows the rule rigidly and fails on edge cases. Without the HOW, Claude agrees and does it wrong anyway. The combination gives it enough to judge unfamiliar situations.

What belongs in CLAUDE.md

• The stack (languages, frameworks, major libraries)
• How the repo is laid out (one-line per top-level folder)
• Non-obvious conventions (error handling, state management, tests)
• Hard rules ("never call X directly; always go through Y")
• Where to look for domain docs (referenced, not inlined)
• The commands you'd run: npm run dev, npm test, etc.

What does NOT belong

• Full API references — link to the file instead
• Examples Claude can derive by reading code
• Anything that changes often (current sprint goals, in-progress work)
• Full architecture diagrams in ASCII — one-sentence summaries, then link
• Boilerplate like "please be helpful" — Claude already is

Tiered architecture

When your project is big enough that 5K isn't enough, go tiered. Keep CLAUDE.md small and point to deeper docs that load only when relevant:

# Project: Shipping Platform

Node.js + Fastify + Postgres. Strict TypeScript.

## Conventions

- All errors throw, never return. See `docs/errors.md` when working with error handling.
- Payments logic is sensitive — read `docs/payments-architecture.md` before touching `src/payments/`.
- Tests colocated with code: `foo.ts` and `foo.test.ts`.

## Commands

- `npm run dev` — local server
- `npm test` — unit + integration
- `npm run db:migrate` — apply new migrations

Claude reads the referenced files only when it needs to. A developer working on the frontend never pays the token cost of payment docs.

Claude Code has two official mechanisms for keeping files out of its reach, and knowing which to reach for saves a lot of "why can Claude see my secrets" moments.

.claudeignore is not a real feature. You'll see it referenced in community blog posts, npm packages, and PreToolUse-hook templates — it's a workaround people built, not something Anthropic ships. The authoritative surfaces are .gitignore respect and permissions.deny. Use those instead.

Mechanism 1 — .gitignore respect

Claude Code respects your .gitignore for search-style operations. The effect: Glob, Grep, and directory listings skip anything gitignored. For most projects this covers the noise automatically — node_modules/, dist/, .next/, build artifacts, and log files are already gitignored, and Claude treats them as invisible to exploration tools.

The win here is passive. If your repo has a sane .gitignore, you've already done the single biggest thing to keep Claude's searches clean. The only action item is to glance at your .gitignore once and make sure it covers build outputs and caches for your stack.

node_modules/
vendor/
.venv/
dist/
build/
.next/
.nuxt/
.output/
.cache/
*.log
**/generated/

Mechanism 2 — permissions.deny for sensitive paths

.gitignore cleans up noisy searches. It's the wrong tool for secrets, because an explicit Read(./.env) can still slip through, and because you can't always gitignore what you want to hide — a notes/private/ folder you keep locally, a fixtures/customer-data/ directory you scrub before commit, credentials files you intentionally track.

For anything that should be strictly off-limits, use permissions.deny in .claude/settings.json:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./notes/private/**)",
      "Read(./fixtures/customer-data/**)",
      "Bash(cat .env*)",
      "Bash(cat **/id_rsa*)"
    ]
  }
}

Two things worth noticing:

• Block the shell path too. A clever Claude might try cat .env instead of Read(./.env). Denying the Bash(...) pattern closes that backdoor.
• Paths are project-root relative. ./path/** is the convention — anchored to the project root, glob-expanded from there.

When to use which

For noise you already gitignore, do nothing — .gitignore respect handles it. For secrets, credentials, and PII, use permissions.deny plus a Bash-pattern deny for the shell surface. For large committed files you don't want re-read (generated docs, fixture dumps) — gitignore them if they're truly generated; Read-deny them if they're committed intentionally but don't belong in context.

Claude Code reads configuration from four places. Each overrides the one above it, so the most specific wins.

{
  "model": "sonnet",
  "permissions": {
    "allow": ["Bash(npm test)", "Bash(npm run lint)", "Read"],
    "deny": ["Bash(rm -rf *)", "Bash(git push --force*)"],
    "ask": ["Bash(git push*)"]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "npx prettier --write $CLAUDE_FILE_PATHS" }]
      }
    ]
  }
}

Claude Code supports three model tiers. Knowing when to reach for each is worth 40% on your bill.

Default model depends on your plan. Free users get Haiku. Pro gets Sonnet. Max gets Opus by default. You can always switch mid-session with /model.

Claude Code ships with sandboxing enabled. By default, every tool call that could modify your system (shell commands, file writes) requires approval the first time Claude tries it in a session. This is slow but safe. As you gain confidence, tune the permissions.

The three permission modes

• Ask (default) — Claude pauses and asks before running anything it hasn't run before
• Allowlist — you pre-approve patterns in settings.json; Claude proceeds without asking for those
• Skip all — --dangerously-skip-permissions; Claude never asks. Use only in isolated environments

The allow / deny / ask lists

In .claude/settings.json you can pre-approve or pre-block patterns. A good starting set for most projects:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run lint)",
      "Bash(npm test*)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)"
    ],
    "ask": [
      "Bash(git push*)",
      "Bash(git checkout*)",
      "Write"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)"
    ]
  }
}