Claude Code로 React/TypeScript 프론트엔드 만들기: 실전 가이드 (2026)

Claude Code로 React/TS 프론트엔드를 만들 수 있나요?

네, Claude Code는 단일 컴포넌트부터 테스트와 성능 튜닝을 포함한 완전한 기능까지, 완성된 React/TypeScript 프론트엔드를 만들 수 있어요. 아직 고민 중이시라면 이게 짧은 답이에요. 하지만 코드를 붙여넣는 챗봇보다 왜 더 잘 해내는지 이해하려면, Claude Code가 무엇이 다른지 알아야 해요.

Claude Code는 에이전트형 CLI예요. 복사할 조각을 던져 주는 대신, 프로젝트 트리를 직접 읽고, 여러 파일을 한 번에 열고, 사양대로 편집한 다음, 명령(개발 서버, 테스트, 타입체크)을 실행하고 그 출력을 읽어 계속 고쳐요. 이 "저장소를 읽고 → 편집하고 → 실행하고 → 에러를 읽고 → 다시 고치는" 루프가 바로 React/TS에 잘 맞는 이유예요. 실제 프론트엔드 프로젝트는 언제나 서로 얽힌 조각들을 갖고 있으니까요. 새 컴포넌트는 다른 파일의 타입이 필요하고, 올바른 import가 필요하고, 기존 테마와 기존 테스트에 맞아야 해요. 프롬프트 하나만 보는 모델은 이런 제약을 볼 수 없지만, Claude Code는 프로젝트 전체를 컨텍스트로 쥐고 있으니 볼 수 있어요.

실제로는 변경할 때마다 타입체크와 테스트를 돌리게 할 때 가장 강력해요. 잘못된 타입이나 깨진 import가 빌드 시점에 물어뜯을 때까지 기다리지 않고 같은 세션 안에서 드러나거든요. 완전히 처음이라면, 먼저 Claude Code가 무엇이고 어떻게 동작하는지를 읽고 에이전트 모델을 잡은 다음 뛰어드세요.

설정: Claude Code 설치 + React/TS 프로젝트 scaffold

첫 프롬프트를 치기 전에 세 가지: Claude Code 설치, React-TS 껍데기 scaffold, 그리고 프로젝트 디렉터리 안에서 Claude Code 실행.

1. Claude Code를 설치하세요. OS별 안내는 Claude Code 설치 방법 가이드를 참고하세요. 설치되면 claude --version을 실행해 CLI가 준비됐는지 확인해요.
2. Vite + React + TypeScript 앱을 만드세요. Vite는 React SPA를 위한 가볍고 기본적인 선택이에요:

npm create vite@latest my-app -- --template react-ts
cd my-app
npm install
npm run dev

이걸로 src/ 구조, TypeScript 설정, 그리고 localhost:5173의 개발 서버가 준비돼요. SPA가 아니라 Next.js를 노린다면, 맨 끝의 FAQ를 참고하세요.

1. 저장소 안에서 Claude Code를 여세요. 프로젝트 루트에서 실행하세요:

claude

Claude Code는 package.json과 tsconfig.json을 보고 이것이 React-TS 프로젝트임을 인식해요. 여기서부터는 평이한 한국어로 지시하면 돼요. 작은 습관 하나: 실제 작업을 넘기기 전에 Read the src/ structure and summarize the stack in use라고 요청해, 프로젝트를 정말 "이해"하는지 확인하세요.

React/TS 프로젝트용으로 CLAUDE.md 설정하기

이건 경쟁사 셋 중 둘이 건너뛰는 단계지만, 이후 모든 것의 품질을 좌우해요. CLAUDE.md는 Claude Code가 매 세션 자동으로 읽는 파일로, 매 프롬프트마다 스택과 규칙을 반복하지 않도록 한 번만 써 두는 "프로젝트 규약"이라고 생각하세요. 프론트엔드라면 실용적인 템플릿은 이렇게 생겼어요:

