デルタメモ

AI開発

画面に出ないときはデプロイを疑う—スタブと障害を混同しない

反映されない画面の切り分け、固定の未接続文言が障害に見える問題、ロール別ナビと管理者の表示確認の設計メモ。

ホスティングや認証を先に進めていると、「画面はあるのに期待どおり動かない」が頻発します。エージェントはすぐコードやキャッシュを疑いがちですが、先に見るべき切り分けがあります。この記事は、個人・小規模SaaSで繰り返し出る型だけをまとめます。

この記事でわかること

「見えない」の切り分け

反映されない・古い画面のまま、と言われたら、コードを読む前に次を確認します。

  1. デプロイ／ビルドのjobがまだRUNNINGではないか 2.対象環境（本番相当かプレビューか）を見間違えていないか 3.キャッシュや別ブランチのURLを開いていないか

エージェントは「直したのに出ない」と聞くと、すぐ実装差分に入ります。job完了前の指摘は、是正指示としてrulesやチェックリストに一文あると再発が減ります。

プレースホルダは障害に見える

一覧が空のときに「データ未接続」などと常時固定すると、インフラ故障・権限エラー・本当にゼロ件、の区別が利用者に付きません。

次のどちらかに寄せます。

スタブと本番未接続を、利用者が誤解しない文言にすることが目的です。開発者向けの内部用語を画面に出さないでください。

ロール別ナビ

管理者が一般画面の見え方を確認したいことがあります。設計で次を決めておきます。

どちらも無しのままロール分離だけ厳しくすると、管理者は確認手段を失い、エージェントも「閉じたまま」を正しい状態だと誤解しやすいです。

管理者と課金

決済が不要なロールでは、メニューを無効化（グレー）し、URL直打ちもサーバ側で拒否します。表示確認と課金フローを同一視しないでください。

表示確認用の切替

管理者だけ、課金非連動の表示プラン切替があるとUI確認が速いです。本番顧客のデータや契約を改ざんできる口にはしないでください。確認用であることがログや画面で分かるようにします。

見た目の差

管理メニューと一般メニューで色や配置を分けると、誤操作と迷いが減ります。同じ主ボタン色のままだと、どちら側にいるか分かりにくいです。

秘密の置き場の言い方

「パスワードマネージャ」と言うと、特定アプリ必須に聞こえることがあります。伝えたい芯は、チャットやGitに出さない保管です。専用アプリでも、OSの保管でも、チームの方針に合わせてよい、と説明すると誤解が減ります。

SSR／ホスティングの環境変数

ビルド時注入とランタイムのdualに注意します。署名鍵などの環境変数名の食い違いで、画面は出るのにセッションだけ死ぬ、という切り分けが難しい障害になります。変数名は設計かREADMEに一覧し、プレビューと本番で揃えます。

作業前にAIへ渡す入力

人間向けの長い手順は書きません。次はすべて、作業前に AIに読ませる／貼る文 です。

AI向け：永続ルール（rules / AGENTS.md）

「画面に出ない／変わらない」と来たら、コード調査の前にデプロイ／ビルド完了・対象環境・URL を確認して報告する。
未接続スタブは障害に見える固定文言を避け、意図的スタブなら画面に一文で明示する案を出す。
管理者の一般画面確認手段（ナビ併記または別アカウント）と、決済不要ロールの直打ち拒否を設計に書く。

AI向け：この作業の開始時にチャットへ貼る文

画面に出ない問題を見る。コード差分の前に、デプロイ／ビルド job の状態、対象環境、開いている URL を確認して報告せよ。スタブ文言の扱いも切り分けに含めよ。

人間向け

なし。上をAIに渡すだけでよい。

まとめ

画面に出ないときは、まずデプロイ完了を疑います。固定の未接続文言は障害に見えるので、接続するか意図的スタブと明示します。管理者の確認手段と課金の無効化は設計に書き、確認用の切替は改ざん口にしないことが安全です。

読者チェックリスト

参考リンク