feed.rss

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>Pepabo Tech Portal</title>
    <link>https://tech.pepabo.com/</link>
    <description>GMOペパボのエンジニア・デザイナーによる技術情報のポータルサイト</description>
    <atom:link href="https://tech.pepabo.com/feed.rss" rel="self" type="application/rss+xml"/>
    <pubDate>Fri, 24 Apr 2026 00:00:00 +0900</pubDate>
    <item>
      <title>後付け可能な認証を NextAuth で設計する — ログイン機構が決まらないまま、ログイン前提のプロダクトを作った話</title>
      <link>https://tech.pepabo.com/2026/04/24/nextauth-mock-auth-design/</link>
      <guid>https://tech.pepabo.com/2026/04/24/nextauth-mock-auth-design/</guid>
      <pubDate>Fri, 24 Apr 2026 00:00:00 +0900</pubDate>
      <description>&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;
</description>
    </item>
    <item>
      <title>プロンプトのtypoをCIで弾く ── TypeScriptの型でAIへの指示を守る</title>
      <link>https://tech.pepabo.com/2026/04/17/typescript-type-safe-prompt/</link>
      <guid>https://tech.pepabo.com/2026/04/17/typescript-type-safe-prompt/</guid>
      <pubDate>Fri, 17 Apr 2026 00:00:00 +0900</pubDate>
      <description>&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;
</description>
    </item>
    <item>
      <title>flaky testの原因は、無関係なファイルの1行にあった</title>
      <link>https://tech.pepabo.com/2026/04/15/flaky-test-investigation/</link>
      <guid>https://tech.pepabo.com/2026/04/15/flaky-test-investigation/</guid>
      <pubDate>Wed, 15 Apr 2026 00:00:00 +0900</pubDate>
      <description>&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;
</description>
    </item>
    <item>
      <title>シニアエンジニア所信表明 — レバレッジと横断性で事業やサービスが向かうべき先に未来を作る</title>
      <link>https://tech.pepabo.com/2026/04/15/senior-engineer-haruotsu/</link>
      <guid>https://tech.pepabo.com/2026/04/15/senior-engineer-haruotsu/</guid>
      <pubDate>Wed, 15 Apr 2026 00:00:00 +0900</pubDate>
      <description>&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;
</description>
    </item>
    <item>
      <title>SUZURIで遭遇したflaky testの事例集</title>
      <link>https://tech.pepabo.com/2026/04/14/flaky-tests/</link>
      <guid>https://tech.pepabo.com/2026/04/14/flaky-tests/</guid>
      <pubDate>Tue, 14 Apr 2026 00:00:00 +0900</pubDate>
      <description>&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;
</description>
    </item>
    <item>
      <title>「技術で事業の成長曲線を変える」── 事業成長を軸に働くエンジニアがGMOペパボを選んだ理由</title>
      <link>https://tech.pepabo.com/2026/04/13/engineer-entry-article/</link>
      <guid>https://tech.pepabo.com/2026/04/13/engineer-entry-article/</guid>
      <pubDate>Mon, 13 Apr 2026 00:00:00 +0900</pubDate>
      <description>&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;
</description>
    </item>
    <item>
      <title>シニアエンジニア所信表明 — AIを使うから、AIに使ってもらうへ</title>
      <link>https://tech.pepabo.com/2026/04/10/senior-engineer-watasan/</link>
      <guid>https://tech.pepabo.com/2026/04/10/senior-engineer-watasan/</guid>
      <pubDate>Fri, 10 Apr 2026 00:00:00 +0900</pubDate>
      <description>&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;
</description>
    </item>
    <item>
      <title>シニアエンジニア所信表明 - 不変条件を見極めて、システムを組み替える</title>
      <link>https://tech.pepabo.com/2026/04/10/senior-furudono/</link>
      <guid>https://tech.pepabo.com/2026/04/10/senior-furudono/</guid>
      <pubDate>Fri, 10 Apr 2026 00:00:00 +0900</pubDate>
      <description>&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;
</description>
    </item>
    <item>
      <title>minneリワードを支えるマルチクラウドアーキテクチャ</title>
      <link>https://tech.pepabo.com/2026/04/10/minne-mission-reward-architecture/</link>
      <guid>https://tech.pepabo.com/2026/04/10/minne-mission-reward-architecture/</guid>
      <pubDate>Fri, 10 Apr 2026 00:00:00 +0900</pubDate>
      <description>&lt;h2 id="はじめに"&gt;はじめに&lt;/h2&gt;

&lt;p&gt;minneでは、アプリでミッションを達成したり、広告を見ることでminneコインが無料で貯まる機能「minneリワード」をリリースしました。
minneリワードには昨年リリースされた作家・ブランドへの応援ミッションの他に、「アプリを起動する」「注目の特集をチェック」といったデイリーミッション、応援・購入回数に応じた累積ミッションが用意されています。ミッションを達成し動画広告を視聴すると、minneコインが付与される仕組みです。&lt;/p&gt;

