Claude Code 실전 가이드: 설치부터 Director 모드·MCP·Sub-Agent까지

터미널에 요청 하나를 던져두면 여러 파일에 걸친 변경과 커밋까지 끝나 있다 — Claude Code는 코드 한 줄을 대신 써주는 도구가 아니라 전체 개발 워크플로우를 넘겨받는 에이전트로 동작한다. Anthropic이 만든 이 도구는 터미널에서 직접 실행되며 프로젝트 전체 컨텍스트를 파악하고, 여러 파일에 걸친 변경사항을 한 번에 처리하며, Git 작업까지 자동화한다.

핵심 역량:

전체 코드베이스 이해: 프로젝트 전체 컨텍스트 파악
다중 파일 편집: 여러 파일에 걸친 변경사항 동시 처리
Git 통합: 자동화된 커밋, PR 생성, 이슈 관리
MCP 지원: Model Context Protocol로 외부 도구 및 API 연결

실행 환경: VS Code, JetBrains IDEs(IntelliJ, PyCharm 등), 데스크톱 앱, 웹 브라우저, Slack에서 모두 실행된다.

기존 코딩 도구와 비교하면 무게중심이 달라졌다는 것이 체감된다. 단순 코드 생성이 전체 워크플로우 자동화로, 파일별 작업이 프로젝트 레벨 이해로, 수동 Git 작업이 자동화된 버전 관리로, 개발자 전용 도구가 비기술자도 쓸 수 있는 도구로 옮겨갔다.

설치와 계정 설정

네이티브 설치가 가장 빠르고 안정적이다.

# macOS/Linux
curl -sSL https://claude.ai/install.sh | sh

# 설치 확인
claude --version

설치 옵션은 네 가지다: 네이티브 인스톨러(권장), VS Code 확장, JetBrains 플러그인, 웹 버전(설치 불필요).

요금제는 두 갈래다.

Pro Plan($20/month)은 개인 개발자 대부분에게 충분한 사양으로, 5시간 윈도우 갱신 시스템(5시간마다 사용량 할당 리셋)과 무제한 프로젝트를 제공한다. Team Plan은 2026년 2월부터 Standard 좌석에 Claude Code 액세스가 추가됐고, PII·HIPAA·금융 데이터를 지원하는 엔터프라이즈급 보안·규정 준수를 갖췄다.

첫 실행 시에는 Anthropic 계정 연결 → 프로젝트 디렉토리 지정 → 선호 IDE 연동 → MCP 서버 설정(선택사항) 순으로 초기 구성을 진행한다.

Shift+Tab으로 오가는 작업 모드들

Default, Director, Plan 세 모드는 Shift+Tab으로 언제든 전환할 수 있다.

⤢✕

Default Mode는 기본 대화형 모드다. 사용자가 요청하면 Claude가 변경을 제안하고, 승인을 기다린 뒤 실행한다. 단계별 확인과 제어가 이뤄지는 만큼 초보자에게 적합하고 워크플로우가 안전하고 예측 가능하다.

User: "index.html에 다크 모드 토글 버튼 추가해줘"
Claude: [변경사항 제안]
User: [승인]
Claude: [실행 및 확인]

Director Mode는 Claude Code의 진정한 잠재력을 발휘하는 모드다. 코드를 마이크로 매니징하지 않고 기술 리드처럼 지시한다는 개념으로, Claude가 자율적으로 계획을 세우고 실행하며 복잡한 다단계 작업에 최적화돼 있다.

❌ 나쁜 예: "src/components/Button.tsx 파일을 열고 onClick 핸들러 추가해"
✅ 좋은 예: "모든 버튼에 클릭 이벤트 트래킹 추가해"

높은 수준의 추상화, 빠른 개발 속도, 전체 프로젝트 컨텍스트 활용, 자동 테스트 및 검증이 이 모드의 장점이다.

Plan Mode는 계획 중심 접근이다. 먼저 전체 계획을 세우고 단계별 실행 전략을 제시한 뒤 사용자가 검토·조정할 수 있어 대규모 리팩토링에 유용하다. 워크플로우는 목표 설명 → Claude가 상세 계획 생성 → 사용자 검토 및 수정 → 단계별 실행 → 각 단계 검증 순이다.

Slash Command로 반복 작업 줄이기

핵심 Slash Command는 용도별로 나뉜다.

파일 및 프로젝트 관리: /read <파일>(파일 내용 읽기), /edit <파일>(파일 편집), /create <파일>(새 파일 생성), /delete <파일>(파일 삭제)

