feed.xml

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Pepabo Tech Portal</title>
  <id>https://tech.pepabo.com/</id>
  <link href="https://tech.pepabo.com/"/>
  <link href="https://tech.pepabo.com/feed.xml" rel="self"/>
  <updated>2026-06-12T00:00:00+09:00</updated>
  <author>
    <name>GMO Pepabo, Inc.</name>
  </author>
  <entry>
    <title>【レポート】毬藻企画とGMOペパボでWebアクセシビリティのイベントを開催しました！</title>
    <link rel="alternate" href="https://tech.pepabo.com/2026/06/12/suzuri-a11y-walkthrough/"/>
    <id>https://tech.pepabo.com/2026/06/12/suzuri-a11y-walkthrough/</id>
    <published>2026-06-12T00:00:00+09:00</published>
    <updated>2026-06-23T00:06:10+00:00</updated>
    <author>
      <name>tarutaru</name>
    </author>
    <content type="html">&lt;ol id="markdown-toc"&gt;
  &lt;li&gt;&lt;a href="#この記事について" id="markdown-toc-この記事について"&gt;この記事について&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#イベントの背景概要" id="markdown-toc-イベントの背景概要"&gt;イベントの背景・概要&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#当日の様子" id="markdown-toc-当日の様子"&gt;当日の様子&lt;/a&gt;    &lt;ol&gt;
      &lt;li&gt;&lt;a href="#アクセシビリティウォークスルー" id="markdown-toc-アクセシビリティウォークスルー"&gt;アクセシビリティウォークスルー&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#改善提案ディスカッション" id="markdown-toc-改善提案ディスカッション"&gt;改善提案ディスカッション&lt;/a&gt;&lt;/li&gt;
    &lt;/ol&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href="#イベントを振り返って" id="markdown-toc-イベントを振り返って"&gt;イベントを振り返って&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#さいごに" id="markdown-toc-さいごに"&gt;さいごに&lt;/a&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;h2 id="この記事について"&gt;この記事について&lt;/h2&gt;

&lt;p&gt;GMOペパボの&lt;a href="https://x.com/tarutaruio"&gt;tarutaru&lt;/a&gt;です。&lt;/p&gt;

&lt;p&gt;2026年3月24日、アクセシビリティエキスパート集団である&lt;a href="https://marimokikakugk.com/"&gt;毬藻企画合同会社&lt;/a&gt;さんとの共催で、「&lt;a href="https://pepabo.connpass.com/event/385692/"&gt;【GMOペパボ・毬藻企画】スクリーンリーダーによる実践的アクセシビリティウォークスルー 〜SUZURI byGMOペパボ編〜&lt;/a&gt;」というイベントを開催しました。&lt;/p&gt;

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

&lt;h2 id="イベントの背景概要"&gt;イベントの背景・概要&lt;/h2&gt;

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

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

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

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

&lt;p&gt;当日は、全盲のエンジニアである&lt;a href="https://yncat.net/"&gt;catさん（野澤 幸男さん）&lt;/a&gt;をゲストとしてお招きし、SUZURIをスクリーンリーダー（NVDA）で操作しながらウォークスルーを実施いただきました。ウォークスルー中は、毬藻企画の&lt;a href="https://x.com/magi1125"&gt;伊原さん&lt;/a&gt;がファシリテートと解説を担当。ウォークスルー後には、catさん・伊原さんに加え、毬藻企画の&lt;a href="https://x.com/mt_dew2"&gt;坂巻さん&lt;/a&gt;、SUZURIデザイナーの&lt;a href="https://tech.pepabo.com/authors/%E3%83%84%E3%83%90%E3%82%B5/"&gt;白石さん&lt;/a&gt;・&lt;a href="https://x.com/na0v0_matsu"&gt;並松さん&lt;/a&gt;も加わり問題点の振り返りと改善方法のディスカッションを行いました。&lt;/p&gt;

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

&lt;h2 id="当日の様子"&gt;当日の様子&lt;/h2&gt;

&lt;h3 id="アクセシビリティウォークスルー"&gt;アクセシビリティウォークスルー&lt;/h3&gt;

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

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

&lt;p&gt;&lt;img src="/blog/2026/06/12/suzuri-a11y-walkthrough/walkthrough.jpg" alt="ウォークスルー中の会場の様子。参加者が着席して見守るなか、登壇者2名がスクリーン脇に立っている。メインスクリーンにはSUZURIのページが映し出され、サブモニターにはUDトークの字幕が表示されている" /&gt;&lt;/p&gt;

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

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

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

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

&lt;p&gt;catさんはこの問題について、こう表現しました。&lt;/p&gt;

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

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

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

&lt;h3 id="改善提案ディスカッション"&gt;改善提案ディスカッション&lt;/h3&gt;

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

&lt;p&gt;&lt;img src="/blog/2026/06/12/suzuri-a11y-walkthrough/discussion.jpg" alt="改善提案ディスカッション中の会場の様子。参加者が着席して見守るなか、複数の登壇者がスクリーン脇から発言している。メインスクリーンにはSUZURIのページが映し出され、サブモニターにはUDトークの字幕が表示されている" /&gt;&lt;/p&gt;

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

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

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

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

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

&lt;h2 id="イベントを振り返って"&gt;イベントを振り返って&lt;/h2&gt;

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

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

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

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

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

&lt;blockquote&gt;
  &lt;p&gt;みんなでいいものができていけばいいんじゃないかな。&lt;/p&gt;
&lt;/blockquote&gt;

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

&lt;h2 id="さいごに"&gt;さいごに&lt;/h2&gt;

&lt;p&gt;以上、イベントのふりかえりでした。&lt;/p&gt;

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

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

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

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

&lt;p&gt;アクセシビリティに関わるみなさんも、これから興味を持つみなさんも、一緒に学び、いいものづくりをしましょう！&lt;/p&gt;
</content>
  </entry>
  <entry>
    <title>GA 直後の Amazon S3 Files を SUZURI の本番 EKS に投入し コンテナイメージを 1/20 に圧縮した</title>
    <link rel="alternate" href="https://tech.pepabo.com/2026/05/13/s3-files-suzuri-lens/"/>
    <id>https://tech.pepabo.com/2026/05/13/s3-files-suzuri-lens/</id>
    <published>2026-05-13T00:00:00+09:00</published>
    <updated>2026-06-23T00:06:10+00:00</updated>
    <author>
      <name>shibatch</name>
    </author>
    <content type="html">&lt;ol id="markdown-toc"&gt;
  &lt;li&gt;&lt;a href="#はじめに" id="markdown-toc-はじめに"&gt;はじめに&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#課題assets-が-コンテナイメージに焼き込まれる構造的問題" id="markdown-toc-課題assets-が-コンテナイメージに焼き込まれる構造的問題"&gt;課題：assets が コンテナイメージに焼き込まれる構造的問題&lt;/a&gt;    &lt;ol&gt;
      &lt;li&gt;&lt;a href="#lenslens2-が扱う-assets-とは" id="markdown-toc-lenslens2-が扱う-assets-とは"&gt;lens/lens2 が扱う assets とは&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#移行前の状況" id="markdown-toc-移行前の状況"&gt;移行前の状況&lt;/a&gt;&lt;/li&gt;
    &lt;/ol&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href="#s3-files-という選択肢" id="markdown-toc-s3-files-という選択肢"&gt;S3 Files という選択肢&lt;/a&gt;    &lt;ol&gt;
      &lt;li&gt;&lt;a href="#当初の候補-efs--datasync" id="markdown-toc-当初の候補-efs--datasync"&gt;当初の候補: EFS + DataSync&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#2026-年-4-月-7-日-ga-amazon-s3-files" id="markdown-toc-2026-年-4-月-7-日-ga-amazon-s3-files"&gt;2026 年 4 月 7 日 GA: Amazon S3 Files&lt;/a&gt;&lt;/li&gt;
    &lt;/ol&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href="#アーキテクチャ設計" id="markdown-toc-アーキテクチャ設計"&gt;アーキテクチャ設計&lt;/a&gt;    &lt;ol&gt;
      &lt;li&gt;&lt;a href="#移行後の全体像" id="markdown-toc-移行後の全体像"&gt;移行後の全体像&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#設計のポイント" id="markdown-toc-設計のポイント"&gt;設計のポイント&lt;/a&gt;&lt;/li&gt;
    &lt;/ol&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href="#実装-lens2rustで先行検証" id="markdown-toc-実装-lens2rustで先行検証"&gt;実装: lens2（Rust）で先行検証&lt;/a&gt;    &lt;ol&gt;
      &lt;li&gt;&lt;a href="#eks-への-s3-files-マウント" id="markdown-toc-eks-への-s3-files-マウント"&gt;EKS への S3 Files マウント&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#phase-2a-動作確認並列マウント" id="markdown-toc-phase-2a-動作確認並列マウント"&gt;Phase 2a: 動作確認（並列マウント）&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#phase-2b-assets_dir-切り替え" id="markdown-toc-phase-2b-assets_dir-切り替え"&gt;Phase 2b: ASSETS_DIR 切り替え&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#phase-2c-dockerfile-から-assets-を除外" id="markdown-toc-phase-2c-dockerfile-から-assets-を除外"&gt;Phase 2c: Dockerfile から assets を除外&lt;/a&gt;&lt;/li&gt;
    &lt;/ol&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href="#ハマりどころ-efs-csi-driver-を動かしてわかったこと" id="markdown-toc-ハマりどころ-efs-csi-driver-を動かしてわかったこと"&gt;ハマりどころ: EFS CSI Driver を動かしてわかったこと&lt;/a&gt;    &lt;ol&gt;
      &lt;li&gt;&lt;a href="#1-inline-ephemeral-csi-volume-は非対応" id="markdown-toc-1-inline-ephemeral-csi-volume-は非対応"&gt;1. inline (Ephemeral) CSI volume は非対応&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#2-accessmodes-readonlymany-が非対応" id="markdown-toc-2-accessmodes-readonlymany-が非対応"&gt;2. &lt;code&gt;accessModes: ReadOnlyMany&lt;/code&gt; が非対応&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#3-volumehandle-に-s3files-プレフィックスが必須" id="markdown-toc-3-volumehandle-に-s3files-プレフィックスが必須"&gt;3. &lt;code&gt;volumeHandle&lt;/code&gt; に &lt;code&gt;s3files:&lt;/code&gt; プレフィックスが必須&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#4-mountoptions-iam-の明示指定が必要" id="markdown-toc-4-mountoptions-iam-の明示指定が必要"&gt;4. &lt;code&gt;mountOptions: [iam]&lt;/code&gt; の明示指定が必要&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#5-controller-sa-と-node-sa-に別々の-iam-ロールが必要" id="markdown-toc-5-controller-sa-と-node-sa-に別々の-iam-ロールが必要"&gt;5. controller SA と node SA に別々の IAM ロールが必要&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#補足-s3-files-障害時の挙動と監視" id="markdown-toc-補足-s3-files-障害時の挙動と監視"&gt;補足: S3 Files 障害時の挙動と監視&lt;/a&gt;&lt;/li&gt;
    &lt;/ol&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href="#計測結果" id="markdown-toc-計測結果"&gt;計測結果&lt;/a&gt;    &lt;ol&gt;
      &lt;li&gt;&lt;a href="#lens2rust本番実測" id="markdown-toc-lens2rust本番実測"&gt;lens2（Rust）本番実測&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#lensjavascript本番実測" id="markdown-toc-lensjavascript本番実測"&gt;lens（JavaScript）本番実測&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#s3-files-の読み取りレイテンシlens-本番実測" id="markdown-toc-s3-files-の読み取りレイテンシlens-本番実測"&gt;S3 Files の読み取りレイテンシ（lens 本番実測）&lt;/a&gt;&lt;/li&gt;
    &lt;/ol&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href="#lensjavascriptへのロールアウト" id="markdown-toc-lensjavascriptへのロールアウト"&gt;lens（JavaScript）へのロールアウト&lt;/a&gt;    &lt;ol&gt;
      &lt;li&gt;&lt;a href="#lens-ならではの差異-上書きマウント方式" id="markdown-toc-lens-ならではの差異-上書きマウント方式"&gt;lens ならではの差異: 上書きマウント方式&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#lens2-のノウハウがそのまま活きた" id="markdown-toc-lens2-のノウハウがそのまま活きた"&gt;lens2 のノウハウがそのまま活きた&lt;/a&gt;&lt;/li&gt;
    &lt;/ol&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href="#まとめ" id="markdown-toc-まとめ"&gt;まとめ&lt;/a&gt;    &lt;ol&gt;
      &lt;li&gt;&lt;a href="#成果サマリ" id="markdown-toc-成果サマリ"&gt;成果サマリ&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#s3-files-を選んでよかった点" id="markdown-toc-s3-files-を選んでよかった点"&gt;S3 Files を選んでよかった点&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#さいごに" id="markdown-toc-さいごに"&gt;さいごに&lt;/a&gt;&lt;/li&gt;
    &lt;/ol&gt;
  &lt;/li&gt;
&lt;/ol&gt;

&lt;h2 id="はじめに"&gt;はじめに&lt;/h2&gt;

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

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

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

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

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

&lt;hr /&gt;

&lt;h2 id="課題assets-が-コンテナイメージに焼き込まれる構造的問題"&gt;課題：assets が コンテナイメージに焼き込まれる構造的問題&lt;/h2&gt;

&lt;h3 id="lenslens2-が扱う-assets-とは"&gt;lens/lens2 が扱う assets とは&lt;/h3&gt;

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

&lt;h3 id="移行前の状況"&gt;移行前の状況&lt;/h3&gt;

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

&lt;p&gt;&lt;img src="/blog/2026/05/13/s3-files-suzuri-lens/before-architecture.png" alt="図1: 移行前アーキテクチャ。assets がイメージに焼き込まれているため、ビルド・起動・ECR コストがすべて assets のサイズに比例する" /&gt;&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;サービス&lt;/th&gt;
      &lt;th&gt;assets サイズ&lt;/th&gt;
      &lt;th&gt;コンテナイメージ（ECR 圧縮後）&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;lens2&lt;/td&gt;
      &lt;td&gt;1.7 GB&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;1.75 GB&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;lens&lt;/td&gt;
      &lt;td&gt;8.6 GB&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;10.3 GB&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

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

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

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

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;サービス&lt;/th&gt;
      &lt;th&gt;Image pull（cold）&lt;/th&gt;
      &lt;th&gt;Pod Scheduled→Ready（cold）&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;lens2&lt;/td&gt;
      &lt;td&gt;—&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;86〜102 秒&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;lens&lt;/td&gt;
      &lt;td&gt;5 分 03 秒&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;約 5〜5.5 分&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

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

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

&lt;hr /&gt;

&lt;h2 id="s3-files-という選択肢"&gt;S3 Files という選択肢&lt;/h2&gt;

&lt;h3 id="当初の候補-efs--datasync"&gt;当初の候補: EFS + DataSync&lt;/h3&gt;

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

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

&lt;h3 id="2026-年-4-月-7-日-ga-amazon-s3-files"&gt;2026 年 4 月 7 日 GA: Amazon S3 Files&lt;/h3&gt;

&lt;p&gt;アーキテクチャを検討していたタイミングで、AWS が &lt;a href="https://aws.amazon.com/blogs/aws/launching-s3-files-making-s3-buckets-accessible-as-file-systems/"&gt;Amazon S3 Files&lt;/a&gt; を GA リリースしました。&lt;/p&gt;

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

&lt;p&gt;&lt;img src="/blog/2026/05/13/s3-files-suzuri-lens/s3-files-concept.png" alt="図2: S3 Files の仕組み。S3 バケットが直接 NFS エンドポイントになる。DataSync 不要" /&gt;&lt;/p&gt;

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

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

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

&lt;hr /&gt;

&lt;h2 id="アーキテクチャ設計"&gt;アーキテクチャ設計&lt;/h2&gt;

&lt;h3 id="移行後の全体像"&gt;移行後の全体像&lt;/h3&gt;

&lt;p&gt;&lt;img src="/blog/2026/05/13/s3-files-suzuri-lens/after-architecture.png" alt="図3: 移行後アーキテクチャ。assets は S3 Files 経由で Pod に NFS マウントされ、コンテナイメージには含まれない" /&gt;&lt;/p&gt;

&lt;h3 id="設計のポイント"&gt;設計のポイント&lt;/h3&gt;

&lt;p&gt;&lt;strong&gt;assets をコードリポジトリから完全分離する&lt;/strong&gt;&lt;/p&gt;

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

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

&lt;p&gt;&lt;strong&gt;ゼロダウンタイムの段階的移行&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;&lt;img src="/blog/2026/05/13/s3-files-suzuri-lens/migration-phases.png" alt="図4: 段階的移行フェーズ。Phase 2a で既存イメージと S3 Files を並存させ、安全を確認してから切り替える" /&gt;&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Phase 1:  S3 バケット作成 + S3 Files 有効化
Phase 2a: 既存 Pod に S3 Files を追加マウントして動作確認
Phase 2b: assets の参照先を S3 Files に切り替え
Phase 2c: Dockerfile から assets を除外 → イメージ軽量化
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;Phase 2a がこの設計の安全弁です。既存イメージを稼働させたまま別パスに S3 Files をマウントし、ファイルの内容とレイテンシを確認します。マウントに失敗しても Kubernetes の rolling update により旧 ReplicaSet がそのまま動き続けるため、本番トラフィックへの影響はゼロです。なお Phase 2c 以降はイメージから assets が除去されるため、fat image への即時ロールバックは現実的ではありません。S3 Files の可用性に依存した設計となる点は後述します。&lt;/p&gt;

