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.
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.
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.
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.
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).
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.
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.
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.
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.
Or if you prefer the functional DI style:
Use inject() function for all DI — no constructor parameters for injected deps.
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.
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.
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.
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().
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.
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
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