conventional-commit

Conventional Commits に準拠したステージ済みファイルのコミット

ユーザーが現在ステージ済み（インデックス済み）の git ファイルを、 Conventional Commits の仕様とコミットメッセージのベストプラクティスに従ってコミットできるよう支援します。

事前チェック

コミットメッセージを作成する前に、必ず次の操作を行います。

1. git status を実行して、ステージ済みのファイルを確認します
2. git diff --cached を実行して、実際のステージ済み変更を確認します
3. ステージ済みの変更がない場合は、ユーザーに伝えて終了します。空のコミットは作成しないでください

Conventional Commit の形式

<type>[optional scope]: <subject>

[optional body]

[optional footer(s)]

タイプ

タイプ	使用する場面
feat	新しい機能や能力
fix	バグ修正
docs	ドキュメントのみの変更
style	フォーマット、空白、セミコロンなど。ロジックの変更はなし
refactor	動作を変えないコードの再構成
perf	パフォーマンスの改善
test	テストの追加または更新
build	ビルドシステムまたは外部依存関係の変更
ci	CI/CD 設定の変更
chore	メンテナンス作業（依存関係の更新、ツール、設定）
revert	以前のコミットの取り消し

注：コメントのみの変更（コードコメントの追加、更新、削除）には、style または chore を使用してください。feat や fix は使用しないでください。コミットメッセージは簡潔にし、個々のコメントについて説明しないでください。

スコープ

• 省略可能ですが、変更対象が特定のモジュール、コンポーネント、領域の場合は付けることを推奨します
• 小文字のケバブケースを使用します：feat(auth):、fix(api-client):
• プロジェクトで既に使用されているスコープの規則に合わせます
• 最近の git ログを確認（git log --oneline -50 以上）し、プロジェクトで使用されているスコープのパターンを確認します
• プロジェクトが実際に Conventional Commits を使用しているかどうかも確認します。使用していない場合は、プロジェクトのスタイルに合わせます

件名のルール

• 命令形：「add feature」とし、「added feature」や「adds feature」とはしません
• 先頭は小文字：「Add feature」ではなく「add feature」
• 末尾にピリオドを付けない
• 50 文字以内。上限は 72 文字です
• 文として成立させる：「このコミットを適用すると、<subject> します」

本文のルール

• 件名との間に空行を入れます
• 72 文字で折り返します
• 何を、なぜ変更したかを説明し、どのように変更したかは説明しません（その方法は差分に示されています）
• 件名だけでは変更を理解するのに不十分な場合に使用します
• 関連する変更が複数ある場合は箇条書きを使用します

フッターのルール

• 破壊的変更には BREAKING CHANGE: <説明> を使用します（メジャーバージョンの更新が発生します）
• イシューを参照する場合は Refs: #123 または Closes #456 を使用します
• 共著者には Co-authored-by: Name <email> を使用します
• プロジェクトで Developer Certificate of Origin（DCO）が求められる場合は Signed-off-by: Name <email> を使用します

判断プロセス

次の手順に従ってコミットメッセージを決定します。

手順 1：ステージ済みの変更を分析する

差分を注意深く読み、次の点を特定します。

• 変更されたファイルとその目的
• 変更が単一の論理的な変更か、相互に関連のない複数の変更か
• 主な意図：新機能、バグ修正、リファクタリングなど

ステップ 2：論理的な変更が複数あるか確認する

ステージされた変更に互いに無関係な変更が複数含まれている場合：

• ユーザーに次のように伝えます：「ステージされた変更には、互いに無関係な変更が複数含まれています。 履歴を整理しやすくするため、個別のコミットに分けることを検討してください。」
• 論理的にまとめる案として、変更を次のカテゴリに分類します：
  • 整理 — 書式設定、名前変更、不要なコードの削除（動作の変更なし）
  • インフラ／ビルド — 依存関係、ツール、設定
  • 機能実装 — 新しい機能
  • バグ修正 — 誤った動作の修正
  • ドキュメント — ドキュメントのみの変更
