DEV Community

Olivia Craft
Olivia Craft

Posted on

CLAUDE.md for Angular: 13 Rules That Make AI Write Idiomatic, Production-Ready Components

#angular #typescript #claudecode #webdev

Angular is the most opinionated framework in the frontend ecosystem — strong conventions, strict TypeScript, modules, services, guards, pipes, and a CLI that generates everything. But Claude Code doesn't know which of those conventions you've adopted, which RxJS patterns your team allows, or whether you're using standalone components or NgModules.

Without a CLAUDE.md, you get components with lifecycle hooks in the wrong order, services that manage state in ways that conflict with your store, and reactive chains that mix imperative and reactive patterns in the same file.

These 13 rules fix that.

Rule 1: Standalone components or NgModules — pick one and lock it in 

Architecture: standalone components (Angular 17+).
No NgModule declarations. All components use standalone: true.
Imports declared per-component. AppModule does not exist.
Enter fullscreen mode Exit fullscreen mode

Or if you're on an older codebase:

Architecture: NgModule-based. All components declared in a feature module.
No standalone components. Shared components live in SharedModule.
Enter fullscreen mode Exit fullscreen mode

Angular supports both patterns. Claude will mix them if you don't specify.

Rule 2: RxJS — operators allowed and banned 

RxJS patterns: use operators from rxjs/operators only.
Allowed: switchMap, mergeMap, exhaustMap, takeUntilDestroyed, combineLatest, forkJoin.
Banned: nested subscribes. Banned: manual unsubscribe in ngOnDestroy (use takeUntilDestroyed).
Banned: tap() for side effects that belong in effects/services.
Enter fullscreen mode Exit fullscreen mode

Nested subscribes and missing unsubscribes are the most common AI-generated Angular bugs. This rule eliminates them.

Rule 3: State management — one pattern 

State: [NgRx / Signals / Services with BehaviorSubject — pick one].
No mixing state patterns across features.
Component state: signals. Cross-feature state: [your choice].
No local state in services unless it's feature-scoped.
Enter fullscreen mode Exit fullscreen mode

Claude will happily mix BehaviorSubject services with NgRx effects. This forces consistency.

Rule 4: HTTP calls live in services, never components 

All HTTP requests go through injectable services. Components call service methods,
never HttpClient directly. Services return Observables or Promises — never
subscribe inside a service (let the component/effect handle subscription).
Enter fullscreen mode Exit fullscreen mode

Without this rule, Claude puts this.http.get() calls directly in components.

Rule 5: Typed reactive forms, not template-driven 

Forms: ReactiveFormsModule only. No ngModel. No template-driven forms.
All FormGroups strongly typed with FormGroup<{field: FormControl<type>}>.
Validators are functions — no inline validator logic in templates.
Enter fullscreen mode Exit fullscreen mode

Template-driven forms and reactive forms coexisting in a codebase create a maintenance nightmare. This rule prevents it.

Rule 6: Lazy loading for every feature route 

All feature routes use loadComponent() (standalone) or loadChildren() (NgModule).
No eagerly loaded feature components in the root router.
Route guards are functional guards (CanActivateFn), not class-based.
Enter fullscreen mode Exit fullscreen mode

Claude defaults to eager loading unless told otherwise. Functional guards are the Angular 15+ standard; class-based guards are deprecated.

Rule 7: Change detection — OnPush everywhere 

ChangeDetectionStrategy.OnPush on all components.
No manual ChangeDetectorRef.detectChanges() except in documented edge cases.
Use async pipe for Observable subscriptions in templates.
Input mutations forbidden — always create new objects/arrays.
Enter fullscreen mode Exit fullscreen mode

Default change detection causes silent performance issues. OnPush everywhere is non-negotiable in production Angular.

Rule 8: Dependency injection — providedIn root vs feature 

Services that are app-wide: providedIn: 'root'.
Services that are feature-scoped: provided in the feature module or route.
No service instantiation with new — always inject.
Constructor injection only — no inject() function except in functional guards/resolvers.
Enter fullscreen mode Exit fullscreen mode

Or if you prefer the functional DI style:

Use inject() function for all DI — no constructor parameters for injected deps.
Enter fullscreen mode Exit fullscreen mode

