Claude Code 사용자 FAQ

질문

답변

1.1 어떻게 설치하나요?

macOS/Linux: curl -fsSL https://claude.ai/install.sh | bash
​Windows PowerShell: irm https://claude.ai/install.ps1 | iex
​Homebrew: brew install --cask claude-code
​WinGet: winget install Anthropic.ClaudeCode
그 다음 모든 저장소에서 claude를 실행하세요.

참고: 빠른 시작

1.2 설치했는데 "claude: command not found"

기본 설치 프로그램은 바이너리를 ~/.local/bin/claude (Windows: %USERPROFILE%\.local\bin)에 배치합니다. 해당 디렉토리를 PATH에 추가하세요. 예를 들어 ~/.zshrc 또는 ~/.bashrc에 export PATH="$PATH:$HOME/.local/bin"를 입력한 후 터미널을 다시 시작하세요.

참고: 문제 해결: PATH

1.3 로그인이 잘못된 머신의 브라우저를 열거나 SSH를 사용 중입니다

로그인 프롬프트에서 c를 눌러 인증 URL을 복사하세요. 로컬 브라우저에서 열고 코드를 터미널에 다시 붙여넣으세요.

참고: 문제 해결: 인증

1.4 로그인 직후 인증 오류가 발생하지만 액세스 권한이 있습니다

400 "organization disabled": 잘못된 ANTHROPIC_API_KEY 환경 변수가 로그인을 재정의하고 있습니다. 설정을 해제하고 셸 프로필에서 제거한 후 다시 시작하세요. /status를 실행하여 활성 인증을 확인하세요.
​403 Forbidden: 관리자가 아직 작업 공간에 대해 Claude Code를 활성화하지 않았거나 회사 프록시가 간섭하고 있습니다.

참고: 문제 해결: 인증

1.5 Claude Code가 내 플랜에 포함되어 있나요?

네. Team 및 Enterprise 시트와 Console(API) 액세스에 포함되어 있습니다. 회사 계정으로 로그인하세요. SSO는 자동으로 처리됩니다. 로그인 후 403이 표시되면 일반적으로 관리자가 아직 작업 공간에 대해 활성화해야 합니다.

참고: 인증

1.6 Claude Code vs. 데스크톱 앱 vs. claude.ai?

Claude Code: 저장소를 읽고 파일을 편집하고 명령을 실행하는 터미널 에이전트입니다.
​데스크톱 / claude.ai: 대화 및 일회성 질문을 위한 채팅 인터페이스입니다.
기본적으로 동일한 모델 제품군이지만 도구의 형태가 다릅니다.

참고: 개요

1.7 내 IDE에서 작동하나요?

네. VS Code 및 JetBrains IDE(IntelliJ, PyCharm 등)용 확장 프로그램을 사용할 수 있습니다. 동일한 기능이지만 별도의 터미널 대신 편집기에 포함되어 있습니다.

참고: VS Code · JetBrains

1.8 이것이 Copilot/Cursor 자동 완성과 어떻게 다른가요?

자동 완성은 다음 몇 줄을 제안합니다. Claude Code는 에이전트입니다: 작업을 지정하면("실패한 테스트 수정") 파일을 읽고 명령을 실행하며 완료될 때까지 다중 파일 편집을 수행합니다. "내 문장을 완성해"보다는 "문제가 있으니 해결해"에 더 가깝습니다.

참고: 개요

1.9 먼저 무엇을 시도해야 하나요?

미루고 있던 지루하지만 어렵지 않은 버그를 지정하세요. 예: "[파일]의 테스트가 불안정합니다. 이유를 파악하세요." 코드를 설명하는 대신 코드를 읽도록 하세요.

참고: 일반적인 사용 사례

1.10 어떻게 업데이트하나요?

기본 설치는 백그라운드에서 자동으로 업데이트됩니다. 지금 강제로 업데이트하려면 claude update를 실행하세요.
Homebrew/WinGet은 자동으로 업데이트되지 않습니다: 주기적으로 brew upgrade claude-code 또는 winget upgrade Anthropic.ClaudeCode를 실행하세요.

