본문으로 건너뛰기

❓ 자주 묻는 질문

설치 및 시작​

Q. Claude Code를 설치했는데 claude 명령어를 찾을 수 없다고 나옵니다.​

npm 글로벌 설치 경로가 PATH에 없는 경우입니다.

# 글로벌 경로 확인
npm config get prefix

# ~/.bashrc 또는 ~/.zshrc에 추가
export PATH="$PATH:$(npm config get prefix)/bin"

# 적용
source ~/.bashrc

Q. Node.js 버전이 맞지 않는다는 오류가 납니다.​

Claude Code는 Node.js 18 이상을 요구합니다.

node --version  # 현재 버전 확인

# nvm으로 업그레이드
nvm install 20
nvm use 20

Q. macOS에서 권한 오류가 납니다.​

sudo 없이 설치하려면 npm 글로벌 디렉토리 소유권을 수정하세요.

sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}
npm install -g @anthropic-ai/claude-code

API 키​

Q. API 키는 어디서 발급받나요?​

console.anthropic.com → API Keys 메뉴에서 발급받습니다. 계정 가입 후 결제 수단 등록이 필요합니다.

Q. API 키를 설정했는데 계속 인증 오류(401)가 납니다.​

  1. 키 앞뒤 공백 여부 확인
  2. ANTHROPIC_API_KEY 환경 변수명 오타 확인
  3. 키 권한이 "활성" 상태인지 대시보드에서 확인
  4. 그래도 안 되면 키를 새로 발급 후 시도

Q. 팀원과 API 키를 공유해도 되나요?​

보안상 권장하지 않습니다. 각자 개인 키를 발급하거나, 조직용 API 키를 용도별로 분리해서 사용하세요. 키 유출 시 즉시 비활성화하고 재발급받으세요.

비용 및 요금​

Q. Claude Code 사용료는 얼마인가요?​

Claude Code는 두 가지 방식으로 사용할 수 있습니다:

  1. 구독 플랜 (Pro/Max/Team): 월정액에 포함된 사용량 제공
  2. API 키: Anthropic API 사용량에 따라 종량제 과금

현재 요금은 Anthropic 가격 페이지에서 확인하세요.

Q. 한 달에 얼마나 쓸지 모르겠어요. 한도 설정이 가능한가요?​

Anthropic 콘솔에서 월 지출 한도(Usage Limit)를 설정할 수 있습니다. console.anthropic.com → Settings → Limits에서 설정하세요.

Q. 세션 중 현재까지 쓴 비용을 확인할 수 있나요?​

Claude Code 대화 중 /cost 커맨드를 입력하면 현재 세션의 누적 토큰 사용량과 예상 비용을 확인할 수 있습니다.

더 알아보기: 실전 비용 절감 전략과 캐싱 아키텍처는 Level 3: 비용 최적화 챕터를 참고하세요.

사용 중 오류​

Q. "Context window exceeded" 오류가 납니다.​

컨텍스트(대화 내용)가 모델의 최대 길이를 초과했습니다.

  • /compact 커맨드로 대화를 요약하거나
  • /clear로 새로 시작하세요
  • CLAUDE.md에 핵심 정보를 저장해두면 새 세션에서도 컨텍스트를 유지할 수 있습니다

Q. Claude가 같은 실수를 반복합니다.​

CLAUDE.md에 "하지 말 것" 규칙을 명시하세요.

## 주의사항
- `package-lock.json`은 절대 수동으로 수정하지 말 것
- 테스트 파일을 삭제하지 말 것
- `console.log` 디버그 코드를 커밋에 포함하지 말 것

더 알아보기: 장기적인 맥락 유지와 기업형 컨텍스트 관리는 Level 2: 메모리 시스템 챕터에서 심도 있게 다룹니다.

Q. 파일을 수정하고 나서 되돌리고 싶습니다.​

Claude Code가 수정한 파일은 git으로 추적됩니다.

git diff          # 변경 내용 확인
git restore .     # 전체 되돌리기
git restore 파일명  # 특정 파일만 되돌리기

