dev-git-workflow

Git ワークフロー

このスキルでは、チームの Git モデルを選び、マージとレビューのポリシーを設定し、人間と AI 支援によるコラボレーションの安全なデフォルトを定義します。読者が Git コマンドを知っていることを前提とし、判断の指針を示します。

デフォルトの方針：GitHub Flow またはトランクベース開発を採用し、リポジトリごとにマージ方法を 1 つに統一し、PR がマージ前に頻繁に古くなるようになったらマージキューを導入し、エージェントごとにワークツリーを 1 つ用意し、バージョンサポート上必要な場合に限りリリースブランチを使用します。ホスティングプラットフォームの機能（スタック型 PR、マージキューのオプション、ルールセットのフィールド）と Git 自体は年に数回変更されます。Git のバージョンに依存する機能を推奨する前に git-scm.com のリリースノートを確認し、プラットフォームの機能を推奨する前に、そのプラットフォームのドキュメントでユーザーのプランで利用できるか確認してください。

クイックリファレンス

必要なこと	デフォルト	参考資料
ブランチモデルを選ぶ	GitHub Flow。マージ頻度が高い場合は、マージキューを併用したトランクベース開発	references/branching-strategies.md
マージ方法を選ぶ	小規模な PR 中心のフローではスカッシュ、リリースブランチではマージコミット	マージ方法, references/pr-best-practices.md
並行作業中も main を正常な状態に保つ	マージキューまたはマージトレイン	マージキュー, references/automated-quality-gates.md
依存関係のある変更を迅速にマージする	スタック型 PR	references/stacked-diffs-guide.md
エージェントまたは機能開発を並行して進める	エージェントごとにワークツリーとブランチを 1 つずつ用意する	references/ai-agent-worktrees.md
リリースとホットフィックス	upstream を優先した修正、main からのタグ作成	references/release-management.md
コミットメッセージと変更履歴	dev-git-commit-message が担当	dev-git-commit-message, references/commit-conventions.md
不適切なマージやリグレッションをデバッグする	コンフリクト対応の規律、bisect	references/conflict-resolution.md, references/git-bisect-debugging.md

別のスキルを参照するケース：特定の変更セットのレビュー → software-code-review。マージゲートを超える CI/CD プラットフォーム設計 → ops-devops-platform。コミットメッセージの形式、トレーラー、変更履歴のツール → dev-git-commit-message。

ワークフロー

1. 制約を確認します。同時にオープンしているブランチの数（人数ではありません）、リリースの頻度とサポート対象バージョンの数、CI の所要時間とデフォルトブランチの失敗率、コントリビューターモデル（共有プッシュかフォークか）、コンプライアンスまたは監査の要件を確認します。
2. 条件に合う最もシンプルなブランチモデルを選びます（下の表を参照）。
3. リポジトリのベースラインを設定します。ルールセット、承認、必須チェック、マージ方法の統一、CODEOWNERS、リリースとタグのルールを定めます。
4. 安全性の事前確認を含め、人間とエージェントのローカル作業手順を定義します。
5. リポジトリのポリシーをその場で考案するのではなく、参考資料とテンプレートを使って実装します。

分岐方法の選択

状況	デフォルト
本番ブランチが1つで、デプロイ頻度が高い	GitHub Flow
マージの同時発生が多く、CI が高速かつ安定していて、main を常にグリーンに保つ必要がある	トランクベース開発とマージキューの併用
未完成の作業を早期にマージする必要がある	トランクベース開発と機能フラグの併用
サポート対象のバージョンが1つで、定期リリースを行う	GitHub Flow、またはリリースタグを使うトランクベース開発
サポート対象のバージョンが複数ある、または安定化に長期間を要する	main から切るリリースブランチ（独立した統合ブランチによって効果が得られる場合に限り、GitFlow を使用）

トランクベース開発には、迅速に回答する CI（目安として10分未満）と、赤になることがまれなデフォルトブランチ（目安としてビルド失敗率5％未満）が必要です。いずれも基準ではなく、各環境に合わせて調整するためのヒューリスティックとして扱ってください。

チームの人数はマージの同時発生数を推測するための指標であり、本当の変数ではありません。

• エージェント中心のチーム。 5人の人間が10個のエージェント用ワークツリーを並行して動かす場合、マージの同時発生数ははるかに大きなチームと同程度になります。モデルとマージキューを採用するかどうかは、同時にオープンしているブランチの数に基づいて決めてください。
• フォークベースのオープンソース。 トランクベース開発はプッシュ権限を前提としています。フォークと PR によるコントリビューションでは、GitHub Flow を使い、コアメンテナーのみを「チーム」として数えてください。
• 規制対象または監査対象の作業。 署名付きコミット、必須の独立した承認、改変不可能な履歴が、制約になることがよくあります。4人の規制対象チームには、40人の SaaS チームより厳格なルールセットが必要な場合があります。
• 分散型の非同期チーム。 当日中のレビューは前提にできません。厳格なブランチの経過時間制限より、ドラフト PR、必須チェック完了時の自動マージ、スタック PR を優先してください。

