specsfy-specialist-technical-research

技術調査

使用する場面

• アーキテクチャ、ライブラリ、アプローチの選択が、誰も一次情報で確認していない技術的事実に左右されるときに実施します。
• コストの高い決定を元に戻す前に選択肢を比較するときや、依存関係の現在のバージョンでも想定している挙動が有効かを確認するときにも実施します。
• すでに決まった選択を、正当化を作るためだけに再確認することは避けます。これは調査ではなく、確証バイアスです。
• 調査結果が ADR に記録可能な構造上の決定を直接裏付ける場合は、$specsfy-specialist-software-architecture と組み合わせます。

手順

1. 具体的な質問、それが裏付ける決定、調査範囲、必要な情報の鮮度を定めます（今日の挙動が必要なのか、過去の情報で十分なのか）。
2. 各選択肢を裏付ける、または否定する証拠をあらかじめ定めます。そうしないと、どの結果も最初の仮説を裏付けているように見えてしまいます。
3. 次の順に優先します：仕様・標準、バージョンが明記された公式ドキュメント、公式のソースコードと変更履歴、対象環境で再現可能な実験、最後に二次情報。
4. バージョン、公開日、プロジェクトで実際に確認された環境への適用性を確かめます。別のバージョンについて記載された挙動は、使用中のバージョンに対する証拠にはなりません。
5. 決定にとって重要な主張はすべて、独立した二つ目の情報源で照合します。ドキュメントで疑問が解消されない場合は、条件を管理した実験を行います。
6. 確認済みの事実、推論（可能性は高いが未確認のもの）、リスク、証拠がないまま残る不足点を明確に分けます。
7. 主張を裏付ける直接リンクを、その主張の近くに添えて要約し、検討中の決定に対する具体的な影響を示します。

基準

• 一次情報にアクセスできる場合、API の挙動の根拠としてフォーラムのスニペット、個人ブログ、一般的な AI の回答を使いません。一次情報を探す手がかりとして使い、最終的な引用元にはしません。
• ドキュメントのトップページへの一般的なリンクではなく、主張の近くに、情報源のページと該当するセクションを記載します。
• 決定に必要な文脈を保って要約し、読解の手間を後回しにするだけの長い転載は避けます。
• リリースごとに挙動が変わり得る情報源は、そのバージョンと日付を記録します。これがないと、結論がいつの間にか古くなります。
• 2つの情報源に食い違いがある場合、どちらが優先されるのかを説明せず黙って一方を選ぶのではなく、食い違いを明示します。
• プロジェクトの規範となる情報源とは別に research.md を作成しません。調査結果はインデックス化され、利用側のプロジェクトの spec が定める場所に保存されます。
• 技術を提供するベンダー自身が公開したベンチマークは、利害のある証拠として扱います。出発点としては有用ですが、独立した再現なしに最終的な結論とすることはありません。

反パターン

• すでに決定した後で、確認だけを求めて調査します。ステップ 1 で立てた質問自体が、最初から偏っています（「X と Y のどちらか、どの基準で選ぶべきか」ではなく、「なぜ X の方が優れているのか」と問う）。
• リンクもバージョンも示さず「ドキュメントに書かれています」と引用します。挙動が変わったときに主張を再検証できません。
• ベンダーのマーケティング用ベンチマークを、プロジェクト環境での中立的な測定値であるかのように転載します。
• 複数の情報源が食い違う質問について、食い違いがあったことを記録せず、最初の好みに合う情報源を選んで解決します。

検証

• 判断を裏付ける各結論には、単なる記憶に基づく主張ではなく、直接的で追跡可能な証拠（リンク＋バージョン＋日付）があります。
• 使用する情報源は、一般的または古いバージョンではなく、利用するプロジェクトの実際のバージョンとランタイムに対応しています。
• 実施した実験は、他の人が再現でき、本番環境や実データに変更を加えません。
• 不明点や残る不確実性は、証拠から裏付けられる以上に確信的な結論で覆い隠さず、最終的な要約で明示します。
• 複数の情報源で裏付けられていない仮説を事実として提示しません。対応する証拠なしに確実性を示唆する表現は禁止です。

関連するスキル

• $specsfy-specialist-domain-modeling は、検証済みのドメイン用語を置き換えることなく、外部情報源を使って概念を整合させます。
• $specsfy-specialist-prototyping は、技術的な不確実性を、仮説と停止基準を備えた破棄可能な実験に変換します。
• $specsfy-specialist-software-architecture は、調査が ADR に記録できる構造上の決定を裏付ける場合に使用します。
• $specsfy-specialist-laravel-package-manager は、調査で Composer Laravel パッケージのドキュメント、バージョン、またはインストールの確認が必要な場合に使用します。
• $specsfy-specialist-debugging は、「調査」が実際には、観察された挙動がドキュメントの記述と異なる理由を調べる場合に使用します。その場合の目的は、選択肢の比較ではなく根本原因の診断です。

情報源の階層、証拠評価マトリクス、要約の形式については、references/standards.md を参照してください。