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-05-01T00:00:00+09:00</updated>
  <author>
    <name>GMO Pepabo, Inc.</name>
  </author>
  <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-05-04T00:07:16+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-05-04T00:07:16+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-05-04T00:07:16+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-05-04T00:07:16+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-05-04T00:07:16+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-05-04T00:07:16+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-05-04T00:07:16+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>
  <entry>
    <title>SUZURIで遭遇したflaky testの事例集</title>
    <link rel="alternate" href="https://tech.pepabo.com/2026/04/14/flaky-tests/"/>
    <id>https://tech.pepabo.com/2026/04/14/flaky-tests/</id>
    <published>2026-04-14T00:00:00+09:00</published>
    <updated>2026-05-04T00:07:16+00:00</updated>
    <author>
      <name>aruma</name>
    </author>
    <content type="html">&lt;p&gt;SUZURI Webアプリケーションエンジニアのarumaです。SUZURIにはRSpecによるテストコードが多数ありますが、一時期flaky testが増えてCIが不安定になってしまったことがありました。まとめて調査・対処した際の記録から、いくつかの事例をピックアップしてご紹介します。&lt;/p&gt;

&lt;p&gt;なお、記事中のコードは説明のために簡略化したものです。&lt;/p&gt;

&lt;ol id="markdown-toc"&gt;
  &lt;li&gt;&lt;a href="#事例1-2026年になると失敗するテスト" id="markdown-toc-事例1-2026年になると失敗するテスト"&gt;事例1: 2026年になると失敗するテスト&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#事例2-深夜0時ちょうどにのみ失敗するテスト" id="markdown-toc-事例2-深夜0時ちょうどにのみ失敗するテスト"&gt;事例2: 深夜0時ちょうどにのみ失敗するテスト&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;li&gt;&lt;a href="#事例4-不正なテストデータが作られていたテスト" id="markdown-toc-事例4-不正なテストデータが作られていたテスト"&gt;事例4: 不正なテストデータが作られていたテスト&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#事例5-偶然の一致で失敗するテスト" id="markdown-toc-事例5-偶然の一致で失敗するテスト"&gt;事例5: 偶然の一致で失敗するテスト&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="事例1-2026年になると失敗するテスト"&gt;事例1: 2026年になると失敗するテスト&lt;/h2&gt;

&lt;p&gt;これは厳密にはflaky testというより「ある時点から必ず失敗するようになったテスト」ですが、テストの書き方に共通する教訓があるので紹介します。&lt;/p&gt;

&lt;p&gt;クレジットカード決済に関するテストのセットアップ内で、カードの有効期限がハードコードされていました。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="n"&gt;let&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="ss"&gt;:credit_card&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
  &lt;span class="n"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="ss"&gt;:credit_card&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="ss"&gt;expire_year: &lt;/span&gt;&lt;span class="mi"&gt;2025&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="ss"&gt;expire_month: &lt;/span&gt;&lt;span class="mi"&gt;12&lt;/span&gt;
  &lt;span class="p"&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;このコードが書かれたのは2020年。5年間は問題なく動いていましたが、2026年を迎えた途端に有効期限切れの無効なカードとなり、テストの検証対象とは無関係な理由でエラーが発生するようになってしまいました。&lt;/p&gt;

&lt;p&gt;対処として、有効期限が常に未来の日付となるよう、現在の日付から算出する形に変更しました。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="n"&gt;let&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="ss"&gt;:credit_card&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
  &lt;span class="n"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="ss"&gt;:credit_card&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="ss"&gt;expire_year: &lt;/span&gt;&lt;span class="no"&gt;Time&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;zone&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;today&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;year&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="ss"&gt;expire_month: &lt;/span&gt;&lt;span class="mi"&gt;12&lt;/span&gt;
  &lt;span class="p"&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;travel_to&lt;/code&gt; で固定した時刻がSQLの &lt;code&gt;now()&lt;/code&gt; には反映されないために、テストとDBで時刻がずれていたケースもありました。&lt;code&gt;travel_to&lt;/code&gt; はRubyプロセス内の時刻を差し替えるだけなので、DBの &lt;code&gt;now()&lt;/code&gt; には効きません。これも月をまたいで初めて顕在化しました。&lt;/p&gt;

