1장. 에이전트에게 개발을 맡긴다 — 설치와 첫 지시

이 장이 끝나면: 내 PC에 Claude Code가 설치·인증되어 있고, 코드를 한 줄도 직접 치지 않은 채 우리 회사의 신규 서비스 '온티켓(OnTicket)'의 첫 페이지가 브라우저에 떠 있다.

1.1 개념 — 대화형 AI에서 에이전트형 AI로

지금까지의 방식: 복사-붙여넣기 루프

AI로 개발을 해 본 사람이라면 대부분 이런 식으로 일해 왔을 것이다.

1. 챗봇 웹사이트를 연다
2. "장바구니 기능 코드 짜줘"라고 묻는다
3. 답변으로 온 코드를 마우스로 긁어 복사한다
4. 내 편집기에 붙여넣고 저장한다
5. 실행해 본다. 에러가 난다
6. 에러 메시지를 복사해서 다시 챗봇에 붙여넣는다
7. 2번으로 돌아간다

이 방식에는 구조적인 한계가 있다. 챗봇은 말만 할 수 있다. 내 컴퓨터의 파일을 직접 만들 수 없고, 프로그램을 실행할 수 없고, 에러 화면을 직접 볼 수도 없다. 그래서 챗봇과 내 컴퓨터 사이를 오가며 코드와 에러를 실어 나르는 택배 기사 역할을 사람이 해야 했다. 기능 하나에 수십 번씩.

문제는 시간만이 아니다. 이 방식에서는 AI가 전체 맥락을 모른다. 내 프로젝트에 어떤 파일이 있는지, 방금 고친 코드가 다른 파일과 어떻게 연결되는지 챗봇은 알지 못한다. 매번 다시 설명해야 하고, 설명이 빠지면 엉뚱한 코드가 온다. 그리고 사람이 옮겨 적는 과정에서 오타가 섞이거나, 답변의 일부만 복사하거나, 여러 파일에 나눠 붙일 위치를 헷갈리는 등 '실어 나르기' 자체가 새로운 버그의 원천이 된다.

에이전트형 AI: 목표를 주면, 직접 한다

에이전트(agent) 는 다르다. 에이전트형 AI에게는 결과물이 아니라 목표를 준다. 그러면 AI가 스스로 다음을 해낸다.

• 목표를 이루기 위한 계획을 세운다
• 내 프로젝트 폴더의 파일들을 직접 읽고, 필요한 파일을 직접 만들고 고친다
• 명령어를 직접 실행한다 (서버 켜기, 테스트 돌리기 등)
• 에러가 나면 에러 메시지를 직접 읽고 원인을 찾아 고친 뒤 다시 실행한다

사람이 코드를 실어 나를 필요가 없다. 두 방식을 나란히 놓으면 이렇다.

'에이전트'라는 말 자체를 짚어 두면 개념이 또렷해진다. 에이전트는 원래 대리인이라는 뜻이다. 부동산 에이전트가 집주인을 대신해 집을 보여주고 계약을 진행하듯, 소프트웨어 에이전트는 사람을 대신해 목표를 향해 스스로 여러 단계를 밟는 프로그램을 말한다. 핵심은 '여러 단계를 스스로'다. 한 번 묻고 한 번 답하는 것(대화형)이 아니라, 목표 하나를 받아 계획-실행-점검-수정을 알아서 반복(에이전트형)한다는 데 차이가 있다.

[짚고 가기] 이 대비가 이 장 전체에서 가장 중요한 개념이다. 직접 비교해 보면 확실히 와닿는다. 웹 챗봇 창과 Claude Code 터미널을 나란히 띄워, 같은 요청("소개 페이지 만들어줘")을 양쪽에 줘 보자. 챗봇은 코드 텍스트를 뱉고 멈추지만, Claude Code는 파일을 만들고 "브라우저로 열어 확인"까지 스스로 진행한다. "말하는 AI vs 일하는 AI"라는 한마디로 정리된다.

그러면 사람은 무엇을 하는가

"AI가 다 하면 나는 뭘 하지?"라는 질문이 나올 수밖에 없다. 답은 더 큰 틀에서 판단하는 일을 한다는 것이다.

코드를 치는 시간은 줄고, 판단하는 시간이 늘어난다. 이 과정 3일 내내 여러분이 연습하는 것이 바로 이 판단이다. 그리고 이것이 회사에서 개발팀이 일하는 방식 — 기획이 결정하고, 개발이 만들고, 리뷰어가 승인하고, QA가 검증하는 프로세스 — 과 정확히 같은 구조라는 점을 기억해 두자. 우리는 그 팀의 각 자리에 사람 대신 AI를 앉힐 것이다.

한 가지 오해를 미리 풀어 두자. "판단하는 시간이 늘어난다"는 것은 일이 더 어려워진다는 뜻이 아니라 일의 종류가 바뀐다는 뜻이다. 문법을 외우고 오타를 잡던 에너지가, 무엇이 좋은 서비스인지, 이 결과가 쓸 만한지를 가리는 데로 옮겨 간다. 후자는 사실 개발자가 아닌 사람도 가진 감각이다. 그래서 이 방식은 비개발자에게 오히려 진입 장벽을 낮춘다.

우리가 3일간 만들 것 — 자체 신규 서비스 '온티켓'

설정은 이렇다. 우리 회사 (주)승승장구가 이번에 신규 서비스로 '온티켓(OnTicket)' 을 개발하려 한다. 승승장구는 그동안 자사 공연·행사 티켓을 인터파크 같은 예매 플랫폼에 올려 팔아 왔는데, 수수료가 비싸다. 그래서 결정했다 — 우리 공연 티켓을 직접 팔 사이트를 우리가 만든다. 목표는 3일 안에 첫 버전 출시다.

만들 기능은 다음과 같다.

• 공연·세미나·전시 이벤트 목록과 상세 페이지 (등급별 잔여석 표시)
• 예매: 티켓 등급 선택 → 수량 선택 → 주문 → 결제(테스트 모드) → QR 티켓 발급
• 마이티켓: 주문번호와 이메일로 내 티켓·QR 조회
• 운영자용 판매 현황 조회

