메인 콘텐츠로 건너뛰기

Claude Code 사용자 FAQ

사무실 시간에 자주 나오는 질문에 대한 간단한 답변과 더 깊이 있는 내용으로 이동할 수 있는 링크입니다. 처음 몇 주 동안의 진행 상황에 따라 정리되어 있습니다.

이 가이드를 사용하는 방법

다음 5개 섹션은 개발자의 첫 주를 따릅니다: 시작하기, 일상적 사용, 수준 올리기, 일반적인 함정, 개인정보 보호 및 신뢰. 현재 상황과 일치하는 섹션을 훑어보거나 특정 질문을 검색하세요.

1. 시작하기

질문

답변

1.1 어떻게 설치하나요?

가장 쉬운 방법: Claude Desktop을 다운로드하고 요금제로 로그인한 후 “Code” 탭을 엽니다. Claude Code가 내장되어 있으므로 다른 것을 설치할 필요가 없습니다.

터미널:

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"을 입력한 후 터미널을 다시 시작합니다.

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

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

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

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

1.5 Claude Code가 내 요금제에 포함되어 있나요?

예. 유료 Claude 요금제 및 Console(API) 액세스에 포함됩니다. 직장 계정으로 로그인하면 SSO가 자동으로 처리됩니다. 로그인 후 403 오류는 일반적으로 관리자가 아직 작업 공간에 대해 활성화해야 함을 의미합니다.


참고: 인증

1.6 Claude Code와 Claude의 채팅 비교

Claude Code: 저장소를 읽고 파일을 편집하고 명령을 실행하는 코딩 에이전트입니다. Claude Desktop의 “Code” 탭이며 터미널이나 IDE에서도 실행됩니다.
​Claude의 채팅(웹, Claude Desktop 또는 모바일): 대화 및 일회성 질문을 위한 채팅입니다.
동일한 모델이 기반이지만 도구의 형태가 다릅니다.


참고: 개요

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. 일상적 사용

질문

답변

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

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


참고: 권한

2.2 권한 모드 및 전환 방법

Shift+Tab을 눌러 모드를 순환합니다:

  • auto · 백그라운드 안전 검사로 자동 승인합니다. 조직이 관리 설정에서 비활성화하지 않은 경우 지원되는 모델에서 사용 가능합니다.

  • manual · 위험한 편집이나 명령 전에 요청합니다

  • acceptEdits · 파일 편집은 진행되지만 명령 실행 전에 여전히 요청합니다

  • plan · 읽기 전용; 계획을 제안하고 승인을 기다립니다

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

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

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

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

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. 레벨 올리기

질문

답변

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 setup

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

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


참고: Hooks guide

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

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


참고: Skills

3.5 스킬 vs. 레거시 명령

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


참고: Skills

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

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

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

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

3.8 수행한 작업 취소

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

3.9 팀과 설정 공유

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


참고: 플러그인


4. 일반적인 주의사항

질문

답변

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/... 대신 ~/). 속도 차이는 극적입니다.

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

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

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

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

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

  • OAuth가 필요한 MCP 서버는 비대화형 모드에서 프롬프트할 수 없습니다

  • 대화형 승인은 이월되지 않습니다

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

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

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


5. 개인정보 보호 및 신뢰

질문

답변

5.1 Anthropic이 내 코드로 학습하나요?

아니요. 조직의 팀/엔터프라이즈 약관에 따라 귀사의 코드와 대화는 모델 학습에 사용되지 않습니다. 단, 조직이 개발 파트너 프로그램과 같이 모델 개선을 위해 데이터를 제공하기로 선택한 경우는 제외됩니다. /feedback으로 피드백을 보내면 제품 및 서비스 개선에 사용할 수 있습니다.

5.2 내 코드는 실제로 어디로 가나요?

Claude Code는 사용자의 컴퓨터에서 실행됩니다. 소스 파일은 로컬에서 읽으며, 현재 작업에 필요한 부분만 API로 전송되어 응답을 생성합니다. 전체 저장소는 인덱싱되거나 업로드되지 않습니다. 조직이 모델 개선을 위해 데이터를 제공하기로 선택하지 않은 한 코드는 학습에 사용되지 않습니다. /feedback으로 보고서를 보내거나 설문 후 세션 기록을 공유하기로 선택하면 코드를 포함한 해당 대화가 Anthropic으로 전송됩니다.

5.3 다른 사람이 내 대화를 볼 수 있나요?

팀원은 공유하지 않는 한 로컬 세션을 열 수 없습니다. 로컬 세션은 프로젝트 디렉터리별로 컴퓨터에 저장됩니다. 대화를 공유하려면 /export를 사용하세요. 회사는 세션을 검토할 수 있습니다. 팀 가시성으로 설정되거나 Slack에서 시작된 클라우드 세션은 조직의 다른 구성원에게 표시될 수 있습니다.

5.4 비밀과 .env 파일을 대화에서 제외하려면 어떻게 하나요?

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


참고: 권한

5.5 “acceptEdits” 모드는 나에게 묻지 않고 무엇을 할 수 있나요?

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


참고: 권한


부록: 여전히 막혔나요?

리소스

용도

/help

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

/feedback

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

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

팀의 #claude-code 채널

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


부록: 리소스 디렉토리

Claude Code는 자주 업데이트됩니다. 내부 배포 전에 code.claude.com/docs에서 버전별 세부 정보를 확인하세요.

답변이 도움되었나요?