AI開発で数日を救う人間によるレビュー・チェックポイント

なぜ5分の人間レビューが大きな時間を救うのか

AI支援での開発は即時に感じられます。機能を説明すると画面ができあがり、アプリは完成したように見えます。しかし落とし穴は、実データや権限、本番設定といったエッジケースで小さな差分が失敗につながることです。その「小さな」見落としが、後で1週間の後始末に化けます。

チェックポイントは、変更を受け入れたり出荷したりする前の短い人間による一時停止です。ミーティングでも長いQAサイクルでもありません。5分の意図的なスキャンで、「もしこれが間違っていたら一番大きく壊れるのは何か？」を自問します。

最も痛い後始末は、次の4つの高リスク領域から来ることが多いです。

• データスキーマ: 型が違う、制約がない、名前が紛らわしい、インデックスがない。
• 認可と権限: ユーザーが見たり編集したりしてはいけないものにアクセスできる、または管理者が仕事できない。
• 破壊的操作: 削除/上書き/バルク更新が簡単に実行でき、復旧手段がない。
• デプロイ設定: 環境変数の誤り、開発と本番のデータ混在、シークレットの扱いが雑、ドメインの設定ミス。

短い一時停止が効く理由は、これらの問題が横断的だからです。小さなスキーマのミスがAPI、画面、レポート、マイグレーションに波及します。認可のミスはセキュリティインシデントになります。デプロイ設定の誤りはダウンタイムを招きます。

手作業でコードを書く場合でも、Koder.aiのようなvibe-codingツールを使う場合でもルールは同じ：速く動くが、ダメージが大きいところには小さなガードレールを付ける。

シンプルな5分チェックポイントルーティン

チェックポイントは予測可能なときにやると効果的です。すべてをレビューするのではなく、取り消しにコストがかかるものだけをレビューします。

常にチェックポイントを発動させるタイミングを選んでください：機能を完成させた直後、デプロイ直前、データ・認可・課金など本番に触れるリファクタ直後です。

タイマーを5分にセットして、終わったら止めます。もし実際のリスクが見つかれば、長めのフォローアップを予定します。見つからなければ自信を持って出荷します。

ルーティン

1. 変更を一文で名付ける（ユーザーが今何をできるようになるか）。
2. 被害範囲を確認する（どのデータ、どのロール、どの環境に触れるか）。
3. 危険なエッジをスキャンする（スキーマ、認可ルール、破壊的操作、デプロイ設定）。
4. 一つの現実検証を行う（動作を証明する最も単純なフロー）。
5. 判断する：進めるか、プロンプトを調整して再生成するか、ロールバックするか。

レビュー担当者役を割り当ててください。たとえ「将来の自分」でもかまいません。後で中断できないチームメイトに承認するつもりで想像します。

小さなテンプレートがあれば一貫性を保てます：

Change:
Risky areas touched:
1 quick test to run:
Decision (proceed / adjust prompt / rollback):

Koder.aiで作業しているなら、最後のステップを意図的に簡単にしておきます。スナップショットとロールバックが「よくわからない」を安全な決断に変えます。

スキーマの健全性：データ問題を早めに見つける

数日を失う最速の方法は、意図と「だいたい合っている」スキーマを受け入れてしまうことです。小さなデータの誤りはすべての画面、API、レポート、マイグレーションに広がります。

まずコアとなるエンティティが現実と一致しているかを確認します。シンプルなCRMなら通常Customers、Contacts、Deals、Notesが必要です。もし “ClientItem” や “Record” のような曖昧な名前が見えるなら、それだけでズレが生じています。

5分のスキーマスキャン：

• 名前が現実に即しているか: テーブルが実際に話す概念を表しているか（users, invoices, subscriptions）。
• 名前が読みやすく一貫しているか: スタイル（created_at vs createdAt）を選んで徹底する。
• リレーションは完全か: 必要なところに one-to-many、役割やメンバーシップが必要なところに many-to-many。
• 制約が意図的か: 必須フィールドがnullableでない、重複が問題となる箇所はユニーク制約がある（email, invoice_number）、ステータス列は可能な値が定義されている。
• 成長で壊れないか: 共通のルックアップにインデックスがあり、大きなBLOBを不適切な場所に格納していない。

