---
type: Reference
title: "ダイナミックキュレーション導入ガイド"
description: "『Living Documentation』第 5 章「Living Curation」に基づき、既存の知識から目的に必要な少数を安定した基準で自動的に選び出すダイナミックキュレーションの導入手順（選択基準、手法の使い分け、実装例、運用ルール、チェックリスト）をまとめた導入ガイド。"
tags: [reference]
status: draft
generated: { by: claude-code/claude-opus-5-5, at: 2026-09-29T00:00:00Z }
---

# ダイナミックキュレーション導入ガイド

## 1. 概要

ダイナミックキュレーションとは、コードやテストなど既存の膨大な知識から、目的に必要な少数だけを、安定した基準で自動的に選び出して提示する手法です。手作業のリストを保守せず、システムの変化に合わせて内容が自然に更新されることが狙いです。

基本原則は次の 4 点です。

- **選ぶことが価値になる**: 知識の大半は捨て、読み手の目的に必要な部分だけを残す。
- **安定した基準で選ぶ**: 名前や URL の直接指定ではなく、フォルダ構成、命名規約、タグ、アノテーションなどで選ぶ。
- **1 つのコーパスから複数の見せ方を作る**: 読み手（業務担当/開発者）や目的（概要/手順）ごとにビューを生成する。
- **手作業の保守をなくす**: 抽出と公開はツールで自動化し、コードの変更に追従させる。

身近な例は、IDE での「名前が DAO で終わる型を全部表示」という検索や、条件で絞り込む SNS の検索です。これらも一種の自動キュレーションです。

## 2. 導入の前提: なぜ「動的」で「安定した基準」なのか

固定のリストで知識を選ぶと、コードの変更に追従できず、すぐに陳腐化します。名前や URL での直接参照は、コピペと同じく更新漏れの温床で、保守コストも高くなります。

そこで、選択基準は時間がたっても変わりにくいものにします。基準さえ安定していれば、対象のコードが増減しても、手作業なしで最新の一覧が得られます。

| 安定した基準 | 例 |
| --- | --- |
| フォルダ構成 | 「Return Policy」フォルダの中身すべて |
| 命名規約 | 名前に "Nominal" を含むテストすべて |
| タグ/アノテーション | "WorkInProgress" タグ付きのシナリオすべて |
| リンクレジストリ | ある短縮 URL の下に登録されたすべての URL |
| ツールの出力 | コンパイラのログに現れたすべてのファイル |

**避けること**: 特定のクラス名や URL を名指しで列挙する方法。リネームや移動で壊れ、更新にも手間がかかります。

**前提となる考え方**: 編集上の判断（何を伝えるか）は人間が行い、その判断を表すメタデータをコードに付けます。抽出と公開はツールに任せます。

## 3. 導入ステップ

小さく始めて、効果を確認しながら広げます。

1. **読み手と目的を決める**: 誰が、何のために読むのか（新メンバーのオンボーディング、業務担当者への説明、設計レビューなど）を 1 つに絞ります。
2. **伝えたいメッセージを 1 つ決める**: キュレーターは 1 つの核心メッセージを届けます。「ここが核心」「ここを真似して」「ここから読んで」のどれかを選びます。
3. **選択基準を決める**: 既存の命名規約やフォルダ構成で足りるか、専用のタグ（アノテーション/属性）が必要かを判断します。
4. **メタデータをコードに付ける**: 重要な少数のコードだけにタグを付けます。数は絞ります（詳しくは第 6 章）。
5. **抽出ツールを用意する**: まずは IDE の検索で十分です。次に、コードを走査して Markdown などに出力するスクリプトや Doclet を作ります。
6. **公開を自動化する**: ビルドや CI で生成し、Wiki や社内サイトに載せます。手作業の更新は残しません。
7. **足りない知識を補う**: 意図や背景など、コードにない情報はアノテーションの説明文や短い解説で補います。
8. **チームで見直す**: 何を模範例やコアとするかは、チームの合意で決めます。定期的に見直します。

**最初のゴール**: 1 つの目的、1 つの基準、5〜10 個以内のタグ付けで動く状態をつくります。

## 4. キュレーション手法の使い分け

目的に合わせて、次の 5 つから選びます。最初は 1 つだけ試すのがお勧めです。

| 手法 | 目的 | 付けるメタデータの例 | 目安 |
| --- | --- | --- | --- |
| コアのハイライト | ドメインの中心概念を示す | `@CoreConcept` | 主要な概念に限定 |
| 模範例（エグザンプラ） | 真似してほしい良いコードを示す | `@Exemplar(pros, cons)` | チーム合意の少数 |
| サイトシーイング・マップ | 見どころを順序なしで示す | `@KeyLandmark` `@MustSee` | 5〜7 個、多くても 10 個 |
| ガイドツアー | 処理の流れを順序付きで案内する | `@GuidedTour(name, description, rank)` | ツアー 1 本あたり数ステップ |
| シナリオダイジェスト | テストやシナリオを目的別に公開する | `@keyexample` `@nominalcase` `@wip` など | 読み手ごとにタグで絞る |

### 選び方の目安

- 新メンバーに全体像を掴ませたい: コアのハイライト → サイトシーイング・マップ
- 「どう書くべきか」を伝えたい: 模範例
- 処理の流れを追わせたい: ガイドツアー
- 業務担当者に振る舞いを説明したい、進捗を報告したい: シナリオダイジェスト

