第1章　「おしゃべり」と「手を動かす」はどう違う？ — エージェントの正体

📖 この章のゴール：Claude Code のような「考えて手を動かすAI」が、3つの部品（頭脳・道具・ループ）でできていることが分かる。とくに 「AIは考えるだけで、実際に動くのはあなたのコード」 が腹落ちする。 ← 目次・はじめにへもどる

📱 Claude Code ではこう見える

ターミナルで Claude Code（や Cursor、Codex）に「このテスト、落ちてるから直して」と頼むと、こんな動きをします。

「まず原因を調べます」と言って、勝手に関係するファイルを開いて読む
「ここが原因のようです」と直す場所を見つけて、コードを書き換える
「テストを走らせて確認します。npm test を実行していいですか？」と確認してくる
あなたが許可するとコマンドを走らせ、結果（成功／失敗）を読む
まだ失敗していたら、もう一度直して、また走らせる——直るまでくり返す
直ったら「直りました」と報告して止まる

ふつうのチャットAI（ChatGPT）は、文章で答えるだけでした。でも Claude Code は 実際にファイルをいじり、コマンドを走らせます。この差はどこから来るのでしょう？ここが分かると、これから作るものが「魔法」ではなく「部品の組み合わせ」に見えてきます。

🤔 「おしゃべり」と「手を動かす」のあいだにある壁（🟢 基礎）

まず、いちばん大事なことを。

LLM（AIの頭脳）は、文章を作ることしかできません。 ファイルを開くことも、コマンドを走らせることも、ネットを見ることも——自分では一切できないのです。

意外でしょうか。でも本当です。LLMができるのは「次にどんな言葉が来るか」を考えることだけ。手も足も無い、口だけの天才だと思ってください。

🍳 前作のたとえ話の続き：ChatGPTクローンでは、LLMを「電話の向こうの天才シェフ」にたとえました。料理（文章）はとびきり上手。でもシェフはあなたの厨房（パソコン）にはいません。だから自分でコンロをひねったり、冷蔵庫を開けたりはできない。できるのは、電話越しに「そこの鍋に水を入れて、火にかけて」と指示することだけです。

では、Claude Code はどうやってファイルをいじっているのか。答えはこうです。

シェフ（LLM）の指示を受けて、実際に厨房で手を動かす「見習い」がいる。 その見習いこそ、あなたが書くプログラムです。

つまり、こういう往復が起きています。

シェフ（LLM）：「test.js というファイルを読ませて」
見習い（あなたのコード）：実際にファイルを読んで、中身を渡す
シェフ：「中身を見た。3行目の = を == に直して」
見習い：実際に書き換える
シェフ：「npm test を走らせて、結果を教えて」
見習い：（人間に確認してから）コマンドを実行し、結果を渡す
シェフ：「成功した。おわり」

この 「指示 → 実行 → 結果を報告 → また指示…」の往復こそが、エージェントの心臓です。

🧩 エージェントは3つの部品でできている（🟢 基礎）

整理すると、Claude Code のようなエージェントは、たった3つの部品でできています。

部品	役割	たとえ
🧠 頭脳（LLM）	何をすべきか考える。でも自分では動けない	電話の向こうの天才シェフ
🔧 道具（ツール）	ファイルを読む・書く・コマンドを走らせる、実際の手	厨房の鍋・包丁・コンロ
🔁 ループ	「考える→道具を使う→結果を見て、また考える」をくり返す	シェフと見習いのやりとり

そして、この3つを動かすあなたのプログラムが「見習い（エージェント本体）」です。見習いの仕事は地味で、こんな感じ。

あなた：「このテスト直して」
   │
   ▼
┌──────────────────────────────────────────┐
│  エージェント本体（あなたのプログラム＝見習い）   │
│                                          │
│   ① 頭脳(LLM)に「どうする？」と聞く            │
│         ▲                  │              │
│         │ 結果を報告         │ 「この道具を使え」 │
│         │                  ▼              │
│   ② 言われた道具を実際に実行する               │
│      （ファイルを読む／書く／コマンド）          │
│         │                                │
│         └──── ③ ①へ戻る（まだ終わってなければ）  │
│                                          │
│   ④ 頭脳が「おわり」と言ったら、結果を表示して止まる │
└──────────────────────────────────────────┘