&lt;blockquote class="twitter-tweet" data-media-max-width="560"&gt;&lt;p lang="ja" dir="ltr"&gt;【予告】お買い物がちょっとお得になる「minneリワード」が3月に登場✨&lt;br /&gt;&lt;br /&gt;アプリでミッションを達成し、広告を見るとコインがもらえます🎁&lt;br /&gt;貯めたコインは、ポイントに交換してお買い物に使えます！… &lt;a href="https://t.co/xp955ifPQ9"&gt;pic.twitter.com/xp955ifPQ9&lt;/a&gt;&lt;/p&gt;&amp;mdash; minne byGMOペパボ（ミンネ） (@minnecom) &lt;a href="https://twitter.com/minnecom/status/2024680460190617737?ref_src=twsrc%5Etfw"&gt;February 20, 2026&lt;/a&gt;&lt;/blockquote&gt;
&lt;script async="" src="https://platform.twitter.com/widgets.js" charset="utf-8"&gt;&lt;/script&gt;

&lt;p&gt;本記事では、マルチクラウド構成でのゲーミフィケーション機能を実現するにあたっての設計判断と、実際に運用する上で直面した課題・解決策を紹介します。&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="#minneリワードの全体像" id="markdown-toc-minneリワードの全体像"&gt;minneリワードの全体像&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#クライアント起点の実績集計を採用しなかった理由" id="markdown-toc-クライアント起点の実績集計を採用しなかった理由"&gt;クライアント起点の実績集計を採用しなかった理由&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#なぜマルチクラウドになったのか" id="markdown-toc-なぜマルチクラウドになったのか"&gt;なぜマルチクラウドになったのか&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#設計判断のポイント" id="markdown-toc-設計判断のポイント"&gt;設計判断のポイント&lt;/a&gt;    &lt;ol&gt;
      &lt;li&gt;&lt;a href="#1-firestoreのドキュメント構造ユーザー起点-vs-日付起点" id="markdown-toc-1-firestoreのドキュメント構造ユーザー起点-vs-日付起点"&gt;1. Firestoreのドキュメント構造：ユーザー起点 vs 日付起点&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#2-dynamodb-gsiシャーディングによるホットパーティション回避" id="markdown-toc-2-dynamodb-gsiシャーディングによるホットパーティション回避"&gt;2. DynamoDB GSIシャーディングによるホットパーティション回避&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#3-sqsを介した非同期書き込み" id="markdown-toc-3-sqsを介した非同期書き込み"&gt;3. SQSを介した非同期書き込み&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#4-2フェーズコイン付与による不正防止" id="markdown-toc-4-2フェーズコイン付与による不正防止"&gt;4. 2フェーズコイン付与による不正防止&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href="#5-graphqlにおけるインターフェース分離パターン" id="markdown-toc-5-graphqlにおけるインターフェース分離パターン"&gt;5. GraphQLにおけるインターフェース分離パターン&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="minneリワードの全体像"&gt;minneリワードの全体像&lt;/h2&gt;

&lt;p&gt;minneリワードは、大きく二種類のミッションで構成されています。&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;デイリーミッション&lt;/strong&gt;: 毎日リセットされ、「アプリを起動する」「注目の特集をチェック」といったタスクをこなすと達成されるミッション&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;累積ミッション&lt;/strong&gt;: 「作品を10回購入する」「応援スタンプを10回送る」のように、長期的な利用で達成されるミッション&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;ミッション達成後にユーザーが動画広告を視聴すると、minneコインが付与されます。このコインはminneでのお買い物に利用できるminneポイントに変換することができます。&lt;/p&gt;

&lt;p&gt;全体の処理は大きく4つのフェーズに分かれます。&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;ミッション進捗の記録&lt;/strong&gt;: ユーザーの行動ログをGC側で非同期にFirestoreへ記録&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;ミッション一覧の表示&lt;/strong&gt;: GraphQLクエリでFirestoreから進捗を取得しクライアントに返却&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;報酬の受け取り&lt;/strong&gt;: 動画広告視聴後、AWS SQS経由でDynamoDBに達成の記録を作成&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;コインの確定&lt;/strong&gt;: バッチで広告配信元の視聴データと突合し、minneコインを付与&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;&lt;img src="/blog/2026/04/10/minne-mission-reward-architecture/images/sequence.png" alt="minneリワードの処理フロー" /&gt;&lt;/p&gt;

&lt;h2 id="クライアント起点の実績集計を採用しなかった理由"&gt;クライアント起点の実績集計を採用しなかった理由&lt;/h2&gt;

&lt;p&gt;当初、ミッションの進捗記録はクライアント（iOS/Android）起点で行う設計を検討していました。具体的には、ミッション達成条件を満たす行動が発生したタイミングで、クライアントからGraphQL APIを呼び出して実績をインクリメントする方式です。&lt;/p&gt;

&lt;p&gt;しかし、この方式では&lt;strong&gt;ミッションを新たに追加するたびに、そのミッションの達成導線となる画面にAPIコールを仕込むクライアント側の改修が必要&lt;/strong&gt;になります。例えば「特集から作品を見る」ミッションを追加するなら特集画面に、「新着作品を確認する」ミッションを追加するなら新着一覧画面に、それぞれAPI呼び出しのコードを追加してアプリをリリースしなければなりません。&lt;/p&gt;