• 依存関係のマニフェストとロックファイルは、同じグループにまとめます（例：package.json + package-lock.json、 go.mod + go.sum、Cargo.toml + Cargo.lock、pyproject.toml + ロックファイル）
• 一貫した流れになるよう、コミット順を提案します：
  1. 整理／構造上の変更を最初に行う（動作変更とは分ける）
  2. 関連するコード変更より先にドキュメントを更新する
  3. 依存する機能より先にインフラ／ビルドの変更を行う
  4. 機能または修正のコミットを最後に行う
• 1 つのコミットで進めるか、分割するかはユーザーに判断してもらいます

ステップ 3：種類を決める

• 「この変更の主な目的は何か」と自問します
• 機能にテストが含まれる場合、種類は test ではなく feat です
• バグ修正にリファクタリングが含まれる場合、種類は refactor ではなく fix です
• 種類は、変更されたすべてのファイルではなく、変更の理由を表します
• 例外 — スコープ自体が種類を示す場合：変更されたすべてのファイルが、独自の種類を持つ単一の領域に属している場合は、スコープを付けずにその種類を直接使用します。たとえば、CI/CD ファイル（例：.github/workflows/）のみを変更するコミットでは、fix(ci): や feat(ci): ではなく ci: を使用します。同じルールは、docs:（ドキュメントファイルのみ）、test:（テストファイルのみ）、build:（ビルド設定のみ）にも適用されます。これらの種類だけでスコープが伝わるため、括弧内に追加すると重複します。

ステップ 4：スコープを決める

• コードベースのどの領域に影響するかを確認します
• 既存のスコープの慣例を確認するため、git log --oneline -50 を実行します
• 変更が複数の領域にまたがる場合は、スコープを省略するか、主要な領域を使用します

ステップ 5：件名を書く

• 命令形で変更内容を簡潔に説明します
• ユーザーまたは開発者への影響に焦点を当てます
• 悪い例：fix(api): fixed the bug in the login endpoint
• 良い例：fix(api): return 401 on expired token instead of 500

ステップ 6：本文を書く（必要な場合）

次の場合は本文を追加します：

• 件名だけでは変更内容を十分に説明できない
• 重要な背景がある（この方法を選んだ理由、検討した選択肢など）
• 変更に副作用や、わかりにくい影響がある
• ドキュメントに記載すべき破壊的変更がある

ステップ 7：提示して確認を得る

• 完全なコミットメッセージをユーザーに提示します
• コミットを実行する前に承認を待ちます
• ユーザーが変更を希望する場合は、それに応じて調整します

コミットの実行

コミットを実行するとき：

• 複数行のメッセージには HEREDOC を使い、git commit -m を実行します
• --no-verify は絶対に使用しません — pre-commit フックを尊重します
• ユーザーが明示的に要求しない限り、--amend は絶対に使用しません
• pre-commit フックが失敗した場合は、原因を調査して問題を修正し、新しいコミットを作成します
• コミット後、成功を確認するために git status を実行します

1 行のコミット

git commit -m "feat(auth): add JWT token refresh endpoint"

複数行のコミット

git commit -m "$(cat <<'EOF'
feat(auth): add JWT token refresh endpoint

Implement automatic token refresh when the access token expires.
The refresh endpoint validates the refresh token and issues a new
access token with a 15-minute expiry.

Closes #234
EOF
)"

例

シンプルな機能

feat: add dark mode toggle to settings page

背景を含むバグ修正

fix(parser): handle empty input without panic

The YAML parser panicked on empty strings because it attempted
to access the first character without a length check. Now returns
an empty document instead.

Closes #89

破壊的変更

feat(api)!: require authentication for all endpoints

All API endpoints now require a valid Bearer token. Previously,
read-only endpoints were publicly accessible.

