Day 2: 멀티턴 프롬프트 전략 & 체이닝
AI Tools Mastery Curriculum — Week 1, Day 2 소요 시간: 45분 | 실습 중심
핵심 배운 점
- 단일 프롬프트는 우선순위 혼란, 컨텍스트 소모, 검증 불가
- 역할 분리(분석→설계→구현→검증) 패턴으로 각 단계에 집중
- Plan Mode(Shift+Tab×2)로 읽기 전용 모드 활성화
- plan.md에 저장하면 세션 간 맥락 유지 가능
① 단일 vs 체이닝 비교 실험
단일 프롬프트의 한계
단일 프롬프트란 하나의 메시지에 모든 것을 담아 보내는 방식이다.
> 수강신청 처리 API를 리팩토링해줘. 현재 @Transactional 안에서
외부 API를 호출하고 있는데, 이걸 분리하고 에러 처리도 개선하고
테스트도 작성해줘. 그리고 기존 코드와 호환되게 해줘.
이렇게 한 번에 요청하면 다음 문제가 발생한다:
- 우선순위 혼란: 리팩토링, 에러 처리, 테스트, 호환성 중 뭐가 가장 중요한지 Claude가 임의로 판단
- 컨텍스트 소모: 한 번에 많은 코드를 생성하면서 컨텍스트 윈도우를 빠르게 소진
- 검증 불가: 중간 단계를 확인할 수 없어서 잘못된 방향으로 진행되면 전부 폐기해야 함
- 품질 저하: 복합 요청일수록 각 부분의 품질이 고르지 못함
체이닝 프롬프트란
하나의 큰 작업을 논리적 단계로 나눠서 순서대로 요청하는 방식이다. 각 단계의 출력이 다음 단계의 입력이 된다.
프롬프트 1 → 결과 확인 → 프롬프트 2 → 결과 확인 → 프롬프트 3
핵심은 각 단계 사이에 사람이 개입해서 방향을 검증한다는 것이다.
비교 실험: 동일 태스크로 직접 해보기
실험 태스크: “수강신청 처리에서 @Transactional과 외부 API 호출 분리 리팩토링”
방법 A: 단일 프롬프트
claude
> EnrollmentService에서 @Transactional 안에 외부 API 호출이
있는 부분을 찾아서 분리 리팩토링해줘. 에러 처리도 개선하고
단위 테스트도 작성해줘.관찰 포인트:
- Claude가 코드베이스를 얼마나 탐색했는가?
- 리팩토링 방향을 설명 없이 바로 코드를 작성했는가?
- 기존 코드 패턴을 존중했는가?
- 테스트가 실제로 의미 있는 케이스를 커버하는가?
방법 B: 체이닝 프롬프트
claude
# 1단계: 현황 분석
> EnrollmentService에서 @Transactional 안에 외부 API를 호출하는
메서드를 모두 찾아서 목록으로 정리해줘.
각 메서드별로 어떤 외부 API를 호출하는지도 포함해줘.
# (결과 확인 후)
# 2단계: 리팩토링 계획
> 위 분석 결과를 바탕으로 리팩토링 계획을 세워줘.
- 트랜잭션 경계를 어디서 끊을지
- 외부 API 호출 실패 시 보상 트랜잭션이 필요한 케이스가 있는지
- 기존 호출자에 영향이 가는 부분은 무엇인지
아직 코드는 작성하지 마.
# (계획 확인 후)
# 3단계: 구현
> 계획대로 구현해줘. enrollCourse() 메서드부터 시작하자.
# (코드 확인 후)
# 4단계: 테스트
> 방금 리팩토링한 enrollCourse()에 대한 단위 테스트를 작성해줘.
특히 외부 API 실패 시 DB 트랜잭션은 커밋되는 케이스를 반드시 포함해.관찰 포인트:
- 1단계에서 놓친 메서드가 없는가?
- 2단계 계획이 실무적으로 합리적인가?
- 3단계에서 계획대로 구현했는가?
- 4단계 테스트가 핵심 시나리오를 커버하는가?
비교 기록 템플릿
## 단일 vs 체이닝 비교 결과
### 태스크
"@Transactional 내 외부 API 호출 분리 리팩토링"
### 단일 프롬프트 결과
- 소요 시간: __분
- 코드 품질 (1-5): __
- 놓친 부분:
- 수동 수정 필요 횟수: __회
### 체이닝 프롬프트 결과
- 소요 시간: __분 (프롬프트 4회)
- 코드 품질 (1-5): __
- 놓친 부분:
- 수동 수정 필요 횟수: __회
### 결론
- 시간 차이:
- 품질 차이:
- 어떤 상황에서 어떤 방식이 유리한가:② 역할 분리 패턴: 분석→설계→구현
체이닝의 가장 실용적인 형태가 역할 분리 패턴이다. Claude에게 매 단계마다 다른 “역할”을 부여하면, 각 단계에 집중할 수 있다.
패턴 구조
[아키텍트] 분석 → [설계자] 설계 → [개발자] 구현 → [QA] 검증
각 역할은 관심사가 다르다:
| 역할 | 관심사 | 출력물 |
|---|---|---|
| 아키텍트 | 현재 구조, 의존 관계, 위험 요소 | 분석 보고서 |
| 설계자 | 인터페이스, 책임 분리, 변경 범위 | 설계 문서 / 다이어그램 |
| 개발자 | 구현 세부사항, 코드 작성 | 코드 변경 |
| QA | 경계 케이스, 실패 시나리오 | 테스트 코드 |
실전 예시: 수강료 환불 프로세스 리팩토링
Step 1: 아키텍트 역할 — 분석
> 아키텍트 관점에서 RefundService를 분석해줘.
다음을 파악해줘:
1. 이 서비스가 의존하는 외부 시스템 목록
2. 데이터 흐름 (어디서 읽고 어디에 쓰는지)
3. 현재 구조에서 위험한 부분 (장애 전파 가능성)
코드 변경은 하지 마. 분석만 해줘.
이 단계의 핵심:
- “코드 변경은 하지 마” 라고 명시적으로 제한
- Claude가 코드베이스를 탐색하면서 전체 그림을 파악
- 우리가 미처 몰랐던 의존 관계를 발견할 수 있음
Step 2: 설계자 역할 — 설계
> 위 분석을 바탕으로 리팩토링을 설계해줘.
조건:
- 환불 처리와 외부 PG 연동을 분리
- 부분 환불 실패 시 재시도 가능한 구조
- 기존 API 시그니처는 유지 (하위 호환)
클래스 다이어그램이나 시퀀스 다이어그램으로 보여줘.
아직 코드는 작성하지 마.
이 단계의 핵심:
- 조건을 명확히 제시 (분리 기준, 실패 처리 방식, 호환성)
- 다이어그램을 요청해서 시각적으로 검증
- “아직 코드는 작성하지 마”로 다시 한번 제한
Step 3: 개발자 역할 — 구현
> 위 설계대로 구현해줘.
순서:
1. RefundExecutor 인터페이스 먼저 만들고
2. PgRefundExecutor 구현체 작성
3. RefundService에서 기존 로직을 새 구조로 전환
한 파일씩 진행하고, 각 파일 완료 후 알려줘.
이 단계의 핵심:
- 구현 순서를 명시해서 Claude가 의존 순서대로 작업
- “한 파일씩”으로 중간 확인 가능
- 설계 단계의 결정사항이 자연스럽게 컨텍스트에 유지됨
Step 4: QA 역할 — 검증
> QA 관점에서 방금 구현한 코드를 검토해줘.
다음 시나리오에 대한 테스트를 작성해:
1. 정상 환불 처리
2. PG 연동 타임아웃 시 재시도
3. 부분 환불 중 일부 실패
4. 동시에 같은 수강권에 환불 요청이 들어오는 경우
역할 분리가 효과적인 이유
단일 프롬프트에서 “분석하고 설계하고 구현하고 테스트해줘”라고 하면 Claude는 분석을 대충 넘기고 바로 코드부터 작성하는 경향이 있다. 역할을 분리하면 각 단계에서 충분한 사고를 하도록 강제할 수 있다.
특히 “코드 작성하지 마”라는 제약이 중요하다. 이 제약 없이는 Claude가 분석이나 설계 단계에서도 코드를 생성하려 해서 컨텍스트를 낭비한다.
역할 분리를 Custom Command로 만들기
자주 쓰는 패턴이라면 .claude/commands/에 저장해둘 수 있다:
<!-- .claude/commands/refactor-analyze.md -->
아키텍트 관점에서 $ARGUMENTS 를 분석해줘.
다음을 파악해줘:
1. 이 서비스/클래스가 의존하는 외부 시스템 목록
2. 데이터 흐름 (어디서 읽고 어디에 쓰는지)
3. 현재 구조에서 위험한 부분
코드 변경은 하지 마. 분석만 해줘.사용법:
> /project:refactor-analyze RefundService③ Plan Mode 활용법 실습
Plan Mode란
Plan Mode는 Claude Code에서 Shift+Tab을 두 번 누르면 활성화되는 모드다. 이 모드에서 Claude는 파일을 읽고 분석할 수는 있지만, 어떤 파일도 수정할 수 없다.
즉, “아키텍트 모드”에 해당한다.
일반 모드: 읽기 ✅ | 쓰기 ✅ | 명령 실행 ✅
Plan Mode: 읽기 ✅ | 쓰기 ❌ | 명령 실행 ❌
Plan Mode가 해결하는 문제
일반 모드에서 “분석해줘”라고 요청하면 Claude가 분석 후 바로 코드를 작성하려는 경향이 있다. “코드 변경은 하지 마”라고 텍스트로 제약을 걸어도 100% 지켜지지 않는다.
Plan Mode는 시스템 레벨에서 쓰기 권한을 제거하기 때문에, 분석과 계획에만 집중하도록 확실하게 보장한다.
Plan Mode 활성화 방법
① Claude Code 실행
② 프롬프트 입력 창에서 Shift+Tab 두 번
③ 입력 창 위에 "Plan Mode" 표시가 나타남
④ 이 상태에서 프롬프트 입력
또는 프롬프트에 접두어를 사용할 수도 있다:
> plan: 이 코드베이스의 아키텍처를 분석해줘
실습 시나리오 3가지
시나리오 1: 코드베이스 첫 파악
새 프로젝트에 합류했거나, 오랜만에 돌아온 코드에 적합하다.
[Plan Mode 활성화]
> 이 프로젝트의 전체 구조를 파악해줘.
- 주요 모듈과 각 모듈의 책임
- 모듈 간 의존 관계
- 진입점 (API 엔드포인트, 스케줄러 등)
- 외부 시스템 연동 포인트
Plan Mode이므로 Claude는:
- 디렉토리 구조를 탐색함 ✅
- 주요 파일을 읽음 ✅
- 분석 결과를 텍스트로 설명함 ✅
- 파일을 생성하거나 수정함 ❌ (불가능)
시나리오 2: 리팩토링 전 영향 분석
코드 변경 전에 영향 범위를 파악할 때 사용한다.
[Plan Mode 활성화]
> NotificationService의 sendEnrollmentConfirm() 메서드를
비동기로 전환하려고 해. 이 변경이 미치는 영향을 분석해줘.
- 이 메서드를 호출하는 곳 전부
- 동기→비동기 전환 시 트랜잭션 관련 이슈
- 변경이 필요한 파일 목록과 예상 난이도
이 분석이 끝나면 Plan Mode를 끄고 실제 구현을 진행한다:
[Shift+Tab 두 번으로 일반 모드 복귀]
> 위 분석을 바탕으로 가장 쉬운 파일부터 순서대로 수정해줘.
시나리오 3: 버그 원인 추적
버그의 근본 원인을 찾을 때, 코드를 건드리지 않고 분석만 하고 싶은 경우.
[Plan Mode 활성화]
> 결제 완료 후 간헐적으로 수강 등록이 누락되는
버그가 있어. 다음 정보를 바탕으로 원인을 추적해줘.
증상:
- 전체 결제의 약 3%에서 발생
- 주로 새벽 시간대(02:00~05:00)에 집중
- 에러 로그에 TimeoutException이 간헐적으로 보임
의심 포인트:
- 이벤트 리스너의 비동기 처리 타이밍 이슈?
- PG사 콜백 수신 후 재시도 로직?
- DB 커넥션 풀 고갈?
관련 코드를 읽고 가능성이 높은 원인부터 순서대로 설명해줘.
Plan Mode + 체이닝 조합 워크플로우
가장 효과적인 사용법은 Plan Mode로 분석/설계 → 일반 모드로 구현이다:
Phase 1: Plan Mode (Shift+Tab×2)
├─ 프롬프트 1: 현황 분석
├─ 프롬프트 2: 리팩토링 계획 수립
└─ 프롬프트 3: 구현 순서 결정
Phase 2: Normal Mode (Shift+Tab×2로 복귀)
├─ 프롬프트 4: 1번 파일 구현
├─ 프롬프트 5: 2번 파일 구현
└─ 프롬프트 6: 테스트 작성
Phase 3: Plan Mode (다시 전환)
└─ 프롬프트 7: 전체 변경사항 리뷰
plan.md 패턴: 계획을 파일로 남기기
Plan Mode에서 나온 분석/계획을 파일로 저장해두면, 세션이 바뀌어도 맥락을 유지할 수 있다.
[Plan Mode]
> 분석 결과를 plan.md 파일로 정리해줘.
- 현재 상태 요약
- 변경 계획 (체크리스트 형태)
- 각 단계의 예상 난이도와 위험도
그러면 다음 세션에서:
[Normal Mode]
> plan.md를 읽고 아직 완료되지 않은 항목부터 이어서 작업해줘.
이렇게 하면 /clear를 해도, 심지어 다음 날 이어 작업해도 맥락이 유지된다. CLAUDE.md가 “프로젝트의 기억”이라면, plan.md는 “작업의 기억”인 셈이다.
실습 과제
과제 1: 비교 실험 수행 (15분)
자신의 프로젝트에서 리팩토링이 필요한 클래스를 하나 골라서:
- 단일 프롬프트로 리팩토링 요청
- /clear 후 체이닝(4단계)으로 동일 리팩토링 요청
- 비교 기록 템플릿 작성
과제 2: 역할 분리 패턴 적용 (15분)
현재 작업 중인 티켓이나 이슈 하나를 골라서:
- 아키텍트 역할로 분석
- 설계자 역할로 설계
- 개발자 역할로 핵심 1개 파일만 구현
- 각 단계 전환 시 이전 단계 결과를 어떻게 활용하는지 관찰
과제 3: Plan Mode 워크플로우 (15분)
- Plan Mode로 진입
- 코드베이스 중 한 모듈의 구조 분석 요청
- plan.md로 분석 결과 저장 요청
- 일반 모드로 복귀 후 plan.md 기반으로 작업 하나 수행
오늘의 핵심 정리
| 포인트 | 설명 |
|---|---|
| 단일 프롬프트 | 간단한 작업(파일 1개, 변경 10줄 이내)에 적합 |
| 체이닝 프롬프트 | 복잡한 작업에서 품질과 제어력을 크게 향상 |
| 역할 분리 | 분석→설계→구현→검증, 각 단계에서 “코드 작성 금지” 제약이 핵심 |
| Plan Mode | Shift+Tab×2, 시스템 레벨에서 쓰기 권한 차단 |
| plan.md 패턴 | 계획을 파일로 남겨 세션 간 맥락 유지 |
| Custom Command | 자주 쓰는 역할 패턴을 .claude/commands/에 저장 |
프롬프트 패턴 치트시트
# 분석 요청 (Plan Mode 또는 텍스트 제약)
"~를 분석해줘. 코드 변경은 하지 마."
# 설계 요청
"위 분석을 바탕으로 ~를 설계해줘. 아직 코드는 작성하지 마."
# 구현 요청 (순서 지정)
"위 설계대로 구현해줘. ~부터 시작하자. 한 파일씩 진행해."
# 검증 요청
"QA 관점에서 ~를 검토하고, 다음 시나리오에 대한 테스트를 작성해: ..."
# 계획 저장
"분석 결과를 plan.md로 정리해줘."
# 계획 기반 재개
"plan.md를 읽고 아직 완료되지 않은 항목부터 이어서 작업해줘."
참고 리소스
- Anthropic 엔지니어링 블로그: Claude Code Best Practices — 멀티턴 워크플로우 패턴
- Claude Code 공식 문서: Custom Commands — .claude/commands/ 설정법
- Medium: Mastering the Vibe: Claude Code Best Practices — Plan Mode 실전 활용기