AITMはソースファイルを読むだけではありません — コードが実際に何をするのかについて、構造化されたクエリ可能なモデルを構築するため、AIは推測をやめ、確認するようになります。

AITMがプロジェクトを理解する仕組み

Behavioral Contracts

コードベースの意味のある機能はすべて、Behavioral Contractとして記録できます。これは機械可読な仕様で、ID、所属するモジュール、1行の動作説明、関係するファイルの正確な一覧、危険領域の警告、そして信頼度スコアを備えています。ContractはプロジェクトごとにローカルのSQLiteデータベースに保存され、AIはコードを1行でも触る前にGraphQLでそれらを照会します。存在しないファイルパスや架空のメソッドが減る最大の理由がこれです — AIは推測する代わりにContractを確認します。

Contractが陳腐化することもありません。マージのたびに、Docsパイプラインステップが変更を自動的に再スキャンし、影響を受けたContractを更新します。

危険領域

各Contractには危険領域を付けることができます — そのコードに触れた場合の影響範囲についての平易な警告です（たとえば「skipフラグを先に確認せずにこれを呼び出さないこと」）。AIは危険領域を事前に読むため、テストが失敗した後ではなく、編集を始める前に、何を壊してはいけないかを把握しています。

ナレッジグラフ

1つのGraphQLエンドポイントの背後には、プロジェクトに関する相互に結び付いた10の信頼できる情報源があります。

• 変数ツリー（BL.*ビジネスロジックのコード、UI.*インターフェースのコード）
• Behavioral Contracts
• DOM要素マップ
• ヒント辞書
• ドキュメントインデックス
• コードマップ — import/export、結合度の高い「god nodes」、モジュールコミュニティ
• テストマップ — UI要素からPlaywrightロケーターへの対応
• スクリーンショット
• バグ
• 上記すべてを結び付けるクロスモジュールエッジ

AIがリポジトリ全体を手当たり次第にgrepする代わりに、1回のクエリで10のすべての情報源にまたがる関連コンテキストを同時に取得できます。

プロジェクトのオンボーディング

プロジェクトを初めてインポートすると、AIが触れる前に、AITMは決定論的な静的プレスキャンを実行します。言語とスタックの検出、完全なコードマップ、data-aitm属性によるDOMの抽出、変数のバックフィル、ドキュメントへのポインターです。その後で初めて、AITMは任意でAIによるパスを実行します — アーキテクチャの探索、モジュール結合のためのgit履歴のマイニング、モジュールごとの詳細なパスです。要するに、リポジトリをインポートすると、最初のTaskが実行される前に、AITMがそれをマッピングします。

DOMマップ + Dev Panel

アプリ内の実際のUI要素にはdata-aitm属性が付けられ、それぞれがトリガーする/トリガーされる効果のエッジと、画面上の位置を示すピクセル単位の矩形マップを持ちます。このマップによって、壊れやすいCSSロケーターではなく、信頼性が高く自己修復するE2Eテストのセレクターが実現します。

Dev Panelの機能

Dev Panelは、独立して動作する、注入可能なJSツールバー（aitm-dev-panel.js）で、AITMが管理するどのプロジェクトも開発中に読み込めます。フローティングでドッキング可能なツールバーで、実行中のアプリ内のdata-aitmが付いたすべての要素にバッジを重ねて表示します。ホバーするとツールチップに要素のコード、タグ、アクション、ハンドラーが表示され、ライブのイベントカウンターが動き続け、小さなChat/Brainstormボックスから実行中のアプリから直接AITMインスタンスにメッセージを送れます。さらに、フォントサイズの調整と、AITM自体のオンライン/オフライン状態インジケーターもあります。パネルは実際のユーザー操作（click/change/input/mount/unmount）をリアルタイムで追跡し、2秒ごとにAITMへ送信します — これによって、AITMはUIのマップを最新の状態に保っています。

パネルには4つのタブがあります。Elements（クリックまたはピン留めした要素。変数コード、Contract、ファイル、危険領域の警告が表示されます。Overlay、Pin / One Pin、Clear Pinsボタンがあります）、Records（記録されたUI要素）、Errors（取得されたJavaScriptエラーとコンソールエラー。AITMでバグTaskに変換できます）、そしてSettingsです。完全なドキュメントは、ヘッダーメニューのHelp → AITM Dev PanelからAITM内で開きます。

AITMがこのWebサイトとは別のマシンで動作している場合は、設定でAitmServer:PublicBaseUrl（例：http://192.168.1.50:3333）を指定してください — ブラウザがaitm-dev-panel.jsを読み込むアドレスです。空の場合はhttp://<page host>:<Port>になります。AITMのアドレスは、後からパネルのSettingsタブで変更することもできます。

Guide & Flow — 要素のビジネスロジックフロー

Dev Panelの要素の行から、Graph、Guide & Flow、App Flowのタブを持つ詳細を開けます。Guide & Flowは、選択した要素を、平易なステップで上位から順に説明します — まずUI要素そのもの、次にその動作を記述するビジネスContract（それぞれ関係する変数付き）です。Copy as Markdownで説明全体をクリップボードにコピーでき、Taskのプロンプトにそのまま貼り付けられます。詳細はContract Explorer & App Flowを参照してください。

プロジェクトごとの有効化と無効化

プロジェクトの共有HTMLシェルに追加する、条件付きの<script>タグ1つだけで済みます。Production以外でのみ表示され、パネルが自動的に正しいプロジェクトを対象とするよう、data-project="<your-project-id>"属性を持ちます。

Blazor Server（.NET 8+）

App.razorでIWebHostEnvironmentをinjectし、scriptタグをIsProduction()で囲みます。

@inject IWebHostEnvironment env

@if (!env.IsProduction())
{
    <script src="http://localhost:3333/aitm-dev-panel.js" data-project="your-project-id"></script>
}

ASP.NET Core Razor Pages

同じパターンです — @inject IWebHostEnvironment envと同じIsProduction()ガードを、共有の_Layout.cshtmlに配置し、上と同じコードブロックを使用します。

Node / Express / TypeScript

HTMLシェルを描画するテンプレート内で、process.env.NODE_ENVで囲みます。

{process.env.NODE_ENV !== 'production' &&
  '<script src="http://localhost:3333/aitm-dev-panel.js" data-project="your-project-id"></script>'}

無効にするには、条件付きのscriptタグを削除するか、単にアプリをProductionで実行します — ガードによって、タグに手を加えなくても自動的に非表示になります。