Pepabo Tech Portal

Agentic Engineering時代における「作り上げる力」を鍛える！2026年度新卒エンジニア研修を実施しました

2026-08-05T00:00:00+09:00

はじめに

新卒エンジニア研修を担当しました、ugo、yukyan、てつを、どすこい、haruotsuです！

2026年度も新たな新卒エンジニアを迎え、講師陣一同で研修を実施しました。本記事では、各研修を設計・実施した講師陣が、カリキュラムの設計意図や工夫、実施の様子を紹介します。新卒エンジニア研修の設計に携わる方々の参考になれば幸いです。ぜひ最後までご覧ください。

はじめに
2026年度新卒エンジニア研修概要
Webアプリケーション研修(バックエンド)
フロントエンド研修
モデリング/設計研修
インフラ/仮想化研修
SRE研修
セキュリティ研修
1. セキュリティレビュー体験
2. 脆弱性診断の体験
機械学習＆データエンジニアリング研修
おわりに

2026年度新卒エンジニア研修概要

今年の新卒エンジニア研修は「Agentic Engineering時代における作り上げる力」をテーマに、次の3つを目的として設計しました。

自分が何を知らないかを知り、自律的に学び続けられる状態になる
配属後すぐに事業インパクトを出せる助走をつける
AIを前提とした技術選定・判断・実装ができ、顧客体験まで考えられるようになる

AIがコードを書いてくれる時代だからこそ、専門職としてのエンジニアとなることを重視しました。 AIの出力の表面をなぞるのではなく、背後の技術体系を理解し実践していること。将来の事業価値に、開発がどのように結びつくのか議論できること。リリースした先の運用まで責任を持てること。AIが速く賢くなっても、説明責任と運用責任は人間が引き受けるものだと考えました。

こうした狙いのもと、Webアプリケーション開発を足掛かりとしました。そのうえで、AIエージェントを用いた開発で重要となるもの、AIエージェントを組み込んだサービス開発で重要となるものを基準に、研修の単元を選定しました。

各研修は次の順で実施しました。

実施順	研修	日数	担当
1	Webアプリケーション研修(バックエンド)	5.5日	harachan、shiorin
2	フロントエンド研修	4日	nacal、てつを
3	モデリング/設計研修	3日	donokun、はらちゃん
4	インフラ/仮想化研修	9日	drumato、homirun、n01e0
5	SRE研修	5日	pochy、homirun
6	セキュリティ研修	2日	n01e0
7	機械学習＆データエンジニアリング研修	2日	miyakey

去年の新卒エンジニア研修について気になる方は、目指せシニアエンジニア！2025年度新卒エンジニア研修資料を一部公開しますもぜひご覧ください。

ここからは各研修の講師陣が、それぞれのカリキュラムを紹介します。

Webアプリケーション研修(バックエンド)

担当: harachan、shiorin

Webアプリケーション研修(バックエンド)は、新卒エンジニア研修の一番最初のステップとして、harachanとshiorinで担当しました。この研修でまず体感してもらいたかったことは3つあります。

Webアプリケーションを1から作る際にどんな言葉が出てきて何が行われているのかという「索引(インデックス)」を持つこと
チーム・複数人で開発を進めるとはどういうことかを知ること
AIとともにチーム開発を円滑に進める方法を考えること

「MVC」「マイグレーション」「セッション」といった言葉を全く知らない状態から、聞いたときに「ああ、あの辺りの話か」となんとなく思い浮かぶ状態までいければ十分、というくらいの解像度を目指しました。索引を先に持っておけば、その先の研修や配属後に実際に必要になったタイミングで、自分で調べにいけるはずだと考えたためです。

題材にはRuby on Railsを選びました。20年分のWeb開発のベストプラクティスが型として詰まっているためです。そのRailsチュートリアルを5.5営業日(昨年からおよそ半分に圧縮した日数)で完走することを、受講者全員が満たすべき要件としてセットしました。ただ内容の理解が置き去りにならないよう、Claude Codeとともに実装を進めながらPRを立ててもらいました。そのPRをまず受講者同士でレビューし、そのあと講師である私たちがレビューする、という2段階の体制をとりました。

受講者同士のレビューでは、誰かと一緒にPRを返しながら開発を進めるとはどういうことか、レビューではどんな観点を見るとよいか、そしてレビューにおける責任を実感してもらうことを狙いました。講師レビューでは、AIがただコードを書いて動いただけの状態にならないよう、「このパターンだったらどうなる？」「どうしてこの実装になっているんだろう？」と問いを投げて理解を深めてもらいました。同時に、普段の業務でどんな観点・コメントの仕方でレビューしているかを見て学び取ってもらうことも意識しました。

受講者同士でPRレビューを進めている様子

実際にやってみると、8名それぞれが自分の実装を進めながら、レビューという新しいタスクにも同時に向き合うことになり、そのバランスの取り方に苦戦する様子が見られました。

一番最初に受ける研修だからこそ、与えられた要件を甘く見ずにマストとして完遂する姿勢は、配属後の実務でも重要になると考えました。そこで研修の後半に一度立ち止まってもらい、受講者同士だけで相談する時間を設けました。講師はあえて入らず、残りの日数で完走するにはどうすればいいか、「完走」を具体的にどこに置くか、全員がその要件を満たすにはどうすればいいかを考えてもらいました。伝えた要件は、Railsチュートリアルの最後の章まで到達し、そこで作る機能がすべて動くようにすること、そして冒頭に掲げていたインデックスを少しでも貼れる状態にすることの2つです。

受講者たちが自分たちで考え直した進め方を、講師陣は「無理のない計画か」「要件を満たしているか」という観点を中心にレビューしました。残りの少ない日数で本当にやり切れるのか、不安に思っている部分は一緒に解消していきました。特に「インデックスを貼れる状態にする」という抽象的な要件は、何を満たせば達成と言えるのかを受講者側と講師側ですり合わせました。そうやってお互いに「これならいける」と思える状態を作ったうえで、残りの日数を進めてもらいました。

受講者たちが集まって見積もり会を行っている様子

この相談の中では、受講者たちから「PRを通じて講師側が身につけてほしいと考えていたスキルはもう掴めたので、ここから先は進捗を優先してレビューを任意にしたい」という提案がありました。当初必須としていた相互レビューについて、求められていたことの本質を自分たちで言語化し、それを踏まえて講師陣と交渉して合意を得て運用を変えたのです。マネージャーなど要件を出した相手と優先順位や認識をすり合わせ、説得して合意を得るという実務そのものの動きを研修の中で経験できていて、講師としてもとても嬉しい出来事でした。

その結果、全員が昨年の半分の日数である5.5営業日でRailsチュートリアルを完走できました。何より大きかったのは、受け身だった空気が「どうすれば達成できるか」を自分たちで考える能動的なマインドに変わったことです。講師があえて手を引いて、受講者同士で考える時間を作ったことが効いていました。講師側が進め方を決めすぎず、受講者自身に委ねたほうが、双方にとって良い結果につながる。この研修を通して、そういう気づきを得られました。最終日には振り返り会も開き、次の研修にどう向き合うといいかまで自分たちで考えられるようになっていました。新卒エンジニア研修に最終日まで一緒に取り組む「チーム」として、能動的に立ち向かう一歩を踏み出せたと感じています。

Webアプリケーション研修を担当したharachanとshiorin

Rubyコミュニティに触れるきっかけをつくるため、5/21に開催されたRailsTokyo#4へ、受講者全員で参加しました。業務時間扱いで参加し、社内外のRubyistと交流する時間も持てました。「コミュニティへ参加する楽しさ」を体感してもらう一歩になったと考えています。

AIと一緒に開発を進められる時代だからこそ、要件を自分ごととして捉えてチームでやり切る経験を、配属前の早い段階でしてもらえたことには大きな意味がありました。この研修で掴んだ「まずは自分たちで考え抜く」感覚を、今後の研修や実際の業務でも活かしてもらえれば嬉しいです。

フロントエンド研修

担当: nacal、てつを

今年のフロントエンド研修は「最高のフロントエンド」について考えてもらうことをテーマとし、nacalとてつをの2名で、4日間実施しました。

研修全体のテーマとして「Agentic Engineering時代における作り上げる力」が置かれている中で、AIを活用すれば、ある程度動くフロントエンドは誰でも容易に実装できるようになってきています。その中でフロントエンドを実装するエンジニアとして、最高のプロダクトにするには何をすべきか、何を意識すべきかを考えてもらいます。その周辺知識を入り口に深く潜り込んでいくことを主な目的として、このテーマを設定しました。

具体的な研修内容としては、SUZURI APIを利用したECサイトのWebフロントエンドを実装してもらい、それぞれ工夫した点や意識したポイントについて発表してもらいました。

成果発表の一例。VLMにブラウザを操作させてUIをタスクベースで定量評価し、失敗タスクの分析をもとにAIが生成した添削付きの改善モック

受講者には、Webフロントエンド未経験の人もいました。それでも成果発表では、アクセシビリティやWeb Core Vitalsといった定量的な指標を自ら発見して評価項目とする人や、理想のUXから逆算して技術スタックを提案する人が現れました。それぞれが自分のアプローチで「最高のフロントエンド」を考えて実現するところまでやり切ってくれて、短い期間で横断的にフロントエンド領域の理解を深められたと感じています。

「最高のフロントエンド」に唯一の正解はありません。だからこそ、それぞれが自分なりの切り口で問いを立て、答えにたどり着くまで試行錯誤したこと自体が、フロントエンドに限らずどんな領域でも通用する財産になるはずです。

AIが「動くもの」を素早く生み出せるようになった今、その先の「最高とは何か」を自ら問い、技術で形にする力の価値は、これまで以上に高まっていくと考えています。この研修が、受講者それぞれにとって「最高のプロダクトとは何か」を追い求め続けるための出発点になれば嬉しいです。

モデリング/設計研修

担当: donokun、harachan

設計研修は、ペパボの新卒エンジニア研修で「設計」を独立したコンテンツとして扱う初めての試みです。donokunとharachanの2名で、3日間実施しました。

配属後の受講者には、コードを書く前に「何をどう変えるか」を文書にまとめ、レビューを通じて合意してから実装に進む、という仕事の進め方が待っています。はじめて「設計を書いてみて」と言われたとき、そもそも何を出せば設計と呼べるのかがわからない。この最初のつまずきをなくすことを研修の目的に置き、ゴールを「Webアプリケーションへの変更の提案を書け、その提案の良し悪しを判断し、レビューを受けて補強できる状態」と定めました。

研修は「書き方」「考え方・伝え方」の2章で構成しました。

「書き方」は、設計を表現する道具を身につける章です。静的な構成を表すC4モデルの抽象化レイヤと、動的な振る舞いを表す図（シーケンス図、状態遷移図、データフロー図）を学び、実際に図を描いて講師のフィードバックを受けます。

「考え方・伝え方」は、表現された設計の良し悪しを判断する章です。品質特性、なかでも変更容易性と複雑さの関係を学びます。Railsチュートリアルで作ったアプリケーションへの機能追加を題材に、提案を書いてレビューを受けて改稿するまでを実践します。

最終日には、受講者が機能追加の実現方式を複数案比較した提案ドキュメントを書き上げ、レビューを受けて改稿するところまで完走しました。実務で設計を任されたときに何を作ることが求められているのか、その像を持って配属に向かってもらえたはずです。

配属後、施策を任された際に、この研修で体験した「要件を抽出して設計書に落とし込む」経験が活かせたようで、スムーズに業務を行えたという嬉しいフィードバックもありました。

課題も見つかりました。演習中、コーディングエージェントの提示する知識や意見に受講者が振り回される、という場面があったのです。AIの出力を自分の評価軸で判断するには、各技術領域の知識がもう少し必要でした。設計研修をエンジニア研修の後半に配置する、演習の題材を実際のプロダクトに近づける、といった改善案を来年に引き継ぎます。

インフラ/仮想化研修

担当: drumato、homirun、n01e0

インフラ/仮想化研修は、2年間続いていたコンテナ研修をさらに拡大した、今年度から新しく設計された研修です。drumatoとhomirun、n01e0の3名で、9日間実施しました。

ソフトウェアエンジニアに求められる貢献のベースラインはAIによって引き上げられました。それぞれのエンジニアは自身の専門性と関心領域についてパフォーマンスを出すだけではなく、自身の価値を提供するまでの一連のサイクルを完遂する、そのためにパフォーマンスの領域を広げる力が求められています。

そこで、本研修の前提を 今日において、知とパフォーマンスの領域はAIによって広げられる とおきました。価値提供に関わるすべてのプロセスに関われるエンジニアとして、不必要にレベルを下げずにインフラ/仮想化技術を学ぶ内容です。

具体的には、以下のような内容を含む研修として実施されました。

LinuxのNetwork namespaceを利用したネットワーク入門。VM上でNetwork namespaceを利用して仮想ホストを構築してもらいました。プロトコルキャプチャによるネットワークプロトコルの理解や、ルーティングの設定を体験してもらいました。
clone(2)を利用したミニマムなコンテナランタイム自作。受講者それぞれが好きな言語でコンテナランタイムを自作しながら、既存のコンテナランタイムと比較してもらいました。
Virtualization frameworkを利用したVM自作。コンテナ技術とのトレードオフを理解してもらうために、Virtualization frameworkを利用したVM作成を体験してもらいました。
Kubernetesクラスタの思想と設計から学ぶ実運用の課題。ここまでの技術の整理として、ペパボで主に採用されているKubernetesを仕組みから理解してもらいました。そのうえで、実際のサービス運用における関心と課題を導入しました。

講義全体を通して意識したことは、技術書やWeb上の記事などで当たり前に解説されているこれらインフラ技術について考察してもらうということでした。「このような技術がないとどう困るだろうか」「この技術は何を解決し、どのような関心を持ち込んだか」といった観点です。AI時代において特に重要なのは課題抽出ができ、意図が説明できることです。この具体的なシミュレーションとして適切な題材だったと考えています。

研修後半では、受講者それぞれに作りたいものを考えてもらい、講師と議論しながら1つのレポートを完成させてもらいました。テーマはAIエージェント用のサンドボックス/ロードバランサ/eBPFイベントトレース/PyTorch Compiler/Gateway API Controller/楕円曲線暗号など多彩でした。それぞれの技術特性と解決される課題について議論できました。

SRE研修

担当: pochy、homirun

過去二年間「オブザーバビリティ研修」として続いた枠でしたが、今年は満を持して「SRE研修」と名付けました。

その内容は「障害対応100本ノック」としました。この節では、実施した内容と設計意図、その効果を記します。

障害対応100本ノックの概要

この研修では、受講者には5営業日の間、システムの管理者として障害対応をしつづけることを求めました。

この研修で実施したことを説明します。準備として講師は研修用のKubernetesクラスタを用意し、その上に3つのサービスを稼働させました。このとき、それぞれのサービスには主に可用性の観点で脆弱な実装やアーキテクチャを複数（100個）仕込みました。また、それぞれのサービスのソースコードを管理するリポジトリは用意したものの、リリースフローの自動化やIaCは不十分な状態としました。研修初日に、受講者にそのクラスタへのadmin権限を与えました。講師は5営業日間、事前に仕込んだ障害が起きるようにシステムに負荷をかけ続けました。受講者には、比喩や誇張ではなく実際に100本の障害へ対応することを求めました。

この研修においてはロールプレイとして、受講者はそのシステムの管理者であるとしました。また、講師2名は、「Slackにはいるものの、たまたま2名とも遠くへ旅行に行っている」という設定にしました。すなわち、「詳しい人」は実際に作業できないが、「現場にいて権限がある人」がなんとかして障害へ対応しなければいけない、という状況設定です。

また、座学用のテキストも用意しました。ただ状況を与えるだけでは何をしたらいいか分からなくなる懸念があったので、リリース自動化や監視、可観測性の整備などに必要な知識はテキストファイルにして読める場所に配置しておきました。具体的にはArgoCD、GitHub Actions、Grafanaなどの技術要素と、それらが必要になる背景を読み物として執筆しました。

5営業日の最後の2時間程度は、ポストモーテムの時間としました。起きた障害に対して、何が起きていたのか、何がうまくいったか、次はどのようにしたらもっとうまくできるかを講師がファシリテーションしつつ受講者間で議論してもらいました。

設計意図

この研修は、ロールプレイによる実践を主として、SREのプラクティスをその身を以て学ぶことを目的としました。

研修設計を考える際に主にインスパイアされたのはAnthropicによるSREについての報告記事でした。曰く、複雑なシステムで根本原因を究明するためには「痛い目に遭う」必要があるとのことです。生成AI技術が全盛を極め続けるこの時代においては、知りたい技術や知識は湯水のように手に入ります。だからといって、SREで必要なトラブルシューティング能力がすぐさま手に入るわけではないと私は感じています。そこで、ひたすら「痛い目に遭う」ような研修を思いつきました。

3サービスは、講師がそれまでにペパボの中で運用を担当したサービスの中から、アーキテクチャが異なる3つを模したものにしました。様々なアーキテクチャのシステムに立ち向かえる能力を養うことと、実務ですぐに使える知識を獲得することがこの決定の目的です。

仕込んだ障害には、すべて過去にペパボの中で起きた障害の機序を使いました。ペパボの中ではポストモーテム文化が浸透しているため、過去の障害履歴を参照することが容易です。起こした障害の例は次のとおりです。

大量のN+1クエリによるレスポンス遅延
キャッシュ戦略の不備による参照データの競合
k8s podのliveness probeの瑕疵による可用性毀損

パフォーマンス問題やデータ不整合問題などさまざまなレイヤの問題を配置することによって、原因究明のために可観測性技術を習得しなければいけない状況を作りました。受講者には研修が完了した後に、起きた障害はすべて過去のポストモーテムから引用したものであることを伝えました。自分たちの対応が実務に繋がるものだと伝えること、そしてペパボのポストモーテム文化を知ってもらうことを目的とした設計です。

リリースフローの自動化やIaCが不徹底な状態から取り組んでもらったのは、ソフトウェアの偉大さを感じてもらうためです。SREのプラクティスの1つに、トイルの解消があります。自動化が何もない状況で障害対応をしてもなかなか捗りません。そこで、最初に対応が遅くなったとしても少しずつ自動化を進めることで、時間のレバレッジによって最終的には多量の成果を出すことができる経験をしてもらいたいという意図を込めました。

受講者8名に対して3サービスを用意した意図は、実際の運用で頻発するコミュニケーションを実践してもらうためです。3サービスが与えられたことで、受講者は自然と3チームに分かれました。しかし3サービスはKubernetesクラスタやDBインスタンス、ArgoCDサーバーを共有する構成になっていました。すなわち、「複数サービスが共有しているリソースがボトルネックになる」事象が発生します。これによって、チーム間でどのようにコミュニケーションをとってボトルネックの解消に取り組むと効果が出やすいのか、あるいは出にくいのかを体感してもらえる研修になりました。ペパボのエンジニア組織が掲げるバリューの1つに「すべてが自分ごと」というフレーズがあります。担当サービスの外だからという理由で誰かが直してくれるのを祈っているだけでは何も解決しないので、どうにかして直そうとする姿勢が必要であると知る機会にしてほしいという意図も込めました。

効果

概ね、期待した効果が得られたのではないかと考えています。

講師として印象的だったのは、チーム間での越境の動きです。チーム分けは講師が明示したものではなく自然発生的にできたものではあるものの、一度決まったチームを越境することは心理的な負担が大きいと私は思っています。そのような中で、共有リソースがボトルネックだと見抜いてチューニングに取り組む動きや、あるアプリケーションでのチューニング方法を受講者間で共有する動きが見えました。これは頼もしかったです。また、講師がちらっと口に出した「推測するな、計測せよ」や「監視で気付けない障害が起きていたら負け」といったフレーズがふりかえりの際に受講者の口からも出てきたことは講師冥利に尽きるなあと思いました。

一方で、AI時代と言っても、5営業日で100本は多いということもわかりました。実際に解消された障害は50本程度で、他は検知されつつも直しきれなかったり、そもそも検知すらされない障害もありました。次からは50本ノックに調整してもよさそうです。

