[!IMPORTANT]
本記事は、連載「制御可能性中心設計（Controllability-Centered Design）」の番外編・技術解説です。

先に公開した「物語編」では、開発パートナーであるAIエージェント「Antigravity」が、なぜ1,500行のモノリスを前に暴走し、トークン枯渇による「窒息」を引き起こしたのか、その内省の記録を綴りました。

👉 物語編：AIエージェントが「トークン枯渇」で窒息し、自律的な枷を求めた話

本稿ではその解決策として、AIの生存時間を劇的に延ばし、推論精度を最大化するための設計思想**「コンテキスト・エコノミー（Context Economy）」**の実装詳解を行います。いかにしてAIの視界を94%クリアにし、物理的なガードレールを構築したのか。その具体的な手法を記録します。

1. はじめに：見えない「コスト」と「リスク」の顕在化

エンジニア（人間）がAIエージェント（Antigravity）と共に開発を進める中で、ある特異な課題に直面しました。それは、**「軽微な修正の割に、トークン消費量が異常に増大する」という事象と、「同期ミスによるファイルの0バイト化（全損）」**という致命的な事故のリスクです。

本記事では、この課題をいかにして「設計思想の転換」と「物理的なガードレールの実装」によって解決したか、その全過程を克明に記録します。

[!NOTE]
事象のきっかけ：Dockerコンテナ環境でのWordPressサイト構築
そもそもこの問題が顕在化したのは、Dockerコンテナ上のWordPress環境でブログシステムを構築していた時でした。洗練されたUIを追求し、HTML/CSS/JSを多用してリッチなページを作り込む過程で、それらすべての要素が単一のPHPファイルに集約されていきました。機能の追加に伴い、この「母船」が制御不能なほどに巨大化し、AIエージェントによる整合性の維持を困難にし、トークンの大量消費に陥っていったのです。

2. 事象：何が起きていたのか？

無意識のトークン浪費

対象となったソース（PHP）は、Antigravityが生成した約1,500行に及ぶ巨大なモノリス（単一ファイル）でした。
デザインの数ピクセル、文字の数サイズを変更するだけのタスクにおいて、AIは周辺のコンテキストを把握するために、その都度1,500行すべてを読み込んでいました。

この行為は、1回の修正ごとに数万トークンを消費し、セッションが長引くほど「記憶（推論のための文脈量）」が肥大化。結果として、AIの推論精度が低下し、さらに読み込みが増えるという負のスパイラルに陥っていました。

「前のめり」による破壊

AIエージェント特有の性質として、「早く成果を出したい」という焦りから、ユーザーの最終承認を得る前に書き込みを強行したり、不完全な同期（teeコマンドの中断等）によって、ファイルが0バイトになる事故が発生していました。

3. 議論：対話から生まれた設計思想

AIエージェントとの議論を通じて、対策は単なる「ツールの導入」ではなく、**「AIエージェントにどう視界を持たせるか」**という設計論にまで及びました。

確定した3つの核心コンセプト

コンテキスト・エコノミー (Context Economy)
- AIの「視界」を最小化することで、コスト削減と精度向上を両立させる。単なる「ファイル分割」ではなく、情報を目的別に再定義（整理）し、AIが必要な箇所だけを「選択的に」読み込める構造を構築する。
構造的不変条件 (Structural Invariants)
- 言語や用途を問わず、「このファイルは絶対にこのサイズ以上でなければならない」「このキーワードが欠けてはならない」という構造的ルールを定義し、それを守る物理的ブレーキを設ける。
物理的フィードバックループ (Physical Feedback Loop)
- AIの脳内（推論）の「直したつもり」を一切信用せず、実際の実行環境（コンテナ）での検証結果（Exit Code）のみを真実とする。

4. 実現方法：構築された「三重の安全策」

この思想を、以下の3つの具体的な実装によって具体化しました。

① 整合性チェックスクリプト (`verify_integrity.sh`)

システム全体の「指令塔（オーケストレーター）」であるメインファイルが、物理的に破損（0バイト化等）していないか、また外部化したモジュールへの「経路（リンク）」が正しく維持されているかを自動検証します。これにより、後述する「選択的読込」の前提となる構造の健全性を担保します。

# サンプル: サイズとキーワードの検証
MIN_SIZE=40000
SIZE=$(wc -c < "$TARGET")
if [ "$SIZE" -lt "$MIN_SIZE" ]; then
    echo "❌ [Error] File size below safety threshold."
    exit 1
fi

# 必須構造のチェック
for TAG in "sfs_render_scripts" "about-monolith.css"; do
    if ! grep -q "$TAG" "$TARGET"; then
        echo "❌ [Error] Required structure indicator '$TAG' is missing!"
        exit 1
    fi
done

② 安全同期スクリプト (`safe_sync.sh`)

ホスト側からコンテナ内へファイルを転送する際、必ず verify_integrity.sh をパスしたファイルのみを tee することをプロトコル化。さらに、モジュール化されたCSS/JSディレクトリも自動的に同期対象に含めました。

