AI時代のドキュメント駆動開発のすすめ

はじめに

この数年、AIの登場によって開発現場は大きく様変わりした。バイブコーディングをはじめ、未経験者が開発に参入するハードルは一気に下がり、参入者は急増している。もはやプロダクトの「インフレ状態」と言ってもいいかもしれない。

しかし、プロダクトを作れるようになったこと自体は喜ばしい一方で、そのプロダクトが長く生き続けられるかどうかは、まったく別の問題として残っている。

仕様が「本当に存在しない」時代

趣味や個人開発であれば、それでも問題ない。しかしAIは今や、世界中の開発現場の最前線で使われている。それ自体はとても良いことだ。

一方で、AIで開発されたプロダクトの多くには、仕様をまとめたドキュメントが残っていないケースが少なくない。これはAI以前の時代にもあった話ではある。だが今の時代は少し事情が違う。

開発者自身の頭の中にも、仕様が残っていないのだ。

つまり、本当の意味で「存在しない」。

AIが登場したことで開発のスピードは劇的に上がったにもかかわらず、プロダクトを運用し続ける難易度は、逆にとてつもなく上がってしまっている。

そこで私は、AI時代のドキュメント駆動開発を提唱したい。

なぜ「今さら」ドキュメント駆動なのか

ドキュメントを起点に開発するという考え方自体は、決して新しいものではない。ウォーターフォール的な仕様書駆動開発や、DDDにおける「言語化」の重視など、以前から語られてきたことだ。

ではなぜ今、あえてこれを掲げるのか。

理由は単純で、AI以前は「面倒だから省略されていた」工程が、AIによって省略しなくても回るようになったからだ。仕様のフォーマット化も、設計書への落とし込みも、人力でやろうとすると相応の時間と労力がかかる。だからこそ、多くの現場で軽視されてきた。

しかしAIを使えば、大雑把なメモをフォーマットの整った仕様書に変換する作業も、その仕様書から設計書を書き起こす作業も、大幅に省力化できる。「仕様を書く余裕がない」という言い訳が、AI時代には成立しなくなったのだ。

AIドキュメント駆動開発とは

まず docs ディレクトリに、プロダクトデザインをざっくりと書き出す。ここはかなり大雑把でいい。

• 何ができるのか
• どんな機能が欲しいのか
• 何の言語/フレームワーク/ライブラリで構築するか
• 何の機能がコアになるのか
• 開発において何を重視したいのか

次に、そのプロダクトデザインをAIを用いてフォーマット化してもらう。この時点で認識の相違や、追加・削除したい点があれば編集する。その後、再度AIにフォーマット化してもらう。

これを繰り返し、product.md を完成させる。ここがコアになる。

設計ドキュメントへの展開

次に、その product.md をベースに、FE/DB/UI/BEの設計ドキュメントを docs 配下にAIを用いて記述してもらう。

そして、認識に相違がないか、設計に問題がないかを確認する。不明点や不満点があれば質問・修正を行い、再度LLMに書き直してもらう。これを繰り返し、それぞれの設計書を完成させる。

より厳密に設計したい場合は、ディレクトリ構成やアーキテクチャについてのドキュメントを作ってもいい。やり方は同じだ。

コーディングへ

すべてに対してある程度納得のいくものができたら、それを元にAIにコーディングを委託し、プロダクトを作っていく。

おすすめはモノレポ構成だ。設計がブレにくく、CLAUDE.md などに書き起こす際やバージョン管理が楽になるからである。

メリット

AI時代のドキュメント駆動開発には、次のようなメリットがある。

• 仕様のバージョン変更がGitで管理できる
  product.md や設計ドキュメントをコードと同じリポジトリで管理することで、仕様がいつ・どう変わったのかを履歴として追える。

• 新規開発者や引き継ぎに強い
  仕様と設計が言語化されているため、口頭説明や記憶に頼らずオンボーディングができる。

• AIとの認識の相違を事前に防げる
  コーディングを委託する前に設計段階ですり合わせておくことで、AIが誤った前提でコードを書いてしまうリスクを減らせる。

• しっかり設計を行なった状態でプロダクトの開発ができる
  勢いだけで実装に入らず、設計を固めてから着手できるため、手戻りが少ない。

• 保守性をある程度担保できる
  仕様と実装の対応関係が残るため、後から機能追加や改修を行う際にも影響範囲を把握しやすい。

注意点・向かないケース

一方で、このやり方が常に最適とは限らない。

• ドキュメントの往復コストが発生する
  仕様策定→フォーマット化→設計→レビューという工程を踏む分、思いついたその日にコードを書き始めるスピード感は失われる。検証段階のMVPや、数時間で作り切りたい小さなツールには過剰な場合がある。

• ドキュメントと実装が乖離するリスク
  設計後にAIへ実装を任せきりにすると、実装が進むうちに仕様書側が更新されなくなり、いつの間にか「また仕様が実態と合わなくなる」状態に逆戻りしかねない。ドキュメントは作って終わりではなく、変更のたびに更新する運用ルールとセットで機能する。

• 探索段階のプロダクトには不向きなことがある
  「何を作るべきか」自体がまだ定まっていない、仮説検証フェーズのプロダクトでは、先に設計を固めることがかえって足かせになる場合もある。この手法は、ある程度作るものの方向性が見えてから効いてくる。

こうした限界があることを踏まえた上で、それでも「後から泣く」よりは「先に少し手間をかける」方が、長く運用するプロダクトには合っていると私は考えている。

おわりに

AIによって、誰もが「動くもの」を作れる時代になった。これは間違いなく歓迎すべき変化だ。しかし「動くもの」と「生き続けられるもの」の間には、依然として大きな溝がある。

その溝を埋めるのは、AIの性能でもコーディング速度でもない。言語化された仕様だ。

コードは書き直せる。しかし、開発者の頭の中にしかない意図や判断の理由は、失われた瞬間に本当に取り戻せなくなる。AI以前の時代であれば、まだ本人に聞けば済んだ。今の時代は、本人の頭の中にすら残っていないかもしれない。だからこそ、ドキュメントという形で外部化しておく必要がある。

プロダクトのインフレ状態は、これからも加速していくだろう。その中で生き残るのは、最も速く作られたプロダクトではなく、最も正しく引き継げるプロダクトだと私は思う。

AIに書かせて終わりにするのではなく、AIと一緒に「残すもの」を作る。それが、AI時代のドキュメント駆動開発だ。