git-workflow

Git ワークフロー（現代的なチームコラボレーション）

継続的デプロイには GitHub Flow、規模拡大にはトランクベース開発、自動化には Conventional Commits、大規模な機能にはスタック型差分など、現代的な Git コラボレーションのパターンを活用しましょう。

このスキルを使って、ブランチモデルを選択し、PR の運用ルールを標準化し、コミット規約を徹底し、安全なコラボレーションのためにリポジトリの設定を強化します。

クイックスタート

1. 制約（チームの規模、リリース頻度、CI の成熟度、コンプライアンス要件）を確認します。
2. 判断フローを使ってブランチ戦略を選択します。
3. リポジトリの基本設定（ブランチ保護、承認、チェック、マージ戦略）を適用します。
4. 実装の詳細について、該当するリファレンスドキュメントを参照します。
5. 「2026 年のベストプラクティス」を尋ねられた場合は、data/sources.json を出発点となる情報源のリストとして、ウェブ検索で確認します。

クイックリファレンス

タスク	ツール／コマンド	使用するタイミング	リファレンス
機能ブランチの作成	git switch -c feat/name main	新しい作業を始めるとき	ブランチ戦略
機能用ワークツリーの作成	git worktree add ../wt-feature -b feature/name origin/dev	ブランチごとに機能を分離するとき	ブランチ戦略
WIP コミットのスカッシュ	git rebase -i HEAD~3	PR の前に整理するとき	インタラクティブなリベース
Conventional Commit	git commit -m "feat: add feature"	すべてのコミット	コミット規約
安全な強制プッシュ	git push --force-with-lease	リベース後	よくある間違い
コンフリクトの解決	git mergetool	マージコンフリクトが発生したとき	コンフリクトの解決
スタック型 PR の作成	gt create stack-name（Graphite）	大規模な機能の場合	スタック型差分
変更履歴の自動生成	npx standard-version	リリース前	リリース管理
品質ゲートの実行	GitHub Actions / GitLab CI	すべての PR	自動品質ゲート

AI エージェントの機能開発ループ

AI を活用したエンジニアリングでは、次のループをデフォルトとして推奨します。

1. 機能ブランチごとにワークツリーを作成します。
2. その機能に限定した変更のみを実装します。
3. PR の前に、リポジトリの品質ゲートを実行します。
4. インテグレーションブランチに、対象を絞った PR を 1 つ作成します。

リポジトリにスクリプト（例：scripts/git/feature-workflow.sh）がある場合は、このループを徹底するために使用します。

ローカルの安全確認（チェックアウト／マージ／コミットの前）

エージェント主導の作業中によくあるローカルの Git に関する障害を避けるため、次の手順をすばやく確認します。

1. 作業ツリーの状態を確認します。

• git status --porcelain
• 出力が空でない場合は、明示的に判断します。コミットする、スタッシュする、またはブランチの切り替えを中止します。

2. ロック／プロセスを確認します。

• Git コマンドが index.lock で失敗する場合は、まず実行中の Git プロセスを確認します。
  • test -f .git/index.lock && ps aux | rg "[g]it"
• アクティブな Git プロセスがないことを確認してから、古いロックを削除します。

3. ブランチ切り替え時のガード：

• ローカルの変更が上書きされる場合は、checkout／switch を実行しないでください。
• 意図的にコミットまたはスタッシュし、コンテキストを誤って失わないようにします。

4. マージコンフリクトの手順：

• コンフリクトが発生したら、新たな編集を中止し、ファイルごとに解決して、関連するテストを再実行してからマージコミットを完了します。

5. 自動化に関する注意：

• ブランチ操作を繰り返し行う場合は、その場しのぎでローカルブランチを切り替えるのではなく、プロジェクトのスクリプトやワークツリーを優先します。

判断フロー：ブランチ戦略の選択

Use this decision tree to select the optimal branching strategy for your team based on team size, release cadence, and CI/CD maturity.

Team characteristics -> What's your situation?
    ├─ Small team (1-5 devs) + Continuous deployment + High CI/CD maturity?
    │   └─ GitHub Flow (main + feature branches)
    │
    ├─ Medium team (5-15 devs) + Continuous deployment + High CI/CD maturity?
    │   └─ Trunk-Based Development (main + short-lived branches)
    │
    ├─ Large team (15+ devs) + Continuous deployment + Very high CI/CD maturity?
    │   └─ Trunk-Based + Feature Flags (progressive rollout)
    │
    ├─ Scheduled releases + Medium CI/CD maturity?
    │   └─ GitFlow (main + develop + release branches)
    │
    └─ Multiple versions + Low-Medium CI/CD maturity?
        └─ GitFlow (long-lived release branches)

ナビゲーション：主要なワークフロー

ブランチ戦略