&lt;p&gt;時間の経過でテストの前提が崩れないようにすることが大切です。&lt;/p&gt;

&lt;h2 id="事例2-深夜0時ちょうどにのみ失敗するテスト"&gt;事例2: 深夜0時ちょうどにのみ失敗するテスト&lt;/h2&gt;

&lt;p&gt;夜間に自動作成されるPRだけなぜか時々CIが落ちる、ということがありました。落ちていたのはセールの適用判定に関するテストで、調査するとテストデータの時刻指定方法が原因でした。&lt;/p&gt;

&lt;p&gt;セールには開始時刻と終了時刻があります。factoryのデフォルトでは、開始時刻が「今日の00:00:00」に設定されていました。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="n"&gt;factory&lt;/span&gt; &lt;span class="ss"&gt;:time_discount&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
  &lt;span class="n"&gt;start_time&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="no"&gt;Time&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;current&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;beginning_of_day&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="n"&gt;end_time&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;hour&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;from_now&lt;/span&gt; &lt;span class="p"&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;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="n"&gt;let&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="ss"&gt;:time_discount&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
  &lt;span class="n"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="ss"&gt;:time_discount&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="ss"&gt;end_time: &lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;minutes&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ago&lt;/span&gt;
  &lt;span class="p"&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;ほとんどの時間帯では問題になりませんが、深夜00:00〜00:02の間にテストが実行されると&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;開始時刻: &lt;code&gt;Time.current.beginning_of_day&lt;/code&gt; → 今日の00:00:00&lt;/li&gt;
  &lt;li&gt;終了時刻: &lt;code&gt;2.minutes.ago&lt;/code&gt; → 昨日の23:58頃&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;と、終了時刻が開始時刻より前になり、セットアップ段階でバリデーションエラーが発生する状態になっていました。&lt;/p&gt;

&lt;p&gt;対処として、時刻の逆転が起きないよう、開始時刻も明示的に指定しました。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="n"&gt;let&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="ss"&gt;:time_discount&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
  &lt;span class="n"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="ss"&gt;:time_discount&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="ss"&gt;start_time: &lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;hour&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ago&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="ss"&gt;end_time: &lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;minutes&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ago&lt;/span&gt;
  &lt;span class="p"&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;/p&gt;

&lt;h2 id="事例3-保証のない順序に依存していたテスト"&gt;事例3: 保証のない順序に依存していたテスト&lt;/h2&gt;

&lt;p&gt;コレクションを返すAPIのテストで、特定の要素が含まれることを検証する際に &lt;code&gt;.first&lt;/code&gt; で先頭要素だけをチェックしていました。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="n"&gt;result&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;api_response&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;items&lt;/span&gt;

&lt;span class="n"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;result&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="nf"&gt;to&lt;/span&gt; &lt;span class="n"&gt;have_attributes&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="ss"&gt;color: &lt;/span&gt;&lt;span class="s2"&gt;"white"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;しかし、このAPIは返却順序を保証しておらず、&lt;code&gt;first&lt;/code&gt; で取得される要素が実行ごとに変わりうる状態になっていました。&lt;/p&gt;

&lt;p&gt;対処として、「先頭が一致すること」ではなく「目的の要素が含まれること」に修正しました。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="n"&gt;result&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;api_response&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;items&lt;/span&gt;

&lt;span class="n"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;result&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;to&lt;/span&gt; &lt;span class="kp"&gt;include&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;an_object_having_attributes&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="ss"&gt;color: &lt;/span&gt;&lt;span class="s2"&gt;"white"&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;first&lt;/code&gt; で検証するのは、flaky testの典型的な原因です。&lt;/p&gt;

&lt;h2 id="事例4-不正なテストデータが作られていたテスト"&gt;事例4: 不正なテストデータが作られていたテスト&lt;/h2&gt;

