angular-migration

angular-migration スキルの概要

angular-migration が実際に支援してくれること

angular-migration スキルは、既存の AngularJS 1.x コードベースをモダンな Angular へ移行するチーム向けのスキルです。特に、全面書き直しのリスクが高すぎるケースで力を発揮します。役割は単なる「構文変換」ではありません。移行方針の選定、必要に応じたハイブリッドアプリ構成の設計、そして移行で最も痛みが出やすい境界面――directive から component への置き換え、AngularJS service から Angular DI への移行、ルート単位での段階的な差し替え――を整理して進めるための支援が中心です。

angular-migration スキルを使うべき人

このスキルは、すでに実運用中の AngularJS アプリを持ち、現実的な移行ルートを必要としているフロントエンドエンジニア、テックリード、移行責任者に向いています。特に次のような場面で有効です。

• big-bang、hybrid、vertical-slice のどれで進めるべきか判断したい
• 移行中もリリースを止めずに進めたい
• 古い directives / controllers を Angular の components / services に書き換えたい
• routing や dependency injection の変更を段階的かつ安全に進めたい

angular-migration が適している移行シナリオ

angular-migration は、レガシー資産の比重が大きいアプリで使うのが適しています。

• 継続リリース中の大規模 AngularJS コードベースがある
• 共有 services や directives を一度に置き換えられない
• 移行期間中に AngularJS + Angular のハイブリッド実行環境が必要
• 抽象的なフレームワーク論ではなく、機能単位の移行計画が必要

逆に、新規の Angular アプリをゼロから作るだけなら、このスキルはやや大げさです。

一般的な migration prompt と angular-migration の違い

一般的な prompt は、すぐコード変換に飛びがちです。angular-migration が本当に役立つのは、難所が「変換そのもの」ではなく「どういう順番で進めるか」にある場合です。つまり、移行戦略の選定、hybrid mode の立ち上げ、古い AngularJS の概念を Angular の対応概念へ落とし込みながら、デリバリーパイプラインを壊さずに進めること。多くのチームで導入の壁になるのは、まさにそこです。

インストール前に知っておくこと

このスキルは repository-light です。実質的な情報源は SKILL.md のみで、追加スクリプト、参照資料、補助アセットはありません。そのため、すぐ中身を確認できる一方で、得られるのは自動化ツールではなく、ガイダンスの型や例が中心になります。turnkey な codemod を期待するなら不向きですが、意思決定の支援や移行の設計図がほしいなら導入価値があります。

angular-migration スキルの使い方

angular-migration スキルのインストール前提

通常の Skills ワークフローで、agent 環境に angular-migration をインストールします。よくあるパターンは次のとおりです。

npx skills add https://github.com/wshobson/agents --skill angular-migration

このスキルは単一の SKILL.md ファイルとして提供されているため、インストールの目的は実行可能なツールを取り込むことではなく、agent の作業フロー内でこのガイダンスを呼び出せるようにすることです。

最初に読むべきファイル

最初に読むのは以下です。

• SKILL.md

実用的な内容はこのファイルにまとまっています。スキルの使いどころ、移行戦略、ハイブリッド構成、コード例までここに入っています。補助的な rules フォルダや resource フォルダはないため、全体を通読するコストは低く、実際に頼る前に一通り読んでおく価値があります。

angular-migration が必要とする入力情報

angular-migration スキルは、抽象的な相談よりも、実リポジトリの事実を渡したときに格段に精度が上がります。特に有用なのは次の情報です。

• 現在の AngularJS のバージョンとアプリ規模
• 移行中もリリース継続が必要か
• 利用中の routing library
• 主要な directive パターン
• DI / service の設計パターン
• build tooling と test の整備状況
• hybrid runtime を許容できるか
• 目標とする Angular のバージョンと移行期限

これらがないと、出力は「大規模アプリなら hybrid が無難です」といった、正しくはあるが判断材料としては弱い内容に留まりやすくなります。

曖昧な目標を強い prompt に変える

弱い prompt:

• “Help migrate my AngularJS app to Angular.”

より強い prompt:

• “Use the angular-migration skill to recommend a migration strategy for a 70k-line AngularJS 1.6 app with ui-router, 120 directives, and weekly releases. We need to keep shipping, can tolerate a hybrid app for 6 months, and want a phased route migration. Propose strategy, sequencing, first feature slice, DI conversion approach, and top technical risks.”

