Mac에서 Claude Code 시작하기 — 설치부터 subagent / MCP / hook까지 (2026년 버전)

Claude Code는 2024년 말부터 2026년까지 상당히 다른 모습으로 변했습니다.

2025년 무렵에는 "터미널에서 사용할 수 있는 채팅형 AI" 정도의 위치였으나, 2026년 현재는 subagent(역할을 나눈 복수 AI), MCP(외부 도구 연결), hook(이벤트 후크)과 같은 에이전트 개발 기반으로서의 기능이 일通り 갖춰져 있습니다. "설치 절차"도 이전과는 달라져서, 공식 curl 인스톨러 한 번으로 끝낼 수 있게 되었습니다.

이 기사에서는 Mac에서 Claude Code를 새로 설치하려는 사람을 위해, 설치 → 초기 설정 → subagent / MCP / hook 사용 시작까지를 2026년 시점의 최신 절차로 남겨둡니다.

동작 확인 환경: macOS Sequoia 15.x / Apple Silicon / Claude Code v2.x (2026년 6월 시점)

이 기사의 목표

[ Claude Code 설치 ]
↓
[ 프로젝트에 CLAUDE.md 배치 ]
...

여기까지 동작한다면, 이후에는 각 기능을 깊이 파고들어 자신만의 개발 에이전트 기반을 구축할 수 있습니다.

전제 조건

• macOS (Apple Silicon / Intel 모두 가능)
• 터미널 사용 가능 (표준 Terminal.app 또는 iTerm2)
• Anthropic 계정 (claude.ai에서 생성)

Node.js는 불필요해졌습니다. 이전에는 npm을 통한 설치가 표준이었으나, 공식 인스톨러로 전환되면서 의존성이 줄어들었습니다.

Step 1: 공식 인스톨러로 설치

터미널에서 다음을 실행합니다.

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

스크립트가 ~/.local/bin/claude에 바이너리를 배치하고, 셸 설정 파일(.zshrc 또는 .bashrc)에 PATH를 추가합니다. 설치 후, 셸을 재시작하거나 다음을 실행하여 반영합니다.

source ~/.zshrc # zsh의 경우
# 또는
source ~/.bashrc # bash의 경우

확인:

claude --version

Claude Code 2.x.x와 같은 출력이 나오면 설치 성공입니다.

이전에 npm을 통해 설치했던 사람에게: 기존 npm install -g @anthropic-ai/claude-code 구성으로부터의 이행은, 공식 인스톨러를 덮어쓰기 실행하면 자동으로 승계됩니다. claude migrate-installer는 불필요해졌습니다.

Step 2: 최초 실행 및 인증

터미널에서 claude라고 입력하는 것만으로 실행됩니다.

claude

최초 실행 시에는 브라우저가 열리며 Anthropic 계정 인증을 요구합니다. Claude.ai에 등록된 계정으로 로그인하여 토큰을 발행합니다. 토큰이 Claude Code 측으로 자동 전달되어 인증이 완료됩니다.

그 후 진단 명령어로 상태를 확인해 둡니다.

claude doctor

버전, 실행 파일 위치, API 연결 상태 등이 표시됩니다. 에러가 발생하지 않았다면 준비 완료입니다.

CLAUDE.md를 배치하기

Step 3: 프로젝트에서 Claude Code는

실행 시 프로젝트 루트의 CLAUDE.md를 자동으로 읽어들입니다. 프로젝트 고유의 규칙이나 컨텍스트를 작성해 두면, 매번 그 내용을 바탕으로 판단합니다.

cd ~/dev/your-project
cat > CLAUDE.md <<'EOF'
# CLAUDE.md
...

이렇게 하면 claude 실행 시 CLAUDE.md가 읽혀서, 위 규칙에 따른 제안 및 구현을 수행합니다.

Step 4: subagent를 하나 실행해 보기

