個人サイト（PortfolioSite）をGemini CLIと一緒に作っていた頃、AIに何か作業を頼む前は決まって同じ指示から始めていた。

「portfolio仕様書フォルダを読み込んで」

要件定義のメモも、技術選定の調査記録も、環境構築の手順書も、全部同じフォルダにまとめて置いてあった（これらのドキュメントをどんな順番で積み上げていったかは、個人サイトを立ち上げる時、僕はどんな順番で決めていったかにまとめてある）。何を頼むにしても、まずこのフォルダを丸ごと読ませてから本題に入る。関連しそうな資料を都度選び分けるのが面倒だったし、うっかり必要な文脈を渡し忘れて的外れな実装をされるくらいなら、多めに読ませておいた方が安全だろうという判断だった。

最初のうちは、これで何の問題もなかった。仕様書もコードもまだ小さく、同じ運用を続けても大した時間はかからなかったし、コストらしいコストも感じなかった。

何が起きたか

問題が表面化したのは、サイトが育ってからだった。要件定義・技術選定・環境構築・アーキテクチャ記録と、フェーズを重ねるごとにドキュメントの数が増え、コードの量も増えていく。それでも自分は同じ指示を繰り返していた。

異変に気づいたのは、コストの請求額を見てではない。当時は無料枠で運用していたので、そもそも請求額という指標がなかった。代わりに気づいたのは、無料枠の消費ペースそのものだった。最初の頃は1日中AIとやり取りを続けてもリミットに達することはなかったのに、気づけば1回の応答だけでリミットに達するようになっていた。同じような感覚で使い続けていたはずなのに、いつの間にかここまで極端に変わっていた。

考えてみれば当然の話だった。ドキュメントが増えれば、同じ指示で読み込ませる量もそのまま増える。仕様書もコードもまだ小さかった頃は、この「全部読む」コストは誤差の範囲に収まっていた。でも規模が育つと、同じ運用のコストは規模の増加以上のペースで膨らんでいく。最初に選んだ「安全策」が、規模が変わったことで静かに割に合わなくなっていた。

対策は、実はもう別記事に書いてある

気づいたあと、この運用はやめた。代わりに、Portfolio_System_MOC（現行アーキテクチャを1箇所にまとめたドキュメント）を起点に、「今日は◯◯から進めよう」とその日着手する範囲だけを指定する形に変えた。フォルダ丸投げから、目次を頼りに必要な部分だけを渡す形への転換だった。

この「人間がすでに作った知識地図を、AIに辿らせる」というやり方の仕組みと実装方法については、実は以前に別の記事としてまとめている。

grepでの全文検索やフォルダ丸読みがなぜコストと精度の両面で不利になりやすいか、MOC（Map of Contents）を探索の起点に据えるとどう変わるか、という技術的な話はそちらに譲る。この記事で書きたかったのは対策の中身そのものより、「安全策のつもりで始めた運用が、規模が変わったことに気づかないまま負債になっていた」という、気づくまでの過程の方だ。

まとめ

個人サイトはまだ小規模だった頃、「関連しそうな資料は全部読ませておく」は妥当な判断だったと思う。判断が誤っていたわけではなく、規模が変わったのに運用を見直さなかったことの方が問題だった。

「最初に選んだやり方が、今も正しいとは限らない」という、当たり前といえば当たり前のことを、無料枠の減りが早くなるという分かりやすい形で教えてもらった。

ただ、これは無料枠だったからこそ「減りが早い」という分かりやすい指標に気づけただけの話でもある。もしあれが従量課金だったらと考えると、正直ぞっとする。従量課金には「あとどれだけ使えるか」を可視化してくれる仕組みはなく、使った分だけ静かに請求額が積み上がっていくだけだ。気づいた時には、思っていたより高い金額を目にしていたかもしれない。

しかも今回は個人開発だったから、この程度の気づきで済んだという面もある。これが会社規模の開発で、同じように「関連しそうな資料は全部読ませておく」という運用を複数人・複数プロジェクトで続けていたら、消費されるトークン量も請求額もまるで桁が違ってくるはずだ。個人の無料枠なら「早く減るな」で気づける話が、組織の従量課金では見過ごされたまま積み上がる金額になりかねない。もし同じような運用に心当たりがあるなら、一度立ち止まって見直す価値はあると思う。

結局のところ、自分はたまたま無料枠という分かりやすい指標のおかげで、規模が変わったことに気づけただけなのだと思う。ドキュメントを書き残す習慣と、それをAIにどう読ませるかという運用は、セットで見直し続けるものなのだろう。