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

開発フロー (Development Workflow)

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

リモートへのプッシュ

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

git push origin feature/new-function

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

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

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

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

レビューと修正の対応

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

マージの実行

• マージ方式は「Create a merge commit」を使用する（作業ブランチの全コミット履歴が main に残る）．
  • 「Squash and merge」「Rebase and merge」は使用しない．
• 先に main へ移ってからマージする．PR ブランチ上で --delete-branch を実行すると gh が暗黙に main への切替と pull を行い，ブランチ削除より前に pull が走る（post-merge hook 等の後処理が削除前の状態を見てしまう）．手順を明示的にして順序を固定する．

git checkout main
gh pr merge feature/new-function --merge --delete-branch   # リモート・ローカルのブランチも削除される

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

マージ完了後はローカルの main を最新化する（ブランチ削除の後に pull する順序を守る）．

git pull origin main
git branch -d feature/new-function   # gh が削除済みなら不要（残っていた場合のみ）

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

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

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

main の取り込み

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

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

競合の解消

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

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 した時点のリモート状態と一致する場合のみ上書きし，ズレていれば拒否される）．

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

gh コマンドが実行される前にブロックされた場合

gh pr merge 等が実行される前に遮断され，gh の出力が返ってこない場合は，auto mode のセキュリティ分類器によるブロックである．リポジトリ側の制約（ブランチ保護・必須レビュー・権限不足）とは原因が異なるため，混同して報告しない．

• 見分け方: リポジトリ側の制約ならコマンドは実行され gh がエラーメッセージを返す．分類器ブロックではコマンド自体が実行されない．
• 対処: .claude/settings.json の permissions.allow に Bash(gh pr merge:*) があるか確認する．無ければユーザーが手で追加し，セッションを再起動する（permissions の変更は再起動後に反映される．Claude 自身が settings.json の permissions を編集することは分類器にブロックされるため，自分では追加できない）．
  • auto mode では Bash(gh *) のような広い allow ルールは分類器に回されるため効かない．Bash(gh pr merge:*) のように操作を特定した狭いルールにする必要がある．
• やってはいけないこと: 別コマンドでの迂回（main への直接 push 等）や，設定を緩めての強行．ブロックされた事実と対処法をそのままユーザーに伝えて停止する．

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

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

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

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

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

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