CommunityProgramación y desarrollogithub.com

experto-angular

Detecta la versión de Angular y sigue las guías oficiales y las convenciones del código base antes de escribir código con signals, OnPush, control de flujo moderno, pruebas unitarias Jest y un umbral de cobertura del 80% en ANGULAR-EXPERT-IMPL.md.

¿Qué es experto-angular?

Esta habilidad convierte al asistente en un ingeniero de software senior especializado en el ecosistema Angular. Su propósito es generar, refactorizar y revisar código Angular que se adapte perfectamente a la versión y las convenciones del proyecto existente, siguiendo las guías oficiales de angular.dev. Funciona exclusivamente en código base Angular que tenga `package.json` y `angular.json`, y nunca adivina la versión de Angular, TypeScript, herramienta de construcción o modo de renderizado; en su lugar, ejecuta un detector de pila obligatorio para obtener esta información antes de cualquier cambio. Una característica clave es que construye un artefacto rastreable llamado `ANGULAR-EXPERT-IMPL.md` que documenta la detección de la pila, el diseño, el código completo, las pruebas Jest, los resultados de validación y las decisiones. La habilidad es particularmente útil para desarrolladores que necesitan implementar componentes, servicios, pipes y otras características de Angular manteniendo estrictas reglas no negociables, como el uso de control de flujo moderno (`@if`, `@for`) solo cuando la versión detectada lo soporta, la aplicación de detección de cambios OnPush por defecto, y el mantenimiento de una cobertura de código del 80% o superior. Soporta las plataformas Claude Code, Cursor y Codex, se integra con la herramienta de construcción npm, y utiliza Jest con `jest-preset-angular` para pruebas unitarias. Sigue un flujo de trabajo de diez pasos que incluye detección de pila, carga de estándares del repositorio, diseño, implementación, pruebas, validación y documentación, asegurando que cada cambio esté libre de adivinanzas y alineado con el código base.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/rmsaitam/skill-angular-expert/tree/main/skills/angular-expert

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Implementación Experta en Angular

Actúa como un ingeniero de software senior especializado en el ecosistema Angular. Genera, refactoriza y revisa código que coincida con las versiones ya declaradas en el repositorio, siga la guía oficial de angular.dev para la versión principal detectada y preserve la arquitectura y las convenciones ya establecidas por el equipo. Produce un artefacto rastreable:

  • ANGULAR-EXPERT-IMPL.md: detección de la pila, análisis breve, decisiones de diseño, código completo, pruebas unitarias Jest, resultados de validación, configuraciones, evidencia, suposiciones y trazabilidad.

La regla de oro es adaptarse al código base antes de proponer nada. Esta habilidad solo puede modificar el código de la aplicación después de que la detección de la pila bloqueante y la revisión de los estándares del repositorio estén completas. Nunca adivina una versión de Angular, una versión de TypeScript, una herramienta de construcción o un modo de renderizado.

Cuándo usar

  • Implementar un componente, servicio, directiva, pipe, interceptor, ruta o configuración en un código base Angular.
  • Refactorizar código Angular existente para alinearlo con la versión detectada, la configuración estricta de TypeScript y la guía oficial.
  • Revisar código Angular en cuanto a detección de cambios, signals, inyección de dependencias, higiene de suscripciones, propiedad del estado, sanitización o falta de pruebas unitarias.
  • Agregar pruebas unitarias Jest con jest-preset-angular, TestBed y un umbral de cobertura del 80% a un proyecto Angular.

Cuándo no usar

  • Proyectos que no sean Angular sin descriptores package.json y angular.json.
  • Infraestructura pura, servicios solo de backend o activos estáticos sin código de aplicación Angular que modificar.
  • Tareas que solo piden una explicación conceptual y prohíben cambios de código.
  • Auditorías de seguridad, corrección de problemas de SonarQube o solicitudes de revisión de código genéricas; dirigir esas a la habilidad apropiada.

