맥에서 Claude Code 시작하기 — 새 맥북 켜고 /init까지 30분

크게 보기

Claude Code는 터미널에서 돌아가는 AI 코딩 도구입니다. 그래서 설치 자체보다 터미널·Homebrew·Node 같은 기본 도구를 갖추는 과정에서 처음 쓰는 분들이 자주 막힙니다. 이 글은 새 맥을 막 켠 상태를 가정하고, 그 기본 도구부터 Claude Code를 설치해 첫 프로젝트에 /init을 실행하기까지를 순서대로 따라갑니다.

모든 명령은 2026년 8월 22일 기준 공식 문서를 따릅니다. 명령어 앞의 $는 프롬프트 표시이니 입력하지 않습니다.

전체 흐름

1. 터미널 열기

⌘ + Space로 Spotlight를 열고 터미널(Terminal)을 입력한 뒤 Enter. 사용자이름@MacBook ~ % 같은 줄이 보이면 준비된 것입니다. 이 줄이 프롬프트이고, 그 뒤에 명령을 입력합니다.

터미널이 열려 있을 때 Dock 아이콘을 우클릭 → 옵션 → "Dock에 유지"를 눌러두면 다음부터 바로 열 수 있습니다. 더 편한 터미널이 필요하면 나중에 brew install --cask iterm2나 ghostty를 설치해도 됩니다.

2. Xcode 명령줄 도구

Git과 컴파일러가 들어 있는 애플의 기본 개발 도구입니다. Homebrew가 여기에 의존하므로 가장 먼저 설치합니다.

xcode-select --install

팝업에서 설치를 누르고 약관에 동의합니다. 5~15분 걸립니다. 이미 설치되어 있으면 already installed라고 나오는데, 그대로 다음으로 넘어가면 됩니다.

xcode-select -p
# /Library/Developer/CommandLineTools
git --version
# git version 2.5x.x (Apple Git-xxx)

3. Homebrew 설치

맥의 표준 패키지 관리자입니다. 앞으로 Node, Git, 각종 CLI 도구를 brew install 한 줄로 설치하게 됩니다.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

맥 로그인 비밀번호를 물어보면 입력합니다. 입력해도 화면에 글자가 표시되지 않는 것이 정상입니다. Enter를 누르라고 하면 누릅니다.

PATH 등록 — Apple Silicon 맥은 빠뜨리면 안 됩니다

설치가 끝나면 화면 마지막에 "Next steps" 안내가 나옵니다. 거기 적힌 두 줄을 그대로 실행합니다. 보통 아래와 같습니다. 이걸 빼먹으면 터미널이 brew 명령을 찾지 못합니다.

# Apple Silicon (M1~M4)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# Intel 맥은 경로만 다릅니다
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/usr/local/bin/brew shellenv)"

brew --version
# Homebrew 4.x.x
brew doctor
# Your system is ready to brew.

brew doctor가 Warning을 몇 줄 보여줘도 대부분 무시해도 됩니다. 마지막 줄이 "ready to brew"거나 Error가 없으면 진행하세요.

4. Node · Git · 기본 도구

Claude Code 자체는 Node가 없어도 돌아갑니다(네이티브 바이너리입니다). 하지만 Claude가 작업할 대부분의 프로젝트 — Next.js, React, 각종 스크립트 — 는 Node와 npm이 필요합니다. 한 번에 설치합니다.

brew install git node gh ripgrep jq

프로젝트마다 다른 Node 버전이 필요하다면 fnm을 쓰면 됩니다. 처음이라면 위의 brew install node로 충분하니 건너뛰어도 됩니다.

# 선택: 프로젝트별 Node 버전 관리
brew install fnm
echo 'eval "$(fnm env --use-on-cd)"' >> ~/.zshrc
source ~/.zshrc
fnm install --lts && fnm default lts-latest

# 선택: 자주 쓰는 GUI 앱도 brew로
brew install --cask visual-studio-code google-chrome

5. Git 설정과 GitHub 로그인

커밋에 들어갈 이름·이메일을 정하고, GitHub 저장소를 비밀번호 없이 받을 수 있게 인증합니다.

git config --global user.name "홍길동"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main
git config --global pull.rebase false

gh auth login
# GitHub.com → HTTPS → Login with a web browser 순으로 선택
# 표시되는 8자리 코드를 브라우저에 입력
gh auth status
# ✓ Logged in to github.com account your-id

6. Claude Code 설치

설치 방법은 세 가지입니다. 처음이라면 네이티브 설치를 권장합니다. 백그라운드에서 자동 업데이트되어 따로 관리할 일이 없습니다.

방법 A — 네이티브 설치

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

설치 스크립트가 ~/.local/bin을 PATH에 추가하라고 안내하면 그 줄을 실행합니다. 보통 아래와 같습니다.

echo 'export PATH="HOME/.local/bin:HOME/.local/bin:HOME/.local/bin:PATH"' >> ~/.zshrc
source ~/.zshrc

방법 B — Homebrew

brew install --cask claude-code
# 최신 기능을 바로 받고 싶으면
brew install --cask claude-code@latest

claude-code는 약 1주일 지연된 안정 채널, claude-code@latest는 최신 채널입니다. Homebrew 설치는 자동 업데이트가 안 되므로 주기적으로 brew upgrade claude-code를 실행합니다.

방법 C — npm

