git-commit

Git コミットの標準

コミットはコードベースの歴史を伝えます。優れたコミット履歴は、どれだけドキュメントを用意するよりも価値があります。常に最新の状態だからです。

コミュニティのデフォルトです。git-commit を明示的に上書きするプロジェクトのスキルまたはエージェント設定ルールがある場合は、そちらが優先されます。

1. Conventional Commits 形式

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

タイプ：

タイプ	使用する場面
feat	新機能（semver の MINOR に相当）
fix	バグ修正（semver の PATCH に相当）
refactor	バグ修正でも機能追加でもないコード変更
perf	パフォーマンスの改善
test	テストの追加または修正
docs	ドキュメントのみの変更
chore	ビルドプロセス、ツール、依存関係
ci	CI/CD 設定の変更
style	フォーマット、空白（CSS ではなくコードのフォーマット）

スコープ：

パッケージ名またはモジュールの領域を使用します。

feat(auth): add JWT refresh token rotation
fix(store/postgres): handle connection pool exhaustion
refactor(service): extract validation into dedicated package
test(handler): add table-driven tests for user endpoints
chore(deps): bump go.uber.org/zap to v1.27.0

破壊的変更：

feat(api)!: change pagination from offset to cursor-based

BREAKING CHANGE: The `offset` and `limit` query parameters are replaced
by `cursor` and `page_size`. All existing clients must migrate.

2. コミットメッセージのルール

件名行：

• 命令形にします。「add feature」のようにし、「added feature」や「adds feature」にはしません
• タイプの接頭辞の後は小文字にします
• 末尾にピリオドを付けません
• 最大 72 文字です
• どのように変更したかではなく、何を変更したかを記述します

本文（必要な場合）：

• 件名と本文の間に空行を入れます
• 変更が必要だった理由を説明します
• 大まかなレベルで何が異なるのかを説明します
• 72 文字で折り返します

フッター：

• Issue を参照します：Fixes #123、Closes #456、Refs #789
• 共同作成者を記載します：Co-authored-by: Name <email>
• 破壊的変更を記載します：BREAKING CHANGE: description

3. 例

簡単な変更：

fix(handler): return 404 instead of 500 for missing user

本文付き：

refactor(service): replace manual SQL with sqlx named queries

The raw SQL string concatenation for dynamic WHERE clauses was
error-prone and difficult to maintain. sqlx named queries provide
the same flexibility with automatic parameter binding.

No behavior change — all existing tests pass.

破壊的変更：

feat(config)!: migrate from YAML to environment variables

BREAKING CHANGE: Configuration is now loaded from environment
variables instead of config.yaml. See README.md for the full
list of supported variables.

Closes #234

依存関係の更新：

chore(deps): upgrade pgx to v5.5.0

Picks up connection pool improvements and fixes for
COPY protocol handling. See release notes:
https://github.com/jackc/pgx/releases/tag/v5.5.0

4. アトミックコミット

各コミットは、次の条件を満たす論理的な変更を 1 つだけ含めます。

• 単独でコンパイルできる（go build ./... が成功する）
• テストに合格する（go test ./... が成功する）
• 他の変更を壊すことなく個別に取り消せる

大きな変更を分割する：

# ❌ Bad — one commit doing everything
feat(user): add user management with CRUD, validation, auth, and tests

# ✅ Good — atomic, reviewable commits
feat(domain): add User entity and validation rules
feat(store): implement PostgreSQL user repository
feat(service): add user service with create and get operations
feat(handler): add REST endpoints for user management
test(service): add table-driven tests for user creation
docs(api): document user endpoints in OpenAPI spec

5. コミット前の検証

コミットする前に、次を実行します。

# Format and lint
goimports -w .
golangci-lint run

# Build
go build ./...

# Test
go test -race ./...

# Tidy modules
go mod tidy

いずれかの手順で失敗した場合は、コミットする前に修正します。「後で直す」といって壊れたコードをコミットしてはいけません。後で直すことはありません。

6. コミットのワークフロー

# Stage specific files (not git add .)
git add internal/service/user.go
git add internal/service/user_test.go

# Review staged changes
git diff --staged

# Commit with message
git commit -m "feat(service): add user creation with email validation"

# Or use editor for longer messages
git commit  # opens $EDITOR

PR 前のインタラクティブなリベース：

インタラクティブなリベースでは $EDITOR が開くため、エージェントは操作できません。まず非インタラクティブに修正コミットを準備し、最後の手順を開発者に引き継ぎます。

# Mark a commit as a fixup of an earlier one (no editor)
git commit --fixup <sha>

# Collapse them automatically (no editor with --autosquash + GIT_SEQUENCE_EDITOR)
GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash main

並べ替えやメッセージの書き換えが必要な場合は、エージェントが試みるのではなく、開発者自身に git rebase -i main を実行するよう伝えてください。

7. コミットしてはいけないもの

• 生成ファイル（必須でない場合の *.pb.go、mocks/）
• IDE の設定（.idea/、.vscode/。グローバル gitignore を使用します）
• OS のファイル（.DS_Store、Thumbs.db）
• バイナリとビルド成果物
• シークレットを含む .env ファイル
• vendor/（プロジェクトのポリシーで明示的に必要とされている場合を除く）