適用レベルガイド

このガイドの設計方針を一度に全部適用する必要はありません。

段階的に進めることで、リスクを抑えながら効果を実感できます。また、「今回は見送る」という判断も、明確な基準があれば正しい選択になります。

成熟度モデル（Lv1〜Lv4）

「どこまでやればいいか」の目安として、4つのレベルを定義します。

レベル	目標	変更範囲	効果
Lv1	確認画面を増やさない	新規開発のみ	将来の負債を防ぐ
Lv2	登録・編集を統合する	UI	画面遷移が減る
Lv3	状態操作を分離する	UI + API	操作が明確になる
Lv4	業務操作を言語化する	DB + API + UI	ルートが整理される

Lv1: 確認画面を増やさない

最小限の第一歩。既存システムには手を入れず、新規開発で確認画面を作らないことから始めます。

やること	やらなくていいこと
新規機能で確認画面を作らない	既存の確認画面を削除する
取り消し機能を検討する	全画面にUndo機能を入れる
「本当に確認画面が必要か」を問う	既存コードを書き換える

ここまでやればOK: 新規開発で確認画面を作らない習慣がつけば、Lv1達成です。

Lv2: 登録・編集を統合する

登録画面・編集画面を詳細画面や一覧画面に統合します。

やること	やらなくていいこと
一覧にインライン追加を導入	複雑なフォームまで統合する
詳細画面に編集モードを追加	リッチエディタが必要な画面を無理に統合
`/new` と `/edit` を統一	既存の全画面をリファクタ

ここまでやればOK: 主要な画面で登録・編集が「その場で」できるようになればLv2達成です。

Lv3: 状態操作を分離する

「保存」と「状態変更」を明確に分離し、一覧から直接状態を変えられるようにします。

やること	やらなくていいこと
状態変更を専用APIに分離	全ての状態をリアルタイム更新
一覧から状態を変更可能に	複雑なワークフローを一気に作り直す
`PATCH /items/:id/status` のようなルート	楽観的UIを完璧に実装

ここまでやればOK: 「保存ボタンを押さなくても状態が変わる」体験ができればLv3達成です。

Lv4: 業務操作を言語化する

業務固有の操作（申請、承認、却下など）を明確なルートとして定義します。

やること	やらなくていいこと
業務操作をルートに反映	全てをCRUDに押し込む
`POST /orders/:id/submit` のような命名	一度に全業務を整理
ルートから「何をするか」が読める	REST原理主義に陥る

ここまでやればOK: ルート一覧を見れば業務が分かる状態になればLv4達成です。

判断表

「これはやっていい？ダメ？」で迷ったときの判断基準です。

確認画面

判定	ケース	理由
❌	社内システムの通常のCRUD操作	取り消しで代替可能
❌	入力ミスを防ぐ目的	確認画面は流し読みされる
🔺	外部APIへの課金が発生する操作	技術的に取り消しが困難な場合のみ
🔺	一括処理（CSVインポートなど）	影響件数の確認として有効
⭕	法的に同意取得が必要	電子契約、金融取引など
⭕	物理的プロセスの開始	印刷、発送、外部通知

判定の読み方

❌ やってはいけない（原則を適用すべき）
🔺 条件付きで許容（代替案を検討した上で）
⭕ 見送ってOK（例外として認める）

登録・編集画面の分離

判定	ケース	理由
❌	単純なフォーム（5項目以下）	インライン化で十分
❌	一覧から直接追加できる内容	画面遷移が無駄
🔺	入力項目が10以上ある複雑なフォーム	モーダルやサイドパネルを検討
⭕	リッチテキストエディタが必要	専用UIが必要
⭕	ドラッグ&ドロップ操作が必要	専用UIが必要
⭕	編集中に他データを参照する必要がある	画面スペースが必要

ステップフォーム

