Jakarta EE API サービス開発 Agent Skill

使い方（6段階プロセス）

ステップ1: 基本設計（SPEC作成）

code

@agent_skills/jakarta-ee-api-base/instructions/basic_design.md

SPECを作成してください

パラメータ
* project_root: <プロジェクトルートパス>
* spec_directory: <SPECディレクトリパス>

AIと対話しながら以下を実施（対話的プロセス）

•
テンプレートを basic_design/common/ フォルダに展開
- •@agent_skills/jakarta-ee-api-base/templates/basic_design/ から5ファイルをコピー
•requirements.mdを読み込み、理解内容を説明
•ユーザーと対話しながら各SPECの中身を埋める
•ドメインフォルダを作成（common/ + 各ドメイン）
•各ドメインのSPEC（functional_design.md、behaviors.md等）を作成

テンプレート:

•architecture_design.md - アーキテクチャ設計書
•data_model.md - データモデル仕様書
•external_interface.md - 外部インターフェース仕様書
•functional_design.md - 機能設計書
•behaviors.md - 振る舞い仕様書（結合テスト用）

注意:

•requirements.md（要件定義書）は所与とする（既に存在している前提）
•基本設計はドメイン単位で分割する（common/ + 各ドメイン）
•フォルダ構成＝実装順序（common/ → 各ドメイン）
•既存SPECファイルがある場合は、削除せずに差分のみを反映する

ステップ2: 詳細設計

code

@agent_skills/jakarta-ee-api-base/instructions/detailed_design.md

詳細設計書を作成してください

パラメータ
* project_root: <プロジェクトルートパス>
* spec_directory: <SPECディレクトリパス>
* target_domain: <ドメイン名>

AIと対話しながら以下を実施（対話的プロセス）

•basic_design/{target_domain}/ の内容に基づいて detailed_design/{target_domain}/ フォルダを作成
•
テンプレートを参照して詳細設計を生成
- •@agent_skills/jakarta-ee-api-base/templates/detailed_design/ から2ファイルをコピー
•
basic_design/{target_domain}/functional_design.md を参照して実装レベルの detailed_design.md を生成
- •基本設計とコードの「橋渡し」となる設計判断のみを簡潔に記載
- •クラス名と責務、主要メソッドのシグネチャ、設計判断を示すアノテーション等
- •実装詳細（処理ステップ等）は記載しない（後から人が修正する可能性を考慮）
•単体テスト用の behaviors.md を新規作成（メソッドレベルのテストシナリオ）

テンプレート:

•detailed_design.md - 詳細設計書
•behaviors.md - 振る舞い仕様書（単体テスト用）

重要:

•commonを最優先で詳細設計する（他のドメインはcommonに依存）
•既存ファイルがある場合は、削除せずに差分のみを反映する
•functional_design.md は basic_design/{target_domain}/ に存在（ドメインごとの真実の情報源）
•behaviors.md はE2Eテスト用（requirements/）、結合テスト用（basic_design/{domain}/）、単体テスト用（detailed_design/{domain}/）の3種類

ステップ3: コード生成（詳細設計→実装→単体テスト）

code

@agent_skills/jakarta-ee-api-base/instructions/code_generation.md

ドメインを実装してください

パラメータ
* project_root: <プロジェクトルートパス>
* spec_directory: <SPECディレクトリパス>
* target_domain: <ドメイン名>

AIが自動で以下を実行

•詳細設計（detailed_design/{target_domain}/）を読み込み
•
実装コードを生成（Resource、Service、Dao、Entity、DTO等）
- •既存コードがある場合は、削除せずに差分のみを反映する
•
ドメイン粒度内の単体テストを作成
- •ドメイン内のコンポーネント間は実際の連携をテスト
- •ドメイン外の依存関係のみモック化
- •既存テストがある場合は、削除せずに差分のみを反映する
•commonを最優先で実装（他のドメインはcommonに依存）

ステップ4: 単体テスト実行評価

code

@agent_skills/jakarta-ee-api-base/instructions/unit_test_execution.md

単体テストを実行してください

パラメータ
* project_root: <プロジェクトルートパス>
* target_domain: <ドメイン名>

AIが自動で以下を実行

•テスト実行（gradle test jacocoTestReport）
•テスト結果とカバレッジ分析
•問題の分類（テスト失敗、必要な振る舞い、デッドコード、設計の誤り）
•フィードバックレポート生成
•ユーザーに推奨アクションを提示

重要:

•問題を発見してもユーザー確認なしに修正しない
•カバレッジ不足やデッドコードを具体的に提案
•必要に応じてステップ2（詳細設計）に戻ってループ

フィードバックループ:

code

詳細設計 → コード生成 → テスト実行評価
    ↑                         ↓
    └──── フィードバック ←────┘

ステップ5: 結合テスト生成

code

@agent_skills/jakarta-ee-api-base/instructions/it_generation.md

結合テストを生成してください

パラメータ
* project_root: <プロジェクトルートパス>
* spec_directory: <SPECディレクトリパス>
* target_domains: all

AIが自動で以下を実行