マージ方法

リポジトリごとにマージ方法を1つ選び、ルールセットの許可されるマージ方法で強制してください。方法が混在すると、PR ごとに git log、bisect、revert の動作が異なります。

方法	選択する状況	コスト
スカッシュ	小規模な PR、または PR 内のコミットが個別に意味を持たない場合	PR ごとに1つの revert 可能な単位になりますが、途中の履歴は失われます。PR タイトルがコミットの件名になるため、PR タイトルの規約を徹底してください。スタックのベースをスカッシュすると、子孫ブランチにあるベースのコミットのコピーが孤立します
リベースマージ	作成者がコミットを整理し、すべてのコミットがビルドとテストに合格する場合	履歴は直線的になり、bisect しやすくなりますが、取り込まれた SHA は CI とレビュアーが確認した SHA と異なります。必須の署名付きコミットと組み合わせる前に、リベースマージがコミット署名をどう扱うか、ホストのドキュメントを確認してください
マージコミット	リリースブランチ、バックマージ、長期運用の統合ブランチ、またはテスト済みの正確な SHA を保持する必要がある場合	履歴が煩雑になります。ログと bisect では --first-parent を使用してください

リリースブランチのバックマージとフォワードポートには、リポジトリの PR マージ方法にかかわらず、マージコミットまたは cherry-pick -x を使用してください。

マージキュー

PR の取り込み前に「ブランチを更新」するサイクルが定期的に複数回必要になる場合、または個別にはグリーンの PR 間の意味的な競合によって main が壊れる場合は、マージキュー（GitHub）またはマージトレイン（GitLab）を導入してください。それより少ない場合は、「ブランチを最新の状態に保つ」を必須にして自動マージを使うほうがシンプルです。

• スループットの上限 ≈ ビルドの同時実行数 × 平均グループサイズ ÷ CI の所要時間。CI に25分かかり、ビルドごとに PR が1つの場合、直列キューで取り込めるのは1時間あたり約2.4 PR です。チームがそれを上回る数の PR をオープンする場合は、まず同時実行数かグループサイズを増やすか、CI の時間を短縮してください。
• グループが大きいほど CI の実行回数は減りますが、失敗が1つでもあるとグループ全体が無効になり、再テストが必要になります。スループットを最も損なうのは不安定なテストです。キューを有効にする前に、修正するか隔離してください。
• 必須チェックはすべて、キューのイベントでも実行する必要があります（GitHub Actions では merge_group、サードパーティ CI ではキューの一時ブランチ）。パスフィルターのためにキューのエントリーで実行されない必須ワークフローがあると、キューが停止します。
• 必須チェックは名前で照合されます。CI ジョブの名前を変更すると、以前の必須チェックがいつまでも保留状態になります。

保護ブランチとルールセット

• ホスティングサービスでルールセットを利用できる場合は、ルールセットを使用します。複数のルールセットを同じブランチに適用でき、組織全体に定義できます。ポリシーに次に手を入れる際に、従来のブランチ保護から移行します。
• 保護ブランチへのマージには PR を必須とし、作成者以外のメンバーによる承認、新しいプッシュ時の古い承認の取り消し、機密性の高いパスに対する CODEOWNERS のレビュー、必須ステータスチェックを設定します。
• main、リリースブランチ、リリースタグでは、強制プッシュと削除を禁止します。バイパスリストは短く、対象を明記して監査可能な状態に保ちます。緊急時にバイパスした場合も、マージ後に CI とレビューを実施します。
• 利用できる場合は、プッシュ保護付きのシークレットスキャンを有効にします。
• 1 つのアカウントで 2 つのエージェントを使っても、レビュー担当者が 2 人いることにはなりません。単独アカウントのリポジトリでは、許可するマージ方法（2 つ目のレビュアーアカウント、必須承認を無効にしたうえでの手動レビュー、または意図的な管理者バイパス）を明確に文書化します。

リリースとホットフィックスのフロー

• リリースには main（またはリリースを出荷するリリースブランチ）からタグを付けます。リリースタグを保護します。
• まず上流へ： 修正を main にマージし、その後、サポート対象の各リリースブランチに cherry-pick -x で適用します。リリースブランチだけに適用した修正は、次のリリースでリグレッションとして再発します。
• main が大きく分岐していて、修正を先に main にマージできない場合は、リリースブランチを修正し、追跡対象のフォワードポート PR を直ちに作成します。
• GitHub Flow でのホットフィックス：main からブランチを作成し、迅速にレビューして、完全な CI を実施します。main に未リリースの作業があり、それを出荷できない場合は、リリースタグからブランチを作成します。
• バージョニング方式、リリースのトリガー、ロールバックについては、references/release-management.md を参照してください。

