項目	内容
公開ページ	https://kotohogi.nozoisfun.workers.dev/
かかった時間	だいたい 1日
使ったもの	Cursor / GitHub / Cloudflare

この記事では、つくったものの紹介だけでなく、なぜその構成にしたか、Cloudflare と KV をどう使ったか、Cursor で出荷まで回した体験、速さに安心を足す自動テスト、そして作り方の振り返り（KPT）までまとめます。

この記事の要点

今回の結論は、次の流れに集約できます。

#	ポイント	一言で
1	全部を最初から完璧にしない	まず出して、あとで直す
2	データの置き場を分ける	自分用 / URL配布 / みんなで共有
3	Cursor → プッシュ → 自動公開	CI/CD 感が出る
4	速さに安心を足す	自動テストと品質ゲート

小さな Web を「動くところまで」早く出すとき、全部をサーバーや DB に載せると重くなります。逆に、共有が必要な機能まで端末だけに閉じると成立しません。
役割ごとに置き場を分けることと、実装と公開を同じループで回すことが、今回いちばん効きました。

なにをつくった？

ことほぎは、幹事・司会の負担を減らし、会場の一体感をつくるためのツール群です。紹介ページを入口に、3つの余興アプリへ進める構成にしました。

名前	できること	たとえ
紹介ページ	アプリの入口	お店の看板
人間ビンゴ	ゲスト同士が話しかけてマスを埋める	紙のビンゴ
新郎新婦クイズ	4択クイズ	宴会のクイズ
リアルタイムアンケート	会場でその場投票	挙手の代わり

ビンゴ / クイズ … 問題やマス設定を URL に載せて配れる。特別なサーバー同期は不要
アンケート … 司会の画面とゲストの票を同じ状態にしたいので、後述の KV を使う

公開サイト: ことほぎ

技術的には、紹介ページとアンケート API は Next.js、余興 UI の本体は public/app-tools/ 配下の静的 HTML です。余興画面を軽く保ちつつ、必要な所だけサーバー側の仕組みを足す、という割り切りです。

いちばん大事：データの置き場を3つに分ける

設計の核心はここです。全部を同じ場所に置かない。

二次会アプリでは、データの性質が混ざりがちです。

自分のスマホにだけあればいいもの（入力した名前など）
みんなに同じ設定を配りたいもの（クイズ問題など）
みんなで同じ数字を見続けたいもの（アンケート票など）

これを1つのデータベースにまとめると、準備も運用も重くなります。今回は次の3つに分けました。

種類	例	置き場	なぜ？
1. 自分だけ	マスに書いた名前	スマホの中	他人と共有しなくていい
2. 配りたい設定	クイズ問題	URL の中	DB なしで同じ問題を配れる
3. みんなで同じ数字	アンケート票	KV（共有ロッカー）	司会画面とゲスト画面で一致が必要

この分け方のおかげで、ビンゴ／クイズは「リンクを配る」だけで完結し、アンケートだけクラウド側の倉庫を用意すればよくなりました。
全部をクラウドにする必要はない、というのが今回の実務的な結論です。

全体の流れ（公開まで）

開発から公開までは、だいたい次の一本道です。手元で完成させてから別途サーバーを借りる、というより、GitHub に置いた瞬間から公開パイプラインに乗るイメージです。

順番	やること	たとえ
1	Cursor で作る・直す	原稿を書く
2	GitHub に送る	原稿を共有フォルダへ
3	Cloudflare が公開	印刷して貼り出す
4	URL で確認	掲示板を見に行く

ポイントは、3番を自分の PC だけでやらなくてもよいことです。Cloudflare と GitHub を連携しておけば、main へのプッシュをきっかけにビルドとデプロイが走ります。
今回いちばん感動したのも、この「送ったら載る」感覚でした。

Cloudflare を図で理解する

Cloudflare には色々なサービスがありますが、今回メインで使ったのは次の2つです。

名前	役割	たとえ
Workers	アクセスに応じてページや投票処理をする	受付係
KV	鍵と中身のペアでデータを置く	共有ロッカー

Workers は、自分でサーバー機を24時間起動し続けなくても、アクセスが来たときに処理して返せる実行環境です。紹介ページや API、静的な余興 HTML の配信も、この仕組みの上で動かしています。

KV は Key-Value Store の略で、「鍵の名前」と「中身」をペアで置く倉庫です。アンケートでは、たとえばルームコード LOVE に対して poll:LOVE のような鍵を作り、質問・票数・いま何問目か、を JSON で保存します。

なぜアンケートだけ KV が必要か

ビンゴやクイズは、「同じ設定を配る」ことが主目的です。一方アンケートは、複数の端末が同じカウンターを見続ける必要があります。

