Claude Code 설치와 첫 사용 FAQ
오피스 아워에서 가장 자주 나오는 질문에 대한 짧은 답변과, 더 깊이 살펴볼 수 있는 링크를 정리했습니다. 처음 몇 주 동안의 흐름에 맞춰 구성했습니다.
사용 방법
다음 다섯 섹션은 개발자의 첫 몇 주 여정에 따라 구성되어 있습니다: 시작하기, 일상적인 사용, 한 단계 발전하기, 자주 겪는 문제, 개인정보 보호, 그리고 신뢰. 지금 자신의 위치에 맞는 섹션을 훑어보거나, 특정 질문을 검색하세요.
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를 실행하세요. 참고: Quickstart |
| 1.2 설치했는데 “claude: command not found”가 표시됩니다 | 네이티브 설치 프로그램은 바이너리를 ~/.local/bin/claude에 둡니다(Windows: %USERPROFILE%\.local\bin). 해당 디렉터리를 PATH에 추가하세요. 예를 들어 ~/.zshrc 또는 ~/.bashrc에 export PATH="$PATH:$HOME/.local/bin"를 넣은 뒤 터미널을 다시 시작하세요. 참고: Troubleshooting: PATH |
| 1.3 로그인하면 잘못된 컴퓨터에서 브라우저가 열립니다 / SSH로 접속 중입니다 | 로그인 프롬프트에서 c를 눌러 인증 URL을 복사하세요. 로컬 브라우저에서 연 다음, 코드를 터미널에 다시 붙여넣으세요. 참고: Troubleshooting: auth |
| 1.4 로그인 직후 인증 오류가 나지만 접근 권한은 있습니다 | 400 “organization disabled”: ANTHROPIC_API_KEY 환경 변수가 남아 있어 로그인 정보를 덮어쓰고 있습니다. 이를 해제하고, 셸 프로필에서도 제거한 뒤 다시 시작하세요. 어떤 인증이 활성화되어 있는지 확인하려면 /status를 실행하세요. 403 Forbidden: 관리자가 아직 작업 공간에서 Claude Code를 활성화하지 않았거나, 회사 프록시가 방해하고 있을 수 있습니다. 참고: Troubleshooting: auth |
| 1.5 Claude Code는 내 요금제에 포함되나요? | 네. 유료 Claude 요금제와 Console(API) 액세스에 포함됩니다. 회사 계정으로 로그인하면 SSO는 자동으로 처리됩니다. 로그인 후 403이 뜬다면 보통 관리자가 아직 해당 작업 공간에 대해 활성화하지 않았다는 뜻입니다. 참고: Authentication |
| 1.6 Claude Code와 Claude의 채팅은 어떻게 다른가요? | Claude Code: 저장소를 읽고, 파일을 수정하고, 명령을 실행하는 코딩 에이전트입니다. Claude Desktop의 “Code” 탭이며, 터미널이나 IDE에서도 실행됩니다. Claude의 채팅(웹, Claude Desktop, 또는 모바일): 대화와 일회성 질문을 위한 채팅입니다. 같은 모델을 쓰지만, 도구의 형태가 다릅니다. 참고: Overview |
| 1.7 제 IDE에서도 동작하나요? | 네. VS Code와 JetBrains IDE(IntelliJ, PyCharm 등)를 위한 확장 기능이 제공됩니다. 별도의 터미널이 아니라 편집기 안에 통합된 같은 기능입니다. 참고: VS Code · JetBrains |
| 1.8 Copilot/Cursor 자동 완성과는 무엇이 다른가요? | 자동 완성은 다음 몇 줄을 제안합니다. Claude Code는 에이전트입니다. “실패하는 테스트를 고쳐” 같은 작업을 주면 파일을 읽고, 명령을 실행하고, 끝날 때까지 여러 파일을 수정합니다. “내 문장을 완성해 줘”에 가깝기보다 “문제가 있으니 처리해 줘”에 가깝습니다. 참고: Overview |
| 1.9 무엇부터 시도해 보면 좋을까요? | 미뤄 두었던, 지루하지만 어렵지는 않은 버그 하나를 맡겨 보세요. 예: “[file]의 테스트가 불안정한데, 이유를 찾아봐.” 코드 설명을 당신이 하는 대신, 코드 자체를 읽게 하세요. 참고: Common use cases |
| 1.10 어떻게 업데이트하나요? | 네이티브 설치는 백그라운드에서 자동 업데이트됩니다. 지금 강제로 업데이트하려면 claude update를 실행하세요. Homebrew/WinGet은 자동 업데이트되지 않습니다. 주기적으로 brew upgrade claude-code 또는 winget upgrade Anthropic.ClaudeCode를 실행하세요. 참고: Setup: updates |
2. 일상적인 사용
질문
답변
2.1 같은 명령에 계속 권한을 묻습니다
기본적으로 승인 내용은 현재 세션 동안만 유지됩니다. 계속 유지하려면:
• 프롬프트에서 “항상 허용”을 선택하세요
• .claude/settings.json의 permissions.allow에 패턴을 추가하세요
• 또는 /permissions를 실행해 대화형으로 관리하세요
참고: Permissions
2.2 권한 모드와 전환 방법
Shift+Tab을 눌러 모드를 순환합니다:
- auto · 백그라운드 안전성 검사와 함께 자동 승인합니다. 지원되는 모델에서, 조직이 관리 설정에서 비활성화하지 않은 경우 사용할 수 있습니다.
- manual · 위험한 편집이나 명령을 실행하기 전에 확인을 요청합니다
- acceptEdits · 파일 편집은 진행되지만, 명령을 실행하기 전에는 여전히 확인을 요청합니다
- plan · 읽기 전용입니다. 계획을 제안하고 승인을 기다립니다
참고: Permission modes
2.3 /init은 무엇이고 언제 실행하나요?
함께 여러 번 작업할 저장소라면 초반에 한 번 실행하세요. 프로젝트를 스캔해 빌드 명령, 아키텍처, 규칙이 담긴 CLAUDE.md를 작성합니다. 이후 세션마다 자동으로 불러오므로 Claude가 처음부터 문맥을 갖고 시작합니다.
2.4 CLAUDE.md에는 무엇을 넣나요?
도구로는 강제할 수 없지만 새 팀원이 첫날에 틀리기 쉬운 것들입니다: “main이 아니라 release에서 배포”, “모든 ID는 문자열”, “라우트 핸들러에서 DB를 직접 호출하지 말 것.” 두 화면 이내로 유지하세요. 그보다 길면 훑어만 보게 됩니다.
2.5 Claude가 제 CLAUDE.md를 따르지 않습니다
• 너무 길거나 너무 모호함: 실제로 중요한 규칙만 남기세요 • 설명문 속에 묻혀 있음: 반드시 지켜야 할 규칙은 상단에 두고, 명령형으로 쓰세요(“절대 X. 항상 Y.”)
참고: Best practices
2.6 붙여넣지 않고 특정 파일을 지정하기
@ 다음에 경로를 입력하세요(탭 자동완성 가능). 언급된 파일은 Claude가 응답하기 전에 읽습니다.
참고: Common workflows
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 What is MCP? | MCP는 Claude Code를 외부 도구와 연결합니다: GitHub, Linear, Slack, 데이터베이스, 관측 스택 등. 하나의 .mcp.json 설정만 있으면 Claude가 이슈를 읽고, 데이터를 조회하고, 여러분이 쓰는 것과 같은 도구로 작업할 수 있습니다. 가장 흔한 첫 번째 연결 대상은 이슈 트래커입니다. 참고: MCP |
| 3.2 Wire up your first MCP server | • 프로젝트 루트에 .mcp.json을 추가하거나 claude mcp add를 사용합니다 • 각 항목에는 서버 패키지와 환경 변수(보통 인증 토큰)가 포함됩니다 • Claude Code를 다시 시작하고 /mcp를 실행해 연결되었는지 확인합니다 참고: MCP setup |
| 3.3 What are hooks for? | 이벤트에 따라 실행되는 셸 스크립트입니다(도구 실행 전, 파일 편집 후, Claude가 사용자 입력을 기다릴 때). 가장 흔한 첫 훅은 Claude가 입력을 필요로 할 때 데스크톱에 알림을 보내는 Notification 훅입니다. 같은 메커니즘으로 모든 편집 후 린터를 실행하거나, Slack에 पोस्ट하거나, 보호된 경로에 대한 편집을 차단할 수도 있습니다. 참고: Hooks guide |
| 3.4 Make a reusable prompt / skill | .claude/skills/ship/SKILL.md를 만들면 폴더 이름이 명령이 됩니다: /ship. 평범한 영어로 쓰면 되고, 특별한 문법은 필요 없습니다. 가장 쉬운 방법은 Claude에게 직접 작성해 달라고 하는 것입니다. (기존 .claude/commands/ship.md 경로도 여전히 작동합니다.) 참고: Skills |
| 3.5 Skills vs. legacy commands | 같은 메커니즘입니다. commands가 skills로 통합되었습니다. .claude/commands/foo.md와 .claude/skills/foo/SKILL.md는 둘 다 /foo를 만듭니다. skills 형식이 권장되며, 지원 파일(참고 문서, 템플릿, 도우미 스크립트)을 위한 폴더를 제공한다는 장점이 있습니다. 참고: Skills |
| 3.6 What are subagents good for? | 병렬 작업에 유용합니다: 코드베이스의 서로 다른 부분을 검색하거나, 여러 관점에서 diff를 검토하거나, 서로 경쟁하는 구현을 동시에 생성할 수 있습니다. मुख्य 세션이 결과를 종합합니다. 참고: Subagents |
| 3.7 Run non-interactively (CI / scripts) | claude -p "your prompt"는 한 번 실행되고 결과를 출력합니다. CI 훅, pre-commit 검사, 다른 도구로의 파이프 연결에 적합합니다. 인증은 로그인된 세션 또는 ANTHROPIC_API_KEY를 통해 합니다. 참고: Unix-style usage |
| 3.8 Undo what it did | /rewind는 이전 체크포인트로 되돌립니다. 체크포인트는 여러분이 보내는 모든 프롬프트마다 자동으로 생성됩니다. 이미 커밋된 내용은 일반적인 git revert를 사용하세요. 참고: Checkpointing |
| 3.9 Share your setup with the team | .claude/를 저장소에 커밋하세요(CLAUDE.md, commands, MCP config). 저장소를 클론한 사람은 누구나 같은 설정을 자동으로 받습니다. skills는 팀이 /plugin으로 설치하는 plugin으로도 패키징할 수 있습니다. 참고: Plugins |
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/... 대신 ~/). 속도 차이는 매우 큽니다. 참고: 문제 해결: WSL |
| 4.4 Mac에서 이미지 붙여넣기가 작동하지 않음 | Cmd+V가 아니라 Ctrl+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이 내 코드를 학습에 사용하나요? | 아니요. 귀하의 조직이 Team/Enterprise 약관을 사용하는 경우, 귀하의 코드와 대화 내용은 모델 학습에 사용되지 않습니다. 참고: Data usage |
| 5.2 내 코드는 실제로 어디로 가나요? | Claude Code는 사용자의 머신에서 실행됩니다. 소스 파일은 로컬에서 읽히며, 현재 작업에 필요한 부분만 응답 생성을 위해 API로 전송됩니다. 어떤 것도 인덱싱되거나, 전체 저장소가 업로드되거나, 학습에 사용되지 않습니다. 참고: Data usage |
| 5.3 다른 사람이 내 대화를 볼 수 있나요? | 아니요. 세션은 프로젝트 디렉터리별로 사용자의 머신에 로컬 저장되며, 팀원과 공유되지도 않고 어떤 대시보드에서도 보이지 않습니다. 대화를 공유하고 싶다면 /export를 사용하세요. 참고: Data usage |
| 5.4 비밀 정보와 .env 파일이 대화에 포함되지 않게 하려면 어떻게 하나요? | Claude는 작업에 필요한 파일만 읽으며, 저장소 전체를 스캔하지 않습니다. 특정 파일을 강제로 차단하려면 .claude/settings.json에 Read 거부 규칙을 추가하세요(예: "Read(.env*)"). 거부된 파일은 실수로 요청하더라도 읽을 수 없습니다. 참고: Permissions |
| 5.5 “acceptEdits” 모드는 내 허락 없이 무엇을 할 수 있나요? | 파일 편집은 프롬프트 없이 진행됩니다. 다만 셸 명령 실행, 네트워크 호출, 작업 디렉터리 밖의 항목을 건드릴 때는 여전히 확인을 요청합니다. 더 엄격하게 제어하려면 기본 모드를 사용하세요. 참고: Permissions |
부록: 아직도 해결되지 않나요?
| 리소스 | 무엇을 위한 것인지 |
|---|---|
/help | 세션에서 사용할 수 있는 항목을 나열하는 내장 명령어 |
/feedback | 터미널에서 이슈를 제출합니다(/bug의 별칭) |
| 전체 문서 | 여기의 모든 내용을 자세히 설명합니다 |
팀의 #claude-code 채널 | 작은 성과도 이상한 오류도 모두 여기에 어울립니다 |
부록: 자료 디렉터리
Claude Code는 자주 업데이트됩니다. 내부에 배포하기 전에 버전별 세부 사항은 code.claude.com/docs에서 확인하세요.
출처
- 원문: https://support.claude.com/en/articles/14554922-claude-code-user-faq (2026-10-27 · support.claude.com)