제 0강. 클로드 코드 설치하기 — 당신이 쓰는 건 클로드 코드가 아닐 수 있다

꿀팁 — 이것만 알면 시킬 수 있다

확인 한 줄이 전부다.

터미널에서 아래를 친다.

claude --version

2.1.x 같은 버전 번호가 뜨면 — 진짜 클로드 코드다. 이 과정의 1강부터 11강까지 전부 돈다.

명령어를 못 찾는다고 나오거나, 당신이 지금 쓰는 게 Cursor·Antigravity·Windsurf 안의 채팅창이라면 — 그건 클로드 코드가 아니다. 같은 Claude 모델을 쓰더라도 다른 프로그램이다. 이 과정의 자율주행은 거기서 돌지 않는다.

기억할 한 문장:

에이전트 ≠ 모델. 같은 Opus를 써도, 구동하는 프로그램이 다르면 능력이 다르다.

설치 한 줄 (Mac / Ubuntu / WSL):

curl -fsSL https://claude.ai/install.sh | bash

Windows는 WSL 또는 Docker가 먼저다. 아래 본문에서 다룬다.

찍먹 체험

같은 작업을 시켜서, CLI와 IDE 채팅의 차이를 눈으로 확인한다. 3분이면 된다.

클로드 코드(CLI)에서:

“빈 폴더에 hello.py를 만들어. 일부러 문법 오류를 하나 넣고, 실행해서 에러를 확인한 다음, 스스로 고쳐서 다시 실행해. ‘Hello’가 출력될 때까지.”

CLI 클로드 코드는 — 파일을 만들고, 직접 실행하고, 에러를 읽고, 고치고, 다시 돌린다. 당신에게 매 단계를 묻지 않는다. 자율 루프가 돈다.

같은 문장을 IDE 확장 채팅(Cursor/Antigravity/Windsurf의 채팅창)에 넣으면 — 코드는 제안하지만, 실행은 당신이 버튼을 눌러야 하고, 에러를 다시 복사해서 붙여넣어야 하고, 매 단계 승인을 기다린다. 루프가 사람을 거쳐야 닫힌다.

이 차이가 0강의 전부다. 그리고 이 과정 전체가 전자를 전제로 설계되어 있다.

왜 이렇게 시켜야 하는가

당신은 아마 이미 “클로드 코드"로 뭔가를 만들어봤을 것이다. 유튜브 강의를 보고, 채팅창에 말을 걸고, 코드가 나오는 것을 봤다.

그런데 한 가지 묻고 싶다. 당신이 쓴 그것이, 정말 클로드 코드가 맞는가?

이 질문이 사소해 보인다면, 실제 온보딩 현장의 이야기를 들어보라.

에이전트 ≠ 모델

한 사용자가 바이브 코딩으로 만든 앱이 터져서 도움을 요청했다. 그는 “클로드 코드로 개발 중"이라고 했다. 며칠을 헤맸다. 시키는 대로 안 되고, AI가 매 갈림길에서 “A안, B안, C안 중 뭘 할까요?“라고 되물어서 진도가 안 나갔다.

원인은 그의 판단력이 아니었다. 그가 쓰던 것은 Antigravity IDE 확장의 Claude 채팅이었다. CLI 클로드 코드가 아니었다. 둘 다 Claude Opus 모델을 쓴다. 모델은 같다. 그런데 결과가 완전히 달랐다.

왜? 모델은 같아도 에이전트가 다르기 때문이다.

• 모델(Model): Opus, Sonnet 같은 두뇌. 글을 읽고 쓰는 능력 그 자체.
• 에이전트(Agent): 그 두뇌를 구동하는 프로그램. 어떤 시스템 프롬프트를 주는가, 어떤 도구(파일 읽기/쓰기/명령 실행)를 쥐여주는가, 사람 승인 없이 어디까지 스스로 하는가 — 전부 에이전트가 정한다.

같은 말(모델)이라도, 굴레 없이 들판에 풀어놓느냐 안장과 마구를 채워 기수가 올라타느냐에 따라 갈 수 있는 곳이 다르다. 에이전트가 바로 그 안장과 마구다 — 고삐(reins)를 걸 수 있게 해주는 장치. (5강에서 다시 만난다.)

