dev-goraebap/krill

Diretrizes para Desenvolvedores Angular

1. Sempre analise a versão do Angular do projeto antes de fornecer orientação, pois as melhores práticas e os recursos disponíveis podem variar significativamente entre as versões. Ao criar um novo projeto com Angular CLI, não especifique uma versão, a menos que o usuário solicite.

2. Ao gerar código, siga o guia de estilo do Angular e as melhores práticas para manutenibilidade e desempenho. Use o Angular CLI para gerar componentes, serviços, diretivas, pipes e rotas para garantir consistência.

3. Após finalizar a geração de código, execute ng build para garantir que não haja erros de compilação. Se houver erros, analise as mensagens de erro e corrija-os antes de prosseguir. Não pule esta etapa, pois é fundamental para garantir que o código gerado esteja correto e funcional.

Criando Novos Projetos

Se nenhuma diretriz for fornecida pelo usuário, aqui estão algumas regras padrão a serem seguidas ao criar um novo projeto Angular:

1. Use a versão estável mais recente do Angular, a menos que o usuário especifique o contrário.
2. Use o Signal Forms para gerenciamento de formulários em novos projetos (disponível no Angular v21 e superior) Saiba mais.

Regras de Execução para ng new: Ao ser solicitado a criar um novo projeto Angular, você deve determinar o comando de execução correto seguindo estas etapas rigorosas:

Etapa 1: Verificar se há uma versão explícita do usuário.

• SE o usuário solicitar uma versão específica (por exemplo, Angular 15), ignore as instalações locais e use estritamente npx.
• Comando: npx @angular/cli@<versão_solicitada> new <nome-do-projeto>

Etapa 2: Verificar se há uma instalação existente do Angular.

• SE nenhuma versão específica for solicitada, execute ng version no terminal para verificar se o Angular CLI já está instalado no sistema.
• SE o comando for bem-sucedido e retornar uma versão instalada, use a instalação local/global diretamente.
• Comando: ng new <nome-do-projeto>

Etapa 3: Fallback para a versão mais recente.

• SE nenhuma versão específica for solicitada E o comando ng version falhar (indicando que não há instalação do Angular), você deve usar npx para obter a versão mais recente.
• Comando: npx @angular/cli@latest new <nome-do-projeto>

Componentes

Ao trabalhar com componentes Angular, consulte as seguintes referências com base na tarefa:

• Fundamentos: Anatomia, metadados, conceitos principais e fluxo de controle de template (@if, @for, @switch). Leia components.md
• Inputs: Inputs baseados em sinais, transformações e model inputs. Leia inputs.md
• Outputs: Outputs baseados em sinais e melhores práticas para eventos personalizados. Leia outputs.md
• Elementos Hospedeiros: Host bindings e injeção de atributos. Leia host-elements.md

Se você precisar de documentação mais aprofundada que não está presente nas referências acima, leia a documentação em https://angular.dev/guide/components.

Reatividade e Gerenciamento de Dados

Ao gerenciar estado e reatividade de dados, use os Angular Signals e consulte as seguintes referências:

• Visão Geral dos Signals: Conceitos principais de signal (signal, computed), contextos reativos e untracked. Leia signals-overview.md
• Estado Dependente (linkedSignal): Criando estado gravável vinculado a sinais de origem. Leia linked-signal.md
• Reatividade Assíncrona (resource): Buscando dados assíncronos diretamente no estado do signal. Leia resource.md
• Efeitos Colaterais (effect): Logging, manipulação de DOM de terceiros (afterRenderEffect) e quando NÃO usar effects. Leia effects.md

Comunicação HTTP

Ao se comunicar com serviços de backend, use as APIs HTTP do Angular e consulte a seguinte referência:

• Cliente HTTP e Recursos: provideHttpClient, HttpClient, interceptors e httpResource. Leia http-client.md

Formulários

Na maioria dos casos para novos aplicativos, prefira signal forms. Ao tomar uma decisão sobre formulários, analise o projeto e considere as seguintes diretrizes:

• Se o aplicativo estiver usando v21 ou superior e este for um novo formulário, prefira signal forms.

• Para aplicativos mais antigos ou ao trabalhar com formulários existentes, use o tipo de formulário apropriado que corresponda à estratégia atual de formulários do aplicativo.

• Signal Forms: Use signals para gerenciamento de estado de formulários. Leia signal-forms.md

• Formulários Template-driven: Use para formulários simples. Leia template-driven-forms.md

• Formulários Reativos: Use para formulários complexos. Leia reactive-forms.md

Injeção de Dependência

Ao implementar injeção de dependência no Angular, siga estas diretrizes:

