Claude Code 완벽 가이드: Mac에서 시작하기

AI/AI Tool

Claude Code 완벽 가이드: Mac에서 시작하기

Somaz 2026. 1. 15. 00:00

728x90

Overview

터미널에서 바로 AI와 코딩하는 시대가 왔다. Claude Code는 Anthropic에서 만든 CLI 기반 에이전틱 코딩 도구로, IDE를 벗어나 터미널에서 직접 Claude와 대화하며 코드를 작성하고, 수정하고, 디버깅할 수 있다.

Claude Code란?

Claude Code는 단순한 코드 자동완성 도구가 아니다. 터미널에서 실행되는 에이전트로, 프로젝트의 컨텍스트를 이해하고 파일을 직접 읽고 쓰며, 쉘 명령어까지 실행할 수 있다. 개발자가 자연어로 지시하면 Claude가 알아서 코드를 수정하고 테스트까지 돌려준다.

설치 방법

사전 요구사항

macOS 10.15 이상
Node.js 18 이상

Node.js가 없다면 먼저 설치한다.

# Homebrew로 Node.js 설치
brew install node

# 버전 확인
node --version

Claude Code 설치

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

설치가 완료되면 claude 명령어를 사용할 수 있다.

트러블 슈팅

만약 npm registry를 offical로 사용하고 있지 않다면 아래의 명령어를 사용해서 변경해준다.

npm config get registry

공식 npm 레지스트리로 변경

npm config set registry https://registry.npmjs.org/

또는 일시적으로 레지스트리 지정해서 설치할 수도 있다.

npm install -g @anthropic-ai/claude-code --registry https://registry.npmjs.org/

이렇게 하면 기존 설정 건드리지 않고 설치 가능하다.

시작하기

인증

Pro 요금제를 사용 중이라면 별도의 API 키 없이 Anthropic 계정으로 바로 인증할 수 있다.

# 프로젝트 디렉토리로 이동
cd ~/projects/my-app

# Claude Code 실행
claude

처음 실행하면 브라우저가 열리면서 계정 인증을 진행한다. 인증이 완료되면 바로 대화형 모드로 진입한다.

기본 사용법

Claude Code는 크게 세 가지 방식으로 사용할 수 있다.

# 1. 대화형 REPL 모드
claude

# 2. 일회성 질문
claude "이 프로젝트의 구조를 설명해줘"

# 3. 이전 대화 이어서 계속
claude -c

주요 명령어 정리

터미널 명령어

명령어	설명
claude	대화형 REPL 모드 시작
claude "질문"	한 번만 질문하고 종료
claude -c	마지막 대화 이어서 계속
claude -p "질문"	파이프라인 모드 (스크립트 연동용)
claude config	설정 메뉴 열기
claude update	최신 버전으로 업데이트

REPL 모드 슬래시 명령어

대화형 모드에서 사용할 수 있는 명령어들이다.

명령어	설명
/help	전체 도움말 보기
/clear	대화 내역 초기화
/compact	컨텍스트 압축 (토큰 절약)
/cost	현재 세션 토큰 사용량 확인
/doctor	설치 및 환경 진단
/init	프로젝트 설정 파일 생성
/quit	종료 (Ctrl+C 두 번도 가능)
/model	모델 변경

web console 사용량을 공유한다.

실전 활용 예시

코드 이해 및 설명

claude "src/api/auth.ts 파일이 어떤 역할을 하는지 설명해줘"

버그 수정

claude "npm run build 하면 타입 에러가 나. 고쳐줘"

리팩토링

claude "이 함수를 더 읽기 쉽게 리팩토링해줘"

테스트 작성

claude "UserService 클래스에 대한 Jest 테스트 코드 만들어줘"

Git 작업

claude "변경사항 확인하고 적절한 커밋 메시지로 커밋해줘"

문서화

claude "이 프로젝트의 README.md를 작성해줘"

프로젝트 설정

프로젝트 루트에 CLAUDE.md 파일을 만들어두면 Claude가 프로젝트 컨텍스트를 더 잘 이해한다.

claude /init

`CLAUDE.md` 에 담으면 좋은 내용은 다음과 같다.

