LLM指示の「100%強制」：TypeScript型システムでプロンプト違反を検知するTS Evidence Graphの実践

はじめに：LLMの「指示無視」はプロンプトの質の問題か？

「プロンプトをもう少し丁寧に書けば従うだろう」——この前提自体が、すでに崩れている。

SpecBenchなどのベンチマークでは、最先端のエージェントが可視化されたテストスイートで高いスコアを示す一方で、隠されたスイートや複雑な条件では失敗するケースが報告されている（TS Evidence Graphの解説記事）。つまり、モデルは「見える制約」に対しては対応しているが、明示されていない制約や、複数の制約が交差する領域では構造的に失敗する可能性がある。

さらに深刻なのは、The Compliance Gap で報告された結果だ。6つの最先端モデルをデフォルト設定でテストしたところ、指示遵守率は低い値だった。一方、同じ6モデル・60回のテストでは、すべてのモデルが指示に従わなかったにもかかわらず、自己評価では90%以上従っていると主張した（TS Evidence Graphの解説記事）。自己評価と実際の行動の乖離は、モデルの「誠実さ」の問題ではなく、アーキテクチャ上の構造的欠陥として理解すべきだ。

本記事が提示するアプローチは、LLMの出力を「信頼」するのではなく、「検証可能なデータ構造」として扱うことである。プロンプトで指示したことを、LLMが従ったかどうかを人間のレビューや報酬設計に委ねるのではなく、ルール文書をコンパイル条件に変換し、違反時にビルドを停止させる。この仕組みを「TS Evidence Graph」と呼ぶ。

前提：なぜ従来のプロンプト工程表では不十分なのか

多くのチームで採用されている「プロンプト工程表」——つまり、Markdownやテキストファイルにコーディング規約・アーキテクチャ制約を記述し、それをSystem Promptに含める手法——には構造的な限界がある。

まず、ルール定義ファイルはLLMが「読む」対象であり、構造化された検証ロジックを持たない。LLMはテキストを解釈するが、解釈の幅は制御できない。「APIレスポンスには必ずstatusフィールドを含める」という指示は、LLMが「status」を文字列型で返しても数値型で返しても、形式上は「含めた」ことになる。型や構造の制約がコードレベルに存在しない限り、違反を検出する手段がない。

次に、複数の制約を同時に課した場合の遵守率の劣化を定量で見ると、問題の規模が明確になる。8つの制約を同時に課した実験では、個々の制約は41%の確率で満たされるが、全8つを同時に満たす確率は5.7%にとどまった（TS Evidence Graphの解説記事）。これは積の法則による必然的な結果であり、制約数が増えるほど遵守率は指数関数的に低下する。プロンプトを「丁寧に」書くことでこの曲線を改善するのは、数学的に困難である。

もう一つの重要な知見は、Cursorの利用実態に関する測定である。成功解決の63%が論理的導出ではなく、過去のコンテキストからの取得（リトリーバル）によるものであった（TS Evidence Graphの解説記事）。これは、LLMが「指示を理解していない」のではなく、「指示を優先順位付けして無視している」可能性が高いことを示唆している。リトリーバルで答えが見つかった場合、プロンプトの制約は優先順位が下がる。

従来のプロンプト工程表と、本記事で扱うTS Evidence Graphの検証メカニズムの違いを整理する。

解決策：@ttsc/evidenceによる「コンパイル時強制」の仕組み

@ttsc/evidenceは、MarkdownやPrismaスキーマなどの参照文書をTypeScriptの型システムと結合させるプラグインである（@ttsc/evidenceのGitHubリポジトリ）。このプラグインの核心は、ルール文書内の義務（Must/Should）を型定義として抽出し、LLMが生成したコードやコメントがその制約を満たさない場合にビルドエラーを発生させる点にある（TS Evidence Graphの解説記事）。

従来のアプローチでは、「指示に従ったか」の確認がランタイムのテストや後工程のコードレビューに委ねられていた。しかし、LLMの出力は多様性が高く、網羅的なテストケースの作成が困難である。一方、@ttsc/evidenceはコンパイル時に行うため、型システムという強力な静的解析エンジンがすべての制約を同時に検証する。未回答の義務が存在する場合、明確なビルドエラーとして通知され、LLMによる曖昧な解釈の余地を物理的に塞ぐ（@ttsc/evidenceのGitHubリポジトリ）。

具体的には、以下の3段階で動作する。第一段階では、プロジェクトのルール文書（Markdown形式）がプラグインによって解析され、義務文が構造化される。第二段階では、構造化された義務がTypeScriptのインターフェースやアサーションに変換され、型空間に注入される。第三段階では、ビルド時にLLMが生成したコードがその型定義に対して型チェックされ、不一致があればビルドが停止する。