&lt;p&gt;minneリワードは今後もミッション種別を柔軟に追加・変更していきたい機能です。ミッションの追加のたびにクライアントの改修とアプリリリースが必要になる構成では、その機動性が大きく損なわれてしまいます。&lt;/p&gt;

&lt;p&gt;この課題を踏まえて、&lt;strong&gt;実績集計をバックエンド側に閉じる&lt;/strong&gt;方針に転換しました。それが次に説明するマルチクラウド構成の採用につながっています。&lt;/p&gt;

&lt;h2 id="なぜマルチクラウドになったのか"&gt;なぜマルチクラウドになったのか&lt;/h2&gt;

&lt;p&gt;minneのメインアプリケーションはAWS上のRuby on Railsで動作していますが、ミッション報酬機能ではGoogle Cloud（以下、GC）のFirestoreやCloud Functionsも組み合わせたマルチクラウド構成を採用しました。&lt;/p&gt;

&lt;p&gt;minneではユーザーの行動ログを &lt;code&gt;Railsアプリケーション → fluentd → fluentd（aggregator） → Cloud Pub/Sub&lt;/code&gt; のパイプラインで収集しています。このCloud Pub/Subに対してBigQueryへの蓄積用とCloud Functions用の2つのサブスクリプションを設定し、Cloud Functionsでミッション進捗をFirestoreに書き込む構成にしたことで、&lt;strong&gt;メインアプリケーションへの変更をほぼゼロ&lt;/strong&gt;にしながらデイリーミッションの進捗記録を実現しました。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;[ユーザー行動]
    ↓
Railsアプリケーション → fluentd → fluentd（aggregator） → Cloud Pub/Sub → BigQuery
                                                               ↓ (subscription)
                                                         Cloud Functions
                                                               ↓
                                                           Firestore
                                                      (デイリーミッション進捗)
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;この設計には2つの大きなメリットがあります。まず、既存のRailsアプリケーションにミッション進捗記録のためのコードを追加する必要がなく、新機能のリリースが既存機能の安定性に影響を与えるリスクを最小限に抑えられます。さらに重要なのは、&lt;strong&gt;新しいミッションを追加する際にiOS/Androidのクライアント側の改修がほとんど不要&lt;/strong&gt;になる点です。ミッションの実績集計はバックエンド側で完結するため、ミッション種別の追加はサーバーサイドの設定変更で対応でき、クライアントアプリのリリースサイクルに縛られません。&lt;/p&gt;

&lt;h2 id="設計判断のポイント"&gt;設計判断のポイント&lt;/h2&gt;

&lt;h3 id="1-firestoreのドキュメント構造ユーザー起点-vs-日付起点"&gt;1. Firestoreのドキュメント構造：ユーザー起点 vs 日付起点&lt;/h3&gt;

&lt;p&gt;デイリーミッションの進捗をFirestoreに格納する際、2つの構造を検討しました。&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;候補A：ユーザー起点（採用）&lt;/strong&gt;&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;missions/{user_id}/dailyProgress/{YYYYMMDD}
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;候補B：日付起点（不採用）&lt;/strong&gt;&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;dailyMissions/{date}/{user_id}
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;候補Bは日別の集計に便利ですが、&lt;strong&gt;同じ日付ドキュメント配下に全ユーザーの書き込みが集中&lt;/strong&gt;します。Firestoreには&lt;a href="https://firebase.google.com/docs/firestore/best-practices?hl=ja#index_exemptions"&gt;書き込み数の制限&lt;/a&gt;があり、キャンペーン時などにDAUが跳ね上がるとボトルネックになり得ます。候補Aのユーザー起点であれば、各ユーザーのドキュメントへの書き込みが自然に分散されるため、こちらを採用しました。&lt;/p&gt;

&lt;h3 id="2-dynamodb-gsiシャーディングによるホットパーティション回避"&gt;2. DynamoDB GSIシャーディングによるホットパーティション回避&lt;/h3&gt;

&lt;p&gt;ミッションの達成状態はDynamoDBに格納しています。DynamoDBではパーティションキーを指定して効率的にデータを取得するQueryが基本であり、パーティションキーの設計がパフォーマンスを左右します。DynamoDBの基礎的な設計の考え方については、以前のテックブログ記事「&lt;a href="https://developers.gmo.jp/technology/77858/"&gt;DynamoDB設計で痛い目にあった話 – RDB脳から抜け出すための実践ガイド&lt;/a&gt;」で紹介していますので、あわせてご覧ください。&lt;/p&gt;

&lt;p&gt;今回、「特定日にミッションを達成したユーザー一覧」を取得するためのGSI（Global Secondary Index）で、ホットパーティション問題が発生し得ます。&lt;/p&gt;

&lt;p&gt;例えば、GSIのパーティションキーを &lt;code&gt;acquired_at_date&lt;/code&gt;（日付）にすると、全ユーザーの書き込みがその日の1パーティションに集中してしまいます。&lt;/p&gt;

&lt;p&gt;これを回避するため、パーティションキーに&lt;strong&gt;シャードサフィックス&lt;/strong&gt;を付与しました。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;パーティションキー: {YYYY-MM-DD}#{user_id % 10}
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;&lt;code&gt;user_id % 10&lt;/code&gt; で10個のシャードに分散させることで、1パーティションあたりの書き込み負荷を1/10に軽減しています。読み取り時は10シャード分をScatterGatherで取得する必要がありますが、日次バッチ処理でしか使わないため許容範囲です。&lt;/p&gt;

