Claude CodeでSpring Bootアプリを作る — REST API開発の実装フロー

Claude CodeでSpring Bootアプリを作るとは

Claude CodeでSpring Bootアプリを作るとは、Spring Initializrで生成した最小構成の雛形をClaude Codeのセッションに読み込ませ、REST APIのエンドポイント実装・ビルド実行・テスト追加を対話的に進める開発スタイルを指します。Spring Boot自体の雛形生成は公式のstart.spring.ioが担い、Claude Codeはその上のコード実装とビルドコマンドの実行を担当する、という役割分担になります。

この分担が重要な理由は、Spring Bootの雛形にはビルドツール・依存関係・パッケージ構成といった「型」があり、そこを自己流で崩さずに保つほうが後続の実装がスムーズになるからです。雛形は公式ツールに任せ、その内側のコード生成とビルド・実行の反復をClaude Codeに任せる形が、迷いなく進められます。Kotlinの別フレームワークでは、Ktorサーバーをtestで検証する手順も同じ型です。

前提条件を揃える

Spring Bootの開発にはJDK(Javaの開発キット)とIDE(統合開発環境)が必要です。公式のQuickstartガイドはBellSoft Liberica JDKのバージョン17または21を推奨し、IDEの選択肢としてIntelliJ IDEA、Spring Boot Extension Pack付きのVisual Studio Code、Spring Tools付きのEclipseを挙げています。

Claude Code側の前提は、ターミナルとClaude Codeのインストール、そしてClaude Pro・Max・Team・Enterpriseのいずれかのサブスクリプション、またはClaude Console(API)アカウントです。macOS・Linux・WSLでは次のコマンドでネイティブインストールできます。

curl -fsSL https://claude.ai/install.sh | bash

インストール後はclaude --versionでバージョン番号と(Claude Code)の表示を確認します。初回起動時はログインを求められ、Claudeサブスクリプションまたはコンソールアカウントのいずれかでブラウザ認証を完了します。

ステップ1: Spring Boot雛形の準備

雛形の生成はstart.spring.ioで行います。「web」の依存関係を検索して追加し、Generateボタンでzipをダウンロード、任意のフォルダに展開します。この操作で生成されるのが、Spring Bootをすぐに使える状態にした最小プロジェクトです。

展開したフォルダをIDEで開くと、src/main/java/com/example/demo配下にDemoApplication.javaが見つかります。ここまではSpring公式のQuickstartが案内する手順そのもので、Claude Codeはまだ登場しません。雛形が用意できたら、そのフォルダでClaude Codeを起動します。

cd /path/to/demo
claude

起動直後にプロジェクトの内容を尋ねると、Claude Codeは必要なファイルを自分で読みに行きます。手動でコンテキストを渡す必要はありません。

このプロジェクトの構成を教えて

ステップ2: CLAUDE.mdとエンドポイント実装

複数セッションにまたがってビルドコマンドやパッケージ構成を毎回説明し直すのは非効率です。プロジェクトルートにCLAUDE.mdを置いておくと、Claude Codeはこのファイルを自動的に読み込み、そこに書いた規約に従うようになります。ビルドコマンドが./gradlewか./mvnwか、パッケージのルートがどこかといった情報を書いておくと、セッションをまたいでも説明が要りません。

CLAUDE.mdを用意したら、エンドポイントの実装をプロンプトで指示します。Quarkusで同じ流れを組む場合は、Claude CodeでQuarkusアプリを開発するでdevモードとテストの分担を扱っています。

GETメソッドの/helloエンドポイントを追加して。nameというクエリパラメータを受け取り、
デフォルト値はWorldにして、"Hello {name}!"という文字列を返して

これに対応する実装は、DemoApplication.javaへの次のような追加になります。

package com.example.demo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
 
@SpringBootApplication
@RestController
public class DemoApplication {
    public static void main(String[] args) {
      SpringApplication.run(DemoApplication.class, args);
    }
    @GetMapping("/hello")
    public String hello(@RequestParam(value = "name", defaultValue = "World") String name) {
      return String.format("Hello %s!", name);
    }
}