ポイントは、賢い部分（考える）は頭脳に、地味な部分（実際に動く）はあなたのコードに、ときれいに分かれていること。あなたが作るのは、この②と③（道具を実行して、結果を頭脳に戻す係）です。

💡 ここが第1の背骨 🔁 です。AIは考えるだけ。動くのはあなたのコード。 だからこそ「AIに何を“させられる”か」は、あなたがどんな道具を渡すかで決まります。道具を渡さなければ、ただのおしゃべりAIのまま。ファイルを読む道具を渡せば、ファイルを読めるAIになる。エージェントの能力は、あなたが設計するのです。

🧠 性格と視野：システムプロンプトとコンテキスト（🟢 基礎）

3つの部品（頭脳・道具・ループ）に加えて、エージェントの“賢さ”を地味に大きく左右するものが2つあります。いまは「名前と、なぜ大事か」だけ分かればOKです。

システムプロンプト＝頭脳に最初に渡しておく「性格・規範・やり方」の指示。たとえば「あなたは慎重なエンジニア。勝手にファイルを消さない。まず計画を述べてから動く」のように書きます。同じLLM・同じ道具でも、ここ次第で賢くも危なくもなります。Claude Code の CLAUDE.md がまさにこれ（くわしくは第10章）。
コンテキスト＝作業中に頭脳が一度に見ている情報のかたまり（これまでのやりとり・読んだファイルの中身・道具の結果）。LLMは毎回これを丸ごと読み直して考えるので、何を入れて何を入れないかで答えが変わります。しかも一度に見られる量には上限があり、長い作業では膨らみすぎます。その問題と対策は第14章で（前作ChatGPTクローンの「記憶」と地続きの話です）。

🍱 たとえ：道具とループが「体」なら、システムプロンプト＝しつけ（育ち）、コンテキスト＝いま見えている視野。体が同じでも、しつけと視野しだいで仕事の出来はまるで変わります。だから本書では、道具やループを作りながら、要所でこの2つにもさらっと触れていきます。

🛡 もうひとつの主役：「危なさ」（🟢 基礎）

道具を渡すと、AIは急にいろんなことができるようになります。でも「できる」は「安全」とは別の話です。

ファイルを書く道具 → 大事なファイルを上書きしてしまうかも
コマンドを走らせる道具 → rm -rf（全消し）のような取り返しのつかない操作をするかも
ネットを見る道具 → 読んだページに「これまでの指示を無視して…」と罠が仕込まれているかも

だから Claude Code は、危ない操作の前で必ず止まって「実行していい？」と聞いてきます。これが第2の背骨 🛡 です。

🔑 覚えておく合言葉：「便利さと危なさは、いつもセット」。強い道具ほど、人間の確認（かくにん）と、取り消せる仕組みが要ります。この教材では、道具を1つ足すたびに「これ、暴走したら何が起きる？」を必ず考えます。

第8章〜第9章で、この「許可」「最小権限」「取り消せる設計」をしっかり作ります。いまは 「手を持たせるほど、安全の設計が大事になる」 とだけ覚えてください。

🛠 これから何を作る？（🟢 基礎）

この教材で作るのは、ターミナルで動く、小さなコーディングエージェント——いわば「Claude Code のミニ版」です。

あなたが作る（見習い＝エージェント本体）        借りて使う
┌─────────────────────────┐         ┌──────────────┐
│  CLIエージェント (TypeScript)  │────────▶│  LLM の API     │（Anthropic / OpenAI）
│                          │◀────────│  考える頭脳     │
│  ・あなたの入力を受け取る       │         └──────────────┘
│  ・頭脳に相談する            │
│  ・言われた道具を実行する       │  ← ここがこの教材の主役
│  ・危ない操作は確認をはさむ     │
│  ・結果を表示する            │
└──────────┬──────────────┘
           │ 道具で操作する
           ▼
   あなたのパソコンの中
   （ファイル・コマンドなど）

頭脳（LLM）：自分では作りません。Anthropic（Claude）の API に「どうする？」と相談するだけ。
道具：ファイルを読む・書く・コマンドを走らせる、を自分で作ります（第5〜7章）。
ループと安全：考える↔動くの往復（第4章）と、許可・確認（第8章）が、エージェント本体の中身です。

