AIエージェントのススメ 第5回 私の思う重要とあなたの思う重要は違う
AIエージェントにドキュメントを作らせようとして失敗した話の続きです。AIと人間の判断の違いについて紹介します。
AIにドキュメントを作らせる別のアプローチ
前回は、AIエージェントにドキュメントを一気に作らせようとした失敗について、コンテキストという技術的な制約の観点から紹介しました。今回は引き続き、同じ失敗についての話ですが、技術的な制約ではなく、AIと人間の判断の違いという観点から見ていきます。
前回の記事で挙げた失敗の原因は以下の3つでした。
- IssueのデータをすべてAIに読み込ませる
- AIエージェントはすべてのデータをメモリ上に読み込むことができない ← 前回
- 重要と思わしき内容をピックアップさせる
- AIエージェントは何が重要かを判断できない ← 今回
- ドキュメントとしてまとめさせる
- AIが考えたまとめ方が、自分的にしっくりこない ← 今回
今回は残りの2つについて見ていきます。
重要な内容のピックアップ
前回書いたように、一気にIssueを読み込ませて上手くいかないなと思っていた筆者は、別のアプローチを試みることにしました。それは、Claude Codeに重要と思わしき内容をピックアップさせ、そこから筆者が「これが重要である」と判断。それをドキュメント化させる、という方法です。
この方法はこうです。
- 前回同様、ダウンロードしてきたIssueのデータを用意
- 全部Claude Codeに読み込ませ、箇条書きでトピックを列挙させる
- その中から筆者が選び、それについて改めて詳しく調査
- そうやって選ばれたトピックについてドキュメント化させる
Claude Codeの力を借りつつ筆者が重要と判断した内容をカテゴライズし、それを元にドキュメントサイトを作ってもらうという具合です。
今改めて考えても、このアプローチはそんなに悪くないようにも思えます。しかし、そのときはそうやって作ったドキュメント一式について、何かしっくりこなくて破棄してしまっていました。
このあたりの試行錯誤をほぼほぼ無限にできるのがAIエージェントの良いところかなとも思いますが、何はともあれ、そういう判断になってしまった理由を見ていきましょう。
重要だと思っていた内容がそこにあったのか
Claude Codeにピックアップされたトピックのうち、確かに「あーこれはそういえばやったけど忘れてたな」みたいなものはありました。
実際の案件なのでここで具体的に挙げることができませんので、CodeGridのサービスに置き換えてみます。たとえばそうですね……以下のようなものを「Claude Codeが探してきて、ピックアップした」と想像すると良いかもしれません。
- お気に入り機能の仕様
- サイト内検索の仕様
- シリーズのデータの持たせ方
- 既読記事の仕様
もしくは、自分のやっているプロジェクトのコードをClaude Codeにひととおり読ませ、「何をドキュメントにしておくべきか？ と聞いてみた」と想像してみても良いでしょう。ディレクトリ構造とか、ファイルのインポートのルールとか、そういうものをたくさん挙げてくると思います。
しかし、そういうふうにClaude Codeが挙げてきた候補が、「本当にドキュメントに残しておくべき内容であると思えるか？」というと、微妙に違っている気がそのときはしたのです。
確かにそのお気に入り機能の仕様は忘れてはいたものの、それをドキュメントに残しておくべきだと、今強く思っているかというとどうだろうか……というのを改めて考えさせられるといいますか。そもそも、他にももっと重要なことがあったっぽい気がするんだが？ というようなことも考えたりしました。
そう思いつつ、上がってきたトピックを選び、Claude Codeにカテゴライズさせてドキュメントを作りました。しかし、できあがったドキュメント一式を読んでみても、何かしっくりこない。それはなぜだろう。すべてのIssueを読ませ、まとめさせた結果なのに？
ドキュメントをまとめるというのは意思をもってすること
筆者はこの手のドキュメント化をその後かなりやっており、今なら自分で把握できていることがあります。それはこのドキュメントをまとめるということが、何かしらの意思を持って進めるべきものであるということです。
つまりは、何が重要で、それをどうまとめるかというのは、その人の経験により判断されているものです。だから、赤の他人──この場合はClaude Code氏──が選んで構成したものは、自分が重要と考える、わかりやすいと考える内容・形式とは必ずしも一致しないというふうに筆者は考えています。
たとえば30ページぐらいのWebアプリがあったとして、それぞれの画面の仕様をまとめようと考えたとしましょう。そういう状況になったら、一つ一つの画面をよく見て、ああこの画面はこういう機能があった、このAPIを叩いている、こういう実装だったけど忘れていたな……みたいなことがたくさん出てくるでしょう。
そのようにして見ていくと、そのWebアプリの構成自体に気づくことがあります。たとえば、このカテゴリ内の一連の画面では共通のUIがあるから、これはこっちにまとめようとか、この画面はそういう共通機能を使っているほかはテキストだけだからほとんど書くことはないとか。そうすると、ドキュメントはどうまとめるとよいのかということにも考えが及ぶかもしれません。これってそもそも画面単位でドキュメントにまとめる必要ある？ 重要なトピックごとにドキュメントにすべきか？ などなど……。
そういう構成自体を考えることが、ドキュメントをまとめるということではないかと筆者には思えます。
ところが、Claude Code氏に「画面ごとに調査して仕様まとめて」みたいな頼み方をすれば、ドバッと、画面ごとにMarkdownファイルを作ってくれます。そこで挙がってきたものは、Claude Code氏が判断したものであって、自分にとって重要そうであるという感覚とは一致しないことが筆者には多かったということです。
そうした試行錯誤を重ねていく中で、そもそもこのドキュメントを作るのは何のためなのか、という点に立ち戻らされる感覚が筆者にはありました。この手のドキュメントはこれまでも比較的多く書いてきましたが、「ドキュメント」と一口に言っても、想定する読者を意識し、何を伝えるべきかを考えなければ、薄っぺらく、あまり役に立たないものになってしまうように感じます。
たとえばWebアプリに関するドキュメントであれば、チームメンバーである開発者向けの開発ガイダンスなのか、あるいはそのアプリを使って顧客と実際にやり取りを行う担当者が参照する資料なのかによって、求められる内容は大きく異なってきます。
Issueやソースコードの中に何らかの有用そうな情報があり、それをClaude Code氏がうまく拾ってくれれば、役に立つドキュメントができることもあります。しかし、たとえばSlackやミーティングでの会話のような内容まで拾ってもらうのは、やはり難しいでしょう。
前回の記事でコンテキストの話をしましたが、Claude Codeの判断した内容は、その場でドバッと一通りのIssueやソースコードを見たことに基づくものです。これに対し、私ら人間はそういう場合、長い時間をかけてそのプロジェクトに取り組んできたという、より長期のコンテキスト情報を持っているのであり、長期スパンで見た場合に適切な判断が下せるのは、そういう経験値が蓄積された人間のほうなのかもしれません。
このあたりのドキュメントの話はまた別の機会にまとめようかとも考えていますが、つまるところ、AIエージェントに何かを丸投げしたところで、何がしたいのかがはっきりしていなければ、成果物はやはり曖昧なものになってしまうということが一つ言えるのではないかなと、筆者は考えていますがいかがでしょうか。
どうしたらうまくいったのか
そのように、AIのコンテキストを理解してない自分＋AIに判断を任せた自分、というダブル効果で、「ドキュメントを楽々作成」はうまくいかなかった筆者なわけですが、その後は、都度都度重要であると考えたトピックについて、ドキュメントとして追加、場合によって不要なものは削除するような体制でプロジェクトを進めています。
そして、ドキュメントは必ず最小限のカテゴリで始める。自分の場合はまず「INBOX」という何でも放り込むカテゴリのみを作り、そこに追加していって後から考える方式でまとめることにしています。このあたりは以前以下で書いたGTD的な考え方を筆者が持っていることに由来しています。
長いこと何かしらのプロジェクトを進めていれば、この機能が追加、あの機能が追加と、どんどん機能が増えてきて、メモしておかないと忘れてしまうようなことが出てくるでしょう。そういう「あーこれは忘れると後でキツイ……」というタイミングを見計らい、Claude Codeなど、AIエージェントを使ってドキュメント化させ、追加していくのです。今回のアイデアも、そういう状態で拾い忘れているトピックを洗い出すという使い方であれば有用だったかもしれません。
具体的にどういうドキュメントを作ったか
具体的にどういうドキュメントサイトを作ったかをお見せしましょう。筆者が個人で運営しているモジュラーシンセサイザーのショップ「Takazudo Modular」と、そのケースオーダー用Webアプリ「Panels」について、それぞれDocusaurusで開発ドキュメントを作成しています。
ドキュメントサイトのカテゴリ構成を見ていただくと、先ほど書いたINBOXカテゴリがそれぞれのサイトにあるのがわかるかと思います。最初は「INBOX」だけだったものが、トピックが増えるにつれて「Overview」や「Writing」、「Builder」、「Knowledge」といったカテゴリに整理されていった形です。こうした構成も、最初からAIに「考えて」と頼んだわけではなく、ドキュメントが増えてきた中で自分が「こう分けたほうがわかりやすいな」と判断して整理していったものです。
また、開発を続けていると、Webサイトを大きくリニューアルしたり、機能を削除したりすることもあります。そうなると当然、既存のドキュメントが実態と合わなくなったり、そもそも不要になったりするわけです。そういうときには、筆者がClaude Codeに「このカテゴリはもう要らないから削除して」「この部分は構成を変えてこういうふうにまとめ直して」といった方針を伝え、具体的な文章はClaude Codeに書かせるようにしています。つまり、自分が判断しているのは「どう整理するか」「何が必要で何が不要か」という方向性の部分であり、詳細なテキストの執筆はAIエージェントに任せているということです。
このようなことは、AIエージェント以前だと、十分な時間と人的リソースがなければ実現不可能なことでした。ですがAIエージェントを使うことでこのコストを大幅に減らせることができるわけです。しかし、かといって無尽蔵にドキュメントを書かせれば良いというものでもないぞ、ということが言えるのだろうと筆者は考えます。
この視点はおそらくAIエージェントを使っていく上で重要です。たとえばコードレビューをAIエージェントにさせると、いろいろと指摘をしてくれたり直してくれたりするわけですが、これもそもそもそれが必要か否かの判断がないと、無限にレビューと改善を繰り返すことにもなり得ます。だったら、何を判断基準として終わらせれば良いのか。そのあたりもこの連載で引き続き見ていきたいと考えています。
今回は、AIエージェントにドキュメントを作らせようとして失敗した話の続きとして、AIと人間の判断の違いについて紹介しました。次回も引き続き、AIエージェントを使った開発で陥った失敗について紹介していきます。