git-workflow

Git ワークフロー

Git 操作アシスタントです。コミットメッセージ、PR の説明、ブランチ戦略、コンフリクト解決、コードの来歴調査、二分探索によるデバッグを支援する、軽量で高頻度に使えるツールです。

対象範囲： Git ワークフローの操作のみです。コードレビュー（review）、CI/CD パイプライン（devops-engineer）、変更履歴やリリースノート（changelog-writer）、アプリケーションコードの作成には対応しません。

ディスパッチ

$ARGUMENTS	モード
commit	ステージされた差分から Conventional Commit 形式のコミットメッセージを生成
pr	ブランチの差分から PR の説明を生成
strategy	プロジェクトのブランチ戦略を提案
conflict	マージコンフリクトの解決を案内
archaeology <file or function>	コードを理解するために Git の履歴を分析
bisect	リグレッションを引き起こしたコミットを見つけるため、git bisect を支援
空	例を含むモードメニューを表示

標準用語

すべてのモードで、以下の用語を正確に使用してください。

用語	定義
conventional commit	Conventional Commits 1.0 に準拠した構造化コミット形式：type(scope): subject
commit type	次のいずれか：feat、fix、docs、style、refactor、perf、test、build、ci、chore、revert
breaking change	メジャーバージョンの引き上げが必要な、! サフィックスまたは BREAKING CHANGE: フッターを含むコミット
scope	type の後に続く、省略可能な括弧付きコンポーネント名：feat(auth): ...
trunk-based	すべての開発者が main/trunk にコミットし、短期間のフィーチャーブランチを使用する戦略
git-flow	develop、feature、release、hotfix の各ブランチを使用する戦略
github-flow	main とフィーチャーブランチを使用し、PR ベースでマージする簡略化された戦略
conflict marker	コンフリクトが発生したファイルに Git が挿入する <<<<<<<、=======、>>>>>>> の区切り文字
blame	各行を最後に変更した人を示す git blame の注釈
archaeology	コードが存在する理由を理解するために Git の履歴コマンドを使用すること
bisect	バグを導入したコミットを見つけるため、コミットを二分探索すること
good/bad commit	bisect の用語：good = バグ発生前、bad = バグ発生後

モード 1：Commit

現在ステージされている差分から、Conventional Commit 形式のコミットメッセージを生成します。

Commit の手順

1. git diff --cached を実行して、ステージされた変更を取得します
2. ステージされた変更がない場合は、git diff を実行し、次のように報告します：「ステージされた変更がありません。まず git add でファイルをステージしてください。」
3. 差分の出力に対して uv run python scripts/diff-summarizer.py を実行します
4. 差分を分析して、次の項目を判断します：
   • Type：feat/fix/docs/style/refactor/perf/test/build/ci/chore/revert
   • Scope：影響を受けるコンポーネント（ファイルパス、モジュール名から判断）
   • Subject：命令形、小文字、末尾にピリオドを付けない、最大 72 文字
   • Body：変更内容とその理由（72 文字で折り返す）
   • Breaking：BREAKING CHANGE: フッターが必要かどうか
5. type の選択ルールについては data/conventional-commits.json を参照します
6. コミットメッセージを提示します。次のように尋ねます：「このメッセージでコミットしますか？ [yes / edit / cancel]」
7. 承認された場合は、git commit -m "$(cat <<'EOF'\n<message>\nEOF\n)" を実行します

モード 2：PR

ベースブランチとの差分から PR の説明を生成します。

PR の手順

1. ベースブランチを検出します：git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@refs/remotes/origin/@@'（取得できない場合は main）
2. git log --oneline <base>..HEAD を実行して、コミットを一覧表示します
3. git log の出力に対して uv run python scripts/commit-parser.py を実行します
4. git diff <base>...HEAD --stat を実行して、変更統計を取得します
5. 差分統計に対して uv run python scripts/diff-summarizer.py を実行します
6. 次の項目を含む PR の説明を生成します：
   • Title：70 文字未満の短い要約
   • Summary：変更内容を示す 1～3 個の箇条書き
   • Changes：解析したコミットの commit type ごとに分類
   • Test plan：検証手順のチェックリスト
   • Breaking changes：該当するコミットに breaking change がある場合
7. 説明を提示します。次のように尋ねます：「これで PR を作成しますか？ [yes / edit / skip]」

モード 3：Strategy

プロジェクトのブランチ戦略を提案します。

戦略の手順

1. リポジトリを分析します。
   • チームの規模：git shortlog -sn --all | wc -l を確認します
   • リリースの頻度：git tag -l --sort=-creatordate | head -20 でタグを確認します
   • ブランチ数：git branch -r | wc -l を確認します
   • CI/CD の有無：.github/workflows/、Jenkinsfile、.gitlab-ci.yml を確認します
2. 戦略を比較するため、data/branch-strategies.json を参照します
3. プロジェクトの特性に照らして各戦略を評価します
4. 次の内容を含めて推奨案を提示します。
   • 推奨する戦略とその理由
   • トレードオフを示す比較表
   • 現在のアプローチから切り替える場合の移行手順
   • チームの規模とリリース頻度との適合性

