sam-react-prod/claudedocs/guides/[GUIDE] LARGE-FILE-WORKFLOW.md

대용량 파일 작업 워크플로우

개요

React → Next.js 디자인 마이그레이션 시 대용량 파일(>1000줄)을 체계적으로 처리하기 위한 프로토콜

트리거 조건

다음 조건 중 하나라도 해당되면 이 워크플로우를 적용:

• ✅ 파일 크기 >1000줄
• ✅ 여러 섹션/기능이 혼재된 복잡한 컴포넌트
• ✅ React → Next.js 디자인 정확 복제 작업
• ✅ 사용자가 명시적으로 "세밀한 작업" 또는 "정확한 복제" 요청

Phase 1: 사전 분석 (Pre-Analysis)

1-1. 파일 크기 확인 및 전략 수립

<1000줄: 일반 접근 (전체 파일 한 번에 처리)
1000-3000줄: 섹션별 분해 (3-4개 섹션)
>3000줄: 기능별 분해 (1000줄 단위)

1-2. 섹션 식별 및 라인 범위 파악

React 파일을 읽고 주요 섹션 구분:

## 섹션 분해 계획

| 섹션 | 라인 범위 | 예상 복잡도 | 체크포인트 수 |
|------|----------|------------|--------------|
| Header | 100-150 | 낮음 | 6개 |
| StatCards | 150-200 | 낮음 | 8개 |
| SearchFilter | 200-280 | 중간 | 10개 |
| Tabs+Table | 280-600 | 높음 | 15개 |
| DetailView | 600-1100 | 매우 높음 | 20개 |

Phase 2: 섹션별 6단계 워크플로우

각 섹션마다 순차적으로 아래 6단계 실행:

Step 1: 구조 파악 하기

목적: 컴포넌트의 구조적 뼈대 이해

체크리스트:

• 사용된 컴포넌트 목록 (Card, Button, Input 등)
• Props 구조 (어떤 데이터를 받는가)
• State 변수 (어떤 상태를 관리하는가)
• 자식 컴포넌트 계층 구조
• 조건부 렌더링 로직

출력 포맷:

## [섹션명] 구조 분석

### 컴포넌트 구성
- 최상위: Card
- 자식: CardHeader, CardContent, Button

### Props
- items: ItemMaster[]
- onItemClick: (id: string) => void

### State
- selectedType: string
- searchTerm: string

### 조건부 렌더링
- filteredItems.length === 0 → 빈 상태 메시지

Step 2: 기능 구현 하기

목적: 스타일 없이 순수 기능만 먼저 동작하게 만들기

원칙:

• ✅ 클릭 이벤트, 상태 변경 등 동작만 구현
• ❌ CSS 클래스는 최소한만 (레이아웃 깨지지 않을 정도)
• ✅ 데이터 바인딩, 필터링 로직 완성

예시:

// ✅ 좋은 예: 기능만 구현
<div>
  <input
    value={searchTerm}
    onChange={(e) => setSearchTerm(e.target.value)}
  />
  <button onClick={handleCreate}>등록</button>
</div>

// ❌ 나쁜 예: 스타일까지 구현
<div className="flex items-center justify-between gap-4 p-6 rounded-lg shadow-md">
  <input
    className="text-sm border rounded px-3 py-2"
    value={searchTerm}
    onChange={(e) => setSearchTerm(e.target.value)}
  />
</div>

Step 3: 기능 검증

목적: 스타일 전에 기능이 완벽히 동작하는지 확인

검증 항목:

• 클릭 이벤트가 정상 동작하는가
• 상태 변경이 UI에 반영되는가
• 데이터 필터링/정렬이 올바른가
• 조건부 렌더링이 정확한가
• 빌드 에러가 없는가

검증 방법:

npm run build  # 빌드 성공 확인
npm run dev    # 개발 서버로 동작 테스트

Step 4: 스타일 파악 하기

목적: React 코드의 정확한 CSS 클래스 체크리스트 작성

중요: 이 단계가 가장 중요! 모든 CSS 클래스를 빠짐없이 기록

체크리스트 작성 규칙:

1. 계층 구조 유지: 부모 → 자식 순서로 체크리스트 작성
2. 모든 클래스 기록: text-, font-, bg-, border- 등 모든 클래스
3. 부정 체크: font-bold ❌처럼 없어야 할 클래스도 명시
4. 반응형 포함: md:, lg: 같은 반응형 클래스도 모두 기록

체크리스트 템플릿:

## [섹션명] 스타일 체크리스트