&lt;h3 id="3-sqsを介した非同期書き込み"&gt;3. SQSを介した非同期書き込み&lt;/h3&gt;

&lt;p&gt;DynamoDBへの書き込みは、Railsアプリケーションから直接行うのではなく、&lt;strong&gt;SQSキューを経由してLambdaで処理&lt;/strong&gt;する構成にしました。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;[Rails] → SQS → Lambda → DynamoDB
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;これは既存の応援スタンプ機能で実績のあるパターンを踏襲したものです。メリットは以下のとおりです。&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;Railsのリクエスト処理とDynamoDBの書き込みを分離し、レイテンシのスパイクを防ぐ&lt;/li&gt;
  &lt;li&gt;DynamoDBのスロットリングが発生してもSQSがバッファとして機能し、リトライが自動で行われる&lt;/li&gt;
  &lt;li&gt;ミッション達成時のトラフィックスパイクからメインアプリケーションを保護する&lt;/li&gt;
&lt;/ul&gt;

&lt;h3 id="4-2フェーズコイン付与による不正防止"&gt;4. 2フェーズコイン付与による不正防止&lt;/h3&gt;

&lt;p&gt;コインの付与は、即時に仮付与→翌日に本付与という2フェーズで行っています。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;[ミッション達成 + 動画広告視聴]
    ↓
DynamoDB に PENDING 状態で記録（仮付与）
    ↓ (翌日 18:00 JST)
広告配信元から取得した広告視聴レポート（CSV）と突合
    ↓
一致 → コイン付与（本付与）
不一致 → 付与をスキップ
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;動画広告の視聴完了をクライアント側の報告だけで信用すると、不正にコインを取得される可能性があります。広告プラットフォーム側が独立に生成するCSVレポートと突合することで、広告が実際に視聴されたことを第三者データで検証しています。&lt;/p&gt;

&lt;p&gt;この突合処理はAWS Step Functionsでオーケストレーションしており、CSV取得→突合→コイン付与という一連のバッチ処理を管理しています。&lt;/p&gt;

&lt;h3 id="5-graphqlにおけるインターフェース分離パターン"&gt;5. GraphQLにおけるインターフェース分離パターン&lt;/h3&gt;

&lt;p&gt;ミッション情報のGraphQLスキーマでは、認証状態に応じて返すフィールドを変えるために&lt;code&gt;Interface + Type&lt;/code&gt;の分離パターンを採用しました。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight graphql"&gt;&lt;code&gt;&lt;span class="k"&gt;interface&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="n"&gt;Mission&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="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nb"&gt;ID&lt;/span&gt;&lt;span class="p"&gt;!&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="n"&gt;title&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nb"&gt;String&lt;/span&gt;&lt;span class="p"&gt;!&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="n"&gt;description&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nb"&gt;String&lt;/span&gt;&lt;span class="p"&gt;!&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="n"&gt;rewardCoins&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nb"&gt;Int&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="k"&gt;type&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="n"&gt;OwnMission&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="k"&gt;implements&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="n"&gt;Mission&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="c"&gt;# Missionの全フィールド + 進捗情報&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="n"&gt;currentCount&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nb"&gt;Int&lt;/span&gt;&lt;span class="p"&gt;!&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="n"&gt;MissionStatus&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="k"&gt;type&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="n"&gt;GuestMission&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="k"&gt;implements&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="n"&gt;Mission&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="c"&gt;# Missionの定義情報のみ&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;p&gt;クライアント側はインラインフラグメントで認証時だけ進捗情報を取得できます。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight graphql"&gt;&lt;code&gt;&lt;span class="k"&gt;query&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="n"&gt;missions&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="k"&gt;on&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="n"&gt;OwnMission&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="n"&gt;currentCount&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="n"&gt;status&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;p&gt;フィールドレベルの認可ディレクティブ（&lt;code&gt;@auth&lt;/code&gt; など）を使う方法も検討しましたが、型レベルで分離するこのパターンを採用しました。理由は以下のとおりです。&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;要件との整合&lt;/strong&gt;: ログインしていないユーザーにもミッション一覧は見せたい（認知→ログイン促進）ため、認証状態によって返す情報の粒度を明確に分けられる&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;フィールド乖離への耐性&lt;/strong&gt;: 今後ログイン・非ログインで必要なフィールドの差が広がっていくことが想定される中、型が分かれていれば各型に独立してフィールドを追加でき、&lt;code&gt;@auth&lt;/code&gt; ディレクティブの付け忘れといった事故も起きない&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;クライアント側の型安全性&lt;/strong&gt;: インラインフラグメントにより、クライアントのコード生成で &lt;code&gt;OwnMission&lt;/code&gt; と &lt;code&gt;GuestMission&lt;/code&gt; が別の型として扱われるため、認証状態に応じたハンドリングがコンパイル時に保証される&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id="累積ミッションの設計新しいデータストアを作らない判断"&gt;累積ミッションの設計：新しいデータストアを作らない判断&lt;/h2&gt;

