Hono Conference 2025 | @scalar/hono-api-reference × Mastra で ドキュメントを自動更新する AIワークフロー構築してみた

Transcript

1. @scalar/hono-api-reference × Mastra で ドキュメントを自動更新する AIワークフロー構築してみた Hono Conference 2025 1
2. • エンジニア • Hono歴: 10ヶ月 🔥 • 出身地: 沖縄 • 趣味: MLB ⚾ • X: @shiromie_dev • LinkedIn: daiki-shiroma 城間 大幹（シロマ ダイキ） 自己紹介 2 Honoっぽいハンキングチェア🔥
3. 株式会社メドレー (HP) • Silver Sponsor • 9月にリリースした 新規事業 でHonoを使用 🔥 会社紹介 3
4. AIワークフロー 概要図 • API ServerからAPI仕様書を llms.txtで出力 GitHub Actions • llms.txtをS3でversion管理 • 変更差分から関連するシステム仕様書を 検索するためのクエリを生成 S3 Bedrock Knowledge Base OpenSearch Serverless • 取得したシステム仕様書と 変更差分からシステム仕様書を更新 Claude • PR作成 & Review 4 定期実行 Claude GitHub Engineer Update KB Merge 社内Wiki Build & Update RAG ※1 システム仕様書 = 非開発者も見るドキュメント ※2 API仕様書 = Honoを利用したAPI Serverから出力す る開発者向けのドキュメント • システム仕様書をOpenSearch Serverlessで保存 • 変更に関わるシステム仕様書を Bedrock KBから取得
5. AIワークフロー 概要図 • API ServerからAPI仕様書を llms.txtで出力 • システム仕様書をOpenSearch Serverlessで保存 • 変更に関わるシステム仕様書を Bedrock KBから取得 GitHub Actions • llms.txtをS3でversion管理 • 変更差分から関連するシステム仕様書を 検索するためのクエリを生成 S3 Bedrock Knowledge Base OpenSearch Serverless • 取得したシステム仕様書と 変更差分からシステム仕様書を更新 Claude • PR作成 & Review 5 定期実行 Claude GitHub Engineer Update KB Merge 社内Wiki Build & Update RAG ※1 システム仕様書 = 非開発者も見るドキュメント ※2 API仕様書 = Honoを利用したAPI Serverから出力す る開発者向けのドキュメント • @hono/zod-openapi ◦ zodでAPIを定義 ◦ APIファイルに仕様を直接記述 ◦ OpenAPI Swaggerを出力可能 • @scalar/openapi-to-markdown ◦ llms.txtに変換して出力
6. AIワークフロー 概要図 • API ServerからAPI仕様書を llms.txtで出力 • システム仕様書をOpenSearch Serverlessで保存 • 変更に関わるシステム仕様書を Bedrock KBから取得 GitHub Actions • llms.txtをS3でversion管理 • 変更差分から関連するシステム仕様書を 検索するためのクエリを生成 S3 Bedrock Knowledge Base OpenSearch Serverless • 取得したシステム仕様書と 変更差分からシステム仕様書を更新 Claude • PR作成 & Review 6 定期実行 Claude GitHub Engineer Update KB Merge 社内Wiki Build & Update RAG ※1 システム仕様書 = 非開発者も見るドキュメント ※2 API仕様書 = Honoを利用したAPI Serverから出力す る開発者向けのドキュメント • @hono/zod-openapi ◦ zodでAPIを定義 ◦ APIファイルに仕様を直接記述 ◦ OpenAPI Swaggerを出力可能 • @scalar/openapi-to-markdown ◦ llms.txtに変換して出力 // 例 const route = createRoute({ method: 'get', path: '/path', description: 'This is a sample API', request: { params: ParamsSchema, // Zod Schema }, responses: { 200: { content: { 'application/json': { schema: UserSchema, // Zod Schema }, }, description: '200 OK', }, }, });
7. AIワークフロー 概要図 • API ServerからAPI仕様書を llms.txtで出力 • システム仕様書をOpenSearch Serverlessで保存 • 変更に関わるシステム仕様書を Bedrock KBから取得 GitHub Actions • llms.txtをS3でversion管理し、差分検出 • 変更差分から関連するシステム仕様書を 検索するためのクエリを生成 S3 Bedrock Knowledge Base OpenSearch Serverless • 取得したシステム仕様書と 変更差分からシステム仕様書を更新 Claude • PR作成 & Review 7 定期実行 Claude GitHub Engineer Update KB Merge 社内Wiki Build & Update RAG ※1 システム仕様書 = 非開発者も見るドキュメント ※2 API仕様書 = Honoを利用したAPI Serverから出力す る開発者向けのドキュメント Claude に変更内容から機能群を推論させる 例えば POST samples / GET samples / DELTE samples/{id} のAPIに変更があった場合、 1機能の変更として認識させる
8. AIワークフロー 概要図 • API ServerからAPI仕様書を llms.txtで出力 • システム仕様書をOpenSearch Serverlessで保存 • 変更に関わるシステム仕様書を Bedrock KBから取得 GitHub Actions • llms.txtをS3でversion管理 • 変更差分から関連するシステム仕様書を 検索するためのクエリを生成 S3 Bedrock Knowledge Base OpenSearch Serverless • 取得したシステム仕様書と 変更差分からシステム仕様書を更新 Claude • PR作成 & Review 8 定期実行 Claude GitHub Engineer Update KB Merge 社内Wiki Build & Update RAG ※1 システム仕様書 = 非開発者も見るドキュメント ※2 API仕様書 = Honoを利用したAPI Serverから出力す る開発者向けのドキュメント • システム仕様書を自然言語で 検索可能なRAGを構築 • 目的 ◦ 「更新」の際に 適切なドキュメントを特定するため ◦ 変更差分の単なる要約ではなく、 システム全体としての変更内容を AIに理解させた上でドキュメントを更新する ため には、変更箇所に関わるドキュメントをcontextと して渡す必要があるため
9. AIワークフロー 概要図 • API ServerからAPI仕様書を llms.txtで出力 • システム仕様書をOpenSearch Serverlessで保存 • 変更に関わるシステム仕様書を Bedrock KBから取得 GitHub Actions • llms.txtをS3でversion管理 • 変更差分から関連するシステム仕様書を 検索するためのクエリを生成 S3 Bedrock Knowledge Base OpenSearch Serverless • 取得したシステム仕様書と 変更差分からシステム仕様書を更新 Claude • PR作成 & Review 9 定期実行 Claude GitHub Engineer Update KB Merge 社内Wiki Build & Update RAG ※1 システム仕様書 = 非開発者も見るドキュメント ※2 API仕様書 = Honoを利用したAPI Serverから出力す る開発者向けのドキュメント • 前STEPで生成したクエリにより Knowledge Baseを検索 • スコアの高いシステム仕様書を採用
10. AIワークフロー 概要図 • API ServerからAPI仕様書を llms.txtで出力 • システム仕様書をOpenSearch Serverlessで保存 • 変更に関わるシステム仕様書を Bedrock KBから取得 GitHub Actions • llms.txtをS3でversion管理 • 変更差分から関連するシステム仕様書を 検索するためのクエリを生成 S3 Bedrock Knowledge Base OpenSearch Serverless • 取得したシステム仕様書と 変更差分からシステム仕様書を更新 Claude • PR作成 & Review 10 定期実行 Claude GitHub Engineer Update KB Merge 社内Wiki Build & Update RAG ※1 システム仕様書 = 非開発者も見るドキュメント ※2 API仕様書 = Honoを利用したAPI Serverから出力す る開発者向けのドキュメント プロンプトの一例 ##Role あなたは、API仕様の変更をレビューし、ドキュメントへの影響を判断する経験豊富なソフ トウェアエンジニアです。 ## 既存ドキュメントの内容 ~~ ## API変更の詳細 ~~ ## タスク 上記の情報をもとに、ドキュメントに対してどのような操作が必要かを判断し、適切なツー ルを呼び出してください • Tool Use により出力を構造化 • 更新内容を静的なルールに基づき評 価
11. AIワークフロー 概要図 • API ServerからAPI仕様書を llms.txtで出力 • システム仕様書をOpenSearch Serverlessで保存 • 変更に関わるシステム仕様書を Bedrock KBから取得 GitHub Actions • llms.txtをS3でversion管理 • 変更差分から関連するシステム仕様書を 検索するためのクエリを生成 S3 Bedrock Knowledge Base OpenSearch Serverless • 取得したシステム仕様書と 変更差分からシステム仕様書を更新 Claude • PR作成 & Review 11 定期実行 Claude GitHub Engineer Update KB Merge 社内Wiki Build & Update RAG ※1 システム仕様書 = 非開発者も見るドキュメント ※2 API仕様書 = Honoを利用したAPI Serverから出力す る開発者向けのドキュメント 開発者は PRをレビューするだけ！
12. 12 成果物の一例 （Before） APIの差分
13. 13 成果物の一例 （After） 更新されたドキュメント
14. 成果 感想 • API仕様書をしっかり書くことが最重要 ◦ システム仕様書の更新をトリガーさせるため • API仕様書 → システム仕様書へ昇華させるのが難しい ◦ API差分だけでは変更に関するコンテキストが小さく、 正確にシステム仕様書を更新する難易度が高い ◦ PR単位やクライアントサイドの情報も含めた変更差分が理想 • 🔥 Hono Ecosystem 最高 🔥 約 30時間 → 15時間 と工数が半分に 💪（月単位）
 まとめ 14