Git 작업: /commit(변경사항 커밋), /pr(Pull Request 생성), /branch(브랜치 관리), /install-github-app(GitHub 앱 설치, 자동 PR 리뷰)

검색 및 탐색: /search <키워드>(코드베이스 검색), /find <패턴>(파일 찾기), /grep <정규식>(정규식 검색)

유틸리티: /help(도움말), /clear(컨텍스트 초기화), /undo(마지막 작업 취소)

반복 작업은 Custom Slash Command로 단일 명령으로 바꿀 수 있다.

// .claude/skills/deploy.md
---
name: deploy
description: 프로덕션 배포 자동화
---

1. 테스트 실행
2. 빌드
3. 버전 업데이트
4. Git 태그 생성
5. 배포 스크립트 실행

/deploy

MCP로 외부 도구와 연결하기

Model Context Protocol(MCP)은 외부 도구 및 API와 Claude Code를 연결하는 표준 프로토콜이다.

⤢✕

파일시스템 MCP 서버는 다음과 같이 설치한다.

claude mcp install @anthropic-ai/mcp-server-filesystem

일반적인 MCP 서버로는 @anthropic-ai/mcp-server-google-drive(Google Drive 접근), @anthropic-ai/mcp-server-jira(Jira 티켓 관리), @anthropic-ai/mcp-server-slack(Slack 통합)이 있고, 커스텀 MCP 서버도 개발할 수 있다.

Google Drive를 연동하면 이런 식으로 쓴다.

"Google Drive의 design-specs 폴더에서 최신 디자인 문서 읽고
컴포넌트 구현해줘"

Jira 연동 예시는 다음과 같다.

"Jira 티켓 PROJ-123의 요구사항 읽고 구현 후
진행 상태를 'In Progress'로 업데이트해줘"

Sub-Agent와 Skills로 작업을 나누기

Sub-Agent는 독립적인 지시사항, 컨텍스트 윈도우, 도구 권한을 가진 전문 AI다. 코드 리뷰 전문 에이전트, 테스트 작성 전문 에이전트, 문서 업데이트 전문 에이전트, 보안 검토 전문 에이전트 같은 용도로 쓴다. .claude/agents/code-reviewer.md처럼 파일로 정의한다.

---
name: code-reviewer
model: claude-sonnet-4.5
temperature: 0.3
---

# Code Reviewer Agent

당신은 코드 리뷰 전문가입니다.

## 책임

- 코드 품질 검토
- 버그 및 취약점 식별
- 성능 최적화 제안
- 베스트 프랙티스 준수 확인

## 리뷰 기준

1. 가독성
2. 유지보수성
3. 성능
4. 보안
5. 테스트 커버리지

2026년 2월에는 멀티 에이전트 협업(Research Preview)인 Agent Teams가 추가됐다. 여러 Sub-Agent가 동시에 작업하고 역할을 자동 분담하며 병렬 처리로 속도를 끌어올린다.

"이 기능을 구현해줘"
→ Agent 1: 코드 작성
→ Agent 2: 테스트 생성
→ Agent 3: 문서 업데이트

Skills는 .claude/skills/ 디렉토리에 정의된 워크플로우 템플릿이다. 2026년 2월 업데이트로 .claude/skills/ 내 추가 디렉토리의 스킬이 자동 로드되어 프로젝트별 커스텀 스킬 관리가 쉬워졌다.

---
name: api-endpoint
description: RESTful API 엔드포인트 생성
parameters:
  - name: resource
    description: 리소스 이름 (예: users, posts)
  - name: methods
    description: HTTP 메서드 (GET, POST, PUT, DELETE)
---

# API Endpoint Skill

1. 컨트롤러 파일 생성
2. 라우트 정의
3. 유효성 검증 미들웨어 추가
4. 테스트 파일 생성
5. API 문서 업데이트

/api-endpoint resource=products methods=GET,POST,PUT,DELETE

Research → Plan → Implement → Validate 워크플로우

효과적인 Claude Code 사용을 위한 4단계 접근이다.

⤢✕

Research(조사) 단계 목표는 문제 이해와 컨텍스트 파악이다. 기존 코드 탐색, 관련 파일 식별, 의존성 확인, 유사 구현 검토가 이 단계 활동이고, 실제로는 이렇게 쓴다.

"이 프로젝트의 인증 시스템 구조 설명해줘"
"/search authentication"
"/read src/auth/AuthService.ts"