@RestControllerがこのクラスをWeb経由で公開するエンドポイントとして扱うようSpringに伝え、@GetMapping("/hello")が/hello宛てのリクエストをhello()メソッドに割り当てます。@RequestParamはnameという値をリクエストから受け取り、無ければ既定値のWorldを使う指定です。Claude Codeがコードを提示した際は、差分を確認してから承認します。

ステップ3: 権限を設定してビルド・実行する

Manualモードでは、読み取り専用コマンドの一部を除いて、Bashコマンドの実行前に承認を求められます。./gradlew bootRunのような起動コマンドを毎回のセッションで承認し直すのは手間なので、リポジトリ単位で許可ルールを保存しておきます。

承認プロンプトで「Yes, and don't ask again」を選ぶと、そのルールはリポジトリのルートにある.claude/settings.local.jsonに永続保存され、以後のセッションやワークツリーでも有効になります。ルートへの保存はv2.1.211以降の挙動で、それより前は起動したディレクトリに保存されます。同じ内容を先に手動で書いておくことも可能です。

{
  "permissions": {
    "allow": [
      "Bash(./gradlew bootRun)",
      "Bash(./gradlew test)"
    ]
  }
}

ルールの幅は3通りに書き分けられます。どこまで許可するかはリポジトリの性格で決まります。

複合コマンドは分解して照合されます。./gradlew test && ./gradlew bootRunのように&&でつなぐと、各コマンドがそれぞれ許可ルールに一致しなければなりません。

許可ルールを設定したら、実際にビルドと起動を行います。macOS・Linuxでは./gradlew bootRun、Windowsでは.\gradlew.bat bootRunです。

./gradlew bootRun

Spring Bootの組み込みApache Tomcatサーバーがローカルのポート8080でリクエストを待ち受け始めます。ブラウザまたはcurlでhttp://localhost:8080/hello?name=Claudeにアクセスすると、Hello Claude!という応答が返ってきます。

bootRunはサーバーが動き続けるコマンドで、そのままではClaude Codeの次の操作が待たされます。公式ドキュメントでは、Bashコマンドをバックグラウンドへ移す方法が2つあります。

ステップ4: テストとリファクタ

エンドポイントが動いたら、次はテストの追加です。Claude Codeは自然言語の指示だけでテストコードの生成にも対応しています。

helloエンドポイントのユニットテストを書いて。nameを指定した場合と省略した場合の両方をカバーして

生成されたテストは./gradlew testで実行します。許可ルールにBash(./gradlew test)を含めておけば、この実行も承認なしで進みます。テストが通った後にロジックを変更したいときは、リファクタの指示も同じ流れで出せます。

hello()メソッドの引数チェックをBean Validationのアノテーションに置き換えて

Claude Codeは該当コードの位置を特定し、変更内容を提示してから適用します。テストが用意されていれば、変更後に自動でテストを再実行するよう指示することもできます。

この指示には、依存関係の落とし穴があります。Spring Bootのスターター一覧では、spring-boot-starter-webとspring-boot-starter-validationが別々のスターターとして並んでいます。Spring Initializrで「web」だけを選んだ雛形のbuild.gradleにはspring-boot-starter-webmvcが入り、バリデーションの注釈が使えるとは限りません。注釈を入れる前にspring-boot-starter-validationを追加するよう、指示へ書き添えます。

build.gradleにspring-boot-starter-validationを追加したうえで、
hello()のnameをBean Validationの注釈で検証して。変更後は./gradlew testを実行して

テストの種類も指示で選べます。公式のテストガイドによると、@WebMvcTestはSpring MVCの基盤だけを組み立て、走査するBeanを@Controllerなどに絞ります。アプリ全体を起動する@SpringBootTestより軽く、エンドポイントの入出力だけを確かめたいときに向きます。モックの置き方まで含めた選び方はJUnit 5とMockitoのテストの書き方にあります。JPAの遅延読み込みで例外が出たときの直し方はLazyInitializationExceptionの解説にあります。

開発フェーズ別のパーミッションモード使い分け

Claude Codeには複数のパーミッションモードがあり、開発フェーズに応じて切り替えると承認の手間と安全性のバランスが取れます。モードの切り替えはセッション中にShift+Tabで行えます。

