Um AGENTS.md que faz a IA escrever Angular moderno

Um arquivo de regras genérico não conserta Angular desatualizado#

O modo de falha em Angular gerado por IA raramente aparece como erro de sintaxe. O que acontece é o agente escrever com confiança o Angular que mais viu pela internet: scaffolding de NgModule, *ngIf por hábito, um service que embrulha tudo em RxJS, uma API experimental tratada como estável. O arquivo de regras deveria barrar isso. A maioria não barra, porque diz coisas como 'escreva código limpo e sustentável', que não restringem nada.

A versão útil é específica. Ela nomeia a versão do Angular, a fronteira de estado, a sintaxe de template e as APIs que ficam fora de escopo. A documentação do Angular é direta sobre o porquê: gerar código com LLMs virou comum o bastante para o time abrir o código do Web Codegen Scorer, uma ferramenta que mede o quão bom esse resultado realmente é.

Comece pelo arquivo gerado, não por um em branco#

O Angular gera esse arquivo de regras para você. O ng generate ai-config escreve um arquivo de boas práticas para sete alvos: agents, claude, copilot, cursor, gemini, jetbrains e windsurf. O alvo agents produz um AGENTS.md, o padrão aberto que a maioria das ferramentas já lê. Eu começaria por aí em vez de montar regras à mão a partir de um post de blog, porque o arquivo oficial se mantém atual com as convenções do Angular e um arquivo escrito à mão só continua atual se alguém for dono dele.

Essa baseline gerada é o piso, não o teto. Ela carrega convenções gerais do Angular. O que ela não tem como saber é o seu repositório: a versão em que você está travado, a abordagem de estado que você escolheu, os diretórios que ainda estão no meio de uma migração.

ng generate ai-config --tool agents
ng generate ai-config --tool claude

As regras que mudam o resultado#

Nos repositórios onde ajustei um arquivo de regras de agente, as linhas que mudaram o diff gerado nunca foram os adjetivos. Foram as restrições que um agente não consegue inferir da média pública do código Angular.

Nomeie as armadilhas, não só as preferências#

Uma preferência diz o que você gosta. Uma armadilha nomeia onde o agente erra de forma recorrente, então a regra tem onde morder. Estas ficam no arquivo porque já vi agentes caírem em cada uma:

# Armadilhas para bloquear

Não converta pipelines RxJS existentes para Signals por consistência.
Não adicione NgModule a um codebase standalone.
Não introduza biblioteca de estado; este repo usa Signals e services.
Não trate Signal Forms ou httpResource como estáveis.
Não coloque API keys ou tokens em código frontend.
Não adicione atributos de acessibilidade sem razão real de semântica.

O arquivo apodrece se ninguém for dono#

Os arquivos gerados pelo Angular se atualizam a cada release. As suas adições não. Um arquivo de regras escrito contra o Angular 18 vai alegremente dizer pro agente evitar uma API que já estabilizou, ou ignorar uma que já chegou. Essa é a armadilha de manutenção, e ela é silenciosa.

Eu amarraria o arquivo de regras ao checklist de upgrade: quando o time sobe um major, o AGENTS.md passa pela mesma revisão que as dependências. Sem isso, ele vira um fóssil que ensina o Angular do ano passado pro agente com toda a confiança.