システム開発の知識継承を止めない：コード、仕様、設計判断をつなぐ方法

システム開発の知識継承が止まる原因は、文書の不足だけではありません。
コード、仕様、設計判断、運用手順が別々に更新され、どれを信じるべきか分からなくなることが、引き継ぎを難しくします。

対策は、資料を一度に作り直すことではありません。
変更が起きたときに、関係する記録も同じ流れで更新される仕組みを作ることです。

知識が消えるのは、文書が少ないからではない

ソースコードは、システムが現在どう動くかを示します。
しかし、なぜその設計を選んだのか、どの制約を優先したのか、障害時にどこまで止めてよいのかまでは、コードだけから確定できません。

一方、仕様書や手順書が残っていても、最終更新日が古く、実装との対応関係が分からなければ、担当者は内容を検証するところから始めることになります。
資料の量が増えても、信頼できる入口がなければ調査時間は減りません。

生きたドキュメントとは、常に長文で詳しく書かれた資料ではなく、変更とレビューの流れに組み込まれた記録です。
更新条件、責任者、関連するコードや運用手順へのリンクが明確であることが、文書の寿命を決めます。

AI駆動開発が知識継承に与える影響

開発支援AIは、コード作成、テスト、調査、文書の下書きを速めます。
ただし、変更量が増えれば、仕様との整合性確認、レビュー、リリース判断、運用手順の更新も増えます。

日本IBMが発表したALSEAは、組織の知見やルールをAIが利用できる「コンテキスト」として体系化し、成果物の品質と整合性を維持する「ハーネス」を組み合わせています。
この設計が示すのは、開発支援AIの性能だけでなく、何を参照させ、どの規則で検証するかを組織側が管理する必要があるということです。

DORAの調査では、生成AIの利用増加は文書品質やコードレビュー速度の改善と関連する一方、デリバリーの安定性やスループットには負の関連も観測されました。
これは因果関係を断定する結果ではありませんが、個々の作業が速くなっても、変更管理やリリース工程を含む全体が自動的に良くなるわけではないことを示唆します。

日立とAnthropicの協業でも、コード生成能力だけでなく、ミッションクリティカル領域のドメイン知識、運用、安全性を組み合わせる方針が示されています。
業務知識と運用知識を、実装から切り離さずに扱う考え方が共通しています。

残すべき4種類の記録

一つの巨大な仕様書へすべてを集約すると、更新範囲が広がり、担当者が変更を避けるようになります。
役割が異なる記録を分け、相互にリンクしたほうが更新単位を小さくできます。

設計判断記録には、会議の議事録をそのまま貼り付ける必要はありません。
後から判断を再評価できるように、前提、選択肢、採用理由、見直し条件を短く残します。

文書更新を変更イベントに組み込む

「余裕があるときに文書を更新する」という運用では、納期が近づくほど更新が後回しになります。
コード変更、仕様変更、リリース、障害対応を、対応する記録の更新条件にします。

• プルリクエストに「影響を受ける仕様、設計判断、運用手順」を記入する欄を置く。
• APIやデータ形式を変えるときは、スキーマと利用例の差分を同じレビューへ含める。
• 新しい監視項目やアラートを追加したら、原因の切り分け方と連絡先も更新する。
• 障害対応後は、時系列の報告だけで終えず、次回の検知と復旧に使う手順へ反映する。
• 廃止した機能の文書は、削除するか、廃止済みであることと移行先を明記する。

自動チェックは、リンク切れ、必須欄の欠落、スキーマとの差分など、機械で判定できる範囲に限ります。
設計理由が妥当か、運用手順が現場で実行できるかは、担当者が確認する必要があります。

レビューで確認する三つの整合性

文書レビューを誤字の確認だけにすると、実装とのずれは残ります。
レビューでは、正しさ、説明可能性、運用可能性を分けて確認します。

• 正しさ：現在のコード、設定、権限、データ形式と一致しているか。
• 説明可能性：採用理由と前提が残り、別の担当者が判断を再現できるか。
• 運用可能性：障害時に、必要な権限を持つ担当者が手順を実行できるか。

開発支援AIの権限、検証、承認、計測まで含めた運用は、AI駆動開発を企業システムに定着させる方法で詳しく整理しています。
今回の知識継承設計は、その運用基盤へ、信頼できる参照情報を供給する役割を持ちます。

4週間で始める改善手順

第1週は信頼できる入口を決める

既存資料をすべて改訂せず、主要なシステムごとに、現在仕様、設計判断、運用手順の正本がどこにあるかを一覧化します。
重複文書はすぐに統合せず、参照停止候補として印を付けます。

第2週は短いテンプレートを用意する

設計判断記録と変更記録のテンプレートを作り、実際の変更一件で試します。
必須欄を増やしすぎず、判断の再評価に必要な情報へ絞ります。

第3週は変更フローへ組み込む

プルリクエスト、チケット、リリース手順に、関連文書の更新確認を追加します。
文書だけの変更も通常のレビュー対象にし、更新履歴を残します。

第4週は一件の障害で検証する

過去の障害を一件選び、新しい担当者が記録だけで検知、切り分け、復旧判断まで進められるかを確認します。
止まった箇所が、次に更新する対象です。

知識継承を測る指標

文書数や文字数は、知識継承の成果を示しません。
担当交代や障害対応で、記録が実際に使えたかを測ります。

• 新しい担当者が、対象機能の変更箇所と影響範囲を特定するまでの時間
• 変更と関連文書の更新が同じレビューで完了した割合
• 手順不足や古い記述が原因で、障害対応が止まった件数
• 正本が分からない重複文書の件数
• 設計判断の前提が変わったのに、再評価されていない記録の件数

最初から全指標を集める必要はありません。
「新しい担当者が変更の影響範囲を特定するまでの時間」と「障害対応で手順が使えたか」の二つから始めると、改善対象を見つけやすくなります。

よくある質問

文書の責任者は誰にすべきですか

文書管理の専任者だけに任せると、実装変更との距離が広がります。
内容を変更できる担当者が更新し、業務、設計、運用の責任者がそれぞれの範囲を承認する形が現実的です。

開発支援AIに文書更新を任せられますか

差分の要約、リンク候補の提示、テンプレートの下書きには使えます。
ただし、採用理由、業務上の制約、停止判断のように組織が責任を負う内容は、担当者が確認して確定します。

古いシステムでは何から始めればよいですか

全体仕様の再作成より、障害対応と頻繁な変更に使う記録を優先します。
現在の入口、主要な依存先、復旧手順、変更時の確認項目がそろうと、次の調査が短くなります。

文書ツールを統一すべきですか

検索、権限、履歴、リンクが安定する範囲では統一が役立ちます。
ただし、ツール移行を先に大規模化するより、正本の場所と更新条件を決めるほうが先です。

参考資料

• 日本IBM「エンタープライズ向けAI駆動開発を本格展開」
• クラウド Watch「日本IBM、エンタープライズ向けAI駆動開発ソリューション『ALSEA』の正式提供を開始」
• 日立製作所「Anthropicと戦略的パートナーシップを締結」
• DORA「Impact of Generative AI in Software Development」