git-commit-message

Git コミットメッセージ生成ツール

階層型のフォーマット適用により、git の差分から Conventional Commits 形式のコミットメッセージを自動生成します

目的

ステージングされた git の変更を分析し、階層型の Conventional Commits 仕様に従って、簡潔で意味のあるコミットメッセージを生成します。このスキルはファイルの変更、追加、削除を調べて変更の種類と範囲を推測し、重要な機能には詳細な説明を、軽微な更新には簡潔なメッセージを付けるなど、変更の重要度に応じたコミットメッセージを作成します。

主な特長：重要なコミット（feat、fix、security）には十分な説明を付け、定型的な変更（docs、chore、style）は効率よく記述できる、3 階層のフォーマットシステムです。

このスキルが有効になる場合

• /commit-msg コマンドが呼び出されたとき
• commit-msg／prepare-commit-msg フックから呼び出されたとき（インストール済みの場合）
• ユーザーがコミットメッセージの候補を求めたとき
• コミットを作成する前に変更を分析するとき

主な機能

1. 差分の分析

• git diff --staged の出力を解析します
• 変更、追加、削除されたファイルを特定します
• コードの変更（追加、削除、修正）を分析します
• 複数のファイルにまたがるパターンを検出します

2. 変更の分類

• 変更内容からコミットの種類を判断します：
  • feat：新機能または新しい機能性
  • fix：バグ修正
  • security：セキュリティ修正またはセキュリティ強化
  • refactor：動作を変えないコードの再構成
  • docs：ドキュメントの変更
  • style：フォーマット、空白、コードスタイル
  • test：テストの追加または変更
  • chore：ビルドプロセス、依存関係、ツール
  • perf：パフォーマンスの改善
  • ci：CI/CD 設定の変更
  • build：ビルドシステムの変更
  • revert：以前のコミットの取り消し

3. スコープの検出

• ファイルパスやパターンからスコープを推測します：
  • ディレクトリ名（例：api、auth、ui）
  • ファイル名のパターン（例：*.test.js → tests）
  • フレームワークの規則（例：components/、services/）

4. メッセージの生成

• 形式：type(scope): description
• 階層ごとの上限を適用します：Tier 1 の概要は最大 50 文字、Tier 2／3 の概要は最大 72 文字（理想は 50 文字）
• 命令形を使用します（「added」ではなく「add」）
• 「どのように」ではなく、「何を」「なぜ」に重点を置きます
• 2～3 件の代替案を提示します

階層システム：スマートなフォーマット適用

このスキルでは、コミットの重要度に応じてメッセージの詳細度を調整する3 階層のフォーマットシステムを使用します。

Tier 1：重要なコミット（feat、fix、perf、security）

要件：影響に関する説明を含む詳細な記述

形式：

type(scope): summary line (max 50 chars)

- Detailed description point 1
- Detailed description point 2
- Detailed description point 3

This change [impact statement describing user-facing benefit or risk addressed].

Affected files/components:
- path/to/file1
- path/to/file2

理由：機能、修正、パフォーマンスの変更はユーザーに直接影響するため、将来の参照や変更履歴の生成に役立つ、十分に詳細な記述が必要です。

Tier 2：標準的なコミット（refactor、test、build、ci）

要件：簡潔な背景情報とファイル一覧

形式：

type(scope): summary line (max 72 chars)

Brief explanation of what changed and why (1-2 sentences).

Files: path/to/file1, path/to/file2

理由：内部的な改善には保守性のための背景情報が必要ですが、詳細な説明までは必要ありません。

Tier 3：軽微なコミット（docs、style、chore）

要件：概要行。説明は任意

形式：

type(scope): summary line (max 72 chars)

[Optional: Additional context if helpful]

理由：ドキュメントや定型的な保守作業は差分から内容が分かるため、冗長なメッセージはノイズになります。

ワークフロー

0. Pre-staging typecheck (if project uses TypeScript):
   - Run `tsc --noEmit` on changed files before staging
   - Fix type errors before committing (avoids pre-commit hook retry loops)
1. Get staged changes (staged only, not working tree):
   - git diff --staged --name-status
   - git diff --staged --stat
   - git diff --staged
