根拠で進める開発仕事術：検索戦略・検証・引用の実務

第1章：一次情報の優先順位（公式/仕様/実装/ブログ）

この章で学ぶこと

  • 情報源を“優先順位”で扱う（公式→仕様→実装→二次情報）
  • 一次情報、二次情報、AI 生成物、経験則を混同しない
  • 対象バージョンと適用範囲を確認する
  • 結論と根拠リンクをセットで残す

成果物（または判断基準）

  • 調査ログ（付録: 調査ログテンプレ）
  • 一次情報へのリンク（公式ドキュメント/仕様/リリースノート等）

本文

一次情報は「正しい可能性が高い」だけでなく、「前提（適用範囲、対象バージョン）が明記されやすい」という利点がある。一方で、一次情報でも改訂遅れや記載漏れは起きるため、対象バージョンと実挙動（検証）で補強する。

一次情報/二次情報の定義

  • 一次情報: 公式ドキュメント、仕様（RFC/規格/契約）、実装（ソースコード/テスト）、リリースノート
  • 二次情報: ブログ/記事、SNS、Q&A（一次情報への導線として活用する）
  • AI 生成物: 要約、候補生成、比較表、コード断片など（根拠ではなく仮説として扱う）
  • 経験則/社内知見: 過去障害、運用メモ、ベテランの判断など（適用条件を明示して補助情報として扱う）

根拠タイプと採用条件

情報源は単純な上下関係ではなく、「何を決めたいか」に対する適合性で評価する。たとえば、標準準拠を判断するなら仕様が強く、実際の挙動を確認するなら実装や検証ログが強い。

根拠タイプ 主な用途 採用条件 ログに残すこと
公式ドキュメント/リリースノート 仕様、利用方法、サポート範囲の確認 対象バージョンと参照箇所が一致している URL、版、参照日、該当見出し
仕様/RFC/規格/契約 用語定義、要件レベル、互換性の判断 該当版と適用範囲が明確である 文書名、版、節番号、規範的キーワード
実装/テスト/検証ログ 実挙動、デフォルト値、境界条件の確認 コミット、環境、入力、観測点が固定されている Permalink、コミット、手順、実測結果
Issue/Discussion/PR 設計意図、既知制約、回避策の確認 メンテナの発言か、実装/リリースに接続できる コメント URL、採用理由、未確定点
ブログ/記事/Q&A 背景理解、検索導線、実務例の収集 一次情報に辿る導線として使える 記事 URL、対象バージョン、採用しない判断
AI 生成物 観点出し、仮説整理、説明のたたき台 一次情報または検証で裏取り済み AI 利用有無、AI 利用目的、プロンプト要旨、採否（採用/一部採用/不採用）と理由、裏取り結果、参照した一次情報/検証ログ、最終文責者
経験則/社内知見 運用上の制約、組織固有の判断 自組織の前提に限定され、再現条件が書ける 適用条件、例外、責任者/確認者

情報源が矛盾したとき

矛盾は「どちらが正しいか」を急いで決めず、次の順で切り分ける。

  1. 対象バージョン、プラン、地域、設定、実行環境が一致しているか確認する
  2. 仕様、公式ドキュメント、実装、リリースノートのどこが矛盾しているかを分ける
  3. 公式 Issue/PR、既知の不具合、移行ガイドに同じ差分がないか確認する
  4. 最小構成で検証し、観測結果を「仕様上の結論」と「実装上の観測」に分けて残す
  5. 判断できない場合は「未確定」として相談・エスカレーションする

優先順位の例

  • 公式ドキュメント（製品/OSSのdocs）
  • 仕様（RFC/規格/契約）
  • 実装（ソースコード/挙動）
  • Issue/Discussion（設計意図の補助）
  • ブログ/記事（補助）

手順（最小）

  1. 目的（何を決めるか）と対象バージョン/適用範囲を固定する
  2. 一次情報（公式/仕様/実装）から該当箇所を特定する
  3. 未確定点（推測/未検証）を残したまま結論に混ぜない
  4. 調査ログに「結論」「根拠（リンク/引用）」「未確定点」を分離して残す

注意点

  • 公式ドキュメントでも古い記述が残る。リリースノートや実装（Permalink）で差分を確認する
  • Issue/Discussion は有用だが、仕様そのものではない。採用する場合は採用理由と前提を残す
  • ブログ/記事は対象バージョンが不明確になりやすい。一次情報へ辿る導線として扱う

具体例（悪い例→良い例）

悪い例

結論: デフォルトタイムアウトは 30 秒
根拠: たまたま見つけたブログ（リンクのみ）

良い例

結論: デフォルトタイムアウトは 10 秒（設定で変更可能）
根拠: 公式ドキュメント（対象バージョン明記）
根拠: 実装コード（定数/デフォルト値の確認）
補足: 再現コードで 10 秒を観測し、条件（ネットワーク遅延）をメモした

チェックリスト

  • 一次情報（公式/仕様/実装）に当たっている
  • AI 生成物や経験則を、根拠ではなく仮説/補助情報として扱っている
  • 対象バージョンが明記されている
  • 結論と根拠リンクがセットになっている
  • 未確定点（推測/未検証）が分離されている
  • 情報源の矛盾を、対象バージョン・適用範囲・実測結果に分解している

まとめ

  • 一次情報（公式/仕様/実装）を優先し、二次情報・AI 生成物・経験則は補助として扱う
  • 結論は「対象バージョン」「根拠リンク」「未確定点」とセットで残す

次章への接続

Edit this page on GitHub