git-commit-workflow

Git コミットのワークフロー

このスキルを使用する場面

次の場合にこのスキルを使用します...	次の場合は代替手段を使用します...
リポジトリの Conventional Commit メッセージとステージング規約を設計する	実際にコミットを作成する場合は git-commit を使用します（pre-commit フック、Issue の検出に対応）
変更を論理的にまとめ、焦点を絞ったコミットにする方法を検討する	BREAKING CHANGE / Co-authored-by のトレーラールールには git-commit-trailers を使用します
慎み深く、事実に基づくコミットのコミュニケーションスタイルについて話し合う	メッセージに Fixes #N / Closes #N のリンクを追加するには github-issue-autodetect を使用します
コードベース向けの feat(scope): subject ルールを作成する	PR タイトルに同じ Conventional Commit 形式を適用するには github-pr-title を使用します

Conventional Commit と明示的なステージングワークフローを用いた、コミットメッセージの規約、ステージングの実践方法、コミットのベストプラクティスに関する専門的なガイダンスです。

詳細な例、高度なパターン、ベストプラクティスについては、REFERENCE.md を参照してください。

前提条件

ファイルをステージングする前に、特に多数のサブディレクトリに触れる一括編集／コミットループのワークフローでは、作業ツリーが自分だけのものか確認してください。

確認項目	理由	方法
同僚の確認	同じチェックアウトで別の Claude セッションが、すでにファイルを事前ステージングしている可能性があります（git commit -a の再試行、放棄されたステージングなど）。そのファイルがループによって誤ったコミットに含まれるおそれがあります。状況を見て確認するのではなく、最初に必ず実行してください。	SlashCommand → /git:coworker-check
作業ツリーの範囲	git status --porcelain に自分の編集内容だけが表示されることを確認します	git status --porcelain

/git:coworker-check の結果が clear 以外の場合は、作業を中止し、新しいワークツリーに移動する（git worktree add ../<repo>-<task>）か、続行する前にユーザーに確認してください。検出シグナルの4項目については .claude/rules/agent-coworker-detection.md を参照してください。

主な専門知識

• Conventional Commits：自動化と明確さのための標準形式
• 明示的なステージング：可視性を確保するため、ファイルを個別にステージングします
• 論理的なグループ化：関連する変更をまとめ、焦点を絞ったコミットにします
• コミュニケーションスタイル：慎み深く、事実に基づいた簡潔なコミットメッセージ
• pre-commit との連携：コミット前にチェックを実行します

**注：**コミットは main ブランチで作成し、PR 用にリモートの feature ブランチへプッシュします。main ブランチでの開発パターンについては、git-branch-pr-workflow スキルを参照してください。

Conventional Commit の形式

標準形式

type(scope): description

[optional body]

[optional footer(s)]

フッター／トレーラーのパターン（Co-authored-by、BREAKING CHANGE、Release-As）については、git-commit-trailers スキルを参照してください。

コミットの種類

• feat：ユーザー向けの新機能
• fix：ユーザー向けのバグ修正
• docs：ドキュメントの変更
• style：フォーマット、セミコロンの不足など（コードの変更なし）
• refactor：動作を変更しないコードの再構成
• test：テストの追加または更新
• chore：保守作業、依存関係の更新、リンターの修正
• perf：パフォーマンスの改善
• ci：CI/CD の変更

例

# Feature with scope
git commit -m "feat(auth): implement OAuth2 integration"

# Bug fix with body
git commit -m "fix(api): resolve null pointer in user service

Fixed race condition where user object could be null during
concurrent authentication requests."

# Breaking change
git commit -m "feat(api)!: migrate to GraphQL endpoints

BREAKING CHANGE: REST endpoints removed in favor of GraphQL.
See migration guide at docs/migration.md"

コミットメッセージのベストプラクティス

推奨事項：

• 命令形を使用します（「added feature」ではなく「add feature」）
• 1行目を72文字未満にします
• 簡潔で事実に基づいた内容にします
• 関連する Issue を必ず参照します — すべてのコミットに関連する Issue へのリンクを含めます
• GitHub のクローズキーワードを使用します：Fixes #123、Closes #456、Resolves #789
• 種類とスコープには小文字を使用します
• 慎み深く、控えめな表現にします

禁止事項：

• 過去形を使用する（「added」や「fixed」）
• 件名に不要な詳細を含める
• 曖昧な説明を使用する（「update stuff」、「fix bug」）
• Issue 参照を省略する — コミットを必ず関連するコンテキストにリンクします
• 参照（Refs）だけを意図しているのに、クローズキーワード（Fixes）を使用する

コミット前のコンテキスト収集（推奨）

コミットする前に、1つのコマンドですべてのコンテキストを収集します。

# Basic context: status, staged files, diff stats, recent log
bash "${CLAUDE_PLUGIN_ROOT}/skills/git-commit-workflow/scripts/commit-context.sh"

# With issue matching: also fetches open GitHub issues for auto-linking
bash "${CLAUDE_PLUGIN_ROOT}/skills/git-commit-workflow/scripts/commit-context.sh" --with-issues

スクリプトは、ブランチ情報、ステージ済み／未ステージの状態、差分の統計情報、検出されたスコープ、最近のコミットのスタイル、pre-commit の設定状態、必要に応じて未解決の Issue を出力します。この出力を使ってコミットメッセージを作成してください。詳細は scripts/commit-context.sh を参照してください。

明示的なステージングのワークフロー

ファイルは必ず個別にステージングする

# Show current status
git status --porcelain

# Stage files one by one for visibility
git add src/auth/login.ts
git add src/auth/oauth.ts
git status  # Verify what's staged

# Show what will be committed
git diff --cached --stat
git diff --cached  # Review actual changes

