android-modernization-upgrade

Android モダナイゼーションアップグレード

使用する場面

• 次のような依頼でこのスキルを使用します：古い Android プロジェクトのアップグレード、AGP や Kotlin のバージョン引き上げ後に発生した Android ビルドの修正、非推奨の Android クラスの置き換え。
• 主な成果：段階的なアップグレード、非推奨 API の置き換え、16 KB アライメントの確認、専門スキルへの明確な引き継ぎを通じて、非常に古い Android プロジェクトを現在サポートされているベースラインに引き上げます。
• 目的：非常に古い Android プロジェクトを現在サポートされているベースラインに引き上げるための、エンドツーエンドのガイダンスを提供します。
• 個別の Kotlin コード整理や単一ライブラリのリファクタリングではなく、リポジトリ全体の互換性と段階的なアップグレード手順が必要な場合に、このスキルを使用します。
• 発動する依頼の例：古い Android コードベースのアップグレード、バージョン引き上げ後の問題の修正、非推奨の Android パターンの移行、非推奨クラスの置き換え、古い Gradle／AGP／Kotlin の問題の解決、16 KB アライメントへの対応、アーキテクチャやセットアップのモダナイゼーションに関する依頼。
• 対象範囲が広がる場合は、次のスキルに引き継ぎます：
• android-gradle-build-logic
• android-viewsystem-foundations
• android-compose-xml-interoperability
• android-security-best-practices
• android-performance-observability
• android-rxjava-to-coroutines-migration

責務

• リポジトリの構成を診断します：AGP、Gradle、Kotlin、AndroidX／サポートライブラリ、SDK レベル、ネイティブ成果物、非推奨 API／クラスを確認します。
• すべてを一度に引き上げるのではなく、安全なアップグレード手順を作成します。
• Compose 中心、View システム中心、相互運用を組み合わせたプロジェクトそれぞれに応じて、移行経路を分岐させます。
• 修正内容が確定的な場合は非推奨の import やクラスを置き換え、それ以外の場合は明示的な修正項目を提示します。
• リリース前に、ネイティブのパッケージングと 16 KB アライメントへの対応状況を検証します。
• 主なアップグレードの阻害要因を特定したら、対象を絞った後続作業を適切な Android 専門スキルに引き継ぎます。

ワークフロー

1. プロジェクトをスキャンして、ツールチェーンの古さ、AndroidX の状況、ネイティブのパッケージング、非推奨 API を把握します。
2. 機械的な修正と、意味的なリスクを伴う変更を分けた、順序付きのモダナイゼーション計画を作成します。
3. 確定的なアップグレードを小さな段階に分けて適用し、各段階の後にビルド、テスト、Lint を再実行します。
4. 残る問題は、問題の正確な特徴とファイルパスを添えて担当する専門スキルに引き継ぎます。専用の移行スキルに移すべき RxJava チェーンも含めます。
5. 隠れた移行負債を残さない、最終的な修正レポートを作成します。

自動化モード

• audit：リポジトリを調査し、ファイルを編集せずに構造化された診断レポートを出力します。
• safe-apply：リポジトリの整理、バージョンの引き上げ、明らかなサポートライブラリの置き換え、マニフェストの正規化、単純な非推奨 API の置き換えなど、確定的な編集を実行します。
• report：未解決の阻害要因、ファイルパス、問題の特徴、次に使用する専門スキルを要約します。

ガードレール

• 自動適用するのは、確定的でレビュー可能な変更に限ります。
• 書き換えるのではなく段階的に移行できる場合は、動作中の機能を維持します。
• AGP、Gradle、Kotlin、SDK、AndroidX、ネイティブのパッケージングを、ひとつの互換性グラフとして扱います。
• 非推奨の動作を、置き換え方法と検証手順を記録せずに黙って削除してはいけません。

アンチパターン

• 段階的な検証をせずに、すべてのバージョンを一度に引き上げる。
• レガシーな View 専用アプリに、デフォルトで Compose 移行のアドバイスを適用する。
• 古いアプリで、ネイティブライブラリ、ABI のパッケージング、ページサイズのアライメントを無視する。
• 非推奨クラスやサポートライブラリがまだ含まれているのに、プロジェクトがモダナイズ済みだと判断する。

必須ツール

• scripts/scan_project.py
• scripts/build_compat_matrix.py
• scripts/generate_remediation_checklist.py
• scripts/apply_safe_upgrades.py
• scripts/check_16kb_alignment.py

必須のリファレンス

• references/agp-upgrade-notes.md
• references/kotlin-compatibility.md
• references/androidx-migration.md
• references/gradle-compatibility.md
• references/sdk-behavior-changes.md
• references/jetpack-release-notes.md
• references/deprecated-replacements.md
• references/upgrade-matrix.md
• references/issue-signature-catalog.md

例

正常系

• シナリオ：サポートライブラリ時代のプロジェクトをスキャンし、順序立てたアップグレードチェックリストを生成します。
• コマンド：python3 skills/android-modernization-upgrade/scripts/scan_project.py examples/fixtures/legacy-support-app

エッジケース

• シナリオ：古い AGP と Kotlin のバージョンの組み合わせで行き詰まったプロジェクトを復旧し、段階的な修正を検証します。
• コマンド：python3 skills/android-modernization-upgrade/scripts/generate_remediation_checklist.py examples/fixtures/legacy-mismatch-app

失敗からの復旧

• シナリオ：リリース前にネイティブのパッケージ化と 16 KB アライメントの問題を自動検出します。
• コマンド：python3 skills/android-modernization-upgrade/scripts/check_16kb_alignment.py examples/fixtures/native-misaligned-app/app-release.apk

完了チェックリスト

• 実装手順が明確かつ最小限で、適切な Android 領域に対応しています。
• 関連するコマンド例とベンチマーク用プロンプトを実行するか、更新しています。
• 依頼内容が隣接するスキルの範囲にまたがる場合は、引き継ぎ方法を記載しています。
• 選択したパターンと、主要な移行またはトラブルシューティングの手順を公式リファレンスで確認できます。
• 安全性が確認された修正は自動適用し、判断が曖昧な移行は、黙って変更せずに報告しています。
• 非推奨クラスは置き換えるか、正確なファイルパスと置き換え方法を記載しています。
• 16 KB アライメントを検証するか、該当するサードパーティ製またはネイティブの阻害要因を明記しています。

公式リファレンス

• https://developer.android.com/build/releases/gradle-plugin
• https://developer.android.com/build/kotlin-support
• https://developer.android.com/jetpack/androidx/migrate
• https://developer.android.com/build/migrate-to-built-in-kotlin