&lt;p&gt;あるモデルが1対多の関連を持ち、そのうち1件を &lt;code&gt;primary: true&lt;/code&gt; で代表データとして扱う構造がありました。代表データは &lt;code&gt;has_one&lt;/code&gt; で取得できるようになっています。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="n"&gt;has_one&lt;/span&gt; &lt;span class="ss"&gt;:primary_record&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="n"&gt;where&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="ss"&gt;primary: &lt;/span&gt;&lt;span class="kp"&gt;true&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt; &lt;span class="ss"&gt;class_name: &lt;/span&gt;&lt;span class="s2"&gt;"Record"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;factoryのデフォルトが &lt;code&gt;primary: true&lt;/code&gt; であり、2件作成すると両方がprimaryで作成されていました。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="n"&gt;let&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="ss"&gt;:parent&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="ss"&gt;:parent&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="n"&gt;let!&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="ss"&gt;:record_a&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="ss"&gt;:record&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="ss"&gt;parent: &lt;/span&gt;&lt;span class="n"&gt;parent&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="c1"&gt;# primary: true&lt;/span&gt;
&lt;span class="n"&gt;let!&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="ss"&gt;:record_b&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="ss"&gt;:record&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="ss"&gt;parent: &lt;/span&gt;&lt;span class="n"&gt;parent&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="c1"&gt;# primary: true&lt;/span&gt;

&lt;span class="n"&gt;it&lt;/span&gt; &lt;span class="s2"&gt;"正しいURLが組み立てられること"&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
  &lt;span class="n"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;parent&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;page_url&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;to&lt;/span&gt; &lt;span class="n"&gt;eq&lt;/span&gt; &lt;span class="s2"&gt;"https://example.com/records/&lt;/span&gt;&lt;span class="si"&gt;#{&lt;/span&gt;&lt;span class="n"&gt;record_a&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;id&lt;/span&gt;&lt;span class="si"&gt;}&lt;/span&gt;&lt;span class="s2"&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;primary_record&lt;/code&gt; を参照していた、URLを組み立てるメソッドのテストがflakyになっていました。&lt;code&gt;has_one&lt;/code&gt; は該当レコードが複数あってもエラーにはならず、いずれか1件を返すため、&lt;code&gt;record_b&lt;/code&gt; が返された場合にテストが落ちていました。&lt;/p&gt;

&lt;p&gt;2件目の作成時に &lt;code&gt;primary: false&lt;/code&gt; を指定することで解消しました。&lt;/p&gt;

&lt;p&gt;テストデータのセットアップでは、実環境では起こりえないようなデータを作ってしまわないよう注意が必要です。&lt;/p&gt;

&lt;h2 id="事例5-偶然の一致で失敗するテスト"&gt;事例5: 偶然の一致で失敗するテスト&lt;/h2&gt;

&lt;p&gt;SUZURIでは、Tシャツなどの物理商品に加えて、スマホ用壁紙画像などのデジタルコンテンツを販売することもできます。これらを横断的に取得するAPIがあり、そのテストで問題が発生しました。&lt;/p&gt;

&lt;p&gt;APIのレスポンスには順序保証がなく、かつ各エントリの属性を個別に検証する必要があったため、IDで目的のレコードを探していました。イメージとしては以下のようなコードです。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="n"&gt;let&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="ss"&gt;:product&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="ss"&gt;:product&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="n"&gt;let&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="ss"&gt;:digital_product&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="ss"&gt;:digital_product&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;before&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
  &lt;span class="n"&gt;register&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;product&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="n"&gt;register&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;digital_product&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;

&lt;span class="n"&gt;it&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
  &lt;span class="n"&gt;entries&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;api_response&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"entries"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;

  &lt;span class="n"&gt;product_entry&lt;/span&gt;         &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;entries&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;find&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt;&lt;span class="n"&gt;entry&lt;/span&gt;&lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="n"&gt;entry&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"id"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="n"&gt;product&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="nf"&gt;to_s&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="n"&gt;digital_product_entry&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;entries&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;find&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt;&lt;span class="n"&gt;entry&lt;/span&gt;&lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="n"&gt;entry&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"id"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="n"&gt;digital_product&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="nf"&gt;to_s&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="c1"&gt;# product専用の検証&lt;/span&gt;
  &lt;span class="n"&gt;verify_product_attributes&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;product_entry&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="c1"&gt;# digital_product専用の検証&lt;/span&gt;
  &lt;span class="n"&gt;verify_digital_product_attributes&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;digital_product_entry&lt;/span&gt;&lt;span class="p"&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;product&lt;/code&gt; と &lt;code&gt;digital_product&lt;/code&gt; は別テーブルであり、IDの採番は独立しています。テストの実行時に両者にたまたま同じIDが振られると、&lt;code&gt;find&lt;/code&gt; が誤った方にマッチしてしまい、属性の検証で失敗するという状況でした。&lt;/p&gt;

