こんにちは！ひさふるです。
最近、登壇で度々使っていた、AIコーディングエージェント性能の決定要因をまとめたスライドに対してご好評いただくことが多かったため、今回はそれを記事にしてみました。
普段何気なく使っているコーディングエージェントですが、その中身を理解することで、更に効果的に使えるようになってみませんか？
AIコーディングエージェントとは？
厳密な定義は無いかもしれませんが、私は"ユーザーの指示をもとに、AIがプログラミング/コーディングを自律的に行ってくれるツールやプロダクト"のことを指しています。
例えば、GitHub CopilotやCursorなどが該当すると思います(正確には、エージェントはその中の一機能ですが)。
今回の記事では、その中でも特にClaude CodeやGemini CLIなどのCLIベースのコーディングエージェントを前提として話を進めようと思います。
これらのCLIベースのツールは今年になって急速に台頭してきたもので、CLIツールならではの拡張性が魅力です。
また、それぞれAnthropicやGoogleといったモデルプロバイダから直接提供されているツールとあって、比較的レートリミットや料金を気にせず使える傾向にあるのも強みです。
今回は、これらのツールがどのようにして振る舞いを決定しているのか、詳しく説明していきます。
AIエージェント性能の決定要因と入力のコツ
AIエージェントの性能の決定要因を図にまとめたものがコチラです。
正直今回の説明内容はこれが全てなので、図を見て理解できる方はこれ以降読まなくても大丈夫です。
① ツール内のプロンプト
ツール内には、それぞれ単なるLLMを"コーディングエージェント"として動作させるためのプロンプトが記述されています。
例えば、AIに数学の問題を解かせるときは「あなたは優秀な数学者です。ユーザーから与えられる数学の問題に対して、適切な解答と解法の説明を答えてください。」のようなプロンプトを与えると思います。
同様に、コーディングエージェント内でも「あなたは優秀なプログラマです。ユーザーから与えられるタスクを達成できるように、プログラムの実装計画を立て、コードの実装を行ってください。」のようなプロンプトが与えられていることでしょう。(実際には、こんなお粗末なプロンプトではなく、もっとしっかりしたものが書かれていますが...)
参考：Gemini CLIのツール内プロンプト
Gemini CLIはオープンソースなため内部のコードが確認でき、以下のようにプロンプト自体も確認することができます。書き出しは以下の通り。
You are an interactive CLI agent specializing in software engineering tasks. Your primary goal is to help users safely and efficiently, adhering strictly to the following instructions and utilizing your available tools. (DeepLでの翻訳：あなたはソフトウェア工学タスクに特化したインタラクティブなCLIエージェントです。あなたの主な目標は、ユーザーが安全かつ効率的に作業できるよう支援することです。以下の指示を厳格に遵守し、利用可能なツールを最大限活用してください。)
最初にAIに対し具体的な役割を与えるというセオリーはしっかりと守られているようです。
このプロンプトはツールの最も基本的な振る舞いを決定します。
例えば、エージェントがどのように実装計画を立て、どのようにツールを選択・使用するかなどはこのプロンプトに大きく左右されることでしょう。
みなさんが普段ツールを使っていて感じる"性格の違い"はここに起因するものです。
性能には大きく影響を与える一方で、基本的に私達はここを修正することはできません。
今後ツールのアップデートで改善される可能性はあるので、気長に待ちましょう。
ツール内プロンプトは最も基本的な性能の決定要因の1つ！
② メモリ機能のプロンプト
ここから3つはユーザーが変更可能かつ、非常に重要な性能の決定要因です。
1つ目はメモリ機能のプロンプトです。
Claude CodeにはCLAUDE.md、Gemini CLIはGemini.mdという形式で、セッション間共通のコンテキスト情報を保存する機能があります。
前提として、これらのAIツールはそのセッション(=会話)で与えた情報しか覚えておらず、一旦ツールを終了して再起動すると全て忘れてしまいます。
それを部分的に防止するため、ツールの起動時に必ず読み込まれるプロンプトがCLAUDE.mdやGemini.mdというわけです。
これらは全てのセッション間で共通して読み込まれるため、全ての指示に共通する、プロジェクト全体の実装方針などに関わるルール等を記述すべきです。
例1) テスト方針："このプロジェクトではTDD(テスト駆動開発)を行っているので、実装時は最初にテストを記述し、最後はテストが通ることを確認してタスクを終了して欲しい"
例2) 実装方針：実装後は必ずリファクタリングを行い、不要な宣言の削除を行うこと。また、重複する宣言や可読性が低い部分に関しては、適宜コンポーネントに分割すること。
例3) フォルダ構成："以下に、このプロジェクトのフォルダ構成を示す。 ... "
このメモリ機能は、プロジェクト全体での整合性を取る上で非常に重要です。
適切に設定しないと、同じコンポーネントを複数宣言されてしまったり、意図を汲まない実装が多くなってしまいます。
プロジェクト内の整合性を取るうえでメモリ機能は最も大切！
③ 参照するファイル
AIコーディングエージェントは、一般的に編集の対象や参考資料となるファイルを指定して渡すことができます。
この機能を利用して、関連するファイルは明示的に渡してあげることが大切です。
ツールによっては自分で関連するファイルを検索して勝手に読み込んでくれることもありますが、絶対にそれをしてくれるとは限りません。
例えば、既にボタンコンポーネントは別ファイルとして定義してあったのに、それを無視して新しく定義されてしまう、なんてこともあるかもしれません。
"メモリ機能のプロンプト"と合わせて、関連するファイルを全て明示的に渡して上げることが、"理路整然としたコード"を生み出す近道です。
余談：AIの進化とツールの進化
"関連するファイルをできるだけ明示的に与えよう"というのは、あくまで現時点での素のコーディングエージェントを使う場合のコツに過ぎません。LLMの進化のスピードは凄まじく、今後登場するモデルよっては毎回全てのファイルを読み込む、なんてことも可能になるかもしれません。(一応、ファイル数によっては今でも可能ではありますが)
そうなれば今よりも大雑把な指示で、正確なタスク実行が可能になるかもしれないでしょう。
また、最近はコーディングエージェントのサポートツールとして、SERENAというオープンソースツールも登場しています。
https://github.com/oraios/serena
これは、セマンティック(意味的)なコード解析を行いその結果を保持しておくことで、エージェントが素早く関連するコードを検索できるようになるというものです。
このように、AI自体の性能の向上とAIに合わせたツールの拡張という両面の進化により、数ヶ月後には今回ご紹介するノウハウも不要になっているかもしれません。
関連するファイルは明示的に与えよう！
④ ユーザー入力のプロンプト
ユーザーがコントロールできる入力情報3つのうち、最後の1つがユーザー入力のプロンプトです。
文字通り、コーディングに関する指示のことですね。
ここは、とにかく解釈の余地を与えないプロンプトにすることがコツです。
どのファイルに対してどのような修正を施したいのか、要望をできるだけ言語化できる方が良いでしょう。
とはいえ、適当な指示でも意図を汲んでくれることも多いので、私は雑に指示を投げてしまうことも多いですが笑
"解釈の余地を与えない"指示を出そう！
⑤ 前回までの出力
多くのAIコーディングエージェントはチャット形式での指示が可能です。
そのため、2回目以降の指示では、前回までの実行の記録(会話やコード修正、使用したツールなど諸々の履歴)も情報として読み込まれます。
会話が長くなればなるほど読み込まれる余計な情報が多くなるため、一般的には会話が長いと精度が落ちる傾向にあると言われています。
その場合は、(Claude Codeの例では)例えば/compactコマンドを使って会話履歴をサマライズし圧縮したり、/clearコマンドで会話履歴自体を削除すると、生成されるコードの質も良くなるでしょう。
個人的には、数回会話を続けたらすぐに/compactか/clearをするよう習慣づけています。
/clearや/compactコマンドで会話履歴のリセットを忘れずに！
⑥ LLMの性能
最後に、① ~ ⑤をLLMに入力します。
LLMの性能もAIコーディングエージェント性能の決定要因としては大きな影響を持ちますが、私達には直接改善できるところではありません。
無理のない範囲でお金を出して、より良いモデルを使いましょう。
AIコーディングエージェント比較の難しさ
ここまでご紹介した通り、AIコーディングエージェントの出力は様々な要因が作用して決定します。
特に、LLMの性能やツール内のプロンプトはツールとしての性能を決定する上で大きく影響しており、各ツールの性格に色濃く反映されています。
一方で、ツールの振る舞いを決定しているのは良くも悪くもほぼプロンプトです。
ユーザーの入力1つや与えるファイル1つで出力が大きく改善されることもあります。
そのため、AIコーディングエージェントの定量的な比較自体はほぼ不可能です。
今後は、私達で感覚知を共有し、ITコミュニティ全体で最適解を模索し続けることこそが重要となります。
ユーザー入力の情報と技術負債
今回ご紹介した中で、②~④は全てユーザーが決定権を握っています。
ここを上手く使うことで出力を劇的に改善できる可能性を秘めている一方で、使い方がテキトーだとどんどん見えない技術負債が溜まってしまいます。
特に、最近流行りのVibeコーディングはプロジェクトの立ち上がりには非常に強力に作用するものの、全てAIに任せていると支離滅裂な構成になりかねません。
これは、上述の通りAIがコンテキスト情報を保持できていないことが原因で、過去の変更や修正の意図を忘れたまま新しい実装を行うため、実装意図が一貫しないファイルが複数生成されることに起因します。
Vibeコーディングはあえてレビューにかかるコストを減らすことも多いため、AI生成によって発生している見えない技術負債(=Vibe負債)が開発者の把握しないまま蓄積されてしまい、プロジェクトが成熟しかけたところで爆発するといった事象はよく報告されています。
これを防止するために大切なのは、以下の2点です。
- AIの出力に責任を持つ
- AIの出力に対して定期的にレビューを行い、AIに実装を丸投げしない。
- どのような変更が行われ、現在のプロジェクトがどうなっているのかを把握しておくこと。
- 開発者の把握していない変更は支離滅裂なコードをの生成を許すだけでなく、致命的なセキュリティ上の欠点を生む原因となる。
- コンテキスト情報を適切に管理する
- セッションをまたいで伝えるべき情報は、コンテキスト情報として適切に管理し毎回AIに伝えれるようにする。
- AIは会話ごとに今までの情報を全て忘れるため、重要な事項は文書化しておき毎回与えることが重要。
AIはあくまで優秀な外部委託先であり、コーディングの代行はしてくれるものの言語化されていないルールは汲み取ってくれません。
AIと上手く付き合うコツは全て文書として書き記すことです。
これを意識して、快適なAIコーディングライフを送りましょう！
おわりに
今回は、自分なりに整理したAIコーディングエージェントの仕組みをご紹介しました。
1つ1つはどこかで聞いたことがある/知っているような話だったと思いますが、個人的にはこうして図としてまとめることで一歩理解が深まった気がします。
とはいえ、これは現時点での知識で、今回ご紹介したノウハウ等も半年後には廃れている可能性も大いにあると思っています。
今後も、AIを中心にIT技術に関する知見を発信しようと思いますので、良ければ次の記事も読んでいただけますと幸いです。