CH01 · Claude Code 입문 & 세팅

1-1. 설치 & 첫 실행

설명 영상이 챕터를 영상으로 먼저 훑어보세요 · 8분 10초

코딩을 한 번도 안 해보셨어도 괜찮습니다. 이 페이지에서는 검은 입력 창(터미널)을 여는 법부터, AI 비서(에이전트)를 내 컴퓨터에 설치하고 깨워 첫 대화를 나누는 순간까지, 막히기 쉬운 곳마다 손을 잡고 한 단계씩 함께 갑니다.


1. 터미널이 무엇인가요? (검은 창 두려움 없애기)

설치 이야기를 하기 전에 가장 먼저 친해져야 할 친구가 있습니다. 바로 터미널입니다.

⌨️
터미널 = 컴퓨터에 글자로 명령을 내리는 검은 입력 창
마우스로 아이콘을 더블클릭하는 대신, 한 줄의 글자를 입력해 컴퓨터에게 "이걸 해줘"라고 시키는 곳입니다. 해커들이 쓰는 무서운 도구가 아니라, 그냥 버튼 대신 글자로 누르는 리모컨이라고 생각하세요.

지금까지는 마우스로만 컴퓨터를 써오셨을 겁니다. 하지만 AI 비서(에이전트)는 이 검은 창 안에서 살아 움직입니다. 그래서 우리는 이 창을 여는 법부터 익혀야 합니다. 딱 한 번만 열어보면 "별것 아니네"라는 생각이 드실 거예요.

macOS (맥)

Spotlight로 1초 만에

  • Cmd + Space(스페이스바)를 동시에 누릅니다.
  • 검색창에 terminal을 입력하고 엔터.
  • 흰색 또는 검은색 글자 창이 뜨면 성공입니다.
Windows (윈도우)

PowerShell 또는 Git Bash

  • 시작 메뉴(화면 왼쪽 아래 윈도우 아이콘) 클릭.
  • PowerShell을 검색해 실행합니다.
  • 맥과 명령어를 똑같이 쓰고 싶다면 Git Bash를 설치해 그 안에서 진행하셔도 좋습니다.

💡 입력 후에는 꼭 엔터: 터미널은 글자를 한 줄 쓰고 엔터(Return)를 눌러야 비로소 실행됩니다. 또 명령을 실행하면 커서가 한참 깜빡일 때가 있는데, 멈춘 게 아니라 일하는 중입니다. 당황하지 말고 기다려 주세요.

이 페이지에는 "아래 명령을 그대로 붙여넣고 엔터"라는 안내가 자주 나옵니다. 그런데 터미널은 우리가 평소 쓰던 Ctrl+V가 운영체제마다 조금씩 다릅니다. 미리 한 번만 익혀 두면 끝까지 막히지 않아요. 명령을 복사할 땐 강의 노트의 코드 오른쪽 복사 버튼(📄)을 누르거나, 글자를 마우스로 드래그한 뒤 복사하면 됩니다.

환경 붙여넣기 단축키
macOS (맥) 터미널 Cmd + V
Windows PowerShell Ctrl + V 또는 창 안에서 마우스 우클릭
Git Bash (윈도우) 마우스 우클릭 또는 Shift + Insert

💡 붙여넣은 줄이 안 보여도 정상: 터미널에 따라 붙여넣어도 글자가 늦게 뜨거나 줄이 길어 한 줄로 이어 보일 수 있습니다. 당황하지 말고 엔터를 한 번 누르면 실행됩니다. 혹시 여러 줄을 붙여넣으면 "정말 붙여넣을까요?" 같은 확인이 뜰 수 있는데, 그대로 진행하셔도 됩니다.

2. Node.js와 npm — 왜 이것부터 깔아야 하나요?

