An AGENTS.md That Makes AI Write Modern Angular

A generic rules file does not fix stale Angular#

The failure mode with AI-generated Angular rarely shows up as a syntax error. What happens is the agent confidently writing the Angular it has seen most online: NgModule scaffolding, *ngIf by habit, a service that wraps everything in RxJS, an experimental API treated as stable. A rules file is supposed to block that. Most do not, because they say things like 'write clean, maintainable code' that constrain nothing.

The useful version is specific. It names the Angular version, the state boundary, the template syntax, and the APIs that are out of scope. The Angular docs are blunt about why this matters: generating code with LLMs is common enough now that the team open-sourced the Web Codegen Scorer to measure how good that output actually is.

Start from the generated file, not a blank one#

Angular scaffolds the rules file for you. ng generate ai-config writes a best-practices file for seven targets: agents, claude, copilot, cursor, gemini, jetbrains, and windsurf. The agents target produces an AGENTS.md, the open standard most tools now read. I would start there instead of hand-rolling rules from a blog post, because the official file stays current with Angular's conventions and a hand-written one only stays current if someone owns it.

That generated baseline is the floor, not the ceiling. It carries general Angular conventions. What it cannot know is your repository: the version you are pinned to, the state approach you chose, the directories still mid-migration.

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

The rules that change the output#

Across repositories where I tuned an agent rules file, the lines that changed the generated diff were never the adjectives. They were the constraints an agent cannot infer from the public average of Angular code.

Name the traps, not just the preferences#

A preference says what you like. A trap names where the agent reliably goes wrong, so the rule has something to bite on. These stay in the file because I have watched agents fall into each one:

# Traps to block

Do not convert existing RxJS pipelines to Signals for consistency.
Do not add NgModule to a standalone codebase.
Do not introduce a state library; this repo uses Signals and services.
Do not treat Signal Forms or httpResource as stable.
Do not put API keys or tokens in frontend code.
Do not add accessibility attributes without a real semantics reason.

The file rots unless someone owns it#

Angular's generated files update with each release. Your additions do not. A rules file written against Angular 18 will happily tell an agent to avoid an API that has since stabilized, or miss one that has since shipped. That is the maintenance trap, and it is quiet.

I would tie the rules file to the upgrade checklist: when the team bumps a major, the AGENTS.md gets the same review as the dependencies. Otherwise it becomes a fossil that teaches the agent last year's Angular with full confidence.