セキュリティ研修

担当: n01e0

今年もセキュリティ研修を担当しました。セキュリティ対策室のn01e0です。日程は色々あって2日間での開催となりました。昨年と大きな違いはありませんが密度が高くなっています。

期間が短い為、座学はほとんど設けず導入にとどめ、ほとんどの時間をハンズオンに費やしてもらいました。

セキュリティレビュー体験

初日は他のイベントも重なっており、作業時間があまり多く取れなかったため、セキュリティレビュー体験を行いました。 Webアプリケーション研修で作成したリポジトリに対し、事前に私が作成した脆弱性のある機能追加のPRをレビューしてもらいました。

今回は受講者が8人いる為、それぞれのリポジトリに対して異なる機能や様々な脆弱性を埋め込むのが講師としての課題でした。しかし研修目的だと言うと、Agentもすんなり受け入れて意図的な脆弱性を埋め込んでくれました。気を使ってくれたのか、指示していない・意図していない脆弱性もいくつか埋め込んでくれました。助かります。

セキュリティレビューはもちろんですが、コードレビューをする際、「どのような意思決定の結果、マージされるコードが出来上がったのか」が大事だと私は考えています。

そのため、今回の研修では「一度出したPRを修正するのが面倒なVibe Coder」として振る舞い、以下の点を明示してもらうようにしました。

具体的に脆弱性の原因となっているコード
なぜそれが脆弱性となるのか
どういったリスクがあるのか
悪用の可能性はあるのか
どのように修正すれば良いのか
どんなテストを追加すればよいのか

これは暗に「PRの裏に相手のCoding Agentがいる」という現状に合わせた内容でもあります。レビューでの指摘を具体的にするほど、相手のAgentにも具体的な指示を伝えられます。

脆弱性診断の体験

昨年に引き続き、Rails製の脆弱なやられアプリの脆弱性を発見・修正してもらうハンズオンです。

私が目指す脆弱性診断の民主化を意識し、ツールやテクニックは共有しつつ、受講者主体で動いてもらいました。既にAgentの使い方が身についており、続々と大量の脆弱性を発見してくれます。教える事など無いんじゃないか？と感じる所ですが、先輩風を吹かせたいので頑張ります。

「XSSを見つけた」「LFIを見つけた」という所までは、Agentに簡単な指示を出すだけでもできます。しかし診断では「それらの脆弱性に最大でどういうリスクがあるのか」を理解・説明しなければなりません。そのうえで一般論でなく、今回のアプリケーションにおける具体的な攻撃を考えて、対応の優先度や方針を決めます。

「LFIで本来見えないはずのファイルが見える」で終わらせないことを意識してもらいました。「LFIで/proc/self/envを見るとDBのクレデンシャルが書いてある」「XSSで管理者アカウントのCookieを窃取できる」「マウントされたホストのディレクトリを操作できる」。こういった事を実際に動かしながら理解してもらえて良かったです。

機械学習＆データエンジニアリング研修

担当: miyakey

ペパボ研究所のmiyakeyです。機械学習＆データエンジニアリング研修として「AIエージェントを前提としたサービス設計と開発」を担当しました。

例年この研修では機械学習やAI活用の基礎知識を扱ってきましたが、今年はAIエージェントがサービス体験そのものを形づくり、開発プロセスの前提にもなりつつある状況を受けて内容を大きく組み替えました。狙いは、AIエージェントを「サービス体験の一部」として設計できること、そしてコーディングエージェントと協働しながら「何を作るか・何を満たすべきか」を自分たちで定義できることの2つです。AIから成果物を受け取るだけでなく、AIが投げかけてくる問いを受け取り、自分たちの判断基準を更新していける力を、設計と開発の両面から鍛えることを目的としました。

演習では、二人一組で「Webサービス内でユーザーまたは運用者を支援するAIエージェント機能を1つ設計・実装する」ことに取り組んでもらいました。作るものは完成度の高いアプリではなく、エージェントの振る舞いとその機序を説明できるプロトタイプです。設計にあたっては3つの要件を明示し、そのまま最終発表の評価軸としました。AIチャットや単純な自動化ではなくエージェントとして実現する理由があること（必然性）。Tool実行・状態保持・ワークフローとして実装可能であること（実現性）。どんな入力になぜそのToolを使い、なぜその応答になるのかを説明できること（了解性）です。「動くもの」はAIの力で誰でも作れる時代だからこそ、その振る舞いに必然性があり、機序を人間が説明できるかを問うことに重きを置いています。

実装は、Google Agent Development Kit（ADK）でToolを実装し、LM Studio上のローカルLLMに接続する制約を課しました。あえて手元のローカルモデルで動かすのは、強力なモデルなら雑な設計でもそれらしく動いてしまうためです。限られた性能で意図通りに動かそうとすると、Toolの切り分けや状態の持たせ方といった設計そのものと向き合わざるを得ません。エージェントの機序を自分の手で理解してもらううえで、この制約はよく効いたと感じています。

2日間の研修はDay1で設計とレビュー、Day2で実装・評価・発表という構成とし、「何を満たすべきか」を先に言語化する流れを体験してもらいました。最終発表では、設計と機序の理解を一緒に確かめました。短い期間ながら各チームが「この場面でこそエージェントが要る」という必然性を自分の言葉で説明し、ローカルLLMとToolで振る舞いを形にし、なぜそう動くのかを説明しきってくれました。この経験を、配属後のサービス開発でAIや機械学習を積極的に活用していく土台にしてもらえれば嬉しいです。

おわりに

2026年度の新卒エンジニア研修は、「Agentic Engineering時代における作り上げる力」をテーマに実施しました。AIとの開発が当たり前になった時代で求められる力を、各講師がそれぞれの領域で問い直すカリキュラムとなりました。

振り返ってみると、どの研修にも共通していたのは、AIの出力をそのまま受け取るのではなく、その背後にある技術体系や課題を自分の言葉で説明できることを受講者に求めていた点です。Railsチュートリアルを自分たちで計画を立て直して完走する、障害対応で「痛い目に遭う」、エージェントの振る舞いの必然性と機序を説明しきる。形は違えど、「動くものはAIが作れる。ではエンジニアは何に責任を持つのか」という問いに、受講者たちは正面から向き合ってくれました。

この記事が、新卒エンジニア研修の設計のヒントになれば幸いです。

ロリポップ！ゼロトラストリンクがLinuxとESP32に対応したのでStackChanで試してみる

2026-08-03T00:00:00+09:00

人とAIを安全につなぐGMOペパボの新サービス「ロリポップ！ゼロトラストリンク」の、Linux版とESP32版クライアントを公開しました。

これまでクライアントがあったのはmacOS、Windows、iOS、Androidで、どれも人が手で触る端末です。今回のLinux版とESP32版のリリースで、サーバとマイコンが加わりました。

PCからサーバ、IoTデバイスまで
これまでのIoTのつなぎ方との違い
StackChanに喋らせる
ESP32版の使い方
AIエージェントクラウドとつなぐ
おわりに

PCからサーバ、IoTデバイスまで

ロリポップ！ゼロトラストリンク（以下、ZTL）は、離れた場所にある機器同士をポート公開なしで直接つなぐサービスです。参加した機器にはネットワーク内だけで通用するIPアドレスが振られ、そのアドレスで相手に届きます。

Linux版はサーバやコンテナ用で、systemdで常駐させます。root権限もカーネルのTUNデバイスも使わないモードがあるので、権限を絞ったコンテナの中でも動かせます。

ESP32版はESP-IDFのコンポーネントです。後述する通り、既存のファームウェアに依存を1つ足して関数を3つ呼ぶと、マイコン自身がネットワークに参加します。センサーやロボットにESP32が載ってさえいれば、開発機や本番サーバと対等に通信できます。なお、ESP32版は実験的な位置づけでのリリースです。

これまでのIoTのつなぎ方との違い

IoTデバイスとクラウドのやり取りには、向きが2つあります。デバイスがクラウドのサービスを呼ぶ向きと、外からデバイスへ指示を送る向きです。

前者の定番は、クラウド側のサービスをインターネットへ公開し、デバイスに持たせたAPIキーで認証する構成です。世界中から届く窓口を開けておいて、キーの強さだけで守ることになります。後者は、NATの内側のデバイスに外から直接は届かないので、双方がMQTTのようなブローカーへ接続しておき、そこ経由で指示を押し込むのが定番です。どちらの向きでも、インターネットへの公開か、中継サービスの追加が要ります。

ゼロトラストリンクではデバイス自身がネットワークに参加するので、どちらの向きもアドレス指定の直接通信になります。デバイスはNATの内側のまま、ネットワーク上の他のノードから届くようになります。クラウド側のサービスも、インターネットに公開しておく必要がなくなります。

アクセス許可の単位は通信元のアドレスではなく、認証されたデバイスです。ZTLのダッシュボードからデバイスを一元管理できます。

StackChanに喋らせる

Linux版とESP32版のクライアントの利用例として、StackChanを題材に説明します。StackChanとは、オープンソース発の卓上ロボットで、今回はM5Stackの公式キット（型番K151）を組み立てて使いました。制御部はキット同梱のM5Stack CoreS3で、ファームウェアはここに書き込みます。ソースはkentaro/rino-stackchanにあります。

</source> ※現在の環境は動画再生に対応していません

StackChanを上図の構成で動かします。StackChanは話しかけられた声をマイクで拾ってZTLのESP32版クライアントを通じてネットワークに流し、返ってきたAIエージェントによる発話音声を鳴らします。音声認識、発話内容の生成、音声合成をするサーバはネットワークの向こう側にあって、ZTLのLinux版クライアントを通じてつながっています。

ESP32版の使い方

ESP32版の使い方について、より詳しく見ていきましょう。

依存を追加する

idf.py add-dependency "gmo-pepabo/lolipop-ztl"

導入は簡単で、上記の通りでlolipop-ztlコンポーネントとその下で動く通信の実装が入ります。コンポーネントはESP Component Registryで公開しています。

接続情報を用意する

ZTLネットワークへ参加するには、デバイスごとの接続情報が必要です。デバイス認証フロー（RFC 8628のOAuth 2.0 Device Authorization Grant）を通じて接続情報を入手します。テレビでサブスクにログインするとき、画面のコードをスマホで入力するあの方式です。

デバイスは起動するとまず保存済みの接続情報を探します。なければサービスへコードを要求し、受け取ったコードと承認URLを画面に出します。ユーザーがブラウザの承認ページでコードを入力すると、ポーリングしていたデバイスに接続情報が発行され、デバイスはそれを保存して接続します。

コードにするとこうなります。

ztl_config_t cfg;

if (!ztl_config_resolve(&cfg)) {
    // 初回起動。接続情報がまだ無いのでデバイス認証を実行する。
    // 起動直後は回線が未確立なことがあるため、成功するまで繰り返す
    while (!run_device_auth(&cfg)) {
        vTaskDelay(pdMS_TO_TICKS(10000));
    }
}

ztl_config_resolveが保存済みの接続情報を読みます。2回目以降の起動はこれだけです。

初回だけztl_device_authを呼びます。コードの表示手段はデバイスごとに違うので、そこはコールバックでホストアプリに任される作りです。

static void device_auth_prompt(const char *user_code,
                               const char *verification_uri,
                               const char *verification_uri_complete,
                               void *cb_arg) {
    const char *url = verification_uri_complete[0] ? verification_uri_complete
                                                    : verification_uri;
    face_show_auth_code(user_code, url);   // 画面にQRコードとコードを出す
}

static bool run_device_auth(ztl_config_t *cfg) {
    esp_err_t err = ztl_device_auth("rino-stackchan", "esp32 (ESP-IDF v5.4)",
                                    device_auth_prompt, NULL, cfg);
    face_hide_auth_code();
    return err == ESP_OK;
}

StackChanには画面があるので、今回作成した例では、デバイス承認のためのURLのQRコードと確認用コードを画面に表示しました。ユーザーがそれをスマホで読んで承認する流れです。画面のないデバイスなら、シリアルログにコードを出すことになります。

つなぐ

ztl_callbacks_t cbs = { .state_cb = on_state_change };
ztl_t *ztl = ztl_connect(&cfg, &cbs);

state_cbが状態変化のコールバックです。StackChanを用いた今回の例では、接続中や再接続中を画面のステータス行に出しています。

通信する

つながったら、相手のアドレスを指定して通信します。

// TCP
ztl_tcp_socket_t *sock = ztl_tcp_connect(ztl, host_ip, port, 15000);

// UDP
ztl_udp_socket_t *usock = ztl_udp_create(ztl, 9000);
ztl_udp_set_rx_callback(usock, on_udp_rx, NULL);

トンネルを通るのは、このztl_*のAPIで書いた通信だけです。ふだんのlwIPソケットは従来どおりの経路に出るため、esp_http_clientもトンネル越しには使えません。StackChanが叩く先はどれもHTTPなので、このTCPのAPIの上に、ヘッダを組んでContent-Lengthぶん読み切るだけの小さなクライアントを書きました。

UDPは、ネットワーク上の他のノードから話しかけるための口として開けています。

echo "こんにちは、調子はどう？" | nc -u <デバイスのアドレス> 9000

これをMacから打つと、返事が声で返ってきます。

コードの全体はkentaro/rino-stackchanにあります。CoreS3でつまずいた設定（PSRAMやTLSのバッファ、マイクとスピーカーがI2Sのクロックを共有する件）もREADMEに書いてあります。

AIエージェントクラウドとつなぐ

StackChanのAIとしての本体は、ロリポップ！AIエージェントクラウドで動いているHermes Agentです。ロリポップ！AIエージェントクラウドは、OpenClawやHermes Agentをクラウド上で動かせるサービスです。クラウドでの常時稼働と安全性を両立するために、外部にポートを公開せず、操作はWebの管理画面かSlackやDiscordなどのチャットに限っています。

そこでZTLの出番です。筆者は、Hermes Agentの動く環境にLinux版クライアントを入れて、ZTLのネットワークへ参加させています。参加すると、環境の中で127.0.0.1に閉じたままのチャットAPIや音声合成が、同じネットワークのStackChanからはアドレス指定で見えるようになります。どこにもポートを開けないまま、机の上のロボットとクラウドのAIが会話しています。

おわりに

Linux版とESP32版で、「ロリポップ！ゼロトラストリンク」はPCやモバイルだけでなく、サーバからIoTデバイスまで使えるようになりました。ESP32版の導入は簡単です。手元にESP32があれば、ぜひ何かひとつZTLのネットワークを通じてつないでみてください。

集約ジョブパターンで解決するモノレポCIのrequired check問題

2026-07-03T00:00:00+09:00

こんにちは！ロリポップ・ムームードメイン事業部ムームードメイングループの中村(@litencatt）です。

今回は、ムームードメインのモノレポで運用していたCIの統合ゲート（複数のCIの結果を1つの required check に集約する仕組み）を、GitHub Actionsネイティブの集約ジョブ方式に移行した話です。約500行のカスタムJavaScript + checks API + ポーリングで構成されていたプロキシ方式を廃止して、保守対象のコードは約335行に、障害モードは6種類まるごと消えました。

集約ジョブ方式は GitHub Actions の標準機能のみで構成されており、GitHub.com / GHES（GitHub Enterprise Server）を問わず、どのランナー環境でも導入できます。

TL;DR

モノレポで paths: フィルタ付き CI を required check（マージ前に成功が必須のチェック）にすると、該当パスに変更がない PR で skipped のまま永久ブロックされる（GitHub の既知制約）
これを解決するために checks API + ポーリングのプロキシを自前実装していたが、~500行のコードに6種の障害モードを抱える状態に
needs + if: always() の集約ジョブパターンに移行し、プラットフォームのネイティブ機能だけで required check 問題を解消
既存 CI は workflow_call（再利用可能ワークフロー呼び出し）で再利用し、コードの重複なく移行
移行時の注意点: concurrency group 衝突、workflow_run 非発火、check run 名の変化

TL;DR
背景：モノレポCIの「required check問題」
CI統合ゲートの変遷
理想形の発見とPoC
1. PoCで動作検証
新アーキテクチャ：CI オーケストレータ
1. 主要な設計決定
実装で遭遇した落とし穴と解決
移行結果の比較
他プロジェクトへの導入ガイド
まとめ

背景：モノレポCIの「required check問題」

ムームードメインのモノレポでも、ご多分に漏れずこの問題にぶつかりました。

GitHub Actions では paths: フィルタを使って「特定ディレクトリに変更があったときだけCIを実行する」ことができます。しかし、その CI をブランチ保護の required status check（PRをマージする前に成功が必須となるチェック）に登録すると、該当パスに変更がない PR では CI が起動せず skipped のまま永久にマージブロックされます。これは GitHub Community でも長く議論されている既知の制約です。

この制約に対する一般的な対処パターンは3つあります。

変更検知 + 集約ジョブ: 変更検知ジョブで対象サービスを判定し、条件付きで各CIを起動。末尾の集約ジョブ（needs + if: always()）で全体の合否を出し、これを required check にする。今回採用した方式
常時起動するプロキシジョブ: 常に起動するジョブが checks API（GitHub が提供する、チェック結果を外部から作成・更新できる REST API）やポーリングで各CIの結果を収集し、1つのチェック結果にまとめる。柔軟だが複雑化しやすい
全CIを常時起動: 全CIを毎回起動し、内部で skip 判定する。シンプルだがランナーのリソースを無駄に消費する

ムームードメインのモノレポには複数の言語・フレームワークで構成されたサービスが共存しており、それぞれに独立した CI ワークフローがあります。この記事では、パターン2（プロキシ方式）を採用してから最終的にパターン1（集約ジョブ方式）に移行するまでの変遷を紹介します。

CI統合ゲートの変遷

この統合ゲートは一度にできたものではなく、問題が出るたびに直して、を繰り返してきました。

第0世代：個別CIをrequired checkに登録（〜2026年3月）

最初期は、各サービスの CI ワークフローをそれぞれ独立した required check として登録していました。

この構成はシンプルですが、前述の「required check問題」がそのまま発生します。service-a/ のみ変更した PR では service-b-ci と service-c-ci が起動せず、永久にマージブロックされます。

第1世代：ポーリング方式のプロキシ（2026年3〜4月）

required check 問題を解決するため、常時起動するプロキシジョブを導入しました。

このジョブが変更パスを見て「どのCIが必要か」を判定し、checks API で該当 CI の完了をポーリングします。全ての必要な CI が成功すれば success、1つでも失敗すれば failure を返します。これを唯一の required check にすることで、不要な CI の skipped によるブロックを回避しました。

この時点での課題:

CI が完了するまで 最大約36分間ランナーを占有 する（ポーリングで待ち続けるため）
CI が36分以内に終わらないと タイムアウトで誤失敗 する（CI自体は成功しているのにゲートが失敗）
CI 完了からゲート反映まで 最大60秒の遅延 がある（ポーリング間隔）

第2世代：イベント駆動化（2026年6月）

ポーリングの課題を解消するため、workflow_run イベント（別のワークフローの完了をトリガーに起動する仕組み）を活用したイベント駆動方式に改修しました。

workflow_run イベントにより、各 CI の完了を即座に検知して Check Run を更新できるようになりました。ポーリングはバックストップに降格し、CI 完了からゲート反映までのラグがほぼゼロになりました。

しかし、この改修で新たな問題が発生しました。

checks API の cross-run update 禁止: GitHub が2025年2月に導入した仕様変更により、ある workflow run が作った Check Run を別の workflow run から更新できなくなり、本番で HttpError が発生しました。即日修正として、update ではなく常に create する方式に切り替えましたが、異なる run 間の通信に依存する設計自体が脆弱です
ブランチ保護の不整合: 自分たちの GHES 環境では、API で作成した独立 Check Run がブランチ保護の required check を満たさないケースがあり、commit status（もう1つのステータス報告手段）の併用が必要になりました。ゲートロジックがさらに複雑化しました
セキュリティ脆弱性の発見: レビュー中に、pull_request イベントが PR のブランチに含まれるワークフロー定義を実行するため、ゲートロジック自体を PR で改ざんできるバイパス経路が指摘されました。CODEOWNERS による保護を追加しましたが、補償的コントロールが増える一方でした

改修のたびに新たな問題が見つかり、補償的な対策が積み重なる一方でした。この時点でプロキシ方式は限界だと判断して、別のやり方を探し始めました。

理想形の発見とPoC

プロキシ方式の問題は、別ワークフローの結果を外部プロキシで集約するという設計そのものにありました。1つのワークフロー内で完結させられないか？と考えました。

調べていくと、GitHub Actions の標準機能だけで実現できることがわかりました。

workflow_call（再利用可能ワークフロー呼び出し）: 既存の CI ワークフローを別のワークフローから uses: で呼び出せる。ジョブ定義をコピーせず再利用が可能
needs + if: always(): needs で依存する子ジョブの結果を needs.*.result で参照でき、if: always() を付ければ子ジョブが skipped や failure でも集約ジョブ自体は実行される
skipped は成功扱い: 条件付きで起動しなかった子ジョブは skipped になり、集約ジョブ側で成功として扱える

数百行のカスタム JavaScript + checks API + ポーリングでやっていたことが、プラットフォームの標準機能だけでできるわけです。

PoCで動作検証

実際に PoC を作成し、以下の4項目を検証しました。

ローカルの reusable workflow（uses: ./.github/workflows/x.yml）が正常に呼び出せる
条件不成立で起動しなかった uses ジョブが needs.*.result == 'skipped' を返す
失敗した uses ジョブが needs.*.result == 'failure' を返す
needs + if: always() の集約ジョブが上記を正しく判定できる

結果は全て成功。PoC の作成から検証完了まで1時間程度でした。

新アーキテクチャ：CI オーケストレータ

移行後の構成は以下の通りです。ci-orchestrator.yml という1つのワークフローに全てが収まっています。

主要な設計決定

変更検知は git diff インライン。changes ジョブ内のシェルスクリプトで git diff --name-only を実行し、パスプレフィックスで判定しています。dorny/paths-filter のような外部 action は使わず、依存ゼロで構成しました。

steps:
  - uses: actions/checkout@v4
    with:
      fetch-depth: 0
  - name: Detect changed service areas
    id: detect
    run: |
      BASE="${{ github.event.pull_request.base.sha }}"
      HEAD="${{ github.event.pull_request.head.sha }}"
      CHANGED=$(git diff --name-only "$BASE"..."$HEAD")

      # service-a: service-a/** から除外パスを引く
      EXCLUDED="service-a/docs/"
      if echo "$CHANGED" | grep -E "^service-a/" | grep -vE "^($EXCLUDED)" | grep -q .; then
        echo "service_a=true" >> "$GITHUB_OUTPUT"
      elif echo "$CHANGED" | grep -qF ".github/workflows/service-a-ci.yml"; then
        echo "service_a=true" >> "$GITHUB_OUTPUT"
      else
        echo "service_a=false" >> "$GITHUB_OUTPUT"
      fi
      # 他のサービスも同様...

secrets は secrets: inherit。子ワークフローが多数の secrets を参照している場合、明示的な mapping は現実的ではありません。secrets: inherit で呼び出し元の secrets を全て継承させています。

service-a:
  needs: changes
  if: needs.changes.outputs.service_a == 'true'
  uses: ./.github/workflows/service-a-ci.yml
  secrets: inherit

集約ジョブの判定は needs.*.result のシェル判定のみ。外部スクリプトは不要です。

aggregate:
  needs: [changes, service-a, service-b, service-c]
  if: always()
  runs-on: ubuntu-latest
  steps:
    - name: Evaluate gate
      run: |
        FAIL=0
        for PAIR in \
          "service-a:${{ needs.service-a.result }}" \
          "service-b:${{ needs.service-b.result }}" \
          "service-c:${{ needs.service-c.result }}"; do
          NAME="${PAIR%%:*}"
          R="${PAIR#*:}"
          case "$R" in
            success|skipped) ;;
            *) echo "BLOCKED: $NAME=$R"; FAIL=1 ;;
          esac
        done
        [ "$FAIL" = "1" ] && exit 1
        echo "aggregate: SUCCESS"

