이 가이드는 Claude Code의 일반적인 워크플로우에 대한 단계별 튜토리얼을 제공합니다. 각 튜토리얼에는 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에게 현대적 접근 방식의 이점을 설명하도록 요청하기
  • 필요할 때 하위 호환성을 유지하도록 요청하기
  • 작고 테스트 가능한 단위로 리팩토링 수행하기

테스트 작업하기

테스트 커버리지 추가

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

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에게 테스트 전략 설명 요청하기

풀 리퀘스트 생성하기

포괄적인 PR 생성

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

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. 이미지를 복사하여 ctrl+v로 CLI에 붙여넣기
# 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

맥락을 제공하고 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 harder about edge cases we should handle

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

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

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

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

  • “think”는 기본적인 확장된 사고를 유발
  • “think more”, “think a lot”, “think harder” 또는 “think longer”와 같은 강화 구문은 더 깊은 사고를 유발

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

Claude는 응답 위에 이탤릭체 회색 텍스트로 사고 과정을 표시합니다.


프로젝트 메모리 설정하기

효과적인 CLAUDE.md 파일 생성

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

1

코드베이스에 대한 CLAUDE.md 부트스트랩

> /init

팁:

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

Model Context Protocol (MCP) 설정하기

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

타사 MCP 서버는 자신의 책임 하에 사용하세요. MCP 서버를 신뢰할 수 있는지 확인하고, 특히 인터넷과 통신하는 MCP 서버를 사용할 때는 프롬프트 인젝션 위험에 노출될 수 있으므로 각별히 주의하세요.

MCP 서버 구성

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

1

MCP Stdio 서버 추가

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

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

MCP 서버 관리

# 구성된 모든 서버 나열
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 스코프가 어떻게 작동하는지 이해하고 팀과 서버를 공유하고 싶을 때

1

로컬 스코프 MCP 서버

기본 스코프(local)는 프로젝트별 사용자 설정에 MCP 서버 구성을 저장합니다. 이러한 서버는 현재 프로젝트에서 작업하는 동안에만 사용자가 사용할 수 있습니다.

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

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

프로젝트 스코프 MCP 서버 (.mcp.json)

프로젝트 스코프 서버는 프로젝트 루트의 .mcp.json 파일에 저장됩니다. 이 파일은 팀과 서버를 공유하기 위해 버전 컨트롤에 체크인해야 합니다.

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

이는 다음 구조의 .mcp.json 파일을 생성하거나 업데이트합니다:

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

사용자 스코프 MCP 서버

사용자 스코프 서버는 기계의 모든 프로젝트에서 사용할 수 있으며 사용자에게만 비공개입니다.

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

팁:

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

Postgres MCP 서버에 연결

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

1

Postgres MCP 서버 추가

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

Claude로 데이터베이스 쿼리

# 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 구성이 있을 때

1

JSON에서 MCP 서버 추가

# 기본 구문
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"}}'
2

서버가 추가되었는지 확인

claude mcp get weather-api

팁:

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

Claude Desktop에서 MCP 서버 가져오기

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

1

Claude Desktop에서 서버 가져오기

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

가져올 서버 선택

명령어를 실행한 후, 가져오고 싶은 서버를 선택할 수 있는 대화형 대화 상자가 표시됩니다.

3

서버가 가져와졌는지 확인

claude mcp list

팁:

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

Claude Code를 MCP 서버로 사용

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

1

Claude를 MCP 서버로 시작

# 기본 구문
claude mcp serve
2

다른 애플리케이션에서 연결

Claude Desktop과 같은 모든 MCP 클라이언트에서 Claude Code MCP 서버에 연결할 수 있습니다. Claude Desktop을 사용하는 경우 다음 구성을 사용하여 Claude Code MCP 서버를 추가할 수 있습니다:

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

팁:

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

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

검증 프로세스에 Claude 추가

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

단계:

1

빌드 스크립트에 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.'"
    }
}

파이프 인, 파이프 아웃

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

1

Claude를 통해 데이터 파이프

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

사용자 정의 슬래시 명령어 생성

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에서 사용자 정의 명령어 사용

claude
> /project:optimize

팁:

  • 명령어 이름은 파일 이름에서 파생됩니다(예: optimize.md/project: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
> /project: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

개인 사용자 정의 명령어 사용

claude
> /user:security-review

팁:

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

다음 단계

Claude Code 참조 구현

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

Was this page helpful?