仕様を読んでも引き継げない現場へ──あとから判断できる設計メモの残し方

仕様書はある。設計書もある。画面一覧、項目定義、処理フロー、テーブル定義、レビュー記録も残っている。それなのに、担当者が抜けた途端に、なぜこの仕様なのかが分からなくなる現場がある。

僕は、これはドキュメント不足だけの問題ではないと思っている。むしろ、資料の量はそれなりにあるのに、あとから判断するための情報が抜けていることが多い。

引き継ぎで本当に困るのは、画面名や項目名が分からないことではない。その設計にした理由が分からないことだ。なぜこの条件で分岐しているのか。なぜこの項目は必須なのか。なぜこの連携は同期ではなく非同期なのか。なぜ例外処理をここで吸収しているのか。こうした理由が残っていないと、後任は仕様を読んでも判断できない。

そして判断できない人は、安全側に倒す。変更を避ける。追加調査を増やす。詳しい人を探す。結果として、現場は少しずつ重くなる。誰も悪くないのに、触りづらいシステムだけが残っていく。

設計書は、現在の形を説明するものになりやすい。一方で、引き継ぎに必要なのは、現在の形に至った判断の道筋だ。何を比較し、何を捨て、どの制約を受け入れ、どのリスクを残したのか。その過程が残っていないと、後任は同じ議論をもう一度やることになる。

ここで必要になるのが、設計メモだ。

設計メモは、正式な設計書を増やすことではない。きれいな成果物を一つ追加することでもない。あとから読む人が、当時の判断を再利用できるようにするための短い記録である。

僕なら、設計メモには最低限、四つのことを残す。

一つ目は、何を決めたか。これは結果である。たとえば、注文データの連携方式をバッチ処理にする、承認ステータスは業務側で管理する、権限チェックはAPI側で行う、というように、決定した内容を短く書く。

二つ目は、なぜそう決めたか。ここが一番重要だ。性能のためなのか、運用負荷を下げるためなのか、既存システムの制約なのか、業務部門の確認頻度なのか、監査対応なのか。理由が残っていれば、後任はその前提が今も有効かを見直せる。

三つ目は、何を選ばなかったか。設計判断には、必ず捨てた選択肢がある。同期連携も検討したが、障害時に注文処理全体を止めるリスクがあるため採用しなかった。画面側で制御する案もあったが、複数チャネルで同じ判定が必要になるためAPI側に寄せた。こういう不採用理由は、あとから効いてくる。残っていないと、同じ案が何度も復活する。

四つ目は、将来見直す条件だ。これは意外と残されない。今はこの判断でよい。ただし、データ量が月間何件を超えたら見直す。利用部門が増えたら権限設計を再検討する。監査要件が変わったらログ保持期間を見直す。こうした条件があるだけで、後任は不用意に壊すのではなく、適切なタイミングで見直せる。

大事なのは、設計メモを完璧に書こうとしないことだ。完璧な文章にしようとすると、また誰も書かなくなる。残すべきなのは、美しい説明ではなく、未来の判断材料である。

たとえば、次のような粒度で十分だ。

今回の決定は、処理Aを夜間バッチに寄せること。理由は、リアルタイム反映の業務要求が低く、既存APIの負荷を日中に増やしたくないため。同期連携案は検討したが、障害時に注文登録まで止まるため採用しない。今後、当日中反映が必須になった場合は、キュー方式を含めて再検討する。

これくらいでいい。むしろ、これくらいだから続く。

設計メモを残すとき、もう一つ意識したいのは、誰に向けて書くかだ。未来の自分だけに向けるなら、多少雑でもよいかもしれない。しかし、引き継ぎを考えるなら、未来の他人が読む。未来の他人は、当時の会議の空気も、顧客の温度感も、上司の一言も知らない。だから、空気で決まったことほど言葉にする必要がある。

現場では、明文化されていない前提ほど強い。あの部署は月末だけ処理量が増える。この顧客は帳票の見た目を重視する。運用担当は夜間対応できない。ある特定のエラーは業務側で握りつぶせない。こうした前提は、仕様書の項目には出にくい。でも、判断には深く影響している。

だから設計メモには、技術だけでなく業務の前提も残したほうがいい。技術的に正しい設計でも、業務の使われ方とずれていれば後で崩れる。逆に、多少きれいではない設計でも、業務制約を踏まえた現実解であることが分かれば、後任は不用意に否定しなくなる。

引き継ぎが強い現場は、詳しい人が多い現場ではない。詳しい人がいなくなっても、判断の跡をたどれる現場だ。

もちろん、すべての判断を残す必要はない。細かすぎる記録は、読む側の負担になる。残すべきなのは、後から迷いそうな判断、再議論になりそうな判断、障害時に責任が問われそうな判断、業務部門との合意に関わる判断である。

特に、次のような設計はメモに残したほうがいい。非機能要件に関わるもの。運用手順に影響するもの。権限や監査に関わるもの。外部連携の方式。例外処理の扱い。業務部門が納得した条件。これらは、あとから仕様だけを読んでも背景が見えにくい。

ドキュメントを書く目的は、後任を縛ることではない。未来の変更をしやすくすることだ。

決定理由が残っていれば、後任は変えていいものと変えてはいけないものを分けられる。前提が変わったなら設計も変えてよい。前提が変わっていないなら、安易に変えないほうがよい。その判断ができるだけで、保守はずいぶん楽になる。

僕たちは、よく引き継ぎ資料を作ろうとする。でも本当に残すべきなのは、資料そのものより、未来の誰かが判断できる状態かもしれない。

あなたの現場にある仕様書は、あとから読む人が判断できるようになっているだろうか。
それとも、詳しい誰かの記憶を前提にして、なんとか成立しているだけだろうか。

次に読む：

はじめての方へ：

マガジンの紹介：

IT業界の「技術×キャリア×整える」を束ねるマガジンを公開中です！
ビジネスや心と体を整える良記事が集まってきていますので、
是非、覗いてみてくださいね。
記事は全て無料記事のみです。
気に入って頂けたらマガジンのフォローもよろしくお願いします！
共同マガジンに参加希望の方も募集中です！