gh-create-pr

GitHub PR の作成

スタック用ツール

このリポジトリには、プロジェクトの公開スキルとして .agents/skills/gh-stack/SKILL.md が含まれています。開発者がエージェントスキルを別途インストールする必要はありません。スタックされたブランチまたは PR を操作する前に、これを読んでください。.agents/skills/ を参照するエージェントは、このスキルを直接検出します。Claude のチェックアウトに .claude/skills/gh-stack がない場合は、pnpm skills:sync の後に pnpm skills:check を実行してください。別のグローバルコピーをダウンロードしないでください。

タスクで最初の gh stack コマンドを実行する前に、GitHub CLI を確認し、見つからない場合は公式拡張機能をインストールしてください。

command -v gh >/dev/null 2>&1 || {
  echo "GitHub CLI is required: https://cli.github.com/" >&2
  exit 1
}
gh auth status
if ! gh stack --help >/dev/null 2>&1; then
  gh extension install github/gh-stack
fi
gh stack --help >/dev/null

認証、インストール、または最後の確認に失敗した場合は中止してください。場当たり的な Git コマンドでスタックを推測しないでください。人が作成した Cherry PR の場合は、gh stack push を使用し、このスキルに従って下から上へ各 PR を作成してから、既存の PR を gh stack link でリンクしてください。gh stack submit --auto は、テンプレートに準拠した本文の作成フローを経ずに PR を作成するため、このワークフローを回避する目的で使用してはなりません。

ワークフロー

1. PR の本文を作成する前に、.github/pull_request_template.md を読みます。
2. 現在のブランチから PR のコンテキスト（ベース／ヘッド、スコープ、関連する issue、テスト状況、破壊的変更、リリースノートの内容）を収集します。実際のベースを確認し、pnpm change:scope --base <verified-base-ref> を実行します。最新のコミットだけからスコープを推測しないでください。
3. .agents/notes/README.md を読み、変更を分類します。
   • Agent Note にはリポジトリ内のパスを記入します。ローカルで完結する変更や機械的な変更の場合は、N/A — <reason> と記入します。
   • Spec PR の場合は、Spec PR: This PR と記入し、すべての AC を列挙します。
   • 実装レイヤーの場合は、Spec PR へのリンクを記載し、このレイヤーで対応する AC ID のみを列挙します。commit_id が現在の Spec の head と一致する APPROVED レビューがあることを確認します。古い承認は実装の許可にはなりません。
   • 根拠を長期的に残す直接的なバグ修正の場合は、実装済みの bug-fix ノートへのリンクを記載し、Spec PR: N/A とします。
   • 自動化によって作成された PR（リポジトリのワークフローおよび Dependabot）は、これらのメタデータ項目が免除されます。本文を人間が作成した PR のようにしないでください。
4. 実装 PR の場合は、スタックツールの事前確認を完了してから gh stack view --json を実行します。終了コードが 2 の場合は、gh-stack スキルのリモート検出手順に従います。ローカルのメタデータがないことだけを根拠に、その PR が単独だと判断してはいけません。下位の実装 PR をすべて調べ、実際の検証で裏付けられた AC のみを集約します。中間レイヤーではノートを提案状態のままにします。現在の PR が最終レイヤーで、累積した証拠が承認済み Spec の全体を網羅している場合は、バイリンガルの 3 項目を implemented/ に移動し、公開前に pnpm agent-notes:check-transition --base <verified-spec-ref> を実行します。
5. 実際に実行したコマンドとシナリオを Verification に記入します。予定、保留中、スキップ済み、または CI のみのチェックを、合格したものとして記載してはいけません。
6. 現在のブランチがリモートにプッシュ済みか確認します。未プッシュの場合は、先にプッシュします。
   • デフォルトのリモートは origin ですが、別のリモートを使用するかユーザーに確認してください。

   git push -u <remote> <head-branch>
   

7. ベースブランチを決定します。
   • デフォルトを適用する前に、ヘッドブランチを確認します。ヘッドが release/v<version> の場合は停止します。リリースブランチからプルリクエストを作成してはいけません。特に main を対象にしてはいけません。独立した修正はトピックブランチに置いてリリースブランチを対象にするか、Post Release にメタデータ同期ブランチを作成させてください。
   • 任意のトピックブランチのベースを main に設定する前に、マージベースとアップストリームを確認します。release/v<version> から開始した製品コードの修正は停止し、ホットフィックスとして main から作り直す必要があります。リリース専用の修復、または明示的なバックポート復旧用トピックのみ、該当するリリースブランチを対象にできます。
   • backport/v<version>/pr-<number> のヘッドは、一致する release/v<version> をベースにし、本文の単独行に、正確な元のホットフィックス PR を示す `` を含める必要があります。release-sync/v<version> のヘッドは main を対象にし、正確なタイトル chore(release): sync v<version> metadata を使用し、本文の release-metadata-boundary: v<version> マーカーを残したうえで、スカッシュマージする必要があります。
   • 公式リポジトリ（CherryHQ/cherry-studio）で origin を使用する場合、デフォルトのベースは origin の main ですが、ユーザーが明示的に別のベースブランチを指定することもできます。
   • main はホットフィックス PR を含む、開発中のアクティブなブランチです。ユーザーが明示的に要求しない限り、古いメンテナンスブランチを対象にしてはいけません。
   • ユーザーがアクティブなドラフトリリースに含める必要があると明示した場合に限り、PR をリリースホットフィックスとして分類します。タイトルには hotfix: <description> または hotfix(<kebab-case-scope>): <description> を使用します。スコープは小文字の英数字によるケバブケースとし、コロンの後はスペース 1 つだけにし、説明を空にしてはいけません。このタイトルの文法により、hotfix ラベルは自動的に同期されます。マージ後に別のバックポート PR が作成されるのは、一致するアクティブな release/v<version> ブランチがあるドラフトのセマンティックバージョンリリースがちょうど 1 つの場合に限ります。それ以外の場合、自動化は対象を推測せずに停止します。
   • ホットフィックスがユーザーに影響する場合は、自動化がアクティブなドラフトと安定版のリリース履歴を更新できるよう、各言語でリリースノートを 1 行ずつ記載します。この正確な形式を、テンプレートに既存の release-note フェンス内に配置します。箇条書き記号は含めないでください。

     
     [Component] 英語での説明。
     
     [组件] 中文说明。
     
     

   • hotfix にユーザー向けのリリースノートがない場合は、テンプレートの release-note フェンス内に NONE をそのまま記載してください。コードはバックポートされますが、リリースメタデータは変更されません。提示されたバイリンガルブロックは、上記の正確な構造を満たす必要があります。
   • フォークしたリポジトリを origin としている場合は、git remote -v で利用可能なリモートを確認してください。デフォルトのベースは upstream/main または別のリモートである可能性があります。ユーザーがベースブランチを明示していない限り、ユーザーは常に CherryHQ/cherry-studio/main へのマージを希望しているものとして扱ってください。
   • デフォルト以外のベースブランチを使う場合は、ユーザーに確認してください。