Q. Claude가 응답을 중간에 멈춥니다.​

  • 네트워크 불안정 시 발생할 수 있습니다
  • 응답이 너무 길 경우 작업을 더 작게 나눠서 요청하세요
  • /doctor 커맨드로 설치 및 연결 상태를 진단해보세요

IDE 연동​

Q. VS Code에서 Claude Code 확장이 보이지 않습니다.​

VS Code Extensions 마켓플레이스에서 "Claude Code"로 검색하거나, 터미널에서 claude 실행 후 IDE 연동 옵션을 선택하세요.

Q. JetBrains IDE(IntelliJ, PyCharm 등)에서도 사용 가능한가요?​

JetBrains 플러그인 마켓플레이스에서 Claude Code 플러그인을 설치하면 됩니다. 동일한 API 키로 연동됩니다.

Agent SDK​

Q. Agent SDK는 어떻게 사용하나요?​

Agent SDK는 Claude Code를 프로그래밍 방식으로 실행하는 도구입니다. 3가지 방식이 있습니다:

  1. CLI: claude -p "프롬프트" (가장 간단)
  2. Python SDK: pip install claude-code 후 Python에서 호출
  3. TypeScript SDK: npm 패키지로 설치 후 TypeScript에서 호출

자세한 내용은 Agent SDK 공식 문서를 참조하세요.

더 알아보기: 실무 적용 사례와 자세한 활용법은 Level 4: Agent SDK 기초 챕터에서 다룹니다.

Q. Agent SDK 실행 시 Claude Code가 설치되어 있어야 하나요?​

네. Agent SDK는 Claude Code의 에이전틱 루프를 사용합니다. API를 직접 호출하는 것이 아니라 Claude Code를 프로그래밍 방식으로 제어하는 것입니다.

Q. 멀티에이전트 실행 시 API 키 하나로 여러 에이전트를 동시에 쓸 수 있나요?​

네, 가능합니다. 다만 동시 요청 수에 따라 Rate Limit에 걸릴 수 있으니 에이전트 수가 많은 경우 큐잉(queuing)을 적용하세요.

기타​

Q. Claude Code가 생성한 코드의 저작권은 누구에게 있나요?​

Anthropic 이용약관에 따르면 사용자가 생성한 출력물의 소유권은 사용자에게 있습니다. 다만 라이선스 관련 사항은 항상 법무 전문가와 확인하세요.

Q. 오프라인 환경에서도 사용 가능한가요?​

Claude Code는 Anthropic API에 인터넷 연결이 필요합니다. 완전 오프라인 환경에서는 사용할 수 없습니다.

Q. 한국어로 물어보면 한국어로 답해주나요?​

네, Claude는 한국어를 완벽하게 지원합니다. 한국어로 질문하면 한국어로 답변하며, CLAUDE.md에 Primary Language: 한국어를 명시하면 더 일관되게 한국어로 응답합니다.

Q. /review 커맨드가 사라졌나요?​

아니요, 다시 내장 커맨드로 사용할 수 있습니다. v2.1.202부터 /review는 빠른 단일 패스 리뷰로 돌아왔고, 멀티 에이전트 리뷰는 별도의 /code-review 커맨드로 분리되었습니다:

/review <pr#>               # 빠른 단일 패스 리뷰
/code-review <level> <pr#>  # effort 레벨을 지정하는 멀티 에이전트 리뷰

v2.1.215부터는 Claude가 /code-review(그리고 /verify)를 스스로 실행하지 않으므로, 필요할 때 직접 호출하세요.

Q. Fast Mode는 무엇인가요?​

/fast로 토글하는 고속 모드입니다. 같은 모델을 더 빠르게 실행하며, 별도 과금됩니다. 라이브 디버깅이나 빠른 반복 작업에 적합합니다. CLAUDE_CODE_DISABLE_FAST_MODE=1로 비활성화할 수 있습니다.

Q. 설치 상태를 진단하려면?​

/doctor 커맨드를 실행하면 Claude Code 설치, 설정, 연결 상태를 자동으로 진단합니다.

이 챕터를 완료하셨나요?

학습 진도를 체크하여 나의 로드맵 달성률을 높여보세요.