software-research

ソフトウェア調査

これが行うこと

1つのソフトウェアエンジニアリングに関する質問を、検証済みの多角的な成果物にします。調査モードを選択し、そのモードの専門家の視点をシミュレーションして、意見が食い違う点を整理します。HTML のブリーフィングと Markdown または ADR の記録を作成した後、主な情報源に照らして、バージョンを考慮しながらすべての主張を敵対的に検証してから提出します。パイプライン全体を実行し、フェーズを省略しないでください。

ポータビリティ

自己完結型です。組み込みツール（汎用の Agent、Write、エージェント内のウェブ検索／取得）と、このフォルダー内のファイルのみを使用します。このフォルダーを任意の .claude/skills/ ディレクトリに配置すれば動作します。

フェーズ 0：範囲の設定とモードの検出

1. $ARGUMENTS に質問があればそれを使用し、なければ何を調査するか尋ねます。
2. data/modes.csv を読み込みます。各行の signals（セミコロン区切りの手がかり）と質問を照合し、最も適合する mode_id を選びます。
   • 2つ以上のモードが同程度に適合する場合は、ユーザーにどのモードにするか尋ねます（該当するモードと、それぞれの簡単な説明を提示します）。それ以外は続行します。
   • 該当するモードがなければ、フォールバックとして deep-research を使用します。
3. 選択したモードと、質問の解釈を1行で示します。ユーザーはモードを変更できます。
4. 文脈から読者の役割（developer / tech-lead / architect）を特定します。既定値は tech-lead です。
5. ファイル名用に kebab-case の topic-slug を作成します。
6. ゲート 1 — 範囲を確認する（ここで1回停止）。 簡潔なブロックを表示し、エージェントを起動する前にユーザーが確認または修正するまで待ちます。

   Mode:        <mode_id> — <one-line why this mode>
   Question:    <your one-line interpretation>
   Reader:      <developer | tech-lead | architect>
   Lenses:      <the N lens names about to run in parallel>
   Outputs:     <primary + secondary format, e.g. HTML briefing + MD>
   Then:        adversarial verification against primary sources.
   Proceed? (or correct the mode / scope)
   

   誤ったモードや範囲の読み違いを、約9〜12のエージェントを動かす前に低コストで修正できるのはここだけです。確認後は、ゲート 2 まで停止せずにフェーズ 1〜3 を自律的に実行します。

フェーズ 1：専門家の視点を並行して集める

references/modes/{mode_id}.md を開きます。このファイルには、このモードで使用する正確な視点のプロンプトが記載されています。そのモードの各視点を、汎用の general-purpose エージェントとして1つのメッセージで起動し、並行して実行します。すべてのエージェントには、同じ質問の枠組みに加えて、次の内容を渡します。

• モードファイルに記載された、その視点用のプロンプト
• references/source-hierarchy.md に記載された情報源の優先順位と検証要件（階層リストと7つすべてのルールを貼り付けます。Rule 7 も含め、重要な主張の根拠は Tier 1〜3 に限定し、ブログや Q&A は決して使わないこと）
• 次の内容を正確に返すよう指示します。(1) 2文の「中核となる見解」。(2) 3〜5個の箇条書きによる「最も強力な証拠」。各項目には具体的なデータポイント、一次情報源の URL、および主張が当てはまるバージョン／日付を含めます。(3) この視点ならではの「唯一の指摘」。400語未満とします。実際に取得した情報源のみを使用し、研究、数値、URL を捏造しないでください。

各視点から返答が届くたびに、そのブリーフを作業用スクラッチファイル software-research-reports/{topic-slug}.work.md に ## Lens: <name> 見出しの下へ追記します（このファイルはここで作成します）。届いたブリーフを順次書き込むことで、実行途中にクラッシュしても内容が失われず、ディスク上の記録から再開できます。ファイルの先頭に実行状態ブロックを設定します：stepsCompleted: [0, 1]

すべての返答が揃ったら、収束点と最も大きな意見の相違を、チャットに2〜3行で投稿します。生のブリーフをチャットに貼らないでください。

❌ よくある失敗：

• 一次情報源をたどらず、ブログ／SO の回答／モデルの記憶を証拠として引用する（Rule 3 と Rule 7 に違反）。ブログは事実の所在を示しますが、事実そのものは一次情報源にあります。
• バージョンを示さず、現在の事実として主張すること（「X は Y を行う」のようにバージョンの記載がない場合、未検証です（Rule 1））。
• 他の視点の返答を待たずに、声の大きい1つの視点に全体の筋書きを決めさせること。N 個すべての返答を待ちます。

