일반적인 워크플로우

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

이 페이지에서는 일상적인 개발을 위한 실용적인 워크플로우를 다룹니다: 익숙하지 않은 코드 탐색, 디버깅, 리팩토링, 테스트 작성, PR 생성, 세션 관리 등이 포함됩니다. 각 섹션에는 프로젝트에 맞게 활용할 수 있는 예시 프롬프트가 포함되어 있습니다. 상위 수준의 패턴과 팁은 모범 사례를 참조하세요.

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

코드베이스 빠르게 파악하기

새 프로젝트에 합류하여 구조를 빠르게 이해해야 하는 상황을 가정해 보겠습니다.

Step 1: 프로젝트 루트 디렉토리로 이동

cd /path/to/project

Step 2: Claude Code 시작

claude

Step 3: 높은 수준의 개요 요청

give me an overview of this codebase

Step 4: 특정 컴포넌트 심층 탐색

explain the main architecture patterns used here

what are the key data models?

how is authentication handled?

팁:

넓은 질문부터 시작한 후 특정 영역으로 좁혀 나가세요

프로젝트에서 사용하는 코딩 컨벤션과 패턴에 대해 질문하세요

프로젝트 전용 용어 사전을 요청하세요

효율적인 버그 수정

오류 메시지가 발생하여 원인을 찾아 수정해야 하는 상황을 가정해 보겠습니다.

Step 1: Claude에게 오류 공유

I'm seeing an error when I run npm test

Step 2: 수정 방법 제안 요청

suggest a few ways to fix the @ts-ignore in user.ts

Step 3: 수정 적용

update user.ts to add the null check you suggested

팁:

Claude에게 문제를 재현하고 스택 트레이스를 얻을 수 있는 명령어를 알려주세요

오류 재현 단계를 함께 언급하세요

오류가 간헐적인지 지속적인지 Claude에게 알려주세요

코드 리팩토링

오래된 코드를 최신 패턴과 관행으로 업데이트해야 하는 상황을 가정해 보겠습니다.

Step 1: 리팩토링 대상 레거시 코드 식별

find deprecated API usage in our codebase

Step 2: 리팩토링 방안 제안 받기

suggest how to refactor utils.js to use modern JavaScript features

Step 3: 안전하게 변경 적용

refactor utils.js to use ES2024 features while maintaining the same behavior

Step 4: 리팩토링 검증

run tests for the refactored code

팁:

Claude에게 최신 접근 방식의 장점을 설명해 달라고 요청하세요

필요한 경우 하위 호환성을 유지하도록 요청하세요

리팩토링을 작고 테스트 가능한 단위로 나누어 진행하세요

전문 서브에이전트 활용

특정 작업을 더 효과적으로 처리하기 위해 전문 AI 서브에이전트를 사용하고 싶은 상황을 가정해 보겠습니다.

Step 1: 사용 가능한 서브에이전트 확인

/agents

사용 가능한 모든 서브에이전트를 보여주며 새로운 서브에이전트를 만들 수 있습니다.

Step 2: 자동으로 서브에이전트 사용

Claude Code는 적절한 작업을 전문 서브에이전트에 자동으로 위임합니다:

review my recent code changes for security issues

run all tests and fix any failures

Step 3: 특정 서브에이전트 명시적으로 요청

use the code-reviewer subagent to check the auth module

have the debugger subagent investigate why users can't log in

Step 4: 워크플로우에 맞는 커스텀 서브에이전트 생성

/agents

"Create New subagent"를 선택하고 안내에 따라 다음을 정의합니다:

서브에이전트의 목적을 설명하는 고유 식별자 (예: code-reviewer, api-designer)
Claude가 이 에이전트를 사용해야 하는 시점
접근 가능한 도구
에이전트의 역할과 동작을 설명하는 시스템 프롬프트

팁:

팀 공유를 위해 .claude/agents/에 프로젝트별 서브에이전트를 만드세요

자동 위임이 가능하도록 description 필드를 명확하게 작성하세요

각 서브에이전트에 실제로 필요한 도구만 접근하도록 제한하세요

자세한 예시는 서브에이전트 문서를 확인하세요

안전한 코드 분석을 위한 Plan Mode 사용

Plan Mode는 Claude가 읽기 전용 작업으로 코드베이스를 분석하여 계획을 생성하도록 지시합니다. 코드베이스 탐색, 복잡한 변경 계획 수립, 코드 리뷰를 안전하게 수행하는 데 적합합니다. Plan Mode에서 Claude는 AskUserQuestion을 사용하여 요구사항을 수집하고 목표를 명확히 합니다.

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 플래그를 사용하세요:

claude --permission-mode plan

Plan Mode에서 "headless" 쿼리 실행

-p 옵션으로 Plan Mode에서 직접 쿼리를 실행할 수도 있습니다 (즉, "headless 모드"):

claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"

예시: 복잡한 리팩토링 계획 수립

claude --permission-mode plan

I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.

Claude가 현재 구현을 분석하고 종합적인 계획을 생성합니다. 후속 질문으로 계획을 다듬으세요:

What about backward compatibility?

How should we handle database migration?

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

Plan Mode를 기본값으로 설정

// .claude/settings.json
{
  "permissions": {
    "defaultMode": "plan"
  }
}

더 많은 설정 옵션은 설정 문서를 참조하세요.

테스트 작업

테스트가 없는 코드에 테스트를 추가해야 하는 상황을 가정해 보겠습니다.

Step 1: 테스트되지 않은 코드 식별

find functions in NotificationsService.swift that are not covered by tests

Step 2: 테스트 스캐폴딩 생성

add tests for the notification service

Step 3: 의미 있는 테스트 케이스 추가

add test cases for edge conditions in the notification service

Step 4: 테스트 실행 및 검증

run the new tests and fix any failures

Claude는 프로젝트의 기존 패턴과 컨벤션에 맞는 테스트를 생성할 수 있습니다. 테스트를 요청할 때 검증하고 싶은 동작을 구체적으로 명시하세요. Claude는 기존 테스트 파일을 분석하여 이미 사용 중인 스타일, 프레임워크, 어설션 패턴을 맞춥니다.

포괄적인 커버리지를 위해 Claude에게 놓칠 수 있는 엣지 케이스를 식별해 달라고 요청하세요. Claude는 코드 경로를 분석하여 오류 조건, 경계값, 예상치 못한 입력에 대한 테스트를 제안할 수 있습니다.