この形のほうがうまく機能するのは、このスキルの強みが「移行の全体像をどう設計するか」にあり、制約条件を推測することにはないからです。

実務で使いやすい angular-migration usage フロー

良い angular-migration usage の進め方は次のようになります。

1. まずアプリを分類する: 小規模で書き直し候補か、hybrid 候補か
2. 戦略を 1 つ選ぶ: big bang、incremental hybrid、vertical slice
3. 移行単位を特定する: routes、features、directives、services
4. AngularJS と Angular の相互運用要件を定義する
5. 最初は狭い機能単位から変換する
6. bootstrapping、DI、routing の境界面を検証する
7. 安定した移行チェックリストで繰り返す

この流れにすると、戦略の議論と低レベルな書き換えを早い段階で混ぜてしまう、よくある失敗を避けられます。

戦略選定: どう選ぶと失敗しにくいか

この repository では、主に 3 つの戦略が重視されています。

• Big Bang: 比較的小さなアプリ、または並行リライトが現実的な場合に向く
• Incremental / Hybrid: リリースを止められない大規模アプリに向く
• Vertical Slice: 機能の境界が明確で、エンドツーエンドに置き換えやすい場合に向く

実際のレガシーアプリでは、hybrid か vertical-slice が現実解になりやすいです。big bang を選ぶのは、長期間の dual-stack 複雑性を抱えるコストより、運用上のリスクのほうが低いと判断できる場合に限るべきです。

ハイブリッドアプリ計画に angular-migration を使う

angular-migration for Frontend Development の中でも特に価値が高いのが、hybrid app の計画支援です。@angular/upgrade/static を使う場合は、次の観点で支援を求めると効果的です。

• bootstrap の順序
• AngularJS / Angular の共存境界
• downgraded / upgraded components と services の扱い
• どの共有 dependency から先に移すべきか
• 共存期間中も feature team の手を止めない進め方

このあたりは、通常の prompt だと曖昧になったり、危うい提案になりやすい部分です。

directive・component・DI 変換の prompt 例

アプリ全体の移行計画だけでなく、局所的な変換にもこのスキルは使えます。効果が高い prompt の形は次のようなものです。

• “Map this AngularJS directive with isolate scope and link function into an Angular component design.”
• “Convert this AngularJS service registration pattern into Angular DI with provider scope guidance.”
• “Explain which controllers should become smart container components versus plain services.”

こうした絞った依頼のほうが、“convert everything” のような投げ方より、実務で使える出力になりやすいです。

routing 移行ガイドの使いどころ

移行計画が崩れやすいのは routing です。このスキルを使って、次の点を整理すると効果的です。

• route 単位で移行するか、feature 単位で移行するか
• AngularJS router の state を Angular routing にどう対応づけるか
• hybrid mode 中に旧 route と新 route の責務をどう分離するか
• guards、resolvers、data fetching の移行タイミングをどうするか

もし複雑な nested states があるなら、prompt の中で明示したほうがよいです。

導入判断のための repository 読み取り手順

angular-migration install する価値があるかを短時間で見極めたいなら、次の順で確認すると効率的です。

1. SKILL.md の frontmatter で適用範囲を確認する
2. strategy 関連の見出しを見て、自分の移行モードがカバーされているか確認する
3. hybrid app の例を見て UpgradeModule が関係しそうか判断する
4. directive、DI、routing の変換セクションが自分の案件に合うか見る

内容は 1 ファイルに集約されているので、評価はかなり素早く行えます。

出力品質を上げる実践的なコツ

angular-migration スキルでより良い結果を得るには、次の点が有効です。

• おもちゃのコードではなく、代表的な AngularJS directive や service を貼る
• リリース制約とチーム体制を説明する
• 最終形だけでなく、移行の順序を聞く
• 2 つの移行パスのトレードオフ比較を依頼する
• コード変更を提案する前に、危険なレガシーパターンを洗い出すよう求める

こうすると、実際の repo レビューや移行計画にそのまま使える出力になりやすくなります。

angular-migration スキル FAQ

angular-migration は初心者にも向いている？

はい。ただし、完全にお任せの移行ツールというより、ガイド付きの計画支援として使うのが前提です。初心者でも、戦略の選択肢や概念対応を理解する助けになりますが、提案されたアーキテクチャやコード変換を検証するには、AngularJS と Angular の基礎理解は必要です。

angular-migration が向いていないのはどんな場合？

次のようなケースでは angular-migration は見送ってよいでしょう。

