GitHubCopilot AgentMode チュートリアル For Java Developer

記事の内容

GitHubCopilotのAgentModeを使って既存のアプリケーションに機能追加を実施してもらうまでの手順を書いた記事です。

• 何もセットアップしていない状態から実施できるように手順を書いています
• 初心者の方でも実施できるように詳細な手順を記載しています
• Java開発者の方向けにSpringBootのアプリケーションを題材にしています
• Agentにうまく働いてもらうために必要なポイントの初歩が掴めます（たぶん）

GitHubCopilotのAgentModeを初めて利用する際のチュートリアルにどうぞ。

事前に準備が必要なもの

• GitHubのアカウント
  有料のプランでは選択できるLLMが増えたり、無制限でAgentModeを利用できますが（2025年6月3日まで）、Freeプランでも十分試してみることができます。

GitHubCopilot AgentModeとは？

AgentModeについて理解するにはGitHubCopilotに追加された機能を順番にみていくのが良いと思います。
以下を参考に簡単にまとめてみました。

GitHubCopilotの基本機能

GitHubCopilotの基本機能はコードの補完機能です。
ユーザーがコードエディタに入力する際に動作し、次の入力内容を提案してくれます。

１年ほど前はCopilotの空気の読み具合に「え、こわ…」と思っていましたが、今や当たり前の機能になり、Copilotなしにはコーディングできない体になってしまいました。

Copilot Chat

GitHub Copilotと会話形式でやりとりをすることができる機能です。
会話形式でやりとりをすることで、既存のコードについて質問して処理の内容を説明してもらったり、自分が書いたコードに無駄な処理やバグがないかを探してもらったり、指定したコードに対する単体テストを作成してもらったり、といった補完機能だけではできなかった体験ができるようになりました。

Copilot Edits

Copilot Chatの会話型のフローに、複数のファイルにインラインで変更を加える機能を組み合わせたもの。
開発者は編集対象のファイルを指定して自然言語で変更をリクエストし、提案された変更を確認しながら適用、修正を繰り返すことができます。

Copilot AgentMode

GitHub Copilotにエージェント的なAIの力を追加するもの。
要求されたタスクだけでなく、必要なサブタスクを推測し、それらを全て完了するまで動作し続けることができる。
より自律的な支援が可能となり、自身のコードを反復してエラーを認識し、それを自動修正したり、ターミナルコマンドを提案・実行したり、ランタイムエラーを分析・自己修復したりすることができる。

これによって条件が整えば、要望レベルの自然言語の指示だけで機能追加や不具合修正が完了できるようになりました。

開発環境の準備

SpringBootの実行環境の準備

こちらの記事の java-homeの設定 までの内容を実施してください。
こちらの記事では java-homeの設定 の後に Spring Initializr で新しいプロジェクトを作成していますが、今回は後述する spring-petclinic というプロジェクトを利用します。
（そのため Spring Initializr はインストールしなくても進めることができます）

Gitのインストール

Gitのインストールがまだの場合はインストールしてください。

参考

アプリケーションの準備

題材

今回の記事では以下のリポジトリのアプリケーションを題材として、実際にCopilot AgentModeを使って機能追加を実施してみます。

DeepWiki¹のIndexも作られているので、必要があれば参照できます。

動作確認をしていたところ、環境によってはいくつか動作しない箇所があったため、Forkして修正したリポジトリを用意しました。
こちらを利用すればすぐに動かすことができると思います。

リポジトリのclone

作業ファイルを配置したいフォルダで以下のコマンドを実行します。

git clone https://github.com/gengen0719/spring-petclinic-fix-parameters.git

VSCodeの準備

プロジェクトの開き方

spring-petclinic-fix-parametersというフォルダができるのでVSCodeで開きます。
（VSCodeのメニューのFile -> Open Folder... でspring-pet-clinicのフォルダを選択します）

ビルドツールの選択

このプロジェクトはビルドツールとしてMavenとGradleのどちらでも利用できるような構成になっているため、プロジェクトを開くと右下に以下のようなポップアップが出てきます。

今回はGradleのExtensionをインストールしているのでGradleで動かしてください。自分で設定できる方はMavenを選択しても問題ありません。

その他の右下に出てくるポップアップの内容の説明

• DevContainerのレコメンデーション
  このプロジェクトはDevContainerで動かすためのファイルが含まれているため、DevContainerの利用のRecommendationが出てくる場合がありますが、今回は利用しないため無視してください。
  

