dr-jskill

Julien Dubois のベストプラクティスに従う Spring Boot スキル

概要

このエージェントスキルを使うと、Julien Dubois のベストプラクティスに従って Spring Boot プロジェクトを作成できます。https://start.spring.io を使用して Spring Boot アプリケーションをすばやく初期化するためのツールとスクリプトを提供します。

推奨モデル： Dr JSkill は GPT-5.5 で最適に動作します。

バージョン管理

バージョンは versions.json で一元管理します。すべてのスクリプトは、JavaScript の scripts/lib/versions.mjs を介してこのファイルを読み込みます。Java、Spring Boot のフォールバックバージョン、Postgres、Node/npm、Testcontainers などのバージョンを更新するには、このファイルを編集してください。

前提条件

1. Java 25 がインストールされていること
2. Node.js 24.x と NPM 11.x がインストールされていること（フロントエンド開発用）
3. Docker がインストールされ、起動していること

機能

• 事前定義された設定で Spring Boot プロジェクトを生成
• さまざまな Spring Boot のバージョンと依存関係をサポート
• プロジェクト構成と設定に関するベストプラクティスに準拠
• 一般的なユースケース向けのクイックセットアップスクリプト
• コンテナ化されたデプロイ向けの Docker サポート
• 複数のフレームワークから選べるフロントエンド開発：
  • Vue.js 3（デフォルト） - Composition API を備えたプログレッシブフレームワーク
  • React 19 - ユーザーインターフェース構築で広く使われているライブラリ
  • Angular 22 - TypeScript を採用した多機能フレームワーク
  • Vanilla JavaScript - フレームワークを使わず、Vite で動作する純粋な ES6+

使い方

スクリプトを使う

このスキルには、scripts/ ディレクトリにクロスプラットフォーム対応の JavaScript（Node.js）スクリプトが含まれています。これらのスクリプトを使って、事前設定済みの Spring Boot プロジェクトを start.spring.io からダウンロードできます。Linux、macOS、Windows で動作します。

統合ランチャー（クロスプラットフォーム対応）：

node scripts/create-project my-app com.myco my-app com.myco.myapp 25 fullstack --output-dir /absolute/path/to/user/workspace

直接実行：

node scripts/create-project-latest.mjs my-app com.myco my-app com.myco.myapp 25 fullstack --output-dir /absolute/path/to/user/workspace

対応フラグ：

• --boot-version <x.y.z> / -BootVersion：Spring Boot のバージョンを上書きします
• --project-type basic|web|fullstack / -ProjectType
• --output-dir <absolute-path>：生成したプロジェクトのフォルダーを、このディレクトリの下に作成します

出力ディレクトリのルール（Agent Skills では重要）： 同梱のスクリプトはスキルのルートディレクトリから実行されます。ユーザーからアプリの作成を依頼された場合は、エージェントセッションでユーザーが現在作業しているディレクトリを --output-dir に指定してください。生成したプロジェクトのフォルダーが dr-jskill スキルフォルダー内ではなく、ユーザーのワークスペースに作成されます。Dr JSkill 自体のテストを実行する場合のみ、--output-dir を省略してください。この場合は、スキルのチェックアウト先に生成するのが意図した動作です。

ヒント：create-project-latest スクリプトは、最新の Boot 4.x を自動的に確認し、まだ利用できない場合は設定済みの springBootFallback にフォールバックします。必要に応じて --boot-version で上書きしてください。

最新バージョンのプロジェクト ⭐

create-project-latest.mjs スクリプトを使って、最新バージョンの Spring Boot を使うプロジェクトを作成します（バージョンを自動取得します）：

node scripts/create-project-latest.mjs my-app com.mycompany my-app com.mycompany.myapp 25 web

利用可能なプロジェクトタイプ：

• basic - 最小構成の Spring Boot プロジェクト
• web - REST API 機能を備えた Web アプリケーション
• fullstack - データベースとセキュリティを備えた完全なアプリケーション