&lt;hr /&gt;

&lt;h2 id="実装-lens2rustで先行検証"&gt;実装: lens2（Rust）で先行検証&lt;/h2&gt;

&lt;h3 id="eks-への-s3-files-マウント"&gt;EKS への S3 Files マウント&lt;/h3&gt;

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

&lt;div class="highlight"&gt;&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="c1"&gt;# PersistentVolume&lt;/span&gt;
&lt;span class="na"&gt;apiVersion&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;v1&lt;/span&gt;
&lt;span class="na"&gt;kind&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;PersistentVolume&lt;/span&gt;
&lt;span class="na"&gt;metadata&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;lens2-assets&lt;/span&gt;
&lt;span class="na"&gt;spec&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;capacity&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;storage&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;100Gi&lt;/span&gt;
  &lt;span class="na"&gt;accessModes&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="s"&gt;ReadWriteMany&lt;/span&gt;
  &lt;span class="na"&gt;mountOptions&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="s"&gt;iam&lt;/span&gt;
  &lt;span class="na"&gt;csi&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;driver&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;efs.csi.aws.com&lt;/span&gt;
    &lt;span class="na"&gt;volumeHandle&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;s3files:fs-xxxxxxxxxxxxxxxxx"&lt;/span&gt;  &lt;span class="c1"&gt;# s3files: プレフィックス必須&lt;/span&gt;
    &lt;span class="na"&gt;readOnly&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="no"&gt;true&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;div class="highlight"&gt;&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="c1"&gt;# Deployment への追加&lt;/span&gt;
&lt;span class="na"&gt;volumeMounts&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;s3-assets&lt;/span&gt;
    &lt;span class="na"&gt;mountPath&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;/mnt/s3-assets&lt;/span&gt;
    &lt;span class="na"&gt;readOnly&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="no"&gt;true&lt;/span&gt;
&lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;s3-assets&lt;/span&gt;
    &lt;span class="na"&gt;persistentVolumeClaim&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;claimName&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;lens2-assets&lt;/span&gt;
      &lt;span class="na"&gt;readOnly&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="no"&gt;true&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;h3 id="phase-2a-動作確認並列マウント"&gt;Phase 2a: 動作確認（並列マウント）&lt;/h3&gt;

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

&lt;h3 id="phase-2b-assets_dir-切り替え"&gt;Phase 2b: ASSETS_DIR 切り替え&lt;/h3&gt;

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

&lt;h3 id="phase-2c-dockerfile-から-assets-を除外"&gt;Phase 2c: Dockerfile から assets を除外&lt;/h3&gt;

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

&lt;div class="highlight"&gt;&lt;pre class="highlight docker"&gt;&lt;code&gt;&lt;span class="c"&gt;# Before（削除する行）&lt;/span&gt;
&lt;span class="k"&gt;COPY&lt;/span&gt;&lt;span class="s"&gt; ./assets ./assets&lt;/span&gt;
&lt;span class="k"&gt;COPY&lt;/span&gt;&lt;span class="s"&gt; --from=builder /lens2/assets /lens2/assets&lt;/span&gt;

&lt;span class="c"&gt;# After: 上記 2 行を削除するだけ&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;これでイメージから assets が消え、ビルドと pull が劇的に速くなります。&lt;/p&gt;

&lt;hr /&gt;

&lt;h2 id="ハマりどころ-efs-csi-driver-を動かしてわかったこと"&gt;ハマりどころ: EFS CSI Driver を動かしてわかったこと&lt;/h2&gt;

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

&lt;h3 id="1-inline-ephemeral-csi-volume-は非対応"&gt;1. inline (Ephemeral) CSI volume は非対応&lt;/h3&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Error: volume mode 'Ephemeral' not supported by driver efs.csi.aws.com
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;S3 Files のマウントには &lt;strong&gt;PersistentVolume / PersistentVolumeClaim&lt;/strong&gt; が必要です。Pod spec へのインライン定義（Ephemeral volume）はサポートされていません。&lt;/p&gt;

&lt;h3 id="2-accessmodes-readonlymany-が非対応"&gt;2. &lt;code&gt;accessModes: ReadOnlyMany&lt;/code&gt; が非対応&lt;/h3&gt;

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

&lt;h3 id="3-volumehandle-に-s3files-プレフィックスが必須"&gt;3. &lt;code&gt;volumeHandle&lt;/code&gt; に &lt;code&gt;s3files:&lt;/code&gt; プレフィックスが必須&lt;/h3&gt;

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

&lt;h3 id="4-mountoptions-iam-の明示指定が必要"&gt;4. &lt;code&gt;mountOptions: [iam]&lt;/code&gt; の明示指定が必要&lt;/h3&gt;

&lt;p&gt;&lt;strong&gt;&lt;code&gt;mountOptions&lt;/code&gt; への &lt;code&gt;iam&lt;/code&gt; の明示指定は省略できません。&lt;/strong&gt; ドキュメント（&lt;a href="https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/docs/parameters.md"&gt;&lt;code&gt;docs/parameters.md&lt;/code&gt;&lt;/a&gt;）では optional な mountOption の一例として列挙されているだけで、デフォルト適用はされません。省略すると mount 時に &lt;code&gt;access denied by server&lt;/code&gt; が返ります。&lt;/p&gt;

&lt;h3 id="5-controller-sa-と-node-sa-に別々の-iam-ロールが必要"&gt;5. controller SA と node SA に別々の IAM ロールが必要&lt;/h3&gt;

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

&lt;h3 id="補足-s3-files-障害時の挙動と監視"&gt;補足: S3 Files 障害時の挙動と監視&lt;/h3&gt;

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

&lt;p&gt;この点への対策を整理します。&lt;/p&gt;

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

&lt;hr /&gt;

&lt;h2 id="計測結果"&gt;計測結果&lt;/h2&gt;

&lt;h3 id="lens2rust本番実測"&gt;lens2（Rust）本番実測&lt;/h3&gt;

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

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

&lt;h3 id="lensjavascript本番実測"&gt;lens（JavaScript）本番実測&lt;/h3&gt;

&lt;p&gt;Before の値は S3 Files 導入前の実測値です。&lt;/p&gt;

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

&lt;h3 id="s3-files-の読み取りレイテンシlens-本番実測"&gt;S3 Files の読み取りレイテンシ（lens 本番実測）&lt;/h3&gt;

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

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

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

&lt;hr /&gt;

&lt;h2 id="lensjavascriptへのロールアウト"&gt;lens（JavaScript）へのロールアウト&lt;/h2&gt;

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

&lt;h3 id="lens-ならではの差異-上書きマウント方式"&gt;lens ならではの差異: 上書きマウント方式&lt;/h3&gt;

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

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

&lt;div class="highlight"&gt;&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="c1"&gt;# lens の場合: アプリの参照パスに直接マウントして shadow&lt;/span&gt;
&lt;span class="na"&gt;volumeMounts&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;s3-assets&lt;/span&gt;
    &lt;span class="na"&gt;mountPath&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;/suzuri-lens/assets&lt;/span&gt;   &lt;span class="c1"&gt;# アプリの参照先パスと一致させる&lt;/span&gt;
    &lt;span class="na"&gt;readOnly&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="no"&gt;true&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;Phase 2b では「既存イメージ（assets 焼き込み）+ S3 Files の上書きマウント」の並存状態になります。どちらのソースから読んでも内容は同一なので、切り替えは透過的です。Phase 2c で軽量イメージに更新すると、S3 Files が唯一の assets ソースになります。&lt;/p&gt;

&lt;h3 id="lens2-のノウハウがそのまま活きた"&gt;lens2 のノウハウがそのまま活きた&lt;/h3&gt;

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

&lt;hr /&gt;

&lt;h2 id="まとめ"&gt;まとめ&lt;/h2&gt;

&lt;h3 id="成果サマリ"&gt;成果サマリ&lt;/h3&gt;

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

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

&lt;h3 id="s3-files-を選んでよかった点"&gt;S3 Files を選んでよかった点&lt;/h3&gt;

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

&lt;h3 id="さいごに"&gt;さいごに&lt;/h3&gt;

&lt;p&gt;正直、GA直後のサービスを本番に入れることにはリスクがありました。GA当日は2026年4月7日で、lens/lens2両方がそろったのがゴールデンウィークを挟んだ5月7日です。実質3週間ほどでここまでできたのは、lens2でスモールスタートしてからlensへ展開するという段階的な設計が効いていたと思います。lens2のほうがトラフィックが少ないため、仮に問題が起きてもロールバックできる状態で実績を積み、ゴールデンウィーク中にレイテンシの計測実績を蓄積してからlensへ投入するという順序があったからこそ、自信を持って進められました。「新しいものを本番に入れることにリスクがある」のは、裏を返せば計測と段階的な設計で解決できる問題でした。この取り組みがどなたかの背中を押せたら嬉しいです。&lt;/p&gt;
</content>
  </entry>
  <entry>
    <title>GitHub Actionsの実行遅延をCloud SchedulerとCloud Workflowsで解消する</title>
    <link rel="alternate" href="https://tech.pepabo.com/2026/05/11/cloud-workflows-github-actions-trigger/"/>
    <id>https://tech.pepabo.com/2026/05/11/cloud-workflows-github-actions-trigger/</id>
    <published>2026-05-11T00:00:00+09:00</published>
    <updated>2026-06-23T00:06:10+00:00</updated>
    <author>
      <name>zaimy</name>
    </author>
    <content type="html">&lt;p&gt;こんにちは、技術部データ基盤チームの &lt;a href="https://x.com/hirokazaitsu"&gt;zaimy&lt;/a&gt; です。&lt;/p&gt;

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

&lt;ol id="markdown-toc"&gt;
  &lt;li&gt;&lt;a href="#背景" id="markdown-toc-背景"&gt;背景&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#検討した構成" id="markdown-toc-検討した構成"&gt;検討した構成&lt;/a&gt;    &lt;ol&gt;
      &lt;li&gt;&lt;a href="#案a-cloud-schedulerからgithub-apiを直接叩く" id="markdown-toc-案a-cloud-schedulerからgithub-apiを直接叩く"&gt;案A: Cloud SchedulerからGitHub APIを直接叩く&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#案b-cloud-schedulerから起動するcloud-workflowsでgithub-actionsを置き換える" id="markdown-toc-案b-cloud-schedulerから起動するcloud-workflowsでgithub-actionsを置き換える"&gt;案B: Cloud Schedulerから起動するCloud WorkflowsでGitHub Actionsを置き換える&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#案c-採用-cloud-schedulerから起動するcloud-workflowsがgithub-actionsをdispatchする" id="markdown-toc-案c-採用-cloud-schedulerから起動するcloud-workflowsがgithub-actionsをdispatchする"&gt;案C (採用): Cloud Schedulerから起動するCloud WorkflowsがGitHub Actionsをdispatchする&lt;/a&gt;&lt;/li&gt;
    &lt;/ol&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href="#なぜcloud-kmsが必要なのか" id="markdown-toc-なぜcloud-kmsが必要なのか"&gt;なぜCloud KMSが必要なのか&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#実装" id="markdown-toc-実装"&gt;実装&lt;/a&gt;    &lt;ol&gt;
      &lt;li&gt;&lt;a href="#cloud-kms-asymmetric-keyの作成-terraform" id="markdown-toc-cloud-kms-asymmetric-keyの作成-terraform"&gt;Cloud KMS asymmetric keyの作成 (terraform)&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#github-appのprivate-keyをcloud-kmsにimport" id="markdown-toc-github-appのprivate-keyをcloud-kmsにimport"&gt;GitHub Appのprivate keyをCloud KMSにimport&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#cloud-workflowsのyaml" id="markdown-toc-cloud-workflowsのyaml"&gt;Cloud WorkflowsのYAML&lt;/a&gt;&lt;/li&gt;
    &lt;/ol&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href="#ハマりどころ" id="markdown-toc-ハマりどころ"&gt;ハマりどころ&lt;/a&gt;    &lt;ol&gt;
      &lt;li&gt;&lt;a href="#import-methodの選択--aes-256-の有無" id="markdown-toc-import-methodの選択--aes-256-の有無"&gt;Import methodの選択 (&lt;code&gt;-aes-256&lt;/code&gt; の有無)&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#pem--pkcs8-derへの変換" id="markdown-toc-pem--pkcs8-derへの変換"&gt;PEM → PKCS#8 DERへの変換&lt;/a&gt;&lt;/li&gt;
    &lt;/ol&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href="#結果" id="markdown-toc-結果"&gt;結果&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#その他の構成案" id="markdown-toc-その他の構成案"&gt;その他の構成案&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#まとめ" id="markdown-toc-まとめ"&gt;まとめ&lt;/a&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;h2 id="背景"&gt;背景&lt;/h2&gt;

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

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

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;日付&lt;/th&gt;
      &lt;th&gt;cron 設定 (UTC)&lt;/th&gt;
      &lt;th&gt;実際の実行時刻 (UTC)&lt;/th&gt;
      &lt;th&gt;遅延&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;4/22 Wed&lt;/td&gt;
      &lt;td&gt;02:55&lt;/td&gt;
      &lt;td&gt;03:55&lt;/td&gt;
      &lt;td&gt;+60min&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;4/21 Tue&lt;/td&gt;
      &lt;td&gt;02:55&lt;/td&gt;
      &lt;td&gt;03:57&lt;/td&gt;
      &lt;td&gt;+62min&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;4/20 Mon&lt;/td&gt;
      &lt;td&gt;02:55&lt;/td&gt;
      &lt;td&gt;04:02&lt;/td&gt;
      &lt;td&gt;+67min&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;GitHub Actionsの &lt;code&gt;schedule:&lt;/code&gt; はベストエフォートで、混雑時は遅延・スキップされる仕様です。これは &lt;a href="https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule"&gt;GitHub公式ドキュメント&lt;/a&gt; にも明記されています。&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;Note: The &lt;code&gt;schedule&lt;/code&gt; 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.&lt;/p&gt;
&lt;/blockquote&gt;

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

&lt;h2 id="検討した構成"&gt;検討した構成&lt;/h2&gt;

&lt;h3 id="案a-cloud-schedulerからgithub-apiを直接叩く"&gt;案A: Cloud SchedulerからGitHub APIを直接叩く&lt;/h3&gt;

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

&lt;p&gt;棄却理由: Cloud SchedulerのHTTPターゲットの認証オプションは、&lt;/p&gt;

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

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

&lt;h3 id="案b-cloud-schedulerから起動するcloud-workflowsでgithub-actionsを置き換える"&gt;案B: Cloud Schedulerから起動するCloud WorkflowsでGitHub Actionsを置き換える&lt;/h3&gt;

&lt;p&gt;&lt;a href="https://cloud.google.com/workflows"&gt;Cloud Workflows&lt;/a&gt; はYAMLで処理を記述するワークフローエンジンで、HTTPコール、Secret Manager / KMS / BigQueryなどのGoogle Cloudサービス連携、リトライ、分岐、ループを書けます。&lt;/p&gt;

&lt;p&gt;&lt;a href="https://tech.pepabo.com/2026/05/11/cloud-composer-retirement/"&gt;データ基盤のワークフロー構成変更によるコスト84%削減とCI 34倍高速化&lt;/a&gt; で紹介している通り、ペパボのデータ基盤ではすでにCloud SchedulerとCloud Workflowsの利用実績があるため、Cloud Workflowsで既存のActionを置き換えられるのでは、というアイデアです。&lt;/p&gt;

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

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

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

&lt;h3 id="案c-採用-cloud-schedulerから起動するcloud-workflowsがgithub-actionsをdispatchする"&gt;案C (採用): Cloud Schedulerから起動するCloud WorkflowsがGitHub Actionsをdispatchする&lt;/h3&gt;

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

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;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を起動 (既存のラベル付けスクリプトが走る)
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;各レイヤの責務がきれいに分かれます。&lt;/p&gt;

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

&lt;h2 id="なぜcloud-kmsが必要なのか"&gt;なぜCloud KMSが必要なのか&lt;/h2&gt;

&lt;p&gt;GitHub Appのトークン取得フローはこうです。&lt;/p&gt;

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

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

&lt;p&gt;回避策は以下の通りで、今回はCloud KMSを利用しました。&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;案&lt;/th&gt;
      &lt;th&gt;署名する場所&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;Cloud KMS asymmetricSign&lt;/td&gt;
      &lt;td&gt;KMS (鍵をimportして署名APIを呼ぶ)&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Cloud Run や Cloud Run Functionsを挟む&lt;/td&gt;
      &lt;td&gt;Python &lt;code&gt;pyjwt&lt;/code&gt; 等で署名&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;h2 id="実装"&gt;実装&lt;/h2&gt;

