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

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

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

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


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

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

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

  1. pyproject.toml の youtube-channels-automation の参照を確認
     - tag pin（tag = "vX.Y.Z"）の場合は tag を "v5.5.1" に書き換え
     - main 追従（branch = "main" または無印）の場合は書き換え不要
  2. uv lock --upgrade-package youtube-channels-automation を実行
  3. uv run yt-skills diff で local fix の有無を確認
     - 差分が出たら内容を私に見せて、upstream 版で上書きしてよいか確認してから次へ
     - 特に community-post / community-draft を以前から手書きで使っていた場合、上流の汎用版と衝突する可能性あり（後述）
  4. uv run yt-skills sync で .claude/skills/ を同期
     - 新スキル /onboard, /release-notes, /community-post, /community-draft, /short, /short-thumbnail, /short-release が配布される
  5. 追従後の動作確認:
     - uv run yt-doctor --json
     - uv run yt-channel-status
     - uv run yt-doctor（v5.5.1 で新規追加。GCP / OAuth まわりの状態診断）
     注: 上記コマンドはすべて v5.5.1 に確実に存在します。command not found / No module named が出ても「ガイドが古い」「コマンドが無い」と判断せず、env 側を疑って uv sync → uv pip list | grep youtube-channels-automation の順で切り分けてください（詳細はガイド本体の Q4 参照）。
  6. .env の GOOGLE_CLOUD_PROJECT 行は v5.5.1 から不要（任意フォールバックに格下げ）。
     gcloud auth application-default login と gcloud config set project が済んでいれば消して OK。
     消さなくても従来通り上書きとして機能するので、急いで対応する必要はありません。
  7. 変更を以下のメッセージでコミットして push:
     chore: youtube-automation v5.5.1 への追従
     git add 対象は pyproject.toml uv.lock .claude/skills/

  詳細仕様は https://github.com/daiki-beppu/youtube-automation/blob/main/docs/upgrades/v5.5.1.md を参照。
  既知の注意点として、過去に .claude/skills/community-post/ や .claude/skills/community-draft/ を手書きで配置していた場合（deepfocus365 / rjn 向け TTP 元実装）、v5.5.1 で汎用版が upstream に取り込まれたため衝突します。私の確認なしに上書きせず、必ず Step 3 で diff を見せてください。


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

- 新しくできるようになったこと:
  /onboard で GCP / OAuth セットアップを AI ウィザード化、/community-post と /community-draft でコミュニティ投稿を自動下書き、/short / /short-thumbnail / /short-release でショート動画制作が復活

- 既存機能が良くなったこと:
  /masterup にタイムスタンプ整合チェックを統合、/video-description に説明欄の一括更新モードを追加、preflight の chapter_max が設定で上書き可能に、yt-skills sync の挙動メッセージが親切に

- 直った不具合:
  GOOGLE_CLOUD_PROJECT 環境変数が必須だった問題を解消（ADC から自動解決）、broken symlink で wheel ビルドが失敗していた問題を修正

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

- local fix がある場合の追加対応:
  過去に .claude/skills/community-post/ や .claude/skills/community-draft/ を手書きで配置していた場合、v5.5.1 で同等の汎用版が upstream に取り込まれたため衝突します。汎用版は config 駆動で各チャンネル固有値を吸収できるよう設計されているので、上書きしたうえで config 側を見直すのが推奨パスです


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

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

1. /onboard — GCP / OAuth セットアップを AI ウィザード化

これまで「鬼門」だった API 設定（gcloud / ADC / OAuth Client ID）を、/onboard 1 本で AI に丸投げできるようになりました。yt-doctor で現状を診断し、AI が次の 1 アクションだけを案内してくれます。新規チャンネル立ち上げ、別 PC への引っ越し、ADC 切れ、client_secrets.json の作り直し、すべて同じ入口です。

