[!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が誤動作しにくい、健全な構造」を人間側が先行して設計し、維持すること。その重要性を、今回のリファクタリングは力強く証明しています。