공개 문서
content/courses/08-multifile-workflow.mdx
아래는 content/courses/08-multifile-workflow.mdx 와 동일한 원문입니다. Markdown과 HTML 변환 결과를 각각 복사할 수 있습니다.
공개 문서 원문 (Markdown)
---
title: "멀티파일 워크플로우"
slug: "08-multifile-workflow"
description: "Claude Code로 여러 파일을 동시에 작업하는 방법"
order: 8
date: "2026-03-10"
level: 2
draft: false
---
# 멀티파일 워크플로우
> **이 챕터를 마치면** Claude Code로 여러 파일을 한 번에 수정하는 요청을 할 수 있어요.
Claude Code의 가장 큰 강점은 **여러 파일을 동시에 이해하고 수정**하는 능력이에요.
Cursor가 열린 파일 위주로 작업한다면, Claude Code는 프로젝트 전체를 보고 작업해요.
---
## 실전 예시: 회원가입 기능 추가
아래 한 줄 요청으로 Claude Code가 무엇을 하는지 보겠습니다.
```bash
claude "Supabase를 사용한 이메일 회원가입 기능을 추가해줘.
폼 컴포넌트, 서버 액션, 타입 파일까지 포함해서."
```
Claude Code의 실제 작업 순서:
```
✻ 계획 수립
1. 기존 파일 구조 파악
2. Supabase 클라이언트 설정 확인
3. 필요한 파일 목록 작성
✻ 실행
Read: app/layout.tsx ← 기존 레이아웃 파악
Read: lib/supabase.ts ← 클라이언트 설정 확인 (없으면 생성)
Write: lib/supabase.ts ← Supabase 클라이언트
Write: types/auth.ts ← 타입 정의
Write: app/actions/auth.ts ← 서버 액션
Write: components/SignupForm.tsx ← 폼 컴포넌트
Edit: app/page.tsx ← 메인 페이지에 폼 연결
✻ 완료 보고
6개 파일 생성/수정 완료
pnpm dev로 확인하세요.
```
한 번의 요청으로 6개 파일이 일관되게 작성됩니다.
---
## 효과적인 요청 작성법
### 맥락을 충분히 주기
❌ 너무 짧은 요청:
```
claude "로그인 만들어줘"
```
✅ 맥락이 있는 요청:
```
claude "Next.js 15 App Router + Supabase Auth로 Google 소셜 로그인을 추가해줘.
- 로그인 버튼은 components/LoginButton.tsx로
- 콜백 처리는 app/auth/callback/route.ts로
- 로그인 성공 시 /dashboard로 리다이렉트"
```
### 단계별로 나누기
한 번에 너무 많이 요청하면 실수가 늘어납니다.
```bash
# 1단계: 기반 설정
claude "Supabase 클라이언트 설정 파일을 만들어줘 (lib/supabase.ts)"
# 2단계: 인증 로직
claude "방금 만든 Supabase 클라이언트로 이메일 로그인 서버 액션을 만들어줘"
# 3단계: UI
claude "로그인 서버 액션을 사용하는 LoginForm 컴포넌트를 만들어줘"
```
---
## 코드 리뷰 요청
작업 후 바로 리뷰를 요청할 수 있습니다.
```bash
claude "방금 만든 인증 코드에서 보안 문제나 개선할 점이 있으면 알려줘"
```
```bash
claude "components/SignupForm.tsx의 에러 처리가 충분한지 확인해줘"
```
---
## 에러 디버깅
에러 메시지를 그대로 붙여넣으면 됩니다.
```bash
claude "pnpm dev 실행 시 아래 에러가 발생해:
Error: Cannot find module '@/lib/supabase'
at Function.Module._resolveFilename
어떻게 고치면 돼?"
```
또는 에러 파일을 직접 전달:
```bash
cat error.log | claude "이 에러를 분석하고 수정 방법을 알려줘"
```
---
## 작업 확인 및 취소
Claude Code가 파일을 수정하기 전에 항상 확인을 요청합니다.
```
Edit components/SignupForm.tsx? (y/n/s)
y: 수정 허용
n: 이 파일은 건너뜀
s: 세션 내 모든 수정 자동 허용
```
**잘못된 수정이 걱정되면:**
```bash
# Git으로 안전망 확보
git add . && git stash # 작업 전 stash
claude "..." # 작업 실행
git diff # 변경사항 확인
git stash pop # 문제 있으면 복구
```
---
## 실전 워크플로우 패턴
### 패턴 1: 기능 추가
```bash
git checkout -b feat/auth # 브랜치 생성
claude "로그인 기능 추가해줘" # 기능 구현
pnpm dev # 동작 확인
git add . && git commit -m "..."
```
### 패턴 2: 리팩토링
```bash
claude "components/ 폴더의 중복 코드를 찾아서 공통 훅으로 분리해줘"
```
### 패턴 3: 타입 일괄 추가
```bash
claude "이 프로젝트의 모든 TypeScript 파일에서 any 타입을 찾아서
적절한 타입으로 교체해줘"
```
### 패턴 4: 테스트 작성
```bash
claude "lib/mdx.ts의 getAllCourses, getCourse 함수에 대한
Jest 테스트를 작성해줘"
```
---
## 주의사항
**Claude Code가 잘 못하는 것:**
- 완전히 새로운 디자인 창작 (→ Cursor + v0.dev 활용)
- 실시간 미리보기가 필요한 UI 조작 (→ Cursor가 유리)
- 매우 긴 단일 파일 수정 (1000줄 이상은 나눠서 요청)
**비용 절약 팁:**
- `/compact` 명령으로 대화를 주기적으로 요약
- 큰 파일 분석보다 목적에 맞는 질문을 짧게
- 작업이 완료되면 `/clear`로 컨텍스트 초기화 후 새 작업 시작
---
## 8장 보강 프로세스 적용: 멀티파일 검증 루프
이 챕터의 핵심은 "많이 고치는 것"이 아니라 **일관되게 검증하는 것**입니다.
6~7장과 동일하게 실패 패턴을 먼저 차단하는 운영 루프를 적용합니다.
### 권장 루프: 계획 → 수정 → 검증 → 정리
1. **계획**
- 변경 파일 목록과 목적을 먼저 텍스트로 고정
2. **수정**
- 한 번에 한 목적(예: 인증, UI, 타입)만 처리
3. **검증**
- `git diff --stat` → `git diff` → `pnpm dev` 순서로 확인
4. **정리**
- 변경 이유/영향/다음 작업을 3줄로 요약
### 멀티파일 작업 실패 패턴 TOP 5
1. **요청 범위가 너무 큼**
- 대응: 기능 단위를 2~4파일 묶음으로 쪼개기
2. **생성 파일만 보고 수정 파일 검증 누락**
- 대응: 기존 파일(`Edit`) diff를 우선 점검
3. **타입/런타임 검증 생략**
- 대응: 최소 `pnpm dev`로 런타임 확인
4. **한 세션에 서로 다른 기능 혼합**
- 대응: 작업 단위마다 `/clear` 또는 새 세션
5. **커밋 기준 없음**
- 대응: "하나의 목적 = 하나의 커밋" 원칙 유지
### 08챕터 실전 체크리스트 (DoD)
- [ ] 작업 전 변경 목표(파일/목적) 기록 완료
- [ ] 멀티파일 수정 후 diff 검토 완료
- [ ] 최소 1회 런타임 확인 완료
- [ ] 변경 요약(이유/영향/다음 단계) 작성 완료
- [ ] 커밋 단위가 기능 목적과 일치하는지 확인 완료
> **다음 챕터 입력값:** 브랜치 전략, 커밋 메시지 규칙, PR 요약 템플릿
공개 문서 변환 코드 (HTML)
<hr>
<h2>title: "멀티파일 워크플로우"
slug: "08-multifile-workflow"
description: "Claude Code로 여러 파일을 동시에 작업하는 방법"
order: 8
date: "2026-03-10"
level: 2
draft: false</h2>
<h1>멀티파일 워크플로우</h1>
<blockquote>
<p><strong>이 챕터를 마치면</strong> Claude Code로 여러 파일을 한 번에 수정하는 요청을 할 수 있어요.</p>
</blockquote>
<p>Claude Code의 가장 큰 강점은 <strong>여러 파일을 동시에 이해하고 수정</strong>하는 능력이에요.
Cursor가 열린 파일 위주로 작업한다면, Claude Code는 프로젝트 전체를 보고 작업해요.</p>
<hr>
<h2>실전 예시: 회원가입 기능 추가</h2>
<p>아래 한 줄 요청으로 Claude Code가 무엇을 하는지 보겠습니다.</p>
<pre><code class="language-bash">claude "Supabase를 사용한 이메일 회원가입 기능을 추가해줘.
폼 컴포넌트, 서버 액션, 타입 파일까지 포함해서."
</code></pre>
<p>Claude Code의 실제 작업 순서:</p>
<pre><code>✻ 계획 수립
1. 기존 파일 구조 파악
2. Supabase 클라이언트 설정 확인
3. 필요한 파일 목록 작성
✻ 실행
Read: app/layout.tsx ← 기존 레이아웃 파악
Read: lib/supabase.ts ← 클라이언트 설정 확인 (없으면 생성)
Write: lib/supabase.ts ← Supabase 클라이언트
Write: types/auth.ts ← 타입 정의
Write: app/actions/auth.ts ← 서버 액션
Write: components/SignupForm.tsx ← 폼 컴포넌트
Edit: app/page.tsx ← 메인 페이지에 폼 연결
✻ 완료 보고
6개 파일 생성/수정 완료
pnpm dev로 확인하세요.
</code></pre>
<p>한 번의 요청으로 6개 파일이 일관되게 작성됩니다.</p>
<hr>
<h2>효과적인 요청 작성법</h2>
<h3>맥락을 충분히 주기</h3>
<p>❌ 너무 짧은 요청:</p>
<pre><code>claude "로그인 만들어줘"
</code></pre>
<p>✅ 맥락이 있는 요청:</p>
<pre><code>claude "Next.js 15 App Router + Supabase Auth로 Google 소셜 로그인을 추가해줘.
- 로그인 버튼은 components/LoginButton.tsx로
- 콜백 처리는 app/auth/callback/route.ts로
- 로그인 성공 시 /dashboard로 리다이렉트"
</code></pre>
<h3>단계별로 나누기</h3>
<p>한 번에 너무 많이 요청하면 실수가 늘어납니다.</p>
<pre><code class="language-bash"># 1단계: 기반 설정
claude "Supabase 클라이언트 설정 파일을 만들어줘 (lib/supabase.ts)"
# 2단계: 인증 로직
claude "방금 만든 Supabase 클라이언트로 이메일 로그인 서버 액션을 만들어줘"
# 3단계: UI
claude "로그인 서버 액션을 사용하는 LoginForm 컴포넌트를 만들어줘"
</code></pre>
<hr>
<h2>코드 리뷰 요청</h2>
<p>작업 후 바로 리뷰를 요청할 수 있습니다.</p>
<pre><code class="language-bash">claude "방금 만든 인증 코드에서 보안 문제나 개선할 점이 있으면 알려줘"
</code></pre>
<pre><code class="language-bash">claude "components/SignupForm.tsx의 에러 처리가 충분한지 확인해줘"
</code></pre>
<hr>
<h2>에러 디버깅</h2>
<p>에러 메시지를 그대로 붙여넣으면 됩니다.</p>
<pre><code class="language-bash">claude "pnpm dev 실행 시 아래 에러가 발생해:
Error: Cannot find module '@/lib/supabase'
at Function.Module._resolveFilename
어떻게 고치면 돼?"
</code></pre>
<p>또는 에러 파일을 직접 전달:</p>
<pre><code class="language-bash">cat error.log | claude "이 에러를 분석하고 수정 방법을 알려줘"
</code></pre>
<hr>
<h2>작업 확인 및 취소</h2>
<p>Claude Code가 파일을 수정하기 전에 항상 확인을 요청합니다.</p>
<pre><code>Edit components/SignupForm.tsx? (y/n/s)
y: 수정 허용
n: 이 파일은 건너뜀
s: 세션 내 모든 수정 자동 허용
</code></pre>
<p><strong>잘못된 수정이 걱정되면:</strong></p>
<pre><code class="language-bash"># Git으로 안전망 확보
git add . && git stash # 작업 전 stash
claude "..." # 작업 실행
git diff # 변경사항 확인
git stash pop # 문제 있으면 복구
</code></pre>
<hr>
<h2>실전 워크플로우 패턴</h2>
<h3>패턴 1: 기능 추가</h3>
<pre><code class="language-bash">git checkout -b feat/auth # 브랜치 생성
claude "로그인 기능 추가해줘" # 기능 구현
pnpm dev # 동작 확인
git add . && git commit -m "..."
</code></pre>
<h3>패턴 2: 리팩토링</h3>
<pre><code class="language-bash">claude "components/ 폴더의 중복 코드를 찾아서 공통 훅으로 분리해줘"
</code></pre>
<h3>패턴 3: 타입 일괄 추가</h3>
<pre><code class="language-bash">claude "이 프로젝트의 모든 TypeScript 파일에서 any 타입을 찾아서
적절한 타입으로 교체해줘"
</code></pre>
<h3>패턴 4: 테스트 작성</h3>
<pre><code class="language-bash">claude "lib/mdx.ts의 getAllCourses, getCourse 함수에 대한
Jest 테스트를 작성해줘"
</code></pre>
<hr>
<h2>주의사항</h2>
<p><strong>Claude Code가 잘 못하는 것:</strong></p>
<ul>
<li>완전히 새로운 디자인 창작 (→ Cursor + v0.dev 활용)</li>
<li>실시간 미리보기가 필요한 UI 조작 (→ Cursor가 유리)</li>
<li>매우 긴 단일 파일 수정 (1000줄 이상은 나눠서 요청)</li>
</ul>
<p><strong>비용 절약 팁:</strong></p>
<ul>
<li><code>/compact</code> 명령으로 대화를 주기적으로 요약</li>
<li>큰 파일 분석보다 목적에 맞는 질문을 짧게</li>
<li>작업이 완료되면 <code>/clear</code>로 컨텍스트 초기화 후 새 작업 시작</li>
</ul>
<hr>
<h2>8장 보강 프로세스 적용: 멀티파일 검증 루프</h2>
<p>이 챕터의 핵심은 "많이 고치는 것"이 아니라 <strong>일관되게 검증하는 것</strong>입니다.
6~7장과 동일하게 실패 패턴을 먼저 차단하는 운영 루프를 적용합니다.</p>
<h3>권장 루프: 계획 → 수정 → 검증 → 정리</h3>
<ol>
<li><p><strong>계획</strong></p>
<ul>
<li>변경 파일 목록과 목적을 먼저 텍스트로 고정</li>
</ul>
</li>
<li><p><strong>수정</strong></p>
<ul>
<li>한 번에 한 목적(예: 인증, UI, 타입)만 처리</li>
</ul>
</li>
<li><p><strong>검증</strong></p>
<ul>
<li><code>git diff --stat</code> → <code>git diff</code> → <code>pnpm dev</code> 순서로 확인</li>
</ul>
</li>
<li><p><strong>정리</strong></p>
<ul>
<li>변경 이유/영향/다음 작업을 3줄로 요약</li>
</ul>
</li>
</ol>
<h3>멀티파일 작업 실패 패턴 TOP 5</h3>
<ol>
<li><p><strong>요청 범위가 너무 큼</strong></p>
<ul>
<li>대응: 기능 단위를 2~4파일 묶음으로 쪼개기</li>
</ul>
</li>
<li><p><strong>생성 파일만 보고 수정 파일 검증 누락</strong></p>
<ul>
<li>대응: 기존 파일(<code>Edit</code>) diff를 우선 점검</li>
</ul>
</li>
<li><p><strong>타입/런타임 검증 생략</strong></p>
<ul>
<li>대응: 최소 <code>pnpm dev</code>로 런타임 확인</li>
</ul>
</li>
<li><p><strong>한 세션에 서로 다른 기능 혼합</strong></p>
<ul>
<li>대응: 작업 단위마다 <code>/clear</code> 또는 새 세션</li>
</ul>
</li>
<li><p><strong>커밋 기준 없음</strong></p>
<ul>
<li>대응: "하나의 목적 = 하나의 커밋" 원칙 유지</li>
</ul>
</li>
</ol>
<h3>08챕터 실전 체크리스트 (DoD)</h3>
<ul>
<li><input disabled="" type="checkbox"> 작업 전 변경 목표(파일/목적) 기록 완료</li>
<li><input disabled="" type="checkbox"> 멀티파일 수정 후 diff 검토 완료</li>
<li><input disabled="" type="checkbox"> 최소 1회 런타임 확인 완료</li>
<li><input disabled="" type="checkbox"> 변경 요약(이유/영향/다음 단계) 작성 완료</li>
<li><input disabled="" type="checkbox"> 커밋 단위가 기능 목적과 일치하는지 확인 완료</li>
</ul>
<blockquote>
<p><strong>다음 챕터 입력값:</strong> 브랜치 전략, 커밋 메시지 규칙, PR 요약 템플릿</p>
</blockquote>