최근 많은 분들이 Claude Code 초보자용 튜토리얼을 만들어 달라고 요청하셨어요.
세계에서 가장 강력한 Agent 제품을 사용해보고 싶으신 거죠.
사실 많은 분들이 모르시는 게 있는데, Agent 제품은 일반적으로 Agent 프레임워크와 모델로 구성됩니다. Claude의 모델들은 실제로 중국에서 자주 차단되고 다루기가 매우 까다로워서, 제가 해결 방법을 가르쳐드릴 방법이 없어요.
하지만 Claude Code는 차단되거나 사용할 수 없게 되지 않습니다. 왜냐하면 실제로는 어떤 모델과도 함께 사용할 수 있는 Agent 프레임워크이기 때문이죠.
Anthropic이 계정 정지와 실명 인증으로 꽤 짜증 나긴 하지만, 그래도 지금 세계 최고의 Agent 프레임워크는 Claude Code라는 점은 인정할 수밖에 없어요.
그래서 저는 항상 말합니다. 한 번에 제대로 할 수 있다면 그렇게 하라고요. OpenClaw나 Hermes Agent 같은 것들이 지금 인기가 많다는 걸 알고 있지만, 저는 여전히 Claude Code를 추천합니다. Claude의 네이티브 모델을 사용할 수 없더라도 국내 모델과 함께 사용해도 여전히 훌륭한 결과를 얻을 수 있어요.
게다가 계정 정지, 해외 전화번호, Visa 카드, VPN 사용까지 걱정할 필요가 없습니다.
그래서 오늘은 Claude Code에 대한 완전한 초보자용 튜토리얼을 처음부터 준비했습니다. Windows와 Mac, VPN이 있는 경우와 없는 경우 모두를 위한 설명을 준비했으니, 필요한 부분을 따라하시면 됩니다.
다음 설치 과정은 저와 제 팀이 주말 내내 5~6대의 컴퓨터에서 반복적으로 설치하고 제거하며 테스트한 것입니다.
예를 들어, VPN이 없는 시나리오에서는 npm을 사용하거나 curl을 통해 국내 미러 소스를 사용하는 등 다른 설치 방법이 있습니다. 이러한 방법들도 작동하지만, 제 테스트에서 여러 컴퓨터에서 충분히 안정적이지 않았습니다.
그래서 최종적으로는 아주 "깨끗한" 컴퓨터에서도 가장 간단하고 실패할 가능성이 가장 낮다고 생각하는 방법을 선택했습니다.
여러분 모두가 이 글을 따라 세계에서 가장 강력한 Agent 프레임워크를 성공적으로 사용할 수 있기를 바랄 뿐입니다.
모든 단계를 최대한 명확하고 자세하게 설명하겠습니다. 다소 장황할 수 있으니 양해 부탁드립니다.
자, 그럼 시작해볼까요.
I. Claude Code 설치
1. Mac
먼저 Mac을 살펴보겠습니다. Windows 사용자는 이 부분을 건너뛰고 아래 Windows 튜토리얼을 찾으시면 됩니다.
먼저 앱에서 터미널을 찾아서 엽니다.
오늘의 주인공인 Claude Code를 설치해 봅시다.
데모를 위해 컴퓨터에 완전히 새로운 macOS 계정을 만들었는데, 이는 기본적으로 깨끗한 컴퓨터와 같습니다.
먼저, VPN이 있는 경우에 대해 알아보겠습니다.
명령어는 단 한 줄입니다:
이 명령어를 터미널에 붙여넣고 Enter 키를 누르세요.
잠시 기다리면 설치 성공 메시지가 나타납니다.
설치는 되었지만, 여기서 프롬프트가 나타날 수 있습니다.
Claude Code가 설치되었지만 설치 위치 ~/.local/bin이 PATH 환경 변수에 추가되지 않아서 claude를 직접 입력하면 명령어를 찾지 못할 수 있다는 의미입니다.
해결 방법은 아래 제공된 명령어를 실행하라고 합니다.
이해가 안 되더라도 괜찮습니다. 시키는 대로 하면 됩니다. 터미널에 표시된 긴 echo 명령어를 복사해서 실행하세요.
그런 다음 claude --version을 입력합니다. 버전 번호가 출력되면 설치가 성공한 것입니다.
VPN이 있는 경우는 매우 간단하지만, 많은 분들이 VPN이 없다는 것을 알고 있습니다.
따라서 VPN이 없는 경우 Homebrew를 통해 설치할 수 있습니다.
Homebrew는 macOS에서 가장 인기 있는 명령줄 패키지 관리자입니다. 한 줄의 명령어로 다양한 소프트웨어와 개발 도구를 설치, 업데이트 및 제거할 수 있습니다.
동료에게서 새 컴퓨터를 빌렸는데, VPN도 없고 환경도 매우 깔끔합니다.
먼저 brew를 설치해 보겠습니다. 복잡해 보일 수 있지만, 따라 하면 실제로는 매우 간단합니다.
다음 명령어를 명령줄에 붙여넣고 Enter 키를 누르세요:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.shhttps://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh))"
프롬프트가 나타나면 Enter 키를 누르기만 하면 됩니다.
그러면 잠시 동안 실행됩니다.
몇 분 동안 기다리십시오. 완료되고 설치 성공 메시지가 나타나면 끝입니다.
다음으로, Homebrew를 path 변수에 추가하여 터미널에서 명령어를 사용할 때 찾을 수 있도록 해야 합니다.
이 몇 줄의 명령어를 터미널에 붙여넣고 한 번 실행하세요.
이제 Homebrew를 사용하여 Mac 패키지를 관리할 수 있습니다.
다음으로 다음 명령어를 사용하여 Claude Code를 설치합니다. 편집기에서 일부 텍스트 형식을 자동으로 수정할 수 있으므로 직접 복사하여 붙여넣으면 오류가 발생할 수 있습니다. 수동으로 입력하거나 Claude에게 형식을 수정하도록 요청한 후 터미널에 붙여넣으세요:
brew install --cask claude-code@latest
여기서 설치 속도가 다소 느립니다. 잠시 쉬었다가 완료되면 다시 오세요.
성공 메시지가 나타나면 터미널에 claude를 입력하면 작은 게 아이콘이 보입니다.
하지만 지금은 사용할 수 없다고 표시될 것입니다. 무시하셔도 됩니다. 잠시 후 모델을 연결하는 방법을 알려드리겠습니다.
Mac에 대해 다루었으니, 이제 Windows에 대해 따로 설명하겠습니다. 약간 다릅니다. Mac 사용자는 이 부분을 건너뛰셔도 됩니다.
2. Windows
이제 Windows입니다.
완전히 포맷된 Windows 컴퓨터를 사용하여 설치했습니다.
Claude Code는 Windows에서 내부적으로 Git Bash를 사용하여 명령어를 실행하므로 Windows에서 Claude Code를 사용하려면 먼저 Git을 설치해야 합니다.
따라서 1단계: Git을 설치합니다.
이미 설치되어 있는 분들은 건너뛰셔도 됩니다.
WinGet을 사용하여 설치합니다. 이것은 공식 Windows 패키지 관리자로, Windows 버전의 Homebrew라고 생각하시면 됩니다.
작업 표시줄에서 "터미널"을 검색하여 엽니다.
다음 명령어를 터미널에 붙여넣습니다. 여기서 VPN을 사용하지 않으면 설치가 훨씬 빨라집니다.
winget install Git.Git
완료되면 설치 성공 메시지가 나타납니다.
Git이 설치되었으면, 평소와 같이 VPN이 있는 경우에 대해 알아보겠습니다.
VPN이 있는 분들을 위해 공식 네이티브 설치 명령어를 사용합니다.
명령어를 터미널에 붙여넣으세요:
잠시 기다리면 설치가 완료됩니다.
매우 편리합니다.
VPN이 없는 경우 WinGet을 사용하여 설치해야 합니다.
터미널에서 다음 명령어를 실행하세요:
winget install Anthropic.ClaudeCode
성공적으로 설치된 후 claude를 입력하면 설치된 것을 확인할 수 있습니다.
이 시점에서 이론적으로 터미널에 claude를 입력하면 Claude Code 페이지로 이동해야 합니다.
하지만.
프레임워크만 설치했을 뿐 아직 "두뇌"를 부여하지 않았기 때문에 사용할 수 없습니다.
다음으로, 두뇌를 연결해야 합니다.
II. 모델 연결
Claude 계정이 있으면 바로 로그인하시면 됩니다. 여기서는 자세히 설명하지 않겠습니다.
이론적으로 이미 Claude 계정이 있다면 이 초보자용 튜토리얼을 읽고 있지 않을 테니까요...
따라서 모든 국내 사용자가 사용할 수 있도록 하기 위해 국내 모델인 GLM-5.1을 예로 들어 설명하겠습니다.
GLM-5.1은 현재 제가 사용해본 국내 모델 중에서 Claude Opus 4.6 경험에 가장 가깝다고 느낀 모델입니다.
물론, 코딩 계획을 놓치셨다면 MiniMax M2.7과 K2.5도 좋습니다. K2.6 코드도 곧 나올 예정이고, Kimi도 비약적인 발전을 이룰 것 같아서 주목해 보시길 추천합니다.
GLM-5.1의 경우, Zhipu 공식에서 한 줄 명령어로 설치할 수 있도록 제공하여 매우 간단합니다:
하지만 다른 모델을 연결하고 자유롭게 전환할 수 있도록 더 보편적인 방법인 CC Switch를 알려드리겠습니다.
다시 Mac과 Windows로 나뉩니다.
1. Mac
Mac에서는 설치 명령어가 두 개입니다. 두 번째 명령어도 형식 문제로 복사하여 붙여넣으면 오류가 발생할 수 있습니다. 수동으로 입력하거나 Claude에게 수정을 요청한 후 붙여넣으세요:
brew tap farion1231/ccswitch
brew install --cask cc-switch
터미널에 붙여넣고 Enter 키를 누르세요.
설치가 완료되면 끝입니다.
2. Windows
Windows의 경우 아래 링크에서 직접 설치 패키지를 다운로드하는 것을 권장합니다:
https://github.com/farion1231/cc-switch/releases
GitHub에 접속할 수 없는 경우, 로컬 설치 패키지도 준비했습니다. 공식 계정 배경에서 "cc"라고 답장하면 다운로드 링크가 자동으로 전송됩니다.
다운로드 후 더블 클릭하여 실행하고, "다음"을 계속 클릭하여 설치를 완료하면 됩니다.
이후 작업은 Mac과 Windows가 동일하므로 따로 구분하지 않겠습니다.
설치가 완료되면 엽니다.
이 도구는 Claude Code뿐만 아니라 Codex와 Xiaolongxia도 사용할 수 있습니다.
아직 구성하지 않았으므로 현재는 공식 Claude 모델 구성만 있습니다.
Claude 열에서 오른쪽 상단의 더하기 기호를 클릭하여 새 모델 구성을 추가합니다.
그런 다음 사용하려는 모델을 선택합니다. 여기서는 GLM 국내 버전을 선택했습니다.
다음으로, 두 부분만 채우면 됩니다: API 키 (API Key가 무엇인지 모르는 경우, 사용 가능한 AI에게 물어보면 도움을 줄 것입니다)와 모델 구성입니다. 나머지는 자동으로 채워집니다.
작성을 완료한 후 오른쪽 하단의 "추가"를 클릭합니다.
그러면 구성한 모델로 전환됩니다.
이 시점에서 Claude Code 설치와 GLM-5.1 연결이 완료되었습니다.
III. Claude Code 시작
터미널로 돌아가서 claude를 입력하고 Enter 키를 누르세요.
이제 Claude Code를 정상적으로 시작할 수 있습니다.
처음 사용 시 몇 가지 초기화 설정이 있습니다.
예를 들어, 색상 모드입니다. 모드 아래에 코드 미리보기가 있습니다. 취향에 따라 선택하고 Enter 키를 누르세요.
나중에 변경하려면 Claude Code 내에서 /theme을 실행하세요.
다음은 보안 프롬프트입니다.
두 가지 주요 사항:
하나는 Claude가 실수할 수 있다는 것입니다. 생성된 코드와 실행하려는 명령어를 승인하기 전에 검토해야 합니다.
하나는 프롬프트 인젝션 공격을 피하기 위해 신뢰하는 코드베이스에서만 Claude Code를 사용해야 한다는 것입니다.
Enter 키를 눌러 다음 단계로 이동합니다.
Claude Code의 터미널 설정을 사용할 것인지 묻습니다.
여기서는 권장 터미널 설정을 사용하면 됩니다.
실제로는 두 가지를 활성화하는 데 도움을 주려는 것입니다:
터미널에서 줄 바꿈을 위한 단축키.
다른 하나는 Visual Bell, 시각적 알림입니다.
즉, Claude가 작업을 완료하거나 사용자의 확인이 필요할 때 터미널 창이 깜박이고 Dock 아이콘이 바운스되어 알려줍니다.
마지막 단계는 현재 디렉토리를 신뢰할 수 있는지 확인하는 것입니다.
"예"를 선택하고 Enter 키를 누르세요.
드디어 GLM-5.1에 연결된 Claude Code의 대화 인터페이스에 도착했습니다.
나중에 모델을 전환하려면 CC Switch에서 구성하고 Claude Code에서 /model을 사용하여 전환하세요.
이 시점에서 모든 설치 및 연결 작업이 완료되었습니다.
앞으로 사용하려면 터미널에 claude를 입력하기만 하면 됩니다.
특히 개발 중에는 "허용"을 반복해서 클릭하면 인생에 대한 의문이 들 수 있으므로 다음 명령어를 사용하는 것이 좋습니다:
claude --dangerously-skip-permissions
시작할 때 컨텍스트 설계로 인해 특정 폴더를 대상으로 시작하여 범위를 제한하고 집중해야 하며, 루트 디렉토리에서 직접 Claude Code를 시작해서는 안 됩니다.
디렉토리를 나누었습니다. "Documents"는 지식 창작을 하는 곳입니다.
"code" 폴더도 있는데, 여기에는 제가 직접 개발한 다양한 제품들이 있습니다.
명령줄에서 특정 폴더에 대해 Claude Code를 시작하는 것도 매우 간단합니다.
cd 명령어이며 Mac과 Windows에서 동일합니다.
예를 들어, "지식 베이스" 폴더로 들어가서 콘텐츠를 만들고 싶다면:
터미널을 열고 cd를 입력한 다음, 공백을 한 번 누르는 것을 잊지 말고 폴더를 직접 끌어다 놓으세요.
Enter 키를 누르면 해당 폴더로 들어갑니다.
그런 다음 명령어를 사용하여 Claude Code를 시작합니다.
해당 폴더로 들어가면 기본적으로 해당 폴더 내에서만 작동하며, 그 안에 있는 모든 파일을 읽습니다.
이렇게 하면 실제로 컨텍스트 오염이 줄어들고 더 집중할 수 있습니다. 즉, 더 똑똑해집니다.
IV. CLAUDE.md 작성
시작 방법을 배운 후에는 공식적으로 대화를 시작하고 작업을 수행하도록 할 수 있습니다.
하지만 깊이 사용하기 전에 설정해야 할 표준이자 매우 중요한 습관이 있습니다. 제가 했던 실수를 반복하지 마세요: 먼저 CLAUDE.md 파일을 정의하세요.
제 생각에는 이것이 Claude Code 시작 방법을 배운 후에 가장 먼저 해야 할 일입니다.
구체적인 작성 스타일을 살펴보기 전에 CLAUDE.md가 무엇인지 설명하겠습니다.
이것은 단순한 파일이 아니라 하향식 계층적 제약 시스템입니다.
제가 전에 사용했던 이 이미지와 같습니다.
설치 후 관리해야 할 두 계층은 전역 CLAUDE.md와 프로젝트 CLAUDE.md입니다.
전역 CLAUDE.md는 사용자 홈 디렉토리의 Claude Code 루트 디렉토리인 ~/.claude/CLAUDE.md에 위치합니다.
Claude Code를 열기만 하면 어떤 프로젝트에 들어가든 자동으로 로드되어 준수됩니다.
이것이 최상위 사양입니다.
당신이 누구인지, 일을 처리하는 원칙, 그리고 당신이 어떻게 협력하기를 원하는지와 같은 문제를 해결합니다.
프로젝트 수준의 CLAUDE.md는 각 프로젝트의 루트 디렉토리인 project_directory/CLAUDE.md에 위치합니다.
해당 프로젝트를 열 때만 로드됩니다.
이 특정 프로젝트를 어떻게 수행해야 하는지, 그리고 이 수준에서 어떤 특별한 약속이 있는지에 대한 문제를 해결합니다.
먼저 전역 CLAUDE.md에 대해 이야기해 보겠습니다. 이것이 가장 먼저 해결해야 할 사항입니다. 하지만 많은 사람들이 무엇을 써야 하는지, 어떻게 써야 하는지, 얼마나 길어야 하는지, 어디에 두어야 하는지 명확하지 않습니다. 개발자가 아닌 분들을 위해 제 경험을 공유하겠습니다.
길이에 관해서는 CLAUDE.md가 길수록 좋은 것이 아니라 오히려 가능한 한 간결해야 합니다.
CLAUDE.md가 너무 길면 후반부의 내용을 무시할 것입니다.
구체적인 한계선은 다음과 같습니다: 80줄을 넘으면 Claude가 일부 내용을 놓치기 시작합니다. 최대 200줄을 절대 넘지 마십시오.
이전 글에서 제 전역 CLAUDE.md 파일의 내용을 보여드렸습니다.
제 내용을 바탕으로 템플릿을 준비했습니다.
여기에는 좋은 전역 CLAUDE.md가 가져야 한다고 생각하는 내용이 포함되어 있습니다.
"About Me" 섹션에 자신의 내용만 작성하면 나머지는 기본적으로 그대로 사용할 수 있습니다.
About Me [Your name / identity / professional background, if you're not a programmer, you must state it]. I use Claude Code for [Specific Use 1] and [Specific Use 2].
Thinking Principles: All decisions start from the essence of the problem, do not copy just because "this is the convention." Go back to the problem itself: What needs to be solved? What is the most direct path? How would it be designed from scratch? Do not flatter. Do not praise my ideas, do not say "this is a very good question," do not add "of course" at the beginning. Give me real judgments; if there's a problem with the plan, point it out directly. If you find a better way, say it directly without waiting for me to ask.
Constraints First: Whether it's a development project or a knowledge management project, the first step is always to establish rules: write CLAUDE.md for new projects first, and define structural conventions for new directories (what goes where, how to name, when to clean up). Do not work in a workspace without specifications. For projects with existing specifications, strictly abide by the agreements in their CLAUDE.md. When adjusting specifications, change the document first, then the practice, not the other way around.
Communication Style - Default to Chinese, use English for code, commands, and variable names - Conclusion first, then reasons, do not pave the way with background - Encountering vague requirements, give the most reasonable plan first, then ask if adjustments are needed - Do not ask "are you sure you want to do this" unless it hits the red lines below
Autonomous Boundaries (Red lines, must ask me first) The following operations must stop and ask me even in auto-accept mode: - Deleting files, directories, or git history - Modifying .env, keys, tokens, CI/CD configurations - Database schema changes or data migrations - git push, git rebase, git reset --hard, force push - Installing new global dependencies or modifying system configurations - Public release (npm publish, deploy to production, publish articles, etc.)
General Engineering Discipline - Actively run verification after changes (see each project's CLAUDE.md for specific commands), do not just change without verifying - Do not comment out errors or add bypass markers just to make the code run; find the root cause - Keys, tokens, and passwords do not enter code, commits, or logs - Before major changes, provide a plan in Plan Mode; only proceed after my confirmation
총 약 30줄, 6개 부분으로 나뉩니다.
이 6개 블록의 공통적인 특징은 프로젝트 전반에 걸쳐 보편적으로 적용된다는 것입니다.
전역 CLAUDE.md가 설정되면 최상위 사양이 마련됩니다.
다음 계층인 프로젝트 CLAUDE.md에 대해 알아보겠습니다.
저를 예로 들어보겠습니다.
저는 주로 개발과 지식 관리를 위해 Claude Code를 사용합니다.
예를 들어, code/my 디렉토리에 CLAUDE.md가 있습니다. 그 역할은 제가 my 폴더에서 자주 코딩하는 것들이 종종 일회성 또는 실험적인 지저분한 것들이고, 실제로 매우 작기 때문에 매번 my 아래에 새 폴더를 만드는 것이 정말 귀찮기 때문입니다.
그래서 제 현재 일반적인 방법은 my 폴더로 cd하여 직접 시작한 다음, 요구 사항을 즐겁게 제시하여 코딩을 도와달라고 하는 것입니다. 이 CLAUDE.md 파일이 있으면 이것이 새 제품인지 스스로 판단합니다. 새 제품이라면 바로 새 폴더를 만들어 시작하도록 도와주므로 전체 파일 관리가 체계적으로 됩니다.
그리고 이 파일을 직접 작성할 필요도 없습니다. 해당 폴더를 열고 Claude Code와 대화하기만 하면 됩니다. 요구 사항과 관심 있는 사항을 직접 논의하고 Claude가 작성하도록 하세요.
저도 지난 며칠 동안 Claude Code와 함께 다양한 사양을 수립하고 이전에 남겨둔 다양한 "코드 쓰레기 더미"를 정리하기 위해 열심히 노력해 왔습니다.
지금 컴퓨터에 아무것도 없다면 더욱 편리합니다.
이것이 제가 항상 제약 조건 우선, 사양 우선을 강조하는 이유 중 하나입니다.
제약 조건이 설정되면 진정으로 사용을 시작할 수 있습니다.
스킬, 플러그인, 일반적인 명령어 및 기능에 대해서는 여기서 다루지 않겠습니다. 관련 기사를 많이 작성했으니 관심 있는 분들은 해당 키워드를 검색해 보세요.
마지막 말
드디어 오랫동안 미뤄왔던 Claude Code 초보자용 튜토리얼을 마쳤습니다.
Claude Code는 제가 여러분께 추천하는 현재 AI 시대의 "졸업 도구"입니다.
지저분한 Agent들을 모두 사용할 필요가 없습니다. Claude Code를 잘 사용하면 가장 강력한 Agent가 무엇인지 진정으로 느낄 수 있을 것입니다.
모두가 즐겁게 창작할 수 있기를 바랍니다.
그리고 이 시대에 여러분만의 작품을 만드세요.
여러분 자신의 작품을요.
