update-docs

現在のブランチにおけるソースコードの変更を反映するため、ドキュメントページを更新します。mainとの差分を分析し、変更されたソースファイルを対応するドキュメントページに割り当て、対象を絞って編集します。

このスキルはリポジトリに依存せず、共有されています。pipecat-dev-skills マーケットプレイスから公開されており、変更内容が pipecat-ai/docs に反映されるすべてのリポジトリで使用されるため、特定のリポジトリに固有の内容を含めないようにしてください。

リポジトリ固有の情報（対象範囲、ファイルとページの対応、新しいページの形式、登録先）はすべて、ドキュメント対象のリポジトリにある、そのリポジトリのプロファイル .claude/skills/update-docs/SOURCE_DOC_MAPPING.md から取得します。このスキルでは、ソースパス、ページテンプレート、ナビゲーショングループをハードコードしません。プロファイルに必要な内容については、PROFILE_CONTRACT.md を参照してください。

ページの読み方（何を記載するか、何を省くか、ページテンプレート、文章の書き方）は、ドキュメントリポジトリのスタイルガイド DOCS_PATH/STYLE.md に従います。このスキルでは、変更点の特定、ドキュメントに必要な内容の判断、結果の確認という手順を扱います。

REVIEW.md は、更新が完了した後に、更新を行っていない新しいセッションで実施する2回目のレビューです。自動処理ではこのスキルの実行後にレビューが行われます。ローカルで更新した場合も、同じ手順で手動レビューを実施してください。

引数

/update-docs [DOCS_PATH]

• DOCS_PATH（任意）：ドキュメントリポジトリのルートへのパス。指定されていない場合は、ユーザーに尋ねます。

例：

• /update-docs /Users/me/src/docs
• /update-docs

手順

ステップ 1：ドキュメントのパス、プロファイル、スタイルガイドを確認する

DOCS_PATH が引数として指定されている場合は、その値を使用します。それ以外の場合は、ドキュメントリポジトリへのパスをユーザーに尋ねます。

パスが存在し、docs.json が含まれていることを確認します。

ソースリポジトリにある .claude/skills/update-docs/SOURCE_DOC_MAPPING.md のプロファイルを読みます。プロファイルには、このリポジトリの対象範囲、対応表、ページテンプレート、登録手順が定義されています。存在しない場合は、処理を中止してその旨を伝えてください。このファイルがなければ、ファイルをページに対応付ける方法がなく、推測で編集すると存在しないページを変更することになります。

DOCS_PATH/STYLE.md をすべて読みます。すべての編集でこのファイルに従います。ページの書き方について、このファイルとスキルの指示が異なる場合は、スタイルガイドを優先してください。ファイルが存在しない場合は、このスキル末尾のガイドラインに従います。

ステップ 2：ドキュメント用ブランチを作成する

現在のソースブランチ名を取得します。

git rev-parse --abbrev-ref HEAD

ドキュメントリポジトリで、main から同じ名前の新しいブランチを作成します。

cd DOCS_PATH && git checkout main && git pull && git checkout -b {branch-name}-docs

たとえば、ソースブランチが feat/new-service の場合、ドキュメントブランチは feat/new-service-docs になります。

以降の手順で行うドキュメントの編集は、すべてこのブランチで実施します。

ステップ 3：変更されたソースファイルを特定する

次を実行します。

git diff main..HEAD --name-only

プロファイルの対象範囲セクションで指定されているルート配下のソースファイルは、すべて対象です。リポジトリでは、最もわかりやすいエントリーポイント以外にも広範な公開 API が提供されます。そのため、対象範囲は許可リストではなく除外リストとして定義します。新しいディレクトリは、誰かが登録を思い出した時点ではなく、作成された時点で対象になります。

プロファイルの対象範囲セクションで除外されているものに加え、ビルドおよびキャッシュの生成物（__pycache__/、*.pyc、node_modules/、dist/）と、それ自体では何も定義しない再エクスポート専用の index ファイルを除外します。

これらのルート外の変更（例、CI 設定、ドキュメントディレクトリ）は、それだけではドキュメント更新の対象になりません。