3일의 큰 흐름은 다음과 같다.

마지막 날, 옆자리 사람이 여러분의 URL로 접속해 티켓을 예매할 수 있으면 성공이다.

일의 순서를 한 줄로 늘어놓으면 이렇다.

회의록 → 기획 → 화면 설계 → 아키텍처 → DB 설계 → API 명세 → 백엔드 → 프론트 → 검증 → 배포

회사에서 사람이 프로젝트를 하는 순서 그대로다. 앞 단계의 산출물이 뒤 단계의 입력이 된다.

[짚고 가기] '온티켓'은 3일 내내 이어지는 하나의 프로젝트다. 매 실습이 독립된 예제가 아니라 같은 서비스를 키워 가는 과정이라는 점을 처음부터 알아두면, "지금 뭘 하는지"를 큰 그림 안에서 이해하게 된다. "인터파크 수수료가 아까워서 우리가 직접 판다"는 동기는 실제 소상공인·기획사가 흔히 겪는 상황이라, 남의 이야기가 아니라 내 이야기처럼 다가온다.

1.2 용어 정리

이 장에서 처음 만나는 용어들이다. 앞으로 3일 내내 쓰이므로 여기서 정확히 잡고 간다. 개발이 처음이라면 이 절이 가장 낯설 수 있는데, 완벽히 외울 필요는 없다. "이런 게 있구나" 정도로 눈에 익혀 두면 실습하며 자연스럽게 손에 붙는다.

터미널(Terminal)과 셸(Shell)

터미널은 마우스 클릭 대신 글자로 명령을 입력해서 컴퓨터를 조작하는 창이다. 폴더를 만들고, 프로그램을 실행하고, 파일을 옮기는 모든 일을 문장으로 시킬 수 있다. 개발 도구의 상당수가 터미널에서 실행되기 때문에, 개발을 하려면 터미널과 친해져야 한다. 다만 이 과정에서는 명령어를 외울 필요가 거의 없다 — 명령 실행조차 AI에게 시킬 것이기 때문이다. 우리가 직접 치는 명령은 설치 확인용 몇 개가 전부다.

'터미널'이라는 이름의 유래를 알면 기억에 남는다. 옛날 대형 컴퓨터 시절, 사람들은 방 하나를 차지하는 중앙 컴퓨터에 단말기(terminal) 라는 화면+키보드를 연결해 명령을 주고받았다. 그 단말기의 화면을 흉내 낸 프로그램이 오늘날의 터미널이다. 그래서 지금도 '콘솔(console)', '명령 프롬프트(command prompt)', '커맨드 라인(command line)'이 거의 같은 뜻으로 쓰인다.

셸(shell) 은 터미널 안에서 실제로 명령을 해석해 주는 프로그램이다. 이름 그대로 '껍데기'인데, 운영체제의 핵심(커널)을 감싸고 사람과 커널 사이에서 명령을 통역하는 껍데기라는 뜻이다. 정리하면 — 터미널은 창(무대), 셸은 그 안에서 명령을 알아듣는 통역사다. 셸에도 종류가 있다.

• bash는 'Bourne Again SHell'의 말장난이다. 유닉스 초창기의 Bourne shell을 잇는다는 뜻과 '다시 태어난 셸'이라는 뜻을 겹쳐 지은 이름으로, 수십 년간 리눅스·유닉스의 사실상 표준이었다.
• zsh는 bash를 개선한 셸로, macOS가 2019년부터 기본 셸로 채택했다. 명령 문법은 bash와 거의 같아서, 이 과정에서 나오는 명령은 zsh에서 그대로 동작한다.

왜 Windows에서 굳이 Git Bash를 쓰는가? 두 가지 이유다. 첫째, 개발 자료·명령 대부분이 bash 기준으로 되어 있어서 macOS 수강생과 같은 명령을 쓸 수 있다. 같은 "폴더 만들기" 명령도 PowerShell과 bash가 문법이 다른데, 강의 자료를 하나로 통일하려면 모두가 bash를 쓰는 편이 낫다. 둘째, 뒤에서 설명하겠지만 Claude Code 자체가 Git Bash가 있으면 그것을 명령 실행 도구로 사용한다.

CLI (Command Line Interface)와 GUI

터미널에서 글자로 실행하는 프로그램을 CLI(명령 줄 인터페이스)라고 부른다. 마우스로 아이콘을 클릭해 쓰는 프로그램인 GUI(그래픽 사용자 인터페이스)와 대비되는 말이다.

• GUI: 버튼·메뉴·창을 눈으로 보고 마우스로 조작한다. 배우기 쉽다. 예: 웹 브라우저, 워드
• CLI: 글자로 명령한다. 배우기는 어렵지만 빠르고, 정확하고, 자동화하기 좋다. 같은 작업을 반복하거나, 사람이 아니라 프로그램(또는 AI)이 대신 실행하기에 적합하다

개발 도구가 CLI로 많이 만들어지는 이유가 여기 있다. "이 폴더의 파일 300개 이름을 한 번에 바꿔라" 같은 일은 마우스로는 300번 클릭이지만 CLI로는 한 줄이다. 그리고 CLI 명령은 글자라서 AI가 그대로 실행할 수 있다 — 우리가 이 과정에서 CLI 도구(Claude Code)를 쓰는 근본 이유다. Claude Code도 CLI다. 터미널에 claude라고 치면 실행된다.

퍼미션(Permission)

Claude Code는 파일을 만들거나 고치거나 명령을 실행하기 전에 사람에게 허락을 구한다. "이 파일을 이렇게 만들겠습니다. 진행할까요?"라는 물음이 화면에 뜨고, 사람이 검토한 뒤 승인하거나 거절한다. 이 승인 절차가 퍼미션이다.

퍼미션은 귀찮은 확인 창이 아니다. AI의 작업 내용을 사람이 검토하는 공식 절차다. 회사로 치면 결재 라인이다. 습관적으로 승인 키를 누르지 말고, 무엇을 하겠다는 것인지 한 줄이라도 읽고 누르는 습관을 첫날 첫 실습부터 들이자. 3일 내내 반복되는 '사람의 일'이다.

