angular-migration

angular-migration 技能總覽

angular-migration 實際能幫你做到什麼

angular-migration 技能是為了要把既有 AngularJS 1.x 程式碼庫遷移到現代 Angular 的團隊而設計，特別適合那種「整個重寫風險太高」的情境。它的核心價值不只是「轉語法」，而是幫你選對遷移路線、在需要時規劃 hybrid app 架構，並處理最棘手的銜接面：從 directives 轉成 components、把 AngularJS services 對應到 Angular DI，以及按 route 逐步替換。

哪些人適合使用 angular-migration 技能

這個 angular-migration 技能特別適合已經有真實 AngularJS 專案、需要可執行遷移路徑的 frontend engineers、tech leads 與 migration owners。以下情況尤其有幫助：

• 要在 big-bang、hybrid 或 vertical-slice 遷移之間做判斷
• 遷移期間仍需要持續交付版本
• 想把舊有 directives/controllers 重構成 Angular components 與 services
• 希望以低風險方式分階段處理 routing 與 dependency injection 變更

最適合的遷移情境

當你的 app 有明顯的 legacy 包袱時，就很適合使用 angular-migration：

• 大型 AngularJS codebase，且產品仍持續發布
• 有共享 services 與 directives，無法一次全部替換
• 過渡期需要 AngularJS + Angular 的 hybrid runtime
• 需要以功能層級規劃遷移，而不是只看抽象的 framework 建議

如果你只是要做一個全新的 Angular app，這個技能多半會太重。

angular-migration 與一般遷移 prompt 的差異

一般 prompt 往往會直接跳進程式碼轉換。angular-migration 更有價值的地方，在於它能處理真正困難的部分：安排遷移順序、建立 hybrid mode、把舊 AngularJS 概念穩定映射到 Angular 對應做法，同時不打亂既有交付節奏。對大多數團隊來說，這才是真正卡住採用的關鍵。

安裝前你應該先知道什麼

這個技能的 repository 結構很精簡：主要內容都在 SKILL.md，沒有額外 scripts、references 或 helper assets。好處是很快就能看完；但也代表你拿到的是指引模式與範例，而不是自動化工具。若你要的是決策支援與遷移結構，它值得安裝；如果你期待的是可直接執行的 codemod，就不符合預期。

如何使用 angular-migration 技能

angular-migration 技能的安裝方式

用你平常的 Skills workflow，把 angular-migration 安裝到 agent environment 即可。常見做法如下：

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

因為這個技能本質上就是單一 SKILL.md 檔案，所以安裝的重點不是拉進可執行工具，而是讓這份指引能在你的 agent workflow 裡被直接呼叫。

先讀這個檔案

請先看：

• SKILL.md

這個檔案就是可直接使用的核心內容：包含什麼時候該用這個技能、遷移策略、hybrid 設定方式，以及程式碼範例。由於這裡沒有其他 rules 或 resource folders，要在使用前完整讀一遍其實很實際，也很值得。

這個技能需要你提供哪些輸入

angular-migration 在你提供具體 repo 現況時，效果會比只問泛用規劃好很多。建議提供：

• 目前 AngularJS 版本與 app 規模
• 遷移期間是否必須持續發布
• 正在使用的 routing library
• 主要 directive patterns
• DI/service patterns
• build tooling 與 test 現況
• 是否可接受 hybrid runtime
• 目標 Angular 版本與時程

如果缺少這些資訊，輸出通常只會停留在「大型 app 建議 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 使用流程

一個好的 angular-migration usage 模式通常是：

1. 先判斷 app 類型：適合小型重寫，還是適合 hybrid
2. 選定一種策略：big bang、incremental hybrid，或 vertical slice
3. 找出遷移單位：routes、features、directives、services
4. 定義 AngularJS 與 Angular 之間需要哪些互通能力
5. 先轉換一個範圍小的功能
6. 驗證 bootstrapping、DI 與 routing 的銜接面
7. 用穩定的 migration checklist 重複推進

這能避免一個很常見的錯誤：還沒定策略，就太早進入低階重寫細節。

策略選擇：怎麼選才合理

這個 repository 主要聚焦三種策略：

• Big Bang：較適合小型 app，或真的有條件平行重寫的情況
• Incremental / Hybrid：較適合大型 app，且遷移期間仍需持續交付
• Vertical Slice：較適合功能邊界清楚、可端到端替換的系統

對大多數真實的 legacy app 來說，hybrid 或 vertical-slice 通常才是務實選項。只有在營運風險明顯低於長期雙技術棧複雜度時，才應該選 big bang。

用 angular-migration 規劃 hybrid app

angular-migration for Frontend Development 最有價值的部分之一，就是 hybrid 規劃。如果你要用 @angular/upgrade/static，可以請這個技能協助你思考：

• bootstrap 順序
• AngularJS / Angular 共存邊界
• downgraded / upgraded components 與 services
• 哪些共享依賴應該先搬
• 如何在共存期間避免 feature teams 被卡住

這正是一般 prompt 很容易變得模糊，甚至給出不安全建議的地方。

Directive、component 與 DI 轉換的 prompt 寫法

與其要求整個 app 一次轉換，不如讓技能處理更聚焦的轉換問題。以下 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.”

這種較窄、較明確的請求，通常會比「全部幫我轉」產出更可用的結果。

Routing 遷移指引

很多遷移計畫最後失敗，都是卡在 routing。你可以用這個技能來判斷：

• 應該逐 route 遷移，還是逐 feature 遷移
• AngularJS router state 要怎麼對應到 Angular routing
• hybrid mode 期間，如何切分新舊 routes 的 ownership
• guards、resolvers 與 data fetching patterns 應該何時搬遷

