@wooojin/forgen 0.4.7 → 0.4.9

package/assets/dev-guide/be/sources/owasp-api/INDEX.md

@@ -0,0 +1,52 @@
+---
+title: OWASP API Security Top 10 문서 인덱스
+fetched: 예정 (2026-05-18 스캐폴드)
+license: CC BY-SA 4.0 (https://owasp.org)
+priority: 3 (출처 우선순위)
+---
+
+# OWASP API Security Top 10 (2023)
+
+> 가장 위험한 API 보안 취약점 10가지. 2023년판 (2019년 대비 갱신).
+
+## 출처
+
+| URL | 설명 |
+|-----|------|
+| https://owasp.org/API-Security/editions/2023/en/0x00-header/ | OWASP API Security Top 10 2023 |
+| https://github.com/OWASP/API-Security | GitHub 원본 |
+| https://owasp.org/www-project-api-security/ | 프로젝트 페이지 |
+
+## 라이선스
+
+Creative Commons Attribution-ShareAlike 4.0 (CC BY-SA 4.0)
+
+## 수집일
+
+예정 (2026-05-18 스캐폴드)
+
+## 참조 우선순위
+
+3 (common.md 출처 우선순위)
+
+## 문서 목록 (수집 예정)
+
+| 파일명 (예정) | 항목 | 제목 |
+|--------------|------|------|
+| api1-bola.md | API1 | Broken Object Level Authorization |
+| api2-broken-auth.md | API2 | Broken Authentication |
+| api3-bopla.md | API3 | Broken Object Property Level Authorization |
+| api4-unrestricted-consumption.md | API4 | Unrestricted Resource Consumption |
+| api5-bfla.md | API5 | Broken Function Level Authorization |
+| api6-ssrf.md | API6 | Unrestricted Access to Sensitive Business Flows |
+| api7-ssrf.md | API7 | Server Side Request Forgery |
+| api8-misconfig.md | API8 | Security Misconfiguration |
+| api9-inventory.md | API9 | Improper Inventory Management |
+| api10-unsafe-apis.md | API10 | Unsafe Consumption of APIs |
+
+## 핵심 참조 원칙 (principles/common.md 연결)
+
+- 전체 → Security E.4 OWASP API Top 10 매핑 테이블
+- API1 (BOLA) → E.2 인증/인가 분리 (소유권 검증)
+- API4 (Rate Limit) → E.1 입력 검증 경계
+- API7 (SSRF) → E.1 신뢰 경계

package/assets/dev-guide/be/sources/postgres/INDEX.md

@@ -0,0 +1,55 @@
+---
+title: PostgreSQL 성능 및 인덱스 문서 인덱스
+fetched: 예정 (2026-05-18 스캐폴드)
+license: PostgreSQL License + CC BY-NC 4.0 (Use The Index, Luke)
+priority: 6 (출처 우선순위)
+---
+
+# PostgreSQL — Use The Index, Luke + 공식 성능 가이드
+
+> 인덱스 설계, 실행 계획, 슬로우 쿼리 최적화.
+
+## 출처
+
+| URL | 설명 | 라이선스 |
+|-----|------|----------|
+| https://use-the-index-luke.com/ | Use The Index, Luke — Markus Winand | CC BY-NC 4.0 |
+| https://www.postgresql.org/docs/current/performance-tips.html | PostgreSQL 공식 성능 가이드 | PostgreSQL License |
+| https://www.postgresql.org/docs/current/indexes.html | 인덱스 유형 | PostgreSQL License |
+| https://www.postgresql.org/docs/current/using-explain.html | EXPLAIN 사용법 | PostgreSQL License |
+| https://www.postgresql.org/docs/current/transaction-iso.html | 트랜잭션 격리 수준 | PostgreSQL License |
+
+## 라이선스
+
+- PostgreSQL 공식 문서: PostgreSQL License (자유 사용)
+- Use The Index, Luke: CC BY-NC 4.0 (비상업적 이용)
+
+## 수집일
+
+예정 (2026-05-18 스캐폴드)
+
+## 참조 우선순위
+
+6 (common.md 출처 우선순위)
+
+## 문서 목록 (수집 예정)
+
+| 파일명 (예정) | 출처 | 주제 |
+|--------------|------|------|
+| index-basics.md | UTIL | B-Tree 인덱스 동작 원리 |
+| composite-index.md | UTIL | 복합 인덱스 설계 (컬럼 순서) |
+| covering-index.md | UTIL | Index-Only Scan (covering index) |
+| index-on-expressions.md | UTIL | 함수/표현식 인덱스 |
+| partial-index.md | UTIL | 부분 인덱스 (WHERE 조건 포함) |
+| explain-analyze.md | PG 공식 | EXPLAIN ANALYZE 읽는 법 |
+| slow-query.md | PG 공식 | pg_stat_statements + 슬로우 쿼리 |
+| vacuum-autovacuum.md | PG 공식 | VACUUM / Autovacuum 설정 |
+| transaction-isolation.md | PG 공식 | 격리 수준 (RC/RR/Serializable) |
+| locking.md | PG 공식 | Row-level locking, deadlock |
+
+## 핵심 참조 원칙 (principles/common.md 연결)
+
+- Index design → DB G.3 인덱스 의도 주석
+- EXPLAIN ANALYZE → be-perf N+1 진단
+- Transaction isolation → DB G.1 트랜잭션 경계
+- Locking → be-perf lock contention 카테고리

package/assets/dev-guide/be/sources/sre-book/INDEX.md

@@ -0,0 +1,48 @@
+---
+title: Google SRE Book 문서 인덱스
+fetched: 예정 (2026-05-18 스캐폴드)
+license: CC BY-NC-ND 4.0 (https://sre.google/books/)
+priority: 2 (출처 우선순위)
+---
+
+# Google SRE Book
+
+> Site Reliability Engineering — Google의 운영 철학. SLO, Error Budget, Toil, Observability.
+
+## 출처
+
+| URL | 설명 |
+|-----|------|
+| https://sre.google/sre-book/table-of-contents/ | SRE Book (온라인) |
+| https://sre.google/workbook/table-of-contents/ | SRE Workbook (온라인) |
+
+## 라이선스
+
+Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 (CC BY-NC-ND 4.0)
+상업적 이용 및 변형 금지. 내부 참조 학습 목적으로만 사용.
+
+## 수집일
+
+예정 (2026-05-18 스캐폴드)
+
+## 참조 우선순위
+
+2 (common.md 출처 우선순위)
+
+## 문서 목록 (수집 예정)
+
+| 파일명 (예정) | 챕터 | 주제 |
+|--------------|------|------|
+| ch04-slo.md | 4 | SLOs — Service Level Objectives |
+| ch06-monitoring.md | 6 | Monitoring Distributed Systems |
+| ch12-on-call.md | 12 | Effective On-Call |
+| ch17-testing.md | 17 | Testing for Reliability |
+| ch26-data-integrity.md | 26 | Data Integrity |
+| red-method.md | 참조 | RED Method (Rate/Errors/Duration) |
+| four-golden-signals.md | 참조 | 4 Golden Signals |
+
+## 핵심 참조 원칙 (principles/common.md 연결)
+
+- 4 Golden Signals (latency, traffic, errors, saturation) → Observability C.2 RED Method
+- SLO / Error Budget → Performance F.1 SLO 명시 의무
+- Monitoring → Observability C.1 구조화 로그

package/assets/dev-guide/fe/README.md

@@ -0,0 +1,197 @@
+# fe-guide — 사내 프론트엔드 스킬 (Claude + Codex)
+
+> AI 코딩 에이전트가 사내 합의된 FE 원칙대로 *구현 / 리뷰 / 성능 진단* 하게 만드는 스킬 번들.
+> 단일 소스 (이 폴더), 양쪽 어댑터 (Claude SKILL.md / Codex AGENTS.md).
+
+## 1. 무엇이 들어있는가
+
+```
+fe-guide/
+├─ sources/          # 원본 코퍼스 (수집일 2026-05-18)
+│  ├─ toss-ff/         Toss Frontend Fundamentals 4원칙 19파일
+│  ├─ react/           React 19 + Compiler + RSC 11파일
+│  ├─ vue/             Vue 3 + Pinia + Nuxt 9파일
+│  ├─ perf/            web.dev (Core Web Vitals 2024 INP) + Next.js 16 캐싱 11파일
+│  └─ a11y-dx/         WCAG 2.2 + Chrome/React DevTools 5파일
+├─ principles/       # 합의 원칙 (코퍼스 위에서 사내 의사결정)
+│  ├─ common.md        프레임워크 중립 (4원칙 + Vitals + WCAG)
+│  ├─ react.md         React/Next 특화
+│  └─ vue.md           Vue/Nuxt 특화
+├─ skills/           # 실제 호출되는 스킬
+│  ├─ react/{fe-build,fe-review,fe-perf}/SKILL.md
+│  └─ vue/{fe-build,fe-review,fe-perf}/SKILL.md
+├─ adapters/
+│  ├─ build-agents-md.sh   SKILL.md → Codex AGENTS.md 변환
+│  └─ refresh.sh           코퍼스 재수집 워크플로우 (수동)
+└─ README.md
+```
+
+3개 스킬 × 2개 스택 = **6개 스킬**:
+
+| 스킬 | 호출 시점 | 무엇을 해주는가 |
+|------|-----------|----------------|
+| **fe-build** | "이 명세대로 구현해줘" | 명세→체크리스트→테스트 매핑 강제, 원칙대로 코드 작성 |
+| **fe-review** | "이 PR 리뷰해줘" | `[SEVERITY] file:line — 이슈` 형식 리뷰 |
+| **fe-perf** | "느려졌어 / 메모리 누는 것 같아" | DevTools 절차 + 흔한 패턴별 픽스 |
+
+## 2. Claude Code 사용법
+
+### 2.1 전역 설치 (모든 프로젝트에서 사용)
+
+```bash
+# 1. fe-guide 를 원하는 위치에 clone (또는 이미 받아둔 경로)
+export FE_GUIDE_ROOT=~/work/fe-guide   # 본인 환경에 맞게
+
+# 2. ~/.claude/skills 에 심볼릭 링크
+cd ~/.claude/skills
+ln -s "$FE_GUIDE_ROOT/skills/react/fe-build"  fe-build-react
+ln -s "$FE_GUIDE_ROOT/skills/react/fe-review" fe-review-react
+ln -s "$FE_GUIDE_ROOT/skills/react/fe-perf"   fe-perf-react
+ln -s "$FE_GUIDE_ROOT/skills/vue/fe-build"    fe-build-vue
+ln -s "$FE_GUIDE_ROOT/skills/vue/fe-review"   fe-review-vue
+ln -s "$FE_GUIDE_ROOT/skills/vue/fe-perf"     fe-perf-vue
+```
+
+이후 Claude Code 에서:
+```
+/fe-build-react  # 또는 자연어로 "fe-build-react 스킬로 이 명세 구현해줘"
+```
+
+### 2.2 프로젝트별 설치 (저장소에 묶어 배포)
+
+```bash
+cd <your-repo>
+mkdir -p .claude/skills
+ln -s "$FE_GUIDE_ROOT/skills/react/fe-build" .claude/skills/fe-build
+# 또는 git submodule / sparse-checkout 으로 fe-guide 자체를 묶음
+```
+
+`.claude/skills/` 의 SKILL.md 는 Claude Code 가 자동 인식.
+
+## 3. Codex CLI 사용법
+
+Codex 는 프로젝트 루트의 `AGENTS.md` (또는 `~/.codex/AGENTS.md` 전역) 를 읽음.
+
+### 3.1 AGENTS.md 생성
+
+```bash
+export FE_GUIDE_ROOT=~/work/fe-guide
+export FE_GUIDE_SOURCE="사내 공유 fe-guide v2026-05-18 (배포: <본인 이름>)"  # AGENTS.md 출처 표기용 (선택)
+
+cd <your-repo>
+"$FE_GUIDE_ROOT/adapters/build-agents-md.sh" react fe-build > AGENTS.md
+
+# 또는 여러 스킬 합치기:
+{
+  "$FE_GUIDE_ROOT/adapters/build-agents-md.sh" react fe-build
+  echo
+  "$FE_GUIDE_ROOT/adapters/build-agents-md.sh" react fe-review
+  echo
+  "$FE_GUIDE_ROOT/adapters/build-agents-md.sh" react fe-perf
+} > AGENTS.md
+```
+
+생성된 `AGENTS.md` 는 Codex 가 매 세션 자동 로딩. principles/sources 는 같은 폴더에서 직접 참조 가능 (저장소 안에 fe-guide 포함하거나 심볼릭 링크).
+
+### 3.2 sources/principles 도 같이 배포
+
+`AGENTS.md` 가 `principles/common.md`, `sources/toss-ff/*` 를 참조하므로:
+
+- **Option A** — `fe-guide/` 자체를 저장소에 git submodule 로 포함
+- **Option B** — 빌드 시 `cp -R fe-guide/{principles,sources} <repo>/.fe-guide/` (배포물)
+- **Option C** — 사내 npm 패키지로 배포 후 `node_modules/@company/fe-guide`
+
+권장: **A (submodule)** — 버전 명시적, AI가 직접 참조 가능.
+
+## 4. 사용 시나리오 예시
+
+### 4.1 fe-build
+
+```
+사용자: 첨부한 요구사항 명세대로 주문 상세 페이지 구현해줘.
+       /fe-build-react
+
+AI: ## 체크리스트
+    - [ ] R-01: "옵션은 그리드/셀렉트 두 종류이며, 셀렉트는 옵셔널이다"
+    - [ ] R-02: "..."
+    ...
+    빠진 항목이 있으면 알려주세요. 없으면 매핑표 → TDD 들어갑니다.
+```
+
+### 4.2 fe-review
+
+```
+사용자: PR #123 리뷰. 요구사항 명세는 attached.
+       /fe-review-react
+
+AI: ## 리뷰 요약
+    - 변경: 8 files +312 -45
+    - HIGH 3, MED 5, LOW 2 / 머지 차단
+
+    [HIGH] src/pages/order/OrderForm.tsx:88 — select 옵션 옵셔널인데 검증에서 차단
+    ...
+```
+
+### 4.3 fe-perf
+
+```
+사용자: 주문 페이지에서 옵션 선택할 때 INP가 480ms 나와. 잡아줘.
+       /fe-perf-react
+
+AI: ## INP 진단
+    - 분류: CPU/렌더 병목
+    - 측정 절차: web-vitals/attribution 로 inputDelay/processing/presentation 분해...
+    - 가설: 핸들러 안 동기 필터링
+    - 검증 후 픽스: startTransition + useDeferredValue
+```
+
+## 5. 유지보수
+
+### 5.1 코퍼스 갱신
+
+외부 사이트 (react.dev, web.dev 등) 가 자주 바뀌므로 **월 1회 수동 갱신** 권장:
+
+```bash
+./adapters/refresh.sh --check   # 마지막 수집 날짜 확인
+./adapters/refresh.sh           # 재수집 절차 안내
+```
+
+재수집은 Claude/Codex 에이전트에게 위임이 가장 안정:
+
+```
+sources/<dir>/INDEX.md 의 출처들을 최신화해서 같은 형식으로 재저장해줘
+```
+
+### 5.2 principles 수정 시
+
+`principles/*.md` 는 사내 합의 문서. 수정 시:
+1. 출처 (sources/ 또는 외부 URL) 명시
+2. 변경 이력 PR 로 남김
+3. 영향받는 SKILL.md 의 참조 위치 확인
+
+### 5.3 새 스킬 추가
+
+`skills/<stack>/<name>/SKILL.md` 한 파일 추가 + `adapters/build-agents-md.sh` 그대로 사용.
+
+## 6. 출처 우선순위 (충돌 시)
+
+코퍼스 간 충돌 발생 시 `principles/common.md` 에 명시된 순서 적용:
+
+1. Toss FF (코드 품질 4원칙)
+2. web.dev (성능 임계값)
+3. WCAG 2.2 (접근성)
+4. React.dev / Vue.js / Nuxt (프레임워크 공식)
+5. Vercel / Meta engineering (벤더 권장)
+
+사용자 영향 우선순위: **a11y > perf > 가독성**.
+
+## 7. 라이선스 / 출처 주의
+
+- Toss FF: Apache-2.0 (frontend-fundamentals)
+- React.dev / web.dev: CC BY 4.0
+- Vue.js / Nuxt: MIT
+- 사내 배포 시 각 코퍼스 원본 출처 보존 (sources/<dir>/INDEX.md 에 명시됨)
+
+## 8. 관련 문서
+
+- fe-build/fe-review 의 "명세→체크리스트→테스트 매핑" 강제는 다수의 실패 사례에서 도출된 패턴 — 표시(UI 분기)와 검증(로직 분기) 불일치 회피가 핵심.

package/assets/dev-guide/fe/adapters/build-agents-md.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# build-agents-md.sh
+#
+# Claude SKILL.md (frontmatter + body) 를 Codex AGENTS.md 형식으로 변환.
+#
+# 사용법:
+#   ./adapters/build-agents-md.sh react fe-build > /path/to/project/AGENTS.md
+#   ./adapters/build-agents-md.sh vue fe-review
+#
+# 동작:
+#   1. skills/<stack>/<skill>/SKILL.md 읽음
+#   2. YAML frontmatter (name, description) 떼어내고 본문만 추출
+#   3. AGENTS.md 표준 헤더로 감싸고 stdout 출력
+#
+# Codex CLI 는 프로젝트 루트의 AGENTS.md 를 자동으로 읽음 (또는 ~/.codex/AGENTS.md 전역).
+# Claude Code 는 SKILL.md 를 직접 사용 (skill loader 가 frontmatter 인식).
+
+set -euo pipefail
+
+if [[ $# -lt 2 ]]; then
+  echo "Usage: $0 <stack> <skill>" >&2
+  echo "  stack: react | vue" >&2
+  echo "  skill: fe-build | fe-review | fe-perf" >&2
+  exit 1
+fi
+
+STACK="$1"
+SKILL="$2"
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+SKILL_FILE="$ROOT/skills/$STACK/$SKILL/SKILL.md"
+
+if [[ ! -f "$SKILL_FILE" ]]; then
+  echo "Error: $SKILL_FILE not found" >&2
+  exit 2
+fi
+
+# frontmatter 파싱: 첫 --- 부터 두번째 --- 사이가 YAML
+NAME=$(awk '/^---$/{c++; next} c==1 && /^name:/ {sub(/^name:[[:space:]]*/,""); print; exit}' "$SKILL_FILE")
+DESC=$(awk '/^---$/{c++; next} c==1 && /^description:/ {sub(/^description:[[:space:]]*/,""); print; exit}' "$SKILL_FILE")
+
+# 본문: 두번째 --- 이후
+BODY=$(awk '/^---$/{c++; next} c>=2 {print}' "$SKILL_FILE")
+
+cat <<EOF
+# ${NAME:-$SKILL}
+
+> ${DESC:-FE engineering guide for $STACK}
+>
+> Generated from \`skills/$STACK/$SKILL/SKILL.md\` on $(date +%Y-%m-%d).
+> Source of truth: ${FE_GUIDE_SOURCE:-fe-guide (OSS skill bundle — set FE_GUIDE_SOURCE to override)}
+
+## When to apply
+
+When working on $STACK code in this repository, follow the guidance below.
+You can also load the principles via:
+
+- \`principles/common.md\` — framework-neutral rules
+- \`principles/$STACK.md\` — $STACK-specific rules
+
+---
+
+$BODY
+EOF

package/assets/dev-guide/fe/adapters/refresh.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# refresh.sh
+#
+# 코퍼스 재수집 — 이벤트 기반 (주기 X).
+# 코드 컨벤션은 잘 안 바뀐다. 갱신이 필요한 건 다음 이벤트 발생 시:
+#
+#   1. React 메이저 버전 릴리스 (예: 19 → 20)
+#   2. Next.js 메이저 버전 릴리스 (예: 16 → 17)
+#   3. Vue/Nuxt 메이저 버전 릴리스
+#   4. web.dev Core Web Vitals 변경 (예: 2024 FID → INP 교체)
+#   5. WCAG 개정 (2.2 → 3.0 등, W3C 권고 발표)
+#   6. Toss FF / Vercel / Google a11y 가이드 큰 개정 (블로그 공지)
+#
+# 사용법:
+#   ./adapters/refresh.sh          # 이벤트 체크리스트 + 각 이벤트별 갱신 절차 출력
+#   ./adapters/refresh.sh --check  # 코퍼스 마지막 수집 날짜 확인 (감시용)
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+SOURCES="$ROOT/sources"
+
+if [[ "${1:-}" == "--check" ]]; then
+  echo "코퍼스 마지막 수집 날짜:"
+  for dir in "$SOURCES"/*/; do
+    name=$(basename "$dir")
+    if [[ -f "$dir/INDEX.md" ]]; then
+      date=$(grep -m1 -oE 'fetched: *[0-9]{4}-[0-9]{2}-[0-9]{2}' "$dir/INDEX.md" | awk '{print $2}' || echo "unknown")
+      count=$(find "$dir" -name "*.md" ! -name "INDEX.md" | wc -l | tr -d ' ')
+      printf "  %-12s  fetched=%s  files=%s\n" "$name" "$date" "$count"
+    else
+      printf "  %-12s  (INDEX.md 없음)\n" "$name"
+    fi
+  done
+  exit 0
+fi
+
+cat <<'EOF'
+=== fe-guide 코퍼스 갱신 — 이벤트 트리거 ===
+
+코드 컨벤션은 잘 안 바뀐다. 주기 갱신 X, 아래 이벤트 발생 시에만 해당 디렉토리 갱신.
+
+┌─ 이벤트 ────────────────────────┬─ 갱신 대상 ──────────────────┬─ 영향받는 principles ─┐
+│ React 메이저 (19→20 등)         │ sources/react/               │ principles/react.md   │
+│ Next.js 메이저 (16→17 등)       │ sources/perf/06-09.md        │ principles/react.md   │
+│ Vue 메이저 (3→4) / Nuxt 메이저  │ sources/vue/                 │ principles/vue.md     │
+│ web.dev Core Web Vitals 변경    │ sources/perf/01-03.md        │ principles/common.md B│
+│ WCAG 개정 (2.2→3.0 등)          │ sources/a11y-dx/wcag22-*.md  │ principles/common.md C│
+│ Toss FF 신규 챕터 / 큰 개정     │ sources/toss-ff/             │ principles/common.md A│
+│ Chrome DevTools 큰 UI 변경      │ sources/a11y-dx/chrome-*.md  │ (스킬 fe-perf 절차)  │
+└─────────────────────────────────┴─────────────────────────────┴───────────────────────┘
+
+체크 절차 (이벤트 발생 의심 시):
+  1. ./refresh.sh --check        # 마지막 수집 날짜 확인
+  2. 위 표에서 해당 행 식별
+  3. Claude/Codex 에이전트에 위임 (가장 안정):
+       "fe-guide/sources/<dir>/INDEX.md 의 출처들을 최신화해서 같은 형식으로 재저장해줘"
+  4. 갱신 후 영향받는 principles/*.md 검토 → 합의 원칙 변경 필요한지 판단
+  5. principles 변경 시 PR 로 이력 남김 (사내 합의 문서)
+
+이벤트 모니터링 (선택):
+  - React/Next 릴리스: github.com/facebook/react/releases, vercel/next.js/releases (RSS)
+  - Vue/Nuxt: github.com/vuejs/core/releases, nuxt/nuxt/releases
+  - web.dev/WCAG: web.dev/blog RSS, w3.org/WAI/standards-guidelines/wcag/
+
+권장: 큰 이벤트는 보통 한미국·유럽 컨퍼런스 시즌(React Conf, Next.js Conf, Google I/O)에 발표됨.
+     그 직후 1주 안에 --check 한 번 돌리고 위 표 매칭이면 갱신.
+EOF

package/assets/dev-guide/fe/principles/common.md

@@ -0,0 +1,160 @@
+---
+title: 공통 FE 원칙 (프레임워크 중립)
+version: 2026-05-18
+sources:
+  - sources/toss-ff/
+  - sources/perf/
+  - sources/a11y-dx/
+---
+
+# 공통 FE 원칙
+
+> 모든 프론트엔드 코드(React/Vue/Vanilla)에 적용되는 합의 원칙.
+> 프레임워크 특화 가이드는 [`react.md`](./react.md), [`vue.md`](./vue.md) 참조.
+
+## 출처 우선순위 (충돌 시)
+
+1. **코드 품질**: Toss Frontend Fundamentals 4원칙 (가독성 > 예측성 > 응집도 > 결합도 순으로 검토)
+2. **성능**: web.dev Core Web Vitals 임계값 (LCP ≤ 2.5s, INP ≤ 200ms, CLS ≤ 0.1)
+3. **접근성**: WCAG 2.2 AA (2023.10 W3C 권고)
+4. 충돌 시 — 사용자 영향 큰 쪽 우선 (a11y > perf > 가독성).
+
+---
+
+## A. 코드 품질 4원칙 (Toss FF 기반)
+
+각 원칙은 **트레이드오프 관계**다. 동시 만족 불가능 시 위 우선순위로 판단.
+
+### A.1 가독성 (Readability) — 최우선
+
+- **같이 실행되지 않는 코드는 분리**한다. 권한별 분기 한 컴포넌트 → 권한별 컴포넌트.
+  근거: `sources/toss-ff/readability-submit-button.md`
+- **구현 상세는 추상화**한다. 로그인 체크 로직 노출 → `<AuthGuard>` 래퍼.
+  근거: `sources/toss-ff/readability-login-start-page.md`
+- **로직 종류에 따라 함수를 쪼갠다**. "페이지 전체 쿼리파람 훅" 같은 다목적 훅 금지 → 파라미터별 독립 훅.
+  근거: `sources/toss-ff/readability-use-page-state.md`
+- **복잡한 조건에 이름 붙인다**. 중첩 `filter().some()` 익명 → `const isSameCategory = ...`.
+  근거: `sources/toss-ff/readability-condition-name.md`
+- **매직 넘버에 이름 붙인다**. `delay(300)` → `const ANIMATION_DELAY_MS = 300`.
+- **시점 이동을 줄인다**. 3단계 이상의 객체 참조 추적 → 인라인 또는 1단계로 평탄화.
+- **삼항 단순화**. 중첩 삼항 금지 → IIFE + early return.
+- **수학 부등식 순서**. `b <= a && a <= c` (a를 가운데에).
+
+### A.2 예측 가능성 (Predictability)
+
+- **이름 충돌 회피**. 라이브러리 이름과 동일한 `http` 등 → `httpService.getWithAuth` 같은 구분자 부착.
+- **같은 종류 함수는 반환 타입 통일**. 모든 데이터 훅은 React Query/SWR 등 *Query 객체* 반환으로 통일.
+- **숨은 로직을 드러낸다**. `fetchBalance` 안에 logging 숨김 금지 → fetch는 fetch만, logging은 호출 측.
+
+### A.3 응집도 (Cohesion)
+
+- **함께 수정되는 파일은 같은 디렉토리에**. 모듈 종류별 flat 구조(`/components`, `/hooks`) 지양 → 도메인별 (`/order/components`, `/order/hooks`).
+- **같이 변하는 상수는 한곳에 묶는다**. 애니메이션 길이 같은 결합 값을 분리하면 한쪽만 수정되는 버그 발생.
+- **폼 응집 전략을 의도적으로 선택한다**. 필드 단위(react-hook-form) vs 폼 전체(zod) — 검증 요구사항에 따라.
+
+### A.4 결합도 (Coupling)
+
+- **책임 하나씩 관리**. 통합 훅은 수정 영향 범위가 폭발한다 → 책임별 분리.
+- **중복을 허용하라**. 유사해 보이는 두 바텀시트의 공통화는 페이지별 분기를 만든다 → 차라리 중복.
+  근거: `sources/toss-ff/coupling-use-bottom-sheet.md` (반직관적이지만 매우 중요)
+- **Props Drilling 제거**. 3단 이상 prop 전달 → Composition (`children`) 또는 Context.
+
+---
+
+## B. 성능 (Core Web Vitals 2024)
+
+### B.1 임계값 (75퍼센타일 기준)
+
+| 지표 | Good | Poor | 측정 시점 |
+|------|------|------|-----------|
+| **LCP** (Largest Contentful Paint) | ≤ 2.5s | > 4.0s | 로드 |
+| **INP** (Interaction to Next Paint) | ≤ 200ms | > 500ms | 인터랙션 |
+| **CLS** (Cumulative Layout Shift) | ≤ 0.1 | > 0.25 | 로드~수명 |
+
+> **INP는 2024년 3월 FID를 대체했다.** FID는 첫 입력만 봤지만 INP는 페이지 수명 전체의 모든 인터랙션 응답성을 본다.
+
+### B.2 LCP 개선 우선순위 (4 하위 구성 요소)
+
+근거: `sources/perf/03-lcp-cls.md`, `sources/perf/10-optimize-lcp.md`
+
+1. **TTFB** (서버 응답 + 리다이렉트) — 평균 40%
+2. **Resource Load Delay** (LCP 자원 발견까지) — `<link rel="preload">`, `fetchpriority="high"`
+3. **Resource Load Time** (다운로드) — 이미지 최적화, CDN
+4. **Render Delay** (렌더링) — 클라이언트 측 렌더링 최소화
+
+### B.3 INP 개선
+
+근거: `sources/perf/02-inp.md`
+
+- **Input Delay → Processing → Presentation Delay** 3단계 중 가장 큰 단계 식별
+- 200ms 이상 Long Task 분할: `scheduler.yield()` (지원 시) 또는 `setTimeout(0)`
+- 이벤트 핸들러 안의 동기 작업 최소화. React 18+ 는 `startTransition`으로 우선순위 낮춤.
+
+### B.4 CLS 방지
+
+- 이미지/iframe/광고에 `width`/`height` 명시 (또는 CSS `aspect-ratio`)
+- 동적 콘텐츠 삽입은 `min-height` 예약
+- 폰트 `font-display: optional` 또는 `size-adjust` 사용
+
+### B.5 네트워크/네비게이션 (선택)
+
+- **Speculation Rules API** — `<script type="speculationrules">` 로 즉시 페이지 전환 (Chrome 109+)
+  근거: `sources/perf/04-speculation-rules.md`
+- **View Transitions API** — 페이지 전환 애니메이션 (Same-doc: Chrome 111+, Cross-doc: Chrome 126+)
+  근거: `sources/perf/05-view-transitions.md`
+
+---
+
+## C. 접근성 (WCAG 2.2 AA)
+
+근거: `sources/a11y-dx/wcag22-new-criteria.md`
+
+### C.1 필수 (Level A/AA, 2.2 신규 9개 중 핵심)
+
+| SC | 요건 | 코드/CSS 영향 |
+|----|------|---------------|
+| **2.4.11 Focus Not Obscured** (AA) | 포커스 받은 요소가 sticky header/footer에 가려지면 안 됨 | `scroll-padding-top` 등으로 보정 |
+| **2.5.8 Target Size Minimum** (AA) | 인터랙티브 영역 최소 24×24 CSS px | 버튼/링크 `min-width/height: 24px` |
+| **3.2.6 Consistent Help** (A) | 도움말 메커니즘의 위치/순서 일관성 | 헤더/푸터 도움말 위치 고정 |
+| **3.3.7 Redundant Entry** (A) | 같은 정보 재입력 요구 금지 | 폼 자동 채움, autocomplete 속성 |
+| **3.3.8 Accessible Authentication** (AA) | 인지 기능 의존 인증 금지 (CAPTCHA 등 대체 제공) | 패스키/생체/2FA 옵션 |
+| **2.5.7 Dragging Movements** (AA) | 드래그 동작은 단일 포인터 대체 제공 | 드래그 슬라이더에 + / − 버튼 병행 |
+
+### C.2 기존 핵심 (1.x / 2.x — 위반 시 즉시 픽스)
+
+- **1.1.1 Non-text Content** — `<img alt>`, 장식 이미지는 `alt=""`
+- **1.3.1 Info & Relationships** — 시멘틱 HTML (`<button>` vs `<div onClick>`)
+- **1.4.3 Contrast (Minimum)** — 본문 4.5:1, 큰 글자 3:1
+- **2.1.1 Keyboard** — 모든 기능 키보드 접근 가능
+- **4.1.2 Name, Role, Value** — 폼 컨트롤 `<label>` 또는 `aria-label`
+
+---
+
+## D. 안티패턴 카탈로그 (리뷰에서 즉시 [HIGH] 잡아라)
+
+| 안티패턴 | 근거 | 픽스 |
+|----------|------|------|
+| 빈 catch 블록 | global rules/anti-pattern | 최소 로그 또는 re-throw |
+| 50줄 초과 함수 | global rules | 책임별 분리 |
+| 중첩 깊이 5+ | global rules | early return |
+| 같은 파일 3+회 수정 | global rules | 전체 재설계 |
+| 명세 옵셔널 항목을 검증 로직에서 필수 취급 | 표시(UI)와 검증(로직) 불일치 → 라이브 데모 즉시 적발 | 명세→체크리스트→테스트 라인 매핑 |
+| 매직 넘버 인라인 | FF 가독성 | 상수로 추출 |
+| 통합 훅 (모든 쿼리파람 등) | FF 결합도 | 책임별 분리 |
+| Props 3단 드릴링 | FF 결합도 | Composition 또는 Context |
+| 라이브러리 이름 재사용 (`http`, `axios`, `query`) | FF 예측성 | 구분자 부착 |
+| 이미지 `width/height` 없음 | CLS | 명시 또는 `aspect-ratio` |
+| `<div onClick>` 버튼 흉내 | WCAG 1.3.1, 2.1.1 | `<button>` 사용 |
+| 포커스 안 보이는 `outline: none` | WCAG 2.4.7 | `:focus-visible` 별도 스타일 |
+
+---
+
+## E. 워크플로우 원칙 (메타)
+
+> 근거: 명세 위반으로 인한 코드 리뷰/과제 실패 패턴 누적 관찰.
+
+1. **명세 → 체크리스트 → 코드 + 테스트 라인 매핑표** 를 우선 작성. 장문 ARCHITECTURE 문서보다 가치 있음.
+2. **임의 UX 결정은 명세 100% 충족 후에만**. 명세가 모호한 부분은 *결정 전에* 명시적으로 질문.
+3. **명세에서 "옵셔널"이라고 한 항목은 반드시 "안 골라도 통과" 테스트 작성**. 표시(UI 분기)와 검증(로직 분기)이 같은 진실을 보는지 점검.
+4. **README/주석이 자랑하는 패턴(discriminated union, 특정 아키텍처 이름)과 실제 코드 결함 공존을 경계**. 자랑한 패턴은 가장 먼저 검증.
+5. **도메인 직관이 명세 위에 올라가는 순간을 경계**. "당연히 이래야 한다" 가 등장하면 명세를 다시 펴라.