Community编程与开发github.com

Angular 专家

执行 Angular 版本检测,并遵循官方指南和代码库约定,在写入 ANGULAR-EXPERT-IMPL.md 之前,使用信号、OnPush、控制流、Jest 单元测试和 80% 覆盖率门限,编写独立或 NgModule 代码。

Angular 专家 是什么?

这是一个专门用于 Angular 代码库的 AI 技能。它能自动检测项目中的 Angular 版本、TypeScript 版本、构建工具等关键技术栈信息,并严格遵循官方 angular.dev 指南和项目现有约定来生成、重构或审查代码。该技能的核心原则是“适配优先”,在提出任何更改前必须先完成堆栈检测和代码库规范审查,绝不会猜测版本或引入不支持的 API。它支持 Angular v20+(v2-v19 被视为不再支持),并且强制使用 Jest 进行单元测试,要求至少 80% 的代码覆盖率。该技能会生成一个详细的 `ANGULAR-EXPERT-IMPL.md` 报告,记录所有检测结果、设计决策、完整代码、测试和验证结果,供开发者追溯和审查。

兼容平台~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 代码的变更检测、信号、依赖注入、订阅管理、状态所有权、消毒或缺少的单元测试。
  • 使用 jest-preset-angular、TestBed 和 80% 覆盖率门限,为 Angular 项目添加 Jest 单元测试。

何时不使用

  • 没有 package.json 和 angular.json 描述符的非 Angular 项目。
  • 纯基础设施、仅后端服务或没有 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 或模板方法;使用信号、computed() 或预计算视图模型。
  14. 信任 Angular 消毒,并将值保持在模板和绑定中;未经显式验证和记录理由,绝不调用 bypassSecurityTrust... 方法。
  15. 构建语义化、可访问的模板,使用适当的元素、标签和 ARIA 属性;默认保持样式封装。
  16. 重用项目的文件夹布局、选择器前缀、命名、状态方法、UI 库和 DTO 映射,而不是引入并行的约定。
  17. 为每次行为更改的 success、validation 和 error 路径,编写与 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+,优先使用带有显式 track 的 @if 和 @for,并在项目已采用信号时使用 signal() 和 computed()。对于早期版本,保留 *ngIf、带 trackBy 的 *ngFor 和 RxJS 状态。基于 Zone 的项目保留 zone.js;仅在支持无 Zone 的地方添加 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:实现

应用最小完整的更改:

  • 保持组件轻量:绑定信号或可观察对象,通过委托给服务来处理事件,并使用语义模板进行渲染。
  • 保持严格的 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-preset-angular、TestBed 和项目现有 jest.config 和 setup-jest.ts 的 Jest;仅在缺少它们并确认了运行器选择后创建它们。
  • 为更改的行为的 success、validation 和 error 路径,编写隔离的单元测试。
  • 使用 TestBed imports 测试独立组件,使用模拟的 HttpClient 或模拟协作者测试服务,直接测试管道,并使用显式断言测试信号。
  • 对于 v20.2+ 上的无 Zone 应用程序,将 provideZonelessChangeDetection() 添加到 TestBed 提供者中;对于 v21+,依赖默认值。
  • 使用 jest.mock 模拟模块,使用 jest.spyOn 专注于协作者;断言可观察对象的结果并验证边界交互。
  • 通过 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 用于证据。在没有内容的部分使用 No changes.,并且永远不要留空白部分。

门 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 时代模式使用带 trackBy 的 *ngIf、*ngFor 和 RxJS;内置控制流不可用基于 Zone;除非被要求,否则不要建议升级
v17-v19 (不受支持)独立可用,v19 上默认v17 引入控制流,v18 稳定;信号可用;仅当项目已使用时才使用它们基于 Zone;v18-v19 上存在实验性的无 Zone 方案,但超出范围
v20.0-v20.1独立默认信号和控制流稳定无 Zone 实验性
v20.2+独立默认信号和控制流稳定通过 provideZonelessChangeDetection() 实现无 Zone 稳定
v21+独立默认信号、控制流和 toSignal() 基线无 Zone 是默认值;不要使用 provideZoneChangeDetection()
v22+独立和 OnPush 隐式不要显式设置 standalone: true不要显式设置 changeDetection: OnPush

检测器输出具有权威性。Angular v2-v19 不再受支持;记录该限制,而不是建议迁移。在未从矩阵和检测到的版本的官方指南确认支持之前,永远不要引入版本门控的 API。

证据规则

  • 记录测试、类型检查、构建和覆盖率的确切命令、退出状态和测量值。
  • 在解释决策时,使用 path:line 引用更改的文件。
  • 保持 ID、标记、严重性、框架名称和状态值为英文。
  • 将令牌、凭据和个人数据编辑为 [REDACTED]。
  • 仅报告配置键;切勿将原始配置值粘贴到工件中。
  • 不要声明 CI 结果...

相关技能