퍼미션이 존재하는 진짜 이유는 되돌리기 어려운 일을 막기 위해서다. AI는 대체로 유능하지만 가끔 엉뚱한 판단을 한다. 파일을 지우거나, 외부로 데이터를 보내거나, 시스템 설정을 바꾸는 일은 한 번 일어나면 되돌리기 어렵다. 퍼미션은 그런 일이 실행되기 직전에 사람이 개입할 지점을 만들어 준다. 그래서 위험한 작업일수록(파일 삭제, 명령 실행) 퍼미션을 더 신중히 본다.

[짚고 가기] 이 책에서 승인 절차는 '퍼미션'이라는 용어로 일관되게 부른다(다른 말로 바꾸지 않는다). 습관적으로 엔터를 연타하는 버릇을 첫날부터 경계해 두는 것이 좋다. "무심코 누른 승인 하나가 나중에 파일을 지운다"는 경고는 과장이 아니다 — Day 3 장애 대응까지 이어지는 복선이니 지금 기억해 두자.

작업 폴더(프로젝트 루트)

Claude Code는 실행된 그 폴더 안에서 일한다. 그 폴더가 프로젝트의 전부이고, AI가 읽고 쓰는 파일도 기본적으로 그 안에 있다. 우리는 onticket이라는 폴더를 만들어 3일 내내 그 안에서 작업한다.

'루트(root)'는 뿌리라는 뜻으로, 프로젝트의 모든 파일이 뻗어 나가는 최상위 폴더를 가리킨다. 이 개념이 중요한 이유는, Claude Code가 현재 작업 중인 폴더를 기준으로 프로젝트를 파악하기 때문이다. 엉뚱한 폴더에서 claude를 실행하면 엉뚱한 곳에 파일을 만든다. 그래서 실습 내내 "지금 터미널의 작업 위치가 onticket 폴더인가"를 확인하는 습관이 중요하다.

VS Code (Visual Studio Code)

마이크로소프트가 만든 무료 코드 편집기다. 전 세계 개발자가 가장 많이 쓰는 편집기이며, 가볍고 확장(extension)이 풍부하다. 우리가 VS Code를 쓰는 이유는 편집 기능보다 배치 때문이다.

• 왼쪽: 파일 탐색기 — AI가 만든 파일이 실시간으로 나타난다
• 가운데: 편집 화면 — 파일 내용을 눈으로 확인한다
• 아래: 내장 터미널 — 여기서 Claude Code를 실행한다

AI가 일하는 모습(터미널)과 그 결과물(탐색기의 새 파일, 편집기의 내용)이 한 화면에 보이는 구조다. 별도의 터미널 앱을 써도 Claude Code는 똑같이 동작하지만, 결과를 눈으로 확인하기에는 이 3분할이 압도적으로 편하다. 그래서 이 과정은 VS Code 내장 터미널 기준으로 진행한다.

1.3 관련 서비스 — Claude, Claude Code, 그리고 준비물

이 과정에서 처음 등장하는 서비스·회사·도구들을 정리한다. 각각이 무엇이고 왜 필요한지를 알아 두면, 앞으로 "이건 왜 쓰지?"라는 의문 없이 실습에 집중할 수 있다.

Anthropic과 Claude — 우리 팀의 두뇌

Anthropic은 Claude를 만든 AI 안전 연구 회사다. Claude는 그 회사가 만든 AI 모델 (대규모 언어 모델)의 이름으로, 사람의 말을 이해하고 글·코드를 생성한다. 우리가 웹에서 쓰는 챗봇 claude.ai도, 지금 배우는 Claude Code의 두뇌도 전부 이 Claude 모델이다.

Claude에는 성능·속도가 다른 여러 모델이 있다(예: 빠른 모델과 더 똑똑한 모델). Claude Code는 작업의 성격에 따라 적절한 모델을 쓰며, 사용자가 고를 수도 있다. 지금 단계에서 모델 이름을 외울 필요는 없다 — "Claude에도 급이 여러 개 있고, 어려운 일엔 더 좋은 두뇌를 쓴다" 정도면 충분하다.

Claude와 Claude Code는 다른 것이다

비유하면 Claude는 엔진, Claude Code는 그 엔진을 얹은 작업 차량이다. 챗봇 Claude는 말만 할 수 있지만, Claude Code는 내 컴퓨터에서 파일을 만들고 명령을 실행한다. 같은 두뇌라도 어떤 '몸'에 담기느냐에 따라 할 수 있는 일이 완전히 달라진다는 것 — 이것이 이 과정 전체를 관통하는 발상이다.

[짚고 가기] "이미 claude.ai 유료로 쓰는데 왜 또 필요하지?"라는 의문이 들 수 있다. 같은 Claude 두뇌지만 claude.ai는 대화(말), Claude Code는 내 컴퓨터에서의 행동(파일·명령)이다. 그리고 뒤(계정 절)에서 보듯 Claude Code는 claude.ai 구독으로 그대로 쓸 수 있으므로, 새 결제가 아니라 이미 있는 구독을 개발 도구로도 쓰는 것이라고 보면 된다.

계정과 요금제 — 무엇이 필요한가

Claude Code를 쓰려면 유료 계정이 필요하다. 무료(free) 플랜으로는 Claude Code를 쓸 수 없다. (공식 문서 기준: Pro, Max, Team, Enterprise 또는 Console 계정 필요)

정액 구독과 종량제의 차이를 이해해 두자.

• 구독(Pro/Max) 은 한 달 요금이 정해져 있다. 아무리 많이 써도 예상치 못한 요금이 청구되지 않는다. 대신 사용량이 아주 많으면 일정 시간 동안 사용량 제한이 걸릴 수 있다(잠시 후 풀린다). 교육·학습에는 이 예측 가능성이 큰 장점이다.
• API(Console) 는 토큰(글자량) 단위로 과금된다. 입력·출력 글자 수만큼 정확히 낸다. 유연하고 자동화에 적합하지만, 익숙하지 않으면 예상 밖의 금액이 나올 수 있다.

