Claude Code 실전 가이드: 설치부터 첫 프로젝트까지

Claude Code는 터미널에서 동작하는 AI 코딩 도구입니다

Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 도구입니다. 요청을 받으면 프로젝트에서 필요한 파일을 찾아 읽고, 수정하고, 명령을 실행합니다. 코드뿐 아니라 글과 간단한 자료 파일도 다룹니다.

요청 하나는 아래 순서로 처리됩니다. Claude Code가 모든 파일을 읽는 것은 아니어서, 파일이 많거나 요청이 모호하면 중요한 내용을 놓치기도 합니다. 그래서 답을 받으면 Claude Code가 어떤 파일을 읽었는지, 실제로 무엇이 바뀌었는지 함께 확인합니다.

요청 하나가 처리되는 순서

1. 11. 요청바꿀 것과
   그대로 둘 것
2. 22. 파일 찾기관련 파일을 골라
   읽음
3. 33. 수정 제안바꿀 파일과
   바꿀 내용을 보여 줌
4. 44. 승인Manual 모드에서는
   허용해야 저장
5. 55. 결과 대조파일을 직접 열어
   요청과 비교

이 글은 코드 프로젝트가 없어도 따라 할 수 있게, 회의록에서 할 일 목록 파일을 만드는 작업으로 시작합니다. 설치와 첫 작업을 마친 뒤 코드 프로젝트 분석과 Git, 규칙 파일로 넘어갑니다.

Claude Code 설치 순서

설치부터 첫 실행까지는 다섯 단계입니다. 단계별 명령과 성공했을 때 나오는 결과는 아래 절에서 차례로 설명합니다.

설치부터 첫 실행까지

1. 11. 요구사항 확인운영체제 버전과
   RAM 4GB 이상
2. 22. 설치 명령운영체제에 맞는
   명령 한 줄
3. 33. 버전 확인새 터미널에서
   claude --version
4. 44. 작업 폴더사본만 담은 폴더로
   터미널 이동
5. 55. 실행과 로그인claude 실행 뒤
   안내대로 인증

시스템 요구사항

플랫폼별 설치 명령어

2026년 10월 4일 공식 안내가 권장하는 방법은 네이티브 CLI 설치입니다. CLI는 명령을 입력해 쓰는 프로그램입니다. 이 방법은 Node.js 없이 바로 설치되고 기본으로 자동 업데이트됩니다. 운영체제에 맞는 명령 하나만 실행합니다. 일부 Linux 배포판은 추가 패키지를 요구합니다.

macOS와 Linux:

Windows PowerShell:

Homebrew로 프로그램을 관리하는 macOS 사용자는 아래 명령으로 설치할 수도 있습니다. 위 네이티브 설치를 이미 마쳤다면 실행하지 않습니다.

Homebrew로 설치한 경우에는 자동 업데이트가 되지 않으므로 brew upgrade claude-code로 직접 올립니다. 설치 뒤 새 터미널을 열고 claude --version을 입력해 버전 번호가 나오면 설치가 끝난 것입니다. 명령을 찾을 수 없다고 나오면 설치 오류 안내를 봅니다.

계정과 작업 폴더 준비

Claude Code는 무료 Claude 계정으로는 쓸 수 없습니다. 로그인 방식은 두 가지입니다.

로그인 방식별 Claude Code 사용

계정	Claude Code 사용	비용
무료 Claude 계정	제공하지 않음	–
Pro 이상 구독	제공	구독료 안에서 요금제 한도까지
Claude Console API 키	제공	쓴 만큼 구독과 따로 청구

다음은 작업 폴더입니다. 파일 탐색기나 Finder에서 meeting-notes라는 새 폴더를 만들고, 최근 회의록 텍스트 파일(.txt나 .md) 두세 개를 복사해 넣습니다. 사본으로 시작하면 요청이 잘못 전달돼 파일이 바뀌어도 원본은 그대로 남습니다. 터미널에서 그 폴더로 이동하는 방법이 처음이라면 윈도우 설치 안내나 맥 설치 안내의 폴더 이동 절차를 따릅니다.

폴더로 이동한 뒤 아래 명령으로 시작합니다.

