dev-git-commit-message

Git コミットメッセージジェネレーター

基本方針：まず件名を記述し、リスク、根拠、または破壊的変更の詳細が必要な場合にのみ本文を追加します。リポジトリですでに独自のタイプを定義している場合を除き、標準タイプのみを使用します。差分から確認できない動作を決して主張しません。

ルール：rules/common/git.md は、すべてのコーディングセッションでこの不変条件を読み込みます。

クイックリファレンス

必要なこと	デフォルト	リファレンス
タイプを選ぶ	feat/fix/perf/refactor/docs/test/build/ci/chore/style/revert	以下のタイプ選択表
件名をフォーマットする	type(scope): imperative summary、72文字以内（理想は50文字）、末尾にピリオドを付けない	以下のリポジトリポリシーチェック
破壊的変更を示す	タイプまたはスコープの後に ! を付けるか、BREAKING CHANGE: フッターを記述	以下の破壊的変更の形式表
本文が必要か判断する	リスク、明らかでない根拠、または破壊的変更の詳細がある場合のみ	以下の本文が必要か？の表
AI 作成のコミットを扱う	件名や本文に帰属情報を記載しない。デフォルトは Assisted-by: トレーラーで、Claude-Session: と Audit-* も使用可能	以下の AI 作成コミット
リリース／変更履歴ツールを選ぶ	レビュー済みの PR リリースには release-please、完全自動化には semantic-release、モノレポには changesets	references/changelog-generation-guide.md
モノレポのコミットスコープを決める	パッケージ／アプリ／サービスのディレクトリ名を使用し、階層は1つまで、長期的に安定した名前にする	references/monorepo-commit-conventions.md
メッセージをローカルで検証する	python scripts/commit_validator.py validate --message "..."	以下のスクリプトのセクション

判断表

モード選択

条件	モード	アクション
ユーザーがステージ済みの差分を提示する、またはコミットを依頼する	生成	ステージ済みの変更範囲を確認し、主案と代替案を提示します
ユーザーが既存のメッセージ文字列を提示する	検証	ルールを確認し、PASS/WARN/FAIL と正確な修正案を返します
ステージ済みの差分に無関係な領域が混在している	分割	生成前にコミットを分けることを推奨します
ステージ済みの変更がない	停止	「ステージ済みの変更はありません」と報告します

タイプ選択

feat と fix は仕様で SemVer 上の意味を持ちます。それ以外のタイプとリリース動作は、リポジトリのツールに依存します。バージョンの引き上げを主張する前に、そのプリセットとリリースルールを確認してください。以下のスコープとスタイルのルールはローカルのデフォルトであり、仕様の要件ではありません。

変更	タイプ	備考
ユーザーまたは API から見える新機能	feat	MINOR の引き上げが発生します
誤った動作を修正	fix	PATCH の引き上げが発生します
測定可能な速度またはメモリの改善	perf	semantic-release のデフォルトルールでは PATCH になります。リポジトリのルールを確認してください
動作を変えずに構造を改善	refactor	デフォルトではリリースされません
ドキュメントのみ	docs	デフォルトではリリースされません
テストのみ	test	デフォルトではリリースされません
ビルドツールまたはパッケージング	build	デフォルトではリリースされません
CI/CD ワークフロー	ci	デフォルトではリリースされません
リポジトリの整理で、プロダクトに変更がない	chore	デフォルトではリリースされません
空白またはフォーマットのみ	style	デフォルトではリリースされません
過去のコミットを取り消す	revert	リリースへの影響はツールによって異なります。仕様では revert の扱いは定められていません
セキュリティ修正	fix(security):	独自の security: タイプより、標準タイプとスコープの組み合わせを優先します
プロンプト／スキル／YAML の動作変更	feat または fix	ファイル拡張子だけで分類しないでください

スコープの選択

状況	アクション
リポジトリに config.yaml のスコープマップがある	マッピングされたスコープを使用します
1つのディレクトリまたはパッケージが明らかに中心となる	その名前を小文字のケバブケースで使用します
2つ以上の安定した領域に同程度にまたがる変更	より広い親スコープを使用するか、省略します
リポジトリ全体に関わる変更	スコープを省略します
独立したバージョン管理を行うパッケージを含むモノレポ	references/monorepo-commit-conventions.md を参照します

