Claude Code 튜토리얼

이 가이드는 Claude Code의 일반적인 워크플로우에 대한 단계별 튜토리얼을 제공합니다. 각 튜토리얼에는 Claude Code를 최대한 활용할 수 있도록 명확한 지침, 예제 명령어 및 모범 사례가 포함되어 있습니다.

​

목차

• 새로운 코드베이스 이해하기
• 효율적으로 버그 수정하기
• 코드 리팩토링하기
• 테스트 작업하기
• 풀 리퀘스트 생성하기
• 문서 처리하기
• 이미지 작업하기
• 확장된 사고 사용하기
• 프로젝트 메모리 설정하기
• Model Context Protocol (MCP) 설정하기
• 유닉스 스타일 유틸리티로 Claude 사용하기
• 사용자 정의 슬래시 명령어 만들기
• Git worktrees로 병렬 Claude Code 세션 실행하기

​

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

​

코드베이스 빠른 개요 얻기

사용 시기: 새 프로젝트에 참여했고 그 구조를 빠르게 이해해야 할 때.

cd /path/to/project

claude

> give me an overview of this codebase

> explain the main architecture patterns used here

> what are the key data models?

> how is authentication handled?

팁:

• 넓은 범위의 질문으로 시작한 다음 특정 영역으로 좁혀가기
• 프로젝트에서 사용된 코딩 규칙과 패턴에 대해 문의하기
• 프로젝트 특정 용어의 용어집 요청하기

​

관련 코드 찾기

사용 시기: 특정 기능이나 기능과 관련된 코드를 찾아야 할 때.

> find the files that handle user authentication

> how do these authentication files work together?

> trace the login process from front-end to database

팁:

• 찾고자 하는 것에 대해 구체적으로 명시하기
• 프로젝트의 도메인 언어 사용하기

​

효율적으로 버그 수정하기

​

오류 메시지 진단하기

사용 시기: 오류 메시지가 발생했고 그 원인을 찾아 수정해야 할 때.

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

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

> update user.ts to add the null check you suggested

팁:

• Claude에게 오류를 재현하는 명령어와 스택 트레이스를 알려주기
• 오류를 재현하는 단계 언급하기
• 오류가 간헐적인지 일관적인지 Claude에게 알려주기

​

코드 리팩토링하기

​

레거시 코드 현대화하기

사용 시기: 오래된 코드를 현대적인 패턴과 관행을 사용하도록 업데이트해야 할 때.

> find deprecated API usage in our codebase

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

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

> run tests for the refactored code

팁:

• Claude에게 현대적 접근 방식의 이점을 설명해달라고 요청하기
• 필요한 경우 이전 버전과의 호환성을 유지하도록 요청하기
• 리팩토링을 작고 테스트 가능한 단위로 수행하기

​

테스트 작업하기

​

테스트 커버리지 추가하기

사용 시기: 테스트되지 않은 코드에 대한 테스트를 추가해야 할 때.

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

> add tests for the notification service

> add test cases for edge conditions in the notification service

> run the new tests and fix any failures

팁:

• 엣지 케이스와 오류 조건을 다루는 테스트 요청하기
• 적절한 경우 단위 테스트와 통합 테스트 모두 요청하기
• Claude에게 테스트 전략 설명 요청하기

​

풀 리퀘스트 생성하기

​

포괄적인 PR 생성하기

사용 시기: 변경사항에 대한 잘 문서화된 풀 리퀘스트를 생성해야 할 때.

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

> create a pr

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

> add information about how these changes were tested

팁:

• Claude에게 직접 PR 생성을 요청하기
• 제출하기 전에 Claude가 생성한 PR 검토하기
• Claude에게 잠재적 위험이나 고려사항 강조 요청하기

​

문서 처리하기

​

코드 문서 생성하기

사용 시기: 코드에 대한 문서를 추가하거나 업데이트해야 할 때.

> find functions without proper JSDoc comments in the auth module

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

> improve the generated documentation with more context and examples

> check if the documentation follows our project standards

팁:

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

​

이미지 작업하기

​

이미지와 스크린샷 분석하기

