메인 콘텐츠로 건너뛰기
이 문서의 각 작업에는 명확한 지침, 예제 명령, 그리고 Claude Code를 최대한 활용하는 데 도움이 되는 모범 사례가 포함되어 있습니다.

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

빠른 코드베이스 개요 얻기

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

프로젝트 루트 디렉토리로 이동

cd /path/to/project 
2

Claude Code 시작

claude 
3

높은 수준의 개요 요청

> give me an overview of this codebase 
4

특정 구성 요소에 대해 더 깊이 있게 살펴보기

> explain the main architecture patterns used here 
> what are the key data models?
> how is authentication handled?
팁:
  • 광범위한 질문으로 시작한 다음 특정 영역으로 좁혀나가세요
  • 프로젝트에서 사용되는 코딩 규칙과 패턴에 대해 물어보세요
  • 프로젝트별 용어의 용어집을 요청하세요

관련 코드 찾기

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

Claude에게 관련 파일 찾기 요청

> find the files that handle user authentication 
2

구성 요소가 상호 작용하는 방식에 대한 컨텍스트 얻기

> how do these authentication files work together? 
3

실행 흐름 이해하기

> trace the login process from front-end to database 
팁:
  • 찾고 있는 것에 대해 구체적으로 설명하세요
  • 프로젝트의 도메인 언어를 사용하세요

버그 효율적으로 수정하기

오류 메시지가 발생했고 그 원인을 찾아 수정해야 한다고 가정해봅시다.
1

Claude와 오류 공유

> I'm seeing an error when I run npm test 
2

수정 권장 사항 요청

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

수정 사항 적용

> update user.ts to add the null check you suggested 
팁:
  • Claude에게 문제를 재현하는 명령과 스택 추적을 알려주세요
  • 오류를 재현하는 단계를 언급하세요
  • 오류가 간헐적인지 일관적인지 Claude에게 알려주세요

코드 리팩토링

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

리팩토링할 레거시 코드 식별

> find deprecated API usage in our codebase 
2

리팩토링 권장 사항 얻기

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

변경 사항을 안전하게 적용

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

리팩토링 확인

> run tests for the refactored code 
팁:
  • Claude에게 최신 접근 방식의 이점을 설명해달라고 요청하세요
  • 필요할 때 변경 사항이 이전 버전과의 호환성을 유지하도록 요청하세요
  • 작고 테스트 가능한 증분으로 리팩토링을 수행하세요

특화된 서브에이전트 사용

특정 작업을 더 효과적으로 처리하기 위해 특화된 AI 서브에이전트를 사용하고 싶다고 가정해봅시다.
1

사용 가능한 서브에이전트 보기

> /agents
이것은 모든 사용 가능한 서브에이전트를 표시하고 새로운 것을 만들 수 있게 해줍니다.
2

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

Claude Code는 자동으로 특화된 서브에이전트에 적절한 작업을 위임합니다:
> review my recent code changes for security issues
> run all tests and fix any failures
3

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

> use the code-reviewer subagent to check the auth module
> have the debugger subagent investigate why users can't log in
4

워크플로우를 위한 사용자 정의 서브에이전트 만들기

> /agents
그런 다음 “Create New subagent”를 선택하고 프롬프트를 따라 다음을 정의하세요:
  • 서브에이전트 유형 (예: api-designer, performance-optimizer)
  • 사용 시기
  • 액세스할 수 있는 도구
  • 특화된 시스템 프롬프트
팁:
  • 팀 공유를 위해 .claude/agents/에 프로젝트별 서브에이전트를 만드세요
  • 자동 위임을 활성화하기 위해 설명적인 description 필드를 사용하세요
  • 각 서브에이전트가 실제로 필요한 도구로만 도구 액세스를 제한하세요
  • 자세한 예제는 서브에이전트 문서를 확인하세요

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

Plan Mode는 Claude에게 읽기 전용 작업으로 코드베이스를 분석하여 계획을 세우도록 지시하며, 코드베이스 탐색, 복잡한 변경 계획 또는 코드를 안전하게 검토하는 데 완벽합니다.

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에서 “헤드리스” 쿼리 실행 -p를 사용하여 Plan Mode에서 직접 쿼리를 실행할 수도 있습니다 (즉, “헤드리스 모드”):
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?

