💻 Claude Code Tutorial - 1

🚀 실전 튜터리얼

Claude Code를
정교하게 사용하는 법

설치부터 Hooks 자동화까지 — 직접 따라하며 배우는 Step-by-Step 가이드

6 핵심 단계

41 테스트 통과

0 사전 지식 필요

목차

• 00 환경 준비
• 01 CLAUDE.md
• 02 Plan Mode
• 03 슬래시 명령어
• 04 @ 파일 참조
• 05 프롬프트 패턴
• 06 Hooks 자동화
• 07 워크플로우 총정리

STEP 00

시작 전 환경 확인

Claude Code는 터미널에서 실행되는 도구입니다. claude.ai 채팅창이 아닙니다.

먼저 Node.js 18 이상이 설치되어 있는지 확인하세요:

Terminal

node --version

v25.3.0  ← v18 이상이면 OK

Claude Code 설치 (이미 설치된 경우 생략)

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

연습 프로젝트 폴더 생성 후 시작

mkdir claude-tutorial && cd claude-tutorial && claude

ℹ️ 필요 조건: macOS/Linux/WSL 터미널 + Claude Pro($20/월) 이상 구독 또는 Anthropic API 키.

---

STEP 01

CLAUDE.md — 한 번 쓰고 영원히 적용

가장 중요한 기능입니다. Claude Code가 프로젝트 시작 시 자동으로 읽는 규칙 파일입니다. 여기에 코딩 규칙을 써두면 매번 설명할 필요가 없어집니다.

Claude Code 세션 안에서 /init 명령어로 CLAUDE.md를 자동 생성합니다:

Claude Code

/init

CLAUDE.md를 생성할까요? → Yes 선택

그 다음 실제 규칙을 직접 작성합니다:

Claude Code

CLAUDE.md를 아래 내용으로 업데이트해줘:

- 언어: Python

- 코딩 스타일: 함수마다 docstring 필수, 타입 힌트 사용

- 테스트: 새 함수 만들면 pytest 테스트도 항상 같이 작성

- 커밋 메시지: 한국어로 작성

- 절대 하지 말 것: print 대신 logging, 전역변수 금지

💡 왜 강력한가? 이 파일이 있으면 앞으로 이 프로젝트에서 Claude Code를 열 때마다 자동으로 규칙을 따릅니다. "타입 힌트 써줘", "테스트도 작성해줘"를 매번 말하지 않아도 됩니다.

⚠️ CLAUDE.md는 git에 커밋해두면 팀원 모두가 같은 규칙을 공유할 수 있습니다.

---

STEP 02

Plan Mode — 실행 전 계획 검토

Claude가 파일을 건드리기 전에 "이렇게 할 계획입니다"를 먼저 보여주는 모드입니다. 큰 작업 전에 방향이 맞는지 확인할 수 있어서 필수입니다.

Plan Mode 진입

Claude Code 세션에서 Shift + Tab을 누르면 모드가 순환합니다:

모드 전환 — Shift + Tab

Normal → Auto-Accept → Plan Mode → Normal → ...

왼쪽 하단에 현재 모드 표시됨

Plan Mode로 전환 후 아래를 입력해보세요:

Claude Code — Plan Mode

간단한 계산기 Python 파일을 만들어줘.

더하기, 빼기, 곱하기, 나누기 기능 포함.

실제 Plan Mode 출력 결과

생성할 파일: calculator.py
— add(a, b), subtract(a, b), multiply(a, b), divide(a, b)
— divide는 0으로 나눌 때 ValueError 발생
— 모든 함수에 docstring + 타입 힌트 ← CLAUDE.md 규칙 자동 적용!

test_calculator.py
— 각 연산 함수에 대한 pytest 테스트 케이스 ← 자동 포함!

💡 CLAUDE.md에 써둔 규칙들을 Claude가 스스로 읽고 계획에 반영했습니다. 계획이 마음에 들면 승인, 아니면 수정 요청 후 승인할 수 있습니다.

---

STEP 03

슬래시 명령어 마스터

Claude Code 세션 안에서 바로 사용할 수 있는 핵심 명령어들입니다.

명령어	기능
/init	프로젝트 분석 후 CLAUDE.md 자동 생성
/clear	대화 히스토리 초기화 (파일은 그대로 유지)
/plan	Plan Mode 진입
/doctor	설치 및 환경 진단

/clear — 가장 중요한 습관

새 작업을 시작할 때마다 /clear를 실행하세요. 대화 히스토리가 길어지면 토큰이 낭비되고 Claude가 혼선을 일으킵니다. 파일 자체는 그대로 남습니다.

Claude Code

/clear

대화 초기화됨

calculator.py가 뭐 하는 파일이야?

파일을 직접 읽어서 정확하게 답변

대화 히스토리가 없어도 실제 파일을 읽기 때문에 정확히 동작

---

STEP 04

@ 파일 참조 — 정확한 컨텍스트

여러 파일이 있을 때 Claude가 어떤 파일을 봐야 하는지 명시적으로 지정합니다. 프로젝트가 커질수록 엉뚱한 파일을 수정하는 실수를 방지하는 핵심 기능입니다.

Claude Code

