設計レビューチェックリスト

背景: なぜこのスキルが必要か

Issue #723（ActionStatusQueue UI）の設計レビューで、11回のイテレーション・41件の指摘が発生した。 根本原因分析の結果、指摘の 73% が以下の2つに集約された:

残りの指摘も「指摘の部分的対応」(29%)、「JS/React仕様理解不足」(12%) が占める。

このスキルの目的: 設計計画を書く前に実コードを徹底調査し、全経路を網羅することで、レビュー指摘を事前に防止する。

文書品質の前提

• 設計書・仕様書を作成する前に plain-japanese スキル（C:\Users\zooyo\.codex\skills\plain-japanese\SKILL.md）を確認し、日本語品質基準を適用する
• 技術文書でも読みやすさを重視し、専門用語の乱用を避ける

Phase 1: 設計前の既存コード調査（必須）

1.1 データフロー全経路の洗い出し

設計対象の機能に関わる 全てのデータ更新経路 を洗い出す。 1つでも漏れると、その経路だけ旧挙動が残り再現困難なバグになる。

過去の失敗例:

• SSE経路だけ修正 → ポーリング経路を忘れた（3回再発: v1, v6, v7）
• 確認必須フロー（confirmation_required）の経路を見落とした（v4）

チェックリスト:
[ ] SSE イベント経路を全種確認した
[ ] REST ポーリング経路を確認した
[ ] REST 同期実行経路を確認した
[ ] 確認必須（confirmation）経路を確認した
[ ] エラー/キャンセル経路を確認した
[ ] 初回データ取得経路を確認した
[ ] AIアシスタント経路を確認した（通常UIと同じテーブル・フィールドを網羅しているか、usacon/references/architecture-pitfalls.md Pitfall #14参照）

出力フォーマット（全経路マトリクス）:

| データ更新経路 | ファイル:行 | ペイロード | 対応済 |
|---------------|-----------|-----------|-------|
| SSE: event_a  | file.js:123 | { jobId, status } | [ ] |
| Polling       | file.tsx:456 | { job: {...} }    | [ ] |
| REST sync     | file.tsx:789 | { result }        | [ ] |

1.2 SSE/APIイベントのペイロード確認

イベントの 実際のペイロード構造 をソースコードで確認する。 存在しないフィールドを前提にしない。

過去の失敗例:

• eventId が SSE に存在しないのに前提にした（v1）
• toolUseId が action_job_queued に含まれないのに昇格ロジックで使用（v2）
• confirmation_required に toolUseId がないのに仮登録→昇格を前提（v4）

チェックリスト:
[ ] 各SSEイベントの emitEvent() 呼び出し箇所を読み、全フィールドを列挙した
[ ] 各REST APIのレスポンス型を TypeScript 型定義で確認した
[ ] 各APIの実際の戻り値（null 可能性含む）を実装コードで確認した

1.3 既存の型定義確認

新しい型を定義する前に、既存の型定義を必ず確認する。

過去の失敗例:

• AssistantActionJob.status に 'stale' が既に含まれるのに無視（v2, v6）
• ConfirmActionResult.job が null を返し得るのに型が未対応（v4）

チェックリスト:
[ ] 関連する既存の TypeScript 型定義を全て読んだ
[ ] 新しい型が既存の型と矛盾しないか確認した
[ ] API から返される全ての status 値を列挙した

1.4 既存UIの分岐ロジック確認

既存のレスポンシブ分岐・条件付きレンダリングを確認する。

過去の失敗例:

• モバイル xs:'none' でサイドバー全体が非表示になることを考慮しなかった（v1, デザインv3）

チェックリスト:
[ ] モバイル/タブレット/デスクトップでの display 分岐を確認した
[ ] 既存の条件付きレンダリング（mobileView 等）を確認した
[ ] 新しいコンポーネントの配置が既存レイアウトと衝突しないか確認した

1.5 既存CSSのグローバルルール確認

