はじめに

Claude Codeを「便利なコード生成ツール」として使っていませんか。プロンプトを投げて、出力をコピーして、ファイルに貼り付ける。もしそうだとしたら、Claude Codeが持つ能力の1割も使えていない可能性があります。

CLAUDE.mdでプロジェクトの記憶を設計し、MCPで外部システムと直接連携し、スキルでワークフローを自動化し、フックで品質を自動保証し、サブエージェントで作業を並列化する。これらを組み合わせると、Claude Codeは「ツール」ではなく「開発プロセスそのものを動かす基盤」になります。

この記事では、Claude Codeを「システム構築基盤」として使いこなすための設計思想と具体的な手法を整理します。

「チャットAI」と「エージェント」の使い方は別物

多くの開発者がClaude Codeに初めて触れるとき、ChatGPTやGeminiと同じ「チャットAI」の延長として理解しようとします。質問を投げて、回答を受け取り、コピー＆ペーストする。しかしClaude Codeはそのような使い方を想定していません。

Claude Codeは自律型エージェントです。コードベースを読み、ファイルを書き、ターミナルコマンドを実行し、テストを走らせ、Gitにコミットし、プルリクエストを作成する。人間がコピー＆ペーストする必要はありません。モデルが直接コードベースに対してアクションを実行します。

2026年初頭の時点で、Claude Codeは全世界のGitHubコミットの約4%を生成しており、年末までに20%に達すると予測されています。Anthropicのエンジニアは1日に10〜30のプルリクエストをClaude Codeで生成し、すべてのプルリクエストはClaude Codeによるレビューを経た後に人間がレビューしています。

この数字が示しているのは、Claude Codeが「コードを生成するツール」ではなく「開発ワークフローの基盤」として機能しているということです。ツールと基盤の違いは決定的です。ツールは人間が使うもの。基盤は人間がその上でシステムを構築するものです。

最もレバレッジの高い行為：Claudeに「自己検証」させる

Claude Codeで生産性を最大化するために、最も効果の高いことが1つあります。それは、Claudeに自分の作業を検証する手段を与えることです。

テストを実行させる、スクリーンショットを撮って比較させる、出力を期待値と照合させる。検証手段がないと、Claudeは「正しく見えるが実際には動かない」コードを生成する可能性があります。そしてその検証の負担はすべて人間に返ってきます。

例えば、「メールアドレスを検証する関数を書いて」ではなく、「validateEmail関数を書いて、テストケース（user@example.comはtrue、invalidはfalse、user@.comはfalse）を実行して結果を確認して」と指示する。この違いだけで、出力の信頼性は格段に変わります。

UI変更の場合は、Chrome拡張機能を通じてスクリーンショットを撮り、実装前後を比較させることも可能です。検証はテストスイート、リンター、あるいは出力をチェックするBashコマンドでもかまいません。重要なのは、Claude自身が「正しいかどうか」を判断できるフィードバックループを持つことです。

CLAUDE.md：セッションを超えて「記憶」を持たせる

Claude Codeのすべてのセッションは独立しています。会話履歴は次のセッションに引き継がれません。これは設計上の制約ですが、ではどうやってプロジェクトの文脈を維持するのか。

その答えがCLAUDE.mdです。プロジェクトルートに置かれたこのMarkdownファイルは、セッション開始時に自動的に読み込まれ、システムプロンプトの一部として機能します。技術スタック、コーディング規約、アーキテクチャの決定、セキュリティ要件、完了の定義。これらをCLAUDE.mdに記述しておけば、新しいセッションを開始するたびにClaude Codeは「このプロジェクトがどういうものか」を即座に理解します。

CLAUDE.mdの品質がClaude Codeの出力品質を決定的に左右します。同じプロンプトを投げても、CLAUDE.mdが整備されたプロジェクトとそうでないプロジェクトでは、出力の的確さに歴然とした差が出ます。

