【コード哲学エッセイ】 設計書は正解を押しつけるものじゃない

迷った痕跡を共有するドキュメント術

設計書を書くとき、あなたは何を書いていますか？

アーキテクチャ図、クラス図、処理フロー。
「こうなっている」
「こうなります」
と、結論だけを並べていく。

かつての僕は、そう書いていました。
設計書は正解を確定させるものだと思っていたのです。

ある日、その正解が未来の誰かを縛りつけていることに気づきました。

「設計書 ＝ 正解」 と読まれた頃

サラリーマン時代の医療系システム開発で、設計書は「完成したら変えないもの」のように扱われることがありました。
レビューで承認された設計書は、その後も「設計書に書いてあるから」と変更しづらい。
仕様変更や障害対応で「ここ、設計書と違う実装になってる」と指摘される場面もありました。

設計書は、その時点での判断の記録であって、絶対の正解ではないはずです。
それでも、「設計書 ＝ 正解」と読まれると、未来の自分やチームが変えていいと判断しづらくなる。
結果として、設計書と実装の乖離が進んでいました。

設計書が正解を押しつけるものになっていた。
その感覚が、今でも胸に残っています。

結論だけを書いて文脈が消えた

設計書に結論だけを書いて、なぜを残さなかった経験があります。
半年後に設計を見直すとき、「あのときは何を考えていたんだろう」と、思い出せない。
当時の仕様もチケットも、もう手元にない。
結局、調査からやり直すことになりました。

逆に、たった一行のメモが救ってくれたこともあります。

その一行で、当時の自分がなぜそう決めたかが、はっきり蘇りました。
設計書は結果しか残していなかった。
でも、その一行が意図を残してくれていた。
未来の僕は、その痕跡を受け取って救われたのです。

迷った痕跡を残す

フリーランスになってから、設計書に

💭 「なぜこの設計にしたか」
💭 「他に検討した案」
💭 「どこで迷ったか」

を、短く書くようにしています。

📍 採用した案の理由
📍 捨てた案と、捨てた理由
📍 「ここは迷った」「将来変更の可能性がある」と明記する箇所
📍 「〇〇時点の判断」と日付を入れる

設計は変わる前提であることを、設計書のなかで示す。
そうすることで、読んだ人が変えていいと判断しやすくなります。

設計書は正解を確定させるものではなく、判断の経緯を共有するもの。
迷った痕跡を残しておくことで、設計書が押しつけではなく対話の土台になる。
そう思うようになりました。

設計書は未来の読者への手紙

コメントが未来の読者への手紙であるように、設計書も未来の自分やチームへの手紙だと思うのです。

手紙に書くのは、結果の報告だけではない。
「こうしました」ではなく、「こうした理由は、こうだったのです」。
選択の背景、妥協した理由、迷ったポイント。
コードや図には表れない、判断の痕跡を数行で残す。

そう考えると、何を書くかがはっきりしてきます。

💭 なぜこのアーキテクチャを選んだか
　（他の選択肢と比べて、ここを選んだ理由）

💭 なぜこの境界で分けたか
　（責務の切り方で迷った点）

💭 ここは将来変える可能性があること、変えるときの注意点

「何をしているか」は、図やコードが語る。
設計書に書くべきなのは、「なぜ、そうしているか」なのだと、僕は思います。

正解を押しつけない設計書

設計書は正解を押しつけるものじゃない。
迷った痕跡を共有するドキュメントとして書いていく。

その積み重ねが未来の自分やチームが設計を理解し、変更を判断しやすくする。
「設計書に書いてあるから変えられない」ではなく、「設計書に書いてあるから、なぜ変えていいか分かる」。

もしあなたが設計書を書くとき。
一度だけ迷った痕跡を一行でもいいから残してみてください。
その一手間が未来の誰かを、きっと助けてくれるはずです。

ひとりごと

設計書を正解の記録ではなく判断の痕跡を残すものとして捉え直してから、僕の設計書の書き方は変わりました。
結論だけでなく、なぜそうしたか、どこで迷ったかを書く。
それだけで半年後に読み返したとき、ずいぶん助かっています。

このエッセイを読んでくれたあなたも、もし設計書を書くとき迷った痕跡を残してみてください。
その一手間が未来の誰かを、きっと救ってくれるはずです。

あわせて読みたい

▼ コメントに意図を残したいときに

コードが語る結果と、コメントが語る意図を分ける。
設計書に迷った痕跡を残すのと同じように、未来の読者に届くコメントの書き方を綴ったエッセイです。

次の一歩を一緒に決める 「作戦会議室」 へ

設計書の書き方やチームでのドキュメントの共有について、仲間と一緒に言葉にしていく場があります。
作戦会議室では、フリーランスとしての開発の進め方やクライアントとの認識合わせについても経験を共有しています。

一人で抱え込まず、少しだけ誰かと話してみる。
その一歩として作戦会議室の扉を開いてみてください。

参加する