Claude Code는 아래 ①번 네이티브 설치로 깔면 Node.js 없이도 돌아갑니다. 하지만 대안 도구인 Codex 설치, 내 웹앱을 브라우저로 미리 보는 도구, 4장의 배포 도구가 모두 Node.js와 npm으로 설치돼요. 그래서 처음에 한 번 깔아 두고 갑니다.

Node.js 란?

AI 도구가 실행되는 엔진(실행 환경)입니다. 자동차로 치면 엔진룸이에요. 우리가 직접 다룰 일은 거의 없지만, 이게 깔려 있어야 도구가 시동을 겁니다.

npm 이란?

Node.js와 함께 따라오는 도구 설치기(앱 스토어 같은 것)입니다. npm install 한 줄이면 전 세계 개발자들이 만든 프로그램을 내 컴퓨터에 자동으로 내려받아 줍니다.

좋은 소식은 Node.js를 설치하면 npm이 자동으로 따라온다는 점입니다. 둘을 따로 깔 필요가 없어요. 그럼 내 컴퓨터에 이미 깔려 있는지부터 확인해 봅시다.

A

설치 여부 확인: 터미널에 아래를 입력하고 엔터를 칩니다.
node -v

B

성공한 경우: v22.x.x나 v24.x.x처럼 22 이상의 버전 번호가 한 줄 출력되면 준비된 것입니다. 다음 단계로 넘어가세요. v18, v20처럼 더 낮은 숫자가 나오면 아래 C처럼 새 LTS를 설치해 주세요.

C

에러가 난 경우: command not found 같은 글자가 뜨면 아직 없는 것입니다. nodejs.org에 접속해 큰 버튼으로 표시된 LTS(장기 안정 버전)를 내려받아 설치한 뒤, 터미널을 완전히 껐다가 다시 켜고 node -v를 한 번 더 확인합니다. 윈도우라면 받은 설치 파일(설치 마법사)을 더블클릭하고 그냥 'Next(다음)'만 계속 누르면 됩니다. 따로 건드릴 옵션은 없어요.

💡 "껐다 켜기"가 진짜 중요합니다: 새 프로그램을 설치한 직후의 터미널 창은 변화를 아직 모릅니다. 반드시 창을 닫고 새로 열어야 node -v가 새 버전을 인식합니다. 설치는 됐는데 자꾸 에러가 난다면 십중팔구 이 한 가지를 놓친 것입니다.

3. '에이전트'란 정확히 무엇인가요?

설치할 도구의 정체를 먼저 이해하고 가면 훨씬 든든합니다. 우리가 깔 Claude Code는 단순한 챗봇이 아니라 에이전트입니다.

🤖
에이전트 = 내 컴퓨터를 직접 다루는 AI 비서
웹사이트 챗봇은 답만 글로 알려주지만, 에이전트는 한 발 더 나아가 내 폴더의 파일을 직접 읽고 쓰고, 터미널 명령까지 대신 실행합니다. "뽀모도로 타이머 만들어줘"라고 한국어로 말하면, 정말로 파일을 만들고 코드를 채워 넣어 줍니다.

우리가 에이전트에게 한국어로 내리는 지시문을 프롬프트라고 부릅니다. 즉 이 강의의 핵심은 "코드를 외우는 것"이 아니라 "에이전트에게 프롬프트로 정확히 지시하는 법"을 익히는 것입니다.

4. Claude Code 설치하기 (두 갈래 길)

설치 방법은 두 가지입니다. 둘 중 하나만 성공하면 됩니다. 맥과 윈도우 모두 더 쉽고 깔끔한 ①번(네이티브 설치)을 먼저 권합니다. 네이티브 설치는 새 버전이 나오면 알아서 업데이트도 해 줍니다.

1

맥/리눅스: 터미널에 아래 한 줄을 그대로 붙여넣고 엔터.
curl -fsSL https://claude.ai/install.sh | bash
윈도우: PowerShell을 열고(관리자 권한 필요 없음) 아래 한 줄을 붙여넣고 엔터.
irm https://claude.ai/install.ps1 | iex
PowerShell이 아니라 명령 프롬프트(CMD)라면: curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

