AI 에이전트 실습 환경 만들기 — Claude Code 설치부터 첫 실행까지 (5/6)

요약 — 실습 가이드는 어떤 AI 코딩 에이전트로도 따라할 수 있게 썼지만, 다들 같은 도구로 시작하면 화면이 똑같아서 따라오기 훨씬 쉽습니다. 이 글은 Anthropic의 Claude Code를 기준으로, 설치부터 “정상적으로 실행됐다”를 확인하는 지점까지만 다룹니다. 코드 작성은 다음 글(실습 가이드)에서 시작합니다.

지금까지 이 시리즈에서 개념 네 편(1편 2편 3편 4편)을 다뤘고, 실습 가이드에서는 “아무 AI 코딩 에이전트나 써도 된다”고 설명했습니다. 맞는 말이지만, 처음 시작할 때는 하나를 정해서 그대로 따라가는 편이 훨씬 헤매지 않습니다. 이 글에서는 Claude Code를 기준으로 설명합니다.

시작 전에 확인할 것 — 계정과 비용

가장 먼저, 정직하게 짚고 갈 부분입니다. Claude Code는 무료 Claude.ai 플랜에는 포함되어 있지 않습니다. 아래 중 하나가 필요합니다.

Claude Pro ($20/월) 이상 구독 (Pro, Max, Team, Enterprise 중 하나)
또는 Anthropic Console 계정(API 사용량 기준 과금)

실습 몇 시간만 해볼 목적이라면 Pro 구독으로 충분합니다. 이미 Claude Pro를 쓰고 계신다면 별도 결제 없이 바로 시작할 수 있습니다.

대안이 필요하다면: 이 시리즈의 개념(에이전트, 컨텍스트, 하네스, 에이전틱 엔지니어링)은 Claude Code 외의 도구(Codex, Cursor 등)에도 동일하게 적용됩니다. 특정 도구에 대한 결제가 부담스럽다면, 이미 쓰고 있는 다른 AI 코딩 도구로 실습을 진행하셔도 됩니다 — 이 경우 아래 설치 과정은 건너뛰고 실습 가이드로 바로 이동하시면 됩니다.

필요한 것

터미널(명령어를 입력할 수 있는 화면)을 열 수 있는 컴퓨터 — macOS, Windows, Linux 모두 가능
위에서 확인한 Claude 계정
인터넷 연결

Node.js 같은 별도 프로그램을 미리 설치할 필요는 없습니다. 최근 방식(네이티브 설치)은 추가 프로그램 없이 바로 설치됩니다.

Step 1. 터미널 열기

macOS: Cmd + Space를 누르고 “터미널” 입력 후 실행

Windows: 시작 메뉴에서 “PowerShell” 검색 후 실행 (반드시 PowerShell이어야 합니다. 명령 프롬프트(CMD)에서는 아래 설치 명령이 작동하지 않습니다. 창 맨 앞에 PS라고 표시되면 PowerShell이 맞게 열린 것입니다)

[스크린샷 위치: 터미널/PowerShell이 열린 화면]

Step 2. Claude Code 설치

터미널에 아래 명령어 중 본인 운영체제에 맞는 것을 그대로 붙여넣고 실행합니다.

macOS / Linux

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

Windows (PowerShell)

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

설치가 진행되는 동안 몇 줄의 로그가 지나갑니다. 별도로 확인 창이 뜨지 않으면 정상입니다.

[스크린샷 위치: 설치 명령 실행 중/완료 화면]

Step 3. 설치 확인

설치가 끝나면, 아래 명령어로 정상 설치됐는지 확인합니다.

claude --version

버전 번호가 출력되면 성공입니다. 만약 “명령어를 찾을 수 없다”는 오류가 뜨면, 터미널을 완전히 닫았다가 새로 열어서 다시 시도해보세요 (설치 직후에는 터미널이 새 경로를 못 읽는 경우가 있습니다).

Step 4. 로그인

아무 폴더에서나 아래 명령어로 Claude Code를 실행합니다.

claude

처음 실행하면 로그인을 요청합니다. 안내에 따라 브라우저가 열리고, 갖고 계신 Claude 계정으로 로그인하면 됩니다. 로그인이 완료되면 터미널로 돌아와 “로그인되었습니다” 같은 메시지가 뜹니다.

[스크린샷 위치: 브라우저 로그인 화면 → 로그인 완료 후 터미널 화면]

이후로는 별도 로그인 없이 claude 명령어만으로 바로 실행됩니다.

Step 5. 첫 실행 확인 (여기까지 되면 준비 완료)

실습을 시작할 폴더를 하나 만들고, 그 폴더로 이동한 뒤 다시 claude를 실행합니다.

macOS / Linux

mkdir budget-practice
cd budget-practice
claude

Windows (PowerShell)

mkdir budget-practice
cd budget-practice
claude

Claude Code 환영 화면이 뜨고, 프롬프트를 입력할 수 있는 상태가 되면 준비가 끝난 것입니다. 정말 동작하는지 간단히 확인해보고 싶다면 이렇게 입력해보세요.

hello.txt 파일을 만들고, "환경 설정 완료"라고 적어줘

파일이 실제로 생성되면 정상적으로 준비된 것입니다. 이 budget-practice 폴더가 실습 가이드에서 계속 사용할 폴더입니다.

[스크린샷 위치: hello.txt 생성 완료 후 화면]

자주 겪는 문제

증상	원인 · 해결
설치 명령 실행 시 권한 오류(permission denied)	관리자 권한으로 설치하려 하지 마세요 (sudo 사용 금지). 대신 터미널을 새로 열어 다시 시도하거나, 공식 문서의 권한 문제 해결 안내를 참고하세요
`claude` 명령어를 찾을 수 없음	터미널을 완전히 껐다가 다시 열어보세요. 그래도 안 되면 설치가 중간에 실패했을 수 있으니 Step 2를 다시 실행하세요
Windows에서 `irm`이 인식되지 않음	CMD에서 실행하고 있는 것입니다. PowerShell을 새로 열어서 다시 시도하세요
로그인 브라우저 창이 안 뜸	터미널에 있는 링크를 복사해서 직접 브라우저 주소창에 붙여넣어 보세요

다음 단계

환경이 준비됐다면, 이제 실습 가이드 — 가계부 요약 앱 만들기로 넘어가서 방금 만든 budget-practice 폴더에서 바로 시작하시면 됩니다.