アプリ	みんなで同じ中身？	方法
ビンゴ・クイズ	だいたい不要	URL で問題を配る
アンケート	必要	KV

司会が結果を出すタイミングで、ゲスト側にも同じ結果が見える。この「会場の一体感」のために KV を入れました。

メモリだけだとダメな理由

「サーバーのメモリに票を足せばいいのでは？」と思うかもしれません。Workers では、アクセスごとに別の実行場所（受付係）が対応することがあります。

受付係が複数いると、メモがバラバラになります。だから「みんなで見る数字」は、共有できる倉庫（KV）に置きます。

あわせて、アンケートのデータはだいたい 24時間で消える 設定にしました。二次会が終わったあとに長く残す必要がない、という前提です。

アンケート：司会とゲストの流れ

アンケートは、技術以前に 会場オペ が大事です。誰が進行し、誰が投票し、いつ結果を見せるか。そこを役割で固定しました。

役割	やること	やらないこと
司会（Host）	ルーム作成・次の質問・結果表示	投票しない
ゲスト（Guest）	投票	進行操作

初版では Host も選択肢を押せてしまい、票に混ざる余地がありました。会場では司会が誤操作しやすいので、Host は表示と進行だけに直しています。
結果も、Host が「結果を表示」するまでゲスト側に出さないようにし、発表のタイミングを司会が握れるようにしました。

ゲスト用 URL（これだけで入れる）

.../wedding-poll/index.html?room=LOVE

ステップ	誰が？	内容
1	司会	Host で入室
2	司会	ゲスト用 URL をコピーして配る
3	ゲスト	リンクを開く → すぐ投票
4	司会	タイミングを見て結果表示

会場では、モード選択やコード手入力が多いほど詰まります。
リンク1本で Guest 入室できるようにしたのは、そのためです。Host がまだルームを作っていない場合は、準備完了まで待って自動で入れるようにもしてあります。

Cursor で感動したこと

今回いちばん強く残ったのは、実装だけでなく Git のコミット＆プッシュまでエージェントに依頼できることでした。

	昔	今回
コード	自分で書く	Cursor に頼む
Git	自分で操作	「コミット＆プッシュして」
公開	手作業が多い	Cloudflare が自動
感覚	工程が多い	会話の延長で出荷

従来は「作る人」と「出す人」の作業が分かれがちでした。今回は、直す会話の直後に出荷まで進めるので、小さな改善をためずに本番へ載せられます。
約1日のあいだに、公開後の改善もすぐ反映しました。

改善	効果
ビンゴ達成に日付と秒	記録がわかりやすい
Host は投票不可	司会が誤って票を入れない
`?room=` で即投票	ゲストが迷わない

この速さは強い一方で、確認なしの自動出荷は危険でもあります。自分では次を守るようにしています。

任せきりにしないチェックリスト

チェック	なぜ？
変更内容をざっと見る	意図しない変更を防ぐ
秘密情報を上げない	パスワード等が漏れる
プッシュ先を確認	本番に影響するため

便利さ × 自分の確認 = 安心できる速さ

Cursor の価値は「全部任せて楽をする」ことより、短い改善ループを回せることにある、というのがいまの実感です。

困ったこと → 学び

公開までの途中では、いくつか典型的な詰まり方をしました。失敗そのものより、次に活かせる学びとして残します。

困ったこと	原因のイメージ	学び
どのフォルダを上げる？	手動アップロードだと思っていた	GitHub に置けば Cloudflare が組み立てる
公開の直前でエラー	KV の番号が仮のまま	共有ロッカーの設定を忘れない
自分の PC で公開コマンドが失敗	環境の差	GitHub 連携の方が安定しやすい

特に印象的だったのは、「ビルドは成功したのにデプロイだけ失敗」パターンです。アプリ本体ではなく、KV の ID が仮のまま残っていたのが原因でした。
アプリコードが正しくても、基盤設定が未完了だと公開できない、という当たり前を、実体験で学びました。

公開の正しいイメージ

node_modules（依存パッケージの巨大フォルダ）は、自分でアップロードする必要はありません。Cloudflare 側のビルドで入ります。
「何を Git に含めて、何を含めないか」を README に地図として書いておくと、後から見ても迷いにくいです。

実践するときの順番

同じことをもう一度やるなら、次の順番が再現しやすいです。最初から全部を同時にやらないのがコツです。

順番	やること	ゴール
1	小さく動くものを作る	まず1画面でもOK
2	GitHub に置く	コードの保管庫
3	Cloudflare と連携	URL で見える
4	必要なら KV	みんなで同じ数字
5	直す→確認→プッシュ	改善ループ
6	自動テスト	速さ＋安心

出してから直す。
最初から認証・厳密な同時制御・完璧なデザインまで入れると、1日では形になりにくいです。まず URL で触れる状態をつくり、会場目線で直す方が早い、というのが今回の実感です。