Plan Mode를 기본값으로 구성

// .claude/settings.json
{
  "permissions": {
    "defaultMode": "plan"
  }
}
더 많은 구성 옵션은 설정 문서를 참조하세요.

테스트 작업

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

테스트되지 않은 코드 식별

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

테스트 스캐폴딩 생성

> add tests for the notification service 
3

의미 있는 테스트 케이스 추가

> add test cases for edge conditions in the notification service 
4

테스트 실행 및 확인

> run the new tests and fix any failures 
팁:
  • 엣지 케이스와 오류 조건을 다루는 테스트를 요청하세요
  • 적절할 때 단위 테스트와 통합 테스트를 모두 요청하세요
  • Claude에게 테스트 전략을 설명해달라고 하세요

풀 리퀘스트 만들기

변경 사항에 대해 잘 문서화된 풀 리퀘스트를 만들어야 한다고 가정해봅시다.
1

변경 사항 요약

> summarize the changes I've made to the authentication module 
2

Claude로 PR 생성

> create a pr 
3

검토 및 개선

> enhance the PR description with more context about the security improvements 
4

테스트 세부 정보 추가

> add information about how these changes were tested 
팁:
  • Claude에게 직접 PR을 만들도록 요청하세요
  • 제출하기 전에 Claude가 생성한 PR을 검토하세요
  • Claude에게 잠재적 위험이나 고려 사항을 강조하도록 요청하세요

문서 처리

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

문서화되지 않은 코드 식별

> find functions without proper JSDoc comments in the auth module 
2

문서 생성

> add JSDoc comments to the undocumented functions in auth.js 
3

검토 및 개선

> improve the generated documentation with more context and examples 
4

문서 확인

> check if the documentation follows our project standards 
팁:
  • 원하는 문서 스타일을 지정하세요 (JSDoc, docstrings 등)
  • 문서에 예제를 포함하도록 요청하세요
  • 공개 API, 인터페이스 및 복잡한 로직에 대한 문서를 요청하세요

이미지 작업

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

대화에 이미지 추가

다음 방법 중 하나를 사용할 수 있습니다:
  1. Claude Code 창으로 이미지를 드래그 앤 드롭
  2. 이미지를 복사하고 CLI에 ctrl+v로 붙여넣기 (cmd+v 사용 금지)
  3. Claude에 이미지 경로 제공. 예: “Analyze this image: /path/to/your/image.png”
2

Claude에게 이미지 분석 요청

> What does this image show?
> Describe the UI elements in this screenshot
> Are there any problematic elements in this diagram?
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?
4

시각적 콘텐츠에서 코드 제안 얻기

> Generate CSS to match this design mockup
> What HTML structure would recreate this component?
팁:
  • 텍스트 설명이 불명확하거나 번거로울 때 이미지를 사용하세요
  • 더 나은 컨텍스트를 위해 오류, UI 디자인 또는 다이어그램의 스크린샷을 포함하세요
  • 대화에서 여러 이미지로 작업할 수 있습니다
  • 이미지 분석은 다이어그램, 스크린샷, 목업 등과 함께 작동합니다

파일 및 디렉토리 참조

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

단일 파일 참조

> Explain the logic in @src/utils/auth.js
이것은 대화에 파일의 전체 내용을 포함합니다.
2

디렉토리 참조

> What's the structure of @src/components?
이것은 파일 정보가 포함된 디렉토리 목록을 제공합니다.
3

MCP 리소스 참조

> Show me the data from @github:repos/owner/repo/issues
이것은 @server:resource 형식을 사용하여 연결된 MCP 서버에서 데이터를 가져옵니다. 자세한 내용은 MCP 리소스를 참조하세요.
팁:
  • 파일 경로는 상대 경로 또는 절대 경로일 수 있습니다
  • @ 파일 참조는 파일의 디렉토리 및 상위 디렉토리에 CLAUDE.md를 컨텍스트에 추가합니다
  • 디렉토리 참조는 내용이 아닌 파일 목록을 표시합니다
  • 단일 메시지에서 여러 파일을 참조할 수 있습니다 (예: “@file1.js and @file2.js”)

