docs-search

AEM ドキュメントの検索

概要

このスキルを使うと、関係のないページにコンテキストを費やすことなく、aem.live のドキュメント（ドキュメントとブログ記事）全体を効率的に検索できます。付属の検索スクリプトで関連するドキュメントページを見つけ、最も関連性の高い結果の全文を取得して読みます。

このスキルを使用するタイミング

次の場合にこのスキルを使用してください：

• aem.live の機能や概念について情報が必要な場合
• すでにプロジェクトのコードベースを確認し、背景情報を把握している場合
• 基本的なウェブ検索を試したものの、関連する aem.live のドキュメントが見つからなかった場合
• aem.live の機能の実装に関する技術的なガイダンスが必要な場合
• 公式ドキュメントのベストプラクティスや例を探している場合

次の場合はこのスキルを使用しないでください：

• 再利用可能なコードスニペットやブロックの例が必要な場合（代わりに block-collection-and-party を使用してください）
• 特定のドキュメント URL がすでに分かっている場合
• 一般的なウェブ開発情報を探している場合（aem.live に特化した情報ではない場合）

このスキルの使用方法

ステップ 1：キーワードを特定する

検索内容に関連する具体的なキーワードを 1～3 個決めます。一般的なキーワードではなく、具体的なキーワードを選んでください。

適切なキーワード：

• 「ブロックの装飾」
• 「メタデータ」
• 「ユニバーサルエディター」
• 「サイドキックプラグイン」

適切でないキーワード：

• 「aem」（一般的すぎるため、ストップワードとして除外されます）
• 「ウェブサイトの構築方法」（範囲が広すぎます）
• 「the」（ストップワード）

ステップ 2：検索スクリプトを実行する

プロジェクトのルートから検索スクリプトを実行します：

node .claude/skills/docs-search/scripts/search.js [--all] <keyword1> [keyword2] [...]

オプション：

• --all：一致する結果をすべて返します（デフォルトでは関連性の高い上位 10 件に制限）
• --all を指定しない場合：上位 10 件を返します

例：

# Search for block decoration info
node .claude/skills/docs-search/scripts/search.js block decoration

# Search for metadata with all results
node .claude/skills/docs-search/scripts/search.js --all metadata

# Multi-word search
node .claude/skills/docs-search/scripts/search.js universal editor blocks

ステップ 3：検索結果を確認する

スクリプトは、次の構造の JSON を返します：

[
  {
    "path": "/developer/markup-sections-blocks",
    "title": "Markup, Sections, Blocks, and Auto Blocking",
    "description": "To design websites and create functionality, developers use the markup and DOM...",
    "snippet": "Markup, Sections, Blocks, and Auto Blocking\n\nTo design websites...",
    "type": "doc",
    "deprecation": null,
    "relevanceScore": 141
  }
]

フィールドの説明：

• path：ドキュメントページの URL パス
• title：ページのタイトル
• description：簡単な概要（通常約 150 文字）— 手早く内容を把握するために使用してください
• snippet：キーワードが使われている箇所が分かる、ページ内容の関連する抜粋
• type：「doc」または「blog」
• deprecation：機能が非推奨の場合の警告メッセージ（または null）
• relevanceScore：関連性スコア（高いほど関連性が高い）

重要な注意事項：

• 結果は関連性の高い順に並べられます
• 非推奨のページは関連性スコアが低くなりますが、結果には表示されます
• ページの概要を素早く把握するには、description フィールドが最適です
• snippet にはキーワードの文脈が示されますが、内容を網羅しているとは限りません

ステップ 4：ドキュメント全文を取得して読む

検索結果から概要を確認できます。詳しい情報を得るには、ページの全文を取得して読む必要があります。

対象 URL の形式：

https://www.aem.live{path}

取得方法： 利用可能な方法で、HTML またはテキストの全文を取得してください：