Pull Request 생성

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

Step 1: 변경 사항 요약

summarize the changes I've made to the authentication module

Step 2: Pull Request 생성

create a pr

Step 3: 검토 및 보완

enhance the PR description with more context about the security improvements

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

팁: Claude가 생성한 PR을 제출하기 전에 검토하고, Claude에게 잠재적 위험이나 고려 사항을 강조해 달라고 요청하세요.

문서화 처리

코드에 대한 문서를 추가하거나 업데이트해야 하는 상황을 가정해 보겠습니다.

Step 1: 문서화되지 않은 코드 식별

find functions without proper JSDoc comments in the auth module

Step 2: 문서 생성

add JSDoc comments to the undocumented functions in auth.js

Step 3: 검토 및 개선

improve the generated documentation with more context and examples

Step 4: 문서 검증

check if the documentation follows our project standards

팁:

원하는 문서화 스타일을 명시하세요 (JSDoc, docstrings 등)

문서에 예시를 포함해 달라고 요청하세요

공개 API, 인터페이스, 복잡한 로직에 대한 문서를 요청하세요

이미지 작업

코드베이스에서 이미지를 다루며 Claude의 이미지 분석 도움이 필요한 상황을 가정해 보겠습니다.

Step 1: 대화에 이미지 추가

다음 방법 중 하나를 사용할 수 있습니다:

Claude Code 창에 이미지를 드래그 앤 드롭
이미지를 복사한 후 CLI에 ctrl+v로 붙여넣기 (cmd+v는 사용하지 마세요)
Claude에게 이미지 경로를 제공. 예: "Analyze this image: /path/to/your/image.png"

Step 2: Claude에게 이미지 분석 요청

What does this image show?

Describe the UI elements in this screenshot

Are there any problematic elements in this diagram?

Step 3: 컨텍스트로 이미지 활용

Here's a screenshot of the error. What's causing it?

This is our current database schema. How should we modify it for the new feature?

Step 4: 시각적 콘텐츠에서 코드 제안 받기

Generate CSS to match this design mockup

What HTML structure would recreate this component?

팁:

텍스트 설명이 불분명하거나 번거로울 때 이미지를 사용하세요

더 나은 컨텍스트를 위해 오류 스크린샷, UI 디자인, 다이어그램을 포함하세요

대화에서 여러 이미지를 함께 사용할 수 있습니다

이미지 분석은 다이어그램, 스크린샷, 목업 등에서 작동합니다

