modernize-ui5-app

UI5 モダナイゼーションワークフロー

このスキルでは、UI5 アプリケーションを5 つのフェーズでモダナイズし、各フェーズの後に検証ゲートを設けます。ユーザーは最初にゲートの動作を 1 回選択します。選択肢は、完全自律型、半自律型、手動です。オーケストレーターは、各フェーズの境界でその選択を適用します。

5 つのフェーズ

1. 機械的なベースライン — 自動修正とテストスターターの再構成を行います。リスクが低く、テストを実行できるようになります。
2. 基盤 — manifest.json と Component.js を対象とします。以降のすべての処理でマニフェストを読み込みます。
3. モジュールシステムとグローバル — 依存関係グラフ（sap.ui.define の配列、遅延読み込み、暗黙のグローバルを使用しない状態）を整備します。循環依存と見落とし箇所の修正はこのフェーズで行います。
4. 非推奨 API — 名前をそのまま置き換えるだけの作業です。フェーズ 3 でグラフが安定してから行うと安全です。
5. CSP 準拠 — 先行するすべてのフェーズで CSP に準拠する必要があるため、最後に行います。

フェーズ 5 の後にドキュメントを作成し、MODERNIZATION-REPORT.md と MODERNIZATION-ISSUES.md を出力します。

ルール ID とスキルの対応

ルール ID	スキル	フェーズ
no-deprecated-theme	fix-bootstrap-params	4
no-outdated-manifest-version	fix-manifest-json	2
no-legacy-ui5-version-in-manifest	fix-manifest-json	2
no-deprecated-library	fix-manifest-json（マニフェスト）または fix-bootstrap-params（HTML）	2 / 4
no-deprecated-component	fix-manifest-json	2
no-removed-manifest-property	fix-manifest-json または fix-component-async	2
async-component-flags	fix-component-async	2
no-globals	fix-xml-globals（すべての XML）または fix-js-globals（JS — sap./jQuery.）	3
no-ambiguous-event-handler	fix-xml-globals	3
no-deprecated-control-renderer-declaration	fix-control-renderer	4
ui5-class-declaration	fix-control-renderer	4
no-pseudo-modules	fix-pseudo-modules	3
no-implicit-globals	fix-pseudo-modules	3
unsupported-api-usage	fix-partially-deprecated-apis	4
prefer-test-starter	modernize-test-starter	1
csp-unsafe-inline-script	fix-csp-compliance	5
（構造上）	fix-cyclic-deps	3
（実行時）	fix-linter-blind-spots	3

no-deprecated-api の識別

ファイルの種類	メッセージに含まれる文字列	スキル	フェーズ
.html	"bootstrap parameter", "deprecated theme"	fix-bootstrap-params	4
manifest.json	"view type", "model type", "resources/js"	fix-manifest-json	2
.js	"Lib.init/Library.init"	fix-library-init	4
.js	"deprecated renderer", "apiVersion", "IconPool", "rerender"	fix-control-renderer	4
.js	"deprecated class/property/interface"	fix-deprecated-controls	4
.js	"registerControllerExtensions" または sap.ui.controller（マニフェストの sap.ui.controllerExtensions 内）	fix-fiori-elements-extensions	4
.js	"sap.ui.controller"（マニフェストの拡張機能内にない場合）	fix-js-globals（ケース 9）	3
.js	"jQuery.sap.declare", "jQuery.sap.require"	fix-js-globals（ケース 10）	3
.js	"getLibraryResourceBundle"	fix-js-globals	3
.js	"MessagePage"	fix-deprecated-controls	4
.js	"Parameters.get", "loadData", "Mobile.init", "createEntry", "View.create", "Fragment.load", "Router"	fix-partially-deprecated-apis	4
.xml	"native HTML", "SVG"	fix-xml-native-html	4
.xml	"visibleRowCountMode", 行モード属性	fix-table-row-mode	4
.xml	"MessagePage"	fix-deprecated-controls	4
任意	（一致なし）	MODERNIZATION-ISSUES.md に記録	—

フェーズ 0：前提条件とモードの選択

前提条件の確認

npx @ui5/linter --version || echo "ERROR: @ui5/linter not available"

インストールされていない場合は、ユーザーに npm install --save-dev @ui5/linter を実行するよう伝えて終了します。

非対話モード

