read-the-damn-docs

Read The Damn Docs

公式ドキュメントで答えが得られるのに、推測で済ませないでください。最も適切な対応は、最新の公式ドキュメントをウェブ検索し、関連するページを開いて、コーディングを始める前に読むことです。API、バージョン、プロバイダーの動作、設定、制限、ライフサイクルフック、セキュリティに関わるフローについては、ドキュメントに実際に書かれている内容を根拠にしてください。

ドキュメントを先に読むべき場合

以下のいずれかに当てはまる場合は、先にドキュメントを読んでください。

• ユーザーが「最新」「現在」「公式」「サポート対象」「ベストプラクティス」「推奨」「今日」「今」または「調べて」と尋ねている。
• 必要なドキュメントがリポジトリ内になく、ユーザーからも提供されていない。モデルの記憶が最新であることを期待するのではなく、公式ドキュメントをウェブ検索してください。
• タスクでパッケージ、SDK、フレームワーク、プラグイン、CLI、モデル、クラウドリソース、またはプロバイダー統合を追加、アップグレード、設定、インポートする。
• APIの変更が速い、またはバージョンに左右される。たとえば、AI SDK、OpenAI／Anthropic／Google API、Next.js、React、Tailwind、Vite、Nitro、Drizzle、Prisma、Stripe、GitHub、Slack、Notion、ブラウザー API、デプロイプラットフォーム、認証ライブラリなど。
• 実装が認証、OAuth スコープ、権限、シークレット、Webhook、課金、決済、PII、暗号化、データ保持、マイグレーション、再試行、レート制限、クォータ、キャッシュ、デプロイ、コンプライアンスに関わる。
• エラーに非推奨、不明なオプション、エクスポートの欠落、無効な設定、未対応のフィールド、デフォルト値の変更、バージョン不一致が示されている。
• リポジトリに、仕様を定めている可能性のあるローカルドキュメント、ADR、生成されたスキーマ、OpenAPI 仕様、ルート／アクションのレジストリ、デザインシステムのドキュメント、パッケージ単位の README がある。
• 選択を後から覆すのが難しい。たとえば、公開ワイヤーフォーマット、データベーススキーマ、マイグレーション戦略、永続 ID、イベント名、顧客向けの動作、外部自動化の契約など。
• 外部 API について、「通常は」「おそらく」「そう思います」「記憶では」などと書こうとしている、あるいはモデルの記憶からコードをコピーしようとしている。

ドキュメントとして扱うもの

入手可能な情報のうち、最も権威ある情報源を使用してください。

• プロジェクト固有の動作については、ローカルのリポジトリドキュメント、仕様、ADR、スキーマ、生成された型、パッケージの README、テスト。
• サードパーティの動作については、公式製品ドキュメント、API リファレンス、マイグレーションガイド、変更履歴、リリースノート、SDK のソース／型。正確な URL がわからない場合は、ウェブ検索で見つけてください。
• バージョンについては、パッケージレジストリのメタデータ。依存関係を追加する前に、npm view <pkg> version、pnpm view <pkg> version、または使用するエコシステムの同等のコマンドを実行し、そのメジャーバージョンのドキュメントを読んでください。
• 公式ドキュメントが不十分な場合は、ソースコードまたは型定義を参照してください。これらは根拠として扱い、伝聞として扱わないでください。

公式ドキュメントがある場合、主な情報源として Stack Overflow、古いブログ記事、出典不明のスニペット、記憶を使うのは避けてください。コミュニティの情報源は、権威ある仕様を確認してから症状のデバッグに使ってください。

必須のワークフロー

