---
title: "An AGENTS.md That Makes AI Write Modern Angular"
description: "A production guide to writing an Angular agent rules file (AGENTS.md) that names the version, the Signals/RxJS boundary, the template syntax, and the traps that make AI write stale code."
deck: "A generic rules file does not stop an agent from writing 2019 Angular. What changes the output is specific constraints. [`ng generate ai-config`](https://angular.dev/cli/generate/ai-config) scaffolds the file for seven targets (agents, claude, copilot, cursor, gemini, jetbrains, windsurf), and the [official guidance](https://angular.dev/ai/develop-with-ai) says these files stay 'up to date with Angular's conventions', which is exactly where most hand-written ones rot."
author: "André Ramos"
url: "https://andreramos.dev/angular/agents-md-for-modern-angular/"
lang: "en"
type: "article"
---

# An AGENTS.md That Makes AI Write Modern Angular

> A generic rules file does not stop an agent from writing 2019 Angular. What changes the output is specific constraints. [`ng generate ai-config`](https://angular.dev/cli/generate/ai-config) scaffolds the file for seven targets (agents, claude, copilot, cursor, gemini, jetbrains, windsurf), and the [official guidance](https://angular.dev/ai/develop-with-ai) says these files stay 'up to date with Angular's conventions', which is exactly where most hand-written ones rot.

## 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](https://angular.dev/ai/develop-with-ai) 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`](https://angular.dev/cli/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.

*Scaffold the rules file for your tool*

```bash
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.

| Rule | Vague version (ignored) | Specific version (works) |
|---|---|---|
| Version | Use modern Angular | Target Angular 21. No NgModule for new code. |
| State | Manage state well | Signals for local and derived state. RxJS for streams, cancellation, debounce. `toSignal` only at the component boundary. |
| Templates | Use good template syntax | Built-in control flow only (`@if`, `@for`, `@switch`). No `*ngIf` or `*ngFor`. |
| Experimental APIs | Be careful with new APIs | Signal Forms and `httpResource` are out of scope unless the task names them. |
| Tests | Write tests | Add or update a test for changed logic, or state why none changed. |

## 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 worth blocking explicitly*

```text
# 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.

## Reusable artifact: What an Angular AGENTS.md should pin down

- The exact Angular version, and whether NgModule is allowed in new code.
- The state boundary: where Signals end and RxJS begins.
- Template rules: built-in control flow, no legacy structural directives.
- Experimental APIs that are out of scope unless explicitly requested.
- Traps written as 'do not' rules, not just preferences.
- An owner and a review trigger tied to Angular major upgrades.

## Sources checked

- 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

## Related

- [Angular CLI MCP and AI-Generated Angular Code](https://andreramos.dev/angular/angular-cli-mcp-ai-generated-angular-code/)
- [A CLAUDE.md for Modern Angular: Memory, Not Just Rules](https://andreramos.dev/angular/claude-md-for-modern-angular/)
- [How I Use AI Agents Day to Day Without Handing Them the Wheel](https://andreramos.dev/angular/ai-agents-day-to-day/)