&lt;h3 id="cloud-kms-asymmetric-keyの作成-terraform"&gt;Cloud KMS asymmetric keyの作成 (terraform)&lt;/h3&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="nx"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"google_kms_key_ring"&lt;/span&gt; &lt;span class="s2"&gt;"workflows"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;name&lt;/span&gt;     &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"workflows"&lt;/span&gt;
  &lt;span class="nx"&gt;location&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;var&lt;/span&gt;&lt;span class="err"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;region&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"google_kms_crypto_key"&lt;/span&gt; &lt;span class="s2"&gt;"github_app"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;name&lt;/span&gt;     &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"github-app-private-key"&lt;/span&gt;
  &lt;span class="nx"&gt;key_ring&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;google_kms_key_ring&lt;/span&gt;&lt;span class="err"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;workflows&lt;/span&gt;&lt;span class="err"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;
  &lt;span class="nx"&gt;purpose&lt;/span&gt;  &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"ASYMMETRIC_SIGN"&lt;/span&gt;

  &lt;span class="c1"&gt;# 既存の GitHub App private key を後から import するため初期バージョンは作らない&lt;/span&gt;
  &lt;span class="nx"&gt;skip_initial_version_creation&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;

  &lt;span class="nx"&gt;version_template&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;algorithm&lt;/span&gt;        &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"RSA_SIGN_PKCS1_2048_SHA256"&lt;/span&gt;
    &lt;span class="nx"&gt;protection_level&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"SOFTWARE"&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"google_kms_crypto_key_iam_member"&lt;/span&gt; &lt;span class="s2"&gt;"github_app_signer"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;for_each&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;toset&lt;/span&gt;&lt;span class="err"&gt;(&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;
    &lt;span class="s2"&gt;"prod-serviceaccount@{project}.iam.gserviceaccount.com"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="s2"&gt;"test-serviceaccount@{project}.iam.gserviceaccount.com"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="err"&gt;)&lt;/span&gt;

  &lt;span class="nx"&gt;crypto_key_id&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;google_kms_crypto_key&lt;/span&gt;&lt;span class="err"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;github_app&lt;/span&gt;&lt;span class="err"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;
  &lt;span class="nx"&gt;role&lt;/span&gt;          &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"roles/cloudkms.signerVerifier"&lt;/span&gt;
  &lt;span class="nx"&gt;member&lt;/span&gt;        &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"serviceAccount:${each.value}"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;h3 id="github-appのprivate-keyをcloud-kmsにimport"&gt;GitHub Appのprivate keyをCloud KMSにimport&lt;/h3&gt;

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

&lt;div class="highlight"&gt;&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# 1. import job を作成する。AES wrapping を含む -aes-256 つきを使う。&lt;/span&gt;
gcloud kms import-jobs create import-github-app &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="nt"&gt;--location&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;us-central1 &lt;span class="nt"&gt;--keyring&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;workflows &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="nt"&gt;--import-method&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;rsa-oaep-3072-sha256-aes-256 &lt;span class="nt"&gt;--protection-level&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;software

&lt;span class="c"&gt;# 2. import job が ACTIVE になるまで数分待つ。&lt;/span&gt;
gcloud kms import-jobs describe import-github-app &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="nt"&gt;--location&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;us-central1 &lt;span class="nt"&gt;--keyring&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;workflows &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="nt"&gt;--format&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s1"&gt;'value(state)'&lt;/span&gt;

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

&lt;span class="c"&gt;# 4. private key を import する。&lt;/span&gt;
gcloud kms keys versions import &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="nt"&gt;--import-job&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;import-github-app &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="nt"&gt;--location&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;us-central1 &lt;span class="nt"&gt;--keyring&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;workflows &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="nt"&gt;--key&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;github-app-private-key &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="nt"&gt;--algorithm&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;rsa-sign-pkcs1-2048-sha256 &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="nt"&gt;--target-key-file&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;/tmp/gh_app.der

&lt;span class="c"&gt;# 5. 一時ファイルを削除する。&lt;/span&gt;
&lt;span class="nb"&gt;rm&lt;/span&gt; /tmp/gh_app.pem /tmp/gh_app.der
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;h3 id="cloud-workflowsのyaml"&gt;Cloud WorkflowsのYAML&lt;/h3&gt;

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

&lt;div class="highlight"&gt;&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;main&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;params&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="pi"&gt;[&lt;/span&gt;&lt;span class="nv"&gt;args&lt;/span&gt;&lt;span class="pi"&gt;]&lt;/span&gt;
  &lt;span class="na"&gt;steps&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;init&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;assign&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;project_id&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${sys.get_env("GOOGLE_CLOUD_PROJECT_ID")}&lt;/span&gt;
          &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;github_app_id_secret&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${args.github_app_id_secret}&lt;/span&gt;
          &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;github_app_installation_id_secret&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${args.github_app_installation_id_secret}&lt;/span&gt;
          &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;kms_key_version_name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${args.kms_key_version_name}&lt;/span&gt;
          &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;target_repo&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${args.target_repo}&lt;/span&gt;
          &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;target_workflow_file&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${args.target_workflow_file}&lt;/span&gt;
          &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;target_ref&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${args.target_ref}&lt;/span&gt;

    &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;get_github_app_id_secret&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;call&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;googleapis.secretmanager.v1.projects.secrets.versions.access&lt;/span&gt;
        &lt;span class="na"&gt;args&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${"projects/" + project_id + "/secrets/" + github_app_id_secret + "/versions/latest"}&lt;/span&gt;
        &lt;span class="na"&gt;result&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;app_id_secret_response&lt;/span&gt;
    &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;decode_github_app_id&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;assign&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;github_app_id&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${int(text.decode(base64.decode(app_id_secret_response.payload.data)))}&lt;/span&gt;

    &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;get_github_app_installation_id_secret&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;call&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;googleapis.secretmanager.v1.projects.secrets.versions.access&lt;/span&gt;
        &lt;span class="na"&gt;args&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${"projects/" + project_id + "/secrets/" + github_app_installation_id_secret + "/versions/latest"}&lt;/span&gt;
        &lt;span class="na"&gt;result&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;installation_id_secret_response&lt;/span&gt;
    &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;decode_github_app_installation_id&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;assign&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;github_app_installation_id&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${text.decode(base64.decode(installation_id_secret_response.payload.data))}&lt;/span&gt;

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

    &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;sign_jwt_with_kms&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;call&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;http.post&lt;/span&gt;
        &lt;span class="na"&gt;args&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;url&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'&lt;/span&gt;&lt;span class="s"&gt;${"https://cloudkms.googleapis.com/v1/"&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;+&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;kms_key_version_name&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;+&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;":asymmetricSign"}'&lt;/span&gt;
          &lt;span class="na"&gt;auth&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
            &lt;span class="na"&gt;type&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;OAuth2&lt;/span&gt;
          &lt;span class="na"&gt;body&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
            &lt;span class="na"&gt;data&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${jwt_signing_input_b64}&lt;/span&gt;
        &lt;span class="na"&gt;result&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;kms_sign_response&lt;/span&gt;

    &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;assemble_jwt&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;assign&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;jwt_signature_b64_std&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${kms_sign_response.body.signature}&lt;/span&gt;
          &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;jwt_signature_b64&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${text.replace_all(text.replace_all(text.replace_all(jwt_signature_b64_std, "+", "-"), "/", "_"), "=", "")}&lt;/span&gt;
          &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;jwt&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${jwt_signing_input + "." + jwt_signature_b64}&lt;/span&gt;

    &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;exchange_jwt_for_installation_token&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;call&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;http.post&lt;/span&gt;
        &lt;span class="na"&gt;args&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;url&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'&lt;/span&gt;&lt;span class="s"&gt;${"https://api.github.com/app/installations/"&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;+&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;github_app_installation_id&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;+&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;"/access_tokens"}'&lt;/span&gt;
          &lt;span class="na"&gt;headers&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
            &lt;span class="na"&gt;Authorization&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${"Bearer " + jwt}&lt;/span&gt;
            &lt;span class="na"&gt;Accept&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;application/vnd.github+json"&lt;/span&gt;
            &lt;span class="na"&gt;X-GitHub-Api-Version&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;2022-11-28"&lt;/span&gt;
            &lt;span class="na"&gt;User-Agent&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;google-cloud-workflows"&lt;/span&gt;
        &lt;span class="na"&gt;result&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;installation_token_response&lt;/span&gt;
    &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;extract_installation_token&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;assign&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;installation_token&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${installation_token_response.body.token}&lt;/span&gt;

    &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;dispatch_workflow&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;call&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;http.post&lt;/span&gt;
        &lt;span class="na"&gt;args&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;url&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'&lt;/span&gt;&lt;span class="s"&gt;${"https://api.github.com/repos/"&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;+&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;target_repo&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;+&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;"/actions/workflows/"&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;+&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;target_workflow_file&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;+&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;"/dispatches"}'&lt;/span&gt;
          &lt;span class="na"&gt;headers&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
            &lt;span class="na"&gt;Authorization&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${"Bearer " + installation_token}&lt;/span&gt;
            &lt;span class="na"&gt;Accept&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;application/vnd.github+json"&lt;/span&gt;
            &lt;span class="na"&gt;X-GitHub-Api-Version&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;2022-11-28"&lt;/span&gt;
            &lt;span class="na"&gt;User-Agent&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;google-cloud-workflows"&lt;/span&gt;
          &lt;span class="na"&gt;body&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
            &lt;span class="na"&gt;ref&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${target_ref}&lt;/span&gt;
        &lt;span class="na"&gt;result&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;dispatch_response&lt;/span&gt;

    &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;log_dispatched&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;call&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;sys.log&lt;/span&gt;
        &lt;span class="na"&gt;args&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;text&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'&lt;/span&gt;&lt;span class="s"&gt;${"Dispatched&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;workflow&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;"&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;+&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;target_repo&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;+&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;"&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;"&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;+&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;target_workflow_file&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;+&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;"&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;ref="&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;+&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;target_ref}'&lt;/span&gt;
          &lt;span class="na"&gt;severity&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;INFO&lt;/span&gt;
    &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;return_result&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;return&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'&lt;/span&gt;&lt;span class="s"&gt;${"dispatched:&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;"&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;+&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;target_repo&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;+&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;"&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;"&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;+&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;target_workflow_file}'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;ポイントを補足します。&lt;/p&gt;

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

&lt;h2 id="ハマりどころ"&gt;ハマりどころ&lt;/h2&gt;

&lt;h3 id="import-methodの選択--aes-256-の有無"&gt;Import methodの選択 (&lt;code&gt;-aes-256&lt;/code&gt; の有無)&lt;/h3&gt;

&lt;p&gt;最初 &lt;code&gt;--import-method=rsa-oaep-3072-sha256&lt;/code&gt; で &lt;code&gt;import-job&lt;/code&gt; を作ったところ、&lt;code&gt;gcloud kms keys versions import&lt;/code&gt; で&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;ERROR: ('target-key-file', "The file is larger than the import method's maximum size of 318 bytes.")
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;と弾かれました。素の &lt;code&gt;rsa-oaep-3072-sha256&lt;/code&gt; はRSA-OAEPで直接wrapできる最大サイズが318バイトしかなく、PKCS#8 DERのRSA 2048 private key (1200バイト超) は入りません。正解はAES wrappingを組み合わせる &lt;code&gt;rsa-oaep-3072-sha256-aes-256&lt;/code&gt; です。これだとAESでkey materialをwrapし、AESキーをRSA-OAEPでwrapする2段構成になり、大きな鍵もimportできます。&lt;/p&gt;

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

&lt;h3 id="pem--pkcs8-derへの変換"&gt;PEM → PKCS#8 DERへの変換&lt;/h3&gt;

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

&lt;div class="highlight"&gt;&lt;pre class="highlight shell"&gt;&lt;code&gt;openssl pkcs8 &lt;span class="nt"&gt;-topk8&lt;/span&gt; &lt;span class="nt"&gt;-nocrypt&lt;/span&gt; &lt;span class="nt"&gt;-inform&lt;/span&gt; PEM &lt;span class="nt"&gt;-in&lt;/span&gt; /tmp/gh_app.pem &lt;span class="nt"&gt;-outform&lt;/span&gt; DER &lt;span class="nt"&gt;-out&lt;/span&gt; /tmp/gh_app.der
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;で変換してから渡しました。最初これを忘れて &lt;code&gt;state: IMPORT_FAILED&lt;/code&gt; になり、&lt;code&gt;importFailureReason: The key material in the import request couldn't be unwrapped or wasn't formatted correctly&lt;/code&gt; で落ちました。&lt;code&gt;reimportEligible: true&lt;/code&gt; だったので同じversion番号に対して再importできました。&lt;/p&gt;

&lt;h2 id="結果"&gt;結果&lt;/h2&gt;

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

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

&lt;h2 id="その他の構成案"&gt;その他の構成案&lt;/h2&gt;

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

&lt;h2 id="まとめ"&gt;まとめ&lt;/h2&gt;

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

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

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

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