프로젝트 개요 및 기술 스택
주요 디렉토리 구조
빌드 및 실행 방법
코딩 컨벤션
자주 쓰는 명령어

Pro 요금제 사용 팁

Pro 플랜은 월간 사용량 제한이 있다. 효율적으로 사용하려면 다음을 참고하자.

`/cost` 명령어로 현재 세션의 토큰 사용량을 수시로 확인한다.
`/compact` 명령어로 긴 대화의 컨텍스트를 압축해 토큰을 절약한다.
단순한 질문은 웹 버전 Claude를 활용하고, 코드 작업이 필요할 때 Claude Code를 사용한다.

사용량이 많아지면 일시적으로 속도 제한이 걸릴 수 있다.

문제 해결

설치나 실행에 문제가 있다면 진단 명령어를 실행해본다.

claude /doctor

자주 발생하는 문제와 해결법은 다음과 같다.

permission denied 에러: `sudo npm install -g @anthropic-ai/claude-code` 또는 npm 권한 설정 확인
Node.js 버전 문제: `node --version` 으로 18 이상인지 확인
인증 실패: `claude config` 에서 계정 다시 연결

Claude Code 활용

Claude Code는 단순히 코드를 작성하는 것 이상으로, 개발 워크플로우 전반에 걸쳐 활용할 수 있다.

코드베이스 이해하기

새로운 프로젝트에 투입되었을 때 가장 먼저 해야 할 일은 코드베이스를 파악하는 것이다.

# 프로젝트 전체 구조 파악
claude "이 프로젝트의 아키텍처를 설명해줘"

# 특정 파일의 역할 이해
claude "src/services/payment.ts가 어떤 로직을 처리하는지 알려줘"

# 함수 간 의존관계 분석
claude "handleCheckout 함수가 호출하는 다른 함수들을 다이어그램으로 보여줘"

코드 작성 및 수정

자연어로 원하는 기능을 설명하면 Claude가 직접 파일을 생성하거나 수정한다.

# 새 기능 구현
claude "사용자 프로필 이미지 업로드 API를 만들어줘. S3에 저장하고 URL을 반환해야 해"

# 기존 코드 개선
claude "이 함수에 에러 핸들링 추가해줘"

# 타입 정의 생성
claude "API 응답에 맞는 TypeScript 인터페이스 만들어줘"

디버깅 및 문제 해결

에러 메시지를 복사해서 붙여넣으면 원인 분석부터 해결까지 도와준다.

# 에러 분석
claude "이 에러 메시지가 왜 나오는 거야? [에러 내용 붙여넣기]"

# 로그 분석
claude "이 로그에서 문제가 되는 부분을 찾아줘"

# 성능 이슈 진단
claude "이 쿼리가 왜 느린지 분석해줘"

테스트 및 품질 관리

테스트 코드 작성부터 코드 리뷰까지 자동화할 수 있다.

# 단위 테스트 생성
claude "UserService에 대한 테스트 코드 작성해줘"

# 테스트 커버리지 개선
claude "커버리지가 낮은 부분에 테스트 추가해줘"

# 코드 리뷰
claude "이 PR의 변경사항을 리뷰해줘"

Git 워크플로우 자동화

커밋, 브랜치 관리, PR 생성까지 터미널에서 처리할 수 있다.

# 커밋 메시지 자동 생성
claude "변경사항 보고 커밋 메시지 작성해서 커밋해줘"

# PR 설명 작성
claude "이 브랜치의 변경사항으로 PR 설명을 작성해줘"

# 충돌 해결
claude "merge conflict 해결해줘"

Infrastructure as Code 작업

DevOps 작업에도 유용하게 활용할 수 있다.

# Terraform 코드 작성
claude "AWS EKS 클러스터를 생성하는 Terraform 코드 만들어줘"

# Kubernetes 매니페스트 생성
claude "이 애플리케이션을 위한 Deployment와 Service YAML 만들어줘"

# CI/CD 파이프라인 구성
claude "GitHub Actions로 빌드, 테스트, 배포 파이프라인 만들어줘"

프로젝트 관리

