Claude Code 세팅 가이드

사전 요구사항 (git · Node.js)

💡 왜 필요한가요? sonmat 플러그인은 GitHub 리포를 git clone으로 가져옵니다. CLI 설치는 npm이 필요합니다. Node.js를 깔면 npm은 자동으로 따라옵니다.

git 확인

터미널 (Windows: PowerShell · Mac: Terminal)에서:

git --version

❌ "command not found" 또는 "찾을 수 없습니다"가 뜨면 설치:

• Windows: git-scm.com/download/win — 기본값으로 설치 (다음 다음 다음)
• Mac: xcode-select --install → 팝업의 "설치" 클릭
• Linux: sudo apt install git (Ubuntu 계열)

Node.js 18+ 확인

node --version

❌ 없거나 18 미만이면: nodejs.org → LTS 버전 다운로드 → 설치 → 터미널 새 창 열어서 다시 확인.

VS Code 설치 (없으면)

이미 쓰고 있다면 2단계로 바로 이동.

1. code.visualstudio.com 접속
2. 자기 OS에 맞는 설치 파일 다운로드 → 설치
3. 실행해서 창이 뜨면 OK

Claude Code 확장 프로그램 설치

VS Code를 열고, 왼쪽 사이드바의 확장 아이콘(네모 4개 모양, 단축키 Ctrl+Shift+X) 클릭.

검색창에 Claude Code 입력 → Anthropic 제공 확장 → Install 클릭.

또는 터미널에서 한 줄로:

VS Code 안에서 터미널을 열어 (Ctrl+` 백틱 키) 아래를 붙여넣기:

code --install-extension AnthropicAI.claude-code

Claude Code CLI 설치 (npm)

💡 왜? VS Code 확장만으로도 채팅은 됩니다. 하지만 sonmat 같은 플러그인을 깔려면 claude라는 명령어(CLI)가 필요해요. 한 번만 깔면 끝.

VS Code 안에서 터미널 열기 (Ctrl+` 백틱 키, 또는 상단 메뉴 → Terminal → New Terminal). 아래를 붙여넣고 엔터:

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

❌ Mac/Linux에서 권한 오류(EACCES)가 뜨면:

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

설치 끝나면 확인:

claude --version

❌ "command not found"가 뜨면 → 터미널을 새 창으로 열어서 다시 시도.

인증 (둘 중 하나)

방법 A — Claude 구독 중 (Pro/Max)

Claude Pro ($20/월) 이상 구독 중이면 추가 비용 없음.

확장 설치 후 Claude Code 패널을 열면 "Sign in" 버튼이 나옵니다. 클릭 → 브라우저로 Claude 계정 로그인 → 완료.

방법 B — API 키 (종량제, 구독 없이)

구독 없이 쓴 만큼만 과금 받고 싶다면:

1. console.anthropic.com 접속 → 계정 생성
2. Billing 메뉴 → 크레딧 충전 (최소 $5)
3. API Keys 메뉴 → "Create Key" → 복사
4. VS Code의 Claude Code 패널에서 API 키 붙여넣기

채팅창 열기

VS Code 왼쪽 사이드바에 Claude 아이콘이 생겼습니다 (작은 별 모양).

클릭하면 오른쪽에 채팅 패널이 열림. ChatGPT 웹과 비슷한 입력창이 보임.

❓ 채팅창이 안 보이나요?

• 상단 메뉴 → View → Command Palette (Ctrl+Shift+P) → Claude Code: Open 입력

권한 사전 설정 (settings.json)

💡 왜 먼저? Claude는 git/npm/python 같은 명령을 처음 쓸 때마다 "실행해도 될까요?" 권한 프롬프트를 띄웁니다. 매번 클릭하기 귀찮으니 자주 쓰는 안전 명령은 미리 허용 목록에 넣어두고 시작합니다.

6-1. ~/.claude/ 디렉토리 + 파일 만들기

VS Code 터미널 (Ctrl+`) 열고 OS에 맞는 명령 실행:

Mac · Linux · Windows WSL (bash)

mkdir -p ~/.claude && cat > ~/.claude/settings.json <<'EOF'
{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm *)",
      "Bash(npx *)",
      "Bash(node *)",
      "Bash(python *)",
      "Bash(uv *)",
      "Bash(uvx *)",
      "Bash(ruff *)",
      "Bash(mkdir *)",
      "Bash(ls *)",
      "Bash(cat *)",
      "Bash(echo *)",
      "Bash(pwd)",
      "Bash(which *)",
      "Bash(curl *)"
    ]
  }
}
EOF

Windows (PowerShell)

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude" | Out-Null
@'
{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm *)",
      "Bash(npx *)",
      "Bash(node *)",
      "Bash(python *)",
      "Bash(uv *)",
      "Bash(uvx *)",
      "Bash(ruff *)",
      "Bash(mkdir *)",
      "Bash(ls *)",
      "Bash(cat *)",
      "Bash(echo *)",
      "Bash(pwd)",
      "Bash(which *)",
      "Bash(curl *)"
    ]
  }
}
'@ | Set-Content -Path "$env:USERPROFILE\.claude\settings.json" -Encoding UTF8

6-2. 확인

cat ~/.claude/settings.json

sonmat 플러그인 설치

💡 sonmat이 뭔가요? AI가 성급하게 답하기 전에 "정말 맞나?" 한 번 더 검증하는 보조 장치입니다. 선택이지만 강력 추천.

채팅창 입력란에 슬래시(/)부터 시작하는 명령어를 한 줄씩 입력 (붙여넣기 후 엔터):

/plugin marketplace add jun0-ds/sonmat

첫 줄 결과: "marketplace 'sonmat' added" 같은 메시지.

/plugin install sonmat@sonmat

두 번째 줄 결과: "Plugin sonmat@sonmat installed" 같은 메시지.

❌ Windows에서 경로 오류(C:/Program Files/Git/plugin...)가 뜨면 → Git Bash 대신 PowerShell을 쓰거나, troubleshooting.md의 WSL 안내 참고.

나머지는 Claude에게 맡기기

채팅창이 열렸으면, auto-setup 프롬프트를 복사해서 채팅창에 붙여넣기:

📋 auto-setup.md — 이 파일을 열고, 내용 전체 선택(Ctrl+A) → 복사(Ctrl+C) → Claude 채팅창에 붙여넣기(Ctrl+V) → 엔터.

Claude가 질문을 시작하면 답하기만 하면 됩니다:

• "Python 프로젝트 하실 건가요?" → Yes/No
• "호칭 지정하시겠어요?" → 자유롭게 (또는 "그냥 존댓말이요")

Claude가 알아서:

• 글로벌 CLAUDE.md 생성 (호칭·기본 규칙)
• settings.json 생성 (sonmat 훅·권한 등)
• Python 도구 설치 (선택 시만)