速さに安心を足す：自動テストを入れた

公開ループが速くなると、次に気になるのは 「壊れたまま出していないか」 です。
人手の確認だけでは、直すたびに同じ確認コストがかかります。そこで、公開後の改善ループの延長として、自動テストを足しました。

方針はデータの置き場と同じです。全部を一度に完璧にしない。壊れたら一発で分かる所から入れる。

テストも「置き場」を分ける

層	なにをするか	コマンド例	保証すること
単体	部品の入出力	`npm test`	ルーム正規化・票配列などが仕様どおりか
シナリオ（E2E）	ブラウザ自動操作	`npm run test:e2e`	LP導線・ビンゴ達成・アンケート Host/Guest など
スモーク（任意）	公開URLへの短い通信	`npm run smoke`	非本番が生きているかの最低確認

本番の KV を CI から直接叩かないこと、テスト用ルームは T 始まりにすること、有料のテスト SaaS は使わないことも最初に決めました。
会場データを汚さない／課金を増やさない、という現場目線の制約です。

シナリオはガーキン記法で書いた

E2E は「前提・もし・ならば」の ガーキン記法 でシナリオを書き、Playwright で動かしています。
仕様書を読んだ人と、テストコードの意図がずれにくいのが利点です。

例（アンケートの最短経路）:

# language: ja
シナリオ: Hostが入室しGuestが投票できる
  前提 アンケート開始画面を開いている
  もし Hostとして新しいテストルームに入室する
  ならば Hostのセッション画面が表示される
  かつ ゲスト用URLが表示される
  もし GuestがそのURLで先頭の選択肢に投票する
  ならば Guestは投票済みと表示される

カバーしている主なストーリーは次のとおりです。

ID	内容	ねらい
SC-LP-02	LP から3アプリへ遷移	導線が死んでいない
SC-POLL-01/02	Host 入室 → Guest 投票 → 結果表示	会場オペの最短経路
SC-POLL-03	Host は投票できない	誤操作を防ぐ UX
SC-BINGO-01	名前入力でビンゴ＋日時	達成体験が壊れていない
SC-QUIZ-01	共有 URL で同じ問題	URL 配布が成立する

実行すると 動画（webm） が残ります。失敗したとき「どこで止まったか」を目で追えるので、ログだけより現場感があります。

npm run test:e2e:install   # 初回だけ（Chromium のダウンロード）
npm run test:e2e
npm run test:e2e:report    # 動画付きレポート

いつ強制で走らせるか

「速いまま」にするには、確認を 適切なタイミングだけ 挟む必要があります。

タイミング	場所	強制する内容	理由
コミット	手元	なし	途中保存を妨げない
プッシュ直前	手元（husky）	単体だけ	数秒で壊れたロジックを止める
プッシュ / PR	GitHub Actions	単体 + E2E	Linux 上の正。動画も残る
main への公開前	Deploy ワークフロー	同じ品質ゲートをもう一度	壊れたままデプロイしない

本番相当の動き（Workers / KV）は、単体だけでは足りません。
プレビュー（非本番）で触ってから main に載せる、という順番は、公開時と同じ考え方です。

途中で見つけた本番バグ

自動テストを書きながら、アンケート入室直後に Guest の選択肢が押せない不具合にも当たりました。
原因は「処理中フラグを下ろしたあとに画面を描き直していなかった」こと。人の手でも再現できますが、E2E が同じ操作を毎回やるので、逃げにくくなります。

テストは品質保証のためだけではない。仕様と実装のズレを見つける道具にもなる、という実感です。

まだ残していること

全部を自動化したわけではありません。

これから	理由
API 単体の厚み	ストア境界をモックしやすくしてから足す
プレビュー専用 KV の分離	試し投票が本番データに混ざらないようにする
Branch protection	マージボタン自体を赤のまま止められないと、ゲートが弱い

まずは「壊れたら一発で分かる」層と「テスト通過後にデプロイ」までを入れた段階です。
速さの型は残したまま、安心を足す、という Try の第一歩、という位置づけです。

振り返り：作り方の KPT

ここまでの進め方を、自分用の振り返りとして KPT でまとめます。

用語	意味
Keep	うまくいったので、次も続けたいこと
Problem	つまずいた・弱かったこと
Try	Problem を減らすために、次に試すこと

KPT は「よかった／悪かった」で終わらせず、次の行動に変えるための枠です。

Keep（よかったので続けたい）

いちばん効いたのは、完成度より「まず届く形」を優先したことです。二次会ツールは会場で使えなければ意味がないので、「公開できる最小構成 → 触って直す」の方が、設計を長く練るより成果が出ました。