&lt;p&gt;累積ミッション（購入回数、応援スタンプ送信回数）については、デイリーミッションのようにFirestoreに進捗を記録する方式を&lt;strong&gt;あえて採用しませんでした&lt;/strong&gt;。&lt;/p&gt;

&lt;p&gt;代わりに、既存のデータソースを直接参照しています。&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;購入回数&lt;/strong&gt;: RDBのテーブルからDISTINCTカウント&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;応援スタンプ回数&lt;/strong&gt;: Lambda経由でDynamoDBの応援スタンプデータを集計&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;ここでのポイントは、&lt;strong&gt;データの出自に応じてストアを使い分ける&lt;/strong&gt;という考え方です。&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;デイリーミッションの進捗は、行動ログとしてフローで流れてくるデータをPub/Sub経由でFirestoreに集約する設計が自然&lt;/li&gt;
  &lt;li&gt;購入回数はすでにRDBのテーブルに蓄積されているため、そこから集計すればよい&lt;/li&gt;
  &lt;li&gt;応援スタンプ回数もDynamoDBにレコードが溜まっているため、そこから集計すればよい&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;つまり、既存のデータストアにすでに集計可能な形でデータが存在しているなら、わざわざFirestoreに二重に持つ必要はありません。もちろん処理の統一性を優先して、累積ミッションの進捗もFirestoreにインポートして管理することも考えましたが、SSoTの原則から今回はそれぞれ既存のデータを参照する形式を採用しました。&lt;/p&gt;

&lt;h2 id="見積もりと開発体制"&gt;見積もりと開発体制&lt;/h2&gt;

&lt;p&gt;本機能は、インフラ・API・Lambdaを2名、iOS・Androidをそれぞれ1名ずつの&lt;strong&gt;計4名体制で約3〜4週間&lt;/strong&gt;で実装しました。&lt;/p&gt;

&lt;p&gt;行動ログベースの進捗記録をGC側に寄せ、実績の集計をバックエンドに閉じたことで、ミッションの追加時にクライアント（iOS/Android）側の工数がほとんどかかりません。ミッション種別のスケーラビリティを確保できた点が、この構成の大きな成果です。&lt;/p&gt;

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

&lt;p&gt;ミッション報酬機能の開発を通じて得た学びをまとめます。&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;実績集計をバックエンドに閉じたことでミッション追加がスケーラブルに&lt;/strong&gt;: 行動ログベースの進捗記録はGC側で、既存データの集計はバックエンドで完結させたことで、新しいミッションを追加してもiOS/Android側の改修がほとんど不要になった&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;データストアは要件に合わせて使い分ける&lt;/strong&gt;: デイリーミッションにはFirestore、報酬状態にはDynamoDB、累積データはRDB/既存Lambdaと、特性に応じたストア選択が運用負荷の低減につながった&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;書き込み分散の設計は初期に行う&lt;/strong&gt;: FirestoreのドキュメントモデルやDynamoDBのGSIシャーディングなど、ホットパーティション対策は後から変更しにくいため、初期設計で考慮しておくことが重要&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;マルチクラウド構成でのゲーミフィケーション機能の設計を検討されている方の参考になれば幸いです。&lt;/p&gt;
</description>
    </item>
    <item>
      <title>RubyKaigi 2026が近いのでローカルオーガナイザーが函館のご飯を紹介します</title>
      <link>https://tech.pepabo.com/2026/04/10/rubykaigi2026-hakodate/</link>
      <guid>https://tech.pepabo.com/2026/04/10/rubykaigi2026-hakodate/</guid>
      <pubDate>Fri, 10 Apr 2026 00:00:00 +0900</pubDate>
      <description>&lt;p&gt;&lt;a href="https://rubykaigi.org/2026/"&gt;RubyKaigi 2026&lt;/a&gt;の開催が近づいてまいりましたが、皆様いかがお過ごしでしょうか。EC事業部のakatsuuraです。インターネットでは&lt;a href="https://x.com/UVB_76"&gt;@UVB_76&lt;/a&gt;として生きています。&lt;/p&gt;

&lt;p&gt;私は生まれてから学生のころまで函館で過ごしており、その縁で今年のRubyKaigiのローカルオーガナイザーとして活動をしています。去年の年末辺りから何度か函館に帰りつつ、地元のローカルオーガナイザーと顔を合わせたり、会場の下見や現地の業者さまと打ち合わせを行って来ました。そしてその合間で様々な飲食店に行って食べ歩きをしてきました。&lt;/p&gt;

&lt;p&gt;この記事では直近函館に帰った際に自腹で食べ歩きをした飲食店を紹介していきます。RubyKaigi会期中の昼食、夜の野良ドリンクアップや夕食、After Partyの帰りの夜食やDay4以降など、それぞれの場面で参考にしていただければ幸いです。&lt;/p&gt;

&lt;h2 id="夜に行きたい"&gt;夜に行きたい&lt;/h2&gt;

&lt;h3 id="たちか屋"&gt;たちか屋&lt;/h3&gt;

