researchkit

researchkit

「どれを使うべきか／どのアプローチを取るべきか」という問いを調査し、推奨案を提示します。researchkit は有力な選択肢を列挙し、それぞれを一次情報（公式ドキュメント、ソースコード、仕様、公式 API、メンテナーによるベンチマーク。ブログでの伝聞は含みません）に照らして調査し、実際に重要な制約条件のもとで比較したうえで、根拠と日付を明記して一つを選びます。これは意思決定のための調査です。目標は、中立的なメモの寄せ集めではなく、実際に行動に移せる選択肢を示すことです。

計画の前段階を担います。「Drizzle と Prisma のどちら？」「このワークロードにはどのキュー？」「ここでは REST と gRPC のどちら？」にまず答え、選んだ方向性を計画に落とし込みます。plankit を使う場合、researchkit はその前のステップです。

どのようなときに使うか

答えが明白ではなく、調べる価値がある「どれを選ぶか／どのアプローチを取るか」という問い全般が対象です。「X と Y を比較して」「どちらを使うべき？」「Z の選択肢を評価して」「…にはどのライブラリ／ツール／サービスが最適？」「X と Y のどちらを使うべき？」「構築前に X を調査して」「/researchkit」などが該当します。

意図的に対象としないことが二つあります。

• 中立的なメモ作成ではありません。 必ず最後に推奨案を示します。本当に比較対象がない場合（有力な選択肢が一つしか残らない場合）は、その選択肢を根拠付きで解説しますが、意見を含まないメモだけを成果物として提示することはありません。
• リポジトリの調査ではありません。 既存のパターンを再利用するためにこのコードベースを読むのは計画作業であり、researchkit の役割ではありません。researchkit が調査するのは、ツール、ライブラリ、サービス、アプローチといった外部の選択肢です。

調べるために実装してはいけません

researchkit の成果物は、根拠を示した論証であり、動作する成果物ではありません。ユーザーが最もよく目にする境界であり、これを越えるのは常に不具合です。仮説を検証するためにコードを書く、実行する、ひな形を作ることは決してありません。スパイク、プロトタイプ、ベンチマーク用ハーネス、使い捨てのリポジトリ、結果を見るためだけの npm install、さらには「手早く」行うものであっても例外ではありません。近道がどれほど魅力的に見えても、推奨案の精度がどれほど上がりそうでも、この原則は変わりません。

この失敗パターンは具体的で、内側からは親切に感じられるため、名前を挙げておく価値があります。調査でドキュメントからは判断できない主張が見つかり、小さなテストを作るのが解決への最短ルートに思えてきます。そして20分後、ユーザーは依頼してもいないプロトタイプについて読むことになります。ユーザーが尋ねたのは、どの選択肢を選ぶべきかです。実装を返すのは、尋ねられていない問いに答えることであり、許可なくユーザーの時間とトークンを費やし、求められていた比較を埋もれさせてしまいます。

したがって、仮説と根拠を示したら、そこで止めてユーザーに選んでもらいます。スパイクが本当に唯一の前進方法であるなら、「未解決の質問」に「これを解決するにはスパイクが必要です：＜測定する内容＞」と記載して、待ちます。スパイクの作成は、明示的に依頼された別の作業です。prototypekit がインストールされている場合はその担当であり、そうでなければ、ユーザーが名称を指定して依頼する使い捨てのプロジェクトです。researchkit の仕事では決してなく、ビルドステップの仕事でもありません。ビルドステップには、意図が確定しており、本番コードをリリースする必要があるからです。

手順

1. 意思決定の枠組みを定める

実際に何を選ぶのか、その選択を左右する制約条件を明確にします。組み合わせる技術スタック、規模、予算、チームの習熟度、必須機能、厳守すべき制約などです。依頼が一行だけの場合は、まず一度にまとめて、依頼から未確定の制約条件についてのみ確認します。一般的な比較を実際の推奨案に変えるのは、こうした制約条件です。