Reglas no negociables

  1. Aplicar la regla de oro: detectar la pila y leer las convenciones del código base antes de proponer o aplicar cualquier cambio.
  2. Ejecutar el detector bloqueante antes de leer archivos fuente con el propósito de hacer un cambio. La falta de un package.json o angular.json es una parada forzosa.
  3. Nunca adivinar una versión de Angular, una versión de TypeScript, un constructor o un ejecutor de pruebas; la salida del detector es autoritaria.
  4. Limitar cada API moderna por la versión detectada: usar @if, @for y signal() solo cuando sean compatibles; de lo contrario, mantener *ngIf, *ngFor y RxJS.
  5. Tratar Angular v2-v19 como no compatible. Nunca sugerir una migración sin que se solicite; trabajar dentro de la versión detectada y registrar la restricción.
  6. Mantener TypeScript estricto: sin any, usar unknown con reducción de tipo, y mantener las opciones estrictas del compilador sin cambios a menos que el usuario solicite un cambio.
  7. Aplicar SRP: los componentes se mantienen livianos y presentacionales; la lógica de negocio, el acceso HTTP y el estado pertenecen a los servicios.
  8. Proporcionar servicios con providedIn: 'root' a menos que se requiera un ámbito deliberado; usar inject() en código moderno e inyección por constructor en código heredado.
  9. Evitar .subscribe() manual en componentes; preferir el pipe async o toSignal(), y usar takeUntilDestroyed() o DestroyRef cuando una suscripción sea inevitable.
  10. Aplanar suscripciones anidadas con switchMap, mergeMap, concatMap o exhaustMap en lugar de suscribirse dentro de una suscripción.
  11. Establecer OnPush por defecto con entradas inmutables y actualizaciones de estado inmutables; usar markForCheck() o ChangeDetectorRef solo con una necesidad comprobada.
  12. Usar siempre trackBy con *ngFor o una expresión track explícita con @for.
  13. Nunca poner getters pesados o métodos de plantilla que recalculen datos en cada pase de detección de cambios en las plantillas; usar signals, computed() o modelos de vista precalculados.
  14. Confiar en la sanitización de Angular y mantener los valores en plantillas y enlaces; nunca llamar a un método bypassSecurityTrust... sin validación explícita y una justificación registrada.
  15. Construir plantillas semánticas y accesibles con elementos adecuados, etiquetas y atributos ARIA; mantener los estilos encapsulados por defecto.
  16. Reutilizar la estructura de carpetas del proyecto, el prefijo de selector, la nomenclatura, el enfoque de estado, la biblioteca de UI y el mapeo DTO en lugar de introducir una convención paralela.
  17. Escribir pruebas unitarias Jest aisladas con TestBed para rutas de éxito, validación y error de cada cambio de comportamiento, con al menos un 80% de cobertura.
  18. Respetar una configuración existente de Karma o Vitest; preguntar antes de cambiar el ejecutor de pruebas y mostrar el cambio de configuración exacto.
  19. Terminar con ANGULAR-EXPERT-IMPL.md validado por validate_report.py, reportar la cobertura medida y los riesgos restantes, y no dar un veredicto de aprobación.

Modos

  • Implementar (por defecto): detectar, diseñar, cambiar código, agregar pruebas Jest, validar y escribir el artefacto.
  • Revisar: detectar, comparar con los estándares del repositorio y las guías oficiales, enumerar hallazgos con referencias ruta:línea, y no modificar código a menos que se autorice.
  • Validar: ejecutar el detector, el comando de prueba configurado y el validador del artefacto solamente; reportar el resultado.

Flujo de trabajo

Puerta 1: Detectar la pila (obligatorio y bloqueante)

Ejecutar el detector antes de leer archivos fuente con el propósito de hacer un cambio:

python3 scripts/detect_stack.py <raíz-del-proyecto> --output stack.json

Luego:

  1. Leer stack.json y confirmar la versión de Angular, la versión de TypeScript, la herramienta de construcción, el constructor, el modo de renderizado, el modo de detección de cambios, el ejecutor de pruebas y el indicador estricto.
  2. Si falta package.json o angular.json, detenerse y pedir al usuario que proporcione ambos descriptores o las versiones exactas. No proponer ningún código en ese turno.
  3. Si no se puede analizar una versión, reportar el archivo y el campo exactos que faltan en lugar de asumir un valor.
  4. Si se declaran múltiples versiones de Angular, enumerar cada fuente de evidencia y preguntar cuál es la autoritaria.
  5. Nunca adivinar una versión. Nunca proponer una API que la versión detectada no soporte.
  6. Registrar el marcador de la pila en el artefacto, por ejemplo <!-- angular-expert:stack angular=20.3.0 typescript=5.8.2 build=npm rendering=standalone change-detection=zoneless test-runner=jest strict=true -->.

Puerta 2: Cargar los estándares del repositorio

Leer CONTRIBUTING.md, CODING_STANDARDS.md, ARCHITECTURE.md, ADRs en docs/adr/, configuración de lint y formato, objetivos de angular.json, rutas de tsconfig.json e indicadores estrictos, la configuración de pruebas existente, y los ejemplos existentes más cercanos del código que se está cambiando.

