| name | issue-plan-strategy |
| description | 1 つの issue に対する plan(企画書・設計書) 作成、および plan 実行(実装)時のブランチ・worktree・Draft PR・レビュー運用を一括で扱うワークフロー。issue ファイル/URL を引数に取るスラッシュコマンドとしても、issue から plan 作成依頼を受けた時 / 既存 plan の実装依頼を受けた時の自動発動 skill としても利用可能。 |
| when_to_use | issue → plan 作成 / 既存 plan の実装 (実行) を依頼されたとき。複数 PR に分割される設計や、release branch + 個別 PR + worktree 運用が必要なときに参照する。Triggers: 'issueのplanを作って', 'PLANxxの設計', '設計書を起こして', 'このplanを実装して', 'PLANxxを実装', 'planを実行', 'release branch 作って実装開始', 'multi-PR で進めて' |
| argument-hint | [issue-path-or-url] (例: issues/i16.md, https://github.com/org/repo/issues/123) |
| allowed-tools | ["Bash","Read","Write","Edit","Glob","Grep"] |
issue → plan → multi-PR ワークフロー
1 つの issue から plan を作る際、推奨される PR が複数に分かれることは日常的に発生する。本 skill はその際の release ブランチ + 個別 PR ブランチ + Draft PR 先行作成 + git worktree 並行開発 + レビュー運用 の標準フローを規定する。
本 skill は plan の作成フェーズと plan の実行(実装)フェーズの両方 をカバーする。同じワークフローが「設計を起こす段階」と「設計に従って実装する段階」を貫通することで、作成者と実装者(あるいは将来の自分)が同じ手順を共有できる。
発動条件
| トリガ | 例 | 入る Step |
|---|
| スラッシュコマンド (引数あり) | /ndf:issue-plan-strategy issues/foo.md、/ndf:issue-plan-strategy https://github.com/org/repo/issues/123 | Step 0 から |
| スラッシュコマンド (引数なし) | /ndf:issue-plan-strategy (現在ブランチで作業中の issue/plan を解析) | Step 0 から |
| 自動発動 (作成系) | 「この issue の plan を作って」「設計書を起こして」「PLAN42 の設計を起こして」 | Step 1〜2 |
| 自動発動 (実行系) | 「この plan を実装して」「PLAN42 を実行して」「multi-PR で進めて」「release branch を切って実装開始」 | Step 0 → 既存 plan を読み → Step 3 以降 |
引数で渡された issue / plan は ファイルパス / URL / 番号 いずれでも受け付ける:
- ファイルパス (
issues/PLANxx_*.md): 直接 Read
- GitHub Issue URL /
#番号: gh issue view <num> --json title,body,labels で取得
- それ以外の文字列: そのまま issue 本文として扱う
Step 0: 作成フェーズか実行フェーズか判定
最初に 既に plan ファイルが存在するか で判定する。skill 内で Glob を使うのが第一選択 (例: Glob('issues/*PLAN42*'))。shell で確認する場合は:
find issues/ -maxdepth 1 -iname '*PLAN42*' -o -iname '*feature-name*'
| 状況 | 進むフェーズ |
|---|
| plan ファイルがない / issue しかない | 作成フェーズ (Step 1〜2 へ) |
| plan ファイルがあり、release branch がない | 実行フェーズ・初期化 (Step 3 へ) |
| release branch も Draft PR も既にある | 実行フェーズ・継続 (Step 5 以降。worktree / 並行開発 / レビュー / merge を進める) |
実行フェーズで入った場合、既存 plan の 「PR 分割計画」セクションを必ず Read してから Step 3 以降の自動化判断に使う。
全体フロー
┌─ 作成フェーズ ──────────────────────────────────────┐
issue 取得 ─┤ │
│ plan 作成 (必要なら plan モード) ─ 単一PR? ─ YES ─▶ implementation-plan + /ndf:pr で完了
│ │
│ NO
└──────────────────────────────────────────┼──────────┘
▼
┌─ 実行フェーズ ──────────────────────────────────────┐
既存 plan ─▶│ Step 3: release branch 作成 + Draft release PR │
│ Step 4: 個別 PR ブランチ作成 + 各 Draft PR (release base)
│ Step 5: git worktree で並行開発 (依存関係を考慮) │
│ Step 6: 個別 PR ごとに /ndf:review or /ndf:cross-review
│ → /ndf:fix → merge into release │
│ Step 7: release ブランチで結合テスト相当のレビュー │
│ Step 8: release → default を Ready & merge │
└─────────────────────────────────────────────────────┘
QA / staging 等の検証環境向けには、個別 PR or release PR 単位で /ndf:cherry-pick-pr を別途実行する (Step 9)。
実行フェーズに途中から入った場合は、対応する Step の途中再開で構わない。各 Step の冒頭で 既に存在するブランチ / PR / worktree を git branch -a / gh pr list / git worktree list で確認してから作業に入る。
Step 1: issue 取得と plan 作成 (作成フェーズ専用)
実行フェーズで入った場合はこの Step をスキップし、既存 plan を Read して Step 3 へ進む。
- 引数を解釈して issue 本文を取得する
issues/ 配下に plan ファイルが既に存在するか Glob で確認する- なければ
/ndf:implementation-plan の プランフォーマットに従って plan ファイルを作成する
- ファイル名は英数 (例:
issues/PLAN42_multi-pr-refactor.md)
- 内容に「複数 PR に分割する根拠」「PR 単位と依存関係」を必ず含める
- 設計判断が重い場合は Claude Code の plan モード (ExitPlanMode を用いる読み取り専用フェーズ) に切り替えて十分検討してから実装へ進む
plan の構造は /ndf:implementation-plan を参照。本 skill では multi-PR を前提に 以下のセクションを追加する:
## PR 分割計画
| PR # | branch 名 | 概要 | 依存 | 並行可否 |
|---|---|---|---|---|
| 1 | feature/PLAN42-schema | スキーマ追加 | なし | ○ |
| 2 | feature/PLAN42-api | API 実装 | PR1 | × (PR1 merge 後) |
| 3 | feature/PLAN42-ui | UI 実装 | PR1 | ○ (mock で開始可) |
release branch: `release/PLAN42`
base branch: `main`
Step 2: 単一 PR で足りるか判定
plan を書いた結果が以下のいずれかなら release ブランチを作らず、/ndf:implementation-plan + /ndf:pr の通常フローに切り替える:
- 変更ファイルが 1〜2 個で結合度が低い
- 1 PR で安全に review 可能 (差分 ~500 行以内が目安)
- 依存関係のある複数タスクが存在しない
複数 PR が妥当な場合 (スキーマ + API + UI、機能追加 + マイグレーション、複数モジュール横断 等) のみ Step 3 に進む。
Step 3: release ブランチ + Draft PR 先行作成 (実行フェーズの開始点)
実行フェーズで自動発動した場合の最初の自動化対象。既に release/<PLAN-ID> ブランチや Draft PR が存在する場合は作成をスキップし、Step 4 へ進む。
release ブランチ作成
git fetch origin <default-branch>
git checkout -b release/<PLAN-ID> origin/<default-branch>
git push -u origin release/<PLAN-ID>
release → default の Draft PR を先行作成
gh pr create \
--base <default-branch> \
--head release/<PLAN-ID> \
--draft \
--title "release: <PLAN-ID> <概要>" \
--body "$(cat <<'EOF'
## Summary
- plan: issues/<PLAN-ID>_xxx.md
- 複数 PR を統合する release ブランチ
- 個別 PR が全て merge され次第 Ready for review にする
## 個別 PR
- [ ] #<TBD> PR1: ...
- [ ] #<TBD> PR2: ...
- [ ] #<TBD> PR3: ...
## Test plan (結合観点のみ)
- [ ] 個別 PR では検出できない結合テスト項目
<!-- I want to review in Japanese. -->
EOF
)"
release PR を 先に作る理由: PR 番号が確定し、個別 PR の説明から参照できるため。
Step 4: 個別 PR ブランチ + Draft PR 先行作成
既存ブランチは git branch -a | grep "feature/<PLAN-ID>-" で確認し、未作成のものだけ作る。Draft PR の存在は gh pr list --base release/<PLAN-ID> --state all で確認。
各 PR について 同じパターンで先に Draft PR まで作る:
git fetch origin release/<PLAN-ID>
git checkout -b feature/<PLAN-ID>-<scope> origin/release/<PLAN-ID>
git commit --allow-empty -m "chore: <PLAN-ID>-<scope> Draft PR 作成"
git push -u origin feature/<PLAN-ID>-<scope>
gh pr create \
--base release/<PLAN-ID> \
--head feature/<PLAN-ID>-<scope> \
--draft \
--title "feat: <PLAN-ID>-<scope> <概要>" \
--body "$(cat <<'EOF'
## Summary
- plan: issues/<PLAN-ID>_xxx.md
- release PR: #<release-pr-number>
- 担当範囲: <scope>
## Test plan
- [ ] ...
<!-- I want to review in Japanese. -->
EOF
)"
完了後 release PR の本文を gh pr edit で更新し、個別 PR 番号を [ ] に埋める。
Step 5: git worktree で並行開発
並行可能 (依存なし or mock で先行可) な PR は git worktree で同時に開く:
git worktree add ../<repo>-<PLAN-ID>-schema feature/<PLAN-ID>-schema
git worktree add ../<repo>-<PLAN-ID>-ui feature/<PLAN-ID>-ui
ガイドライン:
- 依存のある PR は順次着手する (PR1 merge → PR2 開始)
- 並行 PR 間で同じファイルを触る場合は事前にレビュー観点で分担を明確化する
- 終わった worktree は
git worktree remove <path> で片付ける
- Claude Code から並行開発を指示する場合、Agent tool の
isolation: "worktree" も検討する
Step 6: 個別 PR のレビュー
レビューは原則個別 PR 単位で行う:
| 用途 | コマンド |
|---|
| PR 作成前のセルフレビュー | /ndf:review-branch |
| GitHub 上の単体レビュー | /ndf:review <PR番号> |
| codex + gemini 両方の収束ループ | /ndf:cross-review <PR番号> |
| 指摘の修正 | /ndf:fix <PR番号> |
個別 PR が APPROVE → Draft 解除 → release ブランチへ merge (squash 推奨)。
Step 7: release ブランチのレビュー (結合テスト相当のみ)
release ブランチへの merge が一通り進んだ段階で:
- 個別 PR で見た観点を再レビューしない
- 結合テスト相当の観点のみレビューする:
- PR 間の API / 型 / スキーマ整合
- 設定値の重複・矛盾
- migration の順序依存
- E2E シナリオ (
/ndf:playwright-scenario-test の活用)
- ここで個別 PR 範囲のバグが見つかった場合は、release PR にコメントせず、該当の個別 PR (既に merge 済みなら新しい修正 PR を release 配下に作成) 側に指摘を書き込み、修正ループを回す
- release PR には integration 観点の指摘のみ残す
Step 8: release → default の merge
release PR が APPROVE されたら:
gh pr ready <release-pr-number>
gh pr merge <release-pr-number> --merge --delete-branch
merge 後は plan ファイル末尾に「完了サマリ」(マージ済み PR 番号 / 検証結果) を追記してクローズ化する。
Step 9: 検証環境 (qa/staging 等) への適用
QA / staging 検証は 個別 PR 単位 or release ブランチ単位 のどちらでも OK。
/ndf:cherry-pick-pr は Claude Code 内の slash command なので、shell ではなく
Claude Code セッション上で実行する点に注意。
個別 PR 単位で qa に反映する場合:
# (Claude Code 内で実行する slash command)
/ndf:cherry-pick-pr qa/staging
release ブランチごと qa に反映する場合 (まとまった検証が必要な場合):
git checkout release/<PLAN-ID>
# 2. (Claude Code 内で実行する slash command)
/ndf:cherry-pick-pr qa/staging
詳細は /ndf:cherry-pick-pr と /ndf:branch-fix-strategy を参照。feature → main 系 PR を汚染しないため、検証ブランチ向けは必ず短命ブランチ経由で扱う。
アンチパターン
| ❌ やってはいけないこと | 理由 |
|---|
| release ブランチを作らず巨大な 1 PR で出す | レビュー困難・revert 困難・並行開発不可 |
| 個別 PR の base を default にする | release で統合する意味が失われ、partial merge が default を汚染する |
| 個別 PR Draft 作成を実装後に回す | PR 番号が未確定でクロス参照や CI 待機の段取りが組めない |
| release PR で個別 PR 範囲の指摘を解決しようとする | 該当 PR が既に閉じている場合、コミット意図がずれる |
| 検証ブランチを feature/release に merge する | feature → main PR への汚染 (詳細: /ndf:branch-fix-strategy) |
関連 skill
/ndf:implementation-plan — plan ファイルのフォーマット (本 skill が依存)/ndf:branch-fix-strategy — ブランチ汚染を避ける原則/ndf:pr — 通常の PR 作成 / 更新/ndf:cherry-pick-pr — 検証ブランチへの cherry-pick PR/ndf:review / /ndf:review-branch / /ndf:cross-review — レビュー/ndf:fix / /ndf:resolve-pr-comments — コメント対応/ndf:playwright-scenario-test — release ブランチでの E2E 結合テスト
