개발을 배우기 시작했거나 이제 막 실무에 들어간 분이라면, 터미널 — 명령어를 글자로 입력해 컴퓨터를 조작하는 검은 화면 — 이 낯설게 느껴질 수 있습니다. 이 글은 그런 분들을 위해 Claude Code(터미널·에디터·데스크톱 앱에서 쓸 수 있는 Anthropic의 코딩 에이전트)를 설치하고, 로그인하고, 실제 프로젝트에서 첫 질문과 첫 코드 수정, 첫 커밋까지 끝내는 과정을 순서대로 안내합니다. 그대로 따라 하면 약 15~20분이면 충분합니다.
🟢 현행 모델 라인업 일치 · 모델 안내 · Fable 구독 안내
Fable 5·5.1 구독 안내(2026년 9월 7일 갱신): 2026년 9월 1일 출시된 Claude Fable 5.1이 현행 Fable 모델이고, Fable 5는 레거시로 전환됐습니다. 구독 조건은 두 모델이 같습니다 — Max·Team Premium 플랜은 주간 사용 한도의 50% 범위에서 포함되고, Pro·Team Standard 플랜은 사용량 크레딧(입력 100만 토큰당
시작 전에 무엇을 준비해야 하나요?
터미널을 열 수 있는 컴퓨터 한 대와 유료 Claude 구독(또는 Console 계정) 하나만 있으면 충분합니다. 공식 문서 기준으로 필요한 것은 다음과 같습니다.
- 운영체제 — macOS 13.0 이상, Windows 10 버전 1809 이상(또는 Windows Server 2019 이상), Ubuntu 20.04 이상, Debian 10 이상, Alpine Linux 3.19 이상
- 하드웨어 — RAM 4GB 이상, x64 또는 ARM64 프로세서
- 지원 국가 — Anthropic이 서비스를 제공하는 국가에서만 사용할 수 있습니다(한국 포함)
- 인터넷 연결 — Claude Code는 항상 온라인 상태에서 동작합니다
- Claude 구독 또는 Console 계정 — Pro, Max, Team, Enterprise 구독 중 하나, 또는 API 요금을 선불 충전하는 Claude Console 계정이 필요합니다. 무료(Free) 플랜만으로는 터미널용 Claude Code를 시작할 수 없습니다
- (선택) 작업할 프로젝트 폴더 — 없어도 됩니다. Claude Code에게 새 프로젝트를 만들어 달라고 요청할 수 있습니다
- (Windows 전용, 선택) Git for Windows — 설치하면 Claude Code가 Bash 도구를 쓸 수 있습니다. 없으면 PowerShell을 대신 사용합니다
개발 입문자가 먼저 알아야 할 용어는 무엇인가요?
본문에서 반복해 등장하는 용어를 미리 풀어 두면 뒤에서 막히지 않습니다.
- 터미널(Terminal) — 마우스 클릭 대신 글자로 명령을 입력해 컴퓨터를 조작하는 검은 화면 프로그램
- CLI(Command Line Interface) — 터미널에서 글자 명령으로 실행하는 프로그램 방식. Claude Code는 CLI로 실행됩니다
- PATH — 터미널이 명령어(예:
claude)를 찾는 폴더 목록. 설치 폴더가 여기 등록돼 있지 않으면 명령어를 "찾을 수 없다"는 오류가 납니다 - CLAUDE.md — 프로젝트 폴더에 두는 메모 파일로, Claude Code가 매 대화 시작 때마다 읽어서 프로젝트 규칙(코드 스타일, 자주 쓰는 명령어 등)을 기억하게 해 줍니다
- 권한 모드(Permission mode) — Claude Code가 파일을 고치거나 명령을 실행하기 전에 사용자 승인을 구할지 정하는 설정. 자동 모드와 수동 모드가 있습니다
- 플랜 모드(Plan mode) — 파일을 바꾸지 않고 코드를 읽고 계획만 세우는 모드. 실제 수정 전에 방향을 점검할 때 씁니다
- 컨텍스트 윈도우(Context window) — 한 대화에서 Claude가 기억할 수 있는 대화·코드 분량의 한도. 꽉 차면 이전 지시를 놓치는 등 실수가 늘어납니다
Claude Code는 어떻게 설치하나요?
운영체제별로 터미널(또는 PowerShell)에 명령어 한 줄을 붙여넣으면 설치가 끝납니다.
macOS·Linux (터미널에서 실행)
curl -fsSL https://claude.ai/install.sh | bashWindows PowerShell (Win+X → Windows PowerShell 선택)
irm https://claude.ai/install.ps1 | iexWindows CMD를 쓰는 경우
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd설치가 끝나면 완료 메시지가 표시됩니다. 잘 설치됐는지 확인하려면 아래 명령어를 입력하세요.
claude --version이렇게 보이면 성공입니다: 버전 번호와 함께 (Claude Code) 문구가 출력됩니다.
주의: PowerShell과 CMD는 겉모습이 비슷하지만 다른 명령어를 씁니다. 프롬프트가 PS C:\로 시작하면 PowerShell, C:\만 있으면 CMD입니다. 서로 다른 설치 명령어를 잘못 넣으면 바로 오류가 납니다.
로그인부터 첫 질문까지 어떻게 진행하나요?
설치 후 터미널에서 프로젝트 폴더로 이동해 claude를 입력하면 로그인 절차가 자동으로 시작됩니다.
cd /path/to/your/project
claude처음 실행하면 브라우저 창이 열리고 Claude 계정으로 로그인하라는 안내가 나옵니다. 화면 지시를 따라가면 됩니다. 이후 계정을 바꾸고 싶으면 세션 안에서 /login을 입력하면 됩니다. 로그인이 끝나면 프로젝트에 대해 바로 질문해 볼 수 있습니다.
이 프로젝트는 뭘 하는 프로젝트야?
어떤 기술 스택을 쓰고 있어?
메인 진입점이 어디야?Claude Code는 파일을 직접 열어 필요한 만큼 읽고 답합니다. 폴더 구조나 파일 내용을 미리 붙여넣어 줄 필요가 없습니다.
첫 코드 수정과 커밋은 어떻게 하나요?
수정을 요청하면 Claude Code가 해당 파일을 찾아 변경 내용을 보여줍니다. 수동 모드에서는 적용 전에 승인을 요청합니다.
메인 파일에 hello world 함수를 하나 추가해줘변경 내용이 마음에 들면 Yes를 선택해 승인합니다. Pro·Max·Team 플랜은 2026년 8월 14일부터 새 세션이 자동(auto) 모드로 시작합니다. 자동 모드에서는 사용자 대신 별도의 분류기(classifier) 모델이 각 작업을 검토해, 위험해 보이는 작업만 걸러내고 나머지는 묻지 않고 진행합니다. 다만 사용자가 ~/.claude/settings.json에 다른 기본 모드를 직접 지정해 뒀다면 그 설정이 그대로 유지되고, 조직에서 관리 설정으로 기본값을 배포한 경우에도 바뀌지 않습니다. Enterprise 플랜과 Claude API 경유 사용은 이 글 작성 시점 기준 자동 모드가 여전히 선택(opt-in) 사항이라 수동 모드로 시작합니다. 세션 중 언제든 Shift+Tab을 눌러 모드를 바꿀 수 있습니다. Git 작업도 자연어로 요청하면 됩니다.
내가 뭘 바꿨는지 보여줘
설명을 담아서 변경사항 커밋해줘자주 쓰는 명령어는 아래와 같습니다.
| 명령어 | 하는 일 | 예시 |
|---|---|---|
claude | 대화형 세션 시작 | claude |
claude "작업" | 첫 요청과 함께 세션 시작 | claude "빌드 에러 고쳐줘" |
claude -p "질문" | 한 번만 물어보고 바로 종료 | claude -p "이 함수 설명해줘" |
/clear | 대화 기록 초기화 | /clear |
/help | 사용 가능한 명령어 보기 | /help |
요청은 구체적일수록 되돌아오는 수정 횟수가 줄어듭니다. 공식 가이드가 제시하는 예시를 비교하면 차이가 뚜렷합니다.
| 상황 | 모호한 요청 | 구체적인 요청 |
|---|---|---|
| 버그 수정 | "로그인 버그 고쳐줘" | "세션 타임아웃 후 로그인이 실패한다는 신고가 있어. src/auth/의 인증 흐름, 특히 토큰 갱신 부분을 확인해서 문제를 재현하는 실패 테스트를 먼저 작성한 다음 고쳐줘" |
| 테스트 작성 | "foo.py에 테스트 추가해줘" | "foo.py에 사용자가 로그아웃된 상태로 접근하는 예외 상황을 다루는 테스트를 작성해줘. mock은 쓰지 말아줘" |
| 빌드 오류 | "빌드가 안 돼" | "빌드가 [에러 메시지]로 실패해. 근본 원인을 고쳐서 빌드가 성공하는지 확인해줘. 에러를 그냥 숨기지 말아줘" |
기능을 새로 추가할 때는 어떤 순서로 진행해야 하나요?
공식 가이드는 작은 수정이 아니라면 곧바로 코딩하지 말고 탐색 → 계획 → 구현 → 커밋 네 단계로 나눠 진행하라고 권합니다. 오타 수정이나 로그 한 줄 추가처럼 범위가 명확한 작업은 이 과정 없이 바로 요청해도 되지만, 여러 파일에 걸치거나 익숙하지 않은 코드를 건드릴 때는 이 순서가 엉뚱한 방향으로 작업이 진행되는 것을 막아 줍니다.
탐색 단계에서는 Shift+Tab을 눌러 상태 표시줄에 ⏸ plan mode on이 뜰 때까지 전환한 뒤, 파일만 읽고 질문하게 합니다. 계획 단계에서는 "이런 기능을 추가하고 싶은데, 어떤 파일을 바꿔야 해? 계획을 세워줘"처럼 요청합니다. 계획이 마음에 들면 승인하거나 Shift+Tab으로 모드를 빠져나와 구현을 맡기고, 마지막으로 "설명을 담아서 커밋하고 PR을 열어줘"로 마무리합니다.
설치·초기 실행에서 자주 막히는 지점은 무엇이고 어떻게 해결하나요?
대부분의 초기 오류는 PATH 설정이나 터미널 종류 혼동에서 옵니다. 공식 문서가 안내하는 해결법은 다음과 같습니다.
| 증상 | 원인 | 해결 |
|---|---|---|
macOS·Linux에서 command not found: claude | 설치 폴더가 PATH에 등록되지 않음 | 사용 중인 셸의 설정 파일(~/.zshrc 또는 ~/.bashrc)에 export PATH="$HOME/.local/bin:$PATH"를 추가하고 새 터미널을 연다 |
PowerShell에서 'irm' is not recognized | PowerShell이 아니라 CMD에서 명령어를 실행함 | Win+X → Windows PowerShell을 선택해 다시 시도하거나, CMD 전용 설치 명령어를 사용한다 |
claude is not recognized(Windows) | 설치 폴더가 사용자 PATH에 없음 | PowerShell에서 PATH에 %USERPROFILE%\.local\bin을 추가하는 명령을 실행한 뒤 새 창을 연다 |
syntax error near unexpected token '<' 또는 화면에 HTML 코드가 보임 | 설치 URL이 스크립트 대신 오류 응답이나 웹페이지를 반환(원인은 상황에 따라 다름) | 다시 시도하고, 계속되면 Homebrew(brew install --cask claude-code)로 설치한다 |
주의: Windows에서 Bash 도구를 쓰려면 Git for Windows가 필요합니다. 설치돼 있지 않아도 Claude Code는 PowerShell로 대신 동작하지만, "Claude Code on Windows requires either Git for Windows or PowerShell" 오류가 뜬다면 PowerShell 실행 파일 경로 또는 Git 설치 여부부터 확인하세요.
다음 단계로는 무엇을 시도하면 좋을까요?
기본 흐름에 익숙해졌다면 프로젝트 폴더에서 /init 명령을 실행해 보세요. 현재 프로젝트 구조를 분석해 CLAUDE.md 초안을 자동으로 만들어 줍니다. 이 파일에는 자주 쓰는 빌드·테스트 명령어, 코드 스타일처럼 "Claude가 코드만 봐서는 알 수 없는 규칙"을 적어 두면 매 세션마다 다시 설명할 필요가 없어집니다. 승인 화면이 반복돼 번거롭다면 /permissions로 자주 쓰는 명령어를 미리 허용해 두는 것도 방법입니다. 익숙해지면 여러 파일을 조사할 때 서브에이전트(subagent, 별도 컨텍스트에서 조사만 맡는 보조 에이전트)에게 "이 부분 좀 조사해줘"라고 위임해 메인 대화창을 깔끔하게 유지하는 방식도 시도해 볼 만합니다.
자주 묻는 질문
Q. 무료(Free) 플랜으로도 Claude Code를 쓸 수 있나요?
터미널용 Claude Code는 Pro, Max, Team, Enterprise 구독 또는 Claude Console 계정이 있어야 로그인해 사용할 수 있습니다. 무료 플랜만으로는 시작할 수 없습니다.
Q. 코딩을 전혀 몰라도 따라 할 수 있나요?
네, 가능합니다. 공식 가이드도 "코드를 몰라도 된다"고 안내합니다. 하고 싶은 일을 자연어(예: "hello world라고 나오는 간단한 웹페이지 만들어줘")로 설명하면 Claude Code가 파일을 만들고 승인을 구합니다.
Q. Windows에서는 PowerShell과 CMD 중 뭘 써야 하나요?
둘 다 가능하지만 명령어가 다릅니다. 이 글의 설치 명령어는 PowerShell 기준이 기본이며, CMD를 쓴다면 별도로 안내된 CMD 전용 명령어를 사용해야 합니다. 프롬프트가 PS C:\로 시작하면 PowerShell입니다.
Q. 첫 세션에서 계속 승인을 눌러야 하나요?
Pro·Max·Team 플랜은 2026년 8월 14일부터 새 세션이 자동 모드로 시작해, 분류기가 위험해 보이는 작업만 걸러내고 나머지는 자동으로 진행합니다. 매번 직접 승인하고 싶다면 Shift+Tab으로 수동 모드로 바꿀 수 있습니다.