2. Load config → frameworks/shared-skills/skills/git-commit-message/config.yaml
3. Analyze changes:
   - Count files modified/added/deleted
   - Identify primary change type using analysis patterns
   - Detect scope from project structure (config.yaml)
   - Determine tier (1/2/3) based on commit type
   - Extract key modifications
4. Generate commit messages:
   - Apply tier-appropriate format
   - Primary suggestion (best match)
   - Alternative 1 (different scope/angle)
   - Alternative 2 (broader/narrower focus)
5. Validate against rules:
   - Check forbidden patterns
   - Verify required elements present
   - Ensure length limits
6. Present to user with explanation and tier info

任意のモード（呼び出し元が対応している場合）

• --validate "<message>"：候補を生成せず、コミットメッセージを検証します（形式／種類／スコープ／長さ／禁止パターンを確認し、不足している場合は Tier 1／2／3 で必要な要素を報告します）。
• --tier <1|2|3>：階層のフォーマットを指定します（自動検出より優先されます）。
• --interactive または -i：最終出力の前に、種類、スコープ、概要の確認を求めます。

出力形式

[NOTE] Suggested Commit Messages (based on X files changed)

PRIMARY:
feat(api): add user authentication endpoints

ALTERNATIVES:
1. feat(auth): implement JWT token validation
2. feat: add user authentication system

ANALYSIS:
- 3 files modified in src/api/
- New functions: authenticateUser, generateToken
- Primary change: new feature (authentication)
- Scope detected: api/auth

Conventional Commits クイックリファレンス

タイプのガイドライン：

• feat：ユーザー向けの機能または API の追加
• fix：誤った動作を修正
• refactor：動作を変更せずにコードを改善
• docs：README、コメント、ドキュメントファイル
• style：フォーマットのみ（prettier、eslint --fix）
• test：テストファイルまたはテストユーティリティ
• chore：ビルドスクリプト、パッケージの更新、設定
• perf：測定可能なパフォーマンスの改善
• ci：GitHub Actions、CircleCI、ビルドパイプライン

スコープのガイドライン：

• 小文字を使用する
• 具体的にするが、細かくしすぎない
• プロジェクトのモジュール構成に合わせる
• 変更が複数の無関係な領域にまたがる場合は省略する

説明のガイドライン：

• 動詞を小文字で始める
• 末尾にピリオドを付けない
• 具体的かつ簡潔にする
• feat と fix ではユーザーへの影響を重視する

エッジケース

複数の無関係な変更：

• 個別のコミットに分けることを提案する
• まとめざるを得ない場合は、より広いスコープを使うか、スコープを省略する

破壊的変更：

• タイプ／スコープの後に感嘆符を付ける（例：feat(api)!: change auth flow）
• 本文に BREAKING CHANGE を含める（ユーザーが対応）

WIP または実験的な変更：

• chore(wip): description または feat(experimental): description を使用する

意味のある変更がない場合：

• 検出して警告する：「ステージされた変更が見つかりません」
• git add コマンドを提案する

統合ポイント

コミット前フック：コミット前に実行されます（インストール／設定されている場合） スラッシュコマンド：/commit-msg で手動実行 スキルの直接呼び出し：他のスキルまたはツールから実行

ベストプラクティス

1. コンテキストを分析する：ファイルパス、関数名、インポート文を確認する
2. 明確さを優先する：気の利いた表現より、分かりやすい説明を選ぶ
3. 規約を尊重する：検出できた場合は、プロジェクト既存のコミットパターンに従う
4. 幻覚を避ける：差分に実際に含まれている内容だけを説明する
5. 簡潔にする：50 文字が理想で、1 行目は最大 72 文字
6. 特定のファイルをステージする：無関係な変更や機密ファイルを含めないよう、git add -A や git add . ではなく git add <file1> <file2> を使用する
7. サンドボックス化されたシェルではヒアドキュメントを避ける：サンドボックス環境では、ヒアドキュメント用の一時ファイル作成がブロックされる場合があります。git commit -m "$(cat <<'EOF'\nmessage\nEOF\n)" を使用するか、-m "message" を直接渡してください
8. コミット前の型チェック：型エラーを早期に検出し、コミット前フックでの再試行が連鎖するのを避けるため、コミット前にステージされた範囲に対して tsc --noEmit を実行する

分析例

シナリオ 1：新しい React コンポーネント