小さな例：invoice_numberにユニーク制約がないInvoicesテーブルはデモでは問題なさそうに見えますが、1か月後に重複が現れ、支払いが間違ったレコードに適用され、クリーンアップスクリプトと謝罪メールを書く羽目になります。レビューで見つければ30秒で直せます。

もし一つしか質問しないなら、これを問う：新しいチームメンバーにスキーマを2分で説明できますか？できなければ、上に構築する前に詰めてください。

認可ルール：誰が何をできるか（検証方法）

認可バグは高コストです。ハッピーパスのデモはそれを隠します。よくある失敗は「誰でも何でもできる」と「誰も何もできない」です。

役割は平易な言葉で書いてください：admin、staff、customer。ワークスペースがあるアプリなら workspace member と workspace owner を追加します。役割を一文で説明できないなら、ルールは拡散します。

次に一つのルールを適用します：デフォルトは最小権限。新しい役割は最初はアクセスなしまたは読み取りのみから始め、必要なものだけを付与します。AI生成コードはテストを通すために許容的になりがちです。

素早く検証するには、簡単なアクセスマトリクスを使い、実際にUIとAPIで試します：

• 各ロールについて、主要オブジェクトの作成/参照/更新/削除を確認する。
• 所有権を確認：ユーザーは自分のレコードのみ見られるべきか（明示的に共有されていない限り）。
• 一つの推測試行を試す：IDを変えて別ユーザーのアイテムを開いてみる。
• 管理者のみの操作（課金、エクスポート、ユーザー管理）が本当に管理者だけか確認する。
• 「隠れた」アクセスを見逃さない：リストエンドポイント、検索、ダウンロード。

所有権チェックは特に重要です。単に「ユーザーはTaskを読める」ではなく、「ユーザーは task.ownerId == user.id のTaskを読める」あるいはユーザーがワークスペースに属している場合のみ読める、という具合にです。

エッジケースが情報漏洩の温床になります：招待済みだが未承認のユーザー、削除済みアカウント、古いセッションを持つワークスペース退会者など。一つの見落としが週単位の修正に発展します。

Koder.aiを使っているなら、アシスタントに役割とアクセス表を出力させてから変更を受け入れ、各ロールで2つのテストアカウントで検証してください。

破壊的操作：誤ったデータ消失を防ぐ

破壊的操作は、小さなミスを数日分の後始末に変える最短ルートです。

まず、データを消去または上書きする可能性があるものをすべて列挙してください。削除ボタンだけではありません。リセット、同期、インポート/置換、インデックスの再構築、シード操作、広範囲な管理ツールも含まれます。

いくつか明確な安全信号を探します：

• 危険な操作には明示的な確認（タイプ入力で確認する方式が最良）。
• 影響範囲が限定的（一件、1ユーザー、1ワークスペースなど）で、簡単に“全件”にならないこと。
• 実行者と影響をログする。
• 安全なデフォルト（dry run、プレビュー、削除ではなくアーカイブ）。

多くのユーザー生成データにはソフトデリートを推奨します。単純なdeleted_atフィールドとフィルタで元に戻せるようにしておくと、バグが出たときに時間を稼げます。

スキーマ変更も破壊的と見なしてください。カラムの削除、型変更、制約の厳格化はデータを失わせる可能性があります。AIがマイグレーションを提案したら、既存行に何が起きるか、どう復元するかを必ず問います。

ロールバック計画を一文で説明できないなら、破壊的変更は出荷しないでください。

デプロイ設定：小さな設定ミスが致命傷に

ほとんどの修正ストーリーは同じ始まり方をします：開発環境では動いたが、本番で挙動が違った。