基本的な Spring Boot プロジェクト

create-basic-project.mjs スクリプトを使って、必須の依存関係を含む基本的な Spring Boot プロジェクトを作成します：

node scripts/create-basic-project.mjs

Web アプリケーション

create-web-project.mjs スクリプトを使って、Web 関連の依存関係を含む Spring Boot Web アプリケーションを作成します：

node scripts/create-web-project.mjs

フルスタックアプリケーション

create-fullstack-project.mjs スクリプトを使って、データベース、セキュリティ、Web 関連の依存関係を含む包括的な Spring Boot アプリケーションを作成します：

node scripts/create-fullstack-project.mjs

ベストプラクティス

Spring Boot プロジェクトを作成する際は、次の点に従ってください。

1. 最新の Spring Boot バージョン（現在は 4.x）を使用します。create-project-latest.mjs スクリプトが自動的に取得します
2. Spring Boot 4 の重要な考慮事項を確認します。Jackson 3 のアノテーションと TestContainers の設定については、Spring Boot 4 移行ガイドを参照してください
3. 本番環境向けの機能を利用するため、Spring Boot Actuator を含めます
4. データベースアクセスには Spring Data JPA を使用します
5. データベースには PostgreSQL を使用します。最適化については、データベースのベストプラクティスを参照してください
6. 設定にはプロパティファイルを使用します。設定のベストプラクティスを参照してください
7. 基本となるドットファイルを用意します。.gitignore、.env.sample、.editorconfig、.gitattributes、.dockerignore、必要に応じて .vscode/、.devcontainer/ を用意してください。プロジェクトのセットアップとドットファイルを参照してください
   • .env ファイルは、ローカルのシークレットを保存する正式な場所です。ユーザーに .env.sample を .env にコピーして、実際の値を入力するよう案内してください
   • .env の読み取りや公開は絶対にしないでください。実際のシークレットが含まれています。内容を cat、表示、出力してはいけません。読み取ったり表示したりできるのは、プレースホルダー値を含む .env.sample のみです
8. 小規模なブランチ、レビュー済みの差分、安全なコミット、プルリクエスト、ワークツリーに関する日々の Git のベストプラクティスに従います。Git のベストプラクティスを参照してください
9. 開発中のデータベースの自動起動には spring-boot-docker-compose を使用します。Docker ガイドを参照してください
10. RESTful API の設計原則に従います
11. Logback を使用して適切なロギングを設定します。ロギングのベストプラクティスを参照してください
12. 依存関係の管理には Maven を使用します
13. 開発の生産性を高めるため、Spring Boot DevTools を含めます
14. 必要な場合にのみ Spring Security を追加します。ベストプラクティスについては、セキュリティガイドを参照してください
15. コンテナ化されたデプロイメントに向けて Docker を設定します。Docker ガイドを参照してください
16. 起動を高速化するため、GraalVM のネイティブイメージ対応を有効にします。GraalVM ガイドを参照してください
17. 起動バナーを必ず用意し、アプリの準備が整ったときにアクセス URL を表示します。起動バナーを参照してください
18. Git に変更をコミットする前に、ユーザーが変更を確認する必要があります。Git リポジトリを初期化する場合、または Git コマンドを実行する場合は、事前にユーザーに確認してください

Java コードインテリジェンス（JDTLS） ⭐

生成されるプロジェクトは Eclipse JDT Language Server（JDTLS） と連携するため、AI エージェントはテキスト検索ではなく、意味に基づいて Java コードをナビゲート、リファクタリング、診断できます。スクリプトには、JDTLS を GitHub Copilot CLI に自動的に接続する .github/lsp.json が含まれています。

AI エージェント向け：Java ファイルを扱うときは、grep／view／sed よりも lsp ツールを優先してください。インポート、ジェネリクス、継承、Javadoc を理解します。