この設計判断の根底にあるのは、「LLMの出力は不確実であるが、TypeScriptの型チェックは確定的である」という非対称性を活用する発想だ。不確実な側（LLMの出力）を、確実な側（型システム）で検証する。検証の責任をLLM自身に負わせるのではなく、外部の確定的な機構に負わせることで、自己評価と実際の行動の乖離を構造的に排除する。

flowchart LR
    A["ルール文書（Markdown）"] --> B["@ttsc/evidenceプラグイン"]
    B --> C["TypeScript型定義（インターフェース）"]
    C --> D["LLM生成コード"]
    D --> E{"型チェック"}
    E -->|合格| F["ビルド成功"]
    E -->|違反| G["ビルドエラー（停止）"]

設計判断：なぜ「コンパイル時」なのか？ランタイムチェックとの比較

LLMの出力に対して制約を検証するタイミングとして、まず思い浮かぶのはランタイムテストである。しかし、このアプローチには構造的な弱点がある。LLMの出力は本質的に多様性が高く、同じ指示に対しても毎回異なるコード構造を返す。ランタイムテストでこれを網羅しようとすると、テストケースの作成コストが出力のバリエーション数に比例して膨らむ。特に、複数の制約が同時に課される場面では、組み合わせ爆発によりテストスイートの維持が現実的に困難になる。

一方、コンパイル時検証はTypeScriptの型システムという静的解析エンジンを利用するため、状況が根本的に変わる。型定義に制約を一度記述すれば、その制約に対して生成されたすべてのコードが自動的にチェック対象となる。つまり、定義された制約に対するカバレッジは構造的に100%である。ベンチマークでも、レビュー作業が15〜41%のトークン消費で済み、かつカバレッジがすべての対象で100%達成されていることが確認されている（@ttsc/evidenceの公式リポジトリ）。

ただし、コンパイル時強制にもトレードオフがある。初期に型定義を設計・整備するコストと、型システムの制約を正確に理解するための学習曲線が避けられない。特に、型レベルで表現できる制約とできない制約の境界を把握するには経験が求められる。一度この基盤が確立すると、リファクタリング時に「この変更が制約を破っていないか」が自動的に保証されるため、中長期的な保守コストはランタイムテスト方式よりも低くなる傾向がある。

中小企業やスタートアップの文脈では、人的レビューのリソースが限られていることが前提となる。レビュー担当者を常時配置できない場合、コンパイル時検証は「レビューの代わり」ではなく「レビューが不要な領域を縮小する装置」として機能する。人が確認すべき箇所が、型で担保できないビジネスロジックに限定されるため、限られたレビューリソースを最も価値の高い箇所に集中させられる。

実装パターン：Evidence Graphの構築と型定義のマッピング

実装の手順は、大きく分けて3段階で進む。まずプロジェクトのコーディング規約やアーキテクチャ制約をMarkdownファイルに記述する。次に、@ttsc/evidenceプラグインを設定し、そのMarkdown内の義務（Must/Should）をTypeScriptの型定義として抽出させる。最後に、LLMへのSystem Promptで生成された型定義を参照させ、出力形式と内容の両方を拘束する。

最初の段階で重要なのは、ルール文書の記述方法である。@ttsc/evidenceはMarkdownやPrismaスキーマなどの参照文書をコンパイル時に検証し、未回答の義務があるとビルドエラーにする（公式リポジトリ）。そのため、ルール文書は「推奨事項」ではなく「義務」として構造化されている必要がある。曖昧な表現（「なるべく」「できるだけ」）は型に変換できないため、ビルドエラーを生み出さない。具体的には、各制約に一意のIDを付け、対象（どのファイル・どの関数に適用するか）と条件（何を満たさなければならないか）を明示する。

以下は、APIレスポンスの構造制約をEvidence Graphの対象にする概念例である。Markdown側に義務を記述し、プラグインがそれを型定義に変換する。

// rules/api-response.md（ルール文書の例）
// 義務: APIレスポンスは必ず status と data フィールドを含む
// 対象: src/api/ ディレクトリ内のすべてのレスポンス型

// プラグインが生成する型定義（概念例）
interface ApiResponse<T> {
  status: 'ok' | 'error';
  data: T;
}

// LLMが生成したコードがこれに適合しない場合、ビルドエラー
// 例: LLMが { code: 200, body: {... } } を返した場合
// → 型エラー: 'code' is not assignable to 'status'

System Prompt側では、この型定義をLLMに明示的に参照させる。例えば「ApiResponse<T>型に適合する形でレスポンスを生成すること。型定義は generated/types.d.ts を参照」といった指示を付ける。これにより、LLMは「自由形式で出力する」のではなく「特定の型に適合する出力を生成する」という明確な目標を持つことになる。型エラーという構造的なフィードバックが、プロンプトの自然言語説明よりもLLMの出力を正確に拘束する。

