AIエージェントのススメ 第4回 コンテキスト圧縮でペラペラのドキュメントが誕生
今回からは、案件のドキュメントを作らせようとしたらまったく上手くいかなかったという失敗談です。失敗の原因には「コンテキスト」というAIエージェントの概念が関わっています。
ドキュメントを作らせようとして失敗した話
前回はAIエージェントの使い方について触れました。今回からは失敗談です。ドキュメントをまるっと作らせようとしたら全然上手くいかなかったという話になります。
この連載で、「AIエージェントは文章も作ってくれちゃうんですよ。すごいんです」という話を書きました。そして第2回では、「AIエージェント使い方のポイントと思わしきもの」という節で、「要件をまとめてAIに渡すのが良いですよ」とお伝えしました。
文章を作るということもAIエージェントはサクサクとやってくれるので、筆者は「じゃあGitHubのIssue内容をすべて渡せば、そのプロジェクトのことを事細かにまとめた文書一式が作れてしまうのでは？」と考えたのです。いろんな経緯があるプロジェクトでも、ページごとの重要情報がガツンとまとめられてしまうのでは?? というのを期待しまして。
プロジェクトの情報をドキュメントにまとめることは、個人的に多くのプロジェクトで課題になっていると感じています。わかっているがそれをやる時間はないというケースはかなり多いのではないでしょうか。
この企ては冒頭で「失敗談」としたように、全然上手くいかなかったんですが、その過程で自分はなぜAIエージェントがこれをうまくできないのかを学ぶに至りました。この記事を経て、読者の皆様が自分の失敗をトレースし、AIエージェントの特性について理解を深める一助になればと思います。
やりたかったことと、失敗の概要
自分の想定としては、以下のような形でした。
- IssueのデータをすべてAIに読み込ませる
- 重要と思わしき内容をピックアップさせ、それぞれについてドキュメントとしてまとめさせる
ごく短い要件をまとめるのにAIエージェントは使えるのだから、その範囲をGitHub Issue全体に広げれば、これはすごいことができると考えたのです。自分で言うのもなんですが、これまで自分はかなり丁寧にIssueに要件をまとめてきました。なので、それをチョイと整理してもらうだけだ……！と。
しかしこれは、以下の理由で上手くいきませんでした。
- IssueのデータをすべてAIに読み込ませる
- AIエージェントはすべてのデータをメモリ上に読み込むことができない
- 重要と思わしき内容をピックアップさせる
- AIエージェントは何が重要かを判断できない
- ドキュメントとしてまとめさせる
- AIが考えたまとめ方が、自分的にしっくりこない
それぞれどういうことか、一つずつ見ていきます。
ドキュメント化の前の下準備
このアイデアを試す前に、いくつか下準備が必要です。まず、Markdownベースのドキュメントサイトの土台を作りました。筆者はDocusaurusを使いましたが、Astro Starlightなど類似のツールでも良いでしょう。お好みで選んでください。この作業もAIにやってもらいます。
補足：Astro Starlight
Astro StarlightについてはCodeGridに次のシリーズがあるので、ご参照ください。
次に、IssueのデータをAIに読ませる必要があります。Issueの内容は何度も参照することになるだろうと考え、ローカルに全部ダウンロードしておくことにしました。
Claude CodeにNode.jsのスクリプトを作らせ、GitHubのIssueをMarkdownで保存、画像も合わせてダウンロードしてきて……という具合です。こういう本筋とは切り離された小規模なスクリプトは、AIエージェントに作らせる練習としてもオススメです。
そんなこんなで10,000以上Issueがあるプロジェクトのデータをローカルに保存し、ドキュメント化の下準備は万端状態を作って満足しつつ、いざドキュメント作成！ へと進みました。
コンテキストという概念
そんなわけでIssueのデータが手元にすべて揃ったわけでして、「いけ！ Claude Code！ すべての情報を読み、いい感じにまとめるのだ！」的なことを命令してみます。すべてのファイルを読んで長い時間をかけてそれをやってくれるのですが、結果としてできあがってきたドキュメントは、それぞれのページについて、ごく端的な箇条書きが列挙されただけのものでした。
具体的には、ページごとに重要な点をまとめよ的なプロンプトを与えたのですが、その画面の誰でもわかりそうな概要がそれぞれ箇条書きでまとめられただけになっていました。これは自分にとってかなり期待外れで、「おかしい！ もっといろいろIssueに書いてあっただろ!? Issue番号は10,000を超えてるんだぞ……」と思ったものです。
なぜこのようなことが起こるのか？ その理解のためにはコンテキストという概念を理解する必要があります。
Claude Codeでコンテキストの内容を確認する
コンテキストとは何か。Claude Codeであれば/contextというコマンドを入力するとそれを視覚的に表示してくれるので、それを見た方が早いでしょう。その出力結果は以下のようになります。
ここで四角がマス目状に並んでいるのが左上に見えるでしょう。これが全体のコンテキスト量と、その使用量を表しています。データベースのような絵文字がある部分がすでに使用されている部分で、それぞれ何に使用されているのかが列挙されています。
これはClaude Codeを立ち上げたばかりの様子なのですが、すでに1/4ぐらい使用されていることがわかります。明細がその後にたくさん続くのですが、ここで使用されているのは、起動時に読み込ませるようにしているツールや、拡張機能等が占めていると考えてください。この他の空いている3/4ぐらいのメモリ領域を使い、Claude Codeは命令を実行していくわけで、これ以上は一度のセッションで記憶しておくことができないのです。
このメモリはセッションを閉じればクリアされ、新しく立ち上げたセッションではまた空っぽの状態から始まります。このメモリは会話やソースコード等を読ませれば埋まっていき、Claude Codeはそうやって読み込んだ情報を元に、命令を実行するという具合に動いています。このコンテキストがあるから、いろいろと融通を利かせて命令に応えてくれるというわけです。
このあたりはClaude Codeというソフトウェアがそのように動いていると認識してもらって良いですが、基本的にはどのAIエージェントでもこのような上限はあるので、その中で作業するということを覚えておく必要があります。つまり、無限に何でも記憶できるわけではないということです。
コンテキストがいっぱいになると？
ではいっぱいになったらどうなってしまうのか？ ここはClaude Codeは賢い仕組みを持っています。
先ほどのキャプチャのマス目下側には×印のついた四角が並んでいますが、メモリ消費がここまで達すると、ちょうど良い区切りのタイミングをClaude Code自身が見計らい、コンテキストの圧縮が自動で行われます。Claude Codeにはコンテキストを圧縮する/compactコマンドがありますが、これを自動で行うauto-compactという仕組みが備わっているのです。
この/compactというのは賢いコマンドで、それまでの内容を要約し、メモリ上に残すべき重要な内容だけを抽出し、残りを捨てるという働きをします。これにより、メモリの使用量を減らし、また新たな情報を読み込むことができるようになるわけです。いってみれば、今までの内容を10,000文字ぐらいでまとめ、新しくセッションを始め、そのセッションに渡すようなイメージです。
補足：コンテキストの情報量
「10,000文字」というのはイメージです。実際の単位はトークンであり、どの程度のトークンなのかは公開されておらず、またケースバイケースであると考えられます。
このようにして、Claude Codeはいくら会話が続いたとしても、以前の内容の重要な部分を覚えたまま、いかにも何事もなかったかのように会話を継続することが可能なのです。
内容を切り捨てる/compact
しかし！ ここで重要なのは、この/compactコマンドは単純にそれまでの内容を要約して自分に渡し直しているだけであるということです。一つ一つの要求が、そこまで多くの情報を必要としない場合にはこれで上手くいきますが、この要約では必ず何かしらの情報が失われます。そのように前提条件の多い実装等が発生した場合、「それ、さっき言ったのに、なんで忘れてんの……」というようなことが起こるのです。仕様の相談を長いことしていたら、元々の目的が忘れられていたみたいなことも筆者は経験しました。
さて、元々のドキュメント作成の話に戻りますが、この大量Issueをまとめさせる計画の失敗の根本的な原因は、筆者のコンテキストに対する理解不足であると言って良いでしょう。そのようにすべてのIssueの内容を一気にClaude Codeに読ませ、判断させることは、コンテキストの容量的に（現時点では）不可能であるためです。
そのように大量の情報を読ませた場合、途中で/compactが挟まり、前に読んだ内容はどんどん薄い状態に圧縮されていきます。これはもしかしたら、今後のAIエージェントの改善で解決されるかもしれませんが、現時点ではこのような有限のコンテキストの中で動いているのがClaude Codeなので、それを把握しながら使う必要があるということですね。一応これを解決するには、都度都度ドキュメントにまとめさせ、それを見返すようにさせるみたいな方法が考えられますが、そうなるとやはりまるごとドカンと重要なことをまとめてくれというわけにはいかなくなります。
そんなわけで、/compactが繰り返された結果、それぞれのドキュメントの内容が、ただの概要の箇条書きみたいな、内容が過剰にコンパクトな状態になってしまっていたというわけです。
このあたりの話は、後から振り返ればなるほどそうだったなという感じなのですが、実際にドキュメントを作ろうとしていた当時は、試行錯誤の連続で、なぜ上手くいかないのかがさっぱりわかりませんでした。
ちなみにこの「会話が長くなると情報が切り捨てられる」という仕組みは、ChatGPTでも似たようなことが起きているのではと想像されます。AIエージェントを使わない場面でも、頭の隅にでも置いておくとトラブル回避に役立つかもしれません。
ここまでのまとめ
今回は、AIエージェントにドキュメントを一気に作らせようとした際の失敗について、コンテキストという技術的な制約の観点から紹介しました。
冒頭で挙げた失敗の原因のうち、今回は「AIエージェントはすべてのデータをメモリ上に読み込むことができない」という点について詳しく見てきました。次回は残りの2つ、「AIエージェントは何が重要かを判断できない」「AIが考えたまとめ方が、自分的にしっくりこない」という点について見ていきます。