struts-to-jsf-migration

name	struts-to-jsf-migration
description	Apache Struts 1.xからJakarta Faces (JSF) 4.0へのマイグレーションを支援。仕様駆動アプローチ（Spec-Driven Migration）により、リバースエンジニアリング、タスク分解、詳細設計、本番コード生成、テスト生成・評価の6段階で確実なマイグレーションを実現。本番コードとテストコードの生成を分離し、ブラックボックス・ホワイトボックス両方の観点からテストを実装。基本設計変更対応も含む。

Struts to JSF マイグレーション Agent Skill

JSF設計の特徴

JSFは画面中心のサーバーサイドMVCフレームワークです：

• 画面グループ: 関連する画面群（一覧、入力、確認等）をまとめたもの
• 基本設計: 画面グループ単位（basic_design/{screen_group}/）
• 詳細設計: 画面単位（detailed_design/FUNC_XXX/）
• 設計の流れ: 画面グループ全体を設計 → 個別画面を詳細設計

REST APIとの違い:

• REST API: ドメイン/リソース単位（orders, images等）
• JSF: 画面グループ単位（person_management等）

---

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

ステップ1: リバースエンジニアリング

@agent_skills/struts-to-jsf-migration/instructions/reverse_engineering.md
@projects/legacy/struts-app

既存のStrutsプロジェクトからSPECを生成してください

パラメータ
* struts_project_root: projects/legacy/struts-app
* spec_output_directory: projects/jsf-migration/struts-app-jsf/specs

AIが自動で以下を実行

1. Strutsコード（Action、ActionForm、JSP、EJB、DAO）を分析
2. テンプレートを参照してSPECを生成
   • @agent_skills/struts-to-jsf-migration/templates/basic_design/ から参照
   • 共通設計: specs/baseline/basic_design/common/
   • 画面グループ単位の設計: specs/baseline/basic_design/{screen_group}/
3. 抽象的・論理的なSPECとしてspecs/フォルダに保存

生成される構造:

• 画面グループ: 関連する画面群（一覧、入力、確認等）をまとめたもの
• JSFは画面中心のサーバーサイドMVCフレームワーク

テンプレート:

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

ステップ2: 詳細設計（ドメイン単位）

@agent_skills/struts-to-jsf-migration/instructions/detailed_design.md

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

パラメータ
* project_root: projects/jsf-migration/struts-app-jsf
* spec_directory: projects/jsf-migration/struts-app-jsf/specs/baseline
* target_domain: common  # または person_management 等

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

1. 画面グループの基本設計（basic_design/{screen_group}/）を読み込み
2. 対象ドメインの理解内容を説明
3. 不明点をユーザーに質問
4. 対話で妥当性・充足性を確認
5. ドメイン単位のdetailed_design/{domain}/detailed_design.mdを生成

実行順序: commonドメインを最優先で実装

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

@agent_skills/struts-to-jsf-migration/instructions/code_generation.md

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

パラメータ
* project_root: projects/jsf-migration/struts-app-jsf
* spec_directory: projects/jsf-migration/struts-app-jsf/specs/baseline
* target_domain: common  # または person_management 等
* skip_infrastructure: false  # commonドメイン初回setup時のみ: true の場合、インフラセットアップをスキップ

AIが自動で以下を実行

1. 詳細設計を読み込み
2. JSFコードを生成（Managed Bean、Entity、Service、Facelets XHTML等）
   • commonドメイン初回時: skip_infrastructure=true の場合、DB/APサーバーのインストールをスキップ（スキーマ作成・初期データは実行）
   • 既存コードがある場合は、削除せずに差分のみを反映する

注意: 単体テストコード生成は次のステップ（ステップ4）で実施

実行順序: commonドメインを最優先で実装

ステップ4: 単体テストコード生成

@agent_skills/struts-to-jsf-migration/instructions/unit_test_generation.md

単体テストコードを生成してください

