AI-First 프론트엔드 개발 종합 가이드

0. 먼저 알고 가기 (30초 요약)

• 이 문서는 모든 가이드를 읽는 출발 지도입니다.
• 먼저 문서 책임 범위를 확인하고 그다음 각 영역(상태/테스트/운영/보안)을 순서대로 보세요.
• 충돌 규칙은 바로 적용 가능한 기준(게이트/예외/승인자)으로 정리되어 있습니다.

비유: 이 문서는 공항의 안내판과 같습니다. 어디로 가야 하는지(목표), 어느 게이트를 거쳐야 하는지(검증), 누구에게 물어야 하는지(소유권)를 한 화면에 보여줍니다.

전체 가이드 전경 한눈에 보기

flowchart TB
  Start(["요구사항 또는 이슈"])

  subgraph L1["Layer 1: System Map"]
    D00["00. 종합 목차"]
  end

  subgraph L2["Layer 2: Core Engineering"]
    D01["01. TypeScript"]
    D02["02. React 19"]
    D03["03. 상태 관리"]
    D04["04. 아키텍처"]
    D05["05. API/모킹"]
    D06["06. 웹 보안"]
  end

  subgraph L3["Layer 3: Quality Gates"]
    D07["07. 테스팅"]
    D08["08. 성능"]
    D13["13. 호환성"]
    D19["19. 접근성"]
  end

  subgraph L4["Layer 4: Delivery & Ops"]
    D09["09. 장애대응"]
    D10["10. IaC"]
    D11["11. CI/CD"]
    D12["12. CDN"]
    D14["14. 배포"]
    D22["22. 모노레포"]
    D27["27. 다중서버"]
    D28["28. Sentry"]
  end

  subgraph L5["Layer 5: Governance & AI"]
    D15["15. RFC"]
    D16["16. AI 코드리뷰"]
    D17["17. 온보딩"]
    D18["18. AI 워크플로우"]
  end

  subgraph L6["Layer 6: Product UX"]
    D20["20. 디자인시스템"]
    D21["21. MFE"]
    D23["23. i18n"]
    D24["24. SEO"]
    D25["25. 모션"]
    D26["26. PWA"]
  end

  Start --> D00
  D00 --> L2
  D00 --> L3
  L2 --> L3
  L3 --> L4
  L2 --> L4
  L4 --> L5
  L3 --> L6
  L5 -.교차참조.-> L2

  style L1 fill:#e3f2fd,stroke:#1565c0
  style L2 fill:#e8f5e9,stroke:#2e7d32
  style L3 fill:#fff8e1,stroke:#f9a825
  style L4 fill:#fce4ec,stroke:#c2185b
  style L5 fill:#f3e5f5,stroke:#7b1fa2
  style L6 fill:#e0f2f1,stroke:#00695c

초심자용 한눈에 보기

이 문서를 처음 볼 때는 아래 순서로 읽으면 훨씬 빨라집니다.

1. 문서 품질 원칙에서 기준을 정하고
2. 문서 아키텍처에서 내가 어디를 먼저 봐야 할지 선택하고
3. 마지막에 공통 PR 완료 기준으로 체크하세요.

React 앱을 새로 도입하거나 버전/빌드 체계를 바꿀 때는 02. React 19 실무 가이드의 13. 리액트 빌드 도입 가이드를 먼저 적용하고, 11. CI/CD 파이프라인의 React 빌드 검증 절차를 연동하세요.

flowchart LR
  A["1단계<br/>품질 원칙"] --> B["2단계<br/>문서 아키텍처"]
  B --> C["3단계<br/>PR 완료 기준"]
  style A fill:#bbdefb
  style B fill:#c8e6c9
  style C fill:#ffe0b2

핵심 용어 빠르게 정리

00부터 28까지, 프론트엔드 개발의 설계, 구현, 검증, 배포, 운영을 하나의 실무 흐름으로 연결하는 문서 허브입니다.

---

추천 항목 (실무 우선순위)