判定	ケース	理由
❌	入力順序に依存関係がない	セクション分割で代替可能
❌	「入力漏れを防ぐ」目的	不足条件の表示で代替
🔺	初回ユーザーのオンボーディング	ただし、慣れたら飛ばせるように
🔺	選択によって後の入力項目が変わる	動的フォームで代替できないか検討
⭕	法的・規制上、順序が定められている	要件に従う

状態と操作の分離

判定	ケース	理由
❌	状態変更のために「編集画面を開いて保存」が必要	一覧から直接変更可能にすべき
❌	statusを変えるために全フィールドをPUT	PATCH `/status` に分離すべき
🔺	状態変更に伴って他のフィールドも変わる	トランザクションとして扱うか検討
⭕	複雑なワークフローで承認者が複数いる	状態遷移の設計自体が必要

よくある質問

実務で必ず聞かれる質問と、その回答です。

「CSV一括登録は確認画面なしでいい？」

回答: 確認画面は残してよい（⭕）

CSV一括登録はこのガイドの前提（インタラクティブなCRUD）とは性質が異なります。

大量のデータを扱う → 事前確認に価値がある
処理時間が長い → 途中でのキャンセルは困難
影響が大きい → 最終確認の価値がある

ただし改善の余地はある:

エラー修正を画面上で行えるように
「何件追加/更新されるか」の差分表示
非同期処理で「待つ画面」をなくす

「法的に確認が必須の業務は？」

回答: 確認画面を残してよい（⭕）

以下は法的・規制上の要件として確認が必要なケースです:

電子契約（電子署名法）
金融取引（金融庁規制）
個人情報の第三者への提供同意
医療情報の取り扱い同意

ポイント: 確認画面を「なくす」のではなく「意味のあるものにする」。

何に同意しているか明確に
形だけのチェックボックスにしない
確認内容を読みやすく整理

「金融・医療システムには適用できない？」

回答: 部分的に適用可能です。

適用可能	慎重に判断
画面名の命名見直し	確認画面の削除
登録・編集の統合	取り消し機能の導入
インライン編集	状態遷移の自動化

規制要件がある部分と、通常のCRUD操作の部分を分けて考えます。

規制対象の操作: 法的要件に従う
通常の管理機能: このガイドを適用可能

例えば、医療システムでも「スタッフ管理」「設備管理」などの管理機能は通常のCRUDであり、このガイドの原則を適用できます。

「既存システムが大きすぎて手が付けられない」

回答: Lv1から始めましょう。

既存システム全体を直す必要はありません。

新規開発から適用: 確認画面を作らない（Lv1）
小さな成功体験: 1つの画面で改善してみる
横展開: 効果を見せて、他の画面にも適用

「全部直す」のではなく「これ以上悪くしない」から始めると、心理的なハードルが下がります。

「チームメンバーを説得できない」

回答: 数字と具体例で示しましょう。

抽象的な「UXが良くなる」では伝わりません。

伝わらない	伝わる
「UXが悪い」	「確認画面で10秒×50回/日=8時間/月の無駄」
「モダンにしたい」	「画面遷移が3→1になり、問い合わせが減る見込み」
「技術的負債」	「セッション管理が不要になり、テストが書きやすくなる」

詳しくは説得テンプレートを参照してください。

どのレベルを目指すか

チームやプロジェクトの状況によって、目指すレベルは変わります。

状況	推奨レベル
新規プロジェクト	Lv2〜Lv3 を最初から
既存システムの改善	Lv1 から段階的に
レガシーシステムの保守	Lv1（これ以上悪化させない）
リプレイスプロジェクト	Lv4 を目指す

重要: Lv1で止まっても「失敗」ではありません。

「確認画面を増やさない」という習慣がつくだけでも、将来の負債を防ぐ効果があります。

補足

このガイドは「すべてをシンプルにしろ」とは言っていません。

必要な複雑さは残す
不要な複雑さは減らす
「今回は見送る」も正しい判断

判断の基準を明確にすることで、「なんとなく」ではなく「理由があって」 その設計を選んだと言えるようになります。