SharePoint ページのアーキテクチャ図は 2009 年に作成されました。当時は正確で、大規模なプラットフォーム移行時のシステムの状態を反映しており、すべてのコンポーネントとその関係を文書化するために 3 週間を費やしたアーキテクトによって作成されました。2009 年以降、システムには約 4,800 件のコミットがあり、15 チームが貢献し、図に示されているコンポーネントのうち 4 つは既に存在せず、11 の新しいコンポーネントが追加されましたが、図には示されませんでした。また、図を作成したアーキテクトは 2016 年に退職しました。それでも、この図は残っています。新しい開発者が参加して「システムはどのように動作するのですか?」と尋ねると、誰かが SharePoint のリンクを送ります。この図はドキュメントではありません。考古学的な資料です。
ドキュメント負債とは、ドキュメント層に適用される技術的負債のことです。つまり、ドキュメントがシステムについて述べている内容と、システムが実際に行っていることとの間に蓄積されたギャップのことです。アーキテクチャドリフトとは、図がそれが示すシステムから乖離してしまう状態であり、ドキュメント負債の中で最も一般的で、かつ最も危険な形態です。最も危険なのは、誤った安心感を与えてしまうからです。プロフェッショナルに見える図が存在すると、ステークホルダーはシステムが理解されているという印象を受けますが、実際には、示されている形ではもはや存在しないシステムを記述した過去の遺物を見ているに過ぎません。古い図は、図がないよりも悪いと言えます。なぜなら、図がない場合は、人々は実際に何が存在するのかを調べようとしますが、古い図は、もはや真実ではないものに基づいて行動してしまうからです。
図が陳腐化する5つのメカニズム
ドキュメントの劣化に関する記事はどれも「図は時間の経過とともに古くなる」と述べているが、その具体的なメカニズムを説明しているものはほとんどない。メカニズムを理解することは、劣化を防ぐための前提条件となる。なぜなら、メカニズムが異なれば、必要な予防策も異なるからだ。
1. 累積デルタ問題。図は、ある時点におけるシステムのスナップショットです。そのスナップショット以降のコード変更はすべて、図と現実との間のデルタとなります。個々のデルタは通常小さく、新しいサービス、名前変更されたコンポーネント、追加された依存関係などです。それぞれを個別に文書化するのは簡単です。問題は、誰もそれらを段階的に文書化しないことです。なぜなら、変更ごとに図を更新することは、すぐにメリットのないオーバーヘッドとみなされるからです。記録されていないデルタが100個に達すると、図は実質的に間違っています。1,000個に達すると、図は実質的に架空のものになります。
2.由来情報の欠如という問題。コードとプログラム的にリンクされていない図には、その図が不正確になったことを検出する仕組みがありません。コードベースの変更が図の記述と矛盾した場合でも、それを知らせる信号は存在しません。図とコードは、たまたま同じシステムを記述しているものの、互いに切り離された成果物です。両者のつながりは、図を描いた人の頭の中にのみ存在し、しかもその人が覚えている限りしか存在しません。
3.所有権の移行問題。アーキテクチャ図は通常、特定の人物が特定の時点で作成します。その人物が終了すると、図の正確性を保つための暗黙知、つまりどのコンポーネントが意図的に省略されたか、どの関係が簡略化されたか、どのラベルがより複雑なものを省略したものかといった理解も、その人と共に失われます。図の新しい管理者は、自分が作成したものではなく、完全に理解していない可能性があり、自分が設計していないコードベースに対して保守するインセンティブもない成果物を引き継ぐことになります。
4. 過剰な精度による劣化問題。詳細すぎる図は、適切な抽象化を示す図よりも早く陳腐化します。すべてのマイクロサービス、すべてのAPIエンドポイント、すべてのデータベーステーブルを示す図は、デプロイメントごとに更新する必要があります。サービスドメインとその主要な相互作用パターンを示す図は、ドメイン境界が変更された場合にのみ更新すれば済みます。過度に詳細な図の陳腐化の半減期はスプリント単位ですが、適切に抽象化された図の陳腐化の半減期は四半期単位です。
5. フォーマットの固定化問題。Visioファイル、PowerPointスライド、PNGエクスポート、またはPDF添付ファイルとして保存された図は、プログラムによる生成、検証、または比較ができません。図はピクセル画像であり、コードはテキストであるため、「この図はコードと一致しているか?」と問う方法はありません。図の作成時に選択したフォーマットによって、図が描写するシステムに対して検証できるかどうかが決まります。
レガシーシステム文書化の大惨事
活発な開発チームを抱える現代のクラウドネイティブシステムでは、図の陳腐化は管理上の問題であり、アーキテクチャ・アズ・コードの実践、ライブドキュメンテーションツール、そしてエンジニアリング規律によって解決できます。システムは頻繁に変更されるため、適切なプロセスであれば、図もそれに合わせて更新できます。
レガシーシステムの場合、問題は程度の差だけでなく、種類も異なる。
1992年にメインフレームシステムの設計レビュー中に作成されたアーキテクチャ図は、作成以来30年分のコード変更が蓄積されている可能性があります。複雑なCOBOLポートフォリオの保守を毎年行うと、数百ものコミット、新しいプログラムの追加、古いプログラムの廃止、コピーブックの更新、JCLジョブストリームの再編成が発生します。1992年の図は当時は正確でしたが、それ以降、年を追うごとに正確性が低下しています。2026年までには、図とシステムとのギャップは元のシステム自体よりも大きくなり、図に示されていない新しいプログラムの数の方が、元の設計どおりに動作している元のシステムのプログラムの数よりも多くなっている可能性があります。
この図が単なる不便さではなく、壊滅的な事態を招くのは、その図の使い方にある。近代化チームがシステム評価のために到着した際、彼らは図が間違っていることに気づかない。どれほど間違っているのかも分からない。図はプロフェッショナルな印象を与える。構成要素を示すボックス、関係を示す矢印、注釈などがあり、誰かがこのシステムを十分に理解して描いたように見える。チームはこの図を起点として分析を進めるが、誤った起点に基づく分析はすべて誤った結論を導き出すことになる。
Docuwriterの監査フレームワークは、この点を明確に述べています。適切なドキュメント監査とは、「漠然とした不安を検証可能な事実へと変える」ものです。レガシーシステムの場合、ドキュメント監査の結果はほぼ必ず同じものになります。図面が存在しないか、あるいは非常に古く、何年も前に存在しなくなったシステムを表しているかのどちらかです。最終的に明らかになった検証可能な事実は、誰もが参考にしていたシステムとは大きく異なるシステム像を示しています。
具体的な失敗事例:近代化チームが1992年の図に基づいて移行範囲を推定したところ、180個のコンポーネントが示されていた。しかし、実際のコードベースの構造分析の結果、340個のプログラムが存在することが判明した。そのうち80個はデッドコードであり、さらに40個は1992年以降に追加されたもので、図式化されていなかった。つまり、新しいコードの最初の行が書かれる前に、移行範囲の推定値が2倍も間違っていたことになる。
図のカテゴリ(陳腐度別)
すべての図が同じ速度で陳腐化するわけではありません。陳腐化の速度は、図が何を表しているか、表されている要素がどのくらいの頻度で変化するか、そして図がそれらの要素をどの程度正確に表現しているかによって異なります。
| 図の種類 | 頻繁に変わるもの | 古さ率 | 緩和の優先順位 |
|---|---|---|---|
| サービス/コンポーネント在庫 | 新サービスが追加され、旧サービスは廃止されました。 | ハイ | 重要 — 最も高い変更頻度 |
| 依存関係/統合マップ | APIが追加され、統合が変更され、データフローが変更されました。 | ハイ | 重要 — 展開のたびにこれが変わる可能性がある |
| データモデル/ER図 | スキーマの変更、新しいテーブルの作成、列の変更 | 中高 | 高 — 活発な開発ではスキーマ変更が頻繁に行われる |
| シーケンス図 | ビジネスロジックの変更、API契約の更新 | 技法 | 高 — ワークフローの変更はこれらを無効にする |
| インフラストラクチャ/デプロイメント | インフラストラクチャ・アズ・コードが頻繁な変更を促進する | ハイ | Medium — IaCツールはこれらを自動生成できます |
| ドメイン/境界コンテキスト | 組織および所有権の変更 | 低中 | 低 — ドメイン境界は四半期ごと、またはそれ以下の頻度で変更される。 |
| 決定記録(ADR) | 変更されることは稀である(決定は歴史的事実である) | 非常に低い | 低 — 正しく記録されれば、精度が維持される |
| プログラム呼び出しグラフ(COBOL) | コードの変更はすべて、潜在的にこれを変更する可能性がある。 | すごく高い | レガシーにとって重要 - 目に見えない変化 |
| コピーブック/スキーマ(COBOL) | FDの変更は、複数のプログラムに影響を与えます。 | ハイ | レガシーにとって重要 ― 変更は静かに連鎖的に広がる |
下2行は、標準的なドキュメントでは対応されていない、レガシーシステム固有のエントリです。COBOLプログラムの呼び出しグラフは、呼び出しツリー内のいずれかのプログラムにコード変更が加えられるたびに無効になる可能性があります。200個のプログラムで共有されているコピーブックは、コピーブックが変更されるたびにすべてのプログラムで無効になります。これらの図は、企業ポートフォリオの中で最も陳腐化率が高く、陳腐化した場合の影響も最も深刻です。なぜなら、これらの図が記述するプログラムは、最も重要なビジネスプロセスを実行しているプログラムだからです。
出所特定ソリューション:図面の出典元をたどる
ドキュメント負債の根本原因は、ドキュメント更新プロセスの欠如ではありません。それは、図の要素からそれが示すコード成果物への追跡可能なリンクであるプロベナンスの欠如です。プロベナンスがなければ、陳腐化を検出するメカニズムがありません。プロベナンスがあれば、陳腐化の検出は自動的に行われます。図が生成されてからコード成果物が変更されていれば、その図は陳腐化していると判断されます。
文書の出所情報は、2つのレベルで存在します。
静的な来歴 これは、ある時点のコードから生成されたドキュメントであり、生成タイムスタンプと、ドキュメントが反映するコードの状態(コミットハッシュ、バージョン、分析日)への参照が含まれています。静的な来歴情報は、コードの陳腐化を防ぐものではありませんが、陳腐化を検出可能にします。タイムスタンプは、ドキュメントがコミットから生成されたことを示しています。 abc123 特定の日付に、現在のコミットは def456 後日。2つのコミット間のギャップは、ドキュメントと現在のコード間のギャップです。
動的な来歴情報とは、コードから継続的に生成されるドキュメントであり、関連するコード変更のたびに再生成されます。ドキュメントは常に最新のコード状態に基づいて作成されるため、常に最新の状態を保ちます。これは、誰かが思い出したときに更新するような図ではなく、コードが変更されるたびにコードから再生成される、生きたドキュメントモデルです。
既存のCOBOLポートフォリオにおける実質的な違いは以下のとおりです。静的なプロベナンス方式では、現在のCOBOLソース分析から依存関係図を生成し、タイムスタンプを付与します。分析は毎週再実行され、新しい図は以前の図と比較されます。変更点は、連続する分析出力間の差異として表示されます。動的なプロベナンス方式では、分析がメインフレームの変更管理パイプラインに統合され、プログラムが本番環境に昇格されるたびに更新された図が生成されます。
図解をコードとして活用する:その利点と欠点
時代遅れの静的な図表に対する現代的な解決策は、図表をコードとして表現することです。これは、アーキテクチャ文書をバージョン管理、差分比較、レビュー、プログラムによる生成が可能なテキスト形式で表現するものです。Mermaid、PlantUML、そしてコード形式のC4モデルが主なツールです。
For modern cloud-native systems, diagrams-as-code solves several of the staleness mechanisms: #mermaid-rlk-r1 { font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; font-size: 16px; fill: rgb(25, 25, 25); } #mermaid-rlk-r1 .edge-animation-slow { stroke-dashoffset: 900; animation: 50s linear 0s infinite normal none running dash; stroke-linecap: round; stroke-dasharray: 9, 5 !important; } #mermaid-rlk-r1 .edge-animation-fast { stroke-dashoffset: 900; animation: 20s linear 0s infinite normal none running dash; stroke-linecap: round; stroke-dasharray: 9, 5 !important; } #mermaid-rlk-r1 .error-icon { fill: rgb(204, 120, 92); } #mermaid-rlk-r1 .error-text { fill: rgb(51, 135, 163); stroke: rgb(51, 135, 163); } #mermaid-rlk-r1 .edge-thickness-normal { stroke-width: 1px; } #mermaid-rlk-r1 .edge-thickness-thick { stroke-width: 3.5px; } #mermaid-rlk-r1 .edge-pattern-solid { stroke-dasharray: 0; } #mermaid-rlk-r1 .edge-thickness-invisible { stroke-width: 0; fill: none; } #mermaid-rlk-r1 .edge-pattern-dashed { stroke-dasharray: 3; } #mermaid-rlk-r1 .edge-pattern-dotted { stroke-dasharray: 2; } #mermaid-rlk-r1 .marker { fill: rgb(145, 145, 141); stroke: rgb(145, 145, 141); } #mermaid-rlk-r1 .marker.cross { stroke: rgb(145, 145, 141); } #mermaid-rlk-r1 svg { font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; font-size: 16px; } #mermaid-rlk-r1 p { margin: 0px; } #mermaid-rlk-r1 .label { font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; color: rgb(25, 25, 25); } #mermaid-rlk-r1 .cluster-label text { fill: rgb(51, 135, 163); } #mermaid-rlk-r1 .cluster-label span { color: rgb(51, 135, 163); } #mermaid-rlk-r1 .cluster-label span p { background-color: transparent; } #mermaid-rlk-r1 .label text, #mermaid-rlk-r1 span { fill: rgb(25, 25, 25); color: rgb(25, 25, 25); } #mermaid-rlk-r1 .node rect, #mermaid-rlk-r1 .node circle, #mermaid-rlk-r1 .node ellipse, #mermaid-rlk-r1 .node polygon, #mermaid-rlk-r1 .node path { fill: rgb(240, 240, 235); stroke: rgb(217, 216, 213); stroke-width: 1px; } #mermaid-rlk-r1 .rough-node .label text, #mermaid-rlk-r1 .node .label text, #mermaid-rlk-r1 .image-shape .label, #mermaid-rlk-r1 .icon-shape .label { text-anchor: middle; } #mermaid-rlk-r1 .node .katex path { fill: rgb(0, 0, 0); stroke: rgb(0, 0, 0); stroke-width: 1px; } #mermaid-rlk-r1 .rough-node .label, #mermaid-rlk-r1 .node .label, #mermaid-rlk-r1 .image-shape .label, #mermaid-rlk-r1 .icon-shape .label { text-align: center; } #mermaid-rlk-r1 .node.clickable { cursor: pointer; } #mermaid-rlk-r1 .root .anchor path { stroke-width: 0; stroke: rgb(145, 145, 141); fill: rgb(145, 145, 141) !important; } #mermaid-rlk-r1 .arrowheadPath { fill: rgb(11, 11, 11); } #mermaid-rlk-r1 .edgePaths .path { stroke: rgb(145, 145, 141); stroke-width: 1px; } #mermaid-rlk-r1 .flowchart-link { stroke: rgb(145, 145, 141); fill: none; } #mermaid-rlk-r1 .edgeLabel { background-color: rgb(245, 230, 216); text-align: center; } #mermaid-rlk-r1 .edgeLabel p { background-color: rgb(245, 230, 216); } #mermaid-rlk-r1 .edgeLabel rect { opacity: 0.5; background-color: rgb(245, 230, 216); fill: rgb(245, 230, 216); } #mermaid-rlk-r1 .labelBkg { background-color: rgba(245, 230, 216, 0.5); } #mermaid-rlk-r1 .cluster rect { fill: rgb(204, 120, 92); stroke: rgb(138, 115, 107); stroke-width: 1px; } #mermaid-rlk-r1 .cluster text { fill: rgb(51, 135, 163); } #mermaid-rlk-r1 .cluster span { color: rgb(51, 135, 163); } #mermaid-rlk-r1 .node .collapsed-indicator { fill: rgb(138, 115, 107); stroke: none; opacity: 0.6; } #mermaid-rlk-r1 .node .collapsed-separator { stroke: rgb(138, 115, 107); stroke-width: 0.75px; } #mermaid-rlk-r1 div.mermaidTooltip { position: absolute; text-align: center; max-width: 200px; padding: 2px; font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; font-size: 12px; background: rgb(204, 120, 92); border: 1px solid rgb(138, 115, 107); border-radius: 2px; pointer-events: none; z-index: 100; } #mermaid-rlk-r1 .flowchartTitleText { text-anchor: middle; font-size: 18px; fill: rgb(25, 25, 25); } #mermaid-rlk-r1 rect.text { fill: none; stroke-width: 0; } #mermaid-rlk-r1 .icon-shape, #mermaid-rlk-r1 .image-shape { background-color: rgb(245, 230, 216); text-align: center; } #mermaid-rlk-r1 .icon-shape p, #mermaid-rlk-r1 .image-shape p { background-color: rgb(245, 230, 216); padding: 2px; } #mermaid-rlk-r1 .icon-shape .label rect, #mermaid-rlk-r1 .image-shape .label rect { opacity: 0.5; background-color: rgb(245, 230, 216); fill: rgb(245, 230, 216); } #mermaid-rlk-r1 .label-icon { display: inline-block; height: 1em; overflow: visible; vertical-align: -0.125em; } #mermaid-rlk-r1 .node .label-icon path { fill: currentcolor; stroke: revert; stroke-width: revert; } #mermaid-rlk-r1 .node .neo-node { stroke: rgb(217, 216, 213); } #mermaid-rlk-r1 [data-look=”neo”].node rect, #mermaid-rlk-r1 [data-look=”neo”].cluster rect, #mermaid-rlk-r1 [data-look=”neo”].node polygon { stroke: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].swimlane.cluster rect { filter: none; } #mermaid-rlk-r1 [data-look=”neo”].node path { stroke: url(“#mermaid-rlk-r1-gradient”); stroke-width: 1px; } #mermaid-rlk-r1 [data-look=”neo”].node .outer-path { filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].node .neo-line path { stroke: rgb(217, 216, 213); filter: none; } #mermaid-rlk-r1 [data-look=”neo”].node circle { stroke: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].node circle .state-start { fill: rgb(0, 0, 0); } #mermaid-rlk-r1 [data-look=”neo”].icon-shape .icon { fill: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].icon-shape .icon-neo path { stroke: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 :root { –mermaid-font-family: system-ui,”Segoe UI”,Roboto,Helvetica,Arial,”PingFang SC”,”PingFang TC”,”Hiragino Sans”,”Apple SD Gothic Neo”,”Kohinoor Devanagari”,”Kohinoor Bangla”,”Kohinoor Telugu”,”Tamil Sangam MN”,”Kohinoor Gujarati”,”Malayalam Sangam MN”,”Nirmala UI”,”Noto Sans Devanagari UI”,”Noto Sans Devanagari”,”Noto Sans Bengali UI”,”Noto Sans Bengali”,”Noto Sans Telugu UI”,”Noto Sans Telugu”,”Noto Sans Tamil UI”,”Noto Sans Tamil”,”Noto Sans Gujarati UI”,”Noto Sans Gujarati”,”Noto Sans Kannada UI”,”Noto Sans Kannada”,”Noto Sans Malayalam UI”,”Noto Sans Malayalam”,Thonburi,”Leelawadee UI”,”Noto Sans Thai UI”,”Noto Sans Thai”,Kefa,Ebrima,”Noto Sans Ethiopic”,”Abyssinica SIL”,sans-serif,ui-sans-serif,system-ui,-apple-system,”Segoe UI”,Roboto,”PingFang SC”,”PingFang TC”,”Hiragino Sans”,”Apple SD Gothic Neo”,sans-serif; }API GatewayAuth ServiceOrder ServiceOrder DBNotification ServiceUser DB
このマーメイド図は、それが示すコードとともにリポジトリに格納されています。開発者が新しいサービスを追加する際は、同じプルリクエストでこのファイルを更新します。コードレビューには、この図の変更も含まれます。ドキュメントとコードは常に一緒に管理されます。
図解をコードとして利用しても解決できないこと:
これはレガシーシステムのドキュメント作成に関する問題を解決しません。開発者がGitプルリクエストではなくコンパイル済みJCLを送信してメインフレームライブラリに追加したCOBOLプログラムは、Mermaidファイルの更新をトリガーしません。メインフレームの変更管理プロセスとGitベースのドキュメント作成プロセスは別々のシステムであり、自動同期は行われません。
これは、過剰な精度という問題を解決するものではありません。新しいサービスごとに手動で更新する必要のあるマーメイド図は、本来このプロセスが置き換えるはずだった人間の規律を依然として必要とします。図の更新が手動の手順である場合、その手順は省略されます。
これは、既存の図を遡って修正するものではありません。機械可読なドキュメントが存在しないCOBOLポートフォリオの場合、ダイアグラム・アズ・コードは将来のドキュメント作成のためのフレームワークを提供しますが、現在のドキュメントを生成するものではありません。
レガシーシステムのための構造解析アプローチ
開発ワークフローがGitを経由しない、既存のドキュメントが古すぎてテキストベースのアプローチの出発点として適さない、あるいはコードベースが正式に文書化されていないといった理由で、図式化が非現実的なレガシーシステムにおいては、構造的コード分析こそが、ゼロから最新かつ正確なドキュメントを作成できる唯一の手段となる。
構造解析は、実際のコード、COBOLプログラム、JCLジョブストリーム、コピーブック、埋め込みSQLなどを解析し、コードに含まれる情報から直接、依存関係、プログラムインベントリ、データ構造を導き出します。出力は、コードを理解した人間が描いた図ではなく、コード自体からアルゴリズム的に導き出された図です。その精度は、解析の精度によって決まり、図を描いた開発者の記憶力によって左右されることはありません。
ワークフロー:
bash
# Structural analysis pipeline for COBOL documentation
# Step 1: Parse all COBOL source in the portfolio
smart-ts-xl analyze --source /cobol/src --output /docs/analysis/
# Step 2: Generate dependency graph (always current)
smart-ts-xl diagram --type dependency-graph \
--format mermaid \
--output /docs/dependency-graph.md
# Step 3: Generate program inventory (always current)
smart-ts-xl report --type program-inventory \
--format markdown \
--output /docs/program-inventory.md
# Step 4: Diff against previous analysis (detect what changed)
smart-ts-xl diff \
--baseline /docs/analysis/2026-09-01/ \
--current /docs/analysis/2026-10-01/ \
--output /docs/changes/delta-report.md
デルタレポートとは、連続する2つの分析結果の差分であり、図の静的な来歴情報が自動的に生成する変更ログです。追加されたプログラム、削除されたプログラム、変更された依存関係、修正されたコピーブックなど、すべてが人間の手による文書化作業なしにデルタレポートに表示されます。
前回の分析で作成された図は、分析日時点での最新のドキュメントです。分析を毎週、または製品プロモーションのたびに定期的に実行することで、継続的な手動によるドキュメント作成作業を必要とせずに、定義された頻度で最新のドキュメントを作成できます。
文書化防止フレームワーク
文書の陳腐化を防ぐには、5つの陳腐化メカニズムに具体的かつ実行可能な対策で対処する必要があります。
累積デルタ問題への対策:
- 分析の頻度を確立する:高速変動システムの場合は週1回、安定システムの場合は月1回
- 分析実行ごとにコードからドキュメントを生成する(手動で生成するのを避ける)
- 各実行ごとに、前回の分析以降に何が変わったかを示す差分レポートを作成する
出所不明問題への対策:
- すべての図には、その生成元(コード分析の日付とバージョン)が含まれています。
- 図を公開する際は、作成方法と作成日時を記録しておくこと。
- 生成された図は、それらを生成した分析結果と並べて保存してください。
所有権の乖離問題への対策:
- ドキュメント作成はパイプラインのステップであり、個人の責任ではない。
- パイプラインがドキュメントを所有しており、個人の退職によってそれが壊れることはない。
- 生成されたドキュメントには所有者がいないため、そこから逸脱することはない。
過剰精度問題への対策:
- 作成する前に、各図タイプに適した抽象化レベルを定義してください。
- コンポーネントのインベントリ図は、機能レベルではなく、サービス/プログラムレベルで作成する。
- ドメイン境界レベルでの関係図であり、個々の呼び出しレベルではない。
- 詳細な図(呼び出しグラフ、データスキーマ)が生成され、手描きではありません。
フォーマットの固定化問題への対策:
- テキストベースの形式(Mermaid、GraphViz DOT、SVG)で生成された図
- Visio、PowerPoint、またはPDFのみのアーキテクチャドキュメントは存在しない。
- 図のソースコードは、それが文書化するコードとともにバージョン管理システムに保存されます。
認定条件 SMART TS XL 過去の文書化に関する負債に対処する
従来の COBOL およびメインフレームのポートフォリオについては、 SMART TS XL これは、証拠に基づいた文書作成を可能にする構造解析エンジンであり、「2009 SharePoint の図を更新する」という作業に代わる実用的な方法として「コードから再生成する」ことを可能にするものです。
静的コード解析機能は、すべてのCOBOLプログラム、コピーブック、JCLジョブストリーム、および埋め込みSQLステートメントを解析し、プログラムインベントリ、複雑度メトリクス、およびデッドコード識別情報を生成します。これらは、正確なレガシー文書の基盤となるものです。このインベントリは、常に不完全で、常に古く、そして誰も知らないような誤りがある、手動で管理されていたプログラムリストに代わる、エビデンスに基づいた情報源となります。
アプリケーションの依存関係マッピングは、アーキテクチャドキュメントの中核となる成果物である、すべての呼び出し関係、すべてのコピー関係、プログラム間のすべてのデータフローを含む依存関係グラフを生成します。このグラフは、分析実行ごとにコードから再生成され、実行間の人的作業なしに、前回の分析時点での最新の依存関係図が生成されます。
影響分析機能は、差分ドキュメントを生成します。コードベースに変更が加えられると、影響分析によって以前の状態と比較して変更されたすべての箇所が特定されます。これは、蓄積される差分問題に対処する自動化された差分レポートであり、図と現実のギャップを広げる可能性のあるすべての変更が自動的に捕捉され、文書化されます。
エンタープライズ検索機能により、ドキュメントをクエリ可能にします。特定のサブルーチンを呼び出すすべてのプログラム(コンポーネントの呼び出しグラフ断片)、特定のコピーブックを含むすべてのプログラム(共有コンポーネントの依存関係スコープ)、特定の日付以降に変更されたすべてのプログラム(一定期間の変更ログ)を検索できます。この検索機能はドキュメントのインターフェースであり、何年も前の静的な図ではなく、最新の分析に基づいて現在のシステム状態に関する質問に答えるツールです。
組織が実施する場合 レガシーの近代化 プログラム、 SMART TS XLドキュメント生成は前提条件となるステップです。これは、近代化プログラムが範囲を定義し、移行フェーズの順序を決定し、結果を検証するために必要な、依存関係図、プログラムインベントリ、およびデータスキーマのドキュメントです。このドキュメントはSharePointアーカイブから生成することはできません。コードから生成する必要があります。
唯一正確な図は、コードから導き出された図である。
SharePointページ上の2009年のアーキテクチャ図は、誰かが明示的に削除するまで存在し続けます。新しい開発者がシステムの仕組みについて質問した際に、引き続きこの図が送られてきます。もはや正確に説明していないシステムに関する意思決定の根拠として、この図が引き続き利用されます。コミット、デプロイ、プログラムの追加と廃止のたびに、この図と実際のシステムとの間の乖離はますます広がっていくでしょう。
代替案は「図をより頻繁に更新する」ことではありません。絶えず変化するコードに対応するために人間の規律を必要とするプロセスには、既知の失敗パターンがあります。それは、規律が機能しなくなることです。代替案は、コードから派生し、コードを真の情報源とし、コードが変更されると自動的に再生成され、分析のタイムスタンプが付いていて、すべての読者にその最新性を正確に伝えるドキュメントです。
最新のクラウドシステムでは、ダイアグラム・アズ・コードやライブドキュメンテーションツールがこれを実現します。従来のCOBOLシステムでは、構造化コード分析がこれを実現します。仕組みは異なりますが、原理は同じです。ダイアグラムはコードから生成された時点では正確ですが、生成されたコードから分離された瞬間から、そのダイアグラムは負債を蓄積していきます。
常に最新の状態を保つ唯一の図は、コードによって作成された図である。