• すでに modern Angular に乗っている
• 必要なのが Angular のバージョン間アップグレードだけ
• 自動 code mod を求めている
• アプリが非常に小さく、段階移行を設計するより作り直したほうが明らかに安い

このスキルが対象にしているのは、AngularJS から Angular への移行そのものです。

angular-migration スキルがあれば Angular docs は読まなくていい？

いいえ。計画立案や翻訳作業、特に hybrid architecture や段階移行まわりの検討はかなり短縮できますが、正確な API、バージョン互換性、実装詳細を詰めるには Angular と ngUpgrade のドキュメントが引き続き必要です。

普通の LLM prompt より良い？

多くの場合は yes です。特に課題が単発のコード変換ではなく、移行全体の構造設計にあるなら有利です。angular-migration guide は agent に対して、戦略選択、hybrid 構成、component 変換、DI 更新、routing 移行というスコープの明確な思考枠組みを与えます。そのぶん、汎用的すぎる助言が減り、移行前提の出力になりやすくなります。

大規模な enterprise app でも angular-migration は使える？

はい。むしろ、もっとも相性が良いケースのひとつです。大規模アプリほど、このスキルが重視する incremental / hybrid アプローチの恩恵を受けやすくなります。実際に使うときは、release cadence、shared libraries、ownership boundary、risk tolerance といった組織的な現実も prompt に含めてください。

このスキルには automation や scripts が含まれる？

いいえ。repository 構成を見る限り、同梱スクリプト、参照資料、補助リソースはありません。価値の中心は実行可能ツールではなく、移行フレームワークと具体例にあります。

angular-migration スキルを改善する方法

目標だけでなく、アーキテクチャの事実を渡す

angular-migration の出力を最も手早く改善する方法は、実システムの形をそのまま渡すことです。

• module 数
• route map
• directive の種類
• shared services
• test coverage
• build 上の制約
• browser support 要件

何が強く結合しているのか分からなければ、このスキルも信頼できる順序づけはできません。

移行計画の出力フォーマットを明示する

次のような構成を指定すると、結果はさらに実務向きになります。

• 推奨戦略
• 残り 2 つを選ばない理由
• 最初の 3 つの migration slice
• hybrid app の要件
• DI と routing の変更点
• rollback リスク
• 各 slice の definition of done

この形にすると、エンジニアリング関係者とのレビューもしやすくなります。

よくある失敗: 戦略より先にコードを求める

ありがちなミスは、移行境界を決める前に component の書き換えを依頼してしまうことです。見栄えのよい出力は返ってきても、実際には使えないことがあります。まず angular-migration スキルで移行順序を決め、その後で、選んだ slice の中にあるコード変換を依頼するのが安全です。

よくある失敗: 制約を隠してしまう

“must release weekly” や “cannot freeze product work” のような制約を省くと、このスキルはきれいではあるが現実的でない提案を返すことがあります。より良い prompt では、次のような条件を表に出してください。

• delivery pressure
• team size
• 許容できる hybrid 期間
• 許される breaking changes
• test の成熟度

こうした情報は、推奨内容を実質的に変えます。

before / after の具体例で angular-migration usage を改善する

変換支援を依頼するときは、次の情報を添えると精度が上がります。

• 現在の AngularJS コード
• 目指す Angular のスタイルまたはバージョン
• ローカルの実装規約
• hybrid mode 中の互換性要件

これにより、教科書的な Angular コードを生成するのではなく、その repo に合った意図の保持がしやすくなります。

最初の出力のあとに必ず反復する

最初の回答は最終計画ではなく、移行の枠組みづくりとして扱うのが適切です。そのうえで、次のような follow-up で絞り込みます。

• “Revise for a 3-team setup with shared libraries.”
• “Change the recommendation if we cannot use ngUpgrade.”
• “Break the first feature slice into weekly milestones.”
• “Show the service migration risks before component migration.”

こうしたやり取りを経て、まずまずの計画が repo 固有の実行可能な計画に育っていきます。

出力が generic に感じるとき、最初に改善すべきこと

angular-migration skill の出力が広すぎたり抽象的すぎたりするときは、次の順で入力を具体化してください。

1. アプリ規模と release モデル
2. 選択済み、または有力視している migration strategy
3. 実在する feature slice を 1 つ
4. 実在する directive / service の例を 1 つ
5. routing と DI の制約

この順序で情報を足すと、一般論の migration advice から、現実のフロントエンド delivery に使えるガイダンスへ移りやすくなります。