프론트엔드 개발 스킬
시니어 수준의 실용적이고 프로덕션에 바로 적용 가능한 프론트엔드 엔지니어링. 항상 목표는 동작하고 유지보수 가능하며 성능이 좋은 코드입니다 — 학문적 순수가 아닙니다.
스택 감지
무엇보다 먼저, 컨텍스트에서 스택을 식별합니다. 불명확하면 질문합니다. 그런 다음 해당하는 참조 파일을 로드합니다.
| 스택 | 로드 파일 |
|---|---|
| React (GraphQL 없음) | references/react.md |
| React + GraphQL/Relay | references/react-graphql.md |
| Angular | references/angular.md |
| TypeScript (모든 스택) | references/typescript.md (스택 파일과 함께 로드) |
프로젝트가 명시적으로 JS 전용이 아닌 이상, 스택 파일과 함께 references/typescript.md를 항상 로드합니다.
보편적 원칙
스택에 관계없이 적용됩니다. 건너뛰지 마십시오.
아키텍처
- 관심사를 적극적으로 분리하세요: UI 렌더링, 비즈니스 로직, 데이터 가져오기, 사이드 이펙트는 서로 다른 계층에 존재해야 합니다. 컴포넌트가 fetch 호출, 원시 API 문자열 또는 비즈니스 규칙을 포함해서는 안 됩니다.
- 유형별이 아닌 기능별로 함께 배치하세요: 최상위
components/,hooks/,tests/폴더보다features/user-profile/내에 컴포넌트, 훅, 테스트, 스타일을 함께 두는 것을 선호합니다. 앱 복잡도에 맞게 구조를 조정하세요 — 작은 앱을 과도하게 엔지니어링하지 마십시오. - 상속보다 합성: 작고 집중된 컴포넌트를 합성하여 UI를 구축합니다. 깊은 컴포넌트 계층 구조는 피하십시오.
- 조기 추상화 금지: 무언가를 두 번 작성한 후 추상화하십시오. 단일 사용 사례를 기반으로 구축된 추상화는 대개 잘못되었습니다.
컴포넌트 설계
- 컴포넌트는 한 가지 일만 해야 합니다. 컴포넌트가 변경될 이유가 두 개 이상이면 분할하십시오.
- 프레젠테이션 컴포넌트(순수 UI, 사이드 이펙트 없음)와 컨테이너/스마트 컴포넌트(데이터, 로직, 오케스트레이션)를 분리하십시오.
- Props 인터페이스는 명시적이고 타입이 지정되어야 합니다.
any,object,{}를 타입으로 사용하지 마십시오. - 폼에는 기본적으로 제어 컴포넌트를 사용하십시오.
성능 (논의 불가 기본 사항)
Core Web Vitals 목표 (실제 사용자 75백분위수 기준 측정):
- LCP ≤ 2.5초 (로딩)
- INP ≤ 200ms (상호작용 — 2024년 3월 FID 대체)
- CLS ≤ 0.1 (시각적 안정성)
보편적 성능 규칙:
- 긴 동기 작업으로 메인 스레드를 차단하지 마십시오
- 기본적으로 라우트와 무거운 컴포넌트를 지연 로딩하십시오
- 모든 이미지와 미디어에 명시적 치수를 설정하십시오 (CLS 방지)
- LCP 이미지에
fetchpriority="high"를 사용하십시오 - 중요하지 않은 타사 스크립트는 지연하십시오
- 레이아웃 스래싱을 피하십시오 (DOM 읽기/쓰기를 배치 처리)
- bfcache 적격성 활성화:
unload리스너 사용 금지, 불필요한no-store사용 금지
디자인 시스템 및 토큰
- 디자인 토큰(색상, 간격, 타이포그래피, 반경, 그림자)을 근본 진리로 정의하십시오 — 컴포넌트에 값을 하드코딩하지 마십시오
- CSS 사용자 정의 속성(
--color-primary) 또는 토큰 시스템(Style Dictionary, Tailwind 설정)을 사용하여 테마를 중앙화하십시오 - Atomic Design을 정신적 모델로 사용: atoms → molecules → organisms → templates → pages. 명명을 강요하지 말고 이 계층 구조로 생각하십시오
- 격리, 발견 가능성 및 시각적 회귀 테스트를 위해 Storybook에 컴포넌트를 문서화하십시오
- 접근성은 선택 사항이 아닙니다: WCAG 2.1 AA 최소 준수. 모든 상호작용 요소는 키보드 지원, 포커스 관리 및 시맨틱 HTML이 불충분한 경우 ARIA가 필요합니다
API 통합
- 컴포넌트에서 직접 API를 호출하지 마십시오. 데이터 계층(커스텀 훅, 서비스 또는 쿼리 라이브러리)을 사용하십시오
- 세 가지 상태(로딩, 오류, 성공)를 명시적으로 처리하십시오 — 절대 해피 패스만 가정하지 마십시오
- 변이에 대한 사용자 체감 성능을 위해 낙관적 업데이트를 사용하십시오
- 경계에서 API 응답을 검증하십시오(Zod, io-ts 등) — 외부 데이터 형태를 신뢰하지 마십시오
- API 기본 URL과 인증 토큰 주입을 중앙화하십시오 — 컴포넌트 전체에 흩뿌리지 마십시오
테스트 전략
3계층 접근법:
- 단위 테스트: 순수 함수, 유틸리티, 커스텀 훅 (Jest / Vitest)
- 컴포넌트 테스트: 렌더링 동작, 사용자 상호작용, 상태 변경 (Testing Library — 동작을 테스트하고 구현을 테스트하지 마십시오)
- E2E 테스트: 중요한 사용자 여정만 (Playwright 또는 Cypress)
규칙:
- 사용자 관점에서 동작을 테스트하고 내부 구현은 테스트하지 마십시오
- 로직에 스냅샷을 사용하지 마십시오 — 취약합니다. 의도적인 시각적 회귀에만 스냅샷을 사용하십시오
- 비즈니스 로직에는 높은 커버리지를 목표로 하고, 보일러플레이트에는 목표를 두지 마십시오
- 테스트 파일을 테스트 대상 코드와 함께 배치하십시오:
Button.tsx옆에Button.test.tsx
코드 탐색 (tsserver)
텍스트 검색을 통한 일반 LSP 워크플로는 dev-standards 스킬 ("코드 탐색")에 있습니다. TypeScript 관련 참고 사항:
LSP 도구는 TS/TSX에 대해 tsserver로 라우팅됩니다. 단일 파일 작업은 cold 상태에서도 안정적입니다: documentSymbol, hover, goToDefinition.
주의 — tsserver는 게으르게 인덱싱합니다(gopls와 달리). 콜드 서버에서 실행된 교차 파일 쿼리(findReferences/workspaceSymbol)는 조용히 부족하게 계산할 수 있습니다: 프로젝트에 이미 로드된 파일만 알며, 확신 있지만 불완전한 결과를 반환합니다(예: 선언만). 이에 대비하십시오:
- 의심스러울 정도로 낮은 참조 수는 미검증으로 간주하십시오.
- 사용처(심볼을 가져오는 파일)에서
findReferences를 쿼리하고, 선언만 단독으로 쿼리하지 마십시오 — 이렇게 하면 프로젝트 그래프가 로드됩니다. - "이것이 아직 사용 중인가?" 결정(데드 코드 제거, 안전한 이름 변경)은
grep으로 확인하십시오 — 부족하게 계산된 결과는 위험합니다.
도구 기본값 (2025)
- 번들러: Vite (신규 프로젝트 기본값); 이미 사용 중인 대규모 엔터프라이즈 환경에서는 Webpack 5
- 린팅: ESLint +
@typescript-eslint+ Prettier (포매팅은 린팅과 분리) - 패키지 매니저: 모노레포에는 pnpm 선호; npm 또는 yarn도 사용 가능
- 모노레포: 멀티 패키지 워크스페이스에는 Nx 또는 Turborepo
- CI: 모든 PR에서 타입 검사, 린트, 테스트, 빌드를 실행하십시오. 빨간 파이프라인을 절대 병합하지 마십시오.
출력 모드
출력을 생성할 때는 다음 지침을 따르십시오:
컴포넌트 코드: 타입을 포함하고, 엣지 케이스를 처리하며, 참조 파일의 스택 패턴을 따릅니다. 크기가 허용되지 않는 경우가 아니면 동일한 응답에 컴포넌트와 테스트를 함께 제공하십시오.
아키텍처 / 파일 구조: 먼저 디렉토리 트리를 표시한 다음, 그 이유를 설명합니다. 의견을 제시하십시오 — 선택 옵션 메뉴가 아닌 하나의 좋은 구조를 제공하십시오.
성능 감사: 심각도별로 결과를 나열합니다 (심각 / 경고 / 정보). 각 결과에 대해: 무엇인지, 왜 중요한지, 어떻게 수정하는지.
디자인 시스템 설정: 토큰 구조를 먼저, 그 다음 컴포넌트 프리미티브, 그 다음 문서화 설정.
API 통합: 특정 스택에 대한 데이터 계층 패턴을 보여준 다음, 이를 소비하는 컴포넌트를 보여줍니다.
테스팅: 테스트할 코드와 함께 테스트를 보여줍니다. AAA(Arrange / Act / Assert)를 따릅니다.
동반 스킬
이 스킬은 엔지니어링을 다룹니다. 시각적 미학(타이포그래피 선택, 색상 시스템, 모션 디자인, 공간 구성, 일반적인 AI 미학 회피)에 대해서는 frontend-design 스킬을 참조하십시오. 둘 다 필요한 작업(예: "멋진 대시보드 구축")에는 두 스킬을 함께 사용하십시오: frontend-dev는 아키텍처와 코드 품질, frontend-design은 시각적 방향을 담당합니다.
참조 파일
스택별 출력을 생성하기 전에 다음을 읽으십시오:
references/typescript.md— TypeScript 엄격 모드, 패턴, 일반적인 함정references/react.md— React 19, Next.js, 훅, 상태 관리, 렌더링 전략references/react-graphql.md— Relay, 함께 배치된 프래그먼트, React의 GraphQL 패턴references/angular.md— Angular v22, Signals, Standalone Components, zoneless, NgRx