기본 워크플로우
Claude Code를 활용한 일상적인 개발 워크플로우를 소개합니다.
기본 워크플로우 사이클
개발 워크플로우 순환 사이클
질문부터 커밋까지 — 반복하여 완성도를 높입니다
💬
1. 질문
자연어 요청
→
🔍
2. 분석
코드베이스 탐색
→
✏️
3. 코드 수정
파일 직접 수정
→
🧪
4. 테스트
자동 실행 및 검증
→
📦
5. 커밋
Git 커밋 & PR
🔁필요 시 다시 1단계로 — 반복을 통해 완성도 향상
프로젝트 탐색
새로운 코드베이스를 이해할 때:
> 이 프로젝트의 구조와 기술 스택을 설명해줘
> src/api/ 디렉토리의 역할을 분석해줘
> 인증 관련 코드가 어디에 있는지 찾아줘
대규모 코드베이스 탐색
코드베이스가 클 때는 범위를 좁혀서 질문하세요:
# 전체를 한 번에 분석하기보다 디렉토리별로 나눠서
> src/auth/ 디렉토리의 인증 플로우를 설명해줘
> 이 프로젝트에서 데이터베이스 쿼리는 어떤 패턴으로 작성되어 있어?
코드 작성
새 기능 추가
> 사용자 프로필 페이지를 만들어줘.
> /api/users/:id 엔드포인트에서 데이터를 가져오고,
> 기존 Layout 컴포넌트를 사용해줘.
Claude Code가:
- 기존 코드 패턴을 분석
- 관련 파일들을 참조
- 일관된 스타일로 코드 작성
- 필요한 파일들을 생성/수정
기존 코드 수정
> UserCard 컴포넌트에 로딩 스켈레톤을 추가해줘
> 이 함수를 async/await 패턴으로 리팩토링해줘
버그 수정
에러 메시지로 디버깅
에러 메시지를 그대로 전달합니다:
> 이 에러를 수정해줘:
> TypeError: Cannot read properties of undefined (reading 'map')
> at UserList (src/components/UserList.tsx:23)
테스트 기반 디버깅
> npm test를 실행하고, 실패하는 테스트를 수정해줘
Claude Code가 테스트를 실행하고, 실패 원인을 분석하고, 코드를 수정합니다.
에러 복구 워크플로우
빌드나 런타임 에러가 연쇄적으로 발생할 때:
# 1단계: 에러 전체 상황 파악
> npm run build를 실행하고 모든 에러를 분석해줘
# 2단계: 근본 원인부터 해결
> 가장 근본적인 원인부터 순서대로 수정해줘
# 3단계: 수정 확인
> 다시 빌드해서 모든 에러가 해결되었는지 확인해줘
대규모 에러 수정 시 주의
여러 파일에 걸친 에러를 수정할 때는 중간중간 테스트를 실행하여 새로운 에러가 발생하지 않는지 확인하세요.
Git 워크플로우
커밋 만들기
> 지금까지의 변경 사항을 커밋해줘
Claude Code가 변경 내용을 분석하고 적절한 커밋 메시지를 작성합니다.
PR 만들기
> 이 브랜치의 변경 사항으로 PR을 만들어줘
코드 리뷰
# 현재 브랜치의 변경 사항 리뷰
> 현재 브랜치의 diff를 리뷰해줘
# 특정 PR 리뷰
> 이 PR의 변경사항을 리뷰해줘: https://github.com/org/repo/pull/123
# 리뷰 관점 지정
> 보안 취약점 관점에서 이 PR을 리뷰해줘
롤백 전략
변경 사항에 문제가 있을 때 Git을 활용한 롤백:
# 마지막 커밋 취소 (변경 사항은 유지)
> 마지막 커밋을 취소하되 변경 사항은 staged 상태로 유지해줘
# 특정 파일만 되돌리기
> src/api/auth.ts를 이전 커밋 상태로 되돌려줘
# 전체 롤백
> 마지막 3개 커밋을 revert하는 새 커밋을 만들어줘
안전한 롤백
Claude Code는 git reset --hard보다 git revert를 사용하여 이력을 보존하는 방식을 선호합니다. 강제 리셋이 필요하면 명시적으로 요청하세요.
일괄 작업
리팩토링
> 프로젝트 전체에서 console.log를 제거해줘
> 모든 컴포넌트에서 PropTypes를 TypeScript 타입으로 변환해줘
의존성 업데이트
> package.json의 의존성을 최신 버전으로 업데이트하고,
> 빌드가 성공하는지 확인해줘
대규모 변경 (/batch)
여러 파일에 걸친 대규모 변경 작업:
# 프로젝트 전체의 import 경로 변경
> 모든 파일에서 @/utils를 @/lib/utils로 변경해줘
# API 응답 형식 일괄 변경
> 모든 API 핸들러에서 응답 형식을 { data, error } 패턴으로 통일해줘
팀 협업 패턴
PR 기반 협업
# 1. 다른 팀원의 PR 리뷰
> PR #45의 변경사항을 리뷰하고 피드백을 남겨줘
# 2. 리뷰 피드백 반영
> PR #45에 달린 리뷰 코멘트를 확인하고 수정해줘
# 3. 충돌 해결
> main 브랜치를 머지하고 충돌을 해결해줘
이슈 기반 작업
# 이슈 확인 후 작업 시작
> GitHub 이슈 #42를 확인하고, 수정 브랜치를 만들고, 해결해줘
CI/CD 연동
GitHub Actions에서 Claude Code 사용
Claude Code를 CI/CD 파이프라인에 통합하여 자동화할 수 있습니다:
# .github/workflows/claude-review.yml
name: Claude Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Claude Code Review
run: |
claude -p "이 PR의 diff를 분석하고 잠재적 문제를 리포트해줘" \
--output-format json \
--permission-mode dontAsk
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
헤드리스 모드
CI/CD에서는 -p 플래그로 비대화형(headless) 모드를 사용합니다. 자세한 내용은 고급 기능을 참고하세요.
실전 예제: 버그 수정 전체 워크플로우
이슈 확인부터 PR 생성까지의 전체 흐름:
# 1단계: 이슈 확인
> GitHub 이슈 #42의 내용을 확인해줘
# 2단계: 브랜치 생성
> fix/issue-42 브랜치를 만들어줘
# 3단계: 코드 분석
> 이슈에서 언급된 로그인 실패 문제의 원인을 분석해줘.
> src/auth/ 디렉토리를 중심으로 살펴봐.
# 4단계: 수정
> 분석 결과를 바탕으로 코드를 수정해줘
# 5단계: 테스트
> 관련 테스트를 실행하고, 필요하면 테스트도 추가해줘
# 6단계: 커밋 및 PR
> 변경 사항을 커밋하고, 이슈 #42를 참조하는 PR을 만들어줘
실전 예제: 새 기능 개발 워크플로우
설계부터 배포까지의 전체 흐름:
# 1단계: 설계
> 사용자 알림 기능을 추가하려고 해.
> 기존 코드 구조를 분석하고, 어떤 파일들을 추가/수정해야 하는지 계획을 세워줘.
# 2단계: 브랜치 생성
> feature/notifications 브랜치를 만들어줘
# 3단계: 데이터 모델
> 알림 데이터를 위한 Prisma 스키마와 마이그레이션을 만들어줘
# 4단계: API 구현
> 알림 CRUD API 엔드포인트를 만들어줘
# 5단계: 프론트엔드 구현
> 알림 목록 페이지와 알림 벨 컴포넌트를 만들어줘
# 6단계: 테스트 작성
> API와 컴포넌트에 대한 테스트를 작성해줘
# 7단계: 통합 확인
> 전체 빌드와 테스트를 실행해줘
# 8단계: PR 생성
> 변경 사항을 커밋하고 PR을 만들어줘.
> PR 설명에 구현 내용과 테스트 방법을 포함해줘.
효율적으로 사용하는 팁
컨텍스트 제공하기
# 나쁜 예: 맥락 없이 요청
> 버그 수정해줘
# 좋은 예: 충분한 맥락 제공
> src/api/users.ts의 getUser 함수에서 존재하지 않는 사용자를 조회할 때
> 500 에러 대신 404를 반환하도록 수정해줘
단계별로 나누기
복잡한 작업은 한 번에 요청하지 말고 단계별로 나눕니다:
# 1단계: 먼저 분석
> 현재 인증 시스템의 구조를 분석해줘
# 2단계: 계획 확인
> OAuth2 지원을 추가하려면 어떤 파일들을 수정해야 해?
# 3단계: 실행
> 계획대로 구현해줘
변경 사항 확인하기
# 수정 후 항상 확인
> 방금 수정한 내용을 요약해줘
> 변경된 파일들의 diff를 보여줘
> 테스트를 실행해서 문제가 없는지 확인해줘
연계 기능
워크플로우를 강화하는 연계 기능들
📋
-p, --bare, --max-budget-usd 등 다양한 플래그로 워크플로우를 자동화하고 세밀하게 제어할 수 있습니다.📄
CLAUDE.md로 코딩 컨벤션, 커밋 규칙 등을 미리 설정하면 매 워크플로우마다 일관된 결과를 얻을 수 있습니다.
⚡
헤드리스 모드로 CI/CD를 자동화하거나, 에이전트 팀을 구성하여 복잡한 워크플로우를 병렬로 처리할 수 있습니다.
장점, 단점과 한계점
장점
- 자연어로 코드 작업: 복잡한 명령어나 문법 없이 자연어로 요청하면 코드 분석, 작성, 수정을 처리합니다.
- Git 통합 워크플로우: 커밋 생성, PR 만들기, 코드 리뷰, 충돌 해결까지 Git 작업 전체를 자연어로 수행할 수 있습니다.
- 멀티 파일 일괄 수정: import 경로 변경, API 응답 형식 통일 등 여러 파일에 걸친 변경을 일관되게 처리합니다.
- 이슈 기반 워크플로우: GitHub 이슈 확인부터 브랜치 생성, 수정, 테스트, PR 생성까지 전체 흐름을 하나의 세션에서 진행할 수 있습니다.
단점과 한계점
- 복잡한 리팩토링 시 정확도 저하: 아키텍처 수준의 대규모 리팩토링에서는 일부 파일 누락이나 불완전한 수정이 발생할 수 있습니다.
- 대규모 코드베이스에서 느려짐: 프로젝트 파일 수가 많으면 코드 탐색과 분석에 시간이 오래 걸리고, 토큰 소비도 증가합니다.
- 의도치 않은 파일 수정 가능: 요청 범위가 모호하면 관련 없는 파일까지 수정할 수 있으므로, 변경 사항을 반드시 확인해야 합니다.
- 테스트 커버리지 확인 필요: 자동 수정 후 기존 테스트가 깨지지 않았는지, 새 코드에 대한 테스트가 충분한지 별도로 검증해야 합니다.
활용 팁
복잡한 작업은 반드시 단계별로 나눠서 요청하고, 각 단계 후 > 변경된 파일의 diff를 보여줘로 결과를 확인하세요. plan 모드(--permission-mode plan)에서 변경 내용을 리뷰하는 습관을 들이면 의도치 않은 수정을 방지할 수 있습니다.