次に、プロファイルのスキップリスト（ステップ 4）を適用します。このリストには、真に内部的な少数のファイルが記載されています。ここで、それ以外のファイルを除外する理由を独自に作らないでください。ベースクラス、共有モジュール、「コアアーキテクチャ」であることは、除外理由になりません。公開コンストラクターパラメーターと観測可能な動作は、どこにあってもドキュメントに記載します。対応するページが明確でないファイルは、一覧から消すのではなく、報告すべき未対応項目としてステップ 8 に進めます。

Step 4: ソースファイルをドキュメントページに対応付ける

変更された各ソースファイルについて、プロファイルのテーブルを次の順序で確認し、編集するドキュメントページを特定します。候補のパスを使用する前に、すべて DOCS_PATH に存在することを確認してください。

1. スキップリスト — ファイルがスキップリストに該当する場合は、そこで終了します。ドキュメントの更新は不要です。
2. 基底クラス — ファイルが基底クラスのテーブルにある場合は、記載されているすべてのページを使用します。ここでの変更は、そのクラスを継承するすべてのものに影響するため、最初のページで止めず、各ページを確認してください。
3. 標準外の場所 — ファイルが標準外の場所のテーブルにある場合は、その項目のパスを候補として使用し、存在することを確認します。
4. パターン照合 — パターンテーブルを適用して候補パスを取得し、その .mdx ファイルが存在することを確認します（DOCS_PATH 内で glob／ls を実行します）。存在する場合は、それを使用します。
5. 検索 — ステップ 2～4 で得た候補がどれもディスク上に存在しない場合は、ファイルの主要なクラス名またはエクスポートされたシンボル名で DOCS_PATH を grep します（プロファイルの Search セクションを参照）。
6. 未対応 — 何も見つからない場合は、ファイルを未対応として扱い、ステップ 8 で報告します。

存在を確認していないパスは編集しないでください。候補パスが見つからない場合は、検索ステップに進んでください。

ステップ 6 に到達した場合、それは調査結果であり、行き詰まりではありません。未対応ファイルは、ドキュメントサイトに掲載先のない公開 API を意味します。これこそが、ステップ 8 で明らかにする対象です。

ファイルを除外して対応付けを解決してはいけません。

Step 5: ドキュメントに必要な内容を整理する

読者にとっての変更点を洗い出す

編集するページを開く前に、PR 全体を読みます。説明（Breaking Changes セクションがある場合はそれも含む）、追加されたすべての変更履歴フラグメント、差分を確認してください。そのうえで、読者にとっての変更点、つまりユーザーが新たに設定、呼び出し、確認、または異なる方法で操作できるようになった点を、自分用に書き出します。Breaking Changes セクションの各項目は、サブクラス化や内部機能の呼び出しをするコードだけに影響する場合を除き、1 項目ずつリストに加えます。ユーザーのコードや期待される動作が変わるため、そのセクションに記載されています。

各項目について、説明文ではなくソースコードから事実を記録します。

• コードで宣言されている名前、型、デフォルト値
• 使用可能な値、制限、必須の組み合わせ
• どのような場合に、何が例外を発生させるか
• 呼び出し元が気づく副作用：再接続、クリッピング、プロバイダーに渡される値、順序
• 非推奨または削除されたものがある場合、何に置き換わるか

記載しようとする影響をすべて、それを生じさせるコードを読んで検証してください。PR の説明、変更履歴、docstring は作者の意図を示しますが、実際に何が起きるかを示すのはコードです。両者が食い違う場合はコードに基づいて記述し、概要で触れられていないケースがないか、Breaking Changes セクションも確認してください。

docstring、コメント、PR の説明、変更履歴の項目は、事実の情報源であり、文章の情報源ではありません。これらはメンテナー向けに書かれており、読者に不要な根拠（「Early Access」、エラーコード、このコードがこのように動作する理由など）が含まれています。ページ独自の言葉で、事実を読者向けに言い換えてください。

ドキュメントに記載する内容がないと判断する前に、既存のドキュメントを確認してください。 対応するページで、差分が影響する動作を検索し、各記述を変更後のコードと照らし合わせます。変更によって誤りになった記述は、コード変更が docstring やコメントだけの場合でも、リストに加えます。ドキュメントには以前の docstring の表現がそのまま使われていることが多く、今では誤った内容になっている場合があります。

