Claude Code는 Anthropic이 공식으로 만든 CLI 기반 AI 코딩 에이전트다. VS Code 확장이 아니라 터미널에서 직접 실행하는 방식이라, 처음 접하면 “이걸 어떻게 쓰는 거지?” 싶을 수 있다. 나도 처음 설치할 때 Node.js 버전 문제부터 API 키 설정, 권한 모드까지 한참을 헤맸다. 특히 M1 Mac에서는 ARM 네이티브 관련 이슈가 하나씩 튀어나와서, 공식 문서만으로는 부족한 부분이 꽤 있었다.
지금은 MacBook M1 32GB에서 매일 Claude Code를 메인 개발 도구로 쓰고 있다. 프로젝트 세팅부터 코드 작성, 디버깅, 리팩토링까지 터미널 하나로 처리한다. 이 글은 M1 Mac에서 Claude Code를 설치하고 첫 프로젝트를 세팅하기까지, 내가 실제로 거친 과정을 그대로 정리한 것이다.
📑 목차
사전 준비 — Node.js 20+ LTS 설치
Claude Code는 Node.js 18 이상을 요구한다. 하지만 2026년 4월 기준으로 Node.js 18은 LTS 지원이 종료된 상태이므로, Node.js 20 LTS 또는 22 LTS를 설치하는 게 맞다. Homebrew로 직접 설치하면 버전 관리가 어려워지므로 nvm을 쓴다. 관련 내용은 Mac Node.js 버전 충돌 해결법에서도 다루고 있다.
nvm 설치 및 Node.js 20 LTS 세팅
# nvm 설치 (이미 설치되어 있다면 스킵)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# 쉘 재시작 또는 설정 파일 소싱
source ~/.zshrc
# nvm 정상 설치 확인
nvm --version
# 0.40.1
# Node.js 20 LTS 설치
nvm install 20
# 기본 버전으로 지정
nvm alias default 20
# 설치 확인
node --version
# v20.18.1
npm --version
# 10.8.2M1 ARM 네이티브로 설치됐는지 확인
여기서 반드시 확인해야 할 게 있다. M1에서 Rosetta 2를 통해 x86 버전의 Node.js가 설치되는 경우가 있다. 특히 이전에 Intel Mac에서 마이그레이션했거나, iTerm2 설정에서 “Open using Rosetta”가 켜져 있으면 이런 일이 벌어진다.
# 아키텍처 확인
node -p "process.arch"
# arm64 ← 이게 나와야 정상
# 만약 x64가 나온다면 Rosetta로 실행 중인 것
# 터미널 앱의 "Rosetta로 열기" 해제 후 nvm reinstall
arch
# arm64 ← 쉘 자체가 ARM으로 돌고 있는지 먼저 확인
# Rosetta 쉘에서 설치한 Node를 정리하고 다시 설치
nvm uninstall 20
nvm install 20process.arch가 arm64로 나오면 정상이다. x64로 나오면 네이티브 모듈 컴파일 시 아키텍처 불일치 에러가 터질 수 있으니, 반드시 ARM 네이티브 상태에서 재설치해야 한다.
Claude Code CLI 설치
Node.js가 준비됐으면 설치는 한 줄이다.
# Claude Code CLI 전역 설치
npm install -g @anthropic-ai/claude-code
# 설치 확인
claude --version
# @anthropic-ai/claude-code/1.0.16
# 설치 경로 확인
which claude
# /Users/kyunghunkim/.nvm/versions/node/v20.18.1/bin/claude설치 경로가 ~/.nvm/versions/ 하위에 있어야 한다. /usr/local/bin/이나 /opt/homebrew/bin/에 있다면 Homebrew로 설치한 시스템 Node.js를 쓰고 있는 것이므로, nvm 설정을 다시 확인해야 한다.
업데이트도 동일한 명령으로 한다. Claude Code는 업데이트가 꽤 잦은 편이라(거의 매주), 가끔씩 최신 버전으로 올려주는 게 좋다.
# 최신 버전으로 업데이트
npm update -g @anthropic-ai/claude-codeAnthropic API 키 발급 및 환경변수 설정
Claude Code를 실행하려면 Anthropic API 키가 필요하다. console.anthropic.com에서 발급받을 수 있다.
API 키 발급 절차
- console.anthropic.com 접속 후 로그인
- 좌측 메뉴에서 API Keys 클릭
- Create Key 버튼 클릭
- 키 이름 입력 (예:
claude-code-macbook) - 생성된 키(
sk-ant-api03-...)를 안전한 곳에 복사
키는 생성 직후에만 전체 값을 볼 수 있다. 닫으면 다시 확인이 안 되므로 반드시 즉시 저장해야 한다.
환경변수 설정
API 키를 쉘 환경변수로 등록하면, Claude Code가 자동으로 인식한다.
# ~/.zshrc에 환경변수 추가
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-여기에-실제-키-입력"' >> ~/.zshrc
# 즉시 적용
source ~/.zshrc
# 환경변수 확인
echo $ANTHROPIC_API_KEY
# sk-ant-api03-... (키 앞부분이 보이면 정상)보안 팁: .zshrc에 직접 키를 넣는 게 불편하다면, ~/.config/claude/ 디렉토리에 설정 파일을 두거나, macOS Keychain을 활용하는 방법도 있다. 하지만 개인 개발 머신에서는 .zshrc 방식이 가장 간단하고, 대부분의 개발자가 이렇게 쓴다.
또는 Claude Code를 처음 실행하면 인터랙티브하게 API 키를 입력할 수도 있다. 이 경우 키가 ~/.claude/ 하위에 저장된다.
첫 프로젝트에서 claude 명령어 실행해보기
프로젝트 디렉토리에서 claude 명령을 실행하면 바로 대화형 세션이 시작된다.
# 프로젝트 디렉토리로 이동
cd ~/workspace/my-project
# Claude Code 실행
claude
# 또는 한 줄짜리 작업이면 인라인으로 실행
claude "이 프로젝트의 디렉토리 구조를 분석해줘"
# 파이프도 가능
cat error.log | claude "이 에러 로그를 분석해서 원인을 찾아줘"처음 실행하면 Claude Code 로고가 터미널에 나타나고, 프로젝트 디렉토리의 파일 구조를 자동으로 스캔한다. 여기서 중요한 게 하나 있는데, Claude Code는 현재 디렉토리(cwd)를 기준으로 프로젝트를 인식한다. 즉 홈 디렉토리에서 실행하면 홈 디렉토리 전체가 프로젝트 범위가 되어버리므로, 반드시 작업할 프로젝트 폴더 안에서 실행해야 한다.
기본 워크플로우
Claude Code의 기본적인 동작 방식은 이렇다:
- 사용자가 자연어로 요청을 입력
- Claude가 필요한 파일을 읽고 분석
- 코드 수정이나 파일 생성이 필요하면 사용자에게 허락을 구함
- 승인하면 실행, 거절하면 다른 방안 제시
Chat GPT의 Canvas나 Cursor 같은 도구와 다른 점은, Claude Code가 실제 터미널 명령어를 실행할 수 있다는 것이다. npm install, git commit, pytest 같은 명령을 직접 실행하고 결과를 확인한다. 그래서 단순 코드 생성을 넘어, 빌드 에러 디버깅이나 테스트 실행까지 루프 안에서 처리할 수 있다.
CLAUDE.md 파일 작성법 — 프로젝트 컨텍스트의 핵심
CLAUDE.md는 Claude Code의 핵심 기능 중 하나다. 프로젝트 루트에 이 파일을 두면, Claude가 매 세션 시작 시 자동으로 읽고 프로젝트 컨텍스트를 파악한다. 사람으로 치면 “프로젝트 온보딩 문서”에 해당한다.
CLAUDE.md가 없으면 어떻게 되나
없어도 Claude Code는 동작한다. 하지만 매번 “이 프로젝트는 TypeScript로 작성되어 있고, Cloudflare Workers 런타임을 사용하고…”를 반복 설명해야 한다. CLAUDE.md가 있으면 이런 배경 설명이 전부 생략된다.
실전 CLAUDE.md 예시
# 프로젝트 개요
khiopost.com(워드프레스) 블로그에 기술 글을 자동 발행하는 Cloudflare Workers 프로젝트.
## 기술 스택
- 런타임: Cloudflare Workers (TypeScript)
- CMS: WordPress REST API
- 저장소: Cloudflare KV
- 알림: Telegram Bot API
- 스케줄: Cron Trigger (UTC 00:00 = KST 09:00)
## 디렉토리 구조
```
src/
├── index.ts # Worker 엔트리포인트
├── wordpress.ts # WordPress API 연동
├── telegram.ts # 텔레그램 알림
├── queue.ts # KV 기반 큐 관리
└── types.ts # 타입 정의
```
## 환경변수
- WP_URL: WordPress 사이트 주소
- WP_USERNAME: WordPress 사용자명
- WP_APP_PASSWORD: Application Password
- TELEGRAM_BOT_TOKEN: 봇 토큰
- TELEGRAM_CHAT_ID: 알림 채팅 ID
## 컨벤션
- 함수명은 camelCase
- 에러 처리는 try-catch로 감싸고 Telegram 알림 전송
- 커밋 메시지는 영어로, conventional commits 형식
- 테스트는 vitest 사용
## 주의사항
- Cloudflare Workers는 Node.js API를 완전히 지원하지 않음 (fs, path 등 사용 불가)
- KV free tier 제한: 읽기 10만/일, 쓰기 1천/일
- wrangler dev로 로컬 테스트 시 --local 플래그 사용CLAUDE.md 작성 팁
경험상 효과가 좋았던 패턴을 정리하면 이렇다:
- 기술 스택과 버전을 명시한다. “TypeScript”만 쓰지 말고 “TypeScript 5.5, target: ES2022″까지 적어야 Claude가 정확한 문법을 쓴다.
- 금지 사항을 적는다. “절대 any 타입을 사용하지 마” 같은 규칙을 넣으면 잘 지킨다.
- 프로젝트 구조를 트리로 보여준다. Claude가 파일을 탐색하는 시간을 줄여줘서, 응답 속도와 정확도가 올라간다.
- 너무 길지 않게 유지한다. CLAUDE.md가 300줄을 넘기면 오히려 맥락이 흐려진다. 핵심만 간결하게.
참고로 claude /init 명령을 사용하면 Claude가 프로젝트를 분석해서 CLAUDE.md 초안을 자동으로 생성해준다. 처음 세팅할 때 유용하다.
CLAUDE.md 계층 구조
Claude Code는 CLAUDE.md를 여러 계층에서 읽는다:
| 위치 | 범위 | 용도 |
|---|---|---|
~/.claude/CLAUDE.md |
전역 (모든 프로젝트) | 개인 코딩 스타일, 선호하는 패턴 |
프로젝트루트/CLAUDE.md |
프로젝트 전체 | 기술 스택, 구조, 컨벤션 |
하위폴더/CLAUDE.md |
해당 폴더 하위 | 모듈별 특수 규칙 |
전역 CLAUDE.md에는 “커밋 메시지는 영어로 써”, “변수명은 snake_case 대신 camelCase 써” 같은 범용 규칙을 넣어두면, 모든 프로젝트에서 일관되게 적용된다.
권한 모드 설정 — allowedTools와 hooks
Claude Code는 기본적으로 파일 수정이나 터미널 명령을 실행하기 전에 사용자 승인을 요청한다. 안전하지만, 매번 “Y” 키를 누르는 게 번거로울 수 있다. 이때 settings.json으로 권한을 세밀하게 제어할 수 있다.
settings.json 위치와 구조
# 전역 설정 파일 위치
~/.claude/settings.json
# 프로젝트별 설정 파일 위치
프로젝트루트/.claude/settings.json프로젝트별 설정이 전역 설정보다 우선한다.
allowedTools 설정
allowedTools에 등록한 도구는 승인 없이 자동으로 실행된다. 자주 쓰는 안전한 명령만 등록하는 게 원칙이다.
{
"permissions": {
"allowedTools": [
"Read",
"Glob",
"Grep",
"Bash(npm test)",
"Bash(npm run lint)",
"Bash(npm run build)",
"Bash(git status)",
"Bash(git diff)",
"Bash(git log)"
]
}
}Bash(npm test)처럼 괄호 안에 정확한 명령을 지정하면, 해당 명령만 자동 허용된다. Bash만 쓰면 모든 쉘 명령이 자동 허용되므로 위험하다. 절대 그렇게 하지 말자.
hooks 설정
hooks는 특정 이벤트 전후에 자동으로 실행되는 명령을 정의한다. 예를 들어, Claude가 파일을 수정할 때마다 자동으로 lint를 돌리게 할 수 있다.
{
"hooks": {
"postEditFile": [
{
"command": "npx eslint --fix ${file}",
"description": "파일 수정 후 자동 ESLint fix"
}
],
"preCommit": [
{
"command": "npm run lint && npm test",
"description": "커밋 전 lint와 테스트 실행"
}
]
}
}hooks를 잘 활용하면 Claude가 코드를 수정한 직후 자동으로 품질 검사가 돌아가므로, 잘못된 코드가 커밋되는 걸 방지할 수 있다.
M1 관련 트러블슈팅 — node-gyp, native module 이슈
M1 Mac에서 Claude Code를 쓰다 보면, Claude가 npm install로 패키지를 설치하는 과정에서 네이티브 모듈 관련 에러를 만날 수 있다. Claude Code 자체의 문제가 아니라 Node.js 네이티브 모듈과 ARM 아키텍처의 호환성 문제인데, Claude Code가 자동으로 패키지를 설치하다가 이런 에러를 만나면 작업이 중단되므로 미리 대비하는 게 좋다.
node-gyp rebuild 실패
가장 흔한 에러다. node-gyp는 C/C++ 네이티브 애드온을 컴파일하는 도구인데, Xcode Command Line Tools가 없거나 Python 경로가 잘못 잡혀 있으면 실패한다.
# 에러 예시
gyp ERR! find Python
gyp ERR! configure error
gyp ERR! stack Error: Could not find any Python installation to use
gyp ERR! not ok
# 해결: Xcode Command Line Tools 설치 (이미 있으면 무시됨)
xcode-select --install
# Python 경로 확인 (macOS에 기본 내장된 python3)
which python3
# /usr/bin/python3
# node-gyp가 python3를 찾도록 설정
npm config set python /usr/bin/python3
# 그래도 안 되면 node-gyp를 명시적으로 글로벌 설치
npm install -g node-gypsharp 등 이미지 처리 라이브러리 설치 실패
sharp는 Node.js에서 이미지 리사이징에 쓰이는 인기 라이브러리인데, M1 초기에는 ARM용 프리빌트 바이너리가 없어서 고생하는 사람이 많았다. 지금은 대부분 해결됐지만, 간혹 캐시 문제로 x64 바이너리를 내려받는 경우가 있다.
# sharp 설치 실패 시
npm install sharp
# Error: Something went wrong installing the "sharp" module
# Cannot find module '../build/Release/sharp-darwin-arm64v8.node'
# 해결: 캐시 정리 후 재설치
npm cache clean --force
npm rebuild sharp --platform=darwin --arch=arm64
# 그래도 안 되면 node_modules 삭제 후 전체 재설치
rm -rf node_modules package-lock.json
npm installbetter-sqlite3, canvas 등 네이티브 모듈 문제
better-sqlite3나 canvas 같은 네이티브 모듈은 컴파일에 시스템 라이브러리가 필요하다. M1에서는 Homebrew 경로가 /opt/homebrew/인데, 일부 모듈이 여전히 /usr/local/을 참조하는 경우가 있다.
# canvas 모듈 설치에 필요한 시스템 라이브러리
brew install pkg-config cairo pango libpng jpeg giflib librsvg pixman
# Homebrew 라이브러리 경로를 명시적으로 설정
export PKG_CONFIG_PATH="/opt/homebrew/lib/pkgconfig:$PKG_CONFIG_PATH"
export LDFLAGS="-L/opt/homebrew/lib"
export CPPFLAGS="-I/opt/homebrew/include"
# 이 값을 ~/.zshrc에 영구 등록해두면 편하다이런 환경변수를 ~/.zshrc에 추가해두면, Claude Code가 npm install을 실행할 때도 자동으로 적용된다.
실전 사용 팁
slash commands 활용
Claude Code 세션 안에서 /로 시작하는 명령을 쓸 수 있다. 자주 쓰는 것들을 정리하면:
| 명령 | 기능 | 사용 시점 |
|---|---|---|
/init |
CLAUDE.md 자동 생성 | 새 프로젝트 처음 세팅할 때 |
/clear |
대화 히스토리 초기화 | 토큰 사용량이 많아졌을 때 |
/compact |
대화 요약 후 컨텍스트 압축 | 긴 세션에서 맥락은 유지하면서 토큰 절약 |
/cost |
현재 세션 API 비용 확인 | 비용 추적이 필요할 때 |
/help |
사용 가능한 명령 목록 | 뭐가 있는지 모르겠을 때 |
/init으로 프로젝트 부트스트랩
새 프로젝트를 시작할 때 /init을 치면, Claude가 프로젝트 디렉토리를 분석해서 CLAUDE.md 초안을 만들어준다. 기존에 package.json, tsconfig.json, .gitignore 같은 설정 파일이 있으면 거기서 정보를 추출한다. 완벽하진 않지만, 빈 파일에서 시작하는 것보다 훨씬 낫다.
# 새 프로젝트 디렉토리에서
cd ~/workspace/new-project
claude
# Claude Code 세션에서
> /init
# Claude가 프로젝트를 분석하고 CLAUDE.md를 생성한다
# 생성된 파일을 검토하고 필요한 부분을 수정하면 된다멀티턴 작업 — 큰 작업을 단계별로
Claude Code의 진짜 힘은 멀티턴 대화에서 나온다. 단발성 질문이 아니라, 하나의 작업을 여러 턴에 걸쳐 점진적으로 완성하는 방식이 가장 효과적이다.
예를 들어 새 API 엔드포인트를 추가하는 작업이라면:
- 1턴: “users 테이블에 접근하는 GET /api/users 엔드포인트를 추가해줘. 기존 /api/posts 엔드포인트의 패턴을 참고해.”
- 2턴: (결과 확인 후) “페이지네이션을 추가해줘. limit과 offset 쿼리 파라미터를 받아서 처리하도록.”
- 3턴: “이 엔드포인트에 대한 테스트를 작성해줘. 빈 결과, 단일 결과, 페이지네이션 케이스를 포함해.”
- 4턴: “테스트를 실행해서 통과하는지 확인해줘.”
한 번에 “API 엔드포인트 만들고 테스트도 작성하고 문서도 업데이트해줘”라고 하면 빠뜨리는 게 생긴다. 한 턴에 하나의 명확한 작업을 지시하는 게 결과물 품질이 훨씬 좋다.
비용 절약 팁
Claude Code는 API 호출당 과금이므로, 무턱대고 쓰면 비용이 빠르게 올라간다. MacBook M1 32GB 기준으로 내가 체감한 팁을 정리하면:
- CLAUDE.md를 잘 써라. 매번 프로젝트 설명을 반복하면 그만큼 토큰이 소모된다.
- /compact를 적극 활용해라. 대화가 길어지면 이전 맥락이 계속 딸려 오면서 토큰이 누적된다. /compact로 요약하면 맥락은 유지하되 토큰 사용량이 확 준다.
- 코드 리뷰보다 코드 생성에 써라. 이미 작성된 긴 코드의 리뷰를 맡기면 입력 토큰이 많이 소모된다. 새 코드를 생성하는 데 쓰는 게 비용 대비 효율이 높다.
- /cost 명령으로 실시간 비용을 확인해라. 어느 작업에서 비용이 많이 나가는지 체감하고 나면, 자연스럽게 효율적으로 쓰게 된다.
터미널 설정 권장사항
M1 MacBook에서 Claude Code를 쾌적하게 쓰기 위한 터미널 설정 몇 가지를 추가로 정리한다:
- 터미널 앱: iTerm2 또는 기본 Terminal 둘 다 잘 동작한다. 핵심은 Rosetta 모드를 끄는 것.
- 쉘: zsh (macOS 기본). bash도 되지만 nvm 자동 전환 설정은 zsh이 더 편하다.
- 폰트: Claude Code가 출력하는 코드 블록이 깨지지 않으려면 모노스페이스 폰트(JetBrains Mono, Fira Code 등)를 쓰는 게 좋다.
- 메모리: Claude Code 자체는 Node.js 프로세스라 메모리를 많이 먹지 않지만, 대규모 프로젝트에서 파일 탐색을 많이 하면 500MB 정도까지 올라갈 수 있다. M1 32GB면 전혀 문제없다.
여기까지 따라했다면, M1 Mac에서 Claude Code를 설치하고 첫 프로젝트를 세팅하는 과정이 끝난 것이다. 처음에는 터미널 기반 인터페이스가 낯설 수 있지만, 하루 이틀 쓰다 보면 IDE보다 훨씬 빠르게 작업이 진행되는 걸 체감하게 된다. 특히 “이 파일 읽고, 저 파일 수정하고, 테스트 돌려” 같은 복합적인 작업에서 진가가 드러난다. CLAUDE.md만 잘 작성해두면 프로젝트에 대한 이해도가 높은 상태에서 바로 작업에 들어가니까, 매번 처음부터 설명하는 수고가 사라진다.