Claude Code CLI를 처음 깔고, 프로젝트별 지침·권한·hooks·MCP까지 셋업해 매일 쓸 수 있는 상태로 만드는 단일 경로.

Claude Code는 Anthropic의 공식 CLI 에이전트다. 잘 깔기만 하면 강력하지만, 셋업 단계에서 권한 모델·CLAUDE.md·hooks·MCP 같은 것들을 그냥 넘기면 매일 같은 작업을 수동으로 반복하게 된다. 이 가이드는 macOS/Linux/Windows(Git Bash 또는 WSL2) 공통 기준으로, 설치 → 인증 → 프로젝트 지침 → 권한 → hooks → MCP 순으로 한 번에 정리한다.

대상은 "이미 git/Node는 잘 쓰지만 Claude Code는 처음" 또는 "쓰고 있긴 한데 셋업이 정리가 안 됐다"인 개발자다.

TL;DR

Node.js 20+ → npm install -g @anthropic-ai/claude-code → claude 실행 → 브라우저 인증
프로젝트 루트에 CLAUDE.md (1~2화면 분량 지침) + .claude/settings.json (권한·env·hooks)
핵심 슬래시 커맨드 3개만 먼저: /help, /config, /init
자주 거부되는 명령은 .claude/settings.json의 permissions.allow에 추가
필요할 때만 MCP 서버 추가 (로컬 stdio 우선, 인증 토큰은 env)

사전 조건

Node.js 20 이상 — node -v로 확인. 미만이면 mise 또는 nvm으로 업그레이드
Anthropic 계정 — console.anthropic.com 또는 Claude.ai Pro/Max 구독
Git — 프로젝트 자동 분석에 사용. macOS는 /mac/initial-setup 가이드 참조
운영체제: macOS / Linux / Windows (Git Bash 또는 WSL2 권장. 순수 PowerShell도 동작하지만 sh 기반 hooks 호환성 ↓)

1. 설치 — 5분

1.1 npm 글로벌 설치

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

권한 에러 시: sudo npm install -g ... 대신 npm prefix를 사용자 디렉토리로 옮기는 것이 안전하다.
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=$HOME/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code

1.2 첫 실행 + 인증

작업할 프로젝트 디렉토리로 이동한 뒤 실행:

cd ~/projects/my-repo
claude

처음이면 브라우저가 열리며 Anthropic 계정 인증을 요구한다. 인증이 끝나면 CLI에서 바로 채팅이 시작된다. 인증 토큰은 OS 키체인에 저장되므로 매번 재로그인하지 않는다.

1.3 검증

claude --version
# 0.x.x 형태로 출력

2. 핵심 슬래시 커맨드 — 5분

CLI 안에서 /로 시작하는 명령들이 슬래시 커맨드다. 초기엔 3개만 알면 된다.

커맨드	용도
`/help`	사용 가능한 명령 + 키바인딩 전체 보기
`/config`	모델·테마·기본 권한 모드 설정 (대화형 UI)
`/init`	현재 디렉토리를 분석해 `CLAUDE.md` 초안 자동 생성

/init은 첫 프로젝트 셋업 시 반드시 한 번 돌린다 — 폴더 구조·언어·빌드 도구를 분석해서 그럴듯한 초안을 박아준다. 이후 본인 손으로 다듬는다.

3. `CLAUDE.md` — 프로젝트 지침 (가장 중요)

CLAUDE.md는 프로젝트 루트에 두는 markdown 파일로, 모든 세션 시작 시 자동 로드된다. 여기에 적힌 규칙은 세션 내내 우선순위 1이다.

좋은 `CLAUDE.md` 구성

# 프로젝트명 — Claude 지침
 
## 페르소나
(선택) 시니어 개발자로서 ... 같은 역할 명시.
 
## 기술 스택
- Framework: Next.js 16 (App Router)
- 언어: TypeScript strict
- DB: Supabase
 
## 명령
- 개발 서버: `pnpm dev`
- 빌드: `pnpm build`
- 테스트: `pnpm test`
 
## 코딩 컨벤션
- `any` 금지 (TS strict)
- 파일명: kebab-case (라우트), camelCase (유틸)
- 시크릿 하드코딩 금지
 
