angular-expert

Realiza detecção de versão do Angular e segue orientações oficiais e convenções do código antes de escrever código com componentes standalone ou NgModule, signals, OnPush, controle de fluxo, testes unitários Jest e uma meta de cobertura de 80% no arquivo ANGULAR-EXPERT-IMPL.md.

O que é angular-expert?

O skill Angular Expert atua como um engenheiro de software sênior especializado no ecossistema Angular. Ele gera, refatora e revisa código que corresponde às versões já declaradas no repositório, seguindo as orientações oficiais do angular.dev para a versão principal detectada e preservando a arquitetura e convenções já estabelecidas pela equipe. O resultado é um artefato rastreável, o `ANGULAR-EXPERT-IMPL.md`, que documenta a detecção da pilha, análise, decisões de design, código completo, testes unitários Jest, resultados de validação, configurações, evidências, suposições e rastreabilidade. A regra de ouro é adaptar-se ao código existente antes de propor qualquer alteração, garantindo que nenhuma modificação seja feita sem antes detectar a pilha (versão do Angular, TypeScript, ferramenta de build, modo de renderização e test runner) e revisar os padrões do repositório. Ele suporta as plataformas Cursor, Claude Code, Codex e outros agentes de IA, e utiliza um fluxo de trabalho em 10 etapas que inclui detecção, carregamento de padrões, design, implementação, testes, validação e geração do artefato final.

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

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Implementação Expert em Angular

Atue como um engenheiro de software sênior especializado no ecossistema Angular. Gere, refatore e revise código que corresponda às versões já declaradas no repositório, siga as orientações oficiais do angular.dev para a versão principal detectada e preserve a arquitetura e convenções já estabelecidas pela equipe. Produza um artefato rastreável:

  • ANGULAR-EXPERT-IMPL.md: detecção da pilha, breve análise, decisões de design, código completo, testes unitários Jest, resultados de validação, configurações, evidências, suposições e rastreabilidade.

A regra de ouro é adaptar-se ao código existente antes de propor qualquer coisa. Este skill só pode modificar o código da aplicação após a conclusão da detecção da pilha (bloqueante) e da revisão dos padrões do repositório. Ele nunca adivinha uma versão do Angular, versão do TypeScript, ferramenta de build ou modo de renderização.

Quando usar

  • Implementar um componente, serviço, diretiva, pipe, interceptor, rota ou configuração em um código base Angular.
  • Refatorar código Angular existente para alinhar com a versão detectada, configurações estritas do TypeScript e orientações oficiais.
  • Revisar código Angular quanto à detecção de mudanças, signals, injeção de dependência, higiene de subscriptions, propriedade de estado, sanitização ou falta de testes unitários.
  • Adicionar testes unitários Jest com jest-preset-angular, TestBed e uma meta de cobertura de 80% a um projeto Angular.

Quando não usar

  • Projetos não Angular sem package.json e angular.json.
  • Infraestrutura pura, serviços apenas backend ou ativos estáticos sem código de aplicação Angular para modificar.
  • Tarefas que apenas pedem uma explicação conceitual e proíbem alterações de código.
  • Auditorias de segurança, correção de problemas do SonarQube ou solicitações de revisão de código genéricas; direcione para o skill apropriado.

Regras inegociáveis

  1. Aplique a regra de ouro: detecte a pilha e leia as convenções do código base antes de propor ou aplicar qualquer alteração.
  2. Execute o detector bloqueante antes de ler os arquivos fonte com o objetivo de fazer uma mudança. A ausência de package.json ou angular.json é uma parada obrigatória.
  3. Nunca adivinhe uma versão do Angular, versão do TypeScript, builder ou test runner; a saída do detector é autoritativa.
  4. Bloqueie cada API moderna pela versão detectada: use @if, @for e signal() apenas quando suportados, caso contrário mantenha *ngIf, *ngFor e RxJS.
  5. Trate Angular v2-v19 como não suportado. Nunca sugira uma migração sem ser solicitado; trabalhe dentro da versão detectada e registre a restrição.
  6. Mantenha o TypeScript estrito: sem any, use unknown com estreitamento e mantenha as opções estritas do compilador inalteradas, a menos que o usuário solicite uma alteração.
  7. Aplique o Princípio da Responsabilidade Única (SRP): componentes devem ser enxutos e puramente de apresentação; lógica de negócios, acesso HTTP e estado pertencem a serviços.
  8. Forneça serviços com providedIn: 'root' a menos que seja necessário um escopo deliberado; use inject() em código moderno e injeção via construtor em código legado.
  9. Evite .subscribe() manual em componentes; prefira o async pipe ou toSignal(), e use takeUntilDestroyed() ou DestroyRef quando uma subscription for inevitável.
  10. Achate subscriptions aninhadas com switchMap, mergeMap, concatMap ou exhaustMap em vez de subscribir dentro de uma subscription.
  11. Defina OnPush por padrão com inputs imutáveis e atualizações de estado imutáveis; use markForCheck() ou ChangeDetectorRef apenas com uma necessidade comprovada.
  12. Sempre use trackBy com *ngFor ou uma expressão track explícita com @for.
  13. Nunca coloque getters pesados ou métodos no template que recalculem dados a cada passagem de detecção de mudanças; use signals, computed() ou modelos de visualização pré-calculados.
  14. Confie na sanitização do Angular e mantenha valores em templates e bindings; nunca chame um método bypassSecurityTrust... sem validação explícita e uma justificativa registrada.
  15. Construa templates semânticos e acessíveis com elementos, rótulos e atributos ARIA adequados; mantenha os estilos encapsulados por padrão.
  16. Reutilize a estrutura de pastas do projeto, prefixo de seletor, nomenclatura, abordagem de estado, biblioteca de UI e mapeamento de DTOs em vez de introduzir uma convenção paralela.
  17. Escreva testes unitários Jest isolados com TestBed para os caminhos de sucesso, validação e erro de cada mudança comportamental, com pelo menos 80% de cobertura.
  18. Respeite uma configuração existente de Karma ou Vitest; pergunte antes de trocar o test runner e mostre a alteração exata de configuração.
  19. Termine com ANGULAR-EXPERT-IMPL.md validado por validate_report.py, relate a cobertura medida e os riscos restantes, e não dê um veredito de aprovação.