階層構造で「記憶」を設計する

CLAUDE.mdは階層構造を持つことができます。

~/.claude/CLAUDE.md: グローバル設定（すべてのプロジェクトに適用）
プロジェクトルートのCLAUDE.md: プロジェクト全体の規約
サブディレクトリのCLAUDE.md: ディレクトリ固有のルール
CLAUDE.local.md: gitignoreされる個人設定

例えば、src/components/ディレクトリにCLAUDE.mdを置いて「このディレクトリのコンポーネントはすべてProps型定義を先頭に書き、Storybook用のstoriesファイルを併設すること」と記述すれば、Claude Codeはそのディレクトリで作業する際に自動的にその規約に従います。チームの誰がClaude Codeを使っても、同じ規約が適用される。CLAUDE.mdは「AIへの指示書」であると同時に「チームのコーディング規約の実行エンジン」でもあるのです。

CLAUDE.mdは「短く、具体的に、検証可能に」

Anthropicの公式ドキュメントは、CLAUDE.mdについて明確なガイドラインを示しています。1ファイルあたり200行以下を目標にすること。長すぎるファイルはコンテキストを消費し、遵守率を下げます。

書くべき指示と書くべきでない指示の判断基準はシンプルです。「これを削除したらClaudeが間違いを犯すか？」。答えがNoなら、削除する。

含めるべきもの:

Claudeが推測できないBashコマンド（ビルド、テスト、リント）
デフォルトと異なるコードスタイルルール
プロジェクト固有のアーキテクチャ決定
一般的な落とし穴や自明でない動作

除外すべきもの:

Claudeがコードを読めば理解できるもの
標準的な言語規約（Claudeは既に知っている）
詳細なAPIドキュメント（リンクで参照すべき）
頻繁に変わる情報

/initコマンドでコードベースを分析させ、ビルドシステムやテストフレームワークを自動検出したCLAUDE.mdの雛形を生成できます。そこから改善していくのが最も効率的な始め方です。

`@import`とルールファイルで指示を分割する

CLAUDE.mdが肥大化してきたら、@path/to/file構文で外部ファイルをインポートできます。

プロジェクト概要は@READMEを参照。
利用可能なnpmコマンドは@package.jsonを参照。
Gitワークフロー: @docs/git-instructions.md

さらに大規模なプロジェクトでは、.claude/rules/ディレクトリにルールを分割できます。特にパス固有のルールが有用です。

---
paths:
  - "src/api/**/*.ts"
---
# API開発ルール
- すべてのAPIエンドポイントに入力検証を含める
- 標準エラー応答形式を使用する

このルールはsrc/api/配下のTypeScriptファイルを操作するときだけ読み込まれます。関係のないコンテキストを消費しないため、コンテキストウィンドウを効率的に使えます。

自動メモリ：Claudeが自分でメモを取る

CLAUDE.mdは人間が書く指示ですが、「自動メモリ」はClaude自身が書くメモです。作業中に発見したビルドコマンド、デバッグの知見、アーキテクチャの決定、コードスタイルの好みを、~/.claude/projects/<project>/memory/に自動保存します。

保存されたメモは次のセッション開始時に自動で読み込まれます（MEMORY.mdの先頭200行または25KBまで）。詳細な情報は別のトピックファイル（debugging.md、api-conventions.md等）に分離され、必要なときにオンデマンドで読み込まれます。

/memoryコマンドで、読み込まれているすべてのCLAUDE.mdとルールファイルの一覧確認、自動メモリのオン/オフ切り替え、メモリフォルダの参照と編集ができます。

MCPサーバー：Claude Codeを「閉じた世界」から解放する

MCP（Model Context Protocol）は、Claude Codeと外部システムを接続するためのプロトコルです。GitHub、Notion、Slack、Gmail、Google Calendar、データベース、ブラウザ自動化（Playwright）。MCPを通じて、Claude Codeはこれらのシステムに直接アクセスし、操作を実行できます。