2

설치 확인: 내려받는 동안에는 화면에 진행 표시가 거의 없을 수 있어요. 멈춘 게 아니니 기다려 주세요. 끝나면 터미널 창을 새로 열고 claude --version을 입력합니다. 버전 번호가 나오면 성공입니다. (공식 안내는 Claude Code 설치 문서에서도 확인할 수 있어요.)

1

설치 명령 실행: 터미널에 아래를 붙여넣고 엔터. (앞에 sudo를 절대 붙이지 마세요. 권한·보안 문제의 원인이 됩니다.)
npm install -g @anthropic-ai/claude-code

2

설치 진행 화면: 점(...)과 패키지 이름이 흐르다가 멈추고 새 입력 줄이 나타나면 완료입니다. 에러 글자가 없으면 성공으로 봐도 됩니다.

💡 맥에서 EACCES 권한 에러가 떴다면? (이 처방은 맥 전용입니다.) sudo로 우회하지 마세요. 올바른 해결책은 npm이 도구를 설치하는 위치를 내 홈 폴더로 바꿔 주는 것입니다. 아래 두 줄을 차례로 실행한 뒤 터미널을 껐다 켜고 다시 설치하면 깔끔하게 해결됩니다. (가장 확실한 길은 위 ①번 네이티브 설치입니다.)

npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc

💡 위 둘째 줄의 ~/.zshrc는 최신 맥(기본 셸이 zsh) 기준입니다. 구형 맥이나 bash를 쓰신다면 ~/.zshrc 대신 ~/.bash_profile 또는 ~/.bashrc에 같은 한 줄을 넣어야 합니다. 내 셸이 무엇인지 모르겠다면, 위 두 줄을 그대로 에이전트에게 붙여넣고 "내 셸이 무엇이고, 이 줄을 어느 파일에 추가해야 하냐"고 한국어로 물어보세요. 어디에 넣을지까지 알려 줍니다.

💡 윈도우 사용자라면? 위의 ~/.zshrc 수정은 맥 전용이니 따라 하지 마세요. 다행히 윈도우에서는 EACCES 권한 에러가 거의 나지 않습니다. 윈도우에서 가장 흔한 문제는 설치는 됐는데 claude를 쳤을 때 'claude'은(는) 인식할 수 없는 ...(command not found에 해당)이 뜨는 경우인데, 처방은 단순합니다. ① 터미널 창을 완전히 닫았다가 새로 열기(그래도 안 되면 PC를 재부팅) → ② 그래도 안 잡히면 설치 경로가 PATH에 아직 안 들어간 것입니다. ①번 네이티브 설치 명령을 한 번 더 실행하고 터미널을 다시 열어 보세요. (npm으로 설치했다면 nodejs.org에서 LTS를 다시 설치하면 PATH가 자동으로 잡힙니다.) 그래도 막히면 7번의 황금률대로 에러 글자를 그대로 복사해 도움을 요청하세요.

여기가 비개발자분들이 가장 많이 헤매는 지점입니다. 에이전트는 "지금 내가 들어와 있는 폴더"를 작업장 삼아 그 안의 파일을 읽고 씁니다. 그런데 터미널을 켜면 처음에는 여러분의 홈 폴더(내 컴퓨터 사용자 폴더)라는 넓은 곳에 떨어집니다. 그래서 claude를 바로 치기 전에, 실습용 폴더를 하나 만들고 그 폴더 안으로 이동해 줘야 합니다. 아래 세 줄을 한 줄씩 차례로 입력하고 엔터를 치세요. (맥·윈도우 PowerShell·Git Bash에서 모두 똑같이 동작합니다.)

3

바탕화면으로 이동: 결과물을 눈으로 찾기 쉽게 바탕화면(Desktop) 안에 만들겠습니다.
cd Desktop  (cd = "이 폴더 안으로 들어가라"는 이동 명령)

4

