デジタル工房 HABAねっと

Claude Code が動作する仕組み

執筆者:

HABA

カテゴリ:

このドキュメントは、Claude Codeを使い始めて1ヶ月ほど経ち、複数の拠点で開発を行う方を対象に、その仕組みと最適な運用方法を解説するものです。

「CLI、Desktop、VS Code、Web版のどれを使えばいいのか？」「拠点間で環境がバラバラでも大丈夫か？」といった疑問を解消するため、共通の核となる「エージェントループ」の仕組みから、各インターフェースの使い分けを図解とともに整理しました。

想定読者（利用1ヶ月、複数拠点利用、環境の差異に混乱している層）

① エージェントループ

Claude Code の核心である「エージェントループ」の全体像です。


図1 Claude Code の全体構造

Claude Code は「コンテキスト収集 → アクション実行 → 結果検証」の3フェーズを繰り返すエージェントループで動いています。 Claude Code Docs

このループが自動的に何十回も回ることで、「バグを直して」という一言から「テスト実行 → 該当ファイル特定 → 修正 → 再テスト → コミット」まで連続して実行されます。

Claude モデル（Sonnet/Opus）が「次に何をすべきか」を推論し、エージェントハーネスがその判断に従ってファイル操作・コマンド実行などを行う、という役割分担です。

② インターフェース比較

次に、各インターフェース（CLI・Desktop・VS Code・Web）の比較を図解します。

図2 インターフェース別 できること・できないこと

どのインターフェースを使っても、エンジン（エージェントループ）は同じです。変わるのは「コードがどこで実行されるか」と「どう操作するか」だけです。 Claude Code Docs

複数拠点での利用でよく混乱するポイント

よくある疑問1：拠点AとBで使うインターフェースは統一すべきか？
不要。ローカル版（CLI・Desktop・VS Code）は設定を共有。インターフェースが違っても問題なし

よくある疑問2：拠点間でのコードの同期はどうするか？
GitHub を使った git push/pull が正解。Claude Code 自体の機能でファイルを転送する仕組みはない

よくある疑問3：Web 版ならローカルPCに何もインストールしなくていい？
Web版はAnthropicが管理するVMで実行されるため、ローカルファイルへのアクセスはできない。
Web は Anthropic のクラウドで実行されるため、切断後もタスクが続行されます。

Web は Anthropic のクラウドで実行されるため、切断後もタスクが続行されます。

Claude Code Docs  Claude Code を実行する場所

自分のコードを使うならローカル版が必要

よくある疑問4：CLI が「最強」か？
CLIはAgent SDK、スクリプト自動化、他社モデルへの切り替えなどCLIにし
かない機能があり、最もフル機能な選択肢。

CLI はターミナルネイティブな作業に最も完全なサーフェスです。スクリプティング、サードパーティプロバイダー、Agent SDK は CLI のみです。

Claude Code Docs 

 ただし、初心者には 最初に CLIのようなコマンドプロンプト操作は敷居が高く感じられるので、用途に合わせて選べばよいです。

③ セッション・コンテキスト・チェックポイント

最後に「セッション・コンテキスト・チェックポイント」の仕組みを図解します。

図3 セッション・コンテキスト・チェックポイントの仕組み

  • セッションはディレクトリ単位で管理。–continue で再開、–fork-session で分岐できます。

  • CLAUDE.md はセッションをまたいで毎回読み込まれる「プロジェクト固有の指示書」。コンテキストが満杯になっても失われないよう、永続させたいルールはここに書くことが推奨されています。 Claude Code Docs

  • チェックポイントは git とは別の仕組みで、ファイル編集前に自動スナップショットを保存。Esc キー ×2回 で巻き戻せます。Claude Code Docs

拠点ごとにインターフェースが違っていても、GitHub でコードを同期しつつ、各PCで好みのインターフェースを使うのが最もシンプルで現実的な運用です。

コンテキスト収集フェーズとは

コンテキスト収集フェーズとは、Claude が実際に作業に取り掛かる前に「状況を把握する」ステップです。

コンテキスト収集フェーズ ── Claude が「状況を把握」する瞬間

簡単に言うと、「あなたが何を頼んでいるか」「プロジェクトがどういう状態か」をClaude が一気に読み込む準備フェーズです。

Claude は作業開始時に、コンテキスト収集・アクション実行・結果検証の3フェーズを繰り返しますが、これらのフェーズは互いに溶け合っています。コンテキスト収集のためにファイルを検索し、変更のために編集し、作業を確認するためにテストを実行するという形でツールを使い続けます。

集められる情報は大きく8種類あります。

8つの情報源

左側4つは「最初から自動で読み込まれるもの」です。

ユーザーの指示（プロンプト）はもちろん、CLAUDE.md（プロジェクト固有の指示や規約を書いておくマークダウンファイル）、過去セッションの学習内容（Auto Memory）、現在のブランチ・未コミットの変更・直近のコミット履歴などのgit の状態が含まれます。 Claude Code Docs

右側4つは「タスクに応じて動的に収集されるもの」です。

ファイルの読み込みや検索、Webによるドキュメント参照やエラー調査 、そして前のステップで実行したコマンドの出力結果なども次の判断材料としてコンテキストに積み上がっていきます。

コンテキストウィンドウの上限

集めた情報はすべて「コンテキストウィンドウ」という器に入れて処理されます。
上限に近づくと、Claude Code は古いツール出力から自動で削除し、必要に応じて会話を要約します。

永続させたいルールはコンテキストが溢れても消えないよう、設定ファイル CLAUDE.md に書いておくことが推奨されています。 

/context コマンドで現在の使用状況を確認できます。CLAUDE.md が特に重要なのはそのため、毎回セッション開始時に自動で読み込まれるため、指示が消える心配がありません。

