複雑なシステムほど、最初の整理に時間をかける

今日は、複雑なシステムを作るときの初動を、あらためて手順として整理した。いきなりコードを書き始めるのではなく、要件定義、設計、実装指示、実装の四段階に分ける。最初に考えることをきちんと考えておくと、その後の作業が驚くほど進めやすくなる。

第一段階は、要件定義だ。ここではGPT Instantを相手に、作りたいものの仕様を壁打ちする。頭の中にある考えを言葉にし、足りない条件を指摘してもらい、利用する人や場面ごとの例外を洗い出す。何を作るかだけでなく、何を作らないか、どこまでを今回の範囲にするかも、この段階で決めていく。

壁打ちの良さは、考えがまとまっていない段階でも始められることだ。思いつきをそのまま投げると、質問が返ってくる。その質問に答えるうちに、自分が本当に決めたいことが見えてくる。もちろん、返ってきた内容をそのまま正解にするわけではない。最後に判断するのは自分だが、考えるための相手としてはとても使いやすい。

第二段階は、設計だ。要件定義の壁打ちが十分に詰まったら、GPT Proにこれまでの内容をすべて渡し、全体を総合した設計書を起こすように指示する。システムの規模によっては、数十万行に及ぶ設計書になることもある。画面や機能の一覧だけではなく、データの持ち方、処理の流れ、エラーの扱い、運用の決めごとまで一つの設計にまとめる。

ここで大事なのは、設計書の分量を増やすこと自体ではない。後で迷いそうな点を先に見つけ、判断を残しておくことだ。設計の途中で曖昧な箇所が見つかったら、要件定義へ戻って決め直す。大きな文書を一度に作るからこそ、前提がずれていないか、同じ意味の言葉を違う場所で使っていないかを人間が確認する必要がある。

第三段階は、実装指示を整えることだ。設計書があっても、実装する人やエージェントが毎回違う解釈をすると、成果物は揺れる。そこで、実装時の注意点、変更してよい範囲、確認してから進める条件、終わりと判断する基準を別にまとめる。実行用のプロンプトも、あとから誰でも読めるようにMDファイルへ整理しておく。

この文書は、作業を急かすための命令書ではない。設計書に書かれたことを、どの順番で、どこまで、どのように確認しながら実装するかをそろえる土台だ。迷ったときに戻る場所があるだけで、途中の判断がかなり安定する。

第四段階で、実装に入る。第二段階で作った設計書のZipファイルと、第三段階で作った実装指示のMDファイルをまとめてFableへ渡す。材料がそろっていれば、要件を読み、設計を参照し、決められた注意点に沿って、実装までを一つの流れで進められる。初動としては、このやり方が一番楽だと感じている。

システムは、初めて作るコストより、あとから直すコストの方が何倍も大きい。最初の画面を作ってから仕様を変えると、画面だけでなく、データ、処理、説明書、確認方法まで連鎖して直すことになる。小さな認識違いを後回しにすると、最後には大きな手戻りになる。だから、早く実装を始めることより、早い段階で不確かな部分を見つけることの方が重要だ。

これはシフトレフトと呼ばれる考え方に近い。要件定義や設計に時間を多く割き、問題をできるだけ前の段階で見つける。実装を遅らせるように見えて、実際には後半のやり直しを減らし、全体の実装時間をかなり削減できる。設計書を作ることが目的ではなく、後から直す時間を最初の確認へ振り替えるということだ。

もちろん、AIが作った設計書や実装が自動的に正しいわけではない。関係者が前提を確認し、重要な判断を承認し、動くものを見て検証する工程は残る。それでも、考える材料と判断の履歴を最初に一つへ集め、実装へ渡す形式をそろえておく価値は大きい。

複雑なものを作るほど、最初の整理が効いてくる。要件を壁打ちし、設計へまとめ、実装の注意点を書き出し、まとまった材料で実装する。この流れを基本の型として、これからも改善していこう。