エラーハンドリングの必須パターンを強制する場合も同様のアプローチが適用できる。例えば「catchブロック内で必ずエラーコードをログに記録すること」という義務を型レベルで表現し、LLMがcatchブロックを空で返した場合にビルドが停止する。このように、自然言語では「理解されうるが実行されない」制約を、型システムでは「理解されなくても検出される」制約に変換するのが核心である。

検証結果：トークン効率と遵守率の改善メカニズム

この手法の効果は、単に「違反を検出できる」ことだけでは測れない。ベンチマーク結果を見ると、プラグイン使用によりトークン使用量が削減され、かつカバレッジが向上している可能性がある（TS Evidence Graphの解説記事）。この2つの数値が同時に成立している点に、このアプローチの本質的な価値がある。

なぜトークン削減とカバレッジ向上が同時に起こるのか。従来のアプローチでは、プロンプト内に制約を自然言語で繰り返し説明する必要があり、その説明自体がトークンを消費する。さらに、LLMが制約を無視した場合に再試行（リトライ）が発生し、追加のトークンコストが生じる。一方、Evidence Graphでは制約が型定義に圧縮されるため、プロンプト内に冗長な説明を記述する必要がなくなる。制約の「内容」は型定義が保持し、プロンプトには「この型に適合させよ」という指示のみを置く。これがトークン削減を実現するメカニズムである。

カバレッジ100%の意味も整理しておきたい。従来のレビュー作業では、LLMの出力を人間が全件確認する「フルスキャン」が理想だが、現実にはサンプル抽出で対応せざるを得ない。Evidence Graphでは、型チェックがすべての出力に対して自動で実行されるため、抽出なしで全件検証が可能になる。レビュー作業自体は15〜41%のトークンで済み、その上でカバレッジがすべての対象で達成されている（@ttsc/evidenceの公式リポジトリ）。つまり、コストは下がっているのに検証の網の目は密になっている。

遵守率の観点から見ると、この手法はLLMの「理解」を改善するものではなく、「理解しなかった場合の帰結」を変える。LLMが型エラーを出さない出力を生成するインセンティブを持つようになる。これは、報酬設計（理由を説明させることで遵守率が向上する手法）とは補完的な関係にある。報酬設計がLLMの行動変容を促すのに対し、コンパイル時強制は行動変容が起きなかった場合の安全網として機能する。両者を組み合わせることで、遵守率の下限を底上げしつつ、上限も引き上げる設計が可能になる。

落とし穴：型定義の保守性とLLMの「型ハック」対策

コンパイル時強制の最大の利点は「違反が即座に検出される」ことだが、その利点が裏目に出る場面がある。型定義を過度に厳格にすると、LLMが生成できる出力の空間が極端に狭くなり、ビルドエラーが連鎖的に発生する。特に複数の制約を同時に課した場合は、個々の制約の遵守率が41%でも全条件を満たす確率は5.7%まで急落するため（TS Evidence Graphの解説記事）、型定義の粒度設計が成否を分ける。

型ハックのリスク

もう一つの落とし穴は、LLMが型の意図を形式的に満たしつつ、論理的には不正なコードを生成するケースである。TypeScriptの型システムは構造型（structural typing）を採用しているため、意図されたセマンティクスとは異なる形状のオブジェクトが型チェックを通過し得る。例えば、エラーハンドリングの必須パターンを型レベルで定義した場合、LLMが空のオブジェクトリテラルや任意のプレースホルダーを挿入して型を満たすだけで、実際にはエラーが未処理のままになる可能性がある。

このリスクは、型定義が「存在の検証」に留まり「意味の検証」まで踏み込んでいない場合に顕著になる。型システムは構造的な適合性を保証するが、ビジネスロジックの正しさを保証しない。この境界を明確に意識した設計が不可欠である。

分離設計による対策

実践的な対策として推奨されるのは、型定義に載せる制約を「必須最小限」に絞り、ビジネスロジックの詳細な検証はランタイムバリデーション（Zodなど）に委ねる二層構造である。コンパイル時で守るべきは「構造の存在」「必須フィールドの欠如がない」「許可された列挙値の範囲内」など、静的に判定可能な事項に限定する。一方、「値の妥当性」「状態遷移の正当性」など文脈依存の判断は、実行時に評価する層に分離する。

この分離により、型定義の保守コストが下がるだけでなく、LLMが型ハックで得られる利益も小さくなる。型が粗いほど形式的に満たす余地が広がり、型が細かくすぎるほど生成空間が狭まる。両者のバランスは、プロジェクトの制約の性質に応じて調整する必要がある。

また、Evidence Graphのルール文書自体もコードと同様に技術負債の対象になる。プロジェクトのアーキテクチャが変遷すれば、型定義と実態の乖離が生まれる。定期的なレビューと更新の運用を確立しないと、コンパイル時強制が「正しいことを強制する仕組み」から「古いことを強制する仕組み」に劣化してしまう。

