Claude Code：インストールから本番ワークフローまでの完全ハンドブック

ネット上の Claude Code 解説は断片的です——npm install だけの記事、diff スクリーンショットだけの投稿、MCP と権限をごちゃ混ぜにした説明。本番投入の段階で足りないのは「もう一つのショートカット」ではなく、CLI インストールから CI グリーンまでの一本道です。

本稿は Cloud Mac AI Stack · L6 支柱ハンドブック（L6-Q01）：Claude Code をエンドツーエンドのコーディング Agentとして、インストール、初日の試運用、日常の委任、MCP 接続から GitHub Runner 連携の本番ワークフローまでを一本で通します。判断基準と権限の閾値は L3 決断入門、MCP の段階的セットアップは MCP チュートリアル——本稿はメインラインの接続に専念します。

本稿の知識骨格

以下は Claude Code 公式機能の全集ではなく、本稿 L6-Q01 ハンドブックのメインライン・ツリーです——各枝は本文の一節に対応し、括弧内がアンカー。各節見出し下の知識骨格ラベルは下表と一対一です。ツリーに含めない機能（Hooks、サブエージェント、エンタープライズ管理など）は後続の専題または公式ドキュメントへ。

インストールから本番ワークフロー · 2026年6月版

本稿メインライン（Claude Code 完全ハンドブック）
├── 環境選定（#prereq）
│   ├── macOS / Linux 公式サポート範囲
│   ├── ローカル Mac mini / MacBook vs Cloud Mac
│   └── Node 18+ · ネットワーク · Anthropic アカウント / API Key
├── インストール検証（#install）
│   ├── npm install -g @anthropic-ai/claude-code
│   ├── claude doctor · claude login
│   └── 5 段階検証（リポルート · /help · 401 なし）
├── 初日試運用（#first-day）
│   ├── 小規模委任 + 全テスト通過
│   ├── git diff で変更範囲を確認
│   └── レビュー習慣の確立（越境 → L3 決断へ戻る）
├── プロジェクト境界（#claude-md）
│   ├── CLAUDE.md 最小テンプレ（インストール / テスト / 変更禁止）
│   └── 説明文より実行可能コマンドを優先
├── 日常リズム（#daily）
│   ├── 三段階委任（高 / 協調 / 低）
│   └── 四ステップ循環（委任 → 観察 → レビュー → マージ）
├── 接続層（#mcp）
│   ├── ~/.claude.json · mcpServers
│   ├── GitHub / CodeGraph / Fetch の定番構成
│   └── /mcp 検証（詳細 → MCP インストールチュートリアル）
├── CI 事実チェーン（#ci）
│   ├── Diff（Claude Code）vs Fact（Runner）
│   ├── feature ブランチ → self-hosted Runner → PR グリーン
│   └── secrets と Agent 環境の分離
├── 本番チェックリスト（#production）
│   ├── CLAUDE.md / 権限 / MCP / シークレット / CI / レビュー / コスト
│   └── 試運用 vs 本番 対照表
└── Stack 位置づけ（#stack-map）
    ├── L0–L5 における Cloud Mac AI Stack 上の位置
    └── 外部リンク：L3 決断 · MCP チュートリアル · Runner 実行エンジン

環境準備：Mac か Cloud Mac か？

知識骨格 · #prereq · 環境選定

Claude Code は公式に macOS と Linux をサポートしています。Web / バックエンドだけなら Linux クラウドでも動きますが、xcodebuild、iOS シミュレータ、macOS 専用ツールチェーンが絡むなら macOS 環境が必須です。

• ローカル Mac mini / MacBook — 24GB メモリが安定（Chrome + Docker + Claude Code 並行時、16GB は Swap しがち）。M4/M5 選定を参照
• Cloud Mac — ハードウェア購入前に試したい、またはメイン機と隔離した開発 / CI 環境が欲しい場合。購入 vs レンタルを参照
• 非推奨 — メインのノート PC 上で本番 secrets、隔離なし Agent、CI Runner を同時運用（Runner 隔離を参照）

ソフトウェア前提：Node.js 18+、Anthropic API へ到達可能なネットワーク、Anthropic アカウント（Claude Pro/Max/Team）または API Key。

インストールとログイン（5 段階検証）

知識骨格 · #install · インストール検証

以下のコマンドは macOS ターミナルで実行（Cloud Mac 上でも同様）：

# 1. CLI をグローバルインストール
npm install -g @anthropic-ai/claude-code

# 2. 環境自己診断（Node バージョン、PATH など）
claude doctor

# 3. ログイン（ブラウザ OAuth または API Key）
claude login

初日：最初の委任タスクを完了する

知識骨格 · #first-day · 初日試運用

インストール成功は「使いこなせる」とは限りません。初日にやることは一つだけ：小規模な変更 + 全テスト通過で、Agent の挙動への感覚を掴むこと。

1. リポジトリルートで CLAUDE.md を作成または整備（次節で詳述）
2. claude を起動。委任例：「README に『ローカル開発』セクションを追加。README のみ変更し、他ファイルは触らない」
3. Agent が先にファイルを読み、変更し、指定した検証コマンドを実行するか観察
4. git diff で変更範囲を確認し、越境していないかチェック
5. マージ前に自分でもテストコマンドを再実行（「Agent が通ったと言った」だけで信じない）

初日の目標はスピードではなくレビュー習慣の確立。Agent が頻繁に誤ったディレクトリを変更したり危険なコマンドを実行するなら、いきなり本番リポに進まず 権限決断へ戻ってください。

CLAUDE.md：プロジェクト境界の説明書

知識骨格 · #claude-md · プロジェクト境界

