Claude Code 시작하기 — 터미널 사이드킥 셋업 가이드

복잡한 비즈니스 로직이 얽혀있는 백엔드 코드. 한 곳을 고치면 다른 세 곳이 터지는 아슬아슬한 레거시. 이런 폭탄 같은 코드를 다뤄야 할 때 개발자들이 가장 신뢰하는 에이전트는 단연 Claude Code다.

Anthropic이 만든 Claude Code는 단순히 빠른 속도나 넓은 컨텍스트를 자랑하는 것이 아니다. 압도적으로 정교한 추론 능력으로 코드를 부수지 않고 안전하게 리팩토링하는 "신중한 시니어 엔지니어"에 가깝다.

이번 4편에서는 이 강력한 터미널 사이드킥을 내 로컬 환경에 설치하고 셋업하는 방법을 알아본다.

1. 설치 및 권한 인증

Claude Code는 Anthropic의 유료 플랜(Pro, Team, Enterprise, API Console 등) 사용자에게 제공된다.

네이티브 설치 (권장)

가장 빠르고 안정적인 방법은 공식 셸 스크립트를 사용하는 것이다.

curl -fsSL https://claude.ai/install.sh | bash

버전을 고정해야 하거나 패키지 매니저 관리가 편하다면 npm을 사용할 수도 있다. npm install -g @anthropic-ai/claude-code

첫 실행과 OAuth 인증

설치가 완료되면 터미널에 claude를 입력한다.

claude

처음 실행하면 브라우저가 열리며 Anthropic 계정 인증을 요구한다. 인증이 완료되면 터미널 창에 반가운 프롬프트가 나타난다. 이제 준비는 끝났다.

2. 모드 전환: 안전함과 속도 사이의 줄타기

Claude Code의 가장 큰 특징 중 하나는 안전 제어 장치다. 에이전트가 로컬 파일 시스템을 제어하고 셸 커맨드를 실행할 수 있기 때문에, 권한을 얼마나 줄 것인지 설정하는 것이 매우 중요하다.

터미널 프롬프트에서 Shift + Tab 키를 누르면 다음 세 가지 핵심 모드를 순환할 수 있다.

🛡️ Normal 모드 (기본값)

특징: 돌다리도 두드려보고 건너는 모드.
동작: 코드를 수정하거나, 파일을 지우거나, 셸 명령(npm install 등)을 실행하려 할 때마다 반드시 사용자에게 y/n 승인을 묻는다.
추천: 처음 다뤄보는 낯선 저장소, 절대 깨지면 안 되는 프로덕션 코드를 다룰 때.

⚡ Auto-Accept 모드

특징: 속도전. 승인 절차를 생략한다.
동작: 파일 수정, 생성 등의 작업을 묻지 않고 즉각적으로 처리한다. 단, 시스템에 치명적인 영향을 줄 수 있는 고위험 셸 커맨드는 여전히 물어볼 수 있다.
추천: 대규모 리팩토링, 수십 개의 자잘한 파일 수정, 내가 코드를 완전히 파악하고 있는 친숙한 프로젝트.

📝 Plan 모드

특징: 코딩 전 설계 전용 모드. Read-only로 동작한다.
동작: 코드를 읽고 분석만 할 뿐, 절대 변경하거나 커맨드를 실행하지 않는다. 어떻게 수정할지 마크다운 형태로 계획서만 작성해 준다.
추천: 아키텍처 변경 전 리뷰, 버그 원인 파악, Vibe Coding의 3단계 워크플로우 중 '계획(Plan)' 단계.

[!TIP] 2026년형 Auto 모드 최근 추가된 --permission-mode auto를 사용하면, Claude가 자체 분류기를 통해 "안전한 작업(단순 텍스트 수정)"은 알아서 통과시키고, "위험한 작업(DB 드랍, 패키지 삭제)"만 사람에게 물어보도록 스마트하게 동작한다.

3. 영혼 주입하기: CLAUDE.md

아무리 똑똑한 개발자도 회사에 갓 입사하면 코딩 컨벤션부터 배워야 한다. Claude Code에게 내 프로젝트의 룰을 가르쳐주는 곳이 바로 CLAUDE.md 파일이다.

셋업하기

터미널에서 /init 명령어를 입력하면, Claude가 폴더를 스캔하고 기본 뼈대가 되는 CLAUDE.md를 프로젝트 루트에 생성해 준다. 매번 세션이 시작될 때마다 Claude는 이 파일을 가장 먼저 읽고 기억(Auto Memory)에 저장한다.

작성 베스트 프랙티스

CLAUDE.md는 너무 길면 토큰을 낭비하고 효과가 떨어진다. 50~100줄 내외로 핵심만 유지하는 것이 좋다.

# 🚀 Acme Corp 백엔드 룰 (CLAUDE.md)

## 핵심 스택
- Node.js 20, NestJS 10, TypeORM, PostgreSQL

## 절대 지켜야 할 규칙
1. **DB 마이그레이션:** 데이터베이스 스키마를 변경할 때는 절대 수동으로 SQL을 짜지 마. 반드시 TypeORM 마이그레이션 스크립트를 생성할 것.
2. **비동기 처리:** `then/catch` 체이닝을 피하고 무조건 `async/await`를 사용할 것.
3. **에러 핸들링:** 컨트롤러에서 직접 에러를 던지지 마. 반드시 `src/filters/`에 있는 전역 예외 필터를 활용할 것.

## 테스트 명령어
- 유닛 테스트: `npm run test`
- e2e 테스트: `npm run test:e2e` (수정 후 반드시 이거부터 돌려볼 것)

만약 개인적인 취향(예: "나는 vim 스타일 단축키를 좋아해")을 넣고 싶다면, 전역 설정인 ~/.claude/settings.json을 사용하거나 .gitignore에 등록된 CLAUDE.local.md를 사용하는 것이 깔끔하다.

📝 정리

[x] 설치와 인증: curl 설치 스크립트 하나로 간단히 설치하고 브라우저로 인증한다. (유료 플랜 필요)
[x] Shift+Tab 모드 전환: 작업의 위험도에 따라 Normal(승인), Auto-Accept(자동), Plan(설계 전용) 모드를 자유자재로 넘나들어야 한다.
[x] CLAUDE.md: 프로젝트의 규칙, 프레임워크 룰, 절대 해서는 안 될 금지 사항을 명시하여 AI의 헛발질을 막는 핵심 통제 장치다.

로컬 환경 세팅이 끝났다. 다음 5편에서는 이 똑똑한 사이드킥과 함께 복잡한 멀티파일 리팩토링을 수행하고, 에러가 해결될 때까지 스스로 디버깅하는 /loop 기능과 Agent Teams 협업에 대해 깊이 파고들어 보자.