「このバッチ処理、月末だけ計算式が変わるんですが、なぜそうなるのか分かる方はいますか」——受託でシステムを引き継ぎ、いざ改修に入ると、手が止まるのは技術的な難しさよりも**「なぜこのコードはこう書かれているのか」が誰にも分からないときです。コードは動いている。しかし、その背後にある業務上の理由——どの法令に対応した処理か、なぜこの顧客区分だけ例外なのか、この丸め方は何の慣習に従っているのか——が、コードのどこにも、ドキュメントのどこにも残っていない。担当者はすでに退職し、当時の事情を知る人はいない。改修が止まるのは、技術ではなくドメイン知識（業務領域の知識）の欠落**が原因です。
この問題を正面から論じているのが、Zenn の記事 リファクタリングにドメイン知識が要るなら、その知識はどこに置くのか（Zenn） です。AI がコードを書く時代になっても、「なぜそう書くべきか」を決めるドメイン知識は、コードの外から与えられなければならない。その知識をどこに置くかが、これからの保守性を左右する——という論点です。本記事では、受託で引き継ぐシステムにおいて、改修に必要なドメイン知識をどこに、どう残すかを、システム開発の立場から整理します。
なぜドメイン知識は失われるのか
ドメイン知識がコードから失われていく経路は、おおむね決まっています。
第一に、「動くコード」だけが残り、「なぜ」が残らない。実装した本人にとっては自明だった業務ルールは、わざわざ書き残されません。コードは結果だけを語り、理由を語らないので、本人が去れば理由は消えます。
第二に、知識が人に貼り付いている。「あの処理のことは Aさんに聞けば分かる」という状態は、回っているうちは効率的ですが、その人が異動・退職した瞬間に、組織からその知識が消えます。受託で引き継ぐ側にとって、最も困るのがこのパターンです。
第三に、ドキュメントとコードがずれていく。仕様書はあっても、改修のたびに更新されず、やがて「コードと違うことが書いてある信用できない文書」になる。すると誰も読まなくなり、知識の置き場として機能しなくなります。
結果として、コードを直すたびに「まず業務を再ヒアリングする」ところから始める羽目になり、改修のコストが膨らみます。なぜその設計を選んだかという技術判断の記録についてはADR（設計決定記録）の記事で扱いましたが、本記事で問題にするのはその一段手前、「業務上、なぜこの処理が必要なのか」という知識そのものの置き場所です。
ドメイン知識を「どこに」残すか — 三つの置き場
ドメイン知識の置き場には、それぞれ得手不得手があります。重要なのは、一か所に頼らず、性質に応じて使い分けることです。
| 置き場 | 向いている知識 | 弱点 |
|---|---|---|
| コードの近く（コメント・命名・型） | 「この一行がなぜ必要か」 | 全体像や背景は書ききれない |
| テスト | 「どう振る舞うべきか（具体例）」 | 「なぜ」までは表しにくい |
| ドキュメント | 背景・経緯・全体ルール | 更新されないと腐る |
第一の置き場は、コードのすぐ近くです。なぜこの分岐があるのかを一行コメントで残し、taxExemptForSmallBusiness のように業務の言葉で命名し、型で「ありえない値」を排除する。「この一行がなぜ必要か」は、コードのそばにあるのが最も腐りにくい。
第二の置き場は、テストです。「月末は計算式が変わる」という業務ルールは、月末の入力に対する期待値をテストとして書いておけば、振る舞いの仕様が実行可能な形で残ります。コードを変えてテストが落ちれば、業務ルールを壊したことに気づける。テストは「腐らないドキュメント」として働きます。
第三の置き場は、ドキュメントです。「なぜこの顧客区分だけ例外なのか」という背景や経緯、業務全体のルールは、コードやテストには収まりません。これはドキュメントに書く。ただし後述するとおり、更新され続ける仕組みとセットにしないと腐ります。
「腐らせない」ための原則
置き場を決めても、更新されなければ意味がありません。受託で実効性を持たせる原則は二つです。
ひとつは、改修とドキュメント更新を「ひとつの作業」にすること。コードを直すプルリクエストの中で、関連する背景の記述も一緒に直す。別作業にすると、必ず後回しになり、ずれていきます。
もうひとつは、「なぜ」を優先して残すこと。「何をしているか」はコードを読めば分かりますが、「なぜそうするか」はコードからは読み取れません。限られた労力をどこに使うか迷ったら、処理の説明より、その処理が存在する業務上の理由を残すほうが、後の改修を救います。本当に共通な土台だけを括り出す設計判断と同じく、知識も「後で効くもの」を選んで残すのが肝心で、間違った抽象化を重複に戻す記事で触れた「なぜこの構造なのかが残っていないと解きほぐせない」という問題は、まさにこのドメイン知識の欠落と表裏一体です。
受託で組み込むときの落とし穴
弊社が改修を引き継いだある販売管理システム（社名は伏せます）では、出荷の締め時刻に関する処理が複雑な分岐になっており、なぜその時刻なのか、なぜ特定の地域だけ別扱いなのかが、コードにもドキュメントにも一切ありませんでした。改修のたびに、お客様の現場担当者に電話で業務を教わり、それを頼りに直す——という綱渡りが常態化していました。その担当者が異動したら、システムが触れなくなる寸前でした。
私たちは、改修で触れた箇所から順に、「なぜ」をコードのコメントとテストに落としていくことから始めました。締め時刻の根拠を一行で残し、地域別の例外を業務の言葉で命名し、「この地域は締めが一時間早い」という規則をテストの期待値として書く。背景や経緯は、コードの近くに置けないぶんだけドキュメントにまとめ、改修のプルリクエストの中で一緒に更新する運用にしました。結果、次の改修からは「まず業務を再ヒアリングする」工程が要らなくなり、担当者が代わっても知識がシステム側に残るようになりました。やったのは、ヒアリングで得た知識を、その場で消さずにコードとテストに固定しただけです。
この案件で一番効いた学びは、ドメイン知識の棚卸しを「一度に全部」やろうとしないことでした。全業務を最初に文書化しようとすると、量に押し潰されて頓挫します。改修で実際に触れた箇所から、その都度「なぜ」を残していく。この積み上げ方は、システム全体を止めずに段階的に整える進め方——モノレポで依存を整理する記事で扱った「触る部分から順に寄せる」方針——と同じで、知識の整備も少しずつが現実的です。
どこから着手するか
改修が止まる原因を「技術が難しいから」と捉える前に、「業務上の理由が残っていないからではないか」と疑うところから、引き継いだシステムは触れるようになります。コードの近くに「なぜ」を、テストに「どう振る舞うべきか」を、ドキュメントに「背景と経緯」を——性質に応じて置き場を分け、改修と一緒に更新する。これが、ドメイン知識を腐らせず残す基本です。
最初の一歩としては、直近の改修で「お客様に業務を教わらないと直せなかった箇所」を一つ思い出し、そのとき得た理由を、コードのコメントとテストに固定してみることをお勧めします。それだけで、次の改修から再ヒアリングが一つ減ります。
改修のたびに業務を聞き直していて手が止まる、知識が特定の人に貼り付いていて引き継ぎが不安、ドキュメントが腐っていて当てにできない——そうしたお悩みがあれば、グリームハブのお問い合わせからご相談ください。現行システムを改修しながら、必要なドメイン知識をコード・テスト・ドキュメントへ段階的に残していく運用を、ご一緒に組み立てます。