ラベル管理・通知は別ジョブに分離。CI 失敗時のラベル付与や PR コメントでの通知は ci-labels ジョブとして aggregate の後段に配置しています。外部 API（GitHub API でのラベル操作等）のエラーが required check の安定性に影響しないようにするためです。

実装で遭遇した落とし穴と解決

workflow_call 化は概念的にはシンプルですが、実際にやると予想外の挙動にいくつか遭遇しました。

concurrency group 衝突問題

GitHub Actions の concurrency 設定は、同じグループ名のジョブが同時に走らないよう制御する仕組みです。workflow_call で呼ばれた reusable workflow 内では、github.workflow（現在のワークフロー名を返す変数）が呼び出し元のワークフロー名に解決されます。そのため、子ワークフロー側に concurrency: group: ${{ github.workflow }}-${{ github.ref }} が残っていると、全ての子ワークフローが同じ concurrency group に入り、相互にキャンセルされるという事態が発生しました。

解決までに複数のアプローチを試しました。

workflow_ref ベースの group 分離 → 不十分
caller input を渡して group を分離 → 環境によっては効かない
reusable workflow 側の concurrency を削除（最終解）

最終的に、concurrency 制御はオーケストレータ側の1箇所のみで行う構成に落ち着きました。

# ci-orchestrator.yml（呼び出し元）のみで制御
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

workflow_run が発火しなくなる問題

workflow_call 経由で実行された reusable workflow は独立した workflow run（ワークフローの個別の実行インスタンス）を生成しません。これは GitHub Actions の仕様です。

影響として、各CIの完了時に workflow_run トリガ（別ワークフローの完了を検知して起動する仕組み）で動いていた後続処理（CI失敗時のラベル管理、PR作者への通知等）が発火しなくなりました。

対応として、該当ロジックをオーケストレータ内の後段ジョブ（ci-labels）に移設しました。aggregate ジョブの outputs（どのCIが失敗したか）を受け取り、ラベルの付与・削除や通知コメントの投稿を行います。

check run 名の変化

workflow_call 経由で実行されたジョブの check run 名（PR のチェック一覧に表示される名前）は、「親ワークフロー名 / ジョブ名」 形式に変わります。例えば、従来 service-a-ci だった名前が CI / service-a になります。

これにより、旧来のジョブ名で完全一致の待機をしていた他のワークフロー（自動マージ等）が永久に pending になるという問題が発生しました。

対応として、他のワークフローの待機対象を個別の CI 名ではなく、集約ジョブ名の aggregate 1つに一本化しました。集約ジョブが成功 = 全CI成功なので、個別の CI 名を知る必要がなくなります。

変更検知の整合性

オーケストレータの git diff による変更検知と、各 CI の旧 paths: 条件は正確に整合させる必要があります。ずれがあると以下の問題が起きます。

集約ジョブが待つのに CI が起動しない: デッドロック（集約ジョブが永久に完了しない）
CI が起動するのに集約ジョブが待たない: ゲートバイパス（CI の結果を無視してマージできてしまう）