Claude가 이미지를 참조할 때 (예: [Image #1]), Cmd+Click (Mac) 또는 Ctrl+Click (Windows/Linux)으로 링크를 클릭하면 기본 뷰어에서 이미지를 열 수 있습니다

파일 및 디렉토리 참조

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

Step 1: 단일 파일 참조

Explain the logic in @src/utils/auth.js

대화에 파일의 전체 내용이 포함됩니다.

Step 2: 디렉토리 참조

What's the structure of @src/components?

파일 정보가 포함된 디렉토리 목록을 제공합니다.

Step 3: MCP 리소스 참조

Show me the data from @github:repos/owner/repo/issues

@server:resource 형식을 사용하여 연결된 MCP 서버에서 데이터를 가져옵니다. 자세한 내용은 MCP 리소스를 참조하세요.

팁:

파일 경로는 상대 경로 또는 절대 경로를 사용할 수 있습니다

@ 파일 참조는 해당 파일의 디렉토리와 상위 디렉토리에 있는 CLAUDE.md를 컨텍스트에 추가합니다

디렉토리 참조는 내용이 아닌 파일 목록을 보여줍니다

단일 메시지에서 여러 파일을 참조할 수 있습니다 (예: "@file1.js and @file2.js")

확장 사고 (thinking mode) 사용

확장 사고는 기본적으로 활성화되어 있으며, Claude에게 응답하기 전에 복잡한 문제를 단계별로 추론할 수 있는 공간을 제공합니다. 이 추론 과정은 verbose 모드에서 확인할 수 있으며, Ctrl+O로 전환할 수 있습니다.

또한 Opus 4.6는 적응형 추론을 도입했습니다: 고정된 사고 토큰 예산 대신, 모델이 노력 수준 설정에 따라 동적으로 사고를 할당합니다. 확장 사고와 적응형 추론이 함께 작동하여 Claude가 응답하기 전에 얼마나 깊이 추론할지 제어할 수 있습니다.

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

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

thinking mode 설정

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

범위	설정 방법	세부사항
노력 수준	`/model`에서 조정하거나 `CLAUDE_CODE_EFFORT_LEVEL` 설정	Opus 4.6 및 Sonnet 4.6의 사고 깊이를 제어: low, medium, high. 노력 수준 조정 참조
`ultrathink` 키워드	프롬프트 어디에나 "ultrathink"를 포함	Opus 4.6 및 Sonnet 4.6에서 해당 턴의 노력을 high로 설정. 노력 설정을 영구적으로 변경하지 않고 깊은 추론이 필요한 일회성 작업에 유용
토글 단축키	`Option+T` (macOS) 또는 `Alt+T` (Windows/Linux) 누르기	현재 세션의 사고를 켜기/끄기 (모든 모델). Option 키 단축키를 활성화하려면 터미널 설정이 필요할 수 있음
전역 기본값	`/config`에서 thinking mode 토글	모든 프로젝트에 대한 기본값 설정 (모든 모델). `~/.claude/settings.json`에 `alwaysThinkingEnabled`로 저장됨
토큰 예산 제한	`MAX_THINKING_TOKENS` 환경 변수 설정	사고 예산을 특정 토큰 수로 제한 (Opus 4.6에서는 0으로 설정하지 않는 한 무시됨). 예: `export MAX_THINKING_TOKENS=10000`

Claude의 사고 과정을 보려면 Ctrl+O를 눌러 verbose 모드를 전환하면 내부 추론이 회색 이탤릭 텍스트로 표시됩니다.

확장 사고의 작동 방식

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

Opus 4.6에서는 사고가 적응형 추론을 사용합니다: 모델이 선택한 노력 수준 (low, medium, high)에 따라 사고 토큰을 동적으로 할당합니다. 이것이 속도와 추론 깊이 간의 트레이드오프를 조절하는 권장 방법입니다.

다른 모델에서는 사고가 출력 예산에서 최대 31,999 토큰의 고정 예산을 사용합니다. MAX_THINKING_TOKENS 환경 변수로 이를 제한하거나, /config 또는 Option+T/Alt+T 토글로 사고를 완전히 비활성화할 수 있습니다.

MAX_THINKING_TOKENS는 적응형 추론이 사고 깊이를 대신 제어하므로 Opus 4.6 및 Sonnet 4.6에서는 무시됩니다. 한 가지 예외: MAX_THINKING_TOKENS=0으로 설정하면 어떤 모델에서든 사고가 완전히 비활성화됩니다. 적응형 사고를 비활성화하고 고정 사고 예산으로 되돌리려면 CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1을 설정하세요. 환경 변수를 참조하세요.

주의: Claude 4 모델이 요약된 사고를 표시하더라도 사용된 모든 사고 토큰에 대해 비용이 청구됩니다

이전 대화 재개

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

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

활성 세션 내에서 /resume을 사용하여 다른 대화로 전환할 수 있습니다.

세션은 프로젝트 디렉토리별로 저장됩니다. /resume 선택기는 worktree를 포함하여 동일한 Git 리포지토리의 세션을 표시합니다.

세션 이름 지정

나중에 찾기 쉽도록 세션에 설명적인 이름을 지정하세요. 여러 작업이나 기능을 동시에 진행할 때 권장되는 방법입니다.

Step 1: 현재 세션에 이름 지정

세션 중에 /rename을 사용하여 기억하기 쉬운 이름을 지정하세요:

/rename auth-refactor

선택기에서 모든 세션의 이름을 변경할 수도 있습니다: /resume을 실행하고 세션으로 이동한 후 R을 누르세요.

Step 2: 나중에 이름으로 재개

커맨드 라인에서:

claude --resume auth-refactor

또는 활성 세션 내에서:

/resume auth-refactor

세션 선택기 사용

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

선택기의 키보드 단축키:

단축키	동작
`↑` / `↓`	세션 간 이동
`→` / `←`	그룹화된 세션 펼치기 또는 접기
`Enter`	강조된 세션 선택 및 재개
`P`	세션 내용 미리보기
`R`	강조된 세션 이름 변경
`/`	세션 필터링을 위한 검색
`A`	현재 디렉토리와 모든 프로젝트 간 전환
`B`	현재 Git 브랜치의 세션만 필터링
`Esc`	선택기 또는 검색 모드 종료

세션 정리:

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

세션 이름 또는 초기 프롬프트
마지막 활동 이후 경과 시간
메시지 수
Git 브랜치 (해당하는 경우)

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

팁:

세션 이름을 일찍 지정하세요: 특정 작업을 시작할 때 /rename을 사용하세요. 나중에 "explain this function"보다 "payment-integration"을 찾는 것이 훨씬 쉽습니다

현재 디렉토리에서 가장 최근 대화에 빠르게 접근하려면 --continue를 사용하세요

어떤 세션이 필요한지 알고 있다면 --resume session-name을 사용하세요

탐색하고 선택해야 한다면 --resume (이름 없이)을 사용하세요

스크립트에서는 claude --continue --print "prompt"를 사용하여 비대화형 모드로 재개하세요

선택기에서 P를 눌러 재개하기 전에 세션을 미리 확인하세요

재개된 대화는 원본과 동일한 모델 및 설정으로 시작됩니다

작동 방식:

대화 저장: 모든 대화는 전체 메시지 이력과 함께 로컬에 자동 저장됩니다

메시지 역직렬화: 재개 시 컨텍스트를 유지하기 위해 전체 메시지 이력이 복원됩니다

도구 상태: 이전 대화의 도구 사용 및 결과가 보존됩니다

컨텍스트 복원: 이전의 모든 컨텍스트가 그대로 유지된 상태로 대화가 재개됩니다

Git Worktree를 사용한 병렬 Claude Code 세션 실행

여러 작업을 동시에 진행할 때, 변경 사항이 충돌하지 않도록 각 Claude 세션에 코드베이스의 자체 사본이 필요합니다. Git worktree는 각각 고유한 파일과 브랜치를 가지면서 동일한 리포지토리 이력과 리모트 연결을 공유하는 별도의 작업 디렉토리를 생성하여 이 문제를 해결합니다. 이를 통해 한 worktree에서 Claude가 기능을 개발하는 동안 다른 worktree에서 버그를 수정할 수 있으며, 서로 간섭하지 않습니다.

--worktree (-w) 플래그를 사용하여 격리된 worktree를 생성하고 그 안에서 Claude를 시작하세요. 전달하는 값이 worktree 디렉토리 이름과 브랜치 이름이 됩니다:

# Start Claude in a worktree named "feature-auth"
# Creates .claude/worktrees/feature-auth/ with a new branch
claude --worktree feature-auth

# Start another session in a separate worktree
claude --worktree bugfix-123

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

# Auto-generates a name like "bright-running-fox"
claude --worktree

Worktree는 <repo>/.claude/worktrees/<name>에 생성되며 기본 리모트 브랜치에서 분기됩니다. worktree 브랜치의 이름은 worktree-<name>입니다.

세션 중에 Claude에게 "work in a worktree" 또는 "start a worktree"라고 요청할 수도 있으며, Claude가 자동으로 생성합니다.

서브에이전트 worktree

서브에이전트도 worktree 격리를 사용하여 충돌 없이 병렬로 작업할 수 있습니다. Claude에게 "use worktrees for your agents"라고 요청하거나, 커스텀 서브에이전트의 frontmatter에 isolation: worktree를 추가하여 설정하세요. 각 서브에이전트는 자체 worktree를 가지며, 변경 사항 없이 완료되면 자동으로 정리됩니다.

Worktree 정리

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

변경 사항 없음: worktree와 해당 브랜치가 자동으로 제거됩니다
변경 사항 또는 커밋 존재: Claude가 worktree를 유지할지 제거할지 확인합니다. 유지하면 나중에 돌아올 수 있도록 디렉토리와 브랜치가 보존됩니다. 제거하면 worktree 디렉토리와 브랜치가 삭제되며, 커밋되지 않은 모든 변경 사항과 커밋이 폐기됩니다

Claude 세션 외부에서 worktree를 정리하려면 수동 worktree 관리를 사용하세요.

팁: .claude/worktrees/를 .gitignore에 추가하면 worktree 내용이 메인 리포지토리에서 추적되지 않는 파일로 나타나는 것을 방지할 수 있습니다.

수동 worktree 관리

worktree 위치와 브랜치 설정을 더 세밀하게 제어하려면 Git으로 직접 worktree를 생성하세요. 특정 기존 브랜치를 체크아웃하거나 리포지토리 외부에 worktree를 배치해야 할 때 유용합니다.

# Create a worktree with a new branch
git worktree add ../project-feature-a -b feature-a

# Create a worktree with an existing branch
git worktree add ../project-bugfix bugfix-123

# Start Claude in the worktree
cd ../project-feature-a && claude

# Clean up when done
git worktree list
git worktree remove ../project-feature-a

자세한 내용은 공식 Git worktree 문서를 참조하세요.

팁: 프로젝트의 설정 과정에 따라 각 새 worktree에서 개발 환경을 초기화하는 것을 잊지 마세요. 스택에 따라 의존성 설치 (npm install, yarn), 가상 환경 설정, 또는 프로젝트의 표준 설정 과정이 포함될 수 있습니다.

Git 이외의 버전 관리

Worktree 격리는 기본적으로 Git과 함께 작동합니다. SVN, Perforce, Mercurial과 같은 다른 버전 관리 시스템의 경우, WorktreeCreate 및 WorktreeRemove 훅을 설정하여 커스텀 worktree 생성 및 정리 로직을 제공하세요. 설정되면 --worktree를 사용할 때 이 훅이 기본 Git 동작을 대체합니다.

병렬 세션의 공유 작업과 메시징을 자동으로 조율하려면 에이전트 팀을 참조하세요.

Claude가 주의를 기울여야 할 때 알림 받기

장시간 실행되는 작업을 시작하고 다른 창으로 전환할 때, Claude가 완료되거나 입력이 필요할 때 알 수 있도록 데스크톱 알림을 설정할 수 있습니다. 이는 Notification 훅 이벤트를 사용하며, Claude가 권한을 기다리거나, 유휴 상태로 새 프롬프트를 대기하거나, 인증을 완료할 때 발동합니다.

Step 1: 훅 메뉴 열기

/hooks를 입력하고 이벤트 목록에서 Notification을 선택하세요.

Step 2: 매처 설정

+ Match all (no filter)를 선택하면 모든 알림 유형에 발동합니다. 특정 이벤트에만 알림을 받으려면 + Add new matcher…를 선택하고 다음 값 중 하나를 입력하세요:

매처	발동 시점
`permission_prompt`	Claude가 도구 사용 승인을 필요로 할 때
`idle_prompt`	Claude가 완료되고 다음 프롬프트를 기다릴 때
`auth_success`	인증이 완료될 때
`elicitation_dialog`	Claude가 질문을 하고 있을 때

Step 3: 알림 명령어 추가

+ Add new hook…을 선택하고 운영체제에 맞는 명령어를 입력하세요:

macOS

osascript를 사용하여 AppleScript를 통해 네이티브 macOS 알림을 트리거합니다:

osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'

Linux

대부분의 Linux 데스크톱에 알림 데몬과 함께 사전 설치된 notify-send를 사용합니다:

notify-send 'Claude Code' 'Claude Code needs your attention'

Windows (PowerShell)

PowerShell을 사용하여 .NET의 Windows Forms를 통해 네이티브 메시지 박스를 표시합니다:

powershell.exe -Command "[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')"

Step 4: 사용자 설정에 저장

User settings를 선택하면 모든 프로젝트에 알림이 적용됩니다.

JSON 설정 예시가 포함된 전체 가이드는 훅으로 워크플로우 자동화를 참조하세요. 전체 이벤트 스키마와 알림 유형은 Notification 레퍼런스를 참조하세요.

Claude를 유닉스 스타일 유틸리티로 사용

검증 프로세스에 Claude 추가

Claude Code를 린터 또는 코드 리뷰어로 사용하고 싶은 상황을 가정해 보겠습니다.

빌드 스크립트에 Claude 추가:

// 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.'"
    }
}

