リポジトリ分離はAIへの「最強の減法設計」である：テキスト負債を削ぎ落とす生存戦略

はじめに

画像処理ロジックがメインリポジトリに混在すると、AIがNode.js依存の重いライブラリとCloudflare Workers制約を混同してコードを生成します。
サムネイル処理を別リポジトリに分離し、アセットをCloudflare R2に外部化することで、AIに「言わなくていいこと」を物理的に削減できます。

AIのために設定を増やしすぎていませんか？

「AIが賢く動くように」とREADMEや設定ファイルを丁寧に作り込み、プロンプトを洗練させようと努力した。
しかし、機能が増えるたびに指示も増え、AIがどのルールを優先すべきか迷い始める場面に直面した。
場当たり的なプロンプトの追加でその場は凌いだが、気づけば設定自体が保守不可能な「テキスト負債」に変わっていた。

この記事をお勧めしない人

プロンプトを1行増やすだけで、AIが常に完璧に動くと信じている人
巨大なモノリスリポジトリこそが、管理の正解であると考えている人
「言わなくていいこと」よりも「言うべきこと」を増やすのが設計だと思っている人

もし一つでも当てはまらないなら、読み進める価値があるかもしれません。

膨れ上がる「指示」という名の負債

指示系統が複雑化したプロジェクトでは、AIが「否定の指示」を読み解くことにリソースを浪費し始める。
本来のビジネスロジックとは無関係な「環境の制約」にAIの脳内メモリが占有され、コード生成の精度が目に見えて低下する。
人間がAIの誤解を訂正するためだけに時間を費やす、「AIのための介護」という本末転倒な事態を招く。

「物理的な境界」がもたらす開発の研鋭化

物理的なリポジトリ分離により、AIに「言わなくていいこと」を強制的に増やし、脳内メモリを100%解放する明るい未来があります。
「3つの聖域」という判断基準を用い、プロンプトに頼らず「物理적境界線」でAIを専門家へと覚醒させる設計図を手に入れられます。
この「減法設計」は、筆者が運営する本番環境のブログにおいて、最小限の設定で最高精度のコード生成を実現し、その実効性を証明済みです。
本記事の内容は、既存のプロンプトエンジニアリングの枠を超えた、巷の情報では決して得られないAI時代の生存戦略です。

このブログもそうでした

筆者も、エッジ環境特有の制約と重厚なライブラリの共存に悩み、設定ファイルの肥大化という「情報のゴミ屋敷」に直面した経験があります。
この記事では、テキスト負債を削ぎ落とし、AIを「鋭利な専門家」として再定義するための、明日から試せる減法設計のTipsをまとめました。
AIとの共進化を「引き算」で加速させたい方は、ぜひ詳細な設計思想を確認してください。

開発の進捗

Before: 画像処理ロジックがブログ本体のリポジトリに混在し、依存関係が複雑化していた
Current: 画像処理専用リポジトリを分離し、アセット管理をCloudflare R2へ完全外部化した
Next: 他の「重いNode.js依存」タスクについても、同様の分離判断指標を適用し、母船の純度を保つ

具体的なタスク

Before: エッジ環境（Cloudflare Workers）でのビルドエラーと闘いながら、画像処理ライブラリを騙し騙し使っていた
Current: 物理的にリポジトリを分けることで、エッジ環境の純度を保ちつつ、画像処理をNode.js環境で実行可能にした
Next: 分離したリポジトリごとに、AIエージェントのコンテキスト（CLAUDE.md等）をドメイン特化させる

課題と解決策

AI時代のシステム設計において、私たちが直面している最大の課題は「テキスト負債」の増大です。
AIを賢く動かそうとするほど、私たちはREADME、CLAUDE.md、ガードレールといった「指示」を増やし続けます。
しかし、この「加法」の最適化こそが、指示系統の腐敗と管理コストの爆発を招く、生存を脅かす負債となります。