また、レビューで指摘されて気づいたのですが、CI 定義ファイル自身（.github/workflows/*-ci.yml）の変更も検知に含める必要があります。含めないと、CI 定義のみを変更する PR で対応する CI がスキップされてしまいます。

移行結果の比較

指標	プロキシ方式	集約ジョブ方式
CI 完了→ゲート確定のラグ	~30〜100 秒	数秒
ランナー占有（ゲート側）	最大 ~36 分	~1 分 + 数秒
保守対象コード	~500 行（JS + テスト + WF定義）	~335 行（WF定義のみ）
「CI 完了を待つ」仕組み	自前実装（ポーリング / イベント受信 / checks API）	GitHub の `needs` 機構
攻撃面	checks API + 外部スクリプト + ワークフロー名同定	*`needs..result` のシェル判定のみ**
既知の障害モード	6種（HttpError / bootstrap / 偽装 / 改ざん / timeout / 遅延）	構造的に発生しない
新規 CI 追加時の作業	3箇所の同期が必要	1ファイルに追記するだけ

一番大きいのは、既知の障害モードが構造的に発生しなくなったことです。プロキシ方式の問題は全て「別ワークフローの結果を外部プロキシで集約する」設計から来ていたので、その設計をやめれば問題も消えました。

他プロジェクトへの導入ガイド

この方式は GitHub Actions の標準機能のみで構成されており、外部 action への依存もありません。以下の手順で導入できます。

1. 各 CI の `on:` を `workflow_call` に変更

# before
on:
  pull_request:
    paths:
      - "service-a/**"

# after
on:
  workflow_call:

pull_request トリガと concurrency ブロックは削除します（前述の concurrency group 衝突を回避するため）。

2. オーケストレータを作成

変更検知（changes）→ 各 CI の条件付き呼び出し（uses:）→ 集約ジョブ（aggregate）の構成でオーケストレータを作成します。changes ジョブの検知パスは、各 CI の旧 paths: 条件と正確に整合させてください。

3. required check を `aggregate` に切り替え

ブランチ保護の required check を、旧来の個別 CI 名から aggregate に切り替えます。check run 名は checks API 上のジョブ名（UI 表示の「CI / aggregate」ではなく aggregate）です。

注意点

concurrency group の衝突: reusable workflow 側の concurrency を削除し、オーケストレータ側のみで制御する
workflow_run が発火しなくなる: workflow_run トリガで動いていた後続処理がある場合、オーケストレータ内に移設する必要がある
check run 名の変化: 他のワークフローで旧 CI 名に依存している箇所がないか確認する
変更検知の整合性: CI 定義ファイル自身の変更も検知に含める

まとめ

CI の統合ゲートは以下の変遷をたどりました。

個別 CI を required check に登録 → skipped で永久ブロック
ポーリング方式のプロキシ → ランナー長時間占有、タイムアウト誤失敗
イベント駆動化（workflow_run + checks API） → GitHub 仕様変更で HttpError、補償的対策の積み重ね
集約ジョブ方式（needs + if: always()） → 構造的に問題が発生しない

課題を直すたびに新しい問題が出てきて、最終的にプラットフォームの標準機能に任せるのが一番シンプルだった、という結論になりました。

移行時に遭遇した落とし穴（concurrency group 衝突、workflow_run 非発火、check run 名の変化）は workflow_call 化で踏みやすいものなので、先に知っておくと手戻りが減ると思います。

【レポート】毬藻企画とGMOペパボでWebアクセシビリティのイベントを開催しました！

2026-06-12T00:00:00+09:00

この記事について
イベントの背景・概要
当日の様子
1. アクセシビリティウォークスルー
2. 改善提案ディスカッション
イベントを振り返って
さいごに

この記事について

GMOペパボのtarutaruです。

2026年3月24日、アクセシビリティエキスパート集団である毬藻企画合同会社さんとの共催で、「【GMOペパボ・毬藻企画】スクリーンリーダーによる実践的アクセシビリティウォークスルー〜SUZURI byGMOペパボ編〜」というイベントを開催しました。

GMOペパボにとっては初めてのアクセシビリティイベント。この記事では、イベント当日の内容・様子など振り返っていきます。

イベントの背景・概要

GMOペパボでは、「人類のアウトプットを増やす」というミッションのもと、誰もが表現活動の機会を持てる世界を目指してアクセシビリティ推進にも取り組んでいます。ただ、組織としての浸透も各サービスの改善も、まだ「道半ば」というのが正直なところで、SUZURIもその例外ではありませんでした。

そんな折に、SUZURIでグッズ販売をしてくださっている毬藻企画の森田さんからお声がけいただきました。お話を重ねるなかで、「SUZURIのアクセシビリティ改善に取り組むなら、まずは現状の課題を知るところから。せっかくならオープンにやってみるといいんじゃないか」と、今回のイベントをご提案いただきました。

お話を受けて、弊社の事例を公開することが、アクセシビリティに取り組まれている方の学びや刺激になれば。そして、その外に向けた発信が巡り巡って社内のアクセシビリティ推進の後押しにもなれば。そんな期待もあって、今回共催という形でイベントを開催することにしました。

本イベントは、弊社のサービス「SUZURI byGMOペパボ」に対して、アクセシビリティウォークスルーを実施いただくイベントとして開催されました。あまり聞き馴染みのないワードだと思いますが、アクセシビリティウォークスルーは、認知的ウォークスルー（初見のユーザーがUIを一手順ずつ操作していくプロセスを追体験し、つまずきを抽出する手法）とエキスパートレビューを組み合わせたもので、毬藻企画さんによる造語になります。

当日は、全盲のエンジニアであるcatさん（野澤幸男さん）をゲストとしてお招きし、SUZURIをスクリーンリーダー（NVDA）で操作しながらウォークスルーを実施いただきました。ウォークスルー中は、毬藻企画の伊原さんがファシリテートと解説を担当。ウォークスルー後には、catさん・伊原さんに加え、毬藻企画の坂巻さん、SUZURIデザイナーの白石さん・並松さんも加わり問題点の振り返りと改善方法のディスカッションを行いました。

今回は現地参加のみの開催でしたが、デザイナー・エンジニアなど計40名の方にご参加いただきました。当日ご参加いただいた皆さんありがとうございました。

当日の様子

アクセシビリティウォークスルー

ウォークスルー本番の前に、比較材料としてまず晴眼者である私が、マウス操作でSUZURIの商品を購入するデモを行いました。SUZURI公式ショップで「忍者スリスリくんのパーカー」を探して、カートに入れ、注文を完了する。私は特に引っかかるところもなく注文を終え、晴眼者にとっては数分で完了するタスクでした。

これに続く形でcatさんにはアクセシビリティウォークスルーを始めていただきました。catさんには、SUZURI内の毬藻企画さんのショップで「アクセシスタディーズのアクリルスタンド」を購入する、というタスクを遂行してもらいました。商品を探して、カートに入れ、注文を完了させる。流れ自体は基本的に同じですが、それをスクリーンリーダーで行うことで先ほどの晴眼者のウォークスルーとどのくらいギャップがあるのか、を参加者の方には体感いただきました。

結果だけ言ってしまうと、ウォークスルー中には本当にさまざまな引っかかりが発生しました。一つの商品を購入するだけでこれだけのつまづきがあるのかと、普段から慣れ親しんだ自分たちのサービスが、まるで全然知らないサービスに見えるくらい衝撃を受けました。

ここですべてのつまづきを取り上げることはできないので1つだけピックアップさせていただきますが、イベントの中で会場が一番ざわついたのが、商品のサイズ選択の場面でした。

SUZURIでは、サイズを選ぶUIとしてHTMLのselect要素が使用されていました。これ自体はなんの違和感もないことですが、catさんがスクリーンリーダーでこのselect要素を操作してサイズを選択し、カートに入れるボタンを押してみたところ、カートに入れることができませんでした。カートに入れられなかった理由は”サイズが未選択だから”。先ほど確かにサイズを選択したのをこの目で確認したはずなのに、実際にはサイズは選ばれていない状態で、皆の頭に「？」が浮かぶ状況でした。

実際には何が起きていたかというと、実はこのselect要素、select要素としての機能は無効化されており、マウスのクリックでカスタムのドロワーUIを開くためのトリガーとして使用されていました。サイズ選択は、そのドロワー側で選択しないとサイズが確定しない仕様になっていたのです。ところが、スクリーンリーダー（キーボード）からは通常のselectとして操作も選択もできてしまったため「選んだのに、選べていない」という状態になっていたのです。

catさんはこの問題について、こう表現しました。

お風呂用洗剤はお風呂を洗うために作られたのに他の目的で使うと何が起こるかわからない。つまり、用法用量を守って使ってほしい。

ネイティブのselect要素には、ブラウザが保証する期待された動作があります。それを別の目的で使えば、期待どおりに動かないケースが出てくる。シンプルだけど重い指摘でした。（※ なお、このサイズ選択の問題については現在改善対応を進めており、近日中に修正される予定です。）

このサイズ選択のほかにも、フォーカスが移動せずモーダルウインドウの存在に気づけなかったり、支払い方法のラジオボタンのグルーピングが把握しづらかったり、広告バナーを誤クリックしてしまったりと、多くのつまずきが発生しましたが、それでもcatさんは最終的に注文を完了させ、無事に（？）ウォークスルーを終えることができました。

改善提案ディスカッション

ウォークスルーを終えた後は、catさん・伊原さん・坂巻さん・白石さん・並松さんの5名で、問題点の振り返りと改善方法を議論しました。モーダルウインドウへのフォーカス移動やアイコンのラベル付けなど、改善策はいくつも挙がりましたが、中でも印象に残ったのは、「グッズの探索しやすさ」をめぐるやり取りでした。

きっかけは、並松さんからの問いかけでした。ウォークスルー中、catさんが「アクリルスタンド」と書かれたリンクを押すと、毬藻企画ショップ内ではなく、SUZURI全体のアクリルスタンドの商品一覧（毬藻とは関係のないアクスタが並ぶ画面）に飛んでしまう、という場面がありました。並松さんはここを取り上げて、「グッズを探しやすくするには、どんな工夫があり得るんでしょうか？」と切り出しました。

これに対しcatさんは、商品一覧から選ぶこと自体は不便ではなかったとしつつ、「そもそも『デザインを選ばないとTシャツやアクスタが出てこない』構造に気づくまでに時間がかかった」と振り返りました。これを受けて、伊原さんがSUZURIの構造的な特徴をこう整理してくれました。

SUZURIには「Tシャツやアクリルスタンドといったハードウェアとしての商品」と「その上に乗るデザイン」という二つの概念があり、これらが同じ画面に同居しているので、自分がいま触れているのが商品の話なのかデザインの話なのかがユーザーには見えづらい。catさんがリンクを押して関係のない商品一覧に飛んでしまったのも、まさにこの概念の混在が原因。

また、地続きの話として白石さんから興味深い補足が入りました。SUZURIショップのトップに並ぶナビゲーション（「デザイン」「グッズ」など）は、実はショップオーナー側でカスタマイズできる仕様になっており、SUZURI公式ショップでは「グッズ」というタブが並んでいるのに対し、今回の毬藻企画ショップのナビゲーションには「グッズ」が存在していなかったそうです。catさんがショップの構造を掴むのに時間がかかった一因も、おそらくここにあったのではないか。同じSUZURIでも、ショップによって構造の理解しやすさが揺らいでしまう、そんな現状そのものが課題として見えてきた、そんな議論でした。

最初はUIの小さな引っかかりに聞こえた話が、気づけば「SUZURIというサービスの情報構造をどう設計するか」という、もう一回り大きな問いに変わっていく。アクセシビリティは「スクリーンリーダーでどう読み上げさせるか」だけではなく、その手前にある情報設計のレイヤーまで含めて考えるべきテーマなのだと、改めて気づかされた時間でした。一つの問いからここまで議論が広がっていくその奥行きが、ディスカッションの中でもとくに面白く、印象に残ったセッションでした。

イベントを振り返って

イベントを終えた今正直に書くと、「まだアクセシビリティの取り組みが浅いSUZURIを題材にして本当に大丈夫か」という不安は企画当初からずっとありました。社内でも協議を重ね結果開催に至りましたが、その不安は当日まで消えませんでした。

それでも、いざイベントが始まってみると、catさんや伊原さんがユーモアを交えながら明るくウォークスルーを進めてくださり、ディスカッションでも「どうすれば良くなるか」が前向きに議論されていきました。参加者の皆さんもその一つひとつに真剣に耳を傾けてくださっていて、会場には終始「目の前の事象に一緒に向き合う」良い空気が流れていました。SNS上でもハッシュタグ #pepabo_marimo で学びをポジティブにシェアしてくださり、読みながらほっとしたのを覚えています。

そうした空気のなかで、私自身もたくさんの学びを持ち帰った一日でした。中でも気づかされたのは、catさんが操作のほとんどの時間を「ページの構造を把握する／要素を把握する／情報を把握する」ことに費やしていた、という事実です。それはおそらく、晴眼者が視覚情報で無意識のうちにやっていることでもあります。この現状把握でつまずきが多いと、目的のアクションにはなかなかたどり着けないし、たどり着くまでに想像以上のエネルギーがかかってしまう。catさんはあらゆる手段を駆使して現状を把握されていましたが、それはエンジニアであるcatさんだからこその引き出しの多さでもあったはずです。誰もがこの把握をスムーズに行える状態を、当たり前のものとして目指していきたいな、と改めて感じる時間でした。

そしてもうひとつ、企画者として嬉しかったことがあります。当日参加していた弊社デザイナーが、翌日にはもう自分の担当サービスでアクセシビリティ改善のPRを立てていたのです。「社外に向けたイベントが、社内にもいい刺激になれば」とひそかに期待していたことが、想像よりずっと早く、目に見える形で動き出していました。

ディスカッションの終盤、catさんがこう言ってくださったのが、強く印象に残っています。

みんなでいいものができていけばいいんじゃないかな。

このひとことに、今回のイベントの空気が全部詰まっていたように思います。アクセシビリティは、一社あるいは一人だけで完結するテーマではありません。社内外で関わる人たちと一緒に課題に向き合いながら、少しずつ良いものに変えていく。今回のイベントが、その小さな一歩目になっていたら嬉しいです。

さいごに

以上、イベントのふりかえりでした。

改めて、catさん、毬藻企画の皆さん、当日ご参加くださった皆さん、そして運営に関わってくださった皆さん、本当にありがとうございました！

今回のイベントで見つかったSUZURIの課題は、これからひとつずつ改善していければと思っています。数も多いので時間がかかるものもあるかもしれませんが、ゆっくり見守っていただけたら嬉しいです。

ちなみに、初開催ということもあり、運営面での反省点・学びもありました。たとえば、UDトークの字幕にスクリーンリーダーの読み上げ音声まで一緒に拾われてしまい、品質に影響が出てしまったり。こうした学びは、次回以降のイベントでしっかり活かしていきます。

今回のイベントは、毬藻企画さんとcatさんのお力を大いにお借りしての開催となりました。弊社としても、アクセシビリティを通して良いものづくりにつながる取り組みを、これからも続けていきたいです。今回はスクリーンリーダーが切り口でしたが、ほかにもさまざまな角度からアクセシビリティに触れられる場を作っていき、皆さんと一緒に学ばせていただけたらと思っています。

アクセシビリティに関わるみなさんも、これから興味を持つみなさんも、一緒に学び、いいものづくりをしましょう！

GA 直後の Amazon S3 Files を SUZURI の本番 EKS に投入しコンテナイメージを 1/20 に圧縮した

2026-05-13T00:00:00+09:00

はじめに
課題：assets がコンテナイメージに焼き込まれる構造的問題
1. lens/lens2 が扱う assets とは
2. 移行前の状況
S3 Files という選択肢
1. 当初の候補: EFS + DataSync
2. 2026 年 4 月 7 日 GA: Amazon S3 Files
アーキテクチャ設計
1. 移行後の全体像
2. 設計のポイント
実装: lens2（Rust）で先行検証
ハマりどころ: EFS CSI Driver を動かしてわかったこと
計測結果
lens（JavaScript）へのロールアウト
1. lens ならではの差異: 上書きマウント方式
2. lens2 のノウハウがそのまま活きた
まとめ

はじめに

こんにちは、技術部技術基盤グループで SUZURI / minne / カラーミーショップなどのインフラをサービス横断で担当している shibatch です。

SUZURI は、オリジナルグッズを手軽に作れる・購入できるサービスです。ユーザーがアップロードした画像とあらかじめ用意した商品テンプレート（assets）を合成して、Tシャツやマグカップの完成イメージを生成する「画像合成サービス」が中核を担っています。この処理を担うのが lens と lens2 という 2 つのサービスです。

lens: JavaScript + ImageMagick 製の画像合成サービス（主力）
lens2: Rust + ImageMagick 製の画像合成サービス（新世代、lens から段階的に移行中）

2 サービスを合わせると 1 日最大約 420 万リクエスト（月間約 1.1 億リクエスト） を本番処理しています。

今回はそのlens/lens2に、2026年4月7日にGAとなったばかりの Amazon S3 Files を本番EKSに投入した話をします。トラフィックの少ないlens2でスモールスタートし、ゴールデンウィークをまたいでレイテンシの実績を積んでからlensへ展開する、という段階的なリスク設計で進めました。その過程と計測結果をお伝えします。

課題：assets がコンテナイメージに焼き込まれる構造的問題

lens/lens2 が扱う assets とは

lens/lens2 が扱う assets は、SUZURI で販売されるすべての商品テンプレート——Tシャツ・マグカップ・トートバッグなどの型紙画像、フォントファイル、ウォーターマーク画像——の集合です。新商品が追加されるたびに増え続けます。

移行前の状況

移行前は assets がそのままコンテナイメージに焼き込まれていました。

サービス	assets サイズ	コンテナイメージ（ECR 圧縮後）
lens2	1.7 GB	1.75 GB
lens	8.6 GB	10.3 GB

これはビルドパイプライン全体に悪影響を与えていました。lens のビルド時間を実測すると次のような内訳です。

ステップ	所要時間	原因
assets の S3 sync（毎ビルドダウンロード）	2m 08s	8.6 GB を毎回取得
コンテナビルド & push	11m 43s	assets を含む巨大レイヤーの書き出し
合計 (wall-clock)	14m 31s	CI の初期化・checkout 等含む

さらに Karpenter による新規ノード追加時（キャッシュなし）の Pod 起動には、イメージサイズが直撃します。

サービス	Image pull（cold）	Pod Scheduled→Ready（cold）
lens2	—	86〜102 秒
lens	5 分 03 秒	約 5〜5.5 分

トラフィックスパイク時にスケールアウトが発動しても、5 分間は新規 Pod を利用できません。SUZURI ではセール開始などをきっかけにトラフィックが急増するため、このスケールアウト遅延は売上機会の取りこぼしに直結します。

さらに問題があります。lens から lens2 への移行が進むと lens2 の assets も最終的に 8.6 GB 相当まで増える見込みでした。放置すれば状況はさらに悪化します。

S3 Files という選択肢

当初の候補: EFS + DataSync

assets をコンテナイメージから切り離し、ネットワークファイルシステム経由でマウントする構成を検討していました。当初の有力候補は Amazon EFS + AWS DataSync の組み合わせです。S3 を source of truth として、DataSync で定期同期した EFS ボリュームを EKS Pod に NFS マウントする構成です。

ただし、この方式には課題がありました。S3 への push が EFS に反映されるまで同期ラグが生じるため、assets の鮮度管理が複雑になります。また DataSync パイプライン自体の構築・運用コストも無視できません。

2026 年 4 月 7 日 GA: Amazon S3 Files

アーキテクチャを検討していたタイミングで、AWS が Amazon S3 Files を GA リリースしました。

S3 バケットをバックエンドとして、NFS 4.1/4.2 でマウントできるファイルシステムを提供するサービスです。

特性	値
プロトコル	NFS 4.1 / 4.2（POSIX セマンティクス準拠 ※ハードリンク等は非対応）
小ファイルの読み取り（キャッシュ済み）	数 ms 以下
キャッシュの読み取りスループット	4.7 GB/s
大ファイル（≥ 128 KB）	S3 から直接ストリーム（サービス全体の集約スループットテラバイト/秒）
対応コンピュート	EC2 / EKS / ECS / Lambda

決め手は DataSync が不要になる点でした。 S3 が source of truth を維持したまま NFS マウントできるため、同期ラグも余分なパイプラインも生じません。また Lambda でも S3 Files マウントが使えるため、将来的な Lambda 化の道筋も確保されます。

これならやろうとしていたことがスマートに実現できる、作り込もうとしていたDataSync部分をまるごと捨てて、S3 Filesへの切り替えを決めました。

アーキテクチャ設計

移行後の全体像

設計のポイント

assets をコードリポジトリから完全分離する

lens は以前から assets 専用のリポジトリが分離されており、デザイナーはそこに PR を出す運用でした。lens2 では assets がコードリポジトリに直接コミットされていたため、専用の assets リポジトリを新設してデザイナーの PR 先を切り替えました。

どちらも assets リポジトリへのマージ時に CI が aws s3 sync を実行し S3 に同期します。S3 Files 経由で Pod への反映はほぼリアルタイムです。

ゼロダウンタイムの段階的移行

Phase 1:  S3 バケット作成 + S3 Files 有効化
Phase 2a: 既存 Pod に S3 Files を追加マウントして動作確認
Phase 2b: assets の参照先を S3 Files に切り替え
Phase 2c: Dockerfile から assets を除外 → イメージ軽量化

Phase 2a がこの設計の安全弁です。既存イメージを稼働させたまま別パスに S3 Files をマウントし、ファイルの内容とレイテンシを確認します。マウントに失敗しても Kubernetes の rolling update により旧 ReplicaSet がそのまま動き続けるため、本番トラフィックへの影響はゼロです。なお Phase 2c 以降はイメージから assets が除去されるため、fat image への即時ロールバックは現実的ではありません。S3 Files の可用性に依存した設計となる点は後述します。

実装: lens2（Rust）で先行検証

EKS への S3 Files マウント

EFS CSI Driver v3.0 以降が S3 Files に対応しています。通常の EFS ボリュームと同じ CSI ドライバーを使いますが、設定にいくつか注意点があります（後述の「ハマりどころ」を参照）。

# PersistentVolume
apiVersion: v1
kind: PersistentVolume
metadata:
  name: lens2-assets
spec:
  capacity:
    storage: 100Gi
  accessModes:
    - ReadWriteMany
  mountOptions:
    - iam
  csi:
    driver: efs.csi.aws.com
    volumeHandle: "s3files:fs-xxxxxxxxxxxxxxxxx"  # s3files: プレフィックス必須
    readOnly: true

# Deployment への追加
volumeMounts:
  - name: s3-assets
    mountPath: /mnt/s3-assets
    readOnly: true
volumes:
  - name: s3-assets
    persistentVolumeClaim:
      claimName: lens2-assets
      readOnly: true

Phase 2a: 動作確認（並列マウント）

Phase 2a では mountPath: /mnt/s3-assets に S3 Files を追加マウントするだけです。アプリの参照先（ASSETS_DIR）はまだ変更しません。Pod に入って find /mnt/s3-assets | wc -l でファイル数を確認し、イメージ内の assets とファイル数が一致することを確かめます。

Phase 2b: ASSETS_DIR 切り替え

動作確認が取れたら、ConfigMap で ASSETS_DIR=/mnt/s3-assets に切り替えます。staging → production の順に適用し、各ステップで Datadog APM のレイテンシに異常がないことを確認します。

Phase 2c: Dockerfile から assets を除外

ASSETS_DIR の参照先が S3 Files に切り替わったことを確認してから、Dockerfile を変更します。

# Before（削除する行）
COPY ./assets ./assets
COPY --from=builder /lens2/assets /lens2/assets

# After: 上記 2 行を削除するだけ

これでイメージから assets が消え、ビルドと pull が劇的に速くなります。

ハマりどころ: EFS CSI Driver を動かしてわかったこと

ドキュメントに記載のない制約が複数ありました。同じ問題に直面した方の参考になれば幸いです。

1. inline (Ephemeral) CSI volume は非対応

Error: volume mode 'Ephemeral' not supported by driver efs.csi.aws.com

S3 Files のマウントには PersistentVolume / PersistentVolumeClaim が必要です。Pod spec へのインライン定義（Ephemeral volume）はサポートされていません。

2. `accessModes: ReadOnlyMany` が非対応

ReadOnlyMany と書くとマウントに失敗します。ReadWriteMany で宣言し、PV の csi セクション・PVC 参照（volumes セクション）・volumeMount の3か所すべてに readOnly: true を設定するのが実際に動作した方法です。上のコード例ではすべての箇所に記載されています。

3. `volumeHandle` に `s3files:` プレフィックスが必須

通常の EFS では fs-xxxxxxxxxxxxxxxxx のみ指定しますが、S3 Files では必ず s3files:fs-xxxxxxxxxxxxxxxxx の形式にしなければなりません。プレフィックスがないと通常の EFS ボリュームとして解釈されてマウントに失敗します。

4. `mountOptions: [iam]` の明示指定が必要

mountOptions への iam の明示指定は省略できません。 ドキュメント（docs/parameters.md）では optional な mountOption の一例として列挙されているだけで、デフォルト適用はされません。省略すると mount 時に access denied by server が返ります。

5. controller SA と node SA に別々の IAM ロールが必要

EFS CSI Driver の controller pod と node plugin pod はそれぞれ異なる ServiceAccount を使います。両方に S3 Files へのアクセス権を持つ IAM ロールを割り当てる必要があります。Pod Identity を使う場合も同様です。片方だけ設定してもマウントが通りません。

補足: S3 Files 障害時の挙動と監視

Phase 2c 以降、コンテナイメージから assets が除去されるため、S3 Files が停止すると lens/lens2 の画像合成機能が利用不可になります。fat image への即時ロールバックは assets をリポジトリから削除済みのため現実的ではなく、S3 Files の可用性に依存した設計です。

この点への対策を整理します。

可用性: S3 Files は EFS の基盤上に構築されており、データは S3 に保存されます。S3 の SLA は月次稼働率 99.9% で、複数 AZ に冗長化されています。S3 Files が停止しても S3 バケット内のデータは保全されるため、S3 Files の復旧後に自動復旧します
監視: Datadog APM・外形監視・レイテンシ監視により異常を検知できる体制を整えています
NFS オプション: soft マウントやタイムアウト設定で NFS I/O ブロック時の挙動を調整することもできますが、lens2 での本番運用で pod 起動やレイテンシに支障がなかったため、今回はデフォルト設定のまま運用しています。詳細は AWS 公式ドキュメントを参照してください

計測結果

lens2（Rust）本番実測

Before の値は assets をイメージに焼き込んでいた移行前の実測値です。

指標	Before	After	改善
ECR image size（圧縮後）	1.75 GB	86 MB	約 1/20
Build wall-clock	19m 19s	3m 43s	約 80% 削減
Pod Scheduled→Ready（cold）	86〜102 s	~39s	約 60% 削減
レンダリングレイテンシ（avg）	158.4 ms	153.8 ms	劣化なし（微改善）

lens（JavaScript）本番実測

Before の値は S3 Files 導入前の実測値です。

指標	Before	After	改善
ECR image size（圧縮後）	10.3 GB	507 MB	約 1/20
Build wall-clock	14m 31s	1m 48s	約 88% 削減
Image pull（cold）	5m 03s	11〜34s	約 1/9〜1/27
Pod Scheduled→Ready（cold）	5〜5.5 分	~45s	約 85% 削減
レンダリングレイテンシ（avg）	~5.1s	~4.9s	劣化なし

S3 Files の読み取りレイテンシ（lens 本番実測）

ファイル	サイズ	初回アクセス	warm（2 回目以降）
NotoSansJP-Medium.otf	4.6 MB	272 ms	~2.7 ms
watermark.png	15 KB	3.7 ms	~1.9 ms
checkerboard.png	14 KB	10.4 ms	~2.0 ms
item 画像（1.2 MB）	1.2 MB	247 ms	~2.4 ms
item 画像（15.4 MB）	15.4 MB	343 ms	~3.4 ms

初回アクセスはファイルサイズに比例して数 ms〜数百 ms かかります。2 回目以降はキャッシュに乗り 2〜3 ms 台に収まります。

アプリレイヤーへの影響はほぼゼロです。 lens のレンダリング処理は ImageMagick の CPU 処理がボトルネックで 1 リクエストあたり平均 5 秒程度かかります。warm 状態での 2〜3 ms という読み取りレイテンシは、処理時間全体に対して誤差の範囲です。Datadog APM でも本番レンダリングレイテンシに劣化は確認されませんでした。

lens（JavaScript）へのロールアウト

lens2 での実装・検証を経て、lens への展開は設計の差分を埋めるだけで済みました。

lens ならではの差異: 上書きマウント方式

lens2 では ASSETS_DIR 環境変数で assets パスを切り替えられましたが、lens は path.resolve('assets/...') + PM2 の cwd: '/suzuri-lens' でパスがハードコードされているため、環境変数による切り替えができません。

そこで S3 Files を /suzuri-lens/assets に直接マウント（既存パスを shadow するボリュームマウント） する方式を採用しました。アプリ側のコード変更は一切不要で、Kubernetes マニフェストの mountPath をアプリの参照パスに合わせるだけです。

# lens の場合: アプリの参照パスに直接マウントして shadow
volumeMounts:
  - name: s3-assets
    mountPath: /suzuri-lens/assets   # アプリの参照先パスと一致させる
    readOnly: true

Phase 2b では「既存イメージ（assets 焼き込み）+ S3 Files の上書きマウント」の並存状態になります。どちらのソースから読んでも内容は同一なので、切り替えは透過的です。Phase 2c で軽量イメージに更新すると、S3 Files が唯一の assets ソースになります。

lens2 のノウハウがそのまま活きた

EFS CSI Driver の制約はすべて lens2 の試行錯誤で解決済みでした。PV/PVC 設定・IAM ロール構成・マウントオプションを lens2 のマニフェストからほぼそのまま流用できたため、lens の展開は短期間で完了しました。

まとめ

成果サマリ

指標	lens2	lens
コンテナイメージ（ECR 圧縮後）	1.75 GB → 86 MB（約 1/20）	10.3 GB → 507 MB（約 1/20）
Build time	19m 19s → 3m 43s（80% 削減）	14m 31s → 1m 48s（88% 削減）
Pod 起動（cold）	86〜102s → ~39s（60% 削減）	5〜5.5 分 → ~45s（85% 削減）
レンダリングレイテンシ	劣化なし	劣化なし

上記はすべて 月間 1.1 億リクエストを処理する本番サービスでの実測値です。

S3 Files を選んでよかった点

DataSync が不要: S3 が source of truth を維持したまま NFS マウントができる。同期ラグの問題が根本的に存在しない
assets が増えてもイメージサイズが変わらない: 今後 lens2 の assets が増えてもコンテナイメージは変わらない
EKS / ECS / Lambda に横展開できる: 将来の Lambda 化へのパスが確保されている
GA 直後でも実用レベルに達している: 2026 年 4 月 7 日 GA、5 月 7 日には lens/lens2 両方で本番稼働中

さいごに

正直、GA直後のサービスを本番に入れることにはリスクがありました。GA当日は2026年4月7日で、lens/lens2両方がそろったのがゴールデンウィークを挟んだ5月7日です。実質3週間ほどでここまでできたのは、lens2でスモールスタートしてからlensへ展開するという段階的な設計が効いていたと思います。lens2のほうがトラフィックが少ないため、仮に問題が起きてもロールバックできる状態で実績を積み、ゴールデンウィーク中にレイテンシの計測実績を蓄積してからlensへ投入するという順序があったからこそ、自信を持って進められました。「新しいものを本番に入れることにリスクがある」のは、裏を返せば計測と段階的な設計で解決できる問題でした。この取り組みがどなたかの背中を押せたら嬉しいです。

GitHub Actionsの実行遅延をCloud SchedulerとCloud Workflowsで解消する

2026-05-11T00:00:00+09:00

こんにちは、技術部データ基盤チームの zaimy です。

GitHub Actionsの schedule: トリガーが大幅に遅延する問題を、Cloud SchedulerとCloud Workflowsで解消した話を書きます。最終的に採用した構成だけでなく、検討して棄却した構成と棄却理由も合わせて紹介します。

背景
検討した構成
なぜCloud KMSが必要なのか
実装
ハマりどころ
1. Import methodの選択 (-aes-256 の有無)
2. PEM → PKCS#8 DERへの変換
結果
その他の構成案
まとめ

背景

データ基盤チームでは、毎日の昼会で「前日のチーム内アップデート」を共有しています。GitHub Projectsのカードを更新者やステータスに基づいてアップデート種別 (例: 話題にすべき / 軽く触れる / ステータス移動) を自動分類してラベル付けするGitHub Actionsを、昼会の少し前に走らせる運用にしていました。このAction自体はラベル付与にClaudeを使う仕組みになっていて中身も面白いのですが、本記事の本題はそこではなく、起動タイミングの話です。

このActionは schedule: トリガー (cron) で平日11:55に実行するよう設定していましたが、実際の実行時刻は以下の通り、毎日60分以上の遅延がある状態でした。

日付	cron 設定 (UTC)	実際の実行時刻 (UTC)	遅延
4/22 Wed	02:55	03:55	+60min
4/21 Tue	02:55	03:57	+62min
4/20 Mon	02:55	04:02	+67min

GitHub Actionsの schedule: はベストエフォートで、混雑時は遅延・スキップされる仕様です。これは GitHub公式ドキュメントにも明記されています。

Note: The schedule event can be delayed during periods of high loads of GitHub Actions workflow runs. High load times include the start of every hour. If the load is sufficiently high enough, some queued jobs may be dropped.

そこで定刻で実行できるよう、スケジューラを別の仕組みに移すことにしました。

検討した構成

案A: Cloud SchedulerからGitHub APIを直接叩く

Cloud Scheduler は秒単位で定刻実行する信頼性の高いサービスです。HTTPターゲットを設定できるので、POST https://api.github.com/repos/{owner}/{repo}/actions/workflows/{workflow}/dispatches を直接叩けばよいのでは、というアイデアです。

棄却理由: Cloud SchedulerのHTTPターゲットの認証オプションは、

なし (公開エンドポイント向け)
OAuth2トークン (Google APIs専用)
OIDCトークン (Cloud Run / Cloud Functions向け)

の3つだけで、Authorization: Bearer <token> のような任意ヘッダの値をSecret Manager等から動的に解決する仕組みがありません。カスタムヘッダ機能はあるものの、ヘッダ値はジョブ定義に平文ハードコードになります。つまりこの構成だと認証に必要な情報をterraform stateに平文で書くことになるため、棄却しました。

案B: Cloud Schedulerから起動するCloud WorkflowsでGitHub Actionsを置き換える

Cloud Workflows はYAMLで処理を記述するワークフローエンジンで、HTTPコール、Secret Manager / KMS / BigQueryなどのGoogle Cloudサービス連携、リトライ、分岐、ループを書けます。

データ基盤のワークフロー構成変更によるコスト84%削減とCI 34倍高速化で紹介している通り、ペパボのデータ基盤ではすでにCloud SchedulerとCloud Workflowsの利用実績があるため、Cloud Workflowsで既存のActionを置き換えられるのでは、というアイデアです。

棄却理由: 既存のラベル付けスクリプトは500行程度のPythonで、

GitHub GraphQL APIのページネーション
Vertex AI ClaudeでのJSON分類
Issue / PRの差分計算 (前回のラベルと今回の分類差分だけを更新)

を含みます。これらをCloud Workflows YAMLで書き直すと、可読性と保守性が大きく落ちます。スクリプトをコンテナに入れて、Cloud Workflowsから呼び出すCloud Runで実行する構成もあり得ますが、本件の本質は定刻実行なので、ラベル付け本体の実装はGitHub Actions側に残すのが妥当と判断しました。

案C (採用): Cloud Schedulerから起動するCloud WorkflowsがGitHub Actionsをdispatchする

最終的に採用したのはこの構成です。Cloud WorkflowsからGitHub AppのJWT署名を行い、installation tokenを取得して dispatches を叩きます。

Cloud Scheduler (Asia/Tokyo, 55 11 * * 1-5)
  └─ Cloud Workflows
       ├─ Secret ManagerからGitHub App ID / Installation IDを取得
       ├─ Cloud KMS asymmetricSignでJWT (RS256) を署名
       │    └─ GitHub App private keyはCloud KMSにasymmetric keyとしてimport済み
       ├─ POST https://api.github.com/app/installations/{id}/access_tokens
       │    └─ installation tokenを取得
       └─ POST https://api.github.com/repos/{org}/{repo}/actions/workflows/{workflow}.yml/dispatches
             └─ GitHub Actionsを起動 (既存のラベル付けスクリプトが走る)

各レイヤの責務がきれいに分かれます。

レイヤ	責務
Cloud Scheduler	定刻実行
Cloud Workflows	GitHub認証 + dispatch (JWT署名 + token取得 + API呼び出し)
GitHub Actions	ラベル付け本体 (Vertex AI Claude / GraphQL / 差分計算)

なぜCloud KMSが必要なのか

GitHub Appのトークン取得フローはこうです。

App ID + private keyでJWT (RS256) を作る
JWTをBearerに付けて POST /app/installations/{id}/access_tokens → installation token (1時間有効) を取得
installation tokenをBearerに付けて dispatches を叩く

問題は、1.のRS256署名です。Cloud Workflowsの標準ライブラリ (base64, text, json など) には暗号系のライブラリが含まれておらず、RSA秘密鍵で署名する関数が無いため、秘密鍵をSecret Managerから取り出してもJWTを組み立てられません。

回避策は以下の通りで、今回はCloud KMSを利用しました。

案	署名する場所
Cloud KMS asymmetricSign	KMS (鍵をimportして署名APIを呼ぶ)
Cloud Run や Cloud Run Functionsを挟む	Python `pyjwt` 等で署名

実装

Cloud KMS asymmetric keyの作成 (terraform)

resource "google_kms_key_ring" "workflows" {
  name     = "workflows"
  location = var.region
}

resource "google_kms_crypto_key" "github_app" {
  name     = "github-app-private-key"
  key_ring = google_kms_key_ring.workflows.id
  purpose  = "ASYMMETRIC_SIGN"

  # 既存の GitHub App private key を後から import するため初期バージョンは作らない
  skip_initial_version_creation = true

  version_template {
    algorithm        = "RSA_SIGN_PKCS1_2048_SHA256"
    protection_level = "SOFTWARE"
  }
}

resource "google_kms_crypto_key_iam_member" "github_app_signer" {
  for_each = toset([
    "prod-serviceaccount@{project}.iam.gserviceaccount.com",
    "test-serviceaccount@{project}.iam.gserviceaccount.com",
  ])

  crypto_key_id = google_kms_crypto_key.github_app.id
  role          = "roles/cloudkms.signerVerifier"
  member        = "serviceAccount:${each.value}"
}

GitHub Appのprivate keyをCloud KMSにimport

GitHub Appは外部公開鍵の登録を許さない (常にGitHub側で鍵を生成する) ので、既にSecret Manager上に登録してあるprivate keyをCloud KMSにimport jobで取り込みます。

# 1. import job を作成する。AES wrapping を含む -aes-256 つきを使う。
gcloud kms import-jobs create import-github-app \
  --location=us-central1 --keyring=workflows \
  --import-method=rsa-oaep-3072-sha256-aes-256 --protection-level=software

# 2. import job が ACTIVE になるまで数分待つ。
gcloud kms import-jobs describe import-github-app \
  --location=us-central1 --keyring=workflows \
  --format='value(state)'

# 3. private key を Secret Manager から取得して PKCS#8 DER に変換する。
#    Secret Manager 上は GitHub から download した PKCS#1 PEM 形式だが、
#    --target-key-file は PKCS#8 DER binary を要求するため変換が必要。
gcloud secrets versions access latest \
  --secret=github-app-private-key-secret \
  --out-file=/tmp/gh_app.pem
openssl pkcs8 -topk8 -nocrypt -inform PEM -in /tmp/gh_app.pem -outform DER -out /tmp/gh_app.der

# 4. private key を import する。
gcloud kms keys versions import \
  --import-job=import-github-app \
  --location=us-central1 --keyring=workflows \
  --key=github-app-private-key \
  --algorithm=rsa-sign-pkcs1-2048-sha256 \
  --target-key-file=/tmp/gh_app.der

# 5. 一時ファイルを削除する。
rm /tmp/gh_app.pem /tmp/gh_app.der

Cloud WorkflowsのYAML

JWT構築 → Cloud KMS署名 → installation token取得 → dispatchの流れをそのまま書き下します。

main:
  params: [args]
  steps:
    - init:
        assign:
          - project_id: ${sys.get_env("GOOGLE_CLOUD_PROJECT_ID")}
          - github_app_id_secret: ${args.github_app_id_secret}
          - github_app_installation_id_secret: ${args.github_app_installation_id_secret}
          - kms_key_version_name: ${args.kms_key_version_name}
          - target_repo: ${args.target_repo}
          - target_workflow_file: ${args.target_workflow_file}
          - target_ref: ${args.target_ref}

    - get_github_app_id_secret:
        call: googleapis.secretmanager.v1.projects.secrets.versions.access
        args:
          name: ${"projects/" + project_id + "/secrets/" + github_app_id_secret + "/versions/latest"}
        result: app_id_secret_response
    - decode_github_app_id:
        assign:
          - github_app_id: ${int(text.decode(base64.decode(app_id_secret_response.payload.data)))}

    - get_github_app_installation_id_secret:
        call: googleapis.secretmanager.v1.projects.secrets.versions.access
        args:
          name: ${"projects/" + project_id + "/secrets/" + github_app_installation_id_secret + "/versions/latest"}
        result: installation_id_secret_response
    - decode_github_app_installation_id:
        assign:
          - github_app_installation_id: ${text.decode(base64.decode(installation_id_secret_response.payload.data))}

    - build_jwt_header_and_payload:
        assign:
          - now_seconds: ${int(sys.now())}
          - jwt_header_obj:
              alg: "RS256"
              typ: "JWT"
          - jwt_payload_obj:
              iat: ${now_seconds - 60}
              exp: ${now_seconds + 480}
              iss: ${github_app_id}
          - jwt_header_json: ${json.encode_to_string(jwt_header_obj)}
          - jwt_payload_json: ${json.encode_to_string(jwt_payload_obj)}
          - jwt_header_b64_std: ${base64.encode(text.encode(jwt_header_json))}
          - jwt_payload_b64_std: ${base64.encode(text.encode(jwt_payload_json))}
          - jwt_header_b64: ${text.replace_all(text.replace_all(text.replace_all(jwt_header_b64_std, "+", "-"), "/", "_"), "=", "")}
          - jwt_payload_b64: ${text.replace_all(text.replace_all(text.replace_all(jwt_payload_b64_std, "+", "-"), "/", "_"), "=", "")}
          - jwt_signing_input: ${jwt_header_b64 + "." + jwt_payload_b64}
          - jwt_signing_input_b64: ${base64.encode(text.encode(jwt_signing_input))}

    - sign_jwt_with_kms:
        call: http.post
        args:
          url: '${"https://cloudkms.googleapis.com/v1/" + kms_key_version_name + ":asymmetricSign"}'
          auth:
            type: OAuth2
          body:
            data: ${jwt_signing_input_b64}
        result: kms_sign_response

    - assemble_jwt:
        assign:
          - jwt_signature_b64_std: ${kms_sign_response.body.signature}
          - jwt_signature_b64: ${text.replace_all(text.replace_all(text.replace_all(jwt_signature_b64_std, "+", "-"), "/", "_"), "=", "")}
          - jwt: ${jwt_signing_input + "." + jwt_signature_b64}

    - exchange_jwt_for_installation_token:
        call: http.post
        args:
          url: '${"https://api.github.com/app/installations/" + github_app_installation_id + "/access_tokens"}'
          headers:
            Authorization: ${"Bearer " + jwt}
            Accept: "application/vnd.github+json"
            X-GitHub-Api-Version: "2022-11-28"
            User-Agent: "google-cloud-workflows"
        result: installation_token_response
    - extract_installation_token:
        assign:
          - installation_token: ${installation_token_response.body.token}

    - dispatch_workflow:
        call: http.post
        args:
          url: '${"https://api.github.com/repos/" + target_repo + "/actions/workflows/" + target_workflow_file + "/dispatches"}'
          headers:
            Authorization: ${"Bearer " + installation_token}
            Accept: "application/vnd.github+json"
            X-GitHub-Api-Version: "2022-11-28"
            User-Agent: "google-cloud-workflows"
          body:
            ref: ${target_ref}
        result: dispatch_response

    - log_dispatched:
        call: sys.log
        args:
          text: '${"Dispatched workflow " + target_repo + " " + target_workflow_file + " ref=" + target_ref}'
          severity: INFO
    - return_result:
        return: '${"dispatched: " + target_repo + " " + target_workflow_file}'

ポイントを補足します。

JWTのbase64url変換: Cloud Workflowsの base64.encode は標準base64 (+, /, =) を返すので、text.replace_all を3段ネストしてbase64url (-, _, パディングなし) に変換します。
Cloud KMS asymmetricSignの呼び出し: RSA_SIGN_PKCS1_2048_SHA256 は data フィールドに署名対象を渡せばKMS側でハッシュ計算と署名をやってくれます。

ハマりどころ

Import methodの選択 (`-aes-256` の有無)

最初 --import-method=rsa-oaep-3072-sha256 で import-job を作ったところ、gcloud kms keys versions import で

ERROR: ('target-key-file', "The file is larger than the import method's maximum size of 318 bytes.")

と弾かれました。素の rsa-oaep-3072-sha256 はRSA-OAEPで直接wrapできる最大サイズが318バイトしかなく、PKCS#8 DERのRSA 2048 private key (1200バイト超) は入りません。正解はAES wrappingを組み合わせる rsa-oaep-3072-sha256-aes-256 です。これだとAESでkey materialをwrapし、AESキーをRSA-OAEPでwrapする2段構成になり、大きな鍵もimportできます。

なお、import-job はimmutableで明示削除APIがありません (作成から3日でexpireする)。method指定を間違えると同名でやり直せないので、suffix変更 (-v2 等) で逃げる必要があります。

PEM → PKCS#8 DERへの変換

--target-key-file にはPKCS#8形式のDER (binary) でエンコードされた鍵を渡す必要があります。Secret Managerに保存していたGitHub Appのprivate keyはPEM形式 (PKCS#1) だったので、

openssl pkcs8 -topk8 -nocrypt -inform PEM -in /tmp/gh_app.pem -outform DER -out /tmp/gh_app.der

で変換してから渡しました。最初これを忘れて state: IMPORT_FAILED になり、importFailureReason: The key material in the import request couldn't be unwrapped or wasn't formatted correctly で落ちました。reimportEligible: true だったので同じversion番号に対して再importできました。

結果

定刻に「Cloud Scheduler実行 → Cloud Workflows実行 → Actions起動」まで一連の流れが安定動作するようになりました。Cloud Workflowsの実行は数秒で完了しています。

また、副次的な収穫として、Cloud KMS asymmetricSign経由でGitHub App JWTを署名するパターンが手元に残ったので、今後Cloud WorkflowsからGitHub APIを叩きたい別ユースケースがあれば容易に再利用できます。

その他の構成案

データ基盤チームでは既存資産としてCloud SchedulerとCloud Workflowsの組み合わせにおけるアラート実装や障害対応フローが存在するためCloud Workflowsを採用しましたが、制約がない場合はCloud SchedulerとCloud Run Functionsによる実装も十分選択できそうです。

まとめ

GitHub Actionsの schedule: トリガーは便利ですが、定刻実行が要件のジョブには使えません。

Cloud Schedulerで定刻実行させる
Cloud Workflowsで「GitHub認証 + dispatch」を担当する
Cloud KMSにGitHub App private keyを取り込んでJWT署名する

の3レイヤ構成にしたことで、ベストエフォートの実行から定刻実行に切り替えられました。

「Cloud SchedulerからGitHubを直接叩く」「Cloud Workflowsで全部やる」など、いくつかの代替案を比較検討した結果、責務がきれいに分かれて既存の運用基盤に乗るこの構成に落ち着きました。

Cloud KMSに鍵をimportする手順 (import-method、AES wrapping、PEM→PKCS#8 DER変換、IMPORT_FAILED時の再import) には地味なハマりどころが多いので、同じ構成を組む方の参考になれば嬉しいです。

データ基盤のワークフロー構成変更によるコスト84%削減とCI 34倍高速化

2026-05-11T00:00:00+09:00

技術部データ基盤チームの@zaimyです。

ペパボの社内データ基盤「Bigfoot」では、2020年にDigdagから移設して以来約5年間にわたりCloud Composer（Managed Apache Airflow）をワークフローエンジンとして運用してきましたが、2026年1Qをもって別構成に移行しました。本記事では、Cloud Composerから3つのマネージドサービスへ移行した経緯と、その効果について紹介します。

Cloud Composerで動いていた3つのワークロード
なぜ撤退したのか
移行先コンポーネントの紹介
コスト比較
開発効率比較
運用面の比較
エラーレート比較
まとめ

Cloud Composerで動いていた3つのワークロード

データ基盤ではCloud Composer上で主に以下の3つのワークロードを動かしていました。

dbtによるデータ変換（Cosmos経由でAirflow DAG上で実行）
事業DBからBigQueryへの同期
dbt以外のデータ変換や機械学習パイプラインなどその他のオーケストレーション

なぜ撤退したのか

3つの課題が重なったため、2026年1Qでの撤退を決定しました。

1. Agentic AI readyになるためにdbtを身軽にしたい

技術部の方針「Agent Ready」に基づき、AIエージェント前提の技術基盤づくりを進めるにあたって、dbtでSSoTなデータマートを作った上でAgentic AIによる分析を実現したいと考えています。そのためにdbtをより身軽に使いたいのですが、Airflow上でdbtを実行する構成はオーバーヘッドが大きく、AIを用いた開発運用においてフィードバックループが遅い状態でした。

2. コストの膨張

Cloud Composer 2からCloud Composer 3への移行や、使用量の増加により、月額コストが数十万円に膨張していました。

3. 運用負荷の高さ

AirflowはPythonで作り込めるがゆえに、5年間の運用を経てコードベースが複雑になっていました。さらにCloud Composer/Airflowのバージョンアップ対応が必要であったり、Cloud Composerはリソース量をプリセットから選ぶ形でフルマネージドとも言えなかったりと、マネージド度合いを高めたいという課題がありました。

なお、Cloud Composerのバージョンアップにまつわる運用課題については、以前「社内データ基盤のワークフローエンジンをBlue-green deploymentで無停止バージョンアップする」で紹介しています。

移行先コンポーネントの紹介

Cloud Composerが担っていた3つのワークロードを、それぞれ専用のマネージドサービスに分離しました。

dbt Cloud

dbtの実行基盤をAirflow + Cosmosからdbt Cloudに移行しました。

	メリット	デメリット
開発体験	CI実行時間が劇的に短縮（後述）。dbtに特化したIDE・ドキュメント生成・リネージが標準で使える	開発者シート数に上限あり
運用	バージョン管理・デプロイがSaaS側で完結。Airflowの運用が不要に	障害時の対応手段が限定的
拡張性	Webhookで後続処理をトリガー可能（Eventarc連携）	-

BigQuery Data Transfer Service (DTS)

事業DBの同期をDTSに移行しました。元はAmazon RDSのAmazon S3へのDBスナップショットデータのエクスポートをAirflow DAGから実行し、さらにBigQueryのLOADジョブをAirflow DAGから発行してロードする構成でしたが、移行後はMySQLやPostgreSQLなどのコネクタを使ってRDSから直接BigQueryにデータ転送します。

	メリット	デメリット
コスト	Google公式コネクタを使うことで現時点で転送コストなし	RDSがプライベートVPC内のためCloud VPNが必要
運用	フルマネージド。スケジュール実行・モニタリングが組み込み	細かいカスタマイズが難しい
信頼性	ジョブ品質をGoogleに任せられる	1ジョブにテーブルを詰め込みすぎるとレコード欠損が生じるケースがある。運用面からもジョブ分散が有用

Cloud Workflows

MLパイプラインやデータ変換のオーケストレーションをAirflow DAGからCloud Workflowsに移行しました。また、dbt Cloudとの連携のため、dbt modelのビルド完了をトリガーにEventarcを介してCloud Workflowsを起動する仕組みも構築しました。

	メリット	デメリット
コスト	従量課金で月額数百円程度。無料枠も大きい	-
開発体験	YAMLベースでシンプル。Terraform統合でCI/CDが容易	Airflowと比べ柔軟性が低い
運用	サーバーレス。ワークロードごとに独立。Cloud Logging/Monitoringに統合	Airflow UIのような統合的な実行管理画面はない

コスト比較

構成変更前後の月額コストを比較すると、約84%の削減となりました。

開発効率比較

開発効率の比較としてdbt modelの開発を例に、構成変更前後のCI実行時間を比較しました。

指標	Cloud Composer（n=622）	dbt Cloud（n=476）	改善
中央値	約17分	約30秒	34倍高速化
平均値	約42分	約2.5分	17倍高速化

CIの高速化により、dbt modelの変更に対するフィードバックループが劇的に短縮されました。これはAgentic AIがdbt modelを自律的に変更する際にも重要な基盤です。

運用面の比較

観点	Cloud Composer	移行後
バージョンアップ	Cloud Composer/Airflowの大型アップグレード対応が必要（Cloud Composer 2→3でコスト増）	マネージドサービスで自動。EOL対応が不要
障害時の影響範囲	全DAGが1環境に依存。障害で全ワークロード停止	ワークロードごとに独立。障害の影響を局所化
スケーリング	環境サイズの変更が必要（Worker 2台〜を常時確保するためコスト負荷もあり）	サーバーレスで自動スケール
デプロイ	時間がかかる（GCS同期→パース待ち）	個別に高速にデプロイ可能
可観測性	Airflow UIで一元管理	Cloud Logging/Monitoringに統合
アラート・障害対応	Airflowのpost hookでSlack通知 + GitHub Issueを作成	Cloud MonitoringとCloud FunctionsでSlack通知 + GitHub Issueを作成

エラーレート比較

Cloud Monitoringのメトリクスから、本番環境のDAG/Workflow実行の失敗率を比較しました。

	Cloud Composer（1〜3月）	Cloud Workflows（4月）
成功	32,494	1,849
失敗	286	15
合計	32,780	1,864
エラーレート	0.87%	0.80%

期間の違いによりサンプル数の差はありますが、移行後の安定性が改善傾向であることを確認できます。

まとめ

Cloud Composerをdbt Cloud / BigQuery Data Transfer Service / Cloud Workflowsの3つのマネージドサービスに分離することで、以下の効果を得ました。

コスト: 月額コスト約84%削減
開発効率: CI中央値17分→30秒（34倍高速化）
運用: サーバーレス化によりEOL対応・スケーリング・障害影響範囲が改善

「マネージドなAirflow」という一枚岩のアーキテクチャから、ワークロードの特性に合った専用サービスに分離するアプローチは、同様の構成で運用コストに課題を感じている方の参考になれば幸いです。

ORDER BY id DESC が招くインデックス誤選択 — 直近のレコードを N 件取り出すクエリを実測約 658 倍に高速化

2026-05-01T00:00:00+09:00

はじめに

「ある所有者の直近のレコード（注文・投稿・取引など）から、最新の N 件を取りたい」というユースケースは、Web アプリケーションを書いていれば頻出するパターンです。Rails 風に書けば次のような形になります。

current_user.orders
  .where.not(id: @order.id)    # 自分自身は除外する
  .order(id: :desc)            # 「直近」を id 降順で表現
  .limit(n)

このパターンが、minne では特定のユーザーで安定的に MySQL のクエリタイムアウトを起こしていました。

Mysql2::Error: Query execution was interrupted, maximum statement execution time exceeded

調査の結果、原因は ORDER BY id DESC + LIMIT N の組み合わせによる MySQL optimizer のインデックス誤選択 で、worst case で 2,300 万行をスキャン して max_statement_time を踏み抜いていることが判明しました。ORDER BY のカラムを既存インデックスに合わせて変えるだけで、

スキャン推定行数: 23,297,383 行 → 65,024 行（約 358 倍削減）
実測実行時間: 56.6ms → 0.086ms（約 658 倍高速化）

まで縮みました。本記事では、その原因分析と修正アプローチを EXPLAIN ANALYZE とあわせて紹介します。「直近のレコードを N 件取り出す」クエリを書くすべての人に還元できる知見となることを願っています。

はじめに
何が起きていたか
原因 — ORDER BY id DESC + LIMIT N で optimizer が PRIMARY を選ぶ
1. 「LIMIT を外せば直る」のではない
修正 — ORDER BY を既存インデックスのソート順に揃える
1. 補足: id DESC と ordered_at DESC の意味的な差
比較サマリ
学び
参考

何が起きていたか

問題のあったコードは、ある作家の 直近の注文を N 件取り出す ためのクエリでした。本筋に関係しない部分を削ぎ落とすと、概形は次のようになります。

current_user.orders
  .where.not(id: @order.id)    # 自分自身は除外する
  .order(id: :desc)            # 「直近」を id 降順で表現
  .limit(n)

current_user（作家）の注文のうち、現在のレコード自身を除いて id 降順に N 件取るだけ。発行される SQL もざっくり次のような形です。

SELECT sales.* FROM sales
WHERE sales.creator_id = ? AND sales.id != ?
ORDER BY sales.id DESC
LIMIT N;

一見、creator_id で絞って id 降順に N 件取るだけのシンプルなクエリです。注文数が少ない作家では即座に返ります。 ところが累計数万件規模の注文を持つような作家では、このクエリが安定してタイムアウトしていました。

原因 — `ORDER BY id DESC` + `LIMIT N` で optimizer が PRIMARY を選ぶ

sales テーブルには (creator_id, ordered_at) の複合インデックス index_sales_on_creator_id_ordered_at が張ってあります。(creator_id, id) のインデックスはありません。

実際の作家（sale 約 6.5 万件保有）で EXPLAIN ANALYZE を取った結果が次のとおりです。なお EXPLAIN ANALYZE は通常の EXPLAIN と違って クエリを実際に実行した上で 実測値を返すため、本番 DB に対して使う場合は負荷影響が伴います。本記事の計測も、実行タイミングや対象クエリを選ぶなど 影響範囲が最小となるよう注意した上で 取得しています。

EXPLAIN ANALYZE SELECT sales.* FROM sales
WHERE sales.creator_id = xxxxx AND sales.id != yyyyy
ORDER BY sales.id DESC
LIMIT 10;

-> Limit: 10 row(s)  (cost=66636 rows=10) (actual time=6.26..56.6 rows=10 loops=1)
   -> Filter: ((sales.creator_id = xxxxx) and (sales.id <> yyyyy))  (cost=66636 rows=34158) (actual time=6.26..56.6 rows=10 loops=1)
       -> Index range scan on sales using PRIMARY over (id < yyyyy) OR (yyyyy < id) (reverse)
          (cost=66636 rows=23.3e+6) (actual time=0.0213..54.1 rows=27907 loops=1)

possible_keys には PRIMARY と index_sales_on_creator_id_ordered_at の両方が挙がっていましたが、optimizer は PRIMARY 逆順スキャン を選択しました。ORDER BY id DESC LIMIT 10 を満たすのに「PRIMARY を逆順に舐めて、creator_id にヒットした行が 10 件揃ったところで打ち切る」プランを最も低コストと見積もったわけです。

これは MySQL が ORDER BY ... LIMIT の組み合わせに対して行う最適化（書籍『MySQL運用・管理［実践］入門』では ORDER BY LIMIT 最適化 と呼ばれています）が裏目に出たケースです。同書第 4 章「ロックとクエリ実行計画」では、ORDER BY Population DESC LIMIT 10 のような単純なケースについてこう説明されています。

idx_population によって Population はすでに昇順（暗黙のソート順は ASC）にソートされており、B+Tree 形式をしているためこのインデックスを昇順にたどるのと逆順にたどるのはほぼ等価に可能です（よってインデックスを使って逆順に処理したことを示す Extra: Backward index scan が追加されています）。

——『MySQL運用・管理［実践］入門』p.93

MySQL 8.0 で導入された Backward index scan によって、ORDER BY id DESC は PRIMARY を逆順に辿ればファイルソート無しに満たせます。さらに LIMIT N が付くと「途中で N 件揃った時点で打ち切れる」という早期終了が見込めるため、optimizer の目には PRIMARY 逆順スキャンが極めて魅力的なプランに映る、というわけです。

なぜこれが罠になるかは、sales の PRIMARY が 全作家の注文が時系列にミックスされた 1 本の列 だと考えると見えてきます。「PRIMARY を逆順に少し舐めれば N 件揃う」という見立ては、暗黙のうちに 対象作家の注文行が PRIMARY の最新側に十分密集している ことを前提にしています。

直近で注文を捌いている作家: 最新側の id 帯に自分の注文行が頻繁に現れる → 数千行のスキャンで N 件揃う
直近で注文を出していない作家: 最新側にはほぼ存在せず、自分の注文行が出てくる id 帯まで遡る必要がある → スキャン量が膨大に

これは『MySQL運用・管理［実践］入門』が示す ORDER BY LIMIT 最適化の 最悪ケース に相当します。

最悪ケースは Continent=’Asia’ を満たす行が確定する前にインデックスフルスキャンが終わるケース（すべて Continent にヒットしない）。

——『MySQL運用・管理［実践］入門』p.94

書籍は Continent='Asia' でフィルタにヒットせずインデックスを最後まで舐めきるケースを挙げていますが、本記事の事例は creator_id = xxxxx でヒットする行が PRIMARY 末尾に十分量現れない、という述語の差があるだけで構造は同じです。WHERE 列と ORDER BY 列のインデックスが分離している限り、optimizer は filtered の見積もりに基づいて「フィルタは早期に効くだろう」と楽観視し、それが外れた瞬間にスキャン量がテーブル全体まで線形に伸びていきます。

23.3M はあくまで rows 推定の上限値で、上のテスト作家では actual 27,907 行で済んでいます。一方で本番では、最新側に行が少ない作家のケースで max_statement_time を実際に踏み抜いていました。テーブルが伸びるほど worst case のスキャン量も線形に増えていく、という構造になっていたわけです。

「LIMIT を外せば直る」のではない

ここで自然な疑問は「じゃあ LIMIT を外せば PRIMARY 誘導は回避できるのでは？」というものです。実際 LIMIT を外すと optimizer の選択は変わります。

EXPLAIN ANALYZE SELECT sales.* FROM sales
WHERE sales.creator_id = xxxxx AND sales.id != yyyyy
ORDER BY sales.id DESC;

-> Sort: sales.id DESC  (cost=63195 rows=65024) (actual time=257..270 rows=35353 loops=1)
   -> Index lookup on sales using index_sales_on_creator_id_ordered_at (creator_id=xxxxx),
      with index condition: (sales.id <> yyyyy)  (cost=63195 rows=65024) (actual time=0.0305..209 rows=35353 loops=1)

(creator_id, ordered_at) インデックスが採用されて creator スコープに閉じる代わりに、id DESC で並べ直すための filesort（Sort ノード）が必要になります。実測 270ms。LIMIT 有りでの 56.6ms より遅く、テーブルが伸びれば線形に悪化します。

つまり罠の核心は LIMIT ではなく、WHERE 列と ORDER BY 列が別インデックスにまたがるクエリの組み立て方 そのものです。LIMIT の有無で optimizer は別の悪い選択肢に逃げるだけです。

LIMIT N + id DESC: PRIMARY 逆順スキャン誘導 → テーブル全体に対する worst case
LIMIT 無し + id DESC: (creator_id, ordered_at) + filesort → creator の sale 件数に対する線形コスト

『MySQL運用・管理［実践］入門』は次のように結論しています。

なお、WHERE と ORDER BY LIMIT 最適化を同時に満たすインデックスは、INDEX(Continent, Population) でこれが最速になります。

——『MySQL運用・管理［実践］入門』p.95

本件に当てはめれば (creator_id, id) の複合インデックスを足すのが理論的な最速解で、両方の問題を一気に解消できます。ただし数千万行規模の sales テーブルへの index 追加は運用コストが大きく、なるべく避けたいところです。本記事の修正は 既存の (creator_id, ordered_at) を活かす形にアプリ側のクエリを寄せる というアプローチを取りました。

修正 — `ORDER BY` を既存インデックスのソート順に揃える

修正の本丸は ORDER BY id DESC を ORDER BY ordered_at DESC に切り替えることです。これだけで (creator_id, ordered_at) インデックスが WHERE と ORDER BY の両方 で使えるようになり、optimizer の選択が劇的に変わります。

SELECT sales.* FROM sales
WHERE sales.creator_id = ? AND sales.id != ?
ORDER BY sales.ordered_at DESC
LIMIT N;

同じ作家で EXPLAIN ANALYZE を取り直したのが次の結果です。

EXPLAIN ANALYZE SELECT sales.* FROM sales
WHERE sales.creator_id = xxxxx AND sales.id != yyyyy
ORDER BY sales.ordered_at DESC
LIMIT 10;

-> Limit: 10 row(s)  (cost=63494 rows=10) (actual time=0.0296..0.0863 rows=10 loops=1)
   -> Filter: (sales.id <> yyyyy)  (cost=63494 rows=32512) (actual time=0.0288..0.0848 rows=10 loops=1)
       -> Index lookup on sales using index_sales_on_creator_id_ordered_at (creator_id=xxxxx) (reverse)
          (cost=63494 rows=65024) (actual time=0.0277..0.0827 rows=10 loops=1)

(creator_id, ordered_at) を逆順に index lookup し、LIMIT 10 で 本当に 10 行だけ読む 計画になりました。filesort も無く、actual rows が 10。実測 0.086ms です。

参考までに、LIMIT を外した場合の EXPLAIN ANALYZE も載せておきます。

EXPLAIN ANALYZE SELECT sales.* FROM sales
WHERE sales.creator_id = xxxxx AND sales.id != yyyyy
ORDER BY sales.ordered_at DESC;

-> Filter: (sales.id <> yyyyy)  (cost=60713 rows=32512) (actual time=0.0286..213 rows=35353 loops=1)
   -> Index lookup on sales using index_sales_on_creator_id_ordered_at (creator_id=xxxxx) (reverse)
      (cost=60713 rows=65024) (actual time=0.0273..209 rows=35353 loops=1)

LIMIT を外しても Sort ノードは現れず、(creator_id, ordered_at) を順に舐めるだけのプランです。actual rows は creator スコープの 35,353 行で、実測 213ms。これは「対象 creator の sale を一通り読む」コストそのものであり、旧クエリのようにテーブル全体の 23M 行を舐めにいくのとは性質がまったく違います。

修正前後の違いを 4 通りの実験で見える化すると次のようになります（同じ作家・同じ条件で測定）。

Query	採用 key	filesort	actual rows	actual time
`id DESC` + `LIMIT 10`	PRIMARY	no	27,907	56.6 ms
`id DESC`（LIMIT なし）	`..._ordered_at`	YES	35,353	270 ms
`ordered_at DESC` + `LIMIT 10`	`..._ordered_at`	no	10	0.086 ms
`ordered_at DESC`（LIMIT なし）	`..._ordered_at`	no	35,353	213 ms

ordered_at DESC 系は LIMIT 有無に関わらず filesort 無しで (creator_id, ordered_at) 一本で完結しています。LIMIT 有りの場合は早期打ち切りも効いて actual rows = 10、文字どおり「N 件だけ読む」状態になっています。

補足: `id DESC` と `ordered_at DESC` の意味的な差

旧実装は id 降順、新実装は ordered_at 降順なので、厳密には「並び順」の意味が変わります。sales.ordered_at が NULL なレコードや、バックフィルなどで ordered_at と id が逆転するレコードでは、選ばれる注文が変わる可能性があります。

今回のユースケースでは「直近の傾向に近いものが取れていれば十分」だったため許容しましたが、厳密に id の最大を取りたい場合は単純な置き換えはできない 点には注意が必要です。(creator_id, id) のインデックスを足すか、(creator_id, ordered_at) の上で取った後に再度 id で並べ替える、といった選択肢があります。

比較サマリ

項目	旧 (`ORDER BY id DESC` + `LIMIT 10`)	新 (`ORDER BY ordered_at DESC` + `LIMIT 10`)
採用 index	PRIMARY	`index_sales_on_creator_id_ordered_at`
スキャン推定行数	23,297,383	65,024（約 358 倍削減）
実 scan 行数	27,907	10
filesort	無し（PRIMARY backward）	無し（index backward）
実測実行時間	56.6 ms	0.086 ms（約 658 倍高速化）
追加 index	–	–

既存 index の活用に閉じているため、sales テーブルに追加負担は発生せず、巨大テーブルへの DDL を一切避けられました。

学び

今回の改善から得た学びを 3 つに整理します。

罠は LIMIT 単独でも id DESC 単独でもなく、WHERE 列 と ORDER BY 列 が別インデックスにまたがるクエリの組み立て方: LIMIT 有り → 別インデックス（PRIMARY）誘導、LIMIT 無し → filesort、どちらにしても遅くなる。fix は ORDER BY を WHERE 列と組になっている既存インデックスのソート順に揃える こと
EXPLAIN を取るまで「速いはず」は信用しない: creator_id で絞っているから速いだろう、ではなく、possible_keys と key を見て optimizer の実際の選択を確認する。本件も possible_keys には正解の index が出ていたが、key は PRIMARY だった。EXPLAIN ANALYZE まで取ると actual rows / actual time も見えて、見積もりとの乖離も追える（ただし EXPLAIN ANALYZE はクエリを実際に走らせるため、本番で取るなら影響範囲が最小となるよう注意するのが基本）
巨大テーブルへの index 追加に頼らず、まずクエリ形を既存インデックスに寄せる: 数千万行規模のテーブルへの index 追加は運用コストが大きい。(creator_id, ordered_at) のような既存複合インデックスを活かす形にアプリ側のクエリを寄せるだけで、追加コストゼロで大幅改善が得られるケースは意外と多い

これらの観点は、minne のように長く運用されるサービスで巨大テーブルと付き合う上で、繰り返し効いてくる考え方だと感じています。同じような「特定ユーザーで突然タイムアウトする」現象に出会った方の参考になれば幸いです。

参考

yoku0825・北川健太郎・tom__bo・坂井恵著『MySQL運用・管理［実践］入門』技術評論社, 2024 — 第 4 章「ロックとクエリ実行計画」が ORDER BY LIMIT 最適化と Backward index scan の理論的背景を丁寧に扱っており、本記事の現象を語彙化する上で大きく参考にしました
MySQL :: MySQL 8.0 Reference Manual :: 8.2.1.16 ORDER BY Optimization — MySQL 公式リファレンス

生成AIの従量課金とどう付き合うか？AIサイトエージェント開発で実践した段階的コスト見積もり

2026-05-01T00:00:00+09:00

はじめに

こんにちは。ロリポップ・ムームードメイン事業部でエンジニアリングリードをしています kinosuke01 といいます。

生成AIを組み込んだアプリケーションを事業として提供するとき、避けて通れないテーマが コスト です。

事業としてやっている以上、売上・利益・粗利率には当然ながら目標値があります。開発者としても「技術的に動けばOK」ではなく、その数字を前提にしたうえで、お金のことも勘案して設計や実装を進める必要があります。

ところが生成AIをAPI経由で使う場合、消費トークン数による従量課金となるため、事前にどの程度のコストになるのかを見積もるのが一筋縄ではいきません。

とくに生成AIが自律的に判断・分岐するワークフローだと、入力も出力もユーザーの指示内容に大きく依存するため、「このケースで n トークン」と簡単には言い切れません。

本記事では、AIサイトエージェント開発プロジェクトで実施した、段階的にコスト試算の精度を上げていくアプローチを紹介します。完璧な見積もりを最初から作ろうとするのではなく、プロジェクトのフェーズごとに見積もり方法を変えていく話です。

前提：AI サイトエージェントというサービス

私たちが開発している AI サイトエージェントは、「カフェのサイトを作りたい」「フリーランス向けのポートフォリオが欲しい」といった自然言語の指示を投げると、ページ構成・デザインテーマ・コンテンツまでを一括で生成してくれる Web サイト制作サービスです。生成したあとも、チャット越しに「トップのキャッチを変えて」「このセクションの写真を差し替えて」と伝えれば、AI が編集を代行してくれます。

内部のワークフローは、決定論的なワークフローをベースに、一部のステップで生成AIが自律的に判断・分岐する 構造になっています。全部を生成AIに任せるのではなく、「ここは構造が決まっている」「ここは自由度を持たせたい」をフェーズごとに使い分けることで、品質と予測可能性を両立させる狙いです。

ざっくり図にすると、このような流れです。

ラベルに「生成AI：」と書かれているブロックが生成AI呼び出しで、それ以外は決定論的な処理です。たとえば PageAndSectionPlanner は「ページ何枚構成にするか」「各ページにどのセクションを置くか」を、ユーザーの指示に応じて柔軟に決めます。一方で、決まったフォーマットの JSON が返ってこないと後続の処理が動かないので、Structured Output を使って構造を縛っています。

このような構造だと、単に「1 回のサイト生成で何トークン？」と問われても、ページ数・セクション数・モデルの揺らぎで大きく変わってきます。見積もりが難しいわけです。

対応方針：段階的に精度を上げる

難しいのでやらない、というわけにはいきません。かといって最初から正確な数字を出すこともできません。そこでビジネス職と以下について合意しました。

従量課金であり、実績に応じてコストが変動すること
開発の進行に合わせて、段階的に試算の精度を上げていくこと

具体的には 3 つのフェーズに分けて見積もりを更新していきます。

フェーズ	何を使って見積もるか	精度
1. 設計直後	ワークフロー骨組み + 各ステップの想定トークン数	概算
2. 実装後（検証環境）	実際の呼び出しログから集計した実績値	中精度
3. ローンチ後	本番の実トラフィックに基づくモニタリング	高精度

以下、それぞれのフェーズで何をやったかを見ていきます。

フェーズ 1：設計段階でざっくり見積もる

まず最初にやるべきは、ワークフロー全体の骨組みを設計することです。このとき、細部の実装よりも「どのステップで、どんなモデルを、どのくらいのトークン量で呼ぶか」を決めることに集中します。

たとえば PageAndSectionPlanner であれば、ざっくりこんな見積もりになります。

モデル：Gemini 2.5 Flash
入力トークン：プロンプト（1,500）+ ユーザー指示（200）= 1,700
出力トークン：3 ページ分の JSON ≒ 800

（※ 上記のトークン数は説明用の仮の値です。実際の値はプロンプトの内容や出力サイズによって変わります）

これを全ステップで行い、1 サイト生成あたりの概算を出します。そこに想定利用数（例：月間 n ユーザー × 平均 m 回/人）を掛けて、ざっくりとした月額コストを算出し、ビジネス職に第一報として共有します。

この段階では精度は荒いものの、

「桁が合っているか」の感覚を関係者で揃える
「粗利率が破綻するオーダーではないか」の早期チェック

という観点で十分に価値があります。桁が想定を超えていれば、そもそもワークフロー設計を見直すべきというシグナルになります。

フェーズ 2：実装してから実データで見積もる

2 回目の見積もりに入ります。このフェーズの流れは大きく 3 ステップです。

エッジケースは後回しにして、まず正常系が一通り動く状態まで実装する
生成AI呼び出しのトークン数を自動で DB に記録できるようにする
検証環境で実データを溜め、集計結果をもとに再見積もりする

順に見ていきます。なお 2 の実装詳細は、記事末尾の「付録：トークン数を DB に記録する仕組み」に切り出しています。

正常系を一通り動かす

このフェーズで大事なのは、エッジケースの対応は後回しにして、まず「とにかく一通り動く」ものを作ること です。

ここで言うエッジケース対応とは、たとえば以下のようなものです。

生成AIが Structured Output のスキーマを逸脱した JSON を返したときのサニタイズや再試行
タイムアウトやレート制限にかかったときのリトライ制御
出力内容が明らかに破綻している（空文字、文字化け等）ときのフォールバック

これらは本番運用では欠かせませんが、最初から詰め始めると、実データが溜まるのがずるずる先延ばしになります。正常系さえ動けば検証環境で大半のケースは実測できるので、まずはそちらを優先します。

トークン数を自動で DB に記録する

次に、生成AI呼び出し時の「使用モデル」「入力/出力トークン数」「所要時間」などを自動で DB に記録する仕組みを入れます。PageAndSectionPlanner、ThemeDeterminer、SectionValueGenerator 等のすべてのステップで、呼び出すたびに 1 レコードが残る状態を作ります。

ポイントは、アプリケーションコード側に計測ロジックを足さずに済む形で組み込むことと、プロンプト・レスポンス本文も併せて保存しておくこと（後からプロンプト改善の材料になるため）です。具体的な実装は付録を参照してください。

実績データから見積もる

ここまで仕込めたら、あとは実データを溜めるフェーズです。検証環境にデプロイし、動作検証がてらサイト生成をひたすら回します。同じ指示文でも、モデルの揺らぎで消費トークン数は変わるため、数を回せば回すほどばらつきが見えてきます。

実績データが溜まったら、stepType ごと・モデルごとの平均トークン数を集計し、それに想定利用数を掛けて月額コストを再計算します。実際の運用では、検証環境のデータに安全係数（今回は 2 倍程度）を掛けておきました。本番では、検証環境では出なかった長いユーザー入力や、エッジケースの追加プロンプトなどが入り込むことを想定しています。

この段階で出てきた数字と粗利率の目標値を突き合わせ、ビジネス職と「このまま進められるか」「料金プランの調整が必要か」を議論します。

フェーズ 3：ローンチ後のモニタリング

ここまで来ると、ローンチして実際のユーザーの利用状況を見るだけです。フェーズ 2 で仕込んだトークン数のログを定期的に集計し、

1 サイト生成あたりの平均トークン数は想定どおりか
粗利率の目標値を脅かす動きはないか
特定のステップだけ異常に消費量が大きくなっていないか

をモニタリングします。想定から外れた動きがあれば、プロンプトの見直し、モデルの選定変更、もしくは料金プラン側での調整を検討します。

本番の実データという最も精度の高い情報源を持っている状態なので、このフェーズの見積もりは「見積もり」というより「実測値のトラッキング」です。ここに至って初めて、生成AIのコストは見積もりの対象ではなく、モニタリングし続ける運用指標 に変わります。

まとめ

生成AI のコストは、事前に一発で正確に見積もることは困難です。だからといって「わかりません」では済まないので、段階的に精度を上げていく という方針で進めるのが現実的でした。

フェーズ 1（設計直後）：ワークフローの骨組みとざっくりトークン数で桁を合わせる
フェーズ 2（実装後）：生成AI呼び出しをラップして実データを集め、安全係数を掛けて再見積もり
フェーズ 3（ローンチ後）：本番データで継続モニタリング、粗利率への影響をチェック

このうち効果が大きかったのは、フェーズ 2 で踏んだ次の 2 点です。

エッジケース対応を後回しにして、一通り動くものを先に作る：実データを早く集めるには、検証環境で回せる状態に到達するのが最優先です。
生成AI呼び出しをラッパー化して、全ステップ自動でログ化する：計測を仕組み化しておけば、フェーズ 2 以降の意思決定が実データベースでできるようになります。

どちらか片方だけでは成立しません。動くものがあってもログが取れなければ実績はわからないし、ログの仕組みだけ整えても呼び出されなければデータは溜まらない。この 2 つを揃えることで、実データを武器に意思決定できる状態に早く到達できました。

生成AI を使うプロダクトを作る方にとって、同じ悩みを抱えている方の参考になれば幸いです。

付録：トークン数を DB に記録する仕組み

フェーズ 2 で触れた「生成AI呼び出しのトークン数を自動で DB に記録する」の実装詳細です。本筋を読み進める上では読み飛ばしても構いません。

どこに永続化するか：RDB を選んだ理由

トークン数の永続化先は、いくつか選択肢がありました。

生成AI 向けの Observability SaaS（ LangSmith など） を使う
Langfuse の OSS 版 をセルフホストする
自前の RDB テーブル に保存する

最終的には RDB に保存する方針を選びました。理由は以下です。

SaaS は便利だが、ベンダーロックイン を避けたい
Langfuse OSS は魅力的だが、この時点では運用対象を増やしたくない
RDB なら既に運用しているので追加コストが相対的に低い

将来的に実データが溜まってきたら BigQuery 等のデータウェアハウスに流す、という拡張余地は残しています。「あとで捨てられる」「あとで移行できる」選択肢を選ぶことで、意思決定のコストを下げています。

Prisma スキーマ

スキーマは必要最小限。どのステップで、どのモデルを、何トークン使ったかが後から辿れれば十分です。

model AiGenerationLog {
  id           String   @id @default(uuid())
  userId       String?  @map("user_id")
  websiteId    String?  @map("website_id")
  stepType     String   @map("step_type")  // "page_and_section_plan" 等
  model        String   @map("model")      // "gemini-2.5-flash"
  prompt       String   @db.MediumText @map("prompt")
  response     String   @db.MediumText @map("response")
  inputTokens  Int?     @map("input_tokens")
  outputTokens Int?     @map("output_tokens")
  durationMs   Int?     @map("duration_ms")
  isError      Boolean  @default(false) @map("is_error")
  errorMessage String?  @db.Text @map("error_message")
  createdAt    DateTime @default(now()) @map("created_at")

  @@map("ai_generation_log")
}

プロンプトとレスポンスも併せて保存しています。これは、後から「このトークン数のときはこういう出力が返っていた」と振り返って、プロンプトをチューニングする材料にできるためです。

ログの書き込み処理

ログの書き込みは、ビジネスロジックに影響させたくありません。そのため、保存失敗はエラーログに残すだけで呼び出し元には伝播させない、という方針にしています。

// ai-generation-logger.ts（抜粋）
async saveLog(input: AiGenerationLogCreateInput): Promise<void> {
  try {
    await this.repository.save(input);
  } catch (error) {
    logger.error({ err: error }, "Failed to save AI generation log");
  }
}

logGeneration(params: { /* ... */ }): void {
  const context = getAiLogContext();

  this.saveLog({
    userId: context.userId,
    websiteId: context.siteId,
    stepType: params.stepType,
    model: params.model,
    prompt: params.prompt,
    response: params.response,
    inputTokens: params.inputTokens,
    outputTokens: params.outputTokens,
    durationMs: params.durationMs,
    isError: params.isError,
    errorMessage: params.errorMessage,
  }).catch(() => {});
}

