코드 정제 프로세스

구리 정제 비유: 0.1% 구리 → 99.9% 순수 구리까지 다단계 정제 적용

개요

AI 코딩의 한계를 보완하기 위한 4단계 정제 프로세스. 각 단계마다 명확한 기준과 체크리스트를 통해 코드 품질을 점진적으로 향상.

AI 코딩 한계와 정제 보완도

한계	증상	정제 보완
토큰 한계	긴 대화 시 컨텍스트 손실	SKILL.md 분리로 70% 보완
이해 범위	전체 프로젝트 맥락 파악 어려움	규칙 파일로 60% 보완
일관성 부족	세션마다 다른 스타일	템플릿으로 50% 보완
장기 메모리	이전 세션 기억 못함	handover로 40% 보완
보안 인식	취약점 놓침	보안 점검으로 보완 필요

AI 자동화 난이도 표시

표시	난이도	의미	예시
●	쉬움	AI 단독 처리 가능	코드 포맷팅, import 정리
●●	보통	AI 제안, 인간 확인 필요	리팩토링, 타입 정의
●●●	어려움	인간 판단 필수	아키텍처 결정, 비즈니스 로직
●●●●	매우 어려움	인간 주도, AI 보조	보안 설계, 성능 최적화 전략

4단계 정제 프로세스

초벌 개발 (Phase 1-4) → 1차 정제 (구조) → 2차 정제 (품질) → 최종 정제 (성능/보안)
      20%                    40%              70%                90%+

정제 흐름도

┌─────────────────────────────────────────────────────────────────────────┐
│                         초벌 개발 (Phase 1-4)                            │
│                                                                         │
│  • 기능 동작 확인                                                        │
│  • TODO/FIXME, 더미 데이터 허용                                          │
│  • "일단 동작하게" 단계                                                  │
└─────────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼ Q-12
┌─────────────────────────────────────────────────────────────────────────┐
│  1차 정제 (구조)                                             AI 난이도: ●● │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │  • any 타입 제거                                                 │   │
│  │  • 미사용 import 정리                                            │   │
│  │  • 코드-DB 스키마 동기화 ← AI가 자주 놓침!                        │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼ Q-13
┌─────────────────────────────────────────────────────────────────────────┐
│  2차 정제 (품질)                                          AI 난이도: ●●● │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │  • React CRITICAL 이슈 0개                                       │   │
│  │  • 에러 핸들링 완성                                              │   │
│  │  • 로딩/에러 상태 UI                                             │   │
│  │  • TODO/FIXME 0개                                                │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼ Q-14
┌─────────────────────────────────────────────────────────────────────────┐
│  최종 정제 (보안/성능)                                   AI 난이도: ●●●● │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │  • 보안 점검 통과 (CRITICAL 0개)                                  │   │
│  │  • console.log 제거                                              │   │
│  │  • 환경 변수 노출 없음                                           │   │
│  │  • 번들 최적화 완료                                              │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                              배포 준비 완료                              │
└─────────────────────────────────────────────────────────────────────────┘

1단계: 초벌 개발 (Phase 1-4)

목표: 기능 동작 확인 - "일단 동작하게" 단계

허용 사항

TODO/FIXME 주석 사용
더미 데이터 사용
임시 console.log
any 타입 허용
긴 함수 허용

완료 기준

모든 페이지 렌더링 됨
핵심 기능 동작 확인
에러 없이 빌드 됨

2단계: 1차 정제 - 구조 (Q-12)

목표: 코드 구조 정리 - AI 난이도 ●●

체크리스트

미구현 정리 ●

더미 데이터 실제 데이터로 교체
임시 하드코딩 제거
비활성 기능 제거 또는 구현

타입 정리 ●●

any 타입 0개
명시적 타입 정의
인터페이스 분리

Import 정리 ●

사용하지 않는 import 제거
import 순서 정렬
barrel imports 최적화

코드-DB 스키마 동기화 ●●●

주의: AI가 자주 놓치는 항목. 개발 중 기능 변경 시 DB 스키마가 과거 상태로 남아 혼란 유발

사용하지 않는 DB 컬럼/테이블 제거
코드에서 삭제된 기능의 DB 스키마 정리
타입 정의와 DB 스키마 일치 확인
마이그레이션 파일 정리 (중복/충돌 제거)

점검 방법:

1. 코드에서 실제 사용하는 테이블/컬럼 목록 추출
2. DB 스키마의 테이블/컬럼 목록과 비교
3. 차이점 = 데드 스키마 (삭제 대상)

흔한 예시:

이미지 업로드 기능 제거 → image_url 컬럼 여전히 존재
리뷰 기능 변경 → 과거 리뷰 관련 테이블 잔존
사용자 필드 삭제 → DB에 deprecated_field 남음

명령어

이 프로젝트 구조 정제 점검해줘 (Q-12)

3단계: 2차 정제 - 품질 (Q-13)

목표: 코드 품질 향상 - AI 난이도 ●●~●●●

체크리스트

React 품질 ●●

CRITICAL 이슈 0개
HIGH 이슈 0개
불필요한 리렌더 제거

에러 처리 ●●

모든 API 호출에 try-catch
사용자 친화적 에러 메시지
에러 경계 설정

UI 상태 ●●

로딩 상태 UI 구현
에러 상태 UI 구현
빈 상태 UI 구현

주석 정리 ●

TODO 0개 (처리 또는 이슈 등록)
FIXME 0개 (모두 수정)
불필요한 주석 제거

명령어

이 프로젝트 품질 정제 점검해줘 (Q-13)

4단계: 최종 정제 - 성능/보안 (Q-14)

목표: 배포 준비 완료 - AI 난이도 ●●●~●●●●

체크리스트

보안 점검 ●●●●

성능 최적화 ●●●

번들 사이즈 최적화
이미지 최적화
폰트 최적화
캐싱 전략 적용

정리 ●

console.log 제거
debugger 제거
주석 처리된 코드 제거

환경 분리 ●●

개발/프로덕션 환경 변수 분리
API 엔드포인트 확인
테스트 데이터 제거

명령어

이 프로젝트 최종 정제 점검해줘 (Q-14)

정제 상태 요약 (Q-15)

출력 형식

📋 정제 상태 요약

| 단계 | 상태 | 미완료 항목 |
|------|------|------------|
| 1차 정제 (구조) | ✅ 완료 | - |
| 2차 정제 (품질) | ⚠️ 진행중 | TODO 3개 |
| 최종 정제 (보안) | ❌ 미시작 | 전체 |

전체 진행률: 60%

다음 작업:
1. TODO 3개 처리 → 2차 정제 완료
2. 보안 점검 시작

명령어

이 프로젝트 정제 상태 요약해줘 (Q-15)

참고

상세 보안 점검 → security-check.md
품질 점검 명령어 → commands/12-quality-check.md
AI 한계 문서 → 05-code-quality/ai-coding-limits/