「このバッチ、なぜ夜間に全件洗い替えしてるんですか」——保守を引き継いだ受託システムで、こう問われて答えに詰まる。コードを読めば「何をしているか」は分かります。でも「なぜそうしたのか」——なぜ差分更新ではなく全件洗い替えなのか、なぜこの DB を選んだのか、なぜここだけ非同期なのか——は、どこにも書かれていない。当時の判断を知る人はもう離任していて、誰も理由を説明できない。だから怖くて変えられず、「触ると何かが壊れるかもしれない」設計が、理由不明のまま温存されていく。受託で他社が作ったシステムの保守を引き継ぐと、この壁にほぼ確実にぶつかります。
問題は、設計の「決定」が記録されていないことにあります。コードは「結果」を残しますが、「なぜその結果を選び、どの選択肢を捨てたか」は残しません。これを軽量に補うのが ADR（Architecture Decision Records、設計決定記録）です。InfoQ が 2026 年 6 月に整理した How Lightweight ADRs and Architectural Advice Forums Can Support Architectural Decisions（InfoQ） は、重い設計書ではなく軽量な ADR と「助言フォーラム」を組み合わせて、決定を残しつつ意思決定を遅らせない進め方を紹介しています。本記事では、受託で「引き継げる設計」を残すために、これを実務へどう落とすかを整理します。
なぜコードだけでは設計が引き継げないのか
コードは「現在の状態」を表しますが、設計判断には、コードに現れない情報がいくつもあります。
第一に、捨てた選択肢。「A・B・C を比較して B を選んだ」という事実のうち、コードに残るのは B だけです。後から「なぜ A じゃないのか」と思っても、A を検討して却下したのか、そもそも知らなかったのかが分からない。誰かが良かれと思って A に作り変え、B を選んだ当時の制約（A だと顧客の既存システムと噛み合わなかった等）を踏み直す、という事故が起きます。
第二に、前提の有効期限。「当時はデータ量が少なかったから全件洗い替えで十分だった」という前提は、データが増えれば無効になります。前提が記録されていないと、「もう状況が変わったから変えていい判断」と「今も生きている制約」の区別がつきません。
第三に、責任の所在。受託では、顧客から「なぜこの構成にしたのか」と問われる場面が必ずあります。判断の理由と、それを誰がいつ合意したかが残っていないと、説明責任を果たせません。
ADR は、この三つを「一決定につき一枚」の短い記録で埋めます。重い設計書を最初に書き上げるのではなく、意思決定が起きるたびに、その都度一枚ずつ残していく。これが「軽量」と呼ばれる所以です。
軽量 ADR の基本 — 一決定を一枚に
ADR は、一つの設計判断を、決まった見出しの短い文書に落とします。形式は重要ではなく、最低限「文脈・決定・結果」が揃っていれば機能します。リポジトリ内に docs/adr/0001-xxx.md のように連番で置き、コードと一緒にバージョン管理するのが定石です。
# ADR-0007: 在庫同期を差分更新ではなく夜間の全件洗い替えにする
- ステータス: 承認済み（2026-06-20）
- 決定者: 開発リード / 顧客側システム担当
## 文脈（なぜ今これを決めるか）
顧客の基幹システムは差分APIを提供しておらず、深夜に当日分の
全在庫CSVが1ファイル出力される。リアルタイム連携の要件はない。
データ量は現状5万件、当面10万件以下の見込み。
## 決定
夜間バッチで全件を洗い替えする。差分更新は実装しない。
## 結果（この決定の代償と前提）
- 利点: 実装が単純で、CSV側の欠落・重複に強い（毎回作り直すため）
- 欠点: 日中の在庫はリアルタイムに反映されない（要件上は許容）
- 前提: データ量が数十万件を超えたら全件洗い替えは見直す
- 却下案: 差分更新（A）= 差分APIが無く、CSV比較が複雑になるため見送りポイントは、「却下案」と「前提」を必ず書くことです。冒頭の「なぜ全件洗い替えなのか」という問いには、この一枚があれば即答できます。差分APIが無かったという当時の制約（前提）も、データ量が増えたら見直すという有効期限も残っている。半年後に在庫が増えて見直す段になっても、「この前提が崩れたから再検討する」と判断の起点が明確です。
書くタイミングは「重要で・後から変えにくく・理由が自明でない」判断に絞ります。すべての実装を ADR にすると形骸化するので、データストアの選定、連携方式、認証方式、非同期化の境界——といった「後で必ず理由を問われるもの」だけを対象にするのが長続きのコツです。
「助言フォーラム」で決定を遅らせず、独断にもしない
ADR が「決定の記録」なら、助言フォーラム（Architectural Advice Forum）は「決定の進め方」です。InfoQ の記事が紹介するこの仕組みの肝は、決める人は分散させたまま、決める前に必ず関係者の助言を集める点にあります。中央のアーキテクトが全部承認するボトルネックを作らず、かといって各自が独断で決めて後から衝突する状態も避ける——その間を取る運用です。
具体的には、ある判断を下す人が、決定前にその判断の影響を受ける人（他の開発者・運用担当・顧客側担当）から助言を募り、もらった助言と、それを採否した理由を ADR に書き残します。助言に従う義務はありませんが、聞かずに決めることはできない。受託の文脈では、この「助言を求める相手」に顧客側のシステム担当を含めることが効きます。
| 進め方 | 速度 | 質 | 受託での問題 |
|---|---|---|---|
| 中央アーキテクトが全決定を承認 | 遅い（ボトルネック） | 高い | リードが離任すると止まる |
| 各自が独断で決める | 速い | ばらつく | 後から衝突・顧客と認識ずれ |
| 助言フォーラム＋ADR | 速い | 安定 | 助言を集める習慣づけが要る |
この「権限を中央に集めず、しかし統制は効かせる」発想は、システム運用の他の領域とも地続きです。本番への常設アクセスを撤廃して監査可能なジョブ実行に寄せる考え方を扱った常設SSHを廃しジョブ実行を委ねる記事や、AIエージェントの権限を委任で表現するAIエージェントの認証認可の記事と同じく、「分散させても追跡・説明できる形にする」という統制設計の一種です。
受託で導入するときの落とし穴
弊社が保守を引き継いだある物流会社の在庫管理システム（社名は伏せます）は、まさに「なぜこの設計か誰も知らない」状態でした。前述の在庫全件洗い替えバッチについて、顧客から「リアルタイムにしてほしい」と要望が出たものの、当初の制約（基幹側に差分APIが無い）を誰も把握しておらず、安易にリアルタイム化を約束しかけていた。
私たちは、まず現行システムの「変えにくく理由が不明な判断」を十数件洗い出し、コードと当時の関係者へのヒアリングから、後追いで ADR を書き起こしました。差分APIが無いという制約が文書化された時点で、リアルタイム化には基幹側の改修が前提になることが顧客と共有でき、要望は「日中数回の準リアルタイム更新」という現実的な落としどころへ着地しました。以降は、新たな設計判断が出るたびに、顧客側担当も交えて助言を集め、決定を ADR として残す運用に切り替えました。派手なドキュメント整備はしていません。やったのは、これから下す判断を一枚ずつ残し、過去の重要判断を後追いで補っただけです。
この案件で一番効いた学びは、ADR は「未来の判断」から始めるのが正しいということです。過去の全設計を遡って文書化しようとすると、量に圧倒されて頓挫します。まずこれから下す判断を一枚ずつ残し、過去分は「触る必要が出た箇所」だけ後追いで書く。そうすれば負担は小さく、しかも「いちばん変更が起きやすい場所」から理由が揃っていきます。
もう一つの落とし穴は、ADR を書いて終わりにすることです。状況が変われば、過去の決定の前提は崩れます。前提が崩れた決定は「却下」ではなく「上書き（superseded）」として、新しい ADR から古い ADR を参照する形で更新します。決定の履歴が連鎖として残ることで、「いつ・なぜ方針を変えたか」まで引き継げるようになります。
どこから着手するか
「なぜこの設計か説明できない」箇所が一つでもあるなら、ADR を始める価値があります。完璧な様式は要りません。文脈・決定・却下案・前提の四つが書かれた短い Markdown を、リポジトリの docs/adr/ にコードと一緒に置くところから始められます。
最初の一歩は、いままさに迷っている設計判断を一つ選び、それを一枚の ADR にすること。決める前に、影響を受ける人（顧客側担当を含む）から助言を集め、採否の理由ごと書き残す。これを習慣にできれば、半年後にその判断を問われても、また状況が変わって見直す段になっても、起点を即座に取り出せます。
引き継いだシステムの設計意図が分からず手を入れられない、保守の属人化を解消したい——そうしたお悩みがあれば、グリームハブのお問い合わせからご相談ください。現行システムの重要な設計判断を後追いで ADR に起こし、これからの意思決定を引き継げる形に整える支援をします。
