Claude Code 완벽 가이드 (1) - 설치부터 기본 기능까지

작년 초만 해도 저는 Cursor를 주력으로 사용했습니다. 그런데 지금은 거의 Claude Code만 쓰고 있어요. 터미널 기반이라 처음엔 낯설었는데, 익숙해지고 나니 오히려 이게 더 빠르고 강력하다는 생각이 듭니다.

이 글에서는 Claude Code를 처음 접하는 분들을 위해 설치부터 기본 기능까지 정리해 보려고 합니다.

---

Claude Code란?

Claude Code는 Anthropic에서 만든 터미널 기반 AI 코딩 에이전트입니다. VS Code나 Cursor 같은 IDE가 아니라 터미널에서 직접 실행하는 방식이에요.

처음에는 소스 원복이나 코드 리뷰가 불편했는데, 지금은 업데이트가 많이 되어서 롤백도 쉽고 diff 확인도 편해졌습니다. 터미널이라 낯설 수 있지만, 코드 에디터는 기존에 쓰던 걸 그대로 쓰면서 Claude Code를 함께 활용하면 됩니다.

---

설치 방법

설치 방법은 세 가지가 있습니다.

방법 1: Native Install (권장)

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

방법 2: Homebrew (macOS)

brew install --cask claude-code

방법 3: NPM

npm install -g @anthropic-ai/claude-code

 

설치가 완료되면, 프로젝트 폴더로 이동해서 claude를 입력하면 됩니다.

cd your-project
claude

처음 실행하면 Anthropic 계정 로그인을 요청합니다. 로그인하면 바로 사용할 수 있습니다.

---

기본 기능

 /init  - 프로젝트 초기화

새 프로젝트에서 Claude Code를 처음 사용한다면, 가장 먼저 할 일은 /init 명령어입니다.

/init

이 명령어를 실행하면 Claude Code가 프로젝트 전체를 분석해서 CLAUDE.md 파일을 자동으로 생성해 줍니다.

CLAUDE.md가 뭔가요?

CLAUDE.md는 Claude Code의 "기억 파일"입니다. 이 파일에 프로젝트에 대한 정보를 적어두면, Claude가 매번 새로운 대화를 시작해도 프로젝트 맥락을 이해한 상태로 시작합니다.

/init으로 자동 생성된 CLAUDE.md를 보면 이런 내용이 들어 있습니다.

# Project Overview
Next.js 14 기반 웹 애플리케이션

# Tech Stack
- Framework: Next.js 14 (App Router)
- Language: TypeScript
- Styling: Tailwind CSS
- Database: Prisma + PostgreSQL

# Project Structure
/app - 페이지 및 라우팅
/components - 재사용 컴포넌트
/lib - 유틸리티 함수
...

 

이 파일은 자동 생성된 후에 직접 수정해도 됩니다. 예를 들어

# Coding Rules
- 함수명은 camelCase 사용
- 컴포넌트는 PascalCase 사용
- 한국어 주석 선호
- console.log 대신 proper logging 사용

# 자주 하는 실수 (Claude 참고용)
- Prisma migrate 전에 db push 먼저 실행할 것
- API 라우트에서 try-catch 필수

이렇게 규칙을 적어두면 Claude가 코드 작성할 때 이를 따릅니다. 팀 프로젝트라면 이 파일을 Git에 커밋해서 공유하면 팀원 모두 같은 규칙으로 Claude를 사용할 수 있습니다.

모드 전환 -  Shift + Tab 

Claude Code에는 두 가지 모드가 있습니다.

1. Plan 모드

• 코드를 직접 수정하지 않음
• 계획만 세우고 검토
• "이렇게 하면 어떨까요?" 식으로 제안

2. Act 모드 (기본)

• 실제로 코드를 수정
• 파일 생성, 삭제, 편집 가능

Shift + Tab을 누르면 모드를 전환할 수 있습니다.

언제 Plan 모드를 쓰나요?

복잡한 기능을 구현하기 전에 먼저 계획을 세우고 싶을 때 유용합니다.

[Plan 모드에서]
사용자 인증 기능을 구현하려고 해. 
어떤 파일들을 만들어야 하고, 어떤 순서로 작업하면 좋을지 계획 세워줘.