확장된 사고 사용

복잡한 아키텍처 결정, 어려운 버그 또는 깊은 추론이 필요한 다단계 구현 계획에 작업하고 있다고 가정해봅시다.
확장된 사고는 Claude Code에서 기본적으로 비활성화되어 있습니다. Tab을 사용하여 Thinking을 켜거나 “think” 또는 “think hard”와 같은 프롬프트를 사용하여 필요에 따라 활성화할 수 있습니다. 또한 설정에서 MAX_THINKING_TOKENS 환경 변수를 설정하여 영구적으로 활성화할 수 있습니다.
1

컨텍스트를 제공하고 Claude에게 생각하도록 요청

> I need to implement a new authentication system using OAuth2 for our API. Think deeply about the best approach for implementing this in our codebase.
Claude는 코드베이스에서 관련 정보를 수집하고 확장된 사고를 사용하며, 이는 인터페이스에서 볼 수 있습니다.
2

후속 프롬프트로 사고 개선

> think about potential security vulnerabilities in this approach 
> think hard about edge cases we should handle 
확장된 사고에서 최대 가치를 얻기 위한 팁:확장된 사고는 다음과 같은 복잡한 작업에 가장 유용합니다:
  • 복잡한 아키텍처 변경 계획
  • 복잡한 문제 디버깅
  • 새로운 기능에 대한 구현 계획 만들기
  • 복잡한 코드베이스 이해
  • 다양한 접근 방식 간의 트레이드오프 평가
세션 중에 Tab을 사용하여 Thinking을 켜고 끌 수 있습니다.사고 결과를 프롬프트하는 방식에 따라 다양한 수준의 사고 깊이가 발생합니다:
  • “think”는 기본 확장된 사고를 트리거합니다
  • “keep hard”, “think more”, “think a lot” 또는 “think longer”와 같은 강화 구문은 더 깊은 사고를 트리거합니다
더 많은 확장된 사고 프롬프팅 팁은 확장된 사고 팁을 참조하세요.
Claude는 응답 위에 기울임꼴 회색 텍스트로 사고 과정을 표시합니다.

이전 대화 재개

Claude Code로 작업 중이고 나중에 세션에서 중단한 부분부터 계속해야 한다고 가정해봅시다. Claude Code는 이전 대화를 재개하기 위한 두 가지 옵션을 제공합니다:
  • --continue는 가장 최근 대화를 자동으로 계속합니다
  • --resume은 대화 선택기를 표시합니다
1

가장 최근 대화 계속

claude --continue
이것은 프롬프트 없이 즉시 가장 최근 대화를 재개합니다.
2

비대화형 모드에서 계속

claude --continue --print "Continue with my task"
--continue와 함께 --print를 사용하여 가장 최근 대화를 비대화형 모드에서 재개하며, 스크립트나 자동화에 완벽합니다.
3

대화 선택기 표시

claude --resume
이것은 다음을 표시하는 깔끔한 목록 보기가 있는 대화형 대화 선택기를 표시합니다:
  • 세션 요약 (또는 초기 프롬프트)
  • 메타데이터: 경과 시간, 메시지 수 및 git 분기
화살표 키를 사용하여 탐색하고 Enter를 눌러 대화를 선택하세요. Esc를 눌러 종료하세요.
팁:
  • 대화 기록은 컴퓨터에 로컬로 저장됩니다
  • 가장 최근 대화에 빠르게 액세스하려면 --continue를 사용하세요
  • 특정 과거 대화를 선택해야 할 때 --resume을 사용하세요
  • 재개할 때 계속하기 전에 전체 대화 기록이 표시됩니다
  • 재개된 대화는 원본과 동일한 모델 및 구성으로 시작됩니다