プロンプトに「確認を求めないでください」などの文言が含まれている場合は、モードの選択、ゲート、コミット、ドキュメント作成を省略します。フェーズ 1～5 を順番に、一時停止せずに実行します。

ユーザーに一度だけ確認：どの検証モードにしますか？

モード	各ゲートでの動作
完全自律	テストを実行 → 失敗した場合、デバッグして修正（再試行は3回まで、またはデバッグに1回失敗した時点で停止）。停止時にレポートを出力し、ユーザーに確認します。
半自律	テストを実行 → 構造化レポートを出力します。ユーザーの「続行」を待ちます。
手動	テストをスキップします。1行の要約を出力します。ユーザーの「続行」を待ちます。

モードを保存します。フェーズ間で再確認しないでください。

ビルドとテストのコマンド

references/build-and-test-commands.md を読みます。Chrome DevTools MCP が接続されている必要があります（必要な場合は /install-mcps でインストールしてください）。

• pom.xml が存在する → Maven を使用します。ゲートには §1.3（mvn clean verify -P execute.qunit ...）を使用します。
• pom.xml が存在しない → npm を使用します。package.json のスクリプトを使用します。フォールバック：npx @ui5/linter --details

運用原則

1. 対応するスキルがあるエラーはすべて修正してください。 エラー数の多さを先送りの理由にしてはいけません。
2. フェーズは順番どおりに必ず実行してください。 フェーズ3では、リンターでは検出できない実行時のパターンを確認します。エラーがゼロのレポートが出ても、フェーズ3が完了したことにはなりません。
3. 戻り値の型が変わる場合、同期処理から非同期処理への自動変更は絶対に行わないでください。 sap.ui.xmlfragment()、sap.ui.component()、sap.ui.view()、sap.ui.controller()（インスタンス化）は MODERNIZATION-ISSUES.md に記載します。
4. MODERNIZATION-ISSUES.md の使用は最終手段です。 有効な理由：スキルが存在しない、またはスキルが実際に失敗した。無効な理由：スキルが存在するのに「ルール X のエラーが残り約 N 件」と記載すること。

Git コミット戦略

フェーズごとに1つ、合計5つのコミットを作成します（ドキュメント分は別）。各フェーズで変更したファイルのみをステージングし、git add -A は絶対に使用しないでください。

絶対にステージングしないファイル： headless-chrome.json、pom.xml（dev profile のパッチ）、.gitignore（ローカルテスト用インフラ）。

#	作成後のフェーズ	メッセージ
1	1	chore: apply UI5 linter autofix and modernize test starter
2	2	fix: modernize manifest.json and Component.js
3	3	fix: modernize module system (globals, pseudo-modules, cycles, blind spots)
4	4	fix: replace deprecated UI5 APIs
5	5	fix: enforce CSP compliance
6	ドキュメント	docs: add modernization report and issues

フェーズで変更がなければ、コミットをスキップします。

フェーズ1：機械的なベースライン

ステップ1.1：初期分析

npx @ui5/linter --details 2>&1 | tee /tmp/ui5-linter-baseline.txt
grep -c " error \| warning " /tmp/ui5-linter-baseline.txt || echo "0"

解析内容：エラーと警告の合計数、ルール ID およびファイルごとの分類。最終比較用に保存します。

ステップ1.2：自動修正の適用

npx @ui5/linter --fix
npx @ui5/linter --details 2>&1 | tee /tmp/ui5-linter-post-autofix.txt

ステップ1.3：テストスターターのモダナイズ

modernize-test-starter を使用してサブエージェントを起動します。カスタムプロンプトで、スキルを読み、変更前にフェーズ0の検出を完全に実施し、すべてのフェーズに従い、14項目の完了チェックリストに照らして検証するよう指示します。

フェーズ1のコミットとゲート

フェーズ2：基盤

ステップ2.1：manifest.json

fix-manifest-json を使用してサブエージェントを起動します。次のルールによる manifest.json のすべてのエラーを渡します：no-outdated-manifest-version、no-legacy-ui5-version-in-manifest、no-deprecated-library、no-deprecated-component、no-removed-manifest-property、および「view type」／「model type」／「resources/js」を含む no-deprecated-api。

ステップ2.2：Component.js

fix-component-async を使用してサブエージェントを起動します。無条件に適用します。リンターが async-component-flags を指摘していなくても適用してください（このエラーは、manifest.json から rootView の async: true を削除した後にのみ表示されます）。