팁:

CI/CD 파이프라인에서 자동 코드 리뷰에 Claude를 사용하세요

프로젝트와 관련된 특정 이슈를 확인하도록 프롬프트를 커스터마이즈하세요

다양한 유형의 검증을 위해 여러 스크립트를 만드는 것을 고려하세요

파이프 입출력

데이터를 Claude에 파이프로 보내고 구조화된 형식으로 결과를 받고 싶은 상황을 가정해 보겠습니다.

Claude를 통해 데이터 파이프:

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

팁:

파이프를 사용하여 Claude를 기존 셸 스크립트에 통합하세요

다른 Unix 도구와 결합하여 강력한 워크플로우를 구성하세요

구조화된 출력을 위해 --output-format 사용을 고려하세요

출력 형식 제어

특히 Claude Code를 스크립트나 다른 도구에 통합할 때 Claude의 출력을 특정 형식으로 받아야 하는 상황을 가정해 보겠습니다.

Step 1: 텍스트 형식 사용 (기본값)

cat data.txt | claude -p 'summarize this data' --output-format text > summary.txt

Claude의 일반 텍스트 응답만 출력합니다 (기본 동작).

Step 2: JSON 형식 사용

cat code.py | claude -p 'analyze this code for bugs' --output-format json > analysis.json

비용 및 소요 시간을 포함한 메타데이터와 함께 메시지의 JSON 배열을 출력합니다.

Step 3: 스트리밍 JSON 형식 사용

cat log.txt | claude -p 'parse this log file for errors' --output-format stream-json

Claude가 요청을 처리하는 동안 실시간으로 일련의 JSON 객체를 출력합니다. 각 메시지는 유효한 JSON 객체이지만, 전체 출력을 연결하면 유효한 JSON이 아닙니다.

팁:

Claude의 응답만 필요한 간단한 통합에는 --output-format text를 사용하세요

전체 대화 로그가 필요하면 --output-format json을 사용하세요

각 대화 턴의 실시간 출력에는 --output-format stream-json을 사용하세요

Claude의 기능에 대해 질문하기

Claude는 자체 문서에 내장 접근 권한이 있으며, 자신의 기능과 제한 사항에 대한 질문에 답할 수 있습니다.

질문 예시

can Claude Code create pull requests?

how does Claude Code handle permissions?

what skills are available?

how do I use MCP with Claude Code?