v2.1.283以降は、ターミナルとVS Codeの対話型セッションが、プランを問わずAuto(分類器が操作を審査するモード)で始まります。それより前のバージョンでは、Auto開始はPro・Max・Teamプランだけでした。どのモードで始めても、Shift+Tabでいつでも切り替えられます。

v2.1.289のclaude --helpでは、--permission-modeの選択肢が次のように出ます。コマンドラインではdefaultでもmanualでも指定でき、helpにはmanualが出ます。

--permission-mode <mode>   Permission mode to use for the session
                           (choices: "acceptEdits", "auto",
                           "bypassPermissions", "manual",
                           "dontAsk", "plan")

表の最後の行にあるCI上での自動実行は、claude -pで対話なしのセッションを起動し、--permission-modeでモードを固定する形です。

claude -p --permission-mode acceptEdits "./gradlew testを実行して結果を要約して"

このコマンドは--print(-p)で応答を出力したら即終了する非対話モードに入り、acceptEditsモードでファイル編集やmkdir・cpのような基本的なファイル操作コマンドを自動承認します。ビルドやテストの実行コマンド自体は、許可ルールで別途カバーしておく必要があります。

許可する範囲を厳密に固定したいなら、公式ドキュメントのCI向けの例にならい、dontAskモードと--allowedToolsを組み合わせます。dontAskは、プロンプトが出るはずの操作をすべて自動で拒否し、事前に許可したツールだけを実行するモードです。

claude -p "./gradlew testを実行して結果を要約して" \
  --permission-mode dontAsk \
  --allowedTools "Bash(./gradlew test)" "Read"

許可リストに無いコマンドは承認待ちで止まらず、拒否されて終わります。

よくあるつまずき

gradlewの実行のたびに承認を求められる

許可ルールを設定する前は、./gradlew bootRunを実行するたびに承認プロンプトが出ます。ステップ3のpermissions.allow設定を.claude/settings.local.jsonに保存すれば、以降は同じコマンドで止まりません。v2.1.211以降は、ルールがリポジトリのルートに保存されるため、同じプロジェクトの別ワークツリーでも有効です。

ポート8080が使用中でbootRunが失敗する

Spring Bootの組み込みTomcatは既定でポート8080を使います。別のプロセスが同じポートを使っていると起動に失敗します。先に該当プロセスを終了するか、ポート番号を変更します。

ポートはserver.portプロパティで変更でき、application.propertiesへの記述のほか、環境変数のSERVER_PORTでも指定できます。GradleのbootRunには、コマンドラインから--argsで引数を渡せます。

./gradlew bootRun --args='--server.port=8081'

この形で起動すると、許可ルールがBash(./gradlew bootRun)の完全一致のままでは別のコマンドと見なされ、承認プロンプトが出ます。ポートを変えて起動する運用なら、Bash(./gradlew bootRun *)のように引数まで受ける幅で書きます。

CLAUDE.mdを置かないと毎回の説明がぶれる

CLAUDE.mdを用意していないプロジェクトでは、ビルドコマンドやパッケージ構成をセッションごとに説明し直すことになり、指示の粒度がぶれがちです。プロンプトやCLAUDE.mdの指示内容はClaude Codeが何を試みるかを左右しますが、実際に何が許可されるかは許可ルールやパーミッションモードが決めるという点も、設定時に区別しておくと迷いません。

まとめ

承認プロンプトに中断されない開発ループは、./gradlew系の許可ルールをtest *のように幅を決めて登録しておくことで作れます。雛形はstart.spring.ioが担い、Claude Codeには実装・ビルド・テストを任せる分担です。既存のSpring Boot 2アプリを3へ上げる作業はClaude CodeでSpring Boot 3へ移行するで扱っています。

Spring BootアプリをMCPサーバーとして公開したい場合は、Spring AIのBoot Starterを使う経路が近道になります。実装手順はJavaでMCPサーバーを書く手順とSpring AIとの関係にまとめています。実装したアプリをコンテナ化してKubernetesへ載せる判断軸はDocker/Podman/Kubernetes MCPの選び方、本番環境へのデプロイまで進めたい場合はHeroku MCPサーバーでClaude Codeからアプリをデプロイ・スケーリングするが参考になります。