従来のチャットAIは「テキストを生成して人間が転記する」というワークフローでした。MCPが変えたのは、「Claude Codeが直接外部システムを操作する」という点です。プルリクエストを作成し、Slackにメッセージを送り、Notionのドキュメントを更新し、データベースにクエリを投げる。すべてが自然言語の指示だけで実行されます。

2026年の重要な進化として「Deferred Tool Loading」があります。従来はセッション開始時にすべてのMCPサーバーのスキーマを読み込む必要がありましたが、現在はオンデマンドでスキーマを取得する方式に変わりました。これにより、多数のMCPサーバーを接続してもセッション開始のオーバーヘッドが発生しなくなっています。

MCPの導入で注意すべきは、権限の設計です。MCPサーバーに付与するアクセス権は、必要最小限に絞るべきです。特定のディレクトリだけ、特定のデータベース操作だけ、という形でスコープを限定する。「便利だから全権限を付与する」のは、セキュリティの観点から避けなければなりません。

なお、CLIツール（gh、aws、gcloud、sentry-cli等）もClaude Codeとの連携に有効です。CLIツールはMCPよりもコンテキスト効率が高く、GitHub連携ならgh CLI、クラウド操作なら各プロバイダのCLIを直接使わせるほうが軽量です。

スキル：「一度教えたら、永遠に覚える」仕組み

スキルは.claude/skills/ディレクトリに置くSKILL.mdファイルで定義される、再利用可能なワークフローです。一度設計すれば、Claude Codeはそのスキルを適切な文脈で自動的に起動します。

例えば、デプロイ用のスキルを定義しておけば、「デプロイして」と指示するだけでテスト実行、ビルド、デプロイターゲットへのプッシュが自動実行されます。セキュリティ監査用のスキルを定義しておけば、コードレビューの際にOWASP Top 10に基づく脆弱性チェックが走ります。

スキルの設計で重要なのは、frontmatterによる精密な制御です。

disable-model-invocation: trueを設定すれば、手動の/コマンドでしか起動しない安全なスキルになる（デプロイやコミットなど、誤って自動実行されると危険な操作に適している）
context: forkを設定すれば、スキルは独立したサブエージェントのコンテキストで実行され、メインのコンテキストを汚染しない
allowed-toolsでスキルがアクセスできるツールを明示的に制限できる

この設計は、UNIXの権限モデルと同じ発想です。「何ができるか」を明示的に定義し、それ以外はすべてブロックする。最小権限の原則がAIエージェントの設計にも適用されています。

一度ワークフローを設計すれば、二度目以降は指示するだけで同じ品質の作業が再現される。これがスキルの本質的な価値です。

CLAUDE.mdとスキルの使い分けも明確です。CLAUDE.mdはすべてのセッションで常にコンテキストに読み込まれる指示。スキルは呼び出されたとき、またはClaudeが関連性を判断したときにだけ読み込まれるモジュール化された知識です。広く適用されるルールはCLAUDE.mdに、特定ドメインの知識やワークフローはスキルに配置します。

フック：イベント駆動の自動化

フックは.claude/settings.jsonで定義される、ライフサイクルイベントに対するハンドラです。特定のイベントが発生したとき、自動的にシェルコマンドやHTTPリクエストを実行します。

CLAUDE.mdの指示は「ガイダンス」であり、Claudeが判断して従います。しかしフックは「決定論的」です。設定されたアクションは例外なく毎回実行されます。「ファイル編集後にリンターを走らせる」というフックは、Claudeがそれを忘れることがありません。

例えば、PostToolUseイベントに対して「EditまたはWriteツールが実行された後にリンターを走らせる」というフックを設定すれば、Claude Codeがファイルを編集するたびに自動的にコード品質がチェックされます。PreToolUseフックでは、ツールの引数を実行前に書き換えることすら可能です。