&lt;p&gt;対処として、IDに加えて型情報も含めて取得するようにしました。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="n"&gt;product_entry&lt;/span&gt;         &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;entries&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;find&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt;&lt;span class="n"&gt;entry&lt;/span&gt;&lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="n"&gt;entry&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"type"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="s2"&gt;"Product"&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="n"&gt;entry&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"id"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="n"&gt;product&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="nf"&gt;to_s&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="n"&gt;digital_product_entry&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;entries&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;find&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt;&lt;span class="n"&gt;entry&lt;/span&gt;&lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="n"&gt;entry&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"type"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="s2"&gt;"DigitalProduct"&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="n"&gt;entry&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"id"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="n"&gt;digital_product&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="nf"&gt;to_s&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;IDがユニークである範囲を意識する必要があります。&lt;/p&gt;

&lt;h2 id="番外編-そもそも実行されていなかったテスト"&gt;番外編: そもそも実行されていなかったテスト&lt;/h2&gt;

&lt;p&gt;flaky test調査の過程で発見した、「そもそも実行されていなかったテスト」の話です。&lt;/p&gt;

&lt;p&gt;有効なテストコードが書かれたあるテストファイルの名前が &lt;code&gt;_spec.rb&lt;/code&gt; で終わっておらず、RSpecの実行対象に含まれていませんでした。&lt;/p&gt;

&lt;p&gt;再発防止として、テストが記述されたRubyファイルが &lt;code&gt;_spec.rb&lt;/code&gt; で終わっていることをチェックする仕組みを導入しました。&lt;/p&gt;

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

&lt;p&gt;どの事例も、原因がわかってしまえば対処は簡単でした。手間がかかるのは、原因を突き止めるところです。今回、flaky testをまとめて対処できたのは、遭遇するたびにClaude Code等のAIにバックグラウンドで調査を任せていたことが大きいです。従来であれば「再実行したら通ったからいいか」と見過ごしがちだったものも、メインの作業と並行して対処を進められるようになりました。&lt;/p&gt;

&lt;p&gt;本記事で紹介した事例は比較的シンプルなものですが、中には複数の要因が重なり、原因の特定に大きく手間取ったケースもありました。その話は&lt;a href="/2026/04/15/flaky-test-investigation/"&gt;明日の記事&lt;/a&gt;で詳しく紹介します。&lt;/p&gt;
</content>
  </entry>
  <entry>
    <title>「技術で事業の成長曲線を変える」── 事業成長を軸に働くエンジニアがGMOペパボを選んだ理由</title>
    <link rel="alternate" href="https://tech.pepabo.com/2026/04/13/engineer-entry-article/"/>
    <id>https://tech.pepabo.com/2026/04/13/engineer-entry-article/</id>
    <published>2026-04-13T00:00:00+09:00</published>
    <updated>2026-05-04T00:07:16+00:00</updated>
    <author>
      <name>tokai</name>
    </author>
    <content type="html">&lt;p&gt;2026年3月、SREチームに新しいメンバーが加わりました。事業会社で約5年間、バックエンド開発からアーキテクチャ設計、開発リードまで幅広く経験してきたtokaiさん。技術力だけでなく「事業と数字に向き合う姿勢」を自身の核に据えるエンジニアがなぜ次の活躍の場としてGMOペパボを選んだのか、そのキャリア観はどのように形成されたのか。これまでの歩みとともにお話を伺いました。&lt;/p&gt;

&lt;hr /&gt;

&lt;h2 id="偶然から始まったエンジニア人生"&gt;偶然から始まったエンジニア人生&lt;/h2&gt;

&lt;p&gt;──エンジニアを目指そうと思ったきっかけを教えてください&lt;/p&gt;

&lt;p&gt;大学4年のとき、1年間休学して海外でインターンをしていました。オフショア企業で日本人のPMと現地エンジニアをつなぐブリッジのような役割を担っていたのですが、そこで初めてコードに触れたのがきっかけです。
もともと親族が建築会社を経営していたこともあり「ものづくり」への漠然とした憧れはずっとありました。プログラミングはそこに通じる感覚があって、一気にのめり込んでいきました。競技プログラミングにも触れていて、問題を解いていくゲーム性も相まって、どんどん面白くなっていった記憶があります。&lt;/p&gt;