フェーズ 2：矛盾を整理する（インライン、エージェントなし）

ブリーフのみをもとに、以下を特定します。

1. 直接的な矛盾 — 食い違っている具体的な主張を挙げます。
2. 最も強い証拠と最も弱い証拠 — 出典の階層に基づいて順位を付けます（Tier 1 一次資料／仕様 > Tier 2 セキュリティ／アグリゲーター > Tier 3 レジストリ > Tier 4 ベンチマーク > Tier 5 調査）。
3. 矛盾を解消する問い — 最大の矛盾を決着させる、単一の実証テストを示します。
4. 普遍的な一致点 — すべての観点が確認していること（根幹をなす知見）を示します。
5. 盲点 — どの観点も扱っていないことを示します（6 つ目の観点に欠けている点 → 最前線の問い）。

このマップをスクラッチファイルの ## Contradiction map の下に追記し、 実行状態を stepsCompleted: [0, 1, 2] に更新します。このマップは統合のための素材であり、独立した成果物ではありません。

フェーズ 3：出力を統合する

data/modes.csv から、モードの primary_output と secondary_output を読み込みます。

出力を作成する前に、必ず references/report-structure.md を読み込みます。 ここでは、 具体性に関する取り決め（一般論より具体的な内容を優先：正確なバージョン、実際のコマンド／設定／ コード、実際の数値、読み手のスタックに即した内容。さらに、埋め草表現の禁止リスト）と 12 セクションの詳細な骨子を定めています。詳細は単なる水増しではありません。トピックの概説ではなく、 実践的で読み手の状況に即した内容にすることで、レポートの分量に価値が生まれます。

• html の場合：assets/briefing-template.html を複製します。CSS は作り直さないでください。 すべての {{TOKEN}} を埋めます。テンプレートは 2 層構成です。（a）冒頭のすばやく把握できる層 — 判定スコアボード、主要な調査結果、（選択肢を比較するモードでは）横並び比較表を配置し、 5 秒で答えがわかるようにします。続いて、（b）12 セクションの詳細本文（セクション 06～16）で 骨子全体を網羅します。具体性に関する取り決めに従って詳細セクションを埋め、比較／数値／フローは 文章ではなくウィジェットで表現します。
• md の場合：references/report-structure.md にある 12 セクションすべての骨子を使います — 導入／方法論、状況、実装手順、スタック、統合、パフォーマンス、セキュリティ、推奨事項、 ロードマップ、リスク、方法論、最後に参考資料の付録を配置します。これは詳細なレポートです。 各セクションを具体的に記述します。参考資料の付録では、すべての出典をクリックできる [タイトル — バージョン／日付](url) 形式の Markdown リンクにします（表のセルに URL だけを記載しないでください。リンクとして正しく表示されないことがあります）。
• adr の場合：assets/adr-template.md を複製し、MADR の各セクション（Context、 Decision Drivers、Considered Options、Decision Outcome、Consequences、各選択肢の Pros/Cons、 More Information）と、最後の References セクションを埋めます。却下した選択肢とその理由も記録します。 ADR は簡潔な意思決定記録とし、12 セクションの骨子は使いません。ただし、具体性に関する取り決めは引き続き適用されるため、バージョンを明記し、具体的な根拠を引用してください。

論文ではなく、多忙なエンジニアに向けて書きます。 文は短く、平易な言葉を使い、結論を先に述べます。 避けられない用語は、その場で定義します。調査結果を理解するのに辞書が必要なら、書き直してください。