ログの保存が原因でサイト生成が失敗したら本末転倒なので、ここは割り切ります。

生成AI呼び出しをラップする

あとは、生成AIクライアント側から上記のLoggerを呼ぶだけです。モデルの呼び出し箇所に毎回 await insertLog(...) を書くのは現実的ではないので、生成AIクライアントをラップする層を 1 枚挟みます。ラッパー側で usageMetadata からトークン数を取り出し、DB 保存用のLoggerに流します。成功時だけでなくエラー時も記録したいので、try/catch の両方でログ化します。

// db-logging-model.ts（抜粋）
export class DbLoggingGenerativeModel implements GenerativeModel {
  get modelName(): string {
    return this.inner.modelName;
  }

  constructor(
    private readonly inner: GenerativeModel,
    private readonly stepType: string,
    private readonly genLogger: AiGenerationLogger,
  ) {}

  async generateContent(prompt: string) {
    const startTime = Date.now();
    try {
      const result = await this.inner.generateContent(prompt);
      const text = result.response.text();
      this.genLogger.logGeneration({
        stepType: this.stepType,
        model: this.modelName,
        prompt,
        response: text,
        inputTokens: result.usageMetadata?.promptTokenCount,
        outputTokens: result.usageMetadata?.candidatesTokenCount,
        durationMs: Date.now() - startTime,
      });
      return result;
    } catch (error) {
      this.genLogger.logGeneration({
        stepType: this.stepType,
        model: this.modelName,
        prompt,
        response: "",
        durationMs: Date.now() - startTime,
        isError: true,
        errorMessage: error instanceof Error ? error.message : String(error),
      });
      throw error;
    }
  }
}

