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

● エンジニア ● Hono歴: 10ヶ月 🔥 ● 出身地: 沖縄 ● 趣味: MLB ⚾ ● X: @shiromie_dev ● LinkedIn: daiki-shiroma 城間 大幹（シロマ ダイキ） 自己紹介 2 Honoっぽいハンキングチェア🔥 

株式会社メドレー (HP) ● Silver Sponsor ● 9月にリリースした 新規事業 でHonoを使用 🔥 会社紹介 3 

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から取得 

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に変換して出力 

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', }, }, }); 

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機能の変更として認識させる 

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と して渡す必要があるため 

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を検索 ● スコアの高いシステム仕様書を採用 

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 により出力を構造化 ● 更新内容を静的なルールに基づき評 価 

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 成果物の一例 （Before） APIの差分 

13 成果物の一例 （After） 更新されたドキュメント 

成果 感想 ● API仕様書をしっかり書くことが最重要 ○ システム仕様書の更新をトリガーさせるため ● API仕様書 → システム仕様書へ昇華させるのが難しい ○ API差分だけでは変更に関するコンテキストが小さく、 正確にシステム仕様書を更新する難易度が高い ○ PR単位やクライアントサイドの情報も含めた変更差分が理想 ● 🔥 Hono Ecosystem 最高 🔥 約 30時間 → 15時間 と工数が半分に 💪（月単位）
 まとめ 14 

ご清聴ありがとうございました！ 15 

Mastraとは？ (https://mastra.ai) ● AIエージェント開発のためのオープンソースフレームワーク ● TypeScriptで実装 ● 変更差分検知→ ナレッジベース検索 → システム仕様書の更新 → PR作成 のワークフローを構築で使用 ● MastraサーバーをHonoで構築し実⾏ 参考: MastraでAIワークフロー構築 16 

● @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 

● @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 

● @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 

参考: Bedrock Knowledge Base によるRAGの実現 ● システムの仕様についてMDX で記述 ○ これが意外と重要。。 ○ Docusaurus で社内向けWikiサイトを構築 ● RAGの技術スタック ○ Amazon Titan Embeddings （ベクトル化） ○ OpenSearch Serverless （ベクトルDB） ○ AWS Bedrock Knowledge Base （キーワード検索が可能） ● Mastra自体は様々なVector DBに対応している（詳細はこちら） 20