HIROKI FUKUOKA（KAI）

「develop 廃止」が腑に落ちなかったので、Git Flow の概念から整理し直したメモ。

Git Flow とは

2010 年に Vincent Driessen が提唱したブランチ運用の型。「本番に出す単位はバージョン（束）」という前提で、5 種類のブランチに役割を固定する。

ブランチ	役割	寿命
main（当時は master）	本番に出た状態だけを置く。ここにあるコミットはすべて「リリース済み」	永続
develop	次のリリースに向けて開発中のものを統合する場所。「次の束」の中身	永続
feature/xxx	機能 1 つの作業。develop から切って、できたら develop へ戻す	機能ができるまで
release/x.y	「そろそろ出す」と決めた時点で develop から切る。不具合修正だけ。QA が終わったら main と develop の両方へマージし、バージョンタグを打つ	出荷準備の間だけ
hotfix/xxx	本番の緊急修正。main から切って直し、main と develop の両方へ戻す	修正の間だけ

main     ──●────────────────●(v1.0)──────●(v1.0.1)──────●(v1.1)──
            \                ↑            ↑ hotfix       ↑
develop  ────●──●──●──●──●──┼──●──●──●───┼──●──●──●──●──┤
              \    /  \    / │            │              │
feature       ●──●    ●──●  │            │              │
                        release/1.0 ─────┘        release/1.1

Git Flow が向く条件

• 出荷がバージョン単位（パッケージソフト、アプリストア配布、顧客ごとに導入するもの）
• QA 期間があり、その間も次の開発を止めない
• 複数バージョンを同時に保守する

用語

QA 期間

• 通常の説明: QA は Quality Assurance（品質保証）。リリース候補のコードを凍結し、テスト担当が仕様どおり動くか、既存機能が壊れていないか、性能や互換性に問題が無いかを体系的に検証する期間。この間は新機能を入れず、不具合の修正だけを行う
• 平たく言うと: 「出す前に、いったん手を止めて、みんなで一通り使ってみる期間」。料理なら、盛り付けが終わってから客に出す前に味見と見た目の確認をする時間。その間は新しい具材を足さず、塩加減の直しだけをする

旧バージョンの保守

• 通常の説明: 新しいバージョンを出した後も、古いバージョンを使い続けている利用者のために、古い側にも不具合修正やセキュリティ修正を提供し続けること。複数のバージョンが同時に稼働するため、系統ごとにブランチを保つ
• 平たく言うと: 「新型を出した後も、旧型を使っている人のために旧型の修理を続ける」こと。車のメーカーが新モデルを出しても旧モデルの部品供給とリコール対応を続けるのと同じ

うちに合わない理由

• 3 製品とも継続デプロイ。マージした PR がそのまま本番に出る。多い日は 1 日 5 回。バージョンという束が存在しない
• 検証は PR ごと（CI の回帰テスト + プレビュー環境）で済み、develop に溜める期間が無い
• 利用者は全員が常に最新の 1 つを使う（自分でバージョンを選べない）ので、旧バージョンが存在せず、その保守も要らない
• 開発者は 3 人 + AI。統合の衝突は PR 単位で受け止められる

この状況で develop を持つと、本番前の統合場所がもう 1 つ増えるだけで、そこに溜まったものと main がずれていく。実際に 1 つのプロジェクトで、同じ変更を develop 用と main 用に別々にコミットする運用になり、ステージングが本番と違う構成で動いていた。

代わりに何をするか

Git Flow を簡略化した GitHub Flow（main + 短命の作業ブランチ + PR、マージで本番）に、PR ごとのプレビュー環境と機能フラグを足した形。

• 「今週の分をまとめて金曜に出したい」となったら: develop ではなく、短命の release ブランチ（金曜に main へマージして消す）か、機能フラグで「本番に入れるが表示しない」
• 「大きな機能を数週間かけて作る」なら: 機能ブランチを長く持つのではなく、機能フラグの裏で小さく PR を重ねる（トランクベース開発）

Git Flow 自体を否定するものではない。提唱者本人も 2020 年に「Web アプリで継続デプロイするなら、もっと単純な流れのほうがよい」と注記を出している。

develop を消す段取り

一気に消すのではなく、順に片付けてから消す。

