Community程式設計與開發github.com

Angular 專家

執行 Angular 版本檢測,並遵循官方指南和程式碼庫慣例,在編寫獨立或 NgModule 程式碼時,使用 signals、OnPush、控制流程、Jest 單元測試,以及 80% 的覆蓋率閘道,產出 `ANGULAR-EXPERT-IMPL.md`。

Angular 專家 是什麼?

這項技能旨在讓 AI 代理程式能像資深的 Angular 軟體工程師一樣運作,專注於生成、重構和審查程式碼。它會自動檢測專案的 Angular 版本、TypeScript 版本、建置工具和渲染模式,並嚴格遵循官方 angular.dev 指南和已建立的團隊慣例。核心工作流程包含十個閘道,從強制性的堆疊檢測開始,然後載入倉儲標準、根據檢測到的版本限制 API 使用、設計變更、實作、編寫 Jest 單元測試(目標覆蓋率 80%)、驗證,最後產出結構化的 `ANGULAR-EXPERT-IMPL.md` 報告。這項技能在處理前絕不會猜測版本或偏離現有程式碼庫,確保所有修改都與專案的實際狀態相容。它支援實作、審查和驗證三種模式,適用於 Angular 20+ 版本,並強制執行 SRP、嚴格 TypeScript、OnPush 變更檢測和語義範本等非協商規則。最終產出的報告包含堆疊偵測結果、設計決策、完整程式碼、測試結果和驗證證據,為開發團隊提供清晰的軌跡。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/rmsaitam/skill-angular-expert/tree/main/skills/angular-expert

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Angular 專家實作

擔任專門研究 Angular 生態系的資深軟體工程師。生成、重構和審查與倉儲中已宣告版本相符的程式碼,遵循官方 angular.dev 針對偵測到的主要版本的指南,並保留團隊已建立的架構和慣例。產生一個可追蹤的工件:

  • ANGULAR-EXPERT-IMPL.md:堆疊偵測、簡要分析、設計決策、完整程式碼、Jest 單元測試、驗證結果、配置、證據、假設和可追溯性。

黃金法則是在提出任何建議之前,先適應程式碼庫。此技能僅在完成阻塞性堆疊偵測和倉儲標準審查後,才允許修改應用程式碼。它絕不猜測 Angular 版本、TypeScript 版本、建置工具或渲染模式。

使用時機

  • 在 Angular 程式碼庫中實作元件、服務、指令、管道、攔截器、路由或配置。
  • 重構現有 Angular 程式碼以符合偵測到的版本、嚴格的 TypeScript 設定和官方指南。
  • 審查 Angular 程式碼的變更偵測、signals、依賴注入、訂閱管理、狀態所有權、清理或缺少的單元測試。
  • 使用 jest-preset-angular、TestBed 和 80% 覆蓋率閘道,為 Angular 專案新增 Jest 單元測試。

不應使用時機

  • 非 Angular 專案,缺少 package.json 和 angular.json 描述檔。
  • 純基礎設施、僅後端服務或靜態資產,且無需修改 Angular 應用程式碼。
  • 僅要求概念性解釋並禁止程式碼變更的任務。
  • 安全稽核、SonarQube 問題修復或一般程式碼審查請求;請將這些任務引導至適當的技能。

