code-context

コードコンテキストの取得

このスキルでは、コードコンテキストを取得する5つの方法を紹介します。対象に応じて、公開 GitHub リポジトリ、ライブラリのドキュメント、コード検索、直接調査、クローン後のウェブ情報の補完から方法を選択してください。

トークンの分離（重要）

メインコンテキストでは、外部検索を実行しないでください。常に Task エージェントを起動してください。

• DeepWiki：エージェントが read_wiki_structure / read_wiki_contents / ask_question を呼び出し、アーキテクチャの概要と主要な関係を抽出して、簡潔な概要を返します。
• Context7：エージェントが resolve-library-id を呼び出してから query-docs を呼び出し、必要最小限の API と使用例を抽出して、バージョン情報付きのコピー可能なスニペットを返します。
• Exa：エージェントが get_code_context_exa を呼び出し、必要最小限のスニペットを抽出し、類似する結果（ミラー、フォーク、重複した StackOverflow の回答）を重複排除して、簡単な説明付きのコピー可能なスニペットを返します。
• Git clone：エージェントが /tmp/ にクローンし、エントリーポイントと主要モジュールを読み取り、rm -rf でクリーンアップして、ファイル構成の概要と主要なパターンを返します。
• ウェブ検索＋取得：エージェントがクローンの調査結果からバージョンを指定した検索クエリを作成して WebSearch を実行し、重要度の高い URL に対して WebFetch を呼び出して、クローンしたコードと照合済みの有効な知見のみを返します。

検索量にかかわらず、メインコンテキストはクリーンな状態に保たれます。呼び出し元に返されるのは最終的な概要だけです。

方法1：DeepWiki（AI 搭載のリポジトリドキュメント）

最適な用途：アーキテクチャの概要、コンポーネントの説明、または高レベルの理解をすばやく得たい場合の、よく知られた公開 GitHub リポジトリ。

ツール：read_wiki_structure、read_wiki_contents、ask_question

手順：

1. トピック一覧を取得するため、owner/repo（例："facebook/react"）を指定して read_wiki_structure を呼び出します
2. 関連するトピックについては read_wiki_contents を呼び出すか、対象を絞った質問には ask_question を呼び出します
3. アーキテクチャ図、コンポーネント間の関係、設計上の判断が必要な場合に使用します

強み：セットアップ不要で、AI が要約したドキュメントをすぐに取得できます。なじみのないリポジトリの導入に適しています。

制限事項：公開 GitHub リポジトリでのみ動作します。網羅性はプロジェクトの人気度によって異なります。

方法2：Context7（ライブラリのドキュメント）

最適な用途：npm/pip パッケージやフレームワークについて、最新の API ドキュメント、使用例、バージョン固有のドキュメントを取得する場合。

ツール：resolve-library-id、query-docs

手順：

1. 正式な ID を取得するため、ライブラリ名（例："react"、"fastapi"）を指定して resolve-library-id を呼び出します
2. ユーザーがバージョンを指定した場合（例："react@18"）、resolve-library-id が返す versions リストから一致するバージョンを選択し、ライブラリ ID のパスに追加します（例：/facebook/react/18.3.1）
3. libraryId と query を指定して query-docs を呼び出します。これらが唯一の2つのパラメーターです

クエリのヒント：具体的に指定してください。「react hooks」よりも「useCallback dependency array」の方が効果的です。分かっている場合は、フレームワークのバージョンも含めてください。

バージョンの固定：バージョンは別のパラメーターとしてではなく、ライブラリ ID のパスに含めてください（例：/vercel/next.js/v14.3.0-canary.87）。正しいスラッグを選ぶには、resolve-library-id の versions リストを使用します。

強み：常に最新のドキュメントを利用でき、バージョンの固定に対応しています。数千のライブラリを網羅し、API リファレンスに優れています。

制限事項：ライブラリがインデックス化されている必要があります。社内向けまたはプライベートなパッケージにはあまり役立ちません。

方法 3：Exa コード検索（Web 全体のコード例）

最適な用途：実際の使用パターン、StackOverflow 形式の回答、GitHub Gist の例、Web 全体のコードスニペットを見つける場合。

ツール：get_code_context_exa

セットアップ：API キーなしで動作します（無料プランにはレート制限があります）。上限を引き上げるには、EXA_API_KEY 環境変数を設定します。

手順：

1. get_code_context_exa を正確なクエリで呼び出します
2. 必要に応じて tokensNum を設定します。簡単な例なら 3000、包括的なパターンなら 8000 にします
3. 結果の公開日を確認し、新しい情報源を優先します

クエリ作成の指針：

• 言語またはフレームワークを含めます。単に "React" とするのではなく、"TypeScript React" とします
• 関連する場合はバージョンを含めます。"Next.js 14 app router" のようにします
• 正確な識別子を使います。"server action hook" ではなく "useServerAction" とします
• パターンの種類を追加します。"example"、"error handling"、"migration guide" などです
• 例："TypeScript Next.js 14 app router server action error handling example"

強み：公式ドキュメントに限らず、さまざまな実例を見つけ、コミュニティの解決策も提示します。

制限事項：結果が古い場合があります。必ず公開日を確認し、公式ドキュメントと照合してください。

方法 4：Git クローン（コードを直接調査）