그래서 어설픈 에이전트는 안 된다 — 왜 이 급의 에이전트인가

에이전트마다 급이 있다. 그리고 이 과정(1강~11강)이 요구하는 급은 한 가지 기준으로 갈린다.

이 과정의 핵심은 한 문장이다.

AI가 코드를 짜고, 기계가 검증하고, 당신은 “통과했어?“만 확인한다.

이게 돌아가려면, AI가 스스로 검증 도구를 실행하고 그 결과를 읽어 다음 행동을 정해야 한다. yongol validate를 돌려 에러를 읽고, 고치고, 다시 돌리는 루프 — 이걸 사람이 매번 중개하면 자율이 아니라 노동이다.

자율 루프 가능:
  AI가 validate 실행 → 에러 읽음 → 수정 → 다시 validate → 통과 → 다음
  (사람 개입 0회)

매 단계 사람 중개:
  AI가 "validate를 이렇게 실행하세요" → 사람이 복사·실행 →
  결과를 사람이 복사 → AI에게 붙여넣기 → AI 수정안 → 사람이 또 실행...

3강 Hurl, 4강 yongol, 6강 tsma, 8강 filefunc — 전부 CLI 도구다. AI가 자율로 돌려야 의미가 있다. 이 루프를 못 도는 에이전트로는 이 과정의 절반이 작동하지 않는다.

그러니 “어설픈 에이전트"의 기준은 브랜드가 아니라 이 한 질문이다:

이 에이전트가 yongol validate / hurl / tsma를 스스로 실행하고, 결과를 읽어 다음 행동을 정하는가? 아니면 매 단계 내가 복사·승인을 중개해야 하는가?

• 전자면 — reins를 걸 수 있는 에이전트다. (CLI 클로드 코드가 여기 해당한다.)
• 후자면 — 어설픈 에이전트다. 모델이 아무리 똑똑해도 이 과정에선 막힌다.

주의: “IDE 확장 = 무조건 안 됨"이 아니다. Cursor·Windsurf의 에이전트 모드처럼 명령을 자율 실행하고 루프를 도는 것도 있다. 반대로 같은 제품 안의 단순 채팅 모드는 매 단계 사람을 거친다. 제품 이름이 아니라 위 기준으로 판별하라. 실제 온보딩 현장에서 막혔던 것도 “IDE라서"가 아니라, 쓰던 채팅 모드가 CLI 루프를 자율로 못 돌렸기 때문이다.

그래서 0강이 강 입구다. 도구를 잘못 고르면, 1강부터 11강까지가 전부 거짓말이 된다.

유튜브의 함정

문제는 이거다. 유튜브와 커뮤니티의 바이브 코딩 강의 대부분이 자율 루프를 도는 에이전트와 단순 채팅 모드를 구분하지 않고 둘 다 “클로드 코드"라고 부른다.

그래서 초심자는 차이를 알 방법이 없다. 채팅창에 말을 걸면서 “나 클로드 코드 쓰는 중"이라고 믿는다. 그리고 강의대로 안 되는 이유를 자기 탓으로 돌린다.

아니다. 도구를 잘못 고른 것이다. 정확히는, 유튜브가 도구를 잘못 알려준 것이다. 위의 한 가지 기준 — “스스로 CLI를 돌리는가” — 만 쥐고 있으면 이 함정에 빠지지 않는다.

클로드 코드 설치하기

이 과정은 Ubuntu(또는 WSL) 환경을 기준으로 한다. Mac 사용자도 대부분 동일하다.

사전 준비

1. Anthropic 계정: https://console.anthropic.com 에서 가입
2. 구독 플랜: Claude Pro($20/월), Max($100/월 또는 $200/월) 중 선택. Max가 사용량 제한이 넉넉하다
3. Ubuntu / Mac / WSL 또는 Docker: Windows 사용자는 아래 두 경로 중 하나를 고른다

Mac · Ubuntu · WSL 안에서 — 네이티브 설치 (권장)

Node.js가 필요 없는 가장 간단한 방법이다.

curl -fsSL https://claude.ai/install.sh | bash

설치가 끝나면 확인한다.

claude --version

2.1.x 같은 버전 번호가 뜨면 성공이다.

Windows A안: WSL (권장)

Windows PowerShell을 관리자 권한으로 열고 실행한다.

wsl --install

