docs-sync

ドキュメント同期

概要

実装上の根拠を用いて、指定されたトピックまたは差分におけるドキュメントの不足や不正確な記述を特定します。

スコープと権限

監査または提案のみを求められた場合は、編集せずに指摘事項を報告します。ユーザーから更新を依頼された場合、または計画が承認された場合は、対象範囲内の編集と検証を、再度確認を求めずに完了します。未解決の動作、スコープ、リリース時期、または追加の権限についてのみ確認します。docs/ に未リリースの動作を含める前に、リポジトリの Documentation Release Timing ポリシーを適用します。

ワークフロー

1. スコープとベースブランチを確認する

   • 現在のブランチとデフォルトブランチ（通常は main）を特定します。
   • 進行中の変更と作業を合わせるため、現在のブランチの分析を優先します。
   • ブランチの差分は、ブランチを対象とする依頼の場合にのみ使用します。指定されたトピックやリリース済みドキュメントの修正は、現在のブランチ差分と無関係であってもスコープに含まれます。
   • ローカルの変更を妨げるブランチの切り替えは避けます。git show main:<path> のような読み取り専用の調査を優先します。別のチェックアウトが本当に必要な場合は、ワークツリーを作成または切り替える前に、AGENTS.md が求める明示的な承認を得ます。

2. 選択したスコープから機能一覧を作成する

   • 一覧は依頼されたトピックまたは差分の範囲に限定します。明示的に包括的な監査を求められた場合にのみ、全体を対象にします。
   • ブランチを対象とする作業では、意図されたベースとの差分を基に、追加、変更、削除を調べます。
   • ユーザー向けの動作に注目します。公開エクスポート、設定オプション、環境変数、CLI コマンド、デフォルト値、ドキュメントに記載された実行時の動作などが含まれます。
   • 各項目の根拠（ファイルパスとシンボル／設定）を記録します。
   • オプションの型や機能フラグを特定するには、対象を絞った検索を使います（例：rg "Options"、rg "process.env"、rg "export"）。
   • トピックが OpenAI プラットフォーム機能に関する場合は、推測ではなく、$openai-knowledge を呼び出して OpenAI Developer Docs MCP サーバーから最新の情報を取得します。相違がある場合は、SDK のソースコードを信頼できる情報源として扱います。
   • MCP SDK（modelcontextprotocol/typescript-sdk）または Vercel AI SDK（@ai-sdk/*）に関するトピックでは、簡単な確認のために Deepwiki MCP を任意で使用できます。その場合も、SDK のソースコードを信頼できる情報源として扱います。

3. ドキュメントを先に確認する：既存ページをレビューする

   • docs/src/content/docs/openai を除く docs/src/content/docs 配下の関連ページを確認します。
   • packages/ からの重要かつサポート対象のオプション（オプトインフラグ、環境変数）、カスタマイズ箇所、新機能について、記載漏れを特定します。
   • ユーザーがそのページで見つけることを妥当と期待する内容について、追加を提案します。

4. コードを先に確認する：機能とドキュメントを対応付ける

   • docs/src/content/docs 配下の現在のドキュメント情報アーキテクチャを確認します。
   • 既存のパターンとパッケージの境界に基づき、各機能に最適なページ／セクションを決定します。
   • ドキュメントページが存在しない機能、またはページはあるものの対応する内容がない機能を特定します。
   • 構成を調整すると見つけやすさが向上する場合は、その旨を記録します。

5. 不足や不正確な記述を検出する

   • 不足：main に存在する機能／設定がドキュメントに記載されていない。
   • 誤り／古い情報：名前、デフォルト値、または動作が main と一致していない。
   • 構成上の問題（任意）：ページに情報が詰め込まれすぎている、概要がない、トピックの分類が適切でない。

6. 提案する差分全体を分類する

   • 唯一の基準として、AGENTS.md の Documentation Change Verification Tiers を使用します。
   • 編集前に、提案する差分全体を、適用される Editorial、Content、または Structural ティアのうち最も高いティアに分類します。
   • ティア固有の検証は、$implementation-final-review、$code-change-verification、$changeset-validation、$pr-draft-summary に関する既存の適用条件とは分けて扱います。

7. 調査結果を報告するか、承認済みの更新を続行します

   • 監査のみの場合は、根拠、推奨する配置場所、変更案、必要な検証を提示して終了します。
   • 更新を依頼された場合は、調査結果と選択された検証レベルに基づいて、承認済みの編集を完了します。

8. 承認済みの変更を適用します（英語のみ）

   • docs/src/content/docs/** 内の英語ドキュメントのみを編集します。
   • レビューと更新の対象から docs/src/content/docs/openai を除外します。
   • docs/src/content/docs/ja、docs/src/content/docs/ko、docs/src/content/docs/zh は編集しないでください。
   • 変更は既存のドキュメントのスタイルとナビゲーションに合わせてください。
   • TypeScript または TSX のコードフェンスブロックを MDX に直接追加しないでください。TypeScript または TSX のスニペットはすべてコンパイル可能なソースファイルとして examples/docs/<doc-area>/ の下に配置し、?raw を使って MDX にインポートし、既存のドキュメントのパターンに従ってインポートしたソースを表示してください。
   • コードを完全な例として保守する価値がない場合は、未検証のスニペットを追加するのではなく、動作を文章で説明してください。
   • AGENTS.md に記載された、適用可能な最も高いドキュメント変更検証レベルで求められる、対象を絞った検証を実行してください。差分全体で、表示される TypeScript または TSX のスニペットソース、あるいはその MDX インポート／表示方法を変更した場合は、pnpm -F docs-code build-check を実行し、引き渡し前に問題を修正してください。

出力形式

調査結果を報告する場合は、次のテンプレートを使用してください。

ドキュメント同期レポート

• ドキュメント起点の調査結果
  • ページ + 不足している内容 → 根拠 + 挿入場所の提案
• コード起点の不足
  • 機能 + 根拠 → 推奨するドキュメントページ／セクション（または不足しているページ）
• 誤りまたは古いドキュメント
  • ドキュメントファイル + 問題点 + 正しい情報 + 根拠
• 構成に関する提案（任意）
  • 変更案 + 理由
• 変更案
  • ドキュメントファイル → 変更概要
• 未解決の判断事項（必要な場合のみ）

参考資料

• references/doc-coverage-checklist.md