들어가며
Claude Code는 터미널에서 동작하는 에이전틱 코딩 도구로, 코드베이스를 이해하고 자연어 명령을 통해 파일 편집, 명령 실행, Git 워크플로우까지 수행합니다. 이 가이드는 Claude Code를 활용하여 프로덕션 수준의 고품질 애플리케이션을 체계적으로 개발하기 위한 절차와 베스트 프랙티스를 정리합니다.
Phase 1: 프로젝트 인프라 구축
고품질 결과물의 80%는 Claude Code에게 제공하는 컨텍스트 품질에 의해 결정됩니다. 코드 한 줄 작성하기 전에 프로젝트 인프라를 먼저 세팅하세요.
1.1 CLAUDE.md 설정 — 가장 중요한 단일 작업
CLAUDE.md는 Claude Code가 세션 시작 시 자동으로 읽는 프로젝트 메모리 파일입니다. 프로젝트의 컨벤션, 아키텍처, 기술 스택을 명시해두면 Claude가 일관된 코드를 생성합니다.
# CLAUDE.md
## 프로젝트 개요
- 프로젝트명: my-service
- 설명: 주문 관리 마이크로서비스
## 기술 스택
- Java 21 + Kotlin
- Spring Boot 3.4 (Spring MVC, Spring Data JPA)
- Gradle (Kotlin DSL)
- PostgreSQL, Redis
- RestClient (WebClient 대신 사용)
## 아키텍처 규칙
- Layered Architecture: Controller → Service → Repository
- DTO는 record(Java) 또는 data class(Kotlin) 사용
- Entity와 DTO를 반드시 분리
- 예외 처리는 @RestControllerAdvice 활용
## 코딩 컨벤션
- 패키지 구조: com.example.{도메인}.{layer}
- REST API는 /api/v1 prefix 사용
- 테스트는 반드시 작성 (JUnit 5 + MockK)
- 커밋 메시지: Conventional Commits 형식
## 빌드 & 실행
- 빌드: ./gradlew build
- 테스트: ./gradlew test
- 린트: ./gradlew ktlintCheck
- 실행: ./gradlew bootRun
## 절대 하지 말 것
- WebClient나 RestTemplate 사용 금지 (RestClient만 사용)
- var 남용 금지, 타입을 명시적으로 선언
- 테스트 없이 PR 생성 금지
CLAUDE.md 스코프 활용:
| ~/.claude/CLAUDE.md | 모든 프로젝트 | 개인 글로벌 설정 |
| 프로젝트루트/CLAUDE.md | 해당 프로젝트 전체 | 팀 공유 컨벤션 (Git 커밋) |
| 프로젝트루트/.claude/CLAUDE.md | 해당 프로젝트 (로컬) | 개인 로컬 설정 (.gitignore) |
1.2 Rules 설정 — 주제별 모듈 지침
.claude/rules/ 디렉토리에 주제별 규칙 파일을 두면, Claude가 관련 작업 시 자동으로 참조합니다. frontmatter로 경로 스코핑도 가능합니다.
<!-- .claude/rules/api-design.md -->
---
globs: ["**/controller/**", "**/api/**"]
---
# API 설계 규칙
- ResponseEntity로 감싸서 반환
- 페이지네이션은 Spring Data의 Pageable 사용
- 400/404/500 에러 응답 형식 통일
1.3 Skills 설정 — 재사용 가능한 워크플로우
.claude/skills/ 디렉토리에 반복되는 작업 패턴을 정의하면 /skill-name으로 호출할 수 있습니다.
<!-- .claude/skills/new-api.md -->
# 새 API 엔드포인트 생성
## 절차
1. Controller 클래스 생성 (또는 기존에 추가)
2. Request/Response DTO 정의
3. Service 인터페이스 및 구현체 작성
4. Repository 생성 (필요 시)
5. 통합 테스트 작성
6. API 문서 업데이트
## 참고 패턴
- 기존 예시: src/main/kotlin/com/example/order/controller/OrderController.kt
1.4 Hooks 설정 — 자동 품질 게이트
Hooks는 Claude의 에이전틱 루프 바깥에서 결정론적으로 실행되는 스크립트입니다. 코드 변경 후 자동으로 린트/빌드를 실행하여 품질을 강제할 수 있습니다.
// .claude/settings.json
{
"hooks": {
"stop": [
{
"command": "./gradlew ktlintCheck --quiet",
"description": "코드 스타일 자동 검증"
}
]
}
}
Phase 2: 계획 수립 (Plan Before Code)
리서치/계획과 구현을 반드시 분리하세요. Claude가 바로 코딩에 뛰어들게 하면, 잘못된 문제를 풀거나 아키텍처가 꼬이는 경우가 빈번합니다.
2.1 Plan Mode 활용
Shift+Tab 두 번으로 Plan Mode를 활성화합니다. 이 모드에서 Claude는 파일을 읽고 분석할 수 있지만, 어떤 파일도 수정하지 않습니다. 아키텍트 모드라고 생각하면 됩니다.
# Plan Mode에서의 프롬프트 예시
주문 취소 API를 구현해야 합니다.
요구사항:
- PUT /api/v1/orders/{id}/cancel
- 주문 상태가 PENDING일 때만 취소 가능
- 취소 시 재고 복원 필요
- 취소 사유(reason)를 기록
먼저 기존 OrderController와 OrderService를 분석하고,
구현 계획을 세워주세요. 아직 코드를 작성하지 마세요.
2.2 구조화된 프롬프트 작성 (CIF 원칙)
효과적인 프롬프트는 Context(맥락), Intent(의도), **Format(형식)**을 포함합니다.
# ❌ 모호한 프롬프트
폼 추가해줘
# ✅ 구조화된 프롬프트
[Context] OrderController.kt에 주문 수정 API가 필요합니다.
[Intent] 기존 createOrder 패턴을 따라서 updateOrder 엔드포인트를 구현해주세요.
[Format]
- PUT /api/v1/orders/{id}
- UpdateOrderRequest DTO 생성 (수량, 배송주소 변경 가능)
- 서비스 레이어에서 변경 감지 및 이벤트 발행
- 통합 테스트 포함
- 기존 OrderControllerTest.kt 패턴 참고
2.3 검증 기준을 먼저 제시
Claude에게 스스로 검증할 수 있는 수단을 제공하면 품질이 극적으로 향상됩니다. 테스트, 빌드 명령, 린트 등이 여기에 해당합니다.
구현 후 다음을 확인해주세요:
1. ./gradlew test 전체 통과
2. ./gradlew ktlintCheck 통과
3. 기존 테스트가 깨지지 않는지 확인
Phase 3: 구현
3.1 작업 단위 분할
복잡한 기능은 한 번에 구현하지 말고, 검증 가능한 단위로 나누세요.
# 주문 시스템 구현을 단계별로 나눈 예시
Step 1: "Order Entity와 Repository를 만들어주세요.
엔티티 생성 후 ./gradlew test로 확인."
/clear
Step 2: "OrderService를 구현해주세요.
주문 생성, 조회, 취소 로직 포함.
각 메서드에 대한 단위 테스트 작성."
/clear
Step 3: "OrderController를 구현해주세요.
기존 UserController.kt 패턴을 따라주세요.
통합 테스트 작성 후 전체 테스트 실행."
3.2 /clear를 적극적으로 사용
새 작업을 시작할 때마다 /clear로 컨텍스트를 초기화하세요. 컨텍스트가 쌓이면 Claude의 성능이 저하되고, 토큰 소비가 증가하며, 이전 대화의 실수가 반복될 수 있습니다. 컨텍스트 열화(context degradation)는 Claude Code 사용 시 가장 흔한 실패 원인입니다.
# 이렇게 하지 마세요 (한 세션에서 모든 것)
"Entity 만들어줘" → "Service도 추가" → "아 그리고 Controller도" → "테스트도..."
# 이렇게 하세요 (작업 단위별 세션 분리)
[세션 1] Entity + Repository + 테스트 → /clear
[세션 2] Service + 테스트 → /clear
[세션 3] Controller + 통합 테스트 → /clear
3.3 기존 코드를 예시로 제공
Claude Code는 프로젝트의 기존 패턴을 보여줄 때 가장 일관된 코드를 생성합니다.
ProductController를 새로 만들어주세요.
기존 OrderController.kt의 패턴(에러 핸들링, 응답 형식, 페이지네이션)을
그대로 따라주세요.
3.4 병렬 세션 활용
독립적인 작업은 여러 Claude Code 세션을 동시에 실행하여 병렬로 처리할 수 있습니다. VS Code 확장을 사용하면 여러 패널에서 동시에 인스턴스를 실행할 수 있습니다.
Writer/Reviewer 패턴:
| 세션 A | Writer | API 엔드포인트 구현 |
| 세션 B | Reviewer | 세션 A의 코드 리뷰 (편향 없이) |
Test-First 패턴:
| 세션 A | 테스트 작성자 | 테스트 케이스 먼저 작성 |
| 세션 B | 구현자 | 작성된 테스트를 통과하는 코드 구현 |
Phase 4: 품질 검증
4.1 자동 검증 루프
Claude Code가 스스로 검증하도록 구성하면, 사람이 피드백 루프에 개입할 필요가 줄어듭니다.
다음 순서로 진행해주세요:
1. OrderCancelService 구현
2. 단위 테스트 작성 및 실행
3. 테스트 실패 시 코드 수정 후 재실행
4. ./gradlew ktlintCheck로 스타일 검증
5. 전체 빌드 ./gradlew build 확인
4.2 MCP 통합으로 시각적 검증
MCP(Model Context Protocol) 서버를 연결하면 Claude가 브라우저, 콘솔 로그 등을 직접 확인할 수 있습니다.
- Claude in Chrome: 실제 브라우저에서 UI를 열어 시각적 검증
- Playwright MCP: 자동화된 브라우저 테스트 실행
- Chrome DevTools MCP: 콘솔 로그와 네트워크 요청 확인
4.3 코드 리뷰 자동화
/install-github-app으로 Claude의 PR 자동 리뷰를 설정할 수 있습니다. 사람이 변수명을 지적하는 동안 Claude는 실제 로직 오류와 보안 이슈를 찾아냅니다.
# claude-code-review.yml
direct_prompt: |
이 PR을 리뷰하고 버그와 보안 이슈만 보고해주세요.
간결하게 작성하세요.
코딩 스타일이나 변수명은 무시하세요.
Phase 5: Git 워크플로우 & 배포
5.1 커밋과 PR 자동화
Claude Code에게 Git 작업을 위임하면 시간을 절약하면서도 일관된 커밋 메시지를 유지할 수 있습니다.
# 변경사항을 Conventional Commits 형식으로 커밋
지금까지의 변경사항을 적절한 단위로 나눠서 커밋해주세요.
Conventional Commits 형식을 사용하세요.
# PR 생성
이 브랜치의 변경사항으로 PR을 만들어주세요.
- 제목: feat: 주문 취소 API 구현
- 본문에 변경 내용, 테스트 방법, 영향 범위를 포함
5.2 CI 파이프라인 연동
Claude Code를 CI/CD 파이프라인에서 비대화형(headless)으로 실행할 수 있습니다.
# CI에서 자동 코드 수정 (린트 에러 등)
claude -p "린트 에러를 모두 수정해주세요" --allowedTools "Edit,Bash"
# 배치 작업
for issue in $ISSUES; do
claude -p "이슈 $issue를 해결하고 PR을 생성해주세요"
done
핵심 원칙 요약
반드시 지켜야 할 것
- CLAUDE.md를 꼼꼼히 작성하세요 — 투자 대비 효과가 가장 큰 단일 작업입니다.
- 코딩 전에 반드시 계획하세요 — Plan Mode로 아키텍처를 먼저 확정하세요.
- 검증 수단을 제공하세요 — 테스트, 린트, 빌드 명령을 Claude에게 알려주세요.
- /clear를 습관화하세요 — 작업 전환 시 컨텍스트를 초기화하세요.
- 기존 패턴을 예시로 보여주세요 — 새 코드의 일관성이 크게 향상됩니다.
- 작업을 작게 나누세요 — 한 세션에 한 가지 작업만 집중하세요.
반드시 피해야 할 것
- Kitchen Sink 세션 — 한 세션에서 관련 없는 여러 작업을 섞지 마세요.
- 모호한 프롬프트 — "API 만들어줘" 대신 구체적인 스펙을 제공하세요.
- 검증 없는 수락 — Claude가 생성한 코드를 반드시 빌드/테스트하세요.
- MCP 서버 과다 연결 — 실제로 사용하는 것만 연결하세요 (4개 이내 권장).
- 코드 소유권 방기 — PR에 이름이 올라가는 것은 당신입니다. 최종 책임은 개발자에게 있습니다.
권장 워크플로우 치트시트
┌─────────────────────────────────────────────────┐
│ 1. 인프라 세팅 │
│ CLAUDE.md 작성 → Rules 설정 → Hooks 구성 │
├─────────────────────────────────────────────────┤
│ 2. 계획 수립 (Plan Mode) │
│ 요구사항 분석 → 아키텍처 설계 → 계획 확인 │
├─────────────────────────────────────────────────┤
│ 3. 단계별 구현 │
│ 작업 분할 → 구현 → 검증 → /clear → 다음 작업 │
├─────────────────────────────────────────────────┤
│ 4. 품질 검증 │
│ 테스트 실행 → 린트 통과 → 빌드 확인 │
├─────────────────────────────────────────────────┤
│ 5. Git 워크플로우 │
│ 커밋 → PR 생성 → 코드 리뷰 → 머지 │
└─────────────────────────────────────────────────┘
참고 자료





















