6 6
7> Claude Code를 사용하여 코드베이스 탐색, 버그 수정, 리팩토링, 테스트 및 기타 일상적인 작업을 위한 단계별 가이드입니다.7> Claude Code를 사용하여 코드베이스 탐색, 버그 수정, 리팩토링, 테스트 및 기타 일상적인 작업을 위한 단계별 가이드입니다.
8 8
9이 페이지는 일상적인 개발을 위한 실용적인 워크플로우를 다룹니다: 낯선 코드 탐색, 디버깅, 리팩토링, 테스트 작성, PR 생성 및 세션 관리. 각 섹션에는 자신의 프로젝트에 맞게 조정할 수 있는 예제 프롬프트가 포함되어 있습니다. 더 높은 수준의 패턴과 팁은 [모범 사례](/ko/best-practices)를 참조하십시오.9이 페이지는 일상적인 개발을 위한 짧은 레시피를 모아놓았습니다. 프롬프팅 및 컨텍스트 관리에 대한 더 높은 수준의 지침은 [모범 사례](/ko/best-practices)를 참조하십시오.
10 10
11## 새로운 코드베이스 이해하기11이 페이지는 다음을 다룹니다:
12 12
13### 코드베이스의 빠른 개요 얻기13* [프롬프트 레시피](#prompt-recipes) - 코드 탐색, 버그 수정, 리팩토링, 테스트, PR 및 문서화
14* [이전 대화 재개](#resume-previous-conversations) - 작업이 여러 세션에 걸쳐 진행될 수 있도록
15* [worktree를 사용하여 병렬 세션 실행](#run-parallel-sessions-with-worktrees) - 동시 편집이 충돌하지 않도록
16* [편집 전에 계획](#plan-before-editing) - 변경사항이 디스크에 닿기 전에 검토
17* [subagent에게 연구 위임](#delegate-research-to-subagents) - 주 컨텍스트를 깨끗하게 유지
18* [Claude를 스크립트로 파이프](#pipe-claude-into-scripts) - CI 및 배치 처리용
19
20## 프롬프트 레시피
21
22이는 낯선 코드 탐색, 디버깅, 리팩토링, 테스트 작성, PR 생성과 같은 일상적인 작업을 위한 프롬프트 패턴입니다. 각각은 모든 Claude Code 표면에서 작동하며, 프로젝트에 맞게 표현을 조정하십시오.
23
24### 새로운 코드베이스 이해하기
25
26#### 코드베이스의 빠른 개요 얻기
14 27
15새로운 프로젝트에 방금 참여했고 그 구조를 빠르게 이해해야 한다고 가정해봅시다.28새로운 프로젝트에 방금 참여했고 그 구조를 빠르게 이해해야 한다고 가정해봅시다.
16 29
56 * 프로젝트별 용어의 용어집 요청하기69 * 프로젝트별 용어의 용어집 요청하기
57</Tip>70</Tip>
58 71
59### 관련 코드 찾기72#### 관련 코드 찾기
60 73
61특정 기능이나 기능과 관련된 코드를 찾아야 한다고 가정해봅시다.74특정 기능이나 기능과 관련된 코드를 찾아야 한다고 가정해봅시다.
62 75
90 103
91***104***
92 105
93## 효율적으로 버그 수정하기106### 효율적으로 버그 수정하기
94 107
95오류 메시지가 나타났고 그 원인을 찾아 수정해야 한다고 가정해봅시다.108오류 메시지가 나타났고 그 원인을 찾아 수정해야 한다고 가정해봅시다.
96 109
124 137
125***138***
126 139
127## 코드 리팩토링140### 코드 리팩토링
128 141
129오래된 코드를 최신 패턴과 관행을 사용하도록 업데이트해야 한다고 가정해봅시다.142오래된 코드를 최신 패턴과 관행을 사용하도록 업데이트해야 한다고 가정해봅시다.
130 143
164 177
165***178***
166 179
167## 특화된 subagent 사용하기180### 테스트 작업하기
168
169특정 작업을 더 효과적으로 처리하기 위해 특화된 AI subagent를 사용하고 싶다고 가정해봅시다.
170
171<Steps>
172 <Step title="사용 가능한 subagent 보기">
173 ```text theme={null}
174 /agents
175 ```
176
177 이것은 모든 사용 가능한 subagent를 표시하고 새로운 것을 만들 수 있게 해줍니다.
178 </Step>
179
180 <Step title="자동으로 subagent 사용하기">
181 Claude Code는 자동으로 특정 작업을 특화된 subagent에게 위임합니다:
182
183 ```text theme={null}
184 review my recent code changes for security issues
185 ```
186
187 ```text theme={null}
188 run all tests and fix any failures
189 ```
190 </Step>
191
192 <Step title="명시적으로 특정 subagent 요청하기">
193 ```text theme={null}
194 use the code-reviewer subagent to check the auth module
195 ```
196
197 ```text theme={null}
198 have the debugger subagent investigate why users can't log in
199 ```
200 </Step>
201
202 <Step title="워크플로우를 위한 사용자 정의 subagent 만들기">
203 ```text theme={null}
204 /agents
205 ```
206
207 그런 다음 "Create New subagent"를 선택하고 프롬프트를 따라 다음을 정의합니다:
208
209 * subagent의 목적을 설명하는 고유 식별자 (예: `code-reviewer`, `api-designer`).
210 * Claude가 이 에이전트를 사용해야 할 때
211 * 액세스할 수 있는 도구
212 * 에이전트의 역할과 동작을 설명하는 시스템 프롬프트
213 </Step>
214</Steps>
215
216<Tip>
217 팁:
218
219 * 팀 공유를 위해 `.claude/agents/`에 프로젝트별 subagent 만들기
220 * 자동 위임을 활성화하기 위해 설명적인 `description` 필드 사용하기
221 * 각 subagent가 실제로 필요한 것으로 도구 액세스 제한하기
222 * 자세한 예제는 [subagent 문서](/ko/sub-agents)를 확인하기
223</Tip>
224
225***
226
227## Plan Mode를 사용하여 안전한 코드 분석
228
229Plan Mode는 Claude에게 읽기 전용 작업으로 코드베이스를 분석하여 계획을 세우도록 지시하며, 코드베이스 탐색, 복잡한 변경 계획 또는 코드 안전한 검토에 완벽합니다. Plan Mode에서 Claude는 [`AskUserQuestion`](/ko/tools-reference)을 사용하여 계획을 제안하기 전에 요구사항을 수집하고 목표를 명확히 합니다.
230
231### Plan Mode를 사용할 때
232
233* **다단계 구현**: 기능이 많은 파일을 편집해야 할 때
234* **코드 탐색**: 무엇이든 변경하기 전에 코드베이스를 철저히 조사하고 싶을 때
235* **대화형 개발**: Claude와 방향을 반복하고 싶을 때
236
237### Plan Mode 사용 방법
238
239**세션 중에 Plan Mode 켜기**
240
241**Shift+Tab**을 사용하여 세션 중에 Plan Mode로 전환할 수 있습니다.
242
243Normal Mode에 있으면 **Shift+Tab**은 먼저 Auto-Accept Mode로 전환되며, 터미널 하단에 `⏵⏵ accept edits on`으로 표시됩니다. 그 다음 **Shift+Tab**은 Plan Mode로 전환되며, `⏸ plan mode on`으로 표시됩니다.
244
245**Plan Mode에서 새 세션 시작하기**
246
247Plan Mode에서 새 세션을 시작하려면 `--permission-mode plan` 플래그를 사용합니다:
248
249```bash theme={null}
250claude --permission-mode plan
251```
252
253**Plan Mode에서 "헤드리스" 쿼리 실행하기**
254
255`-p`를 사용하여 Plan Mode에서 직접 쿼리를 실행할 수도 있습니다 (즉, ["헤드리스 모드"](/ko/headless)에서):
256
257```bash theme={null}
258claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"
259```
260
261### 예제: 복잡한 리팩토링 계획하기
262
263```bash theme={null}
264claude --permission-mode plan
265```
266
267```text theme={null}
268I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.
269```
270
271Claude는 현재 구현을 분석하고 포괄적인 계획을 만듭니다. 후속 질문으로 정제합니다:
272
273```text theme={null}
274What about backward compatibility?
275```
276
277```text theme={null}
278How should we handle database migration?
279```
280
281<Tip>`Ctrl+G`를 눌러 기본 텍스트 편집기에서 계획을 열고, Claude가 진행하기 전에 직접 편집할 수 있습니다.</Tip>
282
283계획을 수락하면 Claude는 계획 콘텐츠에서 자동으로 세션 이름을 지정합니다. 이름은 프롬프트 바와 세션 선택기에 나타납니다. 이미 `--name` 또는 `/rename`으로 이름을 설정한 경우 계획을 수락해도 덮어쓰지 않습니다.
284
285### Plan Mode를 기본값으로 구성하기
286
287```json theme={null}
288// .claude/settings.json
289{
290 "permissions": {
291 "defaultMode": "plan"
292 }
293}
294```
295
296더 많은 구성 옵션은 [설정 문서](/ko/settings#available-settings)를 참조하십시오.
297
298***
299
300## 테스트 작업하기
301 181
302적용되지 않은 코드에 대한 테스트를 추가해야 한다고 가정해봅시다.182적용되지 않은 코드에 대한 테스트를 추가해야 한다고 가정해봅시다.
303 183
333 213
334***214***
335 215
336## 풀 요청 만들기216### 풀 요청 만들기
337 217
338Claude에게 직접 풀 요청을 만들도록 요청하거나 ("create a pr for my changes"), 단계별로 Claude를 안내할 수 있습니다:218Claude에게 직접 풀 요청을 만들도록 요청하거나 ("create a pr for my changes"), 단계별로 Claude를 안내할 수 있습니다:
339 219
357 </Step>237 </Step>
358</Steps>238</Steps>
359 239
360`gh pr create`를 사용하여 PR을 만들면 세션이 자동으로 해당 PR에 연결됩니다. 나중에 `claude --from-pr <number>`로 재개할 수 있습니다.240`gh pr create`를 사용하여 PR을 만들면 세션이 자동으로 해당 PR에 연결됩니다. 나중에 `claude --from-pr <number>`로 재개하거나 [`/resume` 선택기](/ko/sessions#use-the-session-picker)에 PR URL을 붙여넣어 재개할 수 있습니다.
361 241
362<Tip>242<Tip>
363 Claude가 생성한 PR을 제출하기 전에 검토하고 Claude에게 잠재적 위험이나 고려사항을 강조하도록 요청하십시오.243 Claude가 생성한 PR을 제출하기 전에 검토하고 Claude에게 잠재적 위험이나 고려사항을 강조하도록 요청하십시오.
364</Tip>244</Tip>
365 245
366## 문서 처리하기246### 문서 처리하기
367 247
368코드에 대한 문서를 추가하거나 업데이트해야 한다고 가정해봅시다.248코드에 대한 문서를 추가하거나 업데이트해야 한다고 가정해봅시다.
369 249
403 283
404***284***
405 285
406## 노트 및 비코드 폴더에서 작업하기286### 노트 및 비코드 폴더에서 작업하기
407 287
408Claude Code는 모든 디렉토리에서 작동합니다. 노트 저장소, 문서 폴더 또는 마크다운 파일의 모든 컬렉션 내에서 실행하여 코드처럼 콘텐츠를 검색, 편집 및 재구성합니다.288Claude Code는 모든 디렉토리에서 작동합니다. 노트 저장소, 문서 폴더 또는 마크다운 파일의 모든 컬렉션 내에서 실행하여 코드처럼 콘텐츠를 검색, 편집 및 재구성합니다.
409 289
411 291
412***292***
413 293
414## 이미지 작업하기294### 이미지 작업하기
415 295
416코드베이스에서 이미지를 작업해야 하고 Claude의 이미지 콘텐츠 분석 도움을 원한다고 가정해봅시다.296코드베이스에서 이미지를 작업해야 하고 Claude의 이미지 콘텐츠 분석 도움을 원한다고 가정해봅시다.
417 297
471 351
472***352***
473 353
474## 파일 및 디렉토리 참조하기354### 파일 및 디렉토리 참조하기
475 355
476@를 사용하여 Claude가 읽을 때까지 기다리지 않고 파일이나 디렉토리를 빠르게 포함합니다.356@를 사용하여 Claude가 읽을 때까지 기다리지 않고 파일이나 디렉토리를 빠르게 포함합니다.
477 357
512 392
513***393***
514 394
515## 확장된 사고 사용하기 (thinking mode)395### 일정에 따라 Claude 실행하기
516
517[확장된 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)는 기본적으로 활성화되어 있으며, Claude가 복잡한 문제를 단계별로 추론할 수 있는 공간을 제공합니다. 이 추론은 `Ctrl+O`로 전환할 수 있는 자세한 모드에서 볼 수 있습니다. 확장된 사고 중에 진행 상황 힌트가 표시기 아래에 나타나 Claude가 적극적으로 작업 중임을 보여줍니다.
518
519또한 [노력을 지원하는 모델](/ko/model-config#adjust-effort-level)은 적응형 추론을 사용합니다: 고정된 사고 토큰 예산 대신 모델은 노력 수준 설정과 작업에 따라 동적으로 사고할지 여부와 얼마나 많이 사고할지 결정합니다. 적응형 추론을 통해 Claude는 일상적인 프롬프트에 더 빠르게 응답하고 이점을 얻을 수 있는 단계를 위해 더 깊은 사고를 예약할 수 있습니다.
520
521확장된 사고는 복잡한 아키텍처 결정, 어려운 버그, 다단계 구현 계획 및 다양한 접근 방식 간의 트레이드오프 평가에 특히 유용합니다.
522
523<Note>
524 "think", "think hard", "think more"와 같은 구문은 일반 프롬프트 지시로 해석되며 사고 토큰을 할당하지 않습니다.
525</Note>
526
527### thinking mode 구성하기
528
529사고는 기본적으로 활성화되어 있지만 조정하거나 비활성화할 수 있습니다.
530
531| 범위 | 구성 방법 | 세부 정보 |
532| -------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
533| **노력 수준** | `/effort` 실행, `/model`에서 조정, 또는 [`CLAUDE_CODE_EFFORT_LEVEL`](/ko/env-vars) 설정 | [지원되는 모델](/ko/model-config#adjust-effort-level)에서 사고 깊이 제어 |
534| **`ultrathink` 키워드** | 프롬프트의 어디든 "ultrathink" 포함 | 해당 턴에 대해 더 많이 추론하도록 모델에 지시하는 컨텍스트 내 지시를 추가합니다. 노력 수준 자체를 변경하지 않습니다. [노력 수준 조정](/ko/model-config#adjust-effort-level) 참조 |
535| **토글 단축키** | `Option+T` (macOS) 또는 `Alt+T` (Windows/Linux) 누르기 | 현재 세션에 대해 사고 켜기/끄기 (모든 모델). [터미널 구성](/ko/terminal-config)이 필요할 수 있습니다 |
536| **전역 기본값** | `/config`를 사용하여 thinking mode 토글 | 모든 프로젝트에서 기본값 설정 (모든 모델).<br />`~/.claude/settings.json`에 `alwaysThinkingEnabled`로 저장됩니다 |
537| **토큰 예산 제한** | [`MAX_THINKING_TOKENS`](/ko/env-vars) 환경 변수 설정 | 사고 예산을 특정 토큰 수로 제한합니다. 적응형 추론이 있는 모델에서는 적응형 추론이 비활성화되지 않으면 `0`만 적용됩니다. 예: `export MAX_THINKING_TOKENS=10000` |
538
539Claude의 사고 과정을 보려면 `Ctrl+O`를 눌러 자세한 모드를 전환하고 회색 이탤릭 텍스트로 표시된 내부 추론을 확인하십시오.
540
541### 확장된 사고 작동 방식
542
543확장된 사고는 Claude가 응답하기 전에 수행하는 내부 추론의 양을 제어합니다. 더 많은 사고는 솔루션을 탐색하고, 엣지 케이스를 분석하고, 실수를 자체 수정할 수 있는 더 많은 공간을 제공합니다.
544
545[노력을 지원하는 모델](/ko/model-config#adjust-effort-level)에서 사고는 적응형 추론을 사용합니다: 모델은 선택한 노력 수준에 따라 동적으로 사고 토큰을 할당합니다. 이것은 속도와 추론 깊이 간의 트레이드오프를 조정하는 권장 방법입니다. 노력 수준이 그렇지 않으면 생성할 것보다 Claude가 더 많거나 적게 사고하기를 원하면 프롬프트나 `CLAUDE.md`에서 직접 그렇게 말할 수도 있습니다.
546
547이전 모델에서 사고는 출력 할당에서 최대 31,999개 토큰의 고정 예산을 사용합니다. [`MAX_THINKING_TOKENS`](/ko/env-vars) 환경 변수로 이를 제한하거나 `/config` 또는 `Option+T`/`Alt+T` 토글을 통해 사고를 완전히 비활성화할 수 있습니다.
548
549적응형 추론이 있는 모델에서 `MAX_THINKING_TOKENS`는 `0`으로 설정하여 사고를 비활성화하거나 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1`이 모델을 고정 예산으로 되돌릴 때만 적용됩니다. `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`은 Opus 4.6 및 Sonnet 4.6에만 적용됩니다. Opus 4.7은 항상 적응형 추론을 사용하며 고정 사고 예산을 지원하지 않습니다. [환경 변수](/ko/env-vars)를 참조하십시오.
550
551<Warning>
552 사고 요약이 편집되더라도 사용된 모든 사고 토큰에 대해 요금이 청구됩니다. 대화형 모드에서 사고는 기본적으로 축소된 스텁으로 나타납니다. `settings.json`에서 `showThinkingSummaries: true`를 설정하여 전체 요약을 표시합니다.
553</Warning>
554
555***
556
557## 이전 대화 재개하기
558
559Claude Code를 시작할 때 이전 세션을 재개할 수 있습니다:
560
561* `claude --continue`는 현재 디렉토리에서 가장 최근 대화를 계속합니다
562* `claude --resume`은 대화 선택기를 열거나 이름으로 재개합니다
563* `claude --from-pr 123`은 특정 풀 요청에 연결된 세션을 재개합니다
564
565활성 세션 내에서 `/resume`을 사용하여 다른 대화로 전환합니다.
566
567선택한 세션이 오래되고 충분히 커서 다시 읽으면 사용 한도의 상당한 부분을 소비할 경우, `--resume`, `--continue` 및 `/resume`은 전체 기록을 로드하는 대신 요약에서 재개할 것을 제안합니다. 이 프롬프트는 Amazon Bedrock, Google Cloud Vertex AI 또는 Microsoft Foundry에서 사용할 수 없습니다.
568
569세션은 프로젝트 디렉토리별로 저장됩니다. 기본적으로 `/resume` 선택기는 현재 worktree의 대화형 세션을 표시하며, 다른 worktree 또는 프로젝트로 목록을 확대하고, 검색하고, 미리보고, 이름을 바꾸는 키보드 단축키가 있습니다. `/add-dir`으로 현재 디렉토리를 추가한 다른 곳에서 시작된 세션도 기본적으로 포함됩니다. 전체 단축키 참조는 아래의 [세션 선택기 사용하기](#use-the-session-picker)를 참조하십시오.
570
571다른 worktree의 세션을 선택하면 Claude Code는 먼저 디렉토리를 전환할 필요 없이 직접 재개합니다. 관련 없는 프로젝트의 세션을 선택하면 `cd` 및 재개 명령을 클립보드에 복사합니다.
572
573이름으로 재개하면 현재 저장소 및 해당 worktree 전체에서 해결됩니다. `claude --resume <name>` 및 `/resume <name>` 모두 정확한 일치를 찾고 세션이 다른 worktree에 있더라도 직접 재개합니다.
574
575이름이 모호하면 `claude --resume <name>`은 이름을 검색 용어로 미리 채운 선택기를 엽니다. 세션 내에서 `/resume <name>`은 대신 오류를 보고하므로 `/resume`을 인수 없이 실행하여 선택기를 열고 선택합니다.
576
577`claude -p` 또는 SDK 호출로 생성된 세션은 선택기에 나타나지 않지만 세션 ID를 `claude --resume <session-id>`에 직접 전달하여 재개할 수 있습니다.
578
579### 세션 이름 지정하기
580
581나중에 찾기 위해 세션에 설명적인 이름을 지정합니다. 이것은 여러 작업이나 기능을 작업할 때 모범 사례입니다.
582
583<Steps>
584 <Step title="세션 이름 지정하기">
585 시작 시 `-n`으로 세션 이름을 지정합니다:
586
587 ```bash theme={null}
588 claude -n auth-refactor
589 ```
590
591 또는 세션 중에 `/rename`을 사용하며, 이는 프롬프트 바에도 이름을 표시합니다:
592
593 ```text theme={null}
594 /rename auth-refactor
595 ```
596
597 선택기에서 세션 이름을 바꿀 수도 있습니다: `/resume`을 실행하고, 세션으로 이동한 다음 `Ctrl+R`을 누릅니다.
598 </Step>
599
600 <Step title="나중에 이름으로 재개하기">
601 명령줄에서:
602
603 ```bash theme={null}
604 claude --resume auth-refactor
605 ```
606
607 또는 활성 세션 내에서:
608
609 ```text theme={null}
610 /resume auth-refactor
611 ```
612 </Step>
613</Steps>
614
615### 세션 선택기 사용하기
616
617`/resume` 명령 (또는 인수 없이 `claude --resume`)은 다음 기능이 있는 대화형 세션 선택기를 엽니다:
618
619**선택기의 키보드 단축키:**
620
621| 단축키 | 작업 |
622| :--------------------------- | :------------------------------------------------------------------------- |
623| `↑` / `↓` | 세션 간 이동 |
624| `→` / `←` | 그룹화된 세션 확장 또는 축소 |
625| `Enter` | 강조 표시된 세션 선택 및 재개 |
626| `Space` | 세션 콘텐츠 미리보기. `Ctrl+V`도 이를 캡처하지 않는 터미널에서 작동합니다 |
627| `Ctrl+R` | 강조 표시된 세션 이름 바꾸기 |
628| `/` 또는 `Space` 이외의 인쇄 가능한 문자 | 검색 모드 진입 및 세션 필터링 |
629| `Ctrl+A` | 이 컴퓨터의 모든 프로젝트에서 세션 표시. 다시 누르면 현재 저장소 복원 |
630| `Ctrl+W` | 현재 저장소의 모든 worktree에서 세션 표시. 다시 누르면 현재 worktree 복원. 다중 worktree 저장소에서만 표시됨 |
631| `Ctrl+B` | 현재 git 분기의 세션으로 필터링. 다시 누르면 모든 분기의 세션 표시 |
632| `Esc` | 선택기 또는 검색 모드 종료 |
633
634**세션 구성:**
635
636선택기는 유용한 메타데이터가 있는 세션을 표시합니다:
637
638* 세션 이름 (설정된 경우), 그렇지 않으면 대화 요약 또는 첫 번째 사용자 프롬프트
639* 마지막 활동 이후 경과 시간
640* 메시지 수
641* Git 분기 (해당하는 경우)
642* `Ctrl+A`로 모든 프로젝트로 확대한 후 표시되는 프로젝트 경로
643
644포크된 세션 (`/branch`, `/rewind` 또는 `--fork-session`으로 생성됨)은 루트 세션 아래에 그룹화되어 관련 대화를 더 쉽게 찾을 수 있습니다.
645
646<Tip>
647 팁:
648
649 * **세션 조기 이름 지정**: 고유한 작업을 시작할 때 `/rename`을 사용합니다—나중에 "payment-integration"을 찾기가 "explain this function"보다 훨씬 쉽습니다
650 * 현재 디렉토리에서 가장 최근 대화에 빠르게 액세스하려면 `--continue` 사용
651 * 필요한 세션을 알 때 `--resume session-name` 사용
652 * 검색하고 선택해야 할 때 `--resume` (이름 없이) 사용
653 * 스크립트의 경우 `claude --continue --print "prompt"`를 사용하여 비대화형 모드에서 재개
654 * 선택기에서 `Space`를 눌러 재개하기 전에 세션을 미리봅니다
655 * 재개된 대화는 원본과 동일한 모델 및 구성으로 시작됩니다
656
657 작동 방식:
658
659 1. **대화 저장소**: 모든 대화는 전체 메시지 기록과 함께 로컬에 자동으로 저장됩니다
660 2. **메시지 역직렬화**: 재개할 때 전체 메시지 기록이 복원되어 컨텍스트를 유지합니다
661 3. **도구 상태**: 이전 대화의 도구 사용 및 결과가 보존됩니다
662 4. **컨텍스트 복원**: 대화는 모든 이전 컨텍스트와 함께 재개됩니다
663</Tip>
664
665***
666
667## Git worktree를 사용하여 병렬 Claude Code 세션 실행하기
668
669여러 작업을 동시에 수행할 때 각 Claude 세션이 변경사항이 충돌하지 않도록 코드베이스의 자체 복사본을 가져야 합니다. Git worktree는 각각 자체 파일과 분기를 가지면서 동일한 저장소 기록 및 원격 연결을 공유하는 별도의 작업 디렉토리를 만들어 이를 해결합니다. 이는 한 worktree에서 기능을 작업하는 동안 Claude가 다른 worktree에서 버그를 수정할 수 있으며, 어느 세션도 다른 세션을 방해하지 않음을 의미합니다.
670
671`--worktree` (`-w`) 플래그를 사용하여 격리된 worktree를 만들고 Claude를 시작합니다. 전달하는 값은 worktree 디렉토리 이름과 분기 이름이 됩니다:
672
673```bash theme={null}
674# "feature-auth"라는 worktree에서 Claude 시작
675# 새 분기를 사용하여 .claude/worktrees/feature-auth/ 생성
676claude --worktree feature-auth
677
678# 별도의 worktree에서 다른 세션 시작
679claude --worktree bugfix-123
680```
681
682이름을 생략하면 Claude가 자동으로 임의의 이름을 생성합니다:
683
684```bash theme={null}
685# "bright-running-fox"와 같은 이름 자동 생성
686claude --worktree
687```
688
689Worktree는 `<repo>/.claude/worktrees/<name>`에 생성되고 기본 원격 분기에서 분기됩니다. worktree 분기는 `worktree-<name>`으로 이름이 지정됩니다.
690
691기본 분기는 Claude Code 플래그 또는 설정을 통해 구성할 수 없습니다. `origin/HEAD`는 복제할 때 Git이 설정한 로컬 `.git` 디렉토리에 저장된 참조입니다. 저장소의 기본 분기가 나중에 GitHub 또는 GitLab에서 변경되면 로컬 `origin/HEAD`는 이전 분기를 계속 가리키며, worktree는 거기에서 분기됩니다. 로컬 참조를 원격이 현재 기본값으로 간주하는 것과 다시 동기화하려면:
692
693```bash theme={null}
694git remote set-head origin -a
695```
696
697이것은 로컬 `.git` 디렉토리만 업데이트하는 표준 Git 명령입니다. 원격 서버에서는 아무것도 변경되지 않습니다. worktree가 원격의 기본값이 아닌 특정 분기에서 기반하도록 하려면 `git remote set-head origin your-branch-name`으로 명시적으로 설정합니다.
698
699worktree 생성 방식을 완전히 제어하려면 호출당 다른 기반을 선택하는 것을 포함하여 [WorktreeCreate hook](/ko/hooks#worktreecreate)을 구성합니다. hook은 Claude Code의 기본 `git worktree` 로직을 완전히 대체하므로 필요한 모든 ref에서 가져오고 분기할 수 있습니다.
700
701세션 중에 Claude에게 "work in a worktree" 또는 "start a worktree"를 요청할 수도 있으며, 자동으로 하나를 만듭니다.
702
703### Subagent worktree
704
705Subagent도 worktree 격리를 사용하여 충돌 없이 병렬로 작업할 수 있습니다. Claude에게 "use worktrees for your agents"를 요청하거나 [사용자 정의 subagent](/ko/sub-agents#supported-frontmatter-fields)에서 에이전트의 frontmatter에 `isolation: worktree`를 추가하여 구성합니다. 각 subagent는 변경사항 없이 완료될 때 자동으로 정리되는 자체 worktree를 가져옵니다.
706
707### Worktree 정리
708
709worktree 세션을 종료할 때 Claude는 변경사항이 있는지 여부에 따라 정리를 처리합니다:
710
711* **변경사항 없음**: worktree 및 해당 분기가 자동으로 제거됩니다
712* **변경사항 또는 커밋 존재**: Claude는 worktree를 유지할지 제거할지 묻습니다. 유지하면 디렉토리와 분기가 보존되어 나중에 돌아올 수 있습니다. 제거하면 worktree 디렉토리와 해당 분기가 삭제되어 모든 커밋되지 않은 변경사항과 커밋이 버려집니다
713
714Subagent worktree는 충돌이나 중단된 병렬 실행으로 인해 고아가 되면 시작 시 [`cleanupPeriodDays`](/ko/settings#available-settings) 설정보다 오래되면 자동으로 제거됩니다. 단, 커밋되지 않은 변경사항, 추적되지 않은 파일 및 푸시되지 않은 커밋이 없는 경우입니다. `--worktree`로 만든 Worktree는 이 정리 과정에서 절대 제거되지 않습니다.
715
716Claude 세션 외부에서 worktree를 정리하려면 [수동 worktree 관리](#manage-worktrees-manually)를 사용합니다.
717
718<Tip>
719 `.claude/worktrees/`를 `.gitignore`에 추가하여 worktree 콘텐츠가 주 저장소에 추적되지 않은 파일로 나타나지 않도록 합니다.
720</Tip>
721
722### Worktree에 gitignored 파일 복사하기
723
724Git worktree는 새로운 체크아웃이므로 주 저장소의 `.env` 또는 `.env.local`과 같은 추적되지 않은 파일을 포함하지 않습니다. Claude가 worktree를 만들 때 이러한 파일을 자동으로 복사하려면 프로젝트 루트에 `.worktreeinclude` 파일을 추가합니다.
725
726파일은 `.gitignore` 구문을 사용하여 복사할 파일을 나열합니다. 패턴과 일치하고 gitignored인 파일만 복사되므로 추적된 파일은 절대 복제되지 않습니다.
727
728```text .worktreeinclude theme={null}
729.env
730.env.local
731config/secrets.json
732```
733
734이것은 `--worktree`, subagent worktree 및 [데스크톱 앱](/ko/desktop#work-in-parallel-with-sessions)의 병렬 세션으로 생성된 worktree에 적용됩니다.
735
736### 수동으로 worktree 관리하기
737
738worktree 위치 및 분기 구성을 더 제어하려면 Git을 사용하여 직접 worktree를 만듭니다. 특정 기존 분기를 체크아웃하거나 worktree를 저장소 외부에 배치해야 할 때 유용합니다.
739
740```bash theme={null}
741# 새 분기를 사용하여 worktree 만들기
742git worktree add ../project-feature-a -b feature-a
743
744# 기존 분기를 사용하여 worktree 만들기
745git worktree add ../project-bugfix bugfix-123
746
747# worktree에서 Claude 시작
748cd ../project-feature-a && claude
749
750# 완료되면 정리
751git worktree list
752git worktree remove ../project-feature-a
753```
754
755[공식 Git worktree 문서](https://git-scm.com/docs/git-worktree)에서 자세히 알아봅니다.
756
757<Tip>
758 프로젝트의 설정에 따라 각 새 worktree에서 개발 환경을 초기화해야 합니다. 스택에 따라 여기에는 종속성 설치 (`npm install`, `yarn`), 가상 환경 설정 또는 프로젝트의 표준 설정 프로세스 따르기가 포함될 수 있습니다.
759</Tip>
760
761### 비 git 버전 제어
762
763Worktree 격리는 기본적으로 git과 함께 작동합니다. SVN, Perforce 또는 Mercurial과 같은 다른 버전 제어 시스템의 경우 [WorktreeCreate 및 WorktreeRemove hook](/ko/hooks#worktreecreate)을 구성하여 사용자 정의 worktree 생성 및 정리 로직을 제공합니다. 구성되면 이러한 hook은 `--worktree`를 사용할 때 기본 git 동작을 대체하므로 [`.worktreeinclude`](#copy-gitignored-files-to-worktrees)는 처리되지 않습니다. hook 스크립트 내에서 대신 로컬 구성 파일을 복사합니다.
764
765공유 작업 및 메시징을 사용한 병렬 세션의 자동 조정을 위해 [에이전트 팀](/ko/agent-teams)을 참조하십시오.
766
767***
768
769## Claude가 주의가 필요할 때 알림 받기
770
771장기 실행 작업을 시작하고 다른 창으로 전환할 때 Claude가 완료되거나 입력이 필요할 때 알 수 있도록 데스크톱 알림을 설정할 수 있습니다. 이것은 Claude가 권한을 기다리거나, 유휴 상태이고 새 프롬프트를 기다리거나, 인증을 완료할 때마다 발생하는 `Notification` [hook 이벤트](/ko/hooks-guide#get-notified-when-claude-needs-input)를 사용합니다.
772
773<Steps>
774 <Step title="설정에 hook 추가하기">
775 `~/.claude/settings.json`을 열고 플랫폼의 기본 알림 명령을 호출하는 `Notification` hook을 추가합니다:
776
777 <Tabs>
778 <Tab title="macOS">
779 ```json theme={null}
780 {
781 "hooks": {
782 "Notification": [
783 {
784 "matcher": "",
785 "hooks": [
786 {
787 "type": "command",
788 "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
789 }
790 ]
791 }
792 ]
793 }
794 }
795 ```
796 </Tab>
797
798 <Tab title="Linux">
799 ```json theme={null}
800 {
801 "hooks": {
802 "Notification": [
803 {
804 "matcher": "",
805 "hooks": [
806 {
807 "type": "command",
808 "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
809 }
810 ]
811 }
812 ]
813 }
814 }
815 ```
816 </Tab>
817
818 <Tab title="Windows">
819 ```json theme={null}
820 {
821 "hooks": {
822 "Notification": [
823 {
824 "matcher": "",
825 "hooks": [
826 {
827 "type": "command",
828 "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
829 }
830 ]
831 }
832 ]
833 }
834 }
835 ```
836 </Tab>
837 </Tabs>
838
839 설정 파일에 이미 `hooks` 키가 있으면 덮어쓰지 말고 `Notification` 항목을 병합합니다. CLI에서 원하는 것을 설명하여 Claude에게 hook을 작성하도록 요청할 수도 있습니다.
840 </Step>
841
842 <Step title="선택적으로 matcher 좁히기">
843 기본적으로 hook은 모든 알림 유형에 대해 발생합니다. 특정 이벤트에만 발생하도록 하려면 `matcher` 필드를 다음 값 중 하나로 설정합니다:
844
845 | Matcher | 발생 시기 |
846 | :--------------------- | :-------------------------- |
847 | `permission_prompt` | Claude가 도구 사용을 승인하도록 요청할 때 |
848 | `idle_prompt` | Claude가 완료되고 다음 프롬프트를 기다릴 때 |
849 | `auth_success` | 인증이 완료될 때 |
850 | `elicitation_dialog` | MCP 서버가 질문 양식을 열 때 |
851 | `elicitation_complete` | MCP 질문 양식이 제출되거나 닫힐 때 |
852 | `elicitation_response` | MCP 질문 응답이 서버로 다시 전송될 때 |
853 </Step>
854
855 <Step title="hook 검증하기">
856 `/hooks`를 입력하고 `Notification`을 선택하여 hook이 나타나는지 확인합니다. 선택하면 실행될 명령이 표시됩니다. 종단 간 테스트하려면 Claude에게 권한이 필요한 명령을 실행하도록 요청하고 터미널에서 전환하거나, Claude에게 직접 알림을 트리거하도록 요청합니다.
857 </Step>
858</Steps>
859
860전체 이벤트 스키마 및 알림 유형은 [알림 참조](/ko/hooks#notification)를 참조하십시오.
861
862***
863
864## Claude를 unix 스타일 유틸리티로 사용하기
865
866### 검증 프로세스에 Claude 추가하기
867
868Claude Code를 linter 또는 코드 검토자로 사용하고 싶다고 가정해봅시다.
869
870**빌드 스크립트에 Claude 추가하기:**
871
872```json theme={null}
873// package.json
874{
875 ...
876 "scripts": {
877 ...
878 "lint:claude": "claude -p 'you are a linter. please look at the changes vs. main and report any issues related to typos. report the filename and line number on one line, and a description of the issue on the second line. do not return any other text.'"
879 }
880}
881```
882
883<Tip>
884 팁:
885
886 * CI/CD 파이프라인에서 자동 코드 검토를 위해 Claude 사용
887 * 프로젝트와 관련된 특정 문제를 확인하도록 프롬프트 사용자 정의
888 * 다양한 유형의 검증을 위해 여러 스크립트 만들기 고려
889</Tip>
890
891### 파이프 인, 파이프 아웃
892
893Claude로 데이터를 파이프하고 구조화된 형식으로 데이터를 다시 받고 싶다고 가정해봅시다.
894
895**Claude를 통해 데이터 파이프하기:**
896
897```bash theme={null}
898cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt
899```
900
901<Tip>
902 팁:
903
904 * 기존 셸 스크립트에 Claude를 통합하기 위해 파이프 사용
905 * 강력한 워크플로우를 위해 다른 Unix 도구와 결합
906 * 스크립트나 다른 도구에 Claude Code를 통합할 때 `--output-format` 사용 고려
907</Tip>
908
909### 출력 형식 제어하기
910
911특히 Claude Code를 스크립트나 다른 도구에 통합할 때 특정 형식의 Claude 출력이 필요하다고 가정해봅시다.
912
913<Steps>
914 <Step title="텍스트 형식 사용 (기본값)">
915 ```bash theme={null}
916 cat data.txt | claude -p 'summarize this data' --output-format text > summary.txt
917 ```
918
919 이것은 Claude의 일반 텍스트 응답만 출력합니다 (기본 동작).
920 </Step>
921
922 <Step title="JSON 형식 사용">
923 ```bash theme={null}
924 cat code.py | claude -p 'analyze this code for bugs' --output-format json > analysis.json
925 ```
926
927 이것은 비용 및 기간을 포함한 메타데이터가 있는 메시지의 JSON 배열을 출력합니다.
928 </Step>
929
930 <Step title="스트리밍 JSON 형식 사용">
931 ```bash theme={null}
932 cat log.txt | claude -p 'parse this log file for errors' --output-format stream-json
933 ```
934
935 이것은 Claude가 요청을 처리할 때 실시간으로 일련의 JSON 객체를 출력합니다. 각 메시지는 유효한 JSON 객체이지만 연결된 전체 출력은 유효한 JSON이 아닙니다.
936 </Step>
937</Steps>
938
939<Tip>
940 팁:
941
942 * Claude의 응답만 필요한 간단한 통합을 위해 `--output-format text` 사용
943 * 전체 대화 로그가 필요할 때 `--output-format json` 사용
944 * 각 대화 턴의 실시간 출력을 위해 `--output-format stream-json` 사용
945</Tip>
946
947***
948
949## Claude를 일정에 따라 실행하기
950 396
951Claude가 정기적으로 작업을 자동으로 처리하도록 하고 싶다고 가정해봅시다. 예를 들어 매일 아침 열린 PR을 검토하거나, 매주 종속성을 감사하거나, 밤새 CI 실패를 확인합니다.397Claude가 정기적으로 작업을 자동으로 처리하도록 하고 싶다고 가정해봅시다. 예를 들어 매일 아침 열린 PR을 검토하거나, 매주 종속성을 감사하거나, 밤새 CI 실패를 확인합니다.
952 398
965 411
966***412***
967 413
968## Claude의 기능에 대해 Claude에게 물어보기414### Claude의 기능에 대해 Claude에게 물어보기
969 415
970Claude는 자신의 문서에 대한 기본 제공 액세스 권한을 가지고 있으며 자신의 기능과 제한사항에 대한 질문에 답할 수 있습니다.416Claude는 자신의 문서에 대한 기본 제공 액세스 권한을 가지고 있으며 자신의 기능과 제한사항에 대한 질문에 답할 수 있습니다.
971 417
972### 예제 질문418#### 예제 질문
973 419
974```text theme={null}420```text theme={null}
975can Claude Code create pull requests?421can Claude Code create pull requests?
1009 455
1010***456***
1011 457
458## 이전 대화 재개하기
459
460작업이 여러 세션에 걸쳐 진행될 때 컨텍스트를 다시 설명하는 대신 중단한 부분부터 계속합니다. Claude Code는 모든 대화를 로컬에 저장합니다.
461
462```bash theme={null}
463claude --continue
464```
465
466이것은 현재 디렉토리에서 가장 최근 세션을 재개합니다. 아직 없으면 `No conversation found to continue`를 출력하고 종료합니다. `claude --resume`을 사용하여 목록에서 선택하거나 실행 중인 세션 내에서 `/resume`을 사용합니다. [세션 관리](/ko/sessions)에서 이름 지정, 분기 및 전체 선택기 참조를 참조하십시오.
467
468## worktree를 사용하여 병렬 세션 실행하기
469
470한 터미널에서 기능을 작업하는 동안 Claude가 다른 터미널에서 버그를 수정하며, 편집이 충돌하지 않습니다. 각 worktree는 자체 분기의 별도 체크아웃입니다.
471
472```bash theme={null}
473claude --worktree feature-auth
474```
475
476다른 이름으로 두 번째 터미널에서 동일한 명령을 실행하여 격리된 병렬 세션을 시작합니다. [Worktrees](/ko/worktrees)에서 정리, `.worktreeinclude` 및 비git VCS 지원을 참조하십시오. 별도의 터미널 대신 한 화면에서 병렬 세션을 모니터링하려면 [백그라운드 에이전트](/ko/agent-view)를 참조하십시오.
477
478## 편집 전에 계획하기
479
480변경사항이 디스크에 닿기 전에 검토하려는 경우 계획 모드로 전환합니다. Claude는 파일을 읽고 계획을 제안하지만 승인할 때까지 편집하지 않습니다.
481
482```bash theme={null}
483claude --permission-mode plan
484```
485
486세션 중에 `Shift+Tab`을 눌러 계획 모드로 전환할 수도 있습니다. [계획 모드](/ko/permission-modes#analyze-before-you-edit-with-plan-mode)에서 승인 흐름 및 텍스트 편집기에서 계획 편집을 참조하십시오.
487
488## subagent에게 연구 위임하기
489
490큰 코드베이스를 탐색하면 컨텍스트가 파일 읽기로 채워집니다. 탐색을 위임하여 결과만 돌아오도록 합니다.
491
492```text theme={null}
493use a subagent to investigate how our auth system handles token refresh
494```
495
496subagent는 자체 컨텍스트 윈도우에서 파일을 읽고 요약을 보고합니다. [Subagents](/ko/sub-agents)에서 자체 도구 및 프롬프트가 있는 사용자 정의 에이전트 정의를 참조하십시오.
497
498## Claude를 스크립트로 파이프하기
499
500CI, 사전 커밋 훅 또는 배치 처리를 위해 Claude를 비대화형으로 실행합니다. stdin 및 stdout은 모든 Unix 도구처럼 작동합니다.
501
502```bash theme={null}
503git log --oneline -20 | claude -p "summarize these recent commits"
504```
505
506[비대화형 모드](/ko/headless)에서 출력 형식, 권한 플래그 및 팬아웃 패턴을 참조하십시오.
507
1012## 다음 단계508## 다음 단계
1013 509
1014<CardGroup cols={2}>510<CardGroup cols={2}>
1016 Claude Code에서 최대한 활용하기 위한 패턴512 Claude Code에서 최대한 활용하기 위한 패턴
1017 </Card>513 </Card>
1018 514
1019 <Card title="Claude Code 작동 방식" icon="gear" href="/ko/how-claude-code-works">515 <Card title="세션 관리" icon="rotate-left" href="/ko/sessions">
1020 에이전트 루프 및 컨텍스트 관리 이해하기516 대화 재개, 이름 지정 및 분기
1021 </Card>517 </Card>
1022 518
1023 <Card title="Claude Code 확장하기" icon="puzzle-piece" href="/ko/features-overview">519 <Card title="Worktrees" icon="code-branch" href="/ko/worktrees">
1024 skill, hook, MCP, subagent 및 플러그인 추가하기520 격리된 병렬 세션 실행
1025 </Card>521 </Card>
1026 522
1027 <Card title="참조 구현" icon="code" href="https://github.com/anthropics/claude-code/tree/main/.devcontainer">523 <Card title="Claude Code 확장하기" icon="puzzle-piece" href="/ko/features-overview">
1028 개발 컨테이너 참조 구현 복제하기524 skill, hook, MCP, subagent 및 플러그인 추가
1029 </Card>525 </Card>
1030</CardGroup>526</CardGroup>