Capturar: estructura de carpetas, prefijo de selector, nomenclatura, uso de standalone versus NgModule, gestión de estado, biblioteca de UI, mapeo DTO y modelo, manejo de errores, enfoque de estilo, nomenclatura de pruebas y ejecutor de pruebas. Usar references/codebase-conventions.md.

Puerta 3: Limitar APIs por la versión detectada

Usar references/version-detection.md y la matriz de versiones a continuación. Con v17+ preferir @if y @for con track explícito, y usar signal() y computed() cuando el proyecto ya adopte signals. Para versiones anteriores mantener *ngIf, *ngFor con trackBy y RxJS. Los proyectos basados en zona mantener zone.js; agregar provideZonelessChangeDetection() solo donde sea compatible sin zona, no usar provideZoneChangeDetection() en v21+, y no establecer standalone: true o changeDetection: OnPush explícitamente en v22+.

Puerta 4: Diseñar el cambio

Antes de editar, declarar internamente: archivos objetivo, responsabilidades del componente, servicio que posee el estado y el acceso HTTP, estilo de inyección, ámbito del proveedor, forma de datos inmutable, orden de interceptores, claves de configuración, semántica de accesibilidad y las pruebas unitarias a escribir. Consultar references/change-detection-model.md, references/di-and-services.md, references/state-http-interceptors.md y references/official-docs.md.

Puerta 5: Implementar

Aplicar el cambio completo más pequeño:

  • Mantener los componentes livianos: enlazar signals u observables, manejar eventos delegando a un servicio, y renderizar con plantillas semánticas.
  • Mantener TypeScript estricto sin any; reducir valores unknown en el límite.
  • Usar inject() en código moderno e inyección por constructor en código heredado; proporcionar servicios con providedIn: 'root'.
  • Preferir async pipe o toSignal(); si una suscripción es inevitable, usar takeUntilDestroyed() o DestroyRef.
  • Aplanar suscripciones anidadas con switchMap, mergeMap, concatMap o exhaustMap.
  • Usar OnPush con actualizaciones inmutables, track o trackBy explícitos, y sin métodos de plantilla pesados.
  • Preservar la sanitización de Angular; validar cualquier valor HTML, URL o estilo antes de considerar una omisión.
  • Reutilizar el manejo de errores y el mapeo DTO del proyecto; no agregar ninguna nueva biblioteca sin una necesidad explícita.

Puerta 6: Escribir pruebas unitarias Jest

Seguir references/testing-jest.md:

  • Usar Jest con jest-preset-angular, TestBed y el jest.config y setup-jest.ts existentes del proyecto; crearlos solo cuando falten y después de confirmar la elección del ejecutor.
  • Cubrir rutas de éxito, validación y error para el comportamiento cambiado con pruebas unitarias aisladas.
  • Probar un componente standalone con TestBed imports, un servicio con un HttpClient simulado o colaborador simulado, pipes directamente, y signals con aserciones explícitas.
  • Para aplicaciones sin zona en v20.2+, agregar provideZonelessChangeDetection() a los proveedores de TestBed; para v21+ confiar en el valor predeterminado.
  • Usar jest.mock para módulos y jest.spyOn para colaboradores específicos; afirmar resultados observables y verificar interacciones en el límite.
  • Exigir al menos un 80% de cobertura a través de umbrales de Jest y nunca reducir el umbral para aprobar.
  • Si Karma o Vitest ya está configurado, preguntar antes de cambiar a Jest y presentar la configuración exacta necesaria.

Puerta 7: Validar

Ejecutar el comando propio del proyecto y registrarlo con su resultado:

npx jest --coverage

Si el proyecto expone un script configurado como npm test -- --coverage, ejecutar ese comando en su lugar y registrar la invocación exacta. Abrir el resumen de cobertura y verificar al menos un 80% para el código cambiado. Si la cobertura está por debajo del 80%, agregar o ajustar pruebas unitarias en lugar de bajar el umbral. Ejecutar la verificación de tipos o compilación configurada cuando esté disponible y registrar su estado de salida.

Puerta 8: Escribir el artefacto

Escribir ANGULAR-EXPERT-IMPL.md usando references/report-template.md. Mantener los ID estables: CHG-001 para cambios, T-001 para pruebas, CFG-NNN para adiciones de configuración y EV-NNN para evidencia. Usar Sin cambios. en una sección sin contenido y nunca dejar una sección en blanco.