&lt;p&gt;下見の際に地元の方に紹介してもらったお店です。五稜郭のエリアに存在していて、店内にはカウンターと座敷席が用意されています。私が行ったときにはおすすめとしてホッキ貝のお刺身とごっこの唐揚げがメニューにあり、日本酒と合わせて美味しくいただきました。&lt;/p&gt;

&lt;p&gt;&lt;img src="/blog/2026/04/10/rubykaigi2026-hakodate/images/01.jpg" alt="" /&gt;
&lt;img src="/blog/2026/04/10/rubykaigi2026-hakodate/images/02.jpg" alt="" /&gt;
&lt;img src="/blog/2026/04/10/rubykaigi2026-hakodate/images/03.jpg" alt="" /&gt;&lt;/p&gt;

&lt;h3 id="煙が目にしみる"&gt;煙が目にしみる&lt;/h3&gt;

&lt;p&gt;五稜郭の繁華街の奥にあるダイニングバーです。料理のメニューが豊富で二次会以降に食べたりなかった場合にも便利かもしれません。個人的にはラーメンサラダがおすすめです。&lt;/p&gt;

&lt;p&gt;&lt;img src="/blog/2026/04/10/rubykaigi2026-hakodate/images/04.jpg" alt="" /&gt;&lt;/p&gt;

&lt;h2 id="締めに行きたい"&gt;締めに行きたい&lt;/h2&gt;

&lt;h3 id="らーめん-ひらき家"&gt;らーめん ひらき家&lt;/h3&gt;

&lt;p&gt;いくつか店舗があるのですが、私が行ったのは五稜郭、本町の元祖 ひらき家でした。深夜までやっているので締めにどうぞ。&lt;/p&gt;

&lt;p&gt;&lt;img src="/blog/2026/04/10/rubykaigi2026-hakodate/images/05.jpg" alt="" /&gt;&lt;/p&gt;

&lt;h3 id="笑てん"&gt;笑てん&lt;/h3&gt;

&lt;p&gt;函館駅前で締めを探して行き着いたのがこのお店でした。塩ラーメンは函館の塩らしいスッキリしたスープで、私はかなり好みでした。深夜でも地元の人が店の外に待ち列を作る人気店のようです。&lt;/p&gt;

&lt;p&gt;&lt;img src="/blog/2026/04/10/rubykaigi2026-hakodate/images/07.jpg" alt="" /&gt;&lt;/p&gt;

&lt;h3 id="赤い風車"&gt;赤い風車&lt;/h3&gt;

&lt;p&gt;通称「赤風」。今回の下見で初めてお店の存在を知ったのですが、なかなかインパクトがあるお店でした。メニューが豊富で、ハンバーグやパスタなどの洋食メニューは一通り揃っています。30時までやっているので、いつ行っても安心ですね(寝坊には気をつけましょう)。&lt;/p&gt;

&lt;p&gt;&lt;img src="/blog/2026/04/10/rubykaigi2026-hakodate/images/09.jpg" alt="" /&gt;
&lt;img src="/blog/2026/04/10/rubykaigi2026-hakodate/images/11.jpg" alt="" /&gt;
&lt;img src="/blog/2026/04/10/rubykaigi2026-hakodate/images/08.jpg" alt="" /&gt;&lt;/p&gt;

&lt;h2 id="お昼に行きたい"&gt;お昼に行きたい&lt;/h2&gt;

&lt;h3 id="コーヒーショップきくち"&gt;コーヒーショップきくち&lt;/h3&gt;

&lt;p&gt;RubyKaigiの会場から徒歩15分程度でいける昭和の香りが残る喫茶店です。某北海道ローカル番組のソフトクリーム3本勝負の舞台で、現在もテイクアウトをやっているようです。ランチブレイクの散歩先としていかがでしょうか。&lt;/p&gt;

&lt;p&gt;&lt;img src="/blog/2026/04/10/rubykaigi2026-hakodate/images/12.jpg" alt="" /&gt;&lt;/p&gt;

&lt;h3 id="葵食堂"&gt;葵食堂&lt;/h3&gt;

&lt;p&gt;会場近くにある定食屋さんです。会場下見のランチにふらっと入ったのですが、ランチメニューとして頼んで出てきた海鮮丼のボリュームを見て、これがしゅっと出てくる函館すごいのでは…?と気持ちを改めました。&lt;/p&gt;

&lt;p&gt;&lt;img src="/blog/2026/04/10/rubykaigi2026-hakodate/images/13.jpg" alt="" /&gt;
&lt;img src="/blog/2026/04/10/rubykaigi2026-hakodate/images/14.jpg" alt="" /&gt;&lt;/p&gt;

&lt;h2 id="朝に行きたい"&gt;朝に行きたい&lt;/h2&gt;

&lt;h3 id="きくよ食堂朝市の海鮮丼"&gt;きくよ食堂(朝市の海鮮丼)&lt;/h3&gt;

&lt;p&gt;函館駅周辺に宿泊されている方々は朝食として朝市の海鮮丼はいかがでしょうか。函館の観光地としては定番で、朝から営業しているお店が多く、何を食べても外れはなさそうです。私が行ったのはきくよ食堂で、うに・いくら・ほたての三色が丼を埋め尽くす元祖 函館巴丼はインパクトがあります。&lt;/p&gt;