最適な用途：プライベートリポジトリ、詳細な実装レビュー、ローカル分析の実行、または他の方法では深く調べられない場合。

手順：

1. git clone <repo-url> /tmp/<repo-name> --depth=1 を実行してコードを取得します
2. エントリポイント、設定、コアモジュールなどの主要ファイルを読みます
3. ファイル構成を把握し、コードベース全体からパターンを検索します
4. 作業が終わったらクリーンアップします：rm -rf /tmp/<repo-name>

強み：コード全体にアクセスでき、プライベートリポジトリでも（認証情報があれば）利用でき、静的解析ツールを使用できます。

制限事項：ネットワークアクセスとディスク容量が必要です。大規模なリポジトリでは時間がかかり、プライベートリポジトリには認証情報が必要です。

方法 5：Web 検索 + Fetch

最適な用途：ソースコード以外にある概念、理由、「ベストプラクティス」に関する質問、変更履歴、課題の議論、ブログ記事、移行ガイド。2 つのモードがあります：

• 単独での利用 — クローンせずに「なぜ」／「Z のベストプラクティス」／「X と Y の比較」を尋ねる自然言語の対象に対する主な方法です。
• クローン後の情報補完 — 方法 4 の後に使う補助的な方法です。クローンでコードを確認し、こちらで 理由 と 変更点 を把握します。

ツール：WebSearch、WebFetch

適用する場面：概念／理由／ベストプラクティスに関するクエリには単独で使い、リポジトリ調査にソースコードにはない背景情報を補う場合はクローン後に使います。

手順：

1. 絞り込んだクエリを作成します。クローン後のモードでは、クローンの調査結果から正確な識別子、エラー文字列、ソース内で見つかった設計パターンを使います。単独モードでは、自然言語の対象から直接作成します
2. query にバージョンを明示した正確な文字列（例："<library> <version> breaking change <symbol>"）を設定して WebSearch を呼び出します
3. 有用性の高い検索結果ごとに、検索結果の url と、関連するセクションだけを抽出するための焦点を絞った prompt を指定して WebFetch を呼び出します
4. 取得した内容を、可能な場合はクローンしたコードと照合し、それ以外の場合は公式ドキュメントと照合します
5. トピックが安定的／基礎的な内容でない限り、2 年以上前の結果は除外します

クエリのパターン：

• 変更履歴："<repo-name> CHANGELOG v<version>" または "<repo-name> release notes"
• 設計上の理由："<repo-name> <concept> why OR rationale site:github.com"
• 既知の問題："<repo-name> <symbol or pattern> issue OR bug site:github.com"
• 移行："<repo-name> migrate from <old-version> to <new-version>"

強み：廃止予定の通知、上流の課題スレッド、作者のブログ記事、コミュニティでの移行経験など、ソースコードには決して現れない背景情報を提示します。

制限事項：結果が古かったり不正確だったりする場合があります。取得した情報は必ず、実際にクローンしたコードと照合して検証してください。API キーがない場合はレート制限があります。

対象の分類

各入力対象は、次の3種類のいずれかに分類されます。手法を選ぶ前に分類してください。

• リポジトリ対象 — owner/repo 形式のスラッグまたは Git URL です。DeepWiki（公開リポジトリ）または Git Clone（プライベートリポジトリ／より詳細な調査）を使用します。
• ライブラリ対象 — パッケージ名／フレームワーク名のみ、または name@version 形式です。Context7 を使用し、バージョンを libraryId のパスに含めます。
• 自然言語の対象 — 質問、比較、概念（「X の仕組み」「X と Y の違い」「Z のベストプラクティス」など）です。コードパターンには Exa を使用し、根拠、変更履歴、「なぜ」に関する質問には Web Search+Fetch を使用します。クエリで特定のライブラリが指定されている場合は、正規の API サーフェスを確認するため、Context7 も実行します。

呼び出し元が --method= を指定した場合は、許可された手法と適用可能な手法の両方に含まれるものだけを使用します。対象に対して該当する手法がない場合、その対象について外部検索をスキップし、許可された手法が適用されないことを報告します。

手法の選択ガイド

シナリオ	主な手法	フォールバック
「X ライブラリの仕組みは？」	Context7	DeepWiki
「Y リポジトリのアーキテクチャを理解する」	DeepWiki	Git Clone
「Z パターンの例を探す」	Exa	Context7
「プライベート／社内リポジトリを調べる」	Git Clone	-
「ライブラリの v3 で何が変わった？」	Context7	Exa
「モジュール同士はどう接続されている？」	DeepWiki	Git Clone
「この設計判断がなされた理由は？」	Git Clone → Web Search+Fetch	DeepWiki
「バージョン間で何が壊れた？」	Web Search+Fetch	Context7
「X と Y を比較する」（自然言語）	Exa + Context7	Web Search+Fetch
「Z のベストプラクティス」（自然言語）	Web Search+Fetch	Exa

手法の組み合わせ

包括的な情報を得るには、次の手法を組み合わせます。

1. アーキテクチャの概要には DeepWiki
2. 特定の API の詳細には Context7
3. コミュニティでの使用パターンには Exa
4. 必要に応じて実装の詳細には Git Clone

常に、破壊を伴わない読み取り専用の操作を優先してください。クローンする場合は /tmp を使用し、完了後にクリーンアップしてください。