공개 문서
content/courses/06-claude-code-install.mdx
아래는 content/courses/06-claude-code-install.mdx 와 동일한 원문입니다. Markdown과 HTML 변환 결과를 각각 복사할 수 있습니다.
공개 문서 원문 (Markdown)
---
title: "Claude Code 설치 및 시작"
slug: "06-claude-code-install"
description: "Claude Code CLI 설치, 인증, 첫 실행까지"
order: 6
date: "2026-03-10"
level: 1
draft: false
---
# Claude Code 설치 및 시작
> **이 챕터를 마치면** Claude Code CLI를 설치하고 터미널에서 첫 대화까지 진행할 수 있어요.
Claude Code는 Anthropic이 만든 CLI 기반 AI 코딩 에이전트예요.
터미널에서 대화하며 **프로젝트 전체를 이해하고 자율적으로 코드를 작성**해 줘요.
> **전제 조건:** Node.js 18+ 설치 완료 ([설치 챕터](./02-installation) 참고)
---
## 설치
<div className="float-right w-full md:w-[40%] md:ml-6 mb-4 flex-shrink-0 not-prose">
<a href="https://www.npmjs.com/package/@anthropic-ai/claude-code" target="_blank" rel="noopener noreferrer" className="block rounded-lg overflow-hidden border border-slate-200 shadow-sm hover:shadow-md transition-shadow">
<img src="/images/claude-code-install.png" alt="Claude Code npm 패키지 — @anthropic-ai/claude-code" className="w-full h-auto" />
</a>
</div>
터미널을 열고 아래 명령어를 실행합니다.
```bash
npm install -g @anthropic-ai/claude-code
```
설치 확인:
```bash
claude --version
# Claude Code 1.x.x
```
---
## 인증
Claude Code는 두 가지 방법으로 인증할 수 있습니다.
### 방법 1: Claude 구독 사용 (Pro/Max 플랜 — 추천)
Claude.ai Pro($20/월) 또는 Max 구독자라면 별도 API 비용 없이 사용합니다.
```bash
claude
```
첫 실행 시 브라우저가 열리며 Claude.ai 로그인 → 권한 허용 순서로 진행합니다.
### 방법 2: API Key 사용
[Anthropic Console](https://console.anthropic.com/)에서 API Key를 발급합니다.
```bash
export ANTHROPIC_API_KEY="sk-ant-..."
claude
```
또는 `.env` 파일에 저장:
```bash
ANTHROPIC_API_KEY=sk-ant-...
```
> **비용 참고 (2026 기준):** claude-sonnet-4-6 기준 입력 $3/100만 토큰, 출력 $15/100만 토큰.
> 일반적인 개발 세션(30~60분)은 $0.5~2 정도 소요됩니다.
---
## 첫 실행
프로젝트 폴더에서 실행합니다.
```bash
cd my-project
claude
```
대화형 모드가 시작됩니다:
```
✻ Welcome to Claude Code!
>
```
간단한 테스트:
```
> 이 프로젝트 구조를 한국어로 설명해줘
```
Claude Code가 파일을 읽고 분석한 뒤 설명합니다.
---
## 실행 모드 3가지
### 1. 대화형 모드 (기본)
```bash
claude
```
세션이 유지되면서 연속 대화합니다. 가장 많이 쓰는 모드입니다.
### 2. 단일 명령 모드
```bash
claude "package.json의 의존성 목록을 마크다운 표로 정리해줘"
```
명령 하나만 실행하고 종료합니다. 스크립트에서 활용하기 좋습니다.
### 3. 파이프 모드
```bash
cat error.log | claude "이 에러의 원인과 해결 방법을 알려줘"
```
파일 내용을 파이프로 전달합니다.
---
## 핵심 슬래시 커맨드
대화 중 아래 커맨드를 입력하면 동작합니다.
| 커맨드 | 설명 |
|--------|------|
| `/help` | 사용 가능한 커맨드 목록 |
| `/clear` | 대화 기록 초기화 (컨텍스트 리셋) |
| `/compact` | 긴 대화를 요약해 컨텍스트 절약 |
| `/cost` | 현재 세션 API 비용 확인 |
| `/doctor` | 환경 진단 (설치 문제 확인) |
| `/exit` | Claude Code 종료 |
---
## 유용한 단축키
| 단축키 | 동작 |
|--------|------|
| `Ctrl+C` | 현재 실행 중인 작업 중단 |
| `Ctrl+L` | 화면 초기화 |
| `↑ / ↓` | 이전/다음 명령어 히스토리 |
| `Esc` | 입력 취소 |
---
## 동작 방식 이해
Claude Code는 요청을 받으면 **스스로 계획을 세우고 도구를 사용**합니다.
```
사용자: "Next.js 프로젝트에 다크모드 추가해줘"
Claude Code:
1. 프로젝트 파일 목록 확인 (Read)
2. 현재 테마 설정 파악 (Read: tailwind.config.ts)
3. 다크모드 클래스 추가 (Edit: tailwind.config.ts)
4. 토글 컴포넌트 생성 (Write: components/ThemeToggle.tsx)
5. 레이아웃에 컴포넌트 추가 (Edit: app/layout.tsx)
6. 결과 보고
```
각 단계에서 **파일 수정 전 확인을 요청**합니다. `y`를 입력하면 진행, `n`이면 건너뜁니다.
---
## 다음 단계
Claude Code를 최대한 활용하려면 프로젝트 맥락을 알려주는 **CLAUDE.md** 설정이 핵심입니다.
다음 챕터에서 자세히 다룹니다.
---
## 8장 보강 프로세스 적용: 설치 챕터 운영 표준
6~7장 보강에서 사용한 동일 프로세스(대본 패턴 분석 → 실패 패턴 제거 → 실행형 체크리스트)를 06챕터에 적용합니다.
### 유튜브 대본 기반 설치 성공 패턴
입문자 튜토리얼의 공통 패턴은 아래 순서를 지키는 것입니다.
1. **계정/권한 준비**
2. **CLI 설치**
3. **버전 확인**
4. **인증**
5. **첫 대화 실행**
설치만 완료하고 첫 대화를 건너뛰면, 다음 챕터에서 인증/권한 문제를 뒤늦게 만나기 쉽습니다.
### 06챕터 실패 패턴 TOP 5
1. **글로벌 설치 경로 문제**
- 증상: `claude --version` not found
- 대응: Node/npm global path 확인 후 터미널 재시작
2. **API 키 노출**
- 증상: `.env` 또는 커밋 로그에 키가 남음
- 대응: `.env.local` 사용 + Git 추적 제외 확인
3. **프로젝트 루트가 아닌 위치에서 실행**
- 증상: 엉뚱한 파일을 읽거나 맥락 누락
- 대응: `pwd` 확인 후 프로젝트 루트에서 실행
4. **권한 승인 흐름 이해 부족**
- 증상: 수정 거절/중단 후 왜 실패했는지 모름
- 대응: `y/n/s` 승인 의미를 먼저 숙지
5. **설치 후 진단 생략**
- 증상: 다음 챕터에서 환경 이슈 재발
- 대응: `/doctor`, `/help` 최소 1회 실행
### 06챕터 완료 체크리스트 (DoD)
- [ ] `claude --version` 확인 완료
- [ ] 인증 방식(구독/API 키) 1개 확정 완료
- [ ] 프로젝트 루트에서 `claude` 첫 대화 실행 완료
- [ ] `/help`, `/doctor` 실행 결과 확인 완료
- [ ] 시크릿 파일이 Git 추적 제외인지 확인 완료
> **다음 챕터 입력값:** 실행된 프로젝트 루트 경로, 인증 방식, 기본 운영 규칙 초안
공개 문서 변환 코드 (HTML)
<hr>
<h2>title: "Claude Code 설치 및 시작"
slug: "06-claude-code-install"
description: "Claude Code CLI 설치, 인증, 첫 실행까지"
order: 6
date: "2026-03-10"
level: 1
draft: false</h2>
<h1>Claude Code 설치 및 시작</h1>
<blockquote>
<p><strong>이 챕터를 마치면</strong> Claude Code CLI를 설치하고 터미널에서 첫 대화까지 진행할 수 있어요.</p>
</blockquote>
<p>Claude Code는 Anthropic이 만든 CLI 기반 AI 코딩 에이전트예요.
터미널에서 대화하며 <strong>프로젝트 전체를 이해하고 자율적으로 코드를 작성</strong>해 줘요.</p>
<blockquote>
<p><strong>전제 조건:</strong> Node.js 18+ 설치 완료 (<a href="./02-installation">설치 챕터</a> 참고)</p>
</blockquote>
<hr>
<h2>설치</h2>
<div className="float-right w-full md:w-[40%] md:ml-6 mb-4 flex-shrink-0 not-prose">
<a href="https://www.npmjs.com/package/@anthropic-ai/claude-code" target="_blank" rel="noopener noreferrer" className="block rounded-lg overflow-hidden border border-slate-200 shadow-sm hover:shadow-md transition-shadow">
<img src="/images/claude-code-install.png" alt="Claude Code npm 패키지 — @anthropic-ai/claude-code" className="w-full h-auto" />
</a>
</div><p>터미널을 열고 아래 명령어를 실행합니다.</p>
<pre><code class="language-bash">npm install -g @anthropic-ai/claude-code
</code></pre>
<p>설치 확인:</p>
<pre><code class="language-bash">claude --version
# Claude Code 1.x.x
</code></pre>
<hr>
<h2>인증</h2>
<p>Claude Code는 두 가지 방법으로 인증할 수 있습니다.</p>
<h3>방법 1: Claude 구독 사용 (Pro/Max 플랜 — 추천)</h3>
<p>Claude.ai Pro($20/월) 또는 Max 구독자라면 별도 API 비용 없이 사용합니다.</p>
<pre><code class="language-bash">claude
</code></pre>
<p>첫 실행 시 브라우저가 열리며 Claude.ai 로그인 → 권한 허용 순서로 진행합니다.</p>
<h3>방법 2: API Key 사용</h3>
<p><a href="https://console.anthropic.com/">Anthropic Console</a>에서 API Key를 발급합니다.</p>
<pre><code class="language-bash">export ANTHROPIC_API_KEY="sk-ant-..."
claude
</code></pre>
<p>또는 <code>.env</code> 파일에 저장:</p>
<pre><code class="language-bash">ANTHROPIC_API_KEY=sk-ant-...
</code></pre>
<blockquote>
<p><strong>비용 참고 (2026 기준):</strong> claude-sonnet-4-6 기준 입력 $3/100만 토큰, 출력 $15/100만 토큰.
일반적인 개발 세션(30<del>60분)은 $0.5</del>2 정도 소요됩니다.</p>
</blockquote>
<hr>
<h2>첫 실행</h2>
<p>프로젝트 폴더에서 실행합니다.</p>
<pre><code class="language-bash">cd my-project
claude
</code></pre>
<p>대화형 모드가 시작됩니다:</p>
<pre><code>✻ Welcome to Claude Code!
>
</code></pre>
<p>간단한 테스트:</p>
<pre><code>> 이 프로젝트 구조를 한국어로 설명해줘
</code></pre>
<p>Claude Code가 파일을 읽고 분석한 뒤 설명합니다.</p>
<hr>
<h2>실행 모드 3가지</h2>
<h3>1. 대화형 모드 (기본)</h3>
<pre><code class="language-bash">claude
</code></pre>
<p>세션이 유지되면서 연속 대화합니다. 가장 많이 쓰는 모드입니다.</p>
<h3>2. 단일 명령 모드</h3>
<pre><code class="language-bash">claude "package.json의 의존성 목록을 마크다운 표로 정리해줘"
</code></pre>
<p>명령 하나만 실행하고 종료합니다. 스크립트에서 활용하기 좋습니다.</p>
<h3>3. 파이프 모드</h3>
<pre><code class="language-bash">cat error.log | claude "이 에러의 원인과 해결 방법을 알려줘"
</code></pre>
<p>파일 내용을 파이프로 전달합니다.</p>
<hr>
<h2>핵심 슬래시 커맨드</h2>
<p>대화 중 아래 커맨드를 입력하면 동작합니다.</p>
<table>
<thead>
<tr>
<th>커맨드</th>
<th>설명</th>
</tr>
</thead>
<tbody><tr>
<td><code>/help</code></td>
<td>사용 가능한 커맨드 목록</td>
</tr>
<tr>
<td><code>/clear</code></td>
<td>대화 기록 초기화 (컨텍스트 리셋)</td>
</tr>
<tr>
<td><code>/compact</code></td>
<td>긴 대화를 요약해 컨텍스트 절약</td>
</tr>
<tr>
<td><code>/cost</code></td>
<td>현재 세션 API 비용 확인</td>
</tr>
<tr>
<td><code>/doctor</code></td>
<td>환경 진단 (설치 문제 확인)</td>
</tr>
<tr>
<td><code>/exit</code></td>
<td>Claude Code 종료</td>
</tr>
</tbody></table>
<hr>
<h2>유용한 단축키</h2>
<table>
<thead>
<tr>
<th>단축키</th>
<th>동작</th>
</tr>
</thead>
<tbody><tr>
<td><code>Ctrl+C</code></td>
<td>현재 실행 중인 작업 중단</td>
</tr>
<tr>
<td><code>Ctrl+L</code></td>
<td>화면 초기화</td>
</tr>
<tr>
<td><code>↑ / ↓</code></td>
<td>이전/다음 명령어 히스토리</td>
</tr>
<tr>
<td><code>Esc</code></td>
<td>입력 취소</td>
</tr>
</tbody></table>
<hr>
<h2>동작 방식 이해</h2>
<p>Claude Code는 요청을 받으면 <strong>스스로 계획을 세우고 도구를 사용</strong>합니다.</p>
<pre><code>사용자: "Next.js 프로젝트에 다크모드 추가해줘"
Claude Code:
1. 프로젝트 파일 목록 확인 (Read)
2. 현재 테마 설정 파악 (Read: tailwind.config.ts)
3. 다크모드 클래스 추가 (Edit: tailwind.config.ts)
4. 토글 컴포넌트 생성 (Write: components/ThemeToggle.tsx)
5. 레이아웃에 컴포넌트 추가 (Edit: app/layout.tsx)
6. 결과 보고
</code></pre>
<p>각 단계에서 <strong>파일 수정 전 확인을 요청</strong>합니다. <code>y</code>를 입력하면 진행, <code>n</code>이면 건너뜁니다.</p>
<hr>
<h2>다음 단계</h2>
<p>Claude Code를 최대한 활용하려면 프로젝트 맥락을 알려주는 <strong>CLAUDE.md</strong> 설정이 핵심입니다.
다음 챕터에서 자세히 다룹니다.</p>
<hr>
<h2>8장 보강 프로세스 적용: 설치 챕터 운영 표준</h2>
<p>6~7장 보강에서 사용한 동일 프로세스(대본 패턴 분석 → 실패 패턴 제거 → 실행형 체크리스트)를 06챕터에 적용합니다.</p>
<h3>유튜브 대본 기반 설치 성공 패턴</h3>
<p>입문자 튜토리얼의 공통 패턴은 아래 순서를 지키는 것입니다.</p>
<ol>
<li><strong>계정/권한 준비</strong></li>
<li><strong>CLI 설치</strong></li>
<li><strong>버전 확인</strong></li>
<li><strong>인증</strong></li>
<li><strong>첫 대화 실행</strong></li>
</ol>
<p>설치만 완료하고 첫 대화를 건너뛰면, 다음 챕터에서 인증/권한 문제를 뒤늦게 만나기 쉽습니다.</p>
<h3>06챕터 실패 패턴 TOP 5</h3>
<ol>
<li><p><strong>글로벌 설치 경로 문제</strong></p>
<ul>
<li>증상: <code>claude --version</code> not found</li>
<li>대응: Node/npm global path 확인 후 터미널 재시작</li>
</ul>
</li>
<li><p><strong>API 키 노출</strong></p>
<ul>
<li>증상: <code>.env</code> 또는 커밋 로그에 키가 남음</li>
<li>대응: <code>.env.local</code> 사용 + Git 추적 제외 확인</li>
</ul>
</li>
<li><p><strong>프로젝트 루트가 아닌 위치에서 실행</strong></p>
<ul>
<li>증상: 엉뚱한 파일을 읽거나 맥락 누락</li>
<li>대응: <code>pwd</code> 확인 후 프로젝트 루트에서 실행</li>
</ul>
</li>
<li><p><strong>권한 승인 흐름 이해 부족</strong></p>
<ul>
<li>증상: 수정 거절/중단 후 왜 실패했는지 모름</li>
<li>대응: <code>y/n/s</code> 승인 의미를 먼저 숙지</li>
</ul>
</li>
<li><p><strong>설치 후 진단 생략</strong></p>
<ul>
<li>증상: 다음 챕터에서 환경 이슈 재발</li>
<li>대응: <code>/doctor</code>, <code>/help</code> 최소 1회 실행</li>
</ul>
</li>
</ol>
<h3>06챕터 완료 체크리스트 (DoD)</h3>
<ul>
<li><input disabled="" type="checkbox"> <code>claude --version</code> 확인 완료</li>
<li><input disabled="" type="checkbox"> 인증 방식(구독/API 키) 1개 확정 완료</li>
<li><input disabled="" type="checkbox"> 프로젝트 루트에서 <code>claude</code> 첫 대화 실행 완료</li>
<li><input disabled="" type="checkbox"> <code>/help</code>, <code>/doctor</code> 실행 결과 확인 완료</li>
<li><input disabled="" type="checkbox"> 시크릿 파일이 Git 추적 제외인지 확인 완료</li>
</ul>
<blockquote>
<p><strong>다음 챕터 입력값:</strong> 실행된 프로젝트 루트 경로, 인증 방식, 기본 운영 규칙 초안</p>
</blockquote>