사용 시기: 코드베이스에서 이미지 작업을 하거나 이미지 내용 분석에 Claude의 도움이 필요할 때.

# 1. Claude Code 창에 이미지를 드래그 앤 드롭
# 2. 이미지를 복사하여 ctrl+v로 CLI에 붙여넣기
# 3. 이미지 경로 제공 
claude "Analyze this image: /path/to/your/image.png"

> What does this image show?
> Describe the UI elements in this screenshot
> Are there any problematic elements in this diagram?

> 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?

> Generate CSS to match this design mockup
> What HTML structure would recreate this component?

팁:

• 텍스트 설명이 불명확하거나 번거로울 때 이미지 사용하기
• 오류, UI 디자인 또는 다이어그램의 스크린샷 포함하기
• 대화에서 여러 이미지로 작업할 수 있음
• 이미지 분석은 다이어그램, 스크린샷, 목업 등에서 작동함

​

확장된 사고 사용하기

​

복잡한 작업을 위해 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.

> think about potential security vulnerabilities in this approach
> think harder about edge cases we should handle

확장된 사고를 최대한 활용하기 위한 팁:

확장된 사고는 다음과 같은 복잡한 작업에 가장 유용합니다:

• 복잡한 아키텍처 변경 계획하기
• 복잡한 문제 디버깅하기
• 새로운 기능에 대한 구현 계획 만들기
• 복잡한 코드베이스 이해하기
• 다양한 접근 방식 간의 트레이드오프 평가하기

사고를 요청하는 방식에 따라 다양한 수준의 사고 깊이가 발생합니다:

• “think”는 기본적인 확장된 사고를 트리거합니다
• “think more”, “think a lot”, “think harder”, “think longer”와 같은 강화 구문은 더 깊은 사고를 트리거합니다

더 많은 확장된 사고 프롬프팅 팁은 확장된 사고 팁을 참조하세요.

​

프로젝트 메모리 설정하기

​

효과적인 CLAUDE.md 파일 만들기

사용 시기: 중요한 프로젝트 정보, 규칙 및 자주 사용하는 명령어를 저장하기 위해 CLAUDE.md 파일을 설정하고 싶을 때.

> /init

팁:

• 자주 사용하는 명령어(빌드, 테스트, 린트)를 포함하여 반복적인 검색 피하기
• 코드 스타일 선호도와 명명 규칙 문서화하기
• 프로젝트에 특화된 중요한 아키텍처 패턴 추가하기
• CLAUDE.md 파일을 다음 위치 중 어디에나 추가할 수 있습니다:
  • Claude를 실행하는 폴더: 해당 폴더에서 시작하는 대화에 자동으로 추가됨
  • 하위 디렉토리: Claude가 필요할 때 이를 가져옴
  • ~/.claude/CLAUDE.md: 소스 제어에 체크인하고 싶지 않은 사용자별 선호도

​

Model Context Protocol (MCP) 설정하기

Model Context Protocol (MCP)은 LLM이 외부 도구와 데이터 소스에 접근할 수 있게 해주는 오픈 프로토콜입니다. 자세한 내용은 MCP 문서를 참조하세요.

​

MCP 서버 구성하기

사용 시기: Model Context Protocol을 사용하여 특수 도구와 외부 서버에 연결하여 Claude의 기능을 향상시키고 싶을 때.

# 기본 구문
claude mcp add <name> <command> [args...]

# 예시: 로컬 서버 추가하기
claude mcp add my-server -e API_KEY=123 -- /path/to/server arg1 arg2

# 기본 구문
claude mcp add --transport sse <name> <url>

# 예시: SSE 서버 추가하기
claude mcp add --transport sse sse-server https://example.com/sse-endpoint

# 구성된 모든 서버 나열하기
claude mcp list

# 특정 서버의 세부정보 가져오기
claude mcp get my-server

# 서버 제거하기
claude mcp remove my-server

팁:

• -s 또는 --scope 플래그를 사용하여 구성이 저장되는 위치 지정:
  • local (기본값): 현재 프로젝트에서 사용자에게만 사용 가능 (이전 버전에서는 project라고 불림)
  • project: .mcp.json 파일을 통해 프로젝트의 모든 사람과 공유
  • user: 모든 프로젝트에서 사용자에게 사용 가능 (이전 버전에서는 global이라고 불림)
• -e 또는 --env 플래그로 환경 변수 설정 (예: -e KEY=value)
• MCP_TIMEOUT 환경 변수를 사용하여 MCP 서버 시작 타임아웃 구성 (예: MCP_TIMEOUT=10000 claude는 10초 타임아웃 설정)
• Claude Code 내에서 /mcp 명령어를 사용하여 언제든지 MCP 서버 상태 확인
• MCP는 Claude Code(클라이언트)가 여러 특수 서버에 연결할 수 있는 클라이언트-서버 아키텍처를 따름

​

MCP 서버 스코프 이해하기

사용 시기: 다양한 MCP 스코프가 어떻게 작동하는지 이해하고 팀과 서버를 공유하고 싶을 때.

# 로컬 스코프 서버 추가하기 (기본값)
claude mcp add my-private-server /path/to/server

# 명시적으로 로컬 스코프 지정하기
claude mcp add my-private-server -s local /path/to/server

# 프로젝트 스코프 서버 추가하기
claude mcp add shared-server -s project /path/to/server

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

# 사용자 서버 추가하기
claude mcp add my-user-server -s user /path/to/server

팁:

• 동일한 이름의 로컬 스코프 서버가 프로젝트 스코프 및 사용자 스코프 서버보다 우선합니다
• 동일한 이름의 프로젝트 스코프 서버(.mcp.json에 있는)가 사용자 스코프 서버보다 우선합니다
• Claude Code는 보안을 위해 .mcp.json의 프로젝트 스코프 서버를 사용하기 전에 승인을 요청합니다
• .mcp.json 파일은 팀과 MCP 서버를 공유하기 위해 버전 관리에 체크인하도록 되어 있습니다
• 프로젝트 스코프 서버를 사용하면 팀의 모든 구성원이 동일한 MCP 도구에 쉽게 접근할 수 있습니다
• 활성화 또는 비활성화된 프로젝트 스코프 서버에 대한 선택을 재설정해야 하는 경우 claude mcp reset-project-choices 명령어를 사용하세요

​

Postgres MCP 서버에 연결하기

사용 시기: Claude에게 쿼리와 스키마 검사를 위한 PostgreSQL 데이터베이스에 대한 읽기 전용 접근 권한을 부여하고 싶을 때.

claude mcp add postgres-server /path/to/postgres-mcp-server --connection-string "postgresql://user:pass@localhost:5432/mydb"

# Claude 세션에서 데이터베이스에 대해 질문할 수 있습니다

> describe the schema of our users table
> what are the most recent orders in the system?
> show me the relationship between customers and invoices

팁:

• Postgres MCP 서버는 안전을 위해 읽기 전용 접근을 제공합니다
• Claude는 데이터베이스 구조를 탐색하고 분석 쿼리를 실행하는 데 도움을 줄 수 있습니다
• 이를 사용하여 낯선 프로젝트의 데이터베이스 스키마를 빠르게 이해할 수 있습니다
• 연결 문자열이 최소한의 필요한 권한을 가진 적절한 자격 증명을 사용하는지 확인하세요

​

JSON 구성에서 MCP 서버 추가하기

사용 시기: Claude Code에 추가하고 싶은 단일 MCP 서버에 대한 JSON 구성이 있을 때.

# 기본 구문
claude mcp add-json <name> '<json>'

# 예시: JSON 구성으로 stdio 서버 추가하기
claude mcp add-json weather-api '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

claude mcp get weather-api

팁:

• JSON이 셸에서 적절히 이스케이프되었는지 확인하세요
• JSON은 MCP 서버 구성 스키마를 준수해야 합니다
• -s global을 사용하여 프로젝트별 구성 대신 전역 구성에 서버를 추가할 수 있습니다

​

Claude Desktop에서 MCP 서버 가져오기

