docs-sync

ドキュメントの同期

概要

main ブランチの機能や設定オプションを現在のドキュメント構成と比較して、ドキュメントの網羅性に関する不足や不正確な記述を特定し、的を絞った改善を提案します。

認可と対象範囲

監査または提案のみの依頼では、編集せずに調査結果を報告します。ユーザーが更新を依頼した場合、またはすでに計画を承認している場合は、再度確認せず、該当するローカル編集とチェックを完了します。未解決の対象範囲、動作、リリース時期、または追加の権限についてのみ確認します。生成された翻訳には手を加えません。docs/ に未リリースの動作を含める前に、リポジトリのドキュメントリリース時期ポリシーを適用します。

ワークフロー

1. 対象範囲とベースブランチを確認する

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

2. 選択した対象範囲から機能一覧を作成する

   • 機能一覧は、依頼されたトピックまたは差分の範囲に限定します。対象全体の一覧を作成するのは、包括的な監査が明示的に依頼された場合のみです。
   • ブランチに限定された作業では、意図されたベースとの差分を基準に、機能の追加、変更、削除を調査します。
   • ユーザーに見える動作に焦点を当てます。公開エクスポート、設定オプション、環境変数、CLI コマンド、デフォルト値、文書化された実行時の動作が対象です。
   • 各項目の根拠（ファイルパス＋シンボル／設定）を記録します。
   • オプションの型や機能フラグを見つけるには、対象を絞った検索を使います（例：rg "Settings"、rg "Config"、rg "os.environ"、rg "OPENAI_"）。
   • トピックに OpenAI プラットフォームの機能が含まれる場合は、推測せずに $openai-knowledge を呼び出し、OpenAI Developer Docs MCP サーバーから最新情報を取得します。相違がある場合は、SDK のソースコードを信頼できる情報源として扱います。

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

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

4. コード優先の確認：機能をドキュメントに対応づける

   • docs/ と mkdocs.yml における現在のドキュメント情報アーキテクチャを確認します。
   • 既存のパターンと docs/ref 以下の API リファレンス構成を基に、各機能に最適なページ／セクションを判断します。
   • ドキュメントページがない機能、またはページはあるものの対応する内容がない機能を特定します。
   • 構成を調整することで見つけやすさが向上する場合は、その旨を記録します。
   • docs/ref/* ページを改善する場合は、src/ にある対応する docstring／コメントを信頼できる情報源として扱います。生成済みのリファレンスドキュメントを直接編集するのではなく、再生成後も正しい内容が保たれるよう、これらのコードコメントを更新することを優先します。

5. 不足や不正確さを検出する

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

6. 調査結果を報告するか、承認済みの更新を続ける

   • 監査のみの場合は、根拠、推奨する掲載箇所、修正案を提示して終了します。
   • 更新依頼の場合は、調査結果に基づいて承認された変更を完了します。

7. 承認された変更を適用する（英語のみ）

   • docs/** 内の英語のドキュメントのみを編集します。
   • docs/ja、docs/ko、docs/zh は編集しないでください。
   • 既存のドキュメントスタイルとナビゲーションに沿った変更にします。
   • ページを追加または名前変更する場合は、mkdocs.yml を更新します。
   • AGENTS.md の Documentation Verification Tiers に従って差分全体を分類し、そのティアで必要なチェックのみを実行します。
   • 内容または構成を変更する場合は、編集と必要なレビューが安定してから make build-docs を一度実行します。編集のみの変更では実行しません。

出力形式

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

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

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

参考資料

• references/doc-coverage-checklist.md