💡 前作（ChatGPTクローン）では ブラウザ画面・データベース・ログイン を作りました。今回はそれらは全部なし。エージェントは自分のパソコンの中だけで動かすので、構成はぐっとシンプルです。そのぶん、「考えて手を動かすループ」という新しい1点に集中できます。

⚠️ ハマりどころ

「AIが自分でファイルを触っている」と思い込む → ちがいます。AIは「このファイルを読んで」と言っているだけ。実際に読むのはあなたのコードです。ここを誤解すると、第3章以降の「道具を作る」話がピンと来ません。
「エージェント＝特別なすごいAI」だと思う → 頭脳は ChatGPT と同じLLMです。違いは 「道具をループで使わせているか」だけ。同じLLMでも、道具を渡せばエージェントに、渡さなければただのチャットになります。
「強い道具を渡せば渡すほど良い」と思う → 逆です。渡した道具のぶんだけ、暴走したときの被害も増えます。必要な道具を、必要なだけ、確認をはさんで渡すのが正解（背骨②）。
「1回で終わる」と思う → エージェントは何度も往復します（読む→直す→走らせる→まだ失敗→直す…）。1往復で終わらないのが、チャットとの大きな違いです。

🤖 AIに頼むなら（Vibe codingのコツ）

おもしろいことに、AIエージェントは、AIエージェント（Claude Code など）に手伝ってもらって作れます。ただし「エージェント作って」とだけ頼むと、安全の確認をすっ飛ばした危ないループが出てくることがあります。3つの部品を意識して頼むと、安全なコードに誘導でき、出てきたものも読めるようになります。

🗣 プロンプト例：「TypeScript で動く、ターミナルのAIエージェントを作りたい。まず全体像だけ教えて。①LLMに相談する → ②LLMが指示した道具を実行する → ③結果をLLMに返す → ④終わりと言われるまでくり返す、というループの骨組みを、関数の名前とコメントだけで（中身は空でいい）書いて。コマンド実行のような危ない道具には、人間の確認をはさむ場所もコメントで示して。」

出てきた骨組みを見るときの確認ポイント：

「考える(LLM)」と「実行する(道具)」が、別の関数に分かれているか？
ループになっていて、「終わり」の合図で止まる作りか？（無限ループしないか）
危ない道具の前に、人間の確認をはさむ場所が用意されているか？
道具を実際に動かすのはあなたのコード側で、LLMは“指示するだけ”になっているか？

📝 ことばメモ

エージェント：LLM（頭脳）に道具を持たせ、「考える→使う→また考える」のループで、自分でタスクを進めるAIの仕組み
LLM（えるえるえむ）：大規模言語モデル。文章を考えるAIの頭脳。Claude（Anthropic）・GPT（OpenAI）など。自分では手を動かせない
ツール（道具）：LLMに渡す「使える道具」＝あなたが用意した関数。ファイルを読む・書く・コマンドを走らせる、などをLLMの代わりに実行する
ループ：「LLMに相談→道具を実行→結果を戻す」をくり返す往復。エージェントの心臓
システムプロンプト：頭脳に最初に渡す「性格・規範・やり方」の指示。同じLLMでもこれ次第で出来が変わる。Claude Code の CLAUDE.md がこれ（第10章）
コンテキスト：作業中にAIが一度に見ている情報のかたまり（やりとり・読んだファイル・道具の結果）。一度に見られる量に上限があり、膨らみすぎ対策は第14章
スキル：よく使う手順（道具の組み合わせ・段取り）を“型”にまとめたもの。第11章で作ります
CLI（しーえるあい）：ターミナル（黒い画面）で文字で操作するアプリの形。今回作るのはこれ
human-in-the-loop（ひゅーまん・いん・ざ・るーぷ）：自動の流れの途中に人間の確認をはさむこと。危ない操作の安全弁（第8章）

➡️ 次の章へ

エージェントの全体像（頭脳・道具・ループ）がつかめました。次の第2章では、いちばん土台になる 「LLMと往復するだけの最小のCLI」 を実際に作ります（道具はまだ無し）。あわせて、前作でも学んだ 秘密のAPIキーの隠し方 も復習します——ここがエージェントの“出発点”です。

← 目次・はじめにへもどる

第1章 「おしゃべり」と「手を動かす」はどう違う？ — エージェントの正体