設計判断の経緯を残す｜「なぜこうしたか」を1枚に書く記録術
「このキャッシュ、なんで5分なんだっけ」 「DBを分けずに1台で持っているの、何か理由があった気がする」
画面の前で手が止まる。しかも、決めたのはたぶん自分です。半年前、ちゃんと考えて決めたはずなのに、理由だけがきれいに抜け落ちている。
これは記憶力の問題ではありません。設計を決めた日は、決めること自体で手いっぱいです。理由は頭の中では当たり前すぎて、わざわざ書く気にならない。だから、いちばん大事な「なぜ」から先に消えていきます。
この記事では、設計判断の経緯を決めた直後に、1枚・5項目だけ残す方法を一緒に整理します。立派な設計書は要りません。
結論：設計で何かを決めたら、その日のうちに「背景・決めたこと・理由・見送った案・見直すきっかけ」の5項目を1枚に書きます。置き場所はコードと同じリポジトリの1フォルダ。書いたものはあとから書き換えず、考えが変わったら新しい1枚を足して「置き換え」と書きます。この形は ADR（Architecture Decision Record＝アーキテクチャ決定記録）と呼ばれる、広く使われている記録の型です。
何が起きているか：「なぜ」だけが消えていく
システムには「何を」は残りやすく、「なぜ」は残りにくい性質があります。
- 何を：コードや設定ファイルそのものに残る。読めば分かる。
- いつ・誰が：Gitの履歴に残る（git blameで「なぜこのコードか」を追うで、たどる方法をまとめています）。
- なぜ：どこにも残らない。決めた人の頭の中にだけある。
コミットメッセージに「キャッシュ時間を5分に変更」とは書いても、「在庫表示が古いと問い合わせが来るので、DB負荷と天秤にかけて5分にした」までは、なかなか書きません。
そして、理由が分からない設計は、次に触る人を二通りに迷わせます。
- 怖くて触れない：何か理由があるはずだから、と手つかずのまま残り続ける。
- 気軽に変えてしまう：理由を知らずに「普通はこうだよね」と直し、昔いちど踏んだ問題をもう一度踏む。
どちらも、担当者が悪いわけではありません。判断の材料が残っていなかっただけです。
具体例：理由が1行あれば防げたこと
一人運用の現場でよくある場面を、3つ挙げます。
- 「なぜかcronが深夜3時15分」：きりのいい時刻にずらしたら、別システムのバックアップと重なって両方が遅くなった。実は「3時のバックアップを避けるため15分ずらした」が理由だった。
- 「わざと古いライブラリのまま」：更新したら、取引先から届くCSVの読み込みが壊れた。「この版より上は、取引先CSVの古い文字コードを読めない」がメモ1行あれば、更新の前に手を打てました。
- 「セッションをDBに保存している」：遅いのでファイル保存に戻したら、2台構成のサーバー間でログインが切れるようになった。「2台に増やしたときにDBへ移した」が理由でした。
どれも、理由そのものは難しくありません。1行あれば済んだ話です。だからこそ、書く手間を極限まで小さくすれば残せます。
1枚に書く5項目
書く項目は5つだけです。1項目1〜3行で十分。全部埋まらなくても、「理由」だけは必ず書きます。
| 項目 | 書くこと | 例（キャッシュ時間の判断） |
|---|---|---|
| 背景 | 何に困っていて、何を決める必要があったか | 商品一覧が遅く、ピーク時にDBのCPUが張りつく |
| 決めたこと | 実際に採った方法 | 商品一覧のキャッシュを5分にする |
| 理由 | なぜそれを選んだか。何と何を天秤にかけたか | 在庫表示が古いと問い合わせが来る。10分だと苦情が出た実績あり。5分ならDB負荷が許容範囲に収まった |
| 見送った案 | 検討してやめた案と、やめた理由 | DBの増強（費用の承認が下りない）、キャッシュ無効化の仕組み化（今の体制では作り切れない） |
| 見直すきっかけ | どうなったら考え直すか | 在庫連携がリアルタイムになったら／DBを増強できたら |
この中で、あとからいちばん効くのは「見送った案」です。次の人が真っ先に思いつく「普通はこうするよね」は、たいてい自分も一度検討して、理由があってやめた案です。そこに理由が書いてあれば、同じ検討を二度しなくて済みます。
「見直すきっかけ」も地味に効きます。設計判断は、そのときの事情に合わせた暫定の最適解であることがほとんどです。前提が変わったら見直していい、と書いてあるだけで、次の人は遠慮なく変えられます。
そのまま使えるひな型
ファイル名は「連番-内容」にしておくと、並べたときに時系列で読めます（例：0007-shohin-cache-5fun.md）。
# 0007 商品一覧のキャッシュを5分にする
- 日付：2026-10-24
- 状態：採用 （採用 ／ 置き換え済み → 00XX）
- 記録：（自分の名前）
## 背景
商品一覧が遅く、ピーク時にDBのCPUが張りつく。
## 決めたこと
商品一覧のキャッシュを5分にする。
## 理由
在庫表示が古いと問い合わせが来る。10分にしたときは苦情が出た。
5分ならDB負荷が許容範囲に収まった（検証環境で計測）。
## 見送った案
- DBの増強：費用の承認が下りない
- 在庫更新時にキャッシュを消す仕組み：今の体制では作り切れない
## 見直すきっかけ
在庫連携がリアルタイムになったとき／DBを増強できたとき設計判断の記録を続ける3つのルール
① 決めた「その日」に書く
経緯の記録は、時間がたつほど書けなくなります。見送った案の理由は、とくに早く消えます。決めた日の作業の最後に、10分だけ。これ以上の工夫は要りません。
「どの判断を書くか」で迷ったら、目安は1つです。「次の人が、普通はこうしないよね、と思いそうな判断」。定石どおりの選択は書かなくていい。ひねった判断、妥協した判断、事情があって外した判断だけで十分です。
② 置き場所はコードの隣にする
おすすめは、コードと同じリポジトリに docs/decisions/（docs/adr/ でも可）のようなフォルダを1つ作ることです。
- コードと一緒に引き継がれるので、行方不明になりにくい。
- コミットで履歴が残るので、いつ書いたかも分かる。
- 該当するコードのコメントに「経緯は docs/decisions/0007 を参照」と1行書けば、コードから記録にたどり着ける。
社内Wikiのほうが見る人が多い現場なら、Wikiでも構いません。大事なのは置き場所を1つに決めることです（置き場所の決め方は運用ドキュメントを腐らせない更新ルールでも触れています）。
③ 書き換えずに、新しい1枚を足す
考えが変わったら、古い記録を直したくなります。でも、そこはぐっとこらえて新しい1枚を足し、古いほうの状態を「置き換え済み → 0012」と書き換えるだけにします。
古い判断と理由がそのまま残っていると、「最初はこう考えて、こういう事情でこう変えた」という流れが読めます。この流れこそが、レガシーを引き継いだ人がいちばん欲しい情報です。
影響：経緯が残っていると、何が変わるか
- 触っていいかどうかを、自分で判断できる：「見直すきっかけ」を満たしていれば変えていい、と分かる。怖くて放置、が減ります。
- 同じ失敗を二度踏まない：見送った案の理由が、次の人の遠回りを止めてくれます。
- 説明がラクになる：上司や取引先に「なぜこの構成なのか」と聞かれたとき、1枚見せれば済みます。
- 引き継ぎの重さが減る：口頭で全部伝えなくても、記録のフォルダを渡せば判断の歴史ごと引き継げます（作った人がいないシステムを引き継いだ初日にやることと合わせてどうぞ）。
そして何より、半年後の自分が助かります。「なぜこうしたんだっけ」の答えが、自分の字で残っている。それだけで、ずいぶん安心して触れるようになります。
すでに理由が分からない過去の設計はどうするか
過去の判断まで全部書き起こす必要はありません。おすすめは、次に触るときについでに1枚です。
- 調べて理由が分かったら、そのまま5項目で記録にする。
- 分からなかったら、「2026-10-24時点で経緯不明。コミット・チケットに手がかり無し」と分からなかったことを記録する。
分からなかったという記録も、立派な経緯です。次の人は、同じ調査を一からやり直さずに済みます。調べ方そのものは仕様書がないシステムの仕様を、現状から起こす進め方が参考になります。
明日やること：最近の判断を1つだけ書く
- ここ1か月で自分が決めた設計・設定の判断を1つだけ思い出す（キャッシュ時間、バッチの時刻、ライブラリの版を固定した、など）。
- リポジトリに
docs/decisions/フォルダを作る。 - 上のひな型をコピーして、
0001-<内容>.mdとして保存する。 - 「理由」と「見送った案」を先に書く。背景と決めたことは後からでも書けます。
- 該当するコードか設定ファイルのそばに、「経緯は docs/decisions/0001 を参照」と1行足す。
10分で終わります。1枚目ができれば、2枚目からはひな型を埋めるだけです。
設計判断の記録チェックリスト
書いた1枚を、この項目で見直してみてください。全部そろわなくても大丈夫です。
- 「理由」が、事情や天秤（何と何を比べたか）まで書けているか
- 検討してやめた案と、やめた理由を1つ以上書いたか
- どうなったら見直していいか（見直すきっかけ）を書いたか
- 日付と状態（採用／置き換え済み）が入っているか
- 置き場所は決めた1か所（
docs/decisions/など）になっているか - コードや設定のそばから、記録にたどり着ける1行を足したか
- 考えが変わったとき、古い記録を消さずに新しい1枚を足す運用になっているか
- 理由が分からない過去の設計は、「分からなかった」ことを記録できているか
よければ、こちらも
- git blameで「なぜこのコードか」を追う｜履歴の読み方：記録が残っていない過去のコードの経緯を、履歴からたどる方法です。
- 古いまま放置しない｜運用ドキュメントを腐らせない更新ルール：書いた記録を「信じられる資料」のまま保つための更新ルール。
- 仕様書がないシステムの仕様を、現状から起こす進め方：判断の記録より手前の「そもそも何をしているか」を起こすときに。
- 変更管理台帳の付け方｜いつ・誰が・何を変えたか残す：「何をいつ変えたか」は台帳に、「なぜ」は決定記録に。役割を分けると両方が軽くなります。
設計の理由を思い出せないのは、あなたがいい加減だったからではありません。決めた日、ちゃんと目の前の問題に集中していた証拠です。足りなかったのは、それを書き留める小さな型だけでした。
今日書く1枚は、半年後のあなたと、いつかこのシステムを引き継ぐ誰かへの、短い手紙です。まずは最近の判断を1つ。「理由」の欄に2行、書いてみるところから始めましょう。
ほかの実務ヒントは記事一覧からどうぞ。保守運用の小さな備えを、メールでも少しずつお届けしています。