&lt;h2 id="小さな組織で全部やる"&gt;小さな組織で、全部やる&lt;/h2&gt;

&lt;p&gt;──新卒の際、どのような軸（基準）で会社を選ばれたのですか？&lt;/p&gt;

&lt;p&gt;正直に言うと、当時業界軸ではあまり考えておらず、当時は事業ドメインへの関心もほとんどなくて、使っている技術スタックが面白そうだな、くらいの感覚で企業を見ていました。ただ「エンジニア組織が小さいところで、何でもやれる環境がいい」という軸は明確にありました。内定をいくつかいただいた中で、エンジニアが最も少ない会社を選んでいます。
実際、入社した企業は、当時エンジニアは20人に満たず、私は新卒エンジニアの第1期生でした。バックエンド担当として入りましたが、インフラもやればフロントも触る。必要なら事業部との折衝まで――とにかく自走するしかない環境でした。
最初の3年間は正直、自身の力不足もあって事業への手触り感はほとんどなかったです。ただ、とにかくいろんなことをやらせてもらえました。振り返れば、あの環境が今のエンジニアとしての土台になっています。&lt;/p&gt;

&lt;h2 id="転機になった事業の早期撤退"&gt;転機になった「事業の早期撤退」&lt;/h2&gt;

&lt;p&gt;──新卒として入社した企業には5年近く在籍されたと思うのですが、その中で印象的なエピソードはありますか？&lt;/p&gt;

&lt;p&gt;2年目に新規プロジェクトのアーキテクチャ設計からアプリケーション開発までゼロベースで任せてもらいました。途中から私がPMを兼務することになり、3年目には正式にPMへ職種を転身しました。何とかリリースまでこぎ着けたものの、運用開始からわずか4ヶ月で早期撤退という結果になりました。
投資対効果が低いと判断されたのが直接の原因です。何より辛かったのは、ユーザーや事業部の期待に応えられなかったこと、そして事業にも何のインパクトも残せなかったことでした。様々な機会をいただいた中でのこの結果は、私にとって非常に大きな挫折となりました。&lt;/p&gt;

&lt;h2 id="技術が好きだからこそ事業を見る"&gt;「技術が好きだからこそ、事業を見る」&lt;/h2&gt;

&lt;p&gt;──その後、考え方はどう変わりましたか？&lt;/p&gt;

&lt;p&gt;4年目に新しいプロジェクトへ異動したタイミングで、ちょうど入社してきたPMの方から事業と数字の大切さを徹底的に叩き込まれました。それがターニングポイントです。
誤解されがちですが、事業を見るというのは技術への追求を手放すことではないんです。やりたい技術を会社で実現するためには、意思決定者の承認が要る。承認を得るには投資対効果を示さなければならない。つまり事業目標や数字にきちんとヒットする提案ができてはじめて、チームがやりたい技術にも投資してもらえる。私はそういう環境を作るのがシニアエンジニアの役割だと思っています。
技術も事業も、どっちもやりたい。だからこそ事業の視点が必要なんです。&lt;/p&gt;

&lt;p&gt;&lt;img src="/blog/2026/04/13/engineer-entry-article/images/DSC2148.jpg" alt="インタビュー中のtokaiさん" /&gt;&lt;/p&gt;

&lt;h2 id="想定外の転職活動"&gt;想定外の転職活動&lt;/h2&gt;

&lt;p&gt;──転職しようと考えたきっかけ、そして転職活動はどのように進められましたか？&lt;/p&gt;

&lt;p&gt;入社して4,5年経ったときに、プロダクト開発そのものにはやりがいを感じていたものの、自身の技術が事業や数字にどれだけインパクトを与えられているのか――その実感をより強く得られる環境に身を置きたいと考えるようになったのが転職のきっかけでした。
そのため、今回の転職活動の軸は2つでした。&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;「技術力が事業成長や数字に直接つながる実感を得られる環境か」&lt;/li&gt;
  &lt;li&gt;「これまでの経験がその会社にとって価値になるか」&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;私はお客さんではないので、これまでの経験を活かしてしっかりと成果を出せるかどうかも重要な判断基準でした。
