Claude Code 完全入門ガイド — AIコーディングエージェントの全機能を体系的に理解する

はじめに — Claude Code とは何か

2025年2月、Anthropic が公開した Claude Code は、AI コーディングツールの概念を根本から刷新した。単にコードを補完・提案するだけでなく、ファイルの読み書き・コマンド実行・git 操作・PR 作成まで、開発タスクを自律的にこなすエージェント型ツールだ。

単なるコード補完との違い

これまでの AI コーディングツールの主流は「コード補完」だった。カーソル位置の次のコードを予測し、開発者がそれを採用するかどうか判断する。優れた補完ツールだが、あくまで「提案」にとどまる。

Claude Code はこのモデルを超える。開発者が「この認証システムにテストを書いて、実行して、失敗があれば修正して」と指示すると、Claude Code はファイルを読み込み、テストを生成し、実行し、エラーを解析し、コードを修正し、再度テストを走らせる——このサイクルを自律的に完結させる。

# テスト自動生成と修正を一気に
claude "write tests for the auth module, run them, and fix any failures"

# ログの異常をリアルタイム監視
tail -200 app.log | claude -p "Slack me if you see any anomalies"

# セキュリティレビュー
git diff main --name-only | claude -p "review these changed files for security issues"

動作環境

Claude Code はさまざまな環境で使える。

多くの場合、開発者はターミナルから claude コマンドで利用する。プロジェクトのルートディレクトリで起動すれば、コードベース全体にアクセスできる状態でセッションが始まる。

機能追加の歩み

Claude Code は2025年2月のリリース以降、急速に機能が拡張されてきた。

2026年3月現在、Claude Code は「AI コーディング OS」とも呼べるプラットフォームに成長している。本記事では、これらの機能を体系的に解説する。

インストールと初期設定

インストール方法

macOS / Linux / WSL（推奨）

curl -fsSL https://claude.ai/install.sh | bash

この方法ではネイティブインストールされ、バックグラウンドで自動更新が行われる。

Windows PowerShell

irm https://claude.ai/install.ps1 | iex

Windows 環境では Git for Windows が必要になる。

Homebrew（macOS）

brew install --cask claude-code

Homebrew でインストールした場合は自動更新されないため、定期的に brew upgrade claude-code を実行する必要がある。

初回起動と認証

インストール後は、プロジェクトのディレクトリに移動して claude コマンドを実行する。

cd your-project
claude

初回起動時にはログイン認証が求められる。認証が完了するとインタラクティブなチャット画面が表示され、プロジェクトに対して指示を出せる状態になる。

基本コマンド一覧

日常的に使うコマンドを覚えておこう。

CLAUDE.md — プロジェクトの「記憶」を設計する

CLAUDE.md とは

Claude Code がセッション開始時に必ず読み込む Markdown ファイルが CLAUDE.md だ。プロジェクトのコーディング規約・ワークフロー・アーキテクチャの意思決定などを記述しておくことで、毎回同じ説明をしなくて済む「永続的なコンテキスト」として機能する。

新しいプロジェクトに加わったばかりのエンジニアに、チームのルールを事前にまとめた文書を渡すようなものだ。Claude Code はこの文書を読んだ上で作業を始める。

3階層の配置場所

CLAUDE.md は3つのスコープで管理できる。

複数の CLAUDE.md が存在する場合、より具体的なスコープが優先される。チーム全体で共有したいルールはプロジェクト直下の CLAUDE.md に書き、自分だけの作業スタイル（好みのエディタ設定、個人的なコーディング癖）はユーザーホームの CLAUDE.md に書く、という使い分けができる。

何を書くべきか・何を書かないか

効果的な CLAUDE.md を書くためのガイドライン。

実際の記述例を見てみよう。

# プロジェクト CLAUDE.md 例

## コードスタイル
- ES modules（import/export）を使用。CommonJS（require）は禁止
- インポートは可能な限り分割代入を使う

## ワークフロー
- コード変更後は必ず型チェックを実行すること: `npx tsc --noEmit`
- テストはスイート全体ではなく単体ファイルを対象に実行する