@test_calculator.py 를 보고,

테스트가 빠진 엣지케이스가 있으면 추가해줘

11개 → 22개 테스트로 자동 확장

- add: 0 더하기, 양수+음수 혼합

- subtract: 0 빼기, 같은 수 빼기, 부동소수점

- divide: 음수÷음수, 0÷숫자, ÷1(항등원)

💡 파일명 타이핑 중에 Tab 자동완성이 됩니다. 여러 파일 동시 참조도 가능합니다: @calculator.py @test_calculator.py

---

STEP 05

프롬프트 패턴 — 되묻기 없애기

같은 요청도 어떻게 쓰느냐에 따라 결과가 완전히 달라집니다. 가장 실전적인 부분입니다.

❌ 나쁜 프롬프트 calculator에 기능 추가해줘 → "어떤 기능을 추가할까요?" 되물음
작업 중단, 계속 기다려야 함

✅ 좋은 프롬프트 @calculator.py 에 추가: - power(base, exp): 거듭제곱 - sqrt(a): 제곱근 제약: 기존 함수 건드리지 말 것 테스트도 추가 후 pytest 실행 → 코드 + 테스트 + 검증 한 번에 완료

패턴 1: 역할 + 제약 + 검증 세트

Claude Code

@calculator.py 를 시니어 Python 개발자 관점에서 리뷰해줘.

리뷰 항목: 타입 힌트 누락 / 예외 처리 미흡 / Pythonic하지 않은 코드

출력 형식: [심각도: 상/중/하] 표시

수정은 하지 말고 리뷰만 해줘

패턴 2: TDD (테스트 먼저 작성)

Claude Code — TDD 방식

modulo(a, b) 함수를 추가할건데,

코드 작성 전에 실패하는 테스트를 먼저 @test_calculator.py 에 작성해줘.

테스트 실패 확인 후에 구현해줘.

1. 테스트 작성 → ImportError 확인 (Red 🔴)

2. 함수 구현

3. 37/37 테스트 PASSED (Green 🟢)

🧪 TDD는 실무에서 가장 안전한 개발 방식입니다. Red(실패) → Green(통과) 순서를 Claude가 그대로 따릅니다.

---

STEP 06

Hooks — 자동화 트리거

특정 이벤트가 발생할 때 자동으로 셸 명령을 실행합니다. 파일 저장 시 자동 테스트 실행이 대표적입니다.

이벤트 종류

이벤트	발생 시점
PreToolUse	Claude가 도구 사용하기 직전
PostToolUse	Claude가 도구 사용한 직후 ← 가장 많이 씀
Stop	Claude가 응답 완료했을 때

⚠️ 저장 위치가 핵심!

파일 위치	범위
~/.claude/settings.json	전역 — 모든 프로젝트에 적용 (비추천)
.claude/settings.json	✅ 프로젝트 — 이 프로젝트에만 적용
.claude/settings.local.json	로컬 — git 제외 개인 설정

프로젝트별로 다른 테스트 파일이 있으므로 반드시 프로젝트 레벨에 저장해야 합니다.

Claude Code

PostToolUse hook을 설정해줘.

조건: Write|Edit|MultiEdit 도구로 .py 파일 저장 시

동작: python3 -m pytest test_calculator.py -q 자동 실행

전역(~/.claude)이 아닌 프로젝트(.claude)에 저장해줘.

생성되는 .claude/settings.json 구조:

.claude/settings.json

{

  "hooks": {

    "PostToolUse": [{

      "matcher": "Write|Edit|MultiEdit",

      "hooks": [{ "type": "command",

        "command": "python3 -m pytest test_calculator.py -q" }]

    }]

  }

}

⚠️ matcher를 Write만 설정하면 Edit 도구로 수정할 때 트리거가 안 됩니다. 반드시 Write|Edit|MultiEdit 세 가지를 모두 포함하세요.

---

SUMMARY

실전 워크플로우 총정리

오늘 배운 것들을 실전에서 사용하는 순서로 정리했습니다.

최적 워크플로우

1. 새 프로젝트 시작

mkdir my-project && cd my-project && claude

/init → CLAUDE.md에 언어·스타일·금지사항 작성

2. 큰 작업 전

Shift+Tab (Plan Mode) → 계획 검토 → 승인

3. 작업 시

@파일명 + 요구사항 + 제약 + 검증 세트로 작성

4. 새 작업마다

/clear → 컨텍스트 초기화

5. 자동화

.claude/settings.json → PostToolUse Hook 설정

📋 CLAUDE.md 규칙을 한 번만 써두면 영원히 자동 적용

🔍 Plan Mode Shift+Tab — 실행 전 검토, 큰 작업 필수

@ 파일 참조 정확한 컨텍스트로 엉뚱한 수정 방지

✍️ 프롬프트 패턴 역할+제약+검증 세트로 되묻기 없앰

🪝 Hooks 프로젝트 레벨 .claude/settings.json에만 저장

🧹 /clear 습관 새 작업마다 컨텍스트 초기화 필수

Claude Code 실전 튜터리얼 · macOS + Claude Pro 환경 기준
공식 문서: docs.anthropic.com/en/docs/claude-code