第9章：完了からナレッジ化（FAQ/Runbook/ADRへの流し込み）

この章で学ぶこと

• 完了時に「残すべき情報」を選別する
• FAQ/Runbook/ADR など再利用先へ転記する
• ナレッジの Owner と更新タイミングを決める

成果物（書けるようになるもの）

• 完了コメント（結論/根拠/運用影響/残タスク）を書ける
• 転記先（FAQ/Runbook/ADR）とリンクを追加できる

本文

Issue は「作業ログ」としては有効だが、運用で再利用しやすい形ではないことが多い。完了時に整形して移す。

転記の判断

• 繰り返し起きる: FAQ/Runbook
• 判断の背景が重要: ADR
• 手順が重要: 手順書/Runbook
• 事故の学び: ポストモーテム

完了の定義に「ドキュメント更新」を含める（運用ルール）

実装が終わっても、運用で再利用できなければ「次に同じ事故が起きる」。完了（Done）の最小要件として、必要なドキュメント更新を含める。

• 変更が運用に影響する: Runbook/手順書（復旧/ロールバック/問い合わせ対応）
• 判断の背景が重要: ADR（なぜその選択をしたか）
• 問い合わせが繰り返される: FAQ（短く再利用）

更新したドキュメントは、Issue/PR の完了コメントで相互リンクする（「どこに残したか」を迷わせない）。

参考（書式/粒度）: https://itdojp.github.io/engineering-documentation-book/

注意点（転記のコツ）

• Issue は“作業ログ”として残し、再利用先（FAQ/Runbook/ADR）には結論と判断根拠を要約して残す（機微情報の貼り付けは要注意）
• Owner と更新タイミング（どのイベントで見直すか）を決めないと、ドキュメントが陳腐化しやすい
• “やらない選択”でクローズする場合も、理由と再オープン条件は残す（付録: トリアージ判断表の「対応しない」判断）

具体例（悪い例→良い例）

悪い例

Close します。
結論/変更/影響が残らない

良い例

結論: バリデーションを追加し誤操作率を低減
変更: PR #456
影響: エラーメッセージが変更
運用: FAQ を更新（リンク）
残タスク: 文言ポリシーの整備（Issue #789）

チェックリスト

• 結論/変更点/影響が残っている
• 転記先が決まっている（必要に応じて）
• Owner/更新タイミングが決まっている

まとめ

• 完了時に結論/根拠/影響/残タスクを残し、後から追える状態にする
• Runbook/FAQ/ADR などの再利用先へ転記し、Owner と更新タイミングを決める

次章への接続

• 付録: テンプレ集