引き継ぎ資料の失敗には型があります。分厚いのに役に立たないというものです。原因は明確で、コードを読めば分かることを書き写しているからです。
この回は、何を書き、何を書かないかの線引きを扱います。書かない判断のほうが、実は難しい。
1. コードから読み取れるものは書かない
原則はこれだけです。読み取れるものを書き写すと、二重管理になって必ず古くなります。しかも読む側は、資料とコードのどちらが正しいか判断できません。
| 内容 | コードから読めるか | 資料に書くか |
|---|---|---|
| 処理の流れ | 読める | 書かない |
| テーブルの構造 | 読める（定義がある） | 書かない |
| 環境変数の一覧 | 読める | 書かない（雛形を置く） |
| なぜその設計にしたか | 読めない | 書く |
| 何を試して駄目だったか | 読めない | 書く |
| 触ってはいけない箇所と理由 | 読めない | 書く |
| 誰に聞けばよいか | 読めない | 書く |
| 定期作業と、その所要時間 | 読めない | 書く |
5行目が最も価値があります。試して駄目だった案は、コードに一切残りません。書かなければ、後任は同じ失敗を最初から繰り返します。これは引き継ぎ資料でしか伝えられない情報です。
コードを読ませれば「何をしているか」の要約は得られます。しかし「なぜそうしたか」は、書かれていない限り復元できません。生成できるものは書かなくてよく、生成できないものだけを人が残す ── これが現時点での合理的な分担です。
2. 判断の記録を残す
「なぜそうしたか」を残す軽量な方法が です。選んだ案と、選ばなかった案を、理由とともに短く記録します。
# 0007. 集計をバッチではなくビューにする
- 日付: 2026-10-21- 状態: 採用
## 背景日次バッチで集計表を作っていたが、当日分が翌朝まで見えないという要望が繰り返し出ていた。
## 決めたこと集計をビューに変え、参照時に計算する。
## 選ばなかった案- バッチの実行間隔を1時間に短縮 → 実行時間が40分あり、間隔を詰めると重なる- 差分更新に変更 → 更新日時が信頼できない列があり、取りこぼす
## 承知しているトレードオフ参照のたびに計算するため、画面表示が2〜3秒遅くなる。件数が3倍になったら再検討する。選ばなかった案の節が最も重要です。後任が「なぜバッチにしないのか」と考えたとき、すでに検討済みで、こういう理由で外したと分かります。これがないと、同じ検討を最初からやり直すことになります。
最後の再検討の条件も効きます。「件数が3倍になったら」と書いてあれば、その判断が永久のものではないと伝わります。条件が満たされたときに、後任が自信を持って変更できます。
3. 定期作業は手順として書く
判断の記録とは別に、定期的にやることの手順が要ります。 と呼ばれるもので、条件は一つ ── 書いた本人以外が読んで実行できることです。
- いつ実行するか — 頻度と、実行すべき時間帯の制約
- 実行前に確認すること — 前提が崩れていないか
- 具体的なコマンドや操作 — 「適宜」と書かない
- 成功したと判断する基準 — 何を見て終わりとするか
- 失敗したときの対処 — 途中で止まったらどうするか
- 誰に連絡するか — 判断が必要な場合の相手
4番目が抜けている手順書は非常に多いです。実行はできるが、成功したか分からないという状態になります。「エラーが出なければ成功」では不十分で、期待する結果を確認する手順まで含めてください。これは LLM時代のテスト戦略 EP.02 で扱った「弱いアサーション」と同じ構造です。通ったことと、検証されたことは別という点で共通しています。
書いた本人には自明でも、後任には判断できません。適宜と書きたくなったら、そこが判断の要る箇所だという印です。判断基準を書くか、あるいは「ここは相談してください」と明記してください。
4. 書く時間を確保する現実的な方法
「資料を作る時間がない」というのは、ほぼ全ての現場で聞く話です。離任前にまとめて書くという前提が非現実的なのだと思います。
現実的なのは、判断したその場で1行残す方式です。設計を決めた瞬間、駄目だった案を捨てた瞬間に書けば、思い出す作業が不要になります。
| 方式 | 所要時間 | 内容の質 |
|---|---|---|
| 離任前にまとめて書く | 数日 | 思い出せた範囲だけ |
| 判断のたびに1行書く | 都度1分 | 判断の直後なので正確 |
後者は総量では多くの時間を使いますが、まとまった時間を要求しないという決定的な利点があります。そして内容の質が段違いです。3か月前になぜその判断をしたかは、たいてい思い出せません。
5. 置き場所を決める
書いても、見つからなければ存在しないのと同じです。置き場所には条件があります。
- 1コードと同じ場所に置く — 変更と同時に更新される可能性が上がる
- 2検索できる — 全文検索の対象になっていること
- 3権限が引き継がれる — 個人のアカウントに紐づく場所に置かない
- 4入口が1つ — どこから読み始めるかが明確なこと
3番目は実務でよく問題になります。個人のアカウントで作った文書は、離任と同時にアクセスできなくなることがあります。組織の領域に置くか、リポジトリに含めるのが確実です。 で統合されている環境では、元のアカウントを止めた瞬間に文書も見えなくなるため、この問題が顕在化しやすい。便利さと裏表の関係にあります。
4番目も効きます。文書が10個あっても、どれから読むべきか分からなければ読まれません。「まずこれを読む」という1ファイルを決めて、そこから他へリンクする形にしてください。
6. 資料の分量は少ないほうがよい
最後に、量についての立場を書きます。分厚い資料は読まれません。そして読まれない資料は、無いのと同じです。
コードから読めることを削ぎ落とすと、残るのは驚くほど少ないはずです。判断の記録が数十件、定期作業の手順が数本、連絡先が1枚。これで足ります。逆に、それ以上に膨らんでいるなら、読めることを書き写していないかを疑ってください。
引き継ぎ資料の目的は、網羅することではなく、後任が最初の1か月で詰まる箇所を減らすこと。
コードから読めるものは書かない（二重管理になり必ず古くなる）。書くのはなぜそうしたか、何が駄目だったか、触ってはいけない箇所、誰に聞くか。判断は ADR として選ばなかった案とともに残す。手順書には成功の判断基準まで書く。そして離任前にまとめて書く前提を捨て、判断のたびに1行残す。次回は属人化の棚卸しを扱います。
この記事の感想を教えてください
あなたの 1 クリックで、本当にこの記事は更新されます。「もっと詳しく」「続編希望」が一定数集まった記事は、 ふくふくが 実際に内容を拡充したり続編記事を公開 します。 送信したリアクションはお使いのブラウザに記録され、再カウントされません。