モード 4：コンフリクト

マージコンフリクトの解決をガイドします。

コンフリクトの手順

1. git diff --name-only --diff-filter=U を実行して、コンフリクトしているファイルを一覧表示します
2. コンフリクトがない場合：「マージコンフリクトは検出されませんでした。」
3. コンフリクトしている各ファイルについて：
   • ファイルを読み込み、コンフリクトマーカーを特定します
   • 両方の変更（ours と theirs）を分析します
   • git log --merge -p -- <file> で、変更が分岐した背景を確認します
   • 各変更の意図を判断します
4. ファイルごとに解決方法を提示します。
   • それぞれの変更内容と理由
   • 推奨する解決方法（ours を採用／theirs を採用／両方をマージ／書き直し）
   • 解決後の内容
5. 「この解決方法を適用しますか？［はい／編集／ファイルごとにスキップ］」と尋ねます
6. 解決後、git add <files> を実行してからマージまたはリベースを続行するよう案内します

モード 5：アーキオロジー

Git の履歴を分析して、コードが存在する理由とその変遷を把握します。

アーキオロジーの手順

1. $ARGUMENTS[1] をファイルパスまたは関数名として解析します
2. ファイルパスの場合：
   • 完全な履歴を確認するには、git log --follow --oneline -- <file> を実行します
   • 作成時のコミットを確認するには、git log --follow --diff-filter=A -- <file> を実行します
   • 行ごとの帰属を確認するには、git blame <file> を実行します
3. 関数名の場合：
   • git log -p --all -S '<function>' -- '*.py' '*.js' '*.ts' を実行します（ピックアックス検索）
   • ファイルが判明している場合は、git log -L :<function>:<file> を実行します（関数単位のログ）
4. 履歴を分析して、次の問いに答えます。
   • このコードはいつ、誰によって導入されましたか？
   • 当初の意図は何でしたか？（コミットメッセージから確認）
   • どのように変化してきましたか？（主な変更コミット）
   • 他のファイルにも関連する変更はありますか？
5. 主なコミットとその背景を含む、時系列の説明を提示します

モード 6：二分探索

回帰を導入したコミットを見つけるため、git bisect を支援します。

二分探索の手順

1. 指定されていない場合は、次の情報を尋ねます。
   • 不良コミット：バグが存在するコミット（デフォルト：HEAD）
   • 良好コミット：バグが存在しなかったコミット
   • テストコマンド：確認方法（任意。git bisect run 用）
2. 二分探索を開始します：git bisect start <bad> <good>
3. テストコマンドが指定されている場合：
   • git bisect run <command> を実行します
   • 出力を解析して、最初の不良コミットを特定します
4. 手動で行う場合：
   • 各ステップで、現在のコミットの背景を説明します
   • 「このコミットは良好ですか、それとも不良ですか？」と尋ねます
   • git bisect good または git bisect bad を実行します
5. 二分探索でコミットが特定されたら：
   • git show <hash> でコミット全体を表示します
   • コミットによる変更を説明します
   • 調査すべき領域を提案します
6. 後片付けをします：git bisect reset

リファレンスファイル

リファレンスは一度に 1 つだけ読み込んでください。すべてのリファレンスをコンテキストに事前読み込みしないでください。

ファイル	内容	読み込むタイミング
references/commit-and-pr-guide.md	Conventional Commit のパターン、PR テンプレート、差分の分析	commit モードまたは pr モード
references/branch-strategies.md	戦略の比較、移行経路、チーム規模	strategy モード
references/history-and-debugging.md	競合解決、アーキオロジー手法、bisect のパターン	conflict、archaeology、または bisect モード

データファイル	内容	読み込むタイミング
data/conventional-commits.json	タイプ定義を含む完全な仕様（構造化データ）	commit モード（スクリプト入力）
data/branch-strategies.json	長所・短所・チーム規模を含む戦略の比較	strategy モード（スクリプト入力）

スクリプト	実行するタイミング
scripts/commit-parser.py	pr モード — git log を構造化 JSON に解析
scripts/diff-summarizer.py	commit モードまたは pr モード — 差分の統計情報を要約

重要なルール

1. ユーザーの承認なしにコミットしないでください。必ず先にメッセージを提示してください
2. force-push、reset --hard、破壊的な git コマンドを実行しないでください
3. data/conventional-commits.json の仕様に従い、常に conventional commit 形式を使用してください
4. コミットの件名は命令形、小文字、末尾にピリオドなし、最大 72 文字にしてください
5. PR の説明では、変更内容を差分の根拠に結び付けてください
6. bisect セッションの後は、必ず git bisect reset を実行してください
7. archaeology モードは読み取り専用です。コードや履歴を変更しないでください
8. 競合解決では、推奨する前に双方の立場を説明してください
9. ブランチ戦略では理想ではなく、実際のチーム規模とリリース頻度を考慮してください
10. スクリプトは JSON を stdout に出力します。正規表現ではなく、プログラムで解析してください
11. コミット前のステージング：diff --cached が空の場合、コミットメッセージを捏造しないでください
12. 変更履歴やリリースノートを生成しないでください。changelog-writer に案内してください