'토큰(token)'이라는 단위를 한 번 짚어 두자. AI는 글을 단어보다 작은 조각인 토큰 단위로 처리한다. 한국어는 대략 한 글자가 한두 토큰쯤 된다고 보면 감이 온다. API 요금은 이 토큰 수에 비례한다. 교육 과정에서는 이런 계산을 신경 쓰지 않아도 되도록 구독을 기본으로 한다.

Node.js는 설치하지 않아도 되는가 — 된다

인터넷의 오래된 자료에는 "Claude Code 설치에 Node.js가 필요하다(npm으로 설치)"고 나온 것이 많다. 지금은 아니다. 공식 문서가 안내하는 기본 설치 방법은 네이티브 설치(native install) 로, 설치 명령 한 줄이 운영체제에 맞는 실행 파일을 직접 내려받아 설치한다. Node.js가 전혀 필요 없다.

용어를 정리하자.

• Node.js: 원래 브라우저 안에서만 돌던 JavaScript를 브라우저 밖(내 컴퓨터)에서도 실행하게 해 주는 프로그램. 많은 개발 도구가 Node 위에서 돌아간다.
• npm: Node와 함께 설치되는 '패키지 관리자'. 남이 만든 코드 부품을 내려받고 관리한다.
• 네이티브 설치: Node 같은 중간 다리 없이, 운영체제에서 바로 실행되는 파일을 직접 설치하는 방식.

참고로 npm으로 설치하는 방법도 여전히 존재하지만, 그 경우조차 설치되는 것은 동일한 네이티브 실행 파일이고 실행할 때 Node를 쓰지 않는다. 우리는 처음부터 네이티브 설치로 간다. 네이티브 설치는 백그라운드 자동 업데이트도 지원해서, 한번 깔아 두면 알아서 최신으로 유지된다.

[짚고 가기] 오래된 블로그·유튜브를 보면 "Node부터 깔아야 하는 것 아닌가" 하고 헷갈리기 쉽다. 그건 예전 방식이고, 지금 공식 방식은 한 줄 설치라 Node가 필요 없다. 여기서 굳이 Node를 깔아 두면 뒤에서 두 앱의 뼈대를 세우며 진짜 Node가 필요할 때와 혼동하기 쉽다. 참고로 그때는 우리가 만들 앱의 개발 도구를 돌리기 위해 Node를 설치하는데, 그것은 Claude Code와는 무관한 별개의 이유다.

VS Code와 Git — 나머지 준비물

• VS Code: 앞서 본 무료 코드 편집기. 편집기 겸 '작업 현황판'으로 쓴다.
• Git: 코드의 변경 이력을 관리하는 도구다(자세한 사용법은 Day 3에서 다룬다). 지금 단계에서 Git이 중요한 이유는 이력 관리가 아니라, Windows에서 Git과 함께 딸려 오는 Git Bash 때문이다.

Git for Windows — Windows 수강생의 필수 준비물

Windows용 배포판인 Git for Windows를 설치하면 Git Bash라는 bash 셸이 함께 설치된다. Windows에서 이것을 설치해야 하는 이유는 공식 문서에 명확히 나와 있다.

• Git for Windows가 있으면 Claude Code가 Git Bash를 명령 실행 도구(Bash tool)로 사용한다
• 없으면 PowerShell로 대체 동작하지만, 이 과정의 모든 명령·자료는 bash 기준이다

즉 Windows 수강생의 설치 순서는 "Git for Windows 먼저, Claude Code는 그다음"이다. macOS는 bash 계열(zsh)이 기본이므로 이 단계가 필요 없다.

개강 전 준비 체크리스트

• claude.ai 계정 만들기 + Pro 구독 (또는 강의장에서 안내하는 계정 사용)
• 노트북: 메모리 4GB 이상, 관리자 권한, 인터넷 연결 (macOS 13 이상 / Windows 10 1809 이상)
• (선택) 크롬 등 최신 웹 브라우저 — 결과 페이지를 확인하는 데 쓴다

1.4 세팅 — 설치에서 인증까지

전체 순서는 다음과 같다. Windows와 macOS가 갈라지는 곳은 2~3단계뿐이다.

1. VS Code 설치        (공통)
2. Git for Windows 설치 (Windows만) → VS Code 터미널을 Git Bash로
3. Claude Code 설치     (한 줄 명령)
4. 설치 확인            (claude --version)
5. 작업 폴더 만들기      (onticket)
6. 실행과 로그인 인증    (claude)

1단계 — VS Code 설치 (공통)

1. 브라우저에서 https://code.visualstudio.com 접속
2. 큰 파란색 Download 버튼 클릭 (운영체제를 자동으로 감지한다)
3. 내려받은 설치 파일 실행 - Windows: 약관 동의 후 계속 '다음'. 기본 옵션 그대로 두면 된다. 설치 옵션 중 "Add to PATH"나 우클릭 메뉴 추가 항목은 켜 두면 편하다(기본값으로 켜져 있다) - macOS: 내려받은 앱을 응용 프로그램 폴더로 끌어다 놓는다
4. 실행해 본다. 영어 화면이 낯설면 한국어 팩을 설치한다: 왼쪽 세로 아이콘 중 네모 4개(Extensions) 클릭 → 검색창에 Korean 입력 → "Korean Language Pack" 설치 → 재시작

2단계 — Git for Windows 설치 (Windows만)

macOS 사용자는 이 단계를 건너뛰고 3단계로 간다.

1. https://git-scm.com/downloads/win 접속 → Download 클릭
2. 설치 파일 실행. 옵션 화면이 많이 나오지만 전부 기본값 그대로 'Next' 를 눌러도 된다. (옵션들은 대부분 Git의 세부 동작 설정으로, 이 과정에는 기본값이면 충분하다)
3. 설치가 끝나면 VS Code를 완전히 종료했다가 다시 실행한다 (새 프로그램을 인식시키기 위해)

이제 VS Code의 터미널을 Git Bash로 바꾼다.