&lt;p&gt;Cloud KMSに鍵をimportする手順 (import-method、AES wrapping、PEM→PKCS#8 DER変換、IMPORT_FAILED時の再import) には地味なハマりどころが多いので、同じ構成を組む方の参考になれば嬉しいです。&lt;/p&gt;
</content>
  </entry>
  <entry>
    <title>データ基盤のワークフロー構成変更によるコスト84%削減とCI 34倍高速化</title>
    <link rel="alternate" href="https://tech.pepabo.com/2026/05/11/cloud-composer-retirement/"/>
    <id>https://tech.pepabo.com/2026/05/11/cloud-composer-retirement/</id>
    <published>2026-05-11T00:00:00+09:00</published>
    <updated>2026-06-23T00:06:10+00:00</updated>
    <author>
      <name>zaimy</name>
    </author>
    <content type="html">&lt;p&gt;技術部データ基盤チームの&lt;a href="https://x.com/hirokazaitsu"&gt;@zaimy&lt;/a&gt;です。&lt;/p&gt;

&lt;p&gt;ペパボの社内データ基盤「Bigfoot」では、&lt;a href="https://rand.pepabo.com/article/2020/06/16/bigfoot-migration/#section-4"&gt;2020年にDigdagから移設して以来&lt;/a&gt;約5年間にわたりCloud Composer（Managed Apache Airflow）をワークフローエンジンとして運用してきましたが、2026年1Qをもって別構成に移行しました。本記事では、Cloud Composerから3つのマネージドサービスへ移行した経緯と、その効果について紹介します。&lt;/p&gt;

&lt;ol id="markdown-toc"&gt;
  &lt;li&gt;&lt;a href="#cloud-composerで動いていた3つのワークロード" id="markdown-toc-cloud-composerで動いていた3つのワークロード"&gt;Cloud Composerで動いていた3つのワークロード&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#なぜ撤退したのか" id="markdown-toc-なぜ撤退したのか"&gt;なぜ撤退したのか&lt;/a&gt;    &lt;ol&gt;
      &lt;li&gt;&lt;a href="#1-agentic-ai-readyになるためにdbtを身軽にしたい" id="markdown-toc-1-agentic-ai-readyになるためにdbtを身軽にしたい"&gt;1. Agentic AI readyになるためにdbtを身軽にしたい&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#2-コストの膨張" id="markdown-toc-2-コストの膨張"&gt;2. コストの膨張&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#3-運用負荷の高さ" id="markdown-toc-3-運用負荷の高さ"&gt;3. 運用負荷の高さ&lt;/a&gt;&lt;/li&gt;
    &lt;/ol&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href="#移行先コンポーネントの紹介" id="markdown-toc-移行先コンポーネントの紹介"&gt;移行先コンポーネントの紹介&lt;/a&gt;    &lt;ol&gt;
      &lt;li&gt;&lt;a href="#dbt-cloud" id="markdown-toc-dbt-cloud"&gt;dbt Cloud&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#bigquery-data-transfer-service-dts" id="markdown-toc-bigquery-data-transfer-service-dts"&gt;BigQuery Data Transfer Service (DTS)&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#cloud-workflows" id="markdown-toc-cloud-workflows"&gt;Cloud Workflows&lt;/a&gt;&lt;/li&gt;
    &lt;/ol&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href="#コスト比較" id="markdown-toc-コスト比較"&gt;コスト比較&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#開発効率比較" id="markdown-toc-開発効率比較"&gt;開発効率比較&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#運用面の比較" id="markdown-toc-運用面の比較"&gt;運用面の比較&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#エラーレート比較" id="markdown-toc-エラーレート比較"&gt;エラーレート比較&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#まとめ" id="markdown-toc-まとめ"&gt;まとめ&lt;/a&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;h2 id="cloud-composerで動いていた3つのワークロード"&gt;Cloud Composerで動いていた3つのワークロード&lt;/h2&gt;

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

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

&lt;h2 id="なぜ撤退したのか"&gt;なぜ撤退したのか&lt;/h2&gt;

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

&lt;h3 id="1-agentic-ai-readyになるためにdbtを身軽にしたい"&gt;1. Agentic AI readyになるためにdbtを身軽にしたい&lt;/h3&gt;

&lt;p&gt;技術部の方針「&lt;a href="https://tech.pepabo.com/2026/02/19/tech-division-agent-ready-2026/"&gt;Agent Ready&lt;/a&gt;」に基づき、AIエージェント前提の技術基盤づくりを進めるにあたって、dbtでSSoTなデータマートを作った上でAgentic AIによる分析を実現したいと考えています。そのためにdbtをより身軽に使いたいのですが、Airflow上でdbtを実行する構成はオーバーヘッドが大きく、AIを用いた開発運用においてフィードバックループが遅い状態でした。&lt;/p&gt;

&lt;h3 id="2-コストの膨張"&gt;2. コストの膨張&lt;/h3&gt;

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

&lt;h3 id="3-運用負荷の高さ"&gt;3. 運用負荷の高さ&lt;/h3&gt;

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

&lt;p&gt;なお、Cloud Composerのバージョンアップにまつわる運用課題については、以前「&lt;a href="https://tech.pepabo.com/2024/12/12/airflow-bg-deployment/"&gt;社内データ基盤のワークフローエンジンをBlue-green deploymentで無停止バージョンアップする&lt;/a&gt;」で紹介しています。&lt;/p&gt;

&lt;h2 id="移行先コンポーネントの紹介"&gt;移行先コンポーネントの紹介&lt;/h2&gt;

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

&lt;h3 id="dbt-cloud"&gt;dbt Cloud&lt;/h3&gt;

&lt;p&gt;dbtの実行基盤をAirflow + Cosmosからdbt Cloudに移行しました。&lt;/p&gt;

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

&lt;h3 id="bigquery-data-transfer-service-dts"&gt;BigQuery Data Transfer Service (DTS)&lt;/h3&gt;

&lt;p&gt;事業DBの同期をDTSに移行しました。元は&lt;a href="https://docs.aws.amazon.com/ja_jp/AmazonRDS/latest/UserGuide/USER_ExportSnapshot.html"&gt;Amazon RDSのAmazon S3へのDBスナップショットデータのエクスポート&lt;/a&gt;をAirflow DAGから実行し、さらにBigQueryのLOADジョブをAirflow DAGから発行してロードする構成でしたが、移行後はMySQLやPostgreSQLなどのコネクタを使ってRDSから直接BigQueryにデータ転送します。&lt;/p&gt;

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

&lt;h3 id="cloud-workflows"&gt;Cloud Workflows&lt;/h3&gt;

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

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

&lt;h2 id="コスト比較"&gt;コスト比較&lt;/h2&gt;

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

&lt;h2 id="開発効率比較"&gt;開発効率比較&lt;/h2&gt;

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

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;指標&lt;/th&gt;
      &lt;th&gt;Cloud Composer（n=622）&lt;/th&gt;
      &lt;th&gt;dbt Cloud（n=476）&lt;/th&gt;
      &lt;th&gt;改善&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;中央値&lt;/td&gt;
      &lt;td&gt;約17分&lt;/td&gt;
      &lt;td&gt;約30秒&lt;/td&gt;
      &lt;td&gt;34倍高速化&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;平均値&lt;/td&gt;
      &lt;td&gt;約42分&lt;/td&gt;
      &lt;td&gt;約2.5分&lt;/td&gt;
      &lt;td&gt;17倍高速化&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

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

&lt;h2 id="運用面の比較"&gt;運用面の比較&lt;/h2&gt;

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

&lt;h2 id="エラーレート比較"&gt;エラーレート比較&lt;/h2&gt;

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

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt; &lt;/th&gt;
      &lt;th&gt;Cloud Composer（1〜3月）&lt;/th&gt;
      &lt;th&gt;Cloud Workflows（4月）&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;成功&lt;/td&gt;
      &lt;td&gt;32,494&lt;/td&gt;
      &lt;td&gt;1,849&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;失敗&lt;/td&gt;
      &lt;td&gt;286&lt;/td&gt;
      &lt;td&gt;15&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;合計&lt;/td&gt;
      &lt;td&gt;32,780&lt;/td&gt;
      &lt;td&gt;1,864&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;エラーレート&lt;/td&gt;
      &lt;td&gt;0.87%&lt;/td&gt;
      &lt;td&gt;0.80%&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

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

&lt;h2 id="まとめ"&gt;まとめ&lt;/h2&gt;

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

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

&lt;p&gt;「マネージドなAirflow」という一枚岩のアーキテクチャから、ワークロードの特性に合った専用サービスに分離するアプローチは、同様の構成で運用コストに課題を感じている方の参考になれば幸いです。&lt;/p&gt;
</content>
  </entry>
  <entry>
    <title>ORDER BY id DESC が招くインデックス誤選択 — 直近のレコードを N 件取り出すクエリを実測 約 658 倍に高速化</title>
    <link rel="alternate" href="https://tech.pepabo.com/2026/05/01/minne-order-by-limit-pitfall/"/>
    <id>https://tech.pepabo.com/2026/05/01/minne-order-by-limit-pitfall/</id>
    <published>2026-05-01T00:00:00+09:00</published>
    <updated>2026-06-23T00:06:10+00:00</updated>
    <author>
      <name>kazu</name>
    </author>
    <content type="html">&lt;h2 id="はじめに"&gt;はじめに&lt;/h2&gt;

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

&lt;div class="highlight"&gt;&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="n"&gt;current_user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;orders&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;where&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;not&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="ss"&gt;id: &lt;/span&gt;&lt;span class="vi"&gt;@order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;    &lt;span class="c1"&gt;# 自分自身は除外する&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;order&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="ss"&gt;id: :desc&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;            &lt;span class="c1"&gt;# 「直近」を id 降順で表現&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;limit&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;n&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;このパターンが、minne では特定のユーザーで安定的に MySQL のクエリタイムアウトを起こしていました。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Mysql2::Error: Query execution was interrupted, maximum statement execution time exceeded
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;調査の結果、原因は &lt;strong&gt;&lt;code&gt;ORDER BY id DESC&lt;/code&gt; + &lt;code&gt;LIMIT N&lt;/code&gt; の組み合わせによる MySQL optimizer のインデックス誤選択&lt;/strong&gt; で、worst case で &lt;strong&gt;2,300 万行をスキャン&lt;/strong&gt; して &lt;code&gt;max_statement_time&lt;/code&gt; を踏み抜いていることが判明しました。&lt;code&gt;ORDER BY&lt;/code&gt; のカラムを既存インデックスに合わせて変えるだけで、&lt;/p&gt;

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

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

&lt;ol id="markdown-toc"&gt;
  &lt;li&gt;&lt;a href="#はじめに" id="markdown-toc-はじめに"&gt;はじめに&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#何が起きていたか" id="markdown-toc-何が起きていたか"&gt;何が起きていたか&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#原因--order-by-id-desc--limit-n-で-optimizer-が-primary-を選ぶ" id="markdown-toc-原因--order-by-id-desc--limit-n-で-optimizer-が-primary-を選ぶ"&gt;原因 — &lt;code&gt;ORDER BY id DESC&lt;/code&gt; + &lt;code&gt;LIMIT N&lt;/code&gt; で optimizer が PRIMARY を選ぶ&lt;/a&gt;    &lt;ol&gt;
      &lt;li&gt;&lt;a href="#limit-を外せば直るのではない" id="markdown-toc-limit-を外せば直るのではない"&gt;「LIMIT を外せば直る」のではない&lt;/a&gt;&lt;/li&gt;
    &lt;/ol&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href="#修正--order-by-を既存インデックスのソート順に揃える" id="markdown-toc-修正--order-by-を既存インデックスのソート順に揃える"&gt;修正 — &lt;code&gt;ORDER BY&lt;/code&gt; を既存インデックスのソート順に揃える&lt;/a&gt;    &lt;ol&gt;
      &lt;li&gt;&lt;a href="#補足-id-desc-と-ordered_at-desc-の意味的な差" id="markdown-toc-補足-id-desc-と-ordered_at-desc-の意味的な差"&gt;補足: &lt;code&gt;id DESC&lt;/code&gt; と &lt;code&gt;ordered_at DESC&lt;/code&gt; の意味的な差&lt;/a&gt;&lt;/li&gt;
    &lt;/ol&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href="#比較サマリ" id="markdown-toc-比較サマリ"&gt;比較サマリ&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#学び" id="markdown-toc-学び"&gt;学び&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#参考" id="markdown-toc-参考"&gt;参考&lt;/a&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;h2 id="何が起きていたか"&gt;何が起きていたか&lt;/h2&gt;

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

&lt;div class="highlight"&gt;&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="n"&gt;current_user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;orders&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;where&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;not&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="ss"&gt;id: &lt;/span&gt;&lt;span class="vi"&gt;@order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;    &lt;span class="c1"&gt;# 自分自身は除外する&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;order&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="ss"&gt;id: :desc&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;            &lt;span class="c1"&gt;# 「直近」を id 降順で表現&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;limit&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;n&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;&lt;code&gt;current_user&lt;/code&gt;（作家）の注文のうち、現在のレコード自身を除いて &lt;code&gt;id&lt;/code&gt; 降順に N 件取るだけ。発行される SQL もざっくり次のような形です。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="n"&gt;sales&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;sales&lt;/span&gt;
&lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;sales&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;creator_id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;sales&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="o"&gt;!=&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt;
&lt;span class="k"&gt;ORDER&lt;/span&gt; &lt;span class="k"&gt;BY&lt;/span&gt; &lt;span class="n"&gt;sales&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="k"&gt;DESC&lt;/span&gt;
&lt;span class="k"&gt;LIMIT&lt;/span&gt; &lt;span class="n"&gt;N&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;一見、&lt;code&gt;creator_id&lt;/code&gt; で絞って &lt;code&gt;id&lt;/code&gt; 降順に N 件取るだけのシンプルなクエリです。&lt;strong&gt;注文数が少ない作家では即座に返ります。&lt;/strong&gt; ところが累計数万件規模の注文を持つような作家では、このクエリが安定してタイムアウトしていました。&lt;/p&gt;

&lt;h2 id="原因--order-by-id-desc--limit-n-で-optimizer-が-primary-を選ぶ"&gt;原因 — &lt;code&gt;ORDER BY id DESC&lt;/code&gt; + &lt;code&gt;LIMIT N&lt;/code&gt; で optimizer が PRIMARY を選ぶ&lt;/h2&gt;

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

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

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;EXPLAIN ANALYZE SELECT sales.* FROM sales
WHERE sales.creator_id = xxxxx AND sales.id != yyyyy
ORDER BY sales.id DESC
LIMIT 10;

-&amp;gt; Limit: 10 row(s)  (cost=66636 rows=10) (actual time=6.26..56.6 rows=10 loops=1)
   -&amp;gt; Filter: ((sales.creator_id = xxxxx) and (sales.id &amp;lt;&amp;gt; yyyyy))  (cost=66636 rows=34158) (actual time=6.26..56.6 rows=10 loops=1)
       -&amp;gt; Index range scan on sales using PRIMARY over (id &amp;lt; yyyyy) OR (yyyyy &amp;lt; id) (reverse)
          (cost=66636 rows=23.3e+6) (actual time=0.0213..54.1 rows=27907 loops=1)
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;&lt;code&gt;possible_keys&lt;/code&gt; には &lt;code&gt;PRIMARY&lt;/code&gt; と &lt;code&gt;index_sales_on_creator_id_ordered_at&lt;/code&gt; の両方が挙がっていましたが、optimizer は &lt;strong&gt;PRIMARY 逆順スキャン&lt;/strong&gt; を選択しました。&lt;code&gt;ORDER BY id DESC LIMIT 10&lt;/code&gt; を満たすのに「PRIMARY を逆順に舐めて、&lt;code&gt;creator_id&lt;/code&gt; にヒットした行が 10 件揃ったところで打ち切る」プランを最も低コストと見積もったわけです。&lt;/p&gt;

&lt;p&gt;これは MySQL が &lt;code&gt;ORDER BY ... LIMIT&lt;/code&gt; の組み合わせに対して行う最適化（書籍『&lt;a href="https://gihyo.jp/book/2024/978-4-297-14184-4"&gt;MySQL運用・管理［実践］入門&lt;/a&gt;』では &lt;strong&gt;ORDER BY LIMIT 最適化&lt;/strong&gt; と呼ばれています）が裏目に出たケースです。同書第 4 章「ロックとクエリ実行計画」では、&lt;code&gt;ORDER BY Population DESC LIMIT 10&lt;/code&gt; のような単純なケースについてこう説明されています。&lt;/p&gt;

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

  &lt;p&gt;——『MySQL運用・管理［実践］入門』p.93&lt;/p&gt;
&lt;/blockquote&gt;

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

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

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

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

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

  &lt;p&gt;——『MySQL運用・管理［実践］入門』p.94&lt;/p&gt;
&lt;/blockquote&gt;

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

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

&lt;h3 id="limit-を外せば直るのではない"&gt;「LIMIT を外せば直る」のではない&lt;/h3&gt;

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

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;EXPLAIN ANALYZE SELECT sales.* FROM sales
WHERE sales.creator_id = xxxxx AND sales.id != yyyyy
ORDER BY sales.id DESC;

-&amp;gt; Sort: sales.id DESC  (cost=63195 rows=65024) (actual time=257..270 rows=35353 loops=1)
   -&amp;gt; Index lookup on sales using index_sales_on_creator_id_ordered_at (creator_id=xxxxx),
      with index condition: (sales.id &amp;lt;&amp;gt; yyyyy)  (cost=63195 rows=65024) (actual time=0.0305..209 rows=35353 loops=1)
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;&lt;code&gt;(creator_id, ordered_at)&lt;/code&gt; インデックスが採用されて creator スコープに閉じる代わりに、&lt;strong&gt;&lt;code&gt;id DESC&lt;/code&gt; で並べ直すための filesort（&lt;code&gt;Sort&lt;/code&gt; ノード）が必要&lt;/strong&gt;になります。実測 270ms。LIMIT 有りでの 56.6ms より遅く、テーブルが伸びれば線形に悪化します。&lt;/p&gt;

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

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

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

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

  &lt;p&gt;——『MySQL運用・管理［実践］入門』p.95&lt;/p&gt;
&lt;/blockquote&gt;

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

&lt;h2 id="修正--order-by-を既存インデックスのソート順に揃える"&gt;修正 — &lt;code&gt;ORDER BY&lt;/code&gt; を既存インデックスのソート順に揃える&lt;/h2&gt;

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

&lt;div class="highlight"&gt;&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="n"&gt;sales&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;sales&lt;/span&gt;
&lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;sales&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;creator_id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;sales&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="o"&gt;!=&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt;
&lt;span class="k"&gt;ORDER&lt;/span&gt; &lt;span class="k"&gt;BY&lt;/span&gt; &lt;span class="n"&gt;sales&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;ordered_at&lt;/span&gt; &lt;span class="k"&gt;DESC&lt;/span&gt;
&lt;span class="k"&gt;LIMIT&lt;/span&gt; &lt;span class="n"&gt;N&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;同じ作家で EXPLAIN ANALYZE を取り直したのが次の結果です。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;EXPLAIN ANALYZE SELECT sales.* FROM sales
WHERE sales.creator_id = xxxxx AND sales.id != yyyyy
ORDER BY sales.ordered_at DESC
LIMIT 10;

-&amp;gt; Limit: 10 row(s)  (cost=63494 rows=10) (actual time=0.0296..0.0863 rows=10 loops=1)
   -&amp;gt; Filter: (sales.id &amp;lt;&amp;gt; yyyyy)  (cost=63494 rows=32512) (actual time=0.0288..0.0848 rows=10 loops=1)
       -&amp;gt; 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)
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;&lt;code&gt;(creator_id, ordered_at)&lt;/code&gt; を逆順に index lookup し、&lt;code&gt;LIMIT 10&lt;/code&gt; で &lt;strong&gt;本当に 10 行だけ読む&lt;/strong&gt; 計画になりました。filesort も無く、actual rows が 10。実測 0.086ms です。&lt;/p&gt;

&lt;p&gt;参考までに、&lt;code&gt;LIMIT&lt;/code&gt; を外した場合の EXPLAIN ANALYZE も載せておきます。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;EXPLAIN ANALYZE SELECT sales.* FROM sales
WHERE sales.creator_id = xxxxx AND sales.id != yyyyy
ORDER BY sales.ordered_at DESC;

-&amp;gt; Filter: (sales.id &amp;lt;&amp;gt; yyyyy)  (cost=60713 rows=32512) (actual time=0.0286..213 rows=35353 loops=1)
   -&amp;gt; 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)
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;&lt;code&gt;LIMIT&lt;/code&gt; を外しても &lt;code&gt;Sort&lt;/code&gt; ノードは現れず、&lt;code&gt;(creator_id, ordered_at)&lt;/code&gt; を順に舐めるだけのプランです。actual rows は creator スコープの 35,353 行で、実測 213ms。これは「対象 creator の sale を一通り読む」コストそのものであり、旧クエリのようにテーブル全体の 23M 行を舐めにいくのとは性質がまったく違います。&lt;/p&gt;

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

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Query&lt;/th&gt;
      &lt;th&gt;採用 key&lt;/th&gt;
      &lt;th&gt;filesort&lt;/th&gt;
      &lt;th&gt;actual rows&lt;/th&gt;
      &lt;th&gt;&lt;strong&gt;actual time&lt;/strong&gt;&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code&gt;id DESC&lt;/code&gt; + &lt;code&gt;LIMIT 10&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;PRIMARY&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;no&lt;/td&gt;
      &lt;td&gt;27,907&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;56.6 ms&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code&gt;id DESC&lt;/code&gt;（LIMIT なし）&lt;/td&gt;
      &lt;td&gt;&lt;code&gt;..._ordered_at&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;YES&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;35,353&lt;/td&gt;
      &lt;td&gt;270 ms&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;&lt;code&gt;ordered_at DESC&lt;/code&gt; + &lt;code&gt;LIMIT 10&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;&lt;code&gt;..._ordered_at&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;no&lt;/td&gt;
      &lt;td&gt;10&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;0.086 ms&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code&gt;ordered_at DESC&lt;/code&gt;（LIMIT なし）&lt;/td&gt;
      &lt;td&gt;&lt;code&gt;..._ordered_at&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;no&lt;/td&gt;
      &lt;td&gt;35,353&lt;/td&gt;
      &lt;td&gt;213 ms&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

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

&lt;h3 id="補足-id-desc-と-ordered_at-desc-の意味的な差"&gt;補足: &lt;code&gt;id DESC&lt;/code&gt; と &lt;code&gt;ordered_at DESC&lt;/code&gt; の意味的な差&lt;/h3&gt;

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

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

&lt;h2 id="比較サマリ"&gt;比較サマリ&lt;/h2&gt;

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

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

&lt;h2 id="学び"&gt;学び&lt;/h2&gt;

