Commit Message Guide

本ガイドは、プロジェクトにおけるコミットメッセージの基本構造、ヘッダー部の構文フォーマット、プレフィックス（prefix）の適用ルール、および参照情報の記述規約を定義するものです。

Message Structure

コミットメッセージは以下の2部構造で構成されます。

1. ヘッダー部 (Header): 主要な情報を集約して1行で記述する 必須 セクション。
2. 詳細部 (Details): 変更の動機・背景・実装詳細、補足情報等を記述する任意セクション（空行を挟んで記述）。

<prefix>[(<scope>)]: <summary> [<TaskID>] [Refs: <ref-id>]

[詳細部 (Details) - 変更の動機や詳細な説明、補足情報]

Header Syntax & Format

基本として ヘッダー部に主要な情報をすべて集約 して記述します。

基本構文

<prefix>[(<scope>)]: <summary> [<TaskID>] [Refs: <ref-id>]

要素	必須/任意	説明	例
<prefix>	原則必須	変更のカテゴリまたは仕様/課題ID	SPEC-001, ISSUE-002, docs
(<scope>)	任意	影響を受けるソフトウェアコンポーネント（AppID やモジュール）。ソフトウェアコンポーネント外では指定がない限り使用しない	(webui), (auth-service)
<summary>	必須	変更内容の簡潔な1行要約。 破壊的変更 の場合は先頭に BREAKING CHANGE: を付与	ログイン画面のバリデーションを追加, BREAKING CHANGE: 認証API構造を変更
[<TaskID>]	任意	対応するタスク詳細の ID（値は <SPEC-ID>）	[SPEC-001-1]
[Refs: <ref-id>]	任意	影響を受ける他 SPEC や関連参照 ID	[Refs: SPEC-002, SPEC-003]

---

Prefix Rules

コミット粒度の原則

• コミットは原則として 最小作業単位（Work Item） で行います。
• 最小作業単位が不明な場合は、最小の機能単位 または 最小の主題単位 に分割してコミットします。
• ソースコードと関連文書の集約: コミット単位には、実装したソースコードおよびそれに関連する文書（設計書・仕様書・テスト仕様書等）をまとめて含めます。

プレフィックス適用の判定基準

コミット単位の中に ソフトウェアコンポーネントのソースコードが含まれているか否か に応じて、適用する Prefix 規則を決定します。

• ソースコードが含まれている場合: 関連する文書が同時に含まれている場合も含め、「1. ソフトウェアコンポーネントに対する変更」 の規則に従います。
• ソースコードが含まれていない場合: ドキュメント単体や環境設定等の変更であるため、「2. ソフトウェアコンポーネント外に対する変更」 の規則に従います。

1. ソフトウェアコンポーネントに対する変更 (apps/ 配下等)

コミット単位にソフトウェアコンポーネントのソースコード（apps/ 配下等）が含まれる場合、<prefix> には原則として以下のいずれかを指定します。

• spec-id: 機能仕様書 ID（例: SPEC-001）
• issue-id: 課題・不具合 ID（例: ISSUE-001）
• 外部管理番号: 外部プロジェクト管理ツール（Jira, Redmine 等）のチケット管理番号（例: PROJ-123）
• <scope> の指定: 変更が影響を与えるソフトウェアコンポーネント（AppID やモジュール）を括弧付きで指定します（例: (webui)）。

※ <prefix> なしのコミット表記もフォーマット上許可されますが、変更の追跡性を保つため 原則として非推奨 とし、適切な prefix を指定することを推奨します。

Refs (参照) の利用

複数コンポーネント間で影響が広がる変更等の場合は、Refs に参照・関連する spec-id や issue-id をカンマ区切りで併記可能です（例: [Refs: SPEC-002, SPEC-003]）。

2. ソフトウェアコンポーネント外に対する変更 (docs/, 全体設定等)

コミット単位にソフトウェアコンポーネントのソースコードが含まれない場合（ドキュメント単体や設定変更等）、基本プレフィックスとして docs または chore を使用します。

• docs: docs/ 配下のファイル変更・ドキュメント更新に適用します。（※ docs/ とそれ以外のディレクトリが同時に含まれる変更の場合も docs を優先指定します）。
• chore: ドキュメント以外の全体設定・ビルド構成・環境整備等に適用します。
• 任意の追加 prefix: 必要に応じて ci, refactor, test などのプレフィックスを任意に追加・使用することを許可します。
• <scope> の扱い: <scope> はソフトウェアコンポーネントに対してのみ使用します。ソフトウェアコンポーネント外に対する変更では、指定がない限り <scope> は使用しません（例: docs: ..., chore: ...）。

3. 特例ルール (revert / merge)

• Revert コミット: コミットの打ち消し（revert）を行う場合、Git が自動生成するコミットメッセージ（例: Revert "..."）をそのまま使用します。
• マージコミット: ブランチ等のマージ（merge）を行う場合、Git や Pull Request 等が自動生成するコミットメッセージ（例: Merge branch '...' into ... や Merge pull request #...）をそのまま使用します。

---

Examples

• 機能仕様に基づく実装: SPEC-001(webui): ログインフォームのバリデーション実装 [SPEC-001-1]
• 複数 SPEC に影響する変更: SPEC-001(auth-service): 共通認証トークンの生成処理追加 [SPEC-001-2] [Refs: SPEC-002]
• 課題・不具合修正: ISSUE-005(webui): セッションタイムアウト時の再描画バグを修正
• ドキュメント更新: docs: コミットメッセージガイドラインを追加
• 環境整備・設定更新: chore: CI設定の更新
• 打ち消し (Revert): Revert "SPEC-001(webui): ログインフォームのバリデーション実装 [SPEC-001-1]"
• マージコミット (Merge): Merge branch 'feature/login' into main
• 破壊的変更 (Breaking Change): SPEC-001(auth-service): BREAKING CHANGE: 認証APIレスポンスの構造を変更 [SPEC-001-3]