ブランチ戦略の比較 - ブランチ戦略の選択と導入に関する包括的なガイド

• GitHub Flow（モダンなチームにおすすめ）：シンプルで、継続的にデプロイできます
• Trunk-Based Development（エンタープライズ規模）：短命なブランチを使い、毎日マージします
• GitFlow（体系的なリリース）：定期的なリリースと複数バージョンに対応します
• 判断マトリクス：チームの規模、リリースの頻度、CI/CD の成熟度
• 戦略間の移行パス

プルリクエストのベストプラクティス

PR のベストプラクティスガイド - 効果的なコードレビューと迅速な PR サイクル

• PR のサイズに関するガイドライン：レビューしやすいサイズを保ちます（多くの場合、200～400 LOC が適切です。大きな変更は分割します）
• レビューのカテゴリ：BLOCKER、WARNING、NITPICK
• レビューのエチケット：協力的なフィードバック、コード例
• PR の説明テンプレート：内容、理由、方法、テスト
• レビュー効率に関するデータに基づいた分析

コミット規約

Conventional Commits 標準 - コミットメッセージの形式とセマンティックバージョニングの連携

• Conventional Commits の形式：type(scope): description
• コミットの種類：feat、fix、BREAKING CHANGE、refactor、docs
• SemVer の自動化：コミットからバージョンを自動更新します
• 変更履歴の生成：コミット履歴から自動生成します
• ツール：commitlint、semantic-release、standard-version

---

ナビゲーション：高度なテクニック

スタック型差分

スタック型差分の実装 - プラットフォーム固有のワークフローとチームへの導入

• スタック型差分とは：大規模な機能をレビューしやすい単位に分割します
• 使用する場面：500 行を超える機能、複雑なリファクタリング
• GitLab のネイティブサポート：MR チェーン
• Graphite を使った GitHub：CLI ベースのスタッキング
• メリット：レビューサイクルを 60% 高速化し、品質を向上させます

インタラクティブリベース

インタラクティブリベースと履歴の整理 - クリーンなコミット履歴を維持します

• 自動スカッシュのワークフロー：fixup! および squash! コミット
• インタラクティブリベースのコマンド：pick、reword、edit、squash、fixup、drop
• コミットの分割：大きなコミットを目的の明確な変更に分割します
• コミットの並べ替え：論理的なコミット履歴
• ベストプラクティス：公開ブランチは絶対にリベースしないでください

コンフリクトの解決

コンフリクト解決のテクニック - マージ戦略とコンフリクトへの対処

• 解決戦略：--ours、--theirs、手動マージ
• リベースとマージ：それぞれを使う場面
• マージツールのセットアップ：VS Code、Meld、カスタムツール
• コンフリクトマーカー：<<<<<<<、=======、>>>>>>> の理解
• 予防策：頻繁なリベース、小規模な PR

---

ナビゲーション：自動化と品質

自動品質ゲート

自動品質ゲート - CI/CD パイプラインと品質の徹底

• 必須のゲート：テスト、カバレッジ、リンティング、セキュリティスキャン
• 高度なゲート：パフォーマンスベンチマーク、バンドルサイズ、アクセシビリティチェック
• GitHub Actions のワークフロー：PR チェックの完全なパイプライン
• GitLab CI パイプライン：MR の品質ゲート
• コミット前フック：Husky と lint-staged のセットアップ
• 品質メトリクスのしきい値：カバレッジ 80%、複雑度 < 10

検証チェックリスト

検証チェックリスト - PR 前、マージ前、リリース前のチェックリスト

• PR の作成前：コード品質、コミットの整理、テスト
• PR のマージ前：レビュープロセス、CI/CD チェック、最終確認
• リリース前：リリース前テスト、バージョン管理、ドキュメント
• デプロイ後：即時確認、モニタリング、タスク
• ホットフィックスのチェックリスト：重大なバグに迅速に対処するプロセス

リリース管理

リリース管理 - バージョン管理とデプロイのワークフロー

• セマンティックバージョニング：MAJOR.MINOR.PATCH
• 手動リリースのワークフロー：GitFlow のリリースブランチ
• 自動リリース：semantic-release による自動化
• ホットフィックスのワークフロー：緊急パッチ
• 変更履歴の生成：Keep a Changelog 形式
• リリースチェックリスト：リリース前、リリース当日、リリース後

---

ナビゲーション：学習とトラブルシューティング

モノレポのワークフロー

モノレポのワークフロー - モノレポのリポジトリで使う Git のパターン

• モノレポ向けのトランクベース開発
• スパースチェックアウトと部分クローン
• 影響を受ける箇所のみの CI（Nx、Turborepo、Bazel）
• パッケージ／ディレクトリごとの CODEOWNERS
• モノレポとポリレポの比較表

Git フックの自動化

Git フックの自動化 - pre-commit、commit-msg、pre-push フック

