# Git 開発フロー・トラブルシューティング (Git Workflow Reference)

`/commit` の実行フェーズ（ops-runner が担当）で参照する実行手順・push・PR・マージの詳細手順と，問題発生時の対処手順．
ブランチ命名・コミットメッセージ等の規約は `.claude/rules/git-conventions.md` に従う．

## コミット実行手順 (Commit Execution Flow)

`/commit` の司令塔（メインループ）から委譲された ops-runner が実行する手順．ユーザーへの確認は不要，全ステップを一気に実行する（停止条件に該当した場合を除く）．

### ステップ 1: 状態確認

- `git branch --show-current` で現在のブランチを確認
- `git status` で変更ファイルの一覧を確認
- `git diff` および `git diff --cached` で変更内容を確認
- 変更がない場合（クリーン）は空コミットせず，その旨を報告して終了する

**main ブランチにいる場合は自動でブランチを作成する:**

1. 司令塔からブランチ名が渡されていればそれを使う．渡されていなければ，変更内容から git-conventions のブランチ命名規則に従い適切なプレフィックスと英単語 2〜4 語のブランチ名を決め，決めた名前を報告に含める
2. `git checkout -b {ブランチ名}` で作業ブランチを作成する

### ステップ 2: ドキュメント関連の事実収集

docs 更新の要否の**判断はしない**（司令塔が行う）．以下の事実を最終報告の「事実報告」に含める:

- `.claude/commit-context.md` の有無と，あれば記録されたフラグ（`docs_updated` / `claude_md_updated` / `progress_md_updated`）
- 変更ファイルの分類: `docs/` 配下・`CLAUDE.md`・`docs/PROGRESS.md` のそれぞれを含むか，およびそれ以外の変更ファイル一覧

### ステップ 3: コミットメッセージの生成

上位から渡された意図サマリ・引数と変更内容をもとに，git-conventions の「コミットメッセージ」書式で生成する．上位がメッセージ全文を確定して渡した場合はそのまま使う．意図サマリと実際の diff に食い違いがある場合は，diff を正としつつ食い違いを「警告」に含める．

### ステップ 4: コミット

1. `git add` で関連ファイルをステージングする（CLAUDE.md / `docs/PROGRESS.md` の変更がある場合はそれも含める．`.env` やクレデンシャルファイルはステージングしない）
2. `git commit -m "{コミットメッセージ}"` でコミットする
3. `.claude/commit-context.md` が存在する場合は削除する

### ステップ 5: プッシュ・PR・マージ

上位から渡された引数に以下のキーワードが含まれる場合のみ実行する（いずれも無ければスキップ）．

| キーワード | 実行する操作 |
| --- | --- |
| `push` | プッシュ・PR 作成 |
| `merge` | プッシュ・PR 作成・マージ・プル（`push` を含む全操作） |

手順は後述「開発フロー」に従う（push → PR 作成（既存 PR があれば URL の確認のみ）→ `merge` の場合はマージの実行 → ローカル環境のクリーンアップ）．コンフリクト等の問題が起きた場合は「トラブルシューティング」を参照し，意味的な衝突の解消や force push を伴う操作は停止して報告する．

## 開発フロー (Development Workflow)

作業ブランチをリモートへ送り，`main` にマージされるまでの手順．

### リモートへのプッシュ

作業ブランチをリモートリポジトリへ送信する．

```bash
git push origin feature/new-function
```

### プルリクエスト (PR) の作成

GitHub CLI (`gh`) を使用して PR を作成する．

```bash
gh pr create --title "[add] 新機能を実装" --body "概要"
```

- `--title` はコミットメッセージと同じ書式（`[タグ] 内容`）とする．
- 必要に応じて `--reviewer` でレビュワーを指定する．

### レビューと修正の対応

- レビュワーのコメントを確認し，修正が必要な場合はローカルで修正・コミット・プッシュを繰り返す．
- 全ての指摘に対応し，レビュワーから Approve をもらう．

### マージの実行

- マージ方式は「Create a merge commit」を使用する（作業ブランチの全コミット履歴が `main` に残る）．
  - 「Squash and merge」「Rebase and merge」は使用しない．

```bash
gh pr merge --merge --delete-branch
```

### ローカル環境のクリーンアップ

マージ完了後はローカル環境も最新状態に戻し，古いブランチを削除する．

```bash
git checkout main
git pull origin main
git branch -d feature/new-function
```

## トラブルシューティング (Troubleshooting)

### コンフリクトが発生した場合

他メンバーの変更と競合した場合の対処手順．

**main の取り込み**

作業ブランチに `main` の最新内容をリベースして競合箇所を洗い出す．`merge` ではなく `rebase` を使うことで，履歴が線形に保たれレビューしやすくなる．

```bash
git checkout main
git pull origin main
git checkout feature/new-function
git rebase main
```

**競合の解消**

エディタ上で `<<<<<<<`，`=======`，`>>>>>>>` で囲まれた箇所を手動で修正する．修正後，以下のコマンドでリベースを続行する．

```bash
git add [修正したファイル]
git rebase --continue
```

**AI 補助によるコンフリクト解消**

Claude Code にコンフリクトを解消させる場合は，衝突の種類に応じて進め方を変える．

- **自明・テキスト的な衝突**（import の競合，隣接行の変更など，双方の意図が両立するもの）
  - AI が解消してよい．人間は解消結果の要点を確認するだけでよい．
- **意味的な衝突**（両側がロジックを非互換に変更しているもの）
  - AI に単一の解決結果を提示させて追認してはならない．AI は以下を提示し，人間が選択する．
    - 両側が各々何をしたかったか（自分の Issue と，相手のコミット・Issue の目的）
    - 解決候補を 2 つ以上と，各案を採った場合の帰結
    - 影響範囲と壊れうる箇所

解消後は衝突の種類によらず，必ずテスト（`/implement` の Tester）と作者による Phase 1 動作確認を行う．人間の判断は「どの意図が正しいか」を，テストは「実際に動くか」を担保するものであり，どちらか一方を省略してはならない．

**プッシュ**

全ての競合が解消されたらプッシュする．リベース後は履歴が書き換わるため通常の push は拒否されるが，他メンバーが push 済みの履歴を誤って上書きしないよう，`-f` ではなく `--force-with-lease` を用いる（自分が最後に fetch した時点のリモート状態と一致する場合のみ上書きし，ズレていれば拒否される）．

```bash
git push --force-with-lease origin feature/new-function
```

### 間違えて main にコミットしてしまった場合

**まだプッシュしていない場合**

コミットを取り消し，変更内容を保持したまま新しいブランチへ移動する．

```bash
git reset --soft HEAD^
git checkout -b feature/new-function
git commit -m "[add] ..."
```

**すでにプッシュしてしまった場合**

`main` への force push はチーム全員の履歴を壊す危険があるため，自分では対処しない．直ちにチームメンバーに報告し，全員で対応方針を決める．