Git ワークフローとバージョニング

概要

Git はあなたのセーフティネットです。コミットをセーブポイント、ブランチをサンドボックス、履歴をドキュメントとして扱ってください。AI エージェントが高速でコードを生成する環境では、変更管理、レビュー可能性、巻き戻し可能性を確保する仕組みとして、厳格なバージョン管理が重要です。

使用時期

常に使用します。すべてのコード変更は Git を通じて行われます。

コア原則

トランクベースの開発(推奨)

main は常にデプロイ可能な状態に保ちます。短命なフィーチャーブランチで作業し、1～3 日以内にマージバックします。長命な開発ブランチは隠れたコスト — 分岐し、マージコンフリクトを生じさせ、統合を遅延させます。DORA の研究では、トランクベース開発がハイパフォーマンスエンジニアリングチームと一貫して相関することが示されています。

main ──●──●──●──●──●──●──●──●──●──  (常にデプロイ可能)
        ╲      ╱  ╲    ╱
         ●──●─╱    ●──╱    ← 短命なフィーチャーブランチ (1-3 日)

これが推奨デフォルトです。gitflow や長命なブランチを使用するチームは、原則(アトミックコミット、小さな変更、記述的なメッセージ)を自分たちのブランチングモデルに適応させることができます — コミットの厳格さが、特定のブランチング戦略よりも重要です。

• 開発ブランチはコスト。 ブランチが生きている毎日、マージリスクが蓄積します。
• リリースブランチは許容可。 main を前に進めながらリリースを安定化させる必要がある場合。
• フィーチャーフラグ > 長命なブランチ。 数週間ブランチに置いておくのではなく、フラグの後ろで不完全な作業をデプロイすることを優先してください。

1. 早期かつ頻繁にコミット

各成功した増分は独自のコミットを取得します。大きなコミットされていない変更を蓄積しないでください。

作業パターン:
  実装スライス → テスト → 検証 → コミット → 次のスライス

これではなく:
  すべてを実装 → 動くことを祈る → 巨大なコミット

コミットはセーブポイントです。次の変更が何かを壊した場合、最後の既知の良好な状態に即座に戻せます。

2. アトミックコミット

各コミットは 1 つの論理的なことを行います:

# 良い: 各コミットが自己完結している
git log --oneline
a1b2c3d タスク作成エンドポイントを追加(検証付き)
d4e5f6g タスク作成フォームコンポーネントを追加
h7i8j9k フォームを API に接続しローディング状態を追加
m1n2o3p タスク作成テストを追加(ユニット + 統合)

# 悪い: すべてが混在している
git log --oneline
x1y2z3a タスク機能を追加、サイドバーを修正、依存関係を更新、ユーティリティをリファクター

3. 記述的なメッセージ

コミットメッセージは「何」だけでなく「なぜ」を説明します:

# 良い: 意図を説明している
feat: 登録エンドポイントにメール検証を追加

無効なメール形式がデータベースに到達するのを防ぎます。
ルートハンドラレベルで Zod スキーマ検証を使用し、
auth.ts の既存の検証パターンと一貫性があります。

# 悪い: diff から明らかなことを説明している
auth.ts を更新

形式:

<type>: <短い説明>

<オプション: why を説明する本文(what ではなく)>

タイプ:

• feat — 新機能
• fix — バグ修正
• refactor — バグ修正でも機能追加でもないコード変更
• test — テストの追加または更新
• docs — ドキュメントのみ
• chore — ツール、依存関係、設定

4. 関心事を分離

フォーマット変更と動作変更を混在させないでください。リファクタリングと機能を混在させないでください。各種の変更は別のコミット — 理想的には別の PR である必要があります:

# 良い: 関心事を分離
git commit -m "refactor: 検証ロジックを共有ユーティリティに抽出"
git commit -m "feat: 登録に電話番号検証を追加"

# 悪い: 関心事が混在
git commit -m "refactor: 検証とフォン番号フィールドを追加"

リファクタリングと機能作業を分離します。 リファクタリング変更と機能変更は 2 つの異なる変更です — 別々に提出してください。これにより、各変更をレビュー、巻き戻し、履歴の理解が容易になります。小さなクリーンアップ(変数名の変更)は、レビュアーの判断で機能コミットに含めることができます。

5. 変更のサイズを調整

1 コミット/PR あたり約 100 行を目標にしてください。約 1000 行を超える変更は分割する必要があります。大きな変更を分割する方法については、code-review-and-quality の分割戦略を参照してください。

~100 行  → レビュー容易、巻き戻し容易
~300 行  → 単一の論理的変更として許容
~1000 行 → より小さな変更に分割

ブランチング戦略

フィーチャーブランチ

main (常にデプロイ可能)
  │
  ├── feature/task-creation    ← 1 つのブランチに 1 つの機能
  ├── feature/user-settings    ← 並列作業
  └── fix/duplicate-tasks      ← バグ修正

• main (またはチームのデフォルトブランチ)から分岐
• ブランチを短命に保つ(1～3 日以内にマージ) — 長命なブランチは隠れたコスト
• マージ後にブランチを削除
• 不完全な機能に対して長命なブランチよりフィーチャーフラグを優先

ブランチ命名

feature/<短い説明>     → feature/task-creation
fix/<短い説明>         → fix/duplicate-tasks
chore/<短い説明>       → chore/update-deps
refactor/<短い説明>    → refactor/auth-module

Worktree の使用

