API連携を見据えたWebアプリはPoC後に伸ばしやすい

PoCのWebアプリに、最初から完全なエンタープライズ設計は必要ありません。ただし、次のステップを妨げる作りにしてはいけません。

良い初版は、ユーザーワークフローを狭く保ちながら、データ境界と連携前提を見えるようにします。「狭いスコープ」と「使い捨て設計」は同じではありません。まず表面積を小さく保つ、次に内部を清潔に保ち、表面が成長できる状態にする。この2つの判断は別物です。

API連携を見据えるとは

API連携を見据えることは、すべての連携を初回から完成させることではありません。データがどこから入り、どこで判断され、出力が将来どこへ渡るのかを明確にすることです。

多くの場合、次の要素が含まれます。

2週間PoCでも、不釣り合いに大きな見返りがある技術判断:

型付き境界モデル。 入力・出力の形をスキーマ(Pydantic、Zod、TypeBox、JSON Schema)で初回コミットから定義する。モデルが契約、それ以外は実装。
外部システムごとのRepository/Serviceクラス。 モック実装でも、インターフェースは実物に似せる:invoices.fetch(since)、crm.upsert(contact)。差し替えは書き換えではなく設定変更になる。
書き込みすべてに冪等キー。 すべての変更系呼び出しが冪等キー(UUIDまたは入力ハッシュ)を受け取る。再試行が既定で安全になる。
events / runs テーブル。 意味のある全アクション（入力、出力、所要時間、状態、トリガー実行者）を永続化。stdoutへのログでは不十分。クエリ可能な履歴が必要。
単一の config モジュール。 環境別設定(URL、鍵、フィーチャーフラグ)を一箇所に集約。起動時に型検証。process.env をあちこちに散らさない。
.env.example とワンコマンド起動。 make dev または docker compose up でローカルにスタック全体が立ち上がる。引き継ぎは初日に始まる。

これらはどれも2週間スプリントに有意な時間を加えません。すべてが次のスプリントで何週も節約します。

買い手は、APIアクセスが完全に承認される前に証拠を必要とすることがあります。スプリントはエクスポート、モックデータ、手動アップロードから始め、PoCが信頼を得た後に直接連携へ進められます。

現実的なデータアクセスの段階:

第1週。 手動CSVアップロード、または匿名化サンプル。アプリはAPI受信のように振る舞うが、実体はフォルダ。
第2〜3週。 サンドボックスのサービスアカウントで読み取り専用APIアクセス、またはS3/SFTPへの定期エクスポート。書込はクライアントが点検できるステージングテーブルへ。
第4週以降。 本番APIアクセス。適切な認証、レート制限、監査付き。書込はフィーチャーフラグとテナント別キルスイッチで防御。

この順序なら、調達やセキュリティ確認の現実を無視せずに、前進できます。問いも分離されます。「業務が成立するか」は第1週に答え、「実システムに繋げるか」は並列で自分の速度で進みます。

リスクは、すべてがハードコードされているために動くデモです。ごく初期のコンセプトには使えますが、業務システムの証拠としては弱くなります。

時間に追われていても拒否すべき具体的なアンチパターン:

フロントエンドからのDB直接書込。 「PoCの便宜」が、実ユーザーが触った瞬間にセキュリティインシデントになる。
取り込み・変換・AI呼び出し・検証・永続化を1関数で行う。 その関数ができた瞬間、すべての変更がリスクになる。初日に分割する。
リポジトリ内の認証情報ハードコード(.env.local 含む)。シークレットマネージャ、またはgit除外のローカル限定ファイルを使う。PoCは予定より広く共有される。
テスト皆無。 PoCに90%カバレッジは不要だが、ハッピーパスと最も起こりやすい失敗モードのスモークテストは必要。引き継ぎと再実装の差はここ。
デモ専用認証。 共有パスワードや「ログインスキップ」はキックオフデモまでは可、それ以降は危険。Auth.js、Clerk、Cognitoを早く接続する。

より良いスプリントでは、後から実システムへ接続できる道筋が見えるだけの構造を持たせます。美意識は「エンタープライズ」ではなく「小さい、清潔、明らかに拡張可能」です。本番アプリの内部を小さくしたように見えるPoCこそ、次のスプリントの予算が付くPoCです。