Plan(계획) 단계는 구현 전략을 세운다. 변경사항 범위 정의, 영향 받는 파일 식별, 테스트 전략 수립, 필요 시 마이그레이션 계획이 여기 들어간다.

"OAuth 2.0 인증 추가 계획 수립해줘"
→ 상세 단계별 계획 생성

Implement(구현) 단계는 코드를 작성하고 변경한다. 코드 작성, 기존 코드 수정, 테스트 작성, 문서 업데이트가 활동이다.

"계획대로 OAuth 2.0 구현해줘"
→ 자동으로 여러 파일 편집

Validate(검증) 단계는 정상 작동을 확인한다. 테스트 실행, 코드 리뷰, 성능 확인, 버그 수정이 여기 속한다.

"모든 테스트 실행하고 실패하는 것 수정해줘"
"/pr"  # PR 생성 후 자동 리뷰

각 단계 사이에 /clear로 컨텍스트를 정리하면 성능을 최적화할 수 있다.

개발자만의 도구가 아니다

개발자 활용은 버그 수정, 기능 구현, 리팩토링, 테스트 작성, 코드 리뷰 같은 일반 작업부터 대규모 코드베이스 탐색, 레거시 코드 마이그레이션, 성능 최적화, 보안 취약점 발견 같은 고급 작업까지 걸쳐 있다. Git 워크플로우는 이렇게 통째로 자동화된다.

# 전체 워크플로우 자동화
"feature-123 브랜치 생성하고
Jira 티켓 내용 구현 후
테스트 작성하고
PR 생성해줘"

비개발자 활용도 2026년 실제 사례로 보고된다. 변호사는 전화 시스템 구축, 문서 자동화 도구 개발, 케이스 관리 시스템 커스터마이징에 쓰고, 마케터는 수백 개 광고 변형 생성, A/B 테스트 자동화, 데이터 시각화 대시보드에 쓴다. 데이터 과학자는 JavaScript를 몰라도 복잡한 시각화를 만들고 데이터 파이프라인을 자동화하며 분석 보고서를 자동 생성하고, 프로덕트 디자이너는 에러 상태 매핑, 로직 흐름도 생성, 엣지 케이스 식별, 디자인 초기 품질 향상에 활용한다.

창의적 활용도 눈에 띈다. 산책 중 녹음한 음성 파일을 정리하는 예시가 대표적이다.

"산책 중 녹음한 음성 파일을
연구 테마로 정리하고
전체 글 작성 후
LinkedIn 버전도 만들어줘"

오디오 파일 처리(샘플 레이트 변환, 파일명 일괄 변경, 번역 자막 생성)와 자동 문서화(Playwright로 소프트웨어 자동 탐색, 스크린샷 캡처 및 설명 생성, 문서 변경사항 자동 커밋)도 창의적 활용 범주에 든다.

2026년 업데이트: Opus 4.6과 그 밖의 변화

Claude Opus 4.6 출시로 코딩 능력, 장시간 작업 지속성, 고품질 전문 작업물 생성, 대규모 코드베이스 내 안정적 작동이 개선됐다. 계획 수립(Planning) 개선, 코드 리뷰 정확도 향상, 디버깅 효율성 증대가 성능 향상 축이고, 보안 기능 측면에서는 500개 이상의 제로데이 취약점을 발견했으며 기본 기능만으로 오픈소스 코드 보안 분석과 자동 취약점 탐지·리포팅이 가능해졌다.

Fast Mode for Opus 4.6은 동일한 Opus 4.6 모델을 쓰면서 품질 저하 없이 응답 속도를 높인다.

/fast

그 밖에 자동 메모리 기록(작업 중 자동으로 메모리를 기록하고 이전 대화 컨텍스트를 자동 회상, 프로젝트별 지식 누적 — 반복 설명 불필요, 일관된 코딩 스타일 유지, 프로젝트 히스토리 추적으로 이어짐), 대화 요약 기능("Summarize from here" — 메시지 선택기에서 부분 대화 요약, 긴 대화 빠른 파악, 중요 정보 추출), Bash Tool 개선(heredoc 내 JavaScript 템플릿 리터럴 사용 시 "Bad substitution" 오류 해결), Skill 컨텍스트 윈도우 확장(스킬 문자 예산이 컨텍스트 윈도우에 맞춰 자동 조정되어 더 복잡한 스킬 작성 가능)이 추가됐다.

엔터프라이즈에서 쓰려면