8. 一時ファイルを作成し、単一の Bash ヒアドキュメントで PR の本文を書き込みます （Windows で mktemp と Write ツールのパスが一致しない問題を回避します）：

   pr_body_file="/tmp/gh-pr-body-$(date +%s).md"
   cat > "$pr_body_file" <<'EOF'
   ...filled template body...
   EOF
   

   テンプレートの構造を正確に保って内容を記入してください（セクションの順序、 見出し、チェックボックスの書式を維持します）。該当しない場合は N/A または None と記載してください。
9. Bash の cat "$pr_body_file" で一時ファイルの内容を確認します（Windows では Read ツールが /tmp/... パスで失敗する場合があります）。ユーザーがプレビューまたは確認を求めている場合は、本文全体を提示してその要望に従ってください。そうでなければ、許可された PR 作成に進みます。
10. PR を作成します。ユーザーがドラフトを希望している場合は --draft を追加します：

gh pr create --base <base> --head <head> --title "<title>" --body-file "$pr_body_file"

リリース hotfix の場合は、ワークフローがラベルを同期し、提示されたバイリンガルノートを個別に検証できるよう、分類器に適合する正確なタイトルを使ってください：

gh pr create --base main --head <head> --title "hotfix: <description>" --body-file "$pr_body_file"

作成後、分類器が hotfix を追加したことを確認してください。追加されていない場合は、手動でラベルを追加するのではなく、タイトルを修正してください。また、ワークフローで不正な形式の任意のリリースノートブロックが報告された場合は、それも修正してください。 11. 一時ファイルをクリーンアップします：rm -f "$pr_body_file" 12. 作成した PR の URL を報告し、タイトル／ベース／ヘッド、Agent Note／Spec、AC の網羅状況、実際に行った検証、および必要なフォローアップを要約してください。

制約

• テンプレートのセクションを省略しないでください。

• テンプレートの形式を書き換えないでください。

• 変更内容に即して、簡潔かつ具体的に記述してください。

• PR のタイトルと本文は英語で記述してください。

• 通常のバグ修正に hotfix のタイトルやラベルを使わないでください。マージ後に該当するドラフトリリースが有効な場合、自動バックポート PR が作成される対象となります。

• リリース hotfix でユーザー向けのリリースノートがない場合は、NONE を使用できます。不完全なもの、片方の言語のみのもの、その他不正な形式のバイリンガルノートは決して記載しないでください。不正な内容があると、バックポートワークフローは処理を中止します。

• release/v<version> のヘッドを main に設定しないでください。リリースブランチはプルリクエストのソースブランチではありません。

• 現在の Spec のヘッドが完全一致する Approval を得ていない場合、実装 PR をレビュー準備完了の状態で公開しないでください。Spec はマージされていなくてもスタックのベースとして使用できます。

• 人が作成するすべての PR で、Agent Note、Spec PR、Acceptance criteria を記入してください。N/A とする場合は簡潔な理由を添えてください。自動化が作成する PR（リポジトリのワークフローおよび Dependabot）は、このメタデータ記入要件の対象外です。

• リリースノートとドキュメントのチェックボックス — どちらも変更がユーザー向けかどうかによって決まります。以下の表を参照してください。

  変更の種類	リリースノート	Docs [x]
  新しいユーザー向け機能／設定／UI	変更内容を記載	✅
  ユーザーに見えるバグ修正	修正内容を記載	動作が変わる場合は ✅
  動作／デフォルト値の変更	変更内容と action required を記載	✅
  ユーザー向け依存関係のセキュリティ修正	修正内容を記載	利用方法が変わる場合は ✅
  CI／GitHub Actions の変更	NONE	❌
  内部リファクタリング（ユーザーが認識できないもの）	NONE	❌
  開発／ビルドツールの変更	NONE	❌
  開発専用の依存関係の更新	NONE	❌
  テストのみ／コードスタイルの変更	NONE	❌

コマンドパターン

# read template
cat .github/pull_request_template.md

# prepare and inspect the PR body
pr_body_file="/tmp/gh-pr-body-$(date +%s).md"
cat > "$pr_body_file" <<'EOF'
...filled template body...
EOF
cat "$pr_body_file"

# create the authorized PR; add --draft when requested
gh pr create --base <base> --head <head> --title "<title>" --body-file "$pr_body_file"
rm -f "$pr_body_file"