計画がコードより先だ——と後から知った
設計書なしで始めて全部やり直した話
ある夜、AIのチャット画面にこんな分析が表示された。
「アナライザーがテキストを返していますが、オーケストレーターは構造化されたオブジェクトを期待しています。インターフェースが合致していません。」
この文を読んで私が理解できたのは半分くらいだった。「アナライザー」と「オーケストレーター」が自分のプロジェクトのモジュール名だということは分かった。「インターフェースが合わない」ということも、なんとなく察しがついた。一方が送る形式と、もう一方が受け取る形式が違うということだろう。コンセントの穴が合わないように。
しかしその瞬間、私が感じたのは技術的な理解ではなく、もう少し根本的な感情だった。ああ、これは最初からやり直さなければならないのだな。
V2と呼ぶ最初のバージョンがあった。Pythonファイル18個。YouTubeチャンネルを監視して、新しい動画が上がったら字幕を取得してAIに分析させるシステムだった。自分のPCで動かしていて、動いていた。「動く」という事実にかなり感動した。コードを一行も自分で書いていないのにプログラムが動作するなんて。
問題は、これをウェブサービスに拡張しようとしたとき噴き出した。
自分のPCで自分だけが使うプログラムと、インターネットに公開して複数の人が使うサービスは、構造的に異なる。レストランに例えれば、家で家族のご飯を作ることと、店を開くことの違いだ。レシピ（コア機能）は同じかもしれないが、厨房設備、衛生管理、注文システム、レジ——こういったものが全部必要になる。
管制塔（私がAIチャット画面を呼ぶ名前だ）にV2の構造を分析してもらった。返ってきた診断書にはイシューが六つ記されていた。
一つ目、分析結果を保存するテーブルがデータベースにない。データベースをエクセルファイルだと考えると、分析結果を記録するシートそのものが欠落していた。V2では分析結果をその都度ファイルに保存していたのでこのシートは不要だった。しかしウェブサービスでは複数のユーザーの結果を体系的に保管する必要がある。
二つ目、ユーザーを区別する仕組みがなかった。V2は自分一人で使うプログラムだったので、「ユーザー」という概念自体が不要だった。しかしウェブサービスになれば「この分析結果はAさんのもの、あれはBさんのもの」という区別が必須だ。
三つ目が、管制塔が指摘したあの問題だった。アナライザーモジュールは分析を終えるとテキストの塊を返していた。しかしその結果を受け取って次のステップに渡すオーケストレーターモジュールは、構造化されたオブジェクト——タイトル、要約、キーポイント、関連概念がそれぞれ分離された形——を期待していた。手紙を送ったのに相手が宅配便の箱を待っている、そんな状態だ。
残りの三つも似た文脈だった。すべて「自分一人で使うときは問題ないが、複数の人が使うサービスになると破綻する」種類のイシューだった。
正直、動揺した。数週間かけて作ったものをやり直さなければならないということだから。しかし同時に不思議な安堵感もあった。問題を知らないままウェブサービスを公開して後で噴き出すよりも、今知って良かったという。
V3として全面リファクタリングを決めた。リファクタリングとは、機能はそのままに内部構造を組み直すこと。メニューは変えないが厨房の動線を再設計する。ただし私の場合は規模が大きく、事実上厨房を建て直すレベルだった。
今回は違うやり方をした。コードを一行も書く前に、文書を先に作った。
アーキテクチャ文書——システム全体がどう構成され、データがどの順序で流れるかを図にした。ビルドプロンプト——AIに「今回はこれだけ作って、これには絶対に触るな」と指示する文書。チェックリスト——各段階で確認すべき項目を並べたもの。コストモデル——AIを動かすのにいくらかかるかの計算。多言語仕様——韓国語、日本語、英語それぞれで何が変わるべきか。
五種類の文書。コードより文書が先。
チェックリストを作りながら、「95%完成」という言葉がいかに危険かを知った。V2がまさにそうだった。コア機能は動いていた。95%完成しているように見えた。しかし残りの5%——ユーザー区別、データ保存構造、モジュール間インターフェース——が解決されなければ、次の段階（ウェブサービス化）に進めなかった。5%が100%を塞いでいた。
文書を先に作るというのは奇妙に聞こえるかもしれない。早く作らなければならないのに、なぜ文章を書いて座っているのかと。しかしコードを読めない人間にとって、文書は特に重要だ。自分でコードをレビューできないのだから、AIに「この文書の通りに作って」と指示するのが唯一の品質管理手段なのだ。文書が正確ならコードも正確になる。文書が曖昧ならAIは独自に解釈して作り、その解釈が私の意図と異なる確率が高い。
V3を再び始めた夜。ターミナルに座ってコードを実行する代わりに、チャット画面で文書を練っていた。生産的でない気がした。しかしそれ以降、V3を作る過程でV2で経験した種類の問題は一度も起きなかった。
🔧 このエピソードの技術用語解説
リファクタリング（Refactoring） 機能はそのままに、コードの内部構造を組み直すこと。レストランの例えなら、メニューを変えずに厨房動線を再設計すること。
データベーステーブル データを保存するExcelのシートのようなもの。シートがなければデータを保存する場所がない。
インターフェース（Interface） モジュール間でデータをやり取りする規格。コンセントの穴の形と考えればよい。
DI——依存性注入（Dependency Injection） レゴの組立説明書のようなもの。各部品（モジュール）がどの部品と結合するかを事前に定めておく設計パターン。
オーケストレーター（Orchestrator） 複数モジュールの作業順序を調整する指揮者。「まず字幕を取得し、次にAIに分析させ、結果を保存する」を管理する中央モジュール。