リストが空のままであれば、この変更についてドキュメントの更新は不要です。 よくある例は、内部リファクタリング、ドキュメントに記載された動作を復元する修正、ログテキストの変更です。理由を記録し（自動化の NOOP 行）、終了します。ファイルが変更されたからといって、何かを書く必要はありません。

各ソースとドキュメントのペアを分析する

マッピングされた各ペアについて、次の手順を実行します。

1. ソースファイル全体を読み、現在の状態を把握します
2. そのファイルの差分を読みます：git diff main..HEAD -- <source_file>
3. 現在のドキュメントページ全体を読みます

Step 5 のリストにある各項目について、そのページのどこですでに説明されているかを確認します。該当する場合は、プロファイルの Section vocabulary に、このリポジトリのページで使われているセクションと、それぞれの構成要素が記載されています。該当する各セクションを確認します。

• コンストラクター／イニシャライザーのパラメーター：シグネチャと Configuration セクションの <ParamField> エントリーを比較します
• オプションまたは設定オブジェクト：宣言されたフィールドと、それらを記載したページの表を比較します
• イベントハンドラー：登録されたイベントとハンドラーのシグネチャを Event Handlers セクションと比較します
• クラス名／インポート：Usage の例で正しい名前が参照されているか確認します
• 動作の変更：ページ上の記述に誤りが生じていないか確認します
• コマンドラインの仕様（リポジトリに含まれる場合）：フラグ、引数、デフォルト値、終了時の動作をコマンドリファレンスと比較します

Step 6: 対象を絞って編集する

Step 5 のリストの各項目は、読者が探す場所に、ページの既存の形式で記載します。STYLE.md の「Changing Existing Pages」表に、各種編集で想定される変更量が示されています。新しいパラメーターは1つのエントリーとして追加し、Note も例も概要の変更も不要です。

ルール

• 変更によって誤りまたは不完全になる行だけを編集します。 周辺の文や箇条書きを言い換えたり、簡潔にしたり、まとめたりしないでください。変更に関係しない文章の言い換えが、誤りや事実の欠落につながります。
• 追加したエントリーと矛盾する行、または重複する行は、誤りになったものとみなします。 エントリーを追加または変更したら、同じ内容についての記述がページ内のほかの場所にないか確認します。単にエントリーを繰り返すだけの記述は削除し、矛盾する記述は修正します（どちらが正しいかコードで確認してください）。
• 各事実は一度だけ記載します。 文を追加する前に、その事実がページ内にすでに記載されていないか検索します。すでに記載されている場合は、新たに追加するのではなく、その箇所を更新します。Note で <ParamField> や表の行を繰り返してはいけません。
• 変更によって誤りになったものはすべて修正します。例やレシピも含みます。変更前は正しかったとしても、動作しなくなった例、非推奨のパラメーターを使っている例、新しい動作と矛盾する例は更新します。
• 対応するソースが削除された場合、または変更によって誤りになった場合を除き、コンテンツを削除しないでください。
• 既存の書式に合わせます。ページで <ParamField> タグを使っている場合はそれを使い、表を使っている場合は表を使います。
• 削除された機能を参照している場合を除き、CardGroup、リンク、例はそのままにします。
• クラス名が変更された場合を除き、フロントマターには手を加えないでください。
• 変更の対象となる未記載の仕様：これまでドキュメント化されていなかったパブリック API に変更が加えられた場合は、簡潔に記載します。新しい説明セクションは作らず、エントリー自体を追加してください。

非推奨化

ソースで非推奨と示されている場合（DeprecationWarning、@deprecated デコレーター、docstring の注記、または削除バージョンなど）は、ドキュメントのエントリーにもその旨を記載します。形式は STYLE.md の指示に従い、別の場所に注記を追加するのではなく、エントリー自体に記載してください。

• ソースに置き換え先と削除バージョンが記載されている場合は、それらも記載します
• ソースにまだ存在する非推奨項目を削除してはいけません
• 非推奨 API のドキュメントエントリーがなく、その API を扱うページに移行表または移行セクションがある場合は、そこに行を追加します。それ以外の場合は Step 8 で報告します。

ステップ 7：変更によってほかに誤った内容がないか確認する

対応付けられたページ以外にも、変更によって内容が誤っているページがある可能性があります。DOCS_PATH（プロファイルのガイドディレクトリと api-reference/）を検索し、次の項目をそれぞれ確認します。