작동 방식:
  1. 대화 저장소: 모든 대화는 전체 메시지 기록과 함께 로컬로 자동 저장됩니다
  2. 메시지 역직렬화: 재개할 때 전체 메시지 기록이 복원되어 컨텍스트를 유지합니다
  3. 도구 상태: 이전 대화의 도구 사용 및 결과가 보존됩니다
  4. 컨텍스트 복원: 대화는 모든 이전 컨텍스트와 함께 재개됩니다
예제:
# 가장 최근 대화 계속
claude --continue

# 특정 프롬프트로 가장 최근 대화 계속
claude --continue --print "Show me our progress"

# 대화 선택기 표시
claude --resume

# 비대화형 모드에서 가장 최근 대화 계속
claude --continue --print "Run the tests again"

Git worktrees를 사용하여 병렬 Claude Code 세션 실행

여러 작업을 동시에 수행해야 하며 Claude Code 인스턴스 간에 완전한 코드 격리가 필요하다고 가정해봅시다.
1

Git worktrees 이해

Git worktrees를 사용하면 동일한 저장소에서 여러 분기를 별도의 디렉토리로 체크아웃할 수 있습니다. 각 worktree는 동일한 Git 기록을 공유하면서 격리된 파일이 있는 자체 작업 디렉토리를 가집니다. 공식 Git worktree 문서에서 자세히 알아보세요.
2

새 worktree 만들기

# 새 분기로 새 worktree 만들기 
git worktree add ../project-feature-a -b feature-a

# 또는 기존 분기로 worktree 만들기
git worktree add ../project-bugfix bugfix-123
이것은 저장소의 별도 작업 복사본이 있는 새 디렉토리를 만듭니다.
3

각 worktree에서 Claude Code 실행

# worktree로 이동 
cd ../project-feature-a

# 이 격리된 환경에서 Claude Code 실행
claude
4

다른 worktree에서 Claude 실행

cd ../project-bugfix
claude
5

worktrees 관리

# 모든 worktrees 나열
git worktree list

# 완료되면 worktree 제거
git worktree remove ../project-feature-a
팁:
  • 각 worktree는 자체 독립적인 파일 상태를 가지므로 병렬 Claude Code 세션에 완벽합니다
  • 한 worktree에서 만든 변경 사항은 다른 worktree에 영향을 주지 않으므로 Claude 인스턴스가 서로 간섭하지 않습니다
  • 모든 worktrees는 동일한 Git 기록 및 원격 연결을 공유합니다
  • 장기 실행 작업의 경우 Claude가 한 worktree에서 작업하는 동안 다른 worktree에서 개발을 계속할 수 있습니다
  • 각 worktree가 어떤 작업을 위한 것인지 쉽게 식별할 수 있도록 설명적인 디렉토리 이름을 사용하세요
  • 프로젝트의 설정에 따라 각 새 worktree에서 개발 환경을 초기화해야 합니다. 스택에 따라 다음이 포함될 수 있습니다:
    • JavaScript 프로젝트: 종속성 설치 실행 (npm install, yarn)
    • Python 프로젝트: 가상 환경 설정 또는 패키지 관리자로 설치
    • 기타 언어: 프로젝트의 표준 설정 프로세스 따르기

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

검증 프로세스에 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 도구와 결합하여 강력한 워크플로우를 만드세요
  • 스크립트나 다른 도구에 Claude를 통합할 때 —output-format 사용을 고려하세요

출력 형식 제어

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

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

cat data.txt | claude -p 'summarize this data' --output-format text > summary.txt
이것은 Claude의 일반 텍스트 응답만 출력합니다 (기본 동작).
2

JSON 형식 사용

cat code.py | claude -p 'analyze this code for bugs' --output-format json > analysis.json
이것은 비용 및 기간을 포함한 메타데이터가 있는 메시지의 JSON 배열을 출력합니다.
3

스트리밍 JSON 형식 사용

