--- type: Reference title: "Living Documentation導入ガイド" description: "『Living Documentation』に基づき、ドキュメントの再定義と 4 原則、知識の活用・拡張・キュレーション、ドキュメントの自動化（Living Glossary・Living Diagram）、ランタイムドキュメンテーションを整理し、本プロジェクトの成果物（ADR・コミット規約・OKF・PlantUML・テスト）への適用方法をまとめた導入ガイド。" tags: [reference] status: draft generated: { by: claude-code/claude-opus-5-5, at: 2026-09-29T00:00:00Z } --- # Living Documentation導入ガイド Living Documentation とは、**ソフトウェア開発に関わる知識に注意を払うこと**です。重要な知識の多くはすでにコード・テスト・設定・ツールの中にあります。それを別文書に書き写すのではなく、ある場所から必要な場所へ取り出し、足りない意図と根拠だけを補い、システムと同じ速さで更新され続ける形にします。 本ガイドは、Cyrille Martraire『Living Documentation』の第 1 章・第 3〜7 章の要点を整理し、本プロジェクトでの適用方法を示します。第 2 章（BDD）は [BDD導入ガイド](BDD導入ガイド.md) を参照してください。 ## ドキュメントを再定義する ### ドキュメントとは知識を伝えるプロセスである ドキュメントは「価値ある知識を、いま他の人へ、そして将来の人へ伝えるプロセス」です。人から人へ伝える**空間の軸（伝達）**と、いまから未来へ残す**時間の軸（保存）**の 2 つで捉えます。 開発者が同じコードに関わる期間の半減期は約 3.1 年、コードの半減期は約 13 年といわれます。書いた人がいなくなった後もコードは残り続けます。この差を埋めるのがドキュメントの役割です。 ドキュメントの形は文書に限りません。対話、コードそのもの、ツール上の活動、そして「何もしない」ことも選択肢に含まれます。 ### デフォルトは書かない ドキュメント化の対象は**価値のある知識だけ**です。長く役立つ知識、多くの人に関係する知識、重要でクリティカルな知識に絞ります。明確な理由がなければ書きません（The Default Is Don't）。 また、Naur の「理論構築としてのプログラミング」が示すとおり、プログラマの頭の中にある心的モデルは完全には共有できません。この限界を受け入れたうえで、伝えるべき知識を選びます。 ### Living Documentation の 4 原則 | 原則 | 要点 | | :--- | :--- | | **Reliable（信頼できる）** | 常にソフトウェアと同期している。既存の知識を活用し、正確性を保証する仕組みを持つ | | **Low effort（低労力）** | 変更時の追加作業を最小にする。シンプルさ、標準の利用、変わらない内容（Evergreen）、リファクタリング耐性、内部ドキュメントを重視する | | **Collaborative（協調的）** | 文書より会話を優先する。知識をアクセス可能にし、チームで所有する | | **Insightful（洞察を与える）** | 意図的な意思決定を促し、学びを埋め込み、実装の実態を映す鏡になる | ### 最重要の 4 点 1. 文書より**会話と協働**を重視する。知識の大半はすでにあり、取り出されるのを待っている 2. 知識の大半は既存の成果物にある。**文脈・意図・根拠**で補うだけでよい 3. **変化の頻度**に注意を払う 4. ドキュメントを考えることは、システムの**品質（または品質の欠如）に注意を向ける**手段である ### 変化の速さでアプローチを選ぶ 知識がどれくらいの頻度で変わるかによって、ドキュメントへのアプローチを選びます。 ```plantuml @startuml title 変化の速さで選ぶドキュメントへのアプローチ rectangle "Avoiding\n書かない" as A rectangle "Stable\n変わらない知識を書く" as S rectangle "Refactorable\nコード・テスト・プレーンテキストで持つ" as R rectangle "Automating\nビルド時・実行時に生成する" as Au rectangle "Beyond\nドキュメントを通じて設計を改善する" as B A -right-> S S -right-> R R -down-> Au Au -left-> B note bottom of A 努力に値しない知識は書かない。 対話や根本原因の修正で解決する end note note bottom of R IDE のリファクタリングで コードと同期を保てる end note @enduml ``` | アプローチ | 対象となる知識 | 手段 | | :--- | :--- | :--- | | Avoiding | 努力に値しない知識 | 対話、根本原因の修正 | | Stable | ほとんど変わらない知識 | 単純な文書（ビジョン、原則） | | Refactorable | コードと一緒に変わる知識 | 命名、型、テスト、プレーンテキストの図 | | Automating | 頻繁に変わり、成果物から抽出できる知識 | 生成された用語集・図・レポート | | Beyond | ドキュメント化が難しいこと自体が問題を示す知識 | 設計の改善 | ### パターンの全体像 『Living Documentation』は約 100 のパターンを次のカテゴリに整理しています。本ガイドでは太字のカテゴリを扱います。 | カテゴリ | 代表的なパターン | | :--- | :--- | | Rethinking Documentation | 知識はすでにそこにある、内部ドキュメント優先、正確性の仕組み | | **Knowledge Exploitation** | 単一情報源からの公開、整合性検証、散在する事実の統合、既成のドキュメント | | **Knowledge Augmentation** | アノテーション、規約、サイドカーファイル、根拠の記録、コミットメッセージ | | **Knowledge Curation** | 動的キュレーション、コアのハイライト、模範例、ガイドツアー | | **Automating Documentation** | Living Document、Living Glossary、Living Diagram、一図一物語 | | **Runtime Documentation** | Visible Tests、Visible Workings、Introspectable Workings | | Refactorable Documentation | コード自体をドキュメントに、プレーンテキストの図 | | Stable Documentation | Evergreen content、永続的な命名、リンクレジストリ | | How to Avoid Traditional Documentation | 雑談、使い捨て文書、オンデマンド文書、新人の驚きの記録 | | Beyond Documentation: Living Design | ドキュメントに耳を傾ける、意図的な意思決定、自らを不要にする文書 | | Living Architecture | 問題を文書化する、Decision log、Test-driven architecture | | Introducing Living Documentation | 小さな実験から始める、新規作業から適用する | | Documenting Legacy Applications | Bubble context、Superimposed structure、External annotations | ### DDD との関係 Living Documentation に投資すると DDD にも近づけます。「Living Documentation」という用語自体が BDD に由来し、BDD は TDD と DDD のユビキタス言語の組み合わせです。 | Living Documentation | DDD パターン | | :--- | :--- | | Code as documentation | モデル駆動設計、意図を表すインターフェース、宣言的設計 | | Living glossary | ユビキタス言語（コードが用語集の唯一の参照元になる） | | Listen to the documentation | Hands-on modelers（高速なフィードバック） | | Change-friendly documentation | 深い洞察へのリファクタリング | | Curation | Highlighted / Segregated / Abstract core | | Ready-made knowledge | 確立された形式知の活用 | | Evergreen document | Domain vision statement | DDD の実践は [ドメインモデル設計ガイド](ドメインモデル設計ガイド.md) を参照してください。 ## 知識を活用する（Knowledge Exploitation） 知識はすでにソースコード、設定ファイル、テスト、実行時の挙動、ツールのデータ、関係者の頭の中にあります。従来のドキュメントはそれを別文書に複製するため、元が変わるたびに古くなります。知識のある場所から必要な場所へ取り出す仕組みを、**軽量・確実・低コスト**で作ります。 ### 権威ある情報源を特定する 同じ知識が複数の場所にあるとき、決定の変更が最も正確に反映される場所を**権威ある情報源**とします。そこから取り出す仕組みを用意し、仕組みそのものは単純に保ちます。 ### 単一情報源から公開する（Single-Source Publishing） 知識は 1 か所にだけ置き、必要なときにそこから文書を生成して公開します。 - DDL やスキーマから ER 図やテーブル定義書を生成する - 1 つの Markdown 原稿から HTML・PDF など複数の形式を生成する - 公開物にはバージョンと最新版へのリンクを付ける - 公開物は編集しにくくし、元を直すよう促す ### 整合性を検証する仕組み（Reconciliation Mechanism） 知識がどうしても複数の場所に重複する場合は、不一致を**自動テストで即座に検出**します。 - BDD のシナリオとコードを、ステップ定義で結びつける。食い違えばテストが失敗する - 前提が真であることを確かめるカナリアテストを置く - 外部に公開した契約（列挙型の値、API のスキーマ）は、変更を検知するテストで守る ### 散在する事実を統合する（Consolidating Dispersed Facts） 知識が多数の小さな部品に分散しているときは、全体像を自動で集めて再構成します。あるインターフェースの全実装の一覧、依存関係の集約、クラス階層の図などが該当します。 統合した結果を新しい真実の源にしてはいけません。キャッシュとして扱い、いつでも捨てて作り直せるようにします。 ### 既成のドキュメントと共通語彙を使う（Ready-Made Documentation） TDD、DDD、デザインパターン、継続的デリバリーなど、自分たちの知識の多くは書籍やブログですでに文書化されています。車を作るのにエンジンの仕組みを書き直す必要はありません。標準的な文献へリンクし、標準的な名前と用語を採用します。 Adapter、State、Visitor のようなパターン名を使うと、短い言葉で設計意図が伝わります。語彙をそろえることは DDD のユビキタス言語の考え方にもつながります。 ## 知識を補う（Knowledge Augmentation） ソースコードは「どう作るか」は語りますが、「なぜそうしたか」は語りません。足りない**意図・判断・根拠**を、**コードに近い場所に、ツールが解析できる形で**補います。補う手段は、内部ドキュメント（アノテーション・規約）、外部ドキュメント（サイドカーファイル・メタデータ DB）、DSL の 3 系統です。 ### アノテーションで補う アノテーションは名前と属性を持つ型なので、ツールが扱いやすい補足手段です。導入手順は [アノテーション導入ガイド](アノテーション導入ガイド.md) を参照してください。 | 用途 | 例 | | :--- | :--- | | ステレオタイプ | `@ValueObject`、`@Entity`、`@DomainService` で DDD の役割を明示する | | 性質 | `@Immutable`、`@SideEffectFree` で振る舞いの性質を明示する | | レイヤー | `package-info.java` に `@Layer` を付け、依存違反をツールで検出する | | 根拠 | `@Decision(rationale = "...")` のように判断した箇所に理由を付ける | - 独自アノテーションのパッケージ名は、参照する文献に対応させる（例: `com.acme.annotation.ddd`） - 大半が該当する性質は付けず、**例外だけ**に付ける（全クラスが不変なら `@Mutable` だけを付ける） - 感情的なアノテーション（`@WTF` など）で型階層を汚さない ### 本質的な知識だけを付ける | 種類 | 説明 | 扱い | | :--- | :--- | :--- | | 本質的（intrinsic） | 要素自体の性質。要素を消せば知識も消える | 付けてよい | | 外在的（extrinsic） | 他との関係や状況に依存する（所有者、配置場所など） | 付けない | 判断基準は「要素を変更したとき、最小の作業で済むか」です。外在的な知識まで付けると、頻繁に変更が入り保守コストが増えます。 ### 規約で補う 命名や構造の規約そのものがドキュメントになります（`*.domain.*` と `*.infra.*` のパッケージ分割など）。規約は README に書くか、他で公開された規約を採用するだけでも構いません。 規約は分類には強いものの、根拠や代替案は書きにくいという限界があります。また、一貫して守られてこそ機能するため、ArchUnit などの静的解析で検証します。 ### サイドカーファイルとメタデータ DB 元ファイルに触れられない場合は、同名で拡張子が違うサイドカーファイルや、メタデータ DB に知識を置きます。ただし名前の変更や移動で関係が壊れやすいため、最後の手段とし、可能ならコード内のアノテーションを優先します。 ### 根拠を記録する 設計判断は問題に対して選んだ答えです。後から「何を考えていたのか」とならないよう、次を残します。 - その時点の文脈（優先度・制約） - 問題・要件 - 選んだ解決策と理由 - 却下した代替案と理由 根拠が残っていないと、変更が怖くなるか、不用意に変更して害を及ぼします。**根拠の記録は変更を後押しします**。 - 推測で書かず、実際に作ったものの必要に応じて書く（just-in-time） - 同種の判断が繰り返されるなら、原則を一度だけ文書化し、各適用箇所から参照する - チームの拠り所となる書籍・ブログを参考文献として残す - モジュールごとの設計スタイル（関数型、DDD など）を宣言する ### コミットメッセージで補う コミットメッセージは変更ごとのドキュメントです。書くことで「これは 1 つの変更か、分割すべきか」を考えさせます（Thinking）。そのほか、意図の説明（Explaining）、変更履歴の元データ（Reporting）、規約に沿った記述（Guidelines）の役割を持ちます。 ```text ():