1. 変更された名前：差分にあるクラス名、名前が変更されたパラメーター、変更されたインポートを確認します。誤りになった参照をすべて更新します。
2. 新しいクラスの同系列クラス。変更によってクラス群（新しい分類器、サービス、トランスポート、シリアライザーなど）にクラスが追加された場合、同系列クラスを列挙しているページを探します。同系列のクラス名を2、3個まとめて grep し、対応サービスの表、比較表、機能一覧、件数（「分類器が2つ」など）を確認します。それぞれのリスト独自の形式で新しいクラスを追加します。比較表なら列または行を追加し、横に文章を付け加えるのではありません。また、件数は、それが数えている表やリストと併せて更新します。
3. 変更された動作を使うレシピ。動作が変わった場合、影響を受けるクラス、イベント、パラメーターを DOCS_PATH 全体で grep します。見つかったスニペットや手順ごとに、新しい動作のもとで何が起きるかを順を追って確認します。何が実行され、何が発生し、ユーザーに何が聞こえるかを確認します。その結果が誤り、重複、または冗長になっている場合（たとえば、フレームワークがデフォルトで行う処理をスニペットが手動で行っている場合）は、スニペットを修正します。
4. 廃止予定項目の行を追加すべき移行表。

変更されたコードを参照するガイドは、それぞれ全文を読み、変更された具体的な参照箇所を修正します。本文の書き換えは行いません。対象に触れていても、変更された API を使っていないガイドは変更しません。

ステップ 8：ドキュメントの不足を特定する

対応付けられたすべてのペアを処理した後、次の2種類の不足がないか確認します。

不足しているページ：パターン、標準外の表、検索を試してもドキュメントページが見つからず、スキップリストにもないソースファイルです。それぞれについて、次の項目を報告します。

• ソースファイルのパス
• 定義されている主なクラスまたはエクスポートされたシンボル
• 新しいドキュメントページを作成すべきかどうか

不足しているセクション：ソースコードから必要と判断できるセクションがない、対応付けられたドキュメントページです。たとえば、コンストラクターのパラメーターを取る型なのに「設定」セクションがないページや、ソースコードで設定クラスが宣言されているのにオプション表がないページです。該当箇所を指摘し、追加を提案します。

新しいページを作成する場合は、プロファイルの新しいページセクションに従います。このセクションには、ページテンプレート、作成先のパス、このリポジトリで必要な登録手順（ナビゲーション、およびインデックスやサポートマトリックスページ）がすべて記載されています。すべて実施してください。ページが存在していても登録されていなければ、見つけられません。ページ構成は STYLE.md に従い、フロントマターはドキュメントリポジトリの CLAUDE.md に従います。

フロントマターの規約

新しいページの title と description は、llms.txt のエントリおよび AI ツールでの引用ラベルになります。また、ドキュメントリポジトリのメタデータリンターで検証されます。

• title：50文字以内にし、末尾に - Pipecat を付けません（Mintlify が追加します）。タイトルが30文字を超える場合は、sidebarTitle を追加します。
• description：110～140文字とし、そのページで説明するクラス名と、該当する場合はモダリティの略称（STT/TTS/LLM/VAD）を含めます。サイト全体で一意である必要があります。有効なアンファールタイトル（og:title があればその値、なければ title）も同様です。別のページですでに同じ短いタイトルが使われている場合は、og:title を追加します。

編集したページをすべて確認する

最後に、編集した各ページを、差分を見ていない読者のつもりで最初から最後まで読み直します。

• Step 5 のリストの各項目が、適切な場所に一度ずつ記載されている
• ページ内で同じ事実が重複していない（概要、機能一覧、Notes、Usage のコメントと各項目を照合する）
• 変更を説明したり、メンテナー側の理由を述べたりする文がない
• すべての例が現在の API で実行できる。廃止されたパラメーターや未定義の名前がない
• 本文中の件数やリストが、それらを説明する表と一致している
• 差分に、意図した編集だけが含まれている。DOCS_PATH で git diff を実行する