Pick one and enforce it — Claude will mix both.

Rule 9: Component communication — Input/Output, not service for siblings 

Parent-to-child: @Input() with required: true where applicable.
Child-to-parent: @Output() EventEmitter.
Sibling communication: shared service with signal or BehaviorSubject.
No direct component references between siblings.
Enter fullscreen mode Exit fullscreen mode

Without this rule, Claude creates service-based communication even for simple parent-child interactions.

Rule 10: Pipe usage — pure pipes only in templates 

Custom pipes: always pure (default). No impure pipes except for documented cases.
No method calls in templates that return new objects/arrays — use pipes or memoization.
No complex logic in template expressions — extract to component properties or pipes.
Enter fullscreen mode Exit fullscreen mode

Impure pipes re-execute on every change detection cycle. Method calls in templates with OnPush break memoization.

Rule 11: Testing — TestBed for components, plain for services 

Component tests: TestBed.configureTestingModule() with shallow rendering.
Mock all service dependencies with jasmine.createSpyObj() or jest.fn().
Service tests: instantiate directly, no TestBed unless HttpClientTestingModule needed.
Test file naming: component.spec.ts colocated with component.
Enter fullscreen mode Exit fullscreen mode

Claude often uses TestBed for service tests unnecessarily, adding setup overhead.

Rule 12: Error handling — HTTP interceptors, not component catch blocks 

HTTP error handling: global HttpInterceptor that catches and transforms errors.
Components never handle HTTP errors directly — they react to service state.
User-facing errors surfaced via a notification service, not alert() or console.error().
Enter fullscreen mode Exit fullscreen mode

Without this, Claude adds try/catch in every component method that calls a service.

Rule 13: File structure — feature-first, not type-first 

File structure: feature-based, not type-based.
/features/user-profile/user-profile.component.ts
/features/user-profile/user-profile.service.ts
/features/user-profile/user-profile.routes.ts
NOT: /components/, /services/, /pipes/ at root level.
Shared utilities: /shared/ directory with explicit barrel exports.
Enter fullscreen mode Exit fullscreen mode

Type-first structure (all components in /components/) breaks when teams scale. Feature-first keeps related code together.

The CLAUDE.md for Angular (copy this) 

# CLAUDE.md

## Stack
- Framework: Angular 17+ (standalone components)
- State: Signals for local, NgRx for global
- Forms: ReactiveFormsModule only
- HTTP: HttpClient via services + interceptors
- Testing: Jest + Angular Testing Library

## Architecture rules
- Standalone components everywhere — no NgModules
- OnPush change detection on all components
- RxJS: no nested subscribes, use takeUntilDestroyed for cleanup
- HTTP calls in services only — never in components
- Lazy loading for all feature routes (loadComponent)
- Functional route guards (CanActivateFn) — no class-based guards
- Feature-first directory structure
- Injectable services with providedIn: 'root' for app-wide, feature-provided for scoped

## Banned patterns
- ngModel and template-driven forms
- Nested RxJS subscribes
- Eagerly loaded feature components
- Direct component references between siblings
- Method calls in templates that return objects/arrays
- alert() or console.error() for user-facing errors
- Class-based route guards

## Testing conventions
- Component tests: TestBed + shallow rendering
- Service tests: direct instantiation
- All specs colocated: feature.component.spec.ts
Enter fullscreen mode Exit fullscreen mode

Why Angular needs this more than other frameworks

Angular's CLI generates consistent boilerplate — but it generates it for the default patterns, not your patterns. Once you've adopted signals over RxJS for local state, or switched to standalone components, the CLI and Claude both need to know. Without explicit rules, every new file is a coin flip between the old Angular and the new Angular.

The CLAUDE.md doesn't fight Angular's conventions — it clarifies which version of those conventions applies to your project.

Part of a series: CLAUDE.md files for Go, Rust, TypeScript/Node.js, Python, Java, C#/.NET, PHP, Ruby, Elixir, Scala, Haskell, C++, Vue.js/Nuxt, React/Next.js, Flutter/Dart, Swift/iOS, Spring Boot, Django/FastAPI, Android/Jetpack Compose, NestJS, and now Angular.

The full rules pack (all frameworks, team license, setup sprint) is at oliviacraft.lat

Top comments (0)