1. ステージングの DB の migration 履歴を main の系列に揃え直す
2. develop にしか無い価値ある変更を、main 宛ての PR で出し直す
3. ステージングのデプロイを PR ブランチからに変える（プレビュー環境）
4. develop を凍結し、個人ブランチへの自動同期 bot を削除する
5. main 取込済みの古い個人ブランチを削除する（持ち主の了承後）

前回の記事で「足りなかったのは、既存を守るテストを蓄積して毎回走らせる仕組み」と書いた。その仕組みを具体的にどう作るか、相談しながら決めたことを、後で読み返す用にまとめておく。

先に、世界基準の知見を確認した

自分たちで発明する必要はなく、確立された考え方の組み合わせで足りる。役割で分けると 4 つに整理できる。

役割	知見	出どころ
何を試すか	テストピラミッド、リスクベーステスト、クリティカルユーザージャーニー	Mike Cohn、ISTQB、Google SRE
いつ・どこで試すか	デプロイメントパイプライン、トランクベース開発、プレビュー環境、密閉テスト	『Continuous Delivery』、Google Testing Blog、Vercel などの慣行
壊れにくく保つ	flaky（不安定な）テストの扱い、DORA の 4 指標	Google の flaky 研究、『Accelerate』
どう書くか	Playwright の公式ベストプラクティス、契約テスト	Playwright docs、Pact

自分たちの状況で特に効くのは「密閉テスト（CI をステージングから切り離す）」と「flaky の扱い（放置すると赤でもマージが常態化する）」の 2 つ。ただし Playwright を使わないという意味ではない。Playwright は「どう書くか」の道具で、回帰テストの E2E はすべてこれで書く。

用語の確認: クリティカルユーザージャーニー

「クリティカル」という言葉は 3 つの意味で使われていた。

• クリティカルユーザージャーニー（CUJ）: これができなければサービスとして成立しない操作の流れ。回帰テストの対象を決める単位
• 不具合の重要度（Critical / High / Medium / Low、P0〜P3）: 起きた問題の深刻さ
• 機能の優先度としての「クリティカル」: 企画で「無いと売れない機能」

回帰テストの対象は CUJ、不具合は重要度、と使い分ける。

本数は先に決めない

「主要な流れを 10 本」と言いかけたが、本数から入るのはやめた。根拠は 2 つから取る。

1. コードにある機能の一覧。画面 URL と API の手続きを列挙すれば、候補は漏れなく出る。URL の階層は組織標準で決めてあるので、機能ごとに URL がある。画面のタイトルが画面ごとに変わっているかは要確認（SPA は固定のままのことが多い）
2. 実際に使われている量。新しくアクセス解析を入れなくても、Cloud Run のリクエストログに全リクエストの URL が残っているので、パス別・手続き別の件数を集計すれば出る

ただし、公開 1〜2 週間ではログが薄く、テスターの操作が混ざる。使用量を待つのは遠回りになるので、順番はこうした。

• 最初の束: コードの一覧と、数字を待たずに分かる「壊れると致命的な流れ」（ログイン、課金、代理店の紐付け、各製品の主業務 1 往復）から作って回し始める
• 1 か月後: ログの使用量を取り、「よく使われるのに束に無い流れ」を足し、「誰も使わない」ものを外す

使用量は「最初の選定」ではなく「1 か月後の見直し」に使う。

活用プラン

書く（規約）

項目	決め方
置き場所	各リポジトリの e2e/。回帰の束は e2e/regression/、issue ごとの受け入れは e2e/acceptance/<issue番号>/。クローズ時に regression へ移す
1 本の単位	1 つの CUJ = 1 ファイル。前提データはテスト内で作り、他のテストに依存しない
ロケーター	役割とラベルで指す（getByRole、getByLabel）。CSS のクラス名や DOM 構造で指さない
待ち方	sleep 禁止。web-first assertion（要素が現れるまで自動で待つ）だけ
データ	製品ごとにデモ店舗・デモ会員を固定 ID で用意し、テストは自分の店舗だけを触る。共有 DB でも PR 同士がぶつからない
外部連携	決済・Google・LINE は CI ではモック。実挙動は本番か Sandbox で別途
証跡	失敗時は trace とスクリーンショットを自動保存し PR に添付。受け入れの画像証跡もこの仕組みで撮る

