fe-stack-and-commands — GS Retail FE 표준 기술 스택과 명령어 기준선

패키지 매니저: pnpm. npm/yarn 절대 사용 금지.

feature-boundaries — Feature-Sliced Design (FSD) 경계 규칙

• 코드를 파일 유형이 아닌 기능(feature)별로 그룹화
• features 간 import는 반드시 각 feature의 public entry point (index.ts)를 통해야 함. 내부 파일 직접 import 금지
• 의존성 방향은 단방향 — 순환 의존성 금지
• 공유 타입은 types/에, feature 내 타입은 해당 feature 안에 co-locate

// ✅ 올바른 import (public entry point 통해)
import { UserCard } from '@/features/user'

// ❌ 잘못된 import (feature 내부 직접 접근)
import { UserCard } from '@/features/user/components/UserCard'

• plan-first: 코드 전에 구현 계획 작성 (컴포넌트 트리, 상태, 데이터 흐름, 변경 파일)
• fe-tdd: Red-Green-Refactor — 동작 지정하는 실패 테스트(Vitest/Jest 또는 Playwright/Cypress) 먼저 작성
• cleanup-after-green: 테스트 통과 후 — 변경된 파일 포맷, 죽은 import 제거, console.log 삭제, 주석 처리된 코드 삭제

• serializable-boundary-props: Server → Client Component 경계에서 직렬화 가능한 값만 전달. 함수, 클래스 인스턴스, Date/Map/Set 금지. 대신 문자열로 직렬화 후 전달.
• hydration-mismatches: React 하이드레이션 불일치는 근본 원인에서 진단/수정. useEffect나 mounted 플래그로 렌더를 지연시켜 침묵시키는 것 금지.

// ❌ hydration 불일치 침묵 패턴 — 금지
const [mounted, setMounted] = useState(false)
useEffect(() => setMounted(true), [])
if (!mounted) return null  // 서버/클라이언트 불일치를 숨김

// ✅ 근본 원인 수정 — 서버와 클라이언트에서 동일한 초기 값 사용

• no-any: TypeScript any 금지. unknown + 타입 가드로 좁히기. 불안전한 as 캐스트 피하기.
• domain-types: 도메인 엔티티를 types/나 소유 feature에 명시적 interface/type으로 정의. API 계약이 있는 경우 그것으로부터 파생.

// ❌ any 사용 금지
function process(data: any) { ... }

// ✅ unknown + type guard
function process(data: unknown) {
  if (!isUser(data)) throw new Error('invalid')
  // 이제 data는 User 타입
}

// ✅ 도메인 타입 명시적 정의
interface User { id: string; name: string; role: 'admin' | 'viewer' }

• design-tokens: Tailwind 디자인 토큰만 사용. 하드코딩된 px/hex 금지. 토큰으로 커버되는 항목에 인라인 스타일 사용 금지. 누락된 토큰은 설정에 추가.
• accessibility: ARIA보다 시맨틱 HTML 우선. WAI-ARIA 올바르게 적용. 키보드 조작 가능성 보장. WCAG AA 명도 대비 충족.

/* ❌ 하드코딩된 값 금지 */
<div style={{color: '#7C3AED', padding: '16px'}}>

/* ✅ 디자인 토큰 사용 */
<div className="text-purple-600 p-4">

/* ✅ 시맨틱 HTML 우선 */
<button onClick={handleClick}>   /* button이 div보다 항상 우선 */
<nav>, <header>, <main>, <article>  /* 구조적 요소 활용 */

• state-ownership: 서버 상태 → TanStack Query. 클라이언트/UI 상태 → Zustand 또는 로컬 useState. 둘 사이에 데이터를 복제하지 않는다.
• route-boundaries: 모든 주요 route segment는 loading.tsx와 error.tsx를 포함해야 함. 빈 화면이나 처리되지 않은 throw 금지.

// ❌ 서버 상태를 Zustand에 복제 — 금지
const useUserStore = create((set) => ({
  users: [],  // ← 이미 TanStack Query가 관리중
  fetchUsers: async () => { const data = await api.get('/users'); set({ users: data }) }
}))

// ✅ TanStack Query로 서버 상태 관리
const { data: users } = useQuery({ queryKey: ['users'], queryFn: fetchUsers })

• casing: PascalCase (컴포넌트/인터페이스), camelCase (유틸/훅), kebab-case (파일명)
• reuse-before-install: package.json 확인 후 없을 때만 추가. 모든 의존성 추가에 명시적 승인 필요.
• commits: Conventional Commits + 명령형 제목 + 소규모 원자적 커밋
• language-policy: 코드/커밋=영어, PR/UI=한국어
• no-hardcoded-secrets: 모든 스테이징 파일에 비밀 스캔 적용
• sanitize-untrusted-input: 외부 입력 전체를 신뢰 불가로 처리. XSS/injection/path traversal 방지
• mask-pii: 로그/에러/애널리틱스에 원시 PII 절대 노출 금지
• autonomous-retry: 빌드/lint/테스트 실패 시 최대 3회 자율 수정
• protected-config-files: next.config, tsconfig, CI/CD 파이프라인 명시적 승인 없이 수정 금지
• no-reading-generated-trees: .next/, node_modules/, 빌드 출력, lockfile 내부 읽기 금지