オンボーディングの終わりを、最後の画面には置かなかった

この記事は、2026年8月10–16日の設計文書、Git記録、運用上の問題をもとに書き直したHaru Spaceの開発回顧だ。実際のメンバー・グループ・リポジトリ情報、内部アドレス、資格情報、非公開の会話は除外している。

オンボーディングを最初に作ったときは、最後の画面までうまく案内できれば十分だと思っていた。「次へ」ボタンを配置し、説明を短くし、完了画面からホームへ送れば終わりだと考えていた。

実際の利用の流れは、それほどまっすぐではなかった。

グループの承認後にブラウザを閉じることがある。リポジトリ接続の途中で外部認証画面へ移り、戻れなくなることもある。最初のコード作業は成功しても、リポジトリへの反映が失敗するかもしれない。まだVercelアカウントを持っていない場合もあり、空のリポジトリと既にコードがあるリポジトリに同じ開始画面を見せてはいけない。

こうした問題を経験してから、オンボーディングの完了基準を変えた。

オンボーディングの終わりは、最後の画面ではなかった。利用者が翌日に戻ったとき、既に終えたことを繰り返さず、失敗した地点で何も失わずに、次の安全な行動を見つけられる瞬間だった。

一般メンバーの最初の参加にも、別の設計が必要だった

初期のHaru Spaceオンボーディングは、グループを作り、空間とペットを設定する管理者の体験に集中していた。一方、招待された人や参加を承認された一般メンバーには、ホームへ入ったあとに何を知るべきかという案内が足りなかった。

アカウントの初回ログインだけで新規メンバーを判断することもできなかった。グループへ参加申請し、承認を待つ間に、既に何度もログインしている可能性があるからだ。同じ人が二つ目のグループへ参加したときに、初回利用者向けの案内を再び見せるべきでもなかった。

そこで、アカウントの初回ログインと最初のグループメンバーシップを分けた。過去にメンバーシップがない一般メンバーが初めて承認されたときだけ、段階状態を作った。

案内も、機能紹介より先にグループ生活の境界を置いた。

1. グループの運用ルールと、公式・非公式空間の違いを確認する。
2. グループメンバー一覧で、自分のプロフィールをどこまで表示するか選ぶ。
3. 端末通知を有効にするか決める。
4. 現在のグループに実際に割り当てられている案内ペットを選ぶ。
5. 最初の挨拶を残すか、望む場合だけ最初のAI会話を行う。

各段階はサーバーに保存し、一段階ずつだけ前へ進めるようにした。途中でログアウトしたりブラウザを閉じたりしても、現在の段階へ戻れた。プッシュ通知に対応しない端末と、AI応答が遅い場合には、「あとで」と通常の挨拶という別の道を残した。

オンボーディングを通過するために、AIコストを必須にはしなかった。

画面で隠すことと、サーバーで隠すことは違った

プロフィールの公開範囲を選べるようにすると、一つの重要な問いが生まれた。一般メンバー一覧のUIからプロフィールを隠すだけで十分なのか。

十分ではなかった。サーバー照会が引き続き全員の一覧を返せば、別の画面やAPIから再び見える可能性がある。公開範囲は照会ポリシーそのものに適用した。ただし、グループ管理者は運用のためにメンバーを確認できるようにし、利用者が自ら残したチャットや活動の投稿者名まで遡って隠すことはしなかった。

一つの設定が何を隠し、何を隠さないのかを正直に定義する必要があった。「非公開」という一語が、過去のあらゆる痕跡まで消すように見えてはいけなかった。

開発オンボーディングは、権限の不一致で止まった

新規グループ管理者の開発接続にも似た問題があった。画面にはリポジトリとAI実行機を接続する段階があったが、実際の承認サーバーはプラットフォームの最高管理者しか許可していなかった。自分のグループを作った管理者が、次の段階へ進めなかった。

新規グループのリポジトリ反映の初期設定も、停止状態として解釈された。最初のペットがファイルを正しく変更しても、コミットとプッシュの段階で突然止まる可能性があった。画面は可能な操作を見せているのに、実行層は別のポリシーを持っていた。

