私の会社のチームではDesign Docsを書いている。AIによってDesign Docsが書きやすくなったり、コードを読ませてContextからDesign Docsを書くみたいなこともできるようになってきた。

Design Docsは人間の設計判断だけではなく、AIのコンテキストとしての役割も求められてきていると感じる。

このブログではその中でもDesign Docsは設計判断をするべき文書であって、仕様や実装方法の詳細とは分離した方が良いのではという主張をします。

Design Docsとは

Design DocsとはGoogleのソフトウェアエンジニアが提唱したなぜこの設計なのか？を合意形成するための文書です。

以下の記事は翻訳もされており、Design Docsを理解する上での原典となっています。

https://www.industrialempathy.com/posts/design-docs-at-google/

GoogleのDesign Docsの特徴は「実装の詳細を書かない」ということです。これはDesign Docsが「設計書」であって、「仕様書」ではないということを意味します。

詳細やDesign Docsの考え方については元記事や翻訳記事に譲りますが、この「実装の詳細を書かない」ということがDesign Docsにおいては重要だと考えます。

Design Docsと仕様の違いについて考えてみる

一方で、AI時代には仕様駆動開発というのがホットワードとして盛り上がっている時期がありました。

仕様駆動開発の中にはもしかしたら流派があるのかもしれませんが、ここでいう仕様駆動開発とはドキュメントの仕様を正としてコーディングを進めていく開発を想定しています。

仕様書というのはコードの詳細、APIの全定義、実装レベルの詳細を定義したものです。

AIという文脈においては、仕様書という文書をコンテキストに含めて実際のコードをリードしていく。そのような意味合いも含むと思います。

一方でDesign DocとはGoogleの厳密な定義に沿うと「人間」に読ませるものです。

「人間」にその設計の背景、トレードオフ、代替案を明確に伝え議論をし、テックリードの視点を設計書に含めることでより良い設計を目指してくものです。設計書ではコードは書かずに、高い抽象度で設計について説明することが求められます。

まずはこの「仕様書」と「設計書」の違いにおいては認識をしておくと良いと思います。

とはいえDesign DocsでもAIという文脈は無視できない

Design Docsが人間の設計判断を高めるため、共有するための「設計書」であることを述べました。

とはいえ現在では、AIにDesign Docsをコンテキストとして与え実装の指針としていくことも考慮する必要もあると思います。

またコードをコンテキストとして読ませ逆にDesign Docsを書かせるというような逆側のワークフローもあるでしょう。

AIに連動させることを意識すると、だんだんとDesign Docsの内容が実装の詳細になっていきます。そのまま実装に反映される理想的なワークフローに思えます。

このような仕様駆動開発にはデメリットが大きいと考えます。

仕様書側もコードに追従し続ける必要が出て来るということです。実装を進めていくにつれて、実際には新たな仕様が浮き彫りになったり、既存仕様との整合性を担保することがほぼ100%発生するでしょう。

その時点で仕様書に書いた詳細は、実装と乖離します。その乖離を仕様書に反映させる必要が出てきます。

なぜならそのドキュメントは実装の詳細を書いた時点で、実装との整合性を判断するドキュメントとなるからです。

Design Docsのような設計書に実装の詳細を含めるということは、文書に負債を持つということと同様だということを認識すると良いと思います。

一方で、Design Docsを基準でコーディングを進めるという観点では、「人間」に読みやすいというだけではガードレールとして弱い気もします。

Design DocsはAIへの制約となる

AIをリードする文章とするためには原典に返って、このDesign Docsが「何を目的として」「何を目的としないか」というのを明確にすることです。

この何をしないかというのがAIへの制約となります。

なぜこの設計にしなかったのか？という「代替案」を書くことの重要性が高まります。それはAIにやらせないことのリストになるでしょう。

一方でなぜこの設計としたのか？という部分も意思決定としてしっかり書く価値があります。

例えばDBの設計でなぜそのプロパティはnullableと考えるのか？などは残しておく価値があると思います。

なぜそのシステムにしたのかという意味、制約、整合性に関わるかどうか？というのを実装の詳細と区別して判断するのが良いでしょう。

このように冒頭の参考記事のDesign Docsの原点の考え方を重要としつつ、AIへどのような制約・整合性・システムの意味を与えるか？という観点を加えるのがDesign Docsには求められていると私は考えます。

こうすることで、Design Docsは実装の変更に追従する必要はなく、ある時点で人間がこういう設計判断をしたというコミュニケーションツールとなります。

このコミュニケーションの軸としてのドキュメントを作ることで、仕様変更・受け入れテスト・不具合発生時の指針となるでしょう。

もちろんその設計が誤りだった場合はDesign Docsを修正することになりますが、それは必要な変更です。

仕様とコードの関係性

これはバランスが難しいテーマですが、仕様駆動開発は「仕様」の何を対象とするのかという部分と、どのように「実装」するべきなのか？というものが自然言語で管理されてしまうというところに難しさがあるのではないかと感じています。

Design Docsのような「設計書」、設計判断をする場所に仕様や実装を含めない。

さらにいうと型定義・テスト・スキーマ・OpenAPIなどの実装可能な仕様はコードに、設計判断はDesign Docsに。この責務の分離は、AI時代だからこそ重要になると私は考えています。

なのでAI時代なので、コーディングエージェントに進めやすくするためにDesign Docを仕様書に近づけるという考えに私は賛同しません。

Design DocはAIに実装方法を教える文書ではない。AIが勝手に設計判断をしないようにするためのガードレールである。というのがこのブログでの主張になります。

まとめ

このブログでは、Design Docsの定義を改めて考えてAI時代ではどうあるべきなのかを考えました。

• Design Docsの原点の考え方はそのまま利用可能であり、むしろAIのコンテキスト・ガードレール、人間の設計への責任という観点でDesign Docsの価値は高まっている。
• AIへのコンテキストを重視するあまりに、Design Docsに実装や仕様を含めることによる負債させる危険性がある。

ことなどを主張しました。AI時代だからこそ、人間が判断する部分を明確にし、逆に実装部分はガードレールに沿って自然言語で余分な縛りをしすぎずにAIのパワーで自走させ続ける。

そんなドキュメンテーションの棲み分けをするスキルもこれからの時代求められていくのではないかと感じました。

Design Docsの考え方を学ぶとどのように実装を進めていくのかの指針になると思うので、おすすめです。

https://www.industrialempathy.com/posts/design-docs-at-google/