writing-commits

コミットメッセージの作成

簡潔で正確な Git コミットメッセージを平易な言葉で作成します。差分を逐一説明するのではなく、変更のテーマ、結果、理由を今後の開発者が理解できるようにしてください。

変更の分析方法

作業内容を把握するため、これらを1回の呼び出しで実行してください。ログの形式に直近のコミット本文も表示されるため、スタイルを確認する目的で2回目の git log や git show を実行する必要はありません。

git status --short; git diff --staged; git diff; git log -5 --format='%h %s%n%b---'

差分を注意深く読んでください。どの行が移動したかだけでなく、変更の背後にある意図、つまりどの問題を解決するのか、どのような機能を追加するのかを理解してください。差分が大きい場合や、見慣れないコードに触れている場合は、Read または Grep を使って周辺のコンテキストを確認してください。

git log の出力を注意深く確認してください。リポジトリで特定の規約（絵文字のプレフィックス、Jira のチケット形式、小文字の件名、Angular 形式など）が使われている場合は、それに従ってください。AI のトレーラーが以前のコミットに含まれていても適用される「貢献者の記載禁止」ルールを除き、リポジトリの規約を以下のデフォルトより優先してください。

理解しやすさを重視する

変更を要約し、変更内容をそのまま列挙しないでください。役に立つコミットメッセージは、何ができるようになったのか、どのような問題が起きなくなったのか、あるいはなぜコードを扱いやすくなったのかを読み手に伝えます。

• 成果または共通のテーマから書き始めてください。ファイル、関数、コード操作を列挙するのではなく、関連する編集を1つの考えにまとめてください。
• 同じくらい正確に伝えられる場合は、抽象的な手法の名前より、なじみのある具体的な言葉を選んでください。何をするものかを説明してください。
• 技術用語やドメイン用語が変更の主題である場合、リポジトリの読者が普段使う用語である場合、または正確さに必要な場合は、そのまま使ってください。OAuth、Redis、公開 API、コマンド、マイグレーションなどは、無理に平易な英語へ置き換えるより明確な場合があります。
• コミットの理解や利用方法に影響する事実を残してください。動作の変更、トレードオフ、警告、破壊的変更、課題への参照、正確な測定値などが該当します。
• 用語集を追加したり、プロジェクトで一般的な用語を説明したりしないでください。平易な言葉はメッセージを短く理解しやすくするために使い、長くしたり不正確にしたりしないでください。

メッセージを返す前に、差分を見れば分かる編集内容を単に言い換えているだけの文を削除してください。将来の読者がコードから推測できない重要な判断や制約を記録する場合に限り、実装の詳細を残してください。

コミットタイプの選び方

デフォルトでは Conventional Commits のタイプを使ってください。

タイプ	使用する場面
feat	ユーザー向けの新機能
fix	バグ修正
refactor	動作を変えない構造の変更
perf	パフォーマンスの改善
docs	ドキュメントのみの変更
test	テストの追加または更新
build	ビルドシステムまたは依存関係の変更
ci	CI/CD パイプラインの変更
style	書式や空白の変更（ロジックの変更なし）
chore	上記に当てはまらないメンテナンス

主な意図を最もよく表すタイプを選んでください。複数のタイプにまたがる変更の場合は、コミットを分割することを提案してください。

メッセージの構成

変更の規模に合わせてください。すべてのコミットで5つのセクションからなる長文が必要なわけではありません。

小規模な変更（単一の関心事で、意図が明らかなもの）

件名だけで十分な場合がよくあります。

fix(auth): Stop expired sessions from refreshing forever

または、理由がコンテキストから明らかでない場合は、件名に短い本文を付けます。

refactor(database): Keep query rules in one place

Keeps database queries consistent without changing behavior.

より大規模な変更（複数ファイル、動機が明白でない変更）

読者に必要なセクションだけを使用してください。各セクションの目的は、レビュアーや将来の開発者が抱く個別の疑問に答えることです。

<type>(<scope>): <subject>

