ClaudeCodeで詳細設計書を生成させながら開発させるのに挫折した理由

ClaudeCodeで小規模なツールを作ったり、趣味の開発をしたりして遊んでいます。

その時のちょっとした体験談を紹介します。

詳細な設計書を生成させながら自走させた

AIを活用するには言語化が命だと考えています。
いかにシステムの状態を言語化したドキュメントがあるかどうかがAI駆動開発のキーになるのかなと。

そこで、「AIに設計書も全て生成させればいいじゃん！」という安直な発想をしていました。

そこで、例えばこういう指示を行いました。

「～という機能を作ってください。その際は自分の作業を詳細にドキュメントとして出力してください」

はじめは良かったのですが、少しコード量が膨らんできた段階で問題が生じました。

問題が生じたところ

ドキュメントのレビューが追いついない

ClaudeCodeはコードを生成する速度も速ければ、当然ドキュメントの出力スピードも速いです。

そうなると、生成AIが書いたコードの妥当性も見なければいけないのに、ドキュメントのレビューも大量に必要になってきます。

文章量が多く、ドキュメントとコードとの整合性や中身の正しさの検証が人間の目では追いつけなくなりました。

メンテナンスできなくなった

大量のドキュメントがあるので実装の一部を変えるだけでドキュメントの修正範囲も広くなることがありました。
実装に合わせてドキュメントを修正してもらうのですが、それが正しいのかどうかを検証するのにまた時間がかかるわけです。

ClaudeCodeなどのCLI系は特に細かく修正範囲を指示するのは難しいため、指示でフラストレーションが溜まりました。

もちろん、一つの仕様は一つのドキュメントに記載するようにし二重管理を避けるようにしていました。

しかし、「本当に二重管理になっていないのか？」「ドキュメントAとBの整合性は合っているのか？」という点を把握するのに時間がかかりました。

解決策（案）

はっきり言いますと、根本的な解決策はまだ持ち合わせておりません。
ドキュメントが少なければAIへのインプットも少なくなりますし、多くなればメンテナンスコストは増大します。
トレードオフの関係にあるのではないかと思っています。
今試しているのは以下のような方法です。

実装の詳細は出力させずに大枠の方針の記載にとどめるようにした

コードと「＝」になるような、実装の詳細に近しい部分の出力は避けるような指示を試しています。
大枠の方針や構造のみをドキュメントとして出力をするような指示をすることでマシになりました。
そもそも詳細な設計はコード自体を読めばいいわけですから、最初からいらなかったわけですね。。

（そもそも人力でコーディングしてたころは書いていなかったし。。）

怪しいドキュメントは思い切って削除

生成されたドキュメントを捨てるのはもったいない感じがします。
しかし、よく考えたら数分で生成されたものなので工数も特にかかっていないわけです。
なので、別に怪しいドキュメントは削除するか、別フォルダに移動してアーカイブとして残して、新たに生成させる流れでも特に損はないのです。
スクラップ＆ビルドですね。

まとめ

これは結局、人間が人力でコーディングするときと同じ問題をはらんでいると思いました。
ドキュメントがないと困るが、詳細すぎるとメンテナンスできません。
この解決策が生まれる日が来るとうれしいです。
しかし、個人の直感では「正解」が出てくることはない気がするので、試行錯誤を続ける必要があるなと思っています。