@k2works/claude-code-booster 6.4.0 → 6.5.0

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