hec-ovi/research-skill

研究

プロジェクトスコープの永続的なストアで、深い調査結果を保存します。このスキルは、ユーザーが実質的な調査質問をした場合、または /research <トピック> で明示的に呼び出した場合に有効になります。

トピック引数（例： /research tailwind-v5）で呼び出された場合は、それを検索のシードとして使用し、まず INDEX.md でそのトピックを調べてください。盲目的に調査しないでください。ルックアップで即座に回答が得られる可能性があります。

使用するタイミング

• 「Xを行う最新のnpmパッケージは何か」
• 「2026年のA vs B vs Cの比較」
• 「Xを高速にクローンできるエンジン/フレームワーク/ライブラリはどれか」
• 「Yの内部動作を調査する方法」
• 「Zの詳細調査」
• ユーザーが長いマークダウンの調査ダンプを貼り付け、保存を依頼する

使用してはいけないタイミング

• 計画段階のメモ
• 小さな事実や一行の好み
• 単一ファイルに紐づくコードレベルの決定
• 単一の情報源から回答可能で、統合が不要な簡単なルックアップ
• 個人的なアイデアや思索の記録
• 単一のWebSearchまたはWebFetchの代替として

単一のWebSearchと1〜2文で質問に答えられる場合、このスキルは必要ありません。

セットアップ（初回のみ）

プロジェクトで初めてアクティブ化されたら、以下を一度だけ実行します。

1. プロジェクトルートを特定: git rev-parse --show-toplevel 2>/dev/null || pwd

2. 存在しない場合は <root>/.research/ を作成

3. 以下の正確な内容で <root>/.research/INDEX.md を作成:

   # 研究インデックス
   
   | トピック | パス | 最終確認日 | 一言要約 |
   |---|---|---|---|
   

4. .research/ を <root>/.gitignore に追加。.gitignore が存在しない場合は作成します。研究データには独自のインサイトが含まれる可能性があり、デフォルトで非公開とします。

データは <root>/.research/（.claude/ の兄弟であり、その内部にはネストされません）に格納されます。これは、研究データがプロジェクトと同じ場所に配置され、デフォルトでgitignoreされ、名前で簡単に見つけられるように選択されたトップレベルのプロジェクトディレクトリです。監査はそのまま維持されます。すべての読み取りと書き込みは、ホストの通常の権限システムを通過します。

ワークフロー

1. 検索（読み取り側 - これがスキルがコンテキストを節約する方法）

このシステムの要点は 段階的な開示 です。必要なものだけをロードしてください。 INDEX.md がディスパッチャーであり、エントリをロードする コストを支払わずに、どのエントリをロードするかを決定できます。最も安価なものから最も高価なものへと階層を進みます。前の階層が質問に答えられない場合にのみ、次の階層に進みます。

ロード階層（最も安い→最も高い）

階層	ロードするもの	おおよそのトークン数	タイミング
1	INDEX.md（常に）	~100-500	すべての検索時 - ルーティングテーブルとして機能
2	エントリの ## Summary のみ	~50-200	インデックスがトピックに一致した場合
3	完全な FINDINGS.md 本文	~500-3000	Summaryで質問がカバーされない場合
4	特定の raw/<file> ドキュメント	変動（多くの場合重い）	調査結果がそれを引用し、主張を検証する必要がある場合
5	相互参照されたエントリ（related:）	階層2-3を繰り返す	質問が複数のエントリにわたる場合

ルックアップ手順

1. まず INDEX.md を読む（階層1）。一言要約の列をユーザーの質問と照らし合わせてスキャンします。これはディスパッチャーであり、GBrainの RESOLVER.md と同じ役割です。

2. マッチングの判断:

   • 強い一致 - あるエントリの一言要約がトピックを明確にカバーしている → そのエントリでステップ3に進む。
   • 複数の可能性がある一致 - それぞれの ## Summary をロードする（それでも階層2で安価）。実際に回答するものを選択する。
   • 弱い/一致なし → 調査にフォールスルー。新しいエントリが追加されます。