npm install -g @anthropic-ai/claude-code

sudo npm install -g는 쓰지 마세요. 권한이 꼬여 나중에 업데이트가 실패합니다. 권한 오류가 나면 방법 A가 가장 간단합니다.

설치 확인

claude --version
# 2.1.xxx (Claude Code)
claude doctor

claude doctor는 설치 상태, 설정 파일 오류, PATH 문제를 한 번에 점검하고 해결 방법까지 출력합니다.

7. 첫 실행과 로그인

Claude Code는 프로젝트 폴더 안에서 실행하는 도구입니다. 아직 프로젝트가 없다면 연습용 폴더를 하나 만듭니다.

mkdir -p ~/project/hello-claude
cd ~/project/hello-claude
git init
claude

처음 실행하면 순서대로 이렇게 진행됩니다.

프롬프트 >가 보이면 성공입니다. 한국어로 아무거나 시켜보세요.

> 이 폴더에 README.md 파일을 만들고 "첫 프로젝트"라고 적어줘

파일을 만들겠다는 권한 확인이 뜨면 Enter(Yes). 종료는 /exit 또는 Ctrl+D입니다. 로그인이 풀리거나 계정을 바꾸려면 세션 안에서 /login, 현재 계정 확인은 /status.

8. 실제 프로젝트에서 /init

/init은 Claude가 프로젝트를 훑어보고 CLAUDE.md를 만들어 주는 명령입니다. 이 파일이 있어야 매 세션마다 프로젝트 구조와 규칙을 다시 설명하지 않아도 됩니다.

cd ~/project
gh repo clone 조직명/저장소명
cd 저장소명
npm install        # Node 프로젝트라면
claude

> /init

Claude가 package.json, 폴더 구조, 빌드 명령을 분석해 CLAUDE.md 초안을 작성합니다. 생성된 내용을 읽어 보고 다음을 직접 보강하면 효과가 큽니다.

• 자주 쓰는 명령 — npm run dev, 테스트, 린트
• 코드 스타일과 금지 사항 — "이 폴더는 건드리지 말 것"
• 사용 언어 — "모든 사용자 문구는 한국어로 작성"

CLAUDE.md는 Git에 커밋해서 팀원과 공유합니다. 개인용 메모는 CLAUDE.local.md에 쓰고 .gitignore에 추가하세요. 세션 중에 #으로 시작하는 문장을 입력하면 그 내용이 바로 CLAUDE.md에 기록됩니다.

9. 처음 일주일에 손에 익힐 것들

슬래시 명령

키보드

터미널에서 실행할 때

claude -c                          # 가장 최근 세션 이어서
claude -r                          # 이전 세션 목록에서 골라 재개
claude -p "이 폴더 구조 요약해줘"   # 대화 없이 한 번만 실행하고 종료
claude update                      # 수동 업데이트

10. 에디터 연동과 추천 설정

VS Code 확장 — 확장(⌘+Shift+X)에서 "Claude Code"를 검색해 설치합니다. VS Code 내장 터미널에서 claude를 실행하면 자동으로 연동되어 변경 사항(diff)을 에디터에서 바로 볼 수 있습니다. 터미널에서 /ide를 입력해도 연결됩니다.

데스크톱 앱 — 터미널이 부담스럽다면 Claude 데스크톱 앱에도 Claude Code가 들어 있습니다. 다만 이 글의 3~5단계는 그래도 해두는 것이 좋습니다. 앱 안에서도 결국 Node·Git이 있어야 프로젝트를 다룰 수 있습니다.

사용자 전역 설정은 ~/.claude/settings.json에 둡니다. 없으면 만들면 됩니다.

{
  "autoUpdatesChannel": "stable",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run build)",
      "Bash(git status)",
      "Bash(git diff*)"
    ]
  }
}

• autoUpdatesChannel: "stable" — 최신 버전에서 가끔 생기는 회귀 버그를 피하고 싶을 때. 기본값은 latest
• permissions.allow — 매번 확인 없이 실행해도 되는 안전한 명령. 세션에서 /permissions로 추가하는 편이 더 쉽습니다

프로젝트 폴더에 생기는 .claude/settings.local.json은 개인 설정이므로 .gitignore에 추가하세요.

echo ".claude/settings.local.json" >> .gitignore

11. 자주 막히는 문제

처음 설치할 때 나오는 오류는 거의 PATH 아니면 권한 문제입니다.

표에 없는 문제는 claude doctor 출력과 함께 공식 문제 해결 페이지를 확인하세요.

완전히 지우고 다시 설치하려면:

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude
# 설정·세션 기록까지 지우려면 (되돌릴 수 없음)
rm -rf ~/.claude ~/.claude.json

마치며

여기까지 끝냈다면 맥에 Homebrew, Node, Git, GitHub 인증, Claude Code가 모두 갖춰진 상태입니다. 이 환경은 Claude Code뿐 아니라 앞으로 어떤 개발 도구를 쓰든 기본이 되는 구성이니, 한 번 제대로 해두면 오래 갑니다.

다음 단계로는 CLAUDE.md를 팀 규칙에 맞게 다듬고, /permissions로 자주 쓰는 명령을 허용해 두고, Shift+Tab으로 계획 모드를 써보는 것을 권합니다. 설치가 끝난 뒤 Claude Code를 실제로 어떻게 쓰는지는 별도의 글에서 다루겠습니다.