처음 실행하면 로그인 안내가 나오고, 안내대로 인증하면 대화 입력칸이 열립니다. 이 명령은 이번 세션을 Manual 권한 모드로 엽니다. Manual 모드에서는 파일을 저장하기 전에 허용할지 묻습니다. 파일을 읽기만 하는 작업과 이미 허용 규칙을 만들어 둔 작업은 묻지 않고 진행합니다. Auto 같은 다른 모드는 저장 전에 확인을 받지 않고 바로 수정합니다.

첫 작업: 회의록에서 할 일 목록 만들기

첫 작업은 폴더의 회의록을 읽고 할 일만 모은 파일 하나를 새로 만드는 일입니다. 원본을 고치지 않고 새 파일만 만들기 때문에 결과를 대조하기 쉽습니다. 대화 입력칸에 아래처럼 요청합니다.

.md는 마크다운 파일의 확장자입니다. 마크다운은 제목과 목록을 #, - 같은 기호로 표시하는 글 형식입니다. 요청을 보내면 Claude Code가 회의록을 읽은 뒤 todo.md를 만들겠다고 제안하고 허용할지 묻습니다.

Claude Code, meeting-notes

> 이 폴더의 회의록 파일을 모두 읽고 담당자별 할 일을 todo.md로 정리해 줘.

회의록 3개를 읽었습니다.
10월 14일 주간회의.md, 10월 21일 주간회의.md, 10월 22일 거래처 미팅.md

todo.md를 새로 만들까요?
1. 예 2. 아니요, 다르게 요청

만들 파일이 todo.md 하나인지 보고 허용합니다

todo.md를 만들었습니다. 담당자 4명, 할 일 11건입니다.

허용하기 전에 만들거나 바꿀 파일이 todo.md 하나인지 봅니다. 완료됐다는 답을 받으면 Finder나 파일 탐색기에서 todo.md를 엽니다. 할 일 두세 건을 골라 적힌 출처 회의록을 열고, 그 할 일이 회의록에 실제로 있는지 대조합니다.

같은 대화에서 고치기

결과를 보고 고칠 점이 생기면 같은 대화에서 요청합니다.

파일을 다시 열어 정렬이 바뀌었는지, 할 일 건수가 그대로인지 봅니다. 결과가 요청과 다르면 "마감일 없는 할 일이 아직 위쪽에 섞여 있어. todo.md를 다시 확인해 줘."처럼 실제로 본 결과를 알려 주고 다시 요청합니다.

파일이 보이지 않을 때

먼저 생성 제안에서 아니요를 고르지 않았는지, 마지막에 오류 문구가 나오지 않았는지 봅니다. 그다음 Claude Code가 다른 폴더에서 일하고 있지 않은지 확인합니다. /exit로 대화를 끝낸 뒤 PowerShell에서는 Get-Location, 맥과 Linux에서는 pwd를 입력하면 지금 폴더 위치가 나옵니다. 위치가 다르면 작업 폴더로 이동해 다시 실행합니다.

실제 코드 프로젝트로 넘어갈 때

코드 프로젝트에서도 순서는 같습니다. 먼저 읽게 하고, 작은 변경 하나를 맡기고, 결과를 직접 확인한 뒤 기록합니다.

코드 프로젝트에서 맡기는 순서

1. 11. 읽고 설명근거 파일 이름까지
   수정은 하지 않음
2. 22. 작은 변경바꿀 동작과
   유지할 동작을 함께
3. 33. 직접 확인테스트 환경에서
   화면으로 대조
4. 44. 기록 범위이번 수정만
   커밋 후보로 정리

먼저 읽은 파일과 모르는 부분 묻기

이미 있는 프로젝트에서는 분석 범위를 먼저 정합니다.

답에 나온 파일을 직접 열어 설명과 맞는지 봅니다. 설명이 그럴듯해도 근거 파일이 몇 개뿐이라면 나머지 부분은 아직 읽지 않은 것입니다.

작은 변경과 확인 기준을 함께 주기

회원가입 양식이 있는 프로젝트라면 "이메일에 @가 없으면 제출하지 않고 안내 문구를 보여 줘. 정상 이메일은 이전처럼 제출되어야 해."처럼 바꿀 동작과 그대로 둘 동작을 함께 적습니다.

수정이 끝나면 변경 파일 목록을 보고, 테스트 환경에서 잘못된 이메일과 정상 이메일을 하나씩 입력해 봅니다. 실제 서비스에서 계정을 만들어 시험하지 않습니다. AI가 테스트에 성공했다고 답해도 화면에서 기대한 결과가 나오는지는 직접 봅니다.