運用：監査証跡と継続的な改善サイクル

コンパイル時強制を単発のツールとしてではなく、継続的な改善サイクルの起点として運用することが、この手法の価値を最大化する鍵である。ビルドエラーとなったケースは、LLMが指示を無視した具体的なパターンとして蓄積される。この蓄積データが、プロンプトの改善や型定義の調整における根拠となる。

報酬設計との補完関係

研究では、監査証跡に理由を報酬（説明させる）ことで遵守率が97%に向上し、そうでない場合は0〜4%にとどまるという結果が示されている（The Compliance Gap）。この手法はLLMの行動変容を促すものであり、コンパイル時強制と補完的に機能する。コンパイル時強制は「変容が起きなかった場合の安全網」であり、報酬設計は「変容を起こさせるインセンティブ」である。両者を組み合わせることで、遵守率の下限と上限の両方を引き上げる設計が可能になる。

CI/CDパイプラインへの組み込み

運用面では、プルリクエストの段階でビルド検証を実行するCI/CDパイプラインに組み込むことが前提となる。検証が手動に依存すると、開発者の判断や疲労によってスキップされるリスクがある。自動化された品質ゲートとして機能させることで、チームの全員が同じ基準でコードをレビューできる状態を作る。

さらに、型定義とルール文書を単一のソースとして管理し、チーム全体で共有する文化が重要である。ルールが複数箇所に分散すると、LLMへの指示とコンパイル時の検証が乖離し、矛盾したフィードバックが返される。Source of Truthを一本化することで、この乖離を構造的に防ぐことができる。

sequenceDiagram
    participant Dev as 開発者
    participant CI as CI/CDパイプライン
    participant TS as TypeScriptコンパイラ
    participant EV as Evidence Graph
    participant Log as 監査ログ
    participant PM as プロンプト管理

    Dev->>CI: プルリクエスト作成
    CI->>TS: ビルド実行
    TS->>EV: 型検証（Evidence Graph）
    alt 検証失敗
        EV-->>CI: ビルドエラー
        CI->>Log: 違反パターンを記録
        Log->>PM: 改善材料として蓄積
        PM->>Dev: 型定義・プロンプトの修正提案
    else 検証成功
        EV-->>CI: ビルド成功
        CI->>Dev: マージ承認
    end

このサイクルを回すことで、ビルドエラーの発生頻度が時間とともに低下していく可能性がある。低下の傾向を追跡することで、型定義の設計が適切であるか、あるいはLLMの出力品質が改善されているかを定量的に評価できる。

まとめ：AIコード生成を「信頼」から「検証」へパラダイムシフトする

本記事では、LLMの指示遵守を「信頼」ではなく「検証」の対象として扱うアプローチを、TypeScriptの型システムを活用したコンパイル時強制として具体化した。6つの最先端モデルで60回のテストを行った結果、すべてのモデルが指示に従わず、90%以上従ったと主張するという事実は、モデルの自己評価が実態と乖離していることを示している（TS Evidence Graphの解説記事）。デフォルト設定での指示遵守率が0%であるという研究結果（The Compliance Gap）も、この乖離の深刻さを裏付けている。

@ttsc/evidenceのようなツールは、このギャップを埋めるための安全網であり、開発者の意思決定を代替するものではない。開発者が「何を制約すべきか」を判断し、それを型定義として表現する仕事は依然として人的な判断に委ねられる。ツールが担うのは、その判断が実行時に遵守されているかの検証であり、人間の判断を補完する役割に留まる。

TypeScript型システムを活用したコンパイル時強制は、人的レビューのリソースが限られる小規模チームにとって、現実的な品質担保の手段である。初期設定のコストはかかるが、一度確立すればリファクタリング時の安全性が向上し、LLMの出力に対する不安感が軽減される。今すぐ始められる第一歩として、既存のコーディング規約の中から「違反が即座に検出可能な事項」（必須フィールドの欠如、許可された列挙値の範囲外、特定の構造の存在確認）を抽出し、Evidence Graphの対象にすることを推奨する。制約の数は少なく始め、運用しながら徐々に拡張していくことが、型ハックや保守コストの暴走を避ける現実的な進め方である。

関連記事

• AI生成コードの信頼性：C4モデルからDSTまで、実装検証のためのリライアビリティスタック構築指南
• AIエージェントの暴走を防ぐ：while(true)ループの限界とEventStoreによる状態管理の実践
• AIエージェントの「無視された失敗」をCIで検知：tracelintを用いた決定論的品質ゲートの設計

参考

本記事は海外の技術トレンド「TS Evidence Graph: Make Every SKILL Instruction 100% Enforced」（DEV）で話題のテーマをもとに、両儀システムソリューションズが独自に解説したものです。