15. ご清聴ありがとうございました！ 15
16. Mastraとは？ (https://mastra.ai) • AIエージェント開発のためのオープンソースフレームワーク • TypeScriptで実装 • 変更差分検知→ ナレッジベース検索 → システム仕様書の更新 → PR作成 のワークフローを構築で使用 • MastraサーバーをHonoで構築し実⾏ 参考: MastraでAIワークフロー構築 16
17. • @hono/zod-openapiでAPIを開発 • Zodを使用して値と型を検証 • APIファイルに直接API仕様を記述可 • /doc 下で OpenAPI Swaggerの API仕様書が利用可 import { OpenAPIHono, createRoute } from '@hono/zod-openapi'; const route = createRoute({ method: 'get', path: '/path', description: 'This is a sample API', request: { params: ParamsSchema, // Zod Schema }, responses: { 200: { content: { 'application/json': { schema: UserSchema, // Zod Schema }, }, description: '200 OK', }, }, }); const app = new OpenAPIHono(); app.openapi(route, (c) => { // API logic should be here }); app.doc('/doc', { openapi: '3.0.0', info: { version: '1.0.0', title: 'Sample API', }, }); 参考: API開発とAPI仕様書の生成① 17
18. • @scalar/openapi-to-markdown でAPI仕様書をllms.txtとして出力 • llms.txtをS3 にてversion管理 • システム仕様書更新のトリガーに import { createMarkdownFromOpenApi } from '@scalar/openapi-to-markdown'; // Get the OpenAPI document const content = app.getOpenAPI31Document({ openapi: '3.1.0', info: { title: 'Example', version: 'v1' }, }); const markdown = await createMarkdownFromOpenApi(JSON.stringify(content)); app.get('/llms.txt', async (c) => { return c.text(markdown); }); 参考: API開発とAPI仕様書の生成② 18
19. • @scalar/hono-api-reference により開発者用API仕様書を構築
 import { apiReference } from '@scalar/hono-api-reference'; app.get( '/api/docs', apiReference({ theme: 'kepler', spec: { url: '/api/openapi', }, forceDarkModeState: 'dark', hideDarkModeToggle: true, customCss: ``, // custom CSS }), ); 参考: API開発とAPI仕様書の生成③ • API仕様の確認から動作確認まで実施可能！ 
 19
20. 参考: Bedrock Knowledge Base によるRAGの実現 • システムの仕様についてMDX で記述 ◦ これが意外と重要。。 ◦ Docusaurus で社内向けWikiサイトを構築 • RAGの技術スタック ◦ Amazon Titan Embeddings （ベクトル化） ◦ OpenSearch Serverless （ベクトルDB） ◦ AWS Bedrock Knowledge Base （キーワード検索が可能） • Mastra自体は様々なVector DBに対応している（詳細はこちら） 20