Diretrizes para Desenvolvedores Angular

Quando Ativar

• Trabalhando em qualquer projeto ou base de código Angular
• Criando ou gerando um novo projeto, aplicação ou biblioteca Angular
• Gerando componentes, serviços, diretivas, pipes, guards ou resolvers
• Implementando reatividade com Angular Signals, linkedSignal ou resource
• Trabalhando com formulários Angular (signal forms, reactive forms ou template-driven)
• Configurando injeção de dependência, roteamento, lazy loading ou route guards
• Adicionando acessibilidade (ARIA), animações ou estilização de componentes
• Escrevendo ou depurando testes específicos do Angular (unitários, component harness, E2E)
• Configurando ferramentas do Angular CLI ou o servidor Angular MCP

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

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

3. Assim que terminar de gerar o 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-as antes de prosseguir. Não pule esta etapa, pois ela é fundamental para garantir que o código gerado seja correto e funcional.

Criando Novos Projetos

Se nenhuma diretriz for fornecida pelo usuário, use estes padrões 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. Prefira Signal Forms para novos projetos apenas quando a versão alvo do Angular as suportar. Saiba mais.

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

Etapa 1: Verifique 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@<requested_version> new <project-name>

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

• 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 <project-name>

Etapa 3: Recorra à 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 Angular existente), você deve usar npx para buscar a versão mais recente.
• Comando: npx @angular/cli@latest new <project-name>

Componentes

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

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

Se você precisar de documentação mais aprofundada que não se encontra 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 Angular Signals e consulte as seguintes referências:

• Visão Geral de Signals: Conceitos centrais de signals (signal, computed), contextos reativos e untracked. Leia signals-overview.md
• Estado Dependente (linkedSignal): Criação de estado gravável vinculado a signals de origem. Leia linked-signal.md
• Reatividade Assíncrona (resource): Busca de 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 efeitos. Leia effects.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 a versão do aplicativo suportar Signal Forms e este for um novo formulário, prefira signal forms.

…