Claude Code는 프로젝트별로 컨텍스트를 관리할 수 있어 여러 프로젝트를 효율적으로 다룰 수 있다.

CLAUDE.md 설정

프로젝트 루트에 `CLAUDE.md` 파일을 생성하면 Claude가 프로젝트 컨텍스트를 자동으로 인식한다.

# 자동 생성
claude /init

# 또는 직접 생성
touch CLAUDE.md

CLAUDE.md 예시

# 프로젝트: MyApp API Server

## 기술 스택
- Node.js 20 + TypeScript
- Express.js
- PostgreSQL + Prisma ORM
- Jest for testing

## 디렉토리 구조
- src/controllers: API 엔드포인트 핸들러
- src/services: 비즈니스 로직
- src/repositories: 데이터 접근 계층
- src/middlewares: 인증, 로깅 등 미들웨어

## 명령어
- npm run dev: 개발 서버 실행
- npm run build: 프로덕션 빌드
- npm run test: 테스트 실행
- npm run migrate: DB 마이그레이션

## 컨벤션
- 커밋 메시지는 Conventional Commits 형식 사용
- 함수명은 camelCase, 클래스명은 PascalCase
- API 응답은 { success, data, error } 형식 통일

프로젝트별 설정 관리

여러 프로젝트를 오가며 작업할 때는 각 프로젝트 디렉토리에서 Claude Code를 실행하면 된다.

# 프로젝트 A 작업
cd ~/projects/frontend-app
claude

# 프로젝트 B로 전환
cd ~/projects/backend-api
claude

각 디렉토리의 `CLAUDE.md` 를 읽어 해당 프로젝트에 맞는 컨텍스트로 동작한다.

대화 히스토리 관리

# 이전 대화 이어서 작업
claude -c

# 새로운 대화 시작 (기존 컨텍스트 초기화)
claude

# REPL 모드에서 대화 초기화
/clear

# 컨텍스트가 너무 길어졌을 때 압축
/compact

팀 프로젝트에서 활용

`CLAUDE.md` 를 Git에 커밋해두면 팀원 모두 동일한 컨텍스트로 Claude Code를 사용할 수 있다.

# .gitignore에 추가하지 않음
git add CLAUDE.md
git commit -m "docs: add CLAUDE.md for AI-assisted development"

팀 컨벤션, 자주 쓰는 명령어, 프로젝트 특이사항 등을 문서화해두면 온보딩에도 도움이 된다.

마무리

Claude Code는 터미널 기반 개발 워크플로우를 완전히 바꿔놓을 도구다. 기존에 IDE 플러그인 형태로 제공되던 AI 코딩 도구들과 달리, CLI에서 직접 동작하기 때문에 SSH로 접속한 원격 서버에서도, CI/CD 파이프라인에서도, 심지어 Vim이나 Neovim만 쓰는 환경에서도 활용할 수 있다.

특히 DevOps 엔지니어 입장에서 보면 Terraform 코드 작성, Kubernetes 매니페스트 수정, 쉘 스크립트 디버깅 같은 작업을 터미널을 벗어나지 않고 처리할 수 있다는 점이 매력적이다. `kubectl get pods` 결과를 보면서 바로 "이 에러 원인이 뭐야?"라고 물어볼 수 있고, Claude가 직접 YAML 파일을 수정해주기도 한다.

아직 발전 중인 도구라 가끔 불안정할 수 있지만, 터미널 중심으로 작업하는 개발자라면 한 번쯤 도입을 고려해볼 만하다. Pro 요금제를 이미 사용 중이라면 추가 비용 없이 바로 시작할 수 있으니, 오늘 설치해서 직접 경험해보자.

Reference

728x90

저작자표시 비영리 변경금지 (새창열림)

'AI > AI Tool' 카테고리의 다른 글

Claude 4.5 Sonnet vs Gemini 3 Pro 비교: 2026년 최신 AI 모델 대결 (0)	2026.01.17
Claude와 Claude Code: AI 기반 개발 환경의 새로운 패러다임 (1)	2026.01.10

현재글Claude Code 완벽 가이드: Mac에서 시작하기