CLAUDE.md は Claude Code 向けの「プロジェクト README」——人間向け README より実行可能コマンドと禁止事項を重視します。本番リポではほぼ必須です。

# プロジェクト：my-saas

## インストール
pnpm install

## テスト（コード変更後は必ず全実行）
pnpm test
pnpm lint

## 変更禁止
- .env、secrets/ は変更しない
- 明示的な指示がない限り major 依存をアップグレードしない
- 課金関連の変更は対応テストも同時に更新すること

## ディレクトリ規約
- src/app — Next.js ページ
- packages/api — バックエンドロジック

CLAUDE.md を整備すると、同じタスクでもファイル誤変更率とテストループ回数が目に見えて下がることが多い——ワークステーション実測では、完全な CLAUDE.md と空テンプレの差は所要時間の約 20% でした。

日常開発ワークフロー

知識骨格 · #daily · 日常リズム

試運用が通ったら日常リズムへ。タスクを三段階に分け、「すべて Agent に丸投げ」しないのがコツです：

日常ループは四ステップに固定するのがおすすめ：

1. 委任 — 範囲、受け入れ基準、触ってはいけないディレクトリを明確に
2. 観察 — Agent がどのファイルを読み、どの shell を実行したか確認
3. レビュー — git diff + 自分でテスト実行（CLAUDE.md と一致）
4. マージ — PR + code review；main 上で Agent に連続コミットさせない

Cursor との役割分担：Cursor はエディタ内の補完と小規模書き換え向き；Claude Code は複数ファイル + shell + テストループの Agent タスク向き。併用は可能ですが、一つのツールですべてをカバーするのは現実的ではありません。

MCP 接続（接続層）

知識骨格 · #mcp · 接続層

Agent が GitHub Issue を読んだり、コードグラフを引いたり、API ドキュメントを取得する必要があるとき、リポ内 grep だけでは足りません——そのとき MCP（Model Context Protocol） を接続し、Claude Code に「標準 USB ポート」を付けます。

• 設定入口 — ~/.claude.json の mcpServers セクション
• 定番構成 — GitHub MCP（Issue/PR）、CodeGraph MCP（影響範囲分析）、Fetch MCP（ドキュメント）
• 検証 — Claude Code で /mcp を入力し、mcp__github__* などのツールが表示されること

段階的インストールとトラブルシュートは MCP インストールチュートリアル（15 分）、権限モデルは MCP 最小権限。MCP は本番ワークフローの重要コンポーネントですが、初日に全部揃える必要はありません——まず MCP なしの基本フローを通し、その後 GitHub MCP を追加するのがおすすめです。

CI 連携：Claude Code + Runner

知識骨格 · #ci · CI 事実チェーン

ローカルで Agent がコードを直しテストが通っても、それだけでは「本番級」ではありません——開発機と隔離された CI 事実チェーンが必要です。Stack における役割分担の口诀：

Claude Code が Diff を、GitHub Runner が Fact を生む。

推奨ワークフロー：

1. 開発者が Cloud Mac / ローカル Mac で Claude Code を使い変更を完了し、feature ブランチへ push
2. Self-hosted Runner（Agent 環境と隔離）が xcodebuild test / pnpm test などを実行
3. PR は CI グリーン + 人手 review の両方を満たしてからマージ
4. 本番 secrets は Runner またはシークレット管理サービスのみに存在し、Agent の日常 shell 環境には入れない

Runner 登録と隔離設定：実行エンジン · キューと TCO · 1 job 1 workspace。

ローカルで Ollama + Claude Code + Runner を同時運用する場合はメモリの段取りに注意し、Swap で CI が遅くならないように——並行スケジューリングを参照。

本番チェックリスト（投入前必須）

知識骨格 · #production · 本番チェックリスト

「動く」から「本番投入できる」へ——この表を一通り確認：

Stack 全体マップ

知識骨格 · #stack-map · Stack 位置づけ

本稿を Cloud Mac AI Stack に置くと、あなたの位置は次のとおり：

• L0 基盤 — なぜ Cloud Mac を使うか
• L1 実行 — GitHub Runner（Fact 層）
• L2 推論 — Ollama プライベート推論（任意、ローカル embedding / 小モデル）
• L3 コーディング — 本稿 · Claude Code 完全ハンドブック（Diff 層メインライン）
• L4 接続 — MCP トリプル接続
• L5 自動化 — OpenHands Agent プラットフォーム

Stack の全体アーキテクチャ図 + 五モジュール接続順序は支柱マップ L6-Q02 · Claude Code コアアーキテクチャと Stack 総図——本稿はその「コーディング Agent」セグメントの実装ハンドブックです。

よくある質問

知識骨格 · #faq · 補足 Q&A

Claude Code を使うには Mac が必須ですか？ 公式は macOS と Linux をサポート。iOS / macOS ビルドには Mac が必要で、ローカルまたは Cloud Mac で対応できます。

サブスクと API Key はどちらを選ぶ？ 個人の試運用なら Pro/Max サブスクが手軽；チームや CI 連携では API Key + 用量管理が一般的。コスト比較は モデル課金を参照。

本番級で MCP は必須ですか？ 小さなリポならなくても可；GitHub Issue の参照やクロスサービスドキュメント検索が必要になれば、MCP はほぼ標準装備です。

Agent が壊してしまったら？ git checkout -- . または git stash；小さくコミットし頻繁にブランチを切る習慣を。汚れた作業ツリーに複数の委任を重ねないこと。

• L3 決断：いつ Agent を正式導入するか
• Claude Code MCP インストールチュートリアル
• Mac mini ワークステーション実測
• GitHub Runner 実行エンジン