@k2works/claude-code-booster 6.3.1 → 6.5.0

package/lib/assets/docs/reference//343/202/242/343/203/216/343/203/206/343/203/274/343/202/267/343/203/247/343/203/263/345/260/216/345/205/245/343/202/254/343/202/244/343/203/211.md

@@ -0,0 +1,268 @@
+---
+type: Reference
+title: "アノテーション導入ガイド"
+description: "『Living Documentation』第 4 章「Knowledge Augmentation」に基づき、設計判断・意図・根拠をコード上の構造化されたアノテーションとして残す導入手順（本質的な知識の判定、語彙カタログ、命名・コミット規約、ツール連携と検証、アンチパターン、チェックリスト）をまとめた導入ガイド。"
+tags: [reference]
+status: draft
+generated: { by: claude-code/claude-opus-5-5, at: 2026-09-29T00:00:00Z }
+---
+
+# アノテーション導入ガイド
+
+## 1. 目的と対象
+
+このガイドは、チームが設計判断・意図・根拠をコード上の**構造化されたアノテーション**として残し、ツールと人の両方が読める状態にするための導入手順をまとめたものです。
+
+- **対象**: Java（Spring Boot）や .NET（C#）でドメイン設計を行う開発チーム
+- **出典**: 『Living Documentation』第 4 章「Knowledge Augmentation」
+- **基本方針**: コードは「どう作るか」を語るが、「なぜそうしたか」は語らない。欠けている知識をコードの近くに、機械が解析できる形で補う。
+
+補強の手段は 3 系統あります。このガイドは主にアノテーション（内部ドキュメント）を扱い、規約とコミットメッセージにも触れます。
+
+| 手段 | 置き場所 | 向く知識 | 主な弱点 |
+| --- | --- | --- | --- |
+| アノテーション | コード内 | 役割・性質・レイヤー・根拠 | 付けすぎるとノイズになる |
+| 規約（命名・パッケージ） | コード内 | 分類・レイヤー | 根拠や代替案は書きにくい |
+| サイドカー/メタデータ DB | コード外 | 元ファイルに触れられない場合 | 名前変更・移動で関係が壊れる |
+
+## 2. 何に注釈を付けるか
+
+**要素そのものの性質（本質的な知識）だけを付け、状況や関係に依存する知識（外在的な知識）は付けない**のが原則です。
+
+判断の問いは 1 つです。「この要素を変更したとき、注釈の更新は最小の作業で済むか」。
+
+| 観点 | 本質的（付ける） | 外在的（付けない） |
+| --- | --- | --- |
+| 定義 | 要素を消せば一緒に消える知識 | 他の要素や状況との関係で決まる知識 |
+| 変更頻度 | 低い | 高い |
+| 例 | 値オブジェクトである、不変である、副作用がない | 誰が所有しているか、画面上のどこにあるか |
+| 保守コスト | 小さい | 大きい（注釈が常に古くなる） |
+
+### 付けすぎを防ぐ 3 つの方針
+
+1. **デフォルトを活用する**: 大半のクラスに当てはまる性質は注釈せず、例外だけに付ける。全クラスが不変なら、可変クラスにだけ `@Mutable` を付ける。
+2. **注釈のコストを意識する**: すべてのクラスに付く注釈はノイズになる。チームの方針を「例外だけ明示」に寄せる。
+3. **外在的な知識は別の手段で**: 変わりやすい情報は、コードの注釈ではなく外部ドキュメントや規約側に置く。
+
+## 3. 導入ステップ
+
+小さく始め、チームで語彙を合意してから広げる 5 段階です。
+
+1. **現状を棚卸しする**: 既存コードで、名前やコメントから読み取れる設計上の役割（値オブジェクト、リポジトリ、レイヤーなど）と、決定の理由が失われている箇所を洗い出す。
+2. **語彙を決める**: 標準文献（DDD、GoF、Fowler の PoEAA など）から借りる語彙と、自分たちの文脈固有の語彙を分けて一覧にする。最初は 5〜10 個に絞る。
+3. **アノテーション用パッケージを作る**: 参照元の書籍やスタイルが分かる名前にする(例: `com.acme.annotation.ddd`、`com.acme.annotation.algebra`)。メタアノテーションで性質を束ねるバンドルも用意する。
+4. **1 つのモジュールで試す**: `package-info.java` にレイヤーやスタイルを宣言し、主要なクラスにステレオタイプを付ける。IDE の検索とツールでの検証が動くことを確認する。
+5. **運用に組み込む**: コードレビューとコミット規約に組み込み、静的解析で違反を検出する。語彙は使いながら育て、不要になったものは削除する。
+
+どの段階でも、アノテーションは**リファクタリング耐性**を持つよう、対象のコードに直接付けます。クラス名変更や移動に追従するため、後から手作業で直す手間が減ります。
+
+## 4. アノテーション語彙カタログ
+
+語彙は目的別に 4 種類に分けると整理しやすくなります。
+
+| 種類 | 目的 | 例 |
+| --- | --- | --- |
+| ステレオタイプ | クラスの設計上の役割を示す | `@ValueObject`、`@Entity`、`@DomainService`、`@DomainEvent` |
+| 性質 | 望ましい振る舞いを宣言する | `@Immutable`、`@SideEffectFree`、`@IdentityByValue`、`@NotNull` |
+| レイヤー・スタイル | パッケージ単位の設計方針を示す | `@Layer(LayerType.INFRASTRUCTURE)`、`@FunctionalFirst` |
+| 根拠 | 判断の理由を記録する | `@MyAnnotation(rationale = "...")` |
+
+### 4.1 ステレオタイプ
+
+役割を表す注釈は、Spring の `@Service`・`@Repository` のように、フレームワーク側の意味と一致する場合だけ流用します。一致しない場合は独自の注釈を定義し、必要なら Spring の注釈で**メタ注釈**として束ねます。
+
+```java
+@Documented
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface ValueObject {}
+```
+
+### 4.2 性質のバンドル
+
+複数の性質を 1 つにまとめると、付ける手間とノイズが減ります。
+
+```java
+@Immutable
+@SideEffectFree
+@IdentityByValue
+public @interface ValueObject {}
+```
+
+こう宣言しておけば、クラスに `@ValueObject` を付けるだけで、不変・副作用なし・値による同一性の 3 つを宣言したことになります。
+
+### 4.3 レイヤーの宣言
+
+レイヤーは、`package-info.java` にパッケージ単位で 1 回だけ宣言します。
+
+```java
+@Layer(LayerType.INFRASTRUCTURE)
+package com.example.infrastructure;
+```
+
+レイヤーごとに独自のカスタム注釈(`@Layer(id = "repositories")` など)を作る方法もあります。
+
+### 4.4 根拠の記録
+
+判断が行われた箇所に、その理由を注釈で残します。
+
+```java
+@MyAnnotation(rationale = "We only know how to do that way")
+```
+
+実際には、次の 3 点を含めます。
+
+- **文脈**: 当時の制約や優先度（例: 「1000 人のユーザーで、1 週間だけ持てばよい」）
+- **問題・要件**: 何を解決したかったか
+- **選んだ理由と却下した代替案**: 他の候補と、採用しなかった理由
+
+### 4.5 .NET での対応
+
+.NET では、属性（Attribute）で同じことができます。アセンブリ単位の宣言は `AssemblyInfo` に書きます。命名は Java 版と揃え、チームで同じ語彙を使います。
+
+```csharp
+[AttributeUsage(AttributeTargets.Class)]
+public sealed class ValueObjectAttribute : Attribute { }
+
+[assembly: Layer(LayerType.Infrastructure)]
+```
+
+### 4.6 アノテーションのパッケージ名
+
+名前が意味を持つよう、参照元をパッケージ名に埋め込みます(例: DDD 由来なら `annotation.ddd`、Gang of Four 由来なら `annotation.gof`)。読む人が、その語彙の出典をたどれるようになります。
+
+## 5. 命名規約とコミット規約
+
+アノテーションが付けにくい場面や、既存コードに手を入れたくない場面では、**規約**が文書の役割を果たします。
+
+### 5.1 命名・パッケージ規約
+
+| 規約 | 例 |
+| --- | --- |
+| レイヤー別パッケージ | `*.domain.*`、`*.infra.*` |
+| 技術的ステレオタイプ別パッケージ | `*.dao.*`、`*.ejb.*`、`*.pojo.*` |
+| 別チームの公開規約を採用 | Rails の「テーブル名は `orders`、コントローラは `orders_controller`」 |
+
+- 規約は README などの**外部ドキュメント**に 1 か所でまとめ、新メンバーの参照先にする。
+- 別会社が公開している規約を採用すれば、自分で説明する手間が減る。
+- `Service` や `DTO` のような接頭辞・接尾辞をすべてのクラスに付けるのは避ける。情報を足さないノイズになる。
+- 規約は守られて初めて機能する。JDepend、ArchUnit、自作の解析ツールで検証する。
+
+### 5.2 コミットメッセージ規約
+
+コミットメッセージは、1 行ごとの変更に対する文書です。構造化しておけば、ツールが読めます。Angular 流の形式は次のとおりです。
+
+```text
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+| type | 用途 |
+| --- | --- |
+| `feat` | 新機能 |
+| `fix` | バグ修正 |
+| `docs` | ドキュメントのみの変更 |
+| `style` | 意味を変えない整形（空白、セミコロンなど） |
+| `refactor` | 機能追加でも修正でもないコード変更 |
+| `perf` | 性能改善 |
+| `test` | テストの追加・修正 |
+| `chore` | ビルドや補助ツールの変更 |
+
+- **scope**: 影響範囲。チームで一覧を決める(例: `pricing`、`ui`、`trade-feeding`)。
+- **破壊的変更**: footer に `BREAKING CHANGE:` から始めて、変更内容と移行方法を書く。
+- **Issue 参照**: footer に `Closes #8125` のように書く。
+
+```text
+feat(trade-feeding): Support trade feeding for negative-coupon
+
+Some bonds have negative coupon rates, e.g. -0.21 percent.
+Change the validation to not reject trades on bonds.
+
+Closes #8125
+```
+
+### 5.3 changelog の自動生成
+
+規約に沿ったメッセージは、`git log <last tag>..HEAD --grep feature` のようなコマンドで種別ごとに取り出せ、changelog の素案を生成できます。リリース前に、人が目を通して編集します。
+
+## 6. ツール連携と検証
+
+アノテーションは**機械可読**なので、ツールに任せられる作業が増えます。
+
+| 用途 | 使い方 |
+| --- | --- |
+| 検索・ナビゲーション | IDE で注釈を検索し、`@ValueObject` が付いたクラスを一覧する |
+| 補完・リファクタリング | 注釈はコードの一部なので、リネームや移動に自動で追従する |
+| 依存関係の検証 | `@Layer` を読み、レイヤー間の禁止依存を JDepend や ArchUnit で検出する |
+| 性質の強制 | `@Immutable` のクラスに可変フィールドがないか、静的解析で確認する |
+| 生成ドキュメント | 注釈を走査して、用語集やレイヤー図などの living document を出力する |
+
+### 導入時の注意
+
+- **注釈にコンパイラのチェックが効く形にする**: 文字列より列挙型(例: `LayerType.INFRASTRUCTURE`)を使い、誤記をコンパイル時に検出する。
+- **知識を 1 か所に集める**: 関連する注釈と、それを読むツールを同じモジュールに置く。
+- **CI で検証する**: 違反をビルドの失敗にすると、規約が形骸化しない。
+- **人が読む文書は生成物にする**: 手書きの設計図は古くなる。注釈から生成すれば、コードと同期を保てる。
+
+## 7. アンチパターンと代替手段
+
+### 避けること
+
+| アンチパターン | なぜ問題か | 代わりに |
+| --- | --- | --- |
+| 感情的な注釈(`@WTF`、`@Facepalm`、`@CantTouchThis`) | 型階層を汚し、理由が伝わらない | 構造化コメントで理由を書く、または根拠付きの注釈にする |
+| 標準注釈の流用（JPA など） | 永続化などの技術的関心事で、ドメインの意味が薄まる | 独自の注釈を定義し、必要ならメタ注釈で束ねる |
+| すべてのクラスに同じ注釈 | 情報量がゼロでノイズになる | デフォルトを決め、例外にだけ付ける |
+| 外在的な知識の注釈 | すぐ古くなり、変更コストが高い | 外部ドキュメントや規約に置く |
+| 推測に基づく文書化 | 使われない設計の説明が増える | 作ったものに対して、必要になった時点で書く |
+
+### 注釈が使えない場合
+
+| 手段 | 使う場面 | 注意 |
+| --- | --- | --- |
+| 構造化コメント（Javadoc タグなど） | 注釈がない言語、注釈を増やしたくない場面 | ツール支援が弱く、リファクタリングで壊れやすい |
+| サイドカーファイル | 元ファイルに触れられない（画像や音声など） | 名前変更・移動で関係が切れる |
+| メタデータ DB | 多数のファイルを一括管理する | 元ファイルと同期がずれるリスク |
+
+サイドカーファイルとメタデータ DB は最後の手段です。可能な限り、コード内のアノテーションを優先します。
+
+### 命名のヒント
+
+- 注釈が独自の意味を持つなら、標準の語彙（GoF、DDD）を出発点にし、自分たちの語彙を足す。
+- 感情や好みなど、注釈で表しにくい微妙な内容は、コメントやコミットメッセージ、ブログなど別の媒体に書く。
+
+## 8. 導入チェックリストと出典
+
+### 導入前
+
+- [ ] 決めたい知識（役割・性質・レイヤー・根拠）を、チームで 3〜5 項目に絞った
+- [ ] 各項目が本質的な知識か、外在的な知識かを判定した
+- [ ] 標準文献から借りる語彙と、独自の語彙を分けた
+
+### 設計時
+
+- [ ] 注釈用パッケージ名が、参照元（DDD、GoF など）を示している
+- [ ] 大半のクラスに当てはまる性質は、デフォルトにして注釈を省いた
+- [ ] 感情的・冗長な注釈を定義していない
+- [ ] 根拠には、文脈・問題・選択理由・却下した代替案を含めている
+
+### 運用時
+
+- [ ] レイヤーや性質の違反を、CI で検出できる
+- [ ] IDE で注釈を検索し、一覧できることを確認した
+- [ ] 規約（命名・コミット）を README にまとめた
+- [ ] 使われない注釈を定期的に見直し、削除している
+
+### 出典
+
+- 『Living Documentation』第 4 章「Knowledge Augmentation」（pp.95–133）。本ガイドは、この章の内容を導入手順としてまとめ直したもの。コード例は説明用に書き起こしたもの。
+
+### 関連ガイド
+
+- [Living Documentation導入ガイド](LivingDocumentation導入ガイド.md) - 知識の補い方（Knowledge Augmentation）の全体像
+- [ダイナミックキュレーション導入ガイド](ダイナミックキュレーション導入ガイド.md) - アノテーションを選択基準にして知識を選び出す
+- [ガイドツアー・サイトシーイング導入ガイド](ガイドツアー・サイトシーイング導入ガイド.md) - アノテーションから見どころとツアーを生成する
+- 本プロジェクトのコミット規約は `git-commit` スキル、根拠の記録は `creating-adr` スキル（ADR）を使う

