“클로드 코드 써봤어?”
“응, 근데 설치하다 막혀서 포기했어.”
커뮤니티 채팅방에서 반복되는 대화다. 2편에서 블로그 자동화부터 코드 리팩토링까지 클로드 코드가 뭘 할 수 있는지 확인했다. 실제로 해보려고 터미널을 열면 문제가 시작된다. Node.js? npm? 권한 오류? 용어부터 낯설고, 공식 문서는 이미 개발 환경이 갖춰진 사람 기준이다.
이번 편은 그 막힌 지점을 정확히 뚫는다. 설치 5분, 초기 세팅 10분. 이 글을 끝까지 따라하면 오늘 안에 클로드 코드가 돌아간다.
“그냥 터미널에 치면 되는 거 아냐?”가 안 통하는 이유
클로드 코드 설치는 명령어 한 줄이다. 진짜 문제는 그 한 줄의 전후에 있다.
“Node.js 18 이상 필요”라는 안내를 보고 Node.js가 뭔지 검색하게 되고, 설치해도 권한 오류가 뜨고, 인증 단계에서 어떤 계정을 써야 하는지 헷갈린다. 채팅형 클로드(claude.ai)에 “설치법 알려줘”라고 물어볼 수도 있지만, 내 운영체제와 현재 환경에 딱 맞는 답을 한 번에 받기는 어렵다.
그래서 아래에 운영체제별 분기 없이, 가장 흔한 막힘 포인트를 짚으며 정리했다.
터미널 한 줄로 시작하는 5분 셋업
클로드 코드 설치는 세 단계로 끝난다. 각 단계에서 흔히 막히는 지점까지 함께 짚는다.
1단계 — Node.js 설치
nodejs.org에서 LTS 버전(18 이상)을 다운로드한다. 설치 후 터미널에 node -v를 입력해서 버전 번호가 뜨면 성공이다.
2단계 — 클로드 코드 설치
터미널에 아래 한 줄을 입력한다.
npm install -g @anthropic-ai/claude-codeWindows라면 관리자 권한 터미널에서 실행한다. macOS/Linux에서 sudo를 붙이고 싶어지겠지만, 공식 문서는 이를 권장하지 않는다. 권한 문제가 생기면 npm의 글로벌 경로 설정을 먼저 확인하는 게 안전하다. 설치 뒤 claude doctor를 실행하면 환경 점검까지 완료된다.
3단계 — 인증
프로젝트 폴더에서 claude를 입력하면 브라우저가 열린다. claude.ai 계정으로 로그인하면 OAuth 인증이 끝난다. Pro(월 $19) 또는 Max(월 $110~) 구독이 필요하며, 정확한 요금은 공식 가격 페이지에서 확인할 수 있다.
터미널 없이 시작하는 방법도 있다. claude.ai/code에서 GitHub 저장소를 연결하면 브라우저만으로 클로드 코드를 쓸 수 있다. 설치가 부담스러우면 여기서 먼저 체험해도 된다.
매번 같은 설명을 반복하지 않는 프로젝트 기억법
클로드 코드에는 프로젝트의 맥락을 기억하는 구조가 있다. 프로젝트 루트에 CLAUDE.md라는 마크다운 파일을 만들어두면, 매 세션 시작 시 자동으로 읽는다.
채팅형 클로드를 쓸 때 매번 “나는 블로거이고, 톤은 이렇고, 금지어는 이거야”라고 반복 입력했던 경험이 있을 것이다. CLAUDE.md에 한 번 적으면 그 반복이 사라진다. 공식 문서는 200줄 이내를 권장한다. 길어질수록 컨텍스트를 잡아먹어 오히려 지시 준수율이 떨어진다.
블로거나 1인 개발자라면 아래 템플릿을 그대로 복사해서 시작할 수 있다.
# 블로그 프로젝트 지침
## 글쓰기 규칙
– 톤: 실무자가 후배에게 설명하듯, 친근하되 가볍지 않게
– 문장: 30~50자 중심, 짧은 문장을 섞어 리듬감 유지
– 금지 표현: “혁신적인”, “획기적인”, “누구나 쉽게”
– 본문 구조: H2 5~6개, 2000~3000자
– 항상 한국어로 응답
## 기술 환경
– 플랫폼: 티스토리 (HTML 모드 작업)
– 이미지: max-width:100% 필수 적용
– 모바일 가독성 최우선
## 작업 방식
– 수정 전 반드시 원본 파일 읽기
– 새 파일 생성보다 기존 파일 수정 우선
– 커밋 메시지는 한국어로
프로젝트 성격에 따라 내용을 바꾸면 된다. 개발 프로젝트라면 빌드 명령어, 코드 컨벤션, 테스트 방법을 적고, 콘텐츠 프로젝트라면 톤·구조·금지어를 적는다. 핵심은 “새 팀원이 첫날 알아야 할 것”만 담는 것이다.
직접 작성이 번거롭다면, 클로드 코드에게 시키는 방법도 있다.
이 프로젝트의 폴더 구조, 사용 언어, 주요 파일 역할을 파악해서
CLAUDE.md 파일을 만들어줘.
포함할 내용:
– 프로젝트 목적 한 줄 요약
– 폴더별 역할 설명
– 빌드/실행 명령어
– 코드 컨벤션 (네이밍 규칙, 들여쓰기)
– 자주 쓰는 테스트 명령어
200줄 이내로 간결하게 작성해.
실수 걱정 없이 토큰도 아끼는 초기 세팅
클로드 코드는 기본적으로 읽기 전용이다. 파일을 수정하거나 명령어를 실행할 때마다 승인을 요청한다. 처음엔 이게 안전하지만, 매번 “허용”을 누르는 게 번거로워진다.
이때 두 가지 선택지가 있다.
| 모드 | 동작 방식 | 추천 상황 |
|---|---|---|
| 샌드박스 모드 | 위험한 작업만 자동 차단, 나머지 허용 | 혼자 작업하는 개인 프로젝트 |
| 설정 파일 허용 목록 | .claude/settings.json에 자주 쓰는 명령어 등록 | 특정 도구만 반복 사용할 때 |
1인 개발자라면 샌드박스 모드로 시작하는 게 균형이 맞다. 승인 피로는 줄이면서 rm -rf 같은 위험 명령은 여전히 막아준다.
토큰 절약은 세 가지 명령어로 충분하다.
/clear— 작업을 전환할 때 컨텍스트를 초기화한다. 블로그 글 쓰다가 코드 작업으로 넘어갈 때, 이전 대화가 남아 있으면 토큰이 낭비된다./compact— 긴 대화를 요약해서 토큰을 줄인다. 뒤에 “코드 변경사항 위주로 유지해줘”처럼 보존 기준을 붙일 수도 있다./usage— 현재 세션의 토큰 사용량을 확인한다. 체감보다 빠르게 쌓이므로 중간중간 확인하는 습관이 중요하다.
클로드 코드는 프롬프트 캐싱(반복 내용 비용 절감)과 자동 압축(컨텍스트 한도 도달 시 자동 요약)을 내부적으로 처리하지만, 위 세 명령어를 의식적으로 쓰면 체감 비용이 확실히 줄어든다.
After — CLAUDE.md에 한 번 작성 → 매 세션 자동 로딩. /clear로 작업 전환, /compact로 장시간 작업 관리. 톤 일관성 유지 + 토큰 절약.
자주 묻는 질문
Q. 클로드 코드를 처음 쓰는데 무료로 시작할 수 있나요?
클로드 코드는 Pro 또는 Max 구독이 필요하다. API 키를 직접 발급받아 사용하는 방법도 있지만, 이 경우 토큰 사용량에 따라 별도 과금된다. 정확한 요금 체계는 수시로 바뀌므로 공식 가격 페이지에서 최신 정보를 확인하는 게 좋다.
Q. CLAUDE.md를 잘못 작성하면 오히려 역효과가 나나요?
길이가 200줄을 넘거나 모호한 지시가 섞이면 준수율이 떨어질 수 있다. “좋은 글을 써줘” 같은 추상적 지시보다 “문장은 50자 이내, 금지어는 X” 같은 구체적 규칙이 효과적이다. 처음엔 짧게 시작하고, 세션을 거듭하며 필요한 규칙만 추가하는 방식을 권장한다.
Q. 터미널 설치와 웹 버전(claude.ai/code) 중 어떤 걸 쓰는 게 좋나요?
로컬 파일을 직접 수정하거나 빌드·테스트 명령어를 실행해야 한다면 터미널 설치가 맞다. 원격 GitHub 저장소 중심으로 작업하거나, 설치 없이 빠르게 시작하고 싶다면 웹 버전이 편하다. 두 버전 모두 같은 구독 계정으로 사용할 수 있다.
설치 끝, 이제 진짜 일을 시킬 차례
이번 시리즈 세 편을 통해 클로드와 클로드 코드의 차이(1편), 실전 활용 비교(2편), 그리고 설치와 세팅(3편)까지 한 바퀴 돌았다. 이제 도구는 준비됐다.
그런데 쓰다 보면 새로운 궁금증이 생긴다. 외부 도구(슬랙, 노션, 데이터베이스)를 클로드 코드에 연결하는 MCP 서버, 여러 작업을 동시에 돌리는 서브에이전트, 반복 업무를 완전히 자동화하는 파이프라인 — 클로드 코드의 진짜 깊이는 여기서부터 시작된다. 후속 콘텐츠에서 하나씩 풀어볼 예정이다.