AIエージェントのススメ 第2回 AIエージェントをうまく使うにはどうしたらいいですか？
「AIは、思ったような返答が返ってこないなあ」と感じたことはありませんか？ AIエージェントをうまく使っていくために考えた、工夫をお伝えします。
AIエージェントは具体的に何をしてくれるのか
前回はAIエージェントとは何かを、筆者が使っているClaude Codeを例にお伝えしました。
さて、そんなAIエージェントについてですが、「どう使うんですか？」「何をしてくれるんですか？」という問いにお答えしたいと考えているのですが、その雰囲気を伝えるのは、実際に使ってみないと難しいように筆者は感じています。ChatGPTやGrokであれば、チャットで何かプロンプトを打つとその結果が返されますが、AIエージェントはその中で実際にコードを編集したり新しくファイルを作ったり、そういったことをしてくれます。
じゃあたとえば……ということで例を挙げると、以下のようなことを最近はClaude Codeに頼んでやらせていました。
- Gitブランチのコンフリクト解決 - ややこしいコンフリクトも文脈を見て適切にマージ
- E2Eテストの作成と実行 - 全ページの表示テストをCIで自動化、GitHub Actionsのワークフローも作成
- ドキュメントの生成 - IssueやPRの内容を参照にして要点をまとめたドキュメントを作成
- Swaggerドキュメントビューアーの統合 - PDFやSwaggerの内容をベースにDocusaurusにAPIドキュメントを追加
- スクリーンショット自動化 - Playwrightで特定サイズの画面キャプチャ画像を全画面について自動作成
- HARファイル分析によるAPIドキュメント化 - 実通信からAPI仕様を抽出し、API仕様をまとめさせドキュメント化
- APIエンドポイントの整理 - 全コードをチェックさせて使っていないAPIエンドポイントに関するコードを削除
- レイアウト不具合調査 - 本番環境のHARファイルを元にレイアウト不具合の原因を特定
- CSV to JSON変換ユーティリティ - データフォーマット間の双方向変換ツールを開発
- テンプレートベースのファイル生成 - プレースホルダー置換で複数ファイルを一括作成するスクリプトを開発
- Astro StarlightによるWebアプリケーション構築 - Markdownビューアーを構築しNetlifyで配信できるようセットアップ
- デプロイ用ビルドスクリプト開発 - 本番リリース用の自動化スクリプトを作成
参考：HARファイル分析
6の「HARファイル分析によるAPIドキュメント化」は、CodeGridの次の記事も参考にしてください。
これは今、自分がClaude Codeに、自分が打ったプロンプトのメモを貯めているディレクトリを読ませて、30個ピックアップさせたものから選んだものです。
こういうのを見せられたところで、「まぁ仕事してますね」っていう感想になるのではないかと思われますが、そういった日常的な開発のあれこれを自分はClaude Codeでやっているという感じです。
AIエージェントはどこまでやってくれるのか？
この一つ一つの具体例を細かく話していくとキリがないので、とりあえずわかりやすいものをピックアップすると、たとえば「Astro StarlightによるWebアプリケーション構築」はわかりやすそうです。
参考：Starlightとは？
Starlightは、軽量かつ拡張性の高いドキュメントサイトを簡単に構築できるAstroベースのフレームワークです。
「Astro StarlightでMarkdownのビューアーを作りたいのでやって」などとClaude Codeに打ち込めば、あれやこれやと作業してくれます。そうやって作ってくれた後、「サイドバーのカテゴリいじりたいんだけどどうやる？」とか「API仕様カテゴリ追加して」などと命令する形です。
しかし、「そういった、お決まりのテンプレート的なものならまぁ、AIならやってくれるんでしょうね。でも実際のいろんな事情にまみれているプロジェクトのコードなんかは、きっとうまいことやってくれないんでしょ？」そう思われるかもしれないですね。でも、そういったケースであっても、その情報源となるデータやテキストがあればかなり機能してくれるのではないかと筆者は考えます。
たとえば、次のようなことができました。
- 「このAPIに投げてるクエリがやたら複雑なんだけどどういう背景？ Issueを探して教えて」=> GitHub CLIを使い、GitHub Issueから関連する情報を見つけてきて教えてくれた
- 「こういうJSエラーが出ているのだが、原因って何？（画面のキャプチャも貼り付ける）」=>わりと正確に原因を突き止める
前回も少し触れましたが、Claude Codeはターミナル上で動かせるものであれば使うことができるので、そういったClaude Code以外の外部ツールも利用可能なのです。よって、Issueにいろいろ要件がまとめられている状態では、そのような情報を参照しつつ調査が可能。Pull Requestにコメントされた会話の流れやレビューコメントも読めますから、この「レビューどう思う？」とか、「こういうレビューコメントをもらったけど、このプロジェクトの要件的にはここはこう書いておく必要がある。でも、コメントもらった内容も理解できる。どうしたらいいか？」みたいな相談をすることも可能です。
Claude CodeをはじめとしたAIのエージェントは、できそうなことを予測して使っていくのが、多くの人の使い方となるでしょう。Claude Codeをどう使うかは人それぞれであり、筆者の場合はとりあえずなんでもClaude Codeにできそうなことだったらとりあえずやらせてみて、やれそうにないことは自分でやるというふうに働く感じになっています。
AIエージェント使い方のポイントと思わしきもの
そんなClaude Codeですが、「どうやって使うんですか？」と聞かれれば、「プロンプトを打つだけだよ」なわけでして、基本は非常にシンプルです。日本語ででも英語ででも、ただ命令すれば動いてくれるんだから、使わない理由はなかろう？ 何か特殊なプログラミング言語を覚える必要があるわけでもないし……。というのが取り急ぎの筆者からのAIエージェント使用の第一歩を踏み出す誘いの言葉ではあります。
ただ、Claude Codeを継続して使っていくうちに、そして他の人とAIについて会話をしていくうちに、これを上手く使っていくというのはそんな単純な話じゃないのではないか……？ と考えるように変化してきました。
SNSでは、AI関連のニュースが出る度に「これはすごい」「こんなにすごい」と言いながら、ミニゲームをAIに作らせるような人がいるようですが、実際に仕事でメンテしているコードを書かせたりしようとすると、確かにささっとやってくれる部分も多いものの、「そうじゃないんだよな〜」という結果に、すぐに遭遇するかと思われます。社内や同業種の人と話していても、「AIにやらせてみてるんだけど、なんか全然とんちんかんなことばかりやってくるんだよね」という話になることはよくあります。
このようなAIエージェントを使うためのポイントとなるようなノウハウは、世間的には最近、「コンテキストエンジニアリング」と呼ばれるようになってきているようです。この話については、以下Anthropic社のブログにすばらしく内容がまとめられていますので、ご興味あれば是非ご一読頂けると良いかと思います。
一応一言添えておくと、「コンテキストエンジニアリング」といったような言葉は最近出てきては消えていくようなものであるかもしれないので、概念を理解していただくような気持ちで読んでいただけると良いかと筆者は考えています。
この「コンテキストエンジニアリング」の言葉の前には、「プロンプトエンジニアリング」という言葉がありました。これはたとえばChatGPTなんかに、どういうふうにプロンプトを与えれば良い結果が得られるかという、命令文を作るコツみたいなものです。この言葉がよく聞かれるようになったとき、筆者は「うーんでも、そんなガチャを引くためのおまじないみたいなことをがんばって考えても、何か身になることなんてあるのか？」と感じていました。
ですが、LLMの進化と、AIエージェントというソフトウェアのアップデートに伴い、AIに与える情報の意味が変化してきました。今まではチャット形式でただ単にその場その場の会話を紡いでいくのが基本でしたが、AIエージェントはディレクトリ配下にあるファイルの情報や、前述のGitHub CLIのようなツールを使い、それ以外の情報も参照することが可能なわけです。そのように前提条件が変化した現在においては、ただ単に命令文をいかにうまく作るかというところから、AIエージェントにどのように背景となる情報（コンテキスト）等々を与えれば良いかというところにフォーカスが移ってきたのではないかと思われます。
さて、そんなClaude CodeをはじめとするAIエージェントを使っていくには、最終的には「プロンプトを打てばOK」ではありますが、いろいろポイントがあります。これを自分なりに以下3点にまとめました。
- AIに作業させたいという気持ち
- 要件をテキストにまとめられる能力
- プロジェクトの情報を文書化していく
それぞれ見ていきます。
1. AIに作業させたいという気持ち
まず1つ目は「AIに作業させたいという気持ち」です。
「なんだい精神論かい！」と思われるかもしれないのですが、筆者はAI系のオンラインイベントなどでも「AI活用が思ったように組織内で広まらない」という問題を解決しようと試みている発表をいくつも見かけました。かく言うピクセルグリッドも、2025年9月現在、皆が皆、バリバリAIエージェントを活用しまくっているかと言われると、そこまででもありません。
AIがなくたって我々は普通にエディタでコードを書いてきました。そしてこれからもその方法は有効なわけです。そんな中でAIを使おうとするには、気持ちが必要ではないかと筆者は考えます。
たとえば、ちょっと話は脱線しますが、キッチン用品で卵の穴開け機というものがあります（例によってAIで生成した画像です）。
これはゆで卵を作る際、できあがった後に殻を取り外しやすくなるよう、小さな穴をあけるためのものです。卵を茹でる際、これで穴を開けておくと殻がつるんと取れるようになるので、筆者はラーメンに入れる味玉を作るために便利に日々使っています。でも、「これすごい便利なんですよ！」と勧めたところで、読者の皆様は別に「そんなにゆで卵作らないしな……」と思われるのではないですかね？
「AIがすごくて便利だよ！」もこれと似た話かと筆者は考えていまして、ただチャット形式で命令するだけで使えるものであったとしても、既存の仕事の仕方があるところに変化を付けるのは、ある程度の興味や期待がその人の中に生まれている必要があるかと思われます。コードなら前回挙げたVSCode + GitHub Copilotを使っても相当に楽に書けるわけですから。AIを使わなくたって、たとえばVSCodeのこの拡張が便利だとか、このGitビューアーのアプリが便利だとか、そういう効率化の話は無限にありますからね。
なのでAIエージェントを使うためのステップの、まず一つ目として「AIに作業させたいという気持ち」をここでは挙げます。「さっさと仕事を終わらせたい」とか「単純作業したくない」とか、そういうものでも十分でしょう。
それについて筆者から言えるのは、「AIに作業させると、めちゃいろいろ楽になる（かも）よ！」というのをお伝えするぐらいのことではないかと思われます。また、AIで解決できることが、本人にとって問題であったことを解決してくれそうかにもよるかもしれません。先ほどの話で言うと、「いつもゆで卵の殻が剥きづらかったんだよな〜」みたいな事実が蓄積されていた人にとって、あのキッチン用品が有益と感じられるという話です。
筆者の場合、このAIエージェントが解決してくれた問題は、筆者自身の仕事の進め方にとってボトルネックになっていた部分でありました。読者の皆様も、何かAIエージェントで楽できそうではないか？ と思ったら、ぜひ使ってみることをオススメします。まぁ、筆者としては、ゆで卵の殻を剥くキッチン用品よりもずっとインパクトがあるとは思っていますが……。
2. 要件をテキストにまとめられる能力
2つ目、AIエージェントを上手く使うためには、「要件をテキストにまとめられる能力」が求められていると筆者は感じます。
この2つ目のポイントについて、筆者自身が「なぜこれほどまでにAIエージェントに興味を抱くのか」を考えたときに感じることがあります。それは、自分がこれまでに携わってきた仕事、そして日々行っている業務の多くが、プロジェクトの中で要件を整理しまとめる役割であったという点です。日常的にチームメンバーと行っているコミュニケーションが、そのままClaude Codeを相手にしたやり取りに置き換わっただけであるため、非常に自然で手に馴染む形で使えているのだろうと考えるに至りました。
前回の最後にも少し触れましたが、AIエージェントに何か頼んだところで、利用価値のある結果にならないことは多いです。何か頼んでみたところで、とんちんかんな修正をしたり、別の問題を生んだり、どう考えても要らないような文章を足してきたりなどなど。そういった状態をベターにすべく、期待する結果が生成される確率を上げるためにはどうすれば良いか。重要なのは、必要な情報をなるべく簡潔にまとめて伝えることではないかと思われます。
ただ改めてそういうのが重要なんだと言われたら、それってAIエージェントだから必要というわけではない気がしませんか？ チームで仕事をしていたら、チームメンバーに何か頼むときにまったく同じことが必要になるでしょう。筆者は過去に、ディレクターとしてどう働いているか、何をしているのかという、以下の連載を書きました。
このAI連載は、言ってみればこの連載の続き的な文脈の話ですらあるように感じています。
例を挙げます。想像してみてください。あなたが突然ピクセルグリッドに入社し、そしてこのCodeGridの開発を任されたという状況を。CodeGridのリポジトリの権限を与えられ、手元にソースコードをダウンロードしてきて、それだけで「はい、この画面で記事のお気に入り数を出してね〜」と言われたら、できると思いますか？ おそらくできないですよね。じゃあそういう状態で何をするかと言われたら、既存のコードを読んであれやこれやを把握、何かしらドキュメントのようなものが残っていたらそれを読んでみる、メンバーに聞くなどということをするでしょう。
ここでClaude Codeを立ち上げて、「はい、この画面で記事のお気に入り数を出してね〜」と伝えても、この新メンバーとまったく同じ状態です。「お気に入り数？ 何ですかそれは？」ってClaude Codeも考えるでしょう。ただClaude Codeはソースコードを読み解いてくれるため、そのコードから推論されるあれやこれや理解してやってくれるかもしれませんが、つまるところ、そのようにAIエージェントに何かをしてもらうには、その前提となる要件、頼みたいこと、そのための情報を的確に渡さなければ、期待した結果を得ることは難しいということです。
筆者の仕事の多くは、お客さんの要望ややりたいことを伺い、そしてチームメンバーに実装を頼むために、GitHub Issueなりに情報をまとめることに費やされていました。Claude Codeを使い出して間もない頃、いつも通りそういった状態のIssueを作った後、試しにClaude Codeに「このIssueの内容を実装して」と頼んでみました。するとなんということでしょう、「わかりました」などと言って5分ぐらいでコードをあれこれ変更し、実装の大部分が終わってしまったのです。これは筆者にとってかなり衝撃的なことでした。「え？ 頼むものもう終わってる……!? チームメンバーに頼むことなくなった……」という感じです。
この要件をまとめることの重要さがわかっていないと、こういったAIエージェントをいくら使っても、「うーん、結局ガチャみたいなものだよね」という感想以上のものにはならない可能性が高いのではないかなと筆者は考えています。今はこっちのAIエージェントが優秀、あっちのAIは最近のアップデートでイマイチになったみたいな話がよくあり、そういうのはある程度事実なんですが、そういうのとは別に、我々が要件をどうAIに伝えるのかを技術として考えていったほうが良いように筆者は感じます。
3. プロジェクトの情報を文書化していく
そういった要件を整理してAIに渡していると、時間が経ってまた別の実装をするとき、過去の情報をAIに把握してもらう必要が発生してきます。挙げた例で言えば、「あっちの画面でもこっちの画面でも、記事のお気に入り数を表示させたい」というようなことです。
そういう場合どうしますか？ 「よし、前のようにまとめた要件をまた作ってClaude Codeに渡すぞ〜」というのを継続していくと、毎回毎回Claude Codeに長文のテキストを書いて渡すようになってしまうでしょう。お気に入り数取得のAPIはこれだよ、この取得したデータはここで整形しているよ、こっちはこういう注意事項があるよ──と。
そういうことを効率的に行っていくにはどうすれば良いか。それは単純で、そういったプロジェクトの知識をテキストとして整理し、まとめておけば良いのです。これは別に大げさな話ではありません。ただプロジェクトのリポジトリに/doc/などというディレクトリを作り、その中にMarkdownファイルをひたすら置いていくだけでも事足ります。このお気に入り機能の話で言えば、API側の実装みたいなものが含まれます。じゃあ、お気に入り機能で使うAPIはどれで、どういう仕組みなのかというのを、/doc/favorites.mdみたいなファイルにまとめておくわけです。
実際のプロジェクトって、プロジェクト固有のノウハウがどこかにまとまっているわけではなく、「知っている人だけが知っている」みたいなことになっている情報が山のようにあったりしませんか？ たとえば、CodeGridでは、コードサンプルを記事上でプレビューさせるために、原稿を蓄積しているリポジトリの中で、特定の名前のルールでディレクトリを切り、そこにHTMLを入れる必要があります。そしてデプロイ時にはこのディレクトリ名のルールに沿って配置されたHTMLを、デモ用の別のサーバーにデプロイし、それをiframeで参照する仕組みになっています。
こういった情報について、テキストを残しておけば、Claude Codeに頼むときに、「このコードサンプルの仕様は/doc/demo-iframe.mdにまとまっているから参照して把握して」などと一言添えればよくなります。開発が進んでいけば、こういう仕様は何度でも参照されます。そのためにはこれが情報としてまとまっていることがチームメンバーにとっても重要なのは言わずともがなという感じですが、これはAIにとっても非常に重要な要素であると言っていいのではないでしょうか。
今回は、筆者が考える「AIエージェント使い方のポイントと思わしきもの」について述べました。次回は、AIエージェントを使った開発の実際的な進め方と課題について考えてみたいと思います。