cat log.txt | claude -p 'parse this log file for errors' --output-format stream-json
이것은 Claude가 요청을 처리할 때 실시간으로 JSON 객체의 시리즈를 출력합니다. 각 메시지는 유효한 JSON 객체이지만 연결되면 전체 출력은 유효한 JSON이 아닙니다.
팁:
  • 단순 통합에 --output-format text를 사용하여 Claude의 응답만 필요할 때
  • 전체 대화 로그가 필요할 때 --output-format json을 사용하세요
  • 각 대화 차례의 실시간 출력이 필요할 때 --output-format stream-json을 사용하세요

사용자 정의 슬래시 명령 만들기

Claude Code는 특정 프롬프트나 작업을 빠르게 실행하기 위해 만들 수 있는 사용자 정의 슬래시 명령을 지원합니다. 자세한 내용은 슬래시 명령 참조 페이지를 참조하세요.

프로젝트별 명령 만들기

모든 팀 멤버가 사용할 수 있는 프로젝트를 위해 재사용 가능한 슬래시 명령을 만들고 싶다고 가정해봅시다.
1

프로젝트에 명령 디렉토리 만들기

mkdir -p .claude/commands
2

각 명령에 대해 Markdown 파일 만들기

echo "Analyze the performance of this code and suggest three specific optimizations:" > .claude/commands/optimize.md 
3

Claude Code에서 사용자 정의 명령 사용

> /optimize 
팁:
  • 명령 이름은 파일 이름에서 파생됩니다 (예: optimize.md/optimize가 됨)
  • 명령을 하위 디렉토리에 구성할 수 있습니다 (예: .claude/commands/frontend/component.md는 설명에 “(project:frontend)“가 표시된 /component를 만듭니다)
  • 프로젝트 명령은 저장소를 복제하는 모든 사람이 사용할 수 있습니다
  • Markdown 파일 내용은 명령이 호출될 때 Claude에 전송되는 프롬프트가 됩니다

$ARGUMENTS로 명령 인수 추가

사용자의 추가 입력을 받을 수 있는 유연한 슬래시 명령을 만들고 싶다고 가정해봅시다.
1

$ARGUMENTS 자리 표시자가 있는 명령 파일 만들기

echo 'Find and fix issue #$ARGUMENTS. Follow these steps: 1.
Understand the issue described in the ticket 2. Locate the relevant code in
our codebase 3. Implement a solution that addresses the root cause 4. Add
appropriate tests 5. Prepare a concise PR description' >
.claude/commands/fix-issue.md 
2

문제 번호로 명령 사용

Claude 세션에서 인수와 함께 명령을 사용하세요.
> /fix-issue 123 
이것은 프롬프트에서 $ARGUMENTS를 “123”으로 바꿉니다.
팁:
  • $ARGUMENTS 자리 표시자는 명령 뒤의 모든 텍스트로 바뀝니다
  • 명령 템플릿의 어디든지 $ARGUMENTS를 배치할 수 있습니다
  • 기타 유용한 응용 프로그램: 특정 함수에 대한 테스트 케이스 생성, 구성 요소에 대한 문서 작성, 특정 파일의 코드 검토 또는 지정된 언어로 콘텐츠 번역

개인 슬래시 명령 만들기

모든 프로젝트에서 작동하는 개인 슬래시 명령을 만들고 싶다고 가정해봅시다.
1

홈 폴더에 명령 디렉토리 만들기

mkdir -p ~/.claude/commands 
2

각 명령에 대해 Markdown 파일 만들기

echo "Review this code for security vulnerabilities, focusing on:" >
~/.claude/commands/security-review.md 
3

개인 사용자 정의 명령 사용

> /security-review 
팁:
  • 개인 명령은 /help로 나열할 때 설명에 “(user)“가 표시됩니다
  • 개인 명령은 당신만 사용할 수 있으며 팀과 공유되지 않습니다
  • 개인 명령은 모든 프로젝트에서 작동합니다
  • 다양한 코드베이스에서 일관된 워크플로우를 위해 이를 사용할 수 있습니다

Claude의 기능에 대해 물어보기

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

예제 질문

> can Claude Code create pull requests?
> how does Claude Code handle permissions?
> what slash commands 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 참조 구현

개발 컨테이너 참조 구현을 복제하세요.