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 확장 사고

기본적으로 활성화됨. 더 어려운 답변 전에 Claude의 추론을 볼 수 있습니다. /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/commands/에 드롭하세요. 파일 이름이 명령이 됩니다: .claude/commands/ship.md는 /ship이 됩니다. 평문, 특수 구문 없음. 가장 쉬운 방법: Claude에게 작성하도록 요청하세요.

참고: 슬래시 명령

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을 사용합니다. 누락된 경우 검색이 저하됩니다. 설치하고(brew install ripgrep 또는 apt install ripgrep) USE_BUILTIN_RIPGREP=0을 설정하여 시스템 복사본을 사용하세요.

참고: 문제 해결: 검색

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

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

4.3 WSL에서 느림

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

참고: 문제 해결: WSL

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

Ctrl+V를 사용하세요. Cmd+V는 텍스트를 붙여넣습니다. Ctrl+V는 클립보드에서 이미지 경로입니다.

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

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

참고: 권한 패턴

4.6 헤드리스 -p 모드는 다르게 작동합니다

• OAuth가 필요한 MCP 서버는 헤드리스 모드에서 프롬프트할 수 없습니다
• 대화형 승인이 이월되지 않습니다
헤드리스/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 "accept-edits" 모드는 나에게 묻지 않고 무엇을 할 수 있나요?

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

참고: 권한

리소스

용도

/help

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

/bug

터미널에서 이슈 제출 (/feedback 별칭)

전체 문서

여기의 모든 것, 자세히

팀의 #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