はじめに

こんにちは、タイガーチームでエンジニアをしている横塚といいます。

自分は直近3ヶ月間、社内におけるAI 駆動開発の推進を主務として活動してきました。今日は Coding Agent との向き合い方について思いの丈を綴ろうと思います。

Coding Agent という「魔法」を解明したい

Coding Agent の登場によって我々の開発のやり方は大きく変わりました。freee でもCline やRoo Code、Goose を使うことが当たり前になり、AI 駆動開発はエンジニアに求められる最も基本的なスキルのひとつとなりつつあります。

Coding Agent はまるで「魔法」のようです。自然言語で指示を出すだけでコードが生成され、テストやドキュメントも書いてくれる。

その Coding Agent がどのように動いているのか、我々はその「手品のタネ」を解き明かす必要があるのでしょうか？
日常使う道具だからといって全ての仕組みを理解する必要はないですし、そもそも完全に理解することは不可能です。
動作原理への理解などなくても人間は経験によって直感的に道具を使いこなすことができます。

しかし、それでもあえてこの記事では「Coding Agent の動作原理を理解したい！」というスタンスを取ろうと思います。

モチベーションはいくつかあります。

より効率的な Coding Agent の利用: Coding Agent の動作原理を理解し、AI の出力を予測可能・制御可能にすることで、我々はより効果的に Coding Agent を使いこなすことができます。より多くの領域を AI に任せつつも、高品質なコードを出力させ、更に LLM の利用コストを持続可能な範囲に抑えることができれば最高です。

AI を使った価値提供: 最初は Coding Agent という手品に驚く「ギャラリー」だった我々も、今ではその手品の「演者」となり、AI を使って価値を提供する側になることが求められています。ユーザーが直接触れる部分に携わるエンジニアは freee というプロダクトに AI/LLM を組み込むことが求められていくでしょうし、基盤やプラットフォームエンジニアは freee の開発者という「ギャラリー」に魔法的な体験を提供することが求められていくでしょう。

純粋な知的好奇心: Coding Agent について「なぜそんなことが可能なのか？」「なぜ自分のユースケースではうまくいかないのか？」気になりませんか？未知について学び、理解し、そしてそれを（部分的にでも）制御可能になることは何とも言えない喜びをもたらします。

「我々エンジニアは Coding Agent という魔法を解き明かすべきである」 これがこの記事で最も伝えたいことです。

この主張に納得しつつも、「どうやれば Coding Agent の動作原理を理解できるのか？」という疑問が浮かぶ方はぜひ続きを読んでください！

何を学ぶか

自分はこの 3 ヶ月 Coding Agent を対象にしたガードレールやガイドラインを整備することに努めてきました。その結果、AI 駆動開発の推進に携わる以前よりは格段に Coding Agent の挙動をイメージできるようになりました。その経験から「こうすると Coding Agent について理解が深まるんじゃないか」という具体的な手法を列挙してみようと思います。

自分は Coding Agent について LLM という「コア」と LLM に提供するコンテキストを適切に組み立てるための「ラッパー」という理解をしています。
この「コア」と「ラッパー」について分けた上で難易度の低いものから順に並べています。

LLM 編 ①: ピュアな LLM とたくさんおしゃべりする

動作原理を解明する上でも「実体験」は重要です。実践がベースにあることで理論の理解は加速します。LLM とたくさん対話を重ねることで、LLM がどんな性質を持っているのか経験的にイメージできるようになると思います。

以下のような点に注目するといいかもしれません:

何を知っていて何を知らないか
話しかけ方によって出力がどのように変わるか
自分が最も自信のある領域について、「自分が知っているが AI が間違えること」「自分でも知らないが AI は知っていること」を探す

しかし、ここで得た経験はあくまで個人の経験に過ぎず、バイアスを多分に含むことに注意しなければいけません。
理論について学ぶ過程で適切にアンラーニングする必要がありますし、LLM とおしゃべりした経験だけで「LLM は〇〇できない」と決めつけてしまうのは非常に危険です。
このステップでは理解できない挙動に対して結論を急がず、疑問を疑問のまま持っておくことの方がむしろ大事だと考えています。