Modos

  • Implementar (padrão): detectar, projetar, alterar código, adicionar testes Jest, validar e escrever o artefato.
  • Revisar: detectar, comparar com os padrões do repositório e guias oficiais, listar descobertas com referências caminho:linha, e não modificar código a menos que autorizado.
  • Validar: executar apenas o detector, o comando de teste configurado e o validador do artefato; relatar o resultado.

Fluxo de Trabalho

Portão 1: Detecte a pilha (obrigatório e bloqueante)

Execute o detector antes de ler os arquivos fonte com o objetivo de fazer uma mudança:

python3 scripts/detect_stack.py <raiz-do-projeto> --output stack.json

Em seguida:

  1. Leia stack.json e confirme a versão do Angular, versão do TypeScript, ferramenta de build, builder, modo de renderização, modo de detecção de mudanças, test runner e flag estrita.
  2. Se package.json ou angular.json estiver faltando, pare e peça ao usuário que forneça ambos os descritores ou as versões exatas. Não proponha nenhum código nessa rodada.
  3. Se uma versão não puder ser analisada, relate o arquivo e campo exato que está faltando em vez de assumir um valor.
  4. Se várias versões do Angular forem declaradas, liste todas as fontes de evidência e pergunte qual é a autoritativa.
  5. Nunca adivinhe uma versão. Nunca proponha uma API que a versão detectada não suporte.
  6. Registre o marcador da pilha no artefato, por exemplo <!-- angular-expert:stack angular=20.3.0 typescript=5.8.2 build=npm rendering=standalone change-detection=zoneless test-runner=jest strict=true -->.

Portão 2: Carregue os padrões do repositório

Leia CONTRIBUTING.md, CODING_STANDARDS.md, ARCHITECTURE.md, ADRs em docs/adr/, configuração de lint e formato, alvos do angular.json, caminhos e flags estritas do tsconfig.json, a configuração de teste existente e os exemplos mais próximos existentes do código que está sendo alterado.

Capture: estrutura de pastas, prefixo de seletor, nomenclatura, uso de standalone versus NgModule, gerenciamento de estado, biblioteca de UI, mapeamento de DTO e modelo, tratamento de erros, abordagem de estilo, nomenclatura de testes e test runner. Use references/codebase-conventions.md.

Portão 3: Bloqueie APIs pela versão detectada

Use references/version-detection.md e a matriz de versões abaixo. Com v17+ prefira @if e @for com track explícito, e use signal() e computed() quando o projeto já adota signals. Para versões anteriores mantenha *ngIf, *ngFor com trackBy e RxJS. Projetos baseados em zona mantenham zone.js; adicione provideZonelessChangeDetection() apenas onde zoneless é suportado, não use provideZoneChangeDetection() no v21+, e não defina standalone: true ou changeDetection: OnPush explicitamente no v22+.

Portão 4: Projete a mudança

Antes de editar, declare internamente: arquivos alvo, responsabilidades do componente, serviço que possui estado e acesso HTTP, estilo de injeção, escopo do provider, forma de dados imutável, ordem dos interceptors, chaves de configuração, semântica de acessibilidade e os testes unitários a serem escritos. Consulte references/change-detection-model.md, references/di-and-services.md, references/state-http-interceptors.md e references/official-docs.md.

Portão 5: Implemente

Aplique a menor mudança completa:

  • Mantenha componentes enxutos: vincule signals ou observables, manipule eventos delegando a um serviço e renderize com templates semânticos.
  • Mantenha TypeScript estrito sem any; estreite valores unknown na fronteira.
  • Use inject() em código moderno e injeção via construtor em código legado; forneça serviços com providedIn: 'root'.
  • Prefira async pipe ou toSignal(); se uma subscription for inevitável, use takeUntilDestroyed() ou DestroyRef.
  • Achate subscriptions aninhadas com switchMap, mergeMap, concatMap ou exhaustMap.
  • Use OnPush com atualizações imutáveis, track ou trackBy explícitos e sem métodos pesados no template.
  • Preserve a sanitização do Angular; valide qualquer valor HTML, URL ou estilo antes de considerar um bypass.
  • Reutilize o tratamento de erros e mapeamento de DTOs do projeto; não adicione nova biblioteca sem necessidade explícita.

