v5.5.0 アップグレードガイド

v5.5.0 アップグレードガイド — チャンネル運営者向け
====================================================

このページは youtube-channels-automation を v5.5.0 へ追従させたいチャンネル運営者向けの平易なガイドです。エンジニア向けの詳細実装は CHANGELOG.md と各 PR を参照してください。

所要時間の目安: 5〜10 分（コマンド 3〜4 個実行するだけ）


■ AI にお任せする場合のプロンプト

以下をそのままチャンネルリポジトリの Claude Code に渡せば、v5.5.0 への追従を自動実行します。dry-run / 差分確認のステップで一度立ち止まるので、内容を確認してから承認してください。

  youtube-channels-automation を v5.5.0 に追従させてください。手順は以下:

  1. pyproject.toml の youtube-channels-automation の参照を確認
     - tag pin（tag = "vX.Y.Z"）の場合は tag を "v5.5.0" に書き換え
     - main 追従（branch = "main" または無印）の場合は書き換え不要
  2. uv lock --upgrade-package youtube-channels-automation を実行
  3. uv run yt-skills diff で local fix の有無を確認
     - 差分が出たら内容を私に見せて、upstream 版で上書きしてよいか確認してから次へ
  4. uv run yt-skills sync で .claude/skills/ を同期
     - 新スキル /playlist, /metadata-audit, /channel-setup が配布される
  5. 追従後の動作確認:
     - uv run yt-channel-status
     注: これらは v5.5.0 に確実に存在する CLI です。command not found / No module named が出ても「ガイドが古い」「コマンドが無い」と判断せず、env 側を疑って uv sync → uv pip list | grep youtube-channels-automation の順で切り分けてください（詳細はガイド本体の Q4 参照）。
  6. 変更を以下のメッセージでコミットして push:
     chore: youtube-automation v5.5.0 への追従
     git add 対象は pyproject.toml uv.lock .claude/skills/

  詳細仕様は https://github.com/daiki-beppu/youtube-automation/blob/main/docs/upgrades/v5.5.0.md を参照。
  既知の注意点として、過去に .claude/skills/masterup/SKILL.md や .claude/skills/wf-next/SKILL.md を手書き修正していた場合は v5.5.0 で同等の修正が upstream に取り込まれているため衝突します。私の確認なしに上書きせず、必ず Step 3 で diff を見せてください。


■ TL;DR（30 秒サマリー）

- 新しくできるようになったこと:
  /playlist でプレイリスト整理、/metadata-audit で説明欄ずれを自動検出、新規チャンネル立ち上げが 1 コマンドで完結（yt-channel-init）

- 既存機能が良くなったこと:
  /masterup がサムネ・設定ファイルも漏れなくメインへ同期、/wf-next がメインリポ側の master-mix も自動検出、/channel-setup が運用中の設定更新でも発動

- 直った不具合:
  チャンネル設定 push が 400 エラーで失敗していた問題が解消

- あなたがやること:
  pyproject.toml の tag を v5.5.0 に更新 → uv lock → uv run yt-skills sync の 3 コマンド（5 分以内）

- local fix がある場合の追加対応:
  過去に .claude/skills/masterup/SKILL.md や wf-next/SKILL.md を手書き編集していた場合、v5.5.0 で同等の修正が upstream に取り込まれたため衝突します。upstream 版で上書きしてください（同等仕様なので破棄して問題なし）


■ このバージョンで何が変わるか

── 新しくできるようになったこと ──

1. /playlist — プレイリスト整理を会話で実行

これまで yt-playlist-manager / yt-playlist-status の 2 つの CLI を直接叩いていたプレイリスト操作が、/playlist という 1 つの会話入口にまとまりました。

- 嬉しいこと: 「プレイリスト整理して」「動画追加して」など自然な日本語で操作できる。dry-run プレビュー → 確認 → 反映の 2 段階運用が安全
- 注意点: 設定は config/channel/playlists.json に書く。書き方は配布された /playlist スキル本体（.claude/skills/playlist/SKILL.md）を参照

関連: PR #245


2. /metadata-audit — YouTube 側の説明欄ずれを自動検知

ローカルの descriptions.md / workflow-state.json と、YouTube 上の動画メタデータが食い違っていないか自動で監査するスキル。手作業で 1 動画ずつ目視チェックする必要がなくなります。