開発と本番を意図的に分けてください：別のデータベース、鍵、バケット、メールプロバイダ。両環境が同じデータベースを指していると、テストスクリプトが実データを汚染し、クイックリセットで消してしまう可能性があります。

次にシークレットを確認します。設定ファイルやプロンプト、コミットメッセージにキーが見えるなら漏洩を前提にしてください。シークレットはデプロイ時に注入（環境変数かシークレットマネージャ）し、本番で必要なシークレットが無ければ起動を失敗させるべきです。その失敗は静かなフォールバックより安価です。

ブラウザ側に見える設定も確認します：allowed origins（CORS）、リダイレクトURL、OAuthコールバックURL。これらは微妙に合わないと「ログインが壊れている」原因になります。

5分のデプロイチェック：

• 開発と本番で別のDBと鍵を使っているか。
• シークレットは注入されており、ハードコーディングされていないか。
• オリジン、リダイレクト、コールバックが実ドメインと一致しているか。
• カスタムドメインの基本が正しいか（DNSが正しい先を指している、HTTPSが期待される）。
• 本番のログとエラーレポートがONで、機密データを出力していないか。

Koder.aiからデプロイしているなら、正しい環境をデプロイしていることと、問題があればロールバックできることをこの時点で確認してください。

マージ直前の60秒チェックリスト

AI生成の変更を受け入れて出荷する前に、1分立ち止まってください。スタイルは見ません。長い後始末に繋がるミスを探します。

• スキーマ: エンティティは妥当か？リレーションは合っているか？制約はあるか（ユニーク、not nullなど）？成長でクエリやストレージが壊れないか？
• 認可: デフォルト拒否か？各リソースの作成/参照/更新/削除を説明できるか？所有権チェックはサーバー側で強制されているか（UIだけでなく）？
• 破壊的操作: 取り返しのつかない操作に確認はあるか？ソフトデリートは使うべき箇所で使われているか？ロールバックプランはあるか（スナップショット、バックアップ、可逆マイグレーション）？
• デプロイ: 開発と本番は分離しているか？シークレットはコードやログに無いか？ドメインとリダイレクトは正しいか？

例：管理者によるユーザー削除機能をマージする直前に、バックエンドにロールチェックが無くUIだけで隠しているのを60秒で発見する、というケースがあります。その1件の発見でインシデントを防げます。

現実を強制する質問で締めます：

ここで実際のユーザーが故意に、または誤操作でできる最悪のことは何か？

答えに「他人のデータを削除する」「プライベートな記録を見る」「本番を壊す」が含まれるなら、止めて変更を強化してください。

例：5分レビューで1週間の後始末を防いだ実例

小さなCRMを作っていて、AIツールに顧客ページに「Delete customer」ボタンを追加させたとします。数分でUI、バックエンドエンドポイント、関連レコードを削除するデータ変更が生成されます。

見た目は全部動きます：ボタンは表示され、リクエストは200を返し、顧客はリストから消えます。多くのチームはそこで次に進みます。

5分レビューが捕まえるのは次の2点です：

1. DBの変更が cascade delete を使っており、請求書やアクティビティログまで削除してしまう。テストデータでは問題ないかもしれませんが、実際のCRMではレポートや監査、履歴が壊れます。
2. エンドポイントはサインイン確認のみで、adminロールの確認がない。どのスタッフでも顧客を削除できてしまう。

実践的な素早いレビュー：

• 非管理者のテストユーザーでボタンをクリックして失敗することを確認する。
• エンドポイントを確認し、権限のないユーザーを拒否することを確かめる。
• スキーマをスキャンして請求書、メモ、ログに何が起きるかを確認する。
• UIが確認を促し、何が削除されるかを表示することを確認する。
• テストする前に正しいデータベースを使っていることを確認する。

プロンプトの微調整で出荷前に直せます：

“Make delete customer a soft delete. Keep invoices and logs. Only admins can delete. Add a confirmation step that requires typing DELETE. Return a clear error message when unauthorized.”