&lt;p&gt;今回の改善から得た学びを 3 つに整理します。&lt;/p&gt;

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

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

&lt;h2 id="参考"&gt;参考&lt;/h2&gt;

&lt;ul&gt;
  &lt;li&gt;yoku0825・北川健太郎・tom__bo・坂井恵 著『&lt;a href="https://gihyo.jp/book/2024/978-4-297-14184-4"&gt;MySQL運用・管理［実践］入門&lt;/a&gt;』技術評論社, 2024 — 第 4 章「ロックとクエリ実行計画」が ORDER BY LIMIT 最適化と Backward index scan の理論的背景を丁寧に扱っており、本記事の現象を語彙化する上で大きく参考にしました&lt;/li&gt;
  &lt;li&gt;&lt;a href="https://dev.mysql.com/doc/refman/8.0/en/order-by-optimization.html"&gt;MySQL :: MySQL 8.0 Reference Manual :: 8.2.1.16 ORDER BY Optimization&lt;/a&gt; — MySQL 公式リファレンス&lt;/li&gt;
&lt;/ul&gt;

</content>
  </entry>
  <entry>
    <title>生成AIの従量課金とどう付き合うか？AIサイトエージェント開発で実践した段階的コスト見積もり</title>
    <link rel="alternate" href="https://tech.pepabo.com/2026/05/01/ai-app-cost-estimate/"/>
    <id>https://tech.pepabo.com/2026/05/01/ai-app-cost-estimate/</id>
    <published>2026-05-01T00:00:00+09:00</published>
    <updated>2026-06-23T00:06:10+00:00</updated>
    <author>
      <name>kinosuke01</name>
    </author>
    <content type="html">&lt;h2 id="はじめに"&gt;はじめに&lt;/h2&gt;

&lt;p&gt;こんにちは。ロリポップ・ムームードメイン事業部でエンジニアリングリードをしています &lt;a href="https://x.com/kinosuke01"&gt;kinosuke01&lt;/a&gt; といいます。&lt;/p&gt;

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

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

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

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

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

&lt;h2 id="前提ai-サイトエージェントというサービス"&gt;前提：AI サイトエージェントというサービス&lt;/h2&gt;

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

&lt;p&gt;&lt;img src="/blog/2026/05/01/ai-app-cost-estimate/img01.png" alt="img01" /&gt;
&lt;img src="/blog/2026/05/01/ai-app-cost-estimate/img02.png" alt="img02" /&gt;&lt;/p&gt;

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

&lt;p&gt;ざっくり図にすると、このような流れです。&lt;/p&gt;

&lt;p&gt;&lt;img src="/blog/2026/05/01/ai-app-cost-estimate/flow.png" alt="flow" /&gt;&lt;/p&gt;

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

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

&lt;h2 id="対応方針段階的に精度を上げる"&gt;対応方針：段階的に精度を上げる&lt;/h2&gt;

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

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

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

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

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

&lt;h2 id="フェーズ-1設計段階でざっくり見積もる"&gt;フェーズ 1：設計段階でざっくり見積もる&lt;/h2&gt;

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

&lt;p&gt;たとえば &lt;code&gt;PageAndSectionPlanner&lt;/code&gt; であれば、ざっくりこんな見積もりになります。&lt;/p&gt;

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

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

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

&lt;p&gt;この段階では精度は荒いものの、&lt;/p&gt;

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

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

&lt;h2 id="フェーズ-2実装してから実データで見積もる"&gt;フェーズ 2：実装してから実データで見積もる&lt;/h2&gt;

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

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

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

&lt;h3 id="正常系を一通り動かす"&gt;正常系を一通り動かす&lt;/h3&gt;

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

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

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

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

&lt;h3 id="トークン数を自動で-db-に記録する"&gt;トークン数を自動で DB に記録する&lt;/h3&gt;

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

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

&lt;h3 id="実績データから見積もる"&gt;実績データから見積もる&lt;/h3&gt;

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

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

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

&lt;h2 id="フェーズ-3ローンチ後のモニタリング"&gt;フェーズ 3：ローンチ後のモニタリング&lt;/h2&gt;

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

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

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

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

&lt;h2 id="まとめ"&gt;まとめ&lt;/h2&gt;

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

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

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

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

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

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

&lt;hr /&gt;

&lt;h2 id="付録トークン数を-db-に記録する仕組み"&gt;付録：トークン数を DB に記録する仕組み&lt;/h2&gt;

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

&lt;h3 id="どこに永続化するかrdb-を選んだ理由"&gt;どこに永続化するか：RDB を選んだ理由&lt;/h3&gt;

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

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;生成AI 向けの Observability SaaS（ &lt;a href="https://smith.langchain.com/"&gt;LangSmith&lt;/a&gt; など）&lt;/strong&gt; を使う&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href="https://langfuse.com/"&gt;Langfuse&lt;/a&gt; の OSS 版&lt;/strong&gt; をセルフホストする&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;自前の RDB テーブル&lt;/strong&gt; に保存する&lt;/li&gt;
&lt;/ul&gt;

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

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

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

&lt;h3 id="prisma-スキーマ"&gt;Prisma スキーマ&lt;/h3&gt;

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

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;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")
}
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;プロンプトとレスポンスも併せて保存しています。これは、後から「このトークン数のときはこういう出力が返っていた」と振り返って、プロンプトをチューニングする材料にできるためです。&lt;/p&gt;

&lt;h3 id="ログの書き込み処理"&gt;ログの書き込み処理&lt;/h3&gt;

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

&lt;div class="highlight"&gt;&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// ai-generation-logger.ts（抜粋）&lt;/span&gt;
&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="nx"&gt;saveLog&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;input&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;AiGenerationLogCreateInput&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="k"&gt;void&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;repository&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;save&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;input&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;error&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;logger&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;error&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;err&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;error&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Failed to save AI generation log&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;logGeneration&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;params&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="cm"&gt;/* ... */&lt;/span&gt; &lt;span class="p"&gt;}):&lt;/span&gt; &lt;span class="k"&gt;void&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;context&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;getAiLogContext&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;

  &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;saveLog&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="na"&gt;userId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;context&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;userId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;websiteId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;context&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;siteId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;stepType&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;params&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;stepType&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;params&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;model&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;prompt&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;params&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;prompt&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;response&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;params&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;response&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;inputTokens&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;params&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;inputTokens&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;outputTokens&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;params&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;outputTokens&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;durationMs&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;params&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;durationMs&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;isError&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;params&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;isError&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;errorMessage&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;params&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;errorMessage&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}).&lt;/span&gt;&lt;span class="k"&gt;catch&lt;/span&gt;&lt;span class="p"&gt;(()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{});&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;ログの保存が原因でサイト生成が失敗したら本末転倒なので、ここは割り切ります。&lt;/p&gt;

&lt;h3 id="生成ai呼び出しをラップする"&gt;生成AI呼び出しをラップする&lt;/h3&gt;

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

&lt;div class="highlight"&gt;&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// db-logging-model.ts（抜粋）&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;class&lt;/span&gt; &lt;span class="nx"&gt;DbLoggingGenerativeModel&lt;/span&gt; &lt;span class="k"&gt;implements&lt;/span&gt; &lt;span class="nx"&gt;GenerativeModel&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;get&lt;/span&gt; &lt;span class="nx"&gt;modelName&lt;/span&gt;&lt;span class="p"&gt;():&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;inner&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;modelName&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="kd"&gt;constructor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;readonly&lt;/span&gt; &lt;span class="nx"&gt;inner&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;GenerativeModel&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;readonly&lt;/span&gt; &lt;span class="nx"&gt;stepType&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;readonly&lt;/span&gt; &lt;span class="nx"&gt;genLogger&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;AiGenerationLogger&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{}&lt;/span&gt;

  &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="nx"&gt;generateContent&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;prompt&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;startTime&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;now&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
    &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;result&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;inner&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;generateContent&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;prompt&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
      &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;text&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;result&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;response&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;text&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
      &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;genLogger&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;logGeneration&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
        &lt;span class="na"&gt;stepType&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;stepType&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="na"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;modelName&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="nx"&gt;prompt&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="na"&gt;response&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;text&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="na"&gt;inputTokens&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;result&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;usageMetadata&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nx"&gt;promptTokenCount&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="na"&gt;outputTokens&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;result&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;usageMetadata&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nx"&gt;candidatesTokenCount&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="na"&gt;durationMs&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;now&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="nx"&gt;startTime&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;});&lt;/span&gt;
      &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;result&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;error&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;genLogger&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;logGeneration&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
        &lt;span class="na"&gt;stepType&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;stepType&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="na"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;modelName&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="nx"&gt;prompt&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="na"&gt;response&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;""&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="na"&gt;durationMs&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;now&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="nx"&gt;startTime&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="na"&gt;isError&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="na"&gt;errorMessage&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;error&lt;/span&gt; &lt;span class="k"&gt;instanceof&lt;/span&gt; &lt;span class="nb"&gt;Error&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="nx"&gt;error&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;message&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;String&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;error&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
      &lt;span class="p"&gt;});&lt;/span&gt;
      &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="nx"&gt;error&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;このデコレータを挟むことで、すべてのステップ（&lt;code&gt;PageAndSectionPlanner&lt;/code&gt;、&lt;code&gt;ThemeDeterminer&lt;/code&gt;、&lt;code&gt;SectionValueGenerator&lt;/code&gt; 等）のアプリケーションコード側に特別な計測ロジックを足さずに、全呼び出しのトークン数を DB に記録できます。&lt;code&gt;stepType&lt;/code&gt; をコンストラクタで受け取っているのは、「どのステップの呼び出しか」をあとから集計できるようにするためです。&lt;/p&gt;
</content>
  </entry>
  <entry>
    <title>Claude Code Skillでメール障害対応を実施</title>
    <link rel="alternate" href="https://tech.pepabo.com/2026/04/30/claude-code-skills-mail-incident/"/>
    <id>https://tech.pepabo.com/2026/04/30/claude-code-skills-mail-incident/</id>
    <published>2026-04-30T00:00:00+09:00</published>
    <updated>2026-06-23T00:06:10+00:00</updated>
    <author>
      <name>kmsn</name>
    </author>
    <content type="html">&lt;p&gt;こんにちは、技術部 技術基盤グループのkmsnです。&lt;/p&gt;

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

&lt;h2 id="結論skill-で障害対応の初動が変わった"&gt;結論：Skill で障害対応の初動が変わった&lt;/h2&gt;

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

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

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

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;サーバー&lt;/th&gt;
      &lt;th&gt;active&lt;/th&gt;
      &lt;th&gt;deferred&lt;/th&gt;
      &lt;th&gt;合計&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;server-1&lt;/td&gt;
      &lt;td&gt;0&lt;/td&gt;
      &lt;td&gt;3,842&lt;/td&gt;
      &lt;td&gt;3,842&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;server-2&lt;/td&gt;
      &lt;td&gt;12&lt;/td&gt;
      &lt;td&gt;0&lt;/td&gt;
      &lt;td&gt;12&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;※ 上記は全数十台のうち抜粋&lt;/p&gt;

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

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

&lt;h2 id="何が起きたか"&gt;何が起きたか&lt;/h2&gt;

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

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

&lt;h2 id="postfix-transport-で-outlook-宛の配送経路を変更する"&gt;Postfix transport で Outlook 宛の配送経路を変更する&lt;/h2&gt;

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

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

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

&lt;h2 id="手動設定を-puppet-でコード化する"&gt;手動設定を Puppet でコード化する&lt;/h2&gt;

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

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

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

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

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

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

&lt;div class="highlight"&gt;&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;sudo &lt;/span&gt;puppet agent &lt;span class="nt"&gt;--test&lt;/span&gt; &lt;span class="nt"&gt;--noop&lt;/span&gt;  &lt;span class="c"&gt;# dry-run で変更内容を事前確認&lt;/span&gt;
&lt;span class="nb"&gt;sudo &lt;/span&gt;puppet agent &lt;span class="nt"&gt;--test&lt;/span&gt;         &lt;span class="c"&gt;# 本適用&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;経路の切り替えが正常に動作していることを確認し、復旧しました。&lt;/p&gt;

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

&lt;h2 id="その他の学び"&gt;その他の学び&lt;/h2&gt;

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

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

&lt;p&gt;&lt;strong&gt;手動設定は「なぜ入っているか」が追えなくなる。&lt;/strong&gt;&lt;/p&gt;

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

&lt;h2 id="おわりに"&gt;おわりに&lt;/h2&gt;

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

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

&lt;p&gt;同様の取り組みを検討されている方の参考になれば幸いです。&lt;/p&gt;
</content>
  </entry>
  <entry>
    <title>後付け可能な認証を NextAuth で設計する — ログイン機構が決まらないまま、ログイン前提のプロダクトを作った話</title>
    <link rel="alternate" href="https://tech.pepabo.com/2026/04/24/nextauth-mock-auth-design/"/>
    <id>https://tech.pepabo.com/2026/04/24/nextauth-mock-auth-design/</id>
    <published>2026-04-24T00:00:00+09:00</published>
    <updated>2026-06-23T00:06:10+00:00</updated>
    <author>
      <name>kinosuke01</name>
    </author>
    <content type="html">&lt;h2 id="はじめに"&gt;はじめに&lt;/h2&gt;

&lt;p&gt;こんにちは。ロリポップ・ムームードメイン事業部でエンジニアリングリードをしています &lt;a href="https://x.com/kinosuke01"&gt;kinosuke01&lt;/a&gt; といいます。&lt;/p&gt;

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

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

&lt;p&gt;この記事では、&lt;a href="https://lolipop.jp/ai/site-agent/"&gt;AIサイトエージェント&lt;/a&gt; というプロダクトの開発で実際に直面したこの状況と、そこで取った方針について紹介していきます。&lt;/p&gt;

&lt;p&gt;要点を先にまとめると、以下の一点になります。&lt;/p&gt;

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

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

&lt;h2 id="前提aiサイトエージェントとは"&gt;前提：AIサイトエージェントとは&lt;/h2&gt;

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

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

&lt;p&gt;&lt;img src="/blog/2026/04/24/nextauth-mock-auth-design/img01.png" alt="img01" /&gt;
&lt;img src="/blog/2026/04/24/nextauth-mock-auth-design/img02.png" alt="img02" /&gt;&lt;/p&gt;

&lt;p&gt;このサービスは、&lt;a href="https://lolipop.jp/"&gt;ロリポップ！レンタルサーバー&lt;/a&gt; と &lt;a href="https://muumuu-domain.com/"&gt;ムームードメイン&lt;/a&gt; のどちらからも利用できるようになっています。ロリポップのユーザーとムームードメインのユーザー、それぞれが AIサイトエージェントのコンパネに入ってサイトを作れる、というのが本番のユースケースとなります。&lt;/p&gt;

&lt;p&gt;&lt;img src="/blog/2026/04/24/nextauth-mock-auth-design/oidc.png" alt="ロリポップ／ムームードメインのアカウントでOIDCログインする構成" /&gt;&lt;/p&gt;

&lt;h3 id="技術スタック"&gt;技術スタック&lt;/h3&gt;

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

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;フレームワーク&lt;/strong&gt;: &lt;a href="https://nextjs.org/"&gt;Next.js&lt;/a&gt;（App Router）&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;認証&lt;/strong&gt;: &lt;a href="https://authjs.dev/"&gt;NextAuth.js（Auth.js v5）&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;言語&lt;/strong&gt;: TypeScript&lt;/li&gt;
&lt;/ul&gt;

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

&lt;h2 id="課題の整理ログインが決まっていない中で何を作るか"&gt;課題の整理：ログインが決まっていない中で何を作るか&lt;/h2&gt;

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

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

&lt;p&gt;この状況から、解くべき課題は次の2つに分解できます。&lt;/p&gt;

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

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

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

&lt;h3 id="開発環境を外部サービスから独立させたい"&gt;開発環境を外部サービスから独立させたい&lt;/h3&gt;

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

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

&lt;h3 id="方針"&gt;方針&lt;/h3&gt;

&lt;p&gt;ここまでを踏まえて、方針は次のように定めました。&lt;/p&gt;

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

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

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

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

&lt;h2 id="モック認証に求める振る舞い"&gt;モック認証に求める振る舞い&lt;/h2&gt;

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

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

&lt;p&gt;求める振る舞いは、次のように整理できます。&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;モック特有の部分&lt;/strong&gt;（偽物としての振る舞い）&lt;/p&gt;

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

&lt;p&gt;&lt;strong&gt;本番と揃えたい部分&lt;/strong&gt;（アプリから見て本物と同じ形）&lt;/p&gt;

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

&lt;p&gt;&lt;strong&gt;開発体験の要件&lt;/strong&gt;&lt;/p&gt;

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

&lt;p&gt;&lt;img src="/blog/2026/04/24/nextauth-mock-auth-design/login-form.png" alt="モック認証のログインフォーム" /&gt;&lt;/p&gt;
&lt;p class="pager__caption"&gt;任意のユーザー名を入力すると、そのユーザーでログインできる&lt;/p&gt;

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

&lt;h2 id="土台として-nextauth-を選ぶ"&gt;土台として NextAuth を選ぶ&lt;/h2&gt;

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

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

&lt;h2 id="テーブル構造は外部連携前提にしておく"&gt;テーブル構造は「外部連携前提」にしておく&lt;/h2&gt;

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

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;model ExternalIdentity {
  userId         String       @unique
  provider       AuthProvider
  providerUserId String
  // ... 他のカラム省略

  @@unique([provider, providerUserId])
}

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

&lt;h2 id="モック認証を-nextauth-の上に載せる"&gt;モック認証を NextAuth の上に載せる&lt;/h2&gt;

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