タスク	使用するもの
クラス／メソッドの定義箇所を検索する	lsp goToDefinition
シグネチャを変更する前に呼び出し元を検索する	lsp findReferences または incomingCalls
型、パラメーター、Javadoc を調べる	lsp hover
ファイル内のシンボルを一覧表示する	lsp documentSymbol
プロジェクト全体からクラス／メソッドを検索する	lsp workspaceSymbol
ファイル間で安全に名前を変更する	lsp rename（sed は使用しないでください）
./mvnw verify の前にコンパイルエラーを確認する	ide-get_diagnostics

Java 作業での優先順位：lsp → .java glob を指定した grep → view。

JDTLS を一度インストールします：brew install jdtls（その他のプラットフォームについてはJDTLS ガイドを参照してください）。完全なセットアップ手順、注意事項、エディター連携については、references/JDTLS.mdを参照してください。

プロジェクト構成

サービス層は、価値がある場合（複雑なビジネスロジックなど）にのみ含めます。シンプルな CRUD アプリケーションでは、コントローラーからリポジトリを直接呼び出せます。

生成されるプロジェクトは、次の推奨構成に従います。

my-spring-boot-app/
├── .gitignore                 # Java + front-end + secrets (see references/PROJECT-SETUP.md)
├── .env.sample                # Template for local env vars; .env is gitignored
├── .editorconfig              # Consistent formatting across IDEs
├── .gitattributes             # Normalize line endings, better diffs
├── .dockerignore              # Slim Docker build contexts
├── .vscode/                   # Optional editor recommendations
│   ├── extensions.json
│   └── settings.json
├── .devcontainer/             # Optional Dev Container (Java 25 + Node 24 + PostgreSQL)
│   ├── devcontainer.json
│   └── docker-compose.yml
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/example/app/
│   │   │       ├── Application.java
│   │   │       ├── config/
│   │   │       ├── controller/
│   │   │       ├── service/         # Only included if needed
│   │   │       ├── repository/
│   │   │       └── domain/
│   │   └── resources/
│   │       ├── static/              # Front-end web assets (HTML, CSS, JS)
│   │       │   ├── index.html
│   │       │   ├── css/
│   │       │   │   └── styles.css
│   │       │   ├── js/
│   │       │   │   └── app.js
│   │       │   └── images/
│   │       └── application.properties
│   └── test/
│       └── java/
│           └── com/example/app/
│               ├── config/
│               ├── controller/
│               ├── service/         # Only included if needed
│               ├── repository/
│               └── domain/
├── Dockerfile                   # JVM image (jlink runtime + distroless)
├── Dockerfile-aot               # JVM + Spring AOT image
├── Dockerfile-native            # GraalVM native image
├── Dockerfile-crac              # CRaC (fast-restore) image
├── checkpoint-and-run.sh        # CRaC entrypoint helper
├── compose.yaml                 # Dev database (spring-boot-docker-compose)
├── docker-compose.yml           # Full stack with PostgreSQL (JVM)
├── docker-compose-aot.yml       # Full stack with PostgreSQL (AOT)
├── docker-compose-native.yml    # Full stack with PostgreSQL (native)
├── docker-compose-crac.yml      # CRaC app (database-free)
├── pom.xml
└── README.md

依存関係

生成されるプロジェクトには、Spring Web、Spring Data JPA、Spring Boot Actuator、DevTools、PostgreSQL、Validation、Docker Compose サポート、JUnit 5 を使用する Test Starter、TestContainers が含まれます。

設定

YAML ではなく .properties ファイルを使用し、環境変数を使ってシークレットを外部化し、型安全性を確保するために @ConfigurationProperties を活用してください。プロファイル、シークレット管理、一般的なパターンについては、設定ガイドを参照してください。

.env ファイルはローカルのシークレットを保管する唯一の場所です。決して読み取ったり、出力したりしないでください。表示できるのはプレースホルダー値を記載した .env.sample のみです。

データベースの最適化については、データベースのベストプラクティスガイドを参照してください。

セキュリティ（任意）