再発を防ぐために、プロジェクトノートに3点を書いておきます：削除ルール（ソフトかハードか）、権限要件（誰が削除できるか）、期待される副作用（関連データの扱い）。

受け入れる前に明確化を促すプロンプト

AIの出力は自信ありげで前提を隠しがちです。目標はその前提を可視化することです。

次の言葉が出たら追確認を促すべきです： “assume”, “default”, “simple”, “should”, “usually”。これらは多くの場合「あなたのアプリに合うか確認していない選択」を意味します。

役立つプロンプトパターン：

“Rewrite your proposal as acceptance criteria. Include: required fields, error states, and 5 edge cases. If you made assumptions, list them and ask me to confirm.”

リスクを素早く露見させるためのプロンプトがもう二つ：

• “Show the data model changes as a before/after table. For each field: type, nullability, default, and migration risk.”
• “List all destructive operations you introduced (drop table/column, delete endpoints, cascade rules). For each, show how to undo it and what data is lost.”

認可については：

“Show roles and permissions for each API route and UI action. For every role: allowed actions, denied actions, and one example request that should fail.”

常に人が検証すべき項目を決め、それを短く保ってください：

• 認可ルールと管理者アクション
• 削除、カスケード、不可逆なマイグレーション
• 環境とデプロイ設定（prod vs staging）
• 支払い、メール、ユーザーデータのフロー
• ロールバックプラン（スナップショットやリリースポイント）

数日分の後始末を招く一般的なミス

長いクリーンアップの多くは同じ小さな選択から始まります：今動くからと出力を信頼すること。

“自分のマシンでは動く”は古典的な罠です。ローカルテストを通っても、実データのサイズや権限、環境の微妙な違いで失敗することがあります。修正は緊急パッチの山になります。

スキーマドリフトも罠です。テーブルが名前や制約、デフォルトなしで進化するとワンオフのマイグレーションや奇妙な回避策が増えます。後になって “status は何を意味する？” と聞かれて誰も答えられない状態になります。

認可を後回しにするのは痛いです。最初から誰でも何でもできる前提で作ると、後でランダムなエンドポイントや画面に穴を埋めるのに数週間かかります。

破壊的操作は一番大きな事故を招きます。“Delete project” や “reset database” は実装も簡単で後悔も早い。ソフトデリート、スナップショット、ロールバックプランが無いと取り返しが付きません。

数日に及ぶクリーンアップのよくある原因：

• 制約のないスキーマ変更（unique、not null、外部キーの欠如）
• UIだけの権限ルールでサーバー側チェックが無い
• 確認や復旧手段のない削除エンドポイント
• ステージングと本番を“ほぼ同じ”に扱うこと
• 誰が何を変えたかの記録が無いこと

次のステップ：チェックポイントを開発プロセスに組み込む

チェックポイントを定着させる一番簡単な方法は、すでにある瞬間に紐付けることです：機能開始、マージ、デプロイ、検証のタイミングです。

軽量なリズム：

• 作る前に: データ形（テーブル、キーとなるフィールド）と役割（誰が作成/参照/更新/削除できるか）について合意する。
• マージ前に: 認可、破壊的操作、本番データに触れるものについて60秒パスを行う。
• デプロイ前に: 環境設定（ドメイン、シークレット、メール、ストレージ、リージョン）をターゲットに合わせて確認する。
• デプロイ後に: 一つの実際のユーザーフローをエンドツーエンドで実行する。

Koder.aiで作業する場合、そのPlanningモードが“作る前”のチェックポイントとして機能します：“ordersはサインインしたユーザーが作成できるが、statusを変えられるのはadminだけ”のような決定を書き残してから変更を生成してください。スナップショットとロールバックがあると“よくわからない”を安全に戻す理由にできます。

5分で全てを捕まえられるわけではありませんが、コストの高いミスを安いうちに確実に捕まえられます。