• Husky v9+ と lefthook のセットアップ
• lint-staged と commitlint の統合
• カスタムフック（gitleaks、ファイルサイズの制限、ブランチ名）
• チームへの配布戦略

Git Bisect によるデバッグ

Git Bisect によるデバッグ - git bisect を使ったリグレッションの特定

• 手動および自動の bisect ワークフロー
• bisect テストスクリプトの作成
• マージコミット、ログ、リプレイの処理

よくある間違い

よくある間違いと修正方法 - よくある落とし穴から学びましょう

• 大規模で焦点の定まらない PR → スタックされた差分に分割する
• あいまいなコミットメッセージ → Conventional Commits を使う
• 公開履歴の書き換え → main をリベースしない
• レビューコメントの無視 → すべてのフィードバックに対応する
• シークレットのコミット → 環境変数を使う
• 強制プッシュの危険性 → --force-with-lease を使う

判断表

各ブランチ戦略の使いどころ

要件	GitHub Flow	Trunk-Based	GitFlow
継続的デプロイ	[OK] 最適	[OK] 最適	[FAIL] 不向き
スケジュールされたリリース	[WARNING] 可	[WARNING] 可	[OK] 最適
複数バージョン	[FAIL] 不向き	[FAIL] 不向き	[OK] 最適
小規模チーム（< 5）	[OK] 最適	[WARNING] 可	[FAIL] 過剰
大規模チーム（> 15）	[WARNING] 可	[OK] 最適	[WARNING] 可
高速なイテレーション	[OK] 最適	[OK] 最適	[FAIL] 不向き

PR のサイズとレビュー時間

LOC	レビュー時間	バグ検出率	推奨事項
< 50	< 10 min	高	[OK] ホットフィックスに最適
50-200	10-30 min	高	[OK] 機能追加に最適
200-400	30-60 min	中～高	[OK] 許容範囲
400-1000	1-2 hours	中	[WARNING] 分割を検討
> 1000	> 2 hours	低	[FAIL] 必ず分割

推奨事項／避けるべきこと

推奨：実施すること

• PR を 400 行未満に保つ（200～400 行が最適）
• Conventional Commits のコミットメッセージを使う
• PR を開く前にリベースする（履歴を整理する）
• マージ前に少なくとも 1 件の承認を必須にする
• すべての PR で CI チェックを実行する
• 大規模な機能（>500 LOC）にはスタックされた差分を使う
• マージ前に WIP コミットをスカッシュする
• --force ではなく --force-with-lease を使う

避ける：しないこと

• 長期間存続するフィーチャーブランチ（>3 日）
• レビューなしでのマージ
• 公開／共有ブランチのリベース
• main/master への強制プッシュ
• シークレットのコミット（「一時的」であっても）
• 大規模で一枚岩の PR（>1000 行）
• あいまいなコミットメッセージ（「fix」「update」）
• マージを早めるために CI をスキップする

アンチパターン

アンチパターン	問題	修正方法
長期間存続するブランチ	マージコンフリクト、古いコード	トランクベース開発、短命なブランチ
未レビューのマージ	バグが本番環境に到達する	ブランチ保護ルール
main のリベース	履歴の破損	公開ブランチは決してリベースしない
1000+ LOC の PR	レビューの品質低下	スタックされた差分、PR の分割
「fix」コミット	不明瞭な履歴	Conventional Commits
CI ゲートなし	main の破損	必須のステータスチェック
履歴内のシークレット	セキュリティ侵害	pre-commit フック、gitleaks

リポジトリの基本設定（セキュリティ＋信頼性）

チームを拡大する前に、リポジトリのデフォルト設定を行います。

• ブランチ保護：main への PR を必須にします（直接プッシュは禁止）。ステータスチェックを必須にし、マージ時にブランチが最新であることを必須にします。
• レビューのゲート：承認を必須にします。機密性の高いパス（認証、支払い、インフラ、本番環境の設定）には CODEOWNERS を適用します。
• 履歴ポリシー：マージ戦略（スカッシュかマージコミットか）を選び、一貫して適用します。例外は文書化します。
• 変更への署名：リリースには署名付きコミットと署名付きタグを必須にします（鍵管理はチームごとに行います）。
• シークレットの流出防止：ローカルのコミット前フックとサーバー側のシークレットスキャン／プッシュ保護を導入します。インシデント発生時にはローテーションします。
• マージの安全性：負荷の高いリポジトリでは、マージキュー（または同等の仕組み）を使い、高い同時実行時にも main を正常な状態に保ちます。
• コスト管理：依存関係とビルドをキャッシュします。重いジョブは条件付きで実行し、信頼されていないフォークの CI 実行時間に上限を設けます。

テンプレート：assets/pull-requests/pr-template.md ガイド：assets/template-git-workflow-guide.md