• 현재팀에 먼저 적용: 현재 팀의 문서 책임 범위와 PR 완료 기준을 기준점으로 잡아, 00-28 각 문서의 충돌 규칙을 1회 정리하세요.
• 다음으로 고정: 01/02/03 문서를 기준으로 타입·상태·비동기 핵심 규칙을 팀 위키에 묶어서 공유하세요.
• 반복 고도화: 월 1회 14/11/09 문서의 운영 게이트를 샘플 PR에 적용해 기준의 누락 항목을 찾아 제거하세요.

실무 우선순위 타임라인

flowchart LR
  subgraph Phase1 ["즉시 (1~10일)"]
    A1["팀 문서 책임 범위 정리"] --> A2["PR 완료 기준 게시"]
  end

  subgraph Phase2 ["1~4주차"]
    B1["타입/상태/비동기 규칙 위키"] --> B2["보일러플레이트 구축"]
  end

  subgraph Phase3 ["1~3개월"]
    C1["운영 게이트 샘플 적용"] --> C2["월간 회고 / 누락 제거"]
  end

  A2 --> B1
  B2 --> C1

  style Phase1 fill:#1e293b,stroke:#38bdf8,stroke-width:1px,color:#fff
  style Phase2 fill:#1e293b,stroke:#34d399,stroke-width:1px,color:#fff
  style Phase3 fill:#1e293b,stroke:#fbbf24,stroke-width:1px,color:#fff

위 gantt는 예시이며, 시작 날짜는 팀 일정에 맞춰 조정합니다.

추천 항목 고도화 체크

• 첫 적용 — 가이드 목차와 책임 범위 중 하나를 실제 PR이나 운영 이슈에 붙이고, 변경 전 기준을 먼저 적는다.
• 증거 정리 — 문서 인덱스 diff, 링크 검사 결과, 충돌 규칙 정리를 같은 작업 기록에 남긴다.
• 재점검 — 찾지 못한 문서 링크와 상충 기준 수가 나아졌는지 30일 안에 확인하고 기준을 유지, 수정, 폐기 중 하나로 판정한다.

추천 항목 실행 기록 템플릿

• 작업 : 가이드 목차와 책임 범위 적용 범위를 어느 화면, 패키지, 문서에 둘지 적는다.
• 증거 : 문서 인덱스 diff, 링크 검사 결과, 충돌 규칙 정리 중 실제로 남긴 항목만 링크한다.
• 판정 : 유지/수정/폐기 중 하나와 이유를 한 문장으로 남긴다.
• 다음 점검 : 찾지 못한 문서 링크와 상충 기준 수를 다시 볼 날짜와 담당자를 지정한다.

문서 책임 범위

---

0. 문서 품질 원칙

이 가이드는 기술 목록이 아니라 변경하기 쉬운 프론트엔드 코드와 운영 가능한 개발 프로세스를 만들기 위한 기준입니다. 좋은 코드는 새 요구사항이 왔을 때 어디를 고치면 되는지 빨리 찾을 수 있고, 변경 범위와 검증 방법이 분명해야 합니다.

0.0 문서 네비게이션 맵

flowchart TD
  A["0. 문서 품질 원칙"] --> B["0.1 교차 검증 매트릭스"]
  A --> C["0.2 운영 게이트"]
  A --> D["0.3 가이드 학습 플로우"]
  B --> E["1~3 기초/문법 계층"]
  C --> F["4~7 구현/테스트 계층"]
  D --> G["8~14 배포/운영 계층"]
  E --> H["11 CI/CD, 14 배포, 09 장애 대응"]
  F --> I["12~19 기타 특화 가이드"]
  H --> J["15~28 운영 및 정책"]

0.1 교차 검증 매트릭스

0.2 운영 게이트

0.3 가이드 학습 플로우 도식

도입부에서 먼저 전체 흐름을 잡고 들어가면 각 문서를 읽는 순서가 고정됩니다.