사용 시기: Claude Desktop에서 이미 MCP 서버를 구성했고 수동으로 재구성하지 않고 동일한 서버를 Claude Code에서 사용하고 싶을 때.

# 기본 구문
claude mcp add-from-claude-desktop

claude mcp list

팁:

• 이 기능은 macOS와 Windows Subsystem for Linux (WSL)에서만 작동합니다
• 해당 플랫폼의 표준 위치에서 Claude Desktop 구성 파일을 읽습니다
• -s global 플래그를 사용하여 전역 구성에 서버를 추가하세요
• 가져온 서버는 Claude Desktop에서와 동일한 이름을 가집니다
• 동일한 이름의 서버가 이미 존재하는 경우 숫자 접미사가 붙습니다(예: server_1)

​

Claude Code를 MCP 서버로 사용하기

사용 시기: Claude Code 자체를 다른 애플리케이션이 연결할 수 있는 MCP 서버로 사용하여 Claude의 도구와 기능을 제공하고 싶을 때.

# 기본 구문
claude mcp serve

{
  "command": "claude",
  "args": ["mcp", "serve"],
  "env": {}
}

팁:

• 서버는 View, Edit, LS 등과 같은 Claude의 도구에 대한 접근을 제공합니다
• Claude Desktop에서 디렉토리의 파일 읽기, 편집 등을 Claude에게 요청해보세요
• 이 MCP 서버는 단순히 Claude Code의 도구를 MCP 클라이언트에 노출하는 것이므로, 개별 도구 호출에 대한 사용자 확인 구현은 클라이언트의 책임입니다

​

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

​

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

사용 시기: Claude Code를 린터나 코드 리뷰어로 사용하고 싶을 때.

단계:

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

​

파이프 인, 파이프 아웃

사용 시기: Claude에 데이터를 파이프로 전달하고 구조화된 형식으로 데이터를 받고 싶을 때.

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

​

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

Claude Code는 특정 프롬프트나 작업을 빠르게 실행하기 위해 생성할 수 있는 사용자 정의 슬래시 명령어를 지원합니다.

​

프로젝트별 명령어 만들기

사용 시기: 모든 팀원이 사용할 수 있는 프로젝트용 재사용 가능한 슬래시 명령어를 만들고 싶을 때.

mkdir -p .claude/commands

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

claude
> /project:optimize

팁:

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

​

$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

claude
> /project:fix-issue 123

팁:

• $ARGUMENTS 플레이스홀더는 명령어 뒤에 오는 모든 텍스트로 대체됩니다
• $ARGUMENTS를 명령어 템플릿의 어디에나 배치할 수 있습니다
• 다른 유용한 적용: 특정 함수에 대한 테스트 케이스 생성, 컴포넌트에 대한 문서 작성, 특정 파일의 코드 검토 또는 지정된 언어로 콘텐츠 번역

​

개인 슬래시 명령어 만들기

사용 시기: 모든 프로젝트에서 작동하는 개인 슬래시 명령어를 만들고 싶을 때.

mkdir -p ~/.claude/commands

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

claude
> /user:security-review

팁:

• 개인 명령어는 /project: 대신 /user:로 시작합니다
• 개인 명령어는 사용자만 사용할 수 있고 팀과 공유되지 않습니다
• 개인 명령어는 모든 프로젝트에서 작동합니다
• 이를 사용하여 다른 코드베이스에서 일관된 워크플로우를 유지할 수 있습니다

​

Git worktrees로 병렬 Claude Code 세션 실행하기

​

격리된 코딩 환경을 위해 worktrees 사용하기

사용 시기: Claude Code 인스턴스 간에 완전한 코드 격리를 유지하면서 여러 작업을 동시에 수행해야 할 때.

# 새 브랜치로 새 worktree 만들기
git worktree add ../project-feature-a feature-a

# 또는 기존 브랜치로 worktree 만들기
git worktree add ../project-bugfix bugfix-123

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

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

cd ../project-bugfix
claude

# 모든 worktrees 나열하기
git worktree list

# 완료되면 worktree 제거하기
git worktree remove ../project-feature-a

팁:

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

​

다음 단계