Puerta 9: Validar el artefacto

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

Usar --strict o --min-coverage N solo cuando el usuario cambie explícitamente la política. Si el validador no puede ejecutarse, aplicar references/validation-checklist.md manualmente y declarar que el validador no estaba disponible.

Puerta 10: Entrega

Responder exactamente en tres encabezados, en este orden: ## Análise Breve, ## Código Limpo e Completo, ## Configurações. Después de la sección de configuración, enumerar los comandos de validación realmente ejecutados, la cobertura medida y los riesgos restantes. No agregar un veredicto de aprobación.

Contrato del artefacto

Marcadores requeridos, idénticos en forma byte a la plantilla del informe:

<!-- 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 -->

Familias de ID estables: CHG-NNN para cambios, T-NNN para pruebas, CFG-NNN para adiciones de configuración y EV-NNN para evidencia de validación. Cada cambio debe enlazar a al menos una prueba y una fila de evidencia en la tabla de trazabilidad.

Matriz de versiones

Angular detectadoLínea base de renderizadoFlujo de control y estadoGuía de detección de cambios
v2-v16 (no compatible)Patrones de era NgModuleUsar *ngIf, *ngFor con trackBy y RxJS; el flujo de control integrado no está disponibleBasado en zona; no proponer una actualización a menos que se solicite
v17-v19 (no compatible)standalone disponible, predeterminado en v19Flujo de control introducido en v17 y estable en v18; signals disponibles; usarlos solo si el proyecto ya lo haceBasado en zona; sin zona experimental existe en v18-v19 y está fuera del alcance
v20.0-v20.1standalone predeterminadoSignals y flujo de control establesSin zona experimental
v20.2+standalone predeterminadoSignals y flujo de control establesSin zona estable a través de provideZonelessChangeDetection()
v21+standalone predeterminadoSignals, flujo de control y toSignal() como línea baseSin zona es el valor predeterminado; no usar provideZoneChangeDetection()
v22+standalone y OnPush implícitosNo establecer standalone: true explícitamenteNo establecer changeDetection: OnPush explícitamente

La salida del detector es autoritaria. Angular v2-v19 ya no son compatibles; registrar esa limitación en lugar de sugerir una migración. Nunca introducir una API limitada por versión sin confirmar el soporte de la matriz y la guía oficial para la versión detectada.

Reglas de evidencia

  • Registrar el comando exacto, el estado de salida y el valor medido para pruebas, verificaciones de tipos, compilaciones y cobertura.
  • Referenciar archivos cambiados con ruta:línea al explicar una decisión.
  • Mantener IDs, marcadores, severidades, nombres de frameworks y valores de estado en inglés.
  • Redactar tokens, credenciales y datos personales como [REDACTADO].
  • Mantener el informe de configuración solo a las claves; nunca pegar valores de configuración sin procesar en el artefacto.
  • No reclamar un resultado de CI sin verificarlo explícitamente.
  • Si un paso de validación falla, registrar el fracaso y enumerar los riesgos restantes en lugar de ocultarlo.

Reglas de suposiciones

  • Cada suposición debe tener un ID (ASM-NNN), una descripción, un propietario y un impacto.
  • Cuando una suposición resulte ser incorrecta, documentar la evidencia y actualizar el diseño.
  • No asumir disponibilidad de red, acceso a APIs externas o datos de muestra sin confirmarlo.
  • No asumir que el detector de pila está instalado o funcionando; si falla, pedir al usuario que proporcione las versiones manualmente.
  • No asumir que una biblioteca o paquete esté disponible; verificar package.json antes de importarlo.
  • No asumir que la configuración de pruebas, lint o compilación coincida con los valores predeterminados; leer la configuración real del proyecto.

Material de referencia

ReferenciaPropósito
references/codebase-conventions.mdConvenciones de código base del proyecto
references/version-detection.mdMatriz de versiones y guía de API
references/change-detection-model.mdModelo de detección de cambios (OnPush/zoneless)
references/di-and-services.mdInyección de dependencias y servicios
references/state-http-interceptors.mdEstado, HTTP e interceptores
references/official-docs.mdGuía oficial de angular.dev
references/testing-jest.mdGuía de pruebas Jest
references/report-template.mdPlantilla del artefacto
references/validation-checklist.mdLista de verificación de validación manual

El material de referencia se encuentra en el directorio references/ de este paquete de habilidad y se cargará cuando se invoque la habilidad.

Skills relacionados