このデコレータを挟むことで、すべてのステップ（PageAndSectionPlanner、ThemeDeterminer、SectionValueGenerator 等）のアプリケーションコード側に特別な計測ロジックを足さずに、全呼び出しのトークン数を DB に記録できます。stepType をコンストラクタで受け取っているのは、「どのステップの呼び出しか」をあとから集計できるようにするためです。

Claude Code Skillでメール障害対応を実施

2026-04-30T00:00:00+09:00

こんにちは、技術部技術基盤グループのkmsnです。

GMOペパボが運営するECサイト構築サービス「カラーミーショップ」で、Outlook/Hotmail/Live宛メールがブロックされる障害が発生しました。この記事では、Claude Code の Skill を活用して障害の初動対応を効率化した事例を紹介します。

結論：Skill で障害対応の初動が変わった

先に結論をお伝えします。今回の障害対応で最も効果的だったのは、Claude Code の Skill によって状況把握のスピードが大幅に上がったことです。

カラーミーショップのメールサーバーは数十台あります。従来であれば、障害発生時に1台ずつ SSH して sudo postqueue -p を叩き、キューの状態を目視で確認していく必要がありました。台数が多いため状況把握だけで時間がかかり、その間もメールは滞留し続けます。

今回は colorme-mailq Skill を使い、「メールキュー確認して」の一言で全台の状態を一括取得しました。

