--- title: "Um AGENTS.md que faz a IA escrever Angular moderno" description: "Um guia de produção para escrever um arquivo de regras de agente (AGENTS.md) que nomeia a versão, a fronteira Signals/RxJS, a sintaxe de template e as armadilhas que fazem a IA gerar código desatualizado." deck: "Um arquivo de regras genérico não impede o agente de escrever Angular de 2019. O que muda o resultado são restrições específicas. O [`ng generate ai-config`](https://angular.dev/cli/generate/ai-config) gera esse arquivo para sete alvos (agents, claude, copilot, cursor, gemini, jetbrains, windsurf), e a [orientação oficial](https://angular.dev/ai/develop-with-ai) diz que esses arquivos ficam 'up to date with Angular's conventions', que é justamente onde os escritos à mão apodrecem." author: "André Ramos" url: "https://andreramos.dev/pt/angular/agents-md-for-modern-angular/" lang: "pt-BR" type: "article" --- # Um AGENTS.md que faz a IA escrever Angular moderno > Um arquivo de regras genérico não impede o agente de escrever Angular de 2019. O que muda o resultado são restrições específicas. O [`ng generate ai-config`](https://angular.dev/cli/generate/ai-config) gera esse arquivo para sete alvos (agents, claude, copilot, cursor, gemini, jetbrains, windsurf), e a [orientação oficial](https://angular.dev/ai/develop-with-ai) diz que esses arquivos ficam 'up to date with Angular's conventions', que é justamente onde os escritos à mão apodrecem. ## 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](https://angular.dev/ai/develop-with-ai) 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`](https://angular.dev/cli/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. *Gere o arquivo de regras da sua ferramenta* ```bash 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. | Regra | Versão vaga (ignorada) | Versão específica (funciona) | |---|---|---| | Versão | Use Angular moderno | Mire Angular 21. Sem NgModule para código novo. | | Estado | Gerencie bem o estado | Signals para estado local e derivado. RxJS para streams, cancelamento, debounce. `toSignal` só na fronteira do componente. | | Templates | Use boa sintaxe de template | Só control flow nativo (`@if`, `@for`, `@switch`). Sem `*ngIf` ou `*ngFor`. | | APIs experimentais | Cuidado com APIs novas | Signal Forms e `httpResource` ficam fora de escopo a menos que a tarefa cite. | | Testes | Escreva testes | Adicione ou atualize um teste para a lógica que mudou, ou diga por que nenhum mudou. | ## 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 que vale bloquear de forma explícita* ```text # 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. ## Artefato reaproveitável: O que um AGENTS.md de Angular precisa fixar - A versão exata do Angular, e se NgModule é permitido em código novo. - A fronteira de estado: onde Signals terminam e RxJS começa. - Regras de template: control flow nativo, sem diretivas estruturais legadas. - APIs experimentais que ficam fora de escopo a menos que pedidas. - Armadilhas escritas como regras de 'não faça', não só preferências. - Um dono e um gatilho de revisão amarrado aos majors do Angular. ## Fontes consultadas - https://angular.dev/ai - https://angular.dev/ai/develop-with-ai - https://angular.dev/cli/generate/ai-config - https://angular.dev/ai/mcp - https://angular.dev/guide/components - https://angular.dev/guide/signals - https://angular.dev/guide/templates/control-flow - https://angular.dev/guide/forms/signals/overview - https://angular.dev/style-guide - https://blog.angular.dev/announcing-angular-v21-57946c34f14b ## Leia também - [Angular CLI MCP e código Angular gerado por IA](https://andreramos.dev/pt/angular/angular-cli-mcp-ai-generated-angular-code/) - [Um CLAUDE.md para Angular moderno: memória, não só regras](https://andreramos.dev/pt/angular/claude-md-for-modern-angular/) - [Como eu uso agentes de IA no dia a dia sem terceirizar a decisão](https://andreramos.dev/pt/angular/ai-agents-day-to-day/)