새 폴더 만들기: vibecoding이라는 빈 폴더를 새로 만듭니다.
mkdir vibecoding  (mkdir = "이 이름으로 새 폴더를 만들어라")

5

그 폴더 안으로 들어가기: 방금 만든 폴더 안으로 이동합니다.
cd vibecoding

💡 "폴더 안에 들어왔다"는 어떻게 알 수 있나요? 입력 줄(커서) 앞에 표시되는 글자가 vibecoding처럼 방금 들어온 폴더 이름으로 바뀌면 성공입니다. 혹시 지금 내가 어디 있는지 헷갈리면 pwd를 입력해 보세요. 현재 위치한 폴더의 전체 경로가 한 줄로 출력됩니다(맨 끝이 vibecoding이라는 폴더 이름으로 끝나면 제대로 들어온 것). cd Desktop에서 no such file or directory가 뜨면 바탕화면 폴더 이름이 다른 경우이니, 그 줄은 건너뛰고 mkdir vibecoding부터 진행해도 됩니다. 윈도우 주의: 바탕화면이 OneDrive로 동기화돼 있으면 cd Desktop이 엉뚱한 위치를 가리켜 폴더가 안 보일 수 있습니다. 이럴 땐 그 줄을 건너뛰고 지금 있는 곳(홈 폴더)에 바로 mkdir vibecoding → cd vibecoding으로 만들어도 실습에는 전혀 지장이 없어요.

6

실행: 방금 들어온 vibecoding 폴더 안에서 claude를 입력하고 엔터. 그러면 에이전트 대화창이 켜집니다.

7

브라우저 로그인: 처음 실행하면 로그인 안내가 뜨고 자동으로 브라우저가 열립니다. Anthropic 계정으로 로그인 → 승인을 누르면 터미널로 돌아와 연결이 완료됩니다.

8

"이 폴더에서 작업할까요?" 승인: 에이전트는 안전을 위해 처음에 "이 폴더의 파일에 접근/작업해도 될까요?" 같은 확인을 물을 수 있습니다. 당황하지 말고 방향키(↑↓)로 허용(Yes)을 골라 엔터를 누르면 됩니다. 내가 직접 만든 폴더이니 안심하고 허용하세요.

9

성공 화면: 환영 메시지와 함께 한국어를 입력할 수 있는 빈 입력 줄이 보이면 준비 끝! 이제 여기에 프롬프트를 쓰면 됩니다.

claude 첫 실행 시 보이는 터미널 환영 화면
✅ 이 화면이 보이면 성공 — claude를 실행하면 환영 메시지가 뜨고, 핑크 박스 아래 > 입력 줄에 한국어로 바로 지시하면 됩니다.

설치가 진짜로 됐는지 확인하는 가장 좋은 방법은 에이전트에게 말을 한 번 걸어 보는 것입니다. 입력 줄에 아래 문장을 그대로 붙여넣고 엔터를 쳐 보세요.

"안녕! 너를 처음 써봐. 지금 이 폴더 안에 어떤 파일이 있는지 한국어로 알려줄래?"

에이전트가 폴더 안 파일 목록을 한국어로 차분히 읊어 주면, 설치와 로그인이 모두 정상이라는 확실한 증거입니다. 축하합니다 — 이제 여러분의 첫 AI 비서가 깨어났습니다.

💡 프로젝트 지침 파일은 CLAUDE.md: Claude Code는 폴더 안에 CLAUDE.md라는 평문(그냥 한국어로 적은) 메모 파일이 있으면 매번 그 내용을 먼저 읽고 시작합니다. "버튼 색은 항상 핑크로" 같은 우리 팀 규칙을 적어 두면 에이전트가 알아서 지켜 줍니다. 이건 1장 뒤에서 자세히 다룹니다.

5. 막힐 때 대처하는 법 (가장 중요한 생존 기술)