ローカルの安全確認

チェックアウト、マージ、リベース、コミット修正、リセット、プッシュの前に、次を行います。

1. git status --porcelain で作業ツリーに変更があるか確認します。明確に判断してください。コミットするか、作業を専用のワークツリーに移すか、作業を中止します。他のエージェントと共有している作業ツリーで git stash を実行してはいけません。すべてのエージェントの未コミット変更が一括で退避され、refs/stash はすべてのワークツリーで共有されるためです。
2. .git/index.lock がある場合は、削除する前に Git プロセスが実行中でないことを確認します。
3. コンフリクトが発生したら、新しい編集を中止し、ファイルごとに解決して、該当するテストを再実行してから続行します。
4. エージェント主導の作業では、意図したファイルだけをステージします。
5. 複数のリポジトリや長時間稼働するシェルでは、シェルの cwd に頼らないでください。変更操作には git -C <path> を使用し、事前に git -C <path> rev-parse --show-toplevel と branch --show-current で対象を確認します。誤ったリポジトリやブランチに変更を加えた場合は、復旧作業に入る前に中止して調査します。

履歴書き換えのリスク判断

リスクを左右するのはコマンドではなく、その ref に依存している人がいるかどうかです。

• 原則として安全： PR が作成される前で、自分または 1 つのエージェントだけがプッシュしたブランチ。
• まず確認： レビューや承認が付いているオープンな PR のブランチ。強制プッシュ（--force-with-lease でも）は、ほとんどの設定で承認を取り消します。再レビューにかかるコストは、履歴を整理して得られる利点を上回ることがよくあります。レビュー状況を確認し（gh pr view --json reviews,reviewDecision）、承認がある場合は履歴を書き換えずにコミットを追加します。書き換えが避けられない場合は、レビュアーに git range-diff の出力を提示します。
• 明示的に伝達された例外がない限り、絶対に行わない： main、develop、リリースブランチ、リリースタグ、または他の人やエージェントが作業の基盤としているブランチ。
• 履歴に含まれるシークレット： まず認証情報をローテーションします。これで情報漏えいを封じ込められます。依然として必要な場合に限り、git filter-repo を使用して履歴を書き換えます（Git の公式ドキュメントでは filter-branch は非推奨です）。クローン、フォーク、ホスティングサービス側の PR ref には古いオブジェクトが残るため、ローテーションは必須です。
• エージェントの失敗パターン： エージェントが履歴を「整理」すると、前回のフェッチ以降に人間がプッシュした変更を破壊するおそれがあります。エージェントが記録したリモートの先端に対して --force-with-lease を必須とし、リースが拒否された場合は作業を中止します。フェッチして調査し、人間を交えて対応します。単独の --force で再試行してはいけません。

承認済みの履歴書き換えを引き継ぐ際は、変更前の先端、変更後の先端、ブランチ、影響を受ける依存ブランチまたは PR、共同作業者が再同期するために実行するコマンドを記録します。

エージェントが作成した変更

• エージェントによるコミットを識別できるようにしてください。専用のボット作成者 ID だけが git log --author と blame の結果を変えます。Co-authored-by: または Assisted-by: のトレーラーでは変わりません。AI トレーラーを追加するかどうか、追加する場合はどれにするかは、リポジトリのポリシーと dev-git-commit-message に従います。その人の承知なしに、人間の ID でコミットしてはいけません。
• リポジトリで署名済みコミットが求められる場合は、エージェントのコミットにも必ず署名してください。エージェント ID も例外ではありません。
• エージェントによる変更の要約はレビューではなく、「テストに合格した」という報告も、リポジトリの実際のゲートが実行されるまでは検証済みではありません。エージェントが作成した main 向け PR は人間がレビューする必要があります。AI レビュアーはコメントできますが、承認者としては数えません。エージェントがマージできる唯一の経路は、次のルールにある dev へのマージです。
• エージェントに自分の PR を承認させてはいけません。このタスクで人間から依頼され、adversarial-review ワークフローが最終的な PR の差分に対して CLEAN を返した場合に限り、エージェントは PR をマージできます。ただし main へのマージはできません。また、レビュー済みのコミットを固定します：gh pr merge <n> -R <owner/repo> --match-head-commit <head_sha>。
• 1 つのエージェントに、1 つのワークツリーと 1 つのブランチを割り当てます。エージェント間で作業ツリーを共有すると、互いの意図が気付かれないままコミットによって上書きされます。

ルール：rules/common/git.md は、すべてのコーディングセッションでこの不変条件を読み込みます。

ワークツリーを優先するループとリポジトリ内の契約

