시리즈: Claude Code 실전 정복 | 4편
작성자: 체리플랜 | 7년차 프론트엔드 개발자
- 1편: [설치 + 첫 실행]
- 2편: [VS Code 연동 + 실전 워크플로우]
- 3편: [CLAUDE.md 완전 정복]
컴포넌트 하나 만들려고 디자인 고민하고, props 구조 잡고, 스타일 입히고 — 이게 생각보다 오래 걸리잖아요.
저도 그랬어요. cherryplan 허브 프로젝트 시작할 때, 9개 미니앱을 다 만들어야 한다는 게 막막했어요. 앱 하나당 컴포넌트가 최소 3~5개는 나오는데, 45개 컴포넌트를 다 직접 처음부터 짜야 하면 언제 끝나나 싶었거든요.
Claude Code 쓰고 나서 달라진 건 이거예요. 첫 컴포넌트 하나를 제대로 만들어서 디자인 시스템을 잡아두면, 나머지는 그 기준으로 쭉 만들어줘요. 색상, 폰트, 간격, 인터랙션 — 다 일관성 있게 나와요.
이번 편에서는 제가 실제로 만든 AI Diary 컴포넌트와 Movie Log 컴포넌트를 예시로, Claude Code로 React 컴포넌트 만드는 실전 방법을 정리할게요.
Claude Code로 컴포넌트 만드는 핵심 원리
https://cherryplan.netlify.app/ai-diary
🍒 CherryPlan
cherryplan.netlify.app
2026년 기준으로 Claude Code와 React를 함께 쓰는 방식이 확립됐어요.
Claude Code는 컴포넌트를 만들 때 기존 코드베이스를 먼저 분석하고, 실제 파일을 읽고 패턴을 파악한 뒤 작업해요. 추상적인 설명보다 실제 코드 레퍼런스를 보여줄 때 결과물 품질이 확 올라가요.
그래서 제가 쓰는 방법이 이거예요. 첫 컴포넌트를 제대로 만들고, 그걸 레퍼런스로 나머지를 만들기.
cherryplan 허브에서 처음에 대표 컬러(#FF6B8A 체리 핑크)와 전체 디자인 톤을 잡아놓은 첫 컴포넌트를 만들었어요. 그다음부터는 "이 컴포넌트랑 같은 디자인 시스템으로 만들어줘"라고 하면 색상, 간격, 컴포넌트 구조가 전부 일관성 있게 나왔어요. 이게 제일 컸어요.
실전 1: AI Diary 컴포넌트 만들기
AI Diary는 일기를 쓰면 Claude API가 감정 분석과 피드백을 해주는 앱이에요.
컴포넌트 구조:
- DiaryEditor — 일기 입력 영역
- DiaryFeedback — AI 피드백 표시
- DiaryList — 과거 일기 목록
- DiaryCard — 개별 일기 카드
Step 1: 프로젝트 구조 파악 요청
현재 cherryplan 허브 프로젝트 구조 봐줘.
src/apps/ 안에 새로 AiDiary 폴더 만들 건데,
기존 앱들이랑 같은 패턴으로 구조 잡아줘.
기존 컴포넌트 하나 읽어보고 패턴 파악한 다음 제안해줘.
코드 작성 전에 먼저 계획 보여줘.
Claude Code가 기존 Budget/ 폴더 구조를 읽고 이렇게 제안했어요:
src/apps/AiDiary/
├── AiDiary.jsx # 메인 컴포넌트
├── DiaryEditor.jsx # 입력 영역
├── DiaryFeedback.jsx # AI 피드백
├── DiaryList.jsx # 목록
├── DiaryCard.jsx # 카드
└── useDiary.js # 커스텀 훅
패턴 파악하고 바로 제안해줬어요. 제가 따로 폴더 구조 설명 안 해도 기존 코드 읽어서 맞춰준 거예요.
Step 2: 첫 컴포넌트 작성 — 디자인 레퍼런스 제공
DiaryEditor 컴포넌트 만들어줘.
기존 Budget 컴포넌트 읽어보고 같은 디자인 시스템 적용해줘.
- 체리 핑크(#FF6B8A) 포인트 컬러
- 다크 네이비(#0D1117) 배경
- part-addon.css 유틸 클래스 사용
- 함수형 컴포넌트
- textarea + 글자수 카운터 + 제출 버튼 포함
Step 3: API 연동 컴포넌트
DiaryFeedback 컴포넌트 만들어줘.
Claude API 호출 결과를 받아서 표시하는 컴포넌트야.
props:
- feedback: string (API 응답 텍스트)
- isLoading: boolean (로딩 상태)
- emotion: string (감정 태그)
로딩 중엔 스켈레톤 UI, 완료되면 애니메이션으로 나타나게 해줘.
디자인은 DiaryEditor랑 같은 시스템으로.
여기서 좋았던 게, "DiaryEditor랑 같은 시스템으로"라고만 해도 Claude Code가 이미 만든 파일을 참조해서 일관성 있게 만들어줬어요.
Step 4: 커스텀 훅으로 로직 분리
useDiary.js 만들어줘.
DiaryEditor, DiaryFeedback, DiaryList에서 공통으로 쓰는 상태랑 로직 분리해줘.
포함할 것:
- 일기 목록 (localStorage)
- 새 일기 저장 함수
- Claude API 호출 함수
- 로딩 상태 관리
API 키는 환경변수에서 가져오게 해줘.
Claude Code는 커스텀 훅 작성에 특히 강해요. useEffect cleanup, 의존성 배열, 메모이제이션까지 챙겨줘요. 직접 쓸 때 놓치기 쉬운 부분들이에요.
실전 2: Movie Log — TMDB API 연동 컴포넌트
Movie Log는 TMDB API로 영화·드라마를 검색하고 시청 기록을 남기는 앱이에요. API 연동이 들어가서 조금 더 복잡했는데, Claude Code가 이 부분에서 제일 빛났어요.
TMDB API 연동 컴포넌트 요청
MovieSearch 컴포넌트 만들어줘.
TMDB API (https://api.themoviedb.org/v3) 연동할 거야.
기능:
- 검색어 입력 → 디바운스 300ms → API 호출
- 검색 결과 그리드 표시 (포스터, 제목, 평점)
- 로딩 스피너
- 에러 처리
API 키: process.env.VITE_TMDB_API_KEY
언어: ko-KR
성인 콘텐츠: 제외
기존 컴포넌트 디자인 시스템 유지.
계획 먼저 보여줘.
여기서 Claude Code가 디바운스 훅까지 같이 만들어줬어요. 제가 따로 요청하지 않았는데 "검색 최적화를 위해 useDebounce 훅을 별도로 만들겠습니다"하고 알아서 추가했어요.
https://cherryplan.netlify.app/movie-log
🍒 CherryPlan
cherryplan.netlify.app
성능 최적화까지 자동으로
2026년 기준 Vercel의 React 베스트 프랙티스에서 제일 강조하는 건 데이터 페칭 워터폴 제거예요. 순차적 API 호출이 쌓이면 600ms짜리 대기 시간이 생기는데, 이게 useMemo 최적화보다 훨씬 큰 영향을 미쳐요.
Claude Code가 MovieSearch 만들 때 알아서 이 패턴을 적용해줬어요. 검색 결과 이미지 lazy loading, API 호출 중복 방지, 에러 바운더리까지요. 제가 "성능 최적화해줘"라고 하지 않았는데 베스트 프랙티스를 알아서 적용해줬어요.
컴포넌트 일관성 유지하는 핵심 전략
9개 앱 만들면서 일관성 유지한 방법이에요.
1. 첫 컴포넌트가 디자인 시스템이다
가장 중요한 원칙이에요. Budget 컴포넌트를 제일 공들여 만들었어요. 색상, 간격, 버튼 스타일, 카드 디자인 — 이게 이후 8개 앱의 기준이 됐어요.
"기존 [컴포넌트명] 읽어보고 같은 디자인으로 만들어줘" — 이 한 줄이 디자인 가이드라인 문서보다 효과 있었어요.
2. @ 파일 참조로 할루시네이션 방지
특정 파일을 직접 참조하는 방식이 할루시네이션을 크게 줄여줘요. @src/components/Budget/BudgetCard.jsx 처럼 파일을 직접 지정하면 Claude Code가 실제 파일을 읽어서 패턴을 파악해요. 추상적인 설명 없이도 정확한 코드가 나와요.
@src/apps/Budget/BudgetCard.jsx 읽어보고
이랑 같은 패턴으로 DiaryCard.jsx 만들어줘.
3. 계획 먼저, 코드는 나중에
2편에서 다룬 워크플로우인데, 컴포넌트 작업에서 특히 중요해요.
계획 단계에서 20개의 결정을 미리 검토하면, 각 결정의 성공률이 80%에서 거의 100%로 올라가요. 계획 없이 바로 구현하면 20개 결정 전부 맞을 확률이 수학적으로 1% 수준이에요.
큰 컴포넌트 작업할 때는 Shift+Tab 두 번으로 Plan Mode 진입하는 것도 좋아요. 이 모드에서는 Claude Code가 코드를 쓰지 않고 분석과 계획만 해요.
4. 컴포넌트 단위로 커밋
이 컴포넌트 완성됐어.
변경된 파일 목록 알려주고
커밋 메시지 한국어로 작성해줘.
Claude Code가 git diff 보고 커밋 메시지까지 써줘요.
실제로 느낀 Claude Code의 컴포넌트 작업 강점
① 파일 간 의존성 파악
컴포넌트 수정할 때 관련된 다른 파일들도 같이 체크해줘요. "이 props 바꾸면 저기서도 수정 필요해요"라고 알려줘요. 7년 개발하면서 이 부분에서 사이드 이펙트 많이 겪었는데, Claude Code가 미리 잡아줄 때 진짜 편했어요.
② 대형 파일도 안 버벅여요
18,000줄짜리 React 컴포넌트도 Claude Code는 잘 처리해요. 다른 AI 코딩 툴들이 대형 파일에서 자주 실패하는 것과 비교되는 부분이에요.
③ 일관성 유지
같은 프로젝트에서 작업하면 자연스럽게 기존 패턴을 따라요. 다른 팀원이 만든 것처럼 따로 노는 코드가 안 나와요.
솔직한 한계
컴포넌트 복잡도가 올라갈수록 한 번에 완성되지 않을 수 있어요. 특히 복잡한 인터랙션이 들어가는 컴포넌트는 계획 → 1차 구현 → 피드백 → 수정의 반복이 필요해요.
그리고 디자인 감각은 제가 가이드 줘야 해요. "예쁘게 만들어줘"는 너무 추상적이에요. 색상값, 참조 컴포넌트, 구체적인 레이아웃 설명이 들어가야 원하는 결과가 나와요.
마무리: 첫 컴포넌트에 공들이세요
Claude Code로 컴포넌트 작업할 때 제일 중요한 거 하나만 기억하세요.
첫 컴포넌트를 제대로 만들면, 나머지는 그 기준으로 자동으로 맞춰져요.
디자인 시스템 문서 따로 안 만들어도, 컴포넌트 가이드라인 없어도 — 첫 컴포넌트가 살아있는 가이드라인이 돼요.
cherryplan 허브 9개 앱이 전부 같은 디자인 톤으로 나온 게 이 덕분이에요.
다음 포스팅 예고: [Claude Code 실전 정복 #5] 버그 잡기 — 콘솔 에러부터 Network 탭까지, 디버깅 실전