&lt;p&gt;&lt;img src="/blog/2026/04/10/rubykaigi2026-hakodate/images/17.jpg" alt="" /&gt;&lt;/p&gt;

&lt;h2 id="会期前後に行きたい"&gt;会期前後に行きたい&lt;/h2&gt;

&lt;p&gt;会期中には時間的に行くことができないのですが、前日やRubyKaigi Day4以降にどうぞ。&lt;/p&gt;

&lt;h3 id="ティーショップ夕日"&gt;ティーショップ夕日&lt;/h3&gt;

&lt;p&gt;函館山の裏手、市電の終点「函館どつく前」から魚見坂を歩いて登っていった先、外国人墓地を抜けた先にある明治時代に建てられた検疫所を改装したカフェです。店名のとおり、時間帯を選べば西に沈んでいく夕陽を眺めながらケーキや珈琲を楽しむことができます。&lt;/p&gt;

&lt;p&gt;&lt;img src="/blog/2026/04/10/rubykaigi2026-hakodate/images/19.jpg" alt="" /&gt;&lt;/p&gt;

&lt;h3 id="cafe-モーリエ"&gt;Cafe モーリエ&lt;/h3&gt;

&lt;p&gt;こちらもティーショップ夕日と同様、外国人墓地の近くに突如として現れるカフェです。ジャムと共に楽しむロシアンティーや、ピロシキ、ホットパイが名物のようです。店内はとても静かで落ち着けるので、RubyKaigi終わりにのんびりしたい人におすすめかもしれません。&lt;/p&gt;

&lt;p&gt;&lt;img src="/blog/2026/04/10/rubykaigi2026-hakodate/images/21.jpg" alt="" /&gt;
&lt;img src="/blog/2026/04/10/rubykaigi2026-hakodate/images/22.jpg" alt="" /&gt;&lt;/p&gt;

&lt;h3 id="函館元町珈琲店"&gt;函館元町珈琲店&lt;/h3&gt;

&lt;p&gt;観光写真で有名な八幡坂を登り切る手前にある喫茶店です。豆の量と抽出量を細かく選べるこだわりのスタイルで、コーヒーにこだわりがある方はとても楽しめるのではないかと思います。八幡坂のまっすぐ海まで降りていく景色はとても綺麗なので、観光のついでに訪れるのも良いかもしれません。&lt;/p&gt;

&lt;p&gt;&lt;img src="/blog/2026/04/10/rubykaigi2026-hakodate/images/24.jpg" alt="" /&gt;&lt;/p&gt;

&lt;h3 id="五島軒"&gt;五島軒&lt;/h3&gt;

&lt;p&gt;西部地区にある歴史ある洋食屋さんで、明治時代から続く函館洋食文化の象徴のような存在です。スパイスを前面に出すタイプではない「洋食としてのカレー」をいただけます。写真を取りそびれたのですが、歴史ある建物で食べるカレーも体験として素敵なのでぜひ！&lt;/p&gt;

&lt;h3 id="尾木カリー"&gt;尾木カリー&lt;/h3&gt;

&lt;p&gt;こちらも西部地区にあるカレー屋さんです。五島軒のクラシカルな洋食カレーとは対照的に、尾木カリーのカレーはスパイスをしっかり効かせた、いわゆる「MPが回復するタイプ」のスパイスカレーだと思っています。&lt;/p&gt;

&lt;p&gt;&lt;img src="/blog/2026/04/10/rubykaigi2026-hakodate/images/26.jpg" alt="" /&gt;&lt;/p&gt;

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

&lt;p&gt;駆け足になりましたが、下見で実際に足を運んで「これは紹介したい」と感じた函館のお店を並べてみました。ここで紹介したお店以外にももちろん美味しいお店は豊富にあるので、RubyKaigi参加者の皆様にはぜひ楽しんでいただけたらと思います。&lt;/p&gt;

&lt;p&gt;RubyKaigiの話に戻ると、ローカルオーガナイザーとして参加者の皆様に函館でお迎えできるのを本当に楽しみにしています。会期中に私を見かけたら、この記事のお店に行った感想をぜひ聞かせてください!&lt;/p&gt;

&lt;p&gt;それではRubyKaigi 2026、函館でお会いしましょう。&lt;/p&gt;
</description>
    </item>
    <item>
      <title>ビジネスロジックのSQL化——セール進捗管理をdbtで再設計する</title>
      <link>https://tech.pepabo.com/2026/04/09/sale-progress-data-mart/</link>
      <guid>https://tech.pepabo.com/2026/04/09/sale-progress-data-mart/</guid>
      <pubDate>Thu, 09 Apr 2026 00:00:00 +0900</pubDate>
      <description>&lt;p&gt;技術部データ基盤チームの新飼（shinkai）です。&lt;/p&gt;

&lt;p&gt;データ基盤チームでは、技術部の「&lt;a href="https://tech.pepabo.com/2026/02/19/tech-division-agent-ready-2026/"&gt;Agent Ready&lt;/a&gt;」方針に基づき、事業部が意思決定に集中できるデータ環境の整備を進めています。今回はその実践として、オリジナルグッズの作成・販売サービス「&lt;a href="https://suzuri.jp/"&gt;SUZURI&lt;/a&gt;」のセール運用において、スプレッドシートに閉じていたビジネスロジックをdbtで構造化し、CSV1行の入力で目標・実績の全指標を自動算出できるようにした取り組みを紹介します。&lt;/p&gt;

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