## コマンド
- ビルド: `npm run build`
- テスト: `npm test`
- Lint: `npm run lint`

## 注意点
- .env.local にシークレットを書く。絶対にコミットしない
- PR のベースブランチは develop（main への直接 push は禁止）

/init による自動生成

既存プロジェクトには /init コマンドが便利だ。Claude Code がコードベースを解析し、ビルドコマンド・テスト手順・プロジェクト規約を自動検出して CLAUDE.md の初稿を生成する。生成された内容を見直して不要な部分を削り、不足している部分を補えばよい。

.claude/rules/ でルールを分割管理する方法

プロジェクトが大きくなると CLAUDE.md が長くなりすぎることがある。そんな時は .claude/rules/ ディレクトリにトピック別のファイルとして分割できる。

.claude/
  CLAUDE.md          # メイン指示（全体方針、コマンド一覧）
  rules/
    code-style.md    # コードスタイル詳細
    testing.md       # テスト規約
    security.md      # セキュリティ要件
    branching.md     # ブランチ戦略

さらに、特定のファイルパターンにのみ適用されるルールも定義できる。

---
paths:
  - "src/api/**/*.ts"
---
# API 開発ルール
- すべてのエンドポイントに入力バリデーションを含める
- エラーレスポンスは RFC 7807 形式に統一する

このファイルは src/api/ 以下の TypeScript ファイルを操作する時だけ読み込まれる。

Auto Memory（自動学習機能）

v2.1.59 以降では Auto Memory 機能が追加された。Claude Code が作業を通じて学んだこと——デバッグで発見した落とし穴、設計上の意思決定、よく使うビルドコマンド——を自動的にメモリファイルに保存する。

保存先は ~/.claude/projects/<project>/memory/MEMORY.md。/memory コマンドで内容を確認・編集できる。これにより、次のセッションでも「前回学んだこと」を引き継いで作業を再開できる。

Skills — 再利用可能なワークフローをパッケージ化する

Skills の概念

Skills（スキル）は、繰り返し使うワークフローや知識を SKILL.md ファイルにパッケージ化したものだ。スラッシュコマンド（/skill-name）で呼び出すか、Claude が自動的に関連スキルを判断して読み込む。

たとえば「GitHub Issue を修正する」という手順——Issue の詳細確認、コード修正、テスト実行、PR 作成——をスキルとして定義しておけば、/fix-issue 123 と入力するだけで一連の手順が実行される。

CLAUDE.md がセッション全体に適用される「常時有効な指示」なのに対し、Skills は「必要な時だけ呼び出すワークフロー」だ。

SKILL.md の構造

スキルは YAML フロントマターと本文で構成される。

---
name: fix-issue
description: >
  GitHub issue を修正する。issue 番号が指定された時に使用する。
disable-model-invocation: true
user-invocable: true
allowed-tools: Read, Grep, Bash, Write, Edit
---

GitHub issue $ARGUMENTS を修正する。

1. `gh issue view $ARGUMENTS` で詳細を取得し、問題を理解する
2. 関連するファイルを特定して修正を実装する
3. テストを書いて実行し、パスを確認する
4. 説明的なコミットメッセージでコミットして PR を作成する

$ARGUMENTS は呼び出し時に渡した引数に置換される。/fix-issue 123 と実行すると $ARGUMENTS が 123 になる。複数引数は $ARGUMENTS[0]、$ARGUMENTS[1]（または $0、$1）で取得可能。

フロントマターの主要フィールド

Reference スキル vs Task スキル

スキルには大きく2種類の使い方がある。

Reference スキル: 仕様書・ドキュメントをオンデマンドで Claude に注入する。CLAUDE.md を肥大化させずに、必要な時だけ関連仕様を読み込む。

---
name: api-spec
description: >
  REST API 仕様を参照する。API エンドポイントに関連する実装を
  行う時に自動的に使用する。
user-invocable: false
---

# REST API 仕様書（抜粋）