ありがたいことに多くの企業様からお声がけいただいたのですが、前職の最終月が丸々有休だったこともあり、1社ずつ会社のサイト・IR情報・テックブログを読み込んでじっくり検討させていただきました。特にこだわったのは、「結果や成果を定量的に把握しようとしているか」どうかでした。&lt;/p&gt;

&lt;h2 id="ペパボを選んだ理由"&gt;ペパボを選んだ理由&lt;/h2&gt;

&lt;p&gt;──最終的にペパボに決めた理由は何ですか？&lt;/p&gt;

&lt;p&gt;選考プロセスでの対応スピードが圧倒的に速かったことは印象に残っています。とにかくレスポンスが早く、それだけでもこの会社は候補者に向き合ってくれていると感じました。
加えて、面談の中で「事業や数字を大切にするエンジニアが欲しい」という話があり、私の軸と一致したのも大きかったです。内定前には配属チーム以外の事業部CTOの方ともお話しする機会をいただき、組織全体の解像度が上がったことで最終的な決断に至りました。&lt;/p&gt;

&lt;h2 id="入社後のギャップ"&gt;入社後のギャップ&lt;/h2&gt;

&lt;p&gt;──実際に入社してみていかがですか？また、今後やっていきたいことがあれば教えてください。&lt;/p&gt;

&lt;p&gt;転職前とのギャップはまったくありません。これまで10年、20年と継続してきたシステムに携わったことは無かったので、この規模感やこれまで関わられてきた事業部、エンジニアのみなさまには素直にリスペクトを持っています。&lt;/p&gt;

&lt;p&gt;SREとしての私の役割は、技術横断で信頼性と経済合理性のバランスを取り、無駄の削減やインフラコストの最適化を通じて利益率を向上させることです。つまり、事業の土台を技術で強くしていくことであり、そこに大きなやりがいを感じています。同じ部門のパートナーやサービスを運営する事業部のパートナーともコミュニケーションをスムーズにとることができています。
また「このチームにあまりいなかったタイプ」と言っていただいているので、事業と数字の目線、そしてそこへの推進力をチームやエンジニア組織全体に広げていくことも、私に期待されている役割だと捉えていますし、どんどんアウトプットしてやっていきたいと思っています。&lt;/p&gt;

&lt;p&gt;&lt;img src="/blog/2026/04/13/engineer-entry-article/images/DSC2194.jpg" alt="tokaiさん" /&gt;&lt;/p&gt;
</content>
  </entry>
  <entry>
    <title>シニアエンジニア所信表明 — AIを使うから、AIに使ってもらうへ</title>
    <link rel="alternate" href="https://tech.pepabo.com/2026/04/10/senior-engineer-watasan/"/>
    <id>https://tech.pepabo.com/2026/04/10/senior-engineer-watasan/</id>
    <published>2026-04-10T00:00:00+09:00</published>
    <updated>2026-05-04T00:07:16+00:00</updated>
    <author>
      <name>watasan</name>
    </author>
    <content type="html">&lt;p&gt;SUZURI・minne事業部の渡辺(&lt;a href="https://x.com/ae14watanabe"&gt;@ae14watanabe&lt;/a&gt;)です。2026年4月にシニアエンジニアとなりました。自己紹介を兼ねてこれまでの自分の取り組みを簡単に紹介します。その上で、これから何をしていくのかを述べ、所信表明とします。&lt;/p&gt;

&lt;h2 id="これまでサービスがaiを使う"&gt;これまで：サービスがAIを使う&lt;/h2&gt;

&lt;p&gt;私は自身の専門領域を「AIが関わるサービスの開発」とし、これまで&lt;a href="https://suzuri.jp"&gt;SUZURI byGMOペパボ&lt;/a&gt;において、AI（LLMをはじめとする機械学習モデル）を導入した機能の開発を複数行ってきました。具体的な取り組みについては&lt;a href="https://speakerdeck.com/ae14watanabe/weve-got-to-make-this-web-service-better-with-ai-trials-and-errors-at-suzuri-by-gmo-pepabo"&gt;こちらの資料&lt;/a&gt;にまとめていますが、一例を挙げると、商品の規約違反チェックをAIで自動化するプロジェクトをリードしてきました。&lt;/p&gt;