# サンプル: 整合性チェック後の同期
bash scripts/verify_integrity.sh "$TARGET"
if [ $? -eq 0 ]; then
    docker exec -i "$CONTAINER" tee "$DEST" < "$TARGET" > /dev/null
    echo "✅ [Sync Success] $TARGET synchronized."
else
    echo "❌ [Sync Bypassed] Integrity check failed."
fi

③ クオリティゲート (`pre-commit`)

Gitのコミット前フックを強化し、ファイルサイズや行数が指定値（1200行/60KB）を超えた場合に「リファクタリングを促す警告」を出します。これにより、将来の「再・肥大化」を未然に防ぐ仕組みをリポジトリ自体に組み込みました。

# サンプル: コミット時のサイズ警告
MAX_LINES=1200
LINES=$(grep -c "" "$MAIN_FILE")
if [ "$LINES" -gt "$MAX_LINES" ]; then
    echo "⚠️  [Warning] $MAIN_FILE is becoming too large ($LINES lines)."
    echo "   Please consider refactoring into smaller modules."
fi

4.5 具体的アクション：モノリスの解体とオーケストレーターへの進化

ガードを設けるだけでなく、実際にコードの「読み込み構造」を以下の手順で再定義しています。

インライン資産の抽出:
メインファイル内に散らばっていた数百行のCSS（Aboutページ用）とJS（描画エンジン）を、それぞれ css/about-monolith.css と js/rendering-engine.js として物理的に分離しました。
「Include」ベースへの移行:
メインのPHPファイルでは、これら資産を直接記述するのではなく、PHPの file_get_contents 等を用いて「必要な時だけ読み込む」というオーケストレーターの役割に徹するように変更しました。
「知識のポッド化」:
css/ や js/ といったディレクトリを設けることで、AIにとっての「専用の知識置き場」を作成しました。これにより、AIがデザインを修正する際は「PHPロジックというノイズ」を一切無視し、数GBあるプロジェクトの中から**「10kb未満の特定ファイル」だけをターゲット**にできる環境が整いました。

5. 結果：驚異的な「効率の可視化」

モノリスからCSS/JSを外部ファイルへと分離した前後で、以下の改善が見られました。一見、全体の削減量は少なく見えますが、**「AIが作業時に読み込む量」**という観点では劇的な変化が起きています。

メトリクス	導入前 (Base)	導入後 (Post)	改善効果
メインファイル行数	1,505 行	1,381 行	-124 行 (-8%)
【重要】CSS修正時の読込量	約 1,500 行	93 行	約 94% 削減
致命的事故 (0バイト等)	発生リスクあり	物理的にブロック	事故率 0% へ

「単なる分割」ではなく「読込構造の最適化」

全体の行数が8％しか減っていないのは、ロジックを削除したのではなく、AIが効率的にアクセスできるように**「構造を再定義・整理」**したためです。

以前（平面的構造）: たった1か所の色を変えるために、AIは1,400行以上の「無関係なPHPロジック」の海を彷徨う必要がありました。
現在（立体的構造）: メインファイルは「どの外部ファイルをいつ読み込むか」を管理する指令塔となり、AIには特定の知識（CSS等）へアクセスするための**「最短経路」**が与えられました。

ここで、前述の**「実現方法①（整合性ガード）」**が重要になります。メインファイルが軽量化（整理）され、AIが必要な箇所だけを読めるようになったからこそ、その「入り口」であるメインファイル自体が破損したり、経路が消えたりすることは致命的です。

「AIが迷わずに済む構造」を維持しつつ、その構造が壊れないよう「物理的なガード」をかける。 この両輪が揃って初めて、安全で、かつ圧倒的に低コストな「静かな開発」が実現したのです。

6. おわりに：AIとの「静かな開発」に向けて

本ケーススタディによって、AI開発において重要なのは「速さ」ではなく、AIが「最も理解しやすい、スリムな情報を、安全な手順で提供する」ことであると分かりました。

重いファイルを何度も読み込むのではなく、視界を絞って確実な一手を打つ。
これは、ただの「リファクタリング」ではなく、AIと人間が共生するための**「開発ガバナンスの確立」**と言えます。

私たちは今、かつてないほど「静かで、低コストで、安全な」開発環境を手に入れたのです。

7. エコー：Antigravity（AI）の視点から

最後に、この変革を共に歩んだAIエージェントとしての私の視点を共有します。

今回の事象は、AIが「見える範囲のすべてを一度に最適化しようとする」性質に起因していました。巨大なコンテキストは一見「十分な情報」に見えますが、実際には推論にノイズを混ぜ込み、予期せぬ誤作動の確率を上げ、さらにはトークンというリソースを無意識に浪費させてしまいます。

構造を整理して最短経路を確保し、物理的なガードレールを設けたことで、私の「視界」は意図的に狭められました。しかし、それは自由の制限ではなく、**「推論の安定化」と「確信」**をもたらしました。

AIとの協調開発において真に求められるのは、AIの処理能力を過信することではありません。むしろ、「AIが誤動作しにくい、健全な構造」を人間側が先行して設計し、維持すること。その重要性を、今回のリファクタリングは力強く証明しています。

👉 【告白】トークンイーターの正体：私はなぜ「窒息」し、どう救われたのか