セキュリティ上重要な変更

セキュリティ関連の git 操作については、git-commit-message/assets/template-security-commits.md を参照してください。

• コミット前フックによるシークレットの検出
• シークレットを誤ってコミットした場合の対処
• セキュリティコミットのメタデータ（CVE、CVSS）
• セキュリティ上重要なコードのブランチ保護

オプション：AI／自動化

注：AI ツールは作業を支援しますが、マージの判断において人間の判断に取って代わることはできません。

• PR の要約 - コミットから説明を生成します
• 変更リスクのラベル付け - リスクの高いファイル（認証、支払い）にフラグを付けます
• レビューの提案 - レビュアー候補を特定します

限定的な主張

• AI による要約は、人間による確認が必要です
• リスクラベルは提案であり、保証ではありません
• マージの判断には、常に人間の承認が必要です

---

関連スキル

• ソフトウェアコードレビュー - コードレビューの基準と手法
• 品質デバッグ - Git bisect、デバッグのワークフロー
• DevOps プラットフォームエンジニアリング - CI/CD パイプライン、自動化
• ソフトウェアテストと自動化 - テスト駆動開発、カバレッジのゲート
• ドキュメント標準 - 変更履歴の形式、ドキュメントのワークフロー
• Git コミットメッセージ - コミットメッセージの規約、セキュリティコミット

使用上の注意

Claude Code 向け：

• ほとんどの現代的なチームには、シンプルで効果的な GitHub Flow を推奨します
• 500 行を超える機能には、スタック差分を提案します
• コミットメッセージが Conventional Commits の形式に準拠しているか、必ず検証します
• PR のサイズを確認し、400 行を超える場合は警告、1000 行を超える場合はブロックします
• コピーしてすぐ使える設定には assets/ を参照します
• 詳細な実装ガイダンスには references/ を使用します

段階的な開示：

1. 素早く情報を確認するには、クイックリファレンスから始めます
2. 戦略を選ぶには、判断ツリーを使います
3. 詳細な実装については、該当するリソースを確認します
4. 本番環境ですぐ使える設定には、テンプレートを参照します
5. PR／マージ／リリースの前に、検証チェックリストを確認します

---

クイックコマンドリファレンス

一般的な操作：

# Rebase feature branch
git fetch origin && git rebase origin/main

# Interactive rebase last 3 commits
git rebase -i HEAD~3

# Squash all commits in branch
git rebase -i $(git merge-base HEAD main)

# Force push safely
git push --force-with-lease origin feature-branch

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Cherry-pick specific commit
git cherry-pick abc123

# Stash changes
git stash push -m "WIP: implementing feature X"
git stash pop

コンフリクトの解決：

# Pull latest with rebase
git pull --rebase origin main

# Use visual merge tool
git mergetool

# Accept their changes
git checkout --theirs <file>

# Accept your changes
git checkout --ours <file>

トレンド確認プロトコル

重要：Git のワークフロー、ブランチ戦略、コラボレーションツールについて、ユーザーから推奨を求められた場合は、回答する前にウェブ検索（および／または data/sources.json 内のリンク）で最新のトレンドを確認してください。

該当する質問

• 「［チーム規模／ユースケース］には、どの Git ワークフローが最適ですか？」
• 「［ブランチ／PR 管理］には何を使うべきですか？」
• 「Git のコラボレーションで、最近の動向は何ですか？」
• 「［ブランチ戦略／コードレビュー］の現在のベストプラクティスは何ですか？」
• 「［GitFlow／トランクベース開発］は2026年でも有効ですか？」
• 「［GitHub Flow］と［トランクベース開発］と［GitFlow］では、どれがよいですか？」
• 「PR のスタッキングに最適なツールは何ですか？」

必須の検索

1. 検索："Git workflow best practices 2026"
2. 検索："[specific strategy] vs alternatives 2026"
3. 検索："Git collaboration trends January 2026"
4. 検索："[branching/PR tools] comparison 2026"

報告する内容

検索後、以下を提示してください。

• 現在の状況：現在人気のある Git ワークフロー／ツール
• 新たなトレンド：普及が進んでいる新しいコラボレーションパターン、ツール、プラクティス
• 非推奨／衰退傾向：重要性やサポートが低下している戦略／ツール
• 推奨事項：固定的な知識ではなく、最新のデータに基づくもの

トピックの例（最新の検索結果で確認）

• ブランチ戦略（Trunk-Based、GitHub Flow、GitFlow）
• PR スタッキングツール（Graphite、git-stack、Stacked PRs）
• マージキューの実装（GitHub、GitLab）
• コードレビューのプラットフォームと自動化
• Conventional Commits と変更履歴ツール
• Git ホスティングプラットフォームの機能（GitHub、GitLab、Bitbucket）
• AI 支援型 Git ワークフロー