update-packages

パッケージの更新

操作モード

更新コマンドを実行する前に、操作モードを特定してください。

• 分析、報告、変更案の提示のみを行う場合は、アドバイザリーモードを使用してください。ブランチは作成しないでください。
• バージョン変更を適用する場合は、実行モードを使用してください。最初のパッケージ編集の前に、新しい更新ブランチを作成してください。

参照資料

実行時は、以下の参照資料を使用してください。

• references/package-groups.md — まとめて更新する必要があるパッケージグループ
• references/feature-adoption-tiers.md — T0～T3 の採用基準
• references/report-formats.md — リリースレポートと「新機能」の出力形式
• references/testing-matrix.md — 更新の種類ごとに必要なテスト
• references/runtime-checklists.md — Bun と Playwright のチェックリスト。Effect またはコンパイラーを更新する場合は Effect Updates セクションを、SDK をアップグレードする場合は SDK Updates セクションを読んでください。

ステップ 0：セッションの準備（実行モードのみ）

パッケージに触れる前に、スキルを更新して専用ブランチを作成してください。

# Update all skills from skills-lock.json (reads sources + skill names from lock)
bun run .agents/skills/update-packages/references/skills-update-local.ts

# Dry run to see what would be executed
bun run .agents/skills/update-packages/references/skills-update-local.ts --dry-run

# Create a fresh branch
git checkout -b chore/update-packages-$(date +%y%m%d-%H%M)

以下のルールを適用してください。

• 最初にスキルを更新してください。
• 実行作業用に新しい更新ブランチを作成してください。
• 以前の更新ブランチは再利用しないでください。
• 更新コミットはすべて実行ブランチに記録してください。

更新戦略

パッケージグループごとの作業フロー

references/package-groups.md を読んでください。次のグループに進む前に、各グループについてステップ 1～4 を実行してください。

ステップ 1 — バージョンとリリースノートの特定

次の 3 つのレポートをすべて実行してください。

bun run .agents/skills/update-packages/references/check-outdated.ts
bun run .agents/skills/update-packages/references/check-outdated.ts --changelog
bun run .agents/skills/update-packages/references/report.ts --json

生成された JSON ファイルをセッションデータとして使用してください。

スクリプトのフラグ	保存先
--json	.agents/skills/update-packages/references/outdated.json
--changelog	.agents/skills/update-packages/references/outdated-changelog.json
report.ts --json	.agents/skills/update-packages/references/runtime-report.json

古いレポートファイルは分析前に処理してください。

• セッション開始時に 3 つのレポートをすべて再生成してください。
• 以前の実行またはブランチのデータが含まれている場合は、古いレポートファイルを先に削除してください。
• 保存された JSON ファイルは破棄可能なローカル生成物として扱ってください。コミットしないでください。

カタログパッケージは一か所で処理してください。

• ルートの package.json にある catalog と catalogs から、カタログのバージョンを確認してください。
• 必要に応じて、最新バージョンを手動で確認してください（npm view <package> version）。
• bunfig.toml に定められたリポジトリの Bun インストールポリシー、特に minimumReleaseAge と関連する除外設定を遵守してください。
• ユーザーが明示的に上書きを依頼しない限り、bun install --minimum-release-age 0 のようなフラグで Bun の公開後経過時間の制限を回避しないでください。
• パッケージグループ全体について、minimumReleaseAge を満たす最新の互換バージョンを選択してください。要求されたバージョンがブロックされるようであれば、拒否を記録する前に bun install <package>@<version> --dry-run --no-save で再現し、その後、条件を満たす最新バージョンを使用してください。
• カタログエントリを手動で更新してから、通常の bun install を実行してください。

ステップ 2 — 機能の更新と採用を並行して実施

トラック A：更新を適用する	トラック B：リリースノートの機能を採用する
bun upgrade またはカタログの編集でバージョンを引き上げます	outdated-changelog.json を読み込みます。各エントリーには、リリースノート全文を含む releases[] があります
カタログを変更した場合は bun install を実行します（bunfig.toml の minimum-release-age ポリシーに従います）	各新機能をティアに分類します（references/feature-adoption-tiers.md を参照）
	T0/T1：設定レベルの変更（configFiles[] 内の対象ファイル）を実装し、bun run check で検証します
	T2：具体的な差分を生成して、レポートに含めます
	変更・非推奨・新規 API の使用箇所をコードベース内で検索します

SDK をアップグレードする場合は、references/runtime-checklists.md の SDK 更新チェックリストに従ってください。

可能な場合は、リリースノートの調査をサブエージェント／ライブラリアンに委任してください。委任できない場合は、同じ基準を用いて、メインエージェントでパッケージグループを順番に処理してください。

references/feature-adoption-tiers.md の T0～T3 の基準を適用してください。

ステップ 3 — 確認と修正

references/testing-matrix.md に記載された必須テストを実行します。 最低限、bun run check を実行してください。 outdated-changelog.json のリリースノートの内容を参考にして、失敗を修正してください。

ステップ 4 — グループをコミットする

バージョンの引き上げと機能の採用は、別々にコミットしてください。

• chore: update <package> to vX.Y.Z — バージョンの引き上げのみ
• feat: adopt <package> vX.Y improvements (<feature list>) — 新機能に伴う設定／コードの変更

更新中に見つかった動作上またはセキュリティ上の修正は、依存関係の引き上げとは別の PR にしてください。

内部ライブラリのリリース

ピア依存関係は、互換性のあるファミリーバージョンに正確に固定してください。ピア依存関係の範囲をプレリリースから始めないでください。リリース前に、サポート対象の各ファミリーバージョンと各パッケージマネージャーについて、クリーンなコンシューマーにライブラリをインストールし、ロックファイルに各ファミリーパッケージが 1 つずつ含まれていることを検証してください。

リリースノートレポート

references/report-formats.md を使用して、リリースレポートを生成してください。 サブエージェントを使用する場合は、それぞれに変更・非推奨・新規 API の使用箇所を検索するよう指示してください。 順番に処理する場合は、同じ検索を直接実行してください。

新機能の概要

references/report-formats.md を使用して、「新機能」概要を生成してください。 主な情報源として outdated-changelog.json を使用してください。 不足しているリリースノートがある場合に限り、ライブラリアンを使って取得してください。

特殊なケース

references/runtime-checklists.md の Bun および Playwright のチェックリストを適用してください。Effect またはコンパイラーを更新する場合は、同ファイルの Effect Updates セクションに従ってください。SDK をアップグレードする場合は、同ファイルの SDK Updates セクションに従ってください。

デプロイ後、各プロジェクトと環境で新しい問題がないか Sentry を確認してください。/ と liveness ルートにリクエストを送り、liveness の応答が成功しただけではサーバーレンダリングを検証したことにはなりません。

テスト要件

必須テストの選択には references/testing-matrix.md を使用してください。

ガードレール

• workspace:* のパッケージは更新しないでください。
• @typescript/native-preview の更新を省略しないでください。
• bun outdated は使用せず、check-outdated.ts を使用してください。
• ユーザーから明示的な依頼がない限り、Bun の minimumReleaseAge ポリシーを回避しないでください。
• minimumReleaseAge が原因で bun install が失敗した場合は、要求されたパッケージのバージョンをポリシーに準拠する最新のリリースに引き下げ、通常の bun install を再試行してください。
• インストールに失敗した場合は、bun clean:packages を実行してから bun install を実行してください。

完了の定義

• check-outdated.ts に、未対応の直接依存関係の更新が残っていないことを確認します。
• bun run check が成功することを確認します。
• references/testing-matrix.md で必要とされているすべてのテストが成功することを確認します。