domain-expert-configuration

ドメインエキスパート向け設定

ドメインエキスパート向けの設定 UI では、複雑なシステム（最適化アルゴリズム、計画エンジン、シミュレーションなど）のパラメーターを、その問題領域に深い知識はあるものの、システム内部については何も知らないユーザーに公開します。

課題：システムのパラメーターは、技術用語（重み、しきい値、フラグ、許容誤差）で定義されています。一方、ユーザーはドメイン用語（待機時間、再試行するタイミング、結果のグループ化方法）で考えます。UI はこの2つの語彙の間を橋渡しし、常にユーザーの言葉を優先する必要があります。

---

核心となる原則：技術用語よりドメイン用語を優先する

すべてのパラメーターラベル、ツールチップ、エラーメッセージでは、パラメーターがシステム内部で何をするかではなく、ユーザーの世界で何を意味するかを説明してください。

技術的なラベル	ドメイン向けのラベル
max_concurrent_jobs	同時に実行するタスクの最大数
enable_auto_retry	失敗したタスクを自動的に再試行する
batch_allocation_threshold	（充足率が）何％になったら新しいバッチを開始するか
request_timeout_ms	リクエストごとの最大待機時間（秒）
enable_fuzzy_matching	あいまい一致を許可する

パラメーターにドメイン向けのラベルを付けられない場合は、そもそもそのパラメーターをユーザーに公開すべきか検討してください。ドメイン用語で説明できないパラメーターは、ユーザー向け UI ではなく、開発者向け設定ファイルに記載するものです。

---

ドメイン概念ごとにグループ化する

パラメーターは、技術的なカテゴリ（真偽値同士、数値同士など）やアルファベット順ではなく、実世界の問題において制御する側面ごとにグループ化してください。

たとえば、処理ツールでは次のようにグループ化できます。

Processing limits
  └─ Maximum tasks at once
  └─ Maximum wait per request
  └─ Memory ceiling

Matching rules
  └─ Allow approximate matches
  └─ Case sensitivity
  └─ Required fields

Batching behaviour
  └─ Batch fill threshold
  └─ Maximum batches

各グループには、そのパラメーターの種類ではなく、タスクのどの側面を制御するのかを説明する短い見出しを付けてください。

---

適切なデフォルト値

すべてのパラメーターには、大多数のケースで正しく動作するデフォルト値を設定してください。すべてデフォルト値のままでも、ユーザーがすぐに妥当な結果を得られるようにする必要があります。

デフォルト値を表示する： フィールドがデフォルト値のときは、その旨を示してください。ユーザーがデフォルト値から変更した場合は、簡単に元に戻せるようにしてください。

Maximum wait per request  [___30___ s]  ← custom value
                          [↺ Reset to default (15 s)]

Batch fill threshold  [_70_ %]  (default)  ← at default

これが重要な理由： ドメインエキスパートは、慣れていないパラメーターにどの値を入力すればよいか分からないことがよくあります。ヒントのない空欄のままだと、入力を飛ばしてシステムを不明な状態のままにするか、適当な値を入力してしまいます。デフォルト値を表示すれば、「特に指定がない限り、システムはこの値を想定します」と伝えられます。

---

ドメイン上の意味に合った入力タイプ

入力タイプは、単にデータ型ではなく、パラメーターが何を意味するかに基づいて選択してください。

パラメーターの性質	入力タイプ	例
二択のルール（オン／オフ）	トグルスイッチ	「自動的に再試行する：[トグル]」
単位が明確な制約付き数値	単位ラベル付き数値入力	「最大待機時間：[___] 秒」
名前付きオプションからの選択	セレクトまたはラジオグループ	「出力形式：[JSON ▾]」
パーセンテージまたは比率	数値入力付きスライダー	「バッチ充足率のしきい値：[━●━━] 70%」
自由入力の識別子	テキスト入力	「ジョブ参照：[___]」

数値入力では単位を必ず表示してください。 単位のない数値を表示してはいけません。単位ラベルは入力欄の隣に配置してください（後置きを推奨：[___] cm。cm [___]ではなく）。

段階的な開示