Git 기록은 외부 전송과 구분하기

Git은 파일 변경 이력을 저장하는 도구입니다. 커밋은 선택한 변경을 내 컴퓨터의 저장소에 기록으로 남기는 작업이고, push는 그 기록을 원격 저장소로 보내는 작업입니다.

Git을 쓰는 프로젝트라면 "변경 파일 목록을 보여 주고 이번에 요청한 수정만 커밋 후보로 정리해 줘. 아직 커밋하거나 push하지 마."라고 요청해 커밋할 범위부터 확인합니다. 다른 사람이 수정한 파일이나 비밀 설정 파일이 섞이지 않았는지 본 뒤 기록할 파일을 정합니다.

Claude Code의 핵심 기능 5가지

아래 기능은 처음부터 모두 설정하지 않습니다. 파일을 읽고 고치는 흐름에 익숙해진 뒤, 같은 설명이나 절차를 되풀이하게 되는 시점에 하나씩 붙입니다.

1. CLAUDE.md로 프로젝트 규칙 설정

프로젝트 최상위 폴더에 CLAUDE.md를 두면 Claude Code가 세션을 시작할 때 프로젝트 지침으로 읽습니다. 모델을 다시 학습시키는 기능은 없고, 세션마다 처음에 읽는 안내 파일로 작동합니다. 이미 파일이 있다면 덮어쓰지 말고 필요한 규칙만 더합니다.

앞의 회의록 폴더라면 이 정도로 시작합니다.

새 세션에서 어떤 규칙을 읽었는지 물어보고, 실제 수정에서도 규칙을 지키는지 봅니다. 상위 폴더의 규칙 파일과 실행 옵션도 결과에 영향을 줍니다. 자동 메모리는 CLAUDE.md와 별개 기능입니다. 자동 메모리를 켜 두면 Claude Code가 유용하다고 판단한 정보 일부만 골라 저장합니다.

2. Skills로 반복 작업 묶기

스킬(Skill)은 반복 작업의 절차를 파일로 묶어 다시 쓰는 기능입니다. 매주 회의록에서 할 일을 같은 형식으로 뽑는다면 그 순서를 스킬로 만들어 둡니다. 공식 문서에 나오는 /review-pr 같은 이름은 사용자가 직접 만든 스킬의 예시입니다. 직접 만들거나 설치한 스킬만 명령 목록에 나타납니다.

3. MCP로 외부 도구 연결

Model Context Protocol(MCP)은 AI 도구를 외부 데이터 소스에 연결하는 개방형 표준입니다. 서비스의 MCP 서버나 커넥터를 연결하고 인증과 권한을 설정하면 Claude Code가 그 서비스의 문서를 읽거나 업무 항목을 고칠 수 있습니다. 인증한 서비스와 허용한 권한 범위 안에서만 동작하며, 읽기 권한과 쓰기 권한은 따로 정합니다. MCP가 무엇인지는 별도 글에서 자세히 다뤘습니다.

4. 멀티 에이전트와 서브에이전트

서브에이전트는 작업 일부를 맡는 보조 AI입니다. 예를 들어 주 작업은 그대로 진행하면서 변경 내용 검토만 서브에이전트에 맡깁니다. 여러 에이전트가 함께 일하면 같은 파일을 동시에 고쳐 충돌이 나기도 하고, 작업량과 사용료도 늘어납니다. 파일 하나를 만드는 작업에는 쓰지 않습니다.

5. 예약 작업과 원격 제어

/loop는 열린 세션 안에서 요청을 반복 실행하는 기능이고, /remote-control은 다른 기기에서 내 컴퓨터의 세션에 접속하는 기능입니다. 둘 다 원래 컴퓨터의 세션이 살아 있어야 동작합니다.

세션 안에서 도는 두 기능의 조건

조건	/loop반복 실행	/remote-control다른 기기에서 접속
원래 컴퓨터와 세션이 켜져 있어야 함	제공	제공
컴퓨터를 꺼도 계속 실행	제공하지 않음	제공하지 않음
반복 예약이 끝나는 기간	7일	–

Cursor, GitHub Copilot과의 차이

