Claude Code: Complete Handbook from Install to Production Workflow

Fragmented tutorials for Claude Code are everywhere: some cover only npm install, some show a single diff screenshot, some mash MCP and permissions into one post. When you actually need to ship, you are not missing "another keyboard shortcut" — you are missing a complete path from CLI install to green CI.

This is the Cloud Mac AI Stack · L6 pillar handbook (L6-Q01): treating Claude Code as an end-to-end coding Agent from install, first-day trial, daily delegation, and MCP wiring through a production workflow tied to GitHub Runner. Decision and permission gates live in the L3 decision opener; step-by-step MCP install is in the MCP guide — this article threads the main spine only.

How this guide is organized

This is not the full official Claude Code capability map — it is the L6-Q01 handbook spine. Each branch maps to a section below; anchor ids are in parentheses. Section headings carry skeleton refs that match this tree. Capabilities not drawn here (Hooks, sub-agents, enterprise hosting, etc.) belong in follow-on articles or official docs.

Install to production workflow · June 2026 Edition

Article spine (Claude Code complete handbook)
├── Environment (#prereq)
│   ├── macOS / Linux official support boundaries
│   ├── Local Mac mini / MacBook vs Cloud Mac
│   └── Node 18+ · network · Anthropic account / API Key
├── Install verification (#install)
│   ├── npm install -g @anthropic-ai/claude-code
│   ├── claude doctor · claude login
│   └── 5-step acceptance (repo root · /help · no 401)
├── First-day trial (#first-day)
│   ├── Small-scope delegation + all-green tests
│   ├── git diff to audit change scope
│   └── Build review habits (out of bounds → back to L3 decision)
├── Project boundaries (#claude-md)
│   ├── CLAUDE.md minimal template (install / test / do-not-touch)
│   └── Executable commands over prose
├── Daily rhythm (#daily)
│   ├── Three delegation tiers (high / collaborative / low)
│   └── Four-step loop (delegate → observe → review → merge)
├── Connection layer (#mcp)
│   ├── ~/.claude.json · mcpServers
│   ├── GitHub / CodeGraph / Fetch common combos
│   └── /mcp acceptance (details → MCP install guide)
├── CI Fact chain (#ci)
│   ├── Diff (Claude Code) vs Fact (Runner)
│   ├── feature branch → self-hosted Runner → green PR
│   └── secrets isolated from Agent environment
├── Production checklist (#production)
│   ├── CLAUDE.md / permissions / MCP / secrets / CI / review / cost
│   └── Trial vs production comparison table
└── Stack placement (#stack-map)
    ├── L0–L5 position in Cloud Mac AI Stack
    └── Links: L3 decision · MCP guide · Runner execution engine

Environment: Mac or Cloud Mac?

Skeleton · #prereq · Environment

Claude Code officially supports macOS and Linux. Pure Web/backend work can run on a Linux VPS; anything involving xcodebuild, the iOS Simulator, or macOS-only toolchains needs a macOS environment.

• Local Mac mini / MacBook — 24GB RAM is steadier (16GB often swaps under Chrome + Docker + Claude Code); see M4/M5 sizing
• Cloud Mac — when you do not want to buy hardware first, or need dev/CI isolated from your daily machine; see buy vs rent
• Not recommended — running production secrets, an unisolated Agent, and CI Runner on the same daily laptop (see Runner isolation)

Software prerequisites: Node.js 18+, network access to Anthropic, and an Anthropic account (Claude Pro/Max/Team) or API Key.

Install and login (5-step acceptance)

Skeleton · #install · Install verification

Run these commands in the macOS Terminal (same on Cloud Mac):

# 1. Global CLI install
npm install -g @anthropic-ai/claude-code

# 2. Environment self-check (Node version, PATH, etc.)
claude doctor

# 3. Login (browser OAuth or API Key)
claude login

First day: run your first delegation

Skeleton · #first-day · First-day trial

Install success is not "knowing how to use it." On day one, do one thing: small-scope change + all-green tests — build intuition for Agent behavior.

1. Create or refine CLAUDE.md at the repo root (next section)
2. Start claude; sample delegation: "Add a 'Local development' section to README — only touch README, no other files"
3. Watch whether the Agent reads files first, edits, then runs your verification commands
4. Review scope with git diff — confirm nothing out of bounds
5. Before merge, run test commands yourself (do not trust "Agent said tests passed")

Day-one goal is not speed — it is building review habits. If the Agent keeps editing wrong directories or running risky commands, go back to permission decision before touching production repos.

CLAUDE.md: project boundary spec

Skeleton · #claude-md · Project boundaries

CLAUDE.md is Claude Code's "project README for the Agent" — more about executable commands and forbidden actions than a human-facing README. Production repos almost always need one.

# Project: my-saas

## Setup
pnpm install

## Tests (run all after code changes)
pnpm test
pnpm lint

## Do not modify
- Do not edit .env or secrets/
- Do not upgrade major dependencies unless explicitly requested
- Billing-related changes must include corresponding test updates

## Directory conventions
- src/app — Next.js pages
- packages/api — backend logic

After a solid CLAUDE.md, wrong-file edits and test-loop rounds usually drop noticeably — in our workstation benchmark, a complete CLAUDE.md vs a blank template differed by roughly 20% elapsed time.

Daily development workflow

Skeleton · #daily · Daily rhythm

Once trial passes, settle into a daily rhythm. Split work into three tiers instead of "throw everything at the Agent":

Fix the daily loop to four steps:

1. Delegate — state scope, acceptance criteria, and directories off limits
2. Observe — which files the Agent read, which shell commands it ran
3. Review — git diff + run tests yourself (match CLAUDE.md)
4. Merge — PR + code review; do not let the Agent commit straight to main

Split with Cursor: Cursor fits in-editor completion and small edits; Claude Code fits multi-file + shell + test-loop Agent work. Both can coexist — neither covers every scenario.

Wire MCP (connection layer)

Skeleton · #mcp · Connection layer

When the Agent must read GitHub Issues, query a code graph, or pull API docs, repo grep alone is not enough — wire MCP (Model Context Protocol), effectively a standard plug-in bus for Claude Code.

• Config entry — mcpServers block in ~/.claude.json
• Common combos — GitHub MCP (Issues/PRs), CodeGraph MCP (impact analysis), Fetch MCP (documentation)
• Acceptance — in Claude Code, type /mcp; you should see mcp__github__* and similar tools

Step-by-step install and troubleshooting: MCP install guide (15 min); permission model: MCP least privilege. MCP is a necessary piece of production workflow, but not day-one mandatory — run the base flow without MCP first, then add GitHub MCP.

Hook up CI: Claude Code + Runner

Skeleton · #ci · CI Fact chain

Local Agent edits and green tests are not "production-grade" until you have a CI Fact chain isolated from the dev machine. Stack shorthand:

Claude Code produces Diff; GitHub Runner produces Fact.

Recommended workflow:

1. Developer finishes changes with Claude Code on Cloud Mac / local Mac, pushes to a feature branch
2. Self-hosted Runner (isolated from Agent environment) runs xcodebuild test / pnpm test, etc.
3. PR requires green CI + human review before merge
4. Production secrets live only on Runner or in a secrets manager — not in the Agent's daily shell

Runner registration and isolation: execution engine · queue and TCO · one job one workspace.

If Ollama + Claude Code + Runner share one machine, schedule memory so CI does not swap — see parallel scheduling.

Production checklist (pre-go-live)

Skeleton · #production · Production checklist

From "it runs" to "it ships" — walk this table:

Full Stack map

Skeleton · #stack-map · Stack placement

Placing this article in the Cloud Mac AI Stack:

• L0 Foundation — why Cloud Mac
• L1 Execution — GitHub Runner (Fact layer)
• L2 Inference — Ollama private inference (optional — local embedding/small models)
• L3 Coding — this article · Claude Code complete handbook (Diff layer spine)
• L4 Connection — MCP triple-connect
• L5 Automation — OpenHands Agent platform

Stack full architecture diagram + five-module onboarding order lives in the pillar map L6-Q02 · Claude Code core architecture & Stack map — this handbook is the "coding Agent" segment.

FAQ

Skeleton · #faq · Supplemental Q&A

Do I need to buy a Mac to use Claude Code? Official support covers macOS and Linux. iOS/macOS builds require Mac — local or Cloud Mac.

Subscription vs API Key? Pro/Max subscription is easiest for personal trial; teams and CI integration often use API Key + usage controls. Cost comparison: model pricing.

Is MCP mandatory for production? Small repos can skip it; once you need GitHub Issues or cross-service docs, MCP is nearly standard.

Agent broke something? git checkout -- . or git stash; commit in small steps on branches — do not stack delegations on a dirty working tree.

• L3 decision: when to formally onboard the Agent
• Claude Code MCP install guide
• Mac mini workstation benchmark
• GitHub Runner execution engine