&lt;div class="highlight"&gt;&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// 入力された puid を簡易バリデーションするための正規表現&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;PUID_PATTERN&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="sr"&gt;/^&lt;/span&gt;&lt;span class="se"&gt;[&lt;/span&gt;&lt;span class="sr"&gt;a-zA-Z0-9-&lt;/span&gt;&lt;span class="se"&gt;]&lt;/span&gt;&lt;span class="sr"&gt;+$/&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nx"&gt;createMockAuth&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;NextAuth&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="na"&gt;providers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
      &lt;span class="nx"&gt;Credentials&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
        &lt;span class="na"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;credentials&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Mock Login&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="na"&gt;credentials&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
          &lt;span class="na"&gt;puid&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;label&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;ProviderUserId&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;text&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
        &lt;span class="p"&gt;},&lt;/span&gt;
        &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="nx"&gt;authorize&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;credentials&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
          &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;puid&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt;
            &lt;span class="k"&gt;typeof&lt;/span&gt; &lt;span class="nx"&gt;credentials&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nx"&gt;puid&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;string&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt;
            &lt;span class="nx"&gt;credentials&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;puid&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;trim&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="dl"&gt;""&lt;/span&gt;
              &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="nx"&gt;credentials&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;puid&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;trim&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
              &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;mock-user&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

          &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;PUID_PATTERN&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;test&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;puid&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
          &lt;span class="p"&gt;}&lt;/span&gt;

          &lt;span class="c1"&gt;// jwt コールバックで user として受け取る値&lt;/span&gt;
          &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;puid&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;
        &lt;span class="p"&gt;},&lt;/span&gt;
      &lt;span class="p"&gt;}),&lt;/span&gt;
    &lt;span class="p"&gt;],&lt;/span&gt;
    &lt;span class="na"&gt;trustHost&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;callbacks&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="nx"&gt;jwt&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="nx"&gt;token&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;account&lt;/span&gt; &lt;span class="p"&gt;})&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;mockJwtCallback&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="nx"&gt;token&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;account&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
      &lt;span class="p"&gt;},&lt;/span&gt;
      &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;token&lt;/span&gt; &lt;span class="p"&gt;})&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;commonSessionCallback&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;token&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt; &lt;span class="c1"&gt;// 本番と共通&lt;/span&gt;
      &lt;span class="p"&gt;},&lt;/span&gt;
    &lt;span class="p"&gt;},&lt;/span&gt;
    &lt;span class="na"&gt;pages&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;signIn&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;/login&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
  &lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;コードの中に &lt;code&gt;authorize&lt;/code&gt; / &lt;code&gt;jwt&lt;/code&gt; / &lt;code&gt;session&lt;/code&gt; という3つのコールバックが出てきます。NextAuth に馴染みのない方向けに、それぞれの役割と、&lt;code&gt;mock-user&lt;/code&gt; でログインボタンを押したときの呼び出し順を軽く整理しておきます。&lt;/p&gt;

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

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

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

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

&lt;h3 id="jit-プロビジョニングで複数ユーザーに対応する"&gt;JIT プロビジョニングで複数ユーザーに対応する&lt;/h3&gt;

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

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

&lt;div class="highlight"&gt;&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nx"&gt;mockJwtCallback&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="nx"&gt;token&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;account&lt;/span&gt; &lt;span class="p"&gt;})&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;account&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;token&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;providerUserId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;token&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;sub&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

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

  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="p"&gt;...&lt;/span&gt;&lt;span class="nx"&gt;token&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nx"&gt;providerUserId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;appUserId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;appUser&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;AuthProvider&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;MOCK&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;};&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;h3 id="セッションコールバックを本番と共通化する"&gt;セッションコールバックを本番と共通化する&lt;/h3&gt;

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

&lt;div class="highlight"&gt;&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nx"&gt;commonSessionCallback&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;token&lt;/span&gt; &lt;span class="p"&gt;})&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="c1"&gt;// jwt コールバックで積んだ error をそのまま伝搬&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;token&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;error&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;error&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;token&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;error&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="c1"&gt;// DB 側でユーザーが削除・無効化されていないかを確認&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;validation&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;validateUserExists&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="nx"&gt;token&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;appUserId&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;validation&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;isValid&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;error&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;validation&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;error&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;validation&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;error&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;ActiveUserNotFound&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;appUserId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;providerUserId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;token&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;providerUserId&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;appUserId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;token&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;appUserId&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;provider&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;token&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;provider&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="nx"&gt;AuthProvider&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;中身はほぼ JWT からセッションへの値の詰め替えだけで、モック・本番の差は一切ありません。「ログイン済みユーザーを DB で再確認する」というプロダクト側の要件だけを淡々と満たす形となっています。この関数がモードに依存しない形で書けていることが、後の差し替えコストを最小にしてくれます。&lt;/p&gt;

&lt;p&gt;セッション型も同じ形で固定しておきます。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kr"&gt;declare&lt;/span&gt; &lt;span class="kr"&gt;module&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;next-auth&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kr"&gt;interface&lt;/span&gt; &lt;span class="nx"&gt;Session&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nl"&gt;providerUserId&lt;/span&gt;&lt;span class="p"&gt;?:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="nl"&gt;appUserId&lt;/span&gt;&lt;span class="p"&gt;?:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="nl"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;?:&lt;/span&gt; &lt;span class="nx"&gt;AuthProvider&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="nl"&gt;error&lt;/span&gt;&lt;span class="p"&gt;?:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;アプリケーションのコードは、このセッションから &lt;code&gt;session.appUserId&lt;/code&gt; を取り出して使うだけです。&lt;strong&gt;モックか本番かを意識する必要がありません&lt;/strong&gt;。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nx"&gt;verifyWebsiteOwnership&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;websiteId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;session&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nx"&gt;appUserId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nx"&gt;UnauthorizedError&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;website&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;websiteService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;findByIdForUser&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="nx"&gt;websiteId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;appUserId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;website&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nx"&gt;NotFoundError&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Website not found&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;このガード関数が、モック時代も本番移行後もそのまま動いているというのが、この設計のポイントとなります。&lt;/p&gt;

&lt;h2 id="本番ログインが決まった後の差し替え"&gt;本番ログインが決まった後の差し替え&lt;/h2&gt;

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

&lt;div class="highlight"&gt;&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nx"&gt;createOidcAuth&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;providers&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
    &lt;span class="nx"&gt;createOidcProviderConfig&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;muumuu&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Muumuu Domain&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;MUUMUU&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
    &lt;span class="nx"&gt;createOidcProviderConfig&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;lolipop&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Lolipop&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;LOLIPOP&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
  &lt;span class="p"&gt;].&lt;/span&gt;&lt;span class="nx"&gt;filter&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;p&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;p&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;NextAuth&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="nx"&gt;providers&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;trustHost&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;session&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="na"&gt;strategy&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;jwt&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="na"&gt;maxAge&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;24&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;60&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;60&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="na"&gt;updateAge&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;60&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;60&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;},&lt;/span&gt;
    &lt;span class="na"&gt;callbacks&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="na"&gt;signIn&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;oidcSignInCallback&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="na"&gt;jwt&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;oidcJwtCallbackWithProviderGuard&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="na"&gt;session&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;commonSessionCallback&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// モック時代と同じもの&lt;/span&gt;
    &lt;span class="p"&gt;},&lt;/span&gt;
    &lt;span class="na"&gt;pages&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;signIn&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;/login&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
  &lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;重要なのは、&lt;strong&gt;&lt;code&gt;session&lt;/code&gt; コールバックはモックと共通のものを使っている&lt;/strong&gt;ところです。セッションから取り出せる値（&lt;code&gt;appUserId&lt;/code&gt;, &lt;code&gt;provider&lt;/code&gt;, &lt;code&gt;providerUserId&lt;/code&gt;）の形は変わっていないので、アプリ本体のコードはほぼそのままで動きました。OIDC 導入に伴う変更は、認証レイヤー内のファイル（新設した OIDC 用のコールバック群と起動時の分岐）にとどまり、ガード関数や Server Action などアプリ側の呼び出しコードは変更不要となっています。&lt;/p&gt;

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

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

&lt;div class="highlight"&gt;&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// OIDC モードで起動する場合&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;nextAuth&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;createOidcAuth&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;

&lt;span class="c1"&gt;// モック認証モードで起動する場合&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;nextAuth&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;createMockAuth&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;handlers&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;signIn&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;signOut&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;nextAuth&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;本番コードの書き換えはほぼこの一カ所で済み、シームレスな差し替えが実現できました。&lt;/p&gt;

&lt;h2 id="副産物モック認証が開発環境に残り続けている"&gt;副産物：モック認証が開発環境に残り続けている&lt;/h2&gt;

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

&lt;h2 id="まとめ"&gt;まとめ&lt;/h2&gt;

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

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

&lt;p&gt;ログイン機構に限らず、要件が決まりきっていない依存を抱えたままプロダクトを前に進めたい場面は、開発の現場には少なくありません。そういうときは、決まっていない部分を特定のレイヤーに封じ込めつつ、それ以外は本番の設計で作り込む、という方針が有効です。どこまでを偽物で受け、どこから先は本番と同じ形で作るか、その線引きの設計こそが、不確実性を抱えたまま前に進むための要となります。&lt;/p&gt;
</content>
  </entry>
  <entry>
    <title>プロンプトのtypoをCIで弾く ── TypeScriptの型でAIへの指示を守る</title>
    <link rel="alternate" href="https://tech.pepabo.com/2026/04/17/typescript-type-safe-prompt/"/>
    <id>https://tech.pepabo.com/2026/04/17/typescript-type-safe-prompt/</id>
    <published>2026-04-17T00:00:00+09:00</published>
    <updated>2026-06-23T00:06:10+00:00</updated>
    <author>
      <name>kinosuke01</name>
    </author>
    <content type="html">&lt;h2 id="はじめに"&gt;はじめに&lt;/h2&gt;

&lt;p&gt;こんにちは。ロリポップ・ムームードメイン事業部でエンジニアリングリードをしています &lt;a href="https://x.com/kinosuke01"&gt;kinosuke01&lt;/a&gt; といいます。先日ゴジラ-0.0のティザー映像が解禁されましたね。公開が楽しみです。&lt;/p&gt;

&lt;p&gt;さて、GMOペパボでは、ユーザーとの対話をもとにWebサイトをまるごと自動生成する&lt;a href="https://lolipop.jp/ai/site-agent/"&gt;AIサイトエージェント&lt;/a&gt;を提供しています。ユーザーが「カフェのサイトを作りたい」「コーポレートサイトがほしい」と伝えるだけで、ページ構成からデザインテーマ、コンテンツまでを一括で生成し、すぐに公開できるWebサイトを作り上げます。&lt;/p&gt;

&lt;p&gt;&lt;img src="/blog/2026/04/17/typescript-type-safe-prompt/img01.png" alt="img01" /&gt;
&lt;img src="/blog/2026/04/17/typescript-type-safe-prompt/img02.png" alt="img02" /&gt;&lt;/p&gt;

&lt;p&gt;この仕組みの裏側では、Webサイトの構造をすべて&lt;strong&gt;JSON&lt;/strong&gt;で表現しています。生成AIに対して「このJSONを埋めてください」と指示し、Structured Outputでフォーマットを固定することで、安定した出力を得ています。&lt;/p&gt;

&lt;p&gt;しかし、JSONの構造を固定するだけでは不十分でした。各プロパティに&lt;strong&gt;何を入れるべきか&lt;/strong&gt;を正しく伝えるために、システムプロンプトでフィールドごとの説明を与えています。ここで問題になったのが、&lt;strong&gt;プロンプトに書いたプロパティ名と実際のコードの型定義がズレるリスク&lt;/strong&gt;です。&lt;/p&gt;

&lt;p&gt;この記事では、TypeScriptの型システムを活用してプロンプトの正しさをコンパイル時に保証する仕組みを紹介します。&lt;/p&gt;

&lt;h2 id="サイト生成の仕組み"&gt;サイト生成の仕組み&lt;/h2&gt;

&lt;h3 id="jsonでwebサイトを表現する"&gt;JSONでWebサイトを表現する&lt;/h3&gt;

&lt;p&gt;私たちのシステムでは、Webサイトを「セクション」の組み合わせで表現しています。ヒーローセクション、特徴紹介セクション、料金表セクションなど、複数のセクションを用意しており、それぞれがJSON構造を持ちます。&lt;/p&gt;

&lt;p&gt;たとえば、ヒーローセクションはこのような構造です。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"component"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"HeroSection"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"props"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"headline"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"text"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"想いを、かたちに。"&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;},&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"title"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"text"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"あなたの「やりたい」を実現するために"&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;},&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"primaryButton"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"label"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"お問い合わせ"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"href"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"/contact"&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;},&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"layout"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"split-content-image"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"image"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"imageId"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"hero-1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"alt"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"メインビジュアル"&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;h3 id="3つのエージェントによる段階的な生成"&gt;3つのエージェントによる段階的な生成&lt;/h3&gt;

&lt;p&gt;サイト生成は、1回のAPI呼び出しで完結するわけではありません。大きく3つの生成ステップに分けて処理を進めます。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;ユーザーのヒアリング情報
          │
          ▼
┌──────────────────────┐
│ PageAndSectionPlanner│  ← ページ構成とセクション選定
└─────────┬────────────┘
          ▼
┌─────────────────────┐
│   ThemeDeterminer   │  ← カラー・フォントの決定
└─────────┬───────────┘
          ▼
┌──────────────────────┐
│ SectionValueGenerator│  ← 各セクションのコンテンツ生成
└─────────┬────────────┘
          ▼
      Webサイト完成
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;h3 id="structured-outputでフォーマットを固定する"&gt;Structured Outputでフォーマットを固定する&lt;/h3&gt;

&lt;p&gt;各ステップの出力は、Zodスキーマで定義した構造に従います。ZodスキーマをJSON Schemaに変換し、Gemini APIの&lt;code&gt;responseSchema&lt;/code&gt;に渡すことで、AIの出力フォーマットを固定しています。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// Zodスキーマを定義&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;themeConfigSchema&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;themeValuesSchema&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;extend&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
  &lt;span class="na"&gt;themeId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;().&lt;/span&gt;&lt;span class="nx"&gt;max&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;MAX_ID&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
  &lt;span class="na"&gt;fontId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="kr"&gt;enum&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;FONT_IDS&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nx"&gt;optional&lt;/span&gt;&lt;span class="p"&gt;(),&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;

&lt;span class="c1"&gt;// JSON Schemaに変換してStructured Outputに渡す&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;themeConfigResponseSchema&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;zodToResponseSchema&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;themeConfigSchema&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="c1"&gt;// AIにリクエスト&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;result&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;model&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;generateContent&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;prompt&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="na"&gt;responseSchema&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;themeConfigResponseSchema&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;これにより、AIが自由なフォーマットでJSONを返してしまう問題は解消されます。&lt;/p&gt;

&lt;h3 id="システムプロンプトで意味を伝える"&gt;システムプロンプトで「意味」を伝える&lt;/h3&gt;

&lt;p&gt;構造を固定しただけでは、AIは各フィールドに何を入れるべきか判断できません。そこで、システムプロンプトでフィールドごとの説明を与えています。&lt;/p&gt;

&lt;p&gt;たとえばセクションのコンテンツを生成する際、こんなプロンプトを組み立てます。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;## セクション1: HeroSection
### フィールド説明
  - layout: レイアウトパターン。split-content-image: コンテンツ左・画像右（全幅）、...
  - headline.text: ページ全体のキャッチコピー。事業の価値を一言で伝える短いフレーズ（10〜20文字）
  - title.text: キャッチコピーを補足するサブメッセージ（15〜30文字）
  - primaryButton.label: メインのCTAボタンのラベル（2〜8文字）。例: 「お問い合わせ」「詳しく見る」
  - primaryButton.href: ボタンのリンク先。サイト内ページへの相対パス（例: /about, /contact）
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;&lt;code&gt;headline.text&lt;/code&gt; や &lt;code&gt;primaryButton.label&lt;/code&gt; といったドットパスでプロパティの位置を指定し、AIに「ここには何文字くらいの、どんなテキストを入れてほしい」と具体的に伝えています。&lt;/p&gt;

&lt;h2 id="課題プロンプトとコードの乖離リスク"&gt;課題：プロンプトとコードの乖離リスク&lt;/h2&gt;

&lt;p&gt;ここまでの仕組みはうまく動いていました。しかし、開発を進める中で不安が生まれます。&lt;/p&gt;

&lt;h3 id="プロパティ名が変わったらどうなる"&gt;プロパティ名が変わったらどうなる？&lt;/h3&gt;

&lt;p&gt;フィールド説明のドットパス（&lt;code&gt;headline.text&lt;/code&gt; や &lt;code&gt;primaryButton.label&lt;/code&gt;）は、セクションのProps型と対応しています。もしリファクタリングで &lt;code&gt;headline&lt;/code&gt; を &lt;code&gt;mainHeading&lt;/code&gt; に変えたとき、フィールド説明のパスも更新しなければなりません。&lt;/p&gt;

&lt;p&gt;しかし、フィールド説明がただの文字列であれば、Props型の変更に追従できているかはコードを目視で確認するしかありません。&lt;/p&gt;

&lt;h3 id="typoは静かに品質を劣化させる"&gt;typoは静かに品質を劣化させる&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;headline.text&lt;/code&gt; を &lt;code&gt;headling.text&lt;/code&gt; とtypoしたらどうなるでしょうか。プログラムはエラーを出しません。プロンプトの中に誤ったパスが紛れ込むだけです。AIはそのパスに対応するフィールドを見つけられず、適切なコンテンツを生成できなくなります。&lt;/p&gt;