!important 付きのグローバルルールとの競合を確認する。

過去の失敗例:

• [data-theme="nord_light"] * の !important でフォント指定が無効化された（デザインv1）
• .MuiCard-root:not(.process-list-card):hover の !important でカードhoverが上書きされた（デザインv1）

チェックリスト:
[ ] テーマCSS（nord-theme.css, cyberpunk-theme.css）のグローバルルールを確認した
[ ] !important 付きルールとの競合がないか確認した
[ ] 必要に応じて :not() セレクタで除外ルールを追加した
[ ] 使用するフォントが index.html で読み込まれているか確認した

1.6 使用するライブラリ/コンポーネントの仕様確認

推測ではなく、公式ドキュメントまたはソースコードで仕様を確認する。

過去の失敗例:

• MUI Drawer にスワイプ機能があると思い込んだ（SwipeableDrawer が必要）（デザインv3）
• CSS opacity が子要素に継承されることを考慮しなかった（デザインv2）

チェックリスト:
[ ] 使用するMUIコンポーネントのProps型をドキュメントで確認した
[ ] 類似コンポーネントとの違いを確認した（Drawer vs SwipeableDrawer 等）
[ ] CSSプロパティの継承挙動を確認した

Phase 2: 設計時の網羅性チェック（必須）

2.1 全経路マトリクスの記載

Phase 1.1 で洗い出した全経路に対して、設計がカバーしているか確認する。

チェックリスト:
[ ] 全経路マトリクスを設計ドキュメントに記載した
[ ] 各経路に対する処理を明記した
[ ] 「対応不要」の経路にはその理由を明記した

2.2 状態遷移の完全性

バックエンドの状態遷移を正確に追跡する。推測しない。

過去の失敗例:

• stale を「完了」と推測 → 実際は「キャンセル前の中間状態」（v7）
• バックエンドで stale → cancelJob() → cancelled という遷移があることを確認していなかった

チェックリスト:
[ ] バックエンドの状態遷移を実コードで確認した
[ ] 各 status 値の意味と遷移先を列挙した
[ ] フロントエンドの正規化ルールがバックエンドの遷移と整合するか確認した

2.3 Props / インターフェースの整合性

コンポーネント境界を越えた暗黙の依存を作らない。

過去の失敗例:

• dispatch / setSheetOpen を子コンポーネント内で直接呼び、props に未定義（デザインv5）
• sx prop を渡す前提だが Props 型に未定義（デザインv4）

チェックリスト:
[ ] コンポーネントの Props インターフェースに、使用する全 props を定義した
[ ] 親→子の操作はコールバック props 経由にした（dispatch を直接渡さない）
[ ] sx, className 等のスタイル拡張ポイントを Props に含めた

Phase 3: 修正時の品質チェック（レビュー指摘対応時）

3.1 指摘の構造分解

指摘を受けたら、表面的な修正の前に以下を自問する:

1. この指摘が示している「構造的な問題」は何か？
2. 同じ構造的問題が「他の箇所」にも存在しないか？
3. 修正によって「新たに影響を受ける箇所」はどこか？

過去の失敗例:

• stale の扱いが 5 バージョンにわたり形を変えて再発（v2→v5→v6→v7→v8） → 最初に「stale の全体的な扱い方針」を構造的に決めるべきだった
• MiniBar の導線消失が 3 回形を変えて再発（デザインv3→v4→v5） → 「アクセス手段を1つに依存させない」原則を最初に適用すべきだった

3.2 修正の影響範囲確認

修正を加える際に、修正対象のデータ/関数を参照する 全箇所 を確認する。

チェックリスト:
[ ] 修正対象のデータ/関数を grep で全参照箇所を洗い出した
[ ] 各参照箇所で修正の影響が問題ないか確認した
[ ] 「同じデータを別経路で取得している箇所」を重点確認した
[ ] 修正が新たな不整合を生まないか確認した