### Container (최상위 div)
- [ ] className: `flex flex-col md:flex-row md:items-center justify-between gap-4`

### Icon Box
- [ ] div className: `p-2 bg-primary/10 rounded-lg hidden md:block`
- [ ] Icon className: `w-6 h-6 text-primary`

### Title Area
- [ ] Title wrapper: `flex items-center gap-2`
- [ ] h1 className: `text-xl md:text-2xl` ⚠️ font-bold ❌ (없어야 함)
- [ ] Badge className: `variant="secondary" gap-1`
- [ ] Badge Icon: `h-3 w-3`
- [ ] Version text: "v1.0.0" (3자리)

### Subtitle
- [ ] p className: `text-sm text-muted-foreground mt-1`

### Stats Card
- [ ] Label: `text-sm font-medium text-muted-foreground`
- [ ] Value: `text-3xl md:text-4xl font-bold mt-2` ⚠️ NOT text-2xl
- [ ] Icon: `w-10 h-10 md:w-12 md:h-12 opacity-15 ${iconColor}`

추출 방법:

# React 파일의 특정 라인 범위를 정확히 읽기
Read file_path="..." offset=1899 limit=30

Step 5: 스타일 구현 하기

목적: 체크리스트를 보며 CSS 클래스 1:1 정확 복제

원칙:

• ✅ 체크리스트의 모든 항목을 하나씩 확인하며 적용
• ✅ 클래스 순서도 가능한 동일하게 유지
• ❌ 추측하거나 비슷한 걸로 대체하지 않기

작업 방법:

1. 체크리스트 1번 항목 보기
2. Edit 도구로 해당 부분 수정
3. 체크리스트 2번 항목 보기
4. Edit 도구로 해당 부분 수정
... 반복

Step 6: 스타일 검증

목적: React와 Next.js 코드의 완전 일치 확인

검증 방법:

## 스타일 검증 결과

### Header Section

**React (라인 1899-1917)**:
```tsx
<h1 className="text-xl md:text-2xl">품목 관리</h1>

Next.js (현재 구현):

<h1 className="text-xl md:text-2xl">품목 관리</h1>

✅ 일치

---

React:

<p className="text-3xl md:text-4xl font-bold">{stat.value}</p>

Next.js:

<p className="text-2xl font-bold">{stat.value}</p>

❌ 불일치: text-3xl md:text-4xl 누락

**최종 빌드 검증**:
```bash
npm run build

---

Phase 3: 섹션 통합 검증

모든 섹션 완료 후:

1. 전체 페이지 빌드 성공
2. 모든 기능 정상 동작
3. React와 시각적 차이 없음
4. 반응형 동작 확인 (모바일, 태블릿, 데스크톱)

---

실전 예시: ItemManagement (2600줄)

파일 분석

파일: ItemManagement.tsx
크기: 2,600줄
전략: 섹션별 분해 (5개 섹션)

섹션 분해 계획

섹션	라인	복잡도	체크포인트
Header	1899-1917	낮음	6개
StatCards	1790-1816, 1920	낮음	8개
SearchFilter	1929-1950	중간	10개
Tabs+Table	1956-2300	높음	15개
DetailView	2300-2900	매우 높음	20개

작업 진행

✅ 1회차: Header (6단계 완료, 검증 통과)
✅ 2회차: StatCards (6단계 완료, 검증 통과)
✅ 3회차: SearchFilter (6단계 완료, 검증 통과)
🔄 4회차: Tabs+Table (진행 중...)
⏳ 5회차: DetailView (대기 중)

---

예상되는 실수 패턴 및 방지법

실수 1: 텍스트 사이즈 불일치

증상: text-2xl vs text-3xl md:text-4xl 원인: 체크리스트에서 반응형 클래스 누락 방지: 모든 md:, lg: 클래스도 체크리스트에 명시

실수 2: font-bold 유무

증상: 타이틀에 bold가 있어야 하는데 없거나, 없어야 하는데 있거나 원인: 부정 체크(❌)를 체크리스트에 안 적음 방지: "없어야 할 클래스"도 font-bold ❌ 형태로 명시

실수 3: opacity, shadow 같은 미세 스타일

증상: opacity-15 vs opacity-20, shadow-sm vs shadow-md 원인: 숫자까지 정확히 확인 안 함 방지: 체크리스트에 정확한 값까지 기록

실수 4: 컴포넌트 variant 불일치

증상: variant="default" vs variant="secondary" 원인: Props도 CSS처럼 체크해야 함 방지: variant, size 같은 Props도 체크리스트에 포함

---

워크플로우 메타 규칙