1. 機能またはエージェントごとにワークツリーを 1 つ作成します（そのディレクトリが無視対象であることを確認してください）。
2. 編集する前に、そのワークツリーで依存関係とベースラインテストを確認します。
3. 編集は割り当てられたファイル内に限定します。
4. PR を作成する前に、ワークツリーからリポジトリのゲートを実行します。
5. リポジトリのポリシーに従ってマージし、マージ後にワークツリーを削除してブランチを削除します。

ユーザーが実際のリポジトリでこのループを使いたい場合は、リポジトリ内のスクリプト（start <slug>、gate、pr、finish <slug>）として標準化し、正確なコマンドとレビュー／マージのポリシーを AGENTS.md に記録します。複数リポジトリにまたがる機能では、共通の slug とリポジトリごとに 1 つの PR を使用し、契約を所有するリポジトリを最初にマージします。契約の全容、複数リポジトリのセッションコマンド、環境変数の上書きパターン、検証手順については、references/ai-agent-worktrees.md を参照してください。

失敗のパターン

• リリース後のサポート負担、マージの並行性、CI の対応能力ではなく、理念に基づいてブランチモデルを選ぶ。
• リリース上の理由がないのにブランチを長期間維持する。dev／staging／prod などの環境ブランチを使い、1 つのビルド成果物を昇格させずにブランチを分岐させる。
• 必須チェックが不安定、パスでフィルタリングされている、または遅い状態でマージキューを有効にする。キューはその 3 つすべての問題を増幅します。
• 合意済みのポリシーがないまま、レビュー中にリベースしたり強制プッシュしたりして、レビュアーの文脈や承認状態を失う。
• 依存関係の順序が不明確な変更を積み重ねる。独立した変更は、並行する PR に分けます。
• リポジトリ内のスクリプトなしでワークツリーや変更を積み重ね、クリーンアップと検証に一貫性がなくなる。固定された兄弟ディレクトリのパスを前提とする自動化を使う。
• 「マージを早めるため」に CI やレビューを省略する。その回避策がプロセスになってしまいます。

ナビゲーション

• references/branching-strategies.md：モデルの選択、モデルごとのホットフィックス手順、移行
• references/pr-best-practices.md：PR の規模、説明の要件、レビューのエチケット、マージ方法の詳細
• references/stacked-diffs-guide.md：スタックするタイミング、ツールの選択、スカッシュマージからの復旧、マージ順
• references/automated-quality-gates.md：必須チェック、マージキューとマージトレインの設定、緊急時のバイパス
• references/release-management.md：バージョニング方式、リリースのトリガー、ホットフィックス、ロールバック
• references/ai-agent-worktrees.md：ワークツリーのセットアップ、エージェントの並列実行、クリーンアップ、リポジトリ内のデリバリー要件
• references/interactive-rebase-guide.md：オートスカッシュ、--update-refs、range-diff、復旧
• references/conflict-resolution.md：予防、解決時の落とし穴、rerere、マージの取り消し
• references/git-bisect-debugging.md：自動 bisect、終了コード、first-parent
• references/git-hooks-automation.md：フックマネージャー、プッシュ前の正確なチップチェック、バイパスポリシー
• references/monorepo-workflows.md：部分クローン、スパースチェックアウト、CODEOWNERS、変更対象のみの CI
• references/validation-checklists.md：PR 作成前、マージ前、ホットフィックス、リベース、スタック、リリースのチェックリスト
• references/common-mistakes.md：ミスと修正方法の一覧
• references/commit-conventions.md：dev-git-commit-message への案内、アトミックコミット、テンプレート
• アセット：PR テンプレート、ワークフローガイドのテンプレート、リリースワークフローのテンプレート、GitHub のチェック、GitLab のチェック
• data/sources.json

関連スキル：software-code-review、qa-debugging、ops-devops-platform、qa-testing-strategy、docs-codebase、dev-git-commit-message、ai-coding-agents。

情報の確認

• スタック型 PR、マージキューの設定、ルールセットのオプションなど、プラットフォーム機能の状況を紹介する前に、プラットフォームの公式ドキュメントと変更履歴で確認してください。ブログよりもそれらと git-scm.com を優先してください。
• Git の機能が利用できるかどうかは、ユーザーがインストールしているバージョンのリリースノートで確認してください。実験的なコマンドには実験的であることを明記してください。

学びのループ

過去の判断や落とし穴が関係する場合は、learnings.consolidated.md があれば参照してください。必要な履歴を確認するとき、または利用可能な代替手段としてのみ learnings.md を使用してください。それ以外の場合は、どちらも参照しないでください。

これを適用した後、覚えておく価値のあるパターン、防止する価値のあるミス、または意外だった分野の事実に遭遇した場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って learnings.md に日付付きの箇条書きを1つ追記してください。SKILL.md 自体は変更しないでください。