참고: 설정: 업데이트

질문

답변

2.1 같은 명령에 대해 계속 권한을 요청합니다

승인은 기본적으로 현재 세션 동안만 지속됩니다. 지속되도록 하려면:
• 프롬프트에서 "항상 허용"을 선택하세요
• .claude/settings.json의 permissions.allow에 패턴을 추가하세요
• 또는 /permissions를 실행하여 대화형으로 관리하세요

참고: 권한

2.2 권한 모드 및 전환 방법

Shift+Tab을 눌러 모드를 순환하세요:

참고: 권한 모드

2.3 /init란 무엇이고 언제 실행하나요?

한 번 실행하고, 초기에, 두 번 이상 작업할 저장소에서 실행하세요. 프로젝트를 스캔하고 빌드 명령, 아키텍처, 규칙을 포함한 CLAUDE.md를 작성합니다. 이후 모든 세션에서 자동으로 로드되므로 Claude가 컨텍스트와 함께 시작됩니다.

참고: 메모리 및 CLAUDE.md

2.4 CLAUDE.md에 무엇을 넣나요?

도구가 강제할 수 없지만 새로운 팀원이 첫날에 실수할 수 있는 것들: "main이 아닌 release에서 배포", "모든 ID는 문자열", "경로 핸들러에서 DB를 직접 호출하지 마세요." 두 화면 이하로 유지하세요. 더 길면 훑어보기만 합니다.

참고: 메모리 및 CLAUDE.md

2.5 Claude가 내 CLAUDE.md를 따르지 않습니다

• 너무 길거나 모호함: 실제로 중요한 규칙으로 정리하세요
• 산문에 묻혀 있음: 어려운 규칙을 위에 배치하고, 명령형 언어를 사용하세요 ("절대 X를 하지 마세요. 항상 Y를 하세요.")

참고: 모범 사례

2.6 붙여넣지 않고 특정 파일을 지정하세요

@를 입력한 후 경로를 입력하세요 (탭 자동완성). 언급된 파일은 Claude가 응답하기 전에 읽혀집니다.

참고: 일반적인 워크플로우

2.7 프롬프트에 스크린샷을 붙여넣으세요

이미지를 터미널로 드래그하거나 Ctrl+V를 누르세요. Mac에서는 Cmd가 아닌 Ctrl입니다 (Cmd+V는 텍스트를 붙여넣습니다). 오류 대화상자, UI 목업, 화이트보드 사진에 작동합니다.

참고: 이미지 작업

2.8 Claude의 응답을 터미널에서 복사하세요

/copy는 마지막 응답을 클립보드에 넣습니다. /export는 전체 대화를 파일에 작성합니다.

2.9 이전 세션을 다시 가져오세요

claude --continue는 가장 최근 세션을 재개합니다. claude --resume은 선택할 목록을 엽니다. 세션은 프로젝트 디렉토리별로 로컬에 저장됩니다.

참고: 일반적인 워크플로우: 재개

2.10 모델 전환

/model은 선택기를 엽니다. 모든 세션에서 동일한 모델을 원하면 .claude/settings.json에서 기본값을 설정하세요.

참고: 모델 구성

2.11 확장 사고

기본적으로 활성화됩니다. 추론 자체는 일반 보기에서 숨겨집니다. Ctrl+O를 눌러 읽고 싶으면 상세 기록으로 전환하세요. /effort를 사용하여 깊이를 높이거나 낮추세요. 까다로운 디버깅이나 아키텍처 결정을 위해 추가 지연 시간을 감수할 가치가 있습니다.

참고: 확장 사고

2.12 작업 중에 중지하세요

Ctrl+C를 눌러 현재 생성을 취소한 후 대신 할 일을 말하세요. 대화를 다시 시작할 필요가 없습니다.

질문

답변

3.1 MCP란 무엇인가요?

