Claude Code로 코드를 작성하고, 리뷰하고, 리팩터링하는 핵심 워크플로우를 실전 예제와 함께 익힙니다.
Claude Code에 지시를 내릴 때, 프롬프트의 품질이 결과의 품질을 결정합니다. 좋은 프롬프트는 세 가지 요소를 갖춥니다.
맥락(Context): Claude가 현재 상황을 이해할 수 있는 배경 정보 의도(Intent): 달성하고자 하는 목표 제약(Constraints): 지켜야 할 조건이나 피해야 할 패턴
// 모호한 프롬프트
"로그인 기능 만들어 줘"
// 효과적인 프롬프트
"NextAuth.js v5를 사용해서 GitHub OAuth 로그인을 구현해 줘.
app/(auth)/login/page.tsx에 로그인 페이지를 만들고,
lib/auth/config.ts에 NextAuth 설정을 작성해 줘.
세션 정보는 서버 컴포넌트에서 접근할 수 있어야 해."
새 기능을 구현할 때는 큰 그림부터 설명하고, Claude가 구현 계획을 세우도록 하는 것이 효과적입니다.
사용자 프로필 페이지를 구현해 줘.
요구사항:
- app/profile/page.tsx에 프로필 페이지 생성
- 사용자 이름, 이메일, 가입일을 표시
- 프로필 이미지 업로드 기능 (S3 presigned URL 사용)
- 닉네임 수정 기능 (Server Action으로 처리)
- 반응형 레이아웃, Tailwind 사용
참고:
- DB 스키마는 lib/db/schema.ts 참고
- 기존 폼 컴포넌트는 components/ui/form.tsx 참고
Claude Code는 이 지시를 받으면 먼저 참조 파일을 읽어 기존 패턴을 파악한 뒤, 해당 패턴에 맞춰 코드를 생성합니다.
복잡한 기능은 한 번에 구현하지 말고 단계별로 진행하는 것이 좋습니다. 각 단계의 결과를 확인한 후 다음 단계로 넘어갑니다.
1단계: 프로필 페이지의 UI만 먼저 구현해 줘. 더미 데이터를 사용해서.
(결과 확인 후)
2단계: DB에서 실제 사용자 데이터를 가져오도록 수정해 줘.
(결과 확인 후)
3단계: 닉네임 수정 기능을 Server Action으로 추가해 줘.
한 번에 너무 많은 것을 요청하면 Claude가 잘못된 방향으로 갈 위험이 커집니다. 특히 복잡한 비즈니스 로직이 포함된 경우, 단계별 접근이 수정 비용을 크게 줄여 줍니다.
이미 존재하는 패턴을 따라 새 코드를 추가할 때는 참조할 파일을 명시합니다.
app/api/posts/route.ts를 참고해서
app/api/comments/route.ts를 만들어 줘.
같은 에러 처리 패턴과 응답 형식을 사용해 줘.
Git에서 변경된 내용을 Claude Code로 리뷰할 수 있습니다.
git diff --staged의 변경사항을 리뷰해 줘.
다음 관점에서 검토해 줘:
- 타입 안전성
- 에러 처리 누락
- 성능 문제
- 보안 취약점
비대화형 모드로 파이프라인에 통합할 수도 있습니다.
git diff --staged | claude -p "이 변경사항을 리뷰해 줘. 버그, 성능 문제, 보안 취약점을 중심으로."특정 PR의 전체 변경사항을 리뷰하는 것도 가능합니다.
현재 브랜치의 main 대비 모든 변경사항을 리뷰해 줘.
git diff main...HEAD를 확인하고, 파일별로 코멘트를 남겨 줘.
보안, 성능, 접근성 등 특정 관점에 집중한 리뷰를 요청할 수 있습니다.
lib/auth/ 디렉토리의 모든 파일을 보안 관점에서 감사해 줘.
특히 다음을 확인해 줘:
- SQL 인젝션 가능성
- XSS 취약점
- CSRF 방어
- 인증 토큰 관리
- 민감 정보 노출
components/Dashboard.tsx를 리팩터링해 줘.
- 500줄이 넘는 거대 컴포넌트를 적절한 크기로 분리
- 비즈니스 로직을 커스텀 훅으로 추출
- 타입 정의를 별도 파일로 분리
- 기존 동작은 변경하지 않을 것
여러 파일에 걸친 패턴 변경도 Claude Code가 효과적으로 처리하는 영역입니다.
프로젝트 전체에서 console.log를 모두 찾아서
적절한 logger 호출로 교체해 줘.
lib/logger.ts의 logger 인스턴스를 사용하고,
에러는 logger.error, 디버그는 logger.debug로 변환해 줘.
라이브러리 버전 업그레이드나 API 변경에 따른 마이그레이션도 일괄 처리할 수 있습니다.
date-fns v2에서 v4로 마이그레이션해 줘.
- 모든 import 경로 업데이트
- 제거된 함수를 대체 함수로 교체
- 타입 변경사항 반영
- 변경 후 pnpm build로 빌드 확인
리팩터링 후에는 항상 빌드와 테스트 실행을 요청하는 것이 좋습니다. "변경 후 pnpm build && pnpm test를 실행해서 문제가 없는지 확인해 줘"를 추가하면 Claude가 자동으로 검증합니다.
에러 메시지를 그대로 전달하면 Claude가 원인을 분석하고 수정합니다.
다음 에러가 발생해:
TypeError: Cannot read properties of undefined (reading 'map')
at ProductList (app/products/page.tsx:23:18)
원인을 찾고 수정해 줘.
애플리케이션 로그를 전달하여 문제를 진단할 수도 있습니다.
cat logs/error.log | claude -p "이 로그에서 반복되는 에러 패턴을 분석하고 근본 원인을 찾아 줘"/api/users/[id] 엔드포인트에서 존재하지 않는 ID로
요청하면 500 에러가 발생해.
404를 반환하도록 수정하고,
이 케이스에 대한 테스트도 추가해 줘.
lib/utils/format.ts의 모든 exported 함수에 대해
Vitest 단위 테스트를 작성해 줘.
- 정상 케이스와 엣지 케이스 모두 포함
- 에러가 발생해야 하는 입력도 테스트
- __tests__/format.test.ts에 작성
테스트를 먼저 작성하고 구현하는 흐름도 가능합니다.
장바구니 기능을 TDD로 개발해 줘.
1. 먼저 lib/cart/__tests__/cart.test.ts에 테스트를 작성해 줘:
- 상품 추가
- 수량 변경
- 상품 제거
- 총액 계산
- 할인 적용
2. 테스트가 실패하는 것을 확인한 후,
lib/cart/cart.ts에 구현을 작성해 줘.
3. 모든 테스트가 통과하는지 확인해 줘.
긴 세션에서는 컨텍스트가 축적되어 비효율적일 수 있습니다. /compact 명령어로 대화를 요약하여 컨텍스트를 절약합니다.
/compact작업의 성격이 완전히 바뀔 때는 /clear로 컨텍스트를 초기화하는 것이 더 효과적입니다.
Claude Code가 코드를 작성한 후, 직접 실행 결과를 확인하도록 요청합니다.
코드 작성 후 다음을 확인해 줘:
1. pnpm build가 성공하는지
2. pnpm lint에서 경고가 없는지
3. 관련 테스트가 모두 통과하는지
Claude Code의 변경이 기대와 다를 때를 대비하여, 작업 전에 Git 상태를 확인하는 습관이 중요합니다.
# 작업 전 현재 상태 커밋 또는 스태시
git stash
# Claude Code로 작업
# 결과가 만족스럽지 않으면
git checkout -- .
# 또는 특정 파일만 되돌리기
git checkout -- src/specific-file.tsxClaude Code의 핵심 워크플로우를 정리하면 다음과 같습니다.
다음 장에서는 이러한 워크플로우를 자동화하는 훅(Hooks) 시스템을 살펴봅니다.
이 글이 도움이 되셨나요?
Claude Code 훅 시스템의 개념과 라이프사이클을 이해하고, 코드 품질 게이트와 자동화 파이프라인을 구축하는 방법을 다룹니다.
CLAUDE.md 파일을 활용하여 프로젝트의 기술 스택, 코딩 컨벤션, 아키텍처 정보를 Claude Code에 효과적으로 전달하는 방법을 알아봅니다.
Claude Code의 스킬 시스템을 이해하고, 반복 작업을 자동화하는 커스텀 슬래시 명령어를 설계하고 구현하는 방법을 다룹니다.