1. VS Code에서 터미널 열기: 상단 메뉴 Terminal → New Terminal (단축키: Ctrl + `. `(백틱)은 키보드에서 숫자 1 왼쪽, Tab 위에 있는 키다)
2. 터미널 창 오른쪽 위의 + 버튼 옆의 작은 아래 화살표 클릭
3. Select Default Profile 선택
4. 목록에서 Git Bash 선택
5. 터미널 창의 휴지통 아이콘으로 기존 터미널을 닫고, 다시 Terminal → New Terminal

새 터미널의 프롬프트(입력 대기 줄)가 $ 로 끝나면 Git Bash가 열린 것이다. (PowerShell은 PS C:\...> 형태, CMD는 C:\...> 형태라서 구분할 수 있다.)

[짚고 가기] 이 단계에서 Windows 사용자의 절반이 막힌다. 가장 흔한 실수는 (1) Git 설치 후 VS Code를 재시작하지 않아 목록에 Git Bash가 안 나오는 것, (2) 기본 프로필을 바꾼 뒤 기존 PowerShell 터미널을 닫지 않아 여전히 PowerShell을 보고 있는 것이다. "프롬프트 끝이 $인가"를 확인하고 넘어가면 이후 실습이 매끄럽다. macOS 사용자라면 이 단계는 건너뛰고 3단계를 먼저 진행해도 된다.

3단계 — Claude Code 설치 (한 줄)

VS Code 내장 터미널에 아래 한 줄을 붙여넣고 Enter.

macOS (기본 터미널) / Windows (Git Bash 터미널) — 동일한 명령:

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

이 한 줄이 무슨 일을 하는지 뜯어 보면 두려움이 사라진다.

• curl: 인터넷에서 파일을 내려받는 명령 도구(macOS·Git Bash에 기본 포함)
• -fsSL: 조용히(진행 메시지 최소화), 실패하면 확실히 실패하게, 안전하게 내려받으라는 옵션 묶음
• https://claude.ai/install.sh: 공식 설치 스크립트 주소
• | bash: 내려받은 스크립트를 곧바로 bash 셸로 실행하라는 뜻(|는 앞의 출력을 뒤로 넘기는 '파이프')

정리하면 "공식 설치 스크립트를 내려받아 즉시 실행"하는 한 줄이다. 스크립트가 운영체제를 감지해 그에 맞는 Claude Code 실행 파일을 설치한다. 앞서 말했듯 Node.js는 필요 없다.

설치가 끝나면 터미널을 닫고 새로 연다. (터미널은 열릴 때 사용 가능한 명령 목록을 읽어 들이는데, 설치 직후의 터미널은 새로 생긴 claude 명령을 아직 모르기 때문이다. 이 "새로 생긴 명령을 인식시키려면 터미널을 다시 연다"는 원리는 앞으로도 자주 쓰인다.)

참고 — Windows에서 위 명령이 실패하는 경우: 회사 보안 프로그램 등이 원인일 수 있다. 이때는 공식 문서의 PowerShell용 명령을 쓰면 된다. VS Code 터미널의 + 옆 화살표에서 PowerShell을 하나 열고 아래를 실행한 뒤, 이후 실습은 다시 Git Bash에서 진행한다.

PS> irm https://claude.ai/install.ps1 | iex

(irm은 PowerShell에서 파일을 내려받는 명령, iex는 그것을 실행하는 명령이다. bash의 curl ... | bash와 같은 역할을 PowerShell 문법으로 한 것이다.)

3단계 보충 (Windows) — claude를 못 찾을 때는 PATH를 잡는다

Windows에서 가장 많이 막히는 지점이다. 설치는 분명히 끝났는데 새 터미널에서 claude --version을 치면 "명령을 찾을 수 없습니다" 또는 command not found가 뜬다. 설치가 실패한 것이 아니다. 파일은 있는데 Windows가 그 파일을 못 찾는 것이다.

왜 그런가. 설치 스크립트는 실행 파일을 여기에 놓는다.

C:\Users\<사용자이름>\.local\bin\claude.exe

그런데 터미널에 claude라고 치면, Windows는 아무 폴더나 뒤지지 않는다. 환경 변수 Path에 적힌 폴더들만 차례로 뒤진다. 저 폴더가 Path 목록에 없으면, 파일이 멀쩡히 있어도 "그런 명령 없다"고 답한다. 공식 설치 스크립트는 이 경로를 Path에 자동으로 넣어 주지 않는다. 그래서 사람이 한 번 넣어 줘야 한다.

무엇을 어디에 넣는지부터 정리한다.

%USERPROFILE%은 "내 사용자 폴더"를 가리키는 Windows의 약속된 표기다. 환경 변수 입력창에는 이 표기를 그대로 넣어도 되고, C:\Users\내이름\.local\bin처럼 전체 경로를 직접 적어도 된다. 사용자 이름에 한글이나 공백이 들어간 경우에는 %USERPROFILE% 표기를 쓰는 쪽이 안전하다.

방법 A — PowerShell 명령으로 (빠르다)

PowerShell을 열고 아래 세 줄을 실행한다. 첫 줄은 설치 폴더 경로를 담아 두고, 둘째 줄은 지금의 사용자 Path를 읽어 오고, 셋째 줄이 둘을 합쳐 저장한다.

PS> $bin = "$env:USERPROFILE\.local\bin"
PS> $cur = [Environment]::GetEnvironmentVariable('PATH', 'User')
PS> [Environment]::SetEnvironmentVariable('PATH', "$cur;$bin", 'User')

'User'가 "사용자 변수"라는 뜻이다. 이 자리를 'Machine'으로 바꾸면 시스템 변수가 되는데, 관리자 권한이 필요하고 컴퓨터를 쓰는 모든 계정에 영향을 주므로 그냥 'User'로 둔다.

방법 B — 설정 화면에서 (눈으로 확인하며)

Windows 10과 11 모두 아래 길이 똑같이 통한다.

1. 시작 버튼 옆 검색창에 환경 변수 를 입력한다
2. "시스템 환경 변수 편집" 을 클릭한다 (이름은 '시스템'이지만, 다음 화면에서 사용자 변수를 고를 것이다)
3. 시스템 속성 창 아래쪽의 [환경 변수(N)...] 버튼을 누른다
4. 창이 위아래 둘로 나뉜다. 위쪽 "○○○에 대한 사용자 변수" 에서 Path를 골라 [편집] 을 누른다 (아래쪽 '시스템 변수'가 아니다)
5. [새로 만들기] 를 누르고 %USERPROFILE%\.local\bin 을 입력한다
6. [확인] 을 세 번 눌러 창을 모두 닫는다

