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

第5章：根拠の残し方（リンク/引用/検証ログ）

この章で学ぶこと

  • 根拠は“リンク + 要約 + 自分の結論”で残す
  • 引用と要約を混同しない
  • 根拠の種類、信頼度、再確認条件を分けて記録する
  • 検証ログを“再利用できる形”で保管する

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

  • 調査ログ（意思決定に必要な根拠の束）
  • 引用箇所の明示（該当節/コミット等）
  • 再確認条件（いつ再調査するか）の記録

本文

根拠は“未来の自分/他者”への引き継ぎである。リンクだけでは、内容の変化やリンク切れに弱い。要点を短く残す。

手順（最小）

  1. 出典（一次情報）を特定し、版（対象バージョン/コミット）と参照日を固定する
  2. 参照箇所（節/見出し/行）を特定し、可能なら Permalink を残す
  3. 引用（原文）と要約（自分の言葉）を分離する
  4. 結論（その根拠で何を決めたか）と未確定点（要確認）を分離する
  5. 検証ログ（手順/観測/結果/否定結果）を再利用できる粒度で保管する

根拠の粒度

  • 仕様: 節番号、対象バージョン
  • 実装: ファイル/関数名、コミット
  • 検証: 手順、観測ログ、結果

根拠カードの最小項目

Issue、PR、ADR、Runbook に根拠を転記するときは、リンクだけでなく「採用判断に必要な項目」を1セットで残す。形式は自由だが、次の項目があると再確認しやすい。

項目 目的 記入例
根拠種別 一次情報、二次情報、AI 生成物、経験則を区別する 仕様 / 公式 Docs / 実装 / 検証ログ / AI 生成物（仮説）
対象範囲 どの環境・版・条件に効く根拠かを限定する v2.3.x / HTTP client / Linux only
信頼度 意思決定に使える強さを明示する 高: 公式 Docs + 実装 + 再現済み
再確認条件 いつ再調査すべきかを明示する 次メジャー更新時 / 依存更新時 / 仕様改訂時
採用判断 この根拠で何を決めたかを明示する 本番設定は CLIENT_TIMEOUT=30s とする
未確定点 推測や不足情報を結論に混ぜない streaming API の扱いは未確認

信頼度は「高/中/低」の粗い表現でよい。重要なのは、根拠の強さを結論文に埋め込まず、判断材料として分離することである。

再確認トリガ

一度確認した根拠でも、次のようなタイミングでは再確認する。

  • 対象製品、ライブラリ、クラウドサービス、標準仕様のメジャー更新が出た
  • リリースノートに互換性破壊、非推奨化、仕様変更が含まれる
  • 実装上の挙動が、過去の検証ログと異なる
  • セキュリティ、法務、プライバシー、料金、SLA など高リスク領域に関わる
  • AI 生成物や二次情報を起点にした仮説を、まだ一次情報で裏取りしていない

リンクで十分なケース / 引用が必要なケース

  • リンクで十分: 定義が安定しており、参照箇所が明確（仕様の節番号や公式ドキュメントの見出しが示せる）
  • 引用が必要: 将来の改訂で文言が変わりうる/判断根拠として文言そのものが重要（例: “デフォルト値”や“例外条件”）
  • 引用が難しい場合: 対象バージョン、参照日、該当箇所（見出し/節/コミット）を必ず残す

引用に含める最小情報

  • 出典（タイトル/URL）
  • 参照日（いつ見たか）
  • 対象バージョン（製品/ライブラリ/仕様）またはコミット/リリース
  • 該当箇所（節番号/見出し/ファイル/関数/行）
  • 自分の結論（その根拠で何を決めたか）

注意: 引用は必要最小限に留め、出典を明示する。要約は自分の言葉で書き、引用と混同しない（責任所在と改訂影響を分離する）。

証跡（ログ/設定/スクショ）の取り扱い（マスキング前提）

