Hono Conference 2025 | Building AI Workflow for Auto-Updating System Specification with @scalar/hono-api-reference and Mastra

Transcript

1. Building AI Workflow for Auto-Updating System Specification with @scalar/hono-api-reference and Mastra Hono Conference 2025 1
2. Daiki Shiroma • Engineer • Hono Experience: 10 months 🔥 • Hometown: OKINAWA • Interests: MLB ⚾ • X: @shiromie_dev • LinkedIn: daiki-shiroma About me 2 Hanging chair looks like Hono🔥
3. MEDLEY, INC. HR Platform (HP) • Silver Sponsor • Use Hono in a new product, launched in September 🔥 About us 3
4. Workflow Overview • Make API specs as llms.txt from API Server • Store System Spec in OpenSearch Serverless • Search and Retrieve Relevant System Specs from Bedrock KB GitHub Actions • Version Control llms.txt (S3) • Generate Query from API diff for Search S3 Bedrock Knowledge Base OpenSearch Serverless • Update System Specs based on Retrieved Docs and Diff Claude • Create & Review PR 4 Claude GitHub Engineer Update KB Merge Internal Wiki Build & Update RAG ※1 System specs = Documents for not only developers bun non-developers as well ※2 API specs = Documents for developers output from an API Server with Hono Daily Scheduled Run
5. Workflow Overview • Make API specs as llms.txt from API Server • Store System Spec in OpenSearch Serverless • Search and Retrieve Relevant System Specs from Bedrock KB GitHub Actions • Version Control llms.txt (S3) • Generate Query from Diff for Search S3 Bedrock Knowledge Base OpenSearch Serverless • Update System Specs based on Retrieved Docs and Diff Claude • Create & Review PR 5 Daily Scheduled Run Claude GitHub Engineer Update KB Merge Internal Wiki Build & Update RAG ※1 System specs = Documents for not only developers bun non-developers as well ※2 API specs = Documents for developers output from an API Server with Hono • @hono/zod-openapi ◦ Define API with zod ◦ Write API specs directly to the API file ◦ OpenAPI Swagger Spec is available • @scalar/openapi-to-markdown ◦ Generate API specs as llms.txt
6. Workflow Overview • Make API specs as llms.txt from API Server • Store System Spec in OpenSearch Serverless • Search and Retrieve Relevant System Specs from Bedrock KB GitHub Actions • Version Control llms.txt (S3) • Generate Query from Diff for Search S3 Bedrock Knowledge Base OpenSearch Serverless • Update System Specs based on Retrieved Docs and Diff Claude • Create & Review PR 6 Daily Scheduled Run Claude GitHub Engineer Update KB Merge Internal Wiki Build & Update RAG ※1 System specs = Documents for not only developers bun non-developers as well ※2 API specs = Documents for developers output from an API Server with Hono • @hono/zod-openapi ◦ Define API with zod ◦ Write API specs directly to the API file ◦ OpenAPI Swagger Spec is available • @scalar/openapi-to-markdown ◦ Generate API specs as llms.txt // e.g. 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. Workflow Overview • Make API specs as llms.txt from API Server • Store System Spec in OpenSearch Serverless • Search and Retrieve Relevant System Specs from Bedrock GitHub Actions • Version Control llms.txt (S3) • Generate Query from Diff for Search S3 Bedrock Knowledge Base OpenSearch Serverless • 取得したシステム仕様書と 変更差分からシステム仕様書を更新 Claude • Create & Review PR 7 Claude GitHub Engineer Update KB Merge Internal Wiki Build & Update RAG • Claude infers functional groups from API changes (= llms.txt diff) • For Instance, when api changes like, POST samples / GET samples / DELTE samples/{id} , happen, recognize these api changes mean modification as a single functionality ※1 System specs = Documents for not only developers bun non-developers as well ※2 API specs = Documents for developers output from an API Server with Hono Daily Scheduled Run
8. Workflow Overview • Make API specs as llms.txt from API Server • システム仕様書をOpenSearch Serverlessで保存 • 変更に関わるシステム仕様書を Bedrock KBから取得 GitHub Actions • Version Control llms.txt (S3) • Generate Query from API diff for Search S3 Bedrock Knowledge Base OpenSearch Serverless • 取得したシステム仕様書と 変更差分からシステム仕様書を更新 Claude • Create & Review PR 8 Daily Scheduled Run Claude GitHub Engineer Update KB Merge Internal Wiki Build & Update RAG • Provide RAG for system spec • Purpose ◦ To Identify appropriate system specs on updating ◦ To ensure updating properly, we needs to give the relevant system spec as context to the AI, to comprehend comprehensive changes across whole system, not just a summary of the modification differences. ※1 System specs = Documents for not only developers bun non-developers as well ※2 API specs = Documents for developers output from an API Server with Hono
9. Workflow Overview • Make API specs as llms.txt from API Server • Store System Spec in OpenSearch Serverless • Search and Retrieve Relevant System Specs from Bedrock KB GitHub Actions • Version Control llms.txt (S3) • Generate Query from Diff for Search S3 Bedrock Knowledge Base OpenSearch Serverless • Update System Specs based on Retrieved Docs and Diff Claude • Create & Review PR 9 Claude GitHub Engineer Update KB Merge Internal Wiki Build & Update RAG ※1 System specs = Documents for not only developers bun non-developers as well ※2 API specs = Documents for developers output from an API Server with Hono Daily Scheduled Run • Using query generated previous step, retrieve high-reliability system spec from Knowledge Base
10. Workflow Overview • Make API specs as llms.txt from API Server • Store System Spec in OpenSearch Serverless • Search and Retrieve Relevant System Specs from Bedrock KB GitHub Actions • Version Control llms.txt (S3) • Generate Query from Diff for Search S3 Bedrock Knowledge Base OpenSearch Serverless • Update System Specs based on Retrieved Docs and Diff Claude • Create & Review PR 10 Daily Scheduled Run Claude GitHub Engineer Update KB Merge Internal Wiki Build & Update RAG Prompt example ##Role You are an experienced software engineer responsible for reviewing API specification changes and determining their impact on documentation. ## Existing Documentation Content ~~ ## Details for API Changes ~~ ## Your task Based on the above information, determine what actions are required for the documentation and invoke the appropriate tool. ※1 System specs = Documents for not only developers bun non-developers as well ※2 API specs = Documents for developers output from an API Server with Hono • Enable structured output with Tool Use • Evaluate update content based on static rules
11. Workflow Overview • Make API specs as llms.txt from API Server • Store System Spec in OpenSearch Serverless • Search and Retrieve Relevant System Specs from Bedrock KB GitHub Actions • Version Control llms.txt (S3) • Generate Query from Diff for Search S3 Bedrock Knowledge Base OpenSearch Serverless • Update System Specs based on Retrieved Docs and Diff Claude • Create & Review PR 11 Claude GitHub Engineer Update KB Merge 社内Wiki Build & Update RAG Developers only review PR! ※1 System specs = Documents for not only developers bun non-developers as well ※2 API specs = Documents for developers output from an API Server with Hono Daily Scheduled Run
12. 12 Example of output（Before） API Diff
13. 13 Example of output（After） Updated system specs
14. Results Learnings • Make sure to Update API specs is key ◦ To trigger system spec updates • Difficult to elevate API specs to system specs ◦ API diff alone provides limited context, making accurate updates is difficult ◦ Ideal diff includes PR unit, client-side info not only server-side • Reduced monthly effort (approx. 30 hours) by 50% 💪
 Summary 14