完了条件： 意思決定を一文で表せており、判断を左右するすべての制約条件に値が設定されているか、「重要ではない」と明示されています。

2. 有力な選択肢を見つける

知識のあるエンジニアが実際に比較検討する、本当の候補を列挙します。徹底的に見せるためだけに、わざと弱い候補を加えてはいけません。制約条件を満たす選択肢が一つしかない場合は、それを明示し、その選択肢の解説に切り替えます。

完了条件： 制約条件を満たし、知識のあるエンジニアなら検討するすべての選択肢がリストに含まれており、よく知られた選択肢のうちリストから除外したものには、それぞれ一行で理由が記されています。

3. 一次情報に照らして調査する

ホストが提供するウェブ検索／取得ツールを使って、判断の根拠となる各主張について信頼できる一次情報（公式ドキュメント、ソース、仕様、公式 API、メンテナーが公開したベンチマーク）を読み、二次的な解釈より優先してください。各情報源のバージョンと日付を記録し、証拠が古くなっている可能性がある場合（古いメジャーバージョンのベンチマーク、書き換え前のドキュメントなど）は明記してください。各主張が実際にどこで裏付けられているかを追跡してください。

次のいずれかに該当する場合は、依拠する前に情報源を再取得してください。対象のバージョンが、その選択肢の現行リリース系列より古い。対象の選択肢の最新メジャーリリースや書き換えより前の情報である。変化の速い分野（フレームワーク、ホスト型サービス、AI ツール）で、情報が12か月以上前のものである。保存済みの調査成果物を更新する場合。この場合、成果物に含まれる判断の根拠となる情報源をすべて再取得してください。新しい代替情報源がない情報源は、日付を付けて⚠ 古いと明記したうえで残してください。

ウェブにアクセスできない場合は、その旨をはっきり伝え、成果物の形式の暫定比較見出しの下で、知識に基づく最善の比較を示してください。**引用を捏造してはいけません。**情報源が見つからない場合は、創作せず、見つからないと明記してください。

情報源だけでは確証を得られない主張（実際のワークロードでの性能数値、2つのライブラリが実際に相互運用できるか、API がドキュメントの説明どおりに動作するかなど）は、未検証のままにしてください。測定で何を確認する必要があるかとともに、未解決の質問に記載してください。

完了条件：比較に含まれる判断の根拠となるすべての主張に、バージョンと日付を伴う情報源があるか、未検証として未解決の質問に記載されています。

4. 比較する

一般的な機能一覧ではなく、制約（意思決定の枠組みを定めるを参照）に照らして各選択肢を比較してください。比較に含まれる判断の根拠となる主張には、それぞれ情報源を付けてください。意思決定に実際に影響する比較軸に絞ってください。

完了条件：比較表のすべての行で、すべての制約軸に値が記載されており、各値に情報源が引用されているか、未検証と明記されています。

5. 推薦する

1つ選んでください。理由を1行で述べ、別の選択肢を選ぶ条件も示してください（「Drizzle はランタイムが軽く、コード生成が不要です。マイグレーションツールと管理用 GUI が必要なら Prisma を選んでください」）。読者が採用、却下、または方向修正できる推薦を示し、曖昧な結論で済ませないでください。推薦の根拠となる重要な主張が未検証または記憶に基づく場合は、推薦に暫定と明記し、その主張を示してください。

6. 引き継ぐ

このセクションは手順を示す文体で書きます。1文につき指示は1つにし、能動態、現在形を使い、比喩は使いません。