如果你的 app 有複雜的 nested states，記得在 prompt 裡明講。

快速評估時的 repository 閱讀路徑

如果你正在判斷 angular-migration install 是否值得，建議依序查看：

1. SKILL.md frontmatter，確認它的實際範圍
2. strategy 相關標題，確認是否涵蓋你的遷移模式
3. hybrid app 範例，判斷是否與 UpgradeModule 相關
4. conversion 章節，確認 directive、DI 與 routing 是否貼合你的需求

因為內容集中在單一檔案裡，所以這個技能其實很容易快速評估。

能明顯提升輸出品質的實用技巧

想讓 angular-migration 技能給出更好的結果，建議你：

• 貼上具代表性的 AngularJS directive 或 service，而不是玩具範例
• 說清楚發布限制與團隊容量
• 要求它規劃 sequencing，而不只是描述最終架構
• 請它比較兩條遷移路徑的 tradeoffs
• 要求模型在提程式碼修改前，先標出高風險 legacy patterns

這樣得到的內容，才更接近你在真實 repo review 裡能直接採用的建議。

angular-migration 技能 FAQ

angular-migration 適合初學者嗎？

適合，但比較偏向「有引導的規劃」，不是放著讓它自動幫你遷移。初學者可以用它來理解策略選項與概念映射，但你仍需要具備基本的 AngularJS 與 Angular 判讀能力，才能驗證它建議的架構與程式碼轉換是否合理。

什麼情況下不該用 angular-migration 技能？

以下情況可以跳過 angular-migration：

• 你的專案已經是現代 Angular
• 你只需要 Angular 版本升級
• 你要的是自動化 code mods
• 你的 app 小到明顯重建比階段式遷移規劃更便宜

這個技能明確聚焦在 AngularJS-to-Angular transition。

angular-migration 技能能取代閱讀 Angular 文件嗎？

不能。它能幫你大幅縮短規劃與轉譯工作，尤其是在 hybrid architecture 與 phased migration 這兩塊。不過在精確 API、版本相容性與實作細節上，你仍然需要查 Angular 與 ngUpgrade 官方文件。

這會比一般 LLM prompt 更好嗎？

通常會，前提是你的問題核心在於遷移結構，而不是單次程式碼翻譯。angular-migration guide 提供 agent 一個有範圍的思考模型：策略選擇、hybrid 設定、component 轉換、DI 更新與 routing 遷移。這能降低泛泛而談的建議，讓輸出更貼近真實遷移工作。

我可以用 angular-migration 處理大型企業級 app 嗎？

可以，而且這正是它最強的適用情境之一。大型 app 最能受益於這個技能對 incremental 與 hybrid 路線的重視。不過你的 prompt 一定要包含組織層面的現實條件，例如 release cadence、shared libraries、ownership boundaries 與 risk tolerance。

這個技能有附自動化工具或 scripts 嗎？

沒有。從 repository 結構來看，裡面沒有打包 scripts、references 或 helper resources。它的價值在於遷移框架與範例，而不是可直接執行的 tooling。

如何提升 angular-migration 技能的使用效果

給 angular-migration 的是架構事實，不只是目標

想讓 angular-migration 輸出更好，最快的方法就是提供真實系統形狀：

• module 數量
• route map
• directive 類型
• shared services
• test coverage
• build 限制
• browser support requirements

只有知道哪些地方高度耦合，這個技能才有辦法提出可信的遷移順序建議。

要求明確的遷移計畫格式

如果你直接指定輸出結構，結果通常會更好，例如：

• recommended strategy
• why not the other two
• first 3 migration slices
• hybrid app requirements
• DI and routing changes
• rollback risks
• definition of done per slice

這樣的答案也更方便拿去跟工程利害關係人一起檢視。

常見失敗模式：策略還沒定，就先要程式碼

很常見的錯誤是，在遷移邊界還沒決定之前，就先要求重寫 components。這類輸出看起來可能很漂亮，但實際上未必能用。更好的做法是：先用 angular-migration 技能決定遷移順序，再針對已選定的 slice 要求程式碼轉換。

常見失敗模式：把限制條件藏起來

如果你沒說清楚像是「每週都必須發版」或「不能凍結產品開發」，這個技能就可能提出較乾淨、但不切實際的方案。更好的 prompt 應該主動揭露：

• 交付壓力
• 團隊規模
• 可接受的 hybrid 持續時間
• 可允許的 breaking changes
• 測試成熟度

這些資訊會實質改變建議內容。

用前後對照範例改善 angular-migration 使用效果

如果你要它幫忙做轉換，建議一併提供：

• 目前的 AngularJS 程式碼
• 期望的 Angular 風格或目標版本
• 團隊本地慣例
• hybrid mode 期間的相容性要求

這樣有助於技能保留原本意圖，而不是產出教科書式、卻不適合你 repo 的 Angular 程式碼。

第一次輸出後要再迭代

把第一版答案當成遷移 framing，而不是最終計畫。接著再用這些追問去收斂：

• “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 的方案。

如果輸出太泛，最先該補強什麼

如果你覺得 angular-migration skill 的回應太空泛，請依照這個順序補資訊：

1. app 規模與 release model
2. 已選定或懷疑適合的 migration strategy
3. 一個真實的 feature slice
4. 一個真實的 directive/service 範例
5. routing 與 DI 限制

這個順序能讓技能拿到足夠上下文，從一般性的遷移建議，進一步變成可落地的 frontend 交付指引。