semantic-commit
Git変更の論理的分割、Conventional Commitsメッセージ生成、プロジェクト規約検出。大きな変更を意味のある最小単位に分割してコミットする際に使用。
When & Why to Use This Skill
The Semantic Commit skill automates the process of organizing Git changes into logical, atomic commits following the Conventional Commits specification. It analyzes code diffs to detect functional boundaries, identifies project-specific linting rules, and generates descriptive commit messages, significantly improving repository maintainability and code review efficiency.
Use Cases
- Splitting monolithic changes: Automatically break down large updates involving multiple features, fixes, and documentation into separate, manageable commits based on logical boundaries.
- Standardizing commit history: Generate consistent, structured commit messages (feat, fix, chore, etc.) that comply with the Conventional Commits standard and project-specific configurations.
- Enhancing code reviewability: Organize complex changes by functional areas or dependency layers to help reviewers understand the intent and impact of each modification more clearly.
- Automated convention detection: Identify existing project rules from configuration files like commitlint.config.js or package.json to ensure seamless integration with established team standards.
- Streamlining bug tracking: Ensure each commit addresses a single concern, making it easier to use tools like git bisect for pinpointing the origin of regressions.
| name | semantic-commit |
|---|---|
| description | Git変更の論理的分割、Conventional Commitsメッセージ生成、プロジェクト規約検出。大きな変更を意味のある最小単位に分割してコミットする際に使用。 |
| allowed-tools | Read, Grep, Glob |
Semantic Commit Skill
Git変更を意味のある最小単位に分割し、セマンティックなコミットメッセージを生成するための知識ベース。
「大きな変更」の検出基準
以下の条件で大きな変更として検出:
- 変更ファイル数: 5ファイル以上
- 変更行数: 100行以上
- 複数機能: 2つ以上の機能領域にまたがる
- 混在パターン: feat + fix + docs が混在
# 変更規模の分析
CHANGED_FILES=$(git diff HEAD --name-only | wc -l)
CHANGED_LINES=$(git diff HEAD --stat | tail -1 | grep -o '[0-9]\+ insertions\|[0-9]\+ deletions' | awk '{sum+=$1} END {print sum}')
if [ $CHANGED_FILES -ge 5 ] || [ $CHANGED_LINES -ge 100 ]; then
echo "大きな変更を検出: 分割を推奨"
fi
分割戦略
1. 機能境界による分割
# ディレクトリ構造から機能単位を特定
git diff HEAD --name-only | cut -d'/' -f1-2 | sort | uniq
# → src/auth, src/api, components/ui など
2. 変更種別による分離
# ファイルの変更タイプを判定
git diff HEAD --name-status | while read status file; do
case $status in
A) echo "$file: 新規作成 → feat:" ;;
M) echo "$file: 修正 → fix/refactor:" ;;
D) echo "$file: 削除 → chore:" ;;
R*) echo "$file: リネーム → refactor:" ;;
esac
done
3. 依存関係の分析
# インポート関係の変更を検出
git diff HEAD | grep -E '^[+-].*import|^[+-].*require' | \
cut -d' ' -f2- | sort | uniq
論理的グループ化の基準
機能単位: 同一機能に関連するファイル
src/auth/配下のファイル → 認証機能components/配下のファイル → UIコンポーネント
変更種別: 同じ種類の変更
- テストファイルのみ →
test: - ドキュメントのみ →
docs: - 設定ファイルのみ →
chore:
- テストファイルのみ →
依存関係: 相互に関連するファイル
- モデル + マイグレーション
- コンポーネント + スタイル
変更規模: 適切なコミットサイズの維持
- 1コミットあたり10ファイル以下
- 関連性の高いファイルをグループ化
Conventional Commits 形式
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
標準タイプ
必須タイプ:
- feat: 新機能(ユーザーに見える機能追加)
- fix: バグ修正
任意タイプ:
- build: ビルドシステムや外部依存関係の変更
- chore: その他の変更(リリースに影響しない)
- ci: CI設定ファイルやスクリプトの変更
- docs: ドキュメントのみの変更
- style: コードの意味に影響しない変更(空白、フォーマット、セミコロンなど)
- refactor: バグ修正や機能追加を伴わないコード変更
- perf: パフォーマンス改善
- test: テストの追加や修正
スコープ(任意)
変更の影響範囲を示す:
feat(api): add user authentication endpoint
fix(ui): resolve button alignment issue
docs(readme): update installation instructions
Breaking Change
APIの破壊的変更がある場合:
feat!: change user API response format
BREAKING CHANGE: user response now includes additional metadata
プロジェクト規約の自動検出
CommitLint設定ファイル検索順序
- commitlint.config.mjs
- commitlint.config.js
- commitlint.config.cjs
- commitlint.config.ts
- .commitlintrc.js
- .commitlintrc.json
- .commitlintrc.yml
- .commitlintrc.yaml
- package.json の commitlint セクション
# 設定ファイル例の確認
cat commitlint.config.mjs
cat .commitlintrc.json
grep -A 10 '"commitlint"' package.json
カスタムタイプの検出
プロジェクト独自のタイプ例:
// commitlint.config.mjs
export default {
extends: ['@commitlint/config-conventional'],
rules: {
'type-enum': [
2,
'always',
[
'feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore',
'wip', // 作業中
'hotfix', // 緊急修正
'release', // リリース
'deps', // 依存関係更新
'config' // 設定変更
]
]
}
}
フォールバック動作
設定ファイルが見つからない場合:
git log分析による自動推測
git log --oneline -100 --pretty=format:"%s" | \ grep -oE '^[a-z]+(\([^)]+\))?' | \ sort | uniq -c | sort -nrConventional Commits標準をデフォルト使用
言語判定
デフォルト: 英語(en)
--lang ja オプションが指定された場合のみ日本語でコミットメッセージを生成する。
技術的実装
順次コミットフロー
# 1. 前処理: 現在の状態を保存
git reset HEAD
CURRENT_BRANCH=$(git branch --show-current)
# 2. グループ別の順次コミット実行
while IFS= read -r commit_plan; do
group_num=$(echo "$commit_plan" | cut -d':' -f1)
files=$(echo "$commit_plan" | cut -d':' -f2- | tr ' ' '\n')
# 該当ファイルのみをステージング
echo "$files" | while read file; do
if [ -f "$file" ]; then
git add "$file"
fi
done
# ステージング状態の確認
staged_files=$(git diff --staged --name-only)
if [ -z "$staged_files" ]; then
continue
fi
# コミット実行
git commit -m "$commit_msg"
done < /tmp/commit_plan.txt
# 3. 完了後の検証
remaining_changes=$(git status --porcelain | wc -l)
if [ $remaining_changes -eq 0 ]; then
echo "すべての変更がコミットされました"
fi
エラーハンドリング
# プリコミットフック失敗時の処理
commit_with_retry() {
local commit_msg="$1"
local max_retries=2
local retry_count=0
while [ $retry_count -lt $max_retries ]; do
if git commit -m "$commit_msg"; then
return 0
else
# プリコミットフックによる自動修正を取り込み
if git diff --staged --quiet; then
git add -u
fi
retry_count=$((retry_count + 1))
fi
done
return 1
}
実際の分割例(Before/After)
例1: 大規模な認証システム追加
Before(1つの巨大なコミット):
feat: implement complete user authentication system with login, registration, password reset, API routes, database models, tests and documentation
After(意味のある5つのコミットに分割):
feat(db): add user model and authentication schema- src/database/migrations/001_users.sql
- src/database/models/user.js
- src/auth/types.js
feat(auth): implement core authentication functionality- src/auth/login.js
- src/auth/register.js
- src/auth/password.js
- src/middleware/auth.js
feat(api): add authentication API routes- src/api/auth-routes.js
test(auth): add comprehensive authentication tests- tests/auth/login.test.js
- tests/auth/register.test.js
- tests/api/auth-routes.test.js
docs(auth): add authentication documentation and configuration- docs/authentication.md
- package.json
- README.md
- .env.example
例2: バグ修正とリファクタリングの混在
Before:
fix: resolve user validation bugs and refactor validation logic with improved error handling
After(種別別に3つのコミットに分割):
fix: resolve user validation and authentication bugs- src/user/service.js(バグ修正部分のみ)
- src/auth/middleware.js
refactor: extract and improve user validation logic- src/user/service.js(リファクタリング部分)
- src/user/validator.js
- src/api/user-routes.js
chore: update documentation and dependencies- docs/user-api.md
- package.json
分割効果の比較
| 項目 | Before(巨大コミット) | After(適切な分割) |
|---|---|---|
| レビュー性 | 非常に困難 | 各コミットが小さくレビュー可能 |
| バグ追跡 | 問題箇所の特定が困難 | 問題のあるコミットを即座に特定 |
| リバート | 全体をリバートする必要 | 問題部分のみをピンポイントでリバート |
| 並行開発 | コンフリクトが発生しやすい | 機能別でマージが容易 |
| デプロイ | 全機能を一括デプロイ | 段階的なデプロイが可能 |
トラブルシューティング
コミット失敗時
- プリコミットフックの確認
- 依存関係の解決
- 個別ファイルでの再試行
分割が適切でない場合
- 手動での
editモード使用 - より細かい単位での再実行
前提条件
- Gitリポジトリ内で実行
- 未コミットの変更が存在すること
- ステージングされた変更は一旦リセットされる
注意事項
- 自動プッシュなし: コミット後の
git pushはユーザーが手動実行 - ブランチ作成なし: 現在のブランチでコミット