続いて、プロファイルの Checks セクションにコマンドがあれば、各コマンドを実行します。編集したページで見つかった指摘は、原因を問わずすべて修正します。ドキュメントリポジトリの CI は PR で変更されたすべてのページに同じチェックを実行し、指摘があると PR が失敗するため、これは Step 6 の「変更対象外の行を編集しない」というルールに優先します。それぞれの指摘を、そのページの形式と STYLE.md に従って修正します（Python の構文では型を記述します）。編集していないページでの指摘は、この変更によって発生した場合（差分で追加した設定や変更したデフォルト値など）に限り修正します。それ以外はそのままにし、未解決事項として列挙します。

続行する前に、失敗した項目をすべて修正します。

Step 9: フォーマットして llms.txt を再生成する

ドキュメントリポジトリでは、各ページのフロントマターを基にナビゲーション順に構築したインデックス llms.txt と、すべてのページの本文を含む llms-full.txt が管理されています。どちらかが古いとメタデータのリンターが失敗するため、ページの編集後、docs.json のナビゲーション変更後、または新しいページの追加後に再生成します。

Prettier は MDX を整形し、llms-full.txt にはページ本文がそのまま埋め込まれます。そのため、生成前にフォーマットを確定させる必要があります。

cd DOCS_PATH
npx prettier --ignore-unknown --write <edited files>
node scripts/gen-llms-txt.mjs

ドキュメントの編集内容と、再生成した llms.txt および llms-full.txt をまとめてコミットします。フォーマット前に生成すると、ファイルが古いままになります。生成後にページをフォーマットするリポジトリの pre-commit フックに任せる場合も同様です。

node scripts/docs-meta-lint.mjs を実行すると、CI と同じ古さおよびフロントマターに関する指摘が報告されます。

Step 10: 出力の要約

すべての編集が完了したら、要約を出力します。

## Documentation Updates

### Updated reference pages
- `<page path>` — what changed, and in which section

### Updated guides
- `<guide path>` — what changed

### New pages
- `<page path>` — created, plus every place it was registered

### Unmapped source files
- `<source path>` — ClassName (no doc page exists)

### Skipped files
- `<source path>` — why

ガイドライン

ページの文体は STYLE.md に従います。STYLE.md がない場合は、少なくとも次のルールに従います。

• 差分ではなく、将来の読者に向けて書く — ドキュメントでは、現在の API を説明します。変更そのものを語ってはいけません。「新たに追加」「これは置き換える」「最近変更された」といった表現や、以前の動作への言及は避けます。
• 理由や内部事情は書かない — 読者が自分のコードで考慮する必要がない限り、コードがそのように動作する理由や内部での仕組みは省きます。
• 補足は、読者が誤解する可能性がある場合に限る — 既存の文に収まる情報は、その文に含めます。
• コードと説明文の内容を一致させる — ページでパラメーター、クラス、識別子に言及するときは、説明文でもソースや <ParamField>／表の項目と同じ表記を使います。
• 技術用語はインラインコードにする — パラメーター名、クラス名、ファイル名、環境変数、設定キーはバッククォートで囲みます。
• 簡潔な文章にする — 埋め草、仮の文章、アシスタントのメタ発言は使いません。このスキルは CI で無人実行されるため、後続処理でこうした内容が検出されることはありません。

手順：

• 編集前に読む — 既存の構成を把握するため、変更を加える前に必ずドキュメントページ全体を読みます。
• 一度に扱う PR は一つ — このスキルは、現在のブランチと main の差分を対象とします。他のブランチは確認しません。
• 共有ソースファイル — 基底クラスや共有モジュールは、それらをインポートするすべてのものに影響します。その利用箇所に関連するページを確認し、すべて更新します。

チェックリスト

完了前に、次の項目を確認します。

• プロファイルとSTYLE.mdを読みました
• 読者向けの変更点をまとめたStep 5のリストを作成し、コードと照合して事実を確認しました。リストが空の場合は、NOOPとして作業を終了しました
• リストの各項目を、ページの既存の形式に従って一度ずつ記載しました
• 変更によって誤りまたは不完全な内容になっていない行は編集していません
• 非推奨項目に印を付け、移行テーブルに行を追加しました
• 変更の影響を受ける関連リスト、レシピ、ガイドを検索しました（Step 7）
• 編集したすべてのページが、プロファイルのChecksを含め、Step 8の最後にあるレビューに合格しました
• 新しいページを、プロファイルで求められているすべての場所に登録しました
• 編集したページをフォーマットし、llms.txtとllms-full.txtを再生成してコミットしました
• マッピングされていないファイルを報告しました