1. 対象となる具体的な範囲を特定します。パッケージ名、インストール済みのバージョン、対象バージョン、プロバイダーのエンドポイント、CLI コマンド、設定ファイル、ローカルヘルパー、スキーマ、製品機能などです。
2. 関連ドキュメントがすでにローカルにある場合や、ユーザーから URL が提供されている場合を除き、最新の公式ドキュメントをウェブで検索します。<product> <feature> official docs、<package> migration guide、<provider> API reference のような、対象を絞った検索語を使用します。
3. 対象に最も近いドキュメントを開いて読みます。内部コードについてはまずローカルのドキュメントを確認し、その後に公式の上流ドキュメントを確認します。新しいパッケージの場合は、インポート、設定、インストールコマンドを記述する前に最新バージョンを確認します。
4. タスクに必要な情報を絞り込んで抽出します。オプション名、インポート、ライフサイクルのルール、デフォルトの動作、破壊的変更、制限、権限、現在のメジャーバージョン向けの例などです。
5. 抽出した情報に基づいて実装または回答します。ドキュメントと既存コードが食い違う場合は、ローカルのコードパスを調査し、相違点を明示します。
6. 型チェック、テスト、ビルド、CLI のドライラン、API スキーマの検証、またはローカルでの再現など、最小限の有効なチェックで確認します。
7. 推奨や実装の根拠となったドキュメントまたはローカルファイルを、最終回答で明記します。

ドキュメントの確認が必須となる例

• 「このアプリに Tailwind を追加して。」現在の Tailwind のメジャーバージョンとインストール手順をウェブで確認してから、設定ファイルを作成したり、古い PostCSS の設定を前提にしたりします。
• 「AI SDK を使ってレスポンスをストリーミングして。」現在の AI SDK のメジャーバージョン、インポート、プロバイダーパッケージ名、ストリーミング用ヘルパー、サーバー／ランタイムの例を公式ドキュメントで確認します。
• 「Stripe の Webhook を接続して。」コードを書く前に、Stripe の現在の署名検証、イベントの再試行、エンドポイントシークレット、フレームワークのボディ解析に関するドキュメントを読みます。
• 「この Next.js のキャッシュのバグを直して。」キャッシュの無効化の仕様を決めつける前に、インストール済みの Next.js のメジャーバージョンとルーターのモードに関するドキュメントを読みます。
• 「Drizzle のマイグレーションを追加して。」ファイルを生成する前に、現在の Drizzle Kit のドキュメントと、既存リポジトリのマイグレーション規約を読みます。
• 「GitHub Action を作成して。」公式の Actions 構文と権限に関するドキュメントを読みます。特に pull_request、workflow_run、OIDC、トークン、アーティファクトについて確認します。
• 「この OAuth フローが失敗するのはなぜ？」コードを変更する前に、プロバイダーのスコープ、リダイレクト URI、PKCE、トークンの更新、アプリの検証に関するドキュメントを読みます。
• 「このリポジトリの plan/comment/action システムを使って。」エンドポイントや props を推測で作らず、ローカルのドキュメント、ルート／アクションのレジストリ、スキーマ、テストを読みます。
• 「Vite／Nitro／React をアップグレードして。」設定やインポートを編集する前に、対象となる正確なメジャーバージョンの移行ガイドを読みます。
• 「どのモデルを使うべき？」推奨する前に、プロバイダーの最新モデルのドキュメント、料金／制限のページ、SDK の例を読みます。

ローカルで簡単に確認すれば十分な場合

ごく小さな編集のたびにウェブを検索する必要はありません。既存のヘルパーの使い方、近くにあるテスト、型付きインターフェース、生成済みクライアント、ADR、パッケージの README など、リポジトリ内ですでに答えが得られる場合は、ローカルで簡単にドキュメントを確認すれば十分です。ただし、タスクが外部ツール、パッケージ、プロバイダー、または現在の製品の動作に依存する場合は、通常、まずウェブで検索します。単純な言語構文、誤字の修正、書式の調整、外部との契約に関係しない自己完結型のコードについては、通常どおり進めます。

ドキュメントを利用できない場合

ネットワークへのアクセス、認証、またはローカルファイルの不足によりドキュメントを読めない場合は、記憶に頼る前にそのことを明確に伝えます。不確実な範囲を絞り込み、利用可能であればソースコードや型を調査し、結果を最新情報として確認済みであるかのように示すことは避けます。