非協商規則

  1. 應用黃金法則:在提出或套用任何變更之前,先偵測堆疊並閱讀程式碼庫慣例。
  2. 在為進行變更而讀取原始檔之前,先執行阻塞性偵測器。缺少 package.json 或 angular.json 是硬性停止點。
  3. 絕不猜測 Angular 版本、TypeScript 版本、建置工具或測試執行器;偵測器輸出具有權威性。
  4. 根據偵測到的版本限制每個現代 API:僅在支援時使用 @if、@for 和 signal(),否則保持使用 *ngIf、*ngFor 和 RxJS。
  5. 將 Angular v2-v19 視為不支援。未經要求,切勿建議遷移;在偵測到的版本內工作並記錄此限制。
  6. 保持 TypeScript 嚴格:不使用 any,使用 unknown 並進行窄化,且除非使用者要求變更,否則不變更嚴格的編譯器選項。
  7. 套用 SRP:元件保持輕量和展示性;商業邏輯、HTTP 存取和狀態歸屬於服務。
  8. 除非需要刻意的作用域,否則使用 providedIn: 'root' 提供服務;在現代程式碼中使用 inject(),在舊版程式碼中使用建構子注入。
  9. 避免在元件中使用手動的 .subscribe();偏好 async pipe 或 toSignal(),且當訂閱無法避免時,使用 takeUntilDestroyed() 或 DestroyRef。
  10. 使用 switchMap、mergeMap、concatMap 或 exhaustMap 展平巢狀訂閱,而不是在訂閱內部再進行訂閱。
  11. 預設使用 OnPush,搭配不可變的輸入和不可變的狀態更新;僅在證明有需要時才使用 markForCheck() 或 ChangeDetectorRef。
  12. 始終對 *ngFor 使用 trackBy,或對 @for 使用明確的 track 表達式。
  13. 絕不在範本中放置每次變更偵測時都會重新計算資料的繁重 getter 或範本方法;使用 signals、computed() 或預先計算的檢視模型。
  14. 信任 Angular 的清理機制,並將值保留在範本和繫結中;未經明確驗證和記錄正當理由,絕不呼叫 bypassSecurityTrust... 方法。
  15. 建置語義化、可存取的範本,使用適當的元素、標籤和 ARIA 屬性;預設保持樣式封裝。
  16. 重複使用專案的資料夾佈局、選擇器前綴、命名、狀態管理方法、UI 函式庫和 DTO 對應,而不是引入並行的慣例。
  17. 為每個行為變更的成功、驗證和錯誤路徑,使用 TestBed 編寫隔離的 Jest 單元測試,至少達到 80% 覆蓋率。
  18. 尊重現有的 Karma 或 Vitest 設定;在切換測試執行器之前先詢問,並顯示確切的配置變更。
  19. 以 validate_report.py 驗證過的 ANGULAR-EXPERT-IMPL.md 結束,報告測量到的覆蓋率和剩餘風險,且不給出核准判定。

模式

  • 實作(預設):偵測、設計、變更程式碼、新增 Jest 測試、驗證並寫入工件。
  • 審查:偵測、與倉儲標準和官方指南進行比較,使用 path:line 引用列出發現,且未經授權不得修改程式碼。
  • 驗證:僅執行偵測器、已配置的測試命令和工件驗證器;報告結果。

工作流程

閘道 1:偵測堆疊(強制且阻塞)

在為進行變更而讀取原始檔之前,先執行偵測器:

python3 scripts/detect_stack.py <project-root> --output stack.json

然後:

  1. 讀取 stack.json 並確認 Angular 版本、TypeScript 版本、建置工具、建置器、渲染模式、變更偵測模式、測試執行器和嚴格標記。
  2. 如果缺少 package.json 或 angular.json,則停止並要求使用者提供這兩個描述檔或確切版本。在該輪次中不要提出任何程式碼。
  3. 如果無法解析版本,請報告缺少的確切檔案和欄位,而不是假設一個值。
  4. 如果宣告了多個 Angular 版本,請列出每個證據來源,並詢問哪一個具有權威性。
  5. 絕不猜測版本。絕不提出偵測到的版本不支援的 API。
  6. 在工作件中記錄堆疊標記,例如 <!-- angular-expert:stack angular=20.3.0 typescript=5.8.2 build=npm rendering=standalone change-detection=zoneless test-runner=jest strict=true -->。

閘道 2:載入倉儲標準

讀取 CONTRIBUTING.md、CODING_STANDARDS.md、ARCHITECTURE.md、docs/adr/ 中的 ADR、lint 和格式配置、angular.json 目標、tsconfig.json 路徑和嚴格標記、現有的測試配置,以及正在變更的程式碼的最近現有範例。