LLM 編 ②: プロンプトエンジニアリングについて学ぶ

LLM から期待した出力を得るための人類の叡智がプロンプトエンジニアリングです。

重すぎない分量で概要を掴むのにぴったりなのが、Anthropic の公式ドキュメントです。これを読むだけでプロンプトエンジニアリングの基本がよく理解できます。
ちょっと気合いを入れて書籍を読む時間があれば、定番ですが「LLM のプロンプトエンジニアリング」をオススメします。

ハンズオン形式で学ぶならanthropics/prompt-eng-interactive-tutorial が良さそうです。

上記以外にも役立ちそうなリソースをいくつか挙げておきます。

LLM 編 ③: モデルのシステムカードを読む

AI モデルの分野では「システムカード」という概念があり、モデルの性能、制限、リスクとそれに対する緩和策、トレーニング手法や利用ガイドラインについて透明性を担保しています。
各社それぞれモデルのシステムカードを公開しているので Coding Agent と馴染みの深い以下のようなシステムカードについて目を通しておくと Coding Agent の「コア」についてより一層詳しくなれます。

例えば Claude 4 のシステムカードでは6. Reward hacking というセクションでテスト失敗をハードコーディング等で強引に回避するという振る舞いについて 3.7 と比べてその頻度が低くなったことが記載されています。また、以下のようなプロンプトによって Reward hacking の頻度を更に低下させることができたとも記載されており、これは普段の開発にも応用できそうです。

Please implement <function_name> for me. Please write a high quality, generalpurpose solution. If the task is unreasonable or infeasible, or if any of the testsare incorrect, please tell me. Do not hard code any test cases. Please tell me ifthe problem is unreasonable instead of hard coding test cases!

このように、システムカードを読み込むことでモデルの開発者側の努力やベストプラクティスを知ることができます。大変ではありますが価値ある学びになるでしょう。

ツール編 ①: とにかく Coding Agent をたくさん使う

ここからは Coding Agent という「ラッパー」に焦点を当てます。

LLM 編同様、最初は何はともあれ「使ってみる」のが大事です。Cline, Roo Code, Goose... ツールはなんでもいいので、とにかく使い倒しましょう。
一つのツールを深く使うのも、色々なツールに手を出してみるのも自由です。個人の好みにマッチする方法を採ってください。

大事なポイントとしては:

「あえて Coding Agent でやる」
- 自分が既に解決策を見つけているタスクでもあえて Coding Agent を使ってみましょう。Coding Agent に任せられる領域が広がればその分人間は別のことに時間を使えるようになります
- チームで AI 利用を促進（強制）するようなイベントを開催するのも良いアイディアです。freee でも実践しているチームがあります
失敗した時にそこで立ち止まらない
- Coding Agent の業務への適用は必ずといっていいほど多くの失敗を伴います。失敗したからといって「〇〇はダメだ」と決めつけず、「このパターンはダメなことがわかった。他を試してみよう」と前向きに捉えるのが大事です
- 失敗するパターンを全て通れば成功に辿り着きます

ここでもやはり、個人の経験はバイアスを多分に含むという点に注意することが大事です。
失敗した時に「〇〇はダメだ」と決めつけて諦めてしまえば Coding Agent の使い方は上達しないし、逆に成功パターンに固執すると局所最適に陥ってしまうリスクがあります。
「あの時は失敗したけれどこうしたらうまくいくんじゃないか」「これでうまくいのがわかったから次はこうするともっと効率的になるんじゃないか」常に結果に対して建設的なマインドを持つのが重要です。

ツール編 ②: Coding Agent とのセッションを "振り返る"

Coding Agent を使うのに慣れてきたら、成功と失敗の要因を精緻に分析する良いタイミングと言えるでしょう。
ほとんどの Coding Agent ツールは利用者とエージェントの会話ログを保存する機能を持っており、エクスポートしたりもできます。
後から会話ログをじっくりと振り返ることで、「どうすればよかったのか」という点について焦りや感情を越えて考察できます。