走らせる（どこで、いつ）

場面	何を	環境	合否
PR を開く・push するたび	単体 + e2e/regression/ 全部	CI の使い捨て MySQL	赤ならマージ不可
受け入れ	e2e/acceptance/<issue>/	同上 + プレビュー環境で目視	受け入れ条件の一部
ステージング（ラベル付き PR）	スモーク数本	STG の pr-N URL	参考。migration の PR は必須
本番デプロイ直後	スモーク数本、読み取りだけ	本番	赤なら通知

保つ（運用）

• flaky: 原因なく 2 回赤になったら「隔離」ラベルで一時的に束から外し、1 週間以内に修正か削除。skip のまま放置しない。件数を月次で記録
• 束を育てる責務: 各プロジェクトの PM。issue クローズ時に受け入れテストを regression へ移す。月次で「本数、失敗数、拾った退行の数」を記録
• 見直し: 1 か月後にログの使用量で過不足を調整

製品ごとの着手

製品	現在地	最初の作業
A（先行）	Playwright + ローカル MySQL の CI あり	e2e/regression/ を作り、既存の受け入れテストから移す。ラベル起動のプレビュー環境
B	E2E 基盤なし	CI の使い捨て DB 基盤を A から移植（2〜3 日）。最初の束はログイン・外部連携・投稿・代理店紐付け
C	基盤なし、ブランチ運用の整理待ち	整理後に B と同じ手順

一番重い部分

B と C に「CI の使い捨て DB 基盤」を作る工数。A の基盤（MySQL を非標準ポートで起動する方式）が移植できる前提で 2〜3 日と見ているが、ORM の構成が違うので同じに動くかは未検証。ここが最初の山。

自分への注意

• 「決めない」を「始めない」にしない。本数は結果として決まる
• 回帰テストは「前に壊れたところを二度と壊さない」ための束。新しい壊れ方はテスターと監視が拾う。この分担を崩さない
• 「特に効く 2 つ」と言った瞬間に、他の 8 つを捨てたように聞こえる。役割が違うものは並べて言う

git 歴 1 年ほどの私が、3 人 + AI エージェントの小さなチームで 2 つの Web サービスを立て続けにリリースし、その直後に直面した問題と、整理した考え方をまとめます。専門用語はできるだけ、日常の言葉に置き換えています。

起きたこと

リリースまではスピード優先で、main ブランチに直接 push して本番へ出していました。リリース後、テスターが見つけた不具合を直していくと、前は動いていた機能が、修正によって動かなくなるケースが出始めました。直したつもりが後戻りする。この現象を業界では「退行（リグレッション）」と呼びます。

原因ははっきりしていて、「変更で既存の機能が壊れていないか」を機械で確かめる仕組みが無かったことです。新機能のテストは書いても、それが蓄積されて毎回走る形になっていませんでした。

用語を整理する

まず、会話の中で混ざっていた言葉を分けました。テストには「目的」と「形式」の 2 つの軸があります。

目的（何のために試すか）

目的	確かめること
受け入れ	新しく作ったものが約束どおりか
回帰	変更で既存が壊れていないか
スモーク	デプロイ直後に起動して主要画面が開くか
探索的	決めた手順に無い操作で壊れ方を探す（テスターの仕事）

形式（どうやって試すか）

形式	範囲	手段
単体	関数 1 つ	コードから直接呼ぶ
結合	API や DB を含む複数の部品	サーバーを起動して叩く
E2E	画面から DB まで全部	ブラウザを自動操作
目視	見た目	人がスクリーンショットを見る

「回帰テスト」は目的の名前、「E2E」は形式の名前です。だから「E2E の形式で書いた回帰テスト」という組み合わせが成り立ちます。料理でたとえると、回帰は「味見をする理由（前と同じ味か）」、E2E は「味見の仕方（一皿をコース通りに食べる）」です。

回帰テストはいつ走らせるか

ここで私が引っかかったのは「STG（ステージング環境）で確認するなら、STG にマージしてデプロイしないと動くかどうか分からない。そうすると時間が空いて、不具合を潰す速さが落ちるのでは」という点でした。

答えは、回帰テストを STG に載せないでした。