## Git 컨벤션
- 커밋: `[프로젝트] {타입}: {설명}` — feat/fix/refactor/...
- main 직접 push: OK (단일 작업자) / PR 필수 (팀)
 
## 작업 원칙
1. 5+파일 수정·새 모듈·아키텍처 변경은 계획 먼저
2. 코드 변경 후 lint+빌드+테스트 통과 전까지 "완료" 금지
3. 시크릿·DB 마이그레이션·외부 push는 승인 받기

Tip

너무 길게 쓰지 말 것 — 1~2화면이면 충분. 길어지면 memory/rules/{topic}.md로 외부화하고 CLAUDE.md에서 링크
프로젝트별로 따로 둔다 — 글로벌 지침은 ~/.claude/CLAUDE.md (사용자 홈)
코드와 함께 git에 커밋해 팀원·다른 머신과 공유

4. `.claude/settings.json` — 권한·env·hooks

프로젝트 루트의 .claude/settings.json이 세션 동작을 제어하는 핵심 파일. 가장 많이 만지는 곳은 permissions다.

4.1 기본 구조

{
  "permissions": {
    "allow": [
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(pnpm test:*)",
      "Read(/Users/me/projects/**)"
    ],
    "deny": [
      "Bash(rm -rf /:*)",
      "Bash(sudo *)"
    ]
  },
  "env": {
    "EDITOR": "code --wait"
  },
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          { "type": "command", "command": "echo '[Session start] $(date)'" }
        ]
      }
    ]
  }
}

4.2 권한 규칙 (`permissions.allow` / `deny`)

매번 Bash(...)로 거부되는 명령이 있다면 패턴으로 allow에 추가
패턴은 prefix 매칭: Bash(pnpm:*)는 pnpm으로 시작하는 모든 명령 허용
위험한 패턴(rm -rf, sudo, curl ... | bash)은 deny에 박아 실수 방지

💡 자주 거부되는 read-only 명령을 한 번에 정리하고 싶다면, CLI에서 /fewer-permission-prompts 같은 빌트인 스킬을 실행해 transcript 기반으로 추천 받을 수 있다.

4.3 다운로드 가능 템플릿

위 구성을 그대로 쓸 수 있는 템플릿 (검증 후 사용):

settings.example.json

# 1. 다운로드
curl -fsSL https://devalice.jaceclub.com/assets/ai-agents/claude-code/settings.example.json -o .claude/settings.example.json
 
# 2. SHA-256 검증
shasum -a 256 .claude/settings.example.json
# 기대값: 22898a20ade2b3497f8299a8ca6139112c476e0a0a4075e1a05123a02c8266ac
 
# 3. 검토 후 settings.json으로 복사
less .claude/settings.example.json
cp .claude/settings.example.json .claude/settings.json

시크릿(API 키 등)은 settings.json에 직접 적지 말고, OS env 또는 .env(gitignored)에서 읽도록 한다.

4.4 글로벌 vs 프로젝트 vs 로컬

파일	위치	용도
`~/.claude/settings.json`	홈	모든 프로젝트 공통 권한·env (예: `git status` 항상 허용)
`<project>/.claude/settings.json`	프로젝트 루트 (git 커밋)	팀 공유 권한·hooks
`<project>/.claude/settings.local.json`	프로젝트 루트 (gitignored)	본인 머신 전용 (개인 토큰·로컬 경로)

5. Hooks — 자동화 트리거

Hooks는 특정 이벤트에 셸 명령을 자동 실행하는 메커니즘이다. 주요 이벤트:

이벤트	시점
`SessionStart`	세션 시작
`PreToolUse`	도구 호출 직전 (검증·차단 가능)
`PostToolUse`	도구 호출 직후
`Stop`	Claude 응답 종료
`UserPromptSubmit`	사용자 프롬프트 제출 직후

예시 1: 세션 시작 시 환경 정보 출력

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "printf '[세션 시작] %s\\n브랜치: %s\\n' \"$(date '+%F %T')\" \"$(git branch --show-current 2>/dev/null || echo none)\""
          }
        ]
      }
    ]
  }
}

