Angular 개발자 가이드라인
활성화 시점
- Angular 프로젝트 또는 코드베이스에서 작업 중
- 새 Angular 프로젝트, 애플리케이션 또는 라이브러리 생성 또는 스케폴딩 중
- 컴포넌트, 서비스, 디렉티브, 파이프, 가드, 리졸버 생성 중
- Angular Signals,
linkedSignal또는resource로 반응형 구현 중 - Angular 폼(시그널 폼, 반응형 폼 또는 템플릿 기반 폼) 작업 중
- 의존성 주입, 라우팅, 게으른 로딩 또는 라우트 가드 설정 중
- 접근성(ARIA), 애니메이션 또는 컴포넌트 스타일링 추가 중
- Angular 특화 테스트(단위, 컴포넌트 harness, E2E) 작성 또는 디버깅 중
- Angular CLI 도구 또는 Angular MCP 서버 구성 중
-
가이드를 제공하기 전에 항상 프로젝트의 Angular 버전을 분석하세요. 버전별로 모범 사례와 사용 가능한 기능이 크게 다를 수 있습니다. Angular CLI로 새 프로젝트를 생성하는 경우, 사용자가 요청하지 않는 한 버전을 지정하지 마세요.
-
코드를 생성할 때 유지보수성과 성능을 위해 Angular 스타일 가이드와 모범 사례를 따르세요. 컴포넌트, 서비스, 디렉티브, 파이프, 라우트를 스케폴딩할 때 Angular CLI를 사용하여 일관성을 유지하세요.
-
코드 생성을 완료한 후
ng build를 실행하여 빌드 오류가 없는지 확인하세요. 오류가 있으면 오류 메시지를 분석하고 수정한 후 진행하세요. 생성된 코드가 올바르고 기능적으로 동작하는지 확인하는 중요한 단계이므로 건너뛰지 마세요.
새 프로젝트 생성
사용자가 별도의 가이드라인을 제공하지 않는 경우, 새 Angular 프로젝트를 생성할 때 다음 기본값을 사용하세요:
- 사용자가 다른 버전을 지정하지 않는 한 최신 안정 버전의 Angular를 사용하세요.
- 대상 Angular 버전이 지원하는 경우에만 새 프로젝트에서 Signal Forms를 선호하세요. 자세히 알아보기
ng new 실행 규칙:
새 Angular 프로젝트 생성을 요청받으면 다음 엄격한 단계에 따라 올바른 실행 명령을 결정해야 합니다:
1단계: 명시적인 사용자 버전 확인.
- 만약 사용자가 특정 버전(예: Angular 15)을 요청하면, 로컬 설치는 무시하고 엄격하게
npx를 사용하세요. - 명령어:
npx @angular/cli@<요청된_버전> new <프로젝트-이름>
2단계: 기존 Angular 설치 확인.
- 만약 특정 버전이 요청되지 않은 경우, 터미널에서
ng version을 실행하여 시스템에 Angular CLI가 이미 설치되어 있는지 확인하세요. - 만약 명령어가 성공하고 설치된 버전을 반환하면, 로컬/전역 설치를 직접 사용하세요.
- 명령어:
ng new <프로젝트-이름>
3단계: 최신 버전으로 대체.
- 만약 특정 버전이 요청되지 않았고
ng version명령어가 실패하면(Angular 설치가 없음을 나타냄),npx를 사용하여 최신 버전을 가져와야 합니다. - 명령어:
npx @angular/cli@latest new <프로젝트-이름>
컴포넌트
Angular 컴포넌트 작업 시, 작업에 따라 다음 참고 자료를 참조하세요:
- 기본 사항: 구조, 메타데이터, 핵심 개념, 템플릿 제어 흐름(@if, @for, @switch). components.md 읽기
- 입력: 시그널 기반 입력, 변환, 모델 입력. inputs.md 읽기
- 출력: 시그널 기반 출력 및 사용자 정의 이벤트 모범 사례. outputs.md 읽기
- 호스트 요소: 호스트 바인딩 및 속성 주입. host-elements.md 읽기
위 참고 자료에 없는 더 깊은 문서가 필요하면 https://angular.dev/guide/components에서 문서를 읽으세요.
반응형 및 데이터 관리
상태 및 데이터 반응형을 관리할 때 Angular Signals를 사용하고 다음 참고 자료를 참조하세요:
- Signals 개요: 핵심 시그널 개념(
signal,computed), 반응형 컨텍스트,untracked. signals-overview.md 읽기 - 종속 상태 (
linkedSignal): 소스 시그널에 연결된 쓰기 가능한 상태 생성. linked-signal.md 읽기 - 비동기 반응형 (
resource): 비동기 데이터를 시그널 상태로 직접 가져오기. resource.md 읽기 - 부수 효과 (
effect): 로깅, 타사 DOM 조작(afterRenderEffect), effect를 사용하지 말아야 할 경우. effects.md 읽기
폼
대부분의 새 앱에서는 시그널 폼을 선호하세요. 폼 결정을 내릴 때 프로젝트를 분석하고 다음 지침을 고려하세요:
-
애플리케이션 버전이 Signal Forms를 지원하고 새 폼인 경우 시그널 폼을 선호하세요.
-
이전 애플리케이션이나 기존 폼의 경우 애플리케이션의 현재 폼 전략을 따르세요.
-
시그널 폼: 폼 상태 관리를 위해 시그널 사용. signal-forms.md 읽기
-
템플릿 기반 폼: 간단한 폼에 사용. template-driven-forms.md 읽기
-
반응형 폼: 복잡한 폼에 사용. reactive-forms.md 읽기
의존성 주입
Angular에서 의존성 주입을 구현할 때 다음 지침을 따르세요:
- 기본 사항: 의존성 주입 개요, 서비스,
inject()함수. di-fundamentals.md 읽기 - 서비스 생성 및 사용: 서비스 생성,
providedIn: 'root'옵션, 컴포넌트 또는 다른 서비스에 주입. creating-services.md 읽기 - 의존성 제공자 정의: 자동 vs 수동 제공,
InjectionToken,useClass,useValue,useFactory, 스코프. defining-providers.md 읽기 - 주입 컨텍스트:
inject()가 허용되는 위치,runInInjectionContext,assertInInjectionContext. injection-context.md 읽기 - 계층형 인젝터:
EnvironmentInjectorvsElementInjector, 해결 규칙, 수정자(optional,skipSelf),providersvsviewProviders. hierarchical-injectors.md 읽기
Angular Aria
다음 패턴 중 하나에 대해 접근 가능한 사용자 정의 컴포넌트를 구축할 때: Accordion, Listbox, Combobox, Menu, Tabs, Toolbar, Tree, Grid, 다음 참고 자료를 참조하세요:
- Angular Aria 컴포넌트: 헤드리스 접근 가능 컴포넌트(Accordion, Listbox, Combobox, Menu, Tabs, Toolbar, Tree, Grid) 구축 및 ARIA 속성 스타일링. angular-aria.md 읽기
라우팅
Angular에서 내비게이션을 구현할 때 다음 참고 자료를 참조하세요:
- 라우트 정의: URL 경로, 정적 vs 동적 세그먼트, 와일드카드, 리디렉션. define-routes.md 읽기
- 라우트 로딩 전략: 즉시 vs 게으른 로딩, 컨텍스트 인식 로딩. loading-strategies.md 읽기
- Outlet으로 라우트 표시:
<router-outlet>, 중첩 outlet, 명명된 outlet 사용. show-routes-with-outlets.md 읽기 - 라우트로 내비게이션:
RouterLink를 사용한 선언적 내비게이션과Router를 사용한 프로그래매틱 내비게이션. navigate-to-routes.md 읽기 - 가드로 라우트 접근 제어: 보안을 위한
CanActivate,CanMatch및 기타 가드 구현. route-guards.md 읽기 - 데이터 리졸버:
ResolveFn으로 라우트 활성화 전 데이터 미리 가져오기. data-resolvers.md 읽기 - 라우터 생명주기 및 이벤트: 내비게이션 이벤트의 시간 순서 및 디버깅. router-lifecycle.md 읽기
- 렌더링 전략: CSR, SSG(사전 렌더링), 하이드레이션이 포함된 SSR. rendering-strategies.md 읽기
- 라우트 전환 애니메이션: View Transitions API 활성화 및 사용자 정의. route-animations.md 읽기
더 깊은 문서나 추가 컨텍스트가 필요하면 공식 Angular 라우팅 가이드를 방문하세요.
스타일링 및 애니메이션
Angular에서 스타일링 및 애니메이션을 구현할 때 다음 참고 자료를 참조하세요:
- Angular에서 Tailwind CSS 사용: Angular 프로젝트에 Tailwind CSS 통합. tailwind-css.md 읽기
- Angular 애니메이션: 기본 CSS(권장) 또는 레거시 DSL을 사용한 동적 효과. angular-animations.md 읽기
- 컴포넌트 스타일링: 컴포넌트 스타일 및 캡슐화 모범 사례. component-styling.md 읽기
테스팅
테스트를 작성하거나 업데이트할 때 작업에 따라 다음 참고 자료를 참조하세요:
- 기본 사항: 단위 테스트 모범 사례, 비동기 패턴,
TestBed. testing-fundamentals.md 읽기 - 컴포넌트 Harness: 견고한 컴포넌트 상호작용을 위한 표준 패턴. component-harnesses.md 읽기
- 라우터 테스팅: 신뢰할 수 있는 내비게이션 테스트를 위한
RouterTestingHarness사용. router-testing.md 읽기 - 종단 간(E2E) 테스팅: Cypress 또는 Playwright를 사용한 E2E 테스트 모범 사례. e2e-testing.md 읽기
도구
Angular 도구를 사용할 때 다음 참고 자료를 참조하세요:
- Angular CLI: 애플리케이션 생성, 코드 생성(컴포넌트, 라우트, 서비스), 서빙, 빌드. cli.md 읽기
- Angular MCP 서버: 사용 가능한 도구, 구성, 실험적 기능. mcp.md 읽기
안티 패턴
- 시그널 폼 필드의 초기값으로
null또는undefined사용 — 대신'',0또는[]사용 - 필드를 먼저 호출하지 않고 폼 필드 상태 플래그에 접근:
form.field.valid()—form.field().valid()사용 - 대상 Angular 버전이 Signal Forms를 지원하는데 이전 폼 API로 새 폼 시작
[formField]입력에min,max,value,disabled또는readonlyHTML 속성 설정 — 대신 스키마 규칙으로 정의- 주입 컨텍스트 밖에서
inject()호출 — 필요 시runInInjectionContext사용 computed()를 사용해야 하는 파생 상태에effect()사용- 중첩된
@for루프에서$parent.$index참조 — Angular는$parent를 지원하지 않음; 대신let outerIdx = $index사용
관련 스킬
tdd-workflow— Angular 컴포넌트 및 서비스에 적용 가능한 테스트 주도 개발 워크플로security-review— Angular 관련 사항을 포함한 웹 애플리케이션 보안 체크리스트frontend-patterns— React/Next.js 접근 방식에 대한 컨텍스트를 위한 일반 프론트엔드 패턴