デモプログラムは“動く仕様書”である──AIKernel が示した設計ドキュメントの力
AIKernel.NET 正典 v0.1.1 における設計ドキュメントとデモプログラムの意味を、Provider / Backend / DI / fallback / Operator / Observer の責務分離を通じて解説します。ドキュメントが契約として機能し、デモが正典実装として問題解決を導いた実例を紹介します。
公開日: 2026年6月12日 著者: 拓也 (@TkySoftware) カテゴリ: Architecture, .NET, AI Infrastructure, Software Engineering, Developer Experience
昨日の記事では、AIKernel.NET エコシステムの 正典 v0.1.1 について、型システムによる Fail-Closed、Interface-Led Architecture、そして AI 時代におけるソフトウェア工学の背骨について書きました。
今日は、その思想をもう少し実装寄りの観点から掘り下げます。
テーマは、設計ドキュメントとデモプログラム です。
多くの開発現場では、ドキュメントは「あとで読むもの」「実装が終わってから整えるもの」「忙しくなると更新されなくなるもの」として扱われがちです。
デモプログラムも同様です。
「とりあえず動かすためのサンプル」 「初心者向けの入口」 「本番実装とは別物」
そう見なされることが少なくありません。
しかし、AIKernel.NET において、設計ドキュメントとデモプログラムはそのような補助物ではありません。
設計ドキュメントは 契約（Contract） です。 デモプログラムは 動く仕様書 です。
そして、その両者が揃ったとき、実装者だけでなく AI もまた、仕様に照らして自律的に調査し、判断し、問題の所在を特定できるようになります。
これは、AI 時代の開発体験を大きく変える力を持っています。
1. なぜ「ドキュメント」と「デモ」が重要なのか
ソフトウェア開発において、設計思想はしばしば暗黙知になります。
なぜこのクラスが存在するのか。 なぜこの責務はここに置かれているのか。 なぜ直接呼び出さず、Interface を経由するのか。 なぜ失敗時に例外を投げず、fallback に倒すのか。
実装者の頭の中では筋が通っていても、それが言葉になっていなければ、チームにも、未来の自分にも、AI にも伝わりません。
特に AIKernel.NET のように、AI コンポーネント、GPU 実行基盤、Web 実行環境、ローカル実行環境、Provider、Backend、Operator、Observer が絡み合う基盤では、設計の意図が失われた瞬間に、システム全体の意味論が崩れます。
たとえば、ある処理が CPU に fallback したとします。
それは正常な安全機構なのか。 GPU Backend が検出できていない異常なのか。 Provider の初期化に失敗しているのか。 DI コンテナに必要な実装が登録されていないのか。 あるいは、Observer が状態を誤って解釈しているのか。
ドキュメントがなければ、これは単なる「動かない問題」です。
しかし、設計ドキュメントがあれば、問題は契約違反として読めるようになります。
デモプログラムがあれば、理想状態と現在の実装を比較できます。
つまり、ドキュメントとデモは、単なる説明ではありません。
システムの意味論を復元するための座標軸 なのです。
2. 設計ドキュメントは AI のための“契約”である
AIKernel.NET における設計ドキュメントは、人間のためだけに存在しているわけではありません。
むしろ、AI 時代において重要なのは、ドキュメントが AI に読ませるための契約 として機能することです。
AI は、コードだけを見ても設計意図を完全には理解できません。
コードには「何が書かれているか」はあります。 しかし、「なぜそうあるべきか」は、必ずしも明示されていません。
そこで必要になるのが、設計ドキュメントです。
AIKernel.NET の設計ドキュメントには、たとえば次のような契約が書かれます。
- Provider は外界の不確実性を受け止める境界である。
- Backend は実際の実行能力を提供する低層の実装である。
- Provider は Backend を直接生成せず、DI によって注入されるべきである。
- GPU が利用できない場合は、安全に CPU fallback へ倒す。
- Operator は計算構造を評価する中核であり、副作用を抱え込まない。
- Observer は状態、テレメトリ、互換性、監査を担当する。
- 不明な状態や危険な状態は Fail-Closed に扱う。
これらは、単なる設計メモではありません。
実装が従うべき 憲法 です。
そして、この憲法が明文化されているからこそ、AI はコードを読むときに、次のような判断ができます。
「この Provider は Backend を DI から受け取っていない。したがって、設計契約に反している可能性がある」
「この Web 実行層は GPU 能力を認識するための bridge を持っていない。したがって、Provider が GPU 対応と判定できない可能性がある」
「この処理は Operator の内部に外界依存を持ち込んでいる。責務境界が崩れている可能性がある」
これは非常に重要です。
AI に自律的な調査をさせるためには、単にコードを渡すだけでは足りません。
何を正とするのか を示す契約が必要です。
AIKernel.NET における設計ドキュメントは、その契約として機能します。
3. Provider / Backend / DI / fallback の設計思想
AIKernel.NET の実行基盤を理解するうえで、特に重要なのが Provider / Backend / DI / fallback の関係です。
この四つは、見た目には単なる実装パターンに見えるかもしれません。
しかし、実際には AIKernel.NET の OS 的な世界観を支える中核です。
Provider は外界との境界である。
Backend は実行能力である。
DI は能力の配線である。
fallback は統治である。
この四行に、AIKernel.NET の実行基盤の本質が凝縮されています。
Provider は「外界との境界」である
Provider は、AIKernel.NET が外界と接続するための境界です。
たとえば、モデル実行、ファイルアクセス、GPU 実行環境、ブラウザ実行環境、ネットワーク越しの推論基盤など、外側の世界は常に揺らぎます。
存在するかもしれない。 存在しないかもしれない。 使えるかもしれない。 権限が足りないかもしれない。 環境によって挙動が違うかもしれない。
この不確実性を、AIKernel.NET の中心部へそのまま流し込んではいけません。
Provider の責務は、その不確実性を境界で受け止め、型と契約によって内側へ渡せる形に整えることです。
Backend は「実行能力」である
Backend は、実際の実行能力を提供する低層のコンポーネントです。
GPU を使うのか。 CPU を使うのか。 Web 実行層を使うのか。 ネイティブ実行層を使うのか。
そうした具体的な能力は Backend に閉じ込められます。
重要なのは、Provider が Backend を勝手に生成しないことです。
Provider が自分で Backend を new してしまえば、その瞬間に抽象境界は崩れます。
どの Backend を使うのか。 どの実装を注入するのか。 どの環境ではどの能力を有効化するのか。
それは DI コンテナと構成層が管理すべき責務です。
DI は「能力の配線」である
DI は、単にテストのための Mock 差し替え機構ではありません。
AIKernel.NET における DI は、能力の配線です。
Provider は契約を知っている。 Backend は能力を持っている。 DI はその二つを結びつける。
この構造によって、AIKernel.NET は実行環境の違いを吸収できます。
ローカルではある Backend を注入する。 Web では別の Backend を注入する。 GPU が使える環境では GPU Backend を注入する。 使えない環境では CPU Backend を注入する。
そして、この配線が欠けていれば、Provider は正しい能力を認識できません。
その結果、システムは安全側に倒れます。
つまり fallback します。
fallback は「失敗」ではなく「統治」である
AIKernel.NET において、fallback は単なる代替処理ではありません。
それは Fail-Closed の一種です。
Fail-Closed とは、簡単に言えば 「安全だと確認できないものを、成功として扱わない」 という考え方です。
GPU が使えると確認できないなら、CPU に倒す。 zero-copy が成立すると確認できないなら、安全なコピー経路に倒す。 外部 bridge が存在すると確認できないなら、GPU 対応とはみなさない。 責務境界が不明なら、実行能力を過信しない。
これは「何でも止める」という意味ではありません。
むしろ逆です。
危険な楽観主義で進むのではなく、確認済みの安全な経路だけを通す。 そのために、必要であれば低速でも安全な実行経路へ退避する。
それが AIKernel.NET における fallback です。
カーネルは、未確認の能力を信頼してはいけません。 カーネルは、曖昧な状態を成功として扱ってはいけません。 カーネルは、危険な楽観主義ではなく、安全な悲観主義で世界を統治すべきです。
4. デモプログラムは“動く仕様書”である
ここで、デモプログラムの意味が重要になります。
デモプログラムは、単に「API の使い方を示すサンプル」ではありません。
AIKernel.NET におけるデモは、正典実装（canonical implementation） です。
つまり、設計ドキュメントに書かれた契約が、実際のコードとしてどのように接続されるべきかを示す、動く仕様書です。
ドキュメントは、構造の意味を説明します。 デモは、その構造が実際にどう配線されるかを示します。
Provider はどこで作られるのか。 Backend はどのように DI へ登録されるのか。 fallback はどこで判定されるのか。 Operator はどこまで純粋性を保つのか。 Observer はどの境界で状態を観測するのか。
これらは文章だけでは伝わりきりません。
コードとして動く形で示されて初めて、実装者は「この構造が正典なのだ」と理解できます。
そして面白いことに、デモプログラムの本当の価値は、最初に読んだときには分からないことがあります。
実装者がまだ設計思想に追いついていない段階では、デモは少し遠回りに見えるかもしれません。
「なぜこんなに分けるのか」 「なぜ Provider が直接 Backend を持たないのか」 「なぜ DI を挟むのか」 「なぜ fallback の経路をここまで明示するのか」
そう感じることもあるでしょう。
しかし、実際に複雑な問題にぶつかり、GPU が認識されない、Web 側で zero-copy が成立しない、責務境界が混ざる、といった問題を経験すると、突然デモの意味が見えてきます。
あの構造は冗長ではなかった。 あの分離は美学ではなく、統治のために必要だった。 あの DI は形式ではなく、能力を注入するための契約だった。
デモプログラムは、実装者が成長したときに、もう一度読み返されることで真価を発揮します。
それはチュートリアルではありません。
未来の自分に向けて置かれた、動く設計思想 なのです。
5. 実際の開発で、ドキュメントとデモが問題解決に貢献した例
ここからは、実際の開発中に起きた問題を抽象化して紹介します。
固有のプロダクト名や内部プロジェクト名は出しません。
重要なのは、個別の現象ではありません。
設計ドキュメントとデモが、どのように問題を可視化し、解決へ導いたかです。
5.1 GPU が有効にならず、CPU fallback に落ち続けていた問題
ある実装で、GPU を利用できるはずの環境にもかかわらず、処理が常に CPU fallback に落ちる問題がありました。
最初に見ると、これは単なる環境依存の問題に見えます。
ドライバが悪いのか。 GPU ランタイムが初期化できていないのか。 Backend 側の検出処理にバグがあるのか。 Provider の判定条件が厳しすぎるのか。
しかし、設計ドキュメントを読み返すと、問題の見え方が変わりました。
そこには、Provider と Backend の関係が明確に書かれていました。
Provider は外界との境界であり、Backend は実際の実行能力である。 そして Backend は、Provider の内部で勝手に生成されるものではなく、DI によって注入されるべきである。
この契約に照らして実装を見直すと、原因は明らかでした。
GPU Backend が存在しないのではありません。 GPU Backend を Provider に注入していなかったのです。
つまり、Provider は GPU を使えないと判断したのではありません。
そもそも GPU 能力を受け取っていなかったのです。
そのため、設計どおり安全側に倒れ、CPU fallback に進んでいました。
ここで重要なのは、fallback が正しく機能していたことです。
システムは壊れていたのではありません。 未注入の能力を勝手に信頼しなかっただけです。
そして、デモプログラムを確認すると、そこでは Provider と Backend が明確に分離され、DI によって接続されていました。
このデモの構造が、正典でした。
実装がデモと違っていた。 だから問題が起きていた。
この事実は、設計ドキュメントとデモが揃っていたからこそ、短時間で特定できました。
5.2 Web 側で zero-copy が false のままになる問題
別の実装では、Web 実行層において zero-copy が期待どおり有効にならず、常に false と判定される問題がありました。
zero-copy は、データ転送の無駄を減らし、GPU 実行や高効率なパイプラインを成立させるうえで重要な性質です。
しかし、これも最初は単純なフラグ設定の問題に見えました。
判定条件が間違っているのか。 Web 側の初期化順序が悪いのか。 GPU 実行環境が見えていないのか。 Provider の能力検出が不足しているのか。
ここでも決定打になったのは、設計ドキュメントでした。
ドキュメントには、Web 実行環境において GPU 能力を扱うには、ホスト側との JS bridge が必要であると書かれていました。
この契約に照らして実装を見直すと、問題は明確でした。
Provider が GPU を認識するために必要な bridge が存在していなかったのです。
そのため、Provider は GPU 実行環境を安全に確認できませんでした。
結果として、zero-copy を成立可能な経路として扱えなかったのです。
ここでも、AIKernel.NET の挙動は一貫しています。
確認できない能力は、存在するものとして扱わない。 bridge がないなら、GPU 対応とはみなさない。 zero-copy が保証できないなら、安全な経路に倒す。
この判断は、まさに Fail-Closed です。
解決方針も、デモプログラムから導かれました。
デモでは、外界との接続点が Provider として分離されていました。
その構造を参考にし、Web 側の bridge も内部に埋め込むのではなく、外部 Provider として切り出す方針にしました。
これにより、Web 固有の接続事情をコアに混ぜ込まず、AIKernel.NET の責務境界を保ったまま拡張できる見通しが立ちました。
5.3 Provider / Operator / Observer の責務が混ざっていた問題
もう一つ重要だったのは、Web 側の実装で Provider / Operator / Observer の責務が混ざり始めていたことです。
これは、複雑な実装ではよく起きます。
Provider が外界との接続を担当するだけでなく、計算の判断まで持ち始める。 Operator が純粋な計算構造の評価だけでなく、環境依存の分岐まで抱え込む。 Observer が監視やテレメトリだけでなく、実行経路の制御に入り込みすぎる。
最初は小さな便宜に見えます。
「ここで判定した方が早い」 「この情報はここにあるから、ついでに処理しよう」 「今は動かすことを優先しよう」
しかし、その小さな妥協が積み重なると、システムは急速に読みづらくなります。
どこが外界との境界なのか。 どこが純粋な計算なのか。 どこが観測なのか。 どこが統治判断なのか。
それが曖昧になると、AIKernel.NET は OS 的な基盤ではなく、ただの便利ライブラリの集合に戻ってしまいます。
このときも、デモプログラムが基準になりました。
デモでは、Provider / Operator / Observer の責務が明確に分離されていました。
Provider は外界を扱う。 Operator は計算構造を評価する。 Observer は状態を観測し、監査可能にする。
この構造に照らして Web 側の実装を見直すことで、混ざっていた責務を再び分離する方向へ整理できました。
重要なのは、デモが「こう書くこともできます」という参考例ではなかったことです。
デモは、AIKernel.NET の意味論を保つための正典でした。
だから、実装が迷ったときに戻る場所になったのです。
5.4 設計ドキュメントが、AI の自律的な調査を可能にした
今回の一連の問題解決で特に印象的だったのは、設計ドキュメントが AI にとっても有効に機能したことです。
AI にコードだけを読ませても、ある程度の調査はできます。
しかし、コードだけでは「現在の実装が正しい設計からズレているのか」「それとも別の実装方針として許容されるのか」を判断しづらい場面があります。
そこで設計ドキュメントが効きました。
Provider と Backend は分離されるべきである。 Backend は DI で注入されるべきである。 WebGPU の利用には JS bridge が必要である。 Provider / Operator / Observer は責務を混ぜてはいけない。 不明な能力は fallback へ倒すべきである。
こうした契約が明文化されていたため、AI はコードを仕様に照らして読むことができました。
これは、単なる検索ではありません。
仕様に基づく診断です。
「この実装は契約に対してどこが違うのか」 「現在の挙動はバグなのか、それとも Fail-Closed として正しいのか」 「正典デモではどう接続されているのか」 「この構造に戻すなら、どの責務をどこへ移すべきか」
AI は、設計ドキュメントを契約として読み、デモプログラムを正典実装として参照しながら、原因を絞り込むことができました。
これは、AIKernel.NET が目指す開発体験そのものです。
AI にすべてを任せるのではありません。 AI に無秩序な推測をさせるのでもありません。
契約を与える。 境界を与える。 正典を与える。
そのうえで、AI に調査と判断を任せる。
ここに、AI 時代のソフトウェア工学の新しい形があります。
6. 設計思想の美しさは、問題が起きたときに証明される
優れた設計は、順調なときには目立ちません。
すべてが動いているとき、人は構造のありがたみを忘れます。
Provider と Backend を分ける必要があるのか。 DI を挟む必要があるのか。 fallback を明示する必要があるのか。 Operator と Observer を分ける必要があるのか。 デモを正典として維持する必要があるのか。
順調なときには、これらは少し厳格に見えます。
しかし、問題が起きた瞬間に、その価値は明らかになります。
GPU が有効にならない。 zero-copy が成立しない。 Web 側の責務が混ざる。 Provider が能力を認識できない。 AI が原因を推測しきれない。
そのとき、設計ドキュメントは地図になります。 デモプログラムはコンパスになります。
ドキュメントが「本来どうあるべきか」を示し、デモが「実際にどう接続すべきか」を示す。
この二つが揃っていることで、実装者は迷子になりません。
そして AI もまた、迷子になりません。
まとめ：AIKernel の設計思想がもたらす開発体験
AIKernel.NET が目指しているのは、単なる AI ライブラリではありません。
それは、AI コンポーネントを OS 的に統治するための基盤です。
LLM や GPU や Web 実行環境のような不確実な外界を、Provider で受け止める。 実行能力を Backend に閉じ込める。 能力の接続を DI によって明示する。 確認できない状態は fallback に倒す。 計算構造は Operator に保つ。 観測と監査は Observer に分離する。
そして、そのすべてを設計ドキュメントという契約と、デモプログラムという動く仕様書によって支える。
この構造があるからこそ、AIKernel.NET は変化に耐えられます。
実装が増えても、意味論が崩れない。 実行環境が増えても、責務境界が保たれる。 問題が起きても、契約に照らして原因を追える。 AI に調査を任せても、判断の基準が失われない。
設計ドキュメントは、過去の説明ではありません。 未来の実装を守る契約です。
デモプログラムは、飾りのサンプルではありません。 正典をコードとして固定する、動く仕様書です。
美しい設計とは、図として美しいものではありません。
問題が起きたときに、開発者と AI を正しい場所へ連れ戻してくれる構造。
それこそが、AIKernel.NET における設計思想の美しさです。
AIKernel.NET は Bing Webmaster Tools / IndexNow に対応しています。
記事更新は検索エンジンへ即時通知され、最新情報が迅速にインデックスされます。