- 嬉しいこと: 「説明欄ずれてない？」と聞くだけで collections/live/ 配下を一括スキャン
- 注意点: このスキルは検出のみ。修正は既存の /video-description が責務

関連: PR #244


3. yt-channel-init — 新規チャンネル立ち上げを 1 コマンドで

新しい YouTube チャンネル用リポジトリを作る際、最小設定 4 ファイル + 正準ディレクトリ構造を 1 コマンドで自動生成できるようになりました。これまでは /channel-new のステップ 4 で手作業 5〜10 分かかっていた工程が数十秒に短縮されます。

- 嬉しいこと: 新規チャンネル開設時の初期セットアップが大幅高速化
- 注意点: 既存チャンネルには影響なし。次回新規チャンネルを立ち上げるとき /channel-new の中で自動的に呼ばれる

関連: PR #318 (Closes #256)


4. /wf-new で多言語シーン辞書を自動生成

多言語対応チャンネル（localizations.json で複数言語が設定されているチャンネル）でコレクション制作を始めるとき、英語のシーン定義から全対応言語へ自動翻訳して workflow-state.json に書き込みます。

- 嬉しいこと: 多言語の scene_phrases を手書きする手間がなくなる
- 注意点: Gemini による自動翻訳なので、品質を念のため目視確認するのを推奨。日本語のみのチャンネルでは自動スキップ