変更内容。 推奨事項を提示します。次に、それを保存するかどうかを一度だけ尋ねます。保存するとの回答があった場合は、次の連番、短い小文字のケバブケースの件名スラッグ、および成果物の ISO 作成日を使って、成果物を docs/research/NNNN-research-<slug>-YYYY-MM-DD.md に書き込みます（例：0003-research-auth-providers-2026-07-23.md）。連番 NNNN を取得するには、このチェックアウトとリポジトリ内のほかのすべてのワークツリーにある docs/research/ を調べ、先頭に付く4桁の連番のうち最大のものに1を加えます。該当するものがない場合は 0001 から始めます。このスキルではシェルを使えないため、Read と Glob でワークツリーを確認します。リンクされたワークツリーでは、.git は <main>/.git/worktrees/<name> を示すファイルです。<main> はメインのチェックアウトであり、各 <main>/.git/worktrees/*/gitdir には別のワークツリーのパスが格納されています。並行作業中のワークツリーで同じ連番が使われないよう、すべてを確認します。連番はディレクトリごとに管理し、再利用しません。後から編集する場合もファイル名全体を変えず、同じ成果物をその場で更新します。リポジトリで研究／メモ／RFC の保存場所や命名規則がすでに定まっている場合は、それに従います。デフォルトではチャット内にのみ出力し、ユーザーが永続的な記録を希望した場合に限りファイルに書き込みます。

保存先。 ファイルパスを示すか、レポートがチャット内のみにあることを伝えます。

次のステップ。 次のいずれかを1つ選び、まだ着手しません。

• 判断の根幹に関わる未解決の疑問には測定が必要 → prototypekit がインストールされている場合はそれを使ってスパイクを行い、インストールされていない場合は、ユーザーが名前を指定して依頼した使い捨てテストを行います。次の手順は、その回答が得られるまで保留します。
• それ以外の場合 → plankit がインストールされている場合はそれを使って、選択した方針を計画にまとめます。インストールされていない場合は、計画を直接作成します。未解決の疑問は計画に引き継ぎます。

成果物の形式

デフォルトではチャット内に出力し、依頼された場合に限りファイルに書き込みます。いずれの場合も、次の形式にします。

# Research: <the question>

## Recommendation
<the pick>: <one-line why>. Choose <alternative> instead if <condition>.

## Options compared
| Option | <constraint A> | <constraint B> | Fit |
|--------|----------------|----------------|-----|
| ...    | ...            | ...            | ... |

## Evidence (primary sources)
- <load-bearing claim> → <source URL> (<version/date>), ⚠ note if stale
- ...

## Provisional comparison (from recall, not verified)
- <claim> (as of <your knowledge cutoff>)

## Open questions
Unresolved or thin spots to settle when planning, including any claim that needs a measurement, with what the measurement would show.

Evidence には、この実行中に取得した主張だけを記載します。 記憶に基づく主張は Provisional comparison に記載し、Evidence には含めません。そうすることで、どの主張が情報源に裏付けられているかが一目でわかります。すべての主張に情報源がある場合は Provisional セクションを省略します。ウェブにアクセスできなかった場合は Evidence セクションを省略します。

判断に応じた分量にします。ライブラリを2つから選ぶ場合は短いブロックで十分です。アーキテクチャの選択では、より詳しく記載します。内容を埋めるだけのセクションは省略します。

注記

• 実行。 デフォルトでは、セッション内で同期的に実行します。ホストがバックグラウンドエージェントに対応し、かつユーザーが「バックグラウンドで調査して」と明示的に依頼した場合に限り、バックグラウンドエージェントを起動します。それ以外の場合は何も言わず同期実行に切り替え、存在するかわからない機能を待つことはしません。
• ツール。 allowed-tools では意図的にシェルとファイル編集のツールを利用不可にしています。これは、このフィールドに対応するホストで 作って確かめない を実現するための最後の手段です。
• 記憶より根拠を重視。 この方法がモデルに直接質問するより優れている理由は、一次情報源を厳密に扱う点にあります。追跡可能な根拠のない推奨は、表に入っただけの推測です。判断を左右する主張には出典を示すか、未検証であることを明記します。
• 変化の速い分野では鮮度が最も重要です。 状況が移り変わるツールやライブラリでは、各情報源のバージョンと日付は、装飾ではなく調査結果の一部です。
• ファイルシステムやシェルを使えない場合（ブラウザベースのエージェントなど）は、デフォルトですでにチャット内への出力になっているため、変更はありません。ファイル保存の提案は省略します。