보안 및 규정 준수 측면에서는 PII(개인 식별 정보) 처리, HIPAA 규정 준수, 금융 데이터 보안을 지원한다. 배포 옵션은 Anthropic API, AWS Bedrock, Google Vertex AI, 자체 인프라/클라우드 제공자 중에서 고른다.

스케일 및 협업은 공유 스킬 라이브러리, 일관된 코딩 표준, 자동 코드 리뷰 같은 팀 기능으로 뒷받침된다. Anthropic 내부에서는 프로덕션 이슈 디버깅, 낯선 코드베이스 탐색, 커스텀 자동화 도구 구축에 쓴다고 알려져 있다.

잘 쓰기 위한 습관

Director Mode를 마스터하려면 고수준 지시를 습관화해야 한다.

❌ "Button.tsx 열어서 onClick 추가"
✅ "전체 앱에 분석 트래킹 추가"

❌ "API 컨트롤러 만들어"
✅ "사용자 관리를 위한 RESTful API 구축"

컨텍스트 관리는 작업 시작 전 /clear로 초기화 → 필요한 파일만 열기 → 큰 작업은 단계별로 분할 → 각 단계 완료 후 검증 순으로 한다.

테스트 작성 자동화는 프로젝트 패턴을 활용한다.

"기존 테스트 파일 스타일 분석해서
동일한 패턴으로 UserService 테스트 작성해줘"

Jest, Mocha, Pytest 등을 자동 인식하고 기존 assertion 패턴을 매칭해 일관된 테스트 코드를 생성하는 자동 프레임워크 감지도 지원한다.

효과적인 PR 관리를 위해서는 GitHub App을 설치해 자동 PR 리뷰를 받을 수 있다.

/install-github-app

PR 생성 워크플로우는 기능 구현 → 테스트 작성 및 실행 → /commit(의미있는 커밋 메시지 자동 생성) → /pr(PR 생성 및 설명 자동 작성) → GitHub App의 자동 리뷰 순이다.

5시간 윈도우는 복잡한 작업을 윈도우 시작 직후에, 간단한 작업은 아무 때나 배치하는 식으로 관리하면 효율적이다. Director Mode로 한 번에 많은 작업을 몰아넣고, 반복 작업은 Custom Slash Command로, 병렬 처리가 필요하면 Sub-Agent로 넘긴다.

컨텍스트 윈도우 최적화는 불필요한 파일을 .claudeignore로 제외하는 것부터 시작한다.

.claudeignore 파일 생성
node_modules/
dist/
.git/
*.log

관련 파일만 언급하고, 불필요한 히스토리는 /clear로 지우고, 큰 파일은 부분적으로 읽는 것도 함께 챙길 습관이다.

막힐 때 확인할 것들

느린 응답 속도는 /clear로 컨텍스트를 정리하거나, Fast Mode를 켜거나, 작업 단위를 줄이는 식으로 대응한다. 예상과 다른 결과가 나오면 더 구체적으로 지시하거나, Plan Mode로 먼저 계획을 확인하거나, 예제 코드를 제공해본다. 컨텍스트 제한을 초과했다면 .claudeignore로 불필요한 파일을 제외하거나, 작업을 여러 세션으로 나누거나, Sub-Agent를 활용한다.

오류를 효과적으로 보고하려면 오류 메시지 전체를 그대로 전달하는 편이 낫다.

"이 오류 메시지 분석하고 원인 찾아서 수정해줘:
[오류 메시지 전체 복사]"

단계별 디버깅은 오류 재현 → 로그 확인 → 원인 분석 → 수정 제안 → 테스트로 검증 순으로 진행한다.

언제 쓰고 언제 손으로 할지

Claude Code가 권장되는 상황은 다중 파일 리팩토링, 테스트 자동 생성, Git 워크플로우 자동화, 낯선 코드베이스 탐색, 반복적인 코드 패턴 구현이다. 반대로 세밀한 UI/UX 조정, 복잡한 알고리즘 최적화, 도메인 특화 로직, 크리티컬한 보안 코드는 수동 작업이 더 낫다.

학습 곡선은 단계적이다. 초보자(1-2주)는 Default Mode 숙달, 기본 Slash Command 학습, 파일 읽기/편집을 익힌다. 중급자(1개월)는 Director Mode 활용, Custom Command 작성, MCP 통합으로 넘어간다. 고급 사용자(2-3개월)는 Sub-Agent 설계, Skills 라이브러리 구축, Agent Teams 활용까지 다룬다.