•basic_design/{domain}/behaviors.md（結合テストシナリオ）を各ドメインから読み込み
•
JUnit 5 + Cucumber + Weld SE を使用した結合テストを生成
- •Service層以下（Service + DAO + Entity + DB）の連携テスト
- •実際のDBアクセス（メモリDB）
- •外部APIはWireMockでスタブ化
- •既存テストがある場合は、削除せずに差分のみを反映する

ステップ6: E2Eテスト生成

code

@agent_skills/jakarta-ee-api-base/instructions/e2e_test_generation.md

E2Eテストを生成してください

パラメータ
* project_root: <プロジェクトルートパス>
* spec_directory: <SPECディレクトリパス>

AIが自動で以下を実行

•requirements/behaviors.md（E2Eテストシナリオ）を読み込み
•
JUnit 5 + Cucumber + REST Assured を使用したE2Eテストを生成
- •API層を含む全体フロー
- •実際のHTTPリクエスト/レスポンス
- •既存テストがある場合は、削除せずに差分のみを反映する
•テストデータのセットアップ/クリーンアップコードを生成

🔄 基本設計変更対応（手戻り・拡張案件）

code

@agent_skills/jakarta-ee-api-base/instructions/basic_design_change.md

基本設計の変更を適用してください

パラメータ
* project_root: <プロジェクトルートパス>
* spec_directory: <SPECディレクトリパス>
* change_spec: <変更差分ファイルパス>（省略可、デフォルト: {spec_directory}/basic_design/CHANGES.md）

AIが自動で以下を実行

•CHANGES.md（変更差分ファイル）を読み込み
•変更の影響を受けるドメインを識別
•影響を受けるドメインの詳細設計・コード・テストを更新
•CHANGES.mdをアーカイブ

使用方法:

•基本設計SPECのマスターファイル（functional_design.md等）を自由に編集
•CHANGES.mdを作成して変更内容を明示的に記載
•上記コマンドを実行
•適用後、CHANGES.mdは自動的にchanges_archive/に移動

重要:

•マスターファイルはMarkdown、EXCEL、PDF、Word等、任意の形式で管理可能
•変更内容はCHANGES.mdに明示的に記載（形式非依存）

実践例

詳細設計の作成（ドメイン単位）

code

@agent_skills/jakarta-ee-api-base/instructions/detailed_design.md

commonドメインの詳細設計を作成してください

パラメータ
* project_root: projects/sdd-wf/bookstore/back-office-api
* spec_directory: projects/sdd-wf/bookstore/back-office-api/specs/baseline
* target_domain: common

コード生成（ドメイン単位）

code

@agent_skills/jakarta-ee-api-base/instructions/code_generation.md

commonドメインのコードを生成してください

パラメータ
* project_root: projects/sdd-wf/bookstore/back-office-api
* spec_directory: projects/sdd-wf/bookstore/back-office-api/specs/baseline
* target_domain: common

その後、他のドメイン（orders, books_proxy等）の詳細設計とコード生成を実施する

対応する主要機能

•JAX-RS 3.1によるREST API実装
•JPA 3.1によるデータ永続化（JPQL、Criteria API）
•CDI 4.0による依存性注入
•トランザクション管理（@Transactional）
•楽観的ロック（@Version）
•JWT認証・認可
•CORS対応
•外部API統合（RestClient）
•例外ハンドリング（ExceptionMapper）

ディレクトリ構造

code

agent_skills/jakarta-ee-api-base/
├── SKILL.md                          # このファイル
├── README.md                         # クイックスタートガイド
├── principles/                       # 原則（全プロジェクト共通）
│   ├── architecture.md              # Jakarta EE APIアーキテクチャ標準
│   ├── security.md                  # セキュリティ標準
│   └── common_rules.md              # 共通ルール
├── templates/                        # SPECテンプレート
│   ├── basic_design/                # 基本設計用テンプレート
│   │   ├── architecture_design.md
│   │   ├── functional_design.md
│   │   ├── data_model.md
│   │   ├── behaviors.md            # 結合テスト用
│   │   └── external_interface.md
│   ├── requirements/                # 要件定義用テンプレート
│   │   └── behaviors.md            # E2Eテスト用
│   └── detailed_design/             # 詳細設計用テンプレート
│       ├── detailed_design.md
│       └── behaviors.md            # 単体テスト用
└── instructions/
    ├── basic_design.md               # ステップ1: 基本設計（SPEC作成、ドメインフォルダ構成）
    ├── detailed_design.md            # ステップ2: 詳細設計（ドメイン単位）
    ├── code_generation.md            # ステップ3: コード生成（実装+単体テスト、ドメイン単位）
    ├── unit_test_execution.md        # ステップ4: 単体テスト実行評価
    ├── it_generation.md              # ステップ5: 結合テスト生成（Cucumber + Weld SE）
    ├── e2e_test_generation.md        # ステップ6: E2Eテスト生成（Cucumber + REST Assured）
    └── basic_design_change.md        # 基本設計変更対応（手戻り・拡張案件）

参考資料

•
開発原則 - アーキテクチャ標準、セキュリティ標準、共通ルール
- •architecture.md - Jakarta EE APIアーキテクチャ標準
- •security.md - セキュリティ標準
- •common_rules.md - 共通ルール
•Jakarta EE 10仕様
•JAX-RS 3.1仕様
•Jakarta Persistence 3.1仕様
•Jakarta CDI 4.0仕様