MCP는 Claude Code를 외부 도구에 연결합니다: GitHub, Linear, Slack, 데이터베이스, 관찰성 스택. 하나의 .mcp.json 구성으로 Claude는 문제를 읽고, 데이터를 쿼리하고, 사용자와 동일한 도구로 작업할 수 있습니다. 일반적인 첫 번째 커넥터: 문제 추적기.

참고: MCP

3.2 첫 번째 MCP 서버를 연결하세요

• 프로젝트 루트에 .mcp.json을 추가하거나 claude mcp add를 사용하세요
• 각 항목은 서버 패키지와 환경 변수(일반적으로 인증 토큰)를 이름 지정합니다
• Claude Code를 다시 시작하고 /mcp를 실행하여 연결되었는지 확인하세요

참고: MCP 설정

3.3 훅은 무엇을 위한 것인가요?

이벤트에서 실행되는 셸 스크립트 (도구 실행 전, 파일 편집 후, Claude가 입력을 기다릴 때). 일반적인 첫 번째 훅: Claude가 입력이 필요할 때 데스크톱에 알림을 보내는 알림 훅. 동일한 메커니즘으로 모든 편집 후 린터를 실행하거나, Slack에 게시하거나, 보호된 경로로의 편집을 차단할 수 있습니다.

참고: 훅 가이드

3.4 재사용 가능한 프롬프트 / 스킬 만들기

.claude/skills/ship/SKILL.md를 만들면 폴더 이름이 명령이 됩니다: /ship. 평문, 특수 구문 없음. 가장 쉬운 방법: Claude에게 작성하도록 요청하세요. (레거시 .claude/commands/ship.md 경로는 여전히 작동합니다.)

참고: 스킬

3.5 스킬 vs. 레거시 명령

동일한 메커니즘; 명령이 스킬로 병합되었습니다. .claude/commands/foo.md와 .claude/skills/foo/SKILL.md 모두 /foo를 만듭니다. 스킬 형식이 선호되며 지원 파일(참고 문서, 템플릿, 도우미 스크립트)을 위한 폴더를 제공합니다.

참고: 스킬

3.6 서브에이전트는 무엇에 좋은가요?

병렬 작업: 코드베이스의 다른 부분을 검색하거나, 다양한 차원을 따라 diff를 검토하거나, 동시에 경쟁하는 구현을 생성합니다. 주 세션이 결과를 집계합니다.

참고: 서브에이전트

3.7 비대화형 실행 (CI / 스크립트)

claude -p "your prompt"는 한 번 실행되고 결과를 출력합니다. CI 훅, 사전 커밋 검사 또는 다른 도구로 파이핑하기에 좋습니다. 로그인한 세션 또는 ANTHROPIC_API_KEY를 통해 인증합니다.

참고: Unix 스타일 사용

3.8 수행한 작업 취소

/rewind는 이전 체크포인트로 롤백합니다. 체크포인트는 전송하는 모든 프롬프트에서 자동으로 생성됩니다. 이미 커밋된 항목의 경우 일반 git revert를 사용하세요.

참고: 체크포인팅

3.9 팀과 설정 공유

.claude/를 저장소에 체크인합니다 (CLAUDE.md, 명령어, MCP 구성). 저장소를 복제하는 모든 사람이 자동으로 동일한 설정을 받습니다. 스킬은 팀이 /plugin을 통해 설치하는 플러그인으로도 패키징할 수 있습니다.

참고: 플러그인

질문

답변

4.1 파일을 찾을 수 없음 / 검색 결과 없음

Claude Code는 ripgrep의 번들 복사본과 함께 제공되므로 설치할 필요가 없습니다. 번들 바이너리는 Alpine/musl 시스템에서 실패할 수 있습니다. 이 경우 시스템 복사본을 설치하고 (apk add ripgrep) USE_BUILTIN_RIPGREP=0을 설정하여 Claude가 대신 사용하도록 하세요.

참고: 문제 해결: 검색

4.2 SSH 또는 tmux에서 복사/붙여넣기 및 스크롤 손상

터미널 UI는 마우스 이벤트를 캡처합니다. 선택할 때 Shift를 누르고 있으면 이를 우회하거나 tmux를 구성하여 마우스 이벤트를 통과시킵니다. /copy와 /export는 문제를 완전히 해결합니다.