Files: src/components/UserProfile.tsx, src/components/UserProfile.test.tsx
Changes: +120 lines, component definition, props interface, tests
Message: feat(components): add UserProfile component

シナリオ 2：API のバグ修正

Files: src/api/auth.ts
Changes: -5 +8 lines, fix token expiration check
Message: fix(auth): correct token expiration validation

シナリオ 3：ドキュメントの更新

Files: README.md, docs/api.md
Changes: +45 lines documentation
Message: docs: update API documentation and README

シナリオ 4：依存関係の更新

Files: package.json, package-lock.json
Changes: version bumps for eslint, typescript
Message: chore(deps): update eslint and typescript

分析パターン：スマートなタイプ検出

このスキルでは、差分のパターンマッチングを使ってコミットタイプをインテリジェントに検出します。

feat の検出

• 新規ファイルの作成（特に src/、components/、api/ 内）
• 新しい関数／クラスのエクスポート（export function、export class）
• 新しい API ルート（app.get、router.post など）
• 新しいアセット／スキル（.claude/、custom-gpt/ など）
• しきい値：通常、20 行以上の追加は機能追加を示す

fix の検出

• テストファイルの変更（バグの再現を示すことが多い）
• 新しい条件分岐（検証の修正）
• エラー処理の追加（try、catch、throw）
• 入力検証（validate、sanitize、check）
• コミットメッセージのヒント：「bug」、「issue」、「error」、「crash」などの語

refactor の検出

• 変更の追加と削除のバランスが取れている（追加と削除が同程度）
• 関数の名前変更／移動（ロジックは同じで場所が異なる）
• 新しい機能や修正がない
• テストカバレッジに変更がない
• キーワード：「extract」、「move」、「rename」、「reorganize」

docs の検出

• ファイルパターン：.md、.txt、README、CHANGELOG、/docs/
• ドキュメントのみの変更（コードの変更なし）
• コードとドキュメントが混在する場合：コードのタイプを優先し、説明にドキュメントについて記載する

test の検出

• ファイルパターン：test.js、spec.ts、__tests__/、/tests/
• テストフレームワークのパターン：describe、it、test、expect、assert

style の検出

• CSS／スタイル設定ファイル：.css、.scss、.sass、.less
• フォーマッター設定：prettier、eslint
• 空白文字のみの変更
• キーワード：「formatting」、「indent」、「whitespace」

chore の検出

• 依存関係ファイル：package.json、requirements.txt、Gemfile
• ロックファイル：package-lock.json、yarn.lock
• 設定ファイル：.gitignore、.env
• キーワード：「dependency」、「deps」、「upgrade」、「bump」

設定

config.yaml から読み込まれるプロジェクト固有の設定：