Claude가 계획을 제시하면 검토하고, 마음에 들면 Shift + Tab으로 Act 모드로 전환해서 실행하면 됩니다.

저는 보통 이렇게 씁니다.

1. Plan 모드에서 계획 수립
2. 계획 검토 및 수정 요청
3. 만족스러우면 Act 모드로 전환
4. "위 계획대로 진행해줘" 입력

이렇게 하면 Claude가 엉뚱한 방향으로 가는 걸 미리 방지할 수 있습니다.

 /config  - 설정

/config 명령어로 Claude Code의 기본 설정을 변경할 수 있습니다.

/config

주요 설정 항목

1. Model 선택

• Claude Sonnet 4.5 (빠름)
• Claude Opus 4.5 (느리지만 더 똑똑함)
• Claude Haiku 4.5 (가장 빠름)

2. Thinking 모드

• 활성화하면 Claude가 더 깊이 생각하고 답변
• 복잡한 문제에 유용

3. Rewind code

• Claude가 수정한 코드를 이전 상태로 되돌리는 기능
• 잘못된 변경이 있을 때 빠르게 원복 가능

4. Notifications

• Claude가 입력을 기다리거나 작업이 완료됐을 때 알림
• 병렬로 여러 세션 돌릴 때 유용

5. Auto-connect to IDE

• VS Code 등 IDE와 자동 연결
• Claude가 수정한 파일이 IDE에서 바로 반영됨

 /clear  - 대화 초기화

/clear

현재 세션의 대화 기록을 모두 지웁니다.

왜 필요한가요?

Claude Code는 대화가 쌓일수록 컨텍스트 윈도우가 차오릅니다. 너무 많은 대화가 쌓이면

• 예전 내용과 최근 내용이 섞여서 혼란
• 응답 품질 저하
• 토큰 비용 증가

그래서 하나의 기능 개발이 끝나면 /clear로 초기화하고 새로 시작하는 게 좋습니다.

 /resume  - 이전 대화 불러오기

/resume

/clear로 지운 대화나 이전 세션의 대화를 다시 불러올 수 있습니다.

"아, 아까 그 대화에서 이어서 작업하고 싶은데..."할 때 유용해요.

 /export  - 대화 내보내기

/export

현재 대화 내용을 클립보드나 파일로 내보냅니다.

활용 예시:

• Claude Code에서 작업하다가 Cursor로 이어서 하고 싶을 때
• 대화 내용을 문서로 저장하고 싶을 때
• 팀원에게 작업 내용을 공유하고 싶을 때

 /mcp  - MCP 서버 상태 확인

/mcp

현재 연결된 MCP 서버들의 상태를 확인합니다.

/agents - 서브에이전트 관리

/agents

서브에이전트 목록을 보거나 새로 만들 수 있습니다. (자세한 내용은 아래에서 설명)

터미널 명령어 실행 -  ! 

Claude Code 안에서 터미널 명령어를 직접 실행할 수도 있습니다. 느낌표(!)를 앞에 붙이면 됩니다.

!npm run build
!git status
!prisma db push

장점:

• 터미널을 따로 열 필요 없음
• 실행 결과를 Claude가 바로 볼 수 있음
• 에러가 나면 Claude가 바로 분석하고 해결책 제시

예를 들어 !npm run build에서 에러가 나면, Claude가 에러 메시지를 보고 "이 부분이 문제네요, 이렇게 수정하면 됩니다"라고 바로 알려줍니다.

---

마무리

여기까지가 Claude Code의 기본 기능입니다. 정리하면:

1. 설치: Native Install, Homebrew, NPM 중 선택
2. 초기화: /init으로 CLAUDE.md 생성
3. 모드 전환: Shift + Tab으로 Plan/Act 모드 전환
4. 설정: /config에서 모델, Thinking 모드 등 설정
5. 유틸리티: /clear, /resume, /export 등 활용
6. 터미널 실행: ! 붙여서 명령어 직접 실행

다음 글에서는 커스텀 명령어, 서브에이전트, Hooks, MCP 서버 연동 등 중급 기능을 다루겠습니다. Claude Code를 만든 보리스 체르니의 활용법도 이어서 다음글에 소개하겠습니다.

Claude Code 완벽 가이드 (2) - 커스텀 명령어부터 고급 활용까지

 

---

참고

• Claude Code 공식 문서