関連: PR (Closes #246)


── 既存機能が良くなったこと ──

5. /masterup — サムネ・設定ファイルも漏れなくメインへ同期

worktree で /masterup を実行したあとに発生する「メインリポへのコピー処理（Step 6）」が rsync ベースに改善されました。これまでは 01-master/（マスター音源）と 02-Individual-music/（個別曲）の 2 つだけが対象で、サムネ画像（10-assets/main.png）、ループ動画（10-assets/loop.mp4）、プロンプト類（20-documentation/）、進捗ファイル（workflow-state.json）がメイン側に届かないというバグがありました。

Before（v5.4.0 以前）:
  01-master/ + 02-Individual-music/ のみメインへコピー（サムネや設定が取り残される）

After（v5.5.0）:
  コレクションディレクトリ全体を rsync で同期。将来ディレクトリが増えても自動追随

- 嬉しいこと: 手動で rsync -a を打って取り残された素材を回収する必要がなくなる
- 注意点: メインリポ側で先行生成した素材は --delete を付けないので保護される

関連: PR #324 (Closes #321)


6. /wf-next — メインリポ側の master-mix.m4a も自動検出

DAW（音楽編集ソフト）で書き出した最終マスター（master-mix.m4a / .wav など）を worktree ではなくメインリポ側の 01-master/ に置いていた場合、これまで /wf-next の音源承認ゲートで検出できず、誤って raw_master を採用してしまうケースがありました。v5.5.0 ではメインリポ側も自動スキャンし、見つかった master-mix を worktree 側へコピーしたうえで採用します。

Before: worktree 内 01-master/ のみ走査 → メイン側に置いた master-mix が認識されない
After:  worktree 検知時にメインリポ側も走査 → 見つかれば worktree へ自動コピーして採用

- 嬉しいこと: DAW 書き出し先がメインでも worktree でもどちらでも OK。短命な worktree が消えても素材を失わない
- 注意点: 採用前にユーザー承認のステップが入るので、誤検出はない

関連: PR #325 (Closes #323)


7. /channel-setup — 運用中の設定更新でも発動

これまで /channel-setup は「新規チャンネル開設時のセットアップ」専用でしたが、v5.5.0 から運用中チャンネルの設定変更（branding / status / localizations）の push でも自動的に呼び出されるようになりました。「設定反映して」「チャンネル設定更新」「branding push」などの言葉で発動します。

- 嬉しいこと: 運用中の設定変更フェーズが明確になり、初回セットアップ後も同じスキルを再利用できる
- 注意点: YouTube API の制約（branding は他 part と同時送信不可）は CLI 内部で自動対応。運営者が意識する必要はない

関連: PR (Closes #248)


8. /collection-ideate の鮮度判定が freshness_days 設定に統一

これまで /collection-ideate のドキュメント内に「3 日より古ければ更新」と固定値で書かれていた部分が、/benchmark の freshness_days（既定 3 日）参照に統一されました。

- 嬉しいこと: freshness_days を変えれば全スキルが一貫して追随。設定の一元管理
- 注意点: 既定値は引き続き 3 日なので、設定をいじらない限り挙動は変わらない

関連: PR #326 (Closes #322)


9. yt-channel-settings の push が API 制約に自動追随

チャンネル設定（説明文、キーワード、ローカライゼーション）を YouTube に push する際、YouTube Data API の制約により brandingSettings を他の part と同時に送信できない仕様が判明していました。v5.5.0 では brandingSettings / localizations / status を自動的に 3 回の API call に分割して送信します。

Before: 同時送信で 400 エラー（branding_settings cannot be used with other parts）が発生 → push 失敗
After:  分割送信で確実に反映される

- 嬉しいこと: 設定 push が確実に成功するようになり、信頼できる
- 注意点: これまで push に失敗していた運営者は uv run yt-channel-settings push --apply を再実行すれば成功する

関連: PR (Closes #230, #248)


── 直った不具合 ──

10. yt-channel-settings push --apply の 400 エラー

上記 9 番と同じ修正。config/channel/meta.json の description / keywords / made_for_kids を変更しても push できなかった問題が解消されました。

関連: Closes #230


── 内部改善（運営者影響なし、参考のみ）──

技術的なリファクタやテスト追加が多数行われましたが、運営者の操作には影響しません。代表的なもの:

- 内部処理の高速化（戦略分析が 7.7 倍高速に）
- コスト計算のハードコード単価を撤廃し GCP Cloud Console を一元ソースに
- OAuth ハンドラのリファクタ、ストリーミング系のヘルスチェック整備、ベンチマークハーネス追加

詳細は CHANGELOG.md の v5.5.0 セクションを参照してください。


■ あなたのチャンネルへの影響（参照形式別）

自分の pyproject.toml の youtube-channels-automation 行を確認して、該当するパターンの手順に進んでください。

── パターン A: tag pin（明示固定）──

  youtube-channels-automation = { git = "...", tag = "v5.4.0" }

やること:
- tag を v5.5.0 に書き換え
- uv lock で lockfile 更新
- uv run yt-skills sync で .claude/skills/ を同期


── パターン B: main 追従（tag 無し / branch = "main"）──

  youtube-channels-automation = { git = "..." }
  youtube-channels-automation = { git = "...", branch = "main" }

やること:
- uv lock で main の最新（v5.5.0 相当）を取り込み
- uv run yt-skills sync で .claude/skills/ を同期
- 過去に local fix を入れていれば衝突解消（次セクション参照）


── local fix がある場合の追加対応 ──

過去に .claude/skills/masterup/SKILL.md や .claude/skills/wf-next/SKILL.md を手書きで修正していた場合、v5.5.0 で同等の修正が upstream に取り込まれたため衝突します。

uv run yt-skills diff で差分を確認し、差分が出たら upstream 配布版で上書きしてください（upstream 版と local fix は同等仕様なので、破棄して問題ありません）。

local fix 自体に独自の意味がある場合のみ、手動マージを検討してください。


■ 実行手順

── パターン A: tag pin の場合 ──

  cd <your-channel-repo>

  # 1. pyproject.toml の tag 参照を更新
  #    例: tag = "v5.4.0" → "v5.5.0"
  #    手で書き換えるか、以下の sed を使う
  sed -i '' 's/tag = "v5.4.0"/tag = "v5.5.0"/' pyproject.toml

  # 2. uv lock を更新（upstream を v5.5.0 で固定）
  uv lock --upgrade-package youtube-channels-automation

  # 3. .claude/skills/ を新バージョンで同期
  #    新規 /playlist, /metadata-audit を含む全 32 skill が配布される
  uv run yt-skills sync

  # 4. （任意）local fix が無いか念のため確認
  uv run yt-skills diff

  # 5. コミット
  git add pyproject.toml uv.lock .claude/skills/
  git commit -m "chore: youtube-automation v5.5.0 への追従"
  git push


── パターン B: main 追従（+ local fix がある場合）──

  cd <your-channel-repo>

  # 1. uv lock 更新で main の最新（= v5.5.0 相当）を取り込み
  uv lock --upgrade-package youtube-channels-automation

  # 2. 配布前に local fix の差分を確認
  uv run yt-skills diff

  # 3. 差分が出たら upstream 版に揃える（local fix を破棄）
  uv run yt-skills sync

  # 4. コミット
  git add pyproject.toml uv.lock .claude/skills/
  git commit -m "chore: youtube-automation v5.5.0 への追従と local fix 統一"
  git push


■ 追従後に確認すべきこと

以下のコマンドはすべて v5.5.0 のリリース時点で entry point として登録済みです（uv run yt-channel-status / uv run yt-skills など）。command not found / No module named 相当が出た場合は「ガイドが古い」「コマンドが存在しない」と判断せず、env 側の問題として以下の順で切り分けてください（詳細は Q4 参照）:

  1. uv sync
  2. uv pip list | grep youtube-channels-automation で v5.5.0 が入っているか確認
  3. ダメなら uv cache clean && uv lock --upgrade-package youtube-channels-automation で再ロック

以下を順に実行して、すべて成功すれば v5.5.0 への追従は完了です。

  # YouTube API への認証 + チャンネル認識が通るか
  uv run yt-channel-status

  # 既存のコレクション一覧が壊れていないか
  uv run yt-skills list

上記コマンドで警告が出る場合は、pyproject.toml の tag を確認してから再度 uv lock を試してください。


■ トラブルシューティング

Q1. uv run yt-skills sync で「差分がある」と表示される
A.  ローカルで手動編集した skill ファイルが upstream 版と食い違っている状態です。uv run yt-skills diff で差分を見て、
    - 手動編集を残したい → 編集箇所を別 issue / commit で upstream に提案
    - 破棄して upstream に合わせる → uv run yt-skills sync --force（注意: 破棄は元に戻せないので事前に git diff で内容を確認）

Q2. yt-channel-settings push --apply で 401 / 403 エラー
A.  OAuth トークンが古いスコープのままです。auth/token.json を削除して再認証してください:

      rm auth/token.json
      uv run yt-channel-status  # 認証フロー再走

Q3. tag を v5.5.0 にしたあと uv lock で「依存解決失敗」
A.  キャッシュが古い可能性。uv cache clean してから uv lock --upgrade-package youtube-channels-automation を再試行。

Q4. uv run yt-channel-status / yt-skills 等で command not found / No module named ...
A.  これらは v5.5.0 に entry point として登録済みなので、ガイドの記載は誤りではありません（pyproject.toml の [project.scripts] に確実に存在）。env 側の不整合（uv sync 未実行 / 古い venv / cache）を疑って以下を順に試してください:

      uv sync
      uv pip list | grep youtube-channels-automation   # v5.5.0 が入っているか確認
      # ダメなら
      uv cache clean
      uv lock --upgrade-package youtube-channels-automation
      uv sync

    それでも解決しない場合は .venv ディレクトリを削除して uv sync で作り直してください。「コマンドが存在しないからガイドが間違っている」と判断して追従後確認をスキップしないこと。

Q5. .claude/skills/ に新スキル /playlist が見えない
A.  Claude Code のセッションキャッシュが古い可能性。Claude Code を再起動して .claude/skills/ を再スキャンしてください。それでも残る場合は ls .claude/skills/playlist/SKILL.md でファイル自体が存在するか確認。

Q6. /masterup を worktree で実行したあと、メインリポにサムネが届かない
A.  v5.5.0 で修正済みです。tag を v5.5.0 に上げて yt-skills sync 完了後、もう一度 /masterup を実行してください。


■ 最終チェックリスト

追従が完了したら以下にチェックを入れて、完了確認:

  [ ] pyproject.toml の youtube-channels-automation 参照が v5.5.0 に更新済み（tag pin の場合）
  [ ] uv lock で uv.lock が更新済み
  [ ] uv run yt-skills sync 完了、.claude/skills/playlist/SKILL.md と metadata-audit/SKILL.md が存在する
  [ ] uv run yt-skills diff で残差分なし（あるいは破棄判断済み）
  [ ] uv run yt-channel-status で自チャンネルが正常認識される
  [ ] コミット + push 完了


■ 関連リンク

- GitHub Release: https://github.com/daiki-beppu/youtube-automation/releases/tag/v5.5.0
- CHANGELOG.md (詳細実装): リポジトリの CHANGELOG.md の [v5.5.0] セクション
- 主要 PR:
  - 新機能: #245 (playlist), #244 (metadata-audit), #318 (yt-channel-init), #246 (wf-new i18n)
  - 挙動変更: #324 (masterup rsync), #325 (wf-next main repo), #248 (channel-setup push), #326 (collection-ideate freshness)
  - バグ修正: #230 (yt-channel-settings 400 エラー)