| 🌐 English | 🌐 日本語 |
AI コーディングは、初回生成の正確さよりも、
誤りをどれだけ安定して修正できるか（Fixability） によって生産性が決まります。
そしてその修正能力を左右するのが、
AI が状況を正しく理解するための情報量と明確さ（Semantic Transparency） です。
このフレームワークは、
AI コード生成の安定性を 「Fixability × Semantic Transparency」 という
2 つの軸で体系的に説明するために設計されています。
テクニカルコンサルタント兼開発者の立場で AI コーディングエージェントを活用する中で、以下の課題が見えてきました。
この問題を構造的に説明可能にしたいという考えから出発した説明モデルです。
「AI が未熟だから間違える」のではなく、
「AI が正しい判断を下すための情報が不十分」
この視点を持つことで、「何を AI に伝えたから、この結果になったのか」を、
個人の勘やおまじないではなく、文脈の設計不備として説明可能になります。
このサイトでは、以下の要素の概要を紹介します。
AI コード生成で大切なのは「一回で正しいコードを出すこと」ではなく、
「間違えたときに正しく修正できるかどうか」 です。
修正ループが安定して収束するほど、AI の出力品質と作業スピードが向上します。
AI が正しく修正するには、状況を理解するための材料が必要です：
これらが揃うほど、AI の誤推論が減り、修正ループが安定します。
この 2 つは独立ではなく強く結びついています：
つまり、Fixability は AI の能力だけでなく、Semantic Transparency は人間側の情報設計の問題。
プロジェクトごとに、AI が誤推論しやすいポイントを体系的に洗い出します。
入力：
出力：
プロジェクトの言語・バージョン・ライブラリ・実行環境を入力すると、
AI が誤推論しやすいポイントと対策を自動で洗い出す
AI モデル非依存の診断プロンプトを提供しています。
フレームワークの理論的背景と思考プロセスを探索します。
詳細なドキュメント、診断プロンプト、サンプルは
GitHub リポジトリで公開しています。
| ポイント | 説明 |
|---|---|
| 課題 | AI コード生成の不安定さは「AI の未熟さ」ではなく、文脈情報の欠落が原因 |
| 鍵 | 修正ループの安定性（Fixability） |
| 解決策 | 意味論の透明性（Semantic Transparency）を高める |
| 診断 | 9軸診断プロンプトでプロジェクトごとのリスクを事前把握 |
「AI をどう使うか」ではなく 「AI と人間の情報のズレ」 を意識することで、
AI コーディングの生産性と品質を安定的に高めることができます。
AI コーディングエージェントの登場で、AI がコードを生成する時代が来ました。
しかし、AI が生成したコードがプロジェクトの文脈に合わなかったり、エラー情報を渡しても修正を繰り返して泥沼化するケースが増えています。
このような状況について、こんな声も聞かれます：
しかし、「個人の経験則（勘）」や「プロンプトのおまじない（運）」に頼っている限り、プロジェクトの生産性は運任せになり、スケールしません。
本フレームワークの視点：
AI に完璧を求めるのではなく、
AIと人間の間にある「情報の不透明さ」をエンジニアリングで制御下に置く
誤推論（Mis-inference）の定義：
モデルの学習過程の誤りではなく、推論フェーズにおける文脈選択の誤り。
つまり、AI が推論時に、プロジェクトの文脈に適さない知識を選択してしまう現象。
この視点により、「何を AI に伝えたから、この結果になったのか」を、
個人の勘ではなく、構造的に説明可能にできます。
AI が誤推論しやすい領域を、以下の 9つの評価軸 で分類しました。
（9軸は意図的に独立させていません。相互に影響し合う構造になっています）
Community Consistency
コミュニティの実務慣行のばらつきが、AI の文脈選択を誤らせる部分
例：.NET と .NET Framework の混線、ASP.NET MVC と Minimal APIs の流派差
Documentation Consistency
公式・非公式ドキュメントの不一致が、AI の知識参照を誤らせる部分
例：API ドキュメントの古いバージョン、ブログ記事の非推奨な書き方
Practice Consistency
実務の揺らぎ（書き方・慣習・構成）が、AI のコード生成を混乱させる部分
例：データベースマイグレーション手順の違い、命名規約のばらつき
Dependency Stability
依存ライブラリの更新頻度・破壊的変更が、AI の推論を不安定にする部分
例：Node.js のメジャー版バージョンアップ、Python パッケージの互換性破壊
API Consistency
API の一貫性の欠如が、AI の誤った呼び出しを誘発する部分
例：同じ機能が複数の方法で実装されている、パラメータ順序が異なる
Ecosystem Consistency
フレームワーク・ツールチェーン間の差異が、AI の推論を混乱させる部分
例：ビルドツール（Maven/Gradle）、テストフレームワーク（Jest/Vitest）の選択肢
Static Semantic Service
コンパイル時に AI が参照できる意味論の豊かさ・一貫性
例：型システム、AST、静的解析 API（Roslyn, tsserver など）
Runtime Semantic Service
実行時に観測できる意味論の安定性・決定性
例：例外、動的型、実行時型情報の有無
Core Semantic Consistency
言語仕様そのものの一貫性
例：歴史的経緯・後方互換性ポリシー・文化的価値観による意味論の揺らぎ
Community Consistency での誤推論ポイント：
AI に与えるべき対策：
Community Consistency での誤推論ポイント：
AI に与えるべき対策：
重要な気づき：
プロジェクト固有の文脈を詳しく与えるほど、診断が詳しく、対策が実用的になります。
本フレームワークが強力な理由：
AI コーディングの安定性を、
技術・言語仕様・AI モデル・プロジェクト構造の観点から
体系的に説明するために開発されたフレームワークです。
著者： Masaki Honda
（テクニカルコンサルタント、MS-DOS の頃から 40 年以上のプログラミング経験）
ライセンス： MIT License
自由に使用・改変・配布できます。詳細は LICENSE を参照。
初版公開： 2025/12/29
本フレームワークは思考実験として公開しており、実証的検証は進行中です。
コミュニティによる拡張・改善を歓迎します。