サーバー	active	deferred	合計
server-1	0	3,842	3,842
server-2	12	0	12

※ 上記は全数十台のうち抜粋

特定サーバーの deferred が突出して積み上がっていることが一目でわかり、対応する方針をすぐに決められました。従来の手動確認では状況把握に時間を要していた工程が、Skill によって数秒で完了し、対応方針の決定までの時間を大幅に短縮できました。

さらに、この Skill は社内のプライベートリポジトリに登録されているため、自分だけでなくチームの誰でも同じように使えます。個人のスクリプトではなく チーム共有の Skill として整備しておくことで、次に同様の障害が起きたときにも誰でも素早く初動に入れるという点が大きな価値です。

何が起きたか

カラーミーショップのユーザーが送信したメールが、Outlook/Hotmail/Live宛に届かずブロックされる事象が発生しました。Microsoft（Outlook.com）のような大手プロバイダーは、スパム判定によるブロック時に 5xx 系（主に 550）のエラーを返すことがあります。ただし、Postfix 側の設定や一時的なレスポンスにより deferred キューに滞留するケースもあり、今回はキューの滞留として顕在化しました。

ログを確認したところ、特定のショップドメインからの大量送信が引き金となり、送信を担うサーバーの IP が Microsoft（Outlook.com）側にブロックされたと判断しました。

Postfix transport で Outlook 宛の配送経路を変更する

Skill で状況を把握した後、ブロックされたサーバーを迂回する対応を取りました。これには Postfix の transport テーブルを使います。

transport テーブルは「特定ドメイン宛の配送を、どの経路で行うか」を定義するファイルです。Outlook 系ドメイン宛のメールを別の経路に切り替える設定を追加しました。

また /etc/postfix/transport を確認すると、以前のインシデント時に手動で投入された送信レート制御の設定が残っていました。今回は別の経路への切り替えで対処するため不要と判断し、削除した上で新しい設定を追加しました。

手動設定を Puppet でコード化する

ここで課題に当たりました。対象サーバーの /etc/postfix/transport は Puppet で管理されておらず、手動設定のみの状態だったのです。

先ほどのレート制御の設定がまさにその典型で、何のためのものか、誰が投入したのかがすぐに追えない状況でした。手動設定が蓄積すると、こうした「経緯のわからない設定」が増えていきます。

別のメールサーバーでは hieradata/nodes/ 配下にノード専用の yaml が存在し、transport 設定が Puppet で管理されていました。一方、対象サーバーにはその yaml が存在しません。チームメンバーにアドバイスをもらいながら、以下の2択で検討しました。

A: 対象サーバーのノード yaml だけに書く → そのサーバーのみに適用。他サーバーへの影響なし
B: ロール共通の yaml に書く → 全メールサーバーに一律適用

既存実装を参考に、今回は A を選択。対象サーバー専用のノード yaml を新規作成し、このサーバーとしては初めて transport 設定を Puppet 管理に取り込みました。

チームメンバーのレビューを受けてマージし、--noop での dry-run で差分を確認してから本適用しました。

sudo puppet agent --test --noop  # dry-run で変更内容を事前確認
sudo puppet agent --test         # 本適用

経路の切り替えが正常に動作していることを確認し、復旧しました。

なお、transport による経路変更はあくまで暫定的な緩和措置であり、根本対処ではありません。これを恒久的な対処としてしまうと、迂回先のサーバーにも負荷が偏るなど新たな問題を招く可能性があります。並行して Microsoft への delist 申請や送信元ショップへの対応など、根本原因の解消に向けた対処を実施し、解消後に transport の設定を元に戻すところまでが一連の対応です。

その他の学び

カスタマーサポート（CS）への連携は「確定情報だけ」を素早く。

技術的な調査の完了を待たず、判明した情報（発生時刻・影響範囲・復旧時刻）をその都度 CS に共有するほうがユーザー影響を最小化できます。調査の過程をすべて流すのではなく、確定した情報だけをタイムリーに伝えるというシンプルな判断が、慣れないうちは意外と難しいと感じました。

手動設定は「なぜ入っているか」が追えなくなる。

今回 Puppet に設定を取り込んだことで、次の担当者が経緯を追いやすくなりました。障害のたびに手動で設定を足していくのではなく、コードに残す習慣が大切だと改めて感じました。

おわりに

今回の対応を通じて、障害対応の定型作業を Skill として整備しておくことの効果を実感しました。状況把握の速さは、そのまま復旧の速さにつながります。

この考え方はメール障害に限りません。たとえば Web サーバーのエラーレート急増時にログを集約する、データベースのスロークエリを一覧する、といった「障害発生直後にまず確認すること」は、どの領域にもあるはずです。こうした初動の定型作業を Skill として整備しておくことで、経験の浅いメンバーでも素早く状況把握に入れるようになり、経験豊富なメンバーは情報収集の手間を省いて判断や対応方針の策定に集中できます。

同様の取り組みを検討されている方の参考になれば幸いです。

後付け可能な認証を NextAuth で設計する — ログイン機構が決まらないまま、ログイン前提のプロダクトを作った話

2026-04-24T00:00:00+09:00

はじめに

こんにちは。ロリポップ・ムームードメイン事業部でエンジニアリングリードをしています kinosuke01 といいます。

「この機能はログインしたユーザーのものとして扱いたい」というのは、ほとんどのプロダクトで当たり前の要件となります。ところが、プロダクト本体の開発を進めたいタイミングで、ログインの仕組みがまだ決まっていないという状況に直面することがあります。

後から差し替え可能にしておくというのは一つの手です。しかし「あとで差し替え」を甘く見ていると、いざ差し替えるときに思いのほか大がかりな書き換えが発生してしまう場合もあるのではないでしょうか。

この記事では、AIサイトエージェントというプロダクトの開発で実際に直面したこの状況と、そこで取った方針について紹介していきます。

要点を先にまとめると、以下の一点になります。

決まっていない領域を、差し替え可能なレイヤーに封じ込める。そのレイヤーだけを「本物と同じ形の偽物」で置き、他のコードからは本物と区別できない状態で先に作り切る。

具体的には、NextAuth.js を土台にした「本物と同じ形の偽物ログイン」を用意することで、後から本番のログイン機構（OIDC）に NextAuth インスタンスの差し替えだけで移行できるようになりました。以降の節で、この構造を順に分解していきます。

前提：AIサイトエージェントとは

本題に入る前に、舞台となるプロダクトの輪郭を簡単に共有しておきます。

AIサイトエージェントは、「カフェのサイトを作りたい」「フリーランスのポートフォリオが欲しい」といった自然言語の指示を投げると、ページ構成・デザインテーマ・コンテンツまでを一括で生成してくれる Web サイト制作サービスです。生成したあとも、チャット越しに「トップのキャッチを変えて」「このセクションの写真を差し替えて」と伝えれば、AI が編集を代行してくれます。

