AI開発でコミットメッセージをどう書くべきか
はじめに
AI を使った開発では、「何をしたのか」だけでなく「誰が（人間か AI か）、なぜ、どの Issue に基づいて」を記録することが重要です。本記事では、AI 開発に適したコミットメッセージの書き方を解説します。
悪いコミットメッセージの例
Commit: "fix bugs"
→ 何が修正されたのか不明
Commit: "update code"
→ 何が更新されたのか不明
Commit: "add feature"
→ どの機能か、なぜか不明
1ヶ月後、問題が発生したときに「この修正は何だったのか」を思い出せません。
良いコミットメッセージの構造
【1行目】タイトル（何をしたのか + Issue ID）
【2行目】空行
【3行目以降】詳細
- 変更内容
- 実装責任
- 決定の根拠
- 注意点
具体例1：機能実装
Implement user profile editing feature (#42)
Changes:
- Add UserProfile component with edit form
- Add name, email, bio fields with validation
- Add error handling for API failures
Implementation:
- Implemented by: Claude Code
- Reviewed by: ChatGPT
- Approved by: yamada (Product Manager)
Tests:
- 10 test cases added
- All existing tests pass
Notes:
- File uploads will be added in separate Issue #43
- TypeScript types defined for all props
- Uses existing validation patterns from LoginForm
Related Issues: #42
具体例2：バグ修正
Fix: Handle null user in getUserProfile (#50)
Problem:
- getUserProfile() throws TypeError when user not found
- Affects /profile/:id endpoint
- User reported: "can't view deleted user profiles"
Solution:
- Add null check before accessing user properties
- Return 404 error with meaningful message
- Add 3 test cases for edge cases
Implementation:
- Implemented by: Claude Code
- Issue analysis by: ChatGPT
- Approved by: yamada
Impact:
- No breaking changes
- Existing tests all pass
- 1 new validation test added
Root cause analysis: See Issue #50 for ChatGPT analysis
具体例3：パフォーマンス最適化
Optimize: Cache user data with 5min TTL (#38)
Rationale:
- User data changes infrequently
- Current implementation makes 10+ DB queries per page load
- Target: Reduce queries to 2-3 per page
Implementation:
- Implemented by: Claude Code
- Reviewed by: ChatGPT (alternative approaches considered)
- Decided by: yamada (cache validity trade-off)
Changes:
- Add Redis cache with 5 min expiry
- Invalidate cache on POST/PUT/DELETE
- Add cache metrics logging
Performance:
- Before: 150ms average load time
- After: 45ms average load time
- Estimated QPS improvement: 40%
Testing:
- Load test with 1000 concurrent users
- Cache hit rate: 92%
- Manual cache invalidation verified
Notes:
- Cache TTL (5 min) balance freshness vs performance
See Issue #38 for discussion
- Future: Consider 24hr cache for admin users
コミットメッセージのテンプレート
# [Type] Short description (#IssueID)
## Changes
- Change 1
- Change 2
- Change 3
## Implementation
- Implemented by: [Claude Code / human]
- Reviewed by: [ChatGPT / human]
- Approved by: [human]
## Rationale
Why this change was made. Link to Issue for full context.
## Testing
- [Test approach]
- [Test results]
## Notes
- [Anything reviewers should know]
- [Constraints or future work]
タイプ別のサンプル
Implement (新機能)
Implement: [Feature Name] (#ID)
Changes:
- List each component/file changed
Implementation:
- Implemented by: Claude Code
- Reviewed by: ChatGPT
- Approved by: [human]
Tests:
- [Test count] test cases
- All existing tests pass
Fix (バグ修正)
Fix: [Bug Description] (#ID)
Problem:
- What was broken
Solution:
- How it's fixed
Implementation:
- Implemented by: Claude Code
- Root cause analysis: ChatGPT
- Approved by: [human]
Impact:
- [What's better now]
- No breaking changes
Refactor (リファクタリング)
Refactor: [Code Improvement] (#ID)
Changes:
- What was refactored
Rationale:
- Why this refactoring was needed
- Benefits (performance, maintainability, etc.)
Implementation:
- Implemented by: Claude Code
- Reviewed by: ChatGPT
- Approved by: [human]
Quality:
- All existing tests pass
- No functional changes
- Diff: [size]
AI 開発で重要な項目
✅ 必ず記載
- Implemented by: Claude Code / ChatGPT / human
- Reviewed by: ChatGPT / human / [team member]
- Approved by: [human name or role]
- Related Issues: #42, #43 など
⚠️ 注意が必要
- セキュリティ変更の場合：セキュリティレビュー記録
- DB スキーマ変更：migration 手順記録
- パフォーマンス変更：before/after メトリクス
- API 変更：breaking change の有無
git log で履歴を追跡するときの活用
例：「このバグ、いつから？」
$ git log --grep="Fix: Handle null user"
Commit abc1234 "Fix: Handle null user in getUserProfile (#50)"
Date: 2026-06-22
→ Issue #50 の詳細を確認
→ いつバグが入ったかわかる
→ ChatGPT の分析結果が記録されている
例：「このコード、なぜこんな実装？」
$ git blame src/services/cache.ts
→ Line 45: Cache TTL = 5 min
$ git show 678def:
"Rationale: 5 min cache balances freshness vs performance
See Issue #38 for discussion"
→ 実装理由が記録されている
CI/CD パイプラインでの活用
commit メッセージからリリースノート生成
$ conventional-commits src/
From commit messages:
- Implement: user profile editing
- Fix: null user handling
- Optimize: user data caching
↓
Release notes 自動生成：
「新機能」セクション
「バグ修正」セクション
「パフォーマンス改善」セクション
チーム運用での活用
開発ログ分析
月間レポート生成：
- 新機能数：12
- バグ修正数：5
- パフォーマンス改善：3
- AI実装率：70%
セキュリティレビュー
grep "Security" git log
→ セキュリティ関連の変更を追跡
→ レビュー漏れを検出
まとめ
AI 開発でのコミットメッセージ：
記録すべき情報：
- 何をしたのか（明確に）
- 誰がしたのか（AI か人間か）
- なぜしたのか（Issue へのリンク）
- テスト結果
活用：
- git log で履歴追跡
- 問題発生時の原因調査
- チーム知識共有
- リリースノート自動生成
AI 開発で作業ログを残すメリットと合わせることで、変更履歴が完全に記録され、保守性が大きく向上します。