• スコープのマッピング：ディレクトリパターンをスコープ名にマッピングします（例：frameworks/claude-code-kit/** → claude-kit）
• ティアルール：コミットの種類ごとに必要なティア形式を定義します
• 禁止パターン：一般的すぎるメッセージやアシスタント／ツールの帰属表示を含むコミットをブロックします
• 分析パターン：コードベースに合わせて種類の検出ロジックをカスタマイズします
• 検証モード：strict（ブロック）、warning（警告）、disabled（無効）

禁止パターン（検証）

このスキルは、次のパターンを含むコミットを自動的にブロックします。

一般的／曖昧なメッセージ

• [FAIL] 「Update files」→ [OK] 「docs: update API reference」
• [FAIL] 「Fix stuff」→ [OK] 「fix(auth): correct token validation」
• [FAIL] 「Change code」→ [OK] 「refactor(utils): simplify date formatting」

アシスタント／ツールの帰属表示（リポジトリのポリシーに準拠）

• [FAIL] 「Generated with Claude Code」
• [FAIL] 「Co-Authored-By: Claude [email protected]」
• [FAIL] コミットメッセージ内のあらゆるアシスタント／ツールの帰属表示

作業中を示すマーカー

• [WARNING] 「WIP: feature」（警告 — マージ前にスカッシュしてください）
• [WARNING] 「temp: quick fix」（警告 — スカッシュしてください）

種類の指定漏れ

• [FAIL] 種類のプレフィックス（feat、fix、docs など）がないコミット

エラー処理

• ステージされた変更がない場合：git status を実行し、ユーザーに git add でファイルを追加するよう案内します
• バイナリファイルのみの場合：コミットメッセージにファイルの種類を記載する必要があることを伝えます
• マージコンフリクトがある場合：検出して chore: resolve merge conflicts を提案します
• Git を利用できない場合：役立つエラーメッセージを表示して、適切に処理を終了します
• 禁止パターンを検出した場合：例を含むエラーを表示し、コミットをブロックします（strict モード）
• 必須要素が不足している場合：ティアの要件に基づいて不足項目を一覧表示します
• 文字数が上限を超えた場合：文字数を表示し、短縮を提案します

リポジトリとの連携

このスキルは、AI-Agents リポジトリの標準に準拠して連携します。

• CLAUDE.md の参照：コミット前のスキル使用を必須とします
• config.yaml：プロジェクト固有のスコープマッピングとルール
• コミット前フック：Git コミット前に自動で有効になります
• CONTRIBUTING.md：コントリビューター向けのコミットガイドライン

---

コミットメッセージのテンプレート

assets/template-commit-message.md — コピーして使えるテンプレートと、良い例／悪い例です。

これを使って type(scope): summary 形式のメッセージを標準化し、履歴の自動処理に適した状態を保ちましょう。

---

セキュリティ上の機微なコミット

assets/template-security-commits.md — セキュリティ上の機微な変更を扱うためのガイドです。

主なセクション

• コミット前のセキュリティチェックリスト — シークレットの検出、禁止パターン
• セキュリティ関連のコミット種類 — セキュリティ修正、機能強化、設定
• シークレットを誤ってコミットした場合 — 即時対応、ローテーション、履歴のクリーンアップ
• 機微なファイルのパターン — .gitignore のテンプレート、コミットしてはいけないファイル
• 監査証跡の要件 — セキュリティコミットに関する CVE、CVSS、CWE のメタデータ

推奨事項／避けるべき事項

推奨：実施すること

• コミットのたびにシークレットスキャンを実行する
• シークレットが漏えいした場合は、ただちにローテーションする
• 認証情報には環境変数を使用する
• CVE／CVSS を記載してセキュリティ修正を文書化する
• 認証関連の変更にはセキュリティチームのレビューを必須とする
• シークレットのパターンに合わせて .gitignore を最新の状態に保つ

悪い例：避けるべきこと

• 秘密情報を「一時的に」コミットする
• テストでハードコードされた認証情報を使用する
• 実際の認証情報をサンプルファイルに保存する
• 削除した秘密情報は安全だと思い込む
• 秘密情報のスキャンが完了する前にコミットする
• セキュリティ修正に汎用的なコミットメッセージを使う

アンチパターン

アンチパターン	問題	対策
「秘密情報は後で追加」	秘密情報を誤ってコミットする	最初から環境変数を使う
テスト内の秘密情報	実際の認証情報がリポジトリに含まれる	モック／テスト用の認証情報を使う
隠すための強制プッシュ	履歴から復元できる	ローテーションして記録する
曖昧なセキュリティ関連のコミット	監査証跡が残らない	CVE／CVSS を含める
コミット前のスキャンなし	秘密情報がリモートに送られる	gitleaks フックをインストールする

---

オプション：AI／自動化

注：AI の提案は人間の意図を尊重する必要があります。

• コミットメッセージの提案 — 差分分析から下書きを作成
• タイプの検出 — パターンに基づいてコミットタイプを推測
• スコープの検出 — 変更されたパスから自動検出

主張の範囲

• AI が生成したメッセージは、人間による確認と修正が必要です
• タイプの自動検出では、文脈を見落とすことがあります
• セキュリティ関連のコミットには、常に人間の判断が必要です

---

リソース

リソース	目的
references/conventional-commits-guide.md	Conventional Commits の仕様とツール
references/commit-message-antipatterns.md	よくある悪いパターン、検出、リント
references/monorepo-commit-conventions.md	複数パッケージのリポジトリ向けスコープ戦略
references/changelog-generation-guide.md	変更履歴ツールの設定、CI との統合
data/sources.json	厳選された外部ソース

---

バージョン: 2.1.1 最終更新日: 2026-01-26 リポジトリ: AI-Agents（ドキュメントリポジトリ） Conventional Commits 仕様: https://www.conventionalcommits.org/