2025년 버전에는 없었던 중요한 기능이 subagent(서브 에이전트)입니다. 역할이 다른 AI를 .claude/agents/<name>.md로 정의하여, 메인 채팅에서 위임할 수 있습니다.

시험 삼아 "코드 리뷰 전담" subagent를 만들어 보겠습니다.

mkdir -p .claude/agents
cat > .claude/agents/reviewer.md <<'EOF'
---
...

이제 메인 채팅에서 다음과 같이 호출할 수 있습니다:

@reviewer 이 디렉토리 변경 사항을 리뷰해 주세요

역할을 나눈 AI를 늘려가면 자신만의 전용 에이전트 팀을 구성할 수 있습니다.

상세한 설계 지침: 여러 개의 subagent를 운용할 때의 규칙 설계에 대해서는 "AI 에이전트 개발 팀의 '헌법'을 어떻게 설계했는가"에 작성하였습니다.

Step 5: MCP 서버 1개 연결해 보기

MCP (Model Context Protocol)는 Claude Code에 외부 도구를 연결하는 메커니즘입니다. Figma, GitHub, Slack, 각종 데이터베이스 등 대응하는 MCP 서버가 점점 늘어나고 있습니다.

테스트 삼아 GitHub MCP를 추가해 보겠습니다.

claude mcp add --transport http github https://mcp.github.com/mcp

확인:

claude mcp list

github가 표시되면 등록 성공입니다. Claude Code 실행 후 /mcp를 통해 인증 플로우(authentication flow)를 거치면, Claude Code에서 GitHub의 Issue / PR / 리포지토리 정보를 다룰 수 있게 됩니다.

설정은 ~/.claude.json (global) 또는 .mcp.json (project scope)에 저장됩니다. project scope로 설정하면 .mcp.json을 리포지토리에 commit 하여 팀원들과 MCP 구성을 공유할 수 있습니다.

Figma MCP 절차: 동일한 패턴으로 Figma도 연결할 수 있습니다. 자세한 내용은 "Claude Code와 Figma 공식 MCP 연결하기"를 참조하세요.

Step 6: hook으로 안전장치 추가하기

hook은 Claude Code가 도구를 호출하기 전후에 임의의 쉘 스크립트(shell script)를 실행하는 메커니즘입니다. "AI가 멋대로 수행하지 않았으면 하는 작업"을 물리적으로 차단할 수 있습니다.

.claude/settings.json에서 등록합니다.

