Claude Code を使い始めた当初、私はそれをチャットのように扱っていました。
何かを依頼すると、それに応答が返ってきて、それで終わり。
確かに機能はしていましたが、時間が経つにつれて、その潜在能力を十分に引き出せていないことに気づき始めました。
同じプロンプトを繰り返し、同じコマンドを実行していました。どうすれば最大限に活用できるのか、はっきりと理解できていなかったのです。
そこで一旦立ち止まり、自問してみました。
Claude Code は内部で実際にどのように動いているのか？
私はドキュメントを読み始め、実験し、テストしました。
そして気づいたのは、こういうことです。
魔法を使っているわけではありません。それぞれに明確な役割を持つ、具体的な部品で構成されているのです。そして、それらを理解すれば、他のすべてが理解できるようになります。
→ 同じ指示を繰り返しているなら、それをスキルに変えましょう。
→ 長いタスクの途中で文脈を見失うなら、サブエージェントに委任しましょう。
→ 手動で繰り返している手順があるなら、フックで自動化しましょう。
基本を理解することで、何を、いつ、なぜ使うべきかがわかるようになるのです。
今では、100 を超えるスキル、以前は何時間もかかっていた自動化されたプロセス、コードレビューや興味のあるトピックを研究するためのエージェントを活用しています。
この記事では、私が学んだすべてを皆さんと共有するために書きました。
さあ、始めましょう。
エージェントループ：Claude Code の心臓部
Claude Code はエージェントです。
目標を与えられると、それを達成するまで働き続けるシステムです。
チャットとは異なります。チャットでは、「アプリに認証を追加するにはどうすればいいですか？」と尋ねると、手順を説明してくれます。
しかし、実際にプロジェクトに移動し、コードを修正し、動作をテストする必要があるのはあなたです。
作業を行うのは、あなたです。
Claude Code なら、「アプリに認証を追加して」と指示するだけで、それが処理されます。
コードを読み込み、ライブラリを選択し、変更を書き込み、完了したらあなたに通知します。
目標は、認証を追加することです。
そして、それを達成するまで働き続けます。
しかし、各ステップの後で次に何をすべきかをどのように判断するのでしょうか？ 何かが機能したかどうかをどのようにして知るのでしょうか？ それらの判断を調整するための何かが必要です。
それがループです。
繰り返されるサイクルです。
Claude Code はアクションを実行し、結果を観察し、次に何をすべきかを決定し、そして最初からやり直します。目標が達成されるまで停止しません。
何かが失敗した場合、戻って修正し、続行します。
ループには 3 つのフェーズがあります。
コンテキストの収集 → 何をすべきかを理解します。ファイルを読み、コードを分析し、プロジェクト構造を調べます。
アクションの実行 → 変更を実行します。ファイルを編集し、コマンドを実行し、依存関係をインストールします。
結果の検証 → 実行した内容が機能することを確認します。テストを実行し、エラーを確認し、何かが失敗した場合は修正します。
ループは、あなたの依頼に適応します。
単純な質問であれば、コンテキストの収集のみで済むかもしれません。バグの修正では、3 つのフェーズすべてを数回実行する必要があるかもしれません。
Claude Code は、前のステップから学習した内容に基づいて、各ステップで必要なものを決定します。そして、あなたもそのループの一部です。
いつでも割り込んで、方向を変えたり、コンテキストを追加したり、別のアプローチを試すように依頼したりできます。
これが Claude Code の心臓部です。
ここから説明するすべてのことは、このループをより強力にするために存在します。
ツール：Claude Code が外界で動作する仕組み
LLM は、設計上、テキストを処理するだけです。
テキストを受け取り、テキストを生成します。ファイルシステムにアクセスすることはできず、コマンドを実行することもできず、プロジェクトに何があるのかも知りません。
隔離されています。
では、Claude Code はどのようにしてファイルを開いたり、修正したりするのでしょうか？
ツールを使用します。
ツールとは、Claude Code が実際の世界とやり取りするために呼び出すことができる関数です。
携帯電話のアプリのように考えてください。電話本体だけでは何もできません。写真を撮ったり、メッセージを送ったり、ナビゲーションをしたりする具体的な機能を提供するのはアプリです。
ツールは Claude Code にとって同じものです。
ツールを使用するたびに、必要なものとともにシステムにリクエストを送信します。システムがそれを実行し、結果を返します。
Claude Code はその結果を使用して、次に何をすべきかを判断します。
1あなたのリクエスト2 ↓3Claude Code が使用するツールを決定4 ↓5┌─────────────────────────────────┐6│ 読み取り・編集・書き込み・Bash │7│ Grep・Glob・WebFetch・WebSearch │8└─────────────────────────────────┘9 ↓10システムがツールを実行11 ↓12結果が Claude Code に返る13 ↓14完了？→ いいえ → 別のツールを使用15 はい → 応答
Claude Code には、最も一般的な操作用のネイティブツールが付属しています。
読み取り / 編集 / 書き込み → ファイルの読み取り、修正、作成。最もよく使われます。Claude Code が「コードを理解する」または「変更を加える」たびに、これら 3 つを使用しています。
Bash → ターミナルへの完全なアクセス。コマンドラインでできることなら、Claude Code もできます。依存関係のインストール、テストの実行、コミットの作成など。
Grep と Glob → プロジェクト内の検索。Glob は名前またはパターンでファイルを検索します。Grep はファイル内の特定のコンテンツを検索します。
WebFetch と WebSearch → インターネットアクセス。ドキュメントの参照、API の読み取り、これまで見たことのないエラーの調査。
ログインボタンのバグの例に戻ります。
Claude Code がそれに取り組むとき、複数のツールを一緒に使用します。
→ Glob を使用してコンポーネントファイルを見つけます
→ 読み取りを使用してコードを読み、何が起こっているかを理解します
→ 編集を使用してエラーを修正します
→ Bash を使用してテストを実行し、動作することを確認します
これらすべてを、あなたが介入することなく行います。それがチャットとエージェントの違いです。
コンテキストとメモリ：Claude Code が覚えていること
Claude Code は動作し、アクションを実行し、結果を取得し、次に何をすべきかを決定します。
しかし、処理を進めるにつれて、自分が何をしたかをどのようにして把握しているのでしょうか？
それはすべて、コンテキストのおかげです。
コンテキストとは、その時点で Claude Code が利用できる情報です。アクションを実行するたびに、結果がそこに蓄積されます。
あなたの最初のプロンプトだけでなく、見つけたすべてのもの（開いたファイル、コードで発見したこと、実行したアクションとその結果）が含まれます。
そのため、ステップを連鎖させ、自分自身を修正し、タスクを単独で完了することができるのです。
そのコンテキストには 2 つの問題があります。
1. 容量に制限がある。 セッションが非常に長くなると、コンテキストがいっぱいになり、Claude Code は以前に何が起こったかを忘れ始めます。後ほど、サブエージェントがこれをどのように解決するかを説明します。
2. 新しい会話を開くたびに空になる。 Claude Code は、自分がどのプロジェクトにいるのか、チームがどのように作業しているのか、すでにどのような決定が下されているのかを知りません。あなたが伝えなければ、推測するか、あなたに尋ねます。
メモリが 2 番目の問題を解決します。
これはマークダウンファイルシステムであり、Claude Code が知っておく必要のあるすべてのもの（使用しているスタック、チームの規約、プロジェクトの構成方法など）を保存します。
Claude Code は各セッションの開始時にこれらを読み取り、最初の行を書く前にその情報をコンテキストに注入します。
メモリなしの場合：「ユーザーを作成するエンドポイントを追加して」と指示すると、Claude Code は「どのフレームワークを使っていますか？ データベースは設定されていますか？ ルートはどのように構成されていますか？」と尋ねます。
メモリありの場合：同じことを指示すると、Claude Code はすでに Express と Prisma を使用していること、ルートが /src/routes にあること、エラーが一元化されたミドルウェアで処理されていることを知っています。尋ねることなく作業を開始します。
Claude Code には 2 つのメモリシステムがあります。
→ CLAUDE.md - Claude Code が知っておく必要のあるすべてのことを記述したマークダウンファイル。さまざまなレベルに配置できます。
→ ~/.claude/CLAUDE.md - すべてのプロジェクトに適用されます。個人の好みをここに記述します。コードの書き方、常に使用する規約など。指示は具体的に記述する必要があります。「コードのフォーマットを整えて」よりも「インデントは 2 つのスペースを使って」の方が明確です。
→ /your-project/CLAUDE.md - リポジトリ固有。アーキテクチャ、チームの規約、重要なコマンドをここに記述します。新しいプロジェクトを開始するときは /init を実行すると、Claude Code が自動的に生成します。200 行未満に保ってください。大きくなりすぎると、Claude Code が指示を無視し始めます。また、リポジトリにコミットすれば、チーム全体が同じコンテキストを共有できます。
→ .claude/rules/ - ファイルの種類に応じてアクティブになるモジュール式ルール。プロジェクトが大きくなり、すべてを 1 つのファイルにまとめたくない場合に便利です。
オートメモリ - Claude Code が自分で構築するメモリ。作業を進めるにつれて、自動的にメモを取ります。検出したパターン、あなたが行った修正、一緒に下した決定などです。~/.claude/projects/<project>/memory/ に保存され、各セッションの開始時に読み込まれます。
頻繁に確認してください。Claude Code があなたの気づかないうちに悪い習慣を保存している可能性があります。
ヒント： /memory を実行すると、Claude Code が覚えているすべてを表示および編集できます。
フックとスキル：制御を掌握する
1. フック
Claude Code は自律的に動作します。
アクションを実行し、決定を下し、前進します。
しかし、その自律性にはあまり言及されない側面があります。Claude Code は各ステップで正しいと判断したことを実行するということです。
何かがうまくいかなかったり、意図していないことを実行したりすると、それはすでに実行されてしまっています。
どうやって制御するのでしょうか？ フックを使います。
フックとは、サイクルの特定のポイントで自動的に実行されるコマンドです。Claude Code がツールを使用する前、使用した後、セッションが終了したときなどです。
各時点で何が起こるかを定義します。
重要なのは、フックは決定論的であるということです。
Claude Code が何かを「覚えて」実行することに依存しません。例外なく、常に実行されます。
4 つの主要なフックは次のとおりです。
PreToolUse - Claude Code がツールを使用する前に実行されます。アクションをブロックできる唯一のフックです。例：.env ファイルを変更しようとするコマンドをすべてブロックします。
PostToolUse - Claude Code がツールを使用した後に実行されます。例：Claude Code がファイルを編集するたびに、Prettier を自動的に実行します。
通知 - Claude Code があなたの注意を必要とするときに実行されます。例：Claude Code が長時間のタスクを完了したときに、Mac に通知を送信します。
停止 - Claude Code が応答を終了したときに実行されます。例：エージェントが終了したときに、ステージングに自動的にプッシュします。
これらは .claude/settings.json で設定されます。
1{2 "hooks": {3 "PostToolUse": [4 {5 "matcher": "Edit|Write",6 "hooks": [7 {8 "type": "command",9 "command": "npx prettier --write $file_path"10 }11 ]12 }13 ]14 }15}
このフックは、Claude Code がファイルを編集または作成するたびに、Prettier を自動的に実行します。
あなたが依頼しなくても。Claude Code が覚えていなくても。
フックなし：Claude Code がファイルを編集し、コードのフォーマットが整っておらず、次のコミットで気付く。
フックあり：Claude Code がファイルを編集し、PostToolUse が自動的にトリガーされ、Prettier がファイルをフォーマットし、コードは常にクリーンな状態を保つ。
フックを使用すると、エージェントのサイクルに保証された動作を追加できます。提案でも、モデルが無視できる指示でもありません。常に実行されるルールです。
2. スキル
もう 1 つ問題があります。一貫性です。
同じタスクを 2 回依頼すると、異なる結果が得られます。新しい会話を開くたびに、Claude Code は前回どのように行ったかを知らない状態で開始します。
どうやって解決するのでしょうか？ スキルを使います。
スキルとは、Claude Code に対してタスクの正確な手順（何を確認するか、どの順序で、どの形式を使用するか、何を無視するか）を説明するマークダウンファイルです。
そのタスクが発生するたびに、Claude Code はその指示に従います。
スキルなし：API のドキュメント作成を依頼すると、何かを生成しますが、毎回異なる形式になります。例があったり、なかったりします。
スキルあり：API のドキュメント作成を依頼すると、あなたが定義した正確な手順に従います。常に同じステップ、同じ形式、同じ基準で。毎回同じです。
スキルを作成するには、次の構造のフォルダを定義します。
1my-skill/2├── SKILL.md # メインの指示（必須）3├── template.md # Claude が記入するテンプレート4├── examples/5│ └── sample.md # 期待される出力の例6└── scripts/7 └── validate.sh # Claude が実行できるスクリプト
必須なのは SKILL.md だけです。残りはオプションであり、タスクの必要に応じて追加します。
SKILL.md には 2 つの部分があります。
フロントマター - 名前と説明を含む YAML ブロック。名前は手動で呼び出すためのコマンドです。説明は、Claude Code が自動的にアクティブにするかどうかを判断するために読み取るものです。
本文 - マークダウンでの指示。ワークフロー、基準、出力形式。
1---2name: api-docs3description: API エンドポイントをドキュメント化します。ユーザーが4 API のドキュメント化を依頼したり、「swagger」や「エンドポイント」に言及したときに使用します5---67## プロセス81. すべてのエンドポイントを特定する92. 各エンドポイントについて：メソッド、パス、パラメータ、期待されるレスポンス103. リクエストとレスポンスの例を含める114. 最後にサマリーテーブルを記載する
作成したら、2 つの方法で呼び出すことができます。
チャットで直接 /api-docs と入力するか、自然言語で Claude Code に依頼するだけです。
説明があなたの依頼内容に一致する場合、自動的にアクティブになります。
明確なプロセスがある、繰り返し行うあらゆるタスク（API ドキュメント、変更ログ、ミーティングの要約、コード移行など）に対して作成できます。
サブエージェント：問題が大きくなったら委任する
コンテキストには容量制限があることをすでに説明しました。
セッションが長くなるほど、コンテキストはいっぱいになります。そして、いっぱいになると、Claude Code は以前に何が起こったかに関する情報を失い始めます。
プロジェクト全体をセキュリティ上の問題についてレビューするように依頼したと想像してください。数十のファイルを読み、コードを分析し、詳細なレポートを生成します。
これらすべてがすぐにコンテキストをいっぱいにします。
そして、その間、メインの会話はブロックされます。
どうやって解決するのでしょうか？ サブエージェントを使います。
サブエージェントは、独自のコンテキストで実行される Claude Code の独立したインスタンスです。
メインのエージェントがタスクを委任し、サブエージェントが独立して実行し、完了すると結果のサマリーを送信します。
メインのエージェントのコンテキストはプロセス全体でいっぱいになることはなく、結論だけが含まれます。
1メインエージェント2 ↓3「プロジェクトをセキュリティ問題についてレビューして」4 ↓5┌─────────────────────────────┐6│ サブエージェント：security-reviewer │7│ │8│ プロジェクトファイルを読む │9│ コードを分析する │10│ 脆弱性を検出する │11│ レポートを生成する │12└─────────────────────────────┘13 ↓14サマリーをメインエージェントに返す15 ↓16メインエージェントがループを続行
そして、それだけではありません。
サブエージェントは並行して実行できます。
コードの 3 つの部分を順次分析する代わりに、Claude Code は 3 つすべてを同時に委任できます。
以前は数分かかっていたことが、数秒で済む可能性があります。
1メインエージェント2 ↓3作業を独立したタスクに分割4 ↓5┌──────────────┐ ┌──────────────┐ ┌──────────────┐6│ サブエージェント 1 │ │ サブエージェント 2 │ │ サブエージェント 3 │7│ │ │ │ │ │8│ 認証をレビュー │ │ DB をレビュー │ │ 外部 API を │9│ │ │ │ │ レビュー │10└──────────────┘ └──────────────┘ └──────────────┘11 ↓ ↓ ↓12 メインエージェントが 3 つのサマリーを受信13 ↓14 ループを続行
Claude Code には、自動的に使用する 3 つのネイティブサブエージェントがあります。
→ 探索 - プロジェクトの検索と分析に特化した、高速な読み取り専用エージェント。結果はサブエージェントのコンテキストに留まり、あなたのコンテキストには入りません。
→ 計画 - 計画モードでアクティブになります。Claude Code があなたに計画を提示する前に、プロジェクトの調査をこのエージェントに委任します。
→ 汎用 - 探索と修正の両方を必要とする複雑なタスク用。
独自のサブエージェントを作成することもできます。
サブエージェントは、YAML フロントマターを含むマークダウンファイルで定義され、.claude/agents/ に保存されます。
1---2name: security-reviewer3description: セキュリティ脆弱性についてコードをレビューします。4 ユーザーがセキュリティレビューを依頼したときに使用します。5tools: Read, Grep, Glob6---78あなたはセキュリティの専門家です。以下の点についてコードを分析してください：9- SQL インジェクション10- 機密データの露出11- 認証の脆弱性1213最後に、重大度順に並べた調査結果のサマリーを記載してください。
フロントマターでツールを Read、Grep、Glob に制限していることに注意してください。
このエージェントは分析はできますが、何も変更することはできません。
各エージェントが何をできるかを細かく制御する必要がある場合、このツール制限が鍵となります。
作成すると、Claude Code は説明によって自動的に検出し、タスクに合うときに呼び出します。または、明示的に呼び出すこともできます。「この PR をレビューするために security-reviewer エージェントを使って」。
サブエージェントを使用する場合と使用しない場合の判断基準は？
タスクが長く、多くの出力を生成する場合、作業を並行して実行できる独立した部分に分割できる場合、またはツールが制限された特殊なエージェントが必要な場合に有効です。
コンテキストを満たさない短いタスクには価値がありません。 メインエージェントが 2 分で解決できるタスクに、サブエージェントを調整する複雑さを追加しても意味がありません。
MCP：エージェントと外界を接続する
ツールは、Claude Code にマシン上で動作する能力を与えます。
しかし、限界があります。発生するすべてのことは、そのマシン上で起こります。
GitHub で PR を開くこと、本番データベースにクエリを実行すること、Jira でチケットを作成することはできません。それを行うには、以前はエージェントから離れて、自分で手動で行う必要がありました。
どうやって解決するのでしょうか？ MCP を使います。
MCP（Model Context Protocol） は、Claude Code が外部サービスとどのように接続するかを定義するオープンプロトコルです。
クライアントサーバーアーキテクチャで動作します。Claude Code がクライアントであり、各外部サービスには、実行可能な機能を公開する独自の MCP サーバーがあります。
MCP サーバーを接続すると、Claude Code は名前と説明付きの利用可能なツールのリストを受け取ります。
その後は、ネイティブツールとまったく同じように使用します。唯一の違いは、アクションが自分のマシン上ではなく、外部サービスで発生することです。
1Claude Code2 ↓3GitHub MCP サーバーからツールを使用することを決定4 ↓5┌─────────────────────────────┐6│ GitHub MCP サーバー │7│ │8│ PR を開く │9│ レビュアーを割り当てる │10│ 確認を返す │11└─────────────────────────────┘12 ↓13Claude Code が結果を受信し、続行
MCP なし：「変更は終わったから、PR を開いて」と指示しても、Claude Code はできません。自分で GitHub に行き、フォームに記入し、レビュアーを割り当て、マージする必要があります。
MCP あり：同じことを指示すると、Claude Code が PR を開き、説明を書き、レビュアーを割り当て、準備ができたら通知します。エージェントから離れることなく、すべて実行されます。
今日接続できるいくつかの MCP サーバー：
→ GitHub - PR、レビュー、イシュー
→ Postgres / Supabase - データベースへのクエリと変更
→ Slack - メッセージとチャンネル
→ Jira - チケットとプロジェクト
ローカル環境用のネイティブツール。外界用の MCP。
すべてがどのように連携するか
Claude Code はエージェントです。目標を受け取り、それを達成するまで自律的なループで動作するシステムです。
この記事で見たすべてのピースは、そのループをより強力にするために存在します。しかし、それらを理解する最良の方法は、それらが相互作用しているところを見ることです。
ケース 1：PR をレビューしてマージする
「PR #42 をレビューして、問題なければマージして」と依頼します。
→ GitHub MCP を使用して、変更されたファイルを読み、変更内容を理解します
→ セキュリティ分析を専門のサブエージェントに委任し、メインのコンテキストを満たさないようにします
→ フックがローカルでテストを実行し、すべてがパスすることを確認します
→ テストがパスしたら、GitHub MCP を使用して、あなたがインターフェースに触れることなくマージを実行します
あなたは 1 行書いただけです。Claude Code は 4 つのシステムを調整しました。
ケース 2：API をドキュメント化し、チームに通知する
「新しいエンドポイントをドキュメント化して、チームに知らせて」と依頼します。
→ ドキュメント化スキルをアクティブにし、正確な形式（何を含めるか、どのように構成するか、どのような例を追加するか）を定義します
→ ツールを使用してコードを読み、エンドポイントを抽出します
→ フックが保存前に出力をフォーマットします
→ Slack MCP を使用して、サマリーをチームチャンネルに送信します
毎回行っても、結果は同じです。ばらつきはなく、あなたが何も説明する必要もありません。
すべてはループを中心に展開します。
各セッションを情報を得た状態で開始するためのメモリ。動作するためのツール。制御するためのフック。標準化するためのスキル。規模を拡大するためのサブエージェント。外界と接続するための MCP。
それを理解すれば、Claude Code を理解したことになります。
そして、Claude Code だけでなく、Cursor、Copilot、そして今後使用するあらゆるエージェントは、同じ基盤の上で動作します。
名前は変わり、インターフェースは変わりますが、ループは同じです。
AI は急速に進歩しています。
毎週、何か新しいものがあります。しかし、基盤はそれほど頻繁には変わりません。それらを明確に理解しておくことが、より速く適応し、次に来るものからより多くを得るための鍵となります。
Claude Code をプロンプトを送るためだけに使わないでください。その下で何が起こっているかに注意を払ってください。そこに機会があります。
今日から始めるためのいくつかの出発点：
→ オートメモリを確認し、Claude Code が保存した内容を改善する
→ プロジェクト用の CLAUDE.md をまだ持っていなければ作成する
→ GitHub MCP を接続する
→ コンテキストを満たすタスク用のサブエージェントを構築する
→ 各変更後にテストを実行するフックを設定する
以上です。また明日。
マーカス