• Null annotationの設定
  このプロジェクトにNull annotationが含まれているため提案されています。
  Javaでは、@Nullable や @NonNull などのアノテーションを使って「変数や戻り値が null を許容するか」を明示できます。
  このようなアノテーションがコード中に存在すると、VSCodeはnull安全性の解析を有効にすることを提案してきます。
  Enableを選択するとnull安全性の解析を行うようになり、Disableを選択すると解析を行いません。今回はどちらを選択しても問題ありません。
  

アプリケーションの起動

ここまでの設定によって、Gradleでbuildが実行され、アプリケーションを起動する準備が整っています。

PetClinicApplication.java を実行し、アプリケーションを起動します。

http://localhost:8080 にアクセスすると、petclinicの画面が開くと思います。

アプリケーションの動作確認

アプリケーションが起動したら、画面を動かしてどのような機能があるのかを確認してみてください。FIND OWNERSに多くの機能が集中しており、飼い主の名前による検索ができ、飼い主を選択するとペットの追加・編集、ペットごとの来院記録の追加ができます。さらに来院記録には来院した日付とメモを残すことができます。

GitHubCopilotの設定

VSCodeの右下にあるCopilotのアイコンをクリックして表示されるコンテキストメニューからSet up Copilotをクリックします。

Sign in　ボタンを押します。

ブラウザでGitHubのアカウントを選択します。

Authorize Visual-Studio-Codeをクリックします。

これでGitHubCopilotを利用する準備が整いました。

GitHubCopilot AgentModeを使って機能追加をする

VSCode上部のCopilotアイコンをクリックすると右側にCopilotとやりとりをするためのChatが表示されます。

Chat欄上部の三点リーダーのOpen Chat in Editorをクリックすると、EditorにChat欄を表示することもできます。

Chatの入力欄の下にあるAskのドロップダウンをクリックするとEditモードもしくはAgentモードに切り替えることができます。Agentモードに切り替えて指示をしてみましょう。

ここから先は選択するLLMのモデルやご機嫌によって結果が変わるため、全く同じ結果にはならないと思いますが、実際に動かしてみことでどんなことができるのかが掴めると思います。
発生するエラーも違う場合があると思いますが、エラーログを読ませればほぼ解消してくれるはずです。

ペットの来院記録に処方薬の項目を追加してください。
処方薬の項目には文字列を入力できるようにしてください。

エージェントにはこのように自然言語で、機能追加や不具合修正のような要望を指示することができます。
要望を実現するために、具体的にどのファイルをどうやって修正するのかはエージェントが考えます。情報が必要であればファイルやログを読み、その情報を使って判断します。

エージェントが利用するLLMはSpring Bootに関する一般的な知識を持っているため、モデル、コントローラー、テンプレートファイルの修正が必要であろうということを考え、ファイルの内容を確認して修正を行なってくれます。

修正したファイルは一覧を出してくれます。
またそれぞれのファイルの中身を見ると差分がわかるようになっています。

Visit.java にフィールドとgetter,setterを追加

ownerDetails.html に処方薬の表示を追加

createOrUpdateVisitForm.html に入力欄を追加

各ファイルはこのような形でうまく修正してくれているように見えます。
しかし起動後オーナーの画面に遷移しようとするとエラーが発生しました。

2025-05-09T01:41:20.965+09:00 ERROR 33047 --- [nio-8080-exec-3] o.h.engine.jdbc.spi.SqlExceptionHelper : 列 "V1_0.MEDICATION" が見つかりません

何をした時のエラーなのかと、その時に出たエラーログを貼り付けて修正を依頼します。

修正依頼の内容

エラーの原因分析と修正の実施
どうやらデータベースの修正ができていなかったようです。

このプロジェクトの特徴として複数のデータベースに対応している点がありますが、プロジェクト内のファイルを読んで他のデータベースに対する修正が必要なことも認識して実施してくれています。

動作確認をするためにアプリケーションを起動しようとすると、今度は起動時にエラーが発生しました。

org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'entityManagerFactory' defined in class path resource [org/springframework/boot/autoconfigure/orm/jpa/HibernateJpaConfiguration.class]: Failed to initialize dependency 'dataSourceScriptDatabaseInitializer' of LoadTimeWeaverAware bean 'entityManagerFactory': Error creating bean with name 'dataSourceScriptDatabaseInitializer' defined in 
class path resource [org/springframework/boot/autoconfigure/sql/init/DataSourceInitializationConfiguration.class]: Failed to execute SQL script statement #44 of file [C:\VSCodeWorkSpace\spring-petclinic-fix-parameters\bin\main\db\h2\data.sql]: INSERT INTO visits VALUES (default, 7, '2013-01-01', 'rabies shot')
以下省略