本文は必須ですか？

条件	本文を含めますか？
件名だけで内容が明確	いいえ
理由が件名から明らかでない	はい — 理由を一文で説明します
セキュリティ上重要、またはリスクのある変更	はい — リスクまたはロールバックに関する注記を記載します
破壊的変更	必要に応じて移行の詳細を記載します。件名で破壊的変更を説明していれば、! だけでも有効です
詳細なテンプレートを求められた場合	はい — assets/template-commit-message.md を使用します

破壊的変更の形式

シグナル	形式
インラインマーカー	feat(api)!: change auth to OAuth2
フッター	BREAKING CHANGE: <migration summary>
両方	使用できます。詳細はフッター本文に記載します

変更前／変更後の例

BAD:  update
GOOD: docs(readme): add deployment instructions

BAD:  fix stuff
GOOD: fix(cart): prevent negative quantity on rapid add

BAD:  feat: added user dashboard (past tense)
GOOD: feat(dashboard): add analytics overview panel

BAD:  feat: add search (generated by Copilot)
GOOD: feat(search): add full-text product search

BAD:  feat(api): add comprehensive user search endpoint with full-text search across all profile fields including bio and location
GOOD: feat(api): add full-text user search endpoint

BAD:  feat: add dashboard, fix auth bug, update deps  (mixed concerns)
GOOD: (3 separate commits)
      feat(dashboard): add analytics overview panel
      fix(auth): correct token refresh race condition
      chore(deps): update react to 18.3.0

ワークフロー

1. 上記のモード選択表からモードを決定します。
2. 生成モードでは、次の順でステージ済みの変更を確認します。
   • git diff --staged --name-status
   • git diff --staged --stat
   • 種別、スコープ、またはリスクが曖昧な場合に限り、git diff --staged --unified=1
3. 上記の表を使って、種別とスコープを分類します。
4. まず config.yaml からスコープを検出し、次に最も近い安定したディレクトリから検出します。
5. 生成：主となる提案を1つ提示し、スコープまたは強調点が曖昧な場合は代替案を最大2つ提示して、簡潔な理由を添えます。
6. 検証：リポジトリポリシーチェックを適用し、失敗時は正確な修正案とともに PASS／WARN／FAIL を返します。同梱のバリデーターは既定値をチェックします。対象リポジトリのオーバーライドは別途確認してください。
7. 差分に無関係な作業が混在している場合は、まとめたコミットメッセージを提示する前に、コミットを分割するよう勧めます。

インデックスがコミットの境界です

作業ツリーの差分ではなく、ステージ済みの差分からメッセージを生成します。メッセージを書く前に git diff --cached --name-status と git diff --cached を確認し、ステージされていない編集が要約に混入しないよう、別途 git diff --name-status も確認します。インデックスが空の場合は、コミットされていない作業を説明せずに停止します。ファイルの一部だけがステージされている場合は、ステージ済みのハンクのみを説明し、同じパスにステージされていない変更が残っていることを明記します。

生成ファイル、ロックファイル、マイグレーションについては、それらを独立した成果として列挙するのではなく、その生成の原因となった動作上の変更を記載します。インデックスは下書き中から実行までの間に変わる可能性があるため、コミットの直前に提案する件名をステージ済みパッチと再度照合して検証します。

出力仕様

生成

[NOTE] Suggested commit messages (3 files changed)

PRIMARY:
fix(auth): reject expired refresh tokens

ALTERNATIVES:
1. fix(api): reject expired refresh tokens
2. fix: reject expired refresh tokens during rotation

RATIONALE:
- Type: fix
- Scope: auth
- Signals: token validation path, regression test update, no new feature surface

検証

VALIDATION: WARN

Message:
feat: update stuff

Issues:
- `update stuff` is too vague
- summary should name the changed behavior or surface

Suggested fix:
feat(auth): add refresh token rotation

AI が作成に関与したコミット