ステップ2.3：Component.js の検証

node {skills-dir}/fix-component-async/scripts/verify-component.js {project-path}

終了コードが1の場合は修正します：imported-interface → deps から削除し、文字列リテラルを使用する。interface-not-string → 変数を文字列に置き換える。missing-interface → metadata に追加する。再実行して確認します。

フェーズ2のコミットとゲート

フェーズ3：モジュールシステムとグローバル

戦略： グローバル／モジュール関連の3つのスキルを並列で実行します（対象ファイルが異なります）。fix-linter-blind-spots と fix-cyclic-deps はその後に順次実行します（安定した完全な JS レイヤーが必要です）。

重要： ステップ3.1では、必ずサブエージェントを使用してください。fix-js-globals の重要なルールは、メインエージェントのコンテキストに含まれていません。

Step 3.1: 並列バッチ

サブエージェントを並列で起動します（同時に最大8つ）：

• fix-js-globals：JS の no-globals エラーと、振り分けられた no-deprecated-api のケースを担当
• fix-pseudo-modules：no-pseudo-modules／no-implicit-globals を担当
• fix-xml-globals：すべての XML の no-globals／no-ambiguous-event-handler（アプリの名前空間のグローバルを含む）を担当

テスト用リソースも含まれています — test/ ファイルにも同じルールを適用します。

Step 3.1b: リグレッションチェック

リンターを再実行します。Step 3.1 のルールに関する新しいエラーが発生した場合は、それらを対象に2回目のバッチを起動します。他のフェーズに属するエラーは無視します。

Step 3.2: fix-linter-blind-spots

サブエージェントを1つ起動します。次のように指示します：スキルを読み、名前空間のマニフェストを読み、detect-blind-spots.js を実行し、すべてのパターンを修正してから、スクリプトを再実行し、合計がゼロであることを確認します。

Step 3.3: fix-cyclic-deps

サブエージェントを1つ起動します。次のように指示します：スキルを読み、依存関係グラフを作成し、2ノードの循環依存を自動修正（遅延 require）し、3ノード以上の依存関係チェーンを MODERNIZATION-ISSUES.md に記録します。

Phase 3 のコミット＋ゲート

コミット前にリンターを再実行し、リグレッションがないことを確認します。

Phase 4: 非推奨 API

方針： スキルごとに対象となるルール／ファイルが異なるため、スキルごとに並列で実行します。マッピングテーブルを使ってスキルごとにエラーをまとめ、ファイルごと（またはクラスターごと）にサブエージェントを1つ起動します。

実行

サブエージェントを並列で起動します（同時に最大8つ）。Sub-Agent Prompt Template を使用します。スキルごとにファイルをまとめます。

Step 4.2: リグレッションチェック

リンターを再実行します。新たに発生した Phase 4 のエラーのみを対象に、2回目のバッチを実行します。

Phase 4 のコミット＋ゲート

Phase 5: CSP 準拠

先行フェーズでインラインブロックが導入される可能性があるため、CSP は最後に対応します。

重要：インラインスクリプトは絶対に削除せず、必ず外部化してください。 インラインコードを .js ファイルに移動し、<script src="..."> に置き換えます。

csp-unsafe-inline-script があるファイルを対象にサブエージェントを起動します。テンプレートで fix-csp-compliance を使用します。

Phase 5 のコミット＋ゲート

エラー数を確認するため、最後にリンターを実行します。

検証ゲート

各フェーズのコミット後、Phase 0 で選択したモードに対応するゲートを実行します。すべてのテストコマンドでタイムアウトを600000msに設定してください。

全自動

サブエージェントに委任してください。 ⏳ Phase {N} gate: launching test sub-agent... を出力します。

サブエージェントへの指示：

1. references/build-and-test-commands.md を読み、Maven と npm のどちらを使うか確認します。
2. テストコマンド（Maven §1.3 または npm test）を実行します。テストコマンドが存在しない場合を除き、リンターのみの実行は検証になりません。
3. Maven：終了コードが0でも、すべてのテストが成功したとは限りません。 出力にある失敗の要約と target/surefire-reports/ を確認します。
4. 成功した場合 → ✅ TESTS OK と報告します。
5. 失敗した場合 → 分析し、最小限の修正（壊れた import／パス／アサーションのみ。コードのモダナイズはしない）を試みて、再実行します。再試行は3回、またはデバッグに1回失敗した時点で終了します。
6. スコープの制約： 現在のフェーズが原因で失敗したテストのみ修正します。他のフェーズのモダナイズは絶対に適用しないでください。

