출처: https://docs.anthropic.com/en/docs/claude-code/tutorials

개요

이 가이드는 Claude Code를 개발 워크플로우에 효과적으로 활용할 수 있는 실용적인 예제와 패턴을 제공합니다. 각 튜토리얼에는 단계별 설명, 예제 명령어, 베스트 프랙티스가 포함되어 있어 Claude Code를 최대한 활용할 수 있도록 돕습니다.

이전 대화 이어서 작업하기
새로운 코드베이스 이해하기
버그 효율적으로 수정하기
코드 리팩터링
테스트 작업
Pull Request 생성
문서화 작업
이미지 작업
확장된 사고 활용
프로젝트 메모리 설정
Model Context Protocol(MCP) 설정
유닉스 스타일 유틸리티로 Claude 사용
커스텀 슬래시 명령어 만들기
Git 워크트리로 병렬 세션 운영

이전 대화 이어서 작업하기

원활하게 작업 이어가기

사용 시점: Claude Code로 작업하다가 나중에 이어서 계속하고 싶을 때.

Claude Code는 이전 대화를 이어갈 수 있는 두 가지 옵션을 제공합니다:

--continue : 가장 최근 대화를 자동으로 이어감
--resume : 대화 선택기를 표시함

1. 가장 최근 대화 이어가기

claude --continue

2. 비대화 모드로 이어가기

claude --continue --print "작업을 이어서 진행해줘"

3. 대화 선택기 표시

claude --resume

대화 선택기에서는:

대화 시작 시간
초기 프롬프트 또는 요약
메시지 개수
를 확인할 수 있습니다. 방향키로 이동 후 Enter로 선택하세요.

동작 방식:

모든 대화는 전체 메시지 기록과 함께 로컬에 자동 저장됩니다.
재개 시 전체 메시지 기록이 복원되어 맥락이 유지됩니다.
이전 대화에서 사용한 도구 상태와 결과도 보존됩니다.
모든 맥락이 복원된 상태로 대화가 이어집니다.

팁:

대화 기록은 로컬에 저장됩니다.
빠른 접근은 --continue, 특정 대화 선택은 --resume을 사용하세요.
재개 시 전체 대화 기록을 확인할 수 있습니다.
재개된 대화는 원래와 동일한 모델 및 설정으로 시작됩니다.

예시:

# 가장 최근 대화 이어가기
claude --continue

# 특정 프롬프트로 이어가기
claude --continue --print "진행 상황을 보여줘"

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

# 비대화 모드로 이어가기
claude --continue --print "테스트를 다시 실행해줘"

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

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

사용 시점: 새 프로젝트에 합류해 구조를 빠르게 파악해야 할 때.

프로젝트 루트 디렉터리로 이동
```
cd /path/to/project
```
Claude Code 실행
```
claude
```

코드베이스 개요 요청

> 이 코드베이스의 개요를 알려줘

특정 컴포넌트 심층 분석

> 여기서 사용된 주요 아키텍처 패턴을 설명해줘

> 주요 데이터 모델은 무엇이야?

> 인증은 어떻게 처리돼?

팁:

넓은 질문부터 시작해 점차 구체적으로 좁혀가세요.
프로젝트에서 사용하는 코딩 규칙이나 패턴도 물어보세요.
프로젝트 고유 용어집을 요청할 수도 있습니다.

버그 효율적으로 수정하기

에러 메시지 진단

사용 시점: 에러 메시지를 마주하고 원인과 해결책이 필요할 때.

에러 메시지 공유

> npm test 실행 시 에러가 발생해

수정 방안 요청

> user.ts의 @ts-ignore를 고칠 방법을 추천해줘

수정 적용

> 네가 제안한 null 체크를 user.ts에 추가해줘

팁:

이슈 재현 명령어와 스택 트레이스를 Claude에 알려주세요.
에러 재현 단계도 함께 설명하면 좋습니다.
에러가 간헐적인지, 항상 발생하는지도 알려주세요.

코드 리팩터링

레거시 코드 현대화

사용 시점: 오래된 코드를 최신 패턴과 관행으로 개선해야 할 때.

리팩터링 대상 코드 식별

> 코드베이스에서 더 이상 사용하지 않는 API를 찾아줘

리팩터링 방안 요청

> utils.js를 최신 JavaScript 기능으로 리팩터링하는 방법을 제안해줘

안전하게 변경 적용

> utils.js를 ES2024 기능을 활용해 리팩터링하되, 동작은 동일하게 유지해줘

리팩터링 검증

> 리팩터링한 코드의 테스트를 실행해줘

팁:

최신 방식의 장점을 설명해달라고 요청하세요.
필요하다면 하위 호환성 유지도 요청하세요.
리팩터링은 작고 테스트 가능한 단위로 진행하세요.

테스트 작업

테스트 커버리지 추가

사용 시점: 테스트가 없는 코드를 테스트로 보강해야 할 때.

테스트 미적용 코드 식별

> NotificationsService.swift에서 테스트가 없는 함수를 찾아줘

테스트 스캐폴딩 생성

> notification service에 대한 테스트를 추가해줘

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

> notification service의 경계 조건에 대한 테스트 케이스를 추가해줘

테스트 실행 및 검증

> 새로 추가한 테스트를 실행하고 실패한 부분을 고쳐줘

팁:

엣지 케이스와 에러 상황을 다루는 테스트도 요청하세요.
필요에 따라 단위 테스트와 통합 테스트 모두 요청하세요.
테스트 전략 설명도 요청할 수 있습니다.