4.3 WSL에서 느림

/mnt/c/를 통해 Windows 파일을 읽는 것은 알려진 성능 저하입니다. 저장소를 WSL 파일 시스템으로 이동하세요 (/mnt/c/... 대신 ~/). 속도 차이는 극적입니다.

참고: 문제 해결: WSL

4.4 Mac에서 이미지 붙여넣기가 작동하지 않음

Cmd+V가 아닌 Ctrl+V를 사용하세요. Cmd+V는 텍스트를 붙여넣고, Ctrl+V는 클립보드의 이미지 경로입니다.

4.5 와일드카드 권한 규칙이 일치하지 않음

규칙을 점진적으로 구축합니다: 먼저 명령어를 대화형으로 승인하고, 설정에 기록된 내용을 확인한 다음, 일반화합니다.

참고: 권한 패턴

4.6 비대화형 -p 모드가 다르게 작동

비대화형/CI 실행의 경우 API 키 인증 및 환경 변수 토큰으로 구성된 MCP 서버를 선호합니다.

4.7 작업 중간에 컨텍스트 부족

/compact는 이전 대화를 요약하여 공간을 확보합니다. /clear는 CLAUDE.md와 설정을 로드한 상태로 새로 시작합니다. 긴 작업의 경우 단계로 나누고 단계 사이에 /clear를 사용하세요.

참고: 컨텍스트 관리

질문

답변

5.1 Anthropic이 내 코드로 학습합니까?

아니요. 조직의 팀/엔터프라이즈 약관에 따라 코드와 대화는 모델 학습에 사용되지 않습니다.

참고: 데이터 사용

5.2 내 코드는 실제로 어디로 갑니까?

Claude Code는 컴퓨터에서 실행됩니다. 소스 파일은 로컬에서 읽으며, 현재 작업에 필요한 부분만 응답을 생성하기 위해 API로 전송됩니다. 아무것도 인덱싱되거나 전체 저장소로 업로드되거나 학습에 사용되지 않습니다.

참고: 데이터 사용

5.3 다른 사람이 내 대화를 볼 수 있습니까?

아니요. 세션은 컴퓨터의 프로젝트 디렉토리별로 로컬에 저장되며 팀원과 공유되거나 대시보드에 표시되지 않습니다. 대화를 공유하려면 /export를 사용하세요.

참고: 데이터 사용

5.4 비밀과 .env 파일을 대화에서 어떻게 제외합니까?

Claude는 작업에 필요한 파일만 읽으며 전체 저장소를 스캔하지 않습니다. 특정 파일을 하드 블록하려면 .claude/settings.json에 읽기 거부 규칙을 추가하세요 (예: "Read(.env*)"). 거부된 파일은 실수로 요청하더라도 읽을 수 없습니다.

참고: 권한

5.5 "acceptEdits" 모드는 나에게 묻지 않고 무엇을 할 수 있습니까?

파일 편집은 프롬프트 없이 진행됩니다. 셸 명령어를 실행하거나 네트워크 호출을 하거나 작업 디렉토리 외부의 항목을 건드리기 전에 여전히 요청합니다. 더 엄격한 제어를 원하면 기본 모드를 유지하세요.

참고: 권한

리소스

용도

/help

세션에서 사용 가능한 항목을 나열하는 기본 제공 명령

/feedback

터미널에서 문제를 보고합니다(/bug의 별칭)

전체 문서

여기의 모든 내용을 자세히 설명합니다

팀의 #claude-code 채널

작은 성공과 이상한 오류 모두 여기에 속합니다

페이지

링크

빠른 시작

code.claude.com/docs/en/quickstart

문제 해결

code.claude.com/docs/en/troubleshooting

권한

code.claude.com/docs/en/permissions

메모리 및 CLAUDE.md

code.claude.com/docs/en/memory

MCP

code.claude.com/docs/en/mcp

데이터 사용

code.claude.com/docs/en/data-usage