- 嬉しいこと: 「セットアップ」「API 設定して」「環境構築」など自然な言い方で発動。AI が叩けるコマンドは AI が直接実行し、人間が押すべきステップ（gcloud auth login など）だけ明示的に止まる
- 注意点: 中央集権 OAuth client はスコープ外。各運営者が自分の GCP プロジェクト + 自分の OAuth client を持つ前提は従来通り

関連: PR #334 / 新規 CLI yt-doctor


2. /community-post — コミュニティ投稿を自動下書き（テンプレ運用）

deepfocus365 で運用していた「動画 1 本 = 投稿 1 本、完全固定テンプレ」のコミュニティ投稿フローを汎用化。動画公開後に呼び出すと、テンプレを展開して pbcopy で本文をコピーし、YouTube Studio を起動するところまで自動化します。

- 嬉しいこと: 「コミュニティ投稿」「community post」で発動。完全テンプレ運用なので運用コストはほぼゼロ、ブランドボイスを全投稿に反復刷り込みできる
- 注意点: YouTube Data API にコミュニティ投稿作成 API は存在しないため、動画添付と投稿ボタンは手動。macOS 専用（pbcopy / open）

関連: PR (#237 ベース) / config 例 examples/channel_config.example/community.example.json


3. /community-draft — 当日リマインダー・週次フィードバック等のテンプレ集

rjn で実装した「当日告知」「週次フィードバック」「視聴者投票」などのコミュニティ投稿テンプレを、--type で切り替えて使える汎用スキル。本文を生成して pbcopy するところまで。

- 嬉しいこと: 「day-of reminder」「sunday vote」「weekly feedback」など語彙で発動。テンプレを切り替えるだけで複数の投稿パターンを使い分けられる
- 注意点: rjn 固有要素（雨題材 5 軸 / 装飾フォント / EDT 時刻表記など）は汎用化済み。config で audience_persona, primary_timezone, theme_axis_pool 等を指定可能

関連: PR (#309 ベース) / examples/community-draft-rjn/ に rjn 実装の参考例を収録


4. /short, /short-thumbnail, /short-release — ショート動画制作スキルが復活

v4.0.0 で撤去されていた Shorts 関連スキル群を v5 規約でゼロベース再実装し復活させました。collection 型チャンネル（BGM テイスター）向けの /short と /short-thumbnail、release 型チャンネル（楽曲リリース）向けの /short-release の 2 系統。

- 嬉しいこと: BGM テイスター用 9:16 ショート 3 本 / リリース型 JP+EN 各 1 本などの制作が一気通貫で回せる。config/channel/shorts.json で投稿可否・公開時刻・収益化設定を集約
- 注意点: 新スキルなので既存運用への影響なし。使う場合は config/channel/shorts.json を先に整備

関連: PR (#287 ベース) / 新 config config/channel/shorts.json


5. /release-notes — 運営者向けアップグレードガイドの自動生成

このページ自体を生成しているスキル。non-trivial リリース後に tag + GitHub Release が揃った状態で発動すると、運営者向けガイド + CHANGELOG 昇格 + 下流影響分析 + 追従 issue 起票までを一気通貫で実施します。

- 嬉しいこと: 開発側から見たメリット。リリースごとに毎回手書きしていた運営者向けノートが自動化された
- 注意点: 各運営者の操作には直接影響しない（このスキルは upstream リリース時にのみ発動）

関連: PR #333 (Closes #253)


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

6. /masterup — タイムスタンプ整合チェックを統合

マスター音源生成後に yt-fix-timestamps を自動実行し、テーマ別タイムスタンプ（chapters）の不整合を後処理で修正するステップが /masterup スキルに組み込まれました。修正が不要な場合は no-op で素通りします。

- 嬉しいこと: マスター生成 → タイムスタンプ整合 → 修正の流れが 1 スキルで完結。手動で yt-fix-timestamps を別途叩く必要がなくなる
- 注意点: CLI 単体実行は引き続き可能

関連: PR (#249 ベース)


7. /video-description — 説明欄の一括更新モードを追加

これまで yt-bulk-update-desc CLI を直接叩く必要があった「ローカル descriptions.md から YouTube 上の動画説明欄を一括反映」の機能が、/video-description スキル内から呼び出せるようになりました。dry-run プレビュー → 確認 → 反映の 2 段階運用で安全。

- 嬉しいこと: 「説明欄一括更新」「タグ修正反映」などで発動。生成（既存）と反映（新規）が同じ入口に統一された
- 注意点: CLI 単体実行は引き続き可能（CI 用途想定）

関連: PR (#247 ベース)


8. preflight — chapter_max を設定で上書き可能に

これまで preflight チェックで「タイムスタンプ 12 個超は一律エラー」だった上限が、config 設定（例: 14 トラックのコレクションを per-track chapter として運用したい場合）で上書き可能になりました。デフォルトは引き続き 12 なので、設定をいじらない限り挙動は変わりません。

- 嬉しいこと: per-track 命名運用（14〜28 chapters 等）が意図的に必要なチャンネルでアップロード可能になる
- 注意点: 既定値は据え置きなので、12 chapter 以下で運用しているチャンネルには影響なし

関連: PR #421


9. yt-skills diff — 出力に --prune の案内を表示

yt-skills diff で「target 側にのみ存在するスキルがある」場合に、yt-skills sync --prune オプションを使えば自動削除できる旨を案内するようになりました。

- 嬉しいこと: rename / 撤去された旧スキルの残骸を手動 rm -rf する事故を防げる
- 注意点: --prune は upstream に存在しないスキルディレクトリを削除する破壊的操作。実行前に diff で内容を確認

関連: PR (#328 ベース)


── 直った不具合 ──

10. GOOGLE_CLOUD_PROJECT が必須だった問題を解消

これまで Vertex AI 系（Gemini / Lyria / 画像生成）の呼び出しに GOOGLE_CLOUD_PROJECT 環境変数が必須でしたが、v5.5.1 から ADC（gcloud auth application-default login）の project_id を自動解決します。env 設定が 1 ステップ減りました。

Before（v5.5.0 以前）:
  .env に GOOGLE_CLOUD_PROJECT を必ず書く必要があった

After（v5.5.1）:
  .env から削除して OK。設定があれば従来通り上書きとして機能（任意フォールバック）

- 嬉しいこと: 新規チャンネル / 別 PC 引っ越し時のセットアップが 1 ステップ短縮
- 注意点: .env から行を消すかどうかは任意。残しても問題ない

関連: PR (#280 ベース)


11. /short と /short-thumbnail の broken symlink を修正

v5.5.1 系で wheel ビルドが失敗するケース（uv run yt-skills list 等）の原因だった broken symlink を実体ファイルで復元しました。

- 嬉しいこと: yt-skills 系コマンドが壊れていた状態が解消
- 注意点: 既に v5.5.0 系で運用していたチャンネルでも、v5.5.1 への bump 時に自動的に解消される

関連: PR (#345 ベース)


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

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

- skills_sync CLI を 443 行 1 ファイルから 5 サブモジュール構成にリファクタ（外部 CLI 仕様は不変）
- スキル運用リスク監査レポート / スキル汎用化整合性監査レポートを docs/audits/ に追加
- 各種テストの追加・整形（pytest collection error 解消、ruff format 適用）

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


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

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

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

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

やること:
- tag を v5.5.1 に書き換え
- 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.1 相当）を取り込み
- uv run yt-skills sync で .claude/skills/ を同期
- 過去に local fix を入れていれば衝突解消（次セクション参照）


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

過去に .claude/skills/community-post/ や .claude/skills/community-draft/ を手書きで配置していた場合（deepfocus365 / rjn の TTP 元実装）、v5.5.1 で汎用版が upstream に取り込まれたため衝突します。

upstream 汎用版は config 駆動（community.json / 各種テンプレ config）で各チャンネル固有値を吸収できるよう設計されているため、原則として upstream 版で上書きしたうえで、チャンネル固有値は config/channel/community.json 等に集約するのが推奨パスです。

uv run yt-skills diff で差分を確認し、上書きしてよいか判断してください。固有テンプレを残したい場合は手動マージを検討。

masterup / video-description / channel-setup / analytics / video-analyze などの既存 skill も v5.5.0 → v5.5.1 で更新されています。手書き編集している場合は同様に diff で確認してください。


■ 実行手順

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

  cd <your-channel-repo>

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

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

  # 3. .claude/skills/ を新バージョンで同期
  #    新規 /onboard, /release-notes, /community-post, /community-draft, /short, /short-thumbnail, /short-release を含む全スキルが配布される
  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.1 への追従"
  git push


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

  cd <your-channel-repo>

  # 1. uv lock 更新で main の最新（= v5.5.1 相当）を取り込み
  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.1 への追従と local fix 統一"
  git push


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

以下のコマンドはすべて v5.5.1 のリリース時点で entry point として登録済みです（uv run yt-channel-status / uv run yt-doctor / 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.1 が入っているか確認
  3. ダメなら uv cache clean && uv lock --upgrade-package youtube-channels-automation で再ロック

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

  # 設定ファイルを含む環境診断
  uv run yt-doctor --json

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

  # GCP / OAuth まわりの状態診断（v5.5.1 で新規追加）
  uv run yt-doctor

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

yt-doctor で WARNING や FAILED が出る場合は、/onboard を起動して指示に従ってください。


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

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.1 にしたあと uv lock で「依存解決失敗」
A.  キャッシュが古い可能性。uv cache clean してから uv lock --upgrade-package youtube-channels-automation を再試行。

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

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

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

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

Q6. Vertex AI 系（Gemini / Lyria / 画像生成）で「project が見つからない」エラー
A.  v5.5.1 から GOOGLE_CLOUD_PROJECT は ADC からの自動解決にフォールバックします。env 設定を消した場合は以下を確認:

      gcloud config set project <your-project-id>
      gcloud auth application-default login

    が完了していれば動きます。env を残していれば従来通り上書きとして機能します。

Q7. /community-post や /community-draft を以前から手書きで使っていた
A.  v5.5.1 で upstream に汎用版が取り込まれました。yt-skills diff で衝突を確認し、可能なら upstream 版で上書きして config 側にチャンネル固有値を寄せるのが推奨パスです。


■ 最終チェックリスト

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

  [ ] pyproject.toml の youtube-channels-automation 参照が v5.5.1 に更新済み（tag pin の場合）
  [ ] uv lock で uv.lock が更新済み
  [ ] uv run yt-skills sync 完了、.claude/skills/onboard/SKILL.md と community-post/SKILL.md が存在する
  [ ] uv run yt-skills diff で残差分なし（あるいは破棄判断済み）
  [ ] uv run yt-doctor --json の channel_config check が ok
  [ ] uv run yt-channel-status で自チャンネルが正常認識される
  [ ] uv run yt-doctor で WARNING / FAILED 無し（または /onboard で対処済み）
  [ ] コミット + push 完了


■ 関連リンク

- GitHub Release: https://github.com/daiki-beppu/youtube-automation/releases/tag/v5.5.1
- CHANGELOG.md (詳細実装): リポジトリの CHANGELOG.md の [v5.5.1] セクション
- 主要 PR / issue:
  - 新機能: #334 (/onboard + yt-doctor), #237 (/community-post), #309 (/community-draft), #287 (Shorts skill 復活), #333 (/release-notes), #247 (/video-description bulk-update)
  - 挙動変更: #249 (/masterup × yt-fix-timestamps), #421 (preflight chapter_max), #328 (yt-skills diff --prune 案内)
  - バグ修正: #280 (GOOGLE_CLOUD_PROJECT ADC fallback), #345 (broken symlink 修正), #335 (v5.5.0 ガイドの command not found ガード), #329 (pytest collection error)