&lt;p&gt;AIを導入した機能開発と、そうでない開発の根本的な違いは、不確実性の有無にあります。従来のソフトウェアは書いた通りに動きます。バグがなければ期待通りの結果を決定的に返します。一方でAIは、入力のわずかな違いで出力が変わりうる、複雑な判断を求められるほど完璧な結果は期待できない、といった性質があり、不確実性が常につきまといます。この不確実性をハンドリングすることが自分の仕事だと考えています。&lt;/p&gt;

&lt;p&gt;ハンドリングとしてやってきたことは大きく2つあります。1つ目はAIへの入力を設計し、評価し、改善するサイクルを回すことです。規約違反チェックの例でいえば、違反ジャンルを網羅したデータセットを構築してAIの判断を定量評価しました。さらに、CSチームが現場で見つけた誤判定のフィードバックも踏まえて改善サイクルを回してきました。2つ目は、AIの誤りを許容できるフローの構築です。AIは間違える前提で、ユーザ・サービス・運営者それぞれのレイヤーで誤りを吸収できる仕組みを設計してきました。&lt;/p&gt;

&lt;h2 id="これからaiにサービスを使ってもらう"&gt;これから：AIにサービスを使ってもらう&lt;/h2&gt;

&lt;p&gt;しかし最近、自分が「AIが関わるサービス」をかなり狭く捉えていたのではないか、と思うようになりました。&lt;/p&gt;

&lt;p&gt;自分がやってきたのは「サービスがAIを使うこと」でした。構造としては「ユーザ ↔ サービス ↔ AI」——サービスがAIを呼び出し、その結果をサービスが受け取ってユーザに届ける形です。&lt;/p&gt;

&lt;p&gt;&lt;img src="/blog/2026/04/10/senior-engineer-watasan/user-service-ai.jpeg" alt="ユーザ ↔ サービス ↔ AI" /&gt;&lt;/p&gt;

&lt;p&gt;一方で、もうひとつの構造があります。「ユーザ ↔ AI ↔ サービス」——AIエージェントがMCPやCLIを通じてサービスをツールとして使う形です。&lt;/p&gt;

&lt;p&gt;&lt;img src="/blog/2026/04/10/senior-engineer-watasan/user-ai-service.jpeg" alt="ユーザ ↔ AI ↔ サービス" /&gt;&lt;/p&gt;

&lt;p&gt;たとえば今、Claude Codeのようなコーディングエージェントは、CLIやMCPを通じてさまざまなサービスを日常的に使っています。こういったエージェントにサービスを使ってもらうことも、「AIが関わるサービスの開発」です。エージェントが単一のタスクにとどまらず複数のサービスを組み合わせて作業を遂行するようになりつつある今、こちらの構造の重要性はより増していくと考えています。&lt;/p&gt;

&lt;p&gt;前者と後者の構造では、不確実性のハンドリングの手段が変わります。前者ではAIの出力をサービス側で受け取れるため、前述の誤りを含む想定でのフロー構築など、出力側のハンドリングを行うことができました。これに対して後者では、AIの出力はユーザに向かい、サービス側からは見えません。出力を制御できないなら、入力の設計がハンドリングのほぼ全てになります。&lt;/p&gt;

&lt;p&gt;だからこそ、ツールとしてのレスポンスやスキーマの設計が重要となります。エージェントに実際にツールを使わせ、どう振る舞うかを観測し、改善していく。SUZURI byGMOペパボでやってきたことと地続きですが、まだ誰も正解を知らない領域だと感じています。これまでやってきたことをより洗練させてやっていかねばと思っています。&lt;/p&gt;

&lt;p&gt;ペパボでは、&lt;a href="https://pepabo.com/news/press/202603091300/"&gt;カラーミーショップのAIコネクター&lt;/a&gt;や&lt;a href="https://pepabo.com/news/information/202603311100/"&gt;ムームードメインのMCPサーバー&lt;/a&gt;など、既存サービスにおけるこの「ユーザ ↔ AI ↔ サービス」構造への取り組みがすでに始まっています。これらは既存サービスの延長線上にある取り組みで、もちろん重要です。しかしこれからは、この構造をネイティブとする新しいサービスに挑戦することで、既存サービスの延長線上では届かない価値を届けられると考えています。そこを、自分が先頭で実践していく。これがシニアエンジニアとしての自分の所信です。&lt;/p&gt;
</content>
  </entry>
  <entry>
    <title>シニアエンジニア所信表明 - 不変条件を見極めて、システムを組み替える</title>
    <link rel="alternate" href="https://tech.pepabo.com/2026/04/10/senior-furudono/"/>
    <id>https://tech.pepabo.com/2026/04/10/senior-furudono/</id>
    <published>2026-04-10T00:00:00+09:00</published>
    <updated>2026-05-04T00:07:16+00:00</updated>
    <author>
      <name>donokun</name>
    </author>
    <content type="html">&lt;p&gt;EC事業部の古殿（&lt;a href="https://x.com/furudono2"&gt;@furudono2&lt;/a&gt;）です。