# Commit with conventional message
git commit -m "feat(auth): add OAuth2 support"

一括編集／プラグインごとのコミットループ

1つの変更が多くのサブディレクトリ（プラグインごと、パッケージごと、ドキュメントごと）に及び、それぞれに release-please 用の個別スコープのコミットが必要な場合は、コマンドをインラインで連結せず、1回限りのスクリプトを作成してください。

インラインループが失敗する理由

パターン	問題となる点
for d in a b c; do git add "$d/" && git commit -m "..."; done	bash-antipatterns.sh は git add ... && git commit ... をブロックします。インデックスを変更する git コマンドの連結は、index.lock の競合を引き起こすおそれがあります
git add -A、git add --all、git add .	bash-antipatterns.sh は広範囲のステージングをブロックします。.env、大容量のバイナリ、さらに共有チェックアウト内で他の共同作業者のセッションが作業中のファイルまで含めてしまいます（.claude/rules/agent-coworker-detection.md を参照）
プラグインごとに、別々の Bash ツール呼び出しで git add <paths>; git commit -m "..." を繰り返す	動作しますが、プラグインが40個ある一括処理では、ツール呼び出しがプラグイン数の3倍ほどになり、数百回の往復が発生します

標準的な手順

ループを /tmp/commit-loop-<slug>.sh に書き、Bash を1回呼び出して実行します。フックはファイルをコマンドの連結ではなくスクリプトとして扱います。インデックスを変更するコマンドは、別々のツール呼び出しで競合するのではなく、bash 内で順番に実行されます。

#!/bin/bash
# /tmp/commit-loop-trim-descriptions.sh
set -uo pipefail
cd "$REPO_ROOT" || exit 1

for p in plugin-a plugin-b plugin-c; do
  # Skip plugins with nothing staged or modified inside them
  [ -z "$(git status --porcelain "$p/")" ] && continue

  git add "$p/skills/"            # explicit path, never -A or .
  git commit -m "docs($p): trim skill descriptions for listing budget"
done

1回だけ呼び出します。

bash /tmp/commit-loop-trim-descriptions.sh

各イテレーションで pre-commit フックが実行され、プラグインごとにクリーンなコミットが作成されます。スクリプト内では、git add と git commit の間に && ではなく ; または改行を使用してください。

失敗からの復旧

ループが途中で中断した場合（プラグイン K で pre-commit フックが失敗した場合など）、プラグイン1からK-1のコミットはすでに適用されています。ロールバックされることはありません。復旧時は次のルールに従ってください。

状況	対応
pre-commit フックがプラグイン K の実際の問題を検出した	問題を修正してスクリプトを再実行します。[ -z ... ] && continue ガードにより、残りの変更がないプラグインはスキップされます
スクリプトの再実行でプラグイン K のステージ済みファイルが残っている	問題ありません。git status --porcelain "$p/" による未ステージまたはステージ済みの確認で、両方が検出されます
プラグイン K をスキップして続行したい	スクリプトからプラグイン K を削除して、再実行します

すでに正常にコミットされたパスを再度ステージングしないでください。残っているファイルの確認には git status を使用します。

複数行のメッセージは、一時ファイルの内容を読み込むのではなく HEREDOC で作成してください。

git commit -m "$(cat <<'EOF'
feat(auth): add OAuth2 support

Implements token refresh and secure storage.

Fixes #123
EOF
)"

メッセージをパスで渡す方法も同様に使用できます。git commit -F <file> / --file=<file> は gh --body-file に相当する git の機能であり、 bash-antipatterns フックの対象外です（#2462）。

git commit -F /tmp/commit-msg.txt

フックが避けるよう促すのは、回りくどい中間的な方法です。一時ファイルを書き込み、その内容を -m "$(cat /tmp/commit-msg.txt)" で読み込む方法です。HEREDOC を使ってインラインで作成するか、ファイルのパスを渡してください。

コミュニケーションのスタイル

謙虚で事実に基づいたメッセージ

# Good: Concise, factual, modest
git commit -m "fix(auth): handle edge case in token refresh"

git commit -m "feat(api): add pagination support

Implements cursor-based pagination for list endpoints.
Includes tests and documentation."

事実に焦点を当てます。何を変更したか、（明らかでない場合は）なぜ変更したか、そして影響（破壊的変更）を記載してください。

Issue 参照の概要

シナリオ	パターン	例
Issue を解決するバグ修正	Fixes #N	Fixes #123
Issue を完了する機能	Closes #N	Closes #456
関連するが完了はしない場合	Refs #N	Refs #789
リポジトリをまたぐ場合	Fixes owner/repo#N	Fixes org/lib#42
複数の Issue	キーワードを繰り返す	Fixes #1, fixes #2

ベストプラクティス

コミットの頻度

• 早めに、頻繁にコミットする：小さく、対象を絞ったコミットにします
• 1つの論理的な変更につき1つのコミットにする：レビューや取り消しが容易になります
• コミットをアトミックに保つ：各コミットは、完全に動作する状態である必要があります

コミットメッセージの長さ

# Subject line: <= 72 characters
feat(auth): add OAuth2 support

# Body: <= 72 characters per line (wrap)
# Use blank line between subject and body

エージェント向け最適化

コンテキスト	コマンド
コミット前のコンテキスト	bash "${CLAUDE_PLUGIN_ROOT}/skills/git-commit-workflow/scripts/commit-context.sh"
コンテキスト＋イシュー	bash "${CLAUDE_PLUGIN_ROOT}/skills/git-commit-workflow/scripts/commit-context.sh" --with-issues
クイックステータス	git status --porcelain
ステージ済み差分の統計	git diff --cached --stat
最近のコミットのスタイル	git log --format='%s' -5
リンク用のオープンイシュー	gh issue list --state open --json number,title --limit 30