git-workflow

Git ワークフロー

GitHub Flow によるブランチ運用、アトミックコミット、復旧操作など、Git のワークフローのパターンを網羅します。クリーンでレビューしやすい履歴を維持するために不可欠です。

引数の解決

SUBCOMMAND = "$ARGUMENTS[0]"  # Optional subcommand, e.g., "recovery", "branch", "stacked"
# If no arguments, show full workflow reference.
# $ARGUMENTS is the full string (CC 2.1.59 indexed access)

ブランチの命名規則

# Feature branches (link to issue)
issue/<number>-<brief-description>
issue/123-add-user-auth

# When no issue exists
feature/<description>
fix/<description>
hotfix/<description>

ブランチのルール：

1. main は常にデプロイ可能な状態にします
2. main からブランチを作成し、main に戻す PR を作成します
3. ブランチの存続期間は 1～3 日未満にします
4. マージ後にブランチを削除します

---

アトミックコミットのチェックリスト

[ ] Does ONE logical thing
[ ] Leaves codebase working (tests pass)
[ ] Message doesn't need "and" in title
[ ] Can be reverted independently
[ ] Title < 50 chars, body wraps at 72

インタラクティブなステージング

# Stage changes hunk-by-hunk
git add -p

# Options:
# y - stage this hunk
# n - skip this hunk
# s - split into smaller hunks
# e - manually edit the hunk
# q - quit

# Review what's staged
git diff --staged    # What will be committed
git diff             # What won't be committed

コミットのパターン

# Separate concerns
git add -p && git commit -m "refactor: Extract database pool"
git add -p && git commit -m "feat(#456): Add query caching"

# Never combine unrelated changes
# BAD:  "feat: Add auth and fix formatting"
# GOOD: Two separate commits

---

復旧クイックリファレンス

セーフティネット

# ALWAYS check reflog first - it has everything
git reflog

# Shows ALL recent HEAD movements
# Even "deleted" commits live here for 90 days

よくある復旧シナリオ

シナリオ	プッシュ前	プッシュ済み
コミットを取り消す	git reset --soft HEAD~1	git revert HEAD
間違ったブランチ	cherry-pick + reset	cherry-pick + revert
コミットを紛失した	git reset --hard HEAD@{N}	該当なし
不適切なリベース	git rebase --abort または reflog	reflog + force-with-lease

クイック復旧コマンド

# Undo last commit, keep changes staged
git reset --soft HEAD~1

# Find lost commits
git reflog | grep "your message"

# Recover to previous state
git reset --hard HEAD@{1}

# Safe force push (feature branches only)
git push --force-with-lease

---

標準的なワークフロー

# 1. Start fresh
git checkout main && git pull origin main
git checkout -b issue/123-my-feature

# 2. Work with atomic commits
git add -p
git commit -m "feat(#123): Add User model"

# 3. Stay updated
git fetch origin && git rebase origin/main

# 4. Push and PR
git push -u origin issue/123-my-feature
gh pr create --fill

# 5. Cleanup after merge
git checkout main && git pull
git branch -d issue/123-my-feature

---

アンチパターン

Avoid:
- Long-lived branches (> 1 week)
- Merging main into feature (use rebase)
- Direct commits to main
- Force push to shared branches
- Commits that need "and" in message
- Committing broken code

---

ベストプラクティスのまとめ

1. main からブランチを作成する - 毎回、新しく始めます
2. インタラクティブにステージングする - git add -p を使用します
3. 1 コミットにつき 1 つの変更にする - 「そして」と言うなら、分けます
4. マージではなくリベースする - 履歴をクリーンに保ちます
5. まず reflog を確認する - 問題が発生したときに確認します
6. Force-with-lease を使用する - force push より安全です
7. マージ後に削除する - 古いブランチを残しません

関連スキル

• ork:commit - 規約に沿った形式とコミット前の検証でコミットを作成します
• git-recovery - reflog 操作を使って、よくある Git のミスから迅速に復旧します
• stacked-prs - 依存関係のある PR を使った、大規模な機能開発向けの複数 PR 開発
• ork:create-pr - 適切なフォーマットで包括的な PR を作成します

主な判断事項

判断事項	選択	理由
ブランチモデル	GitHub Flow	シンプルな単一ブランチのワークフローで、main は常にデプロイ可能です
マージ戦略	マージよりリベース	履歴をクリーンかつ直線的に保ち、二分探索を容易にします
ブランチの命名	issue/-	作業を追跡対象に関連付け、自動化を可能にします
コミットの粒度	アトミック（1 つの変更）	個別に取り消せて、履歴が明確になり、レビューも容易になります
強制プッシュ	--force-with-lease のみ	共有ブランチ上で他の人の作業を上書きするのを防ぎます

ルール

各カテゴリには、オンデマンドで読み込まれる個別のルールファイルが rules/ にあります。

カテゴリ	ルール	影響度	主なパターン
ブランチ保護	${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/branch-protection.md	CRITICAL	保護されたブランチ、必須の PR ワークフロー
マージ戦略	${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/merge-strategy.md	HIGH	リベース優先、競合解決、force-with-lease
履歴の整理	${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/history-hygiene.md	HIGH	WIP のスカッシュ、fixup コミット、クリーンな履歴
復旧	${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/recovery-reflog.md	CRITICAL	紛失したコミットやブランチを reflog で復旧
復旧	${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/recovery-reset.md	CRITICAL	安全な reset モードと危険な reset モード
復旧	${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/recovery-stash.md	HIGH	stash の管理と、削除した stash の復旧
スタック型 PR	${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/stacked-pr-workflow.md	HIGH	スタックの計画、PR の作成、依存関係の追跡
スタック型 PR	${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/stacked-pr-rebase.md	HIGH	リベースの管理、force-with-lease、ターゲットの変更
モノレポ	${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/monorepo-context.md	MEDIUM	--add-dir、サービスごとの CLAUDE.md、ワークスペースの検出

合計：6 カテゴリにわたる 9 個のルール

参考資料

必要に応じて、Read("${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/references/<file>") で読み込みます。

ファイル	内容
github-flow.md	GitHub Flow のブランチ運用ガイド
interactive-staging.md	インタラクティブなステージングのパターン
reflog-recovery.md	Reflog を使った復旧テクニック
recovery-decision-tree.md	復旧シナリオの判断ツリー

チェックリスト

必要に応じて、Read("${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/checklists/<file>") で読み込みます。

ファイル	内容
branch-checklist.md	ブランチ作成前の事前確認
pre-commit-checklist.md	コミット前の検証