Agentic Loop（エージェンティック・ループ）

Claude Codeが普通のチャットAIと何が違うのか、内部でどう動いているのか知りたい人向け

Agentic Loop は、Claude Code が頼みごとを片付けるときの「動き方」のことです。普通のチャットAIは、聞かれたら文章で1回答えて終わります。Claude Code は違って、自分でファイルを読みに行き、コードを直し、テストを動かして直ったか確かめる、という動作を自分でぐるぐる回します。この「回す動き」が Agentic Loop です。

公式ドキュメントは、この動きを3つの段階に分けています。材料を集める、手を動かす、結果を確かめる。この3つが混ざり合いながら進みます。前の段階で分かったことを元に次の一手を自分で決めて、ときには途中で「あ、方向が違った」と気づいて軌道修正もします。

噛み砕くと

新しい職場に入った初日の同僚を思い浮かべてください。「この資料のミス直しといて」と頼むと、できる人は勝手にキャビネットを開けて元データを探し、該当箇所を直し、念のため見直してから「直しました」と返してきます。指示の一つ一つを待ちません。

Agentic Loop はこれと同じ動きです。あなたが「ログインのバグ直して」と1行頼むだけで、Claude Code は自分で関連ファイルを開き、原因を探し、直して、テストで答え合わせまでやります。

普通のチャットAIだと「ここを確認してみては?」という文章のアドバイスで終わります。手は動かしません。ここが一番大きな違いです。

そして大事なのが、あなた自身もこのループの中にいるという点。途中で「いや、そっちじゃない」と口を出せば、Claude Code はそれを受けて方向を変えます。丸投げして待つだけでも、横から口を出して操縦してもいい。そういう関係です。

ループを動かしているのは「考える頭」と「動く手」の2つ

公式ドキュメントは、Agentic Loop を動かす部品は2つだと書いています。考える側のモデルと、動く側のツールです。

モデルは Claude 本体のこと。コードを読んで意味を理解し、何を直せばいいか筋道を立てる頭の部分です。ツールは、その判断を実際の行動に移す手の部分。読む、書き換える、動かす、検索する、を担当します。

公式の言い方を借りると、ツールがなければ Claude は文章で答えることしかできません。ツールがあって初めて、Claude は「動ける」。ここはハッキリ言い切られています。

そして Claude Code 自体は、この頭と手をつなぐ「外枠」の役です。公式は agentic harness（エージェンティック・ハーネス）と呼んでいます。道具をそろえ、会話の記憶を管理し、コマンドを実際に動かす場所を用意する。これによって、ただ喋るだけの言語モデルが「コードを書ける相棒」に変わる、という構図です。

「読書記録アプリのログインバグ」を例に、実際の動きを見る

具体的な題材で追います。本の感想を記録するアプリを作っていて、ログインした直後にすぐ401エラーが出る、という状況。401エラーというのは、サーバーから「あなた誰?」と弾かれて中に入れない状態のことです。せっかくログインしたのに、認証がすぐ切れてしまう。

これを Claude Code に直してもらいます。ここからループが回り始めます。

ステップ1: 頼む

ターミナルに、こう打って送ります。

ログイン後にすぐ401エラーになるバグを直して。
認証まわりは auth.js と tokens.js を見て。

ここで初心者がやりがちな勘違いがあります。「どのファイルを開いて、何行目をこう直して」と全部こちらが指示しないと動かないと思いがちです。そんなことはありません。「直して」の一言でも動きます。ただし対象ファイルを最初に教えておくと、後の往復が減ります。理由は後で書きます。

ステップ2: 材料を集める（gather context）

Claude Code は、まず自分で状況を調べ始めます。指定した auth.js を読み、認証トークンを更新している処理がどこにあるかを検索し、tokens.js も開いて中身を確認する。この「読んで・探して・理解する」段階が材料集めです。

ここではまだ何も書き換えていません。現場を見て回っているだけ。

ステップ3: 手を動かす（take action）

調べた結果、原因の見当がつきます。たとえば「トークンを更新するとき、新しいトークンが発行される前に古いトークンを無効化していて、一瞬だけ認証が空っぽになる」といった具合です。Claude Code は、その箇所を tokens.js で書き換えます。

この「実際にファイルを編集する」のが、手を動かす段階です。

ステップ4: 結果を確かめる（verify results）

直したら終わり、ではありません。Claude Code はテストを動かして、本当に直ったかを自分で確認します。

$ npm test

ここで「ログイン後のテストが通った」と出れば、答え合わせ成功です。普通のチャットAIには、この「自分で動かして確かめる」段階がありません。文章で「これで直るはずです」と返すだけです。

ステップ5: 通らなければ、また回す（course-correct）

もしテストがまだ通らなかったら、Claude Code はそのエラー内容を読んで、もう一度ステップ2に戻ります。新しく分かったことを元に、別の原因を探し、また直し、また確かめる。これを「自分で」繰り返すのがループの本体です。

公式は、バグ修正だと3つの段階を何度も繰り返し、何十もの動作をつないでいく、と書いています。1往復で終わるとは限りません。

ステップ6: 見当違いなら、横から止める