&lt;p&gt;SUZURIでは年間を通じて複数回のセールを実施しています。セール期間中は目標に対する進捗（売上・流通額等）を毎日確認する必要があります。&lt;/p&gt;

&lt;p&gt;データはBigQueryにありますが、売上の算出ロジックはスプレッドシートの関数に組まれていました。そのため毎日の数値確認には「BIツールからCSVエクスポート → スプレッドシートに転記 → 関数で再計算」という手作業が必要でした。&lt;/p&gt;

&lt;h2 id="何を自動化し何を残すか"&gt;何を自動化し、何を残すか&lt;/h2&gt;

&lt;p&gt;最初に考えたのは、事業部とデータ基盤の役割分担です。&lt;/p&gt;

&lt;p&gt;&lt;img src="/blog/2026/04/09/sale-progress-data-mart/role-division.png" alt="事業部とデータ基盤の役割分担" /&gt;&lt;/p&gt;

&lt;p&gt;スプレッドシートで行われていた作業のうち、確定した目標値に基づく算出処理（日別配分、KPI概算、実績集計、目標との突合）はロジックが固定されておりSQLに書き起こせます。一方、セール企画時の試算プロセス（アイテムの選定、割引額の設定、目標数量の決定）はセールごとに変数と判断基準が変わるため、スプレッドシートに残しました。&lt;/p&gt;

&lt;p&gt;この線引きにより、事業部との接合点を「CSVに1行追加してPull Requestを出す」という1つのアクションに集約しています。確定した目標値（流通額と売上）だけをデータ基盤に渡せば、残りはすべて自動で算出されます。&lt;/p&gt;

&lt;h2 id="設計方針"&gt;設計方針&lt;/h2&gt;

&lt;h3 id="精度より実用性を優先する"&gt;精度より実用性を優先する&lt;/h3&gt;

&lt;p&gt;KPI目標の概算には前年同日の注文単価やCVRをそのまま使っています。最初から完璧な精度を目指すより、まず使える状態にして、運用しながら必要に応じて精度を上げていく方針です。比較セールが存在しない場合、KPI目標はNULLとし、無理に算出しない設計にしています。&lt;/p&gt;

&lt;h3 id="表示ロジックはbiツールに委ねる"&gt;表示ロジックはBIツールに委ねる&lt;/h3&gt;

&lt;p&gt;マートテーブルには日別の目標値と実績値だけを持たせています。累積値や達成率の計算はBIツール側に委ねました。マートの責務を「正確な基礎数値の提供」に限定することで、ダッシュボードの見せ方を事業部が自由に変えられるようにしています。BIツール側で計算式を誤るリスクはありますが、初回のダッシュボード構築時にQA対応することでカバーしています。&lt;/p&gt;

&lt;h2 id="csv1行からの自動算出"&gt;CSV1行からの自動算出&lt;/h2&gt;

&lt;p&gt;セール担当者が入力するCSV（dbt seed）はこれだけです。&lt;/p&gt;

&lt;div class="highlight"&gt;&lt;pre class="highlight plaintext"&gt;&lt;code&gt;sale_name,start_date,end_date,target_gmv,target_revenue,prev_sale_name
サンプルセール,2026-04-01,2026-04-10,50000000,20000000,前年サンプルセール
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;ここから、目標値の日別配分、KPI目標の概算、実績の自動集計、目標と実績の突合がすべて自動で算出されます。実績集計と突合は定型的な集計処理のため、ここでは設計判断が必要だった日別配分とKPI概算について説明します。&lt;/p&gt;

&lt;h3 id="日別配分"&gt;日別配分&lt;/h3&gt;

&lt;p&gt;目標値を日数で按分します。ただし均等配分ではなく、過去数年分のセール実績を分析して算出した倍率を、セール日数の区分ごとに適用しています。&lt;/p&gt;

&lt;h3 id="前年実績からのkpi概算"&gt;前年実績からのKPI概算&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;prev_sale_name&lt;/code&gt;に前年の比較セール名を設定すると、前年同日の注文単価やCVRから目標注文件数・目標DAUを逆算します。前年同日のデータがない日は、前年セール全期間の中央値でフォールバックします。&lt;/p&gt;

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

&lt;p&gt;スプレッドシートに閉じていたロジックを1つのマートテーブルに統合し、現在は実運用に入っています。事業部からは「手作業がなくなって助かる」という声に加えて、「何を見るか、何を気にするかに集中できるようになった」という嬉しい声が上がってきています。&lt;/p&gt;

&lt;p&gt;セール期間中の進捗管理に絞った今回のスコープを足がかりに、次は目標設定の上流まで構造化していきます。スプレッドシートに閉じたビジネスロジックの構造化は多くの組織に共通する課題だと思いますので、同様の取り組みを検討されている方の参考になれば幸いです。&lt;/p&gt;
</description>
    </item>
  </channel>
</rss>