工夫したこと：最強の減法設計「リポジトリ分離」

AIへの指示を増やすのではなく、物理的に「言わなくていいこと」を増やす設計へと舵を切りました。
ブログ本体（母船）から画像処理という文脈を物理的に削ぎ落とすことで、母船を管理するAIに「画像処理の制約」を説明する必要をなくしました。

増築か分離か迷った際、私は以下の「3つの聖域」を判断基準としています：

依存の聖域（ライブラリの純度） : 母船のランタイム寿命を縮める重いNode依存を隔離病棟（別リポジトリ）へ送る。
検索の聖域（認知の純度） : 破壊的変更の際、検索結果からノイズを物理的に追放し、人間とAIの脳内メモリを「本質」に集中させる。
AIの聖域（コンテキストの純度） : 物理的境界線によってAIの視界を強制的に限定し、特定ドメインの専門家へと進化させる。

ぶつかった壁：自動化の誘惑と情報のゴミ屋敷

当初は、記事作成から画像生成までを完全自動化し、一つの大きなシステムとして統合する誘惑に駆られました。
しかし、それを実現するためには膨大な「例外処理」と「AIへの微細な指示」が必要になり、結果として情報のゴミ屋敷をAIと人間が整理し続けるコストが増大することに気づきました。

これは「コストの逆転現象」です。
モノリスな環境でAIを介護し続けるコストは、物理的にリポジトリを分けるオーバーヘッドを遥かに上回ります。

解決方法：「手動境界」による安全装置

完全自動化をあえて捨て、Geminiからの保存フローとの連続性を考慮した「slug（ID）の手動入力」を境界線として設計しました。
物理的に分かれた画像リポジトリでslugを入力し実行する。この「一呼吸置く」プロセスが、意図しない上書きを防ぐ安全装置となり、かつAIへの指示を劇的に減らす「最強の減法設計」を完成させました。

コード抜粋

分離した画像処理リポジトリ側では、エッジランタイムの制約を気にすることなく、Node.jsのフルパワー（Sharp等）を活用できます。

// image-repo/processor.ts
import sharp from 'sharp';
import { R2Client } from './storage';

/**
 * 記事のslugを受け取り、画像をリサイズ・WebP変換してR2へアップロードする
 * 物理的に分離されているため、ブログ本体（Edge）の制約を受けない
 */
export async function processThumbnail(slug: string, inputPath: string) {
  const buffer = await sharp(inputPath)
    .resize(1200, 630, { fit: 'cover' })
    .webp({ quality: 80 })
    .toBuffer();

  const fileName = `blog/thumbnails/${slug}.webp`;

  // Cloudflare R2への外部接続（SDKがそのまま使える）
  await R2Client.put(fileName, buffer);

  console.log(` Thumbnail processed: ${fileName}`);
}

ブログ本体側では、R2の不変URLを参照するだけで済みます。画像処理に関するコードやライブラリは一切存在しません。

今回の学びと感想

AIを使えば、道具は一瞬で作れるようになりました。
しかし、その道具をどこに置くかという「置き場所」の設計を怠れば、指示という名の負債に押しつぶされることになります。

リポジトリを分離し、AIに「言わなくていいこと」を物理的に増やすこと。
これこそが、AI時代の最強のコンテキストエンジニアリングであり、5〜10年死なないプロダクトを築くための生存戦略であると確信しました。

この「減法設計」の思想は、CLAUDE.mdのコンテキスト管理にも同様に適用できます。CLAUDE.mdを公式ベストプラクティスで再構築し約1,600トークンのコンテキストを削減した記録では、情報を「増やす加法」から「ポインタ化する減法」へ転換するプロセスを解説しています。また、AIエージェントにサブタスクを分担させるSubagent設計も「何を知らせるか」の設計です。これらはすべて「AIに渡す情報量を最小化する」という同じ思想の異なる実装形態です。