途中で Claude Code が明らかに違う方向に進んでいたら、放っておく必要はありません。Esc キーを押せば、その場で動作が止まり、次の指示を待つ状態になります。

あるいは、止めずに修正だけ打ち込んで Enter で送る手もあります。すると Claude Code は、今やっている動作が終わった瞬間にそれを読んで、次の一手を決める前に方向を直します。あなたもループの一部、というのはこういうことです。

つまり Agentic Loop は何をしているのか

• やってくれる: 1行頼むだけで、自分でコードを読み・直し・テストで確かめるところまで一気に進める。直らなければ自分で何度も回し直す
• やってくれない: ツールがなければただの文章応答に戻る。読む・書き換える・動かす、はすべてツールを通して行われるので、道具を取り上げると手が止まる
• 意味が薄い場面: 「このアプリって何ができるの?」みたいな、コードを触らず一般論を聞くだけの質問。この場合は材料集めだけで終わり、ループが何周も回ることはない

使いどころ3シナリオ（読書記録アプリで再現）

シナリオ1: ただ知りたいだけのとき

「このアプリのログイン処理って、どこから呼ばれてる?」と聞く場面。これは調査だけで答えが出ます。Claude Code はファイルを読んで関係する箇所を探し、「こことここで呼ばれています」と教えて終わり。コードは一切書き換えません。

公式の言い方だと、コードについての質問は材料集めだけで足りる、というケースです。ループが3段階フル回転する必要はありません。

シナリオ2: バグを直したいとき

さっきの401エラーがこれです。原因が一発で分からないことも多いので、調べる→直す→確かめる、を何度も回します。テストが通るまで自律的に進むのが強み。

個人的には、ここが Claude Code を使う一番のうまみだと思っています。エラーログを貼って「これ直して」と投げるだけで、テストが緑になるまで付き合ってくれる。地味だけど効きます。

シナリオ3: 既存コードを整理して書き直したいとき

「読書記録の保存処理、同じような処理が3か所に散らばってて読みづらいから整理して」と頼む場面。動きを変えずに中身だけ綺麗にする作業です。

こういう書き直しは、結果を確かめる段階が特に重要になります。整理した拍子に動きを壊していないか、テストで何度も確認するからです。ここで効くのが、テストを最初に渡しておくこと。次の落とし穴で触れます。

初心者が踏みやすい落とし穴

• 「1回答えて終わり」のチャットAIだと思って使う。Claude Code は自分で調べ・直し・確かめるループを回します。文章のアドバイスを期待して待っていると、実際にはファイルが書き換わっていて驚くことになります。ここが最大の違いです
• ツールなしで何でもできると思う。読む・書き換える・テストを動かす、はすべてツールを通した動作です。公式は5種類に整理しています。ファイル操作・検索・実行（コマンドやテストを動かす）・Web（検索やドキュメント取得）・コード解析（編集後の型エラー検出など）。道具がなければ文章応答に逆戻りします
• 変な方向に進んでも黙って待ってしまう。見当違いに気づいたら Esc で即停止できます。止めずに修正を打って Enter で送れば、今の動作が終わり次第それを読んで方向を直します。あなたもループの一部なので、遠慮なく操縦していい
• 最初の頼み方をふわっとさせる。曖昧でも動きますが、その分こちらが何度も方向を直すことになります。最初に対象ファイル・守ってほしい条件・お手本になる書き方を具体的に伝えると、往復が減って一発で当たりやすくなります
• 答え合わせの材料を渡さない。テストケースや「期待する出力はこれ」という指定、画面の見た目ならスクリーンショットを渡すと、Claude Code が自分で答え合わせできて精度が上がります。逆に何も渡さないと、合っているかの判断が甘くなりがちです
• 「考える頭」と「動く手」を混同する。判断しているのはモデル（Claude 本体）で、実際に動くのはツールです。Claude Code はその2つをつなぐ外枠の役。どこで何が起きているか分かると、うまくいかないときの切り分けが楽になります
• 頼みごとによってループの長さが変わるのを知らない。ただの質問なら材料集めだけで一瞬。バグ修正は何十もの動作をつないで長く回ります。「なかなか終わらない」のは、たいてい難しい修正をきちんと回している証拠です

書き方

（コマンドではなく動作原理。何かを打って起動するものではない。Claude Codeに頼みごとをすると自動で回り始める）

やってみるとこうなる

入力

ログイン後にすぐ401エラーになるバグを直して。認証まわりは auth.js と tokens.js を見て。

出力例

Claude Codeが自分で auth.js と tokens.js を読み（材料集め）→ トークン更新処理の不具合を見つけて書き換え（手を動かす）→ npm test を動かして直ったか確認（結果確認）→ 通らなければエラーを読んでまた調べ直す、という3段階を自律的に何度も回す。途中でEscを押せば即停止でき、修正を打ってEnterで送れば走行中でも方向を直せる

関連項目

• Context Window（コンテキストウィンドウ）
• /sub-agents（準備中）
• Explore → Plan → Implement（エクスプロア・プラン・インプリメント）
• Permission Modes（パーミッションモード）
• claude（クロード）

公式ドキュメント

https://code.claude.com/docs/en/how-claude-code-works