Angular 개발자 가이드라인
활성화 시점
- Angular 프로젝트 또는 코드베이스에서 작업할 때
- 새로운 Angular 프로젝트, 애플리케이션 또는 라이브러리를 생성하거나 스캐폴딩할 때
- 컴포넌트, 서비스, 디렉티브, 파이프, 가드, 리졸버를 생성할 때
- Angular Signals,
linkedSignal또는resource로 반응성을 구현할 때 - Angular 폼(시그널 폼, 반응형 폼, 템플릿 기반 폼)으로 작업할 때
- 의존성 주입, 라우팅, 지연 로딩, 라우트 가드를 설정할 때
- 접근성(ARIA), 애니메이션, 또는 컴포넌트 스타일링을 추가할 때
- Angular 관련 테스트(단위, 컴포넌트 하네스, 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): 시그널 기반 입력, 변환, 모델 입력. inputs.md 읽기
- 출력(Outputs): 시그널 기반 출력 및 사용자 정의 이벤트 모범 사례. outputs.md 읽기
- 호스트 요소(Host Elements): 호스트 바인딩 및 속성 주입. 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), 효과를 사용하지 말아야 할 경우. effects.md 읽기
폼
대부분의 새 앱에서는 시그널 폼을 선호하세요. 폼 결정을 내릴 때는 프로젝트를 분석하고 다음 가이드라인을 고려하세요:
-
애플리케이션 버전이 Signal Forms를 지원하고 새 폼인 경우 시그널 폼을 선호하세요.
-
기존 애플리케이션 또는 기존 폼의 경우 애플리케이션의 현재 폼 전략을 따르세요.
-
시그널 폼: 폼 상태 관리를 위해 시그널을 사용하세요. signal-forms.md 읽기
-
템플릿 기반 폼: 간단한 폼에 사용하세요. template-driven-forms.md 읽기
-
반응형 폼: 복잡한 폼에 사용하세요. reactive-forms.md 읽기
의존성 주입
Angular에서 의존성 주입을 구현할 때는 다음 가이드라인을 따르세요:
- 기본 사항: 의존성 주입 개요, 서비스,
inject()함수. di-fundamentals.md 읽기 - 서비스 생성 및 사용: 서비스 생성,
providedIn: 'root'옵션, 컴포넌트 또는 다른 서비스에 주입. creating-services.md 읽기 - 의존성 제공자 정의: 자동 대 수동 제공,
InjectionToken,useClass,useValue,useFactory, 범위. defining-providers.md 읽기 - 주입 컨텍스트:
inject()가 허용되는 위치,runInInjectionContext,assertInInjectionContext. injection-context.md 읽기 - 계층적 인젝터:
EnvironmentInjector대ElementInjector, 해석 규칙, 수정자(optional,skipSelf),providers대viewProviders. 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 경로, 정적 대 동적 세그먼트, 와일드카드, 리디렉션. define-routes.md 읽기
- 라우트 로딩 전략: 즉시 로딩 대 지연 로딩, 컨텍스트 인식 로딩. loading-strategies.md 읽기
- 아웃렛으로 라우트 표시:
<router-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 읽기 - 컴포넌트 하네스: 강력한 컴포넌트 상호 작용을 위한 표준 패턴. 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 접근 방식에 대한 컨텍스트를 위한 일반 프론트엔드 패턴