私たちは、グループごとの有効な管理者メンバーシップを共通ポリシーとして使うよう揃えた。自分のグループの接続は、そのグループ管理者が承認できるようにした。新規グループの反映フローは利用可能な状態から始めたが、自動承認は引き続きオフにした。既存グループが保存していた安全設定は変えなかった。

「利用可能」と「自動で許可」を分けたのだ。次のボタンが見えるということは、人が申請して承認できるという意味であって、システムが勝手にリポジトリを変えるという意味ではなかった。

失敗したコミットとプッシュを削除しなかった

最初の作業後にリポジトリ反映が失敗すると、初期UIにはもう一度試す道がなかった。隔離作業領域にはファイルと検証結果が残っていたが、利用者には新しい作業を始めるしかないように見えた。

反対に、再試行だけを無条件に提供すれば、終わらせたい失敗をいつまでも抱え続けることになる。ローカル作業領域も積み上がっていく。

そこで、反映失敗後の次の行動を二つに分けた。

• 一時的な実行失敗なら、同じ隔離変更と検証済みコミットから再試行する。
• もう反映しないと決めたなら、利用者が明示的に取り消す。

取り消しは、ファイルをすぐに消すボタンではなかった。反映状態と判断履歴を記録し、ローカルの隔離作業領域を猶予期間後の整理候補にした。失敗した作業領域は再試行の唯一の原本かもしれないため、自動削除しなかった。リモートブランチも、PR状態の確認と別の権限なしに実行機が勝手に削除できないようにした。

当時、自動整理はまだ有効にしていなかった。何を、いつ、どの監査契約のもとで削除できるかを先に決めた。保存コストを減らそうとして、復旧の原本を真っ先に消さないためだった。

デプロイ用アカウントがなくても、最初の作業は続けられるべきだった

以前のオンボーディングは、最初のPreview URLがなければ完了できないように構成されていた。Vercelをまだ接続していないグループは、コード作業を終えても最後の段階で止まった。

デプロイは重要な成果だが、すべてのグループが同じ日に運用アカウントとドメインを準備するわけではない。そこで、デプロイ方法を選択肢に変えた。

• 自分のVercelプロジェクトを接続する。
• 準備されている場合は、制限されたHaru Spaceの一時Previewを使う。
• 今は飛ばして、あとで接続する。

どの道を選んでも、最初の作業とオンボーディングを完了できるようにした。一時Previewは、機密性のあるプロジェクトのビルドを代わりにデプロイする機能ではなかった。グループ名だけを含む小さな静的体験画面に範囲を限定し、設定がなくてもオンボーディングを止めなかった。

運用上の所有権も分けた。体験用デプロイはプラットフォームが作れても、実際のサービスは利用者自身のデプロイアカウントとプロジェクトに属する必要があった。プラットフォームの資格情報を利用者のプロジェクトへコピーすることはなかった。

空のリポジトリと既存コードを、同じボタンで扱わなかった

最初のページを作るフローで最も危険な誤解は、すべてのリポジトリを空白のキャンバスとして扱うことだった。既にコードがあるリポジトリへ既定テンプレートを重ねれば、既存プロジェクトを壊す恐れがある。

そのため、接続検証の段階でリポジトリルートの状態を先に分類した。

• 空のリポジトリなら、既定プロジェクトから始めるか、空のままにするかを人が選ぶ。
• 既存コードがあれば、そのコードを維持して接続だけを進める。
• 既にHaru Starterなら、以前の段階を続ける。
• 判別できなければ推測せず、もう一度確認する。

既定プロジェクトは、AIが毎回フレームワークと依存関係を新しく選ぶ方式ではなかった。ブリッジが検証済みStarterと固定ロックファイルを隔離作業領域へ先に置き、最初のAI作業は、既存ページのタイトルと説明をグループの目的に合わせて変える小さな変更へ集中した。

この方法はトークン使用とネットワーク失敗を減らし、新規プロジェクトが最初から外部公開状態を管理する土台も持てるようにした。ただし、ゲートは既定で無効だったため、通常の公開動作を突然変えることはなかった。

「公開準備中」も、実際のプロジェクトごとに実装する必要があった