flowchart LR
  subgraph Entry ["1단계: 가이드 시작점"]
    A["요구사항/이슈 제기"] --> B["00 종합 가이드<br/>(문서 품질 / 운영 게이트)"]
    B --> C["01~03 기술 기초<br/>(TypeScript/React/상태관리)"]
  end

  subgraph TrackA ["2단계 (A): 설계 & 구현"]
    D["04 아키텍처 설계"] --> E["05~07 구현/테스트"]
  end

  subgraph TrackB ["2단계 (B): 사용자 경험 (UX)"]
    F["08 성능 최적화"] --> G["13 브라우저 호환성"]
    G --> H["19 웹 접근성"]
  end

  subgraph TrackC ["3단계 (A): 배포 & 운영"]
    I["11 CI/CD 파이프라인"] --> J["14 배포 프로세스"]
    J --> K["09 장애 대응 표준"]
    K --> O["28 Sentry 모니터링"]
  end

  subgraph TrackD ["3단계 (B): 인프라 아키텍처"]
    L["10 인프라/IaC"] --> M["12 CDN 캐시 전략"]
    M --> N["27 다중 개발 서버"]
  end

  C --> D
  C --> F
  C --> I
  C --> L

  style Entry fill:#0f172a,stroke:#38bdf8,stroke-width:2px,color:#fff
  style TrackA fill:#0f172a,stroke:#34d399,stroke-width:1px,color:#fff
  style TrackB fill:#0f172a,stroke:#f43f5e,stroke-width:1px,color:#fff
  style TrackC fill:#0f172a,stroke:#fbbf24,stroke-width:1px,color:#fff
  style TrackD fill:#0f172a,stroke:#a78bfa,stroke-width:1px,color:#fff

flowchart TD
  A2["기능/도메인 구조를 바꿔야 하나?"] -->|예| B2["04, 22, 15"]
  A2 -->|아니오| C2["성능/품질 이슈인가?"]
  C2 -->|예| D2["08, 07, 19, 13"]
  C2 -->|아니오| E2["배포/운영 안정성이 핵심인가?"]
  E2 -->|예| F2["11, 14, 09, 28"]
  E2 -->|아니오| G2["18 AI 워크플로우"]

---

1. 먼저 정할 것

새 프로젝트나 큰 리팩터링을 시작할 때는 기술 선택보다 아래 결정을 먼저 문장으로 씁니다.

---

2. 디렉토리 구조 원칙

파일 종류별 폴더만으로 프로젝트를 구성하면 처음에는 단순하지만, 규모가 커질수록 어떤 기능의 컴포넌트, hook, API, 타입, 테스트가 서로 연결되는지 찾기 어려워집니다. 이 가이드는 Frontend Fundamentals의 code-directory 원칙을 따라 함께 수정되는 파일을 같은 디렉토리에 둔다를 기본값으로 삼습니다.

2.1 피해야 할 구조

src/
  components/
  hooks/
  utils/
  constants/
  remotes/
  contexts/

이 구조는 파일 종류는 잘 보이지만 변경 단위가 보이지 않습니다. checkout 기능을 삭제하거나 수정할 때 여러 폴더를 뒤져야 하고, 사용되지 않는 hook이나 util이 남기 쉽습니다.

2.2 권장 구조

src/
  app/
    providers/
    routes/
  features/
    checkout/
      api/
      components/
      hooks/
      model/
      tests/
      index.ts
    profile/
      api/
      components/
      hooks/
      model/
      tests/
      index.ts
  shared/
    ui/
    lib/
    config/

기능 내부에서만 쓰는 코드는 기능 폴더에 둡니다. 여러 기능에서 실제로 재사용되고, 도메인 의존이 없으며, 독립 테스트가 있는 코드만 shared로 올립니다.

2.3 이동 판단표

---

3. Frontend Fundamentals 코드 품질 매트릭스

아래 17개 예시는 모든 PR에서 같은 방식으로 묻는 공통 리뷰 질문입니다. 특정 도구 규칙으로 전부 강제하기보다, 코드 배치, 이름, 반환 타입, 모킹, 주석, 컴포넌트 경계의 판단 기준으로 사용합니다.