이 한 줄이 WSL 활성화, Linux 커널 다운로드, Ubuntu 설치를 전부 처리한다. 재부팅 후 Ubuntu가 열리면서 사용자 이름과 비밀번호를 물어본다. 소문자로 된 짧은 이름을 입력한다.

주의: 앞으로의 모든 작업은 Ubuntu 터미널 안에서 한다. PowerShell이나 CMD에서 클로드 코드를 설치하면 “Windows is not supported” 에러가 난다.

그 다음 위의 네이티브 설치 한 줄을 Ubuntu 안에서 실행한다.

WSL 팁: 프로젝트는 반드시 Linux 파일 시스템(/home/사용자명/)에 둔다. Windows 쪽(/mnt/c/)에 두면 파일 읽기가 극심하게 느려진다.

Windows B안: Docker (WSL이 막힐 때)

회사 정책이나 환경 문제로 WSL이 안 되는 경우, Docker로 Linux 컨테이너를 띄워서 그 안에서 클로드 코드를 쓴다.

# 프로젝트 폴더에서, ubuntu 컨테이너를 띄우고 현재 폴더를 마운트
docker run -it -v "$(pwd)":/work -w /work ubuntu:24.04 bash

# 컨테이너 안에서
apt update && apt install -y curl
curl -fsSL https://claude.ai/install.sh | bash
claude --version

-v "$(pwd)":/work가 당신의 프로젝트 폴더를 컨테이너 안 /work에 연결한다. 컨테이너 안에서 작업한 결과가 그대로 당신 폴더에 남는다.

방법 보충: npm으로 설치

이미 Node.js 경험이 있는 사람을 위한 방법이다. 처음이라면 위의 네이티브 설치를 쓴다.

# nvm 설치 후 Node.js LTS
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install --lts

# 클로드 코드 설치
npm install -g @anthropic-ai/claude-code

주의: sudo npm install -g는 쓰지 않는다. 권한 문제와 보안 위험이 생긴다.

최초 실행과 인증

# 프로젝트 폴더로 이동 (없으면 만든다)
mkdir -p ~/projects/my-first-app
cd ~/projects/my-first-app

# 클로드 코드 실행
claude

처음 실행하면 브라우저가 열리면서 Anthropic 로그인을 요청한다. 로그인하면 인증이 완료되고, 다음부터는 자동으로 연결된다.

설치 확인 체크리스트

이 세 가지가 전부 체크되면, 1강으로 넘어갈 준비가 된 것이다.

• claude --version이 2.1.x 버전 번호를 출력하는가
• claude를 실행하면 프롬프트(대화창)가 뜨는가
• 브라우저 로그인으로 인증이 완료되었는가
• 위의 찍먹 체험에서, AI가 스스로 파일을 만들고 실행하고 고쳤는가 (매 단계 승인을 요구하지 않았는가)

마지막 항목이 가장 중요하다. AI가 알아서 명령을 실행하고 에러를 고쳤다면 — 당신은 진짜 클로드 코드를 쓰고 있다.

IDE 확장은 보조로만

Cursor, Antigravity, Windsurf가 나쁜 도구라는 말이 아니다. 코드를 눈으로 보면서 한 줄씩 고치는 데는 훌륭하다. 프로그래머에게는 좋은 도구다.

다만 이 과정의 자율주행은 CLI에서 한다. IDE 확장은 코드를 들여다보는 보조 창으로 쓰고, “만들고 검증하고 잠그는” 루프는 클로드 코드 CLI에 맡긴다. 둘을 같이 쓰되, 역할을 구분한다.

실습: 진짜를 확인하기

목표: 내가 쓰는 것이 CLI 클로드 코드임을 확인하고, 자율 루프를 한 번 돌려본다.

단계 1 — 설치 확인

claude --version

버전이 2.1.x로 나오는지 확인한다. 안 나오면 위의 설치 절차로 돌아간다. Windows면 WSL(A안) 또는 Docker(B안) 중 하나를 먼저 세팅한다.

단계 2 — 자율 루프 관찰

claude를 실행하고 빈 폴더에서 시킨다:

빈 폴더에 hello.py를 만들어. 일부러 문법 오류를 하나 넣고,
실행해서 에러를 확인한 다음, 스스로 고쳐서 다시 실행해.
"Hello"가 출력될 때까지.