3.3 JavaScript/TypeScript の仕様確認

以下の頻出ミスパターンに注意する:

Phase 4: データベース・API設計チェック（Issue #925教訓）

4.1 マイグレーションの安全性確認

自動生成マイグレーション（supabase db remote commit / supabase db pull）は、リモートDBの現在の状態をスナップショットとして反映するため、手動変更が意図せず削除されるリスクがある。

過去の失敗例:

• supabase db remote commit で生成されたマイグレーションに、手動追加したカラムやポリシーの削除が含まれていた（Issue #925）

チェックリスト:
[ ] 自動生成マイグレーションに DROP COLUMN / DROP POLICY / ALTER COLUMN DROP が含まれていないか確認した
[ ] 手動追加したカラム・制約・ポリシーが保持されているか確認した
[ ] マイグレーション適用前に git diff で全変更内容を精査した

4.2 空文字列 vs NULL の取り扱い

PostgreSQLでは空文字列''とNULLは別の値。フロントエンドのフォームが空文字列を送信し、DB側のNULL許容カラムに保存されると、IS NULLチェックやCOALESCEが期待通り動作しない。

過去の失敗例:

• フォームの未入力フィールドが空文字列''としてDBに保存され、NULL前提のクエリが正しく動作しなかった（Issue #925）

チェックリスト:
[ ] NULL許容カラムに対して、フロントエンドで空文字列→null変換を実装した
[ ] DB側で空文字列とNULLが混在していないか確認した
[ ] COALESCE / IS NULL を使用するクエリが、空文字列の存在を考慮しているか確認した

Phase 5: マルチハンドラファイルの網羅性チェック（Issue #1016教訓）

5.1 ハンドラ全数列挙

横断的機能（プロンプト注入、認証追加、ログ追加等）をルートファイルに追加する際、 対象ファイル内の 全ルートハンドラ を列挙し、どのハンドラに変更が必要かを明示する。

過去の失敗例:

• gBizINFO注入を「transformationRecognitions.js に追加」と設計 → フルハンドラ（L2068）にのみ実装
• フロントエンドが呼ぶのは個別ステップハンドラ（P1-1-1〜P1-1-4）→ gBizINFOデータが分析に反映されなかった

要注意ファイル（マルチハンドラ）:

チェックリスト:
[ ] 対象ファイル内の全ルートハンドラを grep で列挙した
    → grep -n "router\.\(get\|post\|put\|delete\)" <file>
[ ] 各ハンドラに対して「変更が必要か」を判定した
[ ] フロントエンドがどのエンドポイントを呼んでいるか確認した
    → grep -rn "<endpoint-path>" frontend/src/
[ ] 変更対象ハンドラのチェックリストを作成し、全て消し込んだ

5.2 フロントエンド→バックエンド呼び出し経路確認

バックエンドに変更を加える際、フロントエンドが実際にどのエンドポイントを呼んでいるかを確認する。 設計時の仮定（「このハンドラが呼ばれるはず」）を検証する。

チェックリスト:
[ ] フロントエンドのAPI呼び出し箇所を grep で特定した
[ ] 呼び出されるバックエンドハンドラを正確に特定した
[ ] 「呼ばれないハンドラ」への変更が不要であることを確認した

Phase 6: 入力体験の設計確認（UI入力欄の新規作成・修正時）

UI入力欄の新規作成・修正を含む設計では、以下を計画時に検討すること：

教訓: 文言変更だけで修正を閉じず、実際の入力体験（改行・複数行・IME）まで検証計画に含めること。

チェックリスト:
[ ] 入力欄の用途に応じて input / textarea / contentEditable を選定した
[ ] Shift+Enter 改行の要否を判断し、必要なら実装した
[ ] IME変換中のEnter送信を防止した（compositionstart/end）
[ ] 長文入力時のレイアウト崩れを確認した（max-height, overflow）
[ ] モバイルでのソフトキーボード表示時のレイアウトを確認した

