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.jsoneangular.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
- 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.
- Execute o detector bloqueante antes de ler os arquivos fonte com o objetivo de fazer uma mudança. A ausência de
package.jsonouangular.jsoné uma parada obrigatória. - Nunca adivinhe uma versão do Angular, versão do TypeScript, builder ou test runner; a saída do detector é autoritativa.
- Bloqueie cada API moderna pela versão detectada: use
@if,@foresignal()apenas quando suportados, caso contrário mantenha*ngIf,*ngFore RxJS. - 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.
- Mantenha o TypeScript estrito: sem
any, useunknowncom estreitamento e mantenha as opções estritas do compilador inalteradas, a menos que o usuário solicite uma alteração. - 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.
- Forneça serviços com
providedIn: 'root'a menos que seja necessário um escopo deliberado; useinject()em código moderno e injeção via construtor em código legado. - Evite
.subscribe()manual em componentes; prefira o async pipe outoSignal(), e usetakeUntilDestroyed()ouDestroyRefquando uma subscription for inevitável. - Achate subscriptions aninhadas com
switchMap,mergeMap,concatMapouexhaustMapem vez de subscribir dentro de uma subscription. - Defina OnPush por padrão com inputs imutáveis e atualizações de estado imutáveis; use
markForCheck()ouChangeDetectorRefapenas com uma necessidade comprovada. - Sempre use
trackBycom*ngForou uma expressãotrackexplícita com@for. - 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. - 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. - Construa templates semânticos e acessíveis com elementos, rótulos e atributos ARIA adequados; mantenha os estilos encapsulados por padrão.
- 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.
- 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.
- 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.
- Termine com
ANGULAR-EXPERT-IMPL.mdvalidado porvalidate_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:
- Leia
stack.jsone 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. - Se
package.jsonouangular.jsonestiver 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. - Se uma versão não puder ser analisada, relate o arquivo e campo exato que está faltando em vez de assumir um valor.
- Se várias versões do Angular forem declaradas, liste todas as fontes de evidência e pergunte qual é a autoritativa.
- Nunca adivinhe uma versão. Nunca proponha uma API que a versão detectada não suporte.
- 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 valoresunknownna fronteira. - Use
inject()em código moderno e injeção via construtor em código legado; forneça serviços comprovidedIn: 'root'. - Prefira
async pipeoutoSignal(); se uma subscription for inevitável, usetakeUntilDestroyed()ouDestroyRef. - Achate subscriptions aninhadas com
switchMap,mergeMap,concatMapouexhaustMap. - Use OnPush com atualizações imutáveis,
trackoutrackByexplí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 osjest.configesetup-jest.tsexistentes 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 umHttpClientmockado 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.mockpara módulos ejest.spyOnpara 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 detectado | Baseline de renderização | Fluxo de controle e estado | Orientação de detecção de mudanças |
|---|---|---|---|
| v2-v16 (não suportado) | Padrões da era NgModule | Use *ngIf, *ngFor com trackBy e RxJS; fluxo de controle embutido não está disponível | Baseado em zona; não proponha um upgrade a menos que seja solicitado |
| v17-v19 (não suportado) | standalone disponível, padrão no v19 | Fluxo de controle introduzido no v17 e estável no v18; signals disponíveis; use-os apenas se o projeto já usar | Baseado em zona; zoneless experimental existe no v18-v19 e está fora de escopo |
| v20.0-v20.1 | standalone padrão | Signals e fluxo de controle estáveis | Zoneless experimental |
| v20.2+ | standalone padrão | Signals e fluxo de controle estáveis | Zoneless estável via provideZonelessChangeDetection() |
| v21+ | standalone padrão | Signals, fluxo de controle e toSignal() como baseline | Zoneless é o padrão; não use provideZoneChangeDetection() |
| v22+ | standalone e OnPush implícitos | Não defina standalone: true explicitamente | Nã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:linhaao 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]