dev-goraebap/krill

Angular 개발자 가이드라인

1. 가이드를 제공하기 전에 프로젝트의 Angular 버전을 항상 분석하세요. Angular 버전에 따라 모범 사례와 사용 가능한 기능이 크게 다를 수 있습니다. Angular CLI로 새 프로젝트를 생성하는 경우, 사용자가 버전을 요청하지 않는 한 특정 버전을 지정하지 마세요.

2. 코드를 생성할 때는 유지보수성과 성능을 위해 Angular 스타일 가이드와 모범 사례를 따르세요. 일관성을 유지하기 위해 Angular CLI를 사용하여 컴포넌트, 서비스, 디렉티브, 파이프, 라우트를 스캐폴딩하세요.

3. 코드 생성이 완료되면 ng build를 실행하여 빌드 오류가 없는지 확인하세요. 오류가 있으면 오류 메시지를 분석하고 진행하기 전에 수정하세요. 이 단계는 생성된 코드가 올바르고 기능적으로 동작하는지 확인하는 데 중요하므로 건너뛰지 마세요.

새 프로젝트 생성

사용자가 별도의 지침을 제공하지 않는 경우, 새 Angular 프로젝트를 생성할 때 다음 기본 규칙을 따르세요:

1. 사용자가 다른 버전을 요청하지 않는 한 Angular의 최신 안정 버전을 사용하세요.
2. 새 프로젝트에서는 폼 관리를 위해 Signal Forms를 사용하세요 (Angular v21 이상에서 사용 가능) 자세히 알아보기.

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.md 읽기

위 참고 자료에 없는 더 깊은 문서가 필요하면 https://angular.dev/guide/components 문서를 읽으세요.

반응성 및 데이터 관리

상태와 데이터 반응성을 관리할 때는 Angular Signals를 사용하고 다음 참고 자료를 참조하세요:

• Signals 개요: 핵심 Signal 개념(signal, computed), 반응형 컨텍스트, untracked. signals-overview.md 읽기
• 종속 상태 (linkedSignal): 소스 시그널에 연결된 쓰기 가능한 상태 생성. linked-signal.md 읽기
• 비동기 반응성 (resource): 비동기 데이터를 직접 시그널 상태로 가져오기. resource.md 읽기
• 부수 효과 (effect): 로깅, 서드파티 DOM 조작(afterRenderEffect), effects를 사용하지 말아야 할 경우. effects.md 읽기

HTTP 통신

백엔드 서비스와 통신할 때는 Angular HTTP API를 사용하고 다음 참고 자료를 참조하세요:

• HTTP 클라이언트 및 리소스: provideHttpClient, HttpClient, 인터셉터, httpResource. http-client.md 읽기

폼

대부분의 새 앱에서는 시그널 폼을 선호하세요. 폼 결정을 내릴 때는 프로젝트를 분석하고 다음 지침을 고려하세요:

• 애플리케이션이 v21 이상을 사용하고 있고 새 폼이라면 시그널 폼을 선호하세요.

• 이전 애플리케이션이나 기존 폼으로 작업할 때는 애플리케이션의 현재 폼 전략에 맞는 적절한 폼 유형을 사용하세요.

• 시그널 폼: 폼 상태 관리에 시그널 사용. 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 읽기
• 계층형 인젝터: EnvironmentInjector vs ElementInjector, 해결 규칙, 수정자(optional, skipSelf), providers vs viewProviders. hierarchical-injectors.md 읽기

파이프

템플릿에서 값을 포매팅하거나 사용자 정의 파이프를 생성하거나 TypeScript에서 파이프 유사 로직을 재사용할 때는 다음 참고 자료를 참조하세요. 템플릿에서는 파이프를 선호하고, 템플릿 외부에서는 transform()을 호출하기 위해 파이프 클래스를 주입하지 마세요.

• 파이프: 내장 파이프 임포트, 사용자 정의 파이프 명명 및 구현, 순수/비순수 파이프, 독립형 포매팅 함수나 추출된 일반 함수를 사용하는 TypeScript 재사용 패턴. pipes.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 읽기

테스팅

테스트를 작성하거나 업데이트할 때는 작업에 따라 다음 참고 자료를 참조하세요:

• 기본 개념: 단위 테스트(Vitest) 모범 사례, 비동기 패턴, TestBed. testing-fundamentals.md 읽기
• 컴포넌트 Harness: 강력한 컴포넌트 상호작용을 위한 표준 패턴. component-harnesses.md 읽기
• 라우터 테스팅: 신뢰할 수 있는 탐색 테스트를 위한 RouterTestingHarness 사용. router-testing.md 읽기
• 종단 간 (E2E) 테스팅: E2E 테스트 설정 및 실행. e2e-testing.md 읽기

도구

Angular 도구로 작업할 때는 다음 참고 자료를 참조하세요:

• Angular CLI: 애플리케이션 생성, 코드 생성(컴포넌트, 라우트, 서비스), 서빙, 빌드. cli.md 읽기
• 코드 현대화: 마이그레이션을 사용하여 자동으로 최신 표준으로 리팩토링. migrations.md 읽기
• Angular MCP 서버: 사용 가능한 도구, 설정, 실험적 기능. mcp.md 읽기
• 환경 설정: 빌드 타임 및 런타임 설정 전략. environment-configuration.md 읽기