AIエージェント×Markdown指示でGitコミットメッセージ自動生成を試してみた

はじめに

この記事は、AIエージェントとMarkdownのカスタム指示ファイルを組み合わせ、gitのコミットメッセージを自動生成する手法を提案します。
なお、私はGitHub Proに加入しており、その利用枠を使い倒したいというのが本手法を検討した動機の一つです。

目的

VSCodeの場合、コミットメッセージを自動生成する機能は既に利用可能です。「ソース管理」タブを開いて「コミットメッセージの生成」ボタンをクリックするだけです。

テキストボックス右の◇♢アイコン

しかし、Jupyter Notebook (.ipynb) ファイルを編集してコミットしようとすると、ファイルの変更点を正常に読み込めない問題を何度か経験しました。
また、何をどう比べてコミット文を生成したのかを質問できないですし、より賢いLLMを使ったほうが高品質な説明を生成できると思いました。
そこで、Markdownのカスタム指示ファイルにコミットメッセージ生成の手順を記載し、毎度これを参照して一定品質のコミットメッセージを生成できるようにすることを目論みました。

なぜカスタム指示ファイルか

カスタム指示ファイルを使って作業を自動化するという考え方を、こちらの記事で知りました。(源流がどなたかは知りませんが、少なくとも私はこの方の記事で知りました)この記事の内容は次のようなものでした。

• Zettelkastenと呼ばれるメモ術を応用し、「思い付きや情報の収集」から「知識や情報の整理」、「本質情報の抽出」までのワークフローをObsidian×Cursorで効率化する。

この記事の「ワークフローについて」セクションで、「md形式でワークフローを定義し、AIエージェントにタスクを遂行してもらう」という手法が紹介されています。
私は、これを読んで「これはもはや自然言語プログラミングと呼ぶべき革新的なものだ」と衝撃を受けました。

この「ワークフロー定義」の手法は、上記記事のような知的生産だけでなく、コンピュータ操作全般に応用できると思いました。そこで今回、gitのコミットメッセージ生成自動化に活用しました。

カスタム指示ファイルの内容と使い方

カスタム指示ファイル

下記プロンプトをMarkdownファイルとして作っておくことで、再利用可能なワークフロー指示書となります。
なお、このプロンプトはprogramsフォルダがGitリポジトリであること前提なので、必要に応じて編集して使ってください。

commit_message_manual.md

# AIエージェント向けコミットメッセージ提案 指示書

## 目的
リポジトリ内の変更点を分析し、開発者にとって分かりやすく、プロジェクトの慣習に沿ったコミットメッセージを複数提案すること。

## 手順

> [!IMPORTANT]
> 下記ステップとその具体的手順を遵守すること。順番通りに、指示内容以外のことをせず、忠実にタスクを実行してください。

このプロジェクトでは `programs` フォルダがGitリポジトリのルートとして扱われます。以降の `git` コマンドはすべて `programs` ディレクトリ内で実行してください。

### ステップ1: 変更内容の把握
1.  **作業ディレクトリの確認**: `pwd` を実行し、カレントディレクトリが `programs` であることを確認します。異なる場合は `cd programs` で移動してください。
2.  **変更ファイルのリストアップ**: `git status` を実行し、変更されたファイル（`modified`, `new file`, `deleted`など）を特定します。
3.  **差分の詳細確認**: 変更された各ファイルに対して `git diff` を実行し、具体的な変更内容（コードの追加、修正、削除）を正確に把握します。
    -   特に、関数やクラスの定義、ロジックの変更、UIの変更点などに注目します。

### ステップ2: 変更の意図と種類の分析
1.  **変更の分類**: 把握した差分から、変更の主な目的を以下のプレフィックスに分類する。
    -   `feat`: 新機能の追加
    -   `fix`: バグ修正
    -   `refactor`: パフォーマンス改善や可読性向上など、機能的変更を伴わないコードの改善
    -   `docs`: READMEやコメントなどのドキュメント修正
    -   `style`: コードフォーマットの修正（インデント、空白など）
    -   `test`: テストコードの追加・修正
    -   `chore`: ビルドツールやライブラリ管理など、雑多なタスク
