Git workflow

Git運用・ブランチ戦略

目的

チームとAIエージェントが同一リポジトリで安全に協調するための運用ルールを定める。 コンフリクト・意図不明コミット・壊れたmainを防ぎ、レビューコストを下げる。

使うタイミング

• 新規リポジトリのブランチ戦略・運用ルールを決めるとき
• PRが大きすぎる・コミット粒度が荒いなどチームで問題が出ているとき
• AIエージェントを複数並列で走らせるとき(ブランチ/worktree設計)
• CI/CDパイプラインと連動したリリースフローを整備するとき([[cicd-deployment]])

ブランチ戦略の選択

戦略	採用基準	注意
GitHub Flow	Webサービス・個人開発・SaaS。デフォルト推奨	main+短命featureブランチのみ。シンプルで十分
Git Flow	複数バージョンを同時保守するパッケージ製品	develop/release/hotfixが必要な場合のみ採用。多くの場面で過剰
Trunk-based	高頻度デプロイ・フィーチャーフラグが整備済みの組織	CI品質・フィーチャーフラグ運用が前提。未整備なら先にそちらを整える

迷ったら GitHub Flow を選ぶ。Git Flowは採用コストに見合うか必ず検討する。

進め方

1. ブランチ戦略を選択する — 上表の基準で1つ決め、チームに明示する
2. リポジトリ保護ルールを設定する — mainへの直pushを禁止、PR必須、ステータスチェック必須
3. ブランチ命名規則を決める — feat/, fix/, chore/ プレフィックス + issue番号(例: feat/123-user-auth)
4. コミット規約を導入する — Conventional Commitsを採用、CIでlintする
5. PRテンプレートを作成する — .github/pull_request_template.md を配置
6. マージ方式を統一する — squashを基本とし、例外ルールを明文化する
7. 新規メンバー/エージェントへの周知 — CONTRIBUTING.md またはCLAUDE.mdに上記を記載する

設計の要点

コミット

• 1コミット1意図: 機能追加とリファクタリングを混ぜない
• Conventional Commits: feat:, fix:, refactor:, docs:, test:, chore:, perf: を使う
• bodyに「なぜ」を書く: 「何をしたか」はdiffを見ればわかる。判断の理由・背景を残す
• WIPコミットはマージ前に整理: git rebase -i でまとめるか、squashマージで吸収する
• メッセージ例: fix: カート合計が0になるバグを修正 + body 割引クーポン適用時にtaxの計算順が逆転していたため

ブランチ

• 短命に保つ: 目安は1〜3日でマージ。長引くほどコンフリクトリスクが増大
• mainを毎日取り込む: git fetch && git rebase origin/main を習慣化
• 大きい機能はフィーチャーフラグで分割: 未完成のままmainにマージし、フラグで非活性化する
• 作業領域をファイル構成で分ける: 同一ファイルへの並行修正はコンフリクトの温床

PR運用

• 400行以下を目安: 超える場合は分割を検討。[[code-review]] と連携
• ドラフトPRを早めに出す: WIP状態でも方向性のフィードバックを受ける
• 説明テンプレートを埋める: 何を・なぜ・確認方法・スクリーンショット(UI変更時)
• 1PRは1つの関心事: 機能追加とバグ修正を同一PRに混ぜない

マージ方式

方式	使いどころ
Squash merge	featureブランチ(デフォルト)。細かいWIPコミットをmainに持ち込まない
Merge commit	ブランチ履歴を保持したい場合(リリースブランチ→mainなど)
Rebase	線形履歴が必要な場合。共有ブランチには使わない

リポジトリ内で方式を統一する。混在は混乱の原因。

成果物テンプレート

# リポジトリ運用ルール

## ブランチ戦略
GitHub Flow(main + 短命featureブランチ)

## ブランチ命名
- feat/<issue番号>-<概要>
- fix/<issue番号>-<概要>
- chore/<概要>
- release/<バージョン>  # リリースブランチが必要な場合のみ