項目	補足
まず出して、あとで直す	LP・3アプリ・Cloudflare 公開まで約1日。最初から認証や厳密な同時投票制御まで入れると、届かなかった可能性が高い
データの置き場を分ける	「自分だけ／URLで配る／みんなで見る」を分けた。全部を DB にすると重いし、全部を端末だけにするとアンケートが成立しない
Cursor → プッシュ → Cloudflare	実装の会話の延長で出荷できた。ビンゴの時刻表示や Poll の UX 改善も、同じ日に本番へ載せられた
本番（または本番相当）で触ってから直す	頭の中の仕様より、実際に Host／Guest をやると弱点が見える。Host 投票や Guest 入室の改善はここで生まれた
スクショやログを共有して進める	Cloudflare の画面やビルドログをそのまま見せる方が、言葉だけの説明より早い。遠回りが減った
`docs/` に要件・設計を残す	コードだけだと「なぜそうなったか」が消える。サイト非公開の `docs/` に置いたのは、公開物と内部資料を分ける意味でもよかった

Keep を一言で言うと、小さく出して、必要な共有だけクラウドに寄せ、出荷ループを回したことです。

Problem（つまずいた・弱かったところ）

速さと引き換えに、準備不足と初回 UX の甘さが出ました。失敗自体は学習になっているので、次は「同じ失敗を繰り返さない仕組み」が必要です。

項目	補足
「何をデプロイするか」が最初あいまい	静的サイト感覚だと「どのフォルダをアップロード？」となりやすい。実際は Git のソースを Cloudflare がビルドする。ここを最初に図解しておくと迷わない
設定の仮置きを本番に持ち込んだ	`wrangler.jsonc` の KV ID が `REPLACE_WITH_...` のまま。ビルドは通ってもデプロイで落ちる、という典型。仮値は「まだ本番不可」の印だと意識する
小さなミスでビルドが落ちた	型定義の `#` コメントなど、言語／ツールの前提を知らないと一瞬で止まる。エラーログをそのまま共有して直す流れはよかったが、最初から防げる類でもある
アンケート初版の UX が弱かった	Host が投票できてしまう、Guest が URL ですぐ入れない、など。技術的には動いていても、会場オペとしては弱い。機能完成と体験完成は別、という学び
記事の読者想定が途中でブレた	技術詳細 ↔ 説明の粒度 ↔ 図の文法修正、と手戻りが多かった。書く前に「誰が何を持ち帰る記事か」を決めていないと起きやすい
手元環境の制約	Windows ARM ではローカルの Workers preview が不安定なことがある。最初から「GitHub 連携で Linux ビルド」と決めた方が、全体としては早かったかもしれない

Problem を一言で言うと、設定の取りこぼし・初回体験の粗さ・前提の後出しで手戻りが出た、です。

Try（次に試すこと）

Try は Problem への対策です。いまの速さを捨てるのではなく、速さの前に短い確認を挟むイメージです。

項目	補足
自動テストと品質ゲート	単体・シナリオ E2E・push/デプロイ前の強制。速さの前に短い確認を挟めるようになった
公開前チェックリスト	KV の ID／binding、ビルドコマンド、Host／Guest の最低動作
「出す前に一度使う」	自分で司会役とゲスト役を両方やる
危険な変更はプレビューブランチ	非本番で試し、問題なければ main
プレビュー KV の分離・Branch protection	まだ手作業設定が残る。ゲートを「破られにくい」形にするのが次

Keep / Problem / Try のつながり

	内容
Keep	小さく出して、共有が必要な所だけクラウドに寄せ、Cursor で出荷まで回す
Problem	設定ミス・初回 UX・前提の後出しで手戻りが出た
Try	チェックリストと自動テストで、速さを保ったまま安心を足す（第一歩は実装済み。KV分離と保護ルールが次）

今回の作り方は「遅い」のではなく、速い出荷の型ができた状態です。
その型に 壊れ検知 を足し始めた、というのがいまの位置です。

まとめ（1枚で）

最後に、全体を1枚の図と表にまとめます。

項目	内容
つくったもの	二次会向け LP＋ビンゴ＋クイズ＋アンケート
公開 URL	https://kotohogi.nozoisfun.workers.dev/
時間	約1日（Cursor 中心）
コツ	データの置き場を分ける／テストも層を分ける
感動	コミット＆プッシュ → 自動公開（CI/CD 感）
振り返り	上記の KPT
安心	単体・シナリオ E2E・デプロイ前ゲート（動画付き）
次	API 単体の厚み、プレビュー KV 分離、Branch protection

小さく出して、必要な共有だけクラウドに寄せ、出荷ループを回す。
そのうえで、自動テストで速さに安心を足す。これが、今回の一連の学びです。

リンク

種類	URL
本番サイト	https://kotohogi.nozoisfun.workers.dev/