Haru Spaceで公開サイトの状態を、公開、公開準備中、メンテナンス中、非公開から選べるようにしても、新しいStarterだけに画面が入っていれば、既存サイトでは設定が反映されない。

既存の公開プロジェクトは、それぞれ異なるフレームワークと実行環境を使っていた。一つのファイルを複製する代わりに共通契約を定め、各環境の正式な入口に合わせて実装した。

• 静的アセットとヘルスチェックは、不要なゲート呼び出しから除外する。
• 外部訪問者には、検索対象外かつキャッシュされない状態画面を返す。
• 有効なグループメンバーは、短時間の一回限りの証明で実際の画面を確認できる。
• 公開サイトは、Haru Spaceの非公開セッションやメンバーシップDBを直接持たない。
• 現段階では、中央の制御面の障害が既存公開サイトすべての障害へ広がらないよう、可用性を優先する。

この選択により、メンテナンス案内のゲートと、完全な非公開セキュリティ境界が別物であることも明確になった。検索除外の表示はアクセス制御ではない。必ず閉じる必要があるサービスには、別の強制プロキシと運用ポリシーが必要だった。

オンボーディングを軽くするには、待機中の作業も減らす必要があった

利用者がいない間も複数の実行機が短い間隔でプロジェクト接続情報を確認し、公開ランディング画面がリクエストごとにセッションを読めば、一度のオンボーディングのために継続的なコストが発生する。

私たちは接続情報の定期照会を減らしながら、新しいプロジェクトの最初の作業が届いたときは即座に同期するよう変更した。公開ランディングとログイン済みメンバーのホームを分け、公開ページは静的キャッシュ経路で提供した。

この変更は、コスト削減を約束する数字ではなく、測定可能な仮説だった。変更前のリクエスト数を記録し、同じ期間・同じプロジェクト条件でActive CPUとエラー率を比較することにした。この期間内に確認できたのは、呼び出しが起こり得る構造を減らし、測定方法を定めたことまでだった。測っていない削減率を成果として書くことはしない。

失敗後に戻れる旅の基準

一週間を通じて、オンボーディングで守る基準は次のようになった。

1. 人の段階とサーバーの事実を一緒に保存する

画面は、利用者がどこまで進んだかを覚える。権限、接続、実行準備はサーバーで再検証する。

2. 選ばなくてもよい外部サービスを完了条件から外す

デプロイアカウント、プッシュ、AI会話は選択肢であるべきだ。準備できていないという理由で、基本的な共同作業まで止めない。

3. 既存資産を上書きする前に状態を分類する

空のリポジトリ、既存コード、Starterを区別する。不確かなときは自動適用しない。

4. 失敗後の次の行動を、再試行と取り消しに分ける

復旧可能な変更は保存する。終了する判断は監査履歴に残し、安全な整理候補へ移す。

5. 自動整理より先に保存契約を作る

ファイルの古さだけで隔離作業領域を削除しない。作業状態と、リポジトリ・リモートPRとの関係を確認できる場合だけ整理する。

6. オンボーディングのコストを、待機中から観察する

グループごとにプロセスを増やさず、実際の作業が届いたときに同期し、公開画面は可能な限り静的に提供する。

最後のボタンより、翌日の最初の画面

8月10–16日の変更は、オンボーディング画面を長くしたことではなかった。いくつかの段階は飛ばせるようになり、失敗には明示的な終了が生まれ、既定プロジェクトは人が選んだ場合だけ適用された。

一般メンバーは、最初のグループで自分の公開範囲と通知を理解したうえで、最初の会話を選べた。グループ管理者は、自分のリポジトリと実行機を接続し、デプロイ用アカウントがなくても最初の作業を始められた。リポジトリ反映に失敗したときは、変更を失わず再試行するか、明示的に終えることができた。

よいオンボーディングは、利用者を一度に最後まで押し込まなかった。どこで止まったかを覚え、戻ったときに権限と外部状態を再確認し、今できる次の選択を見せた。

私たちが完成させようとしたのは、完了率の高い一度きりの案内ではない。中断されても信頼を失わない、最初の旅だった。