Phase 7: 多段レビュー実行戦略（大規模変更時）

教訓（Issue #1515→#1534）: 設計レビューだけでは空配列truthyの罠・文字列前提結合などの実装バグを検出できない。設計レビューと実装安全性レビューの2段構えで初めてBug-freeに到達できる。

エスカレーション基準

以下のいずれかに該当する場合、Phase 1-6のチェックリストに加えて多段レビューを実施する:

2段レビューの構成

Stage 1: 設計レビュー（6エージェント並列）

• コード構造・仕様整合性・リスク定量化を検出
• 詳細な構成は issue-flow スキルのステップ③-escalatedを参照

Stage 2: 実装安全性レビュー（Codex 1エージェント）

• 「この変更を入れたら他のどこが壊れるか」を検証
• 全呼び出し元を横断的に走査し、型変更の波及を検出

実績数値（Issue #1515→#1534）

チェックリスト:
[ ] エスカレーション基準に該当するか判定した
[ ] 該当する場合、Stage 1（6エージェント設計レビュー）を実施した
[ ] Stage 2（Codex実装安全性レビュー）を実施した
[ ] 全指摘をCRITICAL/BLOCKER/HIGH/MEDIUM/LOWで分類し記録した

チェック深度基準（教訓 #9）

コードチェック・設計レビューでは以下の深度を必ず満たすこと:

• 環境変数は vercel env ls 等で実際の設定を確認したか（推測でOKとしない）
• マッピングや定数は具体的なコード行を引用（ファイルパス:行番号）して検証したか
• 「問題なし」と判定する前に、各確認項目のエビデンスを提示したか
• 概要レベルの構造把握と、詳細レベルの値検証を明確に区別したか

Phase 8: 計画前提の実在性検証（Issue #1638教訓 — 再プランで7カテゴリの欠陥検出）

背景: Issue #1638の実装計画を精密調査で再プランした結果、初回計画に7カテゴリの未検証仮定が含まれていた。 共通する根本原因は「計画の前提が正しいと仮定して検証しなかった」こと。 このPhaseは計画を書いた後に実行し、計画の各前提を実コードと照合する。

8.1 API/ライブラリの能力境界検証

計画でAPI/ライブラリを使用する場合、「存在する」だけでなく「意図した入力を処理できるか」を検証する。

過去の失敗例:

• Claude Vision APIで.xlsxテンプレート解析を計画 → 実際はPDF/画像のみ対応（Issue #1638初回計画）
• ExcelJSプログラマティック解析に変更が必要だった

チェックリスト:
[ ] 計画で使用する各API/ライブラリの入力形式制約を公式ドキュメントで確認した
[ ] 「このAPIにこの形式のデータを渡せるか」を具体的に検証した
[ ] 入力形式が非対応の場合、代替方式を明記した

8.2 内部関数のexport/import境界検証

計画で他ファイルの関数を再利用する場合、module.exports / export に含まれるか検証する。

過去の失敗例:

• collectSubsidyFiles, decodeBase64File, SSEヘルパー(setupSSE, sendSSE, sendSSEError)がsubsidies.js内のローカル関数 → module.exports = router のみで未公開（Issue #1638）
• 計画の前提が崩れ、Sub-Phase 0（共通ユーティリティ抽出）が追加必要に

チェックリスト:
[ ] 計画で再利用する全関数について、定義元ファイルの module.exports / export を確認した
[ ] 未公開の関数がある場合、抽出・公開のサブステップを計画に追加した
[ ] 抽出後の既存呼び出し元への影響（import変更）を計画に反映した

8.3 プロパティ名・インターフェースの正確性検証

計画で使用するプロパティ名やフック戻り値を、実コードと照合する。推測しない。

過去の失敗例:

• selectedCompanyId と記載 → 実際は selectedCompany?.id（useEnterprise()がオブジェクトを返す）（Issue #1638）