根拠としてログや設定を貼る場合は、秘密情報・個人情報を含めないことを前提にする。特に Issue/PR/チャットへの貼り付けは、公開範囲が広がりやすい。

  • 残す（調査に必要）: timestamp、request-id、HTTP status、エラー種別、対象バージョン、再現手順
  • 伏せる（貼り付け禁止）: トークン/パスワード/秘密鍵、Cookie、セッションID、個人情報、内部URLやIP（運用上の判断が必要）

禁止例（貼り付けない）

Authorization: Bearer <ACCESS_TOKEN>
Cookie: sessionid=<SESSION_ID>
GET /api/v1/users?email=person@example.com

推奨例（伏字/REDACTED）

Authorization: Bearer [REDACTED]
Cookie: sessionid=[REDACTED]
GET /api/v1/users?email=[REDACTED]
x-request-id: 2f3a8d1c-...

詳細な観点（データ分類、脅威、初動）は、別冊の security-privacy-literacy-book も参照する。

良い引用・良い参照（ミニ例）

  • 仕様/ドキュメント: 版（version）+ 節番号/見出し名 + 参照日
  • 実装: Permalink（blob/<sha>/...）+ 行/関数名
  • Issue/PR: コメント URL + 判断の根拠（採用/不採用の理由）

例（悪い→良い）

悪い: 「ここに書いてある」+ URL だけ（版・箇所が不明）
良い: v2.3 / "Timeout" 節 / 参照日 YYYY-MM-DD + 該当箇所の引用（短く） + 結論

反証（否定結果）の残し方（例）

調査の品質は「試したが違った」も残っているかで上がる。否定結果がないと、同じ試行が繰り返される。

仮説: TIMEOUT=30（環境変数）でデフォルト値が変わる
検証: v2.3 で TIMEOUT=30 を設定して実行
結果: 変化しない（10s のまま）
解釈: 参照した記事は v1 系の仕様だった。v2.3 は別の設定キー（CLIENT_TIMEOUT）を使用
次: 公式ドキュメントの該当節と実装の定数定義を確認する

恒久リンク（Permalink）の作り方（例）

リンクだけだと、ページ改訂・リダイレクト・消失に弱い。可能な限り「内容が固定されるURL」を使う。

  • GitHub（コード）: blob/<commit_sha>/... のURL（Permalink）を使う
    • 例: ファイルの「…」→「Copy permalink」
  • GitHub（Issue/PR）: 該当コメント/レビューのURLを使う（後から追跡できる）
  • 仕様/標準: 対象バージョン（または版）と節番号を残し、可能なら版固定のURLを使う
  • リリースノート: version 固定のページ（タグ/リリース URL）を使う
  • Web記事: 参照日と該当見出しを必ず残す（重要ならアーカイブも検討する）

運用に落とし込むため、調査ログテンプレでは「通常 URL」と「Permalink」を分けて記録する。

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

悪い例

根拠: https://example.com/doc
コメント: ここに書いてある

良い例

根拠: 公式ドキュメント（v2.3、"Timeout" 節）
要約: デフォルト10秒、設定で変更可、例外は接続確立前のみ
検証ログ: 手順/結果（添付）
結論: 本番は設定Aで30秒に延長（理由: 遅延ピーク対応）

チェックリスト

  • リンクだけでなく要約を残した
  • 根拠種別と信頼度を記録した
  • 対象バージョン/範囲を明記した
  • 再確認条件を明記した
  • 検証ログが再利用できる粒度になっている
  • 結論と根拠が対応付いている
  • 未確定点を結論から分離した

まとめ

  • 根拠は「リンク + 要約 + 結論」を基本に、版/参照日/箇所（節/コミット等）を残す
  • 根拠種別、信頼度、再確認条件を分け、引用・ログ・スクショはマスキング前提で扱う
  • Permalink、否定結果、未確定点も記録し、後続の再調査コストを下げる

次章への接続

Edit this page on GitHub