Spring Security は任意です。認証または認可が必要な場合にのみ追加してください。JWT、OAuth2、ロールベースのアクセス制御、CORS の設定については、セキュリティガイドを参照してください。

テスト

単体テスト（Mockito、@WebMvcTest）、統合テスト（TestContainers + @ServiceConnection）、AssertJ を使った Given-When-Then パターンについては、テストガイドを参照してください。

フロントエンド開発

フロントエンドフレームワークを選択してください。

• Vue.js 3（デフォルト）⭐ → Vue.js ガイド
• React 19 → React ガイド
• Angular 22 → Angular ガイド
• Vanilla JavaScript（フレームワークなし）→ Vanilla JS ガイド

すべての選択肢に、ホットリロード対応の Vite／CLI 開発サーバー、Bootstrap 5.3 以降、SPA ルーティング、Spring Boot JAR への自動ビルドが含まれます。

frontend-maven-plugin を設定する際は、Node のインストール、npm install、npm run build の実行を generate-resources フェーズにバインドしてください。これにより、明示的にパッケージ関連のコマンドを実行したときだけでなく、./mvnw spring-boot:run でも、Spring Boot の起動前にフロントエンドがビルドされます。

非対話型のスキャフォールディング（CI と AI エージェントでは重要です）。 個別のプロンプトを 2 つとも抑止する必要があります。

1. npm 自体の「Ok to proceed?」インストールプロンプト — パッケージ名の前に -y を指定して抑止します（-- の後ろにあるフラグは npm ではなくスキャフォルダーに渡されます）。npm create -y vite@latest … または npx --yes create-vite@latest … を使用してください。
2. スキャフォルダー自体のプロンプト — create-vite 9.x と Angular CLI 22 は、-y／--yes では抑止されない対話型の質問（「Use rolldown-vite?」やアナリティクスへのオプトインなど）を引き続き表示します。確実に対処するには、標準入力を閉じます。コマンドに echo | をパイプでつなぎ、スキャフォルダーがすぐに EOF を受け取り、デフォルト値を受け入れるようにしてください。

基本のレシピ：

• React／Vanilla：echo | npx --yes create-vite@latest frontend --template react（または --template vanilla）
• Vue：npm create -y vue@latest frontend -- --router --pinia --vitest --eslint --prettier（create-vue は追加のプロンプトを表示しません）
• Angular：echo | npx --yes @angular/cli@22 new frontend --style=css --ssr=false --skip-git --defaults --skip-install の後に npm install

Vue：最初の npm install の前に正規化してください（必須）。 create-vue は oxlint と eslint-plugin-oxlint のマイナーバージョンが一致しないものを固定して生成するため、npm install は ERESOLVE のピア依存関係の競合で失敗します。その結果、frontend-maven-plugin のステップが失敗し、Maven ビルド全体が失敗します。スキャフォールディングの直後に、次を実行してください。

# Dr JSkill スキルディレクトリから実行してください（`scripts/` がある場所です）。
# 生成されたプロジェクトの frontend/ ディレクトリへのパスを渡します。
node scripts/normalize-vue-frontend.mjs /absolute/path/to/my-app/frontend

これにより oxlint による二重のリンターが削除され、ESLint のみのパイプラインが残ります。また、create-vue が生成しないものの Maven の frontend-maven-plugin ビルドで実行される lint:check スクリプトが追加されます。何度実行しても結果は変わらず、--check を指定すると変更を加えずに報告します。Vue.js ガイドを参照してください。

Vitest とコールバック形式の Vite 設定。 vite.config.js が defineConfig(({ mode }) => ...) をエクスポートする場合、生成された vitest.config.js から mergeConfig(viteConfig, ...) を呼び出さないでください。先に viteConfig({ mode: 'test', command: 'serve' }) でコールバックを解決してください。そうしないと、Vitest は Cannot merge config in form of callback で失敗します。Vue.js ガイドを参照してください。

Docker デプロイ

