Design Doc の4要素、毎回書くのはどれか — Non-Goals だけは書く

参考: 優秀なエンジニアが書くDesign Docは何が違うのか?

まとめ

• 毎回書く価値があるのは Non-Goals だけ。他の3つは条件付き
• 代替案を書くのは「後から変えると他人を巻き込む判断」のときだけ。それ以外は時間の無駄
• 未決定事項は「いつ決めるか」を日付で書かない。何が起きたら決めるかを書く

どれを書くか

Design Doc は実装前に「何をどう作るか」を書いて、関係者のレビューを受ける文書。冒頭の記事は、レビュアーとして大量に読んだ立場から「代替案・懸念点・未決定事項の書き方に実力が出る」と言っている。Non-Goals を足すと、判断が絡む部分は次の4つになる。

表1: 4要素と、そこから読み取れるもの

要素	中身	読み手が受け取るもの
Non-Goals	今回やらない範囲	どこまで期待していいかの境界
代替案	検討して捨てた方式と理由	書き手の引き出しの広さ
懸念点	不安が残る点・分からない点	考えた深さ
未決定事項	今決めない項目と、決める時期	不確実性の見極め

読んで納得はした。ただ、これを全部埋めろと言われると重い。自分は代替案を書き始めると時間が溶けるので避ける癖があるし、未決定事項も「いつ決めるか」の部分がいつも抜ける。全部やろうとして形骸化させるくらいなら、どれを捨てるか先に決めたほうがいい。

重要な条件から順に落としていくと、こうなる。

表2: 判定フロー

手順	判断すること	結果
1	読み手（レビュアー・委譲先・後任）がいるか	いなければ全部書かない。自分用メモに代替案は要らない
2	この判断を後から変えるとき、他人を巻き込むか	巻き込むなら代替案を書く。自分だけで直せるなら書かない
3	保留したまま先に進む項目があるか	あれば未決定事項を書く。日付ではなく、何が起きたら決めるかを添える
4	上のどれでもない	Non-Goals だけ書く

手順4に落ちる文書がほとんど。だから実質「Non-Goals は毎回、残りはたまに」になる。

Non-Goals はゴールの裏返しではない

Non-Goals はゴールの否定形ではない。「ログイン機能を作る → ログアウト機能は作らない」の形は情報量がゼロで、書いても誰も助からない。

手が動くのはこの問い。

この文を読んだ人が、書いてないのに入っていると期待しそうなことは何か。

ゴールを見て考えるのではなく、読み手の頭を想像する。だから裏返しでは出てこない。

たとえば「通知機能をリリースします」の一文から、読み手が抱く期待を並べてみる。

表3: 「通知機能をリリースします」に対する読み手の期待

読み手が期待しそう	Non-Goals に書くか
メール以外（Slack / Push / SMS）も来る	書く（今回はメールのみ）
通知の ON/OFF を設定できる	書く（設定画面は次フェーズ）
過去分にも遡って通知される	書く（リリース以降の発生分のみ）
管理画面で送信履歴が見られる	書く（履歴画面は作らない）
通知文面を管理者が編集できる	書く（文面は固定）
データベースが新設される	書かない（誰も期待しないし興味もない）

出てくるのは全部「やってもおかしくないが、今回は入れていない隣接機能」。ゴールの否定形はひとつも出てこない。

探し方で一番安いのは、依頼を受けたときに一瞬よぎって捨てたものを拾い直すやり方。「ついでにこれも要る?」と思って却下したものは、読み手も同じように思う。新しく考える必要がないぶん、机上で3分あれば書ける。

作業を人に委譲する場合はもっと直接的で、Non-Goals は「作業者が良かれと思ってやりそうなこと」になる。関連箇所のリファクタ、既存テストの手直し、作業中に見つけた別のバグの修正。書いておかないと本当に膨らんで返ってくる。うちの作業指示テンプレにはこの節が無くて、実際に何度か膨らんだ。

代替案は「戻す値段」で決める

元記事は代替案を書く量に線を引いていない。ここから先は元記事の主張ではなく、自分がどう運用するかの話。

代替案を並べるのは時間が溶けるので、正直これまで避けてきた。それでも困らなかったのは、避けた場面のほとんどが戻せる判断だったからだと思う。実装方式・命名・ライブラリ選定は、間違えたら直せばいい。直すコストが、代替案を書くコストを下回る。

逆に、戻すのが高い判断では避けたツケが来る。データの持ち方（移行が発生する）、外部との契約（API や IF など他チームが依存する）、環境の切替手順（走り出すと止まらない）。この3つは、間違いに気づいた時点で自分ひとりでは戻せない。

なので線はここに引くことにした。

これを後から変えるとき、他人を巻き込むか。

巻き込むなら書く。自分だけで直せるなら書かない。この基準だと代替案を書く機会は年に数回しかないので、避ける癖はそのままでいい。

未決定事項に日付を入れても守られない

保留すること自体は自然にやっている。抜けるのは「いつ決めるか」のほうで、これは意志の問題ではない。保留した瞬間は「後で決める」で正しく、期日を決める材料がまだ無いから書けない。

そこで日付の代わりに、何が起きたら決めに行くのかを書く。

たとえば「通知の送信基盤を自前で持つか、外部サービスを使うか」を保留したとする。

日付で書くと「9月中旬に決める」になる。9月中旬になっても判断材料は増えていないので、また先送りされる。日付は自分で置いた締切であって、決められるようになる時点とは何の関係もない。

起きたことで書くと「1日の送信量が1万通を超えたら決める」になる。自前で持つ理由が費用なら、費用が問題になる量に届くまでは決めても意味がない。逆に届いたら決めるしかない。しかもこの書き方だと、自分で思い出さなくていい。監視の数字が勝手に条件に引っかかるので、向こうから知らせが来る。

書き方に迷ったら、保留した理由をそのまま裏返せばいい。「いまは送信量が読めないから決められない」なら、書くのは「送信量が読めたとき」。決められない理由の中に、決められるようになる条件がそのまま入っている。

日付で書いた保留はだいたい流れた。それが意志の弱さではなく書き方の問題だと分かってから、こっちに切り替えた。

4要素の扱い方

表4: 要素ごとの結論

要素	いつ書くか	コスト
Non-Goals	毎回。ゴールを書いた直後	ほぼゼロ
代替案	後から変えると他人を巻き込む判断のときだけ	高い。だから絞る
懸念点	判断が絡むとき。調査なら「分からなかった範囲」として	低い
未決定事項	保留したとき。日付でなく、何が起きたら決めるかを書く	低い

Design Doc は実装前の設計案なので、レビューで変わる前提の文書。決まった後の記録は ADR の役割で、そちらは「採った案・理由・捨てた案」を1決定1ファイルで積む。前を Design Doc、後ろを ADR が受け持つ。

とりあえず自分は Non-Goals から始めることにした。作業指示テンプレに節を足したので、次の委譲で効くかどうか見る。