{
"hooks": {
"PreToolUse": [
...

.claude/hooks/block-dangerous-bash.sh의 내용은 예를 들어 다음과 같습니다.

#!/bin/bash
# stdin으로부터 JSON 형식의 tool_input이 전달됨
CMD=$(jq -r '.tool_input.command' 2>/dev/null)
...

실행 권한을 부여하는 것을 잊지 마세요.

chmod +x .claude/hooks/block-dangerous-bash.sh

이렇게 하면 rm -rf / chmod 777 / sudo를 포함하는 명령은 즉시 차단됩니다. exit 2로 반환하면 Claude Code에 "차단된 이유"가 전달되어, 에이전트가 다음 판단에 활용할 수 있습니다.

더 깊은 hook 설계: worktree 격리가 깨졌을 때의 최후의 보루로서 hook을 사용한 이야기는 "Claude Code의 PreToolUse hook으로 AI 에이전트의 행동을 물리적으로 제어하기"에 작성되어 있습니다.

잘 작동하지 않을 때

claude: command not found

PATH가 설정되지 않았을 가능성이 있습니다. 쉘(shell)을 재시작하거나 source ~/.zshrc를 실행하세요. 그래도 안 된다면:

ls -la ~/.local/bin/claude

명령어로 바이너리 존재 여부를 확인하세요. 존재한다면 PATH에 ~/.local/bin을 명시적으로 추가합니다.

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

인증 루프에서 빠져나올 수 없는 경우

브라우저 측의 cookie / cache 문제인 경우가 많습니다. Claude.ai에서 한 번 로그아웃한 후 다시 로그인하고, Claude Code 측에서 claude logout $\rightarrow$ claude를 통해 재인증을 진행하세요.

claude doctor

「API connection failed」가 발생하는 경우

• 네트워크 프록시 (Network Proxy) 설정 확인
• 기업 네트워크의 경우 TLS 검사 (TLS Inspection)로 인해 차단될 수 있으므로 IT 부서에 확인
• 자신의 계정이 Claude Code를 이용 가능한 플랜 (Pro / Max / Team)인지 확인

.claude/agents/<name>.md

의 subagent를 호출할 수 없는 경우

• 파일명이 <name>.md 형식으로 되어 있는지 확인
• 프론트매터 (frontmatter, ---로 둘러싸인 메타데이터)의 name:이 올바른지 확인
• Claude Code를 재시작하여 agents를 재스캔(re-scan) 수행

connected 상태가 되지 않는 경우

• MCP 서버가 claude mcp list를 통해 등록 자체에 성공했는지 확인
• /mcp에서 상태를 확인했을 때 needs auth라면 엔터를 눌러 OAuth 플로우 진행
• 네트워크 방화벽에서 MCP 엔드포인트(endpoint)로의 액세스가 허용되어 있는지 확인

다음 단계

여기까지 진행했다면 Claude Code의 기본 기능을 한 차례 모두 사용할 수 있는 상태가 되었습니다. 다음으로 더 깊게 파고들고 싶은 영역별로, Penne에 작성한 기사를 안내합니다.

관심 분야	참조 기사
subagent로 팀 구성하기	AI 에이전트 개발 팀의 "헌법"을 어떻게 설계했는가
subagent를 worktree로 격리하기	Claude Code의 worktree 격리를 신뢰하지 마라
hook으로 안전장치 구축하기	Claude Code의 PreToolUse hook으로 AI 에이전트의 행동을 물리적으로 제어하기
MCP로 Figma 연결하기	Claude Code와 Figma 공식 MCP 연결하기
실제 프로덕트 활용 사례	AI 에이전트 팀 개발 기록 1~3

Penne에서는 "안전 받아쓰기"라는 SaaS를 여러 개의 Claude Code 에이전트 (lead / dev / PO / webmaster / qa / claude-code-guide)와 함께 개발하고 있습니다. 멀티 에이전트 (multi-agent) 운용의 실례로서, 각 기사에서 구체적인 구성과 설계 판단을 기술하고 있습니다.

마치며

2025년 8월에 작성한 이전 기사에서는 "Claude Code를 어떻게 설치하는가"만으로도 한 편의 글이 되었습니다. 당시에는 npm을 통한 설치가 표준이었고, PATH 설정도 수동이었으며, 기능도 "터미널에서 사용할 수 있는 채팅형 AI" 수준에 머물러 있었습니다.

1년이 채 되지 않아 설치는 명령어 한 줄로 간편해졌고, subagent / MCP / hook이라는 신기능들을 한 차례 모두 사용할 수 있게 되면서 진입 장벽이 상당히 낮아졌다고 느낍니다.

도구가 가벼워진 만큼, 본래 하고 싶었던 일(코드 작성, 설계, 팀 구성)에 더 많은 시간을 할애할 수 있게 됩니다. 우선 curl -fsSL https://claude.ai/install.sh | bash로 시작해 보세요. 30분 정도면 위의 Step 6까지는 구동할 수 있을 것입니다.

"안전 받아쓰기"라는 서비스를 만들고 있습니다. 취재나 회의 음성을 저희 전용 서버에서 처리하며, Google이나 OpenAI 같은 외부 AI 기업에는 전송하지 않는 설계의 SaaS입니다. 사적인 대화를 외부 AI 서비스에 안심하고 맡겨도 될까? 라는 불안함에서 시작된 프로젝트입니다. 여러 개의 Claude Code 에이전트와 함께 개발하고 있습니다.

Discussion