再び何をした時に出たエラーなのかを伝え、エラーログを貼り付けると、エラーの内容を確認し修正してくれます。

原因を特定して修正を実施してくれました。

data.sql の修正内容

修正後再起動すると、起動しました。
動作確認をしてみると、うまく動いているようでした。

Pets and Visitsの画面にMedicationが追加されています

Add Visitsの画面に入力欄が追加されています

入力した内容がPets and Visitsに表示されています

シンプルなプロジェクトに対する簡単な機能追加ではありますが、何度かやり取りをすると動作する状態まで進めてもらうことができました。
しかし実は少し問題も残っています。
このプロジェクトはもともと多言語対応していますが、機能追加した処方薬の部分では実装ができていません。
プロジェクト内には多言語対応のためのファイルがあるため気づいて実装してくれる場合もありますが、今回のように気づかず実装してくれない場合もあります。
またJUnitTestの修正も今回は実行してくれませんでした。

ポイント

一般的なフレームワークやコーディングの知識を持っている

例えば今回の「項目追加をして」という指示であれば、多くのLLMはSpring Bootに関する知識を持っているため、プロジェクト内のファイルを確認してSpring Bootを使ったプロジェクトであることを判断し、MVCの修正をするために修正が必要なファイルを割り出して修正する、というところまではスムーズに実行できます。

プロジェクト固有の知識は持っていない

例えば今回であれば

• アプリケーションの起動時に、データベースにデータを投入する
• 複数のデータベースに対応している
• 多言語対応している

といったプロジェクト固有の知識は知らないため、うまく修正できないことがありました。

ファイルを読んでうまくやってくれる場合もあるがご機嫌次第である

Agentはファイルを読み込んでその情報を元に判断してくれるので、うまくやってくれる場合もありますが、ご機嫌次第なところがあります。
今回のプロジェクトであれば複数のデータベースや多言語の修正もしてくれたものの、一部だけ対応が漏れているということもありました。

プロジェクト固有の知識をAgentにうまく伝える

copilot-instructions.mdを活用する

GitHub Copilotは .github/copilot-instructions.md に記載した内容を毎回のChat欄の入力と合わせて必ず読み込んでくれます。
そのためこのファイルにプロジェクト固有の知識を記載しておくと良いと思います。

また修正を実施してもらった後にAgent自身にこのファイルを作ってもらうことも有効です。

今回の修正の振り返りを行なって retrospective.mdを作成してください。
その中から次回の修正時にも知っておいた方が良いことを.github/copilot-instructions.mdにまとめてください。

「振り返り」という単語が含まれていると今回の修正内容に寄りすぎてしまうようなので、一旦振り返りをした後にインストラクションをまとめてもらう方がうまくいくようです。

以下のようにまとめてくれました

# Spring PetClinicアプリケーション修正のための重要ガイドライン

このドキュメントは、Spring PetClinicアプリケーションの修正・拡張時に知っておくべき重要な情報をまとめたものです。

## データベースとスキーマ管理

1. **複数のデータベースに対応**
   - このアプリケーションは複数のデータベース（H2, HSQLDB, MySQL, PostgreSQL）をサポートしています
   - スキーマの変更時は以下のファイルを全て更新する必要があります：
     - `/src/main/resources/db/h2/schema.sql`
     - `/src/main/resources/db/hsqldb/schema.sql`
     - `/src/main/resources/db/mysql/schema.sql`
     - `/src/main/resources/db/postgres/schema.sql`

2. **初期データの修正**
   - テーブル構造を変更した場合は、初期データファイルも更新する必要があります：
     - `/src/main/resources/db/h2/data.sql`
     - `/src/main/resources/db/hsqldb/data.sql`
     - `/src/main/resources/db/mysql/data.sql`
     - `/src/main/resources/db/postgres/data.sql`

3. **HIbernateの自動スキーマ生成は使用していない**
   - このアプリケーションは明示的なSQLスクリプトでスキーマを管理しています
   - `spring.jpa.hibernate.ddl-auto` は設定されておらず、Hibernateによる自動スキーマ更新は行われません

## 修正する際の重要な手順

1. **エンティティの変更**
   - エンティティクラスにフィールドを追加する場合は、対応するゲッター・セッターメソッドも追加
   - JPA/Hibernateアノテーションを適切に設定（@Column, @NotBlankなど）