2.  **変更内容の要約**: 変更の「なぜ（Why）」と「何を（What）」を簡潔にまとめる。
    -   例：「ユーザーが設定を変更できないバグを修正するため、設定保存時のバリデーションロジックを修正した」

### ステップ3: コミットメッセージの生成と提案
1.  **フォーマットの遵守**: 以下の形式で日本語のメッセージを生成する。
    ```
    <プレフィックス>: <件名>

    <本文（必要に応じて）>
    ```
2.  **件名の作成**:
    -   変更の核心を50文字以内で簡潔に表現する。
    -   動詞の原形（命令形）で記述する。（例: 「追加」→ `Add`、「修正」→ `Fix`）
3.  **本文の作成（必要な場合）**:
    -   変更が複雑な場合や、背景説明が必要な場合に記述する。
    -   「なぜこの変更が必要だったのか」という背景や課題を説明する。
    -   「どのように解決したのか」という実装の詳細を記述する。
4.  **複数パターンの提案**:
    -   異なる視点や粒度で、3〜5個程度のメッセージ案を提示する。
    -   シンプルな件名のみのパターンと、詳細な本文付きのパターンを両方含める。

## 提案の出力形式

-   **パターン1（シンプル）:**
    `feat: ユーザープロフィールページを追加`
-   **パターン2（詳細）:**
    `feat: ユーザープロフィール機能の実装
    
    ユーザーが自身のプロフィール情報（ユーザー名、メールアドレス、アイコン）を
    閲覧・編集できるページを追加する。`
-   **パターン3（背景重視）:**
    `feat: ユーザー情報管理のためプロフィールページを導入
    
    これまで管理画面でしか確認できなかったユーザー情報を、
    ユーザー自身が確認・編集できるようにするため、
    新たにプロフィールページを設ける。`

(2025年8月1日 追記) VSCodeの機能のみを使って変更点を検出するプロンプト

commit_message_manual_ver2.md (ステップ1のみ抜粋)

### ステップ1: 変更内容の把握
1.  **VS Code機能を使った変更検出**: `get_changed_files`ツールを使用し、リポジトリパスを指定してgitリポジトリの変更点を検出します。
    -   リポジトリパスは `./programs` を指定してください。
2.  **変更ファイルの自動取得**: ツールの実行により、変更されたファイルのリスト（`modified`, `new file`, `deleted`など）と具体的な差分情報が自動的に取得されます。
3.  **差分内容の詳細分析**: 取得された差分情報から、具体的な変更内容（コードの追加、修正、削除）を正確に把握します。
    -   関数やクラスの定義、ロジックの変更、設定ファイルの変更点などに注目します。
    -   各ファイルの変更箇所を行単位で確認し、変更の性質を理解します。

使い方

Github CopilotやCursorなどで「エージェントモード」に切り替え、下記のように打ち込みます。GitHub Copilot、Gemini 2.5 Proを使いました。

最初にpwdを使うように指示しているのを無視していたり、新規ファイルの内容を読み込むためにgit diffを使うのではなくCopilotの機能を使っていたりと、微妙に指示を聞いてくれないところがあります。
まあこれは仕方ないような気もするので、今回のカスタム指示ファイルをたたき台として今後も改良していければ良いかなと思います。

考察: 本手法の呼称

「自然言語プログラミング」という言葉は現在、「自然言語をソースコードとして解釈、コンパイル、実行するプログラミング体系」を指すようです (Wikipedia)。しかし本記事の手法も、自然言語に基づき作業を実行するという点で本質的に同じであるように感じられます。そのため、「自然言語プログラミング」の意味を本手法を含めて再定義するか、あるいは本手法を新しい概念として命名してもいいのではないかと思いました。

最後に

本記事はこれで以上です。最後までお読みいただきありがとうございます！