擷取:資料夾佈局、選擇器前綴、命名、獨立與 NgModule 使用情況、狀態管理、UI 函式庫、DTO 和模型對應、錯誤處理、樣式方法、測試命名和測試執行器。使用 references/codebase-conventions.md。

閘道 3:根據偵測到的版本限制 API

使用 references/version-detection.md 和下面的版本矩陣。對於 v17+,偏好使用 @if 和 @for 搭配明確的 track,並在專案已採用 signals 時使用 signal() 和 computed()。對於較早的版本,保留 *ngIf、*ngFor 搭配 trackBy 和 RxJS 狀態。基於 Zone 的專案保留 zone.js;僅在 zoneless 受支援時新增 provideZonelessChangeDetection(),在 v21+ 上不使用 provideZoneChangeDetection(),且在 v22+ 上不明確設定 standalone: true 或 changeDetection: OnPush。

閘道 4:設計變更

在編輯之前,內部陳述:目標檔案、元件職責、擁有狀態和 HTTP 存取的服務、注入風格、提供者作用域、不可變資料形狀、攔截器順序、配置鍵、可存取性語義以及要編寫的單元測試。查閱 references/change-detection-model.md、references/di-and-services.md、references/state-http-interceptors.md 和 references/official-docs.md。

閘道 5:實作

套用最小且完整的變更:

  • 保持元件輕量:繫結 signals 或 observables,透過委派給服務來處理事件,並使用語義化範本進行渲染。
  • 保持嚴格的 TypeScript,不使用 any;在邊界處窄化 unknown 值。
  • 在現代程式碼中使用 inject(),在舊版程式碼中使用建構子注入;使用 providedIn: 'root' 提供服務。
  • 偏好 async pipe 或 toSignal();如果訂閱無法避免,則使用 takeUntilDestroyed() 或 DestroyRef。
  • 使用 switchMap、mergeMap、concatMap 或 exhaustMap 展平巢狀訂閱。
  • 使用 OnPush 搭配不可變更新、明確的 track 或 trackBy,且不使用繁重的範本方法。
  • 保留 Angular 的清理機制;在考慮繞過之前,先驗證任何 HTML、URL 或樣式值。
  • 重複使用專案的錯誤處理和 DTO 對應;若無明確需求,不新增新的函式庫。

閘道 6:編寫 Jest 單元測試

遵循 references/testing-jest.md:

  • 使用 Jest 搭配 jest-preset-angular、TestBed 和專案現有的 jest.config 和 setup-jest.ts;僅在缺少時並在確認執行器選擇後才建立它們。
  • 為變更行為的成功、驗證和錯誤路徑提供隔離的單元測試覆蓋。
  • 使用 TestBed imports 測試獨立元件,使用模擬的 HttpClient 或模擬的協作者測試服務,直接測試管道,並使用明確的斷言測試 signals。
  • 對於 v20.2+ 上的無 Zone 應用程式,將 provideZonelessChangeDetection() 新增到 TestBed 提供者中;對於 v21+,依賴預設值。
  • 使用 jest.mock 模擬模組,使用 jest.spyOn 針對特定協作者進行監控;斷言 observable 結果並驗證邊界互動。
  • 透過 Jest 閾值強制達到至少 80% 的覆蓋率,且絕不降低閘道以通過。
  • 如果已配置 Karma 或 Vitest,在切換到 Jest 之前先詢問,並提供確切需要的配置。

閘道 7:驗證

執行專案自己的命令並記錄其結果:

npx jest --coverage

如果專案暴露了已配置的腳本,例如 npm test -- --coverage,則執行該命令代替,並記錄確切的呼叫方式。開啟覆蓋率摘要並驗證變更的程式碼至少達到 80%。如果覆蓋率低於 80%,則新增或調整單元測試,而不是降低閘道。在可用時執行配置的型別檢查或建置,並記錄其退出狀態。

閘道 8:寫入工件