예시 2: 위험한 파일 쓰기 차단

PreToolUse hook에서 exit code로 차단할 수 있다. (1: 경고, 2: 차단)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | grep -qE '\\.env$|secrets/|private_key' && { echo 'BLOCKED: secret file'; exit 2; } || exit 0"
          }
        ]
      }
    ]
  }
}

Hook 상세 스펙은 /help의 docs 링크 또는 공식 문서를 참고. 디버깅 중엔 echo 한 줄짜리 hook으로 발화 여부부터 확인하면 빠르다.

6. MCP 서버 통합 — 필요할 때만

MCP(Model Context Protocol) 서버는 Claude Code에 외부 도구를 노출하는 표준이다. 깃허브·Slack·Linear·Figma 등 통합이 있고, 사용자가 직접 만들 수도 있다.

등록 방법

.claude/settings.json의 mcpServers에 추가:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

${GITHUB_TOKEN}은 shell env에서 expand 된다 — .zshrc나 .envrc(direnv)에 export GITHUB_TOKEN=...로 두면 settings.json에 시크릿이 박히지 않는다.

안전 가이드

로컬 stdio 서버 우선 (command: "npx" / 로컬 바이너리) — 네트워크 RPC 서버보다 공격면이 작다
공식/검증된 패키지만 — @modelcontextprotocol/*, @upstash/* 등. 무명 패키지는 사용 전 코드 점검
시크릿은 env로 — settings.json은 git에 커밋되는 경우가 많다. 토큰을 직접 박지 말 것

7. IDE 통합 — VS Code · Cursor

Claude Code는 CLI지만 IDE 안에서도 띄울 수 있다.

VS Code / Cursor 통합 터미널에서 claude 명령을 그대로 실행 — 가장 단순. 파일 편집은 IDE에서, 대화는 터미널에서.
VS Code 확장: 마켓플레이스에서 "Claude Code" 검색. 사이드패널로 띄울 수 있다.
JetBrains (IntelliJ/PyCharm 등): 플러그인 마켓에서 설치 가능.

Cursor·Windsurf 같은 AI 네이티브 에디터를 이미 쓴다면, Claude Code는 "여러 파일·셸·git을 동시에 다루는 큰 작업" 전용으로 두고 인라인 코딩은 에디터 AI에 맡기는 분담이 효율적이다.

8. 검증 — 셋업이 완성됐나?

# 1. 설치 확인
claude --version
 
# 2. 프로젝트 셋업 파일 확인
ls -la CLAUDE.md .claude/settings.json
 
# 3. 글로벌 설정 확인
ls -la ~/.claude/settings.json 2>/dev/null && echo "global OK" || echo "no global (선택)"
 
# 4. 인증 확인 — claude 실행 후 아래 출력
#    > claude
#    │ Welcome to Claude Code!

위 4가지가 통과하면 셋업 완료. 다음으로 실제 작업: 프로젝트 디렉토리에서 claude를 띄우고 첫 명령 — 예: "이 repo 구조를 한 문단으로 설명해줘" — 으로 동작 검증.

9. 트러블슈팅

`command not found: claude`

npm 글로벌 bin이 PATH에 없는 경우. npm config get prefix로 prefix 확인 → <prefix>/bin을 ~/.zshrc(~/.bashrc)에 추가
Windows Git Bash: npm config get prefix가 C:\Users\<you>\AppData\Roaming\npm인지 확인. 이 경로가 PATH에 있어야 함

첫 실행 시 브라우저 인증이 안 열림

헤드리스 환경(SSH 원격, WSL2 등): CLI에 표시되는 URL을 수동으로 브라우저에 붙여 인증
인증 후에도 실패하면 ~/.claude/ 디렉토리의 토큰 캐시 삭제 후 재시도

Bash 명령마다 권한 묻기 — 너무 자주

.claude/settings.json의 permissions.allow에 자주 쓰는 read-only 명령을 추가
또는 CLI 안에서 /config → permission mode를 acceptEdits로 (코드 편집은 자동 승인, 셸은 여전히 물음)

Hooks가 발화 안 함

# 1. settings.json 구문 확인 (JSON 파싱 OK?)
cat .claude/settings.json | jq .
 
# 2. 명령부터 단순화해 발화 여부 확인
# command: "echo HOOK_FIRED >> /tmp/claude-hook.log"

JSON 파싱이 깨져있으면 hook 자체가 등록되지 않는다.

MCP 서버가 안 뜸

claude mcp list (CLI 안에서 /mcp) — 등록된 서버와 상태 확인
command가 PATH에 있는지 (which npx)
로그: ~/.claude/logs/ 또는 stderr 출력 확인

10. 다음 단계

이 가이드는 "Claude Code를 매일 쓸 수 있는 상태"까지였다. 그다음은:

워크플로 노하우 — 멀티 에이전트·plan 모드·서브에이전트 활용 (준비 중)
Cursor 비교/병행 — /ai-agents/cursor-setup (준비 중)
고급 hooks 패턴 — SessionStart로 메모리 동기화, PreToolUse로 보안 가드 (준비 중)
MCP 서버 자작 — 사내 도구 노출하기 (준비 중)

참고 링크

변경 이력

2026-05-11 — 초안 (devAlice M0 두 번째 시드 컨텐츠)

Claude Code 셋업 — 설치부터 권한·hooks·MCP까지 첫 1시간

TL;DR

사전 조건

1. 설치 — 5분

1.1 npm 글로벌 설치

1.2 첫 실행 + 인증

1.3 검증

2. 핵심 슬래시 커맨드 — 5분

3. `CLAUDE.md` — 프로젝트 지침 (가장 중요)

좋은 `CLAUDE.md` 구성

Tip

4. `.claude/settings.json` — 권한·env·hooks

4.1 기본 구조

4.2 권한 규칙 (`permissions.allow` / `deny`)

4.3 다운로드 가능 템플릿

4.4 글로벌 vs 프로젝트 vs 로컬

5. Hooks — 자동화 트리거

예시 1: 세션 시작 시 환경 정보 출력

예시 2: 위험한 파일 쓰기 차단

6. MCP 서버 통합 — 필요할 때만

등록 방법

안전 가이드

7. IDE 통합 — VS Code · Cursor

8. 검증 — 셋업이 완성됐나?

9. 트러블슈팅

`command not found: claude`

첫 실행 시 브라우저 인증이 안 열림

Bash 명령마다 권한 묻기 — 너무 자주

Hooks가 발화 안 함

MCP 서버가 안 뜸

10. 다음 단계

참고 링크

변경 이력

댓글

Claude Code 셋업 — 설치부터 권한·hooks·MCP까지 첫 1시간

TL;DR

사전 조건

1. 설치 — 5분

1.1 npm 글로벌 설치

1.2 첫 실행 + 인증

1.3 검증

2. 핵심 슬래시 커맨드 — 5분

3. CLAUDE.md — 프로젝트 지침 (가장 중요)

좋은 CLAUDE.md 구성

Tip

4. .claude/settings.json — 권한·env·hooks

4.1 기본 구조

4.2 권한 규칙 (permissions.allow / deny)

4.3 다운로드 가능 템플릿

4.4 글로벌 vs 프로젝트 vs 로컬

5. Hooks — 자동화 트리거

예시 1: 세션 시작 시 환경 정보 출력

예시 2: 위험한 파일 쓰기 차단

6. MCP 서버 통합 — 필요할 때만

등록 방법

안전 가이드

7. IDE 통합 — VS Code · Cursor

8. 검증 — 셋업이 완성됐나?

9. 트러블슈팅

command not found: claude

첫 실행 시 브라우저 인증이 안 열림

Bash 명령마다 권한 묻기 — 너무 자주

Hooks가 발화 안 함

MCP 서버가 안 뜸

10. 다음 단계

참고 링크

변경 이력

댓글

3. `CLAUDE.md` — 프로젝트 지침 (가장 중요)

좋은 `CLAUDE.md` 구성

4. `.claude/settings.json` — 권한·env·hooks

4.2 권한 규칙 (`permissions.allow` / `deny`)

`command not found: claude`