Claude Code 튜토리얼
개발 워크플로우에서 Claude Code를 효과적으로 사용하기 위한 실용적인 예제와 패턴
이 가이드는 Claude Code의 일반적인 워크플로우에 대한 단계별 튜토리얼을 제공합니다. 각 튜토리얼에는 Claude Code를 최대한 활용할 수 있도록 명확한 지침, 예제 명령어 및 모범 사례가 포함되어 있습니다.
목차
- 새로운 코드베이스 이해하기
- 효율적으로 버그 수정하기
- 코드 리팩토링하기
- 테스트 작업하기
- 풀 리퀘스트 생성하기
- 문서 처리하기
- 이미지 작업하기
- 확장된 사고 사용하기
- 프로젝트 메모리 설정하기
- Model Context Protocol (MCP) 설정하기
- 유닉스 스타일 유틸리티로 Claude 사용하기
- 사용자 정의 슬래시 명령어 만들기
새로운 코드베이스 이해하기
코드베이스 빠른 개요 얻기
사용 시기: 새로운 프로젝트에 참여하여 그 구조를 빠르게 이해해야 할 때
프로젝트 루트 디렉토리로 이동
Claude Code 시작
상위 수준 개요 요청
특정 컴포넌트 자세히 살펴보기
팁:
- 광범위한 질문으로 시작한 다음 특정 영역으로 좁혀가기
- 프로젝트에서 사용된 코딩 규칙과 패턴에 대해 문의하기
- 프로젝트 특정 용어의 용어집 요청하기
관련 코드 찾기
사용 시기: 특정 기능이나 기능과 관련된 코드를 찾아야 할 때
Claude에게 관련 파일 찾기 요청
컴포넌트 간 상호작용 맥락 파악
실행 흐름 이해하기
팁:
- 찾고자 하는 것을 구체적으로 명시하기
- 프로젝트의 도메인 언어 사용하기
효율적으로 버그 수정하기
오류 메시지 진단
사용 시기: 오류 메시지가 발생하여 그 원인을 찾아 수정해야 할 때
Claude와 오류 공유
수정 권장사항 요청
수정사항 적용
팁:
- Claude에게 오류를 재현하는 명령어와 스택 트레이스를 알려주기
- 오류를 재현하는 단계 언급하기
- 오류가 간헐적인지 일관적인지 Claude에게 알려주기
코드 리팩토링
레거시 코드 현대화
사용 시기: 오래된 코드를 현대적인 패턴과 관행을 사용하도록 업데이트해야 할 때
리팩토링할 레거시 코드 식별
리팩토링 권장사항 받기
안전하게 변경사항 적용
리팩토링 검증
팁:
- Claude에게 현대적 접근 방식의 이점을 설명하도록 요청하기
- 필요할 때 하위 호환성을 유지하도록 요청하기
- 작고 테스트 가능한 단위로 리팩토링 수행하기
테스트 작업하기
테스트 커버리지 추가
사용 시기: 테스트되지 않은 코드에 대한 테스트를 추가해야 할 때
테스트되지 않은 코드 식별
테스트 스캐폴딩 생성
의미 있는 테스트 케이스 추가
테스트 실행 및 검증
팁:
- 엣지 케이스와 오류 조건을 다루는 테스트 요청하기
- 적절한 경우 단위 테스트와 통합 테스트 모두 요청하기
- Claude에게 테스트 전략 설명 요청하기
풀 리퀘스트 생성하기
포괄적인 PR 생성
사용 시기: 변경사항에 대한 잘 문서화된 풀 리퀘스트를 생성해야 할 때
변경사항 요약
Claude로 PR 생성
검토 및 개선
테스트 세부정보 추가
팁:
- Claude에게 직접 PR 생성 요청하기
- 제출하기 전에 Claude가 생성한 PR 검토하기
- Claude에게 잠재적 위험이나 고려사항 강조 요청하기
문서 처리하기
코드 문서 생성
사용 시기: 코드에 대한 문서를 추가하거나 업데이트해야 할 때
문서화되지 않은 코드 식별
문서 생성
검토 및 개선
문서 검증
팁:
- 원하는 문서 스타일 지정하기 (JSDoc, docstrings 등)
- 문서에 예제 요청하기
- 공개 API, 인터페이스 및 복잡한 로직에 대한 문서 요청하기
이미지 작업하기
이미지와 스크린샷 분석
사용 시기: 코드베이스에서 이미지 작업을 하거나 Claude의 도움을 받아 이미지 내용을 분석해야 할 때
대화에 이미지 추가
다음 방법 중 하나를 사용할 수 있습니다:
Claude에게 이미지 분석 요청
맥락을 위해 이미지 사용
시각적 콘텐츠에서 코드 제안 받기
팁:
- 텍스트 설명이 불명확하거나 번거로울 때 이미지 사용하기
- 오류, UI 디자인 또는 다이어그램의 스크린샷 포함하기
- 대화에서 여러 이미지로 작업할 수 있음
- 이미지 분석은 다이어그램, 스크린샷, 목업 등에서 작동함
확장된 사고 사용하기
복잡한 작업을 위해 Claude의 확장된 사고 활용하기
사용 시기: 복잡한 아키텍처 결정, 까다로운 버그 또는 깊은 추론이 필요한 다단계 구현 계획을 작업할 때
맥락을 제공하고 Claude에게 생각하도록 요청
Claude는 코드베이스에서 관련 정보를 수집하고 인터페이스에 표시될 확장된 사고를 사용할 것입니다.
후속 프롬프트로 사고 개선
확장된 사고를 최대한 활용하기 위한 팁:
확장된 사고는 다음과 같은 복잡한 작업에 가장 유용합니다:
- 복잡한 아키텍처 변경 계획
- 복잡한 문제 디버깅
- 새로운 기능에 대한 구현 계획 수립
- 복잡한 코드베이스 이해
- 다양한 접근 방식 간의 트레이드오프 평가
사고를 프롬프트하는 방식에 따라 다양한 수준의 사고 깊이가 발생합니다:
- “think”는 기본적인 확장된 사고를 유발
- “think more”, “think a lot”, “think harder” 또는 “think longer”와 같은 강화 구문은 더 깊은 사고를 유발
더 많은 확장된 사고 프롬프팅 팁은 확장된 사고 팁을 참조하세요.
Claude는 응답 위에 이탤릭체 회색 텍스트로 사고 과정을 표시합니다.
프로젝트 메모리 설정하기
효과적인 CLAUDE.md 파일 생성
사용 시기: 중요한 프로젝트 정보, 규칙 및 자주 사용하는 명령어를 저장하기 위해 CLAUDE.md 파일을 설정하고 싶을 때
코드베이스에 대한 CLAUDE.md 부트스트랩
팁:
- 자주 사용하는 명령어(빌드, 테스트, 린트)를 포함하여 반복적인 검색 방지
- 코드 스타일 선호도와 명명 규칙 문서화
- 프로젝트에 특화된 중요한 아키텍처 패턴 추가
- 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의 기능을 향상시키고 싶을 때
MCP Stdio 서버 추가
MCP 서버 관리
팁:
-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 스코프가 어떻게 작동하는지 이해하고 팀과 서버를 공유하고 싶을 때
로컬 스코프 MCP 서버
기본 스코프(local
)는 프로젝트별 사용자 설정에 MCP 서버 구성을 저장합니다. 이러한 서버는 현재 프로젝트에서 작업하는 동안에만 사용자가 사용할 수 있습니다.
프로젝트 스코프 MCP 서버 (.mcp.json)
프로젝트 스코프 서버는 프로젝트 루트의 .mcp.json
파일에 저장됩니다. 이 파일은 팀과 서버를 공유하기 위해 버전 컨트롤에 체크인해야 합니다.
이는 다음 구조의 .mcp.json
파일을 생성하거나 업데이트합니다:
사용자 스코프 MCP 서버
사용자 스코프 서버는 기계의 모든 프로젝트에서 사용할 수 있으며 사용자에게만 비공개입니다.
팁:
- 로컬 스코프 서버는 동일한 이름의 프로젝트 스코프 및 사용자 스코프 서버보다 우선순위가 높습니다
- 프로젝트 스코프 서버(
.mcp.json
에 있는)는 동일한 이름의 사용자 스코프 서버보다 우선순위가 높습니다 .mcp.json
의 프로젝트 스코프 서버를 사용하기 전에 Claude Code는 보안을 위해 승인을 요청할 것입니다.mcp.json
파일은 팀과 MCP 서버를 공유하기 위해 버전 컨트롤에 체크인하도록 되어 있습니다- 프로젝트 스코프 서버를 사용하면 팀의 모든 구성원이 동일한 MCP 도구에 쉽게 접근할 수 있습니다
- 프로젝트 스코프 서버의 활성화 또는 비활성화 선택을 재설정해야 하는 경우
claude mcp reset-project-choices
명령어를 사용하세요
Postgres MCP 서버에 연결
사용 시기: Claude에게 PostgreSQL 데이터베이스에 대한 읽기 전용 접근 권한을 부여하여 쿼리와 스키마 검사를 수행하고 싶을 때
Postgres MCP 서버 추가
Claude로 데이터베이스 쿼리
팁:
- Postgres MCP 서버는 안전을 위해 읽기 전용 접근을 제공합니다
- Claude는 데이터베이스 구조를 탐색하고 분석 쿼리를 실행하는 데 도움을 줄 수 있습니다
- 이를 사용하여 익숙하지 않은 프로젝트의 데이터베이스 스키마를 빠르게 이해할 수 있습니다
- 연결 문자열이 최소한의 필요한 권한을 가진 적절한 자격 증명을 사용하는지 확인하세요
JSON 구성에서 MCP 서버 추가
사용 시기: Claude Code에 추가하려는 단일 MCP 서버에 대한 JSON 구성이 있을 때
JSON에서 MCP 서버 추가
서버가 추가되었는지 확인
팁:
- JSON이 셸에서 적절히 이스케이프되었는지 확인하세요
- JSON은 MCP 서버 구성 스키마를 준수해야 합니다
-s global
을 사용하여 프로젝트별 구성 대신 전역 구성에 서버를 추가할 수 있습니다
Claude Desktop에서 MCP 서버 가져오기
사용 시기: Claude Desktop에서 이미 MCP 서버를 구성했고 수동으로 재구성하지 않고 동일한 서버를 Claude Code에서 사용하고 싶을 때
Claude Desktop에서 서버 가져오기
가져올 서버 선택
명령어를 실행한 후, 가져오고 싶은 서버를 선택할 수 있는 대화형 대화 상자가 표시됩니다.
서버가 가져와졌는지 확인
팁:
- 이 기능은 macOS와 Windows Subsystem for Linux (WSL)에서만 작동합니다
- 해당 플랫폼의 표준 위치에서 Claude Desktop 구성 파일을 읽습니다
-s global
플래그를 사용하여 전역 구성에 서버를 추가하세요- 가져온 서버는 Claude Desktop에서와 동일한 이름을 가집니다
- 동일한 이름의 서버가 이미 존재하는 경우 숫자 접미사가 붙습니다(예:
server_1
)
Claude Code를 MCP 서버로 사용
사용 시기: Claude Code 자체를 다른 애플리케이션이 연결할 수 있는 MCP 서버로 사용하여 Claude의 도구와 기능을 제공하고 싶을 때
Claude를 MCP 서버로 시작
다른 애플리케이션에서 연결
Claude Desktop과 같은 모든 MCP 클라이언트에서 Claude Code MCP 서버에 연결할 수 있습니다. Claude Desktop을 사용하는 경우 다음 구성을 사용하여 Claude Code MCP 서버를 추가할 수 있습니다:
팁:
- 서버는 View, Edit, LS 등과 같은 Claude의 도구에 대한 접근을 제공합니다
- Claude Desktop에서 디렉토리의 파일 읽기, 편집 등을 Claude에게 요청해보세요
- 이 MCP 서버는 단순히 Claude Code의 도구를 MCP 클라이언트에 노출하는 것이므로, 개별 도구 호출에 대한 사용자 확인은 클라이언트가 구현해야 합니다
유닉스 스타일 유틸리티로 Claude 사용하기
검증 프로세스에 Claude 추가
사용 시기: Claude Code를 린터나 코드 리뷰어로 사용하고 싶을 때
단계:
빌드 스크립트에 Claude 추가
파이프 인, 파이프 아웃
사용 시기: Claude에 데이터를 파이프로 전달하고 구조화된 형식으로 데이터를 받고 싶을 때
Claude를 통해 데이터 파이프
사용자 정의 슬래시 명령어 생성
Claude Code는 특정 프롬프트나 작업을 빠르게 실행하기 위해 생성할 수 있는 사용자 정의 슬래시 명령어를 지원합니다.
프로젝트별 명령어 생성
사용 시기: 모든 팀 구성원이 사용할 수 있는 프로젝트용 재사용 가능한 슬래시 명령어를 만들고 싶을 때
프로젝트에 명령어 디렉토리 생성
각 명령어에 대한 Markdown 파일 생성
Claude Code에서 사용자 정의 명령어 사용
팁:
- 명령어 이름은 파일 이름에서 파생됩니다(예:
optimize.md
는/project:optimize
가 됨) - 하위 디렉토리에 명령어를 구성할 수 있습니다(예:
.claude/commands/frontend/component.md
는/project:frontend:component
가 됨) - 프로젝트 명령어는 저장소를 복제하는 모든 사람이 사용할 수 있습니다
- Markdown 파일 내용은 명령어가 호출될 때 Claude에 전송되는 프롬프트가 됩니다
$ARGUMENTS로 명령어 인수 추가
사용 시기: 사용자로부터 추가 입력을 받을 수 있는 유연한 슬래시 명령어를 만들고 싶을 때
$ARGUMENTS 플레이스홀더로 명령어 파일 생성
이슈 번호로 명령어 사용
이는 프롬프트에서 $ARGUMENTS를 “123”으로 대체합니다.
팁:
- $ARGUMENTS 플레이스홀더는 명령어 뒤에 오는 모든 텍스트로 대체됩니다
- 명령어 템플릿의 어디에나 $ARGUMENTS를 배치할 수 있습니다
- 다른 유용한 적용: 특정 함수에 대한 테스트 케이스 생성, 컴포넌트에 대한 문서 작성, 특정 파일의 코드 검토 또는 지정된 언어로 콘텐츠 번역
개인 슬래시 명령어 생성
사용 시기: 모든 프로젝트에서 작동하는 개인 슬래시 명령어를 만들고 싶을 때
홈 폴더에 명령어 디렉토리 생성
각 명령어에 대한 Markdown 파일 생성
개인 사용자 정의 명령어 사용
팁:
- 개인 명령어는
/project:
대신/user:
로 시작합니다 - 개인 명령어는 사용자에게만 제공되며 팀과 공유되지 않습니다
- 개인 명령어는 모든 프로젝트에서 작동합니다
- 이를 사용하여 다른 코드베이스에서 일관된 워크플로우를 유지할 수 있습니다
다음 단계
Claude Code 참조 구현
개발 컨테이너 참조 구현을 복제하세요.