# CLAUDE.md - React/TS project

## Stack
- Vite + React 19 + TypeScript (strict mode)
- Styling: Tailwind CSS (or MUI v7 - pick one, don't mix)
- Data: TanStack Query; Routing: TanStack Router
- Testing: Vitest + React Testing Library

## Code conventions
- Functional components + hooks only. No class components.
- TypeScript strict: NO `any`. If a type is unclear, ask first.
- Absolute imports via the `@/` alias (already set in tsconfig).
- Every component has explicit prop types (a `XxxProps` interface).
- Complex components ship with a test.

## Workflow
- Before editing multiple files, outline a short plan for me to approve.
- After each change: run `npm run typecheck` and the relevant tests.
- Don't install new dependencies without asking.

가장 값진 줄은 "no any", "absolute imports", "run typecheck after every change"예요. 이 줄들은 제약이 없을 때 Claude Code가 저지르기 쉬운 실수를 정확히 막아 줘요. 이 파일 작성법을 더 깊이 파고들려면 CLAUDE.md 완전 가이드를 참고하세요. 프론트엔드 작업의 핵심은 이거예요: 스택과 "수락하기 전에 diff를 검토한다"는 규칙을 더 명확히 고정할수록, 출력은 매번 표류하지 않고 프로젝트 스타일에 맞춰져요.

첫 React/TS 컴포넌트 생성하기(실제 워크스루)

여기가 핵심이에요. 프롬프트를 어떻게 쓰느냐가 결과의 80%를 결정해요. 좋은 프롬프트는 목표만이 아니라 스택 + 제약 + 처리해야 할 상태를 명시해요. 비교해 볼게요:

• 약한 프롬프트: "UserCard 컴포넌트를 만들어 줘." → Claude Code는 props를 추측하고, 스타일링을 추측하고, 혼자 라이브러리를 끌어올 수도 있어요.
• 좋은 프롬프트: "src/components/에 UserCard 컴포넌트를 만들어 줘. 타입 지정 props: user(id, name, avatarUrl, role), isLoading, error. 로딩 중엔 스켈레톤 표시; 에러 시엔 메시지 표시; 기존 테마로 Tailwind 스타일링. 기본 테스트 파일 추가. 새 의존성은 추가하지 마."

두 번째 프롬프트라면 Claude Code는 보통 한 번에 전부 만들어요: UserCard.tsx, props 인터페이스, 세 개의 렌더 분기(loading/error/data), 그리고 UserCard.test.tsx. 생성되는 인터페이스의 예:

interface User {
 id: string;
 name: string;
 avatarUrl: string;
 role: string;
}

interface UserCardProps {
 user?: User;
 isLoading?: boolean;
 error?: string | null;
}

절대 건너뛰면 안 되는 단계: 수락하기 전에 diff를 검토하세요. Claude Code는 변경을 파일별 diff로 보여줘요. 꼼꼼히 읽으세요 — import가 실제로 존재하는지, 다른 파일을 몰래 건드렸는지, 타입이 any로 느슨해졌는지 확인해요. 만족스러운 부분은 수락하고 나머지는 고쳐 달라고 하세요(예: "스켈레톤을 별도 컴포넌트로 빼 줘"). 수락한 뒤엔 그 세션 안에서 npm run typecheck와 테스트를 돌리게 하세요.

상태, 데이터 페칭 & 라우팅

2026년의 현대적인 React 프로젝트에서는 Claude Code가 곧장 Redux를 기본값으로 삼게 두지 마세요. 대부분의 경우 더 군더더기 없는 패턴은 이거예요: 로컬 상태엔 hooks, 서버 상태엔 TanStack Query, 내비게이션엔 TanStack Router, 그리고 전역 상태(Zustand/Context)는 정말 여러 분기에서 공유되는 상태가 있을 때만 손대세요.

Suspense를 통해 로딩/에러를 내장한 페치 훅을 생성하는 예시 프롬프트:

Create a `useUser(id)` hook using TanStack Query `useSuspenseQuery`,
fetching from /api/users/:id and returning a typed User.
Wrap UserCard in a <Suspense fallback> and an error boundary.
Don't create global state.

useSuspenseQuery(TanStack Query v5)는 데이터가 준비될 때까지 컴포넌트 렌더링을 "서스펜드"시켜, 로딩 상태를 부모의 <Suspense>로 끌어올려요. if (isLoading)를 여기저기 흩뿌리는 대신이라, 눈에 띄게 깔끔한 코드가 돼요(TanStack Query 문서, 2026 참고). 위임할 때의 규칙: "서버 상태는 Query에 넣고, 전역 스토어에 쑤셔 넣지 마"라고 분명히 말하세요. 안 그러면 Claude Code는 필요 없는 큰 스토어로 과하게 설계하는 경향이 있어요.

스타일링 & 반응형(디자인 시스템, 다크 모드)

Claude Code는 컴포넌트를 빠르게 스타일링하지만, 막지 않으면 태연히 색과 여백을 하드코딩해요. 디자인 시스템을 강제하는 방법: CLAUDE.md에 토큰/테마만 쓴다고 선언하고, 프롬프트에서 구체적으로 지정하세요.

• 토큰을 지키고 하드코딩하지 않기: "기존 설정의 Tailwind 클래스를 써(여백과 색은 테마에서); 생 hex 값은 쓰지 마." MUI v7이라면: "sx와 테마로 스타일링하고, theme.palette를 쓰고, 색은 하드코딩하지 마."
• 반응형: 원하는 브레이크포인트를 명시하세요 — "모바일에선 한 열, 768px 이상에선 두 열로 전환."
• 다크 모드: 기존 테마 변수 / dark: 클래스를 쓰라고 요청하고, 병행하는 테마 메커니즘을 새로 만들게 하지 마세요.

여기서도 diff를 검토하고, 새 UI 라이브러리를 슬쩍 끼워 넣었는지 확인하세요. 미학과 경험 쪽을 더 깊이 파고들고 싶다면, Claude Code로 UI/UX 디자인하기 글이 세련되고 일관된 인터페이스를 만드는 데 특화돼 있어요.

컴포넌트의 테스트 & 접근성

이건 경쟁 글들의 큰 사각지대예요. 테스트와 a11y를 지나가듯 언급만 하거든요. 하지만 컴포넌트의 진짜 라이프사이클엔 둘 다 들어가요. Claude Code가 테스트를 잘 쓰는 건, 바로 그걸 실행하고 초록이 될 때까지 계속 고칠 수 있기 때문이에요.

Vitest + React Testing Library로 테스트하기. 효과적인 프롬프트는 커버할 분기를 또렷이 적어요:

Write tests for UserCard with Vitest + React Testing Library:
- render loading state -> shows a skeleton
- render with a user -> shows name and role
- render with an error -> shows the error message
Run the tests and fix until they pass.

생성되는 테스트 케이스의 예:

it('shows a message when there is an error', () => {
 render(<UserCard error="Failed to load" />);
 expect(screen.getByText('Failed to load')).toBeInTheDocument();
});

접근성. 여기가 상기시키지 않으면 Claude Code가 잊기 쉬운 곳이에요. 컴포넌트가 동작하면 곧바로 직접적인 작업을 넘기세요: "UserCard의 접근성을 감사하고 고쳐 줘: role/aria가 적절한지, 아바타 이미지에 alt 텍스트가 있는지, 키보드로 조작 가능한지, 색 대비가 충분한지 확인해." 그러면 alt를 추가하고, 올바른 aria-label/role을 붙이고, 포커스를 조정해요. 그래도 실제로 컴포넌트를 Tab으로 훑으며 확인하세요 — a11y는 "맞겠지" 하고 넘어가기 쉬워요.

성능 최적화(지연 로딩, memo, 번들)

앱이 커지면 Claude Code에 최적화를 요청하세요 — 다만 성급하지 않게, 의도적으로.

• 라우트 기반 코드 분할: React.lazy + <Suspense>로 페이지별로 번들을 나눠, 필요한 것만 불러와요(React 문서 - lazy, 2026 참고). 프롬프트: "라우트를 React.lazy + Suspense로 옮겨 번들을 분할해 줘."
• 효과 있는 곳에 메모이제이션: 비싼 계산엔 useMemo, 안정적인 props로 자주 다시 렌더되는 컴포넌트엔 memo. 전부 감싸지 마세요 — 무심한 메모이제이션은 얻는 것보다 비쌀 수 있어요.
• 낭비되는 재렌더 찾기: "<컴포넌트 목록>에서 불필요한 재렌더를 찾아 수정안을 제안해 줘." Claude Code는 컴포넌트 트리 전체를 읽을 수 있어, 추측 대신 실제 원인을 짚어 줘요.

단도직입적인 경고: 너무 이른 최적화는 더 빨라진다는 보장도 없이 코드를 읽기 어렵게 만들어요. 측정(번들 크기, React DevTools Profiler)해서 진짜 문제가 있다고 확인한 뒤에만 최적화하세요.

미리 만들어진 프론트엔드 스킬로 더 빠르게(AgentKit)

프로젝트마다 CLAUDE.md를 다시 쓰고, React/TS 규약을 고정하고, "Suspense를 써", "테마를 지켜"라고 매번 상기시키는 건 지겨워요. 지름길이 있어요: 미리 만들어진 프론트엔드 스킬을 쓰는 거예요. 구체적으로, AgentKit의 ak-frontend-development 스킬은 현대적인 React/TS 패턴 — 함수 컴포넌트, React.lazy/Suspense, useSuspenseQuery, MUI v7, TanStack Router — 을 묶어 둬서, 매번 다시 설명하지 않아도 Claude Code가 곧바로 적용해요.

혼동을 피하려면: 여기서 AgentKit은 Claude Code용 키트(agentkit.best, ak CLI)이지 "OpenAI의 AgentKit"이 아니에요. 큰 그림부터 잡으려면 AgentKit이 무엇이고 값어치가 있는지를 참고하세요. 스킬이라는 개념이 처음이라면 Claude Code의 스킬이 무엇인지를 읽어 보세요. ak-frontend-development 스킬은 Engineer Kit에 들어 있어요. 전체 분해는 Engineer Kit 리뷰(ak-frontend-development 스킬 포함)에 있어요.

Claude Code가 React를 잘못 만들 때는? 흔한 실패 유형

정직함이야말로 경쟁사가 피하는 부분이에요. Claude Code는 완벽하지 않아요 — 약점을 미리 알아 두면 옳은 곳을 지킬 수 있어요.

• 환각 import / 잘못된 라이브러리 버전. 설치하지 않은 패키지에서 import하거나, 옛 버전의 API를 쓸 수 있어요(예: 프로젝트가 v5인데 React Query v4 패턴). 방어: CLAUDE.md에 버전을 고정하고, 즉시 타입체크를 돌리게 하세요 — 깨진 import가 곧장 드러나요.
• 과잉 설계. 단순한 폼에 상태 머신이 통째로 붙을 수 있어요. 방어: 원하는 복잡도를 명시하세요("단순하게, 새 라이브러리 없이").
• 프롭 드릴링. context/컴포지션을 쓰지 않고 여러 층에 props를 계속 넘겨요. 방어: 컴포넌트 트리가 깊어지면 아키텍처 리뷰를 요청하세요.
• 접근성 잊기. 위에서 말했듯 — a11y는 프롬프트하지 않으면 기본적으로 빠지기 쉬워요.
• 낡은 React API. 때때로 Suspense/Query 대신 구식 useEffect 데이터 페칭에 손을 뻗어요. 방어: CLAUDE.md에 현대적 패턴을 고정하세요.

모든 방어를 관통하는 한 줄기: 바로 diff를 검토하고 테스트/타입체크를 돌리며, 맹목적으로 수락하지 마세요. 이건 "AI 슬롭" — 돌아가지만 지저분하고 유지보수하기 힘든 코드 — 을 피하는 데도 도움이 돼요.

자주 묻는 질문(FAQ)

Claude Code가 npm run dev와 테스트를 스스로 실행하나요?

네. Claude Code는 프로젝트 안에서 터미널 명령을 실행해요 — 개발 서버 시작, 테스트 실행, 타입체크 — 그런 다음 출력을 읽어 스스로 고쳐요. 변경할 때마다 테스트/타입체크를 요청하는 습관을 들여, 버그가 일찍 드러나게 하세요.

Vite만이 아니라 Next.js에도 쓸 수 있나요?

둘 다요. Claude Code는 특정 프레임워크에 묶이지 않아요. 프로젝트가 잘 구성돼 있다면 Next.js, Vite, Remix, React Native와 함께 동작해요. 올바른 규약을 따르게 하려면 CLAUDE.md에 프레임워크를 선언하기만 하세요(예: Next.js의 App Router).

쓰기 전에 React를 알아야 하나요?

알아야 해요. Claude Code는 코드를 빠르게 쓰지만, diff를 읽고, 어디서 틀렸는지 짚고, 올바른 제약을 걸려면 충분한 React/TS 지식이 필요해요. 완전한 초보자도 배울 수는 있지만, 이해하지 못하는 코드를 수락하지 마세요 — 그게 풀기 어려운 버그의 근원이에요.

Cursor나 VS Code와 함께 쓸 수 있나요?

네. Claude Code는 CLI라서 어떤 에디터와도 나란히 동작해요. 많은 개발자가 에이전트 작업(여러 파일 생성/편집, 테스트 실행)은 Claude Code에 맡기고, 읽고 손보기 위해 VS Code를 열어 둬요. 두 도구는 서로를 보완해요.

낡은 코드나 잘못된 라이브러리 버전을 어떻게 피하나요?

CLAUDE.md에 특정 버전을 고정하고, 즉시 타입체크를 돌리게 하고, 원하는 현대적 패턴(Suspense, TanStack Query v5)을 또렷이 적으세요. 낡은 API에 손을 뻗는 걸 보면 지적하고, 최신 문서로 업데이트하라고 말하세요.

프론트엔드 작업을 위한 미리 만들어진 스킬이 있나요?

네. AgentKit의 ak-frontend-development 스킬(Engineer Kit, agentkit.best)은 현대적 React/TS 패턴을 묶어 둬서, 프로젝트마다 규약을 설정하지 않아도 Claude Code가 곧바로 적용해요. 이건 Claude Code용 AgentKit으로, OpenAI의 AgentKit과는 달라요.

결론 + 다음 단계

워크플로는 반복 가능한 여섯 단계로 요약돼요: 설치 + scaffold → CLAUDE.md 작성 → 범위를 좁힌 프롬프트로 컴포넌트 생성하고 항상 diff 검토 → TanStack Query/Router로 상태/데이터 추가 → 테스트하고 a11y 수정 → 필요할 때 성능 최적화. 핵심은 "더 긴 프롬프트"가 아니라 명확한 제약 + diff 검토 + 바로 테스트 실행이에요. 다음은: 인터페이스를 끌어올리려면 Claude Code로 UI/UX 디자인하기를 읽고, 풀스택 앱을 위해 Claude Code로 백엔드 API 만들기와 짝지으며, 변경을 커밋할 때는 Claude Code의 git 워크플로를 표준화하세요. 아직 환경을 설정하는 중인가요? Claude Code 설치로 돌아가세요. 그리고 프론트엔드 구축이 매일의 일이라면, 미리 만들어진 스킬이 담긴 AgentKit 번들 — 지금 $149($198에서)가 반복 설정을 꽤 많이 덜어 줄 거예요.