このサービスは、ロリポップ！レンタルサーバーとムームードメインのどちらからも利用できるようになっています。ロリポップのユーザーとムームードメインのユーザー、それぞれが AIサイトエージェントのコンパネに入ってサイトを作れる、というのが本番のユースケースとなります。

技術スタック

この記事のコード例を読む前提として、プロダクトの技術スタックにも軽く触れておきます。

フレームワーク: Next.js（App Router）
認証: NextAuth.js（Auth.js v5）
言語: TypeScript

以降の本文では NextAuth の authorize / jwt / session といったコールバック関数がコード例に登場します。NextAuth に馴染みのない方は、「ログイン処理の各ステップで呼ばれるフック関数」程度のざっくりした理解で読み進めていただければ大丈夫です。

課題の整理：ログインが決まっていない中で何を作るか

AIサイトエージェントは、最終的にはロリポップとムームードメインの2つのサービスのアカウントでログインできる形に落ち着きました。しかし、はじめからそう決まっていたわけではなく、アカウント基盤をどうするか・どう認証するかは、ビジネス・技術の両面から議論が続いている状況でした。

一方で、サイトを生成・編集するというプロダクトの中核機能の開発を止めて待つ、という選択肢はありませんでした。Webサイトの生成、ユーザーによる編集、自分のサイトにだけアクセスできる仕組みといった機能は、どれも「ログイン済みユーザーがいる」ことを前提にしています。つまり、ログイン機構が決まっていないまま、ログイン前提の機能を作り進める必要があるという状況になっていました。

この状況から、解くべき課題は次の2つに分解できます。

今、ログイン前提の機能をどう作るか
本番のログイン機構が決まったとき、どうシームレスに繋ぎ込むか

1.だけなら、サーバー側関数で固定の userId を返すような簡易なモックで十分です。しかし 2. を同時に成立させようとすると、それだけでは足りません。本物のログインが乗ったときに、セッションの持ち方もユーザーのテーブル構造もごっそり変わるとなると、結局そのタイミングで広範囲の書き換えが発生してしまいます。

加えて、設計上もうひとつ大きな制約がありました。それが次の 独立開発の要件 です。

開発環境を外部サービスから独立させたい

この時点では本番のログイン機構がまだ決まっていない、というのは先に述べたとおりです。ただし、アカウント基盤の候補として議論されていたロリポップやムームードメインといった既存サービスは、どちらも長く運用されている巨大なコードベースを持つサービスとなります。仮にこうした既存サービスのアカウント基盤と繋ぎ込むことが決まった場合、それら本番と同等のログイン基盤をまるごとローカル開発に繋ぎ込むというのは現実的ではありません。セットアップの手間もさることながら、外部依存が増えるほど開発体験は悪くなっていきます。

そのため、本番のログイン機構が最終的に何になっても困らないよう、認証の外部依存ゼロでプロダクト本体を動かせる ことも考慮したいと考えていました。

方針

ここまでを踏まえて、方針は次のように定めました。

「本物が来たときに差し替えるレイヤー」だけを偽物にする。それ以外は、本番運用で使うものと同じ構造で作り込む。

具体的には、以下の3点を本物と同じ形で作り込むことにしました。

セッション管理の仕組み: JWT ベースのセッション、コールバックの流れ
ユーザーのテーブル構造: 外部認証プロバイダーとの紐付けを前提にしたスキーマ
JIT プロビジョニング: 初回ログイン時にユーザーと所属組織を作成する流れ

偽物にするのは「認証のやり方そのもの」だけとなります（以降、この偽物の認証を モック認証 と呼びます）。これなら、認証のやり方が決まったときに、そこだけ差し替えれば済むようになります。

モック認証に求める振る舞い

実装の話に入る前に、このモック認証にどんな挙動をさせたいのかを具体化しておきます。「本物と同じ形」と言っても曖昧ですので、期待する振る舞いをあらかじめ言語化しておくと、以降の実装がなぜそうなっているのかが見えやすくなります。

ここで puid（provider user id の略。プロバイダー側のユーザー識別子に相当する値）という言葉が出てきます。本番では OIDC プロバイダーから渡ってくる sub クレームですが、モックでは開発者が自由に指定できる文字列として扱います。以降の節でも繰り返し登場する語となります。

求める振る舞いは、次のように整理できます。

モック特有の部分（偽物としての振る舞い）

任意のIDでログインできる: ログイン画面で puid を自由に入力でき、未指定の場合は固定のデフォルトユーザーとしてログインできる
外部サービスへの問い合わせは発生しない: OIDC の認可エンドポイントや userinfo を呼ばない。入力された puid を信頼してログイン完了とする（前節の独立開発要件に対応）
初回ログイン時にユーザーを自動生成する: その puid に対応する DB レコードが無ければ、ユーザー・組織・ExternalIdentity を自動で作る（JIT プロビジョニング）

本番と揃えたい部分（アプリから見て本物と同じ形）

セッションから得られる情報は本番と同じ: appUserId, providerUserId, provider がセッションに揃い、アプリケーションコードから見ると 本番認証と区別がつかない状態となる

開発体験の要件

puid を変えればユーザーを切り替えられる: 権限・所有権など複数ユーザーが絡む検証を、開発中も素直に試せる

任意のユーザー名を入力すると、そのユーザーでログインできる

1〜3 が偽物として置く部分、4 がアプリに向けてそろえる部分、5 が開発者が使うときの体験です。では、この3つの層をどう実装していくか、順に見ていきましょう。

土台として NextAuth を選ぶ

この設計を支える土台として NextAuth を採用しました。NextAuth は Provider という概念を中心に、Credentials（任意の独自認証）、OAuth、OIDC など複数の認証方式を同じ抽象のもとに扱えるフレームワークです。

「モック認証も一つの Provider として扱い、本番の OIDC 認証も同じく Provider として差し替える」という構造が、そのまま課題にフィットしました。セッション管理やコールバックの組み立て方は Provider に依存しないので、モック時に書いたコールバック処理は OIDC 導入後もそのまま使い回せます。このことが、後述する差し替え時の手数の少なさに直結しました。

テーブル構造は「外部連携前提」にしておく

ログインがモックであっても、テーブル構造はあとで使う本物のスキーマを想定して設計しました。ポイントは、ユーザー本体（User）と外部認証プロバイダーとの結び付け情報（ExternalIdentity）をテーブル分離し、プロバイダー種別をユニーク制約に含めたところとなります。

model ExternalIdentity {
  userId         String       @unique
  provider       AuthProvider
  providerUserId String
  // ... 他のカラム省略

  @@unique([provider, providerUserId])
}

enum AuthProvider {
  MUUMUU
  LOLIPOP
  MOCK
}

モック認証もれっきとした「プロバイダーの一つ」として AuthProvider.MOCK を割り当てることで、本番のプロバイダーと同じ経路でユーザーを特定できるようになります。本番のプロバイダーが後から増えても、enum に値を足して ExternalIdentity を作るだけで対応可能です。モックと本番を同じ構造で受け止めるスキーマとなっています。

モック認証を NextAuth の上に載せる

モック認証は NextAuth の Credentials Provider で実装しました。本物の認証ではなく、画面で入力された puid をそのまま通すだけのダミーです。

// 入力された puid を簡易バリデーションするための正規表現
const PUID_PATTERN = /^[a-zA-Z0-9-]+$/;

function createMockAuth() {
  return NextAuth({
    providers: [
      Credentials({
        id: "credentials",
        name: "Mock Login",
        credentials: {
          puid: { label: "ProviderUserId", type: "text" },
        },
        async authorize(credentials) {
          const puid =
            typeof credentials?.puid === "string" &&
            credentials.puid.trim() !== ""
              ? credentials.puid.trim()
              : "mock-user";

          if (!PUID_PATTERN.test(puid)) {
            return null;
          }

          // jwt コールバックで user として受け取る値
          return { id: puid };
        },
      }),
    ],
    trustHost: true,
    callbacks: {
      async jwt({ token, account }) {
        return mockJwtCallback({ token, account });
      },
      async session({ session, token }) {
        return commonSessionCallback({ session, token }); // 本番と共通
      },
    },
    pages: { signIn: "/login" },
  });
}

コードの中に authorize / jwt / session という3つのコールバックが出てきます。NextAuth に馴染みのない方向けに、それぞれの役割と、mock-user でログインボタンを押したときの呼び出し順を軽く整理しておきます。

authorize: ログインフォームから送られた値を受け取り、認証の可否を判断するコールバックです（Credentials Provider 特有のもの）。OK ならユーザーを表すオブジェクトを返し、NG なら null を返します。
jwt: セッションの元となる JWT を組み立てるコールバックです。authorize が返した情報をベースに、JWT へ積みたい情報（ここでは appUserId や providerUserId など）を追加できます。
session: アプリケーション側で auth() から取り出すセッションオブジェクトを組み立てるコールバックです。JWT の中身を、アプリに見せたい形へ整えるのが役割です。

ログイン画面で puid に mock-user を入力してログインボタンを押した場合、これらは次の順で呼ばれます。

authorize({ puid: "mock-user" }): puid を検証し、{ id: "mock-user" } を返す
jwt: authorize が返した情報をもとに、JIT プロビジョニングで DB からユーザーを取得（なければ作成）し、appUserId などを JWT に積む
session: JWT の値をセッションに詰め替え、アプリから参照できる形に整える

この流れを頭に入れておくと、以降のコールバックの中身が読みやすくなります。では、authorize は任意の puid を受け取ってそのまま通すだけなので、キモとなるのは残りの2つです。session コールバックは本番と共通のものを使っており、jwt コールバックもモックと本番で中の処理（後述する JIT プロビジョニングの有無）こそ違うものの、JWT に積む情報の形（providerUserId, appUserId, provider）は揃えてあります。

JIT プロビジョニングで複数ユーザーに対応する

開発中は「ユーザーAとしてログインして確認」「ユーザーBとしてログインして権限を確認」といったシナリオが頻繁に発生します。モックだからといって単一ユーザー固定にしてしまうと、そうした検証がやりにくくなってしまいます。

そこで、JWT コールバックで JIT（Just-In-Time）プロビジョニング を行うようにしました。ログイン時に指定された puid がまだ DB に存在しなければ、そのタイミングでユーザーと所属組織を作成します。

async function mockJwtCallback({ token, account }) {
  if (!account) {
    return token;
  }

  const providerUserId = token.sub as string;

  // (provider, providerUserId) で既存ユーザーを探し、なければ
  // ユーザー・組織・組織メンバー・ExternalIdentity をトランザクション内で一括作成する
  const appUser = await userService.getOrCreateUserByExternalIdentity(
    AuthProvider.MOCK,
    providerUserId,
  );

  return {
    ...token,
    providerUserId,
    appUserId: appUser.id,
    provider: AuthProvider.MOCK,
  };
}

セッションコールバックを本番と共通化する

さて、この記事のキモとなるのが次の commonSessionCallback です。モックと本番で 完全に同じ関数 を使い回すことで、「セッションから取り出せる値の形」がモードに依らず一定です。

async function commonSessionCallback({ session, token }) {
  // jwt コールバックで積んだ error をそのまま伝搬
  if (token.error) {
    session.error = token.error as string;
    return session;
  }

  // DB 側でユーザーが削除・無効化されていないかを確認
  const validation = await validateUserExists(
    token.appUserId as string | undefined,
  );
  if (!validation.isValid) {
    session.error = validation.error;
    if (validation.error === "ActiveUserNotFound") {
      session.appUserId = undefined;
    }
    return session;
  }

  session.providerUserId = token.providerUserId as string | undefined;
  session.appUserId = token.appUserId as string | undefined;
  session.provider = token.provider as AuthProvider | undefined;
  return session;
}

中身はほぼ JWT からセッションへの値の詰め替えだけで、モック・本番の差は一切ありません。「ログイン済みユーザーを DB で再確認する」というプロダクト側の要件だけを淡々と満たす形となっています。この関数がモードに依存しない形で書けていることが、後の差し替えコストを最小にしてくれます。

セッション型も同じ形で固定しておきます。

declare module "next-auth" {
  interface Session {
    providerUserId?: string;
    appUserId?: string;
    provider?: AuthProvider;
    error?: string;
  }
}

アプリケーションのコードは、このセッションから session.appUserId を取り出して使うだけです。モックか本番かを意識する必要がありません。

export async function verifyWebsiteOwnership(websiteId: string) {
  const session = await auth();
  if (!session?.appUserId) {
    throw new UnauthorizedError();
  }

  const website = await websiteService.findByIdForUser(
    websiteId,
    session.appUserId,
  );
  if (!website) {
    throw new NotFoundError("Website not found");
  }
}

このガード関数が、モック時代も本番移行後もそのまま動いているというのが、この設計のポイントとなります。

本番ログインが決まった後の差し替え

その後、「ロリポップとムームードメインのアカウントで OIDC ログインする」という方針が確定しました。OIDC は NextAuth が標準でサポートしているので、Provider 設定を書くだけで基本的には動くようになっています。

function createOidcAuth() {
  const providers = [
    createOidcProviderConfig("muumuu", "Muumuu Domain", "MUUMUU"),
    createOidcProviderConfig("lolipop", "Lolipop", "LOLIPOP"),
  ].filter((p) => p !== null);

  return NextAuth({
    providers,
    trustHost: true,
    session: {
      strategy: "jwt",
      maxAge: 24 * 60 * 60,
      updateAge: 60 * 60,
    },
    callbacks: {
      signIn: oidcSignInCallback,
      jwt: oidcJwtCallbackWithProviderGuard,
      session: commonSessionCallback, // モック時代と同じもの
    },
    pages: { signIn: "/login" },
  });
}

重要なのは、session コールバックはモックと共通のものを使っているところです。セッションから取り出せる値（appUserId, provider, providerUserId）の形は変わっていないので、アプリ本体のコードはほぼそのままで動きました。OIDC 導入に伴う変更は、認証レイヤー内のファイル（新設した OIDC 用のコールバック群と起動時の分岐）にとどまり、ガード関数や Server Action などアプリ側の呼び出しコードは変更不要となっています。

JWT コールバックだけは OIDC 用に差し替わります。ムームー／ロリポップの OIDC では「契約 API 側で事前に作成済みのユーザーに対してログインを許可する」というルールとなっているため、getOrCreateUserByExternalIdentity（なければ作る）ではなく getUserByExternalIdentity（見つからなければログイン拒否）を使う点がモックとの違いとなります。

モードの切り替えは、どちらのファクトリ関数を呼ぶかを差し替えるだけとなっています。

// OIDC モードで起動する場合
const nextAuth = createOidcAuth();

// モック認証モードで起動する場合
const nextAuth = createMockAuth();

export const { handlers, auth, signIn, signOut } = nextAuth;

本番コードの書き換えはほぼこの一カ所で済み、シームレスな差し替えが実現できました。

副産物：モック認証が開発環境に残り続けている

最初から狙っていたこととはいえ、本番ログインが決まったあとも開発環境向けにモック認証モードを残せているというのは、実際に開発を回すうえで効いています。ローカル開発で puid を切り替えながら複数ユーザーのシナリオを試せるので、「差し替えのためのモック」がそのまま「開発体験のためのモック」として現役で動き続けている状態となります。

まとめ

決まっていない領域があるとき、「あとで差し替える」を本当にシームレスにやるには、本物と同じ形の偽物を用意するというのが有効なアプローチになります。ポイントを振り返ります。

差し替えるレイヤーを明確にする: 認証のやり方だけを偽物にし、セッション・テーブル構造・JIT プロビジョニングは本番と同じ形で作り込む
抽象の提供者を借りる: NextAuth のように「複数の認証方式を同じ抽象で扱う」ことが前提のフレームワークを土台にすると、差し替えが自然な操作となる
モックも本番と同列に扱う: AuthProvider.MOCK のように、モックを本番プロバイダーと同じ型・経路の上に載せることで、設計がぶれない

ログイン機構に限らず、要件が決まりきっていない依存を抱えたままプロダクトを前に進めたい場面は、開発の現場には少なくありません。そういうときは、決まっていない部分を特定のレイヤーに封じ込めつつ、それ以外は本番の設計で作り込む、という方針が有効です。どこまでを偽物で受け、どこから先は本番と同じ形で作るか、その線引きの設計こそが、不確実性を抱えたまま前に進むための要となります。

Pepabo Tech Portal

Agentic Engineering時代における「作り上げる力」を鍛える！2026年度新卒エンジニア研修を実施しました

はじめに

2026年度新卒エンジニア研修概要

Webアプリケーション研修(バックエンド)

フロントエンド研修

モデリング/設計研修

インフラ/仮想化研修

SRE研修

障害対応100本ノックの概要

設計意図

効果

セキュリティ研修

セキュリティレビュー体験

脆弱性診断の体験

機械学習＆データエンジニアリング研修

おわりに

ロリポップ！ゼロトラストリンクがLinuxとESP32に対応したのでStackChanで試してみる

PCからサーバ、IoTデバイスまで

これまでのIoTのつなぎ方との違い

StackChanに喋らせる

ESP32版の使い方

依存を追加する

接続情報を用意する

つなぐ

通信する

AIエージェントクラウドとつなぐ

おわりに

集約ジョブパターンで解決するモノレポCIのrequired check問題

TL;DR

背景：モノレポCIの「required check問題」

CI統合ゲートの変遷

第0世代：個別CIをrequired checkに登録（〜2026年3月）

第1世代：ポーリング方式のプロキシ（2026年3〜4月）

第2世代：イベント駆動化（2026年6月）

理想形の発見とPoC

PoCで動作検証

新アーキテクチャ：CI オーケストレータ

主要な設計決定

実装で遭遇した落とし穴と解決

concurrency group 衝突問題

workflow_run が発火しなくなる問題

check run 名の変化

変更検知の整合性

移行結果の比較

他プロジェクトへの導入ガイド

1. 各 CI の on: を workflow_call に変更

2. オーケストレータを作成

3. required check を aggregate に切り替え

注意点

まとめ

【レポート】毬藻企画とGMOペパボでWebアクセシビリティのイベントを開催しました！

この記事について

イベントの背景・概要

当日の様子

アクセシビリティウォークスルー

改善提案ディスカッション

イベントを振り返って

さいごに

GA 直後の Amazon S3 Files を SUZURI の本番 EKS に投入し コンテナイメージを 1/20 に圧縮した

はじめに

課題：assets が コンテナイメージに焼き込まれる構造的問題

lens/lens2 が扱う assets とは

移行前の状況

S3 Files という選択肢

当初の候補: EFS + DataSync

2026 年 4 月 7 日 GA: Amazon S3 Files

アーキテクチャ設計

移行後の全体像

設計のポイント

実装: lens2（Rust）で先行検証

EKS への S3 Files マウント

Phase 2a: 動作確認（並列マウント）

Phase 2b: ASSETS_DIR 切り替え

Phase 2c: Dockerfile から assets を除外

ハマりどころ: EFS CSI Driver を動かしてわかったこと

1. inline (Ephemeral) CSI volume は非対応

2. accessModes: ReadOnlyMany が非対応

3. volumeHandle に s3files: プレフィックスが必須

4. mountOptions: [iam] の明示指定が必要

1. 各 CI の `on:` を `workflow_call` に変更

3. required check を `aggregate` に切り替え

GA 直後の Amazon S3 Files を SUZURI の本番 EKS に投入しコンテナイメージを 1/20 に圧縮した

課題：assets がコンテナイメージに焼き込まれる構造的問題

2. `accessModes: ReadOnlyMany` が非対応

3. `volumeHandle` に `s3files:` プレフィックスが必須

4. `mountOptions: [iam]` の明示指定が必要

Import methodの選択 (`-aes-256` の有無)

ORDER BY id DESC が招くインデックス誤選択 — 直近のレコードを N 件取り出すクエリを実測約 658 倍に高速化

原因 — `ORDER BY id DESC` + `LIMIT N` で optimizer が PRIMARY を選ぶ

修正 — `ORDER BY` を既存インデックスのソート順に揃える

補足: `id DESC` と `ordered_at DESC` の意味的な差