効果がある場合は、視覚化を追加します。 assets/widgets/ には、依存関係ゼロでそのまま使える視覚要素が 約 45 種類あります（インライン SVG／CSS／少量のバニラ JS）。assets/widgets/README.md を読みます。 用途別に分類した全カタログ（比較と意思決定、数値と根拠、仕組みの説明、時間経過、組織と管理、インラインのアクセント）と、 「使用する視覚要素の選び方」を番号付きで示す判断順序が記載されています。目新しさではなく、コンテンツの内容に応じて選び、 ファイルをコピーして FILL: マーカーを置き換えます。よく使うものには、comparison-matrix（選択肢 × 評価基準）、 weighted-decision-matrix（ADR のスコア付け）、metric-bars（ベンチマーク／コスト／サイズ）、 evidence-confidence（各調査結果の信頼度）、callout（注意点／警告）、verdict-card（推奨事項）、 slider-metric（唯一のインタラクティブな「ドラッグする」ウィジェット。1 レポートにつき最大 1 つ）があります。 ゼロ依存のウィジェットを標準にしてください。すぐにレンダリングされ、オフラインで動作し、印刷できるうえ、CDN の障害やランタイムのハンドシェイク失敗によって空白になることもありません。ツリー、グラフ、図には、ウィジェットで手動配置した座標を使ってください。自動レイアウトは使用しないでください。ライブラリを使うのは、独自の SVG では対応しにくい場合に限ります。テキストで書くほうが簡単な標準的なフロー図、シーケンス図、ER 図には Mermaid（バージョンを固定し、securityLevel:'strict' を設定）、大規模な実データの定量表示には Chart.js、**シンタックスカラーリングが必要なコードスニペットには code-compare（固定バージョンと SRI 付きで highlight.js を読み込みます。レポートごとにそのブロックを 1 回だけ含め、スニペットごとに class="language-…" を設定してください）**を使います。そのうえで、バージョンを固定し、CDN の <script> をそのまま使うのではなく、SRI またはインラインを優先してください。テンプレートに値を入れるのではなく、モデルに任意のウィジェット JS を生成させる場合は、サンドボックス化してください（allow-same-origin を付けずに iframe の sandbox="allow-scripts" を使用し、CSP で connect-src をブロックします）。生成されたマークアップはレポートのオリジン上で実行される信頼できないコードです。SRI では対処できません。ルールの全文は assets/widgets/README.md を参照してください。

出力は software-research-reports/ に保存してください（必要に応じて作成します）。

• HTML → {topic-slug}-briefing.html
• MD → {topic-slug}.md、ADR → ADR-{topic-slug}.md

❌ よくある失敗：

• 推奨事項を説明文の中に埋もれさせること — スコアボードと結論は、詳細に入る前に読者が答えを得られるように用意されています。
• 知的に見えても情報が伝わらない、学術的で回りくどい表現。
• X と Y の比較を求められているのに、比較表を省くこと（読者は並べて比較したいと考えています）。

フェーズ 4：敵対的検証（必須）

ゲート 2 — 検証前に調査結果を確認する（1 回停止）。 ドラフトを統合したら、チャットに簡潔な一覧を投稿します。推奨事項、3～5 件の主要な調査結果、そして重要な根拠（推奨事項の前提となる主張）を示します。調査結果のセットを確認し、さらに詳しく調査すべき点があれば指摘するよう、ユーザーに尋ねます。検証エージェントにコストをかける前に方向を修正できる、最後の安価なタイミングです。その後、4a～4c を実行します。

verify_depth は data/modes.csv に記載されています（full ＝すべての引用、load-bearing ＝推奨事項の前提となる主張。いずれも必須です）。

4a. セルフレビュー（インライン）。 各調査結果の信頼性を 1～10 で評価し、その理由を説明します（確信度ではなく、出典の階層に基づきます）。最も弱い根拠と、それを検証する方法を特定します。バイアスを確認します。どの視点が支配的だったか、何が軽視されたかを示します。欠けている第 6 の視点を挙げます。総合評価を率直に付けます。

4b. 引用を検証する（並列エージェント）。 1 回のメッセージで、引用クラスター（約 4～6 件）ごとに 1 つずつ、general-purpose エージェントを起動します。各プロンプトでは、references/source-hierarchy.md の7 つのルールすべてを適用し、主張を独立して一次情報源と照合するよう指示します（バージョンを特定する。現行バージョンで有効か確認する。一次情報源までたどる。日付を明記する。OSV/GHSA とバージョン範囲を使ってセキュリティを確認する。ベンチマークには再現可能な方法論が必要。重要な根拠となる主張は Tier 1～3 で確認できなければならない）。次のいずれかの判定とともに、バージョンと日付を含む、修正済みの 1 行の引用、および一次情報源の URL を含む 2～4 件の具体的情報を返すよう指示します。判定は CONFIRMED / PARTIALLY CONFIRMED（修正点を列挙）/ UNVERIFIED / FALSE / VERSION-STALE / UNVERIFIED-LOWTIER（Tier 5～6 の情報源のみで裏付けられ、一次情報源が見つからない重要な根拠となる主張）です。280 語未満に収めます。