세 도구 모두 파일을 분석하고 수정할 수 있습니다. 차이는 주로 쓰는 작업 공간에 있습니다.

세 도구를 주로 쓰는 곳

항목	Claude Code	Cursor	GitHub Copilot
파일 분석과 수정	제공	제공	제공
주로 쓰는 곳	터미널, VS Code 확장 데스크톱 앱	자체 편집기와 에이전트 작업	편집기와 GitHub 작업

처음 고를 때는 순위보다 같은 작은 요청에서 바뀐 내용을 찾기 쉬운지, 잘못됐을 때 되돌리기 쉬운지를 봅니다. 이미 쓸 수 있는 도구가 있다면 앞의 회의록 정리처럼 결과를 대조할 수 있는 작업으로 시작합니다.

Claude Code를 더 잘 쓰기 위한 실전 팁

같은 문제라도 요청을 어떻게 쓰느냐에 따라 Claude Code가 읽는 범위가 달라집니다. 아래 화면은 증상과 순서를 적고, 수정 전에 원인부터 찾게 한 요청의 예입니다.

Claude Code, 웹 프로젝트

> 로그인 화면에서 비밀번호를 틀리게 입력하면 빈 화면이 나와. 관련 파일을 찾아 원인만 설명해 줘. 아직 수정하지 마.

증상, 발생 순서, 아직 하지 말 일을 함께 적었습니다

로그인 처리 파일과 화면 파일을 읽었습니다.
오류 응답을 받았을 때 화면에 보여 줄 문구가 비어 있습니다.
근거가 된 줄을 아래에 적었습니다.

• 증상을 구체적으로 적기: "버그 수정"보다 위처럼 화면, 입력, 결과를 적으면 Claude Code가 찾아야 할 파일이 좁아집니다.
• 단계를 나눠 요청하기: 복잡한 작업은 번호를 붙여 단계별로 요청하고 단계마다 결과를 봅니다.
• 탐색 먼저, 수정은 그다음: 원인을 먼저 설명하게 하면 읽은 파일과 고칠 파일을 연결해 볼 수 있습니다.
• CLAUDE.md 활용하기: 프로젝트 규칙을 파일로 남겨 두면 세션마다 같은 설명을 반복하지 않습니다.
• 도움말로 명령 확인하기: Claude Code 안에서 /help를 입력하면 명령 목록이, ?를 누르면 단축키 안내가 나옵니다. /help와 ?는 Claude Code 대화 입력칸에서 쓰며, PowerShell이나 맥 터미널의 입력줄에 입력하면 동작하지 않습니다.

자주 묻는 질문

Claude Code는 어떤 요금제부터 쓸 수 있나요?

Claude Code는 Pro 플랜부터 포함되고, 무료 플랜에서는 쓸 수 없습니다. API 키로 연결하면 API 사용량에 따라 구독과 별도로 청구됩니다.

반드시 터미널에서만 써야 하나요?

VS Code 확장이나 데스크톱 앱의 Code 탭에서도 쓸 수 있습니다. 이 글은 터미널 사용법을 다루며, VS Code 확장만 설치했다면 터미널의 claude 명령은 따로 설치해야 합니다.

코드를 모르는 사람도 쓸 수 있나요?

쓸 수 있습니다. 요청은 한국어로 하면 되고, 무엇을 고쳤는지 설명도 받습니다. 다만 결과가 맞는지는 사람이 판단해야 하므로, 결과를 직접 대조할 수 있는 작업부터 맡기고 원본은 사본으로 작업합니다.

Sources

• Claude Code 설치
• Claude Code 권한 모드
• 프로젝트 지침과 메모리
• 스킬
• 서브에이전트
• 세션 예약과 장기 예약 차이
• 원격 제어
• Cursor 공식 안내
• GitHub Copilot 공식 안내

3줄 요약

1. Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 도구로 요청을 받아 프로젝트 파일을 읽고 수정하며 명령을 실행합니다.

2. 2026년 10월 기준 권장 설치는 Node.js 없이 명령 한 줄로 끝나는 네이티브 설치이며 Pro 이상 구독이나 API 과금 계정으로 로그인합니다.

3. 첫 작업은 업무 파일의 사본만 담은 폴더에서 Manual 권한 모드로 시작하고 CLAUDE.md와 스킬, MCP는 같은 설명을 되풀이하게 될 때 추가합니다.