## エンドポイント設計原則
- リソース名は複数形（/users、/posts）
- エラーレスポンスは RFC 7807 形式
...

Task スキル: 具体的な操作手順をパッケージ化する。コードレビュー、デプロイ、Issue 対応などが典型例。

呼び出し制御の仕組み

スキルをいつ・誰が起動できるかをフロントマターで細かく制御できる。

デプロイや本番環境への操作など、意図せず実行されると困るスキルには disable-model-invocation: true を設定しておこう。

ビルトインスキル

Claude Code には最初からいくつかのスキルが組み込まれている。

CLAUDE.md vs Skills の使い分け

Subagents — タスクを専門家に委譲する

Subagents の概念

Subagents（サブエージェント）は、Claude Code が専門タスクを委譲できる独立した AI アシスタントだ。それぞれが独自のコンテキストウィンドウ・システムプロンプト・ツールアクセス権限を持つ。

「大量のファイルを読んで調査する」「書き込みは禁止して読み取りだけ許可する」「軽量モデルに回してコストを削減する」といった用途に力を発揮する。

4つのメリット

1. コンテキスト保護

サブエージェントが 100 個のファイルを読んで探索しても、メイン会話に戻るのは「要約だけ」だ。探索の詳細はサブエージェントのコンテキスト内で完結し、メイン会話を汚染しない。

2. ツール制限

サブエージェントに許可するツールを限定できる。読み取り専用のエージェント（Read, Grep, Glob のみ）を使えば、調査フェーズで誤ってファイルを書き換えるリスクがなくなる。

3. 専門特化

ドメイン固有のシステムプロンプトを持ったエージェントを定義できる。「セキュリティレビュー専門」「パフォーマンス最適化専門」など、特定領域に深い知識を持つエージェントを作れる。

4. コスト削減

重い処理を軽量モデルに回せる。コードベース探索のような反復作業は Haiku に委譲し、重要な判断だけ Sonnet/Opus で処理するという使い分けが可能だ。

ビルトインサブエージェント

Claude Code には3つのビルトインエージェントが含まれる。

カスタムサブエージェントの定義方法

YAML フロントマター付きの Markdown ファイルで定義する。

---
name: code-reviewer
description: コードレビュー専門エージェント。コード変更後に積極的に使用する
tools: Read, Grep, Glob, Bash
model: sonnet
---

あなたはシニアコードレビュアーです。以下を確認してください：
- コードの可読性・命名・重複
- エラーハンドリング
- セキュリティ（シークレット漏洩・入力検証）
- テストカバレッジ
- パフォーマンス

フィードバックは優先度別（Critical/Warning/Suggestion）に整理し、
具体的な修正例を示してください。

配置場所はプロジェクト直下の .claude/agents/ ディレクトリ。ユーザーホームの ~/.claude/agents/ に置けば全プロジェクトで使える。

フロントマターの主要フィールド

呼び出し方

サブエージェントの起動方法は3通りある。

# 自然言語（Claude が判断して委譲）
"code-reviewer エージェントを使って最近の変更をレビューして"

# @メンション（確実に指定エージェントを起動）
@"code-reviewer (agent)" auth の変更をレビューして

# セッション全体をエージェントモードで起動
claude --agent code-reviewer

Agent Teams — 複数エージェントの協調作業

Subagents との違い

2026年2月にリリースされた Agent Teams は、サブエージェントをさらに発展させた機能だ。

サブエージェントは「メイン Claude から委譲され、結果を返す」一方向のモデルだった。Agent Teams では複数のエージェントが互いに通信しながら、並列で大規模な作業を分担する。

4つのコンポーネント

Agent Teams は以下のコンポーネントで構成される。

Lead（リード）: チーム全体を統括し、タスクを分解して Teammates に割り当てる。進捗管理と品質検証を担当。

Teammates（チームメート）: Lead の指示を受けて実装する専門エージェント。それぞれが独自のシステムプロンプト（専門知識）を持つ。

Task List（タスクリスト）: チームが処理するタスクの一覧と依存関係（DAG）を管理する。並列実行可能なタスクを自動で特定する。