AI エージェントの並列作業の場合、git worktree を使用して複数のブランチを同時に実行します:

# フィーチャーブランチの worktree を作成
git worktree add ../project-feature-a feature/task-creation
git worktree add ../project-feature-b feature/user-settings

# 各 worktree は独自のブランチを持つ別のディレクトリ
# エージェントは干渉なく並列に作業できます
ls ../
  project/              ← main ブランチ
  project-feature-a/    ← task-creation ブランチ
  project-feature-b/    ← user-settings ブランチ

# 完了したら、マージしてクリーンアップ
git worktree remove ../project-feature-a

メリット:

• 複数のエージェントが異なる機能に同時に作業できます
• ブランチ切り替えが不要(各ディレクトリは独自のブランチ)
• 1 つの実験が失敗しても、worktree を削除 — 何も失われません
• 変更は明示的にマージされるまで分離されています

セーブポイントパターン

エージェントが作業を開始
    │
    ├── 変更を加える
    │   ├── テストが成功? → コミット → 続行
    │   └── テストが失敗? → 最後のコミットに戻す → 調査
    │
    ├── 別の変更を加える
    │   ├── テストが成功? → コミット → 続行
    │   └── テストが失敗? → 最後のコミットに戻す → 調査
    │
    └── 機能が完成 → すべてのコミットがきれいな履歴を形成

このパターンは、作業の 1 増分を超えて失うことがないことを意味します。エージェントが線路から外れた場合、git reset --hard HEAD で最後に成功した状態に戻ります。

変更サマリー

任意の修正後に、構造化されたサマリーを提供します。これにより、レビューが容易になり、スコープ規律が文書化され、意図しない変更が浮かび上がります:

変更内容:
- src/routes/tasks.ts: POST エンドポイントに検証ミドルウェアを追加
- src/lib/validation.ts: Zod を使用して TaskCreateSchema を追加

意図的に触らなかったもの:
- src/routes/auth.ts: 同様の検証ギャップがありますがスコープ外
- src/middleware/error.ts: エラー形式は改善可能(別タスク)

潜在的な懸念:
- Zod スキーマは厳密 — 余分なフィールドを拒否します。これが望ましいか確認してください。
- zod を依存関係として追加(gzip で 72KB) — すでに package.json にあります

このパターンは、間違った仮定を早期に発見し、レビュアーに変更の明確なマップを提供します。「DIDN'T TOUCH」セクションは特に重要 — スコープ規律を発揮し、不招請のリノベーションに行かなかったことを示しています。

コミット前のハイジーン

すべてのコミット前に:

# 1. コミットしようとしているものを確認
git diff --staged

# 2. シークレットがないことを確認
git diff --staged | grep -i "password\|secret\|api_key\|token"

# 3. テストを実行
npm test

# 4. リント を実行
npm run lint

# 5. 型チェックを実行
npx tsc --noEmit

git フックで自動化します:

// package.json (lint-staged + husky を使用)
{
  "lint-staged": {
    "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{json,md}": ["prettier --write"]
  }
}

生成されたファイルの処理

• 生成されたファイルをコミット するのは、プロジェクトがそれらを想定している場合のみ(例: package-lock.json、Prisma マイグレーション)
• コミットしない: ビルド出力(dist/、.next/)、環境ファイル(.env)、IDE 設定(共有されていない限り .vscode/settings.json)
• .gitignore を持つ: node_modules/、dist/、.env、.env.local、*.pem をカバーするもの

デバッグに Git を使用

# バグを導入したコミットを見つける
git bisect start
git bisect bad HEAD
git bisect good <既知の良好なコミット>
# Git が中点をチェックアウト; 各ポイントでテストを実行してナローダウン

# 最近何が変わったかを見る
git log --oneline -20
git diff HEAD~5..HEAD -- src/

# 特定の行を最後に変更した人を見つける
git blame src/services/task.ts

# キーワードのコミットメッセージを検索
git log --grep="validation" --oneline

一般的な言い訳

言い訳	現実
「機能が完成したらコミットする」	1 つの巨大なコミットはレビュー、デバッグ、巻き戻しが不可能です。各スライスをコミットしてください。
「メッセージは重要ではない」	メッセージはドキュメントです。未来のあなた(と未来のエージェント)は、何が変わり、なぜかを理解する必要があります。
「後で全部スカッシュしる」	スカッシュは開発ナラティブを破壊します。最初からきれいな増分コミットが良いです。
「ブランチはオーバーヘッドを追加する」	短命なブランチは無料で、競合する作業が衝突するのを防ぎます。長命なブランチが問題 — 1～3 日以内にマージしてください。
「これを後で分割する」	大きな変更はレビュー難、デプロイ難、巻き戻し難です。提出前に分割し、後ではなく。
「.gitignore は不要」	本番シークレット付きの .env がコミットされるまで。すぐにセットアップしてください。

赤旗

• 大きなコミットされていない変更が蓄積している
• 「fix」「update」「misc」などのコミットメッセージ
• フォーマット変更と動作変更が混在している
• プロジェクトに .gitignore がない
• node_modules/、.env、またはビルド成果物をコミットしている
• main から大きく分岐した長命なブランチ
• 共有ブランチへの強制プッシュ

検証

すべてのコミットについて:

• コミットが 1 つの論理的なことを行う
• メッセージが why を説明し、型規則に従う
• コミット前にテストが成功している
• diff にシークレットがない
• フォーマットのみの変更が動作変更と混在していない
• .gitignore が標準除外をカバーしている