Claude Code 입문: 설치부터 첫 대화까지, 터미널에서 일하는 AI 코딩 도우미
Claude Code 설치 방법(Windows·Mac), 첫 대화 여는 법, 기본 권한 모드와 되돌리기 같은 안전장치까지 처음 쓰는 사람 눈높이로 정리했습니다.
한국어English
기준: Claude Code 공식 문서, Claude Code v2.1.283 이상. 2026년 9월에 확인했습니다. 설치 방법과 기본 권한 모드는 버전에 따라 바뀔 수 있습니다.
Claude Code는 Anthropic이 만든 AI 코딩 도우미로, 내 컴퓨터의 프로젝트 폴더를 직접 읽고, 파일을 고치고, 명령을 실행합니다. 채팅창에서 코드를 받아 복사해 붙이는 방식과 달리, 일을 맡기면 스스로 파일을 찾아보고 고친 뒤 결과까지 확인합니다.
이 글을 마치면 아래를 할 수 있습니다.
- Claude Code가 무엇인지 알아 둡니다.
- Windows와 Mac에 Claude Code를 설치합니다.
- 첫 대화를 엽니다.
- 처음 켜기 전에 꼭 알아야 할 권한 모드를 구분합니다.
터미널이 처음이라면 GUI와 CLI, 무엇이 다를까를, "에이전트"라는 말이 낯설다면 AI와 AI 에이전트는 어떻게 다를까를 먼저 읽으면 이해가 빠릅니다.
한 문장으로 본 Claude Code
Claude Code는 코드베이스를 읽고, 파일을 편집하고, 명령을 실행하고, 개발 도구와 연결되는 에이전트형 코딩 도구입니다. 낯선 말을 풀어 보겠습니다.
- 코드베이스: 한 프로젝트를 이루는 파일 전체입니다. 책 한 권의 모든 장을 합친 것과 비슷합니다.
- 에이전트형: 질문에 답만 하는 것이 아니라, 도구를 써서 직접 일을 처리한다는 뜻입니다.
- 터미널: 글자로 명령을 입력하는 창입니다. Claude Code는 이 창 안에서 대화하듯 씁니다.
일상에 빗대면, 일반 챗봇은 전화로 조언해 주는 전문가입니다. "이 부분을 이렇게 고치세요"라고 말해 주지만 실제로 고치는 것은 나입니다. Claude Code는 집에 와서 직접 수리하는 기사님에 가깝습니다. 어디가 고장 났는지 살펴보고, 공구를 꺼내 고치고, 물을 틀어 새지 않는지 확인합니다. 대신 기사님을 집에 들이는 만큼, 어디까지 손대도 되는지 미리 정해 두어야 합니다. 이 글 뒤쪽의 "권한 모드"가 바로 그 약속입니다.
쓸 수 있는 곳
터미널 도구로 알려져 있지만, 여러 화면에서 같은 엔진을 씁니다.
| 쓰는 곳 | 특징 |
|---|---|
| 터미널(CLI) | 기능이 가장 많은 기본형. 명령줄에서 바로 실행 |
| VS Code·Cursor 확장 | 코드 편집기 안에서 바뀐 부분을 나란히 비교 |
| JetBrains 플러그인 | IntelliJ, PyCharm 같은 편집기용. CLI를 따로 설치해야 함 |
| 데스크톱 앱 | 터미널 없이 창으로 사용. CLI가 들어 있어 따로 설치할 필요 없음. 유료 구독 필요 |
| 웹(claude.ai/code) | 설치 없이 브라우저에서. 오래 걸리는 일을 맡겨 두기 좋음 |
어느 화면에서 쓰든 프로젝트의 규칙 파일(CLAUDE.md), 설정, 연결한 도구(MCP 서버)가 똑같이 적용됩니다. 이 글에서는 가장 기본인 터미널을 기준으로 설명합니다.
일하는 방식: 알아보고, 고치고, 확인하기
Claude Code의 작업 방식을 에이전트 루프라고 부릅니다. 세 단계입니다.
- 맥락 모으기: 관련 파일을 찾아 읽고, 오류 메시지를 확인합니다.
- 행동하기: 파일을 고치거나, 새로 만들거나, 명령을 실행합니다.
- 결과 확인하기: 테스트를 돌리거나 결과를 다시 읽어 제대로 됐는지 봅니다.
이 세 단계는 한 번으로 끝나지 않고, 일이 끝날 때까지 여러 번 돕니다. 예를 들어 "실패하는 테스트를 고쳐 줘"라고 하면 테스트를 실행해 무엇이 실패하는지 보고, 오류를 읽고, 관련 파일을 찾아 읽고, 고친 뒤, 테스트를 다시 돌려 확인합니다. 사람도 이 루프 안에 있습니다. 중간에 방향이 틀렸다 싶으면 언제든 끼어들어 다른 방법을 알려 줄 수 있습니다.
이렇게 움직일 수 있는 것은 도구 덕분입니다. 기본 도구는 다섯 갈래입니다.
| 도구 갈래 | 할 수 있는 일 |
|---|---|
| 파일 작업 | 파일 읽기, 코드 고치기, 새 파일 만들기, 이름 바꾸기 |
| 검색 | 이름이나 내용으로 파일 찾기 |
| 실행 | 셸 명령, 테스트, git 실행 |
| 웹 | 웹 검색, 문서 찾아보기 |
| 코드 인텔리전스 | 고친 뒤 오류 경고 보기, 정의 위치 찾기(플러그인 필요) |
표의 낯선 말을 하나씩 풀면 이렇습니다.
- 셸 명령: 터미널에 글자로 치는 명령입니다. 예를 들어 "폴더 만들기", "파일 목록 보기"를 마우스 대신 한 줄로 시키는 것입니다.
- 테스트: 프로그램이 제대로 움직이는지 자동으로 확인하는 작은 검사 프로그램입니다. 요리로 치면 간을 보는 숟가락입니다.
- git: 파일이 바뀐 기록을 저장하는 도구입니다. 게임의 "저장 지점"처럼 언제든 예전 상태로 돌아갈 수 있게 해 줍니다.
- 코드 인텔리전스: 코드를 고친 직후 "여기 오타가 있어요", "이 이름은 저 파일에 정의돼 있어요"를 알려 주는 기능입니다. 워드 프로그램의 빨간 밑줄 맞춤법 검사와 비슷합니다.
- 플러그인: 기본 프로그램에 기능을 덧붙이는 추가 부품입니다. 코드 인텔리전스는 언어별 플러그인을 설치해야 켜집니다.
여기에 MCP로 바깥 도구를 더 붙일 수 있습니다. MCP가 무엇인지는 MCP란 무엇인가에서, 실제로 연결하는 방법은 MCP 서버 연결하기에서 다룹니다.
설치부터 첫 대화까지
준비물
- 터미널: Windows는 PowerShell 또는 명령 프롬프트(CMD), Mac은 Terminal
- 작업할 프로젝트 폴더
- 계정: Claude 유료 구독(Pro, Max, Team, Enterprise), Claude Console 계정(미리 충전해 쓰는 API 계정), 지원하는 클라우드 제공자 가운데 하나가 필요합니다. 무료 요금제는 이 목록에 없습니다. 데스크톱 앱은 이 가운데 유료 구독이 있어야 쓸 수 있습니다. 요금제 이름과 조건은 자주 바뀌니 가입 전에 공식 요금 페이지를 꼭 다시 확인하세요.
1단계: 설치
Anthropic이 권장하는 방법은 "네이티브 설치"입니다. 명령은 터미널 종류마다 다릅니다. 아래 첫 줄의 WSL은 Windows 안에서 Linux를 돌리는 기능입니다.
# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
# Windows CMD(명령 프롬프트)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
Windows에서 지금 창이 PowerShell인지 CMD인지 헷갈린다면 줄 맨 앞을 보세요. PowerShell은 PS C:\처럼 앞에 PS가 붙고, CMD는 PS 없이 C:\로 시작합니다. 오류 글자로도 알 수 있습니다. 'irm' is not recognized라는 오류가 나오면 CMD에 있는 것이고, The token '&&' is not a valid statement separator가 나오면 PowerShell에 있는 것입니다. 창에 맞는 명령으로 다시 입력하면 됩니다.
설치가 끝나면 새 터미널 창을 열고 claude --version을 입력합니다. 버전 번호가 나오면 성공입니다.
"claude를 찾을 수 없다(not found, not recognized)"는 말이 나오면 대개 설치 폴더가 아직 PATH에 들어가지 않은 것입니다. PATH는 컴퓨터가 명령어 프로그램을 찾아볼 폴더 목록입니다. 전화번호부에 이름이 아직 안 올라간 상태라, 프로그램은 설치됐는데 컴퓨터가 어디 있는지 모르는 것입니다. 새 창을 열어도 같다면 공식 문서의 "Fix your PATH" 안내를 따르세요.
그 밖에 알아 둘 점입니다.
- Windows에서는 Git for Windows를 함께 설치해 두는 편이 좋습니다. 없으면 Claude Code가 PowerShell을 대신 씁니다.
- 네이티브 설치는 백그라운드에서 자동으로 업데이트됩니다. Homebrew(Mac)나 WinGet(Windows) 같은 프로그램 설치 도구로 설치했다면 업데이트를 직접 해야 합니다.
2단계: 프로젝트 폴더에서 시작하고 로그인
cd 내-프로젝트-폴더
claude
cd는 "이 폴더로 들어가라"는 명령입니다. 처음 실행하면 브라우저가 열리며 로그인을 요청합니다. 한 번 로그인하면 다음부터는 묻지 않습니다. 어느 폴더에서 claude를 실행하느냐를 꼭 확인하세요. Claude Code는 그 폴더와 하위 폴더를 작업 공간으로 삼습니다. 다른 곳의 파일은 허락을 받아야 봅니다. 처음에는 중요한 파일이 없는 연습용 폴더에서 시작하세요.
3단계: 먼저 물어보기
처음에는 고치라고 하기보다 질문부터 해 보세요. 첫 질문의 예는 이렇습니다. 한국어로 물어도 됩니다.
- "이 프로젝트는 무엇을 하는 거야?"
- "폴더 구조를 설명해 줘"
- "시작 지점이 되는 파일이 어디야?"
파일을 일일이 붙여 넣을 필요는 없습니다. Claude Code는 필요한 파일을 알아서 읽습니다.
4단계 전에: 권한 모드부터 바꾸기
이 글에서 꼭 기억할 부분입니다. 최신 버전(v2.1.283 이상)은 대화형 터미널에서 기본 시작 모드가 Auto입니다. Auto 모드에서는 Claude Code가 대부분의 파일 수정과 명령을 나에게 묻지 않고 진행합니다. "고치기 전에 매번 물어보겠지"라고 생각하고 일을 맡기면, 확인할 틈 없이 파일이 바뀔 수 있습니다.
그래서 처음에는 이렇게 시작하세요.
claude를 켠 뒤 화면 아래 상태 표시줄에서 지금 모드를 확인합니다.Shift+Tab을 눌러 모드를 바꿉니다. Auto에서 한 번 누르면 Manual, 그다음부터 Accept edits → Plan 순서로 돕니다.- 처음에는 Plan(계획만 받기)이나 Manual(매번 묻기)로 두고 일을 맡깁니다.
아예 Plan 모드로 켜고 싶다면 claude --permission-mode plan으로 시작해도 됩니다. 설정이나 회사 정책에 따라 시작 모드가 다를 수 있으니, 켤 때마다 상태 표시줄을 한 번 보는 습관을 들이세요.
4단계: 작은 변경 맡기기
익숙해지면 작은 일을 맡깁니다. 예를 들어 "README에 설치 방법을 추가해 줘"라고 해 봅니다. README는 프로젝트 폴더에 들어 있는 "사용 설명서" 문서입니다. Manual 모드라면 Claude Code가 바꿀 내용을 보여 주며 허락을 묻습니다. 내용을 읽고 괜찮으면 Yes를 고릅니다. Plan 모드라면 먼저 계획을 보여 주고, 내가 승인하면 그때 고치기 시작합니다.
자주 쓰는 명령
| 명령 | 뜻 |
|---|---|
claude | 대화형으로 시작 |
claude -c | 이 폴더의 가장 최근 대화 이어 가기 |
claude -r | 예전 대화 골라서 다시 열기 |
claude -p "질문" | 한 번 묻고 바로 끝내기 |
/help | 쓸 수 있는 명령 보기 |
/clear | 대화 기록 비우기 |
/exit | 끝내기 |
실수를 막는 두 가지 안전장치
집에 온 기사님에게 "이 방만 손대 주세요", "벽을 뚫기 전에는 꼭 물어봐 주세요"라고 말해 두듯, Claude Code에도 두 가지 장치가 있습니다.
1. 권한 모드: 어디까지 묻고 할지 정하기
Shift+Tab을 누르면 모드가 바뀝니다. 주요 모드는 이렇습니다.
| 모드 | 동작 | 알맞은 때 |
|---|---|---|
| Manual | 파일을 고치거나 명령을 실행하기 전에 매번 묻습니다 | 처음 쓸 때, 중요한 파일이 있을 때 |
| Accept edits | 파일 수정과 폴더 만들기·옮기기 같은 간단한 명령은 바로 하고, 다른 명령은 묻습니다 | 바뀐 내용을 곁에서 보며 고칠 때 |
| Plan | 파일은 고치지 않고 살펴본 뒤 계획만 제안합니다 | 무엇을 할지 먼저 보고 싶을 때 |
| Auto | 묻지 않고 진행합니다. 대신 별도의 검사기가 위험해 보이는 행동을 막습니다 | 익숙해진 뒤, 긴 작업 |
Auto 모드의 분류기(classifier)는 "이 행동이 위험한지"를 따로 판단하는 두 번째 AI 검사기입니다. 부탁한 범위를 넘어서는 행동, 모르는 외부 시스템을 건드리는 행동, 읽은 글 속 수상한 지시에 따라 움직이는 행동을 막습니다. 사람 대신 경비원이 문 앞에 서 있는 것과 같지만, 경비원도 모든 것을 알 수는 없습니다. 그래서 익숙해지기 전에는 사람이 직접 확인하는 Manual이나 Plan이 마음 편합니다.
2. 체크포인트: 파일 되돌리기
Claude Code는 파일을 고치기 전에 원래 내용을 저장해 둡니다. 결과가 마음에 들지 않으면 Esc를 두 번 눌러 이전 상태로 되돌리거나 "방금 바꾼 것 되돌려 줘"라고 하면 됩니다. 단, 데이터베이스, 외부 서비스, 배포처럼 내 컴퓨터 밖에 영향을 주는 일은 되돌릴 수 없습니다. 그런 일은 권한 모드로 미리 막아야 합니다. 큰 작업 전에는 git으로 저장 지점을 만들어 두는 습관도 도움이 됩니다. git은 Git과 GitHub 차이에서 설명합니다.
잘 쓰는 요령
- 구체적으로 말하기: "버그 고쳐 줘"보다 "틀린 비밀번호를 넣으면 빈 화면이 나오는 로그인 버그를 고쳐 줘"가 낫습니다. 자세한 원칙은 프롬프트 잘 쓰는 법에 있습니다.
- 단계로 나누기: 큰 일은 1, 2, 3 순서로 적어 줍니다.
- 먼저 살펴보게 하기: 고치기 전에 "이 부분 구조를 먼저 분석해 줘"라고 합니다. Plan 모드와 잘 맞습니다.
- 대화하듯 고쳐 가기: 첫 결과가 틀려도 처음부터 다시 할 필요 없이 "그게 아니라 이 부분 문제야"라고 이어서 말합니다.
Esc를 누르면 하던 일을 바로 멈춥니다. - 오래 지킬 규칙은 CLAUDE.md에: 프로젝트 폴더에
CLAUDE.md라는 파일을 두면 Claude Code가 매 세션 시작 때 읽습니다. "문서는 한국어로", "이 폴더는 건드리지 말 것" 같은 규칙을 적어 둡니다./init명령으로 초안을 만들 수 있습니다.
마지막 요령에는 이유가 있습니다. 새 세션은 이전 대화 기록 없이 시작하고, 대화가 길어지면 앞부분을 요약하면서 초반 지시가 사라질 수 있습니다. 컨텍스트가 무엇인지는 토큰과 컨텍스트 창 뜻에서 자세히 다룹니다.
흔한 오해
"개발자만 쓸 수 있다." Claude Code는 코딩에 강하지만 문서 쓰기, 파일 검색, 자료 조사처럼 명령줄로 할 수 있는 일이면 무엇이든 도울 수 있습니다. 다만 결과를 확인할 책임은 여전히 사람에게 있으니, 처음에는 되돌리기 쉬운 작은 일부터 맡기는 편이 좋습니다.
"알아서 다 해 주니 확인하지 않아도 된다." Claude Code는 스스로 확인 단계를 거치지만, 무엇이 "완성"인지는 사람이 정합니다. 특히 기본이 Auto 모드라면 바뀐 내용을 나중에라도 직접 읽어 보세요.
"채팅 앱의 Claude와 똑같다." 같은 Claude 모델을 쓰지만, 내 파일과 터미널을 다루는 도구가 붙어 있다는 점이 다릅니다. 자세한 구조는 AI와 AI 에이전트는 어떻게 다를까에서 다룹니다.
정리
| 항목 | 정리 |
|---|---|
| Claude Code | 파일을 읽고 고치고 명령을 실행하는 AI 코딩 도우미 |
| 비유 | 조언만 하는 전화 상담이 아니라 집에 와서 고치는 기사님 |
| 일하는 방식 | 맥락 모으기 → 행동하기 → 결과 확인하기를 반복 |
| 설치 | Mac은 curl, Windows는 PowerShell(irm) 또는 CMD 명령. 안 되면 PATH 확인 |
| 처음 켰을 때 | 최신 버전은 Auto(대부분 묻지 않음). Shift+Tab으로 Plan이나 Manual로 바꾸고 시작 |
| 되돌리기 | 체크포인트(Esc 두 번). 단, 외부 시스템 변경은 되돌릴 수 없음 |
함께 읽기
- GUI와 CLI, 무엇이 다를까: 클릭과 타이핑의 차이
- AI와 AI 에이전트는 어떻게 다를까: 대답하는 AI, 일하는 AI
- MCP란 무엇인가: AI에 도구를 꽂는 USB-C 같은 표준
- MCP 서버 연결하기: AI에게 도구를 붙이는 방법
- 토큰과 컨텍스트 창 뜻: 긴 대화에서 AI가 앞 내용을 놓치는 이유
- Git과 GitHub 차이: 깃허브에 올려 달라는 말은 무슨 뜻일까
- 프롬프트 잘 쓰는 법: 공식 가이드가 말하는 5가지 원칙
참고 자료
- Claude Code Docs, Overview: https://code.claude.com/docs/en/overview
- Claude Code Docs, Quickstart: https://code.claude.com/docs/en/quickstart
- Claude Code Docs, How Claude Code works: https://code.claude.com/docs/en/how-claude-code-works
- Claude Code Docs, Choose a permission mode: https://code.claude.com/docs/en/permission-modes