설정 앱으로 들어가고 싶다면 — Windows 11은 설정 → 시스템 → 정보 → 고급 시스템 설정, Windows 10은 설정 → 시스템 → 정보 → 고급 시스템 설정으로 3번 화면에 닿는다. 다만 버전에 따라 메뉴 이름이 조금씩 달라서, 검색창에 "환경 변수"를 치는 1번 방법이 가장 확실하다.

Git Bash로 설치했어도 마찬가지다. 오히려 더 헷갈리는 경우다. Git Bash는 Linux 방식의 설정(~/.bashrc)을 쓰고, PowerShell·CMD는 Windows의 환경 변수를 쓴다. 둘은 PATH를 공유하지 않는다. 그래서 이런 일이 생긴다.

위 표대로, Windows 사용자 변수 Path에 한 번 넣어 두면 세 셸(Git Bash·PowerShell· CMD) 모두에서 claude가 통한다. 이 과정의 실습은 Git Bash에서 진행하지만, 나중에 다른 터미널을 열 일이 반드시 생기므로 지금 잡아 두는 편이 낫다.

잡혔는지 확인하는 법. PowerShell에서는 —

PS> $env:PATH -split ';' | Select-String '\.local\\bin'

Git Bash에서는 —

$ echo $PATH | tr ':' '\n' | grep local/bin

한 줄이라도 출력되면 잡힌 것이고, 아무것도 안 나오면 아직 안 잡힌 것이다.

마지막이 제일 중요하다 — 터미널을 새로 연다. 환경 변수는 터미널이 켜질 때 한 번 읽힌다. PATH를 방금 바꿨어도 이미 열려 있던 터미널은 옛날 목록을 들고 있다. VS Code를 쓰고 있다면 터미널 창 하나가 아니라 VS Code 전체를 껐다 켜는 것이 확실하다.

[짚고 가기] 이 대목은 Windows 수강생이 가장 많이 손드는 자리다. 강사가 먼저 물어볼 것은 딱 두 가지다 — "터미널을 새로 열었나요?"와 "설정한 게 사용자 변수가 맞나요?" 실제로 열에 여덟은 이 둘 중 하나다. 그리고 이 원리("Path에 있는 폴더만 뒤진다")는 뒤에서 Node.js·pnpm·gh·wrangler를 깔 때 똑같이 반복되니, 여기서 한 번 제대로 짚어 두면 뼈대를 세울 때와 인프라 도구를 깔 때 시간을 벌 수 있다.

[짚고 가기] 시간이 빠듯하면 방법 A(PowerShell 두 줄)를 복사해 주고 넘어가되, 왜 필요한지 한 문장("Windows는 Path에 적힌 폴더만 뒤진다")은 반드시 말해 준다. 이유 없이 명령만 붙여넣게 하면, 나중에 혼자 설치할 때 똑같이 막힌다.

4단계 — 설치 확인

새로 연 터미널에서:

$ claude --version

2.x.x (Claude Code) 처럼 버전 숫자가 나오면 성공이다. (--version은 대부분의 CLI 도구가 가진 공통 옵션으로, "너 버전 몇이야?"를 묻는 것이다. 버전을 대답한다는 것은 프로그램이 정상 설치되어 실행 가능하다는 증거다.)

문제가 있는 것 같으면 진단 명령을 실행해 볼 수 있다. 설치 상태와 설정을 점검해서 문제와 해결책을 알려 준다.

$ claude doctor

doctor라는 이름 그대로 '건강 검진' 명령이다. 무엇이 설치됐고, 어떤 셸을 쓰며, 인증은 됐는지 등을 점검해 보여 준다. 설치가 꼬였을 때 가장 먼저 돌려 볼 명령이다.

5단계 — 실습 폴더 준비 (제공된 자료 열기)

명령어 없이 GUI로 한다. 이 과정은 실습에 쓰는 데이터(회의록·CSV 등)를 미리 담아 둔 시작 폴더를 제공한다.

1. 강의 자료에서 onticket-실습시작.zip 을 내려받아 압축을 푼다. (바탕화면이나 문서 폴더 등 찾기 쉬운 곳에)
2. 압축을 풀면 onticket 폴더가 나온다. 그 안에 data 폴더(실습 데이터)가 들어 있다.
3. VS Code 상단 메뉴 File → Open Folder (macOS: 파일 → 폴더 열기)로 이 onticket 폴더를 선택해 연다.
4. "Do you trust the authors...?"(이 폴더의 작성자를 신뢰합니까?) 창이 뜨면 Yes (VS Code는 낯선 폴더를 열 때 안전을 위해 신뢰 여부를 묻는다. 제공된 실습 폴더이니 신뢰하면 된다)

이제 VS Code 왼쪽 탐색기에 ONTICKET 폴더가 열리고, 그 안에 data 폴더가 보인다. 여기가 앞으로 3일간 온티켓의 모든 코드가 살게 될 집이다.

주의: 폴더를 새로 열면 터미널도 닫힌다. Terminal → New Terminal로 다시 연다. 터미널 프롬프트에 onticket 경로가 보이는지 확인하자 — Claude Code는 터미널이 현재 서 있는 폴더에서 일하기 때문에, 엉뚱한 폴더에서 실행하면 엉뚱한 곳에 파일이 생긴다.

6단계 — 실행과 로그인 인증

터미널에서:

$ claude

처음 실행하면 몇 가지를 묻는다.

1. 테마 선택: 화살표 키로 골라 Enter (아무거나 좋다. 어두운 테마가 눈이 편하다)
2. 로그인: Enter를 누르면 브라우저가 자동으로 열린다. claude.ai 계정(Pro 구독이 있는 계정)으로 로그인하고 "승인" 버튼을 누른다. 이 과정은 내 계정과 이 컴퓨터의 Claude Code를 연결하는 절차로, 최초 1회만 하면 된다.
3. 터미널로 돌아오면 준비 완료. 화면 아래에 입력을 기다리는 프롬프트가 깜박인다