---

4. 도구 기반 품질 게이트

도구는 코드 품질 기준을 대체하지 않고, 사람이 놓치기 쉬운 반복 검증을 빠르게 실패시키는 장치입니다.

---

5. 문서 아키텍처

Layer 1: System Map

• 00. 종합 가이드: 전체 구조, 읽는 순서, 공통 완료 기준.

Layer 2: Core Engineering

• 01. TypeScript 심화: strict mode, runtime boundary, generated type, schema.
• 02. React 19 실무: Actions, Server Components, Compiler, Suspense/Error Boundary.
• 13. 리액트 빌드 도입 가이드: 빌드 커맨드, 타입체크, 산출물 증적, 배포 연동.
• 03. 상태 관리 패턴: server state, UI state, URL state, optimistic update.
• 04. 아키텍처 설계 패턴: 기능 단위 폴더, public API, import boundary, server/client 경계.
• 05. API 통신 및 모킹: contract-first, codegen, MSW, error model.
• 06. 웹 보안 심화: authentication, CSP, Trusted Types, supply chain.

Layer 3: Quality Gates

• 07. 테스팅: unit, integration, E2E, visual regression, mutation testing.
• 08. 성능 최적화: Core Web Vitals, bundle budget, RUM, attribution.
• 13. 브라우저 호환성: Baseline, feature detection, polyfill, cross-browser smoke.
• 19. 웹 접근성: WCAG, ARIA, keyboard, screen reader, release evidence.

Layer 4: Delivery & Operations

• 09. 장애 대응 및 관측성: error tracking, RUM, trace, severity, postmortem.
• 10. 인프라 및 IaC: IaC, preview, workload identity, drift, cost.
• 11. CI/CD 파이프라인: deterministic install, quality gate, artifact, attestation.
• 12. CDN 캐시 전략: cache-control, immutable assets, invalidation, security headers.
• 14. 배포 프로세스: deploy/release 분리, canary, rollback, monitoring.
• 22. 모노레포 운영: package boundary, ownership, task graph, cache, release.
• 27. 다중 개발 서버 구축: PR preview, branch deploy, Amplify, S3 artifact, GitHub Actions, cleanup.
• 28. Sentry 모니터링 활용: SDK, source map, release health, tracing, replay, alert routing.
• 29. 표준 라이브러리 스택: HTTP·상태·URL·검증·로깅·스타일 표준과 선택 이유.
• 30. 사례 회고: 저장소 일관성 정렬: 여러 저장소 표준 수렴 과정, 공유 config 메커니즘, 검증 게이트 롤아웃 회고.

Layer 5: Governance & AI

• 15. 기술 의사결정과 워킹그룹 운영: working group, RFC, ADR, PoC, risk, exit criteria.
• 16. AI 협업 코드리뷰: PR size, review evidence, AI finding triage.
• 17. 신규 입사자 온보딩: dev setup, permission, first PR, mentoring.
• 18. AI 개발 워크플로우: task boundary, context policy, verification.

Layer 6: Product Architecture & Experience

• 20. 디자인 시스템: token, component API, primitive, migration.
• 21. 마이크로 프론트엔드: host/remote contract, shared dependency, independent deploy.
• 23. 국제화: ICU message, placeholder, RTL, pseudo-localization.
• 24. SEO 및 메타데이터: metadata, structured data, sitemap, indexing.
• 25. 웹 애니메이션 모션: motion budget, View Transitions, reduced motion.
• 26. PWA 오프라인 전략: service worker, offline cache, sync, push, fallback.

---

6. 추천 학습 경로

목표별 학습 경로 시각화