언제 이 워크플로우를 사용하는가?

1. 사용자가 "React와 똑같이" 요청
2. 파일이 1000줄 이상
3. 이전에 디테일을 놓친 경험이 있을 때
4. 사용자가 "체크리스트 방식으로" 명시

언제 사용하지 않는가?

1. 간단한 버그 수정 (<50줄)
2. 새로운 기능 추가 (참조할 React 코드 없음)
3. 리팩토링 작업
4. 사용자가 "대략적으로만" 요청

워크플로우 적용 선언

작업 시작 시 사용자에게 명시:

📋 대용량 파일 워크플로우 적용

파일: ItemCreate.tsx (1,200줄)
전략: 4개 섹션으로 분해
예상 시간: 40분

Section 1: FormHeader (진행 중...)

---

---

Phase 4: 복잡한 다중 작업 처리 프로토콜

개요

사용자가 여러 요구사항을 한 번에 제시할 때 누락 없이 체계적으로 처리하는 프로세스

트리거 조건

다음 중 하나라도 해당되면 이 프로토콜 적용:

• ✅ 3개 이상의 독립적인 수정 요청
• ✅ 여러 파일/섹션에 걸친 작업
• ✅ 복잡한 로직 변경 + UI 수정 혼재
• ✅ 사용자가 "여러 개 한번에" 또는 "전체적으로" 요청

Step 1: TodoWrite로 작업 분해 및 체크리스트 생성

원칙:

• 모든 요구사항을 독립적인 태스크로 분해
• 각 태스크는 검증 가능한 단위로 작성
• 작업 순서를 논리적으로 정렬 (의존성 고려)

예시 입력:

사용자: "구매부품 화면을 다음과 같이 수정해줘:
1. 품목명 선택 시 전원, 용량, 단위, 비고 표시
2. 전동개폐기는 220V/380V 선택
3. 모터는 용량 입력 + 전압 선택
4. 체인은 규격 선택 + 길이 입력
5. 품목코드 자동생성 로직 변경
6. 품목 상태를 품목코드 다음으로 이동"

TodoWrite 출력:

[
  {
    content: "요구사항 분석 및 파일 구조 파악",
    status: "in_progress",
    activeForm: "요구사항 분석 중"
  },
  {
    content: "품목명 선택 로직 확인 (기존 코드)",
    status: "pending",
    activeForm: "품목명 선택 로직 확인 중"
  },
  {
    content: "전원, 용량, 단위, 비고 필드 추가",
    status: "pending",
    activeForm: "필드 추가 중"
  },
  {
    content: "전동개폐기 전용 220V/380V 선택 구현",
    status: "pending",
    activeForm: "전동개폐기 필드 구현 중"
  },
  {
    content: "모터 전용 용량 입력 + 전압 선택 구현",
    status: "pending",
    activeForm: "모터 필드 구현 중"
  },
  {
    content: "체인 전용 규격 선택 + 길이 입력 구현",
    status: "pending",
    activeForm: "체인 필드 구현 중"
  },
  {
    content: "품목코드 자동생성 함수 수정",
    status: "pending",
    activeForm: "품목코드 로직 수정 중"
  },
  {
    content: "품목 상태 기존 위치 제거",
    status: "pending",
    activeForm: "품목 상태 제거 중"
  },
  {
    content: "품목 상태 새 위치(품목코드 다음)에 추가",
    status: "pending",
    activeForm: "품목 상태 추가 중"
  },
  {
    content: "전체 동작 검증 및 빌드 테스트",
    status: "pending",
    activeForm: "검증 중"
  }
]

Step 2: 순차적 실행 및 진행상황 업데이트

실행 규칙:

1. 한 번에 하나씩: 절대 여러 태스크를 동시에 처리하지 않음
2. 완료 후 체크: 각 태스크 완료 즉시 TodoWrite 업데이트
3. 명시적 보고: "✅ N번 완료, 다음 N+1번 시작" 형태로 진행상황 공유
4. 에러 처리: 실패 시 즉시 보고, 해결 후 재개

실행 흐름:

1. Task 1 시작
   → TodoWrite: status="in_progress"
   → 작업 수행
   → 검증
   → TodoWrite: status="completed"
   → 사용자에게 "✅ 1번 완료" 보고

2. Task 2 시작
   → TodoWrite: status="in_progress"
   → 작업 수행
   ...

Step 3: 중간 체크포인트 제시

5개 태스크마다 중간 보고:

## 진행상황 (5/10 완료)