段階	いつ	どこで	何を確かめる
1	PR を開いた瞬間、自動	CI（使い捨ての DB）	単体 + 回帰テストの最低セット
2	DB の形や設定を変えた PR だけ、手動	STG	本番と同じ手順で壊れないか
3	1 が緑のとき、人が押す	GitHub	マージ
4	マージで自動、テストが緑のときだけ	本番	デプロイ
5	デプロイ直後、自動	本番	スモーク（読み取りだけ）

普通の修正は 1 → 3 → 4 で、待つのは CI の十数分だけ。STG を通す必要があるのは、データベースの構造や環境設定を変えるような一部の PR だけです。

「マージせずに STG に出す」が分からなかった

もう 1 つ引っかかったのが、「STG に出すのにマージは要らない」という説明でした。私の理解は「STG に PR → マージ → 確認 → 本番に PR → マージ」だったからです。

原稿と印刷にたとえると腑に落ちました。

• ブランチ = 下書き。作業中の下書きが何本もある
• main = 決定稿
• ビルド = 原稿を版下にする
• デプロイ = 印刷して店に並べる
• マージ = 下書きの内容を決定稿に書き写す

本番は「決定稿に書き写してから印刷する」順番です。でも試し刷り（STG）は、下書きをそのまま印刷機にかければ済みます。印刷機（GitHub Actions）は「どの原稿を刷るか」を指定できるので、下書きのブランチを指定すれば下書きが刷れる。決定稿を書き換える必要はありません。

試し刷りのたびに決定稿を書き換えると、決定稿が試作の内容で汚れて、本番に出すときに何が正しいか分からなくなります。実際、STG 用のブランチを別に持っていたプロジェクトでは、STG と本番のコードが大きく食い違っていました。

だから PR は 1 本だけ。下書きのまま STG で試し、OK なら同じ PR をマージして本番へ、という流れになります。開発しながら何度も直す前提だからこそ、決定稿は最後の 1 回だけ更新します。

STG が 1 台だと同時に試せない

3 人 + AI エージェントが同時に別々のブランチを進めると、STG が 1 台では取り合いになります。人数分の STG を用意する必要があるのか、と思いましたが、答えは「1 台でいい」でした。

PR ごとのプレビュー環境という考え方です。STG のサービスは 1 つのまま、その中に PR ごとのコピー（Cloud Run ではリビジョンにタグを付ける機能で実現）を置き、pr-123 のような専用 URL を付けます。ローカル開発で、ブランチ A を 3001 番ポート、ブランチ B を 3002 番で同時に立ち上げて見比べる、あの感覚をクラウドでやるものです。

費用が増えないのは、Cloud Run が「リクエストが来たときだけ動く」仕組みだからです。人感センサー付きの照明のように、誰かが URL を開いた瞬間に起動し、しばらくアクセスが無いと止まる。PR が 10 本あっても、誰も見ていなければ費用はかかりません。

DB だけは共有の 1 台なので、DB の構造を変える PR は一度に 1 本ずつ、という規律が要ります。ただ、大半の PR は画面や API の変更で DB の形を変えないので、実際に順番待ちになるのは月に数本です。

整理した結論

1. PR は main 宛てに 1 本。STG 用のブランチや PR は作らない
2. 回帰テストの最低セット（主要な流れ 10 本前後、E2E 形式）を PR ごとの CI で走らせ、赤ならマージできない
3. 各機能の受け入れテストは、完了時に回帰テストの束へ移す（束を育てる責任者を決める）
4. STG は 1 台 + PR ごとのプレビュー環境。DB は共有し、DB を変える PR は直列
5. 本番デプロイはテストが緑のときだけ。直後にスモークテスト

古いバックログについても、リリース前の環境で起きた不具合は前提が変わっているので、一括で「保管」扱いにして、同じ現象が今の本番で再現したら新しく起票する、と決めました。古い記述に沿って直すと、いま動いている機能を壊す方向に働くからです。

反省

「E2E をしっかりやる」「STG を整える」とは何度も言っていましたが、目的と形式を分けて考えるまで、何が足りないのかを言葉にできていませんでした。足りなかったのは「既存を守るテストを蓄積して毎回走らせる仕組み」で、STG の台数でも E2E の量でもありませんでした。