4c. 修正を適用する。 誤った数値／タイトル／日付／バージョンを修正します。根拠が薄い場合は確信度を下げます。異論のある主張／プレプリント／バージョンが古い主張、および UNVERIFIED-LOWTIER の主張を、異論ありのサイドバーに移します（一次情報源による裏付けのない重要な根拠を、調査結果として残してはなりません）。検証バナーに N checked · X corrected · Y demoted · Z version-stale を記入し、引用ごとのステータスタグを付けます。主張の安全性ガイド（断言可／留保付き／使用回避）と、バージョンの最新性に関する注記を記入し、すべての情報源が References セクションにあることを確認します。実行状態を stepsCompleted: [0, 1, 2, 3, 4] に更新します。

❌ よくある失敗：

• 調査結果が「もっともらしく見える」からと検証を省略すること。もっともらしいが誤っている内容こそ、LLM パネルが生み出すものです。検証担当者がそれを防ぎます。
• ブログ／SO の回答のみを根拠とする重要な主張を、メインの調査結果に残してしまうこと（ルール 7 → UNVERIFIED-LOWTIER）。
• 検証担当者が一次情報源を取得せず、記憶に基づいて「確認済み」と判定すること。

出力

1. 成果物：検証後の HTML と MD/ADR を software-research-reports/ に保存します。
2. プラットフォームのオープナーで HTML を開きます。macOS の場合は open <path>、Linux の場合は xdg-open <path>、Windows の場合は start "" <path> を実行します。判断できない場合はパスを出力します。
3. チャットで要約します。ファイルパス、検証件数、普遍的な調査結果 1 件、推奨事項とその重要な根拠、未解決の最先端の問い、主張の安全性に関する要約（断言してよい内容と避けるべき内容）を含めます。簡潔にまとめます。

注意事項とガードレール

• Web 検索は必須です。 各レンズと検証担当者は、最新の一次情報を取得する必要があります。エージェント内で Web 検索／取得ができない場合は中止してユーザーに伝えてください。バージョンやセキュリティに関わるソフトウェアの質問に、学習データだけを根拠として回答してはいけません。モデルの記憶は Tier 6 であり、古くなります。
• 実際の調査のみを行います。 すべてのレンズと引用は、実際に取得したバージョンまたは日付付きの一次情報にたどれる必要があります。数値を検証できない場合は、格下げするか削除してください。決してごまかしてはいけません。
• Q&A より公式ドキュメントを優先します。 重要な主張の根拠は Tier 1〜3（公式ドキュメント／仕様、セキュリティデータベース、レジストリ）にたどれる必要があります。ブログ、Stack Overflow、Medium、モデルの記憶は一次情報を探すための手掛かりであり、それだけでは証拠になりません。
• 具体的かつ実用的にし、一般論は避けます。 正確なバージョンを明記し、実際のコマンド／設定／コードを示し、実数を使い、すべての推奨事項を読者のスタック、チーム、規模に結び付けてください。事実を述べずにカテゴリを説明する文（「堅牢なサポートを提供する…」「広く利用されている…」「パフォーマンスの向上に役立つ…」など）は削除してください。読者の行動に影響しない文は削除してください。完全な契約と良い例／悪い例については references/report-structure.md を参照してください。
• スクラッチファイル。 {topic-slug}.work.md には再開できるようレンズの概要と矛盾マップを記録します。これは作業用成果物であり、納品物ではありません。そのまま残してください（再開または再実行時に再利用できます）。納品物は HTML／MD／ADR です。
• バージョンを考慮します。 「X は Y を行う」という主張が有効なのは、「バージョン N では…」の場合のみです。非推奨またはバージョンが古い主張には印を付け、古い情報を現行の情報として提示してはいけません。
• パネルは著者が構成したものです。 そのことを開示してください。レンズ間の一致は有力な仮説であり、現場の総意ではありません。
• 信頼性とはソース階層に基づく証拠の品質であり、確信度ではありません。
• コスト。 実行あたり約 9〜12 個のエージェント（レンズと検証担当者）が必要です。これは想定どおりです。モードのレンズ数、または引用クラスターごとに 1 人の検証担当者を超えて増やさないでください。
• デザイン。 HTML テンプレートの CSS はそのまま維持してください（白を基調とし、Montserrat／Roboto Mono、青のアクセント）。