Pull Request 생성

포괄적인 PR 생성

사용 시점: 변경사항에 대해 잘 정리된 PR을 만들어야 할 때.

변경사항 요약

> authentication 모듈에서 변경한 내용을 요약해줘

Claude로 PR 생성
```
> pr을 생성해줘
```

설명 보강

> 보안 개선에 대한 맥락을 더해 PR 설명을 보강해줘

테스트 내용 추가

> 이 변경사항이 어떻게 테스트되었는지 설명을 추가해줘

팁:

Claude에게 직접 PR 생성을 요청하세요.
Claude가 생성한 PR을 제출 전 반드시 검토하세요.
잠재적 위험이나 고려사항도 강조해달라고 요청하세요.

문서화 작업

코드 문서 자동 생성

사용 시점: 코드에 대한 문서가 없거나 갱신이 필요할 때.

미문서화 코드 식별

> auth 모듈에서 JSDoc 주석이 없는 함수를 찾아줘

문서 자동 생성

> auth.js의 미문서화 함수에 JSDoc 주석을 추가해줘

문서 보강

> 생성된 문서에 더 많은 맥락과 예시를 추가해줘

문서 표준 검증

> 문서가 프로젝트 표준을 따르는지 확인해줘

팁:

원하는 문서 스타일(JSDoc, docstring 등)을 명확히 지정하세요.
예시 코드 추가도 요청하세요.
공개 API, 인터페이스, 복잡한 로직에 대한 문서화도 요청하세요.

이미지 작업

이미지 및 스크린샷 분석

사용 시점: 코드베이스 내 이미지 작업이나 이미지 내용 분석이 필요할 때.

이미지를 대화에 추가
- Claude Code 창에 이미지를 드래그 앤 드롭
- 이미지를 복사해 CLI에 붙여넣기(cmd+v, Mac)
- 이미지 경로를 명시: claude "이 이미지를 분석해줘: /path/to/your/image.png"

이미지 분석 요청

> 이 이미지는 무엇을 보여주나요?

팁:

Claude가 이미지 내 텍스트, 구조, 주요 특징을 설명하도록 요청할 수 있습니다.
이미지와 관련된 코드, 문서, 설명을 함께 요청하세요.

유닉스 스타일 유틸리티로 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.'"
 }
}

파이프 인/아웃

사용 시점: Claude에 데이터를 파이프로 전달하고, 구조화된 결과를 받고 싶을 때.

Claude로 데이터 파이프 처리

cat build-error.txt | claude -p '이 빌드 에러의 근본 원인을 간결하게 설명해줘' > output.txt

출력 형식 제어

사용 시점: Claude의 출력을 특정 형식으로 받아 스크립트나 도구에 통합하고 싶을 때.

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

cat data.txt | claude -p '이 데이터를 요약해줘' --output-format text > summary.txt

JSON 형식 사용

cat code.py | claude -p '이 코드의 버그를 분석해줘' --output-format json > analysis.json

스트리밍 JSON 형식 사용

cat log.txt | claude -p '이 로그 파일에서 에러를 파싱해줘' --output-format stream-json

팁:

단순 응답만 필요하면 --output-format text를 사용하세요.
전체 대화 로그가 필요하면 --output-format json을 사용하세요.
각 턴별 실시간 결과가 필요하면 --output-format stream-json을 사용하세요.

커스텀 슬래시 명령어 만들기

Claude Code는 프로젝트별, 개인별로 재사용 가능한 슬래시 명령어를 만들 수 있습니다.

프로젝트별 명령어 생성

사용 시점: 팀원 모두가 사용할 수 있는 재사용 명령어가 필요할 때.

프로젝트에 명령어 디렉터리 생성
```
mkdir -p .claude/commands
```

각 명령어별 마크다운 파일 생성

echo "이 코드의 성능을 분석하고 세 가지 최적화 방안을 제안해줘:" > .claude/commands/optimize.md

Claude Code에서 명령어 사용
```
claude > /project:optimize
```

팁:

파일명(예: optimize.md)이 명령어 이름(/project:optimize)이 됩니다.
하위 디렉터리로 명령어를 분류할 수 있습니다.
프로젝트를 클론한 모든 사용자가 명령어를 쓸 수 있습니다.
마크다운 파일의 내용이 Claude에 전달되는 프롬프트가 됩니다.

$ARGUMENTS로 명령어 인자 추가

사용 시점: 사용자 입력을 받아 유연하게 동작하는 명령어가 필요할 때.

$ARGUMENTS 플레이스홀더가 포함된 명령어 파일 생성

echo "이슈 #$ARGUMENTS를 찾아 고쳐줘. 다음 단계를 따라줘: 1. 티켓 설명 이해 2. 관련 코드 찾기 3. 근본 원인 해결 4. 테스트 추가 5. 간결한 PR 설명 준비" > .claude/commands/fix-issue.md

명령어 사용 시 인자 전달
```
claude > /project:fix-issue 123
```

팁:

$ARGUMENTS는 명령어 뒤에 입력한 텍스트로 대체됩니다.
함수별 테스트 케이스 생성, 특정 파일 리뷰, 지정 언어로 번역 등 다양한 활용이 가능합니다.

개인별 슬래시 명령어 생성

사용 시점: 모든 프로젝트에서 쓸 수 있는 개인 명령어가 필요할 때.

홈 폴더에 명령어 디렉터리 생성
```
mkdir -p ~/.claude/commands
```