코드 품질 규칙 (Code Quality Rules)

버전: 2.0 | 최종 업데이트: 2026-01-29 React 성능 최적화 + UI/UX 점검 + AI 코딩 협업 가이드

📋 개요

🔥 React Best Practices (45개 룰)

카테고리별 우선순위

CRITICAL 카테고리 상세

1. Eliminating Waterfalls (async-)

• async-defer-await - await를 실제 사용하는 분기로 이동
• async-parallel - 독립 작업에 Promise.all() 사용
• async-dependencies - 부분 의존성에 better-all 사용
• async-api-routes - API 라우트에서 promise 일찍 시작
• async-suspense-boundaries - Suspense로 콘텐츠 스트리밍

2. Bundle Size Optimization (bundle-)

• bundle-barrel-imports - barrel 파일 대신 직접 import
• bundle-dynamic-imports - 무거운 컴포넌트에 next/dynamic
• bundle-defer-third-party - hydration 후 analytics 로드
• bundle-conditional - 기능 활성화 시에만 모듈 로드
• bundle-preload - hover/focus 시 preload

점검 명령어

이 프로젝트 React 성능 점검해줘.

이 프로젝트 번들 사이즈 점검해줘.

이 프로젝트 API 호출 waterfall 점검해줘.

이 컴포넌트 리렌더 최적화 점검해줘.

React 성능 점검하고 수정까지 해줘.

🎨 Web Design Guidelines (UI/UX)

점검 카테고리

점검 명령어

이 프로젝트 UI/UX 점검해줘.

이 페이지 접근성 점검해줘.

이 폼 UX 점검해줘.

이 프로젝트 다크모드 점검해줘.

📊 품질 점검 흐름도

┌─────────────────────────────────────────────────────────────────────────┐
│                           "React 성능 점검해줘"                          │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  우선순위 1: Waterfall 제거                                    [CRITICAL] │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │  • async-parallel: 병렬 데이터 패칭                             │   │
│  │  • async-suspense-boundaries: Suspense 경계                     │   │
│  │  • async-dependencies: 의존성 최적화                            │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  우선순위 2: 번들 최적화                                       [CRITICAL] │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │  • bundle-dynamic-imports: 동적 임포트                          │   │
│  │  • bundle-barrel-imports: 배럴 임포트 최적화                    │   │
│  │  • bundle-defer-third-party: 서드파티 지연                      │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  우선순위 3~8: 서버/클라이언트/렌더링/리렌더/고급/JS           [HIGH~LOW] │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │  • 총 45개 룰 순차 점검                                         │   │
│  │  • 05-code-quality/react-best-practices/rules/ 참조             │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                              점검 결과 출력                              │
│                                                                         │
│  ✅ 통과: 35개                                                          │
│  ⚠️ 경고: 7개                                                           │
│  ❌ 수정 필요: 3개                                                       │
└─────────────────────────────────────────────────────────────────────────┘

📁 파일 구조

05-code-quality/
├── README.md                      ← 이 파일
│
├── react-best-practices/          ← React/Next.js 성능 최적화
│   ├── SKILL.md                   ← 빠른 참조
│   ├── AGENTS.md                  ← 전체 가이드 (상세)
│   ├── README.md
│   └── rules/                     ← 개별 룰 파일들 (45개)
│       ├── async-*.md             ← Waterfall 관련
│       ├── bundle-*.md            ← 번들 관련
│       ├── server-*.md            ← 서버 관련
│       ├── client-*.md            ← 클라이언트 관련
│       ├── rerender-*.md          ← 리렌더 관련
│       ├── rendering-*.md         ← 렌더링 관련
│       ├── js-*.md                ← JS 최적화
│       └── advanced-*.md          ← 고급 패턴
│
├── web-design-guidelines/         ← UI/UX 점검
│   └── SKILL.md                   ← UI/UX 가이드
│
└── ai-coding-limits/              ← AI 코딩 협업
    └── README.md                  ← AI 한계, Best Practices

🔧 사용 방법

1. 전체 프로젝트 점검

이 프로젝트 React 성능 점검해줘.

05-code-quality/react-best-practices/SKILL.md 읽고
우선순위 순서대로 체크해줘.

2. 특정 카테고리만 점검

이 프로젝트 번들 사이즈 점검해줘.

05-code-quality/react-best-practices/rules/ 에서
bundle-*.md 룰들 기준으로 체크해줘.

3. 점검 후 자동 수정

React 성능 점검하고 수정까지 해줘.

1. 05-code-quality/react-best-practices/ 기준으로 점검
2. CRITICAL 이슈부터 자동 수정
3. 수정 전/후 diff 보여주기

4. 정제 프로세스 점검 (NEW)

이 프로젝트 구조 정제 점검해줘. (Q-12)
이 프로젝트 품질 정제 점검해줘. (Q-13)
이 프로젝트 최종 정제 점검해줘. (Q-14)
이 프로젝트 정제 상태 요약해줘. (Q-15)

정제 프로세스 상세: refining-process.md

📋 출력 예시

React 성능 점검 결과

📋 React 성능 점검 결과

🔴 CRITICAL 이슈

1. bundle-barrel-imports 위반
   - 파일: src/components/Icons.tsx:3
   - 현재: import { Check, X } from 'lucide-react'
   - 수정: import Check from 'lucide-react/dist/esm/icons/check'
   - 영향: 200-800ms 로딩 시간 절약

2. async-parallel 위반
   - 파일: src/app/api/data/route.ts:12
   - 현재: 순차적 await 3개
   - 수정: Promise.all() 사용
   - 영향: ~2초 → ~0.7초

🟡 HIGH 이슈
...

📊 요약
- CRITICAL: 2개
- HIGH: 1개
- MEDIUM: 3개

수정 진행할까요?

UI/UX 점검 결과

📋 UI/UX 점검 결과

🔴 접근성 이슈

1. aria-label 누락
   - 파일: src/components/IconButton.tsx:15
   - 현재: <button><Icon /></button>
   - 수정: <button aria-label="닫기"><Icon /></button>

2. 키보드 접근 불가
   - 파일: src/components/Dropdown.tsx:42
   - 현재: onClick만 있음
   - 수정: onKeyDown 추가 (Enter, Escape)

🟡 폼 이슈

1. autocomplete 누락
   - 파일: src/components/LoginForm.tsx:23
   - 수정: <input type="email" autoComplete="email" />

📊 요약
- 접근성: 2개
- 폼: 1개

수정 진행할까요?

← 체계 목차