https://note.com/habanet_com/n/ne4cea04713dd

アクション実行フェーズとは

アクション実行フェーズは、コンテキスト収集で状況を把握したClaudeが実際に「手を動かす」フェーズです。

アクション実行フェーズ
アクション実行フェーズ ── Claude が「手を動かす」瞬間

5カテゴリのツール

ツールはClaude Codeをエージェントたらしめるものです。
ツールがなければClaudeはテキストで応答するだけですが、ツールがあることでClaudeは行動できます。 

5つのカテゴリは次のとおりです。

  1. ファイル操作（ファイルの読み書き・作成・名前変更・整理）

  2. 検索（パターンによるファイル検索・正規表現による内容検索・コードベースの探索）

  3. コマンド実行（シェルコマンド・サーバー起動・テスト実行・git操作）

  4. Webアクセス（Web検索・ドキュメント取得・エラーメッセージ調査）

  5. コード解析（編集後の型エラーや警告の確認・定義へのジャンプ・参照の検索、ただしプラグインが必要）

ポイント：ツールを連鎖させる

「失敗しているテストを直して」と言うと、Claudeは

  1. テストスイートを実行して何が失敗しているかを確認し

  2. エラー出力を読み取り

  3. 関連ソースファイルを検索し

  4. それらを読んでコードを理解し、問題を修正するためにファイルを編集し

  5. 再度テストを実行して検証する

という流れで動きます。

バグ修正の行動例


各ツール使用がClaudeに新しい情報をもたらし、次のステップに反映されます。これがエージェントループの実際の動作です。

安全面：チェックポイントと権限モード

ファイルを編集する前には必ずスナップショット（チェックポイント）が自動保存されます。Escキー×2回 でいつでも巻き戻せます。

また Shift+Tab で権限モードを切り替えることで、Claudeが何をどこまで自動で実行するかをコントロールできます。

複数拠点で作業している場合、慣れないPCでは「Default（都度確認）」モードで始めるのが安全です。

結果検証フェーズとは

結果検証フェーズは、アクションを実行したあとで Claude が「本当にうまくいったか」を自分で確かめるステップです。

検証結果フェーズ
結果検証フェーズ ── Claude が「確かめる」瞬間

4つの検証方法

ツールを使ってアクションを実行するたびに、その結果がコンテキストに戻ってきて次の判断に使われます。具体的には次の4種類で確認します。

  1. テスト実行：もっとも基本で、npm test や pytest などを自動テストのフレームワークを実際に走らせてパス／フェイルを判断します。

  2. 差分確認：編集したファイルの変更内容が意図通りかを確かめます。

  3. エラー確認：型エラー (Type Errors)、リント (Lint Errors)、ビルドエラー (Build Errors)を拾います。（コードインテリジェンスプラグインが入っていれば自動）

  4. 出力検証：コマンドの標準出力を読んで期待値と突き合わせます。

「問題あり」なら自律的にループする

エージェントループは質問に応じて適応します。バグ修正はすべてのフェーズを繰り返し循環し、何十もの行動を連鎖させながら途中で軌道修正します。 

つまり1回で直らなければ、また「コンテキスト収集 → アクション実行 → 結果検証」を繰り返します。ユーザーが何もしなくても自動で回り続けます。

ユーザーが割り込めるのもこのフェーズ

ユーザーもこのループの一部です。どの時点でも割り込んで、別方向への誘導・追加コンテキストの提供・別アプローチの試行を依頼できます。

検証結果を見て「その直し方ではなくこっちの方針で」と入力すれば、Claude はその場で方向を変えます。なお外部 API やデータベースへの操作は検証後も巻き戻せないため、事前に Plan mode（Shift+Tab 2回）で計画を確認しておくのが安全です。

解釈の仕組み

コマンド出力の解釈は、結果検証フェーズの中でも特に重要な部分です。

Claude がコマンド出力を解釈する流れを説明します。

結果検証フェーズ ── Claude が「確かめる」瞬間

コマンド実行後、その標準出力・標準エラー出力・終了コードがそのままコンテキストウィンドウに追加されます。
Claude はそれをテキストとして読み、次の判断材料にします。特別な「解析エンジン」があるわけではなく、言語モデルとしての読解力で解釈しています。

具体的に何を読み取るか

終了コード（exit code） はまず最初に見ます。0 なら成功、0 以外なら何らかの失敗と判断します。

エラーメッセージのパターン認識 は得意分野です。”TypeError: Cannot read properties of undefined”、”ENOENT: no such file or directory”、”AssertionError” のような見慣れたパターンから、何が起きているかを推定します。

テストフレームワークの出力 も読み解きます。Jest なら “Test suite failed to run”、pytest なら “FAILED test_foo.py::test_bar” のような構造化されたテキストから、どのテストがどんな理由で落ちたかを把握します。

数値や統計 も拾います。ビルド時間、テスト通過数、カバレッジ率、警告の件数などを見て、改善しているか悪化しているかを判断します。

注意点：あくまでテキスト解釈

Claude はコマンド出力を「読む」だけで、バイナリ・画像・インタラクティブな TUI (ターミナルユーザーインターフェース)などは解釈できません。

また出力が長すぎるとコンテキストウィンドウを大量消費するため、冗長なログを垂れ流すコマンドは | tail -50 などで絞ってから渡すと効率的です。

🛠 デジタル工房 HABAねっと
北陸を拠点に、中小企業経営者・個人事業主がデジタル経営を実現するためのお手伝いを行っています。
「外注で完結」ではなく「自社で動かせる体制を作る」伴走型の支援を、北陸から提供しています。

サービス一覧 ▶ https://habanet.jp/services/
お問い合わせ ▶ https://habanet.jp/contact/

シェアする Facebook X (Twitter)