## コミット規約(Conventional Commits)
形式: <type>(<scope>): <概要>
type: feat / fix / refactor / docs / test / chore / perf
- bodyに変更の理由を記載する
- WIPコミットはPRマージ前に整理する

## PRルール
- 400行以下を目安に分割する
- .github/pull_request_template.md のテンプレートを必ず埋める
- レビュアーを最低1名指定する
- CIが通過するまでマージしない

## PRテンプレート (.github/pull_request_template.md)
### 何を変えたか
### なぜ変えたか
### 確認方法
### スクリーンショット(UI変更時)

## マージ方式
- featureブランチ → main: Squash merge
- その他: Merge commit

## 保護ルール(main)
- 直pushを禁止
- PR必須(1名以上の承認)
- ステータスチェック必須(CI通過)
- force pushを禁止

チェックリスト

• ブランチ戦略を選択し、チームに明示した
• mainブランチの保護ルールを設定した(直push禁止・PR必須)
• ブランチ命名規則を決めた
• Conventional Commitsを導入し、CIでlintする設定をした
• PRテンプレートを配置した(.github/pull_request_template.md)
• マージ方式をリポジトリで統一した
• .gitignore に .env・秘密情報ファイルを含めた
• CONTRIBUTING.md またはCLAUDE.mdに運用ルールを記載した

アンチパターン

• 巨大PR: 1000行超のPRはレビューが形骸化する。分割必須
• 意味のないコミットメッセージ: fix・update・wip だけでは意図がわからない
• 数週間生きるfeatureブランチ: コンフリクトが大量発生し、マージに数日かかる
• mainが壊れた状態の放置: ビルド失敗・テスト失敗を放置すると全員の開発が止まる
• .envファイルのコミット: 漏れた場合は履歴削除でなくキーのローテーションが正解([[security]])
• 共有ブランチへのforce push: チームメンバーの作業を消す危険がある
• mainへの直push: 保護ルールで物理的に禁止する

モデル委譲ガイド

共通原則は [[orchestration]] を参照。

役割	担当	Git運用における作業例
司令塔(メインモデル)	意思決定・統合	ブランチ戦略の選択、コンフリクト解決の判断、エージェント作業の統合とmainへのマージ
Opus相当	複雑な実働	コンフリクトの複雑な解決、運用ルール文書のドラフト、既存履歴の整理(rebase設計)
Sonnet相当	通常の実働	PRテンプレート作成、CONTRIBUTING.md作成、コミットメッセージの整形、差分レビュー補助
Haiku相当	軽作業	ブランチ一覧の取得、コミットログの要約、ファイル変更状況の確認

AIエージェント並列開発時のブランチ/worktree運用

複数エージェントが同一リポジトリで並列開発する場合、エージェントごとにgit worktreeで作業領域を分離する。

# 司令塔がエージェント用worktreeを事前に作成する
git worktree add ../agent-api feat/agent-api-layer
git worktree add ../agent-db feat/agent-db-schema
git worktree add ../agent-test feat/agent-test-suite

# エージェントはそれぞれ自分のworktreeパスのみ操作する
# 統合は司令塔がレビュー後にmainへマージする

• インターフェースを固定してから並列化: APIの型・関数シグネチャを先に決め、司令塔がCLAUDE.mdに記録してから各エージェントに作業を委譲する
• 同一ファイルへの並行書き込み禁止: ファイル担当をエージェント間で重複させない
• 統合は司令塔が行う: 各エージェントのブランチを司令塔がレビュー → squash merge → 次の作業を委譲する順序を守る

関連スキル

• [[orchestration]] — 複数エージェント協調の共通原則
• [[code-review]] — PRレビューの観点と自動化
• [[security]] — 秘密情報漏洩時の対応、.gitignore設計
• [[cicd-deployment]] — タグ・リリース運用、CI設定との連携
• [[implementation]] — 実装フェーズのコミット粒度管理
• [[solo-development]] — 個人開発でのシンプルなGit運用
• [[project-management]] — ブランチとissue/マイルストーンの連携