how do I configure Claude Code for Amazon Bedrock?

what are the limitations of Claude Code?

참고: Claude는 이러한 질문에 대해 문서 기반 답변을 제공합니다. 실행 가능한 예시와 실습 데모는 위의 특정 워크플로우 섹션을 참조하세요.

팁:

Claude는 사용 중인 버전에 관계없이 항상 최신 Claude Code 문서에 접근할 수 있습니다

구체적인 질문을 하면 자세한 답변을 얻을 수 있습니다

Claude는 MCP 통합, 엔터프라이즈 구성, 고급 워크플로우와 같은 복잡한 기능을 설명할 수 있습니다

다음 단계

모범 사례 - Claude Code에서 최대한 활용하기 위한 패턴
Claude Code 작동 방식 - 에이전트 루프 및 컨텍스트 관리 이해하기
Claude Code 확장하기 - skill, hook, MCP, subagent 및 플러그인 추가하기
참조 구현 - 개발 컨테이너 참조 구현 복제하기

일반적인 워크플로우

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

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

코드베이스 빠르게 파악하기

새 프로젝트에 합류하여 구조를 빠르게 이해해야 하는 상황을 가정해 보겠습니다.

Step 1: 프로젝트 루트 디렉토리로 이동

cd /path/to/project

Step 2: Claude Code 시작

claude

Step 3: 높은 수준의 개요 요청

give me an overview of this codebase

Step 4: 특정 컴포넌트 심층 탐색

explain the main architecture patterns used here

what are the key data models?

how is authentication handled?

팁:

넓은 질문부터 시작한 후 특정 영역으로 좁혀 나가세요

프로젝트에서 사용하는 코딩 컨벤션과 패턴에 대해 질문하세요

프로젝트 전용 용어 사전을 요청하세요

효율적인 버그 수정

오류 메시지가 발생하여 원인을 찾아 수정해야 하는 상황을 가정해 보겠습니다.

Step 1: Claude에게 오류 공유

I'm seeing an error when I run npm test

Step 2: 수정 방법 제안 요청

suggest a few ways to fix the @ts-ignore in user.ts

Step 3: 수정 적용

update user.ts to add the null check you suggested

팁:

Claude에게 문제를 재현하고 스택 트레이스를 얻을 수 있는 명령어를 알려주세요

오류 재현 단계를 함께 언급하세요

오류가 간헐적인지 지속적인지 Claude에게 알려주세요

코드 리팩토링

오래된 코드를 최신 패턴과 관행으로 업데이트해야 하는 상황을 가정해 보겠습니다.

Step 1: 리팩토링 대상 레거시 코드 식별

find deprecated API usage in our codebase

Step 2: 리팩토링 방안 제안 받기

suggest how to refactor utils.js to use modern JavaScript features

Step 3: 안전하게 변경 적용

refactor utils.js to use ES2024 features while maintaining the same behavior

Step 4: 리팩토링 검증

run tests for the refactored code

팁:

Claude에게 최신 접근 방식의 장점을 설명해 달라고 요청하세요

필요한 경우 하위 호환성을 유지하도록 요청하세요

리팩토링을 작고 테스트 가능한 단위로 나누어 진행하세요

전문 서브에이전트 활용

특정 작업을 더 효과적으로 처리하기 위해 전문 AI 서브에이전트를 사용하고 싶은 상황을 가정해 보겠습니다.

Step 1: 사용 가능한 서브에이전트 확인

/agents

사용 가능한 모든 서브에이전트를 보여주며 새로운 서브에이전트를 만들 수 있습니다.

Step 2: 자동으로 서브에이전트 사용

Claude Code는 적절한 작업을 전문 서브에이전트에 자동으로 위임합니다:

review my recent code changes for security issues

run all tests and fix any failures

Step 3: 특정 서브에이전트 명시적으로 요청

use the code-reviewer subagent to check the auth module

have the debugger subagent investigate why users can't log in

Step 4: 워크플로우에 맞는 커스텀 서브에이전트 생성

/agents

"Create New subagent"를 선택하고 안내에 따라 다음을 정의합니다:

서브에이전트의 목적을 설명하는 고유 식별자 (예: code-reviewer, api-designer)
Claude가 이 에이전트를 사용해야 하는 시점
접근 가능한 도구
에이전트의 역할과 동작을 설명하는 시스템 프롬프트

팁:

팀 공유를 위해 .claude/agents/에 프로젝트별 서브에이전트를 만드세요

자동 위임이 가능하도록 description 필드를 명확하게 작성하세요

각 서브에이전트에 실제로 필요한 도구만 접근하도록 제한하세요

자세한 예시는 서브에이전트 문서를 확인하세요

안전한 코드 분석을 위한 Plan Mode 사용

Plan Mode를 사용해야 하는 경우

다단계 구현: 기능 구현을 위해 여러 파일을 수정해야 하는 경우
코드 탐색: 변경하기 전에 코드베이스를 철저히 조사하고 싶은 경우
대화형 개발: Claude와 함께 방향을 반복적으로 조율하고 싶은 경우

Plan Mode 사용 방법

세션 중 Plan Mode 전환

세션 중에 Shift+Tab으로 권한 모드를 순환하여 Plan Mode로 전환할 수 있습니다.

새 세션을 Plan Mode로 시작

새 세션을 Plan Mode로 시작하려면 --permission-mode plan 플래그를 사용하세요:

claude --permission-mode plan

Plan Mode에서 "headless" 쿼리 실행

-p 옵션으로 Plan Mode에서 직접 쿼리를 실행할 수도 있습니다 (즉, "headless 모드"):

claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"

예시: 복잡한 리팩토링 계획 수립

claude --permission-mode plan

I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.

Claude가 현재 구현을 분석하고 종합적인 계획을 생성합니다. 후속 질문으로 계획을 다듬으세요:

What about backward compatibility?

How should we handle database migration?

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

Plan Mode를 기본값으로 설정

// .claude/settings.json
{
  "permissions": {
    "defaultMode": "plan"
  }
}

더 많은 설정 옵션은 설정 문서를 참조하세요.

테스트 작업

테스트가 없는 코드에 테스트를 추가해야 하는 상황을 가정해 보겠습니다.

Step 1: 테스트되지 않은 코드 식별

find functions in NotificationsService.swift that are not covered by tests

Step 2: 테스트 스캐폴딩 생성