Spring Boot は、開発中に spring-boot-docker-compose を通じて Docker コンテナを自動的に管理します。本番環境では、用意されている 4 種類のイメージから 1 つを選択してください。Dockerfile（JVM、jlink + distroless）、Dockerfile-aot（JVM + Spring AOT）、Dockerfile-native（GraalVM ネイティブ）、または Dockerfile-crac（CRaC 高速復元）です。詳しいセットアップ、対応する Maven プロファイル、デプロイパターンについては、Docker ガイドを参照してください。

GraalVM ネイティブイメージ

Docker 経由で（ローカルに GraalVM を用意せずに）ネイティブイメージをビルドするか、ローカルで ./mvnw -Pnative -DskipTests package native:compile を実行してビルドできます。設定、ランタイムヒント、テスト、CI/CD との統合については、GraalVM ガイドを参照してください。

Azure へのデプロイ

オプションで VNET に注入された Azure Database for PostgreSQL Flexible Server を使用し、Azure Container Apps にデプロイします。イメージの保存には GitHub Container Registry（GHCR）を使用します（CI では GITHUB_TOKEN を使ってプッシュし、Container Apps は保存済みの PAT を使ってプルします）。DB パスワードには Container Apps のシークレットを使用するため、ソース、環境変数のダンプ、シェル履歴にシークレットが残りません。GitHub Actions OIDC ワークフローを含み、JVM と GraalVM ネイティブイメージの両方に対応しています。Azure Deployment Guide を参照してください。

検証

#	内容	コマンド
1	バックエンドのビルド	./mvnw clean install
2	単体テスト	./mvnw test
3	統合テスト	./mvnw verify（Testcontainers 2 と @ServiceConnection を使用）
4	フロントエンドの開発サーバー	cd frontend && npm run dev

まず検証手順を実行してください。失敗した場合は、次に進む前に修正してください。

プロジェクトの生成後、上記の手順に沿って、生成されたプロジェクトが完全に機能し、ベストプラクティスに従っていることを確認してください。検証手順が失敗した場合は、原因を特定して、次に進む前に修正してください。これにより、生成されたプロジェクトの品質が高く、開発を始められる状態であることを確認できます。

追加リソース

付属のリファレンスガイド

Spring Boot の基本：

• Spring Boot 4 移行ガイド - Spring Boot 3 からの主な変更点、Jackson 3 のアノテーション
• 設定のベストプラクティス - プロパティファイル、プロファイル、シークレット管理
• ロギングのベストプラクティス - Logback の設定とパターン
• Java コードインテリジェンス（JDTLS） - LSP ベースのナビゲーション、リファクタリング、診断

データと永続化：

• データベースのベストプラクティス - PostgreSQL と Hibernate の最適化

セキュリティ（任意）：

• セキュリティガイド - Spring Security、JWT、OAuth2、認証パターン

テスト：

• テストガイド - TestContainers を使用した単体テストと統合テスト

フロントエンド開発：

• Vue.js 開発ガイド - Vite を使った Vue.js 3（デフォルト）
• React 開発ガイド - Vite を使った React 19
• Angular 開発ガイド - Angular CLI を使った Angular 22
• Vanilla JS 開発ガイド - Vite を使った純粋な ES6+

プロジェクトのセットアップ：

• プロジェクトのセットアップと Dotfiles - .gitignore、.env.sample、.editorconfig、.gitattributes、.dockerignore、.devcontainer/
• Git のベストプラクティス - 日々の Git ワークフロー、ブランチ、コミット、プルリクエスト、安全な取り消し、スタッシュ、ワークツリー

デプロイ：

• Docker デプロイガイド - Docker、Docker Compose、開発の自動化
• GraalVM ネイティブイメージガイド - Docker ベースのネイティブビルド、最適化
• Azure デプロイガイド - Azure Container Apps、PostgreSQL Flexible Server、GitHub Container Registry（GHCR）へのイメージのプッシュ／プル、DB パスワード用の Container Apps シークレット、GitHub Actions OIDC