• 専用のウェブ取得ツール
• ターミナルコマンド（curl、wget など）
• ウェブの閲覧・スクレイピング機能

ベストプラクティス： まず関連性の高い上位 2～3 件を全文読み、さらに結果が必要かどうかを判断します。ドキュメント内で参照されているリンクをたどったり、読んだ内容を基に追加検索したりすることもできます。

ステップ 5：非推奨機能をユーザーに知らせる

結果に内容のある deprecation フィールドが含まれている場合は、その機能が非推奨であることをユーザーに知らせ、非推奨に関するメッセージを含めてください。関連性スコアがより高い（非推奨ではない）代替機能を確認するよう提案してください。

検索対象

検索スクリプトは、まずドキュメント（150 ページ以上）を検索します。ブログ記事が検索されるのは、ドキュメントの結果が 5 件未満の場合のみです。ブログ記事も含めて網羅的に検索するには、--all フラグを使用してください。

例

例 1：ブロックのドキュメントを探す

ユーザーのリクエスト：「aem.live でブロックを装飾するにはどうすればよいですか？」

適切な方法：

1. 検索：node .claude/skills/docs-search/scripts/search.js block decoration
2. 上位 3 件の結果を確認します
3. 最も関連性の高いページを取得します：https://www.aem.live/developer/markup-sections-blocks
4. 全文を読み、回答します

適切でない方法：

• 代わりに一般的なウェブ検索を使う（無関係な結果に時間を取られます）
• 検索スクリプトを使わない（最適なドキュメントページを見逃す可能性があります）

例 2：メタデータについて調べる

ユーザーのリクエスト：「ページにメタデータを追加したいです」

適切な方法：

1. 検索：node .claude/skills/docs-search/scripts/search.js metadata
2. 上位の結果が「/docs/bulk-metadata」であることを確認します（スコア：63）
3. 「/docs/metadata」も確認します（スコア：30）
4. ページ単位のメタデータと一括メタデータの違いを理解するため、両方を取得して読みます
5. 両方の方法を含む包括的な回答を提示します

適切でない方法：

• 最初の結果しか読まず、一括メタデータの選択肢を見逃す
• 網羅的に調べる必要がある場合に --all を使わない

例 3：非推奨機能に関する警告

ユーザーのリクエスト：「フォルダーマッピングを使うにはどうすればよいですか？」

検索結果：

[
  {
    "path": "/developer/authoring-path-mapping",
    "title": "Path mapping for AEM authoring",
    "relevanceScore": 51,
    "deprecation": null
  },
  {
    "path": "/developer/folder-mapping",
    "title": "Folder Mapping",
    "relevanceScore": 34.5,
    "deprecation": "Please contact us if you have a use case for folder mapping..."
  }
]

適切な回答： 「フォルダーマッピングに関する情報が見つかりましたが、この機能は非推奨です。非推奨に関するお知らせには、『フォルダーマッピングのユースケースがある場合は、お問い合わせください……』と記載されています。現在推奨されている方法は、最上位の検索結果にある AEM オーサリング向けのパスマッピング です。代わりに、そのドキュメントを読んでご案内します。」

適切でない方法：

• 非推奨の警告を無視して、非推奨機能を実装する
• より適切な代替方法に触れない

関連スキル

• block-collection-and-party：再利用可能なコード例やブロックの実装が必要な場合に使用します
• building-blocks：ブロックをゼロから作成する場合に使用します
• content-modeling：ブロックのコンテンツモデルを設計する場合に使用します

重要な注意事項

1. 非推奨に関する警告を必ず確認し、ユーザーに知らせます
2. ページを取得して全文を読みます。検索結果は適切なページを見つけるためのものにすぎません
3. 検索範囲を広げる前に、上位 2～3 件の結果を確認します
4. description フィールドを活用します。通常、よく書かれていて簡潔です
5. スニペットだけに頼らないでください。スニペットは概要を把握するためのものであり、網羅的な情報ではありません