概要
https://zenn.dev/loglass/articles/ab5431010454b0
詳細内容
## Claude Agent SDKでQ&Aエージェントを開発して得た学び
https://zenn.dev/loglass/articles/ab5431010454b0
**Original Title**: Claude Agent SDKでQ&Aエージェントを開発して得た学び
ログラスのエンジニアがClaude Agent SDKを用いて社内Q&Aエージェントを開発し、AIの回答精度を高めるためのコード品質、ドキュメント整備、UX改善における実践的な知見を共有します。
**Content Type**: ⚙️ Tools
**Language**: ja
**Scores**: Signal:5/5 | Depth:4/5 | Unique:4/5 | Practical:5/5 | Anti-Hype:5/5
**Main Journal**: 91/100 | **Annex Potential**: 90/100 | **Overall**: 92/100
**Topics**: [[Claude Agent SDK, 社内Q&Aエージェント, AIとコード品質, LLM開発のUX, GitHub APIレートリミット]]
ログラスのエンジニアが社内向けのプロダクト仕様Q&Aエージェントを開発する過程で得た学びを詳細に解説しています。このエージェントは、非エンジニアが仕様疑問を自己解決できるよう、ソースコードやドキュメントを読み込んで回答を提供するもので、単なる検索ツールを超えて運用相談にも活用されるほどの成果を上げました。
技術選定の中心はClaude Agent SDKで、著者は自前でのエージェントループやツール呼び出し制御の実装を省き、「何を読ませるか」「どう答えさせるか」のロジックに集中できた点を高く評価しています。複雑なRAGパイプラインやベクトルDBを構築せずとも、コードやドキュメントを読ませるシンプルなアプローチで実用的なエージェントが構築できたと報告されています。実装言語にはTypeScriptが選ばれ、UIは全社員が利用するSlack上で展開されました。
特に注目すべきは、AIの回答が遅延する問題へのUX改善策として、「問い合わせ中」ステータスの可視化とプログレス表示を導入した点です。これにより、ユーザーはエージェントが動作していることを把握し、体感的な待ち時間を削減できました。
運用を通じて得られた「AIに賢く答えてもらうための3つの学び」は、ウェブアプリケーションエンジニアにとって示唆に富んでいます。第一に、インプットの質が全てであり、ノイズの多い過去の問い合わせ履歴ではなく、ソースコード、リリースノート（変更意図や背景）、ユビキタス言語集といった信頼できる情報に厳選すべきだと強調されています。第二に、「隠れたロジック」（例：SQLのWHERE句に埋め込まれたルール）はAIにとって見えにくく、ドメインロジックをコードとして明示的に表現することの重要性が再認識されました。これは、人間にとっても読みやすいコードがAIにとっても読みやすいという原則に繋がります。第三に、コードコメントはAIにとって「検索アンカー」として機能し、的確なコメントが関連コードのヒット率を高めると指摘されています。
さらに、GitHub APIのレートリミットという課題に直面した際、GitHub MCPサーバー経由でのコード取得から、エージェントが動作するサーバーに直接リポジトリを`git pull`してローカルファイルとして読ませるという、一見泥臭い方法に切り替えたことで、レートリミットの撤廃と劇的な速度向上が実現した運用上の工夫も紹介されています。
本記事の最大の学びは、「AIに正しく仕様を理解させるには、人間にとっても読みやすいコードとドキュメントが必要」という、本質的なソフトウェア開発の「良い習慣」の再確認にあります。AIのために整備された情報は、結果として新メンバーや非エンジニアにとっても有益な資産となる、と著者は締めくくっています。