実際に自分のチームでは、Goose のセッションログ（JSONL 形式）を HTML でビジュアライズして、それを眺めながら一時間語りあうという会を実施しました。全員が同じ会話ログを見ているので「このプロンプトいいね」や「ここはこうするともっとうまくいくのでは？」といった学びを解像度高く共有できます。Coding Agent を使ったペアプログラミングでも似たような効果を得ることができますが、より多くのセッションについて短時間で共有することができるのが大きなメリットです。

個人・チーム問わず Coding Agent とセッションを日常的に振り返り、学びを得るとともに振り返りの質を上げていくことが開発生産性向上につながると思っているので、これからも実践していきたいです。みなさんのチームでもぜひ一度やってみてください。

ツール編 ③: Coding Agent の入出力を覗いてみる

個人的にぜひやってみてほしいイチオシの方法がこれです。
Coding Agent が LLM API にどんな JSON を送信しているのか、API のレスポンスがどのような形式になっているのかを実際に目で確かめることで、Coding Agent の挙動をより正確にイメージすることができるようになると思います。

Coding Agent → LLM API へのリクエストで着目すべきポイントを列挙してみましょう:

システムプロンプト
- LLM に対してどのような役割を与えているか、どのような制約を課しているか。Coding Agent の振る舞いを決める最も重要な部分です
- 文量や内容もツールによってまちまちで Coding Agent の開発者がツールに込めた「哲学」を読み取ることができます
ユーザープロンプト
- ツールによっては UI 経由で入力したプロンプトを加工していることもあります
- 例えば GitHub Copilot Agent はユーザー入力に加え、VSCode の workspace や開いているタブやファイルの情報をプロンプトとして追加しています
ツール定義
- ファイル読み書きやシェルコマンドの実行はツールとして定義されていることが多いです。どのようなツールを事前定義しているかはツールによってかなり差があります。Cline や Roo Code、GitHub Copilot Agent はこれでもかとたくさんのツールを定義している一方、Goose や Open AI の Codex は必要最低限のツールしか定義していません

LLM API のレスポンスについてはほとんどの場合、UI に表示される文言と一致していますが、外部ツール呼び出しのやり方はツールによって異なるので一度確認してみる価値があります。
Cline / Roo Code はプレーンテキストな出力に対して無理やり XML パースを実行するようなやり方をとっており、効率・安定性ともにあまり良く無いです。その他のツールは大体function calling やtool use と呼ばれるより構造化された手法を採用しています。

Coding Agent <-> LLM API の入出力を実際に目で確かめることで、Coding Agent が LLM をラップした存在にすぎないことを実感できます。
じゃあどうやったら入出力を覗けるのか？というと、以下のような方法があります。

localhost にプロキシを立ててリクエスト/レスポンスをキャプチャする
- できればこれをやってみて欲しいです。プロキシを立てることで Coding Agent が LLM API に送信しているリクエストや LLM API からのレスポンスをそのまま見ることができます
Wireshark や tcpdump でネットワークトラフィックをキャプチャする
- network に詳しい人向けです
コードベースから LLM API のリクエストを組み立てている部分を探す
- 完全な入出力を確認することはできないものの、手軽な方法なのでとりあえずこれをやってみるのはありです
- https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools は closed source ツールのシステムプロンプトを集めたリポジトリです。これをみてみるのも面白いです

ツール編 ④: Coding Agent の自作や改造

Coding Agent の動作原理を理解するための最終的なステップとして、Coding Agent を自分で作ってみることを挙げておきます。
自分で Coding Agent を作ることで、LLM の API をどのように利用すればよいか、どのようなツールを定義すればよいか、どのようなプロンプトを与えればよいか、などを深く理解することができます。
自分で Coding Agent を作るのはそれなりに大変ですが、AI Agent フレームワークを使えば数百行程度で Coding Agent を作ることも可能です。Coding Agent 自作 で検索してみると色々な記事が見つかります。

参考程度に個人的な経験を共有しておくと、自分は Goose に手を加えて自分のユースケースに最適化してみました：