설치 단계에서 에러는 누구에게나 납니다. 부끄러운 일이 전혀 아니에요. 중요한 건 당황하지 않고 에러 글자를 그대로 활용하는 것입니다. 아래는 비개발자분들이 가장 자주 만나는 4가지 상황과 그 처방입니다.

화면에 뜨는 글자 무슨 뜻인가 이렇게 하세요
command not found 그 프로그램이 아직 설치 안 됐거나, 설치 직후 터미널을 안 껐다 켰음 설치를 다시 확인하고, 터미널을 완전히 껐다 켠 뒤 재시도
네이티브 설치 후
claude: command not found
설치 스크립트가 PATH(명령을 찾는 경로)를 추가했지만 현재 창이 아직 모름 먼저 터미널을 완전히 껐다 켜기. 그래도 안 잡히면, 설치가 끝날 때 화면 맨 마지막에 안내된 한 줄(보통 export PATH=... 형태)을 그대로 복사해 실행한 뒤 다시 claude를 입력. 그래도 안 되면 위 ②번 npm 설치로 다시 시도. claude doctor를 입력하면 설치 상태를 점검해 줍니다
EACCES / permission denied 설치 권한 문제 (맥에서 흔함) sudo 금지. 위 4번의 npm prefix 변경 또는 네이티브 설치 이용
브라우저가 안 열려요 로그인 창이 자동으로 안 뜸 터미널에 표시된 로그인 주소(URL)를 직접 복사해 브라우저 주소창에 붙여넣기
회사 네트워크에서 막혀요 사내 방화벽·프록시가 설치를 차단 개인 인터넷(휴대폰 테더링 등)으로 시도하거나 IT 담당자에게 문의

★ 막힐 때의 황금률 (온라인 라이브 필수 꿀팁):
온라인 라이브는 강사가 여러분의 화면을 직접 볼 수 없어, 말로 증상을 설명하면 시간이 오래 걸립니다. 그러니 터미널에 붉은 글씨나 Error 문구가 뜨면, 절대 손으로 옮겨 적지 말고 그 문장을 마우스로 드래그해 그대로 복사(맥 Cmd+C / 윈도우 Ctrl+C)한 뒤, ① 에이전트에게 "이 에러 어떻게 고쳐?"라고 붙여넣거나 ② 줌(Zoom) 채팅창·패들릿에 그대로 올려 주세요. 빨간 글자 안에 이미 해결의 90%가 들어 있습니다.

에이전트가 이미 깨어 있다면(설치를 마쳤다면), 가장 빠른 디버깅은 그 에러를 에이전트에게 그대로 보여 주고 한국어로 물어보는 것입니다. 아래 틀을 복사해 [ ] 안에 복사한 에러 글자를 붙여넣고 보내 보세요.

"방금 터미널에서 이런 에러가 떴어. 이게 무슨 뜻인지, 그리고 비개발자도 따라 할 수 있게 어떻게 고치는지 한국어로 한 단계씩 알려줄래? 에러 내용: [여기에 복사한 빨간 에러 글자를 붙여넣기]"

이것만 기억하세요

① 터미널은 글자로 누르는 리모컨일 뿐입니다. ② node -v로 Node.js(22 이상)를 먼저 확인해 두면 이후 실습이 편합니다. ③ Claude Code 설치는 맥·윈도우 모두 네이티브 설치가 기본, 막히면 npm(sudo 금지). ④ claude를 치기 전에 mkdir로 폴더를 만들고 cd로 그 안에 들어가는 것을 잊지 마세요 — 에이전트는 "지금 들어와 있는 폴더"에서 일합니다. ⑤ Claude Code가 부담되면 이미 쓰는 계정으로 Codex(codex)나 구글의 Antigravity CLI(agy)를 골라도 실습은 동일합니다. ⑥ 막히면 빨간 에러 글자를 그대로 복사해 붙여넣는 것이 가장 빠른 해결책입니다.

다음 클립
1-2. 대안 환경 & 도구 원리
이어보기 →