エンジニアの三田(@Eichisanden)です。
今年取り組んだ、プロダクトの仕様を答える社内向けQ&Aエージェント開発で得た学びを記事にしたいと思います。
はじめに
「この機能の仕様ってどうなってましたっけ？」
「このデータ、どういう条件で作成されますか？」
開発チームには日々、こうした仕様に関する問い合わせがきます。ドキュメントがあっても探しきれなかったり、最新の実装と乖離していたりして、エンジニアがコードを読んで答えることも多いです。
これを何とかしたくて、非エンジニア（ビジネスサイド、デザイナー、PdMなど）が仕様の疑問を自己解決できるようにするために、ソースコードやドキュメントを読み込んで良い感じに答えてくれるような社内向けQ&Aエージェントを作ってみました。
（※入力データが学習に利用されない設定でLLMを利用しています）
仕様の質問に対しても適切に回答できると好評いただきましたが、想定以上の使われ方もされており、「この機能、現状の仕様だとどう運用するのがベスト？」みたいな運用相談の壁打ち相手としても活用されていて、エージェントもそれに対してかなり的確な提案を返していることに驚きました。
本記事では、社内Q&Aエージェントが単なる検索ツールを超えてワークするようになった理由と、技術的な工夫、そして失敗から学んだことを書いていきます。
アーキテクチャと技術選定
Claude Agent SDK
今回の中心となる技術選定が Claude Agent SDK です。
Claude Agent SDKは、Claude Codeを組み込んだアプリを作れるよう公式から提供されているライブラリです。これを使うと、自前でエージェントループを実装しなくても、以下のような機能をすぐに使えます。
- ツール使用の自動化: ファイル読み込みや検索などのツールを定義すれば、AIが必要に応じて自律的に呼び出してくれる
- マルチステップ推論: 複数のツールを組み合わせて段階的に問題を解決する、Claude Codeのような動きが可能
- ストリーミング対応: 長い処理でもリアルタイムに途中経過を返せる
正直、エージェントの「ループ処理」や「ツール呼び出しの制御」を自前で実装するのはかなり面倒で、SDKがこの部分を抽象化してくれるので、「何を読ませるか」「どう答えさせるか」というロジックに集中できました。
また、複雑なRAGパイプラインやベクトルDBを構築しなくても、シンプルに「コードやドキュメントを読ませてAIに考えさせる」というアプローチで十分実用的なエージェントが作れました。まずは小さく始めてみたい、という場合にちょうどいい選択肢でした。
実装言語：TypeScript
SDKはPython、TypeScriptが提供されていますが、TypeScript を選択しました。
開発当時、Claude Codeはnpmでのみ提供されており、動かすにはNode.js環境が必須だったため、追加でPythonのセットアップもするのは煩雑だと思ったためです。
現在はClaude Codeはネイティブバイナリとしても提供されるようになったので、これから始めるなら Python も全然アリだったなと思いました。
AIの「遅さ」を隠すUXの工夫
専用のWeb画面を作ると、それだけで利用のハードルが上がってしまうため、UIは全社員が毎日使っている Slack から実行できるようにしました。
どんなにモデルが速くなっても、複雑な推論が入れば数秒〜数十秒の待ち時間は発生します。この待ち時間はユーザーに「動いてる？」という不安を与えてしまいます。
そこで以下の工夫を入れました。
- 「問い合わせ中」ステータスの可視化: メッセージを受け取ったら即座に動くスタンプを表示して、「ちゃんと動いてるよ」と伝える
- プログレス表示: 最終回答が出るまでの間、思考中である旨のメッセージを都度返して、体感的な待ち時間を減らす
実際は🤔のスタンプがクルクル回ってます
AIに「賢く」答えてもらうための3つの学び
運用してみて痛感したのは、AIの回答精度は「モデルの賢さ」よりも「渡す情報の質」に大きく依存するということ。
ここからは、運用で得られた 「AIフレンドリーなコードベースとドキュメント」 に関する3つの学びを共有します。
1. インプットの質が全て：ノイズを捨て、信頼できる情報だけを渡す
当初は「過去の問い合わせ履歴（Slackログなど）」も学習させようとしました。が、これは失敗でした。古い仕様に基づいた回答や、解決に至らなかったノイズが多く、回答精度を下げる要因になってしまいました。
最終的にインプットとして採用したのは以下の3点だけです。
- ソースコード: 最新の仕様そのもの
- リリースノート（Notion）: 変更の意図や背景情報。ここはかなり細かく書いています
- ユビキタス言語集: 表記揺れを防ぎ、AIが用語を正しく理解するための辞書
これらを厳選して渡すことで、AIは迷いなく正確な情報を引き出せるようになりました。
2. 「隠れたロジック」はAIには見えない
運用中、ユーザーから「Q&Aエージェントが間違った仕様を返してくる」というフィードバックがありました。
原因を調べてみると、答えられなかった仕様は 「SQLのWHERE句の中にだけ存在するルール」 でした。
アプリケーションコード（ドメインロジック）として明示されておらず、クエリの中に埋め込まれた条件分岐はAIにとって非常に見つけにくい「隠れたロジック」なのかなと推測できました。
逆に、普段から良い回答を返せている機能は、ドメインロジックが独立して記述されている 箇所でした。
「AIに仕様を答えさせる」という要件を通じて、ビジネスルールをコードとして明示的に表現することの重要性を改めて実感しましたし、AIでのコーディングがうまくいかないとき、モデルやプロンプトだけでなく、既存コード側に問題がある可能性も考えるようになりました。人間にとって読みやすいコードは、AIにとっても読みやすいのだと思います。
なお、すぐにリファクタリングできない場合もあるので、「FAQドキュメント」 を別途作成してAIに読ませることで、当面の回避策としています。
3. コードコメントは「検索アンカー」である
もう一つ効果的だったのがコードコメントです。
これまでコメントは「人間が読むための補助」だと思っていましたが、AIにとっては 「該当箇所を探し当てるための強力なアンカー（検索の目印）」 として機能します。
AIは膨大なコードの中から関連箇所を探索しますが、的確なコメントがある関数やクラスは明らかにヒット率が高い。「AIが見つけやすいようにコメントを書く」という意識は、結果として人間にとっても読みやすいコードに繋がっています。
泥臭い実装の工夫：API制限との戦い
AIエージェント開発では、モデル選定と同じくらい「どうやってデータを食わせるか」という足回りが重要です。ここからは実際に直面した課題と、その解決策について。
GitHub APIのレートリミットとMCPの限界
開発初期は、GitHub上のコードを取得するために GitHub MCP (Model Context Protocol) サーバー を使っていました。標準的な仕組みで実装もスマートだったんですが、運用を始めるとすぐに レートリミット（API利用制限） の壁にぶつかりました。
エージェントが回答を作るために複数ファイルを探索したり、広範囲のコードを読み込んだりすると、あっという間にAPI制限に達して回答不能になることが頻発しました。
解決策：ローカルにgit pull
API経由での取得に見切りをつけて、「エージェントが動いているサーバー上に、対象リポジトリを直接 git pull して、ローカルファイルとして読ませる」 という原始的な方法に切り替えました。
一見スマートではありませんが、結果として多くのメリットがありました。
- レートリミットの撤廃: APIを叩かないので、どれだけファイルを読んでも制限に引っかからない
- 圧倒的な速度: ネットワーク越しのAPIコールがなくなり、ローカルI/Oで完結するので検索・読み込みが劇的に速くなった
最新のプロトコルやAPIにこだわらず、「ローカルに落としてgrepする」 ような泥臭いアプローチの方が、実運用では安定的かつ高速だったという結果になりました。
（※情報へは必要なコンテナからのみ参照できるようにアクセス権を制御しています）
まとめ
エンジニアの問い合わせ対応を減らしたい——そんな動機から始まったこのプロジェクト。得られた最大の成果は自動化だけではありませんでした。
「AIに正しく仕様を理解させるには、人間にとっても読みやすいコードとドキュメントが必要」 という、当たり前だけど見過ごしがちなことを再認識できた。これが私にとって一番大きかったです。
- ドメインロジックをSQLやViewに埋め込まず、コードとして独立させる
- 「なぜそうしたのか」という背景をリリースノートに残す
- 検索の手掛かりとなるコメントを丁寧に書く
これらはすべて、従来のソフトウェア開発でも「良い習慣」とされてきたことです。
AIのために整備した情報は、新しくチームに入ったメンバーや、仕様を確認したい非エンジニアにとっても有益な資産になります。
今後の展望
現在は人間がインプットを整備していますが、今後は以下に取り組んでいきたいと思っています。
- 回答評価の自動化: AIの回答が適切だったかを自動採点し、精度をモニタリングする
- 自己改善ループ: ユーザーからのフィードバックを元に、AI自身がFAQを更新したり、回答パターンを学習したりする仕組み
社内Q&Aエージェントは、Claude Agent SDKと少しの工夫があれば、驚くほど低コストで構築できますのでオススメです。
Discussion