すべてのパラメーターが同じように重要とは限りません。段階的に表示します。

主要な設定（常に表示）： 最も頻繁に調整される動作を制御するパラメーターです。ドメインの専門家は、これらだけを調整すればタスクの80％を実行できるようにします。

詳細設定（デフォルトでは折りたたみ）： 特殊なケース、微調整、またはあまり一般的でないシナリオ向けのパラメーターです。開示コントロール（「詳細オプション ▾」）の背後に配置します。必要なユーザーだけが開き、必要ないユーザーには表示されません。

開発者／システムパラメーター： ユーザー向け UI には一切表示しません。設定ファイルまたは環境変数で管理します。

何でも入れられる受け皿として、すべてを詳細設定のセクションに入れないでください。頻繁に必要となるパラメーターは、主要な設定に含めます。

---

保存済み設定とセッション設定

多くの運用ツールでは、次のように区別します。

• 保存済み設定： ユーザーが保持する設定（標準の処理設定、標準のルール）です。自動的に読み込まれます。
• セッションごとの上書き設定： 保存済みのデフォルトを変更しない、その実行だけの調整です。

この区別を UI ではっきり示します。ユーザーが1回の実行のためにパラメーターを調整しても、保存済みのデフォルト設定が損なわれる心配がないようにします。

┌─ Configuration ────────────────────────────┐
│  Maximum wait    [30 s]   ← session only    │
│  Retry on fail   [✓]      ← saved           │
│                                             │
│  [Save as default]   [Reset to saved]       │
└─────────────────────────────────────────────┘

---

検証と制約に関するフィードバック

値が無効な場合や、別の設定と競合する場合は、ドメインの用語でユーザーに伝えます。

技術的なエラー	ドメイン用語によるエラー
value out of range [0, 9999]	「待機時間は0～999秒にする必要があります」
constraint conflict: retry=true, fail_fast=true	「自動再試行と最初の失敗時に停止は、同時に有効にできません」
threshold must be < 1.0	「バッチの充填しきい値は100％未満にする必要があります」

検証結果は影響を受けるフィールドの横にインラインで表示します。競合の報告を、ユーザーが送信するまで待たないでください。

相互に影響する設定については、その関係を示します。「自動再試行がオフの場合、最大試行回数の設定は効果がありません」のように説明します。これにより、専門家が有効でないパラメーターの調整に時間を費やすのを防げます。

---

モデルによる提案

モデルが自由記述を設定に変換する場合、その解釈を文章ではなく、同じフォームコントロールで表示します。

• モデルが読み取ったのではなく推測した値には、すべてマークを付けます。ユーザーがそのフィールドを修正すると、マークは消えます。
• どのコントロールを編集しても提案を再実行し、修正による影響が表示されるようにします。
• 選択、並べ替え、件数のカウントはコードで行います。モデルが作成したリストでは、実行によって項目の脱落、統合、または数え間違いが起こることがあります。
• この役割分担をヘルプテキストで説明します。

文章で表示すると、数字を1つ修正するだけでもプロンプトを再入力する必要があります。フィールドにマークを付ければ、1回の操作で修正できます。

---

レビューチェックリスト

• すべてのパラメーターラベルで、技術用語ではなくドメインの用語を使っていますか？
• パラメーターは種類やアルファベット順ではなく、制御するドメインの概念ごとにグループ化されていますか？
• すべてのパラメーターに、目に見えるデフォルト値がありますか？
• 個々のパラメーターに「デフォルトに戻す」操作がありますか？
• すべての数値入力で、単位がフィールドの隣に表示されていますか？
• 入力タイプはドメイン上の意味に合っていますか（真偽値にはトグル、名前付きの選択肢にはセレクト）？
• 詳細パラメーターは、開示コントロールの背後にデフォルトで隠されていますか？
• 保存済み設定とセッションごとの上書き設定の区別は明確ですか？
• 検証結果はドメインの用語でインライン表示されていますか？
• パラメーター間の相互作用（競合、依存関係）は UI で説明されていますか？
• モデルが推測した値は、マーク付きの編集可能なフィールドとして表示され、選択と件数の処理はコードで行われていますか？