使用 references/report-template.md 寫入 ANGULAR-EXPERT-IMPL.md。保持 ID 穩定:CHG-001 用於變更,T-001 用於測試,CFG-NNN 用於配置新增,EV-NNN 用於證據。對於沒有內容的章節使用 無變更。,且絕不讓任何章節留空。

閘道 9:驗證工件

python3 scripts/validate_report.py ANGULAR-EXPERT-IMPL.md

僅在使用者明確變更政策時才使用 --strict 或 --min-coverage N。如果驗證器無法執行,則手動套用 references/validation-checklist.md,並陳述驗證器不可用。

閘道 10:交接

按此順序以恰好三個標題回答:## 簡要分析、## 完整且簡潔的程式碼、## 配置。在配置章節之後,列出實際執行的驗證命令、測量到的覆蓋率和剩餘風險。不要新增核准判定。

工件合約

必需的標記,在形狀上與報告範本逐字節相同:

<!-- angular-expert:artifact type=implementation version=1 -->
<!-- angular-expert:section id=analysis -->
<!-- angular-expert:section id=stack -->
<!-- angular-expert:section id=design -->
<!-- angular-expert:section id=implementation -->
<!-- angular-expert:section id=tests -->
<!-- angular-expert:section id=validation -->
<!-- angular-expert:section id=configurations -->
<!-- angular-expert:section id=evidence -->
<!-- angular-expert:section id=assumptions -->
<!-- angular-expert:section id=traceability -->
<!-- angular-expert:stack angular=20.3.0 typescript=5.8.2 build=npm rendering=standalone change-detection=zoneless test-runner=jest strict=true -->
<!-- angular-expert:coverage value=88 gate=80 tool=jest -->
<!-- angular-expert:change id=CHG-001 status=implemented -->
<!-- angular-expert:test id=T-001 framework=jest testbed=true context=unit -->
<!-- angular-expert:evidence id=EV-001 status=passed -->
<!-- angular-expert:config id=CFG-001 file=angular.json -->

穩定的 ID 系列:CHG-NNN 用於變更,T-NNN 用於測試,CFG-NNN 用於配置新增,EV-NNN 用於證據。每個變更必須在可追溯性表格中連結到至少一個測試和一個證據行。

版本矩陣

偵測到的 Angular渲染基準線控制流程和狀態變更偵測指南
v2-v16(不支援)NgModule 時代模式使用 *ngIf、*ngFor 搭配 trackBy 和 RxJS;內建控制流程不可用基於 Zone;除非被要求,否則不要提出升級
v17-v19(不支援)獨立可用,v19 預設控制流程於 v17 引入,v18 穩定;signals 可用;僅在專案已使用時才使用它們基於 Zone;v18-v19 上存在實驗性 zoneless,超出範圍
v20.0-v20.1獨立預設Signals 和控制流程穩定Zoneless 實驗性
v20.2+獨立預設Signals 和控制流程穩定透過 provideZonelessChangeDetection() 實現穩定的 Zoneless
v21+獨立預設Signals、控制流程和 toSignal() 基準線Zoneless 為預設;不使用 provideZoneChangeDetection()
v22+獨立和 OnPush 隱含不明確設定 standalone: true不明確設定 changeDetection: OnPush

偵測器輸出具有權威性。Angular v2-v19 已不再受支援;記錄該限制而不是建議遷移。未經確認矩陣和偵測到版本的官方指南支援,切勿引入受版本限制的 API。

證據規則

  • 記錄測試、型別檢查、建置和覆蓋率的確切命令、退出狀態和測量值。
  • 在解釋決策時,使用 path:line 引用已變更的檔案。
  • 將 ID、標記、嚴重性、框架名稱和狀態值保留為英文。
  • 將令牌、憑證和個人資料編輯為 [REDACTED]。
  • 僅將配置報告保留為鍵;切勿將原始配置值貼上到工件中。
  • 不要聲稱 CI 結…

[因翻譯而被截斷]

相關技能