만약 브라우저가 자동으로 안 열리면, 터미널에 표시된 인증 URL을 복사해서 브라우저 주소창에 직접 붙여넣으면 된다. 이렇게 "브라우저로 로그인해서 도구에 권한을 연결"하는 방식은 앞으로 다른 서비스(클라우드 배포 등)에서도 똑같이 반복되니 익혀 두자.

자주 막히는 곳 정리 (트러블슈팅)

[짚고 가기] 설치 단계는 환경마다 달라 시간이 들쭉날쭉하다. 순조롭게 6단계까지 마쳤다면 이 장 끝 실습의 첫 지시를 미리 해 봐도 좋다. 반대로 막히는 곳이 생기면, 위 트러블슈팅 표를 증상별로 짚어 보면 대부분 해결된다.

1.5 프롬프트 작성법 — 첫 지시의 기본형

설치가 끝났으니 이제 일을 시켜 볼 차례다. 그 전에, 에이전트에게 내리는 지시(프롬프트)는 챗봇에게 하는 질문과 어떻게 다른지 정리하자. 원칙은 세 가지다.

'프롬프트(prompt)'는 원래 '재촉하다·유도하다'라는 뜻으로, AI에게 주는 지시문 전체를 가리킨다. 좋은 프롬프트를 쓰는 능력이 곧 AI를 다루는 능력이다. 이 과정 3일 내내 갈고닦는 핵심 기술이다.

원칙 1 — 방법이 아니라 목표를 말한다

나쁜 지시:

index.html 파일을 만들어서 h1 태그에 온티켓이라고 쓰고, CSS로 가운데 정렬하고,
폰트 크기는 48px로 하고, 배경색은...

이것은 지시가 아니라 코딩이다. 어떤 파일에 어떤 태그를 어떤 속성으로 쓸지까지 사람이 정하고 있다면, 타자만 AI에게 시키는 셈이다. 그럴 거면 직접 치는 게 빠르다.

좋은 지시:

온티켓 소개 페이지를 만들어줘.

무엇을(목표) 만 말하고 어떻게(방법) 는 AI에게 맡긴다. 파일을 몇 개로 나눌지, 어떤 기술을 쓸지는 AI가 정하게 두고, 사람은 결과를 보고 판단한다. 방법에 개입하고 싶어질 때는 다음 원칙처럼 '기준'으로 개입한다.

여기서 흔한 오해 하나. "목표만 말하라"는 것이 "짧게 말하라"는 뜻은 아니다. 목표는 풍부할수록 좋다 — 다만 그 풍부함이 방법(코드를 어떻게 짤지) 이 아니라 의도와 맥락(무엇을 왜 원하는지) 을 향해야 한다. "티켓 서비스라 신뢰감이 중요하다", "공연장 느낌이면 좋겠다" 같은 맥락은 많이 줄수록 결과가 좋아진다. "h1 태그를 써라" 같은 방법 지정은 줄일수록 좋아진다.

원칙 2 — 완료 기준을 한 줄 넣는다

"잘 만들어줘", "예쁘게 해줘"는 기준이 없는 지시다. 무엇이 보이면 완료인지를 문장에 넣는다.

온티켓이라는 티켓 예매 서비스를 만들 거야.
지금은 소개용 index.html 하나만 만들어줘.
서비스 이름 '온티켓'과 '3일 뒤 오픈' 문구가 보이면 완료야.

완료 기준이 있으면 두 가지가 좋아진다. AI가 과하게 많은 것을 만들지 않는다(범위 통제). 그리고 결과를 확인할 때 무엇을 보면 되는지 내가 안다(검증 가능). "예쁘게"처럼 사람마다 다르게 읽히는 말 대신, 눈으로 확인할 수 있는 사실로 기준을 적는 것이 요령이다.

원칙 3 — 퍼미션 요청은 읽고 승인한다

지시를 내리면 Claude Code는 곧 "이 파일을 만들겠습니다"라며 퍼미션을 요청한다. 이때 내용을 훑어보는 것이 사람의 일이다. 파일 이름이 내가 의도한 것인지, 엉뚱한 위치는 아닌지, 대략 무슨 내용인지. 전부 이해할 필요는 없다. 다만 읽지 않고 누르는 습관이 들면, 나중에 중요한 변경(파일 삭제, 외부 전송 등)도 기계적으로 승인하게 된다. 첫날부터 읽고 누르는 습관을 들인다.

정리 — 첫 지시의 기본형

[목표] + [완료 기준 한 줄] + (필요할 때만) [제약 한 줄]

제약이란 "파일은 하나만", "외부 라이브러리는 쓰지 마" 같은 울타리를 말한다. 모든 지시에 필요한 것은 아니고, 범위가 새어 나갈 것 같을 때 한 줄 추가한다.

프롬프트 사례 모음 — 나쁜 지시를 좋은 지시로

원칙을 실제 문장에 적용해 보자. 왼쪽의 흔한 지시를 오른쪽처럼 바꾸면 결과가 달라진다.

세 가지 실전 감각을 덧붙인다.

• "원인부터 설명하고 고쳐줘" 는 강력한 습관이다. AI가 무턱대고 코드를 바꾸는 대신, 무엇이 왜 문제인지 먼저 말하게 하면, 엉뚱한 수정을 조기에 걸러 낼 수 있다.
• 한 번에 하나씩. "소개 페이지 만들고 예매도 붙이고 결제도…"처럼 몰아서 시키면 결과를 검증하기 어렵다. 작게 시켜 확인하고 다음으로 넘어가는 리듬이 결국 더 빠르다.
• 맥락은 아끼지 말 것. "우리 회사가 인터파크 수수료가 아까워서 직접 판매 사이트를 만든다" 같은 배경을 한 번 주면, AI가 톤과 문구를 그 맥락에 맞춰 준다.