15. Thank you for listening! 15
16. What is Mastra？ (https://mastra.ai) • Open-source framework for AI Agent development • Implemented in TypeScript • Build workflow: ◦ Diff Detection ◦ Search from KB ◦ System Specs Update ◦ Make PR • Mastra server built and executed with Hono Appendix: Building AI Workflow with Mastra 16
17. • Develop API with @hono/zod-openapi • Write API specs directly in the API file • Validate values and types with Zod • OpenAPI Swagger Spec is available at /doc endpoint 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', }, }); Appendix: API Development & API Specs Generation① 17
18. • Output API spec as llms.txt using @scalar/openapi-to-markdown • Version control llms.txt in S3 • Used as a trigger for system spec updates 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); }); Appendix: API Development & API Specs Generation② 18
19. • @scalar/hono-api-reference build API specs for developpers
 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 }), ); Appendix: API Development & API Specs Generation • Allows spec viewing and operational testing easily !
 19
20. Appendix: RAG with Bedrock Knowledge Base • System specs written in MDX ◦ very important more than we though ◦ Built internal Wiki with Docusaurus • Tech Stack in RAG ◦ Amazon Titan Embeddings （Vectorization） ◦ OpenSearch Serverless （Vector DB） ◦ AWS Bedrock Knowledge Base （allow keyword search for system specs） • Mastra supports various Vector DBs （details here） 20