> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 일반적인 워크플로우

> Claude Code를 사용하여 코드베이스 탐색, 버그 수정, 리팩토링, 테스트 및 기타 일상적인 작업을 위한 단계별 가이드입니다.

이 페이지는 일상적인 개발을 위한 실용적인 워크플로우를 다룹니다: 낯선 코드 탐색, 디버깅, 리팩토링, 테스트 작성, PR 생성 및 세션 관리. 각 섹션에는 자신의 프로젝트에 맞게 조정할 수 있는 예제 프롬프트가 포함되어 있습니다. 더 높은 수준의 패턴과 팁은 [모범 사례](/ko/best-practices)를 참조하십시오.

## 새로운 코드베이스 이해하기

### 코드베이스의 빠른 개요 얻기

새로운 프로젝트에 방금 참여했고 그 구조를 빠르게 이해해야 한다고 가정해봅시다.

<Steps>
  <Step title="프로젝트 루트 디렉토리로 이동">
    ```bash theme={null}
    cd /path/to/project 
    ```
  </Step>

  <Step title="Claude Code 시작">
    ```bash theme={null}
    claude 
    ```
  </Step>

  <Step title="높은 수준의 개요 요청">
    ```text theme={null}
    give me an overview of this codebase
    ```
  </Step>

  <Step title="특정 구성 요소에 대해 더 깊이 있게 살펴보기">
    ```text theme={null}
    explain the main architecture patterns used here
    ```

    ```text theme={null}
    what are the key data models?
    ```

    ```text theme={null}
    how is authentication handled?
    ```
  </Step>
</Steps>

<Tip>
  팁:

  * 광범위한 질문으로 시작한 다음 특정 영역으로 좁혀나가기
  * 프로젝트에서 사용되는 코딩 규칙과 패턴에 대해 질문하기
  * 프로젝트별 용어의 용어집 요청하기
</Tip>

### 관련 코드 찾기

특정 기능이나 기능과 관련된 코드를 찾아야 한다고 가정해봅시다.

<Steps>
  <Step title="Claude에게 관련 파일을 찾도록 요청">
    ```text theme={null}
    find the files that handle user authentication
    ```
  </Step>

  <Step title="구성 요소가 어떻게 상호작용하는지에 대한 컨텍스트 얻기">
    ```text theme={null}
    how do these authentication files work together?
    ```
  </Step>

  <Step title="실행 흐름 이해하기">
    ```text theme={null}
    trace the login process from front-end to database
    ```
  </Step>
</Steps>