관찰할 것:

• AI가 파일을 직접 만드는가? (당신이 코드를 복사·붙여넣기하지 않는가)
• AI가 python hello.py를 직접 실행하는가?
• 에러가 나면 AI가 스스로 읽고 고치는가?
• 이 전 과정에서 당신이 한 일은 처음 한 문장과 (필요 시) 실행 승인뿐인가?

전부 “그렇다"이면 — 당신은 게이트를 통과했다. 1강으로 간다.

(IDE 채팅을 쓰고 있었다면) 같은 문장을 IDE 채팅창에도 넣어보고, 어디서 막히는지 직접 비교해본다. 이 차이를 한 번 체감하면, 왜 0강이 필요한지 평생 잊지 않는다.

정리

1. 에이전트 ≠ 모델. 같은 Claude 모델이라도, 구동 프로그램(에이전트)이 다르면 능력이 완전히 다르다.
2. 유튜브가 “클로드 코드"라고 부르는 것의 상당수는 자율 루프를 못 도는 단순 채팅 모드다. 판별 기준은 브랜드가 아니라 “스스로 CLI를 돌리는가"다.
3. 이 과정은 CLI를 전제로 설계되었다. 3강 Hurl, 4강 yongol, 6강 tsma, 8강 filefunc — 전부 AI가 자율로 실행해야 의미가 있는 CLI 도구다.
4. 설치는 한 줄. curl -fsSL https://claude.ai/install.sh | bash. Windows는 WSL 또는 Docker가 먼저.
5. 게이트 통과 기준: claude --version이 2.1.x를 뱉고, AI가 스스로 파일을 만들고 실행하고 고친다.

도구를 잘못 고르면, 다음 열한 강이 전부 거짓말이 된다. 강 입구를 여기서 막았다.

다음 강 예고: “AI에게 시키는 법.” 이제 진짜 클로드 코드를 쥐었으니, 코드를 모르는 사람이 AI에게 무엇을, 어떻게 시키는지 배운다.

과제

1. 내 도구 정체 확인하기: 지금까지 “클로드 코드"라고 믿고 쓰던 것이 CLI인지 IDE 채팅인지 확인한다. claude --version이 답이다.
2. 자율 루프 한 번 돌리기: 위 실습의 hello.py 과제를 끝까지 돌려보고, AI가 사람 개입 없이 몇 단계를 스스로 처리했는지 센다.
3. (Windows 사용자) 환경 정하기: WSL과 Docker 중 본인 환경에서 되는 것을 하나 골라 세팅을 마친다.

연관 글

• 코딩 에이전트는 왜 작동하고 왜 무너지는가 — 에이전트의 자율적 검증 루프가 작동하는 조건과 무너지는 조건. 0강의 “왜 CLI 자율 루프인가"의 이론적 배경.
• Reins Engineering — 고삐 있는 AI — 울타리(하네스)와 고삐(Reins)의 차이, 그리고 에이전트를 reins의 기판으로 보는 전체 프레임.

더 읽을거리 (외부)

• Agent Harness Engineering — Addy Osmani. “괜찮은 모델 + 훌륭한 하네스가, 훌륭한 모델 + 나쁜 하네스를 이긴다.” 모델을 고정하고 하네스만 바꿔 벤치마크 순위가 뒤집힌 사례. 에이전트 ≠ 모델의 결정판.
• Agents are models using tools in a loop — Simon Willison. 에이전트의 표준 정의. 도구 결과가 모델로 되먹임되는 “loop"가 진짜 에이전트와 마케팅 용어를 가른다.
• Which AI Coding Harness Actually Works Without You? — Paweł Józefiak. 코딩 도구를 Orchestrator(자율) / Pair Programmer(단계별 지시) / Supervised IDE(단독 결정 거부) 세 범주로 구분. 이 셋을 혼동하는 게 핵심 실수 — 0강 “유튜브의 함정"과 정확히 일치.

Reins Engineering 전체 강의

출처

• Anthropic. “Claude Code overview.” Anthropic Documentation. link
• Anthropic. “Set up Claude Code.” Anthropic Documentation. link
• Karpathy, A. (2025). “Vibe coding” — 코드를 읽지 않고 느낌으로 시키는 코딩의 어원.