flowchart TD
  subgraph Goal1["신규 프로젝트 표준 수립"]
    direction LR
    G1A[00] --> G1B[01] --> G1C[02] --> G1D[04] --> G1E[05] --> G1F[07] --> G1G[11] --> G1H[14]
  end

  subgraph Goal2["기존 프로젝트 품질 개선"]
    direction LR
    G2A[04] --> G2B[07] --> G2C[08] --> G2D[13] --> G2E[19] --> G2F[20]
  end

  subgraph Goal3["배포/운영 안정화"]
    direction LR
    G3A[09] --> G3B[10] --> G3C[11] --> G3D[12] --> G3E[14]
  end

  subgraph Goal6["Sentry 운영 적용"]
    direction LR
    G6A[09] --> G6B[28] --> G6C[14] --> G6D[11]
  end

  subgraph Goal4["AI 협업 도입"]
    direction LR
    G4A[16] --> G4B[18] --> G4C[07] --> G4D[15]
  end

  subgraph Goal5["글로벌 제품 준비"]
    direction LR
    G5A[19] --> G5B[20] --> G5C[23] --> G5D[24] --> G5E[26]
  end

  style Goal1 fill:#e3f2fd
  style Goal2 fill:#e8f5e9
  style Goal3 fill:#fff3e0
  style Goal4 fill:#fce4ec
  style Goal5 fill:#f3e5f5
  style Goal6 fill:#e0f7fa

어떤 경로를 선택할까? (결정 가이드)

flowchart TD
  Q1{"지금 무엇이 가장 급한가?"}
  Q1 -->|"새 프로젝트 시작"| P1["Goal1: 신규 표준 수립"]
  Q1 -->|"기존 프로젝트 개선"| Q2{"무엇이 문제인가?"}
  Q1 -->|"배포가 자주 깨짐"| P3["Goal3: 운영 안정화"]
  Q1 -->|"Sentry 적용/알림 정리"| P7["09 -> 28 -> 14 -> 11"]
  Q1 -->|"AI 활용 정착"| P4["Goal4: AI 협업"]
  Q1 -->|"해외/접근성 확장"| P5["Goal5: 글로벌"]
  Q2 -->|"품질/성능 부족"| P2["Goal2: 품질 개선"]
  Q2 -->|"환경/PR 미리보기 부재"| P6["27 -> 10 -> 11 -> 12 -> 14"]

---

7. 공통 PR 완료 기준

PR 완료 기준 체크 흐름

flowchart TD
  PR["PR 생성"] --> Type{"변경 유형?"}
  Type -->|타입/계약| C1["tsc + schema test"]
  Type -->|UI| C2["상태 캡처 + interaction"]
  Type -->|API| C3["contract diff + MSW"]
  Type -->|아키텍처| C4["boundary lint + 삭제 범위"]
  Type -->|성능| C5["bundle diff + Web Vitals"]
  Type -->|접근성| C6["axe + keyboard"]
  Type -->|보안| C7["secret scan + audit"]
  Type -->|배포| C8["artifact + rollback 절차"]

  C1 --> Gate["통과 시 머지"]
  C2 --> Gate
  C3 --> Gate
  C4 --> Gate
  C5 --> Gate
  C6 --> Gate
  C7 --> Gate
  C8 --> Gate

  Gate -->|실패| Fix["수정 후 재요청"]
  Fix --> PR

---

8. 공식 출처 기준

---

실무 적용 가이드

언제 이 문서를 펼칠까

• 새 프로젝트의 기본 구조를 정할 때
• 기능 폴더, shared 폴더, package 경계를 어디에 둘지 논쟁이 생겼을 때
• 문서가 너무 추상적이라 실제 PR 완료 기준이 필요할 때
• 기존 가이드에서 오래된 연도 중심 문구를 걷어내고 최신 공식 기준으로 다시 맞출 때

적용 순서

1. 기능을 기준으로 디렉토리를 먼저 나눕니다.
2. 각 기능 안에 컴포넌트, hook, API, 타입, 테스트를 함께 둡니다.
3. 실제로 여러 기능에서 같은 목적으로 반복될 때만 shared로 승격합니다.
4. 승격된 코드는 public API, 테스트, 접근성/성능 영향 범위를 함께 적습니다.
5. PR에는 변경한 기능 폴더, 검증 명령, 되돌리는 방법을 남깁니다.