<Tip>
  팁:

  * 찾고 있는 것에 대해 구체적으로 설명하기
  * 프로젝트의 도메인 언어 사용하기
  * 언어에 대한 [코드 인텔리전스 플러그인](/ko/discover-plugins#code-intelligence)을 설치하여 Claude에게 정확한 "정의로 이동" 및 "참조 찾기" 네비게이션 제공하기
</Tip>

***

## 효율적으로 버그 수정하기

오류 메시지가 나타났고 그 원인을 찾아 수정해야 한다고 가정해봅시다.

<Steps>
  <Step title="Claude와 오류 공유하기">
    ```text theme={null}
    I'm seeing an error when I run npm test
    ```
  </Step>

  <Step title="수정 권장사항 요청하기">
    ```text theme={null}
    suggest a few ways to fix the @ts-ignore in user.ts
    ```
  </Step>

  <Step title="수정 적용하기">
    ```text theme={null}
    update user.ts to add the null check you suggested
    ```
  </Step>
</Steps>

<Tip>
  팁:

  * Claude에게 문제를 재현하는 명령과 스택 추적을 알려주기
  * 오류를 재현하는 단계 언급하기
  * 오류가 간헐적인지 일관적인지 Claude에게 알려주기
</Tip>

***

## 코드 리팩토링

오래된 코드를 최신 패턴과 관행을 사용하도록 업데이트해야 한다고 가정해봅시다.

<Steps>
  <Step title="리팩토링할 레거시 코드 식별">
    ```text theme={null}
    find deprecated API usage in our codebase
    ```
  </Step>

  <Step title="리팩토링 권장사항 얻기">
    ```text theme={null}
    suggest how to refactor utils.js to use modern JavaScript features
    ```
  </Step>

  <Step title="안전하게 변경사항 적용하기">
    ```text theme={null}
    refactor utils.js to use ES2024 features while maintaining the same behavior
    ```
  </Step>

  <Step title="리팩토링 검증하기">
    ```text theme={null}
    run tests for the refactored code
    ```
  </Step>
</Steps>

<Tip>
  팁:

  * Claude에게 최신 접근 방식의 이점을 설명하도록 요청하기
  * 필요할 때 변경사항이 하위 호환성을 유지하도록 요청하기
  * 작고 테스트 가능한 증분으로 리팩토링 수행하기
</Tip>

***

## 특화된 subagent 사용하기

특정 작업을 더 효과적으로 처리하기 위해 특화된 AI subagent를 사용하고 싶다고 가정해봅시다.

<Steps>
  <Step title="사용 가능한 subagent 보기">
    ```text theme={null}
    /agents
    ```

    이것은 모든 사용 가능한 subagent를 표시하고 새로운 것을 만들 수 있게 해줍니다.
  </Step>

  <Step title="자동으로 subagent 사용하기">
    Claude Code는 자동으로 특정 작업을 특화된 subagent에게 위임합니다:

    ```text theme={null}
    review my recent code changes for security issues
    ```

    ```text theme={null}
    run all tests and fix any failures
    ```
  </Step>

  <Step title="명시적으로 특정 subagent 요청하기">
    ```text theme={null}
    use the code-reviewer subagent to check the auth module
    ```

    ```text theme={null}
    have the debugger subagent investigate why users can't log in
    ```
  </Step>

  <Step title="워크플로우를 위한 사용자 정의 subagent 만들기">
    ```text theme={null}
    /agents
    ```

    그런 다음 "Create New subagent"를 선택하고 프롬프트를 따라 다음을 정의합니다:

    * subagent의 목적을 설명하는 고유 식별자 (예: `code-reviewer`, `api-designer`).
    * Claude가 이 에이전트를 사용해야 할 때
    * 액세스할 수 있는 도구
    * 에이전트의 역할과 동작을 설명하는 시스템 프롬프트
  </Step>
</Steps>

<Tip>
  팁:

  * 팀 공유를 위해 `.claude/agents/`에 프로젝트별 subagent 만들기
  * 자동 위임을 활성화하기 위해 설명적인 `description` 필드 사용하기
  * 각 subagent가 실제로 필요한 것으로 도구 액세스 제한하기
  * 자세한 예제는 [subagent 문서](/ko/sub-agents)를 확인하기
</Tip>

***

## Plan Mode를 사용하여 안전한 코드 분석

Plan Mode는 Claude에게 읽기 전용 작업으로 코드베이스를 분석하여 계획을 세우도록 지시하며, 코드베이스 탐색, 복잡한 변경 계획 또는 코드 안전한 검토에 완벽합니다. Plan Mode에서 Claude는 [`AskUserQuestion`](/ko/tools-reference)을 사용하여 계획을 제안하기 전에 요구사항을 수집하고 목표를 명확히 합니다.

### Plan Mode를 사용할 때

* **다단계 구현**: 기능이 많은 파일을 편집해야 할 때
* **코드 탐색**: 무엇이든 변경하기 전에 코드베이스를 철저히 조사하고 싶을 때
* **대화형 개발**: Claude와 방향을 반복하고 싶을 때

### Plan Mode 사용 방법

**세션 중에 Plan Mode 켜기**

**Shift+Tab**을 사용하여 세션 중에 Plan Mode로 전환할 수 있습니다.

Normal Mode에 있으면 **Shift+Tab**은 먼저 Auto-Accept Mode로 전환되며, 터미널 하단에 `⏵⏵ accept edits on`으로 표시됩니다. 그 다음 **Shift+Tab**은 Plan Mode로 전환되며, `⏸ plan mode on`으로 표시됩니다.

**Plan Mode에서 새 세션 시작하기**

Plan Mode에서 새 세션을 시작하려면 `--permission-mode plan` 플래그를 사용합니다:

```bash theme={null}
claude --permission-mode plan
```

**Plan Mode에서 "헤드리스" 쿼리 실행하기**

`-p`를 사용하여 Plan Mode에서 직접 쿼리를 실행할 수도 있습니다 (즉, ["헤드리스 모드"](/ko/headless)에서):

```bash theme={null}
claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"
```

### 예제: 복잡한 리팩토링 계획하기

```bash theme={null}
claude --permission-mode plan
```

```text theme={null}
I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.
```

Claude는 현재 구현을 분석하고 포괄적인 계획을 만듭니다. 후속 질문으로 정제합니다:

```text theme={null}
What about backward compatibility?
```

```text theme={null}
How should we handle database migration?
```

<Tip>`Ctrl+G`를 눌러 기본 텍스트 편집기에서 계획을 열고, Claude가 진행하기 전에 직접 편집할 수 있습니다.</Tip>

계획을 수락하면 Claude는 계획 콘텐츠에서 자동으로 세션 이름을 지정합니다. 이름은 프롬프트 바와 세션 선택기에 나타납니다. 이미 `--name` 또는 `/rename`으로 이름을 설정한 경우 계획을 수락해도 덮어쓰지 않습니다.

### Plan Mode를 기본값으로 구성하기

```json theme={null}
// .claude/settings.json
{
  "permissions": {
    "defaultMode": "plan"
  }
}
```

더 많은 구성 옵션은 [설정 문서](/ko/settings#available-settings)를 참조하십시오.

***

## 테스트 작업하기

적용되지 않은 코드에 대한 테스트를 추가해야 한다고 가정해봅시다.

<Steps>
  <Step title="테스트되지 않은 코드 식별">
    ```text theme={null}
    find functions in NotificationsService.swift that are not covered by tests
    ```
  </Step>

  <Step title="테스트 스캐폴딩 생성">
    ```text theme={null}
    add tests for the notification service
    ```
  </Step>

  <Step title="의미 있는 테스트 케이스 추가">
    ```text theme={null}
    add test cases for edge conditions in the notification service
    ```
  </Step>

  <Step title="테스트 실행 및 검증">
    ```text theme={null}
    run the new tests and fix any failures
    ```
  </Step>
</Steps>

Claude는 프로젝트의 기존 패턴과 규칙을 따르는 테스트를 생성할 수 있습니다. 테스트를 요청할 때 검증하려는 동작에 대해 구체적으로 설명하십시오. Claude는 기존 테스트 파일을 검토하여 이미 사용 중인 스타일, 프레임워크 및 어설션 패턴을 일치시킵니다.

포괄적인 적용 범위를 위해 Claude에게 놓쳤을 수 있는 엣지 케이스를 식별하도록 요청하십시오. Claude는 코드 경로를 분석하고 오류 조건, 경계값 및 쉽게 간과할 수 있는 예상치 못한 입력에 대한 테스트를 제안할 수 있습니다.

***

## 풀 요청 만들기

Claude에게 직접 풀 요청을 만들도록 요청하거나 ("create a pr for my changes"), 단계별로 Claude를 안내할 수 있습니다:

<Steps>
  <Step title="변경사항 요약하기">
    ```text theme={null}
    summarize the changes I've made to the authentication module
    ```
  </Step>

  <Step title="풀 요청 생성하기">
    ```text theme={null}
    create a pr
    ```
  </Step>

  <Step title="검토 및 정제하기">
    ```text theme={null}
    enhance the PR description with more context about the security improvements
    ```
  </Step>
</Steps>

`gh pr create`를 사용하여 PR을 만들면 세션이 자동으로 해당 PR에 연결됩니다. 나중에 `claude --from-pr <number>`로 재개할 수 있습니다.

<Tip>
  Claude가 생성한 PR을 제출하기 전에 검토하고 Claude에게 잠재적 위험이나 고려사항을 강조하도록 요청하십시오.
</Tip>

## 문서 처리하기

코드에 대한 문서를 추가하거나 업데이트해야 한다고 가정해봅시다.

<Steps>
  <Step title="문서화되지 않은 코드 식별">
    ```text theme={null}
    find functions without proper JSDoc comments in the auth module
    ```
  </Step>

  <Step title="문서 생성하기">
    ```text theme={null}
    add JSDoc comments to the undocumented functions in auth.js
    ```
  </Step>

  <Step title="검토 및 개선하기">
    ```text theme={null}
    improve the generated documentation with more context and examples
    ```
  </Step>

  <Step title="문서 검증하기">
    ```text theme={null}
    check if the documentation follows our project standards
    ```
  </Step>
</Steps>

<Tip>
  팁:

  * 원하는 문서 스타일 지정하기 (JSDoc, docstring 등)
  * 문서에 예제 요청하기
  * 공개 API, 인터페이스 및 복잡한 로직에 대한 문서 요청하기
</Tip>

***

## 노트 및 비코드 폴더에서 작업하기

Claude Code는 모든 디렉토리에서 작동합니다. 노트 저장소, 문서 폴더 또는 마크다운 파일의 모든 컬렉션 내에서 실행하여 코드처럼 콘텐츠를 검색, 편집 및 재구성합니다.

`.claude/` 디렉토리와 `CLAUDE.md`는 다른 도구의 구성 디렉토리와 충돌 없이 나란히 있습니다. Claude는 각 도구 호출에서 파일을 새로 읽으므로 다른 애플리케이션에서 만든 편집을 다음에 파일을 읽을 때 봅니다.

***

## 이미지 작업하기

코드베이스에서 이미지를 작업해야 하고 Claude의 이미지 콘텐츠 분석 도움을 원한다고 가정해봅시다.

<Steps>
  <Step title="대화에 이미지 추가하기">
    다음 방법 중 하나를 사용할 수 있습니다:

    1. Claude Code 창으로 이미지를 드래그 앤 드롭하기
    2. 이미지를 복사하고 ctrl+v로 CLI에 붙여넣기 (cmd+v 사용하지 않기)
    3. Claude에 이미지 경로 제공하기. 예: "Analyze this image: /path/to/your/image.png"
  </Step>

  <Step title="Claude에게 이미지 분석 요청하기">
    ```text theme={null}
    What does this image show?
    ```

    ```text theme={null}
    Describe the UI elements in this screenshot
    ```

    ```text theme={null}
    Are there any problematic elements in this diagram?
    ```
  </Step>

  <Step title="컨텍스트를 위해 이미지 사용하기">
    ```text theme={null}
    Here's a screenshot of the error. What's causing it?
    ```

    ```text theme={null}
    This is our current database schema. How should we modify it for the new feature?
    ```
  </Step>

  <Step title="시각적 콘텐츠에서 코드 제안 얻기">
    ```text theme={null}
    Generate CSS to match this design mockup
    ```

    ```text theme={null}
    What HTML structure would recreate this component?
    ```
  </Step>
</Steps>

<Tip>
  팁:

  * 텍스트 설명이 불명확하거나 번거로울 때 이미지 사용하기
  * 더 나은 컨텍스트를 위해 오류, UI 디자인 또는 다이어그램의 스크린샷 포함하기
  * 대화에서 여러 이미지를 작업할 수 있습니다
  * 이미지 분석은 다이어그램, 스크린샷, 목업 등과 함께 작동합니다
  * Claude가 이미지를 참조할 때 (예: `[Image #1]`), `Cmd+Click` (Mac) 또는 `Ctrl+Click` (Windows/Linux)을 클릭하여 기본 뷰어에서 이미지를 엽니다
</Tip>

***

## 파일 및 디렉토리 참조하기

@를 사용하여 Claude가 읽을 때까지 기다리지 않고 파일이나 디렉토리를 빠르게 포함합니다.

<Steps>
  <Step title="단일 파일 참조하기">
    ```text theme={null}
    Explain the logic in @src/utils/auth.js
    ```

    이것은 대화에 파일의 전체 내용을 포함합니다.
  </Step>

  <Step title="디렉토리 참조하기">
    ```text theme={null}
    What's the structure of @src/components?
    ```

    이것은 파일 정보가 있는 디렉토리 목록을 제공합니다.
  </Step>

  <Step title="MCP 리소스 참조하기">
    ```text theme={null}
    Show me the data from @github:repos/owner/repo/issues
    ```

    이것은 @server:resource 형식을 사용하여 연결된 MCP 서버에서 데이터를 가져옵니다. 자세한 내용은 [MCP 리소스](/ko/mcp#use-mcp-resources)를 참조하십시오.
  </Step>
</Steps>

<Tip>
  팁:

  * 파일 경로는 상대 또는 절대 경로일 수 있습니다
  * @ 파일 참조는 파일의 디렉토리 및 상위 디렉토리에 `CLAUDE.md`를 추가합니다
  * 디렉토리 참조는 내용이 아닌 파일 목록을 표시합니다
  * 단일 메시지에서 여러 파일을 참조할 수 있습니다 (예: "@file1.js and @file2.js")
</Tip>

***

## 확장된 사고 사용하기 (thinking mode)

[확장된 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)는 기본적으로 활성화되어 있으며, Claude가 복잡한 문제를 단계별로 추론할 수 있는 공간을 제공합니다. 이 추론은 `Ctrl+O`로 전환할 수 있는 자세한 모드에서 볼 수 있습니다. 확장된 사고 중에 진행 상황 힌트가 표시기 아래에 나타나 Claude가 적극적으로 작업 중임을 보여줍니다.

또한 [노력을 지원하는 모델](/ko/model-config#adjust-effort-level)은 적응형 추론을 사용합니다: 고정된 사고 토큰 예산 대신 모델은 노력 수준 설정과 작업에 따라 동적으로 사고할지 여부와 얼마나 많이 사고할지 결정합니다. 적응형 추론을 통해 Claude는 일상적인 프롬프트에 더 빠르게 응답하고 이점을 얻을 수 있는 단계를 위해 더 깊은 사고를 예약할 수 있습니다.

확장된 사고는 복잡한 아키텍처 결정, 어려운 버그, 다단계 구현 계획 및 다양한 접근 방식 간의 트레이드오프 평가에 특히 유용합니다.

<Note>
  "think", "think hard", "think more"와 같은 구문은 일반 프롬프트 지시로 해석되며 사고 토큰을 할당하지 않습니다.
</Note>

### thinking mode 구성하기

사고는 기본적으로 활성화되어 있지만 조정하거나 비활성화할 수 있습니다.

| 범위                   | 구성 방법                                                                         | 세부 정보                                                                                                                   |
| -------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **노력 수준**            | `/effort` 실행, `/model`에서 조정, 또는 [`CLAUDE_CODE_EFFORT_LEVEL`](/ko/env-vars) 설정 | [지원되는 모델](/ko/model-config#adjust-effort-level)에서 사고 깊이 제어                                                              |
| **`ultrathink` 키워드** | 프롬프트의 어디든 "ultrathink" 포함                                                     | 해당 턴에 대해 더 많이 추론하도록 모델에 지시하는 컨텍스트 내 지시를 추가합니다. 노력 수준 자체를 변경하지 않습니다. [노력 수준 조정](/ko/model-config#adjust-effort-level) 참조 |
| **토글 단축키**           | `Option+T` (macOS) 또는 `Alt+T` (Windows/Linux) 누르기                             | 현재 세션에 대해 사고 켜기/끄기 (모든 모델). [터미널 구성](/ko/terminal-config)이 필요할 수 있습니다                                                   |
| **전역 기본값**           | `/config`를 사용하여 thinking mode 토글                                              | 모든 프로젝트에서 기본값 설정 (모든 모델).<br />`~/.claude/settings.json`에 `alwaysThinkingEnabled`로 저장됩니다                                |
| **토큰 예산 제한**         | [`MAX_THINKING_TOKENS`](/ko/env-vars) 환경 변수 설정                                | 사고 예산을 특정 토큰 수로 제한합니다. 적응형 추론이 있는 모델에서는 적응형 추론이 비활성화되지 않으면 `0`만 적용됩니다. 예: `export MAX_THINKING_TOKENS=10000`            |

Claude의 사고 과정을 보려면 `Ctrl+O`를 눌러 자세한 모드를 전환하고 회색 이탤릭 텍스트로 표시된 내부 추론을 확인하십시오.

### 확장된 사고 작동 방식

확장된 사고는 Claude가 응답하기 전에 수행하는 내부 추론의 양을 제어합니다. 더 많은 사고는 솔루션을 탐색하고, 엣지 케이스를 분석하고, 실수를 자체 수정할 수 있는 더 많은 공간을 제공합니다.

[노력을 지원하는 모델](/ko/model-config#adjust-effort-level)에서 사고는 적응형 추론을 사용합니다: 모델은 선택한 노력 수준에 따라 동적으로 사고 토큰을 할당합니다. 이것은 속도와 추론 깊이 간의 트레이드오프를 조정하는 권장 방법입니다. 노력 수준이 그렇지 않으면 생성할 것보다 Claude가 더 많거나 적게 사고하기를 원하면 프롬프트나 `CLAUDE.md`에서 직접 그렇게 말할 수도 있습니다.

이전 모델에서 사고는 출력 할당에서 최대 31,999개 토큰의 고정 예산을 사용합니다. [`MAX_THINKING_TOKENS`](/ko/env-vars) 환경 변수로 이를 제한하거나 `/config` 또는 `Option+T`/`Alt+T` 토글을 통해 사고를 완전히 비활성화할 수 있습니다.

적응형 추론이 있는 모델에서 `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)를 참조하십시오.

<Warning>
  사고 요약이 편집되더라도 사용된 모든 사고 토큰에 대해 요금이 청구됩니다. 대화형 모드에서 사고는 기본적으로 축소된 스텁으로 나타납니다. `settings.json`에서 `showThinkingSummaries: true`를 설정하여 전체 요약을 표시합니다.
</Warning>

***

## 이전 대화 재개하기

Claude Code를 시작할 때 이전 세션을 재개할 수 있습니다:

* `claude --continue`는 현재 디렉토리에서 가장 최근 대화를 계속합니다
* `claude --resume`은 대화 선택기를 열거나 이름으로 재개합니다
* `claude --from-pr 123`은 특정 풀 요청에 연결된 세션을 재개합니다

활성 세션 내에서 `/resume`을 사용하여 다른 대화로 전환합니다.

선택한 세션이 오래되고 충분히 커서 다시 읽으면 사용 한도의 상당한 부분을 소비할 경우, `--resume`, `--continue` 및 `/resume`은 전체 기록을 로드하는 대신 요약에서 재개할 것을 제안합니다. 이 프롬프트는 Amazon Bedrock, Google Cloud Vertex AI 또는 Microsoft Foundry에서 사용할 수 없습니다.

세션은 프로젝트 디렉토리별로 저장됩니다. 기본적으로 `/resume` 선택기는 현재 worktree의 대화형 세션을 표시하며, 다른 worktree 또는 프로젝트로 목록을 확대하고, 검색하고, 미리보고, 이름을 바꾸는 키보드 단축키가 있습니다. `/add-dir`으로 현재 디렉토리를 추가한 다른 곳에서 시작된 세션도 기본적으로 포함됩니다. 전체 단축키 참조는 아래의 [세션 선택기 사용하기](#use-the-session-picker)를 참조하십시오.

다른 worktree의 세션을 선택하면 Claude Code는 먼저 디렉토리를 전환할 필요 없이 직접 재개합니다. 관련 없는 프로젝트의 세션을 선택하면 `cd` 및 재개 명령을 클립보드에 복사합니다.

이름으로 재개하면 현재 저장소 및 해당 worktree 전체에서 해결됩니다. `claude --resume <name>` 및 `/resume <name>` 모두 정확한 일치를 찾고 세션이 다른 worktree에 있더라도 직접 재개합니다.

이름이 모호하면 `claude --resume <name>`은 이름을 검색 용어로 미리 채운 선택기를 엽니다. 세션 내에서 `/resume <name>`은 대신 오류를 보고하므로 `/resume`을 인수 없이 실행하여 선택기를 열고 선택합니다.

`claude -p` 또는 SDK 호출로 생성된 세션은 선택기에 나타나지 않지만 세션 ID를 `claude --resume <session-id>`에 직접 전달하여 재개할 수 있습니다.

### 세션 이름 지정하기

나중에 찾기 위해 세션에 설명적인 이름을 지정합니다. 이것은 여러 작업이나 기능을 작업할 때 모범 사례입니다.

<Steps>
  <Step title="세션 이름 지정하기">
    시작 시 `-n`으로 세션 이름을 지정합니다:

    ```bash theme={null}
    claude -n auth-refactor
    ```

    또는 세션 중에 `/rename`을 사용하며, 이는 프롬프트 바에도 이름을 표시합니다:

    ```text theme={null}
    /rename auth-refactor
    ```

    선택기에서 세션 이름을 바꿀 수도 있습니다: `/resume`을 실행하고, 세션으로 이동한 다음 `Ctrl+R`을 누릅니다.
  </Step>

  <Step title="나중에 이름으로 재개하기">
    명령줄에서:

    ```bash theme={null}
    claude --resume auth-refactor
    ```

    또는 활성 세션 내에서:

    ```text theme={null}
    /resume auth-refactor
    ```
  </Step>
</Steps>

### 세션 선택기 사용하기

`/resume` 명령 (또는 인수 없이 `claude --resume`)은 다음 기능이 있는 대화형 세션 선택기를 엽니다:

**선택기의 키보드 단축키:**

| 단축키                          | 작업                                                                         |
| :--------------------------- | :------------------------------------------------------------------------- |
| `↑` / `↓`                    | 세션 간 이동                                                                    |
| `→` / `←`                    | 그룹화된 세션 확장 또는 축소                                                           |
| `Enter`                      | 강조 표시된 세션 선택 및 재개                                                          |
| `Space`                      | 세션 콘텐츠 미리보기. `Ctrl+V`도 이를 캡처하지 않는 터미널에서 작동합니다                              |
| `Ctrl+R`                     | 강조 표시된 세션 이름 바꾸기                                                           |
| `/` 또는 `Space` 이외의 인쇄 가능한 문자 | 검색 모드 진입 및 세션 필터링                                                          |
| `Ctrl+A`                     | 이 컴퓨터의 모든 프로젝트에서 세션 표시. 다시 누르면 현재 저장소 복원                                   |
| `Ctrl+W`                     | 현재 저장소의 모든 worktree에서 세션 표시. 다시 누르면 현재 worktree 복원. 다중 worktree 저장소에서만 표시됨 |
| `Ctrl+B`                     | 현재 git 분기의 세션으로 필터링. 다시 누르면 모든 분기의 세션 표시                                   |
| `Esc`                        | 선택기 또는 검색 모드 종료                                                            |

**세션 구성:**

선택기는 유용한 메타데이터가 있는 세션을 표시합니다:

* 세션 이름 (설정된 경우), 그렇지 않으면 대화 요약 또는 첫 번째 사용자 프롬프트
* 마지막 활동 이후 경과 시간
* 메시지 수
* Git 분기 (해당하는 경우)
* `Ctrl+A`로 모든 프로젝트로 확대한 후 표시되는 프로젝트 경로

포크된 세션 (`/branch`, `/rewind` 또는 `--fork-session`으로 생성됨)은 루트 세션 아래에 그룹화되어 관련 대화를 더 쉽게 찾을 수 있습니다.

<Tip>
  팁:

  * **세션 조기 이름 지정**: 고유한 작업을 시작할 때 `/rename`을 사용합니다—나중에 "payment-integration"을 찾기가 "explain this function"보다 훨씬 쉽습니다
  * 현재 디렉토리에서 가장 최근 대화에 빠르게 액세스하려면 `--continue` 사용
  * 필요한 세션을 알 때 `--resume session-name` 사용
  * 검색하고 선택해야 할 때 `--resume` (이름 없이) 사용
  * 스크립트의 경우 `claude --continue --print "prompt"`를 사용하여 비대화형 모드에서 재개
  * 선택기에서 `Space`를 눌러 재개하기 전에 세션을 미리봅니다
  * 재개된 대화는 원본과 동일한 모델 및 구성으로 시작됩니다

  작동 방식:

  1. **대화 저장소**: 모든 대화는 전체 메시지 기록과 함께 로컬에 자동으로 저장됩니다
  2. **메시지 역직렬화**: 재개할 때 전체 메시지 기록이 복원되어 컨텍스트를 유지합니다
  3. **도구 상태**: 이전 대화의 도구 사용 및 결과가 보존됩니다
  4. **컨텍스트 복원**: 대화는 모든 이전 컨텍스트와 함께 재개됩니다
</Tip>

***

## Git worktree를 사용하여 병렬 Claude Code 세션 실행하기

여러 작업을 동시에 수행할 때 각 Claude 세션이 변경사항이 충돌하지 않도록 코드베이스의 자체 복사본을 가져야 합니다. Git worktree는 각각 자체 파일과 분기를 가지면서 동일한 저장소 기록 및 원격 연결을 공유하는 별도의 작업 디렉토리를 만들어 이를 해결합니다. 이는 한 worktree에서 기능을 작업하는 동안 Claude가 다른 worktree에서 버그를 수정할 수 있으며, 어느 세션도 다른 세션을 방해하지 않음을 의미합니다.

`--worktree` (`-w`) 플래그를 사용하여 격리된 worktree를 만들고 Claude를 시작합니다. 전달하는 값은 worktree 디렉토리 이름과 분기 이름이 됩니다:

```bash theme={null}
# "feature-auth"라는 worktree에서 Claude 시작
# 새 분기를 사용하여 .claude/worktrees/feature-auth/ 생성
claude --worktree feature-auth

# 별도의 worktree에서 다른 세션 시작
claude --worktree bugfix-123
```

이름을 생략하면 Claude가 자동으로 임의의 이름을 생성합니다:

```bash theme={null}
# "bright-running-fox"와 같은 이름 자동 생성
claude --worktree
```

Worktree는 `<repo>/.claude/worktrees/<name>`에 생성되고 기본 원격 분기에서 분기됩니다. worktree 분기는 `worktree-<name>`으로 이름이 지정됩니다.

기본 분기는 Claude Code 플래그 또는 설정을 통해 구성할 수 없습니다. `origin/HEAD`는 복제할 때 Git이 설정한 로컬 `.git` 디렉토리에 저장된 참조입니다. 저장소의 기본 분기가 나중에 GitHub 또는 GitLab에서 변경되면 로컬 `origin/HEAD`는 이전 분기를 계속 가리키며, worktree는 거기에서 분기됩니다. 로컬 참조를 원격이 현재 기본값으로 간주하는 것과 다시 동기화하려면:

```bash theme={null}
git remote set-head origin -a
```

이것은 로컬 `.git` 디렉토리만 업데이트하는 표준 Git 명령입니다. 원격 서버에서는 아무것도 변경되지 않습니다. worktree가 원격의 기본값이 아닌 특정 분기에서 기반하도록 하려면 `git remote set-head origin your-branch-name`으로 명시적으로 설정합니다.

worktree 생성 방식을 완전히 제어하려면 호출당 다른 기반을 선택하는 것을 포함하여 [WorktreeCreate hook](/ko/hooks#worktreecreate)을 구성합니다. hook은 Claude Code의 기본 `git worktree` 로직을 완전히 대체하므로 필요한 모든 ref에서 가져오고 분기할 수 있습니다.

세션 중에 Claude에게 "work in a worktree" 또는 "start a worktree"를 요청할 수도 있으며, 자동으로 하나를 만듭니다.

### Subagent worktree

Subagent도 worktree 격리를 사용하여 충돌 없이 병렬로 작업할 수 있습니다. Claude에게 "use worktrees for your agents"를 요청하거나 [사용자 정의 subagent](/ko/sub-agents#supported-frontmatter-fields)에서 에이전트의 frontmatter에 `isolation: worktree`를 추가하여 구성합니다. 각 subagent는 변경사항 없이 완료될 때 자동으로 정리되는 자체 worktree를 가져옵니다.

### Worktree 정리

worktree 세션을 종료할 때 Claude는 변경사항이 있는지 여부에 따라 정리를 처리합니다:

* **변경사항 없음**: worktree 및 해당 분기가 자동으로 제거됩니다
* **변경사항 또는 커밋 존재**: Claude는 worktree를 유지할지 제거할지 묻습니다. 유지하면 디렉토리와 분기가 보존되어 나중에 돌아올 수 있습니다. 제거하면 worktree 디렉토리와 해당 분기가 삭제되어 모든 커밋되지 않은 변경사항과 커밋이 버려집니다

Subagent worktree는 충돌이나 중단된 병렬 실행으로 인해 고아가 되면 시작 시 [`cleanupPeriodDays`](/ko/settings#available-settings) 설정보다 오래되면 자동으로 제거됩니다. 단, 커밋되지 않은 변경사항, 추적되지 않은 파일 및 푸시되지 않은 커밋이 없는 경우입니다. `--worktree`로 만든 Worktree는 이 정리 과정에서 절대 제거되지 않습니다.

Claude 세션 외부에서 worktree를 정리하려면 [수동 worktree 관리](#manage-worktrees-manually)를 사용합니다.

<Tip>
  `.claude/worktrees/`를 `.gitignore`에 추가하여 worktree 콘텐츠가 주 저장소에 추적되지 않은 파일로 나타나지 않도록 합니다.
</Tip>

### Worktree에 gitignored 파일 복사하기

Git worktree는 새로운 체크아웃이므로 주 저장소의 `.env` 또는 `.env.local`과 같은 추적되지 않은 파일을 포함하지 않습니다. Claude가 worktree를 만들 때 이러한 파일을 자동으로 복사하려면 프로젝트 루트에 `.worktreeinclude` 파일을 추가합니다.

파일은 `.gitignore` 구문을 사용하여 복사할 파일을 나열합니다. 패턴과 일치하고 gitignored인 파일만 복사되므로 추적된 파일은 절대 복제되지 않습니다.

```text .worktreeinclude theme={null}
.env
.env.local
config/secrets.json
```

이것은 `--worktree`, subagent worktree 및 [데스크톱 앱](/ko/desktop#work-in-parallel-with-sessions)의 병렬 세션으로 생성된 worktree에 적용됩니다.

### 수동으로 worktree 관리하기

worktree 위치 및 분기 구성을 더 제어하려면 Git을 사용하여 직접 worktree를 만듭니다. 특정 기존 분기를 체크아웃하거나 worktree를 저장소 외부에 배치해야 할 때 유용합니다.

```bash theme={null}
# 새 분기를 사용하여 worktree 만들기
git worktree add ../project-feature-a -b feature-a

# 기존 분기를 사용하여 worktree 만들기
git worktree add ../project-bugfix bugfix-123

# worktree에서 Claude 시작
cd ../project-feature-a && claude

# 완료되면 정리
git worktree list
git worktree remove ../project-feature-a
```

[공식 Git worktree 문서](https://git-scm.com/docs/git-worktree)에서 자세히 알아봅니다.

<Tip>
  프로젝트의 설정에 따라 각 새 worktree에서 개발 환경을 초기화해야 합니다. 스택에 따라 여기에는 종속성 설치 (`npm install`, `yarn`), 가상 환경 설정 또는 프로젝트의 표준 설정 프로세스 따르기가 포함될 수 있습니다.
</Tip>

### 비 git 버전 제어

Worktree 격리는 기본적으로 git과 함께 작동합니다. SVN, Perforce 또는 Mercurial과 같은 다른 버전 제어 시스템의 경우 [WorktreeCreate 및 WorktreeRemove hook](/ko/hooks#worktreecreate)을 구성하여 사용자 정의 worktree 생성 및 정리 로직을 제공합니다. 구성되면 이러한 hook은 `--worktree`를 사용할 때 기본 git 동작을 대체하므로 [`.worktreeinclude`](#copy-gitignored-files-to-worktrees)는 처리되지 않습니다. hook 스크립트 내에서 대신 로컬 구성 파일을 복사합니다.

공유 작업 및 메시징을 사용한 병렬 세션의 자동 조정을 위해 [에이전트 팀](/ko/agent-teams)을 참조하십시오.

***

## Claude가 주의가 필요할 때 알림 받기

장기 실행 작업을 시작하고 다른 창으로 전환할 때 Claude가 완료되거나 입력이 필요할 때 알 수 있도록 데스크톱 알림을 설정할 수 있습니다. 이것은 Claude가 권한을 기다리거나, 유휴 상태이고 새 프롬프트를 기다리거나, 인증을 완료할 때마다 발생하는 `Notification` [hook 이벤트](/ko/hooks-guide#get-notified-when-claude-needs-input)를 사용합니다.

<Steps>
  <Step title="설정에 hook 추가하기">
    `~/.claude/settings.json`을 열고 플랫폼의 기본 알림 명령을 호출하는 `Notification` hook을 추가합니다:

    <Tabs>
      <Tab title="macOS">
        ```json theme={null}
        {
          "hooks": {
            "Notification": [
              {
                "matcher": "",
                "hooks": [
                  {
                    "type": "command",
                    "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
                  }
                ]
              }
            ]
          }
        }
        ```
      </Tab>

      <Tab title="Linux">
        ```json theme={null}
        {
          "hooks": {
            "Notification": [
              {
                "matcher": "",
                "hooks": [
                  {
                    "type": "command",
                    "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
                  }
                ]
              }
            ]
          }
        }
        ```
      </Tab>

      <Tab title="Windows">
        ```json theme={null}
        {
          "hooks": {
            "Notification": [
              {
                "matcher": "",
                "hooks": [
                  {
                    "type": "command",
                    "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
                  }
                ]
              }
            ]
          }
        }
        ```
      </Tab>
    </Tabs>

    설정 파일에 이미 `hooks` 키가 있으면 덮어쓰지 말고 `Notification` 항목을 병합합니다. CLI에서 원하는 것을 설명하여 Claude에게 hook을 작성하도록 요청할 수도 있습니다.
  </Step>

  <Step title="선택적으로 matcher 좁히기">
    기본적으로 hook은 모든 알림 유형에 대해 발생합니다. 특정 이벤트에만 발생하도록 하려면 `matcher` 필드를 다음 값 중 하나로 설정합니다:

    | Matcher                | 발생 시기                       |
    | :--------------------- | :-------------------------- |
    | `permission_prompt`    | Claude가 도구 사용을 승인하도록 요청할 때  |
    | `idle_prompt`          | Claude가 완료되고 다음 프롬프트를 기다릴 때 |
    | `auth_success`         | 인증이 완료될 때                   |
    | `elicitation_dialog`   | MCP 서버가 질문 양식을 열 때          |
    | `elicitation_complete` | MCP 질문 양식이 제출되거나 닫힐 때       |
    | `elicitation_response` | MCP 질문 응답이 서버로 다시 전송될 때     |
  </Step>

  <Step title="hook 검증하기">
    `/hooks`를 입력하고 `Notification`을 선택하여 hook이 나타나는지 확인합니다. 선택하면 실행될 명령이 표시됩니다. 종단 간 테스트하려면 Claude에게 권한이 필요한 명령을 실행하도록 요청하고 터미널에서 전환하거나, Claude에게 직접 알림을 트리거하도록 요청합니다.
  </Step>
</Steps>

전체 이벤트 스키마 및 알림 유형은 [알림 참조](/ko/hooks#notification)를 참조하십시오.

***

## Claude를 unix 스타일 유틸리티로 사용하기

### 검증 프로세스에 Claude 추가하기

Claude Code를 linter 또는 코드 검토자로 사용하고 싶다고 가정해봅시다.

**빌드 스크립트에 Claude 추가하기:**

```json theme={null}
// package.json
{
    ...
    "scripts": {
        ...
        "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.'"
    }
}
```

<Tip>
  팁:

  * CI/CD 파이프라인에서 자동 코드 검토를 위해 Claude 사용
  * 프로젝트와 관련된 특정 문제를 확인하도록 프롬프트 사용자 정의
  * 다양한 유형의 검증을 위해 여러 스크립트 만들기 고려
</Tip>

### 파이프 인, 파이프 아웃

Claude로 데이터를 파이프하고 구조화된 형식으로 데이터를 다시 받고 싶다고 가정해봅시다.

**Claude를 통해 데이터 파이프하기:**

```bash theme={null}
cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt
```

<Tip>
  팁:

  * 기존 셸 스크립트에 Claude를 통합하기 위해 파이프 사용
  * 강력한 워크플로우를 위해 다른 Unix 도구와 결합
  * 스크립트나 다른 도구에 Claude Code를 통합할 때 `--output-format` 사용 고려
</Tip>

### 출력 형식 제어하기

특히 Claude Code를 스크립트나 다른 도구에 통합할 때 특정 형식의 Claude 출력이 필요하다고 가정해봅시다.

<Steps>
  <Step title="텍스트 형식 사용 (기본값)">
    ```bash theme={null}
    cat data.txt | claude -p 'summarize this data' --output-format text > summary.txt
    ```

    이것은 Claude의 일반 텍스트 응답만 출력합니다 (기본 동작).
  </Step>

  <Step title="JSON 형식 사용">
    ```bash theme={null}
    cat code.py | claude -p 'analyze this code for bugs' --output-format json > analysis.json
    ```

    이것은 비용 및 기간을 포함한 메타데이터가 있는 메시지의 JSON 배열을 출력합니다.
  </Step>

  <Step title="스트리밍 JSON 형식 사용">
    ```bash theme={null}
    cat log.txt | claude -p 'parse this log file for errors' --output-format stream-json
    ```

    이것은 Claude가 요청을 처리할 때 실시간으로 일련의 JSON 객체를 출력합니다. 각 메시지는 유효한 JSON 객체이지만 연결된 전체 출력은 유효한 JSON이 아닙니다.
  </Step>
</Steps>

<Tip>
  팁:

  * Claude의 응답만 필요한 간단한 통합을 위해 `--output-format text` 사용
  * 전체 대화 로그가 필요할 때 `--output-format json` 사용
  * 각 대화 턴의 실시간 출력을 위해 `--output-format stream-json` 사용
</Tip>

***

## Claude를 일정에 따라 실행하기

Claude가 정기적으로 작업을 자동으로 처리하도록 하고 싶다고 가정해봅시다. 예를 들어 매일 아침 열린 PR을 검토하거나, 매주 종속성을 감사하거나, 밤새 CI 실패를 확인합니다.

작업을 실행할 위치에 따라 일정 옵션을 선택합니다:

| 옵션                                        | 실행 위치            | 최적 사용                                                                                                                                     |
| :---------------------------------------- | :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------- |
| [Routines](/ko/routines)                  | Anthropic 관리 인프라 | 컴퓨터가 꺼져 있어도 실행되어야 하는 작업. API 호출 또는 GitHub 이벤트 외에도 일정에 따라 트리거될 수 있습니다. [claude.ai/code/routines](https://claude.ai/code/routines)에서 구성합니다. |
| [데스크톱 예약 작업](/ko/desktop-scheduled-tasks) | 데스크톱 앱을 통한 컴퓨터   | 로컬 파일, 도구 또는 커밋되지 않은 변경사항에 직접 액세스해야 하는 작업.                                                                                                |
| [GitHub Actions](/ko/github-actions)      | CI 파이프라인         | 열린 PR 또는 cron 일정과 같은 저장소 이벤트와 연결된 작업. 워크플로우 구성과 함께 있어야 합니다.                                                                               |
| [`/loop`](/ko/scheduled-tasks)            | 현재 CLI 세션        | 세션이 열려 있는 동안 빠른 폴링. 새 대화를 시작하면 작업이 중지됩니다. `--resume` 및 `--continue`는 만료되지 않은 것을 복원합니다.                                                    |

<Tip>
  예약된 작업을 위한 프롬프트를 작성할 때 성공이 무엇인지, 결과를 어떻게 처리할지 명시적으로 설명하십시오. 작업이 자동으로 실행되므로 명확한 질문을 할 수 없습니다. 예를 들어: "Review open PRs labeled `needs-review`, leave inline comments on any issues, and post a summary in the `#eng-reviews` Slack channel."
</Tip>

***

## Claude의 기능에 대해 Claude에게 물어보기

Claude는 자신의 문서에 대한 기본 제공 액세스 권한을 가지고 있으며 자신의 기능과 제한사항에 대한 질문에 답할 수 있습니다.

### 예제 질문

```text theme={null}
can Claude Code create pull requests?
```

```text theme={null}
how does Claude Code handle permissions?
```

```text theme={null}
what skills are available?
```

```text theme={null}
how do I use MCP with Claude Code?
```

```text theme={null}
how do I configure Claude Code for Amazon Bedrock?
```

```text theme={null}
what are the limitations of Claude Code?
```

<Note>
  Claude는 이러한 질문에 대해 문서 기반 답변을 제공합니다. 실행 가능한 예제 및 실습 시연을 위해 `/powerup`을 실행하여 애니메이션 데모가 있는 대화형 수업을 받거나 위의 특정 워크플로우 섹션을 참조하십시오.
</Note>

<Tip>
  팁:

  * Claude는 사용 중인 버전에 관계없이 항상 최신 Claude Code 문서에 액세스할 수 있습니다
  * 자세한 답변을 얻으려면 구체적인 질문을 하십시오
  * Claude는 MCP 통합, 엔터프라이즈 구성 및 고급 워크플로우와 같은 복잡한 기능을 설명할 수 있습니다
</Tip>

***

## 다음 단계

<CardGroup cols={2}>
  <Card title="모범 사례" icon="lightbulb" href="/ko/best-practices">
    Claude Code에서 최대한 활용하기 위한 패턴
  </Card>

  <Card title="Claude Code 작동 방식" icon="gear" href="/ko/how-claude-code-works">
    에이전트 루프 및 컨텍스트 관리 이해하기
  </Card>

  <Card title="Claude Code 확장하기" icon="puzzle-piece" href="/ko/features-overview">
    skill, hook, MCP, subagent 및 플러그인 추가하기
  </Card>

  <Card title="참조 구현" icon="code" href="https://github.com/anthropics/claude-code/tree/main/.devcontainer">
    개발 컨테이너 참조 구현 복제하기
  </Card>
</CardGroup>