2. **データベースの更新**
   - スキーマファイル（schema.sql）を全てのデータベース方言で更新
   - 初期データファイル（data.sql）も全てのデータベース方言で更新
   - PostgreSQLの場合はINSERT文の構文が他と異なるので注意（WHERE NOT EXISTS句を使用）

3. **ビュー（HTML）の変更**
   - Thymeleafテンプレートを更新
   - フォーム入力項目を追加する場合は、対応するモデル属性が正しく設定されていることを確認
   - 関連する全てのビューを更新（一覧画面、詳細画面、入力フォームなど）

4. **テストの更新**
   - モデルやコントローラーの変更に合わせてテストケースも更新

## エラー発生時の対処法

1. **テーブル構造の不一致エラー**
   - スキーマファイルの更新が正しく行われているか確認
   - データベースを完全に初期化するには `spring.sql.init.mode=always` を設定

2. **初期データエラー**
   - 初期データファイルとテーブル構造が一致しているか確認

3. **起動時データベースエラー**
   - Gradleの場合: `./gradlew clean bootRun` でクリーンビルド後に起動
   - Mavenの場合: `./mvnw clean spring-boot:run` でクリーンビルド後に起動

詳細な振り返りや実装手順については、`retrospective.md`を参照してください。

この中には最初からうまく修正してくれたものも含まれています。
しかしいろいろなファイルを読み込んで修正方法を探す際にはLLMとのやりとりが増え、トークンをたくさん消費することになりますし、毎回うまく修正方法が見つけられるとも限りません。
そのためプロジェクト固有の知識は明文化してまとめておく方が良いと思います。

修正を検証できるものを用意する

今回の手順の中ではアプリケーションを起動した際のエラーを伝えたり、画面を操作して発生したエラーを伝えたりして修正してもらいましたが、この作業をAgentに実施してもらえるようにすれば、より自立的に作業を行ってもらうことができます。
コマンドラインで実行した際の出力内容や返り値は読んでくれるのでコマンドでの実行手段をまとめておくと結構頑張ってくれます。

修正後アプリケーションを起動してエラーが出ないことを確認する

例えば copilot-instructions.md に以下のようなコマンドを書いておけば修正が終わった後に検証してくれるようになります。²
前述の起動時のエラーであればこれで検知して自分で修正してくれると思います。

## アプリケーション修正後の確認方法

1. **正しく起動することを確認**
   - Java 21を使用して起動: 
     ```
     JAVA_HOME=/opt/homebrew/Cellar/openjdk@21/21.0.7 ./gradlew bootRun --args='--spring.output.ansi.enabled=ALWAYS'
     ```
   - 起動ログでエラーがないことを確認
   - 起動完了後、以下のコマンドでHTTPレスポンスを確認:
     ```
     curl -I http://localhost:8080
     ```
   - `HTTP/1.1 200` レスポンスが返ってくることを確認

テストを実行する

2. **ユニットテストの実行**
   - Javaコードを修正した場合、テスティングペアのユニットテストを実行

というように書いておけば、修正したクラスのテスティングペアのJUnitTestを実行してくれます。

さらに応用するとテスト実行時のカバレッジを取って不足があればテストを追加してもらうこともできると思いますし、E2Eテストがコマンドで実行できるようになっていれば、それを実行してもらうこともできると思います。

このように修正の正しさを確認する方法を整備して使えるようにしてあげると、自主的に誤りを見つけてくれるので、修正の精度が上がっていきます。

インストラクションが整備された状態で機能追加をする

ここまでのインストラクションを用意した状態で似たような機能追加を依頼してみましょう。

ペットの来院記録に支払い金額の項目を追加してください。
支払い金額の項目には数値を入力できるようにしてください。
通貨の単位はドルとしてください。

先ほどよりも修正の精度が上がっていると思います。

他の機能追加依頼を試してみる

• 来院記録を削除する機能を追加してください
• 日本語表示に対応してください
• 来院記録に担当医を入力できるようにしてください、担当医はマスタから選択できるようにしてください

などいろいろ試してみてください。

おわり。

1. GitHubの公開リポジトリのソースコードを解析し、その詳細な解説をWiki形式で表示してくれるサービスです。リポジトリの内容を理解するのに必要な情報をまとめてくれて、さらに質問をすると答えてくれる機能もあります。 ↩

2. JAVA_HOMEなどは環境に合わせて修正する必要があります。 ↩