3. 一致したエントリの ## Summary のみを読む（階層2）:

   sed -n '/^## Summary/,/^## /p' <root>/.research/<slug>/FINDINGS.md
   

   通常はこれで十分です。

4. 必要な場合のみ、次の階層にエスカレーション:

   • 質問がSummaryを超えた主張レベルの詳細を必要とする → 完全な FINDINGS.md 本文をロードする（階層3）。
   • 質問が「以前にXを試したか/何が破棄されたか？」である → そのセクションだけを sed で抽出: sed -n '/^## Discarded approaches/,/^## /p' <root>/.research/<slug>/FINDINGS.md。残りはロードしない。
   • 質問がペースト引用された主張を参照している → raw/ 下の該当ファイルを開く（階層4）。
   • 質問が別々のエントリでカバーされるトピックにまたがる → related: に従い、各エントリで階層2-3を繰り返す。

5. 調査にフォールスルー。モードを選択:

   • INDEX.md に エントリが存在しない → 新規エントリモード での調査。
   • 既存のエントリが実際に質問を解決しない（問題が未解決のまま） → マージモード での調査（既存のエントリ内容をサブエージェントに渡す）。
   • 既存のエントリが、急速に変化するトピックで古くなっている → マージモード での調査（リフレッシュし、引用しない）。

絶対にやってはいけないこと

• すべてをロードしないでください。 スキーマは選択的にロードできるように存在します。
• Summaryで十分な場合に完全な本文をロードしないでください。 3行で答えられるなら、300行を引っ張ってこないでください。
• 推測で生のドキュメントをロードしないでください。 それらは重く、ほとんどの質問には必要ありません。
• このセッションですでにロードしたエントリを再読み込みしないでください - 更新されていない限り。

INDEX.md をディスパッチャーとして

INDEX.md は、ロードせずに どのエントリをロードするかを決定できるように のみ 存在します。一言要約の列は、エントリ読み取りのコストを支払う前に持っている唯一のシグナルです。保存時には特にこれを記述してください。

INDEX.md はコンパクトに保ってください。約100行未満にしてください。それを超えて成長した場合は、プルーニングするかアーカイブしてください。INDEX.md 自体が肥大化の原因になると、トークン節約の設計全体が崩壊します。

2. 調査（新しい調査が必要な場合）

model: "opus" および run_in_background: true を指定して general-purpose サブエージェントを起動します。調査フェーズには強力なモデルが必要です。反対意見パスと統合ステップは、小さなモデルでは提供できない推論の深さに依存します。バックグラウンドモードにより、会話の対話性が維持されます。ユーザーは調査の実行中も作業を続けることができます。エージェントの完了通知が届いたら、ストレージが非同期的に実行されます。

サブエージェントは調査を実行し、構造化テキストとして統合結果を返します。ファイルは一切書き込みません。 すべてのファイル書き込みは、あなた（メインエージェント）がストレージで処理します。この分割により、責任が明確になります。サブエージェントはコンテキストがゼロであり、スキーマや INDEX.md のレイアウトを知る必要はありません。

命名規則。 Agentツールの description パラメータを Research investigation: <topic>（3〜5語）に設定します。これにより、research-skillの起動がハーネスUIで識別可能になります。

完了通知時: エージェントの戻り値を解析し、すぐにStorageを適用し、簡単な通知をユーザーに表示します（例： " の調査を に保存しました"）。求められない限り、完全な調査結果をチャットにダンプしないでください。

サブエージェントは事前コンテキストがゼロです。 このスキル、CLAUDE.md、または私たちの会話を見ることはできません。完全に指示を与えてください。このハーネスでは継続はありません - エージェントを再開するための SendMessage ツールは利用できません。ワンショットのみです。ギャップが残る場合は、改良された指示で再生成します。

モード（新規エントリ vs マージ）は、検索フェーズ5で決定されました。それに応じてサブエージェントに指示してください。

• 新規エントリモード - 標準の指示、既存のコンテキストは不要。
• マージモード - 既存のエントリの ## Summary および関連する ## Findings セクションを、"エントリの現在の状態 - 検証、更新、または置き換え" として明確にマークして、指示に貼り付けます。サブエージェントに、現在間違っている主張をフラグするように指示します。