ペパボでシニアエンジニアに昇格しました。この記事では、私がどのような関心を持ち、今後どのように取り組んでいくかを紹介します。&lt;/p&gt;

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

&lt;p&gt;学生の頃はプログラミング言語の意味論を研究していました。どのようなプログラミング言語の定義をすると、どのような不変条件がプログラムに生まれ、プログラミングを頑強にするかを議論してきました。この頃の関心と今の仕事には共通するものがあると考えています。どちらも、あるシステムの上で期待される営みを見定め、それがうまく進むための制約を設計する仕事です。私はこの種の問題を解くことに楽しさと価値を感じています。&lt;/p&gt;

&lt;p&gt;2023年に入社してからは、この関心に沿った仕事をしてきました。新規サービスの立ち上げ、サービス間で共通するID・決済機能の基盤設計、大規模メールリレーシステムの移設など、いずれも特定のレイヤに閉じず横断的に課題を捉える仕事です。議論の対象は技術の話からそれを用いたソフトウェアや、ソフトウェアを組み合わせて提供するサービスへと広がってきました。&lt;/p&gt;

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

&lt;p&gt;EC事業部のシステムには、長年の積み重ねによる制約がいくつかあります。たとえばサービスを支える複数のロール（管理画面とAPI）の責務境界が歴史的に曖昧になっていたり、古い文字コードへの依存が広範に残っていたりします。こうした制約は、提供できる機能の幅や日々の開発速度に影響を与えています。&lt;/p&gt;

&lt;p&gt;これらが今日まで解きほぐされずに残っているのには理由があると考えています。何が本当に守らなければならない制約なのかを見抜くことは難しく、見抜いた上でそれを実際のコードやデータに反映させるには膨大な労力が要るからです。過去に取り組んだ人がいなかったのではなく、取り組むコストが割に合いづらい性質の課題だったのだと考えています。&lt;/p&gt;

&lt;p&gt;生成AIエージェントの登場によって、広範囲にわたるコードやデータの変更、あるいは依存関係や情報の欠落を洗い出す調査といった、かつて膨大な手作業を要した仕事を、現実的なコストで進められるようになってきたのではないかと考えています。もっとも、AIを使えば何でも解けるわけではありません。システムに何が本当に守らなければならない不変条件があるのかは、まだ人間が見抜く必要があるように感じています。そして、その不変条件を満たし続けるようにシステムの変更を組み立てていく仕事があってはじめて、AIの力を安全に借りられるようになります。制約が曖昧なまま大きな力を走らせても、壊れ方が速くなるだけです。&lt;/p&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;半期ごとの評価制度と同時期に行われ、エンジニア自身の立候補と面談を経て、通過すると4等級以上の専門職に昇格します。シニア・プリンシパルエンジニア、プリンシパルエンジニア、シニアエンジニアの3つの職位があり、対象の職位のエンジニアは各サービスや会社全体の技術的な問題解決、技術力の底上げ、事業価値の創出にコミットする業務を行います。&lt;/p&gt;

  &lt;p&gt;— &lt;a href="https://tech.pepabo.com/engineers/"&gt;ペパボのエンジニア&lt;/a&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;どのような人がシニアなどの専門職にふさわしいかは、定性的に定められた基準の他に、過去にどのような振る舞いをした人が専門職として認められてきたかをもとに判断されます。今回私はシニアエンジニアとして立候補し、面談を経て昇格しました。&lt;/p&gt;

&lt;p&gt;この記事が、ペパボの職位制度を知っていただくための一つの例として役立てば幸いです。&lt;/p&gt;
</content>
  </entry>
</feed>