コミットメッセージには変更内容を記述し、変更を作成したツールは記述しません。コードの草案を人間が作成したか、AI エージェントが作成したかにかかわらず、同じルールを適用します。

件名と本文の文章では、次の表現は禁止です：generated by、via copilot、via claude、chatgpt、ai assistant、bot。作成者の帰属情報は、末尾のトレーラーブロックにのみ記載します。

AI の支援を受けた作業の監査証跡が必要な場合、推奨される既定の形式は Assisted-by: トレーラーです。Co-authored-by: <ai-tool> は既定の形式ではなく、引き続き検証に失敗します。トレーラーを件名行に記載しないでください。例：

feat(search): add full-text product search

Assisted-by: LLM

受け入れられる AI トレーラーは次のとおりです。すべて、トレーラー間に空行を入れず、最後の段落にまとめてください。

• Assisted-by: 推奨される既定の形式です。カーネル形式では、モデルの後にツールを記載します（Assisted-by: LLM coccinelle sparse）
• Claude-Session: 一部のエージェントランタイムが追加するセッションリンクです
• Audit-*（例：Audit-Batch: や Audit-Skill:）監査プログラムの来歴情報です

AI ツールを示すその他のトレーラーは、すべて検証に失敗します。前の段落に置かれたトレーラーは git interpret-trailers で認識されないため、バリデーターが警告します。

対象プロジェクトが文書化している正確な形式を使用してください。形式はプロジェクトによって異なります。Assisted-by: は Co-Authored-By: とは別のトレーラーです。上流プロジェクトでは形式が統一されておらず、ポリシーも変更されるため、AI トレーラーを追加する前に、対象プロジェクトの最新のコントリビューションポリシーを確認してください。確認すべきポリシーには、Linux カーネルのコーディング支援に関する文書（LLM とツールを列挙する Assisted-by: トレーラー。AI エージェントは Signed-off-by: を追加してはいけません。DCO を証明できるのは人間のみです）、LLVM の AI ツールポリシー（トレーラーの例として Assisted-by: を提示）、Apache の生成ツールに関するガイダンス（Generated-by:）、QEMU のコード来歴ポリシー（AI が生成したコントリビューションを受け付けない）があります。リポジトリですでに慣例として Co-Authored-By: <ai-tool> を使用している場合は、黙って Assisted-by: に書き換えないでください。違いを明示し、メンテナーに判断を委ねてください。履歴が存在する状態でトレーラーの慣例を変更すると、古いトレーラーを検索する blame／来歴ツールが機能しなくなります。

リポジトリのポリシーチェック

次のようなメッセージは、拒否するか書き換えてください。

• 型プレフィックスがないもの（ただし、コントリビューションガイドまたは AGENTS.md に記載されたリポジトリの慣例が、命令形の件名のみを使うものである場合を除きます。その場合は、プレフィックスなしで Imperative summary を生成し、--no-type-prefix で検証してください。このオプションでスキップされるのはこのルールのみです）

• : の後にスペースがないもの、またはスコープが空のもの。スコープの既定形式は小文字のケバブケースです

• 曖昧な要約：update、fix stuff、change code、WIP、misc

• 受け入れられるトレーラー以外にアシスタント／ツールの作成者情報が含まれるもの（上記参照）

• 差分から確認できない影響を誇張するもの

• 型プレフィックスの後に過去形または動名詞を使うもの

• 件名行が 72 文字を超えるもの

• 件名行がピリオドで終わるもの

• 破壊的変更には !、BREAKING CHANGE:、または BREAKING-CHANGE: を付けてください。! を使う場合、フッターは任意です。

• 参照仕様は Conventional Commits v1.0.0 です。

• commitlint がサポートする Node の範囲と設定形式はメジャーバージョンごとに異なります。設定ファイルを作成する前に、ドキュメント（data/sources.json を参照）を確認してください。

• 従来の standard-version の設定では、移行を提案する前にリポジトリのお知らせを確認してください。そこでは release-please またはコミュニティフォークの commit-and-tag-version が案内されています。