add tests for the notification service

Step 3: 의미 있는 테스트 케이스 추가

add test cases for edge conditions in the notification service

Step 4: 테스트 실행 및 검증

run the new tests and fix any failures

Pull Request 생성

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

Step 1: 변경 사항 요약

summarize the changes I've made to the authentication module

Step 2: Pull Request 생성

create a pr

Step 3: 검토 및 보완

enhance the PR description with more context about the security improvements

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

팁: Claude가 생성한 PR을 제출하기 전에 검토하고, Claude에게 잠재적 위험이나 고려 사항을 강조해 달라고 요청하세요.

문서화 처리

코드에 대한 문서를 추가하거나 업데이트해야 하는 상황을 가정해 보겠습니다.

Step 1: 문서화되지 않은 코드 식별

find functions without proper JSDoc comments in the auth module

Step 2: 문서 생성

add JSDoc comments to the undocumented functions in auth.js

Step 3: 검토 및 개선

improve the generated documentation with more context and examples

Step 4: 문서 검증

check if the documentation follows our project standards

팁:

원하는 문서화 스타일을 명시하세요 (JSDoc, docstrings 등)

문서에 예시를 포함해 달라고 요청하세요

공개 API, 인터페이스, 복잡한 로직에 대한 문서를 요청하세요

이미지 작업

코드베이스에서 이미지를 다루며 Claude의 이미지 분석 도움이 필요한 상황을 가정해 보겠습니다.

Step 1: 대화에 이미지 추가

다음 방법 중 하나를 사용할 수 있습니다:

Claude Code 창에 이미지를 드래그 앤 드롭
이미지를 복사한 후 CLI에 ctrl+v로 붙여넣기 (cmd+v는 사용하지 마세요)
Claude에게 이미지 경로를 제공. 예: "Analyze this image: /path/to/your/image.png"

Step 2: Claude에게 이미지 분석 요청

What does this image show?

Describe the UI elements in this screenshot

Are there any problematic elements in this diagram?

Step 3: 컨텍스트로 이미지 활용

Here's a screenshot of the error. What's causing it?

This is our current database schema. How should we modify it for the new feature?

Step 4: 시각적 콘텐츠에서 코드 제안 받기

Generate CSS to match this design mockup

What HTML structure would recreate this component?

팁:

텍스트 설명이 불분명하거나 번거로울 때 이미지를 사용하세요

더 나은 컨텍스트를 위해 오류 스크린샷, UI 디자인, 다이어그램을 포함하세요

대화에서 여러 이미지를 함께 사용할 수 있습니다

이미지 분석은 다이어그램, 스크린샷, 목업 등에서 작동합니다