パラメータ
* project_root: projects/jsf-migration/struts-app-jsf
* spec_directory: projects/jsf-migration/struts-app-jsf/specs/baseline
* target_domain: common  # または person_management 等

AIが自動で以下を実行

1. 詳細設計（detailed_design/{target_domain}/）とbehaviors.mdを読み込む
2. 本番コード（ステップ3で生成）に対応する単体テストコードを生成
   • ブラックボックステスト: behaviors.mdのGherkinシナリオから外形的な振る舞いをテスト
   • ホワイトボックステスト: 境界値・エッジケース・分岐パスをカバーするテスト
   • 同じドメイン内のコンポーネント間は実際の連携をテスト
   • ドメイン外の依存関係のみモック化
   • 既存テストがある場合は、削除せずに差分のみを反映する
3. @Nestedを使用してテストを構造化（振る舞いテスト、カバレッジ確保テスト）

重要:

• テスト生成のみを実施（テスト実行は手動で ./gradlew test を実行）
• behaviors.mdのGherkinシナリオを必ず参考にする
• Managed Bean はカバレッジ除外推奨（UI層はE2Eで検証）

ステップ5: テスト評価（単体/結合/E2E共通）

@agent_skills/struts-to-jsf-migration/instructions/test_evaluation.md

テスト実行結果を評価してください

パラメータ
* project_root: projects/jsf-migration/struts-app-jsf
* jacoco_reports_dir: build/reports/jacoco/test
* test_type: unit  # unit, integration, e2e のいずれか
* spec_directory: projects/jsf-migration/struts-app-jsf/specs/baseline

前提: テストは既に実行済み（./gradlew test または integrationTest または e2eTest）

AIが自動で以下を実行

1. Jacocoレポート（XML）を読み込む
2. カバレッジ評価（行、分岐、メソッド）
3. パッケージ別/クラス別/メソッド別カバレッジ分析
4. デッドコード検出
5. テスト品質評価（テスト数、失敗分析）
6. 評価レポート生成
7. ユーザーに推奨アクションを提示

重要:

• テスト実行は不要（既に実行済みのレポートを評価）
• 単体テスト、結合テスト、E2Eテストのいずれにも対応
• Managed Bean はカバレッジ除外推奨（UI層はE2Eで検証）

フィードバックループ:

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

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

@agent_skills/struts-to-jsf-migration/instructions/it_generation.md

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

パラメータ
* project_root: projects/jsf-migration/struts-app-jsf
* spec_directory: projects/jsf-migration/struts-app-jsf/specs/baseline

AIが自動で以下を実行

1. basic_design/{screen_group}/behaviors.md（結合テストシナリオ）を読み込み
2. JUnit 5 + Weld SE を使用した結合テストを生成
   • Service層以下（Service + DAO + Entity + DB）の連携テスト
   • 実際のDBアクセス（メモリDB）
   • 画面グループの業務フローを検証
   • 既存テストがある場合は、削除せずに差分のみを反映する

重要:

• テスト生成のみを実施（テスト実行は手動で ./gradlew integrationTest を実行）
• テスト実行後、ステップ5（test_evaluation.md）でtest_type=integrationとして評価

---

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

@agent_skills/struts-to-jsf-migration/instructions/basic_design_change.md

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

パラメータ
* project_root: projects/jsf-migration/struts-app-jsf
* spec_directory: projects/jsf-migration/struts-app-jsf/specs/baseline
* change_spec: <変更差分ファイルパス>（省略可、デフォルト: {spec_directory}/basic_design/CHANGES.md）

AIが自動で以下を実行

1. CHANGES.md（変更差分ファイル）を読み込み
2. 変更の影響を受けるファイル（詳細設計、コード、XHTML、テスト）を特定
3. 変更タスクファイル（tasks/change_tasks.md）を生成
4. 既存の指示書を呼び出して更新
5. CHANGES.mdをアーカイブ

使用方法:

1. 基本設計SPECのマスターファイル（functional_design.md、screen_design.md等）を自由に編集
2. CHANGES.mdを作成して変更内容を明示的に記載
   • 共通設計の変更: basic_design/common/CHANGES.md
   • 画面グループ固有設計の変更: basic_design/{screen_group}/CHANGES.md
3. 上記コマンドを実行
4. 適用後、CHANGES.mdは自動的にchanges_archive/に移動

重要:

• マスターファイルはMarkdown、EXCEL、PDF、Word等、任意の形式で管理可能
• 変更内容はCHANGES.mdに明示的に記載（形式非依存）
• 共通設計と画面グループ固有設計で別々のCHANGES.mdを管理

注意:

• JSFは画面中心のサーバーサイドMVCフレームワーク
• 画面グループ: 関連する画面群（一覧、入力、確認等）をまとめたもの

---

実践例

@agent_skills/struts-to-jsf-migration/instructions/reverse_engineering.md
@projects/master/person/struts-person

既存のstruts-personプロジェクトからSPECを生成してください

パラメータ
* struts_project_root: projects/master/person/struts-person
* spec_output_directory: projects/master/person/jsf-person-migrated/specs

その後、SPEC検証とコード生成を実施する

---

マイグレーション対象

Strutsの構成要素

既存コード分析で対象となるStrutsの構成要素

• ActionForm: リクエストパラメータの保持
• Action: ビジネスロジックの呼び出し
• struts-config.xml: マッピング設定
• JSPタグライブラリ: <logic:iterate>, <bean:write>, <html:form>等
• EJB: ステートレスセッションBean（JNDIルックアップ）
• DAO: JDBC + DataSource

JSFの構成要素

仕様駆動開発で生成されるJSFの構成要素

• Managed Bean: @Named, @ViewScoped
• CDI: @Injectで依存性注入
• JPA: EntityManager、JPQL
• トランザクション: @Transactional
• Facelets XHTML: <h:dataTable>, <h:outputText>, <h:form>等

---

ディレクトリ構造

agent_skills/struts-to-jsf-migration/
├── SKILL.md                          # このファイル
├── README.md                         # クイックスタートガイド
├── principles/                       # マイグレーション原則
│   ├── architecture.md              # Jakarta EE APIアーキテクチャ標準
│   ├── security.md                  # セキュリティ標準
│   └── common_rules.md              # マイグレーションルール、マッピング規則
├── templates/                        # SPECテンプレート（リバースエンジニアリング用）
│   └── basic_design/                # 基本設計用テンプレート
│       ├── architecture_design.md  # アーキテクチャ設計書
│       ├── data_model.md           # データモデル仕様書
│       ├── external_interface.md   # 外部インターフェース仕様書
│       ├── functional_design.md    # 機能設計書（画面グループ）
│       ├── screen_design.md        # 画面設計書（JSF専用）
│       ├── behaviors.md            # 振る舞い仕様書（E2Eテスト用）
│       └── CHANGES_template.md     # 変更管理テンプレート
└── instructions/
    ├── reverse_engineering.md        # ステップ1: リバースエンジニアリング
    ├── task_breakdown.md             # ステップ2: タスク分解
    ├── detailed_design.md            # ステップ3: 詳細設計
    ├── code_generation.md            # ステップ4: コード生成（実装+単体テスト）
    ├── unit_test_execution.md        # ステップ5: 単体テスト実行評価
    ├── it_generation.md              # ステップ6: 結合テスト生成（JUnit + Weld SE）
    └── basic_design_change.md        # 基本設計変更対応（手戻り・拡張案件）

---

参考資料

• マイグレーション原則 - マイグレーションルール、アーキテクチャ標準、セキュリティ標準
  • architecture.md - Jakarta EE APIアーキテクチャ標準
  • security.md - セキュリティ標準
  • common_rules.md - 共通ルール、マッピング規則
• Jakarta EE 10仕様
• Jakarta Faces 4.0仕様
• Jakarta Persistence 3.1仕様
• Apache Struts 1.x Documentation