チェックリスト:
[ ] 計画で使用する全プロパティ名を、実コードの型定義/フック戻り値で確認した
[ ] useXxx() フックの戻り値の正確な構造（オブジェクト vs プリミティブ）を確認した
[ ] コンテキスト値の取得パターン（useEnterprise, useAuth 等）が実装と一致するか確認した

8.4 MVPスコープの実データ妥当性検証

計画のMVPスコープが、実際のユースケースのデータ形式をカバーするか検証する。

過去の失敗例:

• .xlsx のみ対応でMVP → 実際の補助金申請様式は .doc/.docx が主体 → 実用価値がほぼない（Issue #1638）
• 結果的に .docx/.pptx/.doc まで Phase 1 スコープを拡大

チェックリスト:
[ ] ターゲットドメインの実データ形式・構成を調査した（サンプルデータ、実際のファイル）
[ ] MVPスコープが最も頻度の高いユースケースをカバーしているか確認した
[ ] スコープ外の形式に対するフォールバック（エラー表示、手動対応案内）を計画に含めた

8.5 HTTP/クライアントパターンの明示的選定

新規API/SSE接続を追加する場合、既存パターンとの整合性と使い分けを明記する。

過去の失敗例:

• 既存SSE（補助金検索）はGETだが、新API（申請書自動記入）はPOST+SSE → パターン不一致（Issue #1638）
• axios共通インスタンス vs fetchEventSource vs fetch の使い分けが未明記

チェックリスト:
[ ] 新規APIのHTTPメソッド（GET/POST/PATCH等）を明記した
[ ] フロントエンドの呼び出し方式（axios / fetchEventSource / fetch）を各APIで明記した
[ ] SSE接続の場合、POST+SSEかGET+SSEかを明記し、既存パターンとの差異を注記した
[ ] レスポンス形式（JSON / SSE / バイナリ / 署名付きURL）を各APIで明記した

8.6 本番環境設定の網羅性検証

ローカル開発設定（config.toml等）が本番環境で自動適用されない項目を洗い出す。

過去の失敗例:

• supabase/config.toml にStorageバケット定義 → ローカル専用で本番には反映されない（Issue #1638）
• マイグレーション内でのINSERTまたはDashboard手動作成が別途必要

チェックリスト:
[ ] config.toml / .env.local 等のローカル設定が本番に自動反映されるか確認した
[ ] Storageバケット・Edgeファンクション・Cron等の非マイグレーション項目を洗い出した
[ ] 本番設定手順（Dashboard手動 / マイグレーションINSERT / Vercel環境変数）をテスト計画に含めた

8.7 データパイプラインの完全性検証

計画で使用する関数が、単独で完結するか、前後のパイプライン関数が必要かを検証する。

過去の失敗例:

• buildAnalysisContext() 単体で企業データ取得を計画 → 実際は企業データ取得 → 株主情報付与 → AI分析コンテキスト構築のパイプラインが必要（Issue #1638）
• API二重パターン（axios vs fetch）の使い分けもパイプライン設計の一部

チェックリスト:
[ ] 計画で使用する主要関数の呼び出しチェーンを実コードでトレースした
[ ] 前段処理（データ取得・変換・付与）が計画に含まれているか確認した
[ ] 関数の引数に必要なデータが、計画の前段ステップで確保されているか確認した

Phase 9: Issue突き合わせゲート（2回実行 — Issue #1638教訓）

背景: Issueから実装計画を立てた際、Issueに記載された要件が計画に反映されていない「読み漏れ」が発生する。 また、実装完了後にIssueの受け入れ条件と照合せずにレビューに進むと、要件漏れが最終段階まで残る。 2回の突き合わせ（計画作成後 + 実装完了後）で、要件の脱落を早期に検出する。

正しい順序（必須）

Issue読解 → 計画作成 → 【Gate A: Issue突き合わせ①】 → 実装 → 【Gate B: Issue突き合わせ②】 → レビュー → テスト