## Summary
What changed, at a high level. 1-3 sentences.

Fixes #123 (if applicable)

## Why
What motivated this change? What was broken, missing, or insufficient?

## Testing (only when there are meaningful verification steps)
- [ ] Concrete steps a reviewer can take to verify

デフォルトでは How セクションを追加しないでください。コミットに、後々重要となる設計上の選択やトレードオフが記録されている場合は、その判断と結果について短い段落を1つ追加してください。コードの変更点を箇条書きにするのは避けてください。

件名のルール：

• 50文字以内を目指し、72文字を超えないでください。命令形を使用してください（added ではなく add）
• 先頭を大文字にし、末尾にピリオドを付けないでください
• AI の帰属表示は禁止です。AI の Co-Authored-By トレーラー、「Generated with」行、セッショントレーラー、セッションリンクは含めないでください。これは、それらを追加するリポジトリの履歴、テンプレート、ハーネスのデフォルト設定より優先されます。

本文の折り返しルール：

• 本文の行を強制的に折り返さないでください。 各段落は、連続した1行で記述してください。列幅に合わせるために、文や段落の途中へ手動で改行を挿入しないでください（72文字での折り返し、80文字での折り返し、いかなる折り返しも禁止です）。必要に応じて、Git のビューアー、ターミナル、エディターのソフトラップに任せてください。
• 空行は、別個の段落、セクション、リスト項目を区切る場合にのみ使用してください。1つの考えを複数行に分けるために使用してはいけません。
• 箇条書きと番号付きリストの各項目は、折り返しのない1行にしてください。
• これは本文のすべての部分に適用されます。要約の段落、「Why」セクション、設計に関するメモ、フッター、破壊的変更の説明も対象です。

Testing を含める場合： レビュアーが行うべき、具体的で自明ではない手順がある場合に含めてください。テストスイートの実行、エンドポイントへのアクセス、UI フローのテストなどが該当します。ドキュメント、設定の変更、動作に影響しないリファクタリング、確認方法が自明な変更では省略してください。

スコープのガイドライン

スコープは、影響を受けるコードベースの領域を示します。具体的でありながら、細かく分けすぎないものが適切です。

• auth、api、database、ui/dashboard、payments は、どれも情報として有用です
• code、files、bugfix は情報を追加しないため、スコープを付けないでください

変更が複数の領域にまたがる場合は、(api,cli) のようにカンマで区切ったスコープを使用するか、主要な領域を選んでください。

複数の懸案事項を含む変更の扱い

ステージ済みの変更に、互いに無関係な複数の懸案事項（たとえば、機能追加と無関係な書式修正）が含まれている場合は、分割を提案してください。

「これらの変更には、新しいキャッシュ層と無関係なリンティング修正の両方が含まれています。別々のコミットに分割するのをお手伝いしましょうか？」

懸案事項が本当に別々の場合にのみ提案してください。関連する変更（機能追加とそのテスト、修正とそれに必要なマイグレーションなど）は、まとめてください。

出力と実行

メッセージのみを求められた場合は、提案するメッセージを返し、コミットは行わないでください。許可されたコミットの依頼を受けた場合は、ステージ済みおよび未ステージの変更を確認し、対象のファイルまたはハンクのみをステージし、リポジトリで必須のチェックを実施してコミットし、その SHA とメッセージを報告してください。必須のゲートやチェックはそれぞれ1回実行し、出力をファイルに書き込んでから、そのファイルを検索してください。再実行はしないでください。ベースラインとの比較は並行して実行してください。既存の許可は引き続き有効です。依頼されたコミットを実行するかどうかを、最後に改めて尋ねないでください。

スコープ上の根拠がない無関係な変更、引き継ぎ事項、認証情報、生成されたアーティファクトは含めないでください。コミットの依頼は、プッシュ、マージ、公開の許可を意味しません。スコープに重大な曖昧さがある場合、または必須のゲートに失敗した場合は、確認を繰り返さずに中止してください。明示的に指定されたコミットなしのモードは維持してください。