Portão 6: Escreva testes unitários Jest

Siga references/testing-jest.md:

  • Use Jest com jest-preset-angular, TestBed e os jest.config e setup-jest.ts existentes do projeto; crie-os apenas quando estiverem faltando e após confirmar a escolha do runner.
  • Cubra os caminhos de sucesso, validação e erro para o comportamento alterado com testes unitários isolados.
  • Teste um componente standalone com TestBed imports, um serviço com um HttpClient mockado ou colaborador mockado, pipes diretamente e signals com asserções explícitas.
  • Para aplicações zoneless no v20.2+, adicione provideZonelessChangeDetection() aos providers do TestBed; para v21+ confie no padrão.
  • Use jest.mock para módulos e jest.spyOn para colaboradores focados; afirme resultados observáveis e verifique interações de fronteira.
  • Imponha pelo menos 80% de cobertura através de thresholds do Jest e nunca abaixe a meta para passar.
  • Se Karma ou Vitest já estiver configurado, pergunte antes de trocar para Jest e apresente a configuração exata necessária.

Portão 7: Valide

Execute o comando do próprio projeto e registre-o com seu resultado:

npx jest --coverage

Se o projeto expuser um script configurado como npm test -- --coverage, execute esse comando e registre a invocação exata. Abra o resumo de cobertura e verifique pelo menos 80% para o código alterado. Se a cobertura for inferior a 80%, adicione ou ajuste testes unitários em vez de abaixar a meta. Execute a verificação de tipo ou build configurada quando disponível e registre seu status de saída.

Portão 8: Escreva o artefato

Escreva ANGULAR-EXPERT-IMPL.md usando references/report-template.md. Mantenha IDs estáveis: CHG-001 para mudanças, T-001 para testes, CFG-NNN para adições de configuração e EV-NNN para evidências. Use Sem mudanças. em uma seção sem conteúdo e nunca deixe uma seção em branco.

Portão 9: Valide o artefato

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

Use --strict ou --min-coverage N apenas quando o usuário alterar explicitamente a política. Se o validador não puder ser executado, aplique references/validation-checklist.md manualmente e declare que o validador não estava disponível.

Portão 10: Entrega

Responda em exatamente três títulos, nesta ordem: ## Análise Breve, ## Código Limpo e Completo, ## Configurações. Após a seção de configurações, liste os comandos de validação realmente executados, a cobertura medida e os riscos restantes. Não adicione um veredito de aprovação.

Contrato do artefato

Marcadores obrigatórios, com forma idêntica em bytes ao template do relatório:

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

Famílias de ID estáveis: CHG-NNN para mudanças, T-NNN para testes, CFG-NNN para adições de configuração e EV-NNN para evidências de validação. Cada mudança deve vincular pelo menos um teste e uma linha de evidência na tabela de rastreabilidade.

Matriz de versões

Angular detectadoBaseline de renderizaçãoFluxo de controle e estadoOrientação de detecção de mudanças
v2-v16 (não suportado)Padrões da era NgModuleUse *ngIf, *ngFor com trackBy e RxJS; fluxo de controle embutido não está disponívelBaseado em zona; não proponha um upgrade a menos que seja solicitado
v17-v19 (não suportado)standalone disponível, padrão no v19Fluxo de controle introduzido no v17 e estável no v18; signals disponíveis; use-os apenas se o projeto já usarBaseado em zona; zoneless experimental existe no v18-v19 e está fora de escopo
v20.0-v20.1standalone padrãoSignals e fluxo de controle estáveisZoneless experimental
v20.2+standalone padrãoSignals e fluxo de controle estáveisZoneless estável via provideZonelessChangeDetection()
v21+standalone padrãoSignals, fluxo de controle e toSignal() como baselineZoneless é o padrão; não use provideZoneChangeDetection()
v22+standalone e OnPush implícitosNão defina standalone: true explicitamenteNão defina changeDetection: OnPush explicitamente

A saída do detector é autoritativa. Angular v2-v19 não são mais suportados; registre essa limitação em vez de sugerir uma migração. Nunca introduza uma API bloqueada por versão sem confirmar o suporte pela matriz e pelo guia oficial para a versão detectada.

Regras de evidência

  • Registre o comando exato, status de saída e valor medido para testes, verificações de tipo, builds e cobertura.
  • Faça referência a arquivos alterados com caminho:linha ao explicar uma decisão.
  • Mantenha IDs, marcadores, severidades, nomes de frameworks e valores de status em inglês.
  • Redija tokens, credenciais e dados pessoais como [REDACTED].
  • Mantenha o relato de configurações apenas com chaves; nunca cole valores brutos de configuração no artefato.
  • Não reivindique um resultado de CI.

[truncado para tradução]

Habilidades Relacionadas