✅ 완료:
1. 요구사항 분석 및 파일 구조 파악
2. 품목명 선택 로직 확인
3. 전원, 용량, 단위, 비고 필드 추가
4. 전동개폐기 전용 필드 구현
5. 모터 전용 필드 구현

🔄 진행 중:
6. 체인 전용 필드 구현

⏳ 대기 중:
7. 품목코드 자동생성 함수 수정
8. 품목 상태 기존 위치 제거
9. 품목 상태 새 위치 추가
10. 전체 검증

Step 4: 최종 완료 보고서

모든 태스크 완료 후:

## ✅ 전체 작업 완료

### 완료된 작업 요약
1. ✅ 품목명 선택 시 전원, 용량, 단위, 비고 표시 (line 990-1122)
2. ✅ 전동개폐기 220V/380V 선택 구현 (line 990-1032)
3. ✅ 모터 용량 입력 + 전압 선택 구현 (line 1035-1057)
4. ✅ 체인 규격 선택 + 길이 입력 구현 (line 1060-1084)
5. ✅ 품목코드 자동생성 로직 변경 (line 248-305)
6. ✅ 품목 상태 이동 완료 (line 1138-1159)

### 최종 확인사항
- [x] 품목명 미선택 시: 품목명만 표시
- [x] 전동개폐기 선택 시: 전원, 용량 정상 표시
- [x] 모터 선택 시: 용량 입력, 전압 선택 정상 표시
- [x] 체인 선택 시: 규격, 길이 정상 표시
- [x] 품목코드 자동생성 정상 작동
- [x] 품목 상태가 품목코드 다음에 위치
- [x] 빌드 에러 없음

### 변경된 파일
- `src/components/items/ItemForm.tsx` (6개 섹션 수정)

### 다음 작업 대기
모든 요구사항이 완료되었습니다. 추가 작업이 있으면 알려주세요.

실전 적용 예시

Before (기존 방식 - 누락 발생):

사용자: A, B, C, D 수정해줘
AI: (A만 수정하고 B, C, D 누락)

After (새 프로토콜 - 완벽 처리):

사용자: A, B, C, D 수정해줘

AI:
[TodoWrite 생성]
1. [ ] A 수정
2. [ ] B 수정
3. [ ] C 수정
4. [ ] D 수정

✅ 1/4 완료: A 수정 완료 (line 100-120)
✅ 2/4 완료: B 수정 완료 (line 200-250)
✅ 3/4 완료: C 수정 완료 (line 300-350)
✅ 4/4 완료: D 수정 완료 (line 400-450)

## 전체 작업 완료 보고서
[상세 내용...]

프로토콜 적용 기준

작업 복잡도	요구사항 수	TodoWrite 사용	중간 보고
단순 (1-2개)	1-2개	선택사항	불필요
보통 (3-5개)	3-5개	필수	권장
복잡 (6개+)	6개 이상	필수	필수

예외 처리

태스크 실패 시:

❌ 3/10 실패: 모터 필드 구현 중 에러 발생

**에러 내용**:
- TypeScript 타입 불일치 (line 1045)

**해결 방안**:
1. 타입 정의 확인
2. 수정 후 재시도

🔄 재시도 중...
✅ 3/10 완료: 모터 필드 구현 성공

의존성 문제 발견 시:

⚠️ 태스크 순서 변경 필요

**발견된 문제**:
- Task 5가 Task 3에 의존함

**재정렬**:
1. [x] Task 1
2. [x] Task 2
3. [ ] Task 3 (우선 처리)
4. [ ] Task 4
5. [ ] Task 5 (Task 3 완료 후)

---

버전 히스토리

• v1.0.0 (2025-01-14): 초기 버전 생성
• 이유: ItemListClient 작업 시 text-2xl/text-3xl, font-bold 같은 미세한 차이 놓침
• 목적: 체계적이고 완벽한 React → Next.js 마이그레이션
• v1.1.0 (2025-01-15): Phase 4 추가 - 복잡한 다중 작업 처리 프로토콜
• 이유: 여러 요구사항 동시 처리 시 누락 발생 방지
• 목적: TodoWrite 기반 체계적 작업 분해 및 순차 실행

---

관련 파일

프론트엔드

• src/components/items/ItemListClient.tsx - 품목 관리 리스트 페이지
• src/components/items/ItemForm.tsx - 품목 등록/수정 폼

참조 소스 (React 원본)

• sma-react-v2.0/src/components/ItemManagement.tsx - React 원본 파일 (2600줄)

참조 문서

• claudedocs/guides/[GUIDE] CSS-MIGRATION-WORKFLOW.md - CSS 마이그레이션 워크플로우