[짚고 가기] 같은 목표를 약한 지시와 강한 지시로 각각 넣어 결과를 직접 비교해 보면 원칙이 체감된다. "예쁘게 만들어줘"와 "공연장 같은 신뢰감 있는 분위기로, …가 보이면 완료"의 결과 차이를 눈으로 보면, 프롬프트가 결과를 좌우한다는 것을 실감하게 된다.

1.6 실습 — 온티켓의 첫 페이지

이제 실제로 첫 결과물을 만든다. 목표: 코드를 한 줄도 직접 치지 않고 온티켓 소개 페이지를 브라우저에 띄운다.

따라하기 1 — 지시한다

터미널의 Claude Code 프롬프트에 다음을 입력하고 Enter:

온티켓이라는 티켓 예매 서비스를 만들 거야.
지금은 소개용 index.html 하나만 만들어줘.
서비스 이름 '온티켓'과 '3일 뒤 오픈' 문구가 보이면 완료야.

위 프롬프트를 그대로 복사해 입력하면 된다. 다른 내용으로 바꿔서 해 보고 싶다면 자유롭게 바꿔도 좋다.

이 지시가 왜 좋은 지시인지 뜯어 보자 — 목표(온티켓 소개 페이지), 완료 기준('온티켓'과 '3일 뒤 오픈' 문구), 제약(index.html 하나만)이 모두 들어 있다. 바로 앞 '프롬프트 작성법'에서 배운 기본형 그대로다.

따라하기 2 — 관찰한다

입력 직후 Claude Code가 하는 일을 지켜보자. 대략 이런 순서로 진행된다.

1. 무엇을 만들지 짧게 계획을 말한다
2. index.html을 만들겠다며 퍼미션을 요청한다 — 파일 내용이 미리 보인다
3. 여기서 멈추고 사람의 응답을 기다린다

이 멈춤이 중요하다. AI는 허락 없이 내 컴퓨터를 바꾸지 않는다. 지금 이 순간이 바로 이 장 첫머리에서 본 "사람의 일(승인)"이 실제로 일어나는 지점이다.

따라하기 3 — 승인한다

퍼미션 요청 내용을 훑어본다. 파일 이름이 index.html이 맞는지, 내용에 '온티켓'이 들어 있는지 정도만 확인하고 승인한다. 승인하는 순간 왼쪽 파일 탐색기에 index.html이 나타난다. 방금 AI가 내 컴퓨터에 파일을 만든 것이다.

따라하기 4 — 확인한다

결과를 브라우저에서 확인하자.

1. 왼쪽 탐색기에서 index.html 우클릭
2. 파일 위치 열기 - Windows: Reveal in File Explorer (한국어 팩 설치 시: 파일 탐색기에 표시) 클릭 → 파일 탐색기가 열린다 - macOS: Reveal in Finder (한국어 팩 설치 시: Finder에 표시) 클릭 → Finder가 열린다
3. 열린 폴더에서 index.html을 더블클릭 → 기본 브라우저에서 페이지가 열린다

화면에 '온티켓'과 '3일 뒤 오픈'이 보이는가? 방금 여러분은 코드를 한 줄도 치지 않고 웹 페이지를 만들었다. 한 일은 세 가지다 — 지시했고, 승인했고, 확인했다.

따라하기 5 — 수정 루프를 돌려 본다

만든 것을 고치는 것도 같은 방식이다. 이어서 입력:

좋아. 부제로 "공연 티켓, 수수료 없이 직접 판매"를 추가해줘.
그리고 전체 분위기를 공연장처럼 어두운 배경으로 바꿔줘.

위 프롬프트를 그대로 복사해 입력하면 된다. 다른 내용으로 바꿔서 해 보고 싶다면 자유롭게 바꿔도 좋다.

퍼미션 요청(이번엔 '수정')을 읽고 승인 → 브라우저에서 새로고침(F5) → 바뀐 화면 확인.

이 지시 → 승인 → 확인 의 반복이 앞으로 3일간의 기본 리듬이다. 기능이 커지고 파일이 많아져도 리듬은 같다.

(더 해보기) 프롬프트를 바꿔 결과를 비교한다

시간이 남으면, 같은 목표를 다른 프롬프트로 시켜 결과가 어떻게 달라지는지 실험해 보자.

소개 페이지를 다시 만들어줘. 이번엔 '3일 뒤 오픈'을 큰 카운트다운처럼 강조하고,
가장 눈에 띄는 자리에 '오픈 알림 받기' 버튼을 하나 넣어줘.

지시를 구체적인 의도로 채울수록 결과가 내 머릿속 그림에 가까워지는 것을 확인할 수 있다. 이것이 "결정은 사람, 실행은 AI"의 첫 경험이다.

완료 기준 체크리스트

• claude --version 이 버전 번호를 출력한다
• (Windows) 터미널 기본 프로필이 Git Bash로 설정되어 있다
• VS Code에 onticket 폴더가 열려 있다
• 브라우저에 온티켓 소개 페이지가 뜬다
• 수정 지시를 한 번 이상 반영해 보았다

1.7 정리

• 대화형 AI는 말만 하고, 에이전트형 AI는 직접 한다. 코드를 실어 나르는 복사-붙여넣기 루프는 끝났다.
• 사람의 일은 코딩에서 결정·승인·검증으로 올라갔다. 퍼미션 요청을 읽고 누르는 것이 그 첫 훈련이다.
• Claude는 두뇌(모델), Claude Code는 그 두뇌를 얹어 내 컴퓨터에서 행동하게 하는 도구(CLI)다.
• Claude Code는 네이티브 설치 한 줄로 설치되며 Node.js가 필요 없다. Windows는 Git for Windows를 먼저 설치해 Git Bash를 셸로 쓴다 — Claude Code도 Git Bash를 명령 실행 도구로 사용한다.
• 지시의 기본형은 목표 + 완료 기준 + (제약). 방법은 AI의 몫, 기준은 사람의 몫이다. 맥락과 의도는 풍부하게, 방법 지정은 아끼는 것이 좋은 프롬프트다.
• 우리 회사의 신규 서비스 온티켓이 첫 페이지를 얻었다. 아직 소개 페이지 한 장이지만, 3일 뒤 이 폴더는 실제 URL에서 돌아가는 예매 서비스가 된다.