model-first-reasoning

Model-First Reasoning（MFR）

推論や実装を行う前に、明示的な問題モデルを構築することを必須とする、厳密な方法論です。このモデルは凍結された契約となり、以降のすべての作業を規定します。

Kumar & Rana（2025）「Model-First Reasoning LLM Agents: Reducing Hallucinations through Explicit Problem Modeling」（arXiv:2512.14474）に基づいています。

MFR が機能する理由

ハルシネーションは、単に誤った記述を生成することではありません。問題領域の明確なモデルなしに推論を行ったことを示す症状です。

推論が構造を生み出すのではなく、構造に基づいて推論が行われます。その構造が暗黙的または不安定な場合、推論の信頼性は低下します。MFR は「ソフトな記号的グラウンディング」を提供し、厳格な形式主義を押し付けることなく、推論を安定させるのに十分な構造を与えます。

中核となる原則

フェーズ 1 では MODEL を作成します。フェーズ 2 では、MODEL の範囲内でのみ推論・実装を行います。

これにより、推論の過程で場当たり的な判断や制約の見落とし、問題の定義に基づかない振る舞いの捏造が生じるという、よくある失敗を防ぎます。

必ず守るルール

1. **フェーズ 1（モデル）**では、コードや解決手順は一切作成せず、形式的なモデルのみを作成します
2. **フェーズ 2（実装）**では、新しいエンティティ、状態、アクション、制約を追加してはいけません
3. モデルにない要素が必要な場合は、MODEL INCOMPLETE と追加すべき内容をそのまま出力し、そこで停止します
4. API や依存関係を捏造してはいけません。提示されていない場合は、不明点について質問するか、STUB と明記したスタブを作成します

契約としてのモデル

モデルを作成した後、コーディングの前にMODEL AUDITを実施します。

監査項目

項目	説明
網羅性	すべてのユーザー要件が、制約、目標／受け入れ基準、またはアクションの事前条件／効果のいずれかに、ちょうど 1 つずつ反映されている
操作可能性	計画で必要となるすべての操作が、アクションとして含まれている
整合性	制約同士が矛盾せず、アクションの効果が不変条件に違反しない
テスト可能性	すべての制約に、少なくとも 1 つのテストオラクルがある

監査項目のいずれかに不合格となった場合は、合格するまでモデルを修正します（引き続きフェーズ 1）。

凍結ルール

監査に合格したら、モデルを読み取り専用の信頼できる情報源として扱います。

実装中に情報の不足に気づいた場合は、次のようにします。

1. MODEL PATCH（最小限の変更）を出力します
2. 更新されたモデルを使用して、フェーズ 2 を最初からやり直します

検証

モデルを作成した後、model.json に保存し、バリデーターを実行します。

python scripts/validate-model.py model.json

終了コード：

• 0 = 有効。フェーズ 2 に進めます
• 1 = 構造が無効（修正して再試行してください）
• 2 = 有効ですが、不明点があります（フェーズ 1 の後で停止してください）

出力形式

フェーズ 1：MODEL

モデルは、自然言語、半構造化テキスト、または JSON で表現できます。柔軟性によって準拠しやすくなります。重要なのは、表現が明示的で、検査可能で、安定していることです。

コード生成タスクでは、以下の構造化形式を推奨します。参考として MODEL_TEMPLATE.json を使用してください。

{
  "deliverable": {
    "description": "What we're building",
    "files_expected": ["path/to/file.ts", ...]
  },
  "entities": [
    {"name": "EntityName", "description": "...", "properties": [...]}
  ],
  "state_variables": [
    {"name": "varName", "type": "...", "initial": "...", "description": "..."}
  ],
  "actions": [
    {
      "name": "actionName",
      "description": "...",
      "preconditions": ["..."],
      "effects": ["..."],
      "parameters": [...]
    }
  ],
  "constraints": [
    {"id": "C1", "statement": "...", "type": "invariant|precondition|postcondition"}
  ],
  "initial_state": ["description of starting conditions"],
  "goal": ["acceptance criteria"],
  "assumptions": ["things we assume to be true"],
  "unknowns": ["questions that must be answered before proceeding"],
  "requirement_trace": [
    {
      "requirement": "<verbatim from user>",
      "represented_as": "goal|constraint|action",
      "ref": "C1|action_name|goal_item"
    }
  ],
  "test_oracles": [
    {"id": "T1", "maps_to": ["C1"], "description": "how to verify constraint"}
  ]
}

