リリース手順 (release-agent)
scripts/release-agent.ts を使った version bump → コミット → push → PR → タグ → GitHub Release の自動化スクリプトです。
リリース作業はこのスクリプトに統一してください。手動での version bump やタグ付けは行いません。
2 段リリース構成
develop → staging → main の 2 段でリリースします。基準番号 (x.y.z) を決めるのは staging 段の 1 回だけで、本番（main）段では -rc を外して確定するだけです。これにより、staging で確認した版と本番に出る版の番号が一致し、二重 bump を防ぎます。
① develop → staging（プレリリース） 1.1.0 → 1.2.0-rc.1 （再実行で rc.2, rc.3 ...）
② staging → main（確定） 1.2.0-rc.2 → 1.2.0 （-rc を外すだけ。再 bump しない）
注意（本番環境について）: 現時点では本番 AWS 環境が未構築で、
staging環境で動作確認を行う運用です。② のstaging → main（本番リリース）コマンドは将来の本番デプロイ用に温存してあり、いずれ本番環境への配線が必要になります。
⚠️ release PR のマージ方法（最重要・必読）
release PR（develop → staging および staging → main）は絶対に squash マージしない。必ず「マージコミット」で取り込む。
# ✅ 正しい（マージコミット）
gh pr merge <PR番号> --merge
# ❌ 禁止（squash）
gh pr merge <PR番号> --squash # ← staging が develop と祖先を共有しなくなる
理由: squash マージは develop の多数コミットを 祖先関係を持たない単一の新コミットに潰して staging に乗せます。すると develop と staging の merge-base が前々回の分岐点まで巻き戻り、次回の release PR で「両ブランチが同じファイルを別々に変更した」と誤判定され、実体のない（phantom）コンフリクトが大量発生します（過去に rc.1 → rc.2 で発生）。
マージコミットなら staging が develop の履歴を親として共有するため、この phantom conflict は起きません。
機能 PR（
* → develop）は従来どおり squash でよい。この禁止ルールは release PR（base がstagingまたはmain）に限る。万一 squash してしまい phantom conflict が起きた場合の復旧: staging をリリース commit（タグ
vX.Y.Z-rc.Nが指す develop 上の commit）にgit push origin <commit>:staging --forceで fast-forward させ、祖先共有を回復する。staging 固有コミットは squash 由来で内容は develop に内包済みのためロスはないが、force-push 前に「staging に develop へ無い独自内容が無いこと」を必ず確認する。
TL;DR
# ── ① develop → staging（プレリリース）──
pnpm run release:stg:dry # 何が起きるか確認（書き込みなし）
pnpm run release:stg # 実行（patch 相当の rc）
# ── ② staging → main（本番確定）── ※ 本番環境構築後に使用
pnpm run release:dry # 確認
pnpm run release:patch # 実行（-rc を外して確定）
前提条件
- ルートで
pnpm install済み（tsxが必要） gh(GitHub CLI) がインストール・認証済み（gh auth statusで確認）- コミットされていない変更がないこと
- 任意のブランチから実行可能（スクリプトが元ブランチへ自動で
checkoutする）
① develop → staging（プレリリース）
処理の流れ
developブランチを最新化- 変更モジュールを検出し、各
package.jsonの version をx.y.z-rc.Nに bump （すでに rc 中なら base 据え置きで rc 番号のみ加算。rc サイクル中は type を無視） - version 変更をコミットし、
developへ push staging向けの Pull Request を作成（--base staging --head develop）- プレリリース用 Git タグ
vX.Y.Z-rc.Nを作成 - GitHub Release を prerelease 扱いで作成
コマンド一覧
| コマンド | 内容 |
|---|---|
pnpm run release:stg:dry | ドライラン（patch 相当、書き込みなし） |
pnpm run release:stg | プレリリース（patch 基準 → x.y.Z-rc.N） |
pnpm run release:stg:minor | プレリリース（minor 基準 → x.Y.0-rc.N） |
pnpm run release:stg:major | プレリリース（major 基準 → X.0.0-rc.N） |
pnpm run release:stg:skip-pr | 同上（patch）、PR 作成をスキップ |
② staging → main（本番・確定リリース）※本番環境構築後
処理の流れ
stagingブランチを最新化- version の
-rcを外して確定（1.2.0-rc.2 → 1.2.0）。再 bump はしない （rc を経由していないパッケージはフォールバックで通常 bump） - version 変更をコミットし、
stagingへ push main向けの Pull Request を作成（--base main --head staging）- Git タグ
vX.Y.Zを作成 - GitHub Release を作成
コマンド一覧
| コマンド | 内容 |
|---|---|
pnpm run release | ヘルプ表示 |
pnpm run release:dry | ドライラン（patch、書き込みなし） |
pnpm run release:patch | 確定リリース（x.y.Z） |
pnpm run release:minor | 確定リリース（x.Y.0） |
pnpm run release:major | 確定リリース（X.0.0） |
pnpm run release:patch:skip-pr / :minor:skip-pr / :major:skip-pr | 同上、PR 作成をスキップ |
バージョンタイプの目安
- patch: バグ修正のみ
- minor: 後方互換のある機能追加
- major: 破壊的変更
オプション
scripts/release-agent.ts に直接渡せるオプション（pnpm exec tsx scripts/release-agent.ts <type> [オプション]）:
| オプション | 内容 |
|---|---|
--prerelease | プレリリースモード（develop → staging）。x.y.z-rc.N に bump し Release を prerelease 扱いにする |
--from <branch> | version bump を行う元ブランチ（PR の head）。省略時は --prerelease なら develop、それ以外は staging |
--merge-to <branch> | PR のマージ先（複数可）。省略時は --prerelease なら staging、それ以外は main |
--dry-run, -d | ドライラン（実際の変更を行わない） |
--skip-pr | PR 作成をスキップ |
--skip-tag | タグ作成をスキップ |
--skip-release | GitHub Release 作成をスキップ |
--message, -m <msg> | コミットメッセージを指定 |
--help, -h | ヘルプを表示 |
完全なヘルプは pnpm run release または pnpm exec tsx scripts/release-agent.ts --help で確認できます。
Claude Code での使い方
Claude Code に リリースしたい旨を伝えるだけで自動的にこのスクリプトが起動します。どちらの段かを明示してください。
ステージングにリリースして → ① develop → staging（release:stg）
本番リリースして / 確定リリース → ② staging → main（release:patch 等）
Claude は以下のように動きます:
- まず該当のドライラン（
release:stg:dryまたはrelease:dry）を実行し、bump 内容を提示 - 内容を確認してから本番コマンドを実行
- 作成された PR と Release の URL を報告
段（staging / 本番）やバージョンタイプが不明な場合は Claude が確認します。
リリース後の手順
① develop → staging の後
- PR を確認:
gh pr view --web - Release を確認:
gh release view v<version>-rc.<N> --web - PR を マージコミットでマージ（
gh pr merge <PR番号> --merge。squash 禁止。理由は「⚠️ release PR のマージ方法」参照） - マージ後、
staging環境で動作確認
② staging → main の後
- PR を確認:
gh pr view --web - Release を確認:
gh release view v<version> --web - PR を マージコミットでマージ（
gh pr merge <PR番号> --merge。squash 禁止） - マージ後、
mainブランチを pull してデプロイ（※本番環境構築後）