「チャットの AI にコードを書いてもらうのは慣れてきた。でも、ターミナルで動くコーディングエージェントを入れてみたら、勝手にファイルを読んで、テストを走らせて、何度も直している。中で何が起きているのか分からなくて、正直ちょっと怖い」。Claude Code や Codex CLI などを入れ始めた方から、こんな声をよく聞きます。
チャットの AI は、主に会話の中で渡された情報をもとに、文章で答えを返します。一方コーディングエージェントは、自分でファイルを探し、コマンドを実行し、その結果を見て次の手を決めます。便利さは段違いですが、仕組みを知らないまま任せると「どこまで任せてよいか」の判断ができません。
このブログの名前の由来になった古事記の久延毘古(くえびこ)は、世の中のことを何でも知っているのに、自分では歩けない神様でした。大規模言語モデル(LLM)もよく似ていて、知識は豊富でも、それだけではファイル一つ開けません。その LLM に「足」を与えるのが、今回から始まるシリーズ「AIに足を ― ハーネス実践」のテーマ、ハーネスです。本記事はシリーズ第 1 回として、コーディングエージェントの仕組みと、シリーズ全体で扱う部品の地図をお見せします!
コーディングエージェントとは
コーディングエージェントとは、LLM に「道具(ツール)」と「作業場所(環境)」を与え、目的を達成するまで自分で作業を繰り返させる仕組みです。ツールとは、ファイルの読み書き・検索・コマンドの実行など、AI が呼び出せる機能のことです。
チャットとの一番の違いは「ループ」にあります。エージェントは、考える → ツールを呼ぶ → 結果を読む、を何十回も繰り返します。たとえば「失敗しているテストを直して」と頼むと、テストを実行してエラーを読み、関係するファイルを探して読み、修正して、もう一度テストを走らせて確かめる、という流れを自分で組み立てます。Claude Code の公式ドキュメントも、この流れを「文脈を集める・行動する・結果を確かめる」の 3 つの段階が混ざり合うループとして説明しています(How Claude Code works)。
もう一つの違いは、AI が見ている範囲です。何を参照できるかは使う環境によって違いますが、通常のチャットでは会話に貼り付けたり添付したりした情報が中心です。一方エージェントは、許可された範囲で、リポジトリ全体やターミナル、Git の状態にまで手が届きます。だからこそ、何を見せて何を許すかを決める仕組みが必要になります。
動く場所にも 2 つの形があります。一つは、自分のパソコンのターミナルで動き、手元のファイルやコマンドを直接扱う形です。もう一つは、クラウド上の一時的な環境で動き、作業の結果をブランチやプルリクエストとして返す形です。前者は手元で様子を見ながら細かく指示しやすく、後者は自分のパソコンから切り離された場所で作業が進みます。どちらの形でも、中で回っているループの考え方は同じです。
ハーネスとは
ハーネスとは、モデルの外側にあって、ループの回し方・使えるツール・モデルに見せる情報(コンテキスト)・許可する操作(権限)を決める部分です。コンテキストとは、AI がその時点で読んでいる指示や会話、ファイルの中身などの情報全体を指します。Claude Code のドキュメントは、モデルの周りでツールを提供し、モデルが見るコンテキストを管理する層をハーネスと呼ぶ、と書いています(How Claude Code works)。
同じモデルでも、ハーネスが違えば成績が変わる、という研究の流れは エージェント・ハーネスの記事 で紹介しました。本シリーズはその実践編です。ここからは、ハーネスの全体像をつかむのに役立つ論文を 3 本紹介します。
📄 論文: AI のためのインターフェースを設計する
SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering(John Yang ほか、2024年5月、arXiv:2405.15793)は、査読前の論文(プレプリント)です。
この研究の出発点は、「人間が IDE(統合開発環境)のおかげで楽に開発できるように、AI にも AI 向けに作った道具があれば作業がはかどるはずだ」という考えです。研究チームは、ファイルの作成や編集、リポジトリ内の移動、テストの実行を AI がやりやすい形にした専用のインターフェースを作り、実在の GitHub の課題を解かせるベンチマーク SWE-bench で評価しました。その結果、1 回の試行で解けた割合は 12.5% で、当時の対話しない方式の最高記録を大きく上回りました。インターフェースの作り方が AI の振る舞いと成績を左右することも分析しています。
なお、その少し後には、AI に次の行動を決めさせず「場所を特定する → 直す → 確かめる」の固定の手順で解かせる方法が、SWE-bench Lite というベンチマークで、当時公開されていたオープンソースのエージェントより良い成績を低いコストで出した、という報告も出ています(arXiv:2407.01489、査読前の論文)。自由に動けるループが常に正解とは限らない、という対照として覚えておくと役立ちます。
現場にとっての意味は、AI の賢さだけでなく「AI に何をどう見せ、どんな道具を渡すか」で結果が変わるということです。これが、ハーネスを自分で整える価値の根っこです。
📄 論文: 11 の実装を解剖して見えた「7 つの部品」
Harness Engineering: Anatomy, Architecture, and Evolution of Coding Agents — A Source-Code Study of Eleven Systems(Paul Barbaste ほか、2026年7月、arXiv:2609.00006)は、査読前の論文(プレプリント)です。
この研究は、Claude Code・Codex CLI・Gemini CLI を含む 11 のコーディングエージェントのソースコードを読み比べ、ハーネスが共通して持つ部品を整理しました。本文では、エージェントのループ・LLM とのやり取り・ツールと操作・記憶とコンテキスト・安全と権限・複数エージェントの取りまとめ・拡張(フックやスキル、MCP など)の 7 つを基本の部品として挙げ、それぞれの最小の形と最大の形を比べています。抄録によると、繰り返し現れる設計パターンは 29 種類にのぼり、最後に設計上の提言と、最小限のハーネスのひな形も示しています。また、同じ実装を 3 か月ほど間をあけて比べたところ、エージェントの振る舞いの決まりが、指示の文章から設定へと移りつつあることも観察しています。
83 ページの大部なので、本シリーズでは部品の整理を借りて地図として使います。現場にとっての意味は、ツールが違っても「どの部品の話か」で考えれば、設定の在りかを探しやすくなるということです。
📄 論文: ループの型は組み合わせでできている
Inside the Scaffold: A Source-Code Taxonomy of Coding Agent Architectures(Benjamin Rombaut、2026年4月、arXiv:2604.03515)は、単著の査読前の論文(プレプリント)です。
この研究は、公開されている 13 のコーディングエージェントのソースコードを、特定の版に固定して分析しました。制御の仕方、ツールと環境とのつなぎ方、資源の管理という 3 つの層に分けて比べたところ、ループは「考えて行動する」「生成してテストして直す」「計画してから実行する」「やり直す」「木のように枝分かれして探す」の 5 つの基本の型の組み合わせでできていました。ほとんどの実装は、一つの型だけに頼らず、複数の型を重ねて使っていたそうです。また、ツールの種類や実行環境の隔離のように外部の制約が強い部分は各実装で似通う一方、コンテキストの圧縮のようにまだ答えが出ていない部分はばらばらだった、とまとめています。
現場にとっての意味は、エージェントの動き方は一つの決まった型ではなく、ツールごとに組み合わせが違うということです。「この道具はなぜこう動くのか」を理解する手がかりになります。
部品の地図:シリーズの各回で扱うこと
ここまでの整理をもとに、本シリーズで扱う部品を一覧にします。第 2 回からは毎週月曜と水曜に 1 本ずつ公開し、各回の冒頭で「地図のどこの話か」を示します。気になる部品の回から読んでいただいても大丈夫です!
| 部品 | 何を決めるか | 扱う回 |
|---|---|---|
| ループとツール | エージェントがどう動くか | 第 1 回(本記事) |
| 指示ファイル | 毎回伝えたい決まりや前提 | 第 2 回 指示ファイルの書き方 |
| 安全と権限 | 何を自動で許し、何を確認し、何を禁じるか | 第 3 回 権限モードとサンドボックス |
| 拡張(フック) | 決まりを仕組みで守らせる | 第 4 回 フック |
| 記憶とコンテキスト・取りまとめ | 長い作業での情報の整理と分担 | 第 5 回 コンテキスト管理とサブエージェント |
| ツールと拡張(MCP・スキル) | どんな道具をどう渡すか | 第 6 回 ツール・MCP・スキル |
| 無人での実行 | 人が見ていない場面での動かし方 | 第 7 回 CI でエージェントを動かす |
| 全体 | 部品の観点でツールを比べる | 第 8 回 コーディングエージェントの選び方 |
実践:エージェントを入れる前にやること
仕組みが分かったところで、導入の最初の一歩を整理します。いきなり本番のリポジトリで全部を任せるのではなく、段階を踏むと安心です。
- 作業用のリポジトリを分ける
最初は、壊れても困らない練習用のリポジトリか、本番の複製で試します。エージェントはファイルの編集やコマンドの実行まで行うので、作業の前後で Git に区切りを残し、いつでも元に戻せる状態にしておきます。 - まずは読み取りだけで試す
各ツールには、ファイルを変更させずに調べさせる方法や、調査と計画だけを先に頼む使い方があります。「このリポジトリの構成を説明して」「このバグの原因を探して」のような調査から始め、エージェントがどのファイルをどの順に読むのかを眺めてみましょう。ループの動きが目で見えるので、仕組みの理解が一気に進みます。 - 変更を任せる範囲を決める
慣れてきたら、作業フォルダの中の編集だけを任せ、外への書き込みやネットワークへのアクセスは確認を挟む、といった線を引きます。秘密情報の入ったファイルや、取り返しのつかない操作には最初から近づけないようにしておくと安心です。詳しくは第 3 回で扱います。 - ログを読み返す
どんなツールをいつ呼んだかを後から確かめ、思わぬ動きがないか見直します。違和感があれば、指示ファイル(第 2 回)や権限(第 3 回)で手当てします。
各ツールで、仕組みの説明と「変更させずに調べさせる方法」がどこにあるかを並べました。モードの細かな挙動は設定や版で変わるため、リンク先で確かめてください。
| 項目 | Claude Code | Codex CLI | Gemini CLI | GitHub Copilot |
|---|---|---|---|---|
| 仕組みの説明 | How Claude Code works | Codex CLI | Get started with Gemini CLI | About GitHub Copilot cloud agent(Copilot cloud agent、旧 coding agent) |
| 変更させずに調べさせる方法 | plan モード(ソースを編集せず調査と計画。調査のためのコマンドは実行される) | read-only のサンドボックスモード | Plan Mode | リサーチと計画を先に頼む使い方(変更を止める設定ではない) |
| 変更の境界 | 権限モード・Bash サンドボックス | サンドボックスと承認ポリシー | ポリシーエンジン・サンドボックス | 専用ブランチへの push と、人によるレビュー・マージ |
2026 年 10 月時点の各社公式ドキュメントに基づきます。仕様は変わるため、最新の公式ドキュメントを確認してください。
表の GitHub Copilot の列は、手元のターミナルではなく GitHub Actions を使った一時的な開発環境で動き、作業結果をブランチやプルリクエストとして返す Copilot cloud agent を扱っています。Copilot には IDE の中で手元のファイルを直接編集する agent mode という別の機能もあり、ターミナルで動くツールの中にも作業をクラウドに渡せるものがあります。同じ「エージェント」でも、どこで動くかによって境界の引き方が変わることを押さえておきましょう。
筆者の現場では:部品は「事故が起きた順」に増えた
筆者のチームは、日々のソフトウェア開発で Claude Code を使い、作業の多くをエージェントに任せています。本シリーズの部品の地図に、筆者のチームの設定を当てはめると次のようになります。
- 指示ファイル: リポジトリの CLAUDE.md に独自の決まりを書き、作業で学んだことは自動の記憶に 1 件 1 ファイルで残す(第 2 回)
- 権限: PR のマージと Issue の削除は、設定の禁止ルールでエージェントに実行させない(第 3 回)
- フック: GitHub への書き込みや push の直後に、実際の状態を取り直してエージェントに見せる(第 4 回)
- サブエージェント: 設計の方針を費用と速さの面から見る係・セキュリティの面から見る係・PR を見る係の 3 つのレビュー役を分け、どれも道具を読み取り中心に絞る(第 5 回・第 6 回)
- 無人での実行: 文章だけの PR は、GitHub Actions の機械のゲートが条件を確かめてマージする。AI 自身はマージしない(第 7 回)
ただし、これを最初から設計したわけではありません。ほとんどの部品は、実際に起きた失敗をきっかけに 1 つずつ足したものです。たとえばフックは、エージェントが外部への操作のあとに「うまくいきました」と報告したものの、実際の状態を確かめていなかった、という誤りを防ぐために入れました。
この経験から言えるのは、上の「ログを読み返す」が部品を足す入口になる、ということです。思わぬ動きを見つけたら、まず指示ファイルに一行書き、それでも繰り返すなら権限やフックなどの仕組みに移す。第 2 回以降の各回の終わりに、この流れで足してきた筆者のチームの実例を「筆者の現場では」として紹介します。
コーディングエージェントと付き合う鍵は次の3点です
- エージェントは「ループ」で動くと知る
考える → ツールを呼ぶ → 結果を読む、の繰り返しです。何をしているかは、呼んだツールの記録を見れば追えます。 - 成果はモデルだけでなくハーネスで決まる
研究でも、AI 向けのインターフェースの作り方で成績が変わることが示されています。見せる情報と渡す道具は、使う側が整えられる部分です。 - 読み取りから始めて、任せる範囲を広げる
練習用のリポジトリで、変更させない調査から試しましょう。境界を決めてから、少しずつ任せる範囲を広げるのが安全です。
まとめ:AIに「足」をつけて、一緒に歩き出そう!
コーディングエージェントは、チャットの AI にループ・ツール・作業環境という「足」を与えたものです。研究からは、AI 向けに道具を設計すると成績が上がること、そして各社のハーネスがループ・ツール・コンテキスト・権限・拡張といった共通の部品でできていることが見えてきました。
仕組みが分かれば、「どこまで任せるか」を自分で決められるようになります。まずは練習用のリポジトリで、エージェントに読み取りだけの調査を頼んで、ループが回る様子を眺めてみてください!
次回は、毎回同じ説明をしなくて済むようにする「指示ファイル」の書き方を扱います。シリーズの一覧は 本記事の「部品の地図」 へ。
参考文献
- Anthropic「How Claude Code works」(https://code.claude.com/docs/en/how-claude-code-works)2026-10-01 確認
- Anthropic「Choose a permission mode」(https://code.claude.com/docs/en/permission-modes)2026-10-01 確認
- Anthropic「Configure the sandboxed Bash tool」(https://code.claude.com/docs/en/sandboxing)2026-10-01 確認
- OpenAI「Codex CLI」(https://learn.chatgpt.com/docs/codex/cli)2026-10-01 確認
- OpenAI「Agent approvals & security」(https://learn.chatgpt.com/docs/agent-approvals-security)2026-10-01 確認
- Google「Get started with Gemini CLI」(https://geminicli.com/docs/get-started/)2026-10-01 確認
- Google「Plan Mode」(https://geminicli.com/docs/cli/plan-mode/)2026-10-01 確認
- Google「Policy engine」(https://geminicli.com/docs/reference/policy-engine/)2026-10-01 確認
- Google「Sandboxing in Gemini CLI」(https://geminicli.com/docs/cli/sandbox/)2026-10-01 確認
- GitHub「About GitHub Copilot cloud agent」(https://docs.github.com/en/copilot/concepts/agents/cloud-agent/about-cloud-agent)2026-10-01 確認
- GitHub「Research, plan, and iterate on code changes with Copilot cloud agent」(https://docs.github.com/en/copilot/how-tos/copilot-on-github/use-copilot-agents/research-plan-iterate)2026-10-01 確認
- GitHub「Risks and mitigations for GitHub Copilot cloud agent」(https://docs.github.com/en/copilot/concepts/security-governance-and-network-settings/risks-and-mitigations)2026-10-01 確認
- John Yang ほか「SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering」arXiv:2405.15793(https://arxiv.org/abs/2405.15793)2026-10-01 確認
- Chunqiu Steven Xia ほか「Agentless: Demystifying LLM-based Software Engineering Agents」arXiv:2407.01489(https://arxiv.org/abs/2407.01489)2026-10-01 確認
- Paul Barbaste ほか「Harness Engineering: Anatomy, Architecture, and Evolution of Coding Agents — A Source-Code Study of Eleven Systems」arXiv:2609.00006(https://arxiv.org/abs/2609.00006)2026-10-01 確認
- Benjamin Rombaut「Inside the Scaffold: A Source-Code Taxonomy of Coding Agent Architectures」arXiv:2604.03515(https://arxiv.org/abs/2604.03515)2026-10-01 確認