함께 두는 파일

• feature의 API client, schema, hook, component, test는 같은 변경 단위로 둡니다.
• route 전용 loading/error/empty UI는 route 또는 feature 가까이에 둡니다.
• 여러 기능에서 재사용되는 코드는 테스트와 public API가 준비된 뒤에만 shared로 올립니다.

features/search/
  api/searchClient.ts
  api/searchClient.test.ts
  components/SearchResultList.tsx
  hooks/useSearchQuery.ts
  model/searchSchema.ts
  tests/search.e2e.ts
  index.ts

같은 기능을 수정할 때 함께 열어야 하는 파일은 같은 디렉토리에 둡니다. 반대로 한 파일을 고칠 때 여러 기능이 동시에 깨진다면, 공통화가 너무 이른 신호일 수 있습니다.

흔한 실수

• 파일 종류별 폴더만 두고 기능별 소유권을 표시하지 않음
• 한 번 재사용됐다는 이유로 바로 shared로 올림
• 테스트와 mock을 기능 폴더 밖에 둬서 삭제 시 누락됨
• shared/ui에 도메인 용어, API 호출, feature flag가 섞임
• import 경계를 문서에만 쓰고 lint나 graph 검사로 막지 않음

PR 완료 기준

• [ ] 새 파일이 기능 단위로 모여 있거나, shared 승격 이유가 적혀 있다.
• [ ] 삭제할 때 함께 지워야 할 파일 범위가 명확하다.
• [ ] 다른 도메인 deep import가 없다.
• [ ] 테스트, mock, schema, story가 기능과 같은 변경 단위에 있다.
• [ ] 검증 명령과 실패 시 되돌리는 방법이 PR에 남아 있다.

추천 항목 실행 우선순위 매핑

• P1(7일 내) — 가이드 목차와 책임 범위 중 하나를 작은 변경 1건에 적용하고 증거(문서 인덱스 diff)를 남긴다.
• P2(30일 내) — 문서 체계 기준을 팀 템플릿, 체크리스트, CI 중 한 곳에 고정한다.
• P3(90일 내) — 찾지 못한 문서 링크와 상충 기준 수 추이를 보고 기준을 유지할지 조정할지 결정한다.
• 완료 기준 — 문서 오너가 증거와 철회 조건을 확인했다는 기록을 남긴다.

추천 항목 실행 체크리스트

• [ ] 1단계(7일) : 가이드 목차와 책임 범위 적용 대상을 1개로 좁힌다.
• [ ] 2단계(30일) : 증거(문서 인덱스 diff, 링크 검사 결과, 충돌 규칙 정리)를 PR, ADR, 회고 중 한 곳에 연결한다.
• [ ] 3단계(60일) : 찾지 못한 문서 링크와 상충 기준 수가 기준 안에 들어왔는지 확인한다.
• [ ] 문제 대응 : 미달성 사유와 다음 조치, 중단 여부를 같은 기록에 남긴다.

추천 항목 실행 운영 규칙

• 실행 게이트 : 새 기준이 어느 문서의 단일 출처인지 먼저 확인한다.
• 승인 체계 : 문서 오너가 영향 범위와 rollback 담당자를 적용 전에 확인한다.
• 재개 조건 : 링크 검사와 책임 범위 표가 모두 맞으면 다음 문서로 확장한다.
• 정지 조건 : 두 문서가 같은 결정을 다르게 말하면 확장을 멈추고 00/15에서 정리한다.
• 리스크 점수 : 상충 문서 수, 깨진 링크 수, 변경 문서 수로 산정한다.
• 리더 승인자 : 문서 체계 오너가 최종 승인 책임을 맡는다.
• 승인 역할 : 문서 체계 작성자, 검토자, 운영 확인자를 분리해 기록한다.
• 재평가 주기 : 월 1회 목차와 검증 스크립트를 함께 점검한다.