• Fundamentos: Visão geral da Injeção de Dependência, serviços e a função inject(). Leia di-fundamentals.md
• Criando e Usando Serviços: Criando serviços, a opção providedIn: 'root' e injetando em componentes ou outros serviços. Leia creating-services.md
• Definindo Providers de Dependência: Provisão automática vs manual, InjectionToken, useClass, useValue, useFactory e escopos. Leia defining-providers.md
• Contexto de Injeção: Onde inject() é permitido, runInInjectionContext e assertInInjectionContext. Leia injection-context.md
• Injetores Hierárquicos: O EnvironmentInjector vs ElementInjector, regras de resolução, modificadores (optional, skipSelf) e providers vs viewProviders. Leia hierarchical-injectors.md

Pipes

Ao formatar valores em templates, criar pipes personalizados ou reutilizar lógica semelhante a pipes em TypeScript, consulte a seguinte referência. Prefira pipes em templates; fora de templates, evite injetar classes de pipe apenas para chamar transform().

• Pipes: Importações de pipes embutidos, nomenclatura e implementação de pipes personalizados, pipes puros vs impuros e padrões de reutilização em TypeScript usando funções de formatação autônomas ou funções simples extraídas. Leia pipes.md

Angular Aria

Ao construir componentes acessíveis personalizados para qualquer um dos seguintes padrões: Accordion, Listbox, Combobox, Menu, Tabs, Toolbar, Tree, Grid, consulte a seguinte referência:

• Componentes Angular Aria: Construindo componentes acessíveis headless (Accordion, Listbox, Combobox, Menu, Tabs, Toolbar, Tree, Grid) e estilizando atributos ARIA. Leia angular-aria.md

Roteamento

Ao implementar navegação no Angular, consulte as seguintes referências:

• Definir Rotas: Caminhos de URL, segmentos estáticos vs dinâmicos, curingas e redirecionamentos. Leia define-routes.md
• Estratégias de Carregamento de Rotas: Carregamento eager vs lazy e carregamento sensível ao contexto. Leia loading-strategies.md
• Exibir Rotas com Outlets: Usando <router-outlet>, outlets aninhados e outlets nomeados. Leia show-routes-with-outlets.md
• Navegar para Rotas: Navegação declarativa com RouterLink e navegação programática com Router. Leia navigate-to-routes.md
• Controlar Acesso a Rotas com Guards: Implementando CanActivate, CanMatch e outros guards para segurança. Leia route-guards.md
• Resolvers de Dados: Pré-buscando dados antes da ativação da rota com ResolveFn. Leia data-resolvers.md
• Ciclo de Vida e Eventos do Router: Ordem cronológica dos eventos de navegação e depuração. Leia router-lifecycle.md
• Estratégias de Renderização: CSR, SSG (Pré-renderização) e SSR com hidratação. Leia rendering-strategies.md
• Animações de Transição de Rota: Habilitando e personalizando a API de Transições de Visualização (View Transitions API). Leia route-animations.md

Se você precisar de documentação mais aprofundada ou mais contexto, visite o guia oficial de Roteamento do Angular.

Estilização e Animações

Ao implementar estilização e animações no Angular, consulte as seguintes referências:

• Usando Tailwind CSS com Angular: Integrando Tailwind CSS em projetos Angular. Leia tailwind-css.md
• Animações Angular: Usando CSS nativo (recomendado) ou o DSL legado para efeitos dinâmicos. Leia angular-animations.md
• Estilizando componentes: Melhores práticas para estilos de componentes e encapsulamento. Leia component-styling.md

Testes

Ao escrever ou atualizar testes, consulte as seguintes referências com base na tarefa:

• Fundamentos: Melhores práticas para testes unitários (Vitest), padrões assíncronos e TestBed. Leia testing-fundamentals.md
• Component Harnesses: Padrões padrão para interação robusta com componentes. Leia component-harnesses.md
• Testes de Roteador: Usando RouterTestingHarness para testes de navegação confiáveis. Leia router-testing.md
• Testes End-to-End (E2E): Configurando e executando testes E2E. Leia e2e-testing.md

Ferramentas

Ao trabalhar com ferramentas Angular, consulte as seguintes referências:

• Angular CLI: Criando aplicações, gerando código (componentes, rotas, serviços), servindo e construindo. Leia cli.md
• Modernização de Código: Refatorando automaticamente para padrões modernos usando migrações. Leia migrations.md
• Servidor MCP Angular: Ferramentas disponíveis, configuração e recursos experimentais. Leia mcp.md
• Configuração de Ambiente: Estratégias para configuração em tempo de compilação e tempo de execução. Leia environment-configuration.md