Claude Code란 무엇인가#
Claude Code가 무엇인지 사용법의 관점에서 다룹니다. 설치와 필요한 인증, 첫 작업 전 데이터·권한 확인, 승인과 제한적인 변경 복구를 살펴봅니다.
이 글은 터미널에서 실행하는 Claude Code CLI를 기준으로 합니다. 공식 빠른 시작은 같은 도구를 웹, 데스크톱 앱, VS Code와 JetBrains IDE, Slack, GitHub Actions와 GitLab CI/CD에서도 쓸 수 있다고 소개합니다. 권한 모드를 바꾸는 방법은 인터페이스마다 다르므로, 메뉴 이름을 따라가기 전에 사용하는 화면의 안내를 확인하세요.
| 단계 | 확인할 내용 |
|---|---|
| 설치·인증 | 운영체제에 맞는 공식 설치 방법과 계정 또는 제공자 이용 조건 |
| 첫 작업 | 프로젝트 설명을 요청하기 전에 권한 모드와 도구 접근 범위 |
| 승인 | 실행할 명령이나 변경할 파일과 경로, 승인 범위 |
- Claude Code 공식 빠른 시작에서 설치 방법을 확인합니다.
- 민감한 정보가 없는 프로젝트 폴더에서
claude를 실행하고 로그인 안내가 나오면 인증합니다. - 데이터 이용 조건과 권한 모드를 확인한 뒤 파일을 수정하지 말고 저장소 구조를 설명해 달라고 요청합니다.
- 승인 요청이 나오면 내용을 검토하고 원하지 않는 작업은 거절합니다.
추가 검증 필요: 실제 설치 과정과 인증, 한국어 입력·IME 및 한글 파일명 처리, 첫 작업과 권한 승인·중단 결과에 대한 기록은 아직 없습니다.
설치 전 확인: 계정·권한·비용#
공식 빠른 시작에 따르면 Claude Pro·Max·Ultra·Team·Enterprise 구독, Claude Console 계정 또는 지원되는 클라우드 제공자 접근 권한이 필요합니다. 무료 Claude 계정만으로 사용할 수 있다고 가정하지 말고 계정별 이용 조건과 비용을 먼저 확인하세요. 공식 문서 링크는 2026-11-03에 확인했습니다.
Console 계정으로 처음 로그인하면 Console에 “Claude Code” 워크스페이스가 자동으로 만들어져 사용 비용을 한곳에서 추적합니다. 회사 계정이라면 인증 안내의 조직 로그인 제한과 API 제공자 제한 항목을 먼저 확인하세요. 시작 전에는 세션에서 /status로 지금 쓰이는 인증 수단을 볼 수 있습니다.
설치 문서는 지원 환경으로 macOS 13.0 이상, Windows 10 1809 이상 또는 Windows Server 2019 이상, Ubuntu 20.04 이상, Debian 10 이상, Alpine Linux 3.19 이상을 적습니다. 하드웨어는 4GB 이상의 메모리와 x64 또는 ARM64 프로세서를 요구하고, 셸은 Bash, Zsh, PowerShell, CMD 가운데 하나를 씁니다. 인터넷 연결도 필요합니다.
설치와 인증#
Claude Code 공식 설치·인증 안내에서 운영체제에 맞는 설치 방법을 선택하세요. 설치 후 프로젝트 폴더에서 claude를 실행하고 로그인 안내가 나타나면 따르세요. 인증 안내에 따르면 이전 로그인이나 승인한 환경 변수의 API 키 등이 있으면 로그인 안내를 건너뛸 수 있으며, 클라우드 제공자는 별도의 인증 설정을 사용합니다. 별도의 Mirr Code 설치 문서는 Claude Code 설치 안내가 아닙니다.
공식 설치 안내는 여러 방법을 나열합니다. 권장되는 네이티브 설치는 macOS, Linux, WSL에서 설치 스크립트를, Windows PowerShell과 CMD에서는 각각 전용 명령을 실행하는 방식입니다. Homebrew는 claude-code와 claude-code@latest 두 cask를 제공합니다. 전자는 보통 한 주쯤 늦은 안정 채널이고 큰 회귀가 있는 릴리스를 건너뛰며, 후자는 최신 채널입니다. WinGet은 Anthropic.ClaudeCode 패키지를 쓰고, apt, dnf, apk 설치도 지원합니다. 네이티브 설치는 백그라운드에서 자동 업데이트되지만, Homebrew, WinGet, Linux 패키지 관리자 설치는 기본적으로 자동 업데이트되지 않으므로 brew upgrade나 winget upgrade로 직접 올려야 합니다.
네이티브 Windows에서는 Git for Windows를 함께 설치하는 것이 권장됩니다. 설치되어 있으면 Claude Code가 Bash 도구를 쓰고, 없으면 PowerShell을 셸 도구로 씁니다. WSL 환경에는 Git for Windows가 필요하지 않습니다.
설치 문서에 따르면 업데이트 채널은 /config의 Auto-update channel이나 설정 파일의 autoUpdatesChannel에서 latest(기본값)와 stable 가운데 고를 수 있습니다. 자동 업데이트 자체를 끄려면 설정 파일의 env 항목에 DISABLE_AUTOUPDATER를 1로 둡니다. 이 경우에도 claude update는 계속 동작합니다.
작업 담당자가 한 macOS 환경에서 확인했다고 적은 버전 출력입니다. 이 출력을 뒷받침하는 기록은 없고, 이 글에서 다시 실행해 아직 확인하지 않았습니다. 설치 과정, 로그인이나 작업 실행의 증거가 아니며 모든 환경의 버전을 뜻하지 않습니다.
$ claude --version
2.1.316 (Claude Code)
인증 수단이 여러 개 있으면 Claude Code는 정해진 순서로 하나를 고릅니다. 앞에서부터 클라우드 제공자 변수, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper 스크립트, CLAUDE_CODE_OAUTH_TOKEN, 프로필과 연동 자격 증명, 마지막으로 /login으로 받은 구독 로그인입니다. 대화형 모드에서 ANTHROPIC_API_KEY가 설정되어 있으면 키를 쓸지 한 번 묻고, 승인하면 구독 로그인보다 먼저 쓰입니다. 구독이 있어도 키가 속한 조직이 비활성화되었거나 만료되었다면 인증이 실패할 수 있으므로, 구독으로 돌아가려면 unset ANTHROPIC_API_KEY를 실행한 뒤 /status로 확인하세요.
로그인 정보는 macOS에서 암호화된 키체인에 저장됩니다. 키체인에 쓸 수 없을 때, 예를 들어 잠긴 SSH 세션에서는 ~/.claude/.credentials.json(권한 0600)에 저장됩니다. Linux는 같은 파일을 쓰고, Windows는 사용자 프로필 아래의 .credentials.json을 씁니다. 이 파일은 /login과 /logout으로 관리합니다.
세션 안에서는 /help로 사용할 수 있는 명령을 확인합니다. 세션을 끝내려면 /exit를 입력하거나 Ctrl+D를 두 번 누릅니다. 같은 폴더에서 이어 가려면 claude -c로 가장 최근 대화를, claude -r로 이전 대화를 다시 엽니다.
첫 작업: 수정하지 말라고 요청하기#
첫 작업에는 민감한 정보가 없는 저장소를 사용하세요. “읽기 전용”은 변경 여부에 관한 요청일 뿐 데이터 기밀성이나 권한 제한을 보장하지 않습니다. 코드와 요청이 모델 제공자에게 전달될 수 있으므로 먼저 Anthropic 데이터 사용·보존 안내와 실제 사용하는 계정·클라우드 제공자의 보존, 학습 및 데이터 처리 조건을 확인하세요.
Claude Code 권한 모드에서 Plan 모드와 현재 설정을 확인하세요. Plan 모드의 셸 명령 처리는 세션과 설정에 따라 달라지므로 완전한 읽기 전용 보안 경계로 간주하지 마세요.
전송 구간은 TLS 1.2 이상으로 암호화되지만, 보관 기간은 계정 종류와 설정에 따라 다릅니다. 데이터 이용 안내에 따르면 Free, Pro, Max, Ultra 계정은 모델 개선을 위한 데이터 사용을 허용하면 5년, 허용하지 않으면 30일 동안 보관합니다. Team, Enterprise, API 같은 상용 계정은 표준 30일 보관이며, 자격을 갖춘 Enterprise 조직만 조직 단위로 제로 데이터 보관(ZDR)을 받을 수 있습니다.
로컬에도 대화 기록이 남습니다. Claude Code 클라이언트는 세션을 이어 쓰기 위해 ~/.claude/projects/ 아래에 대화 기록을 평문으로 기본 30일 저장하며, cleanupPeriodDays 설정으로 기간을 바꿀 수 있습니다. 민감한 정보가 들어간 세션은 서버 보관과 별개로 이 폴더에 남을 수 있으므로, 연습 저장소에서 시작하라는 원칙은 로컬 기록에도 적용됩니다.
웹이나 클라우드에서 세션을 시작하면 경로가 달라집니다. 클라우드 세션은 기본적으로 Anthropic이 관리하는 가상 머신에서 실행되며, 저장소가 그 가상 머신에 복제되고 세션 기록은 나중에 돌아오기 위해 Anthropic 서버에 보관됩니다. GitHub 자격 증명은 Anthropic 서버에서 암호화되어 보관되고 가상 머신 안으로 들어가지 않습니다. 민감한 저장소라면 로컬 세션과 클라우드 세션 중 어디에서 실행할지 먼저 정하세요.
웹 페이지를 가져오는 WebFetch 도구는 요청 전에 호스트 이름을 Anthropic의 안전 차단 목록과 대조하며, 이때 전송되는 것은 호스트 이름뿐이고 전체 URL과 경로, 페이지 내용은 보내지 않습니다. 검사를 끄는 skipWebFetchPreflight 설정은 차단 목록 없이 어떤 URL이든 가져오므로, 이를 쓴다면 WebFetch 권한 규칙으로 허용 도메인을 따로 제한하세요.
데이터 이용 안내에 따르면 텔레메트리는 기본으로 사용 지표를 Anthropic에 보내며, DISABLE_TELEMETRY=1로 끌 수 있습니다. 세션 중 나오는 품질 평가 설문은 평점만 기록하고 대화 내용을 수집하지 않습니다. 다만 이어지는 질문에 “예”를 고르면 대화 기록과 그 세션의 원시 로그가 업로드될 수 있으므로, 민감한 세션에서는 그 질문에 응답하지 않는 편이 안전합니다. 설문은 CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1로 끌 수 있습니다.
반복해서 적을 지침은 CLAUDE.md에 두면 세션마다 다시 입력하지 않아도 됩니다. 예를 들어 “코드와 오류 원문은 그대로 두고 설명은 한국어로 해 달라”는 요청을 적을 수 있습니다. Claude는 이 파일을 세션 시작 때 읽지만, 메모리 안내는 CLAUDE.md를 강제 설정이 아니라 맥락으로 취급한다고 설명합니다. 개인 취향만 담는 파일은 CLAUDE.local.md로 만들고 .gitignore에 추가해 커밋되지 않게 하세요. /init은 빌드와 테스트 명령, 프로젝트 규칙을 찾아 시작용 CLAUDE.md 초안을 만들어 줍니다.
권한 승인과 중단#
권한 설정에서 도구별 허용·확인·거부 규칙을 확인하세요. 승인 요청이 항상 표시되는 것은 아니며 모드와 기존 규칙에 따라 달라집니다. Claude Code v2.1.283 이상에서는 대화형 터미널과 VS Code 세션의 기본 시작 권한 모드가 auto입니다(권한 모드). 셸의 간접 파일 접근까지 제한해야 한다면 공식 안내의 샌드박스와 격리 범위도 검토하세요.
대화형 조작 안내에 따르면 진행 중 Esc로 현재 응답이나 도구 호출을 중단하거나 열린 다이얼로그를 닫을 수 있습니다.
체크포인트 안내에 따르면 /rewind로 추적된 파일 변경을 복구할 수 있지만, 셸로만 변경된 파일과 다른 작업의 변경은 일반적으로 추적되지 않습니다. 반대로 Claude가 그 파일을 편집한 뒤 Bash 명령이 같은 파일에 가한 변경은 /rewind가 함께 되돌립니다. 복구 전에 그 Bash 변경을 확인하고 필요한 내용은 별도로 저장하세요. 체크포인트는 버전 관리의 대체물이 아닙니다.
권한 모드는 Claude가 묻지 않고 할 수 있는 행동의 범위를 정합니다. 기본 모드는 CLI에서 Manual로 표시되며 읽기만 자동으로 허용합니다. acceptEdits는 파일 수정과 mkdir, touch, mv, cp 같은 일반 파일 명령을 묻지 않고 실행하므로 검토 중인 코드에서만 쓰는 편이 안전합니다. plan은 파일을 읽고 탐색해 계획을 만들며, 계획을 승인하기 전에는 편집을 막습니다(bypass 권한을 쓸 수 있는 대화형 터미널 세션은 예외). dontAsk는 허용된 도구 밖의 호출을 묻지 않고 거부하며 CI와 스크립트용입니다. bypassPermissions는 격리된 컨테이너나 가상 머신에서만 쓰라고 안내합니다. Shift+Tab을 누르면 모드가 순서대로 바뀝니다.
권한 모드 안내에 따르면 보호 경로에 대한 쓰기는 저장소 상태와 Claude 설정을 지키려고 따로 정해져 있습니다. bypassPermissions 모드에서는 자동으로 허용되고, default와 acceptEdits 모드에서는 묻고, auto 모드에서는 분류기가 검토하고, dontAsk 모드에서는 거부됩니다. 설정 파일의 허용 규칙도 이 보호를 미리 풀어 주지 않습니다.
자동 모드에서는 행동마다 분류기가 검토하므로 묻는 횟수가 줄어듭니다. 분류기는 요청 범위를 넘는 행동, 인식되지 않는 인프라를 겨냥한 행동, Claude가 읽은 적대적 내용에 따른 것으로 보이는 행동을 막습니다. 명시적인 확인 규칙이 있으면 자동 모드에서도 여전히 묻고, 조직은 자동 모드 자체를 끌 수 있습니다.
권한 모드 안내에 따르면 시작 모드는 실행 방식에 따라 다릅니다. 설정 파일에 disableAutoMode가 disable로 있거나 조직에 HIPAA 구성이 적용되면 대화형 세션도 기본 모드로 시작할 수 있습니다. claude -p와 Agent SDK 실행은 권한 모드를 지정하지 않으면 v2.1.302 이상에서 Manual로 시작하며, 승인이 필요한 호출은 허용 규칙이나 훅으로 미리 승인하지 않는 한 거부됩니다.
계획 모드에서도 Claude는 셸 명령을 실행해 탐색할 수 있습니다. 자동 모드를 쓸 수 있고 useAutoModeDuringPlan 설정이 켜져 있으면(기본값), 분류기가 셸 명령을 검토해 승인된 명령은 실행합니다. 자동 모드를 쓸 수 없으면 기본 읽기 명령 밖의 명령마다 승인을 요청합니다. 계획을 승인하면 계획 모드가 끝나고 선택한 모드로 편집이 시작됩니다.
계획이 준비되면 Claude는 세 가지 중 하나를 고르라고 묻습니다. 자동 모드로 전환해 승인하거나, 편집마다 직접 검토하며 승인하거나, 계획을 더 다듬도록 계획 모드에 머무는 것입니다. Ctrl+G를 누르면 제안된 계획을 기본 편집기에서 직접 고칠 수도 있습니다.
권한 설정에 따르면 권한 규칙은 거부, 확인, 허용 순서로 평가되며 처음 일치한 규칙이 결과를 정합니다. 넓은 거부 규칙을 더 구체적인 허용 규칙으로 뒤집을 수는 없습니다. 파일 도구가 특정 파일을 읽지 못하게 하려면 Read(./.env)처럼 경로에 Read 거부 규칙을 넣습니다. 프로젝트의 .claudeignore는 효과가 없으므로 그 항목을 Read 거부 규칙으로 옮겨야 합니다. 연습 저장소에 가짜 .env를 두고 이 규칙을 넣은 뒤 읽기 요청이 거부되는지 보는 방법을 제안할 수 있습니다(실행하지 않은 제안).
Read 거부 규칙은 Claude의 내장 파일 도구, cat이나 head 같은 인식되는 명령, 리디렉션 대상에 적용됩니다. 그러나 파일 이름을 지정하지 않고 디렉터리를 읽는 명령이나 스크립트가 직접 여는 파일은 막지 못하므로, OS 수준 차단이 필요하면 샌드박스를 켜야 합니다. 설정 범위가 여럿이면 관리 설정, 명령줄 인수, 프로젝트 로컬, 공유 프로젝트, 사용자 설정 순서로 우선하며, 어느 범위에서든 거부 규칙은 허용 규칙을 이깁니다.
중단 키는 상황마다 다릅니다. 권한 요청 중에 Esc를 누르면 그 요청을 거절하고, Ctrl+C는 실행 중인 작업을 멈추고, 실행 중인 작업이 없으면 첫 번째 누름에 입력창을 비우고 두 번째에 종료합니다. 입력창이 비어 있을 때 Esc를 두 번 누르면 되감기 메뉴가 열립니다.
체크포인트 안내에 따르면 되감기에도 한계가 있습니다. 체크포인트는 세션당 최근 100개의 파일 스냅샷을 보관하고, 마지막 저장 뒤 약 30일이 지나면 스냅샷이 정리될 수 있습니다. 그 뒤의 되감기는 No files were restored 오류로 실패할 수 있습니다. 되감기 메뉴는 코드와 대화를 함께 되돌리거나, 대화만 되돌리거나, 코드만 되돌리거나, 특정 지점 전후를 요약하는 선택지를 줍니다. 요약은 디스크의 파일을 바꾸지 않습니다. 서브에이전트가 만든 편집은 대부분 체크포인트에 잡히지 않고, 심볼릭 링크와 하드 링크 경로는 복구할 때 건너뛰며 경고를 띄웁니다.
샌드박스 안내에 따르면 샌드박스는 셸 명령에만 적용되는 운영체제 수준의 경계입니다. 기본값은 꺼짐이며 세션에서 /sandbox를 실행해 켭니다. 켠 뒤에도 파일 도구, MCP 서버, 훅은 샌드박스 밖에서 실행됩니다. 쓰기는 작업 디렉터리와 사용자 임시 폴더로 제한되지만, 읽기는 ~/.ssh나 ~/.aws/credentials 같은 자격 증명 파일을 포함해 대부분의 파일에 기본 허용됩니다. 네이티브 Windows에서는 명령이 샌드박스 없이 실행되므로, Windows에서 샌드박스를 쓰려면 WSL2 배포판 안에서 실행해야 합니다.
한국어 설정과 한글 파일명#
한국어 입력과 한글 파일명 처리는 사용 중인 환경에서 확인하세요.
연습 파일의 한글 입력·저장·다시 열기와 경로 검색을 따로 확인하세요. 요청에는 한국어 응답을 원한다고 적되 코드와 오류 원문은 보존합니다. 입력 중 깨짐과 파일 인코딩 문제는 다른 증상일 수 있으므로 운영체제·터미널·입력기·제품 버전을 함께 기록하세요.
아래는 실행하지 않은 제안입니다. 같은 짧은 한글 문장을 Claude Code 입력창에 조합해 넣고 전송한 뒤, 같은 문장을 Ctrl+G로 기본 텍스트 편집기에서 입력해 돌아온 다음 전송한 결과와 비교합니다. 외부 편집기 쪽 결과는 정상이고 입력창만 다르면 입력창 쪽 문제를, 두 결과가 모두 다르면 입력기나 터미널 설정을 의심하세요.
자주 막히는 지점#
설치 후 claude를 찾을 수 없다면 새 터미널에서 다시 확인하고 공식 설치·로그인 문제 해결을 참고해 PATH와 설치 상태를 살펴보세요. 로그인에 실패하면 같은 문서에서 계정 권한과 인증 오류에 맞는 항목을 확인하세요.
여러 설치가 섞였는지는 which -a claude로 PATH에서 찾을 수 있는 claude를 모두 나열해 확인합니다. 네이티브 설치는 ~/.local/bin/claude에 놓입니다. 설치 프로그램은 이 폴더가 PATH에 없으면 Native installation exists but ~/.local/bin is not in your PATH.라고 알리지만 PATH를 직접 고치지는 않습니다. VS Code 확장만 설치했다면 ~/.local/bin/claude가 없으며, 터미널에서 쓰려면 독립 설치를 따로 해야 합니다.
claude doctor는 세션을 시작하지 않고 설치 상태, 설정 파일 검증 오류, 조치 방법이 있는 경고를 읽기 전용으로 보여 줍니다. 세션 하단에 Auto-update failed가 보이면 claude doctor로 마지막 업데이트 시도 결과를 확인하고, 네이티브 설치라면 셸에서 claude update로 직접 갱신하세요. 편집기 안의 터미널은 편집기에서 PATH를 받으므로, PATH를 고친 뒤에도 찾지 못하면 편집기를 완전히 종료했다가 다시 여세요.
설치 문제와 계정 문제를 나눠 보기#
claude가 실행되지 않는 상황과 실행된 뒤 인증이 거부되는 상황은 다릅니다. 전자는 실행 파일의 위치와 터미널 환경을, 후자는 계정과 선택한 인증 경로를 먼저 확인할 수 있습니다. 오류를 없애려고 다른 경로를 계속 추가하거나 기존 파일을 무작정 지우기보다 현재 상태를 기록하는 편이 낫습니다.
브라우저에서 로그인한 계정과 도구가 사용하는 결제 경로도 구분하세요. 구독 계정, Console API와 지원되는 클라우드 제공자는 인증과 사용량 확인 위치가 다를 수 있습니다. 로그인 화면을 보았다는 이유만으로 특정 구독의 포함량이 적용된다고 가정하지 마세요. 회사 환경이라면 사용할 제공자와 조직 정책부터 확인합니다. 인증 오류를 공유할 때는 토큰이나 전체 콜백 주소처럼 비밀값이 포함될 수 있는 부분을 제거하세요.
로그인이 만료되면 요청이 실패하기 전에 신호가 나타납니다. 인증 안내에 따르면 /login으로 만든 로그인은 만료 3일 전부터 시작할 때 Your login expires in 3 days · run /login to renew 경고가 뜨고, 만료되어 갱신할 수 없으면 모델 요청이 Login expired 오류로 실패합니다. v2.1.210 이상의 /status에서는 Login 행에 Expired — log in again이 표시됩니다. 백그라운드 세션이나 원격 제어 세션은 로그인이 끊기면 복구되지 않으므로, 무인으로 돌리기 전에 /login으로 미리 갱신하세요.
한국어 문제를 재현 가능한 기록으로 남기기#
조합 중 글자가 중복되는 문제와 저장한 파일의 글자가 깨지는 문제를 나눕니다. 같은 짧은 한글 문장을 터미널 입력란과 일반 편집기에서 비교하고, 전송 전후 문장이 같은지 보세요. 한글 경로는 실제 열린 폴더와 검색 결과를 함께 기록합니다. 공유 화면에는 사용자 경로와 저장소 이름이 드러날 수 있으므로 연습 자료로 재현하는 편이 좋습니다. 이 글은 특정 운영체제의 IME 호환성을 검증한 결과를 제공하지 않습니다.
데이터 이용 안내에 따르면 재현 자료를 보내려고 /feedback, /bug, /share를 쓰면 코드를 포함한 대화 기록이 Anthropic으로 전송되고 5년 동안 보관됩니다. 기록 범위는 기본으로 현재 세션만 포함되며, 같은 프로젝트의 다른 세션을 최근 24시간이나 7일 범위로 함께 고를 수 있습니다. 연습용 한글 파일이라도 이 경로는 공유 범위를 먼저 확인하세요.
편집 메모#
편집 메모 (2026-11-02): 설치 기록과 버전 확인의 차이, Plan·중단·데이터 조건 FAQ를 보충했습니다. 설치·인증·첫 작업과 승인 화면은 여전히 미확보입니다.