Gate A: 計画作成後のIssue突き合わせ（計画投稿前）

計画を作成した後、Issueの全セクションを再読し、以下を照合する:

チェックリスト:
[ ] Issueタイトルの意図が計画に反映されているか確認した
[ ] Issue本文の各要件（箇条書き・チェックリスト項目）を1つずつ計画ステップとマッピングした
[ ] Issue本文に記載された技術的指示（特定のライブラリ使用、特定のパターン適用等）が計画に反映されているか確認した
[ ] Issue本文に添付された画像・スクリーンショット・参考リンクを確認した
[ ] Issueのコメント（追加の要件変更・方針決定）が計画に反映されているか確認した
[ ] Issueの受け入れ条件（Acceptance Criteria）がE2Eテスト計画にマッピングされているか確認した
[ ] マッピングできなかった要件がある場合、計画に追加するか除外理由を明記した

出力フォーマット（要件カバレッジマトリクス）:

| Issue要件 | 計画ステップ | カバー状態 |
|----------|-----------|-----------|
| 要件1: ○○機能 | Step 1B-3 | ✅ カバー |
| 要件2: △△対応 | — | ❌ 未カバー → 追加 |
| 要件3: □□制約 | Step 1A-1 | ✅ カバー |

Gate B: 実装完了後のIssue突き合わせ（レビュー開始前）

実装が完了した後、再度Issueを読み、実装結果と照合する:

チェックリスト:
[ ] Issueの受け入れ条件を1つずつ、実装コードと照合した
[ ] Issueに記載された各機能が実際に動作する状態か確認した（ビルド通過だけでなく）
[ ] Issue本文で言及された特定のエッジケース（エラー時、未入力時、権限不足時等）が実装されているか確認した
[ ] 計画時に「Phase N で対応」と除外した項目が、誤って実装に混入していないか確認した
[ ] 逆に、計画に含まれていたが実装で落ちた項目がないか確認した
[ ] git diff と Issue要件の対応表を作成した

Gate Bの後にのみレビューに進むこと。 Gate Bを通過せずにレビューを開始してはならない。

実行タイミング

トラブルシューティング

関連スキル

• issue-flow - GitHub Issue 実装の自動ワークフロー
• usacon - Usacon プロジェクトの開発ガイド
• codex-autopilot - Codex 自動運転モード
• ui-ux-pro-max - UI/UX デザインガイド

改訂履歴

• 2026-04-03: Phase 8「計画前提の実在性検証」追加（Issue #1638教訓: API能力境界・export境界・プロパティ正確性・スコープ妥当性・パターン整合・本番設定・パイプライン完全性の7カテゴリ）
• 2026-04-03: Phase 9「Issue突き合わせゲート」追加（Issue #1638教訓: 計画作成後+実装完了後の2回照合で要件脱落を早期検出）
• 2026-03-23: Phase 7「多段レビュー実行戦略」追加。エスカレーション基準・2段構え・実績数値を記載（feedback_multistage_review.md + feedback_review_agent_strategy.md教訓）
• 2026-03-23: Phase 1.1にAIアシスタント経路確認項目追加、トラブルシューティングにAIアシスタント行追加（lesson-to-skill棚卸し、Issue #1090/#1092教訓）
• 2026-03-17: Phase 6（入力体験の設計確認）追加、文書品質の前提セクション追加
• 2026-03-04: チェック深度基準（教訓 #9）追加、トラブルシューティングセクション追加
• 2026-03-01: Phase 5 追加（Issue #1016教訓: マルチハンドラファイルのハンドラ網羅性チェック）
• 2026-02-26: Phase 4 追加（Issue #925 の教訓: remote_schemaマイグレーションの落とし穴、空文字列 vs NULL）
• 2026-02-18: 初版作成（Issue #723 の 11 回レビュー・41 件指摘の根本原因分析に基づく）