[튜토리얼] Claude Code로 프로젝트 시작하기

Claude Code란

Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 에이전트입니다. VS Code의 확장이나 웹 인터페이스가 아니라, 터미널에서 직접 실행되며 로컬 파일 시스템을 읽고, 코드를 수정하고, 명령어를 실행합니다.

핵심 특징

기능	설명
코드베이스 인식	프로젝트 전체를 인덱싱하고 파일 간 관계 파악
로컬 실행	파일 편집, 명령어 실행을 로컬에서 직접 수행
권한 시스템	파일 변경, 명령어 실행 시 사용자 승인 필요
Plan Mode	복잡한 작업을 단계별로 계획 후 실행
CLAUDE.md	프로젝트별 코딩 규칙과 컨텍스트를 정의하는 설정 파일

1단계: 설치

사전 요구사항

Node.js 18 이상
Anthropic API 키 (https://console.anthropic.com)

설치 명령어

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

설치 후 API 키를 설정합니다.

export ANTHROPIC_API_KEY="sk-ant-your-key-here"

영구 설정을 원하면 ~/.zshrc 또는 ~/.bashrc에 위 줄을 추가합니다.

실행 확인

claude --version

버전 정보가 출력되면 설치가 완료된 것입니다. 이제 프로젝트 디렉토리에서 claude를 입력하면 세션이 시작됩니다.

cd ~/my-project
claude

2단계: CLAUDE.md 작성

CLAUDE.md는 Claude Code가 세션을 시작할 때 가장 먼저 읽는 파일입니다. 프로젝트의 코딩 규칙, 아키텍처 결정, 선호하는 라이브러리 등을 정의합니다.

프로젝트 루트에 CLAUDE.md 파일을 생성합니다.

# 프로젝트 개요
Next.js 16 + TypeScript + Tailwind CSS 기반 블로그 사이트

## 기술 스택
- Framework: Next.js 16 (App Router, Static Export)
- Language: TypeScript (strict mode)
- Styling: Tailwind CSS 4
- Content: Markdown (gray-matter + remark)

## 코딩 규칙
- 컴포넌트: React Server Components 우선, 필요시에만 "use client"
- 파일명: kebab-case (my-component.tsx)
- 함수: export default function 사용, arrow function 금지
- 타입: interface 우선, type은 유니온/인터섹션에만 사용
- import: 절대경로 (@/) 사용

## 금지 사항
- any 타입 사용 금지
- console.log 커밋 금지
- 불필요한 주석 금지 (코드로 설명)

## 프로젝트 구조
src/
  app/          # 페이지 라우트
  components/   # 재사용 컴포넌트
  lib/          # 유틸리티 함수
content/
  posts/        # 마크다운 포스트

CLAUDE.md 작성 팁

구체적으로 작성합니다. "깔끔한 코드를 작성해" 대신 "함수는 50줄 이내, 파라미터는 3개 이내"처럼 측정 가능한 기준을 제시합니다.
금지 사항을 명시합니다. Claude Code는 허용된 것보다 금지된 것에 더 잘 반응합니다.
아키텍처 결정을 기록합니다. "왜 이 라이브러리를 선택했는지"를 적으면 Claude가 일관된 결정을 내립니다.

3단계: Plan Mode 활용

2개 이상의 파일을 수정하는 작업이라면 Plan Mode를 사용합니다. Plan Mode는 코드를 바로 수정하지 않고, 먼저 실행 계획을 보여줍니다.

Plan Mode 실행

Claude Code 세션 내에서 /plan 명령어를 입력합니다.

> /plan 블로그에 검색 기능을 추가하고 싶어.
  검색 인덱스는 빌드 타임에 생성하고,
  클라이언트에서 fuzzy search를 지원해야 해.

Claude는 다음과 같은 계획을 제시합니다.

Plan:
1. search-index.json API 라우트 생성 (src/app/search-index.json/route.ts)
   - 모든 포스트의 title, description, tags를 JSON으로 출력
2. SearchBar 컴포넌트 생성 (src/components/search-bar.tsx)
   - "use client" 컴포넌트
   - fuse.js를 사용한 fuzzy search
   - 디바운스된 입력 처리
3. 레이아웃에 SearchBar 통합 (src/app/layout.tsx)
   - 헤더 영역에 검색바 추가
4. 패키지 설치
   - npm install fuse.js

Proceed? [y/n]

y를 입력하면 계획대로 단계별 실행을 시작합니다. 각 단계마다 변경사항을 보여주고 승인을 요청합니다.

4단계: 실전 워크플로

일상적인 코딩 작업

> 이 컴포넌트에 다크모드 토글 버튼을 추가해줘

간단한 수정은 Plan Mode 없이 바로 요청합니다. Claude Code는 관련 파일을 자동으로 찾아 수정합니다.

버그 수정

> npm run build 하면 타입 에러가 나. 에러 로그를 보고 수정해줘

Claude Code는 빌드 명령을 실행하고, 에러를 분석하고, 수정까지 자동으로 진행합니다.

코드 리뷰

> git diff main 의 변경사항을 리뷰해줘.
  보안 취약점, 성능 이슈, 코딩 규칙 위반을 체크해.

커밋 전 코드 리뷰를 요청하면 CLAUDE.md에 정의된 규칙 기준으로 검토합니다.

Git 커밋

> 변경사항을 커밋해줘. 커밋 메시지는 conventional commits 형식으로.

Claude Code가 변경사항을 분석하고 적절한 커밋 메시지를 생성합니다.

5단계: 유용한 슬래시 명령어

명령어	기능
`/plan`	Plan Mode 진입 (복잡한 작업 시)
`/help`	사용 가능한 명령어 목록
`/clear`	컨텍스트 초기화
`/cost`	현재 세션의 API 사용량 확인
`/compact`	대화 내역 압축 (토큰 절약)

비용 관리

Claude Code는 API 기반이므로 토큰 사용량에 따라 비용이 발생합니다.

비용 절감 팁

CLAUDE.md를 잘 작성합니다. 프로젝트 컨텍스트를 명확히 하면 불필요한 질의 반복이 줄어듭니다.
/compact를 주기적으로 사용합니다. 긴 세션에서 대화 내역이 쌓이면 토큰 소비가 급증합니다.
구체적으로 요청합니다. "이 파일 개선해줘"보다 "src/lib/utils.ts의 parseDate 함수에서 ISO 8601 형식도 지원하게 수정해줘"가 토큰을 절약합니다.
Plan Mode를 활용합니다. 계획 없이 바로 수정하면 잘못된 방향으로 갔을 때 롤백과 재시도에 추가 비용이 듭니다.

핵심 요약

Claude Code는 터미널 기반 AI 코딩 에이전트로, npm install -g @anthropic-ai/claude-code로 설치하고 프로젝트 디렉토리에서 claude로 실행합니다
CLAUDE.md에 프로젝트 규칙과 아키텍처를 정의하면 Claude Code가 일관된 코드를 생성합니다
2개 이상의 파일을 수정하는 작업은 Plan Mode(/plan)를 사용해 계획 후 실행하는 것이 효율적입니다