利用可能なイベントは多岐にわたります。ツールのライフサイクル（PreToolUse、PostToolUse）、セッション（SessionStart、Stop）、タスク（TaskCreated、TaskCompleted）、環境変更（CwdChanged、FileChanged）、権限（PermissionDenied）。

Claudeにフックを書かせることもできます。「すべてのファイル編集後にeslintを実行するフックを書いて」「migrationsフォルダへの書き込みをブロックするフックを書いて」のように指示するだけです。

フックとスキルの使い分けは明確です。スキルは「特定のタスクを実行するワークフロー」であり、フックは「特定のイベントに対する自動的な反応」です。ソフトウェアエンジニアリングに例えるなら、スキルは「関数」、フックは「イベントリスナー」です。

サブエージェント：並列処理で「コンテキスト汚染」を防ぐ

Claude Codeのコンテキストウィンドウは有限です。Opus 4.6で約20万トークン。複雑な作業を1つのセッションで処理し続けると、初期の指示や制約が「忘れられる」コンテキスト飽和が発生します。

サブエージェントはこの問題を解決します。メインのClaude Codeセッションから独立したコンテキストを持つ子エージェントを生成し、特定のタスクを委任する。セキュリティ監査、テスト生成、ドキュメント作成など、専門性の高いタスクをサブエージェントに切り出すことで、メインコンテキストの汚染を防ぎます。

Anthropicの公式ドキュメントでも、サブエージェントは「コンテキストが基本的な制約であるため、利用可能な最も強力なツールの1つ」と位置づけられています。Claudeがコードベースを調査するとき、多くのファイルを読み取り、すべてがコンテキストを消費します。サブエージェントは別のコンテキストウィンドウで実行され、要約だけをメインに報告するため、メインのコンテキストをクリーンに保てます。

2026年の新機能として「Worktree Isolation」があります。isolation: worktreeを設定すると、サブエージェントは独自のGitワークツリーで作業するため、ファイル編集の競合が物理的に発生しません。フロントエンドの作業とバックエンドの作業を完全に並列化できるようになっています。

ビルトインのサブエージェント型は3つあります。

Explore: 高速・読み取り専用。コードベースの調査に特化
Plan: リサーチとアーキテクチャ設計。コード変更は行わない
General-purpose: フルアクセス。実装作業が可能

使い分けの基準はシンプルです。「このタスクの結果をメインコンテキストに残す必要があるか」。残す必要がなければサブエージェントに委任する。残す必要があればメインで処理する。

プロンプトは「書くもの」ではなく「設計するもの」

Claude Codeの出力品質は、プロンプトの具体性によって決まります。

「タスク管理アプリを作って」というプロンプトと、「タイトル、説明文、期日、優先度を持つタスクの管理アプリ。ユーザーへのアサイン機能あり。localStorageに永続化。一覧・作成・編集・削除の4画面。React + TypeScript、UIライブラリはshadcn/ui」というプロンプトでは、出力の品質が全く異なります。

判断基準は「能力のあるエンジニアがこのプロンプトだけを読んで、あなたの意図通りのものを作れるか」です。この基準を満たさないプロンプトは、モデルの能力不足ではなく、仕様の不足です。

「探索→計画→実装」の3フェーズ

Anthropicが推奨するワークフローは明確に3つのフェーズに分かれています。

1つ目は「探索」。Plan Modeに入り、Claudeにファイルを読ませ、コードベースを理解させる。変更は一切加えない。

2つ目は「計画」。Claudeに詳細な実装計画を作成させる。Ctrl+Gを押せばテキストエディタで計画を開いて直接編集できる。

3つ目は「実装」。Normal Modeに戻り、計画に基づいてコーディングさせ、テストで検証する。

この計画フェーズに30分を投資することで、10時間のビルドが3時間に短縮されるケースは珍しくありません。ただし、タイプミスの修正やログ行の追加のような小さなタスクでは、計画をスキップして直接実行させるほうが効率的です。差分を1文で説明できるなら、計画は不要です。

