commit

コミットのベストプラクティス

このスキルでは、論理的でアトミックな、適切に構成されたコミットを作成できるようにします。コミットは単なる保存ポイントではありません。将来の開発者（および AI エージェント）が、コードベースの 履歴 と 意図 を理解するためのコミュニケーション手段です。

🧠 考え方と理念

• 仕組みだけでなく意図を伝える： コードを見れば、何が変更されたかはわかります。コミットメッセージでは、なぜ変更したのかを伝える必要があります。
• アトミックなコミット： 1 つのコミットで行う変更は 1 つだけにします。バグ修正と機能追加を行う場合は、2 つのコミットに分けます。これにより、取り消し、リベース、レビューが大幅に容易になります。
• 読み手は未来の人です： 6 か月後の午前 3 時に問題をデバッグしている人に変更を説明するつもりで、コミットメッセージを書きます。

🚫 避けるべきパターン

• コードの動作を本文に書かないでください。 「42 行目に if 文を追加した」とは書きません。「ユーザープロフィールがない場合にクラッシュしないよう、null チェックを追加した」と書きます。
• コミットメッセージに絵文字を使わないでください。 すべてのターミナル環境との互換性を確保し、統一されたプロフェッショナルな検索可能な Git 履歴を維持できます。
• 曖昧な件名は避けてください。 「バグを修正」「ファイルを更新」「WIP」には意味がありません。git log --oneline を見ても、背景がまったくわかりません。
• 無関係な変更をまとめないでください。 auth システムの作業中に README.md の誤字に気づいた場合は、誤字の修正と auth の機能を別々にコミットします。
• 自分の差分を確認せずにコミットしないでください。 git diff --cached を実行するか、ステージされた変更を確認し、デバッグ用の記述（console.log、print）や秘密情報が誤って含まれていないことを確かめます。

📝 手順とワークフロー

コミットを作成する前に、次の手順に従ってください。

1. 差分を確認する： 具体的に何をコミットしますか？ 無関係な変更はありませんか？
2. 種類を決める： 最も適切な Conventional Commit の種類を選びます。
3. メッセージを作成する： 件名を書き、必要に応じて理由を説明する詳しい本文を追加します。
4. 共著者： コミットメッセージ本文の末尾に、AI エージェントとユーザーの Co-authored-by: を追加します。
5. 検証する： 作成したメッセージの形式が要件を満たしていることを確認します。

🏷️ Conventional Commits の形式

形式： <type>[optional scope][optional !]: <description>

有効な種類

• feat：新機能
• fix：バグ修正
• docs：ドキュメントのみの変更
• style：コードの意味に影響しない変更（空白、フォーマット、セミコロンの不足など）
• refactor：バグ修正にも機能追加にも該当しないコード変更
• perf：パフォーマンスを改善するコード変更
• test：不足しているテストの追加、または既存のテストの修正
• build：ビルドシステムまたは外部依存関係に影響する変更
• ci：CI 設定ファイルとスクリプトの変更
• chore：src ファイルや test ファイルを変更しないその他の変更
• revert：以前のコミットの取り消し

件名のルール

• Git ツールで見やすく表示されるよう、件名は 50 文字以内にします。
• 命令形の現在形を使います。「changed」や「changes」ではなく「change」とします。
• 先頭の文字は大文字にしないでください。
• 末尾にピリオドを付けないでください。

本文のルール（複雑な変更の場合は推奨）

• 件名との間に空行を 1 行入れます。
• 1 行は 72 文字で折り返します。
• どのように 変更したかではなく、何を、なぜ 変更したかを説明します。

破壊的変更

• 件名のコロンの前に ! を付けます（例：feat(api)!: remove v1 endpoints）。
• 本文の最後に BREAKING CHANGE: <description> を含めます。

💡 例

例 1：新機能 入力：JWT トークンによるユーザー認証を追加 出力：

feat(auth): implement JWT-based authentication

例 2：背景を含むバグ修正 入力：ユーザーがログインボタンを 2 回クリックすると発生するクラッシュを修正 出力：

fix(login): resolve crash on double click

The login button was missing a debounce handler, allowing users to
submit multiple network requests. Added a 500ms debounce to prevent
race conditions during authentication.

例 3：破壊的変更 入力：/users エンドポイントの API レスポンスを、単一のオブジェクトではなくオブジェクトの配列を返すように変更 出力：

feat(api)!: return array of objects from /users endpoint

BREAKING CHANGE: The `/users` endpoint now returns an array of user
objects instead of a single user object. Clients will need to update
their parsing logic.

✅ 検証

コミットする前に、付属の検証スクリプトを実行してメッセージ形式を検証してください。スクリプトの場所がわからない場合は、SKILL.md のパスを基準に探すか、find を使用してください。

# Example assuming you are in the repo root:
bash skills/commit/scripts/validate-commit.sh "your commit message"