• release-please-action では、破壊的変更を含むメジャーバージョンがリリースされます（ランナーのランタイムや入力の変更）。ワークフローで固定する前に、リリースページで最新のメジャーバージョンとそのランタイム要件を確認し、コミット SHA で固定してください。

• semantic-release やその他のリリースツールのメジャーバージョンを、記憶を頼りに記載しないでください。先にリリースページを確認してください。

スクリプト

スクリプト	目的
scripts/commit_validator.py	単一のメッセージの検証、履歴ファイルのリント、または Markdown 品質レポートの生成

# Validate one message
python scripts/commit_validator.py validate --message "feat(auth): add refresh token rotation"

# Lint a batch history file
python scripts/commit_validator.py lint --input data/sample-commit-history.json

# Generate a full Markdown report
python scripts/commit_validator.py report --input data/sample-commit-history.json --output report.md

クイックスタート、入力形式、ルールの詳細については、scripts/README.md を参照してください。

履歴の入力は、文字列の message を含むオブジェクトの空でない配列である必要があります。省略可能な hash、author、date も文字列である必要があります。どちらの履歴コマンドも、出力を生成する前に空の入力と不正なレコードを拒否します。ファイルエラーには入力または出力のパスが示されます。バリデーターは同梱のポリシー既定値を使用し、config.yaml は読み込みません。

Worktree PR ループ

このスキルは、../dev-git-workflow/SKILL.md で定義されている、worktree を優先する広範なデリバリーループのコミット手順として使用してください。

このループでは、機能用 worktree を作成または使用 → コードを変更 → 意図的にステージング → このスキルを使用 → リポジトリのゲートを実行 → PR を作成します。

ステージ済みの差分に無関係な領域が複数含まれている場合は作業を止め、PR の手順に進む前にコミットを分割することを推奨してください。

既知の落とし穴

• ファイル名だけからスコープを推測し、リポジトリの境界づけられたコンテキストのマップに合わないスコープを作成する。
• 無関係な変更を 1 つの「整った」conventional commit にまとめ、取り消しやリリースノートでの有用性を損なう。
• 差分に隠れたマイグレーションや破壊的変更が残っているのに、AI が生成した要約を信頼できるものとして扱う。
• リントを通過する形式を優先し、インシデントの調査に必要な運用上の意図を失う。
• ! や BREAKING CHANGE を安易に使い、後続の自動化に不要なノイズを生じさせる。

ナビゲーション

• config.yaml — リポジトリ固有のスコープマッピングと検証の既定値
• assets/template-commit-message.md — 複雑なコミット向けの詳細な本文テンプレート（任意）
• assets/template-security-commits.md — セキュリティ上重要なコミットの文言に関するガイダンス
• references/conventional-commits-guide.md — 完全な仕様 v1.0.0、タイプ定義、破壊的変更、ツールのセットアップ
• references/commit-message-antipatterns.md — アンチパターンのカタログ、正規表現による検出パターン、commitlint 設定、CI の例
• references/monorepo-commit-conventions.md — スコープ戦略、パッケージごとの変更履歴生成、影響を受けるパッケージに応じた CI の振り分け
• references/changelog-generation-guide.md — リリースツールの比較（standard-version は非推奨です。GitHub のリリース PR には release-please、パッケージごとのモノレポ変更履歴には changesets を既定で使用してください）
• data/sources.json — ツール検証用に厳選した一次ソース
• data/sample-commit-history.json — リントおよびレポートのサブコマンド用の 20 件のコミットのサンプルデータセット
• 関連項目：../dev-git-workflow/SKILL.md — ブランチ作成、フック、PR ワークフロー、リリース自動化。ブランチ作成や PR 戦略には dev-git-workflow を、コミットメッセージの規約にはこのスキルを使用してください。

学びのループ

過去の判断や落とし穴が関係する場合は、learnings.consolidated.md があれば参照してください。必要な履歴を確認するとき、または利用可能な代替手段としてのみ learnings.md を使用してください。それ以外の場合は、どちらも参照しません。

適用後に記録しておく価値のあるパターンに遭遇した場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って、日付入りの箇条書きを 1 つ learnings.md に追記してください。SKILL.md 自体は変更しないでください。