重要：unknowns が空でない場合は、フェーズ 1 の後で停止します。不明点が解決するまで実装してはいけません。

フェーズ 1.5：MODEL AUDIT

次の内容を返します。

{
  "audit_pass": true|false,
  "issues": [
    {"type": "coverage|operability|consistency|testability", "detail": "..."}
  ]
}

audit_pass が false の場合は、停止してフェーズ 1 に戻り、モデルを修正します。

フェーズ 2：実装

凍結されたモデルのみを使用します。

A）計画

各ステップが定義済みアクションのインスタンスである、番号付きの手順を作成します。

Step 1: [action_name]
  - Preconditions check: [list which preconditions are satisfied]
  - Effects applied: [what state changes]
  - Constraints check: [C1, C2, ...]

B）コード

deliverable.files_expected に記載されているすべてのファイルを作成します。

モデル要素	コードへの反映
entities / state_variables	型、インターフェース、データモデル
actions	検証と明示的な失敗時の動作を備えた関数／モジュール
constraints	実行時チェック、防御的な解析、不変条件

C）テスト

すべての test_oracles を実装します。すべての制約を、少なくとも 1 つのテストで網羅する必要があります。

D）検証マップ

各制約について、次の内容を記録します。

• コード内で適用される箇所（ファイル：行）
• その制約を対象とするテスト

MFR を使用する場面

MFR が最も効果を発揮するのは、次のような場合です。

• 複雑な状態機械 — 遷移が有効でなければならない場合
• 不変条件を伴うビジネスロジック — 決して破ってはならないルールがある場合
• データ変換 — 入出力の契約が重要な場合
• 複数ステップのワークフロー — 各ステップ間に依存関係がある場合
• セーフティクリティカルな機能 — バグが大きな損失につながる場合
• 共同で作成する仕様 — モデルがドキュメントとして機能する場合

使用すべきでない場面： 明示的なモデル化のオーバーヘッドが、そのメリットを上回るような、単純な単一ステップのタスク。

他の推論戦略との関係

MFR は競合するものではなく、補完するものです。

• Chain-of-Thought と併用する場合：Phase 2 で CoT を使い、モデルに基づいて段階的に推論します
• ReAct と併用する場合：アクションが操作する永続的な状態としてモデルを扱います
• プランニングエージェントと併用する場合：モデルは、プランナーが推論する対象となるドメイン仕様を提供します

MFR は、制約の多いドメインにおけるあらゆる推論戦略の堅牢性を高める基盤レイヤーを提供します。

ワークフローの例

User: Build a shopping cart that enforces: max 10 items, no duplicate SKUs,
      total can't exceed $1000

You: [PHASE 1: MODEL]
{
  "entities": [
    {"name": "CartItem", "properties": ["sku", "price", "quantity"]}
  ],
  "constraints": [
    {"id": "C1", "statement": "cart.items.length <= 10", "type": "invariant"},
    {"id": "C2", "statement": "all SKUs in cart are unique", "type": "invariant"},
    {"id": "C3", "statement": "sum(items.price * items.quantity) <= 1000", "type": "invariant"}
  ],
  "actions": [
    {
      "name": "addItem",
      "preconditions": ["cart.items.length < 10", "sku not in cart", "new total <= 1000"],
      "effects": ["item added to cart"]
    }
  ],
  ...
}

[PHASE 1.5: MODEL AUDIT]
{
  "audit_pass": true,
  "issues": []
}

[PHASE 2: IMPLEMENTATION]
// Now implementing strictly from the model...

覚えておくこと

モデルは余計な負担ではありません。モデルそのものが仕様です。複雑な推論における失敗の大半は、推論ではなく表現に起因します。推論自体は適切でも、不完全または不安定な問題の理解に基づいて行われていたのです。

モデルを外部化することで、前提を検証可能にし、制約を適用可能にし、エラーを診断可能にします。モデルは、意図と実装をつなぐ契約になります。

まずモデル化します。その後で推論します。この順序を逆にしてはいけません。