指示チェックリスト

すべての調査指示には以下を必ず含める必要があります。

• 「あなたは事前コンテキストがゼロです」というプリアンブル
• 今日の実際の日付（最初に date +%Y-%m-%d を実行します。リテラル文字列を渡します）
• WebSearchクエリの年固定ルール（サブエージェントのモデルが現在の年について持っている事前知識を信頼しない）
• 自明でない主張ごとに少なくとも2つの独立した情報源。情報源は戻り値の最後にある単一の ## Sources ブロックにまとめられます。インラインで引用しないでください。
• 以下の認知フェーズを明示的な番号付きステップとして含める
• サブエージェントの必須出力形式（以下）
• Findings本文に対する厳格な [n] なし / インラインURLなしのルール（必須出力形式を参照）
• マージモードのみ: サブエージェントが検証/置き換える必要がある既存のエントリコンテンツ

認知フェーズ（指示に逐語的に含める）

サブエージェントはこれらを個別のフェーズとして実行します。フェーズ4が重要です。

1. 分解 - 質問を解決するサブ主張をリストアップします。それぞれを決着させる証拠を特定します。
2. 収集 - 各サブ主張について、≥2つの独立した情報源を見つけます（年固定のWebSearch → 上位結果のWebFetch）。逐語的に引用します。まだ統合しないでください。
3. 検証 - 数値、ベンチマーク、バージョン主張を再導出します。失敗するものをフラグします。
4. 反対意見パス - 「なぜこれが間違っているか/詐欺か/批判されているか/非推奨か/既知の悪いものか」を積極的に検索します。見つかった最も強い反論を述べます。これをスキップすることは、サブエージェントの最も一般的な障害モードです。 指示で明示的に注意を促します。
5. 統合 - 評決 + 引用 + 残りの不一致を明示的にリストアップします。黙って選択しないでください。

必須サブエージェント出力形式

指示には、明示的な引用ルールを含める必要があります。アカデミックなスタイルの文章でトレーニングされたサブエージェントは、デフォルトで [1]、[2] のインライン引用を使用するため、明示的な指示がないとノイズの多い出力を生成します。平易な言葉でルールを述べてください。指示に貼り付けるための推奨される逐語的ブロック:

引用ルール。注意深く読み、正確に従ってください:

• 番号付き引用 [n] は使用しないでください。Findings本文には [1]、[2]、または括弧で囲まれた数字は一切使用しないでください。
• Findings本文にURLを入れないでください。
• インラインの脚注マーカー、アンカー、または主張ごとの引用タグを一切追加しないでください。
• Findingsはプレーンな散文段落として記述してください。
• 主張の解釈がどの情報源が言ったかに依存する場合は、情報源を散文として名前を挙げてください（「READMEによると」、「littlemight.comによると」、「HN-simulatorのコメンテーターは...と主張している」）。URL、[n] はなし。
• すべての情報源を戻り値の最後にある単一の ## Sources ブロックにまとめ、情報源ごとに1つの箇条書き: - url - fetched YYYY-MM-DD。メインエージェントはこのブロックをFINDINGS.mdのフロントマターに移動します。
• 情報源の数の規律は維持されます。自明でない主張ごとに少なくとも2つの独立した情報源。規律はインラインタグ付けではなく、情報源の数にあります。

必須出力形式（サブエージェントが返すもの）:

## Summary
3〜6行のTL;DR。

## Findings
プレーンな散文。`[n]` マーカーなし。インラインURLなし。解釈に重要な場合にのみ、情報源を散文としてインラインで名前を挙げる。

## Strongest objection（反対意見パスから）
1〜2文、または「none found」。

## Sources
- url - fetched YYYY-MM-DD
- url - fetched YYYY-MM-DD

## （マージモードのみ）Supersedes
- 現在間違っている既存のエントリからの主張 + 理由

サブエージェントはファイルを書き込みません。この戻り値を解析し、Storageルールを適用します。

ギャップ処理

サブエージェントの戻り値にギャップがある場合:

• 小さなギャップ（1つの欠落した事実、1つの特定の角度） → フォーカスしたWebSearch/WebFetchで自分で埋めます。再生成するよりも安価です。
• 大きなギャップ（セクション全体が浅い、反対意見パスが明らかにスキップされている） → 特定のギャップを指定した改良された指示で再生成します。以前の戻り値は破棄されます（まだファイルは書き込まれていません）。

3. ストレージ（書き込み側 - メインエージェントがすべてのファイル書き込みを担当）

保存前のレビュー

サブエージェントの構造化フォーマットは、内容を検証するものではありません。フォーマットは「テンプレートに従いました」というシグナルにすぎず、内容が正しいか、適切に情報源が示されているか、質問に関連しているかを確認するものではありません。Storageを適用する前に、以下の4つのポイントをチェックしてください。

1. 関連性: Summaryは実際に質問に答えていますか？エージェントがあいまいなトピックを明確にした（いくつかの解釈のうち1つを選んだ）場合、ユーザーの意図と一致していることを確認してください。間違っている場合は、より厳密な指示で再生成します。保存しないでください。
2. 情報源の質: ## Sources ブロックで、プライマリURLと集約されたWebSearchスニペットの数を数えます。ほとんどの情報源が特定のフェッチされたURLのない検索結果の要約である場合、エントリは見た目よりも弱いです。フォーカスしたWebFetchで自分でプライマリを埋めるか、または保存しますが、## Open questions で弱点を明示的にフラグします。
3. 反対意見パスの証拠: 「none found」は、自明でないトピックではまれです。「none found」が返ってきた場合は、懐疑的になってください。トピックが本当に議論の余地がない（まれ）か、サブエージェントがフェーズ4をスキップした（一般的）かのいずれかです。スキップされた場合は、フォーカスした反対意見検索で自分で埋めるか、再生成します。
4. 引用のクリーンアップ: 指示の [n] 禁止ルールにもかかわらず、戻り値のFindings本文に [n] マーカーが含まれている場合は、FINDINGS.mdを書き込む前にそれらを削除します。これは既知の障害モードです（サブエージェントはアカデミックな引用習慣に戻ります）。ノイズを後続に押し出さないでください。Findings本文のインラインURLも同様に削除します。情報源はフロントマターに属します。

レビューで修正可能なギャップが明らかになった場合は、フォーカスしたWebSearch/WebFetchで自分で埋めてください（再生成よりも安価）。ギャップが体系的な場合は、改良された指示で再生成します。中途半端なエントリを書き込まないでください。

Storageの適用

調査が統合結果を返した後（またはユーザーが調査結果を貼り付けた後）、あなた（メインエージェント。サブエージェントは決して行いません）がデータレイヤーを確定します。検索フェーズ5で選択されたモードに基づいて、2つのパスがあります。

新規エントリパス:

1. <root>/.research/<topic-slug>/ を作成します。
2. ファイルスキーマのスキーマを使用して FINDINGS.md を書き込みます。フロントマター: created と last_verified は今日の日付。status: active。sources はサブエージェントの戻り値から。raw: は省略（まだ生データなし）。related: []（相互リンクが適用されない限り）。
3. INDEX.md を読み取り、行を追加します。トピック、パス、今日の日付、具体的な一言要約。

マージパス:

1. 既存の FINDINGS.md を読み取ります。
2. フロントマターを更新: last_verified は今日の日付。新しい情報源を追加します。
3. サブエージェントの ## Supersedes リストを適用: 名前付きの各主張を ## Findings から ## Discarded approaches に移動し、日付と理由を追加します。競合処理を参照してください。
4. 新しい主張で ## Findings を更新/拡張します。
5. 変更を要約する ## Timeline エントリを追加します。
6. INDEX.md を読み取り、行の Last verified 列を更新します。状況が変わった場合は、一言要約を更新します。

ユーザーが再度尋ねる可能性が高い方法に一致するケバブケースのスラッグを使用してください。例：tailwind-v5、2d-engines-clonable、orm-comparison-2026。スラッグは曖昧さを排除する必要があります。

4. 過去

…

[翻訳のため省略]