Design docs は期待を文書化したもの
†思想†です[1].
今日AIエージェントを使ったプログラミングのプラクティスとして軽量ドキュメント文化が注目されています. 中でも design docs はドキュメントフレームワークとして確立しており, 広く認知されるようになってきました[2][3].
Design docs の特徴としては context や goal/non-goal, 代案の提示といったシステムの仕様そのものの文書化にとどまらない点にあります.
つまり design docs は期待を文書化したものといえるのではないでしょうか.
Q. それってただのWHYの言い換えでは?
ここには少し違いがあります. ここでいう design docs の作成は実装の前に行います. そのため design docs に書かれた内容は誤りである可能性があるのです. システム開発における意思決定根拠を文書化したものと呼べるようなものではありません. 実装の前に design docs の作成を行う以上, そもそも前提が間違っているといったこともあり得るのです.
だからこそWHYの文書化というものではなく, 「現時点でシステムはこうあってほしい」という期待を文書にしたもの, その程度のものだと思うのです.
WHYが難しくなりすぎた
ゴールデンサークルや問いの力などビジネスの文脈でWHYがもてはやされ様々な観点で論じられてきた結果, WHYというものがいつの間にか高尚なものになってしまったように感じます. WHYというのはビジネス上の重要な意思決定となり, それを文書化するのは非常に勇気のいる行為となってしまったのです.
問いがとおーい存在（）になってしまったことで, design docs も難しい存在のように感じてしまうのです.
Design docs をもっと気軽に
先述の通り, design docs は実装前に作成する以上, 誤りは避けられません. だからこそ誤りを恐れずに, 期待そのものを書いてしまえばいいのです[4][5]. Design docs は開発者にとっての青写真です. 仕様書ではありません. あとから間違いに気づいたら Architecture Decision Record(ADR) を使って訂正すればいいのです[6]. システムのふるまいや構成はすべて design docs に書く必要はありません. ユーザーストーリー, Gherkin記法, 自動テスト, IaC, システムのありようは様々な面から様々な方法で記述できます. 今ならAIエージェントを使えばこれらからすぐに理解できるはずです. であれば design docs にはもっとシステムへの期待を込めていいはずです.
システム設計を中心とした文書化はADRとも異なります. システム設計における判断や反省の記録は他のシステムにも活きるはずです.
テストと異なり design docs を含め自然言語で記述された文書は一般に検証可能性がありません. だからこそ, そのフレームワークの特性を理解し活用すべきなのです. 教義化も軽視も間違いです. 丁寧な理解と適度な距離を持ち適応するべきなのです.
参考文献
Design Docs のいけすかなさ / morrita - Message Passing https://messagepassing.github.io/011-designdocs/01-morrita/
-
この記事は個人の考えを示すものであり, 何らかの定義や推奨を行うものではありません. ↩︎
-
Design Docs at Google https://www.industrialempathy.com/posts/design-docs-at-google/ ↩︎
-
メルカリShopsでのDesign Docs運用について | メルカリエンジニアリング https://engineering.mercari.com/blog/entry/20220225-design-docs-by-mercari-shops/ ↩︎
-
チーム内で認識が統一されていない場合 design docs レビューでどうなるかは知らない. ↩︎
-
とはいえ指摘されまくるとつらい気持ちになるので, モビングとか期待値コントロールしような :fist_oncoming: ↩︎
-
文書管理できている場合に限る. ↩︎
Discussion