BREAKING CHANGE: unauthenticated requests to /api/* now return 401.
Clients must include an Authorization header with a valid token.

Refs: #156

ドキュメントの更新

docs: add API rate limiting guide

リファクタリング

refactor(db): extract connection pooling into dedicated module

Move connection pool logic from the monolithic database module into
its own module to improve testability and separation of concerns.
No behavior change.

避けるべきアンチパターン

アンチパターン	なぜ問題なのか	より良い代替案
fix: fix bug	何の役にも立つ情報がありません	fix(cart): prevent negative quantities
update code	規約に沿ったコミットではありません	refactor(utils): simplify date parsing
feat: Added new feature and fixes	過去形で、曖昧で、対象範囲が混在しています	別々のコミットに分けます
WIP	履歴として意味がありません	説明的なメッセージまたは --fixup を使います
misc changes	何が変わったのか分かりません	実際に変更した内容を説明します
fix: fix	冗長で意味がありません	実際に修正した内容を説明します
72 文字を超える件名	ツールや読みやすさに支障をきたします	簡潔にまとめ、詳細は本文に記載します

Fixup コミット

ユーザーが変更をfixupと指定した場合（例：「これは fixup です」「fixup の変更」「前のコミットに付けて」）、 問題を引き起こした元のコミットを対象とする fixup! コミットを作成します。

Fixup の手順

1. ブランチの境界を特定する — 何よりも先に、現在のブランチに属するコミットを特定します。

   git log --oneline $(git merge-base HEAD origin/main)..HEAD
   

   これが安全にリベースできる範囲です。この範囲内のコミットのみを fixup または autosquash の対象にできます。

2. 対象コミットを特定する — git log を検索し、修正対象のコードを導入したコミットを探します。

   • git log --oneline $(git merge-base HEAD origin/main)..HEAD -- <changed-files> を使い、現在のブランチで同じファイルに変更を加えたコミットを探します
   • 修正内容に件名が最もよく一致するコミットを選びます
   • 重要なガードレール：対象コミットがブランチ範囲内にない場合（つまり、main 上またはブランチポイントより前にある場合）、fixup コミットを作成しないでください。その代わりにユーザーに伝え、適切な種類（例：fix、ci）の通常のコミットを作成します

3. fixup コミットを作成する — git commit --fixup <target-sha> を使います。

   git commit --fixup abc1234
   

   これにより、メッセージが fixup! <original subject> のコミットが作成されます。

4. autosquash を行うかユーザーに尋ねる — fixup コミットの作成後、次のように尋ねます。

   「Fixup コミットを作成しました。今すぐ対象コミットに autosquash しますか （git rebase --autosquash）？」

5. ユーザーが承諾した場合、ブランチの範囲内で autosquash を使った対話型リベースを実行します。

   GIT_SEQUENCE_EDITOR=true git rebase --autosquash $(git merge-base HEAD origin/main)
   

   GIT_SEQUENCE_EDITOR=true を使うと、リベースエディターが自動で確定され、非対話的に実行できます。 絶対に merge-base より前までリベースしないでください。main と共有されているコミットを書き換えることになります。

6. ユーザーが断った場合、fixup コミットはそのまま残します。今後のリベース時にスカッシュされます。

Fixup の例

# Original commit:
a1b2c3d feat(auth): add OAuth2 login flow

# Fixup commit (auto-generated message):
fixup! feat(auth): add OAuth2 login flow

重要なガイドライン

• コミットメッセージを書く前に必ず差分を確認してください — 推測してはいけません
• シークレットをコミットしないでください（.env、API キー、認証情報など）— ステージされている場合はユーザーに警告してください
• プロジェクトの規約を尊重してください — 最近の履歴を確認してパターンを把握します
• コミットごとに論理的な変更は 1 つにしてください — 適切な場合は分割を提案します
• コミットする前に確認してください — 必ず最初にメッセージを提示し、承認を得ます