Claude가 이미지를 참조할 때 (예: [Image #1]), Cmd+Click (Mac) 또는 Ctrl+Click (Windows/Linux)으로 링크를 클릭하면 기본 뷰어에서 이미지를 열 수 있습니다

파일 및 디렉토리 참조

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

Step 1: 단일 파일 참조

Explain the logic in @src/utils/auth.js

대화에 파일의 전체 내용이 포함됩니다.

Step 2: 디렉토리 참조

What's the structure of @src/components?

파일 정보가 포함된 디렉토리 목록을 제공합니다.

Step 3: MCP 리소스 참조

Show me the data from @github:repos/owner/repo/issues

@server:resource 형식을 사용하여 연결된 MCP 서버에서 데이터를 가져옵니다. 자세한 내용은 MCP 리소스를 참조하세요.

팁:

파일 경로는 상대 경로 또는 절대 경로를 사용할 수 있습니다

@ 파일 참조는 해당 파일의 디렉토리와 상위 디렉토리에 있는 CLAUDE.md를 컨텍스트에 추가합니다

디렉토리 참조는 내용이 아닌 파일 목록을 보여줍니다

단일 메시지에서 여러 파일을 참조할 수 있습니다 (예: "@file1.js and @file2.js")

확장 사고 (thinking mode) 사용

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

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

thinking mode 설정

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

범위	설정 방법	세부사항
노력 수준	`/model`에서 조정하거나 `CLAUDE_CODE_EFFORT_LEVEL` 설정	Opus 4.6 및 Sonnet 4.6의 사고 깊이를 제어: low, medium, high. 노력 수준 조정 참조
`ultrathink` 키워드	프롬프트 어디에나 "ultrathink"를 포함	Opus 4.6 및 Sonnet 4.6에서 해당 턴의 노력을 high로 설정. 노력 설정을 영구적으로 변경하지 않고 깊은 추론이 필요한 일회성 작업에 유용
토글 단축키	`Option+T` (macOS) 또는 `Alt+T` (Windows/Linux) 누르기	현재 세션의 사고를 켜기/끄기 (모든 모델). Option 키 단축키를 활성화하려면 터미널 설정이 필요할 수 있음
전역 기본값	`/config`에서 thinking mode 토글	모든 프로젝트에 대한 기본값 설정 (모든 모델). `~/.claude/settings.json`에 `alwaysThinkingEnabled`로 저장됨
토큰 예산 제한	`MAX_THINKING_TOKENS` 환경 변수 설정	사고 예산을 특정 토큰 수로 제한 (Opus 4.6에서는 0으로 설정하지 않는 한 무시됨). 예: `export MAX_THINKING_TOKENS=10000`

Claude의 사고 과정을 보려면 Ctrl+O를 눌러 verbose 모드를 전환하면 내부 추론이 회색 이탤릭 텍스트로 표시됩니다.

확장 사고의 작동 방식

주의: Claude 4 모델이 요약된 사고를 표시하더라도 사용된 모든 사고 토큰에 대해 비용이 청구됩니다

이전 대화 재개

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

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

활성 세션 내에서 /resume을 사용하여 다른 대화로 전환할 수 있습니다.

세션은 프로젝트 디렉토리별로 저장됩니다. /resume 선택기는 worktree를 포함하여 동일한 Git 리포지토리의 세션을 표시합니다.

세션 이름 지정

나중에 찾기 쉽도록 세션에 설명적인 이름을 지정하세요. 여러 작업이나 기능을 동시에 진행할 때 권장되는 방법입니다.

Step 1: 현재 세션에 이름 지정

세션 중에 /rename을 사용하여 기억하기 쉬운 이름을 지정하세요:

/rename auth-refactor

선택기에서 모든 세션의 이름을 변경할 수도 있습니다: /resume을 실행하고 세션으로 이동한 후 R을 누르세요.

Step 2: 나중에 이름으로 재개

커맨드 라인에서:

claude --resume auth-refactor

또는 활성 세션 내에서:

/resume auth-refactor

세션 선택기 사용

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

선택기의 키보드 단축키:

단축키	동작
`↑` / `↓`	세션 간 이동
`→` / `←`	그룹화된 세션 펼치기 또는 접기
`Enter`	강조된 세션 선택 및 재개
`P`	세션 내용 미리보기
`R`	강조된 세션 이름 변경
`/`	세션 필터링을 위한 검색
`A`	현재 디렉토리와 모든 프로젝트 간 전환
`B`	현재 Git 브랜치의 세션만 필터링
`Esc`	선택기 또는 검색 모드 종료

세션 정리:

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

세션 이름 또는 초기 프롬프트
마지막 활동 이후 경과 시간
메시지 수
Git 브랜치 (해당하는 경우)

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

팁:

세션 이름을 일찍 지정하세요: 특정 작업을 시작할 때 /rename을 사용하세요. 나중에 "explain this function"보다 "payment-integration"을 찾는 것이 훨씬 쉽습니다

현재 디렉토리에서 가장 최근 대화에 빠르게 접근하려면 --continue를 사용하세요

어떤 세션이 필요한지 알고 있다면 --resume session-name을 사용하세요

탐색하고 선택해야 한다면 --resume (이름 없이)을 사용하세요

스크립트에서는 claude --continue --print "prompt"를 사용하여 비대화형 모드로 재개하세요

선택기에서 P를 눌러 재개하기 전에 세션을 미리 확인하세요

재개된 대화는 원본과 동일한 모델 및 설정으로 시작됩니다

작동 방식:

대화 저장: 모든 대화는 전체 메시지 이력과 함께 로컬에 자동 저장됩니다

메시지 역직렬화: 재개 시 컨텍스트를 유지하기 위해 전체 메시지 이력이 복원됩니다

도구 상태: 이전 대화의 도구 사용 및 결과가 보존됩니다

컨텍스트 복원: 이전의 모든 컨텍스트가 그대로 유지된 상태로 대화가 재개됩니다

Git Worktree를 사용한 병렬 Claude Code 세션 실행

# Start Claude in a worktree named "feature-auth"
# Creates .claude/worktrees/feature-auth/ with a new branch
claude --worktree feature-auth

# Start another session in a separate worktree
claude --worktree bugfix-123

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

# Auto-generates a name like "bright-running-fox"
claude --worktree

Worktree는 <repo>/.claude/worktrees/<name>에 생성되며 기본 리모트 브랜치에서 분기됩니다. worktree 브랜치의 이름은 worktree-<name>입니다.

세션 중에 Claude에게 "work in a worktree" 또는 "start a worktree"라고 요청할 수도 있으며, Claude가 자동으로 생성합니다.

서브에이전트 worktree

Worktree 정리

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

변경 사항 없음: worktree와 해당 브랜치가 자동으로 제거됩니다
변경 사항 또는 커밋 존재: Claude가 worktree를 유지할지 제거할지 확인합니다. 유지하면 나중에 돌아올 수 있도록 디렉토리와 브랜치가 보존됩니다. 제거하면 worktree 디렉토리와 브랜치가 삭제되며, 커밋되지 않은 모든 변경 사항과 커밋이 폐기됩니다

Claude 세션 외부에서 worktree를 정리하려면 수동 worktree 관리를 사용하세요.

팁: .claude/worktrees/를 .gitignore에 추가하면 worktree 내용이 메인 리포지토리에서 추적되지 않는 파일로 나타나는 것을 방지할 수 있습니다.

수동 worktree 관리

# Create a worktree with a new branch
git worktree add ../project-feature-a -b feature-a

# Create a worktree with an existing branch
git worktree add ../project-bugfix bugfix-123

# Start Claude in the worktree
cd ../project-feature-a && claude

# Clean up when done
git worktree list
git worktree remove ../project-feature-a

자세한 내용은 공식 Git worktree 문서를 참조하세요.

팁: 프로젝트의 설정 과정에 따라 각 새 worktree에서 개발 환경을 초기화하는 것을 잊지 마세요. 스택에 따라 의존성 설치 (npm install, yarn), 가상 환경 설정, 또는 프로젝트의 표준 설정 과정이 포함될 수 있습니다.

Git 이외의 버전 관리

병렬 세션의 공유 작업과 메시징을 자동으로 조율하려면 에이전트 팀을 참조하세요.

Claude가 주의를 기울여야 할 때 알림 받기

Step 1: 훅 메뉴 열기

/hooks를 입력하고 이벤트 목록에서 Notification을 선택하세요.

Step 2: 매처 설정

매처	발동 시점
`permission_prompt`	Claude가 도구 사용 승인을 필요로 할 때
`idle_prompt`	Claude가 완료되고 다음 프롬프트를 기다릴 때
`auth_success`	인증이 완료될 때
`elicitation_dialog`	Claude가 질문을 하고 있을 때

Step 3: 알림 명령어 추가

+ Add new hook…을 선택하고 운영체제에 맞는 명령어를 입력하세요:

macOS

osascript를 사용하여 AppleScript를 통해 네이티브 macOS 알림을 트리거합니다:

osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'

Linux

대부분의 Linux 데스크톱에 알림 데몬과 함께 사전 설치된 notify-send를 사용합니다:

notify-send 'Claude Code' 'Claude Code needs your attention'

Windows (PowerShell)

PowerShell을 사용하여 .NET의 Windows Forms를 통해 네이티브 메시지 박스를 표시합니다:

powershell.exe -Command "[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')"

Step 4: 사용자 설정에 저장

User settings를 선택하면 모든 프로젝트에 알림이 적용됩니다.

JSON 설정 예시가 포함된 전체 가이드는 훅으로 워크플로우 자동화를 참조하세요. 전체 이벤트 스키마와 알림 유형은 Notification 레퍼런스를 참조하세요.

Claude를 유닉스 스타일 유틸리티로 사용

검증 프로세스에 Claude 추가

Claude Code를 린터 또는 코드 리뷰어로 사용하고 싶은 상황을 가정해 보겠습니다.

빌드 스크립트에 Claude 추가:

// 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.'"
    }
}

팁:

CI/CD 파이프라인에서 자동 코드 리뷰에 Claude를 사용하세요

프로젝트와 관련된 특정 이슈를 확인하도록 프롬프트를 커스터마이즈하세요

다양한 유형의 검증을 위해 여러 스크립트를 만드는 것을 고려하세요

파이프 입출력

데이터를 Claude에 파이프로 보내고 구조화된 형식으로 결과를 받고 싶은 상황을 가정해 보겠습니다.

Claude를 통해 데이터 파이프:

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

팁:

파이프를 사용하여 Claude를 기존 셸 스크립트에 통합하세요

다른 Unix 도구와 결합하여 강력한 워크플로우를 구성하세요

구조화된 출력을 위해 --output-format 사용을 고려하세요

출력 형식 제어

특히 Claude Code를 스크립트나 다른 도구에 통합할 때 Claude의 출력을 특정 형식으로 받아야 하는 상황을 가정해 보겠습니다.

Step 1: 텍스트 형식 사용 (기본값)

cat data.txt | claude -p 'summarize this data' --output-format text > summary.txt

Claude의 일반 텍스트 응답만 출력합니다 (기본 동작).

Step 2: JSON 형식 사용

cat code.py | claude -p 'analyze this code for bugs' --output-format json > analysis.json

비용 및 소요 시간을 포함한 메타데이터와 함께 메시지의 JSON 배열을 출력합니다.

Step 3: 스트리밍 JSON 형식 사용

cat log.txt | claude -p 'parse this log file for errors' --output-format stream-json

팁:

Claude의 응답만 필요한 간단한 통합에는 --output-format text를 사용하세요

전체 대화 로그가 필요하면 --output-format json을 사용하세요

각 대화 턴의 실시간 출력에는 --output-format stream-json을 사용하세요

Claude의 기능에 대해 질문하기

Claude는 자체 문서에 내장 접근 권한이 있으며, 자신의 기능과 제한 사항에 대한 질문에 답할 수 있습니다.

질문 예시

can Claude Code create pull requests?

how does Claude Code handle permissions?

what skills are available?

how do I use MCP with Claude Code?

how do I configure Claude Code for Amazon Bedrock?

what are the limitations of Claude Code?

참고: Claude는 이러한 질문에 대해 문서 기반 답변을 제공합니다. 실행 가능한 예시와 실습 데모는 위의 특정 워크플로우 섹션을 참조하세요.

팁:

Claude는 사용 중인 버전에 관계없이 항상 최신 Claude Code 문서에 접근할 수 있습니다

구체적인 질문을 하면 자세한 답변을 얻을 수 있습니다

Claude는 MCP 통합, 엔터프라이즈 구성, 고급 워크플로우와 같은 복잡한 기능을 설명할 수 있습니다

다음 단계

모범 사례 - Claude Code에서 최대한 활용하기 위한 패턴
Claude Code 작동 방식 - 에이전트 루프 및 컨텍스트 관리 이해하기
Claude Code 확장하기 - skill, hook, MCP, subagent 및 플러그인 추가하기
참조 구현 - 개발 컨테이너 참조 구현 복제하기

8. 일반적인 워크플로우

일반적인 워크플로우

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

코드베이스 빠르게 파악하기

Step 1: 프로젝트 루트 디렉토리로 이동

Step 2: Claude Code 시작

Step 3: 높은 수준의 개요 요청

Step 4: 특정 컴포넌트 심층 탐색

관련 코드 찾기

Step 1: Claude에게 관련 파일 찾기 요청

Step 2: 컴포넌트 간 상호작용 파악

Step 3: 실행 흐름 이해

효율적인 버그 수정

Step 1: Claude에게 오류 공유

Step 2: 수정 방법 제안 요청

Step 3: 수정 적용

코드 리팩토링

Step 1: 리팩토링 대상 레거시 코드 식별

Step 2: 리팩토링 방안 제안 받기

Step 3: 안전하게 변경 적용

Step 4: 리팩토링 검증

전문 서브에이전트 활용

Step 1: 사용 가능한 서브에이전트 확인

Step 2: 자동으로 서브에이전트 사용

Step 3: 특정 서브에이전트 명시적으로 요청

Step 4: 워크플로우에 맞는 커스텀 서브에이전트 생성

안전한 코드 분석을 위한 Plan Mode 사용

Plan Mode를 사용해야 하는 경우

Plan Mode 사용 방법

세션 중 Plan Mode 전환

새 세션을 Plan Mode로 시작

Plan Mode에서 "headless" 쿼리 실행

예시: 복잡한 리팩토링 계획 수립

Plan Mode를 기본값으로 설정

테스트 작업

Step 1: 테스트되지 않은 코드 식별

Step 2: 테스트 스캐폴딩 생성

Step 3: 의미 있는 테스트 케이스 추가

Step 4: 테스트 실행 및 검증

Pull Request 생성

Step 1: 변경 사항 요약

Step 2: Pull Request 생성

Step 3: 검토 및 보완

문서화 처리

Step 1: 문서화되지 않은 코드 식별

Step 2: 문서 생성

Step 3: 검토 및 개선

Step 4: 문서 검증

이미지 작업

Step 1: 대화에 이미지 추가

Step 2: Claude에게 이미지 분석 요청

Step 3: 컨텍스트로 이미지 활용

Step 4: 시각적 콘텐츠에서 코드 제안 받기

파일 및 디렉토리 참조

Step 1: 단일 파일 참조

Step 2: 디렉토리 참조

Step 3: MCP 리소스 참조

확장 사고 (thinking mode) 사용

thinking mode 설정

확장 사고의 작동 방식

이전 대화 재개

세션 이름 지정

Step 1: 현재 세션에 이름 지정

Step 2: 나중에 이름으로 재개

세션 선택기 사용

Git Worktree를 사용한 병렬 Claude Code 세션 실행

서브에이전트 worktree

Worktree 정리

수동 worktree 관리

Git 이외의 버전 관리

Claude가 주의를 기울여야 할 때 알림 받기

Step 1: 훅 메뉴 열기

Step 2: 매처 설정

Step 3: 알림 명령어 추가

Step 4: 사용자 설정에 저장

Claude를 유닉스 스타일 유틸리티로 사용

검증 프로세스에 Claude 추가

파이프 입출력

출력 형식 제어

Step 1: 텍스트 형식 사용 (기본값)