完了後：✅ → 続行します。❌ → 要約を出力し、ユーザーに確認します。

半自動

同じサブエージェントを使用しますが、失敗のデバッグは行いません。結果のみ報告します：

✅/❌ Tests: N passed, N failed, N skipped
Failed test names (≤10)

ユーザーの指示を待ちます：「continue」／「skip phase」／「run tests」／「abort」。

手動

次を出力します：Phase {N} done. Files: {count}. Fixed: {count}. Deferred: {count}. ユーザーの「continue」を待ちます。

Sub-Agent Prompt Template（Phases 1–5）

Fix UI5 linter errors in the following file(s) using the {skill-name} skill.

Project root: {project-path}

File: {file-path}
Errors to fix:
{errors}

Instructions:
1. Read {skills-dir}/{skill-name}/SKILL.md
2. Pay special attention to "Key Rules" — load-bearing constraints from past failures.
3. Read reference files mentioned in the skill.
4. Read the affected file(s).
5. Apply fix patterns EXACTLY as documented.
6. Verify each error is resolved.
7. Report: files modified, errors fixed, unfixable errors ({file}:{line} | {rule} | {reason}).

サブエージェントの実行ルール

• フォアグラウンドモードのみ。 フェーズ内の各ステップについて、すべてのサブエージェントを1つのメッセージで起動します。全エージェントの結果が返るまで待機します。
• メッセージあたり同時実行数は約8つまで。 それ以上の場合は順次バッチ処理し、1回のバッチで終了しないでください。
• 関連するファイル（コントローラーとその XML ビューなど）は1つのサブエージェントにまとめます。
• フェーズ内の各ステップでは、バッチ間に検証を行いません。 チェックはフェーズのステップ完了後に行います。
• マッピングされたエラーがあるファイルは、すべて処理する必要があります。

フェーズごとのスキルの割り当て

フェーズ	スキル
1	modernize-test-starter
2	fix-manifest-json、fix-component-async
3（並列）	fix-js-globals、fix-pseudo-modules、fix-xml-globals
3（順次）	fix-linter-blind-spots、fix-cyclic-deps
4	fix-bootstrap-params、fix-library-init、fix-control-renderer、fix-deprecated-controls、fix-fiori-elements-extensions、fix-partially-deprecated-apis、fix-table-row-mode、fix-xml-native-html
5	fix-csp-compliance

ドキュメント作成フェーズ（フェーズ 5 の後）

references/documentation-templates.md のテンプレートを使用して、MODERNIZATION-ISSUES.md と MODERNIZATION-REPORT.md を作成します。

コミット：docs: add modernization report and issues

コンテキスト管理

メインエージェントは子スキルのファイルを読みません。読み取るのはサブエージェントのみです。

1. 子スキルを読まないでください。 ルーティングテーブルでスキルを選択し、サブエージェントが自身のスキルを読み取ります。
2. リンターの出力を解析して破棄します。 各サブエージェントには、フィルタリング済みのエラーのみを渡します。
3. サブエージェントの結果を圧縮します。 修正件数、修正不能なエラー、変更したファイルのみを保持します。
4. 完了を優先します。 コンテキストが不足しそうな場合は、フェーズ 5 を完了させてください。必要であればドキュメント作成を省略します。

エラー処理

修正に失敗した場合は、内容を記録して MODERNIZATION-ISSUES.md に追加し、次のエラーに進みます。

完了チェックリスト

• ユーザーはフェーズ 0 で検証モードを選択済みで、エージェントは再度質問していない
• フェーズ 1～5 の各フェーズにコミットがある（または変更がなくスキップされている）
• 選択したモードに従い、各フェーズの後に検証ゲートを実行した
• フェーズ 3 では、バッチ後のリンター結果が 0 件でも、3 つすべての手順（並列処理、見落としの確認、循環依存の確認）を実行した
• サブエージェントをフォアグラウンドで、単一メッセージのバッチとして起動した
• ファイルはフェーズごとにステージングした（git add -A は使用していない）
• MODERNIZATION-ISSUES.md には、実際に修正できないエラーのみが記載されている