**模範例の注意点**: 目的はコピペの推奨ではなく、会話のきっかけです。完璧な例でなくてもよく、弱点があればその理由も書きます。ペア/モブプロやレビューで話題にします。

## 5. 実装例

Java と C#は、アノテーション/属性の考え方がほぼ同じです。まずタグを定義し、次にコードへ付け、最後にツールで抽出します。

### 5.1 Java: アノテーションの定義

```java
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface PointOfInterest {
    String value() default "";
}
```

### 5.2 Java: コードへの付与

```java
@PointOfInterest("Key calculation")
private double pricing(ExoticDerivative ...) { ... }
```

名前は自由に決められます。汎用名 `KeyCalculation` などを目的別に作る方法もあります。

### 5.3 C#: カスタム属性

```csharp
[AttributeUsage(AttributeTargets.Class)]
public sealed class CoreConceptAttribute : Attribute
{
    public CoreConceptAttribute(string description = "") => Description = description;
    public string Description { get; }
}

[CoreConcept("The main steps of enriching the Customer Purchase from the initial order to a ready-to-ship")]
public class Shipment { ... }
```

Visual Studio の他のプロジェクトとも共有する場合は、属性を専用のアセンブリに置くと、特定のプロジェクトに依存しません。

### 5.4 ガイドツアーの定義と抽出

```java
@GuidedTour(name = "Quick Developer Tour",
            description = "The MQ listener which triggers a full chain of processing",
            rank = 1)
public class FuelCardTxListener { ... }
```

ツアーの抽出は、次の流れで行います。

1. ソースを走査して `@GuidedTour` の要素をすべて集める
2. ツアー名で分類し、`rank` の順に並べる
3. 各ステップの Javadoc コメントや説明文を取り出す
4. Markdown として連結し、Wiki やサイトに公開する

Java では、QDox（Javadoc のようなライブラリ）で `src/main/java` 内の Java ファイルを解析し、クラス、メソッド、フィールドのアノテーションやコメントを取り出せます。C# ではメタモデルを使います。

### 5.5 まず試すなら: IDE 検索だけで始める

専用ツールがなくても、タグを付けたら、IDE の「アノテーションの参照箇所を検索」で一覧が得られます。まずこの状態で価値を確認し、必要になってから自動生成を足します。

## 6. 運用ルールと落とし穴

| 落とし穴 | 対策 |
| --- | --- |
| 名前や URL の直接参照で陳腐化する | 安定した基準（命名規約、タグ、フォルダ）で間接的に選ぶ |
| タグの付けすぎでコードが汚れ、意味も薄まる | サイトシーイング・マップは 5〜7 個（最大 10 個）に限定する |
| 全部を載せて、ノイズだけになる | 1 つのドキュメントにメッセージは 1 つ。目的外の情報は載せない |
| 何が模範例かで意見が割れる | チームの演習で合意を作り、特別なアノテーションで明示する |
| 模範例が複製され、改善が止まる | 目的を会話のきっかけと明記し、弱点も書く |
| 命名がばらばらで検索できない | `PointOfInterest` `KeyLandmark` などに統一し、名前を先に決める |
| 生成物が更新されない | ビルド/CI で自動生成し、公開まで自動化する |
| コードにない知識が足りない | アノテーションの説明や短い解説で補う |

### 運用のコツ

- ツアーやマップを作る作業は、設計の見直しにもなる。歩いてみて分かりにくい部分は、設計改善の合図です。
- ガイドツアーの各ステップには、1 つずつ、「次に何が起きるか」が分かる短い説明を付けます。
- 完全版と要約版を分けて用意すると、時間のない読み手にも届きます。
- 生成したドキュメントの入口を、README などから 1 本のリンクで示します。

## 7. 導入チェックリストと最初の一歩

### 導入前の確認

- [ ] 読み手と目的を 1 つに絞った
- [ ] 伝えたいメッセージを 1 文で言える
- [ ] 選択基準は名前や URL の直接指定ではなく、安定した基準である
- [ ] タグの名前と付与のルールをチームで合意した
- [ ] タグ付けの上限数（5〜7 個、最大 10 個）を決めた

### 導入後の確認

- [ ] IDE の検索で、タグ付き要素の一覧が得られる
- [ ] 抽出と公開がビルド/CI で自動化されている
- [ ] コードにない背景や意図が、説明文で補われている
- [ ] 手作業で更新しているリストが残っていない
- [ ] 定期的な見直しの機会（レビュー、ふりかえり）が決まっている

### 最初の一歩（小さく始める案）

1. 自分の担当プロジェクトで、コアと思う概念を 3〜5 個選び、`@CoreConcept` を付ける。
2. IDE の検索で一覧を確認し、チームに共有する。
3. 反応が良ければ、模範例、サイトシーイング・マップ、ガイドツアーの順に広げる。
4. 抽出スクリプトを書き、CI で生成して Wiki に公開する。

## 8. 関連ガイドと出典

- [Living Documentation導入ガイド](LivingDocumentation導入ガイド.md) - 知識のキュレーション（Knowledge Curation）の全体像
- [アノテーション導入ガイド](アノテーション導入ガイド.md) - 選択基準にするアノテーションの設計
- [ガイドツアー・サイトシーイング導入ガイド](ガイドツアー・サイトシーイング導入ガイド.md) - サイトシーイング・マップとガイドツアーの詳細
- [BDD導入ガイド](BDD導入ガイド.md) - タグによるシナリオダイジェスト
- 出典: 『Living Documentation』第 5 章「Living Curation」（pp.135–156）。コード例は説明用に書き起こしたもの。