&lt;p&gt;結果として、ある日突然「ヒーローセクションのキャッチコピーがなぜか空っぽのサイトが生成された」といった不具合が起きる可能性があります。Structured Outputで構造は正しいのに、中身の品質が落ちる。原因の特定が難しい厄介な問題です。&lt;/p&gt;

&lt;h2 id="解決策typescriptの型でプロンプトを縛る"&gt;解決策：TypeScriptの型でプロンプトを縛る&lt;/h2&gt;

&lt;h3 id="アプローチの全体像"&gt;アプローチの全体像&lt;/h3&gt;

&lt;p&gt;まず、私たちが取ったアプローチの全体像を示します。&lt;/p&gt;

&lt;p&gt;セクションごとに「フィールド説明オブジェクト」を定義し、それをプロンプト組み立て時に埋め込む構成にしました。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;fieldDescs&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="na"&gt;layout&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;レイアウトパターン。split-content-image: コンテンツ左・画像右...&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;headline.text&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;ページ全体のキャッチコピー。事業の価値を一言で伝える短いフレーズ（10〜20文字）&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;title.text&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;キャッチコピーを補足するサブメッセージ（15〜30文字）&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;primaryButton.label&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;メインのCTAボタンのラベル（2〜8文字）。例: 「お問い合わせ」「詳しく見る」&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;primaryButton.href&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;ボタンのリンク先。サイト内ページへの相対パス（例: /about, /contact）&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;};&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;ドットパスをキー、AIへの説明を値とするシンプルなオブジェクトです。プロンプト組み立て時にこのオブジェクトを展開し、箇条書き形式でプロンプトに埋め込みます。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nx"&gt;formatSectionFieldDescs&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;descs&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;Record&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nb"&gt;Object&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;entries&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;descs&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;map&lt;/span&gt;&lt;span class="p"&gt;(([&lt;/span&gt;&lt;span class="nx"&gt;path&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;desc&lt;/span&gt;&lt;span class="p"&gt;])&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="s2"&gt;`  - &lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;path&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;: &lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;desc&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="se"&gt;\n&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;ここまでは特別なことはしていません。ポイントはこの次です。&lt;/p&gt;

&lt;p&gt;このオブジェクトのキーに&lt;strong&gt;TypeScriptの型制約&lt;/strong&gt;を加えることで、typoやプロパティ名の変更に対してコンパイルエラーで気づけるようにしました。&lt;/p&gt;

&lt;h3 id="satisfiesで定義を検証する"&gt;satisfiesで定義を検証する&lt;/h3&gt;

&lt;p&gt;具体的に見ていきましょう。各セクションのメタデータ定義で &lt;code&gt;satisfies&lt;/code&gt; を使って型制約をかけます。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;heroSectionMeta&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;HeroSection&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="c1"&gt;// ...&lt;/span&gt;
  &lt;span class="na"&gt;fieldDescs&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="na"&gt;layout&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;buildLayoutFieldDesc&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;layoutDescs&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
    &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;headline.text&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;ページ全体のキャッチコピー。事業の価値を一言で伝える短いフレーズ（10〜20文字）&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;title.text&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;キャッチコピーを補足するサブメッセージ（15〜30文字）&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;primaryButton.label&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;メインのCTAボタンのラベル（2〜8文字）。例: 「お問い合わせ」「詳しく見る」&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;primaryButton.href&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;ボタンのリンク先。サイト内ページへの相対パス（例: /about, /contact）&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;secondaryButton.label&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;サブのCTAボタンのラベル（2〜8文字）。例: 「詳しく見る」「サービス一覧」&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="nx"&gt;satisfies&lt;/span&gt; &lt;span class="nx"&gt;ValidFieldDescs&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;HeroSectionProps&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;  &lt;span class="c1"&gt;// ← ここ&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;末尾の &lt;code&gt;satisfies ValidFieldDescs&amp;lt;HeroSectionProps&amp;gt;&lt;/code&gt; が効いています。もし &lt;code&gt;"headline.text"&lt;/code&gt; を &lt;code&gt;"headling.text"&lt;/code&gt; とtypoしたら、&lt;strong&gt;コンパイルエラー&lt;/strong&gt;になります。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;// typoするとコンパイルエラー
"headling.text": "ページ全体のキャッチコピー..."
// ~~~~~~~~~~~~~~
// Type '"headling.text"' is not assignable to type 'FieldDescPaths&amp;lt;HeroSectionProps&amp;gt;'
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;Props型のプロパティ名を変更した場合も同様です。&lt;code&gt;headline&lt;/code&gt; を &lt;code&gt;mainHeading&lt;/code&gt; にリネームすれば、&lt;code&gt;"headline.text"&lt;/code&gt; は無効なパスになり、コンパイラが教えてくれます。&lt;/p&gt;

&lt;h3 id="validfielddescsの仕組み"&gt;ValidFieldDescsの仕組み&lt;/h3&gt;

&lt;p&gt;では &lt;code&gt;ValidFieldDescs&lt;/code&gt; がどのように機能しているかを見てみましょう。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nx"&gt;ValidFieldDescs&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;Props&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;Partial&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;
  &lt;span class="nb"&gt;Record&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;FieldDescPaths&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;Props&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;&lt;code&gt;FieldDescPaths&amp;lt;Props&amp;gt;&lt;/code&gt; がProps型から「有効なドットパス」のunion型を自動生成する部分です。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nx"&gt;FieldDescPaths&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;T&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;D&lt;/span&gt; &lt;span class="kd"&gt;extends&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;4&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt;
  &lt;span class="nx"&gt;D&lt;/span&gt; &lt;span class="kd"&gt;extends&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;
    &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="nx"&gt;never&lt;/span&gt;
    &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;T&lt;/span&gt; &lt;span class="kd"&gt;extends&lt;/span&gt; &lt;span class="nx"&gt;object&lt;/span&gt;
      &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="nx"&gt;IsIndexSignature&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;T&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="kd"&gt;extends&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
        &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="nx"&gt;never&lt;/span&gt;
        &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;K&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="kr"&gt;keyof&lt;/span&gt; &lt;span class="nx"&gt;NonNullish&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;T&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;]:&lt;/span&gt;
              &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="nx"&gt;K&lt;/span&gt;
              &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;NonNullish&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;T&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;K&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="kd"&gt;extends&lt;/span&gt; &lt;span class="nb"&gt;Array&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;infer&lt;/span&gt; &lt;span class="nx"&gt;E&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
                  &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="nx"&gt;E&lt;/span&gt; &lt;span class="kd"&gt;extends&lt;/span&gt; &lt;span class="nx"&gt;object&lt;/span&gt;
                    &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;K&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;[]`&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;K&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;[].&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;FieldDescPaths&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;E&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;Prev&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;D&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;
                    &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;K&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;[]`&lt;/span&gt;
                  &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;NonNullish&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;T&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;K&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="kd"&gt;extends&lt;/span&gt; &lt;span class="nx"&gt;object&lt;/span&gt;
                    &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;K&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;.&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;FieldDescPaths&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;NonNullish&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;T&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;K&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt; &lt;span class="nx"&gt;Prev&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;D&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;
                    &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;never&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
          &lt;span class="p"&gt;}[&lt;/span&gt;&lt;span class="kr"&gt;keyof&lt;/span&gt; &lt;span class="nx"&gt;NonNullish&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;T&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
      &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;never&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;一見複雑ですが、やっていることはシンプルです。Props型を再帰的に走査し、有効なドットパスをすべてunion型として列挙します。&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;トップレベル&lt;/strong&gt;: &lt;code&gt;"layout"&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;ネストしたオブジェクト&lt;/strong&gt;: &lt;code&gt;"headline.text"&lt;/code&gt;, &lt;code&gt;"primaryButton.label"&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;配列の要素&lt;/strong&gt;: &lt;code&gt;"orderList.items[].title.text"&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;たとえば &lt;code&gt;HeroSectionProps&lt;/code&gt; に適用すると、&lt;code&gt;"layout" | "headline" | "headline.text" | "title" | "title.text" | "primaryButton" | "primaryButton.label" | "primaryButton.href" | ...&lt;/code&gt; のようなunion型が得られます。このunion型に含まれないキーを &lt;code&gt;fieldDescs&lt;/code&gt; に書くと、&lt;code&gt;satisfies&lt;/code&gt; によりコンパイルエラーになるというわけです。&lt;/p&gt;

&lt;h3 id="テーマプロンプトでも同じアプローチ"&gt;テーマプロンプトでも同じアプローチ&lt;/h3&gt;

&lt;p&gt;テーマ決定のプロンプトでも、カラーパスの定数を型で縛っています。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nx"&gt;ColorsInferred&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;infer&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="k"&gt;typeof&lt;/span&gt; &lt;span class="nx"&gt;colorsSchema&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="cm"&gt;/** "group.field" 形式のパス型。colorsSchemaと一致しない場合コンパイルエラー */&lt;/span&gt;
&lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nx"&gt;ColorPath&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;G&lt;/span&gt; &lt;span class="kd"&gt;extends&lt;/span&gt; &lt;span class="kr"&gt;keyof&lt;/span&gt; &lt;span class="nx"&gt;ColorsInferred&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt;
  &lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;G&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;.&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="kr"&gt;string&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&lt;/span&gt; &lt;span class="kr"&gt;keyof&lt;/span&gt; &lt;span class="nx"&gt;ColorsInferred&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;G&lt;/span&gt;&lt;span class="p"&gt;]}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="cm"&gt;/** スキーマと連動した型安全なパス定数 */&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;BG_PRIMARY_PATH&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;ColorPath&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;background&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;background.primary&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;TYPOGRAPHY_CONTRAST_PATH&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;ColorPath&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;typography&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;typography.contrastText&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;これらの定数はシステムプロンプトに埋め込まれます。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;themePrompt&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;`
...
- {TYPOGRAPHY_CONTRAST_KEY} と {BG_PRIMARY_KEY} は必ず高コントラストを保ってください
...
`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;// プロンプト組み立て時に定数を埋め込む&lt;/span&gt;
&lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;themePrompt&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;replace&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sr"&gt;/{TYPOGRAPHY_CONTRAST_KEY}/g&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;TYPOGRAPHY_CONTRAST_PATH&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;replace&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sr"&gt;/{BG_PRIMARY_KEY}/g&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;BG_PRIMARY_PATH&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;もし &lt;code&gt;colorsSchema&lt;/code&gt; から &lt;code&gt;contrastText&lt;/code&gt; が削除されたり名前が変わったりすれば、&lt;code&gt;TYPOGRAPHY_CONTRAST_PATH&lt;/code&gt; の定義でコンパイルエラーが発生します。プロンプトに存在しないプロパティ名が紛れ込む余地がありません。&lt;/p&gt;

&lt;h3 id="フィールド説明の型安全性も"&gt;フィールド説明の型安全性も&lt;/h3&gt;

&lt;p&gt;テーマのカラーフィールド説明にも、同じ考え方を適用しています。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="cm"&gt;/** palette 各フィールドの説明（AI プロンプト用） */&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;paletteFieldDescs&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;Record&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;
  &lt;span class="kr"&gt;keyof&lt;/span&gt; &lt;span class="nx"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;infer&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="k"&gt;typeof&lt;/span&gt; &lt;span class="nx"&gt;paletteSchema&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="kr"&gt;string&lt;/span&gt;
&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="na"&gt;primary&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;パレットの主役となる色（全体の起点）&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="na"&gt;light&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;背景とprimaryを繋ぐ低彩度カラー&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="na"&gt;deep&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;primary のダークトーン（引き締め）&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;};&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;&lt;code&gt;Record&amp;lt;keyof z.infer&amp;lt;typeof paletteSchema&amp;gt;, string&amp;gt;&lt;/code&gt; により、&lt;code&gt;paletteSchema&lt;/code&gt; のすべてのフィールドに対して説明を書くことが強制されます。フィールドを追加したのに説明を書き忘れたらコンパイルエラー、存在しないフィールドの説明を書いてもコンパイルエラーです。&lt;/p&gt;

&lt;h2 id="まとめ"&gt;まとめ&lt;/h2&gt;

&lt;p&gt;生成AIを活用したシステムでは、プロンプトの品質がそのままサービスの品質に直結します。しかしプロンプトは往々にしてただの文字列として扱われ、コードとの整合性は開発者の注意力に依存しがちです。&lt;/p&gt;

&lt;p&gt;私たちはTypeScriptの型システムを使って、&lt;strong&gt;プロンプトに埋め込むフィールド名やパスをコードの型定義と連動させる&lt;/strong&gt;ことで、この問題を解決しました。特別なツールやライブラリは必要ありません。&lt;code&gt;satisfies&lt;/code&gt;、Template Literal Types、&lt;code&gt;Record&amp;lt;keyof T, string&amp;gt;&lt;/code&gt; といったTypeScriptの標準的な機能だけで実現できます。&lt;/p&gt;

&lt;p&gt;この仕組みの良いところは、&lt;strong&gt;CIの型チェック（&lt;code&gt;tsc --noEmit&lt;/code&gt;）で自然にカバーされる&lt;/strong&gt;点です。プロンプト専用のテストを書く必要はなく、普段の開発フローの中で、プロパティ名の変更やtypoが自動的に検出されます。&lt;/p&gt;

&lt;p&gt;プロンプトもコードの一部です。型で守れるものは、型で守りましょう。&lt;/p&gt;
</content>
  </entry>
  <entry>
    <title>flaky testの原因は、無関係なファイルの1行にあった</title>
    <link rel="alternate" href="https://tech.pepabo.com/2026/04/15/flaky-test-investigation/"/>
    <id>https://tech.pepabo.com/2026/04/15/flaky-test-investigation/</id>
    <published>2026-04-15T00:00:00+09:00</published>
    <updated>2026-06-23T00:06:10+00:00</updated>
    <author>
      <name>aruma</name>
    </author>
    <content type="html">&lt;p&gt;SUZURI Webアプリケーションエンジニアのarumaです。&lt;a href="/2026/04/14/flaky-tests/"&gt;昨日の記事&lt;/a&gt;では、SUZURIで遭遇したflaky testの事例をいくつかご紹介しました。本記事では、その中でも特に原因の特定が難しかった1件を深掘りします。&lt;/p&gt;

&lt;ol id="markdown-toc"&gt;
  &lt;li&gt;&lt;a href="#発生していた現象" id="markdown-toc-発生していた現象"&gt;発生していた現象&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#手がかり1-自前のメソッドが呼ばれていない" id="markdown-toc-手がかり1-自前のメソッドが呼ばれていない"&gt;手がかり1: 自前のメソッドが呼ばれていない&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#手がかり2-フレームワークに同名メソッドが追加されていた" id="markdown-toc-手がかり2-フレームワークに同名メソッドが追加されていた"&gt;手がかり2: フレームワークに同名メソッドが追加されていた&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#手がかり3-ancestorsチェーンの順序が変わっている" id="markdown-toc-手がかり3-ancestorsチェーンの順序が変わっている"&gt;手がかり3: ancestorsチェーンの順序が変わっている&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#手がかり4-トップレベルでのinclude" id="markdown-toc-手がかり4-トップレベルでのinclude"&gt;手がかり4: トップレベルでのinclude&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#真相" id="markdown-toc-真相"&gt;真相&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#おわりに" id="markdown-toc-おわりに"&gt;おわりに&lt;/a&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;h2 id="発生していた現象"&gt;発生していた現象&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;ApplicationHelper&lt;/code&gt; に定義された画像表示用のヘルパーメソッド &lt;code&gt;picture_tag&lt;/code&gt; のテストが、時々failしていました。&lt;/p&gt;

&lt;p&gt;fail時のログを確認すると、&lt;code&gt;picture_tag&lt;/code&gt; が期待と異なるHTMLを生成していました。&lt;/p&gt;

&lt;p&gt;CIの実行ログからpass時とfail時それぞれのseed値を確認し、ローカルで同じseedを指定して実行してみると、seed値に応じてpassとfailが再現しました。&lt;/p&gt;

&lt;h2 id="手がかり1-自前のメソッドが呼ばれていない"&gt;手がかり1: 自前のメソッドが呼ばれていない&lt;/h2&gt;

&lt;p&gt;試しに &lt;code&gt;ApplicationHelper#picture_tag&lt;/code&gt; の中身に &lt;code&gt;raise&lt;/code&gt; を加えてそれぞれのseedで実行してみると、&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;passしていたseedで実行 → 例外が発生&lt;/li&gt;
  &lt;li&gt;failしていたseedで実行 → 例外は発生せず、同じようにfail&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;という結果になりました。つまり、failするseedでは、テスト対象 &lt;code&gt;ApplicationHelper#picture_tag&lt;/code&gt; がそもそも呼ばれていないということです。では、代わりに何が呼ばれているのでしょうか？&lt;/p&gt;

&lt;h2 id="手がかり2-フレームワークに同名メソッドが追加されていた"&gt;手がかり2: フレームワークに同名メソッドが追加されていた&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;picture_tag&lt;/code&gt; で検索してみると、Rails 7.1で &lt;code&gt;ActionView::Helpers::AssetTagHelper&lt;/code&gt; に同名の &lt;code&gt;picture_tag&lt;/code&gt; メソッドが&lt;a href="https://guides.rubyonrails.org/7_1_release_notes.html#action-view-notable-changes"&gt;新規追加されていた&lt;/a&gt;ことがわかりました。&lt;code&gt;ApplicationHelper#picture_tag&lt;/code&gt; とは異なる動作をするメソッドです。&lt;/p&gt;

&lt;p&gt;fail時の出力は、この &lt;code&gt;AssetTagHelper#picture_tag&lt;/code&gt; の動作と一致していました。failするseedでは、&lt;code&gt;ApplicationHelper#picture_tag&lt;/code&gt; ではなく &lt;code&gt;AssetTagHelper#picture_tag&lt;/code&gt; が呼ばれていたようです。&lt;/p&gt;

&lt;p&gt;Rubyのメソッド解決は、ancestorsチェーンを前から順にたどり、最初に見つかったメソッドを呼び出す仕組みです。通常、&lt;code&gt;ApplicationHelper&lt;/code&gt; は &lt;code&gt;ActionView::Helpers::AssetTagHelper&lt;/code&gt; よりもancestorsチェーンの前方に位置するため、フレームワーク側に同名のメソッドが追加されても &lt;code&gt;ApplicationHelper&lt;/code&gt; の方が優先されるはずです。&lt;/p&gt;

&lt;p&gt;ところが今回は、seed値によって呼ばれるメソッドが変わっています。ancestorsチェーンを実際に確認してみることにしました。&lt;/p&gt;

&lt;h2 id="手がかり3-ancestorsチェーンの順序が変わっている"&gt;手がかり3: ancestorsチェーンの順序が変わっている&lt;/h2&gt;

&lt;p&gt;pass時とfail時、それぞれのseedでテスト対象のオブジェクトのancestorsチェーンを出力して比較してみると、次のようになっていました。&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;pass時&lt;/strong&gt;&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;...
 29: ApplicationHelper
...
 77: ActionView::Helpers::AssetTagHelper
...
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;fail時&lt;/strong&gt;&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;...
 76: ActionView::Helpers::AssetTagHelper
...
 95: ApplicationHelper
...
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;pass時には &lt;code&gt;ApplicationHelper&lt;/code&gt; が &lt;code&gt;AssetTagHelper&lt;/code&gt; より前にありますが、fail時には順序が逆転していました。つまり、failするseedでは &lt;code&gt;AssetTagHelper#picture_tag&lt;/code&gt; が先に見つかり、そちらが呼ばれていたのです。&lt;/p&gt;

&lt;h2 id="手がかり4-トップレベルでのinclude"&gt;手がかり4: トップレベルでのinclude&lt;/h2&gt;

&lt;p&gt;ancestorsチェーンが変わる原因を突き止めるため、&lt;code&gt;ApplicationHelper&lt;/code&gt; に &lt;code&gt;included&lt;/code&gt; フックを仕込みました。モジュールがどこかに &lt;code&gt;include&lt;/code&gt; されるたびに、include先とそのコールスタックを出力するものです。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="k"&gt;module&lt;/span&gt; &lt;span class="nn"&gt;ApplicationHelper&lt;/span&gt;
  &lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nc"&gt;self&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;included&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;base&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="nb"&gt;puts&lt;/span&gt; &lt;span class="s2"&gt;"ApplicationHelper included into: &lt;/span&gt;&lt;span class="si"&gt;#{&lt;/span&gt;&lt;span class="n"&gt;base&lt;/span&gt;&lt;span class="si"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;
    &lt;span class="nb"&gt;puts&lt;/span&gt; &lt;span class="nb"&gt;caller&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;first&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;3&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="se"&gt;\n&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;failするseedで実行してみると、次の出力が得られました。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;ApplicationHelper included into: Object
  spec/graphql/queries/some_query_spec.rb:2:in 'include'
  spec/graphql/queries/some_query_spec.rb:2:in '&amp;lt;main&amp;gt;'
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;&lt;code&gt;ApplicationHelper&lt;/code&gt; が &lt;strong&gt;&lt;code&gt;Object&lt;/code&gt; クラスに&lt;/strong&gt; includeされています。該当のspecファイルを見てみると、以下のようなコードでした。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="nb"&gt;require&lt;/span&gt; &lt;span class="s1"&gt;'spec_helper'&lt;/span&gt;
&lt;span class="kp"&gt;include&lt;/span&gt; &lt;span class="no"&gt;ApplicationHelper&lt;/span&gt;

&lt;span class="n"&gt;describe&lt;/span&gt; &lt;span class="s1"&gt;'SomeQuery'&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
  &lt;span class="c1"&gt;# ...&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;&lt;code&gt;include&lt;/code&gt; が &lt;code&gt;describe&lt;/code&gt; ブロックの外、つまりトップレベルで実行されています。トップレベルで &lt;code&gt;include&lt;/code&gt; を実行すると、&lt;code&gt;Object&lt;/code&gt; クラスに対しての &lt;code&gt;include&lt;/code&gt; となります。&lt;code&gt;Object&lt;/code&gt; はほぼ全てのRubyクラスの祖先なので、ここにモジュールが追加されると全クラスのancestorsチェーンに影響します。&lt;/p&gt;

&lt;h2 id="真相"&gt;真相&lt;/h2&gt;

&lt;p&gt;今回の事象は、3つの要因が重なって発生していました。&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;Rails 7.1で追加された &lt;code&gt;AssetTagHelper#picture_tag&lt;/code&gt; と、自前の &lt;code&gt;ApplicationHelper#picture_tag&lt;/code&gt; が名前衝突していた。どちらが呼ばれるかはancestorsチェーンの順序で決まる（通常は自前のメソッドが優先される）&lt;/li&gt;
  &lt;li&gt;あるspecファイルがトップレベルで（つまり &lt;code&gt;Object&lt;/code&gt; へ） &lt;code&gt;include ApplicationHelper&lt;/code&gt; を実行していた&lt;/li&gt;
  &lt;li&gt;RSpecのテスト実行順序はseed値によって毎回変わる&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;つまり、seed値次第で、テスト実行の流れは次のどちらかになります。&lt;/p&gt;

&lt;p&gt;問題のspecが&lt;strong&gt;先に&lt;/strong&gt;実行される場合:&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;テスト実行開始&lt;/li&gt;
  &lt;li&gt;問題のspecが読み込まれ、&lt;code&gt;ApplicationHelper&lt;/code&gt; が &lt;code&gt;Object&lt;/code&gt; にincludeされる&lt;/li&gt;
  &lt;li&gt;ヘルパーのspecが実行される。&lt;code&gt;ApplicationHelper&lt;/code&gt; はすでにinclude済みのため、テストコンテキストへのincludeが無視され、&lt;code&gt;AssetTagHelper#picture_tag&lt;/code&gt; が優先される → &lt;strong&gt;fail&lt;/strong&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;問題のspecが&lt;strong&gt;後に&lt;/strong&gt;実行される場合:&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;テスト実行開始&lt;/li&gt;
  &lt;li&gt;ヘルパーのspecが実行される。&lt;code&gt;ApplicationHelper&lt;/code&gt; が通常通りテストコンテキストにincludeされ、&lt;code&gt;ApplicationHelper#picture_tag&lt;/code&gt; が優先される → &lt;strong&gt;pass&lt;/strong&gt;&lt;/li&gt;
  &lt;li&gt;問題のspecが読み込まれ、&lt;code&gt;ApplicationHelper&lt;/code&gt; が &lt;code&gt;Object&lt;/code&gt; にincludeされる（しかし結果に影響しない）&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;なお、”先か後か” の二択ならfailの確率は50%となりますが、SUZURIのCIではテストを複数プロセスに分散して実行しているため、実際の発生頻度は数%程度となっていたのでした。&lt;/p&gt;

&lt;p&gt;原因さえわかれば対策はシンプルで、トップレベルでの &lt;code&gt;include&lt;/code&gt; をやめるだけでした。&lt;br /&gt;
同種の問題を防ぐには、トップレベルでの &lt;code&gt;include&lt;/code&gt; を禁止するlint規則が有効です。&lt;/p&gt;

&lt;h2 id="おわりに"&gt;おわりに&lt;/h2&gt;

&lt;p&gt;この問題は、今回のflaky test対処の中で原因特定に最も時間がかかったケースでした。どの要因も単体では問題になりませんが、3つが重なることで原因の見えにくいflaky testになっていました。&lt;/p&gt;

&lt;p&gt;他のflaky testの事例は&lt;a href="/2026/04/14/flaky-tests/"&gt;前回の記事&lt;/a&gt;で紹介しています。&lt;/p&gt;
</content>
  </entry>
  <entry>
    <title>シニアエンジニア所信表明 — レバレッジと横断性で事業やサービスが向かうべき先に未来を作る</title>
    <link rel="alternate" href="https://tech.pepabo.com/2026/04/15/senior-engineer-haruotsu/"/>
    <id>https://tech.pepabo.com/2026/04/15/senior-engineer-haruotsu/</id>
    <published>2026-04-15T00:00:00+09:00</published>
    <updated>2026-06-23T00:06:10+00:00</updated>
    <author>
      <name>haruotsu</name>
    </author>
    <content type="html">&lt;p&gt;こんにちは！ロリポップ・ムームードメイン事業部ムームードメイングループのはるおつ（&lt;a href="https://x.com/haruotsu_hy"&gt;@haruotsu_hy&lt;/a&gt;）です。2026年4月1日にシニアエンジニアになりました。このエントリーでは、シニアエンジニアとしてこれから何をしていくのかを、ここに至るまでの経緯とあわせて書きます。&lt;/p&gt;

&lt;h2 id="所信表明"&gt;所信表明&lt;/h2&gt;

&lt;p&gt;シニアエンジニアとして、&lt;strong&gt;レバレッジの効く開発と横断的な行動を武器に、目の前の課題を技術構造ごと解き、事業やサービスが向かうべき先に未来を作る。その成果を全社・業界を動かすレベルまで広げていきます。&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;レバレッジの効く開発とは、一つの技術投資が時間軸・組織軸・技術軸で複数の価値を生む開発です。個別の問題を個別に解くのではなく、構造的に解く。目の前のタスクの背後にある構造を変えることで、まだ見えていない未来の課題まで同時に解決する。&lt;/p&gt;

&lt;p&gt;横断的な行動とは、価値を届けるために自分から境界を越えに行くということです。技術領域も、組織も、職域も関係ない。価値があるなら自分のチームに閉じさせず、どこまでも持っていく。境界を一つ越えるたびに、同じ投資の効果が倍になっていく。&lt;/p&gt;

&lt;p&gt;レバレッジで一つの投資の価値を最大化し、横断性でその価値の届く範囲を最大化する。この掛け算で、事業が向かうべき方向に対して技術の力で道を作る。それが私のエンジニアリングです。&lt;/p&gt;

&lt;h2 id="ペパボのエンジニア職位制度"&gt;ペパボのエンジニア職位制度&lt;/h2&gt;

&lt;p&gt;GMOペパボのエンジニア職位制度は立候補制です。「作り上げる力」「先を見通す力」「影響を広げる力」の3軸で評価され、基準を超えた人が立候補資料を提出して昇格の判断を受けます（&lt;a href="https://tech.pepabo.com/engineers/"&gt;詳細&lt;/a&gt;）。&lt;/p&gt;

&lt;p&gt;判断は「&lt;strong&gt;追認制&lt;/strong&gt;」、つまりすでに実質その等級として振る舞えている人だけが昇格します。&lt;br /&gt;
私の立候補資料も「以上で、私がシニアエンジニアに相応しい人材であるということは十分であろう。」という結論とともに締めくくりました。&lt;/p&gt;

&lt;p&gt;&lt;img src="/blog/2026/04/15/senior-engineer-haruotsu/images/position-map.png" alt="エンジニア職位制度" /&gt;&lt;/p&gt;

&lt;h2 id="これまで"&gt;これまで&lt;/h2&gt;

&lt;p&gt;私は2024年4月、&lt;a href="https://recruit.group.gmo/710program/"&gt;新卒年収710万プログラム&lt;/a&gt;のエンジニアとしてペパボに入社しました。&lt;a href="https://www.onecareer.jp/articles/2754"&gt;プログラムの導入背景&lt;/a&gt;にあるように、尖った技術力や専門性を幹にしながら複数の枝を生やし、すべてを自分ごと化しながら高いモチベーションと覚悟でチャレンジしていくことが求められる採用枠です。&lt;/p&gt;

&lt;p&gt;その期待に応えるべく、ペパボの「&lt;a href="https://speakerdeck.com/kentaro/the-secret-of-leadership-and-followership"&gt;やっていき・のっていき&lt;/a&gt;」文化の「いいじゃん！」に背中を押されながら、同期や先輩パートナーとともに、速度感をもってありとあらゆることに挑戦し時には職種を超えて社内外で注目される活動を重ねてきたように思います。&lt;/p&gt;

&lt;p&gt;しかし、2025年8月に行った1度目の立候補では、シニアエンジニアになることは叶いませんでした。&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;「キャッチアップ力と行動量によって仕事が速いことは素晴らしい」「課題の粒度が小さい」「専門性が浅い」「レバレッジの影響範囲が狭い」「ペパボやサービスが haruotsu の専門性によってどう変わっていくのかという視点で課題に取り組み、上長やチームと同期し、意思決定を行なっていくことを期待」（抜粋）&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;与えられたタスクを速を出しながらやっていき・のっていきを発揮しながら薙ぎ倒していくと同時に、シニアエンジニアに求められていたのは、部門の目標達成に関わる構造的課題を自分で定義し、自分の専門性で解き、その成果を事業部や会社レベルで動かしていく。この一連のサイクルを自分の手で回し切ることでした。&lt;/p&gt;

&lt;p&gt;それ以降降ってくるタスクひとつひとつに対して、事業のボトルネックや構造的な課題はどこにあるか、当たり前を常に疑い、開発にレバレッジを組み込める余地はないか。&lt;/p&gt;

&lt;p&gt;そしてそれを個人の思いつきで突き進めるのではなく、事業が向かうべき方向、ムームードメインでいえば「ドメインを入り口としたサービス展開」を軸に、未解決の専門領域の課題を自分で定義し、最速最高で実行し続けました。
その過程では、エンジニアチームが描きたい未来、自分が目指す「最高」が他メンバーの「最高」と干渉しないか、チーム・設計・拡張性の観点で最適かを常にすり合わせました。
それに加えて「なぜ今これをやるのか」「どのような価値を出しながら進めていくか」を言葉にし、エンジニアが目指す姿とマネージャを含めたビジネス側が求める価値のキャリブレーションを続けました。&lt;/p&gt;

&lt;p&gt;結果として、私が引いた設計や事業価値の整理は、以降の施策を進める際の判断軸の一つとしてチームに残り、他メンバーの意思決定の土台にもなっていきました。
自分の動きが、自分一人の成果にとどまらず、組織の共通資産として機能し始めた手応えがあります。&lt;/p&gt;

&lt;p&gt;これをひとつのサイクルとして回し続けることで、言葉として持っていた「レバレッジ」と「横断性」を実践の規模で体現していきました。&lt;/p&gt;

&lt;p&gt;そうして臨んだ2度目の立候補で、以下のようなフィードバックをいただきました。&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;長らく手がつけられなかった大きな事業課題に対し、臆することなく解決可能なサイズへと切り分け、&lt;strong&gt;圧倒的なコミット力で薙ぎ倒していく姿勢&lt;/strong&gt;を高く評価します。アウトプットの量のみならず、その質においても &lt;strong&gt;「最高・最速」を両立&lt;/strong&gt;させており、シニアエンジニアに相応しい模範を示しました。特に、歴史的経緯から困難であったシステムに対し、&lt;strong&gt;長期的な拡張性を担保した基盤を短期間で組み込んだ功績&lt;/strong&gt;は大きいです。&lt;strong&gt;「負の遺産の解消と未来の創出」が同時に実現&lt;/strong&gt;されたことは、4等級に求められる&lt;strong&gt;専門性と推進力の証左&lt;/strong&gt;です。（抜粋）&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;過去の負債を片付けるために作ったものが、そのまま未来の武器になる。一つの投資で過去と未来の両方を動かす。これがレバレッジと横断性の掛け算であり、大切にしていることそのものを認めていただけたと受け止めています。&lt;/p&gt;

&lt;h2 id="これから"&gt;これから&lt;/h2&gt;

&lt;p&gt;てこの支点が深いところにあるほど、動かせるものは大きくなります。フィードバックでは、以下のような期待もいただいています。&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;事業の中核をなす専門技術への理解をさらに深め、社内での実践に留まらず、該当領域の技術コミュニティへの積極的な参加や発信にも取り組んでほしいです。一般的なWebエンジニアの枠を超え、ペパボの事業ドメインにおける第一人者としての専門性を身につけることで、会社に、そして業界にさらなる大きなインパクトを与えるリーダーへと成長していく姿を期待しています。 (抜粋)&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;今いる場所でその中核技術となるのはドメインやDNSです。インターネットの根幹をなすこの領域にまずは深く潜ります。&lt;br /&gt;
また、ドメイン領域に限らず、どこにいても、その事業の中核をなす技術に深く潜っていきます。&lt;/p&gt;

&lt;p&gt;それがレバレッジの支点を深くすることになると考えています。&lt;/p&gt;

&lt;p&gt;加えて、AIによって開発の時間軸が圧縮され続けているいま、この変化にただ適応するのではなく、自分自身、そしてペパボが業界において先んじてインパクトを起こしていきたいと考えています。&lt;/p&gt;

&lt;p&gt;事業ドメインの深化も新しい時代への対応も、レバレッジと横断性を武器に最高・最速を両立させていきます。&lt;/p&gt;
</content>
  </entry>
</feed>