コンテキストウィンドウは「最も重要なリソース」

Claude Codeのベストプラクティスの大半は、1つの制約に基づいています。コンテキストウィンドウはすぐにいっぱいになり、満杯になるにつれてパフォーマンスが低下するということです。

これを管理するための実践的な手法をまとめます。

無関係なタスクの間で/clearを実行し、コンテキストをリセットする
コンテキスト制限に近づくと自動コンパクションがトリガーされるが、/compact APIの変更に注力してのようにカスタム指示付きで手動実行もできる
調査タスクはサブエージェントに委任し、メインコンテキストの消費を防ぐ
会話履歴に入らない簡単な質問は/btwを使う（回答はオーバーレイに表示され、コンテキストを消費しない）
claude --continueで中断したセッションを再開、claude --resumeで最近のセッションから選択

同じ問題についてClaudeを2回以上修正した場合、コンテキストは失敗したアプローチで散らかっています。/clearを実行し、学んだことを組み込んだより具体的なプロンプトで新しく開始するほうが、蓄積された修正を持つ長いセッションをほぼ常に上回ります。

「デモが動く」と「プロダクトが動く」は全く別の問題

Claude Codeで何かを「動かす」こと自体は、もはや難しくありません。しかし、それを「プロダクトとして動かし続ける」ことは全く別の課題です。

デモとプロダクトの差を埋めるのは、ここまで述べてきた機能の「組み合わせ」です。

CLAUDE.mdで「完了の定義」を明示する（テストが通る、リンターエラーがない、エッジケースが処理されている、ドキュメントがある）
フックで品質ゲートを自動化する（コード変更のたびにリンターが走る）
スキルでデプロイメントを標準化する（手動のデプロイ手順を排除する）
サブエージェントでセキュリティ監査を並列実行する
MCPでCI/CDパイプラインと直接連携する

これらはすべて「Claude Codeをどう使うか」ではなく「Claude Codeの上にどういうシステムを構築するか」という問いです。個々のプロンプトを工夫するレベルの話ではなく、開発プロセス全体をClaude Codeを前提に再設計する。その発想の転換が、デモとプロダクトの間にある溝を埋めます。

避けるべき失敗パターン

最後に、Anthropicの公式ドキュメントが挙げている典型的な失敗パターンを整理しておきます。

「キッチンシンクセッション」。1つのタスクで開始し、無関係なことを聞き、最初のタスクに戻る。コンテキストが無関係な情報で埋まります。対策は、無関係なタスクの間で/clearを実行すること。

「何度も修正する泥沼」。Claudeが間違えたので修正し、まだ間違っている。コンテキストが失敗したアプローチで汚染されています。2回の修正で解決しない場合は、/clearして学んだことを反映したより良いプロンプトで再開するほうが速い。

「肥大化したCLAUDE.md」。長すぎるCLAUDE.mdは、重要なルールがノイズに埋もれ、Claudeが半分を無視します。容赦なく削除し、Claudeが指示なしで既に正しく行うことは書かない。

「検証なしの信頼」。Claudeがもっともらしい実装を生成したが、エッジケースを処理していない。常に検証手段（テスト、スクリプト、スクリーンショット）を提供する。検証できないなら、出荷しない。

おわりに

CLAUDE.mdでプロジェクトの記憶を設計し、MCPで外部システムと接続し、スキルでワークフローを標準化し、フックで品質を自動保証し、サブエージェントで作業を並列化する。個々の機能は単なる便利さですが、これらを組み合わせて設計されたシステムは、開発者一人の生産性を根本的に変えます。

Claude Codeは「ツール」ではありません。その上にシステムを構築するための「基盤」です。この違いを理解できるかどうかが、AIコーディングを「便利な補助」で終わらせるか、「開発プロセスそのものの再設計」につなげるかの分岐点ではないでしょうか。