package/lib/assets/docs/reference//343/202/254/343/202/244/343/203/211/343/203/204/343/202/242/343/203/274/343/203/273/343/202/265/343/202/244/343/203/210/343/202/267/343/203/274/343/202/244/343/203/263/343/202/260/345/260/216/345/205/245/343/202/254/343/202/244/343/203/211.md

@@ -0,0 +1,192 @@
+---
+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. 概要
+
+初めて訪れる街では、観光名所を巡る地図やガイドツアーで、要点を素早くつかめます。コードベースも同じで、初見の開発者には「見どころ」の案内が有効です。
+
+- **サイトシーイング・マップ**: 重要な場所（見どころ）を、順序なしでタグ付けして示す。
+- **ガイドツアー**: 見どころを順序付きでたどらせ、1 つの物語として案内する。
+
+どちらも、コードに付けた少量のメタデータ（アノテーション/属性）から自動生成し、コードの変更に追従させます。手作業のブックマーク一覧は保守が追いつかず、すぐ陳腐化するため使いません。
+
+**効果**: 新メンバーがコードを自力で探し回る時間を減らし、重要な部分から読み始められます。案内づくりは設計の見直しにもなります。
+
+## 2. 使い分け
+
+短時間で全体をつかませたいならマップ、処理の流れを追わせたいならツアーを選びます。
+
+| 観点 | サイトシーイング・マップ | ガイドツアー |
+| --- | --- | --- |
+| たとえ | 観光名所の地図 | 順路のある案内ツアー |
+| 順序 | なし（選んだ見どころの集合） | あり（rank で順序付け） |
+| 目的 | 重要な場所を素早く見つけさせる | 処理の流れを最初から最後まで追わせる |
+| 数の目安 | 5〜7 個、多くても 10 個 | 1 本あたり数ステップ（例: 6〜7） |
+| タグの例 | `@KeyLandmark` `@MustSee` `@PointOfInterest` | `@GuidedTour(name, description, rank)` |
+| 向いた場面 | オンボーディング初日、全体像の把握 | 特定の機能や処理チェーンの理解 |
+| 出力 | 見どころの一覧（リンク付き） | ステップ順に連結した文書 |
+
+**組み合わせ方**: まずマップで全体の見どころを示し、その中の主要な処理についてツアーを用意します。
+
+## 3. サイトシーイング・マップの作り方
+
+見どころを最も重要な 5〜7 個（多くても 10 個）に絞り、専用のタグで印を付け、自動で一覧を生成します。
+
+1. **見どころを選ぶ**: 「ここを理解すれば全体が分かる」場所を、チームで選びます。決めるのが難しい判断ほど、価値があります。
+2. **タグの名前を決める**: 何を示すかが分かる汎用名を 1 つ選びます。例: `KeyLandmark`、`MustSee`、`PointOfInterest`（POI）、`TopAttraction`、`CoreConcept`。
+3. **タグを付ける**: 選んだクラスやメソッドにだけ付けます。説明文で理由を書きます。
+4. **一覧を生成する**: IDE の検索、またはスクリプトで、タグ付き要素を集めます。
+5. **入口に置く**: README や Wiki からリンクします。
+
+**コードを汚さないために**: タグを付けすぎると、コードが目立つ印だらけになります。自然の中に、赤と白の標識をペンキで塗るのと同じで、少しだけに抑えます。
+
+**コードが頻繁に変わる場合の代替**: ブックマーク形式（タイトル、短い説明、場所へのリンク）で手作業の一覧を作る方法もあります。ただし、保守の負担が大きく、更新漏れが起きやすいため、可能なら動的な選択を選びます。
+
+**検索機能が使える場合**: GitHub のように、行単位でリンクできるなら、リンクを一覧に載せます。ツールがタグ検索に対応していれば、タグだけで十分です。
+
+## 4. ガイドツアーの作り方
+
+ガイドツアーは、処理の入口から出口まで、見どころを順にたどるルートです。コードに付けた `@GuidedTour` から、順序付きの文書を生成します。
+
+### パラメータ
+
+| パラメータ | 役割 | 備考 |
+| --- | --- | --- |
+| ツアー名（name） | どのツアーに属するステップかを示す | ツアーが 1 本だけなら省略可 |
+| 説明（description） | このステップの意味を、このツアーの文脈で書く | Javadoc は「使い方」、こちらは「ツアーでの意味」 |
+| 順序（rank） | ステップの並び順 | 数値など比較できる値。1, 2, 3...でも、10, 20, 30...でもよい |
+
+### 手順
+
+1. **ツアーの題材を決める**: 例として、「外部から届いたデータが処理され、DB に保存されるまで」のような 1 本の流れを選びます。
+2. **ステップを選ぶ**: 流れの節目になるクラスやメソッドだけを選びます。全部を載せると、ノイズになります。
+3. **タグを付ける**: 各要素に、名前、説明、順序を付けます。
+4. **生成する**: ツアー名で分類し、順序で並べ、各ステップのタイトルと説明を連結して、Markdown で出力します。
+5. **確認する**: 最初から最後まで歩いて、分かりにくい箇所を直します。
+
+**ステップの順序の付け方**: 途中に追加できるよう、10 刻み（10, 20, 30...）にすると便利です。昔の BASIC の行番号と同じ考え方です。
+
+**書き方のコツ**: 各ステップの説明は、「次に何が起きるか」が分かるように短く書きます。ツアーの最後のステップまで、1 本の物語になるようにします。
+
+**ドキュメント作成との関係**: ガイドツアーは、コードの順序に沿って散文を書く方法です（リテラルプログラミングの逆）。歩いた結果、構造の分かりにくさに気づけば、設計の改善にもつながります。
+
+## 5. 実装例
+
+### 5.1 サイトシーイング・マップのタグ（Java）
+
+```java
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+public @interface PointOfInterest {
+    String value() default "";
+}
+```
+
+```java
+@PointOfInterest("Key calculation")
+private double pricing(ExoticDerivative ...) { ... }
+```
+
+### 5.2 サイトシーイング・マップのタグ（C#）
+
+```csharp
+[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method)]
+public sealed class KeyLandmarkAttribute : Attribute
+{
+    public KeyLandmarkAttribute(string description = "") => Description = description;
+    public string Description { get; }
+}
+
+public class Foo
+{
+    [KeyLandmark("The main steps of enriching the Customer Purchase")]
+    public void Enrich(CustomerPurchase cp) { ... }
+}
+```
+
+複数の Visual Studio プロジェクトで共有するなら、属性は専用のアセンブリに置きます。
+
+### 5.3 ガイドツアーのタグ（Java）
+
+```java
+@GuidedTour(name = "Quick Developer Tour",
+            description = "The MQ listener which triggers a full chain of processing",
+            rank = 1)
+public class FuelCardTxListener { ... }
+
+@GuidedTour(name = "Quick Developer Tour",
+            description = "The DAO to store the resulting fuel card reports after processing",
+            rank = 7)
+public class ReportDAO { ... }
+```
+
+タグは、クラスにも、メソッド、フィールド、パッケージにも付けられます。名前は、目的に合わせて決めます。ツアー名を省略できるようにすると、ツアーが 1 本だけの場合に書きやすくなります。
+
+### 5.4 文書の生成の流れ
+
+1. `src/main/java` 以下のソースを走査し、`@GuidedTour` の要素を集める。
+2. ツアー名でグループ化し、`rank` で並べる。
+3. 各要素の名前と Javadoc、`description` を取り出す。
+4. Markdown に連結して出力する。各ステップのタイトルは、GitHub などのソースへのリンクにする。
+5. ビルドや CI で実行し、Wiki やサイトに公開する。
+
+Java では、QDox のような Doclet 風ライブラリで、Java ファイルの解析ができます。C# では、メタモデルを使います。
+
+**注意**: 生成の実装は、複雑になりがちです。アノテーションの走査と、Java の型の探索で、コードが毛深く育つことがあります。共通の用途なら、今後、主要ライブラリが対応する可能性があります。まずは IDE 検索で始め、必要になってから作り込みます。
+
+## 6. 運用ルールと落とし穴
+
+| 落とし穴 | 対策 |
+| --- | --- |
+| 見どころが多すぎて、マップの意味が薄れる | 5〜7 個（最大 10 個）に絞り、最も難しい取捨選択を避けない |
+| タグでコードが汚れる | 控えめに付け、説明はタグの引数か生成側に持たせる |
+| 手作業の一覧が古くなる | タグ付けと自動生成に統一し、名前や URL の直接指定を避ける |
+| ツアーの順序が変わり、番号が崩れる | 10 刻みで rank を付け、途中に追加しやすくする |
+| 説明がコードの複製になる | ツアーの文脈での意味と、次に起きることを書く |
+| 生成ツールが複雑化する | 最初は IDE 検索。必要になってから自動生成を作る |
+| 誰も読まない | README など入口からリンクし、オンボーディングで実際に歩く |
+
+### 運用のコツ
+
+- 新メンバーに歩いてもらい、迷った箇所をフィードバックとして、タグや説明を直す。
+- 大きな変更後は、ツアーが最後まで通るか、CI で確認する。
+- ツアーが長くなったら、テーマごとに分割する。
+
+## 7. 導入チェックリストと最初の一歩
+
+### 導入前の確認
+
+- [ ] 読み手（新メンバー、他チームなど）と目的を決めた
+- [ ] マップかツアーか、どちらから始めるかを決めた
+- [ ] タグの名前と付与のルールを、チームで合意した
+- [ ] マップは 5〜7 個、ツアーは数ステップ、という上限を決めた
+
+### 導入後の確認
+
+- [ ] タグ付き要素の一覧が、IDE の検索で得られる
+- [ ] ツアーがステップ順に生成され、各ステップから該当コードへ飛べる
+- [ ] 生成と公開が、ビルドや CI で自動化されている
+- [ ] README などの入口から、ドキュメントへリンクしている
+- [ ] 新メンバーに歩いてもらい、フィードバックを反映した
+
+### 最初の一歩
+
+1. 自分のプロジェクトで、最も重要な処理の流れを 1 本選ぶ。
+2. 流れの節目になる 5〜7 個の要素に、`@GuidedTour` を rank 10, 20, 30... で付ける。
+3. IDE 検索で一覧を確認し、順番どおりに読んでみる。
+4. うまくいけば、サイトシーイング・マップを足し、生成スクリプトと CI 公開へ進む。
+
+## 8. 関連ガイドと出典
+
+- [Living Documentation導入ガイド](LivingDocumentation導入ガイド.md) - 知識のキュレーション（Knowledge Curation）の全体像
+- [ダイナミックキュレーション導入ガイド](ダイナミックキュレーション導入ガイド.md) - 安定した基準で知識を選び出す手法全般
+- [アノテーション導入ガイド](アノテーション導入ガイド.md) - タグに使うアノテーションの設計
+- 出典: 『Living Documentation』第 5 章「Living Curation」（pp.145–152）。コード例は説明用に書き起こしたもの。

package/lib/assets/docs/reference//343/203/200/343/202/244/343/203/212/343/203/237/343/203/203/343/202/257/343/202/255/343/203/245/343/203/254/343/203/274/343/202/267/343/203/247/343/203/263/345/260/216/345/205/245/343/202/254/343/202/244/343/203/211.md

@@ -0,0 +1,191 @@
+---
+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）。コード例は説明用に書き起こしたもの。