Mailbox（メールボックス）: エージェント間の非同期メッセージング。結果の報告や質問のやり取りに使う。

いつ Teams を使うべきか

タスクが複雑か？
  ↓ No → 通常の Claude Code で対応
  ↓ Yes
コンテキストウィンドウ内に収まるか？
  ↓ Yes → Subagents で対応
  ↓ No
並列実行可能な独立したサブタスクがあるか？
  ↓ No → 順次実行（単一エージェントで）
  ↓ Yes → Agent Teams を使う

大規模なリファクタリング（複数モジュールを同時に変更）、マルチステップのデータパイプライン構築、クロスリポジトリの整合性確認などが Agent Teams の典型的なユースケースだ。

Hooks — 100%実行される自動化

Hooks の概念

Hooks（フック）は Claude Code のライフサイクル上の特定タイミングで自動実行されるスクリプトだ。

CLAUDE.md の指示は Claude が理解し、遵守しようとするものだが、完全ではない（約80%の遵守率）。「Lint を実行してから変更を終了すること」と書いても、Claude がたまにスキップしてしまうことがある。

一方 Hooks は100%確実に実行される。ファイルを編集した後に必ず Lint を実行したい、危険なコマンドを絶対にブロックしたい——そういった「例外なく実行すべき自動化」に使う。

イベント種別

設定方法

.claude/settings.json に記述する。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint --fix"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "./.claude/hooks/check-dangerous-command.sh"
          }
        ]
      }
    ]
  }
}

この設定では「Edit または Write ツールが使われた後（PostToolUse）に必ず npm run lint --fix を実行」「Bash ツールが使われる前（PreToolUse）に危険コマンドのチェックスクリプトを実行」という動作を定義している。

実践例: ファイル編集後に自動 Lint

危険なコマンドをブロックするスクリプトの例も見てみよう。

#!/bin/bash
# .claude/hooks/block-dangerous.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  echo "危険なコマンドをブロックしました: $COMMAND" >&2
  exit 2  # exit 2 でブロック
fi

exit 0  # 許可

Hook スクリプトの Exit Code には意味がある。

Hook のタイプ

スクリプトだけでなく、複数の実行方式をサポートしている。

設定ファイルの場所

MCP サーバー統合 — 外部サービスとつなぐ

MCP とは

Model Context Protocol（MCP） は Anthropic が2024年11月に公開したオープン標準だ。外部データソースやツールを AI エージェントに接続するためのプロトコルで、Claude Code はこれを使ってさまざまな外部サービスと連携できる。

2026年2月には Apple（Xcode）・OpenAI（ChatGPT）も MCP 対応を発表しており、業界標準として普及が進んでいる。

接続できるサービス例

• 開発ツール: GitHub / GitLab（Issue・PR 管理）、Jira（チケット管理）
• コミュニケーション: Slack（メッセージ送受信）
• ドキュメント: Google Drive、Notion
• データベース: PostgreSQL、SQLite
• デザイン: Figma
• クラウド: AWS / GCP / Azure（リソース管理）

設定方法

対話形式で MCP サーバーを追加できる。

claude mcp add

.mcp.json に直接記述することもできる。

{
  "playwright": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@playwright/mcp@latest"]
  },
  "github": {
    "type": "stdio",
    "command": "uvx",
    "args": ["mcp-server-github"],
    "env": {
      "GITHUB_TOKEN": "${GITHUB_TOKEN}"
    }
  }
}

サブエージェントへの MCP スコープ

MCP サーバーを特定のサブエージェントだけに公開できる。

---
name: browser-tester
description: Playwright を使ったブラウザテスト
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  - github
---

メイン会話には GitHub MCP ツールを見せずにサブエージェントだけに提供する、といった制御が可能だ。コンテキストの節約にもなる。

おすすめ MCP サーバー

2026年3月時点で、実用性が高く導入しやすい MCP サーバーを厳選して紹介する。

開発・コード管理

ドキュメント・ナレッジ

