Commit Message Guide

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

Message Structure

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

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

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

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

Header Syntax & Format

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

基本構文

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

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

Prefix Rules

コミット粒度の原則

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

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

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

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

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

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

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

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

対象の増分仕様（<SPEC-I-ID>）を参照している親機能仕様書（<SPEC-ID>）が存在する場合は、Refs にその spec-id（例: SPEC-001）を記述します。また、複数コンポーネント間で影響が広がる変更や関連する仕様がある場合は、関連する spec-id、spec-i-id、または issue-id をカンマ区切りで併記可能です（例: [Refs: SPEC-001], [Refs: SPEC-001, SPEC-I-002]）。

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

コミット単位にソフトウェアコンポーネントのソースコードが含まれない場合（ドキュメント単体や設定変更等）、基本プレフィックスとして tools、 docs または chore を使用します。docs プレフィックスより他のプレフィックスを優先します。docs および chore プレフィックスを除いて、1つのコミットに複数のプレフィックスがある場合、コミットの分割を検討してください。

tools: scripts/ および tools 配下のファイル変更に適用します。
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-I-001(webui): ログインフォームのバリデーション実装 [Refs: SPEC-001]
複数 SPEC に影響する変更: SPEC-I-001(auth-service): 共通認証トークンの生成処理追加 [Refs: SPEC-001, SPEC-I-002]
課題・不具合修正: ISSUE-005(webui): セッションタイムアウト時の再描画バグを修正
ドキュメント更新: docs: コミットメッセージガイドラインを追加
環境整備・設定更新: chore: CI設定の更新
打ち消し (Revert): Revert "SPEC-I-001(webui): ログインフォームのバリデーション実装"
マージコミット (Merge): Merge branch 'feature/login' into main
破壊的変更 (Breaking Change): SPEC-I-001(auth-service): BREAKING CHANGE: 認証APIレスポンスの構造を変更

Keyboard shortcuts