メモ
スタック プル要求は パブリック プレビュー であり、変更される可能性があります。
大規模なプル要求は、特に AI が短時間で大量のコードを生成するのに役立つ場合に、ボトルネックを確認して作成することは困難です。 pull request サイズが大きくなると、レビューの品質も低下します。 レビュー担当者は、結果、ミスの問題、または先延ばしを回避し、古くなりマージ競合が発生するまで pull request を残すことができます。
スタック プル要求では、大きなコード変更をレビュー可能な状態に保ちます。
スタックは、同じリポジトリ内の一連のプル要求です。各プル要求は、その下のプル要求のブランチを対象とし、1 つのブランチ (通常はメイン ブランチ) に配置される順序付きチェーンを形成します。 1 つの大きなプル要求の代わりに、一連の小さなプル要求を取得します。 各プル要求には独自のフォーカスされた差分があるため、チームメイトは各レイヤーを個別に確認して承認できます。
このチュートリアルでは、エージェントと共にスタックプル要求を使用して、個別にレビュー可能なレイヤーに機能を構築する方法について説明します。 この例では、アプリにユーザー認証を追加する方法を検討します。
GitHub Copilot CLI（コマンドラインインターフェース）とgh-stack エージェント スキルを使用します。
前提条件
エージェントで gh-stack スキルを使用するには、まず、 GitHub CLI と gh-stack CLI 拡張機能をインストールする必要があります。 以下のものが必要です。
- GitHub CLI (
gh) 2.90.0 以降、および Git 2.20 以降。gh auth loginを使用してGitHub CLIを認証します。
- プッシュできる GitHub リポジトリ。
- GitHub Copilot CLI（コマンドラインインターフェース） インストールおよびサインイン済み。
GitHub CLIで、gh-stack拡張機能とスキルをインストールします。
gh extension install github/gh-stack
gh skill install github/gh-stack
メモ
このチュートリアル全体を通して、 Copilot 実行するのではなく、自分でスタック コマンドを実行する場合は、 GitHub CLIを使用する必要があります。
1. コードを生成する前にスタックを設計する
良いスタックは、家を建て、強い基盤から始めて、壁をフレームに入れ、配線を取り付け、それからドライウォールを仕上げるようなものです。 構築された各レイヤーは、以下のものに依存します。 最後に、レビュー担当者は、下から上にプル要求を読み取り、一緒に表示される機能に従うことができる必要があります。
- フィーチャをレイヤーに分割します。 各レイヤーは、単独で確認できる単一の一貫性のある変更である必要があります。
- 各レイヤーは、プル要求が簡単に読み取れるほど小さくします。 レイヤーがレビューに長い説明が必要だと感じる場合は、おそらく大きすぎる可能性があります。
- 自分で境界を決定するか、プランで Copilot を操作します。 どちらの方法でも、スタックの形状を所有します。
- 依存関係別にレイヤーを並べ替える。 基本的な変更は下部に表示されます。 それらに依存するものは、より高くなります。 認証の場合、次のようになります。
- レイヤー 1: データ モデルと移行
- レイヤー 2: CRUD エンドポイント
- レイヤー 3: JWT ミドルウェアとガード
- レイヤー 4: 統合テストと単体テスト
プロンプトの例
Propose a layered approach to add user authentication to this app. Order the layers by dependency, keeping each layer independently reviewable.Review my planned layers and flag any that are too large or that depend on a branch above them.
2. 最初に下部レイヤーを構築する
基盤を使用してスタックを開始します。 上記のすべては、このレイヤーを正しく取得することに依存します。
- スタックプル要求を作成 Copilot 通知し、プランに基づいて最初のレイヤーを構築するように依頼します。 エージェントは、
gh-stackスキルを使用してスタックの最初のブランチを作成します。 - スタックを自分で作成する場合は、
gh stack initで直接作成し、プレフィックスを使用してブランチ名を整理します (例:gh stack init BRANCH-NAME-1)。 - 次に進む前に、生成された変更を自分で確認してください。 下位レイヤーの間違いは、その上のすべてのブランチに反映されるため、次に進む前にレビューを行ってください。
プロンプトの例
Start the pr-stack and build only the first layer: the user data model and migration.Conduct a review of the generated code and confirm this branch contains only the data model and migration, and nothing that belongs in a later layer.
3. 新しい各コード レイヤーを上に積み重ねる
基盤を整えた状態で、フィーチャの残りの部分を一度に 1 レイヤーずつ構築します。
- Copilotに次のレイヤーを追加し、以下のレイヤーのコンテキストで実装するように依頼します。 エージェントは、スタックの一番上に分岐を追加し、そこで作業をコミットします。
- ブランチを自分で追加する場合は、
gh stack add BRANCH-NAME-NEXTを使用します。 - レイヤーが大きくなりすぎる場合は、プランの外側にドリフトしたか、1 つではなく 2 つのレイヤーが実際に必要かどうかを検討します。
- レイヤーごとに新しいブランチを作成し、すべてのブランチがクリーンで自己完結型の差分を維持するようにします。
- プル要求を作成する準備ができたら、スタックの送信を Copilot に要求するか、自分で実行する場合は、
gh stack submitを使用します。 - 各プル要求を単独で実行します。 通常は、重点を置いたタイトルと、レイヤーの簡潔でわかりやすい説明で十分です。
プロンプトの例
Add the next layer in a new branch on top: the CRUD endpoints that use the user model from the branch below.This branch is getting large. Suggest how it could be split into two independently reviewable layers.
4. レビューを依頼する前に pull request を自分で確認する
各レイヤーは小さく、自己レビューも簡単になります。 チームメイトを巻き込む前に、すべてのブランチにパスを渡します。 レビュー担当者は、既に信頼している変更を受け取る必要があります。
- 各ブランチでテスト、リンター、コード スキャンを実行します。 レビュー Copilot 要求する前に、各レイヤーを標準に照らして確認できるようにします。
- AI によって生成された変更を徹底的に確認する手法については、 AI によって生成されたコードを確認する を参照してください。
5. スタックのレビューを一番下から要求する
レイヤーを構築すると、校閲者はコードの大きな壁ではなく、小さな差分を取得します。
- 依存関係が厳密に統合されている場合は、スタックの下部からレビューを依頼して、後続のレビューの前に変更をスタックに統合できるようにします。
- 異なるレイヤーの個別のユーザーからのレビューが必要な場合は、レビュー担当者が並行して作業できます。 1 人のユーザーがデータ モデルを確認し、別のユーザーがエンドポイントをレビューし、どちらも機能全体を確認することはできません。
6. フィードバックを反復処理する
フィードバックは、機能全体ではなく、レイヤーに個別に反映されます。 スタックを使用すると、適切なレイヤーを所定の位置に固定し、変更を上に移動できます。
- レビュー担当者がフラグを設定したレイヤーを変更するように Copilot に依頼します。 エージェントは右ブランチに移動し、変更を行い、そこでコミットします。 次に、上のレイヤーをリベースして修正プログラムを取得します。
- 各修正は、それが属するレイヤーに保持します。 間違ったブランチで行われた変更により、エラーが混乱し、エラーが発生する可能性があります。
- 修正を行う際は、上記のブランチをリベースし、変更を反映するように Copilot に依頼してください。
- スタック内を自分で移動する場合は、
gh stack down、gh stack up、またはgh stack checkout BRANCH-NAMEを使用してブランチ間を移動します。 次に、変更をコミットし、gh stack rebase --upstackを実行して変更をスタックに反映します。
プロンプトの例
A reviewer flagged that the auth service doesn't handle expired tokens. Fix that on BRANCH-NAME and test the changes.I've rebased the layers above onto this fix. Check that the branch with endpoints still works with the change and flag anything that needs updating.
7. 下のレイヤーから結合する
スタックは、メイン ブランチを指すレイヤーから順にマージされます。 レイヤーを一度に 1 つずつマージし、GitHub自動的にメインをポイントするように次のレイヤーを再ターゲットします。
- スタックを一度に 1 つずつ、またはスタック内の任意の場所からマージすると、マージするプル要求の下にあるすべてのブランチが一番下からマージされます。
- 各レイヤーの差分は親に対してまったく同じままで、基本の変更のみであるため、進行中の作業やレビューに影響を与えることなく、一度にレイヤーを簡単にマージできます。
- 自動マージまたはマージ キューを使用して、各レイヤーが承認され、そのチェックが成功するとすぐにマージされるようにします。 スタック全体を一度に待機する必要はありません。
最上位レイヤーがマージされると、フィーチャ全体が着陸します。 すべての部分は、1 つの大きなプル要求ではなく、小さな意図的な変更としてより効果的にレビューされました。