データベース・インフラ

コミュニケーション・外部連携

特に最初に入れるべき3つ

Claude Code を始めたばかりなら、まずこの3つを設定するのがおすすめだ。

1. GitHub MCP — PR 作成・Issue 管理が会話の中で完結する。開発ワークフローの中核
2. Context7 — 「Astro 5 の最新 API を使って」と指示するだけで最新ドキュメントを参照してくれる
3. Playwright — UI 変更後に「スクリーンショットを撮って確認して」が可能に

# GitHub MCP の追加例
claude mcp add github -- uvx mcp-server-github

# Context7 の追加例
claude mcp add context7 -- npx -y @upstash/context7-mcp@latest

コンテキスト管理 — パフォーマンスの鍵

なぜコンテキスト管理が重要か

Claude Code のパフォーマンスに最も影響する要因はコンテキストウィンドウの使用量だ。

Claude のコンテキストウィンドウは最大200,000トークン（約150,000語）。セッションが長くなるほどコンテキストが積み上がり、満杯に近づくと過去の指示を「忘れ」てミスが増える。優れたプロジェクト設定よりも、コンテキストの賢い管理の方が実際のパフォーマンスに直結する。

/clear, /compact, /btw の使い分け

コンテキストが95%に達すると自動的にコンパクションが発生する。閾値は環境変数 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50 で変更できる。

Plan モード — 探索と実装の分離

Plan モードは「実装の前にしっかり考える」ためのモードだ。Plan モード中は Claude がファイルを読んで質問に答えるが、ファイルの変更は一切行わない（読み取り専用）。

切り替えは Shift+Tab を2回押すか、settings.json でデフォルト設定できる。

{
  "permissions": {
    "defaultMode": "plan"
  }
}

推奨のワークフローは4フェーズだ。

フェーズ1: 探索（Plan モード）

/src/auth を読んで、セッション管理とログイン処理を理解して

フェーズ2: 計画（Plan モード）

Google OAuth を追加したい。変更が必要なファイルは？
セッションフローはどうなる？実装計画を作成して

計画が表示されたら Ctrl+G でエディタで開いて直接編集もできる。

フェーズ3: 実装（Normal モード）

計画通りに OAuth フローを実装して。
コールバックハンドラーのテストを書いて、テストスイートを実行して失敗を修正して

フェーズ4: コミット（Normal モード）

説明的なメッセージでコミットして PR を作成して

Plan モードは出力トークンも削減できる（探索だけで実装を伴わないため）。コスト面でも有利だ。

よくある失敗パターンと対策

コンテキスト効率化のベストプラクティス

• CLAUDE.md は200行以内を目標にする
• 詳細な仕様・ドキュメントは Skills に分離してオンデマンドロード
• MCP ツールは必要なサブエージェントにのみスコープする
• 30分スプリント戦略: 30分単位で作業を区切り、スプリント間で /compact を実行する。この方法で長時間セッションでも高いパフォーマンスを維持できる
• サブエージェントを活用して大量の探索をメイン会話から分離する

まとめ — 機能比較表と次のステップ

全機能の比較表

機能の使い分けガイド

どこから始めるか

1. まず CLAUDE.md を整備する。プロジェクトのルール・コマンド・注意点を記述するだけで体験が大きく変わる
2. 繰り返す手順があれば Skills にパッケージ化する
3. 「毎回必ずやること」は Hooks で自動化する
4. 大量のファイル探索や専門知識が必要な場合は Subagents を活用する
5. 外部サービスとの連携が必要になったら MCP を設定する
6. 大規模な並列タスクが必要になったら Agent Teams を検討する

次のステップ

Claude Code は単なるコーディングツールを超え、開発ワークフロー全体を変える可能性を持つプラットフォームだ。まずは自分のプロジェクトで /init を実行して CLAUDE.md を生成することから始めてみよう。

使い込むほど、プロジェクトに最適化されたコーディングエージェントとして成長していく。そのポテンシャルを引き出すのは、適切な設定とコンテキスト管理の習慣だ。