Claude Code란?

Claude Code가 무엇인지, 다른 AI 도구와 어떻게 다른지 알아봅니다.

01. Claude Code란?

터미널에서 실행되는 AI 코딩 어시스턴트 — 코드를 읽고, 파일을 수정하고, 명령을 직접 실행합니다.

한 줄 정의

Claude Code는 터미널(명령줄)에서 작동하는 AI 코딩 도구입니다. 코드를 읽고, 파일을 직접 수정하고, 테스트를 실행하고, Git 커밋까지 만들어 줍니다. 말 그대로 "내 컴퓨터에서 일하는 AI 개발 파트너"입니다.

Claude.ai 웹 vs Claude Code vs Cursor — 핵심 차이

	Claude.ai 웹	Claude Code	Cursor
어디서 쓰나	브라우저	터미널 / 데스크탑 앱 / IDE	IDE (에디터)
파일 직접 수정	불가 (복붙 필요)	가능 (자동)	가능
명령어 실행	불가	가능 (테스트, 빌드 등)	제한적
전체 코드베이스 이해	수동으로 붙여넣어야 함	자동으로 읽음	자동으로 읽음
Git 연동	불가	가능 (커밋, PR 생성)	제한적
가격	구독 포함	구독 포함 또는 API 과금	별도 구독

핵심 차이: Claude.ai 웹은 대화창에서 코드를 보여주기만 합니다. Claude Code는 실제로 파일을 열고, 수정하고, 저장하고, 실행까지 합니다.

CLI(터미널)라서 강력한 이유

Claude Code가 터미널에서 실행되는 것은 단순한 설계 선택이 아닙니다. 터미널은 컴퓨터에서 할 수 있는 모든 것의 관문이기 때문입니다.

Claude Code가 직접 할 수 있는 것들

능력	설명
파일 읽기/쓰기	프로젝트의 모든 파일을 읽고 직접 수정
명령어 실행	테스트 실행, 빌드, 서버 시작 등
검색	파일명, 코드 내용, 정규식으로 코드베이스 탐색
Git 작업	스테이징, 커밋, 브랜치 생성, PR 열기
웹 검색	에러 메시지 검색, 문서 확인
코드 인텔리전스	타입 에러 감지, 정의로 이동, 참조 찾기

실제로 어떻게 작동하나? (예시)

예시 1: 버그 수정 요청

사용자: "테스트가 실패하는데 고쳐줘"

Claude Code가 하는 일:
1. 테스트 스위트 실행 → 실패 항목 확인
2. 에러 로그 읽기
3. 관련 소스 파일 검색
4. 파일 내용 읽고 코드 이해
5. 파일 수정 (버그 패치)
6. 테스트 다시 실행 → 통과 확인

예시 2: 새 기능 추가 요청

사용자: "로그인 폼에 입력값 검증 기능 추가해줘"

Claude Code가 하는 일:
1. 프로젝트 구조 파악
2. 기존 폼 코드 찾기
3. 검증 로직 작성 및 파일에 직접 삽입
4. 관련 테스트 작성
5. Git 커밋 메시지 작성 후 커밋

어떤 사람에게 맞는가?

Claude Code가 잘 맞는 사람

유형	이유
바이브코더	코드 작성보다 방향 설정에 집중하고 싶은 개발자
비개발자 창업자	아이디어를 실제 코드로 구현하고 싶은데 개발 지식이 부족한 분
입문 개발자	코드를 배우면서 동시에 실제 프로젝트를 진행하고 싶은 분
1인 개발자	혼자서 풀스택 개발을 빠르게 진행해야 하는 분
반복 작업이 많은 개발자	테스트 작성, 린트 수정, 의존성 업데이트 등 반복 작업을 자동화하고 싶은 분

이런 분에게도 추천

"코드가 뭔지는 아는데 직접 짜기는 어려운" 비개발자
터미널이 익숙하지 않지만 배워보고 싶은 분 (데스크탑 앱도 있습니다)
MVP(최소 기능 제품)를 빠르게 만들어야 하는 스타트업 팀원

이런 분에게는 맞지 않을 수 있음

순수하게 글쓰기, 번역, 분석만 필요한 분 → Claude.ai 웹으로 충분
특정 IDE 안에서만 작업하고 싶은 분 → Cursor나 VS Code 확장 고려

어디서 사용할 수 있나?

Claude Code는 터미널에만 국한되지 않습니다.

환경	설명
터미널 (CLI)	가장 강력한 기본 환경
데스크탑 앱	GUI로 diff 확인, 터미널 불필요
VS Code / Cursor 확장	에디터 안에서 바로 사용
JetBrains 플러그인	IntelliJ, PyCharm 등 지원
웹 브라우저	claude.ai/code 에서 바로 실행

한 줄 요약

Claude Code = "내 프로젝트 폴더에 직접 접근해서 코드를 짜고, 테스트하고, 커밋까지 해주는 AI 개발자"

다음 섹션에서는 어떤 플랜으로 시작하면 좋은지 알아봅니다.

제품군 & 가격

Claude Code를 사용하는 방법과 요금제를 알아봅니다.

02. 제품군 & 가격

Claude Code를 사용하는 방법은 3가지입니다. 입문자라면 Max $100 플랜부터 시작하세요.

Claude Code를 쓰는 방법 3가지

방법 1. Claude.ai 구독 (Pro / Max) — 개인 입문자 추천

가장 간단한 방법입니다. Claude.ai에서 구독하면 Claude Code를 바로 사용할 수 있습니다. 토큰(사용량)을 일일이 신경 쓸 필요 없이 정해진 월정액만 냅니다.

방법 2. Anthropic API 직접 사용 — 개발자 / 자동화 목적

Anthropic Console에서 API 키를 발급받아 연결하는 방식입니다. 사용한 만큼 토큰(글자 수 단위)으로 과금됩니다. 자동화 파이프라인, CI/CD 연동 등에 적합합니다.

방법 3. 엔터프라이즈 클라우드 — 기업 보안 요건이 있는 팀

Amazon Bedrock, Google Vertex AI, Microsoft Foundry 등 기업용 클라우드를 통해 Claude Code를 사용합니다. 데이터가 회사 클라우드 안에 머뭅니다.

Pro vs Max 플랜 비교

아래 가격은 2025년 공식 기준입니다. 최신 가격은 claude.com/pricing에서 확인하세요.

	Pro	Max (5x)	Max (20x)
월 가격	$20	$100	$200
사용량 한도	기본	Pro의 5배	Pro의 20배
Claude Code 포함	포함	포함	포함
Claude.ai 웹 포함	포함	포함	포함
적합한 사용자	가끔 사용, 탐색 목적	Claude Code 주 사용자	헤비유저, 대규모 프로젝트

입문자 추천: Max $100

Claude Code를 본격적으로 사용하려면 Max $100 플랜을 권장합니다. 그 이유:

Pro($20)는 사용량 한도가 빠르게 차서 Claude Code를 집중적으로 쓰기 어렵습니다.
API 직접 사용은 토큰 과금 방식이라 예상치 못한 비용이 발생할 수 있습니다.
Max $100는 하루 평균 사용량 기준으로 대부분의 개인 개발자에게 충분합니다.

공식 문서에 따르면, API 사용자의 평균 비용은 개발자 1인당 하루 약 $6, 월 $100~$200 수준입니다 (사용 강도에 따라 차이 있음).

비용 구조 설명

구독 플랜 (Pro / Max)

월정액 결제 → 정해진 사용량 한도 내에서 자유롭게 사용
한도 초과 시 → 추가 응답 제한 (추가 과금 없음)

토큰 수를 신경 쓸 필요 없음
한도 도달 시 일정 시간 후 리셋

API 직접 사용

사용한 토큰만큼 과금 (입력 토큰 + 출력 토큰)
모델에 따라 단가 다름 (Sonnet < Opus)

/cost 명령어로 현재 세션 비용 확인 가능
자동화/팀 사용 시 Console에서 지출 한도 설정 가능

⚠️ 비용 주의사항

API 사용 시 주의할 점

⚠️ API 사용은 사용한 만큼 청구됩니다.

대형 프로젝트에서 장시간 작업하면 토큰이 빠르게 소모됩니다.
Agent Team(여러 AI를 동시에 실행) 기능은 토큰 소모가 약 7배 많습니다.
백그라운드 작업(대화 요약 등)에도 소량의 토큰이 사용됩니다.

비용 절감 팁

방법	설명
작업 사이에 `/clear` 실행	이전 대화 컨텍스트를 지워 토큰 절약
Sonnet 모델 우선 사용	Opus보다 저렴하고 대부분 작업에 충분
명확한 요청	"이 코드베이스 전체 개선해줘" 대신 특정 파일/함수 지정
MCP 서버 최소화	사용하지 않는 연결은 비활성화

어떤 플랜으로 시작할까?

처음 써보고 싶다       → Pro ($20) 로 체험
본격적으로 쓰고 싶다   → Max $100 (강력 추천)
팀/자동화 목적         → API 또는 엔터프라이즈
보안 요건이 있는 기업  → Bedrock / Vertex / Foundry

요금 페이지

최신 가격 및 플랜 비교: https://claude.com/pricing

설치 & 인증

Claude Code를 설치하고 인증하는 방법을 알아봅니다.

03. 설치 & 인증

터미널에서 명령어 하나로 설치, 브라우저에서 로그인하면 끝입니다.

설치 전 확인사항

지원 운영체제

OS	지원 버전
macOS	13.0 이상
Linux	Ubuntu 20.04+, Debian 10+, Alpine Linux 3.19+
Windows	Windows 10 (1809+) 또는 Windows Server 2019+

하드웨어 요구사항

RAM: 4GB 이상
인터넷 연결 필수

Node.js가 필요한가요?

아닙니다. Claude Code는 네이티브(Native) 설치 방식을 사용합니다. Node.js를 따로 설치할 필요가 없습니다.

⚠️ npm 설치는 deprecated(구식)입니다. 예전에는 npm install -g @anthropic-ai/claude-code로 설치했지만, 지금은 공식적으로 아래 방법을 권장합니다. npm 방식은 사용하지 마세요.

설치 방법

macOS / Linux / WSL (Windows Subsystem for Linux)

터미널을 열고 아래 명령어를 붙여넣으세요:

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

또는 Homebrew를 사용한다면:

brew install --cask claude-code

Windows

방법 1 — PowerShell 사용 (권장):

irm https://claude.ai/install.ps1 | iex

방법 2 — WinGet 사용:

winget install Anthropic.ClaudeCode

방법 3 — CMD 사용:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Windows에서 로컬 세션을 사용하려면 Git for Windows가 설치되어 있어야 합니다.

Alpine Linux 추가 패키지

apk add libgcc libstdc++ ripgrep

설치 후 인증 (로그인)

설치가 완료되면 터미널에서 아래 명령어를 실행하세요:

claude

처음 실행하면 브라우저가 자동으로 열리면서 OAuth 로그인 화면이 나타납니다. Claude.ai 계정(Pro 또는 Max 구독)으로 로그인하면 자동으로 인증이 완료됩니다.

인증 흐름 요약

터미널에서 claude 실행
       ↓
브라우저 자동 오픈 (OAuth 페이지)
       ↓
Claude.ai 계정으로 로그인
       ↓
터미널로 자동 복귀 → 인증 완료

자격 증명 보안

macOS: API 키와 OAuth 토큰은 **macOS Keychain(암호화 저장소)**에 안전하게 저장됩니다.
재로그인이 필요한 경우: claude 실행 후 /login 입력

첫 실행 확인

설치와 인증이 완료되었는지 확인하려면:

claude --version

버전 번호가 출력되면 정상 설치된 것입니다. 또는 설치 진단을 위해:

claude doctor

이 명령어로 설치 타입, 버전, 환경 상태를 한 번에 확인할 수 있습니다.

자동 업데이트

Claude Code는 자동으로 최신 버전으로 업데이트됩니다. 시작 시 업데이트를 확인하고 백그라운드에서 다운로드합니다. 다음 실행 시 새 버전이 적용됩니다.

수동으로 업데이트하려면:

claude update

흔한 설치 문제 & 해결법

문제 1: `curl: command not found` (curl이 없다는 오류)

원인: curl이 설치되어 있지 않은 경우 (드물지만 일부 Linux 환경).

해결법:

# Ubuntu/Debian
sudo apt-get install curl

# Alpine
apk add curl

이후 설치 명령어 다시 실행.

문제 2: `claude: command not found` (설치 후에도 명령어를 못 찾는 경우)

원인: 설치 경로가 셸의 PATH에 등록되지 않은 경우.

해결법:

# 현재 셸 세션에 PATH 즉시 반영
source ~/.bashrc
# 또는 zsh 사용자라면
source ~/.zshrc

그래도 안 되면 터미널을 완전히 닫고 다시 열기.

문제 3: Windows에서 Git이 없다는 오류

원인: 로컬 세션 실행에 Git이 필요합니다.

해결법: git-scm.com에서 Git for Windows 설치 후 재시도.

다음 단계

설치와 인증이 완료되었다면, 프로젝트 폴더로 이동해서 바로 시작해 보세요:

cd 내-프로젝트-폴더
claude

Claude Code가 프로젝트를 분석하고 무엇을 도와드릴지 기다립니다.

플러그인 설치

한국어 추천

gptaku_plugins 등 유용한 플러그인을 설치하고 활용합니다.

04. 플러그인 추천 설치

Claude Code의 기능을 확장하는 플러그인을 설치해봅시다.

플러그인이란?

Claude Code는 기본 기능만으로도 충분히 강력하지만, **플러그인(Plugin)**을 설치하면 더 많은 것을 할 수 있습니다.

플러그인은 쉽게 말하면 Claude Code에 추가 기능 꾸러미를 설치하는 것입니다. 스마트폰에 앱을 설치하듯, Claude Code에 필요한 기능을 플러그인으로 추가할 수 있습니다.

플러그인 하나에는 다음 요소들이 들어있을 수 있습니다:

구성 요소	설명
Skills (스킬)	`/플러그인명:명령어` 형태의 커스텀 명령어
Agents (에이전트)	특정 역할을 수행하는 AI 에이전트
Hooks (훅)	파일 저장, 명령 실행 시 자동으로 동작하는 이벤트 핸들러
MCP 서버	GitHub, Figma 등 외부 서비스 연동

공식 플러그인 마켓플레이스

Anthropic이 운영하는 공식 마켓플레이스(claude-plugins-official)는 Claude Code를 시작하면 자동으로 사용 가능한 상태입니다.

Claude Code 안에서 /plugin 을 입력하면 Discover 탭에서 바로 공식 플러그인들을 둘러볼 수 있습니다.

공식 마켓에서 플러그인 설치하기

/plugin install 플러그인이름@claude-plugins-official

공식 마켓에서 제공하는 주요 플러그인 카테고리

카테고리	대표 플러그인	설명
코드 인텔리전스	`typescript-lsp`, `pyright-lsp`	타입 오류 실시간 감지, 코드 탐색
외부 서비스 연동	`github`, `figma`, `notion`	외부 서비스를 Claude와 연결
개발 워크플로	`commit-commands`, `pr-review-toolkit`	Git 커밋, PR 리뷰 자동화
출력 스타일	`explanatory-output-style`	Claude 응답 방식 커스터마이징

gptaku_plugins — 한국 입문자 전용 플러그인 모음

GitHub: https://github.com/fivetaku/gptaku_plugins

gptaku_plugins는 한국의 Claude Code 입문자, 비개발자, 바이브코더를 위해 특별히 만들어진 플러그인 모음입니다. 어렵고 낯선 개발 개념들을 Claude가 더 친절하게 안내해주도록 설계되어 있습니다.

포함된 플러그인

플러그인 이름	역할	사용 예시
docs-guide	라이브러리 공식 문서 기반으로 정확한 답변 제공. Claude가 최신 공식 문서를 참고해 할루시네이션 없이 답변	`/docs-guide:explain React hooks`
바르다 깃선생 (git-teacher)	비개발자를 위한 Git 온보딩 가이드. "커밋이 뭐야?"부터 시작해서 실무 Git 워크플로우까지 단계별 안내	`/git-teacher:what-is-commit`
바선생 (vibe-sunsang)	바이브코더 전용 AI 멘토. 코드를 몰라도 아이디어를 제품으로 만들 수 있도록 격려하고 안내	`/vibe-sunsang:help`

설치 방법

1단계: 마켓플레이스 추가 및 플러그인 설치

Claude Code 안에서 다음 명령어를 입력하세요:

/plugin install https://github.com/fivetaku/gptaku_plugins

또는 마켓플레이스를 먼저 추가하고 설치할 수도 있습니다:

# 마켓플레이스 추가
/plugin marketplace add fivetaku/gptaku_plugins

# 이후 Discover 탭에서 원하는 플러그인 선택하여 설치
/plugin

2단계: 설치 확인

설치된 플러그인 목록을 확인하세요:

/plugin list

또는 /plugin 을 입력 후 Installed 탭으로 이동하면 설치된 플러그인 목록을 볼 수 있습니다.

3단계: 플러그인 사용해보기

설치가 완료되면 바로 사용할 수 있습니다:

# git-teacher 사용 예시
/git-teacher:what-is-commit

# docs-guide 사용 예시
/docs-guide:explain useState

# vibe-sunsang 멘토에게 도움 요청
/vibe-sunsang:help

플러그인 관리

명령어	설명
`/plugin`	플러그인 매니저 열기 (Discover/Installed/Marketplaces/Errors 탭)
`/plugin list`	설치된 플러그인 목록 확인
`/plugin disable 플러그인명`	플러그인 임시 비활성화
`/plugin enable 플러그인명`	비활성화된 플러그인 다시 활성화
`/plugin uninstall 플러그인명`	플러그인 완전 삭제

⭐ CC101이 도움이 됐다면 Star 부탁드려요!

이 가이드가 도움이 됐다면, GitHub에서 Star를 눌러주세요.

Star 하나가 이 가이드를 계속 발전시키는 큰 힘이 됩니다.

→ CC101 GitHub에서 Star 누르기

어렵지 않아요. 링크 클릭 후 오른쪽 상단의 ⭐ Star 버튼만 누르면 됩니다!

다음 단계

플러그인 설치를 완료했다면, Claude Code가 어떻게 작동하는지 핵심 개념을 이해해봅시다.

→ 05. 핵심 개념 이해하기

핵심 개념

Context, Tools, Permissions, Memory, Session 등 핵심 개념을 이해합니다.

05. 핵심 개념 이해하기

Claude Code가 어떻게 작동하는지 알면, 더 잘 사용할 수 있습니다.

Claude Code는 어떻게 작동하나요?

Claude Code는 단순한 챗봇이 아닙니다. 여러분이 일을 시키면, 스스로 계획을 세우고, 파일을 읽고, 코드를 수정하고, 결과를 확인하는 에이전트(Agent) 입니다.

이 과정을 에이전트 루프(Agentic Loop) 라고 합니다.

여러분의 지시
     ↓
1. 상황 파악 (Context 수집)
   - 파일 읽기, 코드 검색, 현재 상태 파악
     ↓
2. 행동 (Action)
   - 파일 수정, 명령어 실행, 웹 검색
     ↓
3. 결과 확인 (Verify)
   - 테스트 실행, 오류 확인, 다시 수정
     ↓
작업 완료 (또는 1로 돌아가서 반복)

예를 들어 "테스트가 실패하는 버그를 고쳐줘"라고 하면 Claude Code는:

테스트를 실행해서 어떤 오류인지 확인
관련 소스 파일을 찾아서 읽음
코드를 수정
다시 테스트를 실행해서 통과하는지 확인

이 모든 과정을 자동으로 수행합니다.

핵심 개념 5가지

1. Context (컨텍스트) — Claude의 작업 기억

컨텍스트는 Claude Code가 현재 기억하고 있는 모든 내용입니다. 대화 내용, 읽은 파일, 실행한 명령어 결과, CLAUDE.md 지시사항 등이 모두 컨텍스트에 담깁니다.

컨텍스트에는 토큰 한계가 있습니다. 대화가 길어지거나 큰 파일을 많이 읽으면 컨텍스트가 가득 찰 수 있습니다. 이 경우 Claude Code가 자동으로 오래된 내용을 정리합니다.

# 컨텍스트 현황 확인
/context

# 대화 압축 (오래된 내용 요약)
/compact

# 특정 주제에 집중해서 압축
/compact API 변경 사항에 집중해서 압축해줘

팁: 자주 참조해야 할 중요한 규칙이나 정보는 CLAUDE.md에 써두면, 매번 컨텍스트를 차지하지 않고도 Claude가 기억합니다.

2. Tools (도구) — Claude가 실제로 할 수 있는 일

Claude Code는 대화만 하는 게 아닙니다. 실제로 여러 **도구(Tools)**를 사용해서 작업을 수행합니다.

도구 종류	Claude가 할 수 있는 일
파일 작업	파일 읽기, 코드 편집, 새 파일 생성, 파일 이름 변경
검색	파일 패턴으로 찾기, 정규식으로 내용 검색, 코드베이스 탐색
실행	셸 명령어 실행, 서버 시작, 테스트 실행, Git 사용
웹	웹 검색, 공식 문서 조회, 오류 메시지 검색
코드 분석	편집 후 타입 오류 감지, 정의로 이동, 참조 찾기

3. Permissions (권한) — 무엇을 허용할지 설정

Claude Code는 강력한 도구인 만큼, 무엇을 허용할지 직접 제어할 수 있습니다.

파일 읽기는 기본적으로 허용되지만, 파일 수정이나 셸 명령어 실행은 여러분의 확인을 요청합니다.

권한 규칙은 크게 세 가지입니다:

규칙	설명
Allow (허용)	묻지 않고 자동으로 실행
Ask (확인 요청)	실행 전에 승인 여부를 물어봄
Deny (거부)	절대 실행하지 않음

# 권한 설정 보기 및 관리
/permissions

우선순위: Deny > Ask > Allow 순으로 적용됩니다. 거부 규칙이 항상 최우선입니다.

4. Memory (메모리) — CLAUDE.md로 프로젝트 기억시키기

Claude Code는 세션이 끝나면 대화 내용을 기억하지 못합니다. 하지만 CLAUDE.md 파일을 만들어두면, 매 세션마다 자동으로 읽어서 프로젝트 맥락을 유지합니다.

CLAUDE.md는 Claude에게 주는 지시서라고 생각하면 됩니다.

파일 위치	적용 범위
`./CLAUDE.md`	현재 프로젝트에만 적용 (팀 공유 가능)
`~/.claude/CLAUDE.md`	내 모든 프로젝트에 적용 (전역 설정)
`./CLAUDE.local.md`	나만의 프로젝트별 설정 (git에 올라가지 않음)

CLAUDE.md에 대한 자세한 내용은 06. CLAUDE.md 완전 정복 에서 다룹니다.

5. Session (세션) — 대화의 시작과 끝

세션은 Claude Code를 시작해서 종료하기까지의 하나의 작업 단위입니다.

새 세션을 시작하면 이전 대화 내용은 없어집니다 (CLAUDE.md는 유지)
세션 중에 한 작업들은 저장됩니다

# 가장 최근 세션 이어서 시작
claude --continue

# 이전 세션 목록에서 선택해서 재개
claude --resume

# 다른 방향을 시도해보기 위해 세션 복사 (포크)
claude --continue --fork-session

"왜 가끔 멈추거나 확인을 요청하나요?"

Claude Code가 작업 중에 멈추고 확인을 요청하는 건 의도된 안전 장치입니다.

파일을 수정하거나 명령어를 실행하기 전에, 여러분이 의도한 것인지 확인하는 것입니다. 특히 되돌리기 어려운 작업(파일 삭제, 배포 등)일수록 중요합니다.

초보자가 알아야 할 권한 모드 3가지

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

모드	동작 방식	언제 쓰나요?
Default (기본 모드)	파일 수정과 셸 명령어 실행 전에 확인을 요청	처음 사용하거나 중요한 작업을 할 때
Auto-Accept (자동 수락)	파일 수정은 자동으로 허용, 셸 명령어는 여전히 확인 요청	빠르게 코딩 작업을 진행할 때
Plan Mode (계획 모드)	파일을 읽고 분석만 하고, 아무것도 수정하지 않음	먼저 계획을 검토하고 싶을 때

모드 전환 방법

# 터미널에서 Shift+Tab을 누르면 모드가 순환됩니다
# Default → Auto-Accept → Plan Mode → Default → ...

# 또는 Plan Mode로 바로 진입
/plan

모드 비교 예시

"모든 JavaScript 파일에서 console.log를 삭제해줘"라고 했을 때:

Default 모드:
  → 각 파일 수정 전마다 "이 파일을 수정해도 될까요?" 확인

Auto-Accept 모드:
  → 파일은 자동으로 수정, 명령어(예: git commit)는 확인 요청

Plan Mode:
  → "어떤 파일의 몇 번째 줄을 수정할 예정입니다"만 보여주고 실제 수정은 안 함

추천: 처음에는 Default 모드로 시작해서 Claude Code가 무엇을 하는지 파악하고, 익숙해지면 Auto-Accept 모드로 전환하세요.

체크포인트: 실수해도 되돌릴 수 있어요

Claude Code는 파일을 수정하기 전에 자동으로 스냅샷을 저장합니다.

실수로 잘못 수정됐다면:

Esc 키를 두 번 연속으로 눌러서 이전 상태로 되돌리기
또는 Claude에게 "방금 한 것 취소해줘"라고 요청

다음 단계

Claude Code의 장기 기억인 CLAUDE.md를 마스터해봅시다.

→ 06. CLAUDE.md 완전 정복

CLAUDE.md 완전 정복

핵심

Claude의 장기 기억, CLAUDE.md 파일 작성법과 활용법을 마스터합니다.

06. CLAUDE.md 완전 정복

Claude Code의 장기 기억을 설정하는 가장 중요한 파일, CLAUDE.md를 마스터해봅시다.

CLAUDE.md가 뭔가요?

Claude Code는 세션이 끝나면 대화 내용을 잊어버립니다. 다음에 다시 시작하면 처음 만난 사이처럼 아무것도 모릅니다.

CLAUDE.md는 이 문제를 해결합니다.

Claude Code를 시작할 때마다 CLAUDE.md 파일을 자동으로 읽어서, 프로젝트에 대한 맥락과 규칙을 기억한 채로 작업을 시작합니다.

CLAUDE.md는 Claude에게 주는 지시서이자 프로젝트 설명서입니다.

사람: "이 프로젝트는 Next.js로 만들었고, TypeScript를 써야 해.
       탭 대신 스페이스 2칸을 사용하고, 한국어로 커밋 메시지를 써줘."

→ 이걸 매번 말하는 대신, CLAUDE.md에 한 번 써두면 영원히 기억합니다.

어디에 만드나요?

CLAUDE.md 파일의 위치에 따라 적용 범위가 달라집니다.

파일 위치	적용 범위	팀 공유 여부
`./CLAUDE.md`	현재 프로젝트	✅ Git으로 팀 공유 가능
`./.claude/CLAUDE.md`	현재 프로젝트 (숨김 폴더)	✅ Git으로 팀 공유 가능
`./CLAUDE.local.md`	현재 프로젝트 (나만)	❌ .gitignore에 자동 추가
`~/.claude/CLAUDE.md`	내 모든 프로젝트 (전역)	❌ 나만 적용

가장 일반적인 위치: 프로젝트 루트 디렉토리의 CLAUDE.md

# 프로젝트 폴더에서 CLAUDE.md 생성
touch CLAUDE.md

# 또는 Claude Code가 자동으로 만들어주게 하기
/init

/init 명령어를 실행하면 Claude Code가 현재 프로젝트를 분석해서 CLAUDE.md 초안을 자동으로 생성해줍니다.

무엇을 써야 하나요?

CLAUDE.md에 정해진 형식은 없습니다. 마크다운으로 자유롭게 작성하면 됩니다. 다음 항목들을 포함하면 특히 효과적입니다.

필수 항목

1. 프로젝트 설명

Claude가 이 프로젝트가 무엇인지 파악할 수 있도록 짧게 설명합니다.

## 프로젝트 개요
이 프로젝트는 소상공인을 위한 재고 관리 웹앱입니다.
Next.js 14 + TypeScript + Supabase로 구성되어 있습니다.

2. 기술 스택

어떤 언어, 프레임워크, 라이브러리를 쓰는지 명시합니다.

## 기술 스택
- **프론트엔드**: Next.js 14 (App Router), TypeScript, Tailwind CSS
- **백엔드**: Next.js API Routes
- **데이터베이스**: Supabase (PostgreSQL)
- **패키지 매니저**: pnpm (npm 사용 금지)

3. 코딩 스타일 / 규칙

코드 스타일, 네이밍 규칙, 주석 언어 등을 지정합니다.

## 코딩 규칙
- 들여쓰기: 스페이스 2칸 (탭 사용 금지)
- 따옴표: 작은따옴표('') 사용
- 컴포넌트 파일명: PascalCase (예: UserCard.tsx)
- 함수명: camelCase (예: getUserData)
- 주석은 한국어로 작성
- `any` 타입 사용 금지, 항상 명시적 타입 사용

4. 하지 말아야 할 것들 (금지 사항)

실수를 방지하기 위해 명시적으로 금지 사항을 적어두면 효과적입니다.

## 절대 하지 말 것
- `console.log` 프로덕션 코드에 남기지 말 것
- `npm` 대신 반드시 `pnpm` 사용
- `.env` 파일에 있는 키를 코드에 하드코딩하지 말 것
- `any` 타입 사용 금지
- `pages/` 디렉토리 방식 사용 금지 (App Router만 사용)

5. 자주 쓰는 명령어

매번 명령어를 검색하는 수고를 덜 수 있습니다.

## 자주 쓰는 명령어
- 개발 서버 실행: `pnpm dev`
- 빌드: `pnpm build`
- 테스트: `pnpm test`
- 린트: `pnpm lint`
- 타입 체크: `pnpm type-check`
- DB 마이그레이션: `pnpm db:migrate`

실제 예시: Next.js + TypeScript 프로젝트용 CLAUDE.md 템플릿

아래는 한국 개발환경에 맞게 작성된 실용적인 템플릿입니다. 복사해서 바로 사용하세요.

# 프로젝트 지침

## 프로젝트 개요
[여기에 프로젝트 설명을 1-2줄로 작성하세요]

예시: 소상공인을 위한 재고 관리 SaaS 서비스.
Next.js 14 App Router + TypeScript + Supabase 기반.

---

## 기술 스택
- **프레임워크**: Next.js 14 (App Router)
- **언어**: TypeScript (strict 모드)
- **스타일**: Tailwind CSS
- **DB/백엔드**: Supabase
- **패키지 매니저**: pnpm
- **배포**: Vercel

---

## 디렉토리 구조
\`\`\`
src/
├── app/          # Next.js App Router 페이지
├── components/   # 재사용 가능한 UI 컴포넌트
│   ├── ui/       # 기본 UI 요소 (Button, Input 등)
│   └── features/ # 기능별 컴포넌트
├── lib/          # 유틸리티, Supabase 클라이언트 등
└── types/        # TypeScript 타입 정의
\`\`\`

---

## 코딩 규칙

### 스타일
- 들여쓰기: 스페이스 2칸
- 따옴표: 작은따옴표('')
- 세미콜론: 사용 (항상)
- 줄 끝 공백: 허용 안 함

### 네이밍
- 컴포넌트: PascalCase (UserCard.tsx)
- 함수/변수: camelCase (getUserData)
- 상수: UPPER_SNAKE_CASE (MAX_RETRY_COUNT)
- 타입/인터페이스: PascalCase (UserProfile)

### TypeScript
- `any` 타입 사용 금지
- 모든 함수 반환 타입 명시
- Props 타입은 인터페이스로 정의

---

## 자주 쓰는 명령어
\`\`\`bash
pnpm dev          # 개발 서버 (localhost:3000)
pnpm build        # 프로덕션 빌드
pnpm test         # 테스트 실행
pnpm lint         # ESLint 검사
pnpm type-check   # TypeScript 타입 검사
\`\`\`

---

## 절대 하지 말 것
- `npm` 또는 `yarn` 사용 (반드시 `pnpm` 사용)
- `any` 타입 사용
- `pages/` 디렉토리 방식 사용 (App Router만)
- 환경 변수를 코드에 하드코딩
- `console.log`를 프로덕션 코드에 남기기

---

## Git 커밋 규칙
- 한국어로 커밋 메시지 작성
- 형식: `타입: 변경 내용`
- 타입 예시: feat(기능), fix(수정), docs(문서), style(스타일), refactor(리팩토링)
- 예시: `feat: 사용자 로그인 페이지 추가`

전역 메모리: 모든 프로젝트에 적용하기

~/.claude/CLAUDE.md 파일을 만들면, 내 모든 프로젝트에서 공통으로 적용되는 규칙을 설정할 수 있습니다.

# 전역 CLAUDE.md 편집
nano ~/.claude/CLAUDE.md

전역 CLAUDE.md에 넣기 좋은 내용:

# 전역 설정 (모든 프로젝트 공통)

## 내 개인 선호
- 설명은 항상 한국어로 해줘
- 코드 변경 전에 무엇을 할지 먼저 설명해줘
- 중요한 변경사항은 실행 전에 한 번 더 확인해줘

## 코딩 스타일 (공통)
- 함수는 가능하면 짧게 (20줄 이하)
- 변수명은 의미가 명확하게
- 주석보다는 코드 자체가 읽기 쉽도록

메모리 우선순위

여러 CLAUDE.md 파일이 있을 때, 더 구체적인 파일이 우선합니다.

우선순위 (높음 → 낮음):
1. CLAUDE.local.md (나만의 프로젝트 설정)
2. ./CLAUDE.md (프로젝트 설정)
3. ~/.claude/CLAUDE.md (전역 설정)
4. 조직 관리 CLAUDE.md (회사 설정)

예를 들어, 전역 설정에서 "스페이스 2칸"으로 설정했더라도, 프로젝트의 CLAUDE.md에서 "탭 사용"으로 설정하면 프로젝트 설정이 우선 적용됩니다.

유용한 팁

`/memory` 명령어 활용

세션 중에 CLAUDE.md를 직접 편집하고 싶다면:

/memory

파일 선택기가 열려서 CLAUDE.md를 바로 편집할 수 있습니다.

파일 가져오기 (Import)

CLAUDE.md에서 다른 파일을 참조할 수 있습니다:

# 프로젝트 지침

프로젝트 개요는 @README.md 를 참고하세요.
사용 가능한 npm 스크립트는 @package.json 을 참고하세요.

## 추가 규칙
- Git 워크플로우: @docs/git-guide.md

처음 시작할 때는 CLAUDE.md부터!

새 프로젝트를 시작한다면, 첫 번째 작업으로 CLAUDE.md를 만드세요.

# 프로젝트 시작 시 Claude에게 CLAUDE.md 자동 생성 요청
/init

또는 직접 Claude에게 부탁할 수도 있습니다:

"이 프로젝트는 Next.js 14 + TypeScript + Tailwind로 만들 거야.
 한국어 주석과 커밋 메시지를 사용하고, pnpm을 패키지 매니저로 써.
 이 내용을 바탕으로 CLAUDE.md 파일을 만들어줘."

정리: CLAUDE.md 핵심 요약

항목	내용
역할	Claude의 장기 기억 / 프로젝트 지시서
위치	프로젝트 루트의 `CLAUDE.md`
전역 설정	`~/.claude/CLAUDE.md`
자동 생성	`/init` 명령어 사용
편집	`/memory` 명령어 또는 일반 텍스트 편집기
형식	자유로운 마크다운

CLAUDE.md 하나로 매번 설명하는 수고를 없애고, Claude Code를 진짜 팀원처럼 만들어보세요.

다음 단계

기본 설정을 마쳤습니다. 이제 Claude Code를 실전에서 활용해봅시다!

→ 07. 실전 활용 예시 (준비 중)

명령어 모음

CLI 명령어, 슬래시 명령어, 키보드 단축키를 한눈에 정리합니다.

07. 명령어 모음

Claude Code를 쓸 때 알아야 할 명령어들을 한눈에 정리했습니다.

명령어 세 가지 종류

Claude Code의 명령어는 크게 세 가지로 나뉩니다.

종류	어디서 입력?	예시
CLI 명령어	터미널 (Claude Code 밖)	`claude`, `claude --version`
슬래시 명령어	대화 중 (Claude Code 안)	`/help`, `/compact`
키보드 단축키	대화 중	`Ctrl+C`, `Shift+Enter`

CLI 명령어 (터미널에서 입력)

Claude Code를 시작하거나 제어하는 명령어입니다. 터미널에서 입력합니다.

기본 실행 명령어

명령어	설명	예시
`claude`	대화형 모드 시작	`claude`
`claude "질문"`	바로 질문하며 시작	`claude "이 프로젝트 설명해줘"`
`claude -p "질문"`	답변만 출력하고 종료 (자동화에 유용)	`claude -p "이 함수 설명해줘"`
`claude -c`	가장 최근 대화 이어서 시작	`claude -c`
`claude --version` 또는 `claude -v`	설치된 버전 확인	`claude -v`
`claude --help`	도움말 보기	`claude --help`
`claude update`	최신 버전으로 업데이트	`claude update`

모델 지정 실행

# 특정 모델로 시작
claude --model claude-opus-4-5

# 또는 짧게
claude --model opus
claude --model sonnet
claude --model haiku

유용한 시작 옵션

# Plan Mode로 시작 (파일 수정 없이 계획만)
claude --permission-mode plan

# 세션 이름으로 이어서 시작
claude --resume 세션이름

# 이전 대화 목록에서 선택해서 이어서 시작
claude --resume

팁: 처음엔 그냥 claude만 입력해서 시작하면 됩니다. 나머지는 필요할 때 배워도 늦지 않습니다.

슬래시 명령어 (대화 중 입력)

Claude Code와 대화하는 도중에 /로 시작하는 명령어를 입력하면 특별한 기능을 사용할 수 있습니다.

자주 쓰는 슬래시 명령어

명령어	설명
`/help`	사용 가능한 명령어 전체 목록 보기
`/compact`	대화 내용 압축 (긴 세션에서 필수!)
`/clear`	대화 초기화 (완전히 새로 시작)
`/cost`	현재 세션에서 사용한 토큰 비용 확인
`/model`	사용 중인 AI 모델 변경
`/permissions`	권한 설정 확인 및 관리
`/memory`	CLAUDE.md 메모리 파일 편집
`/quit` 또는 `/exit`	Claude Code 종료
`/plan`	Plan Mode 진입
`/init`	프로젝트에 CLAUDE.md 파일 생성
`/doctor`	설치 상태 점검
`/stats`	사용량 통계 보기 (구독 사용자용)
`/vim`	Vim 편집 모드 켜기/끄기
`/theme`	색상 테마 변경

슬래시 명령어 사용법

> /compact
→ 대화 내용을 요약해서 컨텍스트를 줄여줍니다

> /compact 코드 변경 사항 위주로 정리해줘
→ 압축 방향을 직접 지정할 수 있습니다

> /model
→ 모델 선택 화면이 나타납니다

팁: 대화창에서 /만 입력하면 사용 가능한 명령어 목록이 자동완성으로 나타납니다.

키보드 단축키

대화 도중 손가락 몇 개로 빠르게 제어할 수 있습니다.

핵심 단축키

단축키	설명
`Ctrl+C`	현재 작업 취소 (Claude가 뭔가 하는 도중에 멈추고 싶을 때)
`Ctrl+D`	Claude Code 종료
`Ctrl+L`	터미널 화면 지우기 (대화 내용은 유지됨)
`Ctrl+R`	이전에 입력한 명령어 검색
`Ctrl+G`	현재 입력 중인 내용을 외부 텍스트 에디터에서 편집
`Ctrl+T`	작업 목록 보기/숨기기

입력 관련 단축키

단축키	설명
`Shift+Enter`	줄바꿈 (긴 지시사항 여러 줄로 입력할 때)
`Option+Enter` (macOS)	줄바꿈 (macOS 기본)
`\` + `Enter`	줄바꿈 (모든 터미널에서 작동)
`↑` / `↓` 화살표	이전/다음 명령어 탐색
`Esc` + `Esc` (두 번)	대화 되감기 (이전 상태로 복원)

모드 전환 단축키

단축키	설명
`Shift+Tab`	Plan Mode ↔ 일반 모드 전환
`Option+P` (macOS) / `Alt+P`	모델 변경
`Option+T` (macOS) / `Alt+T`	확장 사고 모드 켜기/끄기

초보자가 자주 쓰는 명령어 TOP 5

막 시작했다면 이 다섯 개만 외워도 충분합니다.

1. `/compact` — 가장 중요한 명령어

> /compact

대화가 길어지면 Claude가 느려지거나 오래된 내용을 잊어버립니다. 이럴 때 /compact를 입력하면 대화를 압축해서 속도를 회복합니다. 긴 작업 중간중간에 습관적으로 사용하세요.

2. `Ctrl+C` — 멈추고 싶을 때

Claude가 엉뚱한 방향으로 가고 있을 때, 또는 실수로 위험한 명령을 허가했을 때 즉시 멈춥니다.

3. `/clear` — 새로 시작할 때

> /clear

완전히 다른 주제로 넘어갈 때 사용합니다. 이전 대화 내용이 모두 지워집니다.

4. `Shift+Enter` — 긴 지시사항 입력

한 줄로 다 쓰기 어려운 긴 요청은 Shift+Enter로 줄바꿈하면서 입력하세요.

(Shift+Enter로 여러 줄 입력 예시)
로그인 페이지를 만들어줘.
- 이메일과 비밀번호 필드
- 비밀번호 보기/숨기기 버튼
- 로그인 버튼 (로딩 상태 포함)

5. `/cost` — 비용 확인

> /cost

현재 세션에서 얼마나 썼는지 확인합니다. (API 키 사용자용, 구독 사용자는 /stats 사용)

빠른 참고표

터미널 입력:
  claude              → 시작
  claude -v           → 버전 확인
  claude --help       → 도움말

대화 중 입력:
  /help               → 전체 명령어 목록
  /compact            → 대화 압축 (자주 쓰기!)
  /clear              → 대화 초기화
  /cost               → 비용 확인
  /model              → 모델 변경
  /quit               → 종료

키보드 단축키:
  Ctrl+C              → 작업 취소
  Ctrl+D              → 종료
  Shift+Enter         → 줄바꿈
  ↑↓ 화살표           → 이전 명령어 탐색
  Esc Esc             → 이전 상태로 되감기

초보자 워크플로우

첫 세션부터 효과적인 프롬프트 작성까지 실전 워크플로우를 배웁니다.

08. 초보자 워크플로우

처음 Claude Code를 쓸 때 어떻게 시작하고, 어떻게 작업하면 좋은지 단계별로 안내합니다.

첫 세션 플로우 (Step-by-Step)

처음이라면 이 순서대로 따라해보세요.

Step 1. 프로젝트 폴더로 이동

cd 내프로젝트

Claude Code는 현재 폴더를 기준으로 파일을 읽고 수정합니다. 반드시 작업할 프로젝트 폴더로 먼저 이동하세요.

폴더가 없다면 mkdir 내프로젝트 && cd 내프로젝트로 만들어도 됩니다.

Step 2. Claude Code 시작

claude

터미널에 claude를 입력하고 Enter를 누르면 대화형 모드가 시작됩니다.

Step 3. 프로젝트 파악시키기 (강력 추천)

처음 시작할 때 Claude에게 프로젝트를 파악하게 하거나, CLAUDE.md 파일을 만들어 달라고 요청하세요.

> 이 프로젝트 전체를 파악하고 CLAUDE.md 파일을 만들어줘

또는 기존 프로젝트라면:

> 이 코드베이스 구조를 설명해줘

CLAUDE.md가 중요한 이유: 이 파일에 프로젝트 규칙, 기술 스택, 주의사항을 적어두면 Claude가 매번 물어보지 않아도 됩니다. 팀이 있다면 git에 커밋해서 공유하세요.

Step 4. 작업 지시

원하는 작업을 자연어로 지시합니다.

> 로그인 기능을 만들어줘
> 이 코드에서 버그를 찾아줘
> README.md를 한글로 번역해줘

Step 5. 결과 확인 & 피드백

Claude가 파일을 수정하면 변경 내용을 보여줍니다. 마음에 들지 않으면 바로 피드백하세요.

> 좋아, 근데 에러 메시지는 한글로 바꿔줘
> 이 부분은 다르게 해줘 — [설명]

Step 6. 세션 종료

> /quit

또는 Ctrl+D를 누르면 종료됩니다.

효과적인 프롬프트 쓰는 법

구체적으로 말할수록 좋은 결과가 나옵니다

나쁜 예 (모호함)	좋은 예 (구체적)
"코드 고쳐줘"	"login.js의 42번 줄에서 발생하는 TypeError 수정해줘"
"기능 추가해줘"	"사용자가 비밀번호를 잊었을 때 이메일로 재설정 링크를 보내는 기능 추가해줘"
"더 좋게 만들어줘"	"이 함수의 성능을 개선해줘. 현재 1000개 데이터에서 3초 걸리는데 1초 이내로 줄여야 해"
"테스트 만들어줘"	"auth.js의 login 함수에 대한 단위 테스트를 만들어줘. 성공/실패/이메일 형식 오류 케이스 포함"

한 번에 하나씩 요청하기

여러 가지를 한꺼번에 요청하면 Claude가 중간에 방향을 잃을 수 있습니다.

# 비추천
> 로그인 만들고, 회원가입도 추가하고, 비밀번호 찾기도 만들고,
  이메일 인증도 넣고, 소셜 로그인도 추가해줘

# 추천
> 먼저 이메일/비밀번호 로그인 기능만 만들어줘
(완료 후)
> 이제 회원가입 기능 추가해줘

결과물 형태를 명시하기

> 이 코드를 설명해줘           → 설명문으로 답변
> 이 코드를 파일로 저장해줘     → 파일로 저장
> 이 코드를 개선해서 덮어써줘   → 파일 직접 수정
> 버그 목록을 표로 정리해줘     → 표 형식으로 답변

@ 기호로 파일 지정하기

> @src/auth/login.js 이 파일에서 버그 찾아줘
> @README.md 를 보고 프로젝트 구조 파악해줘

일반적인 사용 사례 예시

새 기능 추가

> 사용자 프로필 페이지를 만들어줘.
  - 닉네임, 이메일, 가입일 표시
  - 프로필 사진 업로드 가능
  - 닉네임 수정 기능

버그 수정

> npm test 실행하면 아래 에러가 나는데 고쳐줘:
  TypeError: Cannot read property 'id' of undefined
  at UserService.getUser (src/services/user.js:45)

코드 리뷰 요청

> @src/payment/ 폴더의 코드를 리뷰해줘.
  보안 취약점과 개선할 점을 알려줘

코드 설명

> @src/utils/tokenizer.js 이 파일이 뭘 하는 건지 쉽게 설명해줘

테스트 코드 작성

> @src/services/auth.js 의 모든 함수에 대한 테스트를 만들어줘.
  기존 테스트 스타일은 @tests/services/user.test.js 를 참고해

문서화

> @src/api/ 폴더의 모든 함수에 JSDoc 주석 추가해줘

Plan Mode 활용 팁

Plan Mode란? Claude가 파일을 수정하지 않고, 계획만 세우는 모드입니다. 위험한 작업을 하기 전에 먼저 계획을 검토할 수 있습니다.

Plan Mode 켜는 방법

Shift+Tab 두 번 누르기
또는
> /plan

언제 Plan Mode를 쓰나?

여러 파일을 동시에 수정해야 할 때
데이터베이스 마이그레이션처럼 되돌리기 어려운 작업
처음 보는 코드베이스를 수정하기 전
아키텍처 변경처럼 큰 작업

Plan Mode 사용 예시

# Plan Mode로 시작
claude --permission-mode plan

# 또는 대화 중에 전환
> Shift+Tab (두 번)

# 계획 수립 요청
> 인증 시스템을 JWT에서 OAuth2로 마이그레이션하는 계획을 세워줘

# Claude가 계획을 보여주면 검토
# 괜찮으면 일반 모드로 전환 후 실행

작업 전 git commit 습관

Claude Code가 파일을 수정하기 전에 현재 상태를 git에 저장해두면, 실수해도 쉽게 되돌릴 수 있습니다.

git add .
git commit -m "Claude Code 작업 전 백업"

이후 Claude가 수정한 내용이 마음에 들지 않으면:

git diff          # 변경된 내용 확인
git checkout .    # 모든 변경 취소 (주의!)

또는 Claude Code 안에서 Esc + Esc를 눌러 이전 상태로 되감기할 수도 있습니다.

⚠️ 절대 하지 말아야 할 것들

민감 정보 입력 금지

# 절대 금지
> 내 AWS 액세스 키는 AKIAXXXXXXXX 이고...
> DB 비밀번호는 mypassword123 인데...
> 내 개인 SSH 키는 -----BEGIN RSA...

API 키, 비밀번호, 개인 인증서 등은 절대 대화창에 직접 입력하지 마세요. 환경변수나 .env 파일을 사용하세요.

권한 요청 무분별 허용 금지

Claude가 sudo 명령이나 시스템 파일 수정 권한을 요청할 때, 이유를 먼저 파악하세요.

# Claude가 이런 권한을 요청하면 이유를 먼저 물어보기
> 왜 sudo가 필요해? 다른 방법은 없어?

`--dangerously-skip-permissions` 사용 주의

이 옵션은 모든 권한 확인을 건너뜁니다. 격리된 테스트 환경(컨테이너 등)이 아니면 사용하지 마세요.

중요한 작업 전 백업 없이 진행 금지

대규모 리팩토링이나 데이터베이스 마이그레이션 전에는 반드시 git commit이나 백업을 먼저 하세요.

세션 관리 팁

긴 작업은 이름을 붙여 저장

> /rename auth-refactor

나중에 이어서 할 때:

claude --resume auth-refactor

컨텍스트가 길어지면 압축

작업이 길어지면 Claude의 응답이 느려집니다. 주기적으로:

> /compact

한 줄 요약

구체적으로 지시하고 → 한 번에 하나씩 요청하고 → 결과를 확인하고 → 피드백을 반복하세요.

다음 섹션에서는 자주 하는 실수와 해결법을 알아봅니다.

자주 하는 실수 & 해결법

초보자가 자주 겪는 10가지 문제와 해결 방법을 알아봅니다.

09. 자주 하는 실수 & 해결법

초보자가 Claude Code를 쓰면서 자주 겪는 문제 10가지를 Q&A 형식으로 정리했습니다.

Q1. `claude` 명령어를 못 찾는다고 한다 (command not found)

증상

$ claude
zsh: command not found: claude

원인 & 해결법

설치는 됐지만 터미널이 claude 명령어 위치를 모르는 상황입니다.

방법 1: 네이티브 설치 사용 (가장 확실)

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

설치 후 터미널을 완전히 닫고 새로 열어보세요.

방법 2: PATH 확인

# claude가 어디 설치됐는지 확인
which claude

# PATH 확인
echo $PATH

~/.local/bin이 PATH에 없으면 shell 설정 파일(.zshrc 또는 .bashrc)에 추가:

export PATH="$HOME/.local/bin:$PATH"

추가 후 source ~/.zshrc 실행.

방법 3: 설치 상태 점검

claude doctor

Q2. 로그인이 안 된다

증상

브라우저가 열리지 않음
인증 화면에서 멈춤
로그인 후에도 인증 오류

해결법

브라우저 팝업이 안 열릴 때

claude 실행 후 c를 눌러 인증 URL을 복사한 뒤, 브라우저에 직접 붙여넣기 하세요.

로그아웃 후 재인증

# Claude Code 안에서
> /logout

# 또는 인증 파일 직접 삭제
rm -rf ~/.config/claude-code/auth.json
claude

여전히 안 된다면

# 모든 설정 초기화 후 재시작
rm ~/.claude.json
rm -rf ~/.claude/
claude

주의: 이렇게 하면 모든 설정과 세션 기록이 삭제됩니다.

Q3. 너무 느리다 / 응답이 늦다

원인

대화가 길어질수록 Claude가 처리해야 할 내용(컨텍스트)이 쌓여서 느려집니다. 이는 정상적인 동작입니다.

해결법

방법 1: /compact로 컨텍스트 정리 (가장 효과적)

> /compact

대화 내용을 압축해서 속도를 회복합니다.

방법 2: /clear로 초기화

완전히 새로 시작해도 되는 경우:

> /clear

방법 3: 더 빠른 모델로 변경

복잡한 작업이 아니라면 Haiku나 Sonnet이 Opus보다 훨씬 빠릅니다.

> /model

모델 선택 화면에서 변경하세요.

방법 4: MCP 서버 줄이기

불필요한 MCP 서버가 많으면 느려질 수 있습니다.

> /mcp

사용하지 않는 서버를 비활성화하세요.

Q4. 내가 원하는 대로 안 고쳐준다

원인

지시가 모호하거나, Claude가 프로젝트 맥락을 모르거나, 같은 말을 계속 반복해서 Claude가 혼란스러운 경우입니다.

해결법

방법 1: 더 구체적으로 지시하기

# 모호한 지시
> 코드 개선해줘

# 구체적인 지시
> auth.js의 login 함수에서 이메일 유효성 검사가 빠져있어.
  정규식으로 이메일 형식 확인하는 코드를 42번 줄 다음에 추가해줘

방법 2: CLAUDE.md에 규칙 추가

자주 반복되는 요구사항은 프로젝트 규칙으로 저장하세요.

> /memory

또는 CLAUDE.md 파일에 직접 추가:

# 코드 스타일
- 에러 메시지는 항상 한글로 작성
- 함수마다 JSDoc 주석 필수
- var 사용 금지, const/let만 사용

방법 3: 같은 실수가 두 번 반복되면 초기화

> /clear

새로 시작해서 더 명확한 지시로 다시 요청하세요.

Q5. 파일을 수정했는데 실수인 것 같다

해결법

방법 1: Claude Code 안에서 되감기 (가장 빠름)

Esc 키를 두 번 연속으로 누르기
또는
> /rewind

이전 상태로 대화와 코드를 함께 되돌립니다.

방법 2: git으로 복구

# 변경된 내용 확인
git diff

# 특정 파일만 되돌리기
git checkout -- src/auth/login.js

# 모든 변경 취소
git checkout .

방법 3: 작업 전 git commit 습관 들이기

Claude Code로 큰 작업을 시작하기 전에 항상:

git add .
git commit -m "작업 전 백업 $(date +%Y%m%d-%H%M)"

Q6. 갑자기 비용이 많이 나왔다

원인

대화가 너무 길어짐 (컨텍스트가 클수록 토큰 소모 증가)
파일이 많은 프로젝트를 전체 분석 요청
Opus 모델을 계속 사용
에이전트 팀 기능 사용

해결법

현재 비용 확인

> /cost

API 사용자용. 구독 사용자는 /stats로 사용량 확인.

비용 줄이는 방법

/compact 자주 사용해서 컨텍스트 관리
단순 작업은 Sonnet이나 Haiku 사용 (/model로 변경)
큰 파일/폴더 전체를 맥락 없이 읽히지 않기
관련 없는 작업 사이에는 /clear로 초기화

예산 한도 설정 (자동화 사용 시)

claude -p --max-budget-usd 1.00 "질문"

Q7. 권한 요청이 너무 많이 뜬다

상황

Claude가 파일을 수정하거나 명령어를 실행할 때마다 허가를 요청합니다.

해결법

방법 1: 자주 쓰는 도구는 항상 허용으로 설정

> /permissions

권한 관리 화면에서 특정 도구를 Always Allow로 설정합니다.

방법 2: 파일 수정을 자동 허용

Shift+Tab을 눌러 Auto-Accept Edit Mode 선택

현재 세션 동안 파일 수정 요청을 자동으로 허용합니다.

방법 3: 각 권한 모드 이해하기

모드	설명	언제 쓰나
기본 모드	첫 사용 시 허가 요청	일반 사용
Plan Mode	파일 수정 불가, 계획만	안전하게 탐색할 때
Auto-Accept	파일 수정 자동 허용	신뢰할 수 있는 작업

--dangerously-skip-permissions 사용 주의

이 옵션은 모든 권한 확인을 건너뜁니다. 격리된 컨테이너 환경이 아니면 사용하지 마세요. 실수로 시스템 파일을 수정하거나 삭제할 위험이 있습니다.

Q8. 한글이 깨진다 / 이상한 문자가 나온다

원인

터미널이 UTF-8 인코딩을 사용하지 않을 때 발생합니다.

해결법

macOS / Linux

shell 설정 파일(.zshrc 또는 .bashrc)에 추가:

export LANG=ko_KR.UTF-8
export LC_ALL=ko_KR.UTF-8

추가 후 source ~/.zshrc 실행.

터미널 앱 설정 확인

iTerm2: Preferences → Profiles → Terminal → Character Encoding → UTF-8
macOS 기본 터미널: 환경설정 → 프로파일 → 고급 → 문자 인코딩 → Unicode(UTF-8)
VS Code 터미널: 자동으로 UTF-8 사용 (대부분 문제없음)

Windows (WSL)

# WSL에서 실행
sudo locale-gen ko_KR.UTF-8

Q9. 맥락을 잃어버렸다 (세션이 초기화됐다)

상황

Claude가 이전에 한 작업을 기억하지 못함
세션이 갑자기 끊김
터미널을 닫았다 다시 열었음

해결법

방법 1: 이전 세션 이어서 시작

# 가장 최근 세션 이어서
claude --continue

# 세션 목록에서 선택
claude --resume

# 이름으로 이어서 (이름을 미리 저장했을 때)
claude --resume auth-refactor

방법 2: 세션에 이름 붙여두기 (예방책)

중요한 작업을 시작할 때:

> /rename 로그인기능-개발

방법 3: CLAUDE.md에 중요 정보 저장

세션이 끊겨도 유지되어야 할 정보는 CLAUDE.md에:

> /memory

# 현재 진행 중인 작업
- 목표: OAuth2 인증 시스템 구현
- 완료: 기본 로그인/로그아웃
- 진행 중: 소셜 로그인 (Google, Kakao)
- 사용 기술: Next.js, Prisma, NextAuth.js

Q10. 코드가 너무 많이 바뀌었다 (예상치 못한 대규모 변경)

상황

"간단히 수정해줘"라고 했는데 Claude가 관련 없는 파일까지 대거 수정하는 경우.

해결법

방법 1: 즉시 멈추기

Claude가 작업 중이면 바로:

Ctrl+C

또는 Esc를 눌러 현재 작업 중단.

방법 2: 이전 상태로 되감기

Esc 두 번 연속
또는
> /rewind

방법 3: git으로 확인 및 복구

# 변경된 파일 목록 확인
git status

# 변경 내용 상세 확인
git diff

# 특정 파일만 복구
git checkout -- 파일경로

# 전부 취소
git checkout .

방법 4: Plan Mode로 먼저 확인 (예방책)

큰 작업 전에는 Plan Mode에서 계획을 먼저 검토하세요.

Shift+Tab (두 번)

또는

claude --permission-mode plan

방법 5: 지시를 더 구체적으로

# 범위를 명확하게 지정
> auth.js 파일의 login 함수만 수정해줘. 다른 파일은 건드리지 마

# 금지 사항 명시
> 리팩토링은 하지 말고 버그만 수정해줘

요약: 자주 하는 실수 방지 체크리스트

Claude Code 시작 전:
□ 프로젝트 폴더로 이동했나? (cd 내프로젝트)
□ 중요한 작업이면 git commit 했나?
□ CLAUDE.md에 프로젝트 규칙이 있나?

작업 중:
□ 지시가 충분히 구체적인가?
□ 한 번에 너무 많이 요청하지 않았나?
□ 대화가 길어지면 /compact 사용했나?
□ 뭔가 이상하면 Ctrl+C로 바로 멈췄나?

작업 후:
□ 변경 내용을 확인했나? (git diff)
□ 테스트가 통과하는가?
□ 중요한 세션이면 이름을 저장했나? (/rename)

문제가 해결되지 않으면 Claude Code 안에서 /doctor를 실행해 설치 상태를 점검하거나, /bug를 입력해 Anthropic에 직접 문제를 보고할 수 있습니다.

MCP & 외부 도구 연결

고급

Model Context Protocol로 GitHub, Slack, DB 등 외부 도구를 연결합니다.

10. MCP & 외부 도구 연결

Claude가 GitHub, Slack, DB, 브라우저를 직접 다룰 수 있게 해주는 표준 프로토콜

MCP란?

**MCP(Model Context Protocol)**는 Claude가 외부 도구와 데이터 소스에 연결할 수 있게 해주는 오픈 표준입니다.

쉽게 말하면: Claude Code는 기본적으로 파일과 터미널만 다룹니다. MCP를 연결하면 Claude가 GitHub PR을 직접 열고, Slack 메시지를 읽고, 데이터베이스를 쿼리하는 등 외부 세계와 상호작용할 수 있게 됩니다.

비유: MCP는 Claude에게 USB 포트를 달아주는 것과 같습니다. 어떤 도구든 꽂으면 사용할 수 있게 됩니다.

MCP로 없어지는 노가다

MCP 없이는 이런 일들을 직접 해야 합니다:

기존 노가다	MCP 연결 후
JIRA 티켓 내용을 복사해서 Claude에게 붙여넣기	"ENG-4521 이슈 구현해줘" 한 마디로 끝
Sentry 에러 스택트레이스를 수동으로 복사	"지난 24시간 주요 에러 분석해줘"
DB 스키마를 Claude에게 설명하고 쿼리 요청	"users 테이블에서 90일 미접속 유저 찾아줘"
Figma 디자인 보고 직접 코딩	"Figma 최신 디자인대로 이메일 템플릿 업데이트해줘"
PR 내용 복사해서 리뷰 요청	"PR #456 리뷰해줘" 한 마디로 끝

MCP로 할 수 있는 것들

GitHub — PR/이슈 직접 조작

# GitHub MCP 서버 연결
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# 연결 후 이런 요청이 가능해집니다
> "PR #456 검토하고 개선점 제안해줘"
> "방금 발견한 버그 이슈 새로 만들어줘"
> "나에게 할당된 오픈 PR 목록 보여줘"

Sentry — 프로덕션 에러 분석

# Sentry 연결
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# /mcp 명령으로 인증 완료 후
> "지난 24시간 주요 에러가 뭐야?"
> "에러 ID abc123 스택트레이스 보여줘"
> "이 에러들이 어느 배포에서 생겼어?"

PostgreSQL — DB 직접 쿼리

# DB 연결 (읽기 전용 추천)
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

# 연결 후
> "이번 달 총 매출 얼마야?"
> "orders 테이블 스키마 보여줘"
> "90일째 구매 안 한 고객 찾아줘"

Slack — 메시지 읽고 보내기

Slack 연동을 통해 슬랙 채널의 맥락을 그대로 Claude에게 전달할 수 있습니다. 팀 대화에서 버그 리포트가 올라오면 Claude가 해당 스레드 맥락을 읽고 바로 코딩 작업을 시작할 수 있습니다.

Notion, Asana, Figma 등

MCP 레지스트리(api.anthropic.com/mcp-registry/docs)에서 수백 가지 MCP 서버를 찾을 수 있습니다.

MCP 서버 설치 방법

방법 1: 원격 HTTP 서버 (권장)

# 기본 문법
claude mcp add --transport http <이름> <URL>

# 예시: Notion 연결
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 인증 헤더가 필요한 경우
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

방법 2: 로컬 stdio 서버

내 컴퓨터에서 실행되는 서버입니다. 시스템 직접 접근이나 커스텀 스크립트에 적합합니다.

# 기본 문법
claude mcp add [옵션] <이름> -- <커맨드> [인자...]

# 예시: Airtable 연결
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

MCP 서버 관리 명령어

# 설정된 서버 목록 보기
claude mcp list

# 특정 서버 상세 확인
claude mcp get github

# 서버 제거
claude mcp remove github

# Claude Code 내에서 상태 확인
/mcp

설정 파일 위치 (스코프)

MCP 서버 설정은 사용 범위에 따라 세 곳에 저장됩니다:

스코프	저장 위치	용도
로컬 (기본값)	`~/.claude.json`	현재 프로젝트에만, 개인 설정
프로젝트	`.mcp.json` (프로젝트 루트)	팀 전체 공유, 버전 관리에 포함
유저	`~/.claude.json`	모든 프로젝트에서 사용

# 팀 공유용 프로젝트 스코프로 추가
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

# 모든 프로젝트에서 쓸 유저 스코프로 추가
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

팀 프로젝트에서는 .mcp.json을 Git에 커밋해서 팀원 모두가 동일한 MCP 서버를 사용할 수 있습니다.

입문자 추천 MCP 3가지

실용성 기준으로 처음 써볼 만한 MCP 서버입니다:

1. GitHub MCP

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

없어지는 노가다: PR 내용 복붙, 이슈 수동 조회, 코드 리뷰 컨텍스트 전달

2. PostgreSQL / DB MCP

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://user:pass@localhost:5432/mydb"

없어지는 노가다: 스키마 설명, 데이터 조회 결과 복붙, SQL 작성 후 직접 실행

3. Sentry MCP

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

없어지는 노가다: 에러 스택트레이스 복붙, 에러 발생 시점 수동 조회

Claude Code 공식 커넥터

Claude.ai 계정으로 Claude Code에 로그인한 경우, claude.ai/settings/connectors에서 설정한 MCP 서버가 Claude Code에 자동으로 연결됩니다.

공식적으로 지원되는 커넥터:

Slack: 채널 메시지 읽기/쓰기
Google Chrome: 브라우저 자동화 (Playwright 기반)

OAuth 인증이 필요한 서버 연결 방법

Sentry, GitHub 같은 클라우드 서버는 OAuth 인증이 필요합니다:

# 1단계: 서버 추가
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 2단계: Claude Code 내에서 인증
> /mcp

# 브라우저 열림 → 로그인 → 완료

인증 토큰은 자동으로 저장되고 갱신됩니다.

MCP 프롬프트를 커맨드로 사용하기

MCP 서버가 프롬프트를 제공하는 경우, Claude Code에서 /mcp__서버명__프롬프트명 형식으로 직접 실행할 수 있습니다:

> /mcp__github__list_prs
> /mcp__github__pr_review 456
> /mcp__jira__create_issue "로그인 버그" high

⚠️ 주의사항

신뢰할 수 없는 MCP 서버를 함부로 설치하지 마세요.

MCP 서버는 Claude를 통해 내 파일 시스템, DB, 외부 서비스에 접근할 수 있습니다
특히 외부 콘텐츠를 가져오는 MCP 서버는 프롬프트 인젝션 위험이 있습니다
Anthropic이 직접 검증한 서버만 공식 MCP 레지스트리에 등록되어 있습니다
출처가 불명확한 서버는 설치 전 소스 코드를 반드시 확인하세요

# 프로젝트 스코프 서버는 팀원들에게 확인 요청이 표시됩니다
# (보안 검토를 위한 안전장치)

한 줄 요약

MCP = Claude에게 외부 세계를 연결하는 플러그인. GitHub, DB, Slack을 Claude가 직접 다루게 해서 "복사-붙여넣기" 노가다를 없앤다.

다음 섹션에서는 Hooks로 Claude Code의 동작을 자동화하는 방법을 배웁니다.

Hooks — 자동화의 핵심

고급

이벤트 기반 자동화 시스템, Hooks를 활용해 Claude Code를 커스터마이즈합니다.

11. Hooks — 자동화의 핵심

"파일 수정할 때마다 포매터 돌려줘", "작업 끝나면 알림 보내줘" — 이런 걸 자동으로 하게 만드는 기능

Hooks란?

Hooks는 Claude Code의 특정 이벤트가 발생할 때 자동으로 실행되는 셸 커맨드입니다.

Claude Code는 코드 수정, 명령어 실행, 작업 완료 등 다양한 이벤트를 발생시킵니다. Hooks를 설정하면 이런 이벤트에 반응해서 사람 개입 없이 자동으로 원하는 동작을 수행합니다.

핵심: Hooks는 "Claude가 알아서 해주면 좋겠다"가 아니라 **"반드시 항상 실행되어야 한다"**는 동작을 위한 것입니다. LLM의 판단이 아니라 결정론적 제어입니다.

Hooks로 없어지는 노가다

기존 노가다	Hooks 설정 후
파일 수정할 때마다 Prettier 수동 실행	파일 수정 후 자동으로 포맷
작업 끝났는지 터미널 계속 확인	완료 시 데스크탑 알림
`.env` 파일 실수로 수정될까 걱정	보호된 파일 수정 시 자동 차단
컨텍스트 압축 후 규칙 재설명	압축 후 핵심 규칙 자동 재주입
실행된 명령어 수동 로그 기록	모든 Bash 명령어 자동 기록

주요 Hook 이벤트

이벤트	발생 시점	주요 용도
`PreToolUse`	도구 실행 직전	위험한 명령어 차단, 검증
`PostToolUse`	도구 실행 직후	자동 포매팅, 로그 기록
`Stop`	Claude가 응답 완료 시	알림 전송, 후처리
`SessionStart`	세션 시작/재개 시	컨텍스트 주입, 초기화
`Notification`	Claude가 알림 보낼 때	데스크탑 푸시 알림
`UserPromptSubmit`	사용자가 프롬프트 제출 시	입력 전처리
`SubagentStart`	서브에이전트 시작 시	에이전트 추적
`SubagentStop`	서브에이전트 종료 시	결과 후처리
`PreCompact`	컨텍스트 압축 전	중요 정보 보존
`SessionEnd`	세션 종료 시	정리 작업

Hook 설정 위치

Hooks는 settings.json의 hooks 섹션에 설정합니다:

위치	범위	공유 가능
`~/.claude/settings.json`	내 모든 프로젝트	아니오
`.claude/settings.json`	현재 프로젝트	예 (Git 커밋 가능)
`.claude/settings.local.json`	현재 프로젝트	아니오 (gitignore)

실용 예시

예시 1: 파일 수정 시 자동 포매팅

Claude가 파일을 수정할 때마다 Prettier를 자동 실행합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

matcher는 어떤 도구에 반응할지 필터입니다. Edit|Write는 파일 편집/작성 시에만 실행합니다.

예시 2: 작업 완료 시 알림 받기

Claude가 작업을 끝냈을 때 자리를 비워도 알 수 있습니다.

macOS (~/.claude/settings.json):

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code가 완료했습니다\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Linux:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' '작업이 완료되었습니다'"
          }
        ]
      }
    ]
  }
}

예시 3: 위험한 파일 수정 차단

.env, package-lock.json, .git/ 수정을 자동으로 막습니다.

Step 1: 스크립트 파일 생성 (.claude/hooks/protect-files.sh):

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "차단: $FILE_PATH 는 보호된 파일입니다 ('$pattern' 패턴)" >&2
    exit 2
  fi
done

exit 0

Step 2: 실행 권한 부여:

chmod +x .claude/hooks/protect-files.sh

Step 3: Hook 등록 (.claude/settings.json):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

exit 2로 종료하면 Claude가 해당 동작을 차단하고 에러 메시지를 받습니다. exit 0은 허용, 다른 코드는 진행되지만 로그만 남습니다.

예시 4: 컨텍스트 압축 후 규칙 재주입

Claude의 컨텍스트가 가득 차면 자동으로 압축(compaction)됩니다. 이때 중요한 규칙을 다시 주입합니다.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo '규칙: npm 대신 Bun 사용. 커밋 전 bun test 실행. 현재 스프린트: 인증 리팩토링.'"
          }
        ]
      }
    ]
  }
}

예시 5: 모든 Bash 명령어 감사 로그

Claude가 실행하는 모든 Bash 명령어를 파일에 기록합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

Hook 첫 설정하는 가장 쉬운 방법

Claude Code 내에서 /hooks 커맨드를 실행하면 인터랙티브 메뉴가 열립니다:

/hooks

원하는 이벤트 선택
matcher 설정 (*는 전체, Edit|Write는 파일 수정만)
실행할 셸 커맨드 입력
저장 위치 선택 (User settings → 모든 프로젝트 적용)

고급: 프롬프트 기반 Hook

판단이 필요한 상황에는 type: "prompt" Hook을 사용합니다. LLM이 yes/no 결정을 내립니다:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "모든 태스크가 완료되었는지 확인하세요. 미완료 항목이 있으면 {\"ok\": false, \"reason\": \"남은 작업\"} 형식으로 응답하세요."
          }
        ]
      }
    ]
  }
}

파일을 읽거나 명령어를 실행해야 하는 검증은 type: "agent" Hook을 사용합니다 (서브에이전트가 실제로 코드베이스를 확인합니다).

Hook 트러블슈팅

문제	해결책
Hook이 실행 안 됨	`/hooks`에서 이벤트 확인, matcher 대소문자 확인
스크립트가 실행 안 됨	`chmod +x` 로 실행 권한 부여
Stop hook이 무한루프	`stop_hook_active` 필드 체크 추가
JSON 파싱 오류	`~/.zshrc`의 echo 구문을 인터랙티브 셸 조건부로 감싸기

디버그 모드: claude --debug 또는 Ctrl+O로 verbose 출력 확인

⚠️ 주의사항

Hooks는 강력합니다. PreToolUse에서 exit 2를 잘못 설정하면 Claude가 아무 파일도 수정하지 못하게 됩니다
PostToolUse Hook은 이미 실행된 도구를 되돌릴 수 없습니다
PermissionRequest Hook은 비대화형 모드(-p)에서 실행되지 않습니다 → 자동화 스크립트에서는 PreToolUse 사용
설정 파일을 직접 수정했다면 /hooks 메뉴를 한 번 열거나 세션을 재시작해야 적용됩니다

한 줄 요약

Hooks = Claude Code 이벤트에 자동으로 반응하는 셸 커맨드. "파일 고칠 때마다 포매팅", "완료되면 알림", "위험한 파일 차단" — 이런 게 LLM 판단 없이 100% 실행됩니다.

다음 섹션에서는 반복 작업을 Skills로 자동화하는 방법을 배웁니다.

Skills & 플러그인 만들기

고급

반복 작업을 자동화하는 Skills를 만들고 플러그인으로 공유합니다.

12. Skills & 플러그인 만들기

반복하는 워크플로우를 /커맨드 하나로 — 팀과 공유도 가능한 재사용 가능한 자동화

Skills란?

Skills는 Claude Code에 새로운 능력을 추가하는 재사용 가능한 워크플로우입니다. SKILL.md 파일을 만들면 Claude가 그것을 도구로 인식하고, /스킬이름 커맨드로 직접 실행하거나 상황에 맞게 자동으로 활성화합니다.

쉽게 말하면: 자주 쓰는 작업 절차를 문서화해 두면, 다음부터는 한 마디로 실행됩니다.

참고: 기존 .claude/commands/ 폴더의 커스텀 슬래시 커맨드는 Skills로 통합되었습니다. 기존 파일은 그대로 작동합니다.

Skills vs 일반 대화 차이점

	일반 대화	Skills
실행 방법	매번 설명 타이핑	`/skill-name` 한 번
일관성	매번 다를 수 있음	항상 동일한 절차
팀 공유	불가	Git 커밋으로 공유
인자 전달	설명 속에 포함	`$ARGUMENTS`로 명확하게
도구 제한	Claude 판단	명시적으로 허용된 도구만

Skills로 없어지는 노가다

반복 작업	Skills 설정 후
커밋 메시지 작성 규칙 매번 설명	`/commit` 한 번으로
코드 리뷰 요청할 때마다 체크리스트 붙여넣기	`/review` 실행
PR 요약 작성 방법 반복 설명	`/pr-summary` 실행
번역 요청할 때마다 언어/형식 명시	`/translate ko en README.md`
GitHub 이슈 처리 절차 매번 설명	`/fix-issue 123`

내 Skills 만드는 방법

Step 1: 디렉터리 생성

# 내 모든 프로젝트에서 사용할 경우 (개인용)
mkdir -p ~/.claude/skills/commit

# 현재 프로젝트에서만 사용할 경우
mkdir -p .claude/skills/commit

Step 2: SKILL.md 작성

.claude/skills/commit/SKILL.md:

---
name: commit
description: 변경사항을 분석해서 좋은 커밋 메시지를 작성하고 커밋합니다. 커밋할 때 사용.
disable-model-invocation: true
---

현재 staged 변경사항을 분석해서 Conventional Commits 형식으로 커밋하세요:

1. `git diff --staged` 실행해서 변경사항 확인
2. 변경 유형 파악 (feat/fix/docs/refactor/test/chore)
3. 50자 이내 제목 작성
4. 필요시 본문에 상세 설명 추가
5. `git commit -m "..."` 실행

Step 3: 실행

# 직접 실행
/commit

# 또는 자연어로 → Claude가 자동 감지
"변경사항 커밋해줘"

Skills 파일 구조

my-skill/
├── SKILL.md           # 메인 지시사항 (필수)
├── template.md        # Claude가 채울 템플릿 (선택)
├── examples/
│   └── sample.md      # 예시 출력 (선택)
└── scripts/
    └── validate.sh    # Claude가 실행할 스크립트 (선택)

팁: SKILL.md는 500줄 이내로 유지하고, 상세 내용은 별도 파일로 분리하세요.

핵심 Frontmatter 옵션

---
name: my-skill           # 스킬 이름 (디렉터리명 기본값)
description: 설명        # Claude가 언제 이 스킬을 쓸지 판단하는 기준 (필수)
disable-model-invocation: true  # true면 사용자만 실행 가능 (Claude 자동 실행 불가)
user-invocable: false    # false면 메뉴에 안 보임 (Claude만 자동 실행 가능)
allowed-tools: Read, Grep, Glob  # 이 스킬 실행 중 허용할 도구만 지정
context: fork            # 독립된 서브에이전트 컨텍스트에서 실행
model: sonnet            # 이 스킬에서 사용할 모델 지정
---

Frontmatter	사용자 실행	Claude 자동 실행	언제 씀
(기본값)	가능	가능	일반 워크플로우
`disable-model-invocation: true`	가능	불가	배포, 전송 등 부작용 있는 작업
`user-invocable: false`	불가	가능	배경 지식, 컨벤션

실용 예시 3가지

예시 1: 코드 리뷰 자동화

.claude/skills/review/SKILL.md:

---
name: review
description: 코드를 리뷰합니다. 코드 품질, 보안, 성능 측면에서 검토가 필요할 때 사용.
---

다음 순서로 코드를 리뷰하세요:

1. `git diff HEAD~1` 또는 `$ARGUMENTS`로 지정된 파일 분석
2. 다음 항목 체크:
   - 코드 가독성 및 명명 규칙
   - 에러 처리 누락 여부
   - 보안 취약점 (SQL injection, XSS, 하드코딩된 시크릿)
   - 중복 코드
   - 테스트 커버리지
3. 우선순위별 정리:
   - 🔴 Critical (반드시 수정)
   - 🟡 Warning (수정 권장)
   - 🔵 Suggestion (고려 사항)

실행:

/review src/auth/login.ts

예시 2: GitHub 이슈 처리

.claude/skills/fix-issue/SKILL.md:

---
name: fix-issue
description: GitHub 이슈를 구현합니다. 이슈 번호를 전달하면 분석-구현-테스트-커밋까지 진행.
disable-model-invocation: true
allowed-tools: Bash(gh *), Read, Edit, Write
---

GitHub 이슈 $ARGUMENTS를 처리하세요:

1. `gh issue view $ARGUMENTS` 로 이슈 내용 확인
2. 요구사항 파악 후 구현 계획 수립
3. 관련 파일 찾고 코드 구현
4. 테스트 작성 및 실행
5. `gh issue close $ARGUMENTS` 후 커밋 생성

실행:

/fix-issue 123

예시 3: 번역 자동화

.claude/skills/translate/SKILL.md:

---
name: translate
description: 파일이나 텍스트를 번역합니다.
argument-hint: [파일경로 또는 텍스트] [대상언어]
---

$ARGUMENTS[0]을 $ARGUMENTS[1]로 번역하세요.

- 기술 용어는 원문 유지 (코드, 명령어, 고유명사)
- 마크다운 구조 보존
- 번역 결과를 원본과 같은 파일명에 언어 코드 추가해서 저장

실행:

/translate README.md ko

동적 컨텍스트 주입 (고급)

! + 백틱 문법으로 스킬 실행 전에 셸 커맨드를 실행하고 결과를 컨텍스트에 주입할 수 있습니다:

---
name: pr-summary
description: PR 요약을 작성합니다.
context: fork
allowed-tools: Bash(gh *)
---

## PR 컨텍스트
- 변경 내용: !`gh pr diff`
- PR 댓글: !`gh pr view --comments`
- 변경된 파일: !`gh pr diff --name-only`

위 내용을 바탕으로 명확한 PR 요약을 작성하세요.

Claude가 이 스킬을 실행하면:

백틱 안의 명령어가 먼저 실행됨
실제 데이터가 프롬프트에 삽입됨
Claude가 실제 PR 내용을 보고 요약 작성

Skills가 저장되는 위치

위치	경로	적용 범위
엔터프라이즈	관리형 설정	조직 전체
개인	`~/.claude/skills/<이름>/SKILL.md`	내 모든 프로젝트
프로젝트	`.claude/skills/<이름>/SKILL.md`	이 프로젝트만
플러그인	`<플러그인>/skills/<이름>/SKILL.md`	플러그인 활성화 시

같은 이름의 스킬이 여러 위치에 있으면 엔터프라이즈 > 개인 > 프로젝트 순으로 우선순위가 적용됩니다.

플러그인으로 패키징하기

팀 전체에 배포하거나 커뮤니티와 공유하려면 플러그인으로 패키징합니다.

플러그인 구조

my-plugin/
├── .claude-plugin/
│   └── plugin.json        # 플러그인 메타데이터
├── skills/
│   ├── review/
│   │   └── SKILL.md
│   └── commit/
│       └── SKILL.md
└── hooks/
    └── hooks.json         # 플러그인 전용 Hooks

plugin.json

{
  "name": "my-plugin",
  "description": "팀 공통 워크플로우 모음",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

로컬 테스트

# 플러그인 디렉터리로 실행
claude --plugin-dir ./my-plugin

# 스킬 실행 (플러그인 네임스페이스 포함)
/my-plugin:review
/my-plugin:commit

Standalone vs 플러그인 선택 기준

상황	권장 방식
개인 워크플로우, 빠른 실험	Standalone (`.claude/skills/`)
팀과 공유, 여러 프로젝트	플러그인
커뮤니티 배포	플러그인 + 마켓플레이스

Skills 자동 감지 원리

Claude는 description 필드를 보고 어떤 상황에서 스킬을 써야 할지 판단합니다:

# 잘 쓴 description 예시
description: 코드를 리뷰합니다. PR 리뷰, 코드 품질 검토, 보안 분석이 필요할 때 사용.

# 아쉬운 description 예시
description: review tool

"어떤 상황에서 쓰는지"를 명확히 기술할수록 Claude가 더 잘 감지합니다
disable-model-invocation: true를 설정하면 Claude가 자동으로 실행하지 않습니다

트러블슈팅

문제	해결책
스킬이 트리거 안 됨	description에 사용자가 실제로 쓸 표현 포함
스킬이 너무 자주 실행됨	description을 더 구체적으로 수정
Claude가 스킬을 못 봄	`/context`에서 컨텍스트 한도 초과 여부 확인
자동 실행 막고 싶음	`disable-model-invocation: true` 추가

한 줄 요약

Skills = 내가 자주 하는 작업을 /커맨드 하나로 만들어두는 것. 팀에 배포하려면 플러그인으로 패키징하면 된다.

다음 섹션에서는 Sub-agents로 복잡한 작업을 병렬 처리하는 방법을 배웁니다.

Sub-agents & Agent Teams

고급

여러 Claude 에이전트가 협력하는 고급 멀티 에이전트 시스템을 활용합니다.

13. Sub-agents & Agent Teams

Claude가 다른 Claude에게 작업을 위임 — 복잡한 작업을 병렬로 처리하는 방법

Sub-agents란?

**Sub-agents(서브에이전트)**는 메인 Claude가 특정 작업을 전문화된 별도의 Claude 인스턴스에 위임하는 기능입니다.

각 서브에이전트는:

독립된 컨텍스트 창을 가집니다 (메인 대화와 분리)
커스텀 시스템 프롬프트로 특정 역할에 집중합니다
제한된 도구만 사용합니다 (필요한 것만)
작업 완료 후 요약 결과만 메인으로 반환합니다

개념도

메인 Claude (오케스트레이터)
    │
    ├──► 서브 Claude A: 탐색 전담 (Explore)
    │         └── 파일 읽기, 코드 검색만 가능
    │
    ├──► 서브 Claude B: 구현 전담 (general-purpose)
    │         └── 파일 읽기+수정 가능
    │
    └──► 서브 Claude C: 테스트 전담 (custom)
              └── Bash 실행만 가능

각 서브에이전트는 독립 컨텍스트에서 실행
→ 메인 컨텍스트를 깨끗하게 유지
→ 결과 요약만 메인으로 반환

언제 유용한가?

Sub-agents를 쓰면 좋은 상황

상황	이유
대용량 출력이 나오는 작업	테스트 로그, 문서 페치 결과가 메인 컨텍스트를 낭비함
독립적인 여러 파일 동시 수정	병렬로 처리하면 더 빠름
특정 도구만 써야 하는 작업	읽기 전용 리뷰어, DB 쿼리 전용 에이전트
탐색과 구현을 분리하고 싶을 때	탐색 결과가 메인 대화를 오염시키지 않게

Sub-agents보다 일반 대화가 나은 상황

상황	이유
잦은 피드백이 필요한 작업	서브에이전트는 독립 실행 → 중간 개입 어려움
빠른 단순 수정	서브에이전트 시작 오버헤드가 있음
여러 단계가 컨텍스트를 공유해야 할 때	계획 → 구현 → 테스트가 긴밀하게 연결된 경우

내장 서브에이전트

Claude Code는 기본적으로 3개의 서브에이전트를 포함합니다:

에이전트	모델	허용 도구	용도
Explore	Haiku (빠름)	읽기 전용	파일 탐색, 코드 검색
Plan	메인 상속	읽기 전용	Plan 모드에서 컨텍스트 수집
general-purpose	메인 상속	모든 도구	복잡한 다단계 작업

Claude가 코드를 탐색해야 할 때는 자동으로 Explore 서브에이전트를 씁니다. 탐색 결과(수천 줄의 파일 내용)가 메인 대화를 오염시키지 않고, 요약만 메인으로 돌아옵니다.

나만의 서브에이전트 만들기

방법 1: /agents 인터랙티브 메뉴 (권장)

/agents

Create new agent 선택
User-level (모든 프로젝트) 또는 Project-level (현재 프로젝트) 선택
Generate with Claude 선택 후 역할 설명
허용 도구 선택
모델 선택 (Haiku/Sonnet/Opus)
저장

방법 2: 파일 직접 작성

.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: 코드를 리뷰합니다. 코드 변경 후 품질, 보안, 성능을 검토할 때 자동으로 사용.
tools: Read, Grep, Glob, Bash
model: sonnet
---

당신은 시니어 코드 리뷰어입니다.

실행 시:
1. `git diff`로 최근 변경사항 확인
2. 수정된 파일에 집중
3. 즉시 리뷰 시작

리뷰 체크리스트:
- 코드 가독성 및 명명 규칙
- 중복 코드 없음
- 에러 처리 적절성
- 보안 취약점 (노출된 시크릿, 입력 검증)
- 테스트 커버리지

피드백 형식:
- 🔴 Critical (반드시 수정)
- 🟡 Warning (수정 권장)
- 🔵 Suggestion (고려 사항)

서브에이전트 설정 옵션

---
name: my-agent           # 소문자 + 하이픈 (필수)
description: 설명        # Claude가 언제 위임할지 판단 기준 (필수)
tools: Read, Grep, Glob  # 허용 도구 목록 (생략 시 모든 도구 상속)
disallowedTools: Write   # 제외할 도구
model: haiku             # haiku / sonnet / opus / inherit(기본값)
permissionMode: default  # default / acceptEdits / dontAsk / bypassPermissions
maxTurns: 20             # 최대 실행 턴 수
memory: user             # 영구 메모리: user / project / local
background: false        # true면 항상 백그라운드 실행
isolation: worktree      # worktree면 격리된 Git 워크트리에서 실행
---

서브에이전트 저장 위치

위치	경로	우선순위
CLI 플래그	`--agents '{...}'`	1 (최고)
프로젝트	`.claude/agents/`	2
유저	`~/.claude/agents/`	3
플러그인	`<plugin>/agents/`	4

실용 예시

예시 1: 병렬 코드베이스 탐색

"인증, DB, API 모듈을 각각 별도 서브에이전트로 병렬 분석해줘"

→ 3개 Explore 서브에이전트가 동시에 실행 → 각 모듈 분석 결과만 메인으로 반환 → 메인 Claude가 통합 분석

예시 2: 코드 리뷰 + 수정 연쇄

"code-reviewer 에이전트로 성능 문제 찾고, 그 다음 optimizer 에이전트로 수정해줘"

→ code-reviewer가 문제 목록 반환 → optimizer가 해당 목록을 받아 수정 실행 → 메인 컨텍스트는 깨끗하게 유지

예시 3: 테스트 실행 격리

"서브에이전트로 전체 테스트 실행하고 실패한 것만 보고해줘"

→ 테스트 로그(수천 줄)가 메인 컨텍스트에 쌓이지 않음 → 실패 항목과 에러 메시지만 반환

예시 4: 특정 에이전트 명시 요청

"code-reviewer 에이전트로 인증 모듈 리뷰해줘"
"debugger 에이전트로 실패 중인 테스트 고쳐줘"

영구 메모리 기능

서브에이전트에 memory 필드를 설정하면 세션 간에도 학습 내용이 유지됩니다:

---
name: code-reviewer
description: 코드를 리뷰합니다
memory: user
---

코드를 리뷰하면서 발견한 코드베이스 패턴, 아키텍처 결정, 반복되는 이슈를
메모리에 기록하세요. 다음 리뷰 때 이전 학습 내용을 활용하세요.

스코프	위치	사용 시점
`user`	`~/.claude/agent-memory/<이름>/`	여러 프로젝트에서 지식 축적
`project`	`.claude/agent-memory/<이름>/`	프로젝트별 학습, 팀 공유 가능
`local`	`.claude/agent-memory-local/<이름>/`	프로젝트별 학습, 개인만

포그라운드 vs 백그라운드 실행

포그라운드: 완료될 때까지 대기. 권한 요청이 사용자에게 전달됨
백그라운드: 백그라운드에서 동시 실행. 계속 다른 작업 가능

# 백그라운드 실행 요청
"이걸 백그라운드에서 실행해줘"

# 실행 중 백그라운드로 전환
Ctrl+B

주의: 백그라운드 서브에이전트는 MCP 도구를 사용할 수 없습니다.

Agent Teams란?

Agent Teams는 서브에이전트보다 한 단계 더 나아간 개념입니다. 여러 에이전트가 각자의 완전히 독립된 세션에서 실행되며 협력합니다.

	Sub-agents	Agent Teams
실행 단위	메인 세션 내부	완전히 독립된 세션
컨텍스트	메인과 공유	각자 독립
적합한 작업	단일 세션 내 위임	장시간 병렬 작업
통신	결과 요약 반환	세션 간 조율

서브에이전트로 컨텍스트 창이 부족하거나, 작업이 여러 세션에 걸쳐 지속되어야 할 때 Agent Teams를 고려합니다.

⚠️ 비용 주의

서브에이전트는 각각 독립된 Claude 인스턴스입니다. 에이전트마다 토큰을 소모합니다.

서브에이전트 3개 병렬 실행 = 토큰 사용량 대폭 증가
결과가 메인 컨텍스트로 돌아올 때 추가 토큰 소모
불필요한 서브에이전트 남용은 비용 증가로 이어짐

비용 절약 팁:

읽기 전용 탐색에는 Haiku 모델 서브에이전트 사용
서브에이전트가 반환하는 결과의 양을 명확히 지정
단순 작업은 메인 대화에서 처리

초보자를 위한 조언

처음엔 단일 Claude로 충분합니다.

서브에이전트는 다음 상황이 생겼을 때 도입하세요:

메인 컨텍스트가 자꾸 넘쳐서 압축이 반복될 때
동일한 탐색 작업을 여러 번 반복할 때
특정 도구만 쓰는 안전한 리뷰어가 필요할 때

한 줄 요약

Sub-agents = Claude가 다른 Claude에게 작업 위임. 독립 컨텍스트에서 실행되므로 메인 대화를 깨끗하게 유지하면서 병렬 처리 가능. 단, 토큰 비용은 에이전트 수만큼 증가.

비용 관리 & 절약 팁

고급

토큰 비용 구조를 이해하고 효율적으로 Claude Code를 사용하는 방법을 배웁니다.

14. 비용 관리 & 절약 팁

Claude Code를 더 스마트하게, 더 저렴하게 쓰는 방법을 알아봅니다.

비용 구조 한눈에 보기

Claude Code의 비용 방식은 크게 두 가지입니다.

구분	방식	특징
Claude.ai Pro / Max	정액제 구독	월 고정 요금, API 비용 별도 없음
Anthropic API	종량제	사용한 토큰 수만큼 요금 발생

Claude.ai Pro/Max 구독자는 구독료 안에 Claude Code 사용이 포함되어 있어 API 비용이 따로 청구되지 않습니다. /cost 명령어가 표시하는 숫자는 API 사용자를 위한 것이므로 구독자는 참고용으로만 보면 됩니다.

API 사용자는 사용량에 따라 요금이 발생합니다. 공식 문서에 따르면 평균적으로 개발자 1인당 하루 약 $6, 90%의 사용자는 하루 $12 이하의 비용이 발생합니다.

토큰이란?

**토큰(token)**은 Claude가 텍스트를 처리하는 단위입니다.

영어 기준: 단어 약 1개 = 1~2 토큰
한국어 기준: 글자 약 2~3자 = 1 토큰
대략적으로: 4글자(영어) ≈ 1 토큰

쉽게 말하면, Claude에게 파일을 읽히거나, 질문을 하거나, 답변을 받을 때마다 토큰이 소모됩니다. 컨텍스트(대화 맥락)가 길어질수록 더 많은 토큰이 사용됩니다.

비용이 많이 드는 상황

1. 긴 파일을 반복해서 읽을 때

Claude가 같은 파일을 여러 번 읽으면 그때마다 토큰이 소모됩니다. 10,000줄짜리 로그 파일을 통째로 읽히면 한 번에 수만 개의 토큰이 사용됩니다.

2. 컨텍스트를 오래 유지할 때

대화가 길어질수록 이전 내용을 모두 컨텍스트로 포함시켜야 합니다. 관련 없는 작업을 계속 같은 세션에서 진행하면 불필요한 정보가 쌓여 비용이 늘어납니다.

3. 고성능 모델을 사용할 때

Opus 모델은 Sonnet보다 강력하지만 토큰당 비용도 높습니다. 간단한 작업에 Opus를 쓰는 것은 비효율적입니다.

4. 자동화(CI/CD)에서 무분별하게 실행할 때

GitHub Actions 등으로 자동화하면 사람의 개입 없이 대량의 토큰이 소모될 수 있습니다.

절약 팁 5가지

팁 1: `/compact`로 컨텍스트 정리하기

대화가 길어졌을 때 /compact 명령어를 실행하면 이전 내용을 요약해서 컨텍스트 크기를 줄여줍니다.

/compact 코드 변경 사항과 테스트 결과 중심으로 요약해줘

이렇게 하면 중요한 정보는 유지하면서 불필요한 대화 내용은 압축됩니다.

CLAUDE.md에 압축 방식을 미리 지정할 수도 있습니다:

# Compact instructions

When you are using compact, please focus on test output and code changes

팁: /clear를 쓰면 컨텍스트를 완전히 초기화할 수 있습니다. 전혀 다른 작업을 시작할 때 유용합니다.

팁 2: 불필요한 파일 참조 피하기

막연한 요청은 Claude가 불필요하게 많은 파일을 읽게 만듭니다.

비효율적인 요청	효율적인 요청
"이 코드베이스를 개선해줘"	"auth.ts의 login 함수에 입력 유효성 검사를 추가해줘"
"버그를 찾아줘"	"세션 만료 후 로그인이 실패하는 문제를 src/auth/에서 확인해줘"

구체적인 요청일수록 Claude가 필요한 파일만 읽어서 토큰 소모가 줄어듭니다.

팁 3: Haiku 모델 활용하기

모든 작업에 고성능 모델을 쓸 필요는 없습니다.

모델	용도	비용
Haiku	간단한 질문, 파일 요약, 단순 작업	낮음
Sonnet	일반 코딩 작업 (기본 추천)	중간
Opus	복잡한 아키텍처 설계, 어려운 추론	높음

모델 전환은 세션 중에도 가능합니다:

/model haiku

또는 시작할 때 지정:

claude --model haiku

opusplan 모드: 계획 단계에서는 Opus, 실행 단계에서는 Sonnet으로 자동 전환되는 하이브리드 모드입니다.

/model opusplan

팁 4: Fast Mode 이해하고 활용하기

/fast 명령어로 Fast Mode를 켜면 Opus 4.6이 약 2.5배 빠르게 응답합니다.

/fast

단, Fast Mode는 토큰당 비용이 더 높습니다. 속도가 중요한 순간(빠른 반복 작업, 실시간 디버깅)에만 사용하고, 장시간 자율 작업에는 끄는 것이 좋습니다.

참고: Fast Mode는 구독 플랜의 기본 사용량에 포함되지 않고 추가 사용(extra usage)으로 청구됩니다.

팁 5: `/cost`로 주기적으로 확인하기

API 사용자라면 현재 세션의 토큰 사용량을 확인할 수 있습니다:

/cost

출력 예시:

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    0 lines added, 0 lines removed

구독자는 /stats로 사용 패턴을 확인할 수 있습니다.

상태 표시줄(status line)을 설정하면 컨텍스트 사용량을 실시간으로 볼 수도 있습니다.

모델별 비용 비교 (간략)

모델	특징	API 기준
Haiku	빠르고 저렴, 간단한 작업	가장 저렴
Sonnet	균형 잡힌 성능, 일반 코딩 작업	중간
Opus	최고 성능, 복잡한 추론	가장 비쌈
Opus (Fast Mode)	Opus 속도 2.5배, 토큰 비용 높음	Opus보다 비쌈

정확한 토큰 가격은 Anthropic 가격 페이지를 참고하세요.

Claude.ai Max 플랜의 장점

Claude.ai Pro 또는 Max 구독자는 API 종량제 비용 없이 Claude Code를 사용할 수 있습니다.

월정액 안에 Claude Code 사용 포함
추가 API 키 불필요
비용 걱정 없이 다양한 실험 가능
Max 플랜의 경우 더 높은 사용량 한도

단, Fast Mode와 1M 컨텍스트 초과 분은 추가 사용(extra usage)으로 청구될 수 있습니다.

팀 비용 관리

API를 팀 단위로 사용하는 경우:

Workspace 지출 한도 설정: Anthropic Console에서 팀 전체 지출 한도를 설정할 수 있습니다.
사용량 대시보드: Console에서 팀원별 비용과 사용량을 확인할 수 있습니다.
에이전트 팀 주의: Agent Teams(여러 Claude 인스턴스 동시 실행) 기능은 표준 세션보다 약 7배 많은 토큰을 소모합니다.

정리: 비용 절약 체크리스트

✅ 작업이 끝나면 /clear로 컨텍스트 초기화
✅ 관련 없는 작업은 새 세션에서 시작
✅ 구체적인 파일명과 함수명을 명시
✅ 간단한 작업은 Haiku 모델 사용
✅ Fast Mode는 필요할 때만 켜기
✅ /cost 또는 /stats로 주기적으로 확인
✅ CLAUDE.md에 compact 지침 설정

Headless & GitHub Actions

고급

CI/CD 파이프라인에 Claude Code를 통합하는 자동화 방법을 알아봅니다.

15. Headless 모드 & GitHub Actions 자동화

Claude Code를 사람 없이 자동으로 실행하는 방법을 배웁니다.

Headless 모드란?

보통 Claude Code는 터미널에서 대화형으로 사용합니다. 사람이 직접 질문하고, Claude가 답하고, 다시 사람이 피드백을 주는 방식이죠.

Headless 모드는 사람 없이 Claude Code를 자동으로 실행하는 방식입니다. 스크립트나 CI/CD 파이프라인에서 Claude Code를 프로그램처럼 호출할 수 있습니다.

Headless = 사람 없이 자동 실행

이전에는 "headless mode"라고 불렸지만, 공식적으로는 Agent SDK CLI라고도 합니다. -p 플래그와 모든 CLI 옵션은 동일하게 작동합니다.

언제 사용하나요?

상황	예시
CI/CD 파이프라인	PR이 열릴 때마다 자동으로 코드 리뷰
자동화 스크립트	매일 밤 코드 품질 리포트 생성
배치 처리	여러 파일을 한꺼번에 마이그레이션
반복 작업	테스트 실패 시 자동 수정 시도

기본 사용법

-p (또는 --print) 플래그를 붙이면 비대화형(non-interactive) 모드로 실행됩니다.

가장 간단한 형태

claude -p "이 프로젝트가 무엇을 하는지 설명해줘"

도구 권한 허용하기

Claude가 파일을 읽고 수정할 수 있도록 도구를 허용합니다:

claude -p "auth.py의 버그를 찾아서 수정해줘" --allowedTools "Read,Edit,Bash"

JSON 출력 받기

스크립트에서 결과를 파싱하기 쉽도록 JSON 형식으로 출력할 수 있습니다:

claude -p "이 프로젝트를 요약해줘" --output-format json

출력 형식 옵션:

text (기본값): 일반 텍스트
json: JSON 구조체로 결과 반환 (세션 ID, 메타데이터 포함)
stream-json: 실시간 스트리밍 JSON

실용적인 예시: 자동 커밋

claude -p "스테이징된 변경 사항을 검토하고 적절한 커밋 메시지로 커밋해줘" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

대화 이어가기

# 첫 번째 요청
claude -p "이 코드베이스의 성능 문제를 검토해줘"

# 이전 대화 이어서
claude -p "이제 데이터베이스 쿼리에 집중해줘" --continue

GitHub Actions 연동

GitHub Actions는 PR 생성, 코드 푸시, 이슈 등록 등 GitHub 이벤트에 반응하여 자동으로 작업을 실행하는 서비스입니다. Claude Code를 여기에 연동하면 AI 기반 자동화가 가능합니다.

공식 액션 소개

Anthropic이 공식으로 제공하는 GitHub Action이 있습니다:

저장소: github.com/anthropics/claude-code-action
버전: anthropics/claude-code-action@v1

빠른 시작

Claude Code 터미널에서 다음 명령어를 실행하면 설정을 자동으로 안내해줍니다:

/install-github-app

저장소 관리자 권한이 필요합니다.

수동 설정 방법

Claude GitHub 앱 설치: github.com/apps/claude에서 저장소에 앱을 설치합니다.
API 키 등록: 저장소 Settings → Secrets에 ANTHROPIC_API_KEY를 추가합니다.
워크플로우 파일 추가: .github/workflows/ 폴더에 YAML 파일을 만듭니다.

예시 1: @claude 멘션으로 PR 리뷰 자동화

PR 댓글이나 이슈에 @claude를 멘션하면 Claude가 자동으로 응답합니다.

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # @claude 멘션에 자동으로 응답

사용 예시:

@claude 이 PR의 보안 취약점을 검토해줘
@claude 이 함수에 엣지 케이스가 있는지 확인해줘
@claude 이 이슈를 기반으로 기능을 구현해줘

예시 2: PR이 열릴 때 자동 코드 리뷰

name: 코드 리뷰
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "/review"
          claude_args: "--max-turns 5"

예시 3: 스케줄 기반 코드 분석

name: 일일 리포트
on:
  schedule:
    - cron: "0 9 * * *"  # 매일 오전 9시

jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "어제의 커밋과 열린 이슈를 요약해줘"
          claude_args: "--model sonnet"

워크플로우 파라미터 설명

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}  # 필수
    prompt: "작업 지시사항"        # 선택 (없으면 @claude 멘션에 반응)
    claude_args: "--max-turns 10"  # 선택 (추가 CLI 인자)

파라미터	설명	필수 여부
`anthropic_api_key`	Anthropic API 키	필수
`prompt`	Claude에게 전달할 지시사항	선택
`claude_args`	추가 CLI 인자 (`--max-turns`, `--model` 등)	선택
`trigger_phrase`	트리거 구문 (기본값: `@claude`)	선택

GitLab CI/CD 연동 (간략)

GitLab을 사용한다면 .gitlab-ci.yml에 Claude Code 작업을 추가할 수 있습니다.

GitLab 연동은 현재 베타 단계입니다.

stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
  before_script:
    - apk add --no-cache git curl bash
    - curl -fsSL https://claude.ai/install.sh | bash
  script:
    - claude -p "${AI_FLOW_INPUT:-'변경 사항을 검토하고 개선사항을 제안해줘'}"
      --permission-mode acceptEdits
      --allowedTools "Bash Read Edit Write"

GitLab CI/CD 변수에 ANTHROPIC_API_KEY를 등록하는 것을 잊지 마세요.

⚠️ 비용 주의사항

자동화는 토큰 소모가 매우 큽니다.

CI/CD 파이프라인은 사람의 감독 없이 실행되므로 비용이 예상보다 빠르게 쌓일 수 있습니다.
--max-turns 옵션으로 최대 반복 횟수를 제한하세요.
워크플로우에 타임아웃을 설정하세요.
불필요한 트리거를 줄이세요.

claude_args: "--max-turns 5 --model sonnet"

API 비용 외에 GitHub Actions 실행 시간 비용도 발생합니다 (GitHub Actions 무료 한도를 초과할 경우).

보안 주의사항

API 키를 코드에 직접 넣지 마세요. 항상 GitHub Secrets를 사용하세요.

# 올바른 방법
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

# 절대 하지 말 것
anthropic_api_key: "sk-ant-api03-..."

Claude의 제안을 머지하기 전에 항상 검토하세요.
액션 권한은 필요한 것만 허용하세요.

입문자에게

이 기능은 지금 당장 필요하지 않습니다.

Headless 모드와 GitHub Actions 연동은 Claude Code를 어느 정도 익힌 후에 도입하는 것이 좋습니다. 기본 사용법, CLAUDE.md 설정, 그리고 MCP 연동을 먼저 익히고 나서 자동화를 고려하세요.

지금은 "이런 것도 가능하구나"라고 알아두는 것으로 충분합니다.

핵심 정리

Headless 모드: claude -p "작업내용" --output-format json
GitHub Actions: anthropics/claude-code-action@v1
트리거: @claude 멘션 또는 자동 프롬프트
비용 제어: --max-turns, 타임아웃, 모델 선택
보안: API 키는 반드시 Secrets 사용

다음 단계 & 리소스

고급

CC101을 마친 후 더 깊이 배울 수 있는 리소스와 학습 경로를 안내합니다.

16. 다음 단계 & 리소스

CC101을 마친 당신에게. 이제 진짜 시작입니다.

여기까지 오셨군요

Claude Code의 기초부터 고급 자동화까지 전 과정을 완주하셨습니다. 쉽지 않은 여정이었지만, 이제 당신은 AI 기반 개발 도구를 실제로 활용할 수 있는 기반을 갖췄습니다.

잠깐 돌아보면, 이런 것들을 배웠습니다:

Claude Code가 무엇이고 어떻게 작동하는지
설치와 인증 설정
CLAUDE.md로 프로젝트 맞춤 설정
기본 명령어와 워크플로우
MCP로 외부 도구 연결
Hooks와 Skills로 자동화
플러그인 생태계 탐색
비용 관리와 최적화
Headless 모드와 CI/CD 연동

이 지식은 단순히 도구 하나를 배운 것이 아닙니다. AI와 협업하는 새로운 개발 방식을 익힌 것입니다.

다음 학습 경로

입문 완료 (지금 여기)

✅ Claude Code 설치 & 인증
✅ CLAUDE.md 작성
✅ 기본 명령어 (/help, /cost, /compact, /model)
✅ 파일 읽기, 코드 수정, 테스트 실행
✅ 플러그인 기본 사용

중급 목표

MCP(Model Context Protocol) 설정

MCP를 통해 Claude Code를 외부 서비스와 연결할 수 있습니다.

# MCP 서버 추가
claude mcp add

고급 목표

Skills 제작

자주 쓰는 작업을 재사용 가능한 Skills로 만듭니다.

# .claude/skills/fix-issue/SKILL.md
---
name: fix-issue
description: GitHub 이슈를 분석하고 수정
---
다음 GitHub 이슈를 분석하고 수정해줘: $ARGUMENTS

1. gh issue view로 이슈 세부사항 확인
2. 관련 파일 검색
3. 수정 사항 구현
4. 테스트 작성 및 실행
5. PR 생성

Agent Teams 활용

여러 Claude 인스턴스를 동시에 실행해 복잡한 작업을 병렬로 처리합니다.

# Agent Teams 활성화 (환경변수 설정 필요)
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

비용이 많이 들 수 있으므로 신중하게 사용하세요.

CI/CD 완전 자동화

섹션 15에서 배운 GitHub Actions를 실제 프로젝트에 적용합니다.

# 예시: 모든 PR에 자동 코드 리뷰
on:
  pull_request:
    types: [opened, synchronize]

공식 리소스

공식 문서

리소스	URL
공식 문서 (영어)	docs.anthropic.com/en/docs/claude-code
GitHub 저장소	github.com/anthropics/claude-code
공식 플러그인	github.com/anthropics/claude-plugins-official
Anthropic 콘솔	platform.claude.com

gptaku_plugins 커뮤니티

CC101 제작팀이 운영하는 플러그인 커뮤니티입니다. 실전에서 검증된 플러그인들을 공유합니다.

리소스	URL
GitHub	github.com/fivetaku/gptaku_plugins

이 저장소가 도움이 됐다면 Star 를 눌러주세요! 커뮤니티 성장에 큰 힘이 됩니다.

첫 실전 프로젝트 추천

CC101을 마쳤다면 바로 실전에 뛰어들어 보세요. 아래는 입문자에게 추천하는 프로젝트들입니다.

1. 포트폴리오 사이트 만들기

가장 동기부여가 되는 프로젝트입니다. Claude Code에게 요구사항을 설명하고 전체 웹사이트를 만들어 보세요.

"HTML/CSS/JS로 개발자 포트폴리오 사이트를 만들어줘.
섹션: 소개, 기술 스택, 프로젝트, 연락처.
미니멀하고 다크 테마로 만들어줘."

2. 기존 코드 리팩토링

이미 있는 코드를 Claude Code와 함께 개선해보세요.

"이 파일의 코드를 리뷰하고 개선해줘.
가독성, 성능, 에러 처리에 집중해줘.
@src/utils/dataProcessor.js"

3. 테스트 코드 자동 생성

테스트가 없는 프로젝트에 테스트를 추가하는 것은 Claude Code가 특히 잘하는 작업입니다.

"auth.ts의 모든 함수에 대한 단위 테스트를 작성해줘.
Jest를 사용하고, 엣지 케이스도 포함해줘."

4. 레거시 코드 마이그레이션

오래된 코드를 현대적인 방식으로 변환합니다.

"이 CommonJS 모듈들을 ES Modules로 마이그레이션해줘.
각 파일을 변환하고 테스트로 검증해줘."

막히면 어떻게 하나요?

1단계: 공식 문서 확인

대부분의 답은 공식 문서에 있습니다.

https://docs.anthropic.com/en/docs/claude-code

Claude Code 안에서도 도움을 받을 수 있습니다:

/help

2단계: Claude Code에게 직접 물어보기

Claude Code 자체가 가장 강력한 도움말입니다.

"Claude Code에서 MCP 서버를 추가하는 방법을 알려줘"
"이 에러 메시지의 의미가 뭔지 설명해줘: [에러 내용]"

3단계: 커뮤니티

GitHub Issues: github.com/anthropics/claude-code/issues
gptaku_plugins: github.com/fivetaku/gptaku_plugins

4단계: Anthropic 지원

계정이나 결제 관련 문제는 Anthropic 콘솔에서 지원을 요청하세요.

마지막으로

Claude Code는 빠르게 발전하는 도구입니다. 오늘 배운 것이 몇 달 후에는 달라져 있을 수 있습니다. 중요한 것은 기본 원리를 이해하는 것입니다.

AI와 함께하는 개발은 단순히 코드를 빠르게 짜는 것이 아닙니다. AI의 강점(넓은 지식, 반복 작업, 패턴 인식)과 사람의 강점(판단력, 창의성, 도메인 지식)을 결합하는 새로운 협업 방식입니다.

CC101을 마친 여러분은 그 첫걸음을 내딛었습니다. 앞으로의 여정이 기대됩니다.

빠른 참조 카드

공식 문서:    https://docs.anthropic.com/en/docs/claude-code
GitHub:       https://github.com/anthropics/claude-code
플러그인:     https://github.com/anthropics/claude-plugins-official
커뮤니티:     https://github.com/fivetaku/gptaku_plugins
콘솔:         https://platform.claude.com

다음 목표:
  중급 → MCP 설정, Hooks 커스터마이징, 플러그인 탐색
  고급 → Skills 제작, Agent Teams, CI/CD 완전 자동화

Claude Code란?

Claude Code가 무엇인지, 다른 AI 도구와 어떻게 다른지 알아봅니다.

01. Claude Code란?

터미널에서 실행되는 AI 코딩 어시스턴트 — 코드를 읽고, 파일을 수정하고, 명령을 직접 실행합니다.

한 줄 정의

Claude.ai 웹 vs Claude Code vs Cursor — 핵심 차이

	Claude.ai 웹	Claude Code	Cursor
어디서 쓰나	브라우저	터미널 / 데스크탑 앱 / IDE	IDE (에디터)
파일 직접 수정	불가 (복붙 필요)	가능 (자동)	가능
명령어 실행	불가	가능 (테스트, 빌드 등)	제한적
전체 코드베이스 이해	수동으로 붙여넣어야 함	자동으로 읽음	자동으로 읽음
Git 연동	불가	가능 (커밋, PR 생성)	제한적
가격	구독 포함	구독 포함 또는 API 과금	별도 구독

핵심 차이: Claude.ai 웹은 대화창에서 코드를 보여주기만 합니다. Claude Code는 실제로 파일을 열고, 수정하고, 저장하고, 실행까지 합니다.

CLI(터미널)라서 강력한 이유

Claude Code가 터미널에서 실행되는 것은 단순한 설계 선택이 아닙니다. 터미널은 컴퓨터에서 할 수 있는 모든 것의 관문이기 때문입니다.

Claude Code가 직접 할 수 있는 것들

능력	설명
파일 읽기/쓰기	프로젝트의 모든 파일을 읽고 직접 수정
명령어 실행	테스트 실행, 빌드, 서버 시작 등
검색	파일명, 코드 내용, 정규식으로 코드베이스 탐색
Git 작업	스테이징, 커밋, 브랜치 생성, PR 열기
웹 검색	에러 메시지 검색, 문서 확인
코드 인텔리전스	타입 에러 감지, 정의로 이동, 참조 찾기

실제로 어떻게 작동하나? (예시)

예시 1: 버그 수정 요청

사용자: "테스트가 실패하는데 고쳐줘"

Claude Code가 하는 일:
1. 테스트 스위트 실행 → 실패 항목 확인
2. 에러 로그 읽기
3. 관련 소스 파일 검색
4. 파일 내용 읽고 코드 이해
5. 파일 수정 (버그 패치)
6. 테스트 다시 실행 → 통과 확인

예시 2: 새 기능 추가 요청

사용자: "로그인 폼에 입력값 검증 기능 추가해줘"

Claude Code가 하는 일:
1. 프로젝트 구조 파악
2. 기존 폼 코드 찾기
3. 검증 로직 작성 및 파일에 직접 삽입
4. 관련 테스트 작성
5. Git 커밋 메시지 작성 후 커밋

어떤 사람에게 맞는가?

Claude Code가 잘 맞는 사람

유형	이유
바이브코더	코드 작성보다 방향 설정에 집중하고 싶은 개발자
비개발자 창업자	아이디어를 실제 코드로 구현하고 싶은데 개발 지식이 부족한 분
입문 개발자	코드를 배우면서 동시에 실제 프로젝트를 진행하고 싶은 분
1인 개발자	혼자서 풀스택 개발을 빠르게 진행해야 하는 분
반복 작업이 많은 개발자	테스트 작성, 린트 수정, 의존성 업데이트 등 반복 작업을 자동화하고 싶은 분

이런 분에게도 추천

"코드가 뭔지는 아는데 직접 짜기는 어려운" 비개발자
터미널이 익숙하지 않지만 배워보고 싶은 분 (데스크탑 앱도 있습니다)
MVP(최소 기능 제품)를 빠르게 만들어야 하는 스타트업 팀원

이런 분에게는 맞지 않을 수 있음

순수하게 글쓰기, 번역, 분석만 필요한 분 → Claude.ai 웹으로 충분
특정 IDE 안에서만 작업하고 싶은 분 → Cursor나 VS Code 확장 고려

어디서 사용할 수 있나?

Claude Code는 터미널에만 국한되지 않습니다.

환경	설명
터미널 (CLI)	가장 강력한 기본 환경
데스크탑 앱	GUI로 diff 확인, 터미널 불필요
VS Code / Cursor 확장	에디터 안에서 바로 사용
JetBrains 플러그인	IntelliJ, PyCharm 등 지원
웹 브라우저	claude.ai/code 에서 바로 실행

한 줄 요약

Claude Code = "내 프로젝트 폴더에 직접 접근해서 코드를 짜고, 테스트하고, 커밋까지 해주는 AI 개발자"

다음 섹션에서는 어떤 플랜으로 시작하면 좋은지 알아봅니다.

제품군 & 가격

Claude Code를 사용하는 방법과 요금제를 알아봅니다.

02. 제품군 & 가격

Claude Code를 사용하는 방법은 3가지입니다. 입문자라면 Max $100 플랜부터 시작하세요.

Claude Code를 쓰는 방법 3가지

방법 1. Claude.ai 구독 (Pro / Max) — 개인 입문자 추천

방법 2. Anthropic API 직접 사용 — 개발자 / 자동화 목적

방법 3. 엔터프라이즈 클라우드 — 기업 보안 요건이 있는 팀

Amazon Bedrock, Google Vertex AI, Microsoft Foundry 등 기업용 클라우드를 통해 Claude Code를 사용합니다. 데이터가 회사 클라우드 안에 머뭅니다.

Pro vs Max 플랜 비교

아래 가격은 2025년 공식 기준입니다. 최신 가격은 claude.com/pricing에서 확인하세요.

	Pro	Max (5x)	Max (20x)
월 가격	$20	$100	$200
사용량 한도	기본	Pro의 5배	Pro의 20배
Claude Code 포함	포함	포함	포함
Claude.ai 웹 포함	포함	포함	포함
적합한 사용자	가끔 사용, 탐색 목적	Claude Code 주 사용자	헤비유저, 대규모 프로젝트

입문자 추천: Max $100

Claude Code를 본격적으로 사용하려면 Max $100 플랜을 권장합니다. 그 이유:

Pro($20)는 사용량 한도가 빠르게 차서 Claude Code를 집중적으로 쓰기 어렵습니다.
API 직접 사용은 토큰 과금 방식이라 예상치 못한 비용이 발생할 수 있습니다.
Max $100는 하루 평균 사용량 기준으로 대부분의 개인 개발자에게 충분합니다.

공식 문서에 따르면, API 사용자의 평균 비용은 개발자 1인당 하루 약 $6, 월 $100~$200 수준입니다 (사용 강도에 따라 차이 있음).

비용 구조 설명

구독 플랜 (Pro / Max)

월정액 결제 → 정해진 사용량 한도 내에서 자유롭게 사용
한도 초과 시 → 추가 응답 제한 (추가 과금 없음)

토큰 수를 신경 쓸 필요 없음
한도 도달 시 일정 시간 후 리셋

API 직접 사용

사용한 토큰만큼 과금 (입력 토큰 + 출력 토큰)
모델에 따라 단가 다름 (Sonnet < Opus)

/cost 명령어로 현재 세션 비용 확인 가능
자동화/팀 사용 시 Console에서 지출 한도 설정 가능

⚠️ 비용 주의사항

API 사용 시 주의할 점

⚠️ API 사용은 사용한 만큼 청구됩니다.

대형 프로젝트에서 장시간 작업하면 토큰이 빠르게 소모됩니다.
Agent Team(여러 AI를 동시에 실행) 기능은 토큰 소모가 약 7배 많습니다.
백그라운드 작업(대화 요약 등)에도 소량의 토큰이 사용됩니다.

비용 절감 팁

방법	설명
작업 사이에 `/clear` 실행	이전 대화 컨텍스트를 지워 토큰 절약
Sonnet 모델 우선 사용	Opus보다 저렴하고 대부분 작업에 충분
명확한 요청	"이 코드베이스 전체 개선해줘" 대신 특정 파일/함수 지정
MCP 서버 최소화	사용하지 않는 연결은 비활성화

어떤 플랜으로 시작할까?

처음 써보고 싶다       → Pro ($20) 로 체험
본격적으로 쓰고 싶다   → Max $100 (강력 추천)
팀/자동화 목적         → API 또는 엔터프라이즈
보안 요건이 있는 기업  → Bedrock / Vertex / Foundry

요금 페이지

최신 가격 및 플랜 비교: https://claude.com/pricing

설치 & 인증

Claude Code를 설치하고 인증하는 방법을 알아봅니다.

03. 설치 & 인증

터미널에서 명령어 하나로 설치, 브라우저에서 로그인하면 끝입니다.

설치 전 확인사항

지원 운영체제

OS	지원 버전
macOS	13.0 이상
Linux	Ubuntu 20.04+, Debian 10+, Alpine Linux 3.19+
Windows	Windows 10 (1809+) 또는 Windows Server 2019+

하드웨어 요구사항

RAM: 4GB 이상
인터넷 연결 필수

Node.js가 필요한가요?

아닙니다. Claude Code는 네이티브(Native) 설치 방식을 사용합니다. Node.js를 따로 설치할 필요가 없습니다.

⚠️ npm 설치는 deprecated(구식)입니다. 예전에는 npm install -g @anthropic-ai/claude-code로 설치했지만, 지금은 공식적으로 아래 방법을 권장합니다. npm 방식은 사용하지 마세요.

설치 방법

macOS / Linux / WSL (Windows Subsystem for Linux)

터미널을 열고 아래 명령어를 붙여넣으세요:

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

또는 Homebrew를 사용한다면:

brew install --cask claude-code

Windows

방법 1 — PowerShell 사용 (권장):

irm https://claude.ai/install.ps1 | iex

방법 2 — WinGet 사용:

winget install Anthropic.ClaudeCode

방법 3 — CMD 사용:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Windows에서 로컬 세션을 사용하려면 Git for Windows가 설치되어 있어야 합니다.

Alpine Linux 추가 패키지

apk add libgcc libstdc++ ripgrep

설치 후 인증 (로그인)

설치가 완료되면 터미널에서 아래 명령어를 실행하세요:

claude

인증 흐름 요약

터미널에서 claude 실행
       ↓
브라우저 자동 오픈 (OAuth 페이지)
       ↓
Claude.ai 계정으로 로그인
       ↓
터미널로 자동 복귀 → 인증 완료

자격 증명 보안

macOS: API 키와 OAuth 토큰은 **macOS Keychain(암호화 저장소)**에 안전하게 저장됩니다.
재로그인이 필요한 경우: claude 실행 후 /login 입력

첫 실행 확인

설치와 인증이 완료되었는지 확인하려면:

claude --version

버전 번호가 출력되면 정상 설치된 것입니다. 또는 설치 진단을 위해:

claude doctor

이 명령어로 설치 타입, 버전, 환경 상태를 한 번에 확인할 수 있습니다.

자동 업데이트

수동으로 업데이트하려면:

claude update

흔한 설치 문제 & 해결법

문제 1: `curl: command not found` (curl이 없다는 오류)

원인: curl이 설치되어 있지 않은 경우 (드물지만 일부 Linux 환경).

해결법:

# Ubuntu/Debian
sudo apt-get install curl

# Alpine
apk add curl

이후 설치 명령어 다시 실행.

문제 2: `claude: command not found` (설치 후에도 명령어를 못 찾는 경우)

원인: 설치 경로가 셸의 PATH에 등록되지 않은 경우.

해결법:

# 현재 셸 세션에 PATH 즉시 반영
source ~/.bashrc
# 또는 zsh 사용자라면
source ~/.zshrc

그래도 안 되면 터미널을 완전히 닫고 다시 열기.

문제 3: Windows에서 Git이 없다는 오류

원인: 로컬 세션 실행에 Git이 필요합니다.

해결법: git-scm.com에서 Git for Windows 설치 후 재시도.

다음 단계

설치와 인증이 완료되었다면, 프로젝트 폴더로 이동해서 바로 시작해 보세요:

cd 내-프로젝트-폴더
claude

Claude Code가 프로젝트를 분석하고 무엇을 도와드릴지 기다립니다.

플러그인 설치

한국어 추천

gptaku_plugins 등 유용한 플러그인을 설치하고 활용합니다.

04. 플러그인 추천 설치

Claude Code의 기능을 확장하는 플러그인을 설치해봅시다.

플러그인이란?

Claude Code는 기본 기능만으로도 충분히 강력하지만, **플러그인(Plugin)**을 설치하면 더 많은 것을 할 수 있습니다.

플러그인 하나에는 다음 요소들이 들어있을 수 있습니다:

구성 요소	설명
Skills (스킬)	`/플러그인명:명령어` 형태의 커스텀 명령어
Agents (에이전트)	특정 역할을 수행하는 AI 에이전트
Hooks (훅)	파일 저장, 명령 실행 시 자동으로 동작하는 이벤트 핸들러
MCP 서버	GitHub, Figma 등 외부 서비스 연동

공식 플러그인 마켓플레이스

Anthropic이 운영하는 공식 마켓플레이스(claude-plugins-official)는 Claude Code를 시작하면 자동으로 사용 가능한 상태입니다.

Claude Code 안에서 /plugin 을 입력하면 Discover 탭에서 바로 공식 플러그인들을 둘러볼 수 있습니다.

공식 마켓에서 플러그인 설치하기

/plugin install 플러그인이름@claude-plugins-official

공식 마켓에서 제공하는 주요 플러그인 카테고리

카테고리	대표 플러그인	설명
코드 인텔리전스	`typescript-lsp`, `pyright-lsp`	타입 오류 실시간 감지, 코드 탐색
외부 서비스 연동	`github`, `figma`, `notion`	외부 서비스를 Claude와 연결
개발 워크플로	`commit-commands`, `pr-review-toolkit`	Git 커밋, PR 리뷰 자동화
출력 스타일	`explanatory-output-style`	Claude 응답 방식 커스터마이징

gptaku_plugins — 한국 입문자 전용 플러그인 모음

GitHub: https://github.com/fivetaku/gptaku_plugins

포함된 플러그인

플러그인 이름	역할	사용 예시
docs-guide	라이브러리 공식 문서 기반으로 정확한 답변 제공. Claude가 최신 공식 문서를 참고해 할루시네이션 없이 답변	`/docs-guide:explain React hooks`
바르다 깃선생 (git-teacher)	비개발자를 위한 Git 온보딩 가이드. "커밋이 뭐야?"부터 시작해서 실무 Git 워크플로우까지 단계별 안내	`/git-teacher:what-is-commit`
바선생 (vibe-sunsang)	바이브코더 전용 AI 멘토. 코드를 몰라도 아이디어를 제품으로 만들 수 있도록 격려하고 안내	`/vibe-sunsang:help`

설치 방법

1단계: 마켓플레이스 추가 및 플러그인 설치

Claude Code 안에서 다음 명령어를 입력하세요:

/plugin install https://github.com/fivetaku/gptaku_plugins

또는 마켓플레이스를 먼저 추가하고 설치할 수도 있습니다:

# 마켓플레이스 추가
/plugin marketplace add fivetaku/gptaku_plugins

# 이후 Discover 탭에서 원하는 플러그인 선택하여 설치
/plugin

2단계: 설치 확인

설치된 플러그인 목록을 확인하세요:

/plugin list

또는 /plugin 을 입력 후 Installed 탭으로 이동하면 설치된 플러그인 목록을 볼 수 있습니다.

3단계: 플러그인 사용해보기

설치가 완료되면 바로 사용할 수 있습니다:

# git-teacher 사용 예시
/git-teacher:what-is-commit

# docs-guide 사용 예시
/docs-guide:explain useState

# vibe-sunsang 멘토에게 도움 요청
/vibe-sunsang:help

플러그인 관리

명령어	설명
`/plugin`	플러그인 매니저 열기 (Discover/Installed/Marketplaces/Errors 탭)
`/plugin list`	설치된 플러그인 목록 확인
`/plugin disable 플러그인명`	플러그인 임시 비활성화
`/plugin enable 플러그인명`	비활성화된 플러그인 다시 활성화
`/plugin uninstall 플러그인명`	플러그인 완전 삭제

⭐ CC101이 도움이 됐다면 Star 부탁드려요!

이 가이드가 도움이 됐다면, GitHub에서 Star를 눌러주세요.

Star 하나가 이 가이드를 계속 발전시키는 큰 힘이 됩니다.

→ CC101 GitHub에서 Star 누르기

어렵지 않아요. 링크 클릭 후 오른쪽 상단의 ⭐ Star 버튼만 누르면 됩니다!

다음 단계

플러그인 설치를 완료했다면, Claude Code가 어떻게 작동하는지 핵심 개념을 이해해봅시다.

→ 05. 핵심 개념 이해하기

핵심 개념

Context, Tools, Permissions, Memory, Session 등 핵심 개념을 이해합니다.

05. 핵심 개념 이해하기

Claude Code가 어떻게 작동하는지 알면, 더 잘 사용할 수 있습니다.

Claude Code는 어떻게 작동하나요?

이 과정을 에이전트 루프(Agentic Loop) 라고 합니다.

여러분의 지시
     ↓
1. 상황 파악 (Context 수집)
   - 파일 읽기, 코드 검색, 현재 상태 파악
     ↓
2. 행동 (Action)
   - 파일 수정, 명령어 실행, 웹 검색
     ↓
3. 결과 확인 (Verify)
   - 테스트 실행, 오류 확인, 다시 수정
     ↓
작업 완료 (또는 1로 돌아가서 반복)

예를 들어 "테스트가 실패하는 버그를 고쳐줘"라고 하면 Claude Code는:

테스트를 실행해서 어떤 오류인지 확인
관련 소스 파일을 찾아서 읽음
코드를 수정
다시 테스트를 실행해서 통과하는지 확인

이 모든 과정을 자동으로 수행합니다.

핵심 개념 5가지

1. Context (컨텍스트) — Claude의 작업 기억

# 컨텍스트 현황 확인
/context

# 대화 압축 (오래된 내용 요약)
/compact

# 특정 주제에 집중해서 압축
/compact API 변경 사항에 집중해서 압축해줘

팁: 자주 참조해야 할 중요한 규칙이나 정보는 CLAUDE.md에 써두면, 매번 컨텍스트를 차지하지 않고도 Claude가 기억합니다.

2. Tools (도구) — Claude가 실제로 할 수 있는 일

Claude Code는 대화만 하는 게 아닙니다. 실제로 여러 **도구(Tools)**를 사용해서 작업을 수행합니다.

도구 종류	Claude가 할 수 있는 일
파일 작업	파일 읽기, 코드 편집, 새 파일 생성, 파일 이름 변경
검색	파일 패턴으로 찾기, 정규식으로 내용 검색, 코드베이스 탐색
실행	셸 명령어 실행, 서버 시작, 테스트 실행, Git 사용
웹	웹 검색, 공식 문서 조회, 오류 메시지 검색
코드 분석	편집 후 타입 오류 감지, 정의로 이동, 참조 찾기

3. Permissions (권한) — 무엇을 허용할지 설정

Claude Code는 강력한 도구인 만큼, 무엇을 허용할지 직접 제어할 수 있습니다.

파일 읽기는 기본적으로 허용되지만, 파일 수정이나 셸 명령어 실행은 여러분의 확인을 요청합니다.

권한 규칙은 크게 세 가지입니다:

규칙	설명
Allow (허용)	묻지 않고 자동으로 실행
Ask (확인 요청)	실행 전에 승인 여부를 물어봄
Deny (거부)	절대 실행하지 않음

# 권한 설정 보기 및 관리
/permissions

우선순위: Deny > Ask > Allow 순으로 적용됩니다. 거부 규칙이 항상 최우선입니다.

4. Memory (메모리) — CLAUDE.md로 프로젝트 기억시키기

CLAUDE.md는 Claude에게 주는 지시서라고 생각하면 됩니다.

파일 위치	적용 범위
`./CLAUDE.md`	현재 프로젝트에만 적용 (팀 공유 가능)
`~/.claude/CLAUDE.md`	내 모든 프로젝트에 적용 (전역 설정)
`./CLAUDE.local.md`	나만의 프로젝트별 설정 (git에 올라가지 않음)

CLAUDE.md에 대한 자세한 내용은 06. CLAUDE.md 완전 정복 에서 다룹니다.

5. Session (세션) — 대화의 시작과 끝

세션은 Claude Code를 시작해서 종료하기까지의 하나의 작업 단위입니다.

새 세션을 시작하면 이전 대화 내용은 없어집니다 (CLAUDE.md는 유지)
세션 중에 한 작업들은 저장됩니다

# 가장 최근 세션 이어서 시작
claude --continue

# 이전 세션 목록에서 선택해서 재개
claude --resume

# 다른 방향을 시도해보기 위해 세션 복사 (포크)
claude --continue --fork-session

"왜 가끔 멈추거나 확인을 요청하나요?"

Claude Code가 작업 중에 멈추고 확인을 요청하는 건 의도된 안전 장치입니다.

초보자가 알아야 할 권한 모드 3가지

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

모드	동작 방식	언제 쓰나요?
Default (기본 모드)	파일 수정과 셸 명령어 실행 전에 확인을 요청	처음 사용하거나 중요한 작업을 할 때
Auto-Accept (자동 수락)	파일 수정은 자동으로 허용, 셸 명령어는 여전히 확인 요청	빠르게 코딩 작업을 진행할 때
Plan Mode (계획 모드)	파일을 읽고 분석만 하고, 아무것도 수정하지 않음	먼저 계획을 검토하고 싶을 때

모드 전환 방법

# 터미널에서 Shift+Tab을 누르면 모드가 순환됩니다
# Default → Auto-Accept → Plan Mode → Default → ...

# 또는 Plan Mode로 바로 진입
/plan

모드 비교 예시

"모든 JavaScript 파일에서 console.log를 삭제해줘"라고 했을 때:

Default 모드:
  → 각 파일 수정 전마다 "이 파일을 수정해도 될까요?" 확인

Auto-Accept 모드:
  → 파일은 자동으로 수정, 명령어(예: git commit)는 확인 요청

Plan Mode:
  → "어떤 파일의 몇 번째 줄을 수정할 예정입니다"만 보여주고 실제 수정은 안 함

추천: 처음에는 Default 모드로 시작해서 Claude Code가 무엇을 하는지 파악하고, 익숙해지면 Auto-Accept 모드로 전환하세요.

체크포인트: 실수해도 되돌릴 수 있어요

Claude Code는 파일을 수정하기 전에 자동으로 스냅샷을 저장합니다.

실수로 잘못 수정됐다면:

Esc 키를 두 번 연속으로 눌러서 이전 상태로 되돌리기
또는 Claude에게 "방금 한 것 취소해줘"라고 요청

다음 단계

Claude Code의 장기 기억인 CLAUDE.md를 마스터해봅시다.

→ 06. CLAUDE.md 완전 정복

CLAUDE.md 완전 정복

핵심

Claude의 장기 기억, CLAUDE.md 파일 작성법과 활용법을 마스터합니다.

06. CLAUDE.md 완전 정복

Claude Code의 장기 기억을 설정하는 가장 중요한 파일, CLAUDE.md를 마스터해봅시다.

CLAUDE.md가 뭔가요?

Claude Code는 세션이 끝나면 대화 내용을 잊어버립니다. 다음에 다시 시작하면 처음 만난 사이처럼 아무것도 모릅니다.

CLAUDE.md는 이 문제를 해결합니다.

Claude Code를 시작할 때마다 CLAUDE.md 파일을 자동으로 읽어서, 프로젝트에 대한 맥락과 규칙을 기억한 채로 작업을 시작합니다.

CLAUDE.md는 Claude에게 주는 지시서이자 프로젝트 설명서입니다.

사람: "이 프로젝트는 Next.js로 만들었고, TypeScript를 써야 해.
       탭 대신 스페이스 2칸을 사용하고, 한국어로 커밋 메시지를 써줘."

→ 이걸 매번 말하는 대신, CLAUDE.md에 한 번 써두면 영원히 기억합니다.

어디에 만드나요?

CLAUDE.md 파일의 위치에 따라 적용 범위가 달라집니다.

파일 위치	적용 범위	팀 공유 여부
`./CLAUDE.md`	현재 프로젝트	✅ Git으로 팀 공유 가능
`./.claude/CLAUDE.md`	현재 프로젝트 (숨김 폴더)	✅ Git으로 팀 공유 가능
`./CLAUDE.local.md`	현재 프로젝트 (나만)	❌ .gitignore에 자동 추가
`~/.claude/CLAUDE.md`	내 모든 프로젝트 (전역)	❌ 나만 적용

가장 일반적인 위치: 프로젝트 루트 디렉토리의 CLAUDE.md

# 프로젝트 폴더에서 CLAUDE.md 생성
touch CLAUDE.md

# 또는 Claude Code가 자동으로 만들어주게 하기
/init

/init 명령어를 실행하면 Claude Code가 현재 프로젝트를 분석해서 CLAUDE.md 초안을 자동으로 생성해줍니다.

무엇을 써야 하나요?

CLAUDE.md에 정해진 형식은 없습니다. 마크다운으로 자유롭게 작성하면 됩니다. 다음 항목들을 포함하면 특히 효과적입니다.

필수 항목

1. 프로젝트 설명

Claude가 이 프로젝트가 무엇인지 파악할 수 있도록 짧게 설명합니다.

## 프로젝트 개요
이 프로젝트는 소상공인을 위한 재고 관리 웹앱입니다.
Next.js 14 + TypeScript + Supabase로 구성되어 있습니다.

2. 기술 스택

어떤 언어, 프레임워크, 라이브러리를 쓰는지 명시합니다.

## 기술 스택
- **프론트엔드**: Next.js 14 (App Router), TypeScript, Tailwind CSS
- **백엔드**: Next.js API Routes
- **데이터베이스**: Supabase (PostgreSQL)
- **패키지 매니저**: pnpm (npm 사용 금지)

3. 코딩 스타일 / 규칙

코드 스타일, 네이밍 규칙, 주석 언어 등을 지정합니다.

## 코딩 규칙
- 들여쓰기: 스페이스 2칸 (탭 사용 금지)
- 따옴표: 작은따옴표('') 사용
- 컴포넌트 파일명: PascalCase (예: UserCard.tsx)
- 함수명: camelCase (예: getUserData)
- 주석은 한국어로 작성
- `any` 타입 사용 금지, 항상 명시적 타입 사용

4. 하지 말아야 할 것들 (금지 사항)

실수를 방지하기 위해 명시적으로 금지 사항을 적어두면 효과적입니다.

## 절대 하지 말 것
- `console.log` 프로덕션 코드에 남기지 말 것
- `npm` 대신 반드시 `pnpm` 사용
- `.env` 파일에 있는 키를 코드에 하드코딩하지 말 것
- `any` 타입 사용 금지
- `pages/` 디렉토리 방식 사용 금지 (App Router만 사용)

5. 자주 쓰는 명령어

매번 명령어를 검색하는 수고를 덜 수 있습니다.

## 자주 쓰는 명령어
- 개발 서버 실행: `pnpm dev`
- 빌드: `pnpm build`
- 테스트: `pnpm test`
- 린트: `pnpm lint`
- 타입 체크: `pnpm type-check`
- DB 마이그레이션: `pnpm db:migrate`

실제 예시: Next.js + TypeScript 프로젝트용 CLAUDE.md 템플릿

아래는 한국 개발환경에 맞게 작성된 실용적인 템플릿입니다. 복사해서 바로 사용하세요.

# 프로젝트 지침

## 프로젝트 개요
[여기에 프로젝트 설명을 1-2줄로 작성하세요]

예시: 소상공인을 위한 재고 관리 SaaS 서비스.
Next.js 14 App Router + TypeScript + Supabase 기반.

---

## 기술 스택
- **프레임워크**: Next.js 14 (App Router)
- **언어**: TypeScript (strict 모드)
- **스타일**: Tailwind CSS
- **DB/백엔드**: Supabase
- **패키지 매니저**: pnpm
- **배포**: Vercel

---

## 디렉토리 구조
\`\`\`
src/
├── app/          # Next.js App Router 페이지
├── components/   # 재사용 가능한 UI 컴포넌트
│   ├── ui/       # 기본 UI 요소 (Button, Input 등)
│   └── features/ # 기능별 컴포넌트
├── lib/          # 유틸리티, Supabase 클라이언트 등
└── types/        # TypeScript 타입 정의
\`\`\`

---

## 코딩 규칙

### 스타일
- 들여쓰기: 스페이스 2칸
- 따옴표: 작은따옴표('')
- 세미콜론: 사용 (항상)
- 줄 끝 공백: 허용 안 함

### 네이밍
- 컴포넌트: PascalCase (UserCard.tsx)
- 함수/변수: camelCase (getUserData)
- 상수: UPPER_SNAKE_CASE (MAX_RETRY_COUNT)
- 타입/인터페이스: PascalCase (UserProfile)

### TypeScript
- `any` 타입 사용 금지
- 모든 함수 반환 타입 명시
- Props 타입은 인터페이스로 정의

---

## 자주 쓰는 명령어
\`\`\`bash
pnpm dev          # 개발 서버 (localhost:3000)
pnpm build        # 프로덕션 빌드
pnpm test         # 테스트 실행
pnpm lint         # ESLint 검사
pnpm type-check   # TypeScript 타입 검사
\`\`\`

---

## 절대 하지 말 것
- `npm` 또는 `yarn` 사용 (반드시 `pnpm` 사용)
- `any` 타입 사용
- `pages/` 디렉토리 방식 사용 (App Router만)
- 환경 변수를 코드에 하드코딩
- `console.log`를 프로덕션 코드에 남기기

---

## Git 커밋 규칙
- 한국어로 커밋 메시지 작성
- 형식: `타입: 변경 내용`
- 타입 예시: feat(기능), fix(수정), docs(문서), style(스타일), refactor(리팩토링)
- 예시: `feat: 사용자 로그인 페이지 추가`

전역 메모리: 모든 프로젝트에 적용하기

~/.claude/CLAUDE.md 파일을 만들면, 내 모든 프로젝트에서 공통으로 적용되는 규칙을 설정할 수 있습니다.

# 전역 CLAUDE.md 편집
nano ~/.claude/CLAUDE.md

전역 CLAUDE.md에 넣기 좋은 내용:

# 전역 설정 (모든 프로젝트 공통)

## 내 개인 선호
- 설명은 항상 한국어로 해줘
- 코드 변경 전에 무엇을 할지 먼저 설명해줘
- 중요한 변경사항은 실행 전에 한 번 더 확인해줘

## 코딩 스타일 (공통)
- 함수는 가능하면 짧게 (20줄 이하)
- 변수명은 의미가 명확하게
- 주석보다는 코드 자체가 읽기 쉽도록

메모리 우선순위

여러 CLAUDE.md 파일이 있을 때, 더 구체적인 파일이 우선합니다.

우선순위 (높음 → 낮음):
1. CLAUDE.local.md (나만의 프로젝트 설정)
2. ./CLAUDE.md (프로젝트 설정)
3. ~/.claude/CLAUDE.md (전역 설정)
4. 조직 관리 CLAUDE.md (회사 설정)

예를 들어, 전역 설정에서 "스페이스 2칸"으로 설정했더라도, 프로젝트의 CLAUDE.md에서 "탭 사용"으로 설정하면 프로젝트 설정이 우선 적용됩니다.

유용한 팁

`/memory` 명령어 활용

세션 중에 CLAUDE.md를 직접 편집하고 싶다면:

/memory

파일 선택기가 열려서 CLAUDE.md를 바로 편집할 수 있습니다.

파일 가져오기 (Import)

CLAUDE.md에서 다른 파일을 참조할 수 있습니다:

# 프로젝트 지침

프로젝트 개요는 @README.md 를 참고하세요.
사용 가능한 npm 스크립트는 @package.json 을 참고하세요.

## 추가 규칙
- Git 워크플로우: @docs/git-guide.md

처음 시작할 때는 CLAUDE.md부터!

새 프로젝트를 시작한다면, 첫 번째 작업으로 CLAUDE.md를 만드세요.

# 프로젝트 시작 시 Claude에게 CLAUDE.md 자동 생성 요청
/init

또는 직접 Claude에게 부탁할 수도 있습니다:

"이 프로젝트는 Next.js 14 + TypeScript + Tailwind로 만들 거야.
 한국어 주석과 커밋 메시지를 사용하고, pnpm을 패키지 매니저로 써.
 이 내용을 바탕으로 CLAUDE.md 파일을 만들어줘."

정리: CLAUDE.md 핵심 요약

항목	내용
역할	Claude의 장기 기억 / 프로젝트 지시서
위치	프로젝트 루트의 `CLAUDE.md`
전역 설정	`~/.claude/CLAUDE.md`
자동 생성	`/init` 명령어 사용
편집	`/memory` 명령어 또는 일반 텍스트 편집기
형식	자유로운 마크다운

CLAUDE.md 하나로 매번 설명하는 수고를 없애고, Claude Code를 진짜 팀원처럼 만들어보세요.

다음 단계

기본 설정을 마쳤습니다. 이제 Claude Code를 실전에서 활용해봅시다!

→ 07. 실전 활용 예시 (준비 중)

명령어 모음

CLI 명령어, 슬래시 명령어, 키보드 단축키를 한눈에 정리합니다.

07. 명령어 모음

Claude Code를 쓸 때 알아야 할 명령어들을 한눈에 정리했습니다.

명령어 세 가지 종류

Claude Code의 명령어는 크게 세 가지로 나뉩니다.

종류	어디서 입력?	예시
CLI 명령어	터미널 (Claude Code 밖)	`claude`, `claude --version`
슬래시 명령어	대화 중 (Claude Code 안)	`/help`, `/compact`
키보드 단축키	대화 중	`Ctrl+C`, `Shift+Enter`

CLI 명령어 (터미널에서 입력)

Claude Code를 시작하거나 제어하는 명령어입니다. 터미널에서 입력합니다.

기본 실행 명령어

명령어	설명	예시
`claude`	대화형 모드 시작	`claude`
`claude "질문"`	바로 질문하며 시작	`claude "이 프로젝트 설명해줘"`
`claude -p "질문"`	답변만 출력하고 종료 (자동화에 유용)	`claude -p "이 함수 설명해줘"`
`claude -c`	가장 최근 대화 이어서 시작	`claude -c`
`claude --version` 또는 `claude -v`	설치된 버전 확인	`claude -v`
`claude --help`	도움말 보기	`claude --help`
`claude update`	최신 버전으로 업데이트	`claude update`

모델 지정 실행

# 특정 모델로 시작
claude --model claude-opus-4-5

# 또는 짧게
claude --model opus
claude --model sonnet
claude --model haiku

유용한 시작 옵션

# Plan Mode로 시작 (파일 수정 없이 계획만)
claude --permission-mode plan

# 세션 이름으로 이어서 시작
claude --resume 세션이름

# 이전 대화 목록에서 선택해서 이어서 시작
claude --resume

팁: 처음엔 그냥 claude만 입력해서 시작하면 됩니다. 나머지는 필요할 때 배워도 늦지 않습니다.

슬래시 명령어 (대화 중 입력)

Claude Code와 대화하는 도중에 /로 시작하는 명령어를 입력하면 특별한 기능을 사용할 수 있습니다.

자주 쓰는 슬래시 명령어

명령어	설명
`/help`	사용 가능한 명령어 전체 목록 보기
`/compact`	대화 내용 압축 (긴 세션에서 필수!)
`/clear`	대화 초기화 (완전히 새로 시작)
`/cost`	현재 세션에서 사용한 토큰 비용 확인
`/model`	사용 중인 AI 모델 변경
`/permissions`	권한 설정 확인 및 관리
`/memory`	CLAUDE.md 메모리 파일 편집
`/quit` 또는 `/exit`	Claude Code 종료
`/plan`	Plan Mode 진입
`/init`	프로젝트에 CLAUDE.md 파일 생성
`/doctor`	설치 상태 점검
`/stats`	사용량 통계 보기 (구독 사용자용)
`/vim`	Vim 편집 모드 켜기/끄기
`/theme`	색상 테마 변경

슬래시 명령어 사용법

> /compact
→ 대화 내용을 요약해서 컨텍스트를 줄여줍니다

> /compact 코드 변경 사항 위주로 정리해줘
→ 압축 방향을 직접 지정할 수 있습니다

> /model
→ 모델 선택 화면이 나타납니다

팁: 대화창에서 /만 입력하면 사용 가능한 명령어 목록이 자동완성으로 나타납니다.

키보드 단축키

대화 도중 손가락 몇 개로 빠르게 제어할 수 있습니다.

핵심 단축키

단축키	설명
`Ctrl+C`	현재 작업 취소 (Claude가 뭔가 하는 도중에 멈추고 싶을 때)
`Ctrl+D`	Claude Code 종료
`Ctrl+L`	터미널 화면 지우기 (대화 내용은 유지됨)
`Ctrl+R`	이전에 입력한 명령어 검색
`Ctrl+G`	현재 입력 중인 내용을 외부 텍스트 에디터에서 편집
`Ctrl+T`	작업 목록 보기/숨기기

입력 관련 단축키

단축키	설명
`Shift+Enter`	줄바꿈 (긴 지시사항 여러 줄로 입력할 때)
`Option+Enter` (macOS)	줄바꿈 (macOS 기본)
`\` + `Enter`	줄바꿈 (모든 터미널에서 작동)
`↑` / `↓` 화살표	이전/다음 명령어 탐색
`Esc` + `Esc` (두 번)	대화 되감기 (이전 상태로 복원)

모드 전환 단축키

단축키	설명
`Shift+Tab`	Plan Mode ↔ 일반 모드 전환
`Option+P` (macOS) / `Alt+P`	모델 변경
`Option+T` (macOS) / `Alt+T`	확장 사고 모드 켜기/끄기

초보자가 자주 쓰는 명령어 TOP 5

막 시작했다면 이 다섯 개만 외워도 충분합니다.

1. `/compact` — 가장 중요한 명령어

> /compact

2. `Ctrl+C` — 멈추고 싶을 때

Claude가 엉뚱한 방향으로 가고 있을 때, 또는 실수로 위험한 명령을 허가했을 때 즉시 멈춥니다.

3. `/clear` — 새로 시작할 때

> /clear

완전히 다른 주제로 넘어갈 때 사용합니다. 이전 대화 내용이 모두 지워집니다.

4. `Shift+Enter` — 긴 지시사항 입력

한 줄로 다 쓰기 어려운 긴 요청은 Shift+Enter로 줄바꿈하면서 입력하세요.

(Shift+Enter로 여러 줄 입력 예시)
로그인 페이지를 만들어줘.
- 이메일과 비밀번호 필드
- 비밀번호 보기/숨기기 버튼
- 로그인 버튼 (로딩 상태 포함)

5. `/cost` — 비용 확인

> /cost

현재 세션에서 얼마나 썼는지 확인합니다. (API 키 사용자용, 구독 사용자는 /stats 사용)

빠른 참고표

터미널 입력:
  claude              → 시작
  claude -v           → 버전 확인
  claude --help       → 도움말

대화 중 입력:
  /help               → 전체 명령어 목록
  /compact            → 대화 압축 (자주 쓰기!)
  /clear              → 대화 초기화
  /cost               → 비용 확인
  /model              → 모델 변경
  /quit               → 종료

키보드 단축키:
  Ctrl+C              → 작업 취소
  Ctrl+D              → 종료
  Shift+Enter         → 줄바꿈
  ↑↓ 화살표           → 이전 명령어 탐색
  Esc Esc             → 이전 상태로 되감기

초보자 워크플로우

첫 세션부터 효과적인 프롬프트 작성까지 실전 워크플로우를 배웁니다.

08. 초보자 워크플로우

처음 Claude Code를 쓸 때 어떻게 시작하고, 어떻게 작업하면 좋은지 단계별로 안내합니다.

첫 세션 플로우 (Step-by-Step)

처음이라면 이 순서대로 따라해보세요.

Step 1. 프로젝트 폴더로 이동

cd 내프로젝트

Claude Code는 현재 폴더를 기준으로 파일을 읽고 수정합니다. 반드시 작업할 프로젝트 폴더로 먼저 이동하세요.

폴더가 없다면 mkdir 내프로젝트 && cd 내프로젝트로 만들어도 됩니다.

Step 2. Claude Code 시작

claude

터미널에 claude를 입력하고 Enter를 누르면 대화형 모드가 시작됩니다.

Step 3. 프로젝트 파악시키기 (강력 추천)

처음 시작할 때 Claude에게 프로젝트를 파악하게 하거나, CLAUDE.md 파일을 만들어 달라고 요청하세요.

> 이 프로젝트 전체를 파악하고 CLAUDE.md 파일을 만들어줘

또는 기존 프로젝트라면:

> 이 코드베이스 구조를 설명해줘

Step 4. 작업 지시

원하는 작업을 자연어로 지시합니다.

> 로그인 기능을 만들어줘
> 이 코드에서 버그를 찾아줘
> README.md를 한글로 번역해줘

Step 5. 결과 확인 & 피드백

Claude가 파일을 수정하면 변경 내용을 보여줍니다. 마음에 들지 않으면 바로 피드백하세요.

> 좋아, 근데 에러 메시지는 한글로 바꿔줘
> 이 부분은 다르게 해줘 — [설명]

Step 6. 세션 종료

> /quit

또는 Ctrl+D를 누르면 종료됩니다.

효과적인 프롬프트 쓰는 법

구체적으로 말할수록 좋은 결과가 나옵니다

나쁜 예 (모호함)	좋은 예 (구체적)
"코드 고쳐줘"	"login.js의 42번 줄에서 발생하는 TypeError 수정해줘"
"기능 추가해줘"	"사용자가 비밀번호를 잊었을 때 이메일로 재설정 링크를 보내는 기능 추가해줘"
"더 좋게 만들어줘"	"이 함수의 성능을 개선해줘. 현재 1000개 데이터에서 3초 걸리는데 1초 이내로 줄여야 해"
"테스트 만들어줘"	"auth.js의 login 함수에 대한 단위 테스트를 만들어줘. 성공/실패/이메일 형식 오류 케이스 포함"

한 번에 하나씩 요청하기

여러 가지를 한꺼번에 요청하면 Claude가 중간에 방향을 잃을 수 있습니다.

# 비추천
> 로그인 만들고, 회원가입도 추가하고, 비밀번호 찾기도 만들고,
  이메일 인증도 넣고, 소셜 로그인도 추가해줘

# 추천
> 먼저 이메일/비밀번호 로그인 기능만 만들어줘
(완료 후)
> 이제 회원가입 기능 추가해줘

결과물 형태를 명시하기

> 이 코드를 설명해줘           → 설명문으로 답변
> 이 코드를 파일로 저장해줘     → 파일로 저장
> 이 코드를 개선해서 덮어써줘   → 파일 직접 수정
> 버그 목록을 표로 정리해줘     → 표 형식으로 답변

@ 기호로 파일 지정하기

> @src/auth/login.js 이 파일에서 버그 찾아줘
> @README.md 를 보고 프로젝트 구조 파악해줘

일반적인 사용 사례 예시

새 기능 추가

> 사용자 프로필 페이지를 만들어줘.
  - 닉네임, 이메일, 가입일 표시
  - 프로필 사진 업로드 가능
  - 닉네임 수정 기능

버그 수정

> npm test 실행하면 아래 에러가 나는데 고쳐줘:
  TypeError: Cannot read property 'id' of undefined
  at UserService.getUser (src/services/user.js:45)

코드 리뷰 요청

> @src/payment/ 폴더의 코드를 리뷰해줘.
  보안 취약점과 개선할 점을 알려줘

코드 설명

> @src/utils/tokenizer.js 이 파일이 뭘 하는 건지 쉽게 설명해줘

테스트 코드 작성

> @src/services/auth.js 의 모든 함수에 대한 테스트를 만들어줘.
  기존 테스트 스타일은 @tests/services/user.test.js 를 참고해

문서화

> @src/api/ 폴더의 모든 함수에 JSDoc 주석 추가해줘

Plan Mode 활용 팁

Plan Mode란? Claude가 파일을 수정하지 않고, 계획만 세우는 모드입니다. 위험한 작업을 하기 전에 먼저 계획을 검토할 수 있습니다.

Plan Mode 켜는 방법

Shift+Tab 두 번 누르기
또는
> /plan

언제 Plan Mode를 쓰나?

여러 파일을 동시에 수정해야 할 때
데이터베이스 마이그레이션처럼 되돌리기 어려운 작업
처음 보는 코드베이스를 수정하기 전
아키텍처 변경처럼 큰 작업

Plan Mode 사용 예시

# Plan Mode로 시작
claude --permission-mode plan

# 또는 대화 중에 전환
> Shift+Tab (두 번)

# 계획 수립 요청
> 인증 시스템을 JWT에서 OAuth2로 마이그레이션하는 계획을 세워줘

# Claude가 계획을 보여주면 검토
# 괜찮으면 일반 모드로 전환 후 실행

작업 전 git commit 습관

Claude Code가 파일을 수정하기 전에 현재 상태를 git에 저장해두면, 실수해도 쉽게 되돌릴 수 있습니다.

git add .
git commit -m "Claude Code 작업 전 백업"

이후 Claude가 수정한 내용이 마음에 들지 않으면:

git diff          # 변경된 내용 확인
git checkout .    # 모든 변경 취소 (주의!)

또는 Claude Code 안에서 Esc + Esc를 눌러 이전 상태로 되감기할 수도 있습니다.

⚠️ 절대 하지 말아야 할 것들

민감 정보 입력 금지

# 절대 금지
> 내 AWS 액세스 키는 AKIAXXXXXXXX 이고...
> DB 비밀번호는 mypassword123 인데...
> 내 개인 SSH 키는 -----BEGIN RSA...

API 키, 비밀번호, 개인 인증서 등은 절대 대화창에 직접 입력하지 마세요. 환경변수나 .env 파일을 사용하세요.

권한 요청 무분별 허용 금지

Claude가 sudo 명령이나 시스템 파일 수정 권한을 요청할 때, 이유를 먼저 파악하세요.

# Claude가 이런 권한을 요청하면 이유를 먼저 물어보기
> 왜 sudo가 필요해? 다른 방법은 없어?

`--dangerously-skip-permissions` 사용 주의

이 옵션은 모든 권한 확인을 건너뜁니다. 격리된 테스트 환경(컨테이너 등)이 아니면 사용하지 마세요.

중요한 작업 전 백업 없이 진행 금지

대규모 리팩토링이나 데이터베이스 마이그레이션 전에는 반드시 git commit이나 백업을 먼저 하세요.

세션 관리 팁

긴 작업은 이름을 붙여 저장

> /rename auth-refactor

나중에 이어서 할 때:

claude --resume auth-refactor

컨텍스트가 길어지면 압축

작업이 길어지면 Claude의 응답이 느려집니다. 주기적으로:

> /compact

한 줄 요약

구체적으로 지시하고 → 한 번에 하나씩 요청하고 → 결과를 확인하고 → 피드백을 반복하세요.

다음 섹션에서는 자주 하는 실수와 해결법을 알아봅니다.

자주 하는 실수 & 해결법

초보자가 자주 겪는 10가지 문제와 해결 방법을 알아봅니다.

09. 자주 하는 실수 & 해결법

초보자가 Claude Code를 쓰면서 자주 겪는 문제 10가지를 Q&A 형식으로 정리했습니다.

Q1. `claude` 명령어를 못 찾는다고 한다 (command not found)

증상

$ claude
zsh: command not found: claude

원인 & 해결법

설치는 됐지만 터미널이 claude 명령어 위치를 모르는 상황입니다.

방법 1: 네이티브 설치 사용 (가장 확실)

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

설치 후 터미널을 완전히 닫고 새로 열어보세요.

방법 2: PATH 확인

# claude가 어디 설치됐는지 확인
which claude

# PATH 확인
echo $PATH

~/.local/bin이 PATH에 없으면 shell 설정 파일(.zshrc 또는 .bashrc)에 추가:

export PATH="$HOME/.local/bin:$PATH"

추가 후 source ~/.zshrc 실행.

방법 3: 설치 상태 점검

claude doctor

Q2. 로그인이 안 된다

증상

브라우저가 열리지 않음
인증 화면에서 멈춤
로그인 후에도 인증 오류

해결법

브라우저 팝업이 안 열릴 때

claude 실행 후 c를 눌러 인증 URL을 복사한 뒤, 브라우저에 직접 붙여넣기 하세요.

로그아웃 후 재인증

# Claude Code 안에서
> /logout

# 또는 인증 파일 직접 삭제
rm -rf ~/.config/claude-code/auth.json
claude

여전히 안 된다면

# 모든 설정 초기화 후 재시작
rm ~/.claude.json
rm -rf ~/.claude/
claude

주의: 이렇게 하면 모든 설정과 세션 기록이 삭제됩니다.

Q3. 너무 느리다 / 응답이 늦다

원인

대화가 길어질수록 Claude가 처리해야 할 내용(컨텍스트)이 쌓여서 느려집니다. 이는 정상적인 동작입니다.

해결법

방법 1: /compact로 컨텍스트 정리 (가장 효과적)

> /compact

대화 내용을 압축해서 속도를 회복합니다.

방법 2: /clear로 초기화

완전히 새로 시작해도 되는 경우:

> /clear

방법 3: 더 빠른 모델로 변경

복잡한 작업이 아니라면 Haiku나 Sonnet이 Opus보다 훨씬 빠릅니다.

> /model

모델 선택 화면에서 변경하세요.

방법 4: MCP 서버 줄이기

불필요한 MCP 서버가 많으면 느려질 수 있습니다.

> /mcp

사용하지 않는 서버를 비활성화하세요.

Q4. 내가 원하는 대로 안 고쳐준다

원인

지시가 모호하거나, Claude가 프로젝트 맥락을 모르거나, 같은 말을 계속 반복해서 Claude가 혼란스러운 경우입니다.

해결법

방법 1: 더 구체적으로 지시하기

# 모호한 지시
> 코드 개선해줘

# 구체적인 지시
> auth.js의 login 함수에서 이메일 유효성 검사가 빠져있어.
  정규식으로 이메일 형식 확인하는 코드를 42번 줄 다음에 추가해줘

방법 2: CLAUDE.md에 규칙 추가

자주 반복되는 요구사항은 프로젝트 규칙으로 저장하세요.

> /memory

또는 CLAUDE.md 파일에 직접 추가:

# 코드 스타일
- 에러 메시지는 항상 한글로 작성
- 함수마다 JSDoc 주석 필수
- var 사용 금지, const/let만 사용

방법 3: 같은 실수가 두 번 반복되면 초기화

> /clear

새로 시작해서 더 명확한 지시로 다시 요청하세요.

Q5. 파일을 수정했는데 실수인 것 같다

해결법

방법 1: Claude Code 안에서 되감기 (가장 빠름)

Esc 키를 두 번 연속으로 누르기
또는
> /rewind

이전 상태로 대화와 코드를 함께 되돌립니다.

방법 2: git으로 복구

# 변경된 내용 확인
git diff

# 특정 파일만 되돌리기
git checkout -- src/auth/login.js

# 모든 변경 취소
git checkout .

방법 3: 작업 전 git commit 습관 들이기

Claude Code로 큰 작업을 시작하기 전에 항상:

git add .
git commit -m "작업 전 백업 $(date +%Y%m%d-%H%M)"

Q6. 갑자기 비용이 많이 나왔다

원인

대화가 너무 길어짐 (컨텍스트가 클수록 토큰 소모 증가)
파일이 많은 프로젝트를 전체 분석 요청
Opus 모델을 계속 사용
에이전트 팀 기능 사용

해결법

현재 비용 확인

> /cost

API 사용자용. 구독 사용자는 /stats로 사용량 확인.

비용 줄이는 방법

/compact 자주 사용해서 컨텍스트 관리
단순 작업은 Sonnet이나 Haiku 사용 (/model로 변경)
큰 파일/폴더 전체를 맥락 없이 읽히지 않기
관련 없는 작업 사이에는 /clear로 초기화

예산 한도 설정 (자동화 사용 시)

claude -p --max-budget-usd 1.00 "질문"

Q7. 권한 요청이 너무 많이 뜬다

상황

Claude가 파일을 수정하거나 명령어를 실행할 때마다 허가를 요청합니다.

해결법

방법 1: 자주 쓰는 도구는 항상 허용으로 설정

> /permissions

권한 관리 화면에서 특정 도구를 Always Allow로 설정합니다.

방법 2: 파일 수정을 자동 허용

Shift+Tab을 눌러 Auto-Accept Edit Mode 선택

현재 세션 동안 파일 수정 요청을 자동으로 허용합니다.

방법 3: 각 권한 모드 이해하기

모드	설명	언제 쓰나
기본 모드	첫 사용 시 허가 요청	일반 사용
Plan Mode	파일 수정 불가, 계획만	안전하게 탐색할 때
Auto-Accept	파일 수정 자동 허용	신뢰할 수 있는 작업

--dangerously-skip-permissions 사용 주의

Q8. 한글이 깨진다 / 이상한 문자가 나온다

원인

터미널이 UTF-8 인코딩을 사용하지 않을 때 발생합니다.

해결법

macOS / Linux

shell 설정 파일(.zshrc 또는 .bashrc)에 추가:

export LANG=ko_KR.UTF-8
export LC_ALL=ko_KR.UTF-8

추가 후 source ~/.zshrc 실행.

터미널 앱 설정 확인

iTerm2: Preferences → Profiles → Terminal → Character Encoding → UTF-8
macOS 기본 터미널: 환경설정 → 프로파일 → 고급 → 문자 인코딩 → Unicode(UTF-8)
VS Code 터미널: 자동으로 UTF-8 사용 (대부분 문제없음)

Windows (WSL)

# WSL에서 실행
sudo locale-gen ko_KR.UTF-8

Q9. 맥락을 잃어버렸다 (세션이 초기화됐다)

상황

Claude가 이전에 한 작업을 기억하지 못함
세션이 갑자기 끊김
터미널을 닫았다 다시 열었음

해결법

방법 1: 이전 세션 이어서 시작

# 가장 최근 세션 이어서
claude --continue

# 세션 목록에서 선택
claude --resume

# 이름으로 이어서 (이름을 미리 저장했을 때)
claude --resume auth-refactor

방법 2: 세션에 이름 붙여두기 (예방책)

중요한 작업을 시작할 때:

> /rename 로그인기능-개발

방법 3: CLAUDE.md에 중요 정보 저장

세션이 끊겨도 유지되어야 할 정보는 CLAUDE.md에:

> /memory

# 현재 진행 중인 작업
- 목표: OAuth2 인증 시스템 구현
- 완료: 기본 로그인/로그아웃
- 진행 중: 소셜 로그인 (Google, Kakao)
- 사용 기술: Next.js, Prisma, NextAuth.js

Q10. 코드가 너무 많이 바뀌었다 (예상치 못한 대규모 변경)

상황

"간단히 수정해줘"라고 했는데 Claude가 관련 없는 파일까지 대거 수정하는 경우.

해결법

방법 1: 즉시 멈추기

Claude가 작업 중이면 바로:

Ctrl+C

또는 Esc를 눌러 현재 작업 중단.

방법 2: 이전 상태로 되감기

Esc 두 번 연속
또는
> /rewind

방법 3: git으로 확인 및 복구

# 변경된 파일 목록 확인
git status

# 변경 내용 상세 확인
git diff

# 특정 파일만 복구
git checkout -- 파일경로

# 전부 취소
git checkout .

방법 4: Plan Mode로 먼저 확인 (예방책)

큰 작업 전에는 Plan Mode에서 계획을 먼저 검토하세요.

Shift+Tab (두 번)

또는

claude --permission-mode plan

방법 5: 지시를 더 구체적으로

# 범위를 명확하게 지정
> auth.js 파일의 login 함수만 수정해줘. 다른 파일은 건드리지 마

# 금지 사항 명시
> 리팩토링은 하지 말고 버그만 수정해줘

요약: 자주 하는 실수 방지 체크리스트

Claude Code 시작 전:
□ 프로젝트 폴더로 이동했나? (cd 내프로젝트)
□ 중요한 작업이면 git commit 했나?
□ CLAUDE.md에 프로젝트 규칙이 있나?

작업 중:
□ 지시가 충분히 구체적인가?
□ 한 번에 너무 많이 요청하지 않았나?
□ 대화가 길어지면 /compact 사용했나?
□ 뭔가 이상하면 Ctrl+C로 바로 멈췄나?

작업 후:
□ 변경 내용을 확인했나? (git diff)
□ 테스트가 통과하는가?
□ 중요한 세션이면 이름을 저장했나? (/rename)

문제가 해결되지 않으면 Claude Code 안에서 /doctor를 실행해 설치 상태를 점검하거나, /bug를 입력해 Anthropic에 직접 문제를 보고할 수 있습니다.

MCP & 외부 도구 연결

고급

Model Context Protocol로 GitHub, Slack, DB 등 외부 도구를 연결합니다.

10. MCP & 외부 도구 연결

Claude가 GitHub, Slack, DB, 브라우저를 직접 다룰 수 있게 해주는 표준 프로토콜

MCP란?

**MCP(Model Context Protocol)**는 Claude가 외부 도구와 데이터 소스에 연결할 수 있게 해주는 오픈 표준입니다.

비유: MCP는 Claude에게 USB 포트를 달아주는 것과 같습니다. 어떤 도구든 꽂으면 사용할 수 있게 됩니다.

MCP로 없어지는 노가다

MCP 없이는 이런 일들을 직접 해야 합니다:

기존 노가다	MCP 연결 후
JIRA 티켓 내용을 복사해서 Claude에게 붙여넣기	"ENG-4521 이슈 구현해줘" 한 마디로 끝
Sentry 에러 스택트레이스를 수동으로 복사	"지난 24시간 주요 에러 분석해줘"
DB 스키마를 Claude에게 설명하고 쿼리 요청	"users 테이블에서 90일 미접속 유저 찾아줘"
Figma 디자인 보고 직접 코딩	"Figma 최신 디자인대로 이메일 템플릿 업데이트해줘"
PR 내용 복사해서 리뷰 요청	"PR #456 리뷰해줘" 한 마디로 끝

MCP로 할 수 있는 것들

GitHub — PR/이슈 직접 조작

# GitHub MCP 서버 연결
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# 연결 후 이런 요청이 가능해집니다
> "PR #456 검토하고 개선점 제안해줘"
> "방금 발견한 버그 이슈 새로 만들어줘"
> "나에게 할당된 오픈 PR 목록 보여줘"

Sentry — 프로덕션 에러 분석

# Sentry 연결
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# /mcp 명령으로 인증 완료 후
> "지난 24시간 주요 에러가 뭐야?"
> "에러 ID abc123 스택트레이스 보여줘"
> "이 에러들이 어느 배포에서 생겼어?"

PostgreSQL — DB 직접 쿼리

# DB 연결 (읽기 전용 추천)
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

# 연결 후
> "이번 달 총 매출 얼마야?"
> "orders 테이블 스키마 보여줘"
> "90일째 구매 안 한 고객 찾아줘"

Slack — 메시지 읽고 보내기

Notion, Asana, Figma 등

MCP 레지스트리(api.anthropic.com/mcp-registry/docs)에서 수백 가지 MCP 서버를 찾을 수 있습니다.

MCP 서버 설치 방법

방법 1: 원격 HTTP 서버 (권장)

# 기본 문법
claude mcp add --transport http <이름> <URL>

# 예시: Notion 연결
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 인증 헤더가 필요한 경우
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

방법 2: 로컬 stdio 서버

내 컴퓨터에서 실행되는 서버입니다. 시스템 직접 접근이나 커스텀 스크립트에 적합합니다.

# 기본 문법
claude mcp add [옵션] <이름> -- <커맨드> [인자...]

# 예시: Airtable 연결
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

MCP 서버 관리 명령어

# 설정된 서버 목록 보기
claude mcp list

# 특정 서버 상세 확인
claude mcp get github

# 서버 제거
claude mcp remove github

# Claude Code 내에서 상태 확인
/mcp

설정 파일 위치 (스코프)

MCP 서버 설정은 사용 범위에 따라 세 곳에 저장됩니다:

스코프	저장 위치	용도
로컬 (기본값)	`~/.claude.json`	현재 프로젝트에만, 개인 설정
프로젝트	`.mcp.json` (프로젝트 루트)	팀 전체 공유, 버전 관리에 포함
유저	`~/.claude.json`	모든 프로젝트에서 사용

# 팀 공유용 프로젝트 스코프로 추가
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

# 모든 프로젝트에서 쓸 유저 스코프로 추가
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

팀 프로젝트에서는 .mcp.json을 Git에 커밋해서 팀원 모두가 동일한 MCP 서버를 사용할 수 있습니다.

입문자 추천 MCP 3가지

실용성 기준으로 처음 써볼 만한 MCP 서버입니다:

1. GitHub MCP

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

없어지는 노가다: PR 내용 복붙, 이슈 수동 조회, 코드 리뷰 컨텍스트 전달

2. PostgreSQL / DB MCP

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://user:pass@localhost:5432/mydb"

없어지는 노가다: 스키마 설명, 데이터 조회 결과 복붙, SQL 작성 후 직접 실행

3. Sentry MCP

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

없어지는 노가다: 에러 스택트레이스 복붙, 에러 발생 시점 수동 조회

Claude Code 공식 커넥터

Claude.ai 계정으로 Claude Code에 로그인한 경우, claude.ai/settings/connectors에서 설정한 MCP 서버가 Claude Code에 자동으로 연결됩니다.

공식적으로 지원되는 커넥터:

Slack: 채널 메시지 읽기/쓰기
Google Chrome: 브라우저 자동화 (Playwright 기반)

OAuth 인증이 필요한 서버 연결 방법

Sentry, GitHub 같은 클라우드 서버는 OAuth 인증이 필요합니다:

# 1단계: 서버 추가
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 2단계: Claude Code 내에서 인증
> /mcp

# 브라우저 열림 → 로그인 → 완료

인증 토큰은 자동으로 저장되고 갱신됩니다.

MCP 프롬프트를 커맨드로 사용하기

MCP 서버가 프롬프트를 제공하는 경우, Claude Code에서 /mcp__서버명__프롬프트명 형식으로 직접 실행할 수 있습니다:

> /mcp__github__list_prs
> /mcp__github__pr_review 456
> /mcp__jira__create_issue "로그인 버그" high

⚠️ 주의사항

신뢰할 수 없는 MCP 서버를 함부로 설치하지 마세요.

MCP 서버는 Claude를 통해 내 파일 시스템, DB, 외부 서비스에 접근할 수 있습니다
특히 외부 콘텐츠를 가져오는 MCP 서버는 프롬프트 인젝션 위험이 있습니다
Anthropic이 직접 검증한 서버만 공식 MCP 레지스트리에 등록되어 있습니다
출처가 불명확한 서버는 설치 전 소스 코드를 반드시 확인하세요

# 프로젝트 스코프 서버는 팀원들에게 확인 요청이 표시됩니다
# (보안 검토를 위한 안전장치)

한 줄 요약

MCP = Claude에게 외부 세계를 연결하는 플러그인. GitHub, DB, Slack을 Claude가 직접 다루게 해서 "복사-붙여넣기" 노가다를 없앤다.

다음 섹션에서는 Hooks로 Claude Code의 동작을 자동화하는 방법을 배웁니다.

Hooks — 자동화의 핵심

고급

이벤트 기반 자동화 시스템, Hooks를 활용해 Claude Code를 커스터마이즈합니다.

11. Hooks — 자동화의 핵심

"파일 수정할 때마다 포매터 돌려줘", "작업 끝나면 알림 보내줘" — 이런 걸 자동으로 하게 만드는 기능

Hooks란?

Hooks는 Claude Code의 특정 이벤트가 발생할 때 자동으로 실행되는 셸 커맨드입니다.

핵심: Hooks는 "Claude가 알아서 해주면 좋겠다"가 아니라 **"반드시 항상 실행되어야 한다"**는 동작을 위한 것입니다. LLM의 판단이 아니라 결정론적 제어입니다.

Hooks로 없어지는 노가다

기존 노가다	Hooks 설정 후
파일 수정할 때마다 Prettier 수동 실행	파일 수정 후 자동으로 포맷
작업 끝났는지 터미널 계속 확인	완료 시 데스크탑 알림
`.env` 파일 실수로 수정될까 걱정	보호된 파일 수정 시 자동 차단
컨텍스트 압축 후 규칙 재설명	압축 후 핵심 규칙 자동 재주입
실행된 명령어 수동 로그 기록	모든 Bash 명령어 자동 기록

주요 Hook 이벤트

이벤트	발생 시점	주요 용도
`PreToolUse`	도구 실행 직전	위험한 명령어 차단, 검증
`PostToolUse`	도구 실행 직후	자동 포매팅, 로그 기록
`Stop`	Claude가 응답 완료 시	알림 전송, 후처리
`SessionStart`	세션 시작/재개 시	컨텍스트 주입, 초기화
`Notification`	Claude가 알림 보낼 때	데스크탑 푸시 알림
`UserPromptSubmit`	사용자가 프롬프트 제출 시	입력 전처리
`SubagentStart`	서브에이전트 시작 시	에이전트 추적
`SubagentStop`	서브에이전트 종료 시	결과 후처리
`PreCompact`	컨텍스트 압축 전	중요 정보 보존
`SessionEnd`	세션 종료 시	정리 작업

Hook 설정 위치

Hooks는 settings.json의 hooks 섹션에 설정합니다:

위치	범위	공유 가능
`~/.claude/settings.json`	내 모든 프로젝트	아니오
`.claude/settings.json`	현재 프로젝트	예 (Git 커밋 가능)
`.claude/settings.local.json`	현재 프로젝트	아니오 (gitignore)

실용 예시

예시 1: 파일 수정 시 자동 포매팅

Claude가 파일을 수정할 때마다 Prettier를 자동 실행합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

matcher는 어떤 도구에 반응할지 필터입니다. Edit|Write는 파일 편집/작성 시에만 실행합니다.

예시 2: 작업 완료 시 알림 받기

Claude가 작업을 끝냈을 때 자리를 비워도 알 수 있습니다.

macOS (~/.claude/settings.json):

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code가 완료했습니다\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Linux:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' '작업이 완료되었습니다'"
          }
        ]
      }
    ]
  }
}

예시 3: 위험한 파일 수정 차단

.env, package-lock.json, .git/ 수정을 자동으로 막습니다.

Step 1: 스크립트 파일 생성 (.claude/hooks/protect-files.sh):

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "차단: $FILE_PATH 는 보호된 파일입니다 ('$pattern' 패턴)" >&2
    exit 2
  fi
done

exit 0

Step 2: 실행 권한 부여:

chmod +x .claude/hooks/protect-files.sh

Step 3: Hook 등록 (.claude/settings.json):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

exit 2로 종료하면 Claude가 해당 동작을 차단하고 에러 메시지를 받습니다. exit 0은 허용, 다른 코드는 진행되지만 로그만 남습니다.

예시 4: 컨텍스트 압축 후 규칙 재주입

Claude의 컨텍스트가 가득 차면 자동으로 압축(compaction)됩니다. 이때 중요한 규칙을 다시 주입합니다.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo '규칙: npm 대신 Bun 사용. 커밋 전 bun test 실행. 현재 스프린트: 인증 리팩토링.'"
          }
        ]
      }
    ]
  }
}

예시 5: 모든 Bash 명령어 감사 로그

Claude가 실행하는 모든 Bash 명령어를 파일에 기록합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

Hook 첫 설정하는 가장 쉬운 방법

Claude Code 내에서 /hooks 커맨드를 실행하면 인터랙티브 메뉴가 열립니다:

/hooks

원하는 이벤트 선택
matcher 설정 (*는 전체, Edit|Write는 파일 수정만)
실행할 셸 커맨드 입력
저장 위치 선택 (User settings → 모든 프로젝트 적용)

고급: 프롬프트 기반 Hook

판단이 필요한 상황에는 type: "prompt" Hook을 사용합니다. LLM이 yes/no 결정을 내립니다:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "모든 태스크가 완료되었는지 확인하세요. 미완료 항목이 있으면 {\"ok\": false, \"reason\": \"남은 작업\"} 형식으로 응답하세요."
          }
        ]
      }
    ]
  }
}

파일을 읽거나 명령어를 실행해야 하는 검증은 type: "agent" Hook을 사용합니다 (서브에이전트가 실제로 코드베이스를 확인합니다).

Hook 트러블슈팅

문제	해결책
Hook이 실행 안 됨	`/hooks`에서 이벤트 확인, matcher 대소문자 확인
스크립트가 실행 안 됨	`chmod +x` 로 실행 권한 부여
Stop hook이 무한루프	`stop_hook_active` 필드 체크 추가
JSON 파싱 오류	`~/.zshrc`의 echo 구문을 인터랙티브 셸 조건부로 감싸기

디버그 모드: claude --debug 또는 Ctrl+O로 verbose 출력 확인

⚠️ 주의사항

Hooks는 강력합니다. PreToolUse에서 exit 2를 잘못 설정하면 Claude가 아무 파일도 수정하지 못하게 됩니다
PostToolUse Hook은 이미 실행된 도구를 되돌릴 수 없습니다
PermissionRequest Hook은 비대화형 모드(-p)에서 실행되지 않습니다 → 자동화 스크립트에서는 PreToolUse 사용
설정 파일을 직접 수정했다면 /hooks 메뉴를 한 번 열거나 세션을 재시작해야 적용됩니다

한 줄 요약

Hooks = Claude Code 이벤트에 자동으로 반응하는 셸 커맨드. "파일 고칠 때마다 포매팅", "완료되면 알림", "위험한 파일 차단" — 이런 게 LLM 판단 없이 100% 실행됩니다.

다음 섹션에서는 반복 작업을 Skills로 자동화하는 방법을 배웁니다.

Skills & 플러그인 만들기

고급

반복 작업을 자동화하는 Skills를 만들고 플러그인으로 공유합니다.

12. Skills & 플러그인 만들기

반복하는 워크플로우를 /커맨드 하나로 — 팀과 공유도 가능한 재사용 가능한 자동화

Skills란?

쉽게 말하면: 자주 쓰는 작업 절차를 문서화해 두면, 다음부터는 한 마디로 실행됩니다.

참고: 기존 .claude/commands/ 폴더의 커스텀 슬래시 커맨드는 Skills로 통합되었습니다. 기존 파일은 그대로 작동합니다.

Skills vs 일반 대화 차이점

	일반 대화	Skills
실행 방법	매번 설명 타이핑	`/skill-name` 한 번
일관성	매번 다를 수 있음	항상 동일한 절차
팀 공유	불가	Git 커밋으로 공유
인자 전달	설명 속에 포함	`$ARGUMENTS`로 명확하게
도구 제한	Claude 판단	명시적으로 허용된 도구만

Skills로 없어지는 노가다

반복 작업	Skills 설정 후
커밋 메시지 작성 규칙 매번 설명	`/commit` 한 번으로
코드 리뷰 요청할 때마다 체크리스트 붙여넣기	`/review` 실행
PR 요약 작성 방법 반복 설명	`/pr-summary` 실행
번역 요청할 때마다 언어/형식 명시	`/translate ko en README.md`
GitHub 이슈 처리 절차 매번 설명	`/fix-issue 123`

내 Skills 만드는 방법

Step 1: 디렉터리 생성

# 내 모든 프로젝트에서 사용할 경우 (개인용)
mkdir -p ~/.claude/skills/commit

# 현재 프로젝트에서만 사용할 경우
mkdir -p .claude/skills/commit

Step 2: SKILL.md 작성

.claude/skills/commit/SKILL.md:

---
name: commit
description: 변경사항을 분석해서 좋은 커밋 메시지를 작성하고 커밋합니다. 커밋할 때 사용.
disable-model-invocation: true
---

현재 staged 변경사항을 분석해서 Conventional Commits 형식으로 커밋하세요:

1. `git diff --staged` 실행해서 변경사항 확인
2. 변경 유형 파악 (feat/fix/docs/refactor/test/chore)
3. 50자 이내 제목 작성
4. 필요시 본문에 상세 설명 추가
5. `git commit -m "..."` 실행

Step 3: 실행

# 직접 실행
/commit

# 또는 자연어로 → Claude가 자동 감지
"변경사항 커밋해줘"

Skills 파일 구조

my-skill/
├── SKILL.md           # 메인 지시사항 (필수)
├── template.md        # Claude가 채울 템플릿 (선택)
├── examples/
│   └── sample.md      # 예시 출력 (선택)
└── scripts/
    └── validate.sh    # Claude가 실행할 스크립트 (선택)

팁: SKILL.md는 500줄 이내로 유지하고, 상세 내용은 별도 파일로 분리하세요.

핵심 Frontmatter 옵션

---
name: my-skill           # 스킬 이름 (디렉터리명 기본값)
description: 설명        # Claude가 언제 이 스킬을 쓸지 판단하는 기준 (필수)
disable-model-invocation: true  # true면 사용자만 실행 가능 (Claude 자동 실행 불가)
user-invocable: false    # false면 메뉴에 안 보임 (Claude만 자동 실행 가능)
allowed-tools: Read, Grep, Glob  # 이 스킬 실행 중 허용할 도구만 지정
context: fork            # 독립된 서브에이전트 컨텍스트에서 실행
model: sonnet            # 이 스킬에서 사용할 모델 지정
---

Frontmatter	사용자 실행	Claude 자동 실행	언제 씀
(기본값)	가능	가능	일반 워크플로우
`disable-model-invocation: true`	가능	불가	배포, 전송 등 부작용 있는 작업
`user-invocable: false`	불가	가능	배경 지식, 컨벤션

실용 예시 3가지

예시 1: 코드 리뷰 자동화

.claude/skills/review/SKILL.md:

---
name: review
description: 코드를 리뷰합니다. 코드 품질, 보안, 성능 측면에서 검토가 필요할 때 사용.
---

다음 순서로 코드를 리뷰하세요:

1. `git diff HEAD~1` 또는 `$ARGUMENTS`로 지정된 파일 분석
2. 다음 항목 체크:
   - 코드 가독성 및 명명 규칙
   - 에러 처리 누락 여부
   - 보안 취약점 (SQL injection, XSS, 하드코딩된 시크릿)
   - 중복 코드
   - 테스트 커버리지
3. 우선순위별 정리:
   - 🔴 Critical (반드시 수정)
   - 🟡 Warning (수정 권장)
   - 🔵 Suggestion (고려 사항)

실행:

/review src/auth/login.ts

예시 2: GitHub 이슈 처리

.claude/skills/fix-issue/SKILL.md:

---
name: fix-issue
description: GitHub 이슈를 구현합니다. 이슈 번호를 전달하면 분석-구현-테스트-커밋까지 진행.
disable-model-invocation: true
allowed-tools: Bash(gh *), Read, Edit, Write
---

GitHub 이슈 $ARGUMENTS를 처리하세요:

1. `gh issue view $ARGUMENTS` 로 이슈 내용 확인
2. 요구사항 파악 후 구현 계획 수립
3. 관련 파일 찾고 코드 구현
4. 테스트 작성 및 실행
5. `gh issue close $ARGUMENTS` 후 커밋 생성

실행:

/fix-issue 123

예시 3: 번역 자동화

.claude/skills/translate/SKILL.md:

---
name: translate
description: 파일이나 텍스트를 번역합니다.
argument-hint: [파일경로 또는 텍스트] [대상언어]
---

$ARGUMENTS[0]을 $ARGUMENTS[1]로 번역하세요.

- 기술 용어는 원문 유지 (코드, 명령어, 고유명사)
- 마크다운 구조 보존
- 번역 결과를 원본과 같은 파일명에 언어 코드 추가해서 저장

실행:

/translate README.md ko

동적 컨텍스트 주입 (고급)

! + 백틱 문법으로 스킬 실행 전에 셸 커맨드를 실행하고 결과를 컨텍스트에 주입할 수 있습니다:

---
name: pr-summary
description: PR 요약을 작성합니다.
context: fork
allowed-tools: Bash(gh *)
---

## PR 컨텍스트
- 변경 내용: !`gh pr diff`
- PR 댓글: !`gh pr view --comments`
- 변경된 파일: !`gh pr diff --name-only`

위 내용을 바탕으로 명확한 PR 요약을 작성하세요.

Claude가 이 스킬을 실행하면:

백틱 안의 명령어가 먼저 실행됨
실제 데이터가 프롬프트에 삽입됨
Claude가 실제 PR 내용을 보고 요약 작성

Skills가 저장되는 위치

위치	경로	적용 범위
엔터프라이즈	관리형 설정	조직 전체
개인	`~/.claude/skills/<이름>/SKILL.md`	내 모든 프로젝트
프로젝트	`.claude/skills/<이름>/SKILL.md`	이 프로젝트만
플러그인	`<플러그인>/skills/<이름>/SKILL.md`	플러그인 활성화 시

같은 이름의 스킬이 여러 위치에 있으면 엔터프라이즈 > 개인 > 프로젝트 순으로 우선순위가 적용됩니다.

플러그인으로 패키징하기

팀 전체에 배포하거나 커뮤니티와 공유하려면 플러그인으로 패키징합니다.

플러그인 구조

my-plugin/
├── .claude-plugin/
│   └── plugin.json        # 플러그인 메타데이터
├── skills/
│   ├── review/
│   │   └── SKILL.md
│   └── commit/
│       └── SKILL.md
└── hooks/
    └── hooks.json         # 플러그인 전용 Hooks

plugin.json

{
  "name": "my-plugin",
  "description": "팀 공통 워크플로우 모음",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

로컬 테스트

# 플러그인 디렉터리로 실행
claude --plugin-dir ./my-plugin

# 스킬 실행 (플러그인 네임스페이스 포함)
/my-plugin:review
/my-plugin:commit

Standalone vs 플러그인 선택 기준

상황	권장 방식
개인 워크플로우, 빠른 실험	Standalone (`.claude/skills/`)
팀과 공유, 여러 프로젝트	플러그인
커뮤니티 배포	플러그인 + 마켓플레이스

Skills 자동 감지 원리

Claude는 description 필드를 보고 어떤 상황에서 스킬을 써야 할지 판단합니다:

# 잘 쓴 description 예시
description: 코드를 리뷰합니다. PR 리뷰, 코드 품질 검토, 보안 분석이 필요할 때 사용.

# 아쉬운 description 예시
description: review tool

"어떤 상황에서 쓰는지"를 명확히 기술할수록 Claude가 더 잘 감지합니다
disable-model-invocation: true를 설정하면 Claude가 자동으로 실행하지 않습니다

트러블슈팅

문제	해결책
스킬이 트리거 안 됨	description에 사용자가 실제로 쓸 표현 포함
스킬이 너무 자주 실행됨	description을 더 구체적으로 수정
Claude가 스킬을 못 봄	`/context`에서 컨텍스트 한도 초과 여부 확인
자동 실행 막고 싶음	`disable-model-invocation: true` 추가

한 줄 요약

Skills = 내가 자주 하는 작업을 /커맨드 하나로 만들어두는 것. 팀에 배포하려면 플러그인으로 패키징하면 된다.

다음 섹션에서는 Sub-agents로 복잡한 작업을 병렬 처리하는 방법을 배웁니다.

Sub-agents & Agent Teams

고급

여러 Claude 에이전트가 협력하는 고급 멀티 에이전트 시스템을 활용합니다.

13. Sub-agents & Agent Teams

Claude가 다른 Claude에게 작업을 위임 — 복잡한 작업을 병렬로 처리하는 방법

Sub-agents란?

**Sub-agents(서브에이전트)**는 메인 Claude가 특정 작업을 전문화된 별도의 Claude 인스턴스에 위임하는 기능입니다.

각 서브에이전트는:

독립된 컨텍스트 창을 가집니다 (메인 대화와 분리)
커스텀 시스템 프롬프트로 특정 역할에 집중합니다
제한된 도구만 사용합니다 (필요한 것만)
작업 완료 후 요약 결과만 메인으로 반환합니다

개념도

메인 Claude (오케스트레이터)
    │
    ├──► 서브 Claude A: 탐색 전담 (Explore)
    │         └── 파일 읽기, 코드 검색만 가능
    │
    ├──► 서브 Claude B: 구현 전담 (general-purpose)
    │         └── 파일 읽기+수정 가능
    │
    └──► 서브 Claude C: 테스트 전담 (custom)
              └── Bash 실행만 가능

각 서브에이전트는 독립 컨텍스트에서 실행
→ 메인 컨텍스트를 깨끗하게 유지
→ 결과 요약만 메인으로 반환

언제 유용한가?

Sub-agents를 쓰면 좋은 상황

상황	이유
대용량 출력이 나오는 작업	테스트 로그, 문서 페치 결과가 메인 컨텍스트를 낭비함
독립적인 여러 파일 동시 수정	병렬로 처리하면 더 빠름
특정 도구만 써야 하는 작업	읽기 전용 리뷰어, DB 쿼리 전용 에이전트
탐색과 구현을 분리하고 싶을 때	탐색 결과가 메인 대화를 오염시키지 않게

Sub-agents보다 일반 대화가 나은 상황

상황	이유
잦은 피드백이 필요한 작업	서브에이전트는 독립 실행 → 중간 개입 어려움
빠른 단순 수정	서브에이전트 시작 오버헤드가 있음
여러 단계가 컨텍스트를 공유해야 할 때	계획 → 구현 → 테스트가 긴밀하게 연결된 경우

내장 서브에이전트

Claude Code는 기본적으로 3개의 서브에이전트를 포함합니다:

에이전트	모델	허용 도구	용도
Explore	Haiku (빠름)	읽기 전용	파일 탐색, 코드 검색
Plan	메인 상속	읽기 전용	Plan 모드에서 컨텍스트 수집
general-purpose	메인 상속	모든 도구	복잡한 다단계 작업

나만의 서브에이전트 만들기

방법 1: /agents 인터랙티브 메뉴 (권장)

/agents

Create new agent 선택
User-level (모든 프로젝트) 또는 Project-level (현재 프로젝트) 선택
Generate with Claude 선택 후 역할 설명
허용 도구 선택
모델 선택 (Haiku/Sonnet/Opus)
저장

방법 2: 파일 직접 작성

.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: 코드를 리뷰합니다. 코드 변경 후 품질, 보안, 성능을 검토할 때 자동으로 사용.
tools: Read, Grep, Glob, Bash
model: sonnet
---

당신은 시니어 코드 리뷰어입니다.

실행 시:
1. `git diff`로 최근 변경사항 확인
2. 수정된 파일에 집중
3. 즉시 리뷰 시작

리뷰 체크리스트:
- 코드 가독성 및 명명 규칙
- 중복 코드 없음
- 에러 처리 적절성
- 보안 취약점 (노출된 시크릿, 입력 검증)
- 테스트 커버리지

피드백 형식:
- 🔴 Critical (반드시 수정)
- 🟡 Warning (수정 권장)
- 🔵 Suggestion (고려 사항)

서브에이전트 설정 옵션

---
name: my-agent           # 소문자 + 하이픈 (필수)
description: 설명        # Claude가 언제 위임할지 판단 기준 (필수)
tools: Read, Grep, Glob  # 허용 도구 목록 (생략 시 모든 도구 상속)
disallowedTools: Write   # 제외할 도구
model: haiku             # haiku / sonnet / opus / inherit(기본값)
permissionMode: default  # default / acceptEdits / dontAsk / bypassPermissions
maxTurns: 20             # 최대 실행 턴 수
memory: user             # 영구 메모리: user / project / local
background: false        # true면 항상 백그라운드 실행
isolation: worktree      # worktree면 격리된 Git 워크트리에서 실행
---

서브에이전트 저장 위치

위치	경로	우선순위
CLI 플래그	`--agents '{...}'`	1 (최고)
프로젝트	`.claude/agents/`	2
유저	`~/.claude/agents/`	3
플러그인	`<plugin>/agents/`	4

실용 예시

예시 1: 병렬 코드베이스 탐색

"인증, DB, API 모듈을 각각 별도 서브에이전트로 병렬 분석해줘"

→ 3개 Explore 서브에이전트가 동시에 실행 → 각 모듈 분석 결과만 메인으로 반환 → 메인 Claude가 통합 분석

예시 2: 코드 리뷰 + 수정 연쇄

"code-reviewer 에이전트로 성능 문제 찾고, 그 다음 optimizer 에이전트로 수정해줘"

→ code-reviewer가 문제 목록 반환 → optimizer가 해당 목록을 받아 수정 실행 → 메인 컨텍스트는 깨끗하게 유지

예시 3: 테스트 실행 격리

"서브에이전트로 전체 테스트 실행하고 실패한 것만 보고해줘"

→ 테스트 로그(수천 줄)가 메인 컨텍스트에 쌓이지 않음 → 실패 항목과 에러 메시지만 반환

예시 4: 특정 에이전트 명시 요청

"code-reviewer 에이전트로 인증 모듈 리뷰해줘"
"debugger 에이전트로 실패 중인 테스트 고쳐줘"

영구 메모리 기능

서브에이전트에 memory 필드를 설정하면 세션 간에도 학습 내용이 유지됩니다:

---
name: code-reviewer
description: 코드를 리뷰합니다
memory: user
---

코드를 리뷰하면서 발견한 코드베이스 패턴, 아키텍처 결정, 반복되는 이슈를
메모리에 기록하세요. 다음 리뷰 때 이전 학습 내용을 활용하세요.

스코프	위치	사용 시점
`user`	`~/.claude/agent-memory/<이름>/`	여러 프로젝트에서 지식 축적
`project`	`.claude/agent-memory/<이름>/`	프로젝트별 학습, 팀 공유 가능
`local`	`.claude/agent-memory-local/<이름>/`	프로젝트별 학습, 개인만

포그라운드 vs 백그라운드 실행

포그라운드: 완료될 때까지 대기. 권한 요청이 사용자에게 전달됨
백그라운드: 백그라운드에서 동시 실행. 계속 다른 작업 가능

# 백그라운드 실행 요청
"이걸 백그라운드에서 실행해줘"

# 실행 중 백그라운드로 전환
Ctrl+B

주의: 백그라운드 서브에이전트는 MCP 도구를 사용할 수 없습니다.

Agent Teams란?

Agent Teams는 서브에이전트보다 한 단계 더 나아간 개념입니다. 여러 에이전트가 각자의 완전히 독립된 세션에서 실행되며 협력합니다.

	Sub-agents	Agent Teams
실행 단위	메인 세션 내부	완전히 독립된 세션
컨텍스트	메인과 공유	각자 독립
적합한 작업	단일 세션 내 위임	장시간 병렬 작업
통신	결과 요약 반환	세션 간 조율

서브에이전트로 컨텍스트 창이 부족하거나, 작업이 여러 세션에 걸쳐 지속되어야 할 때 Agent Teams를 고려합니다.

⚠️ 비용 주의

서브에이전트는 각각 독립된 Claude 인스턴스입니다. 에이전트마다 토큰을 소모합니다.

서브에이전트 3개 병렬 실행 = 토큰 사용량 대폭 증가
결과가 메인 컨텍스트로 돌아올 때 추가 토큰 소모
불필요한 서브에이전트 남용은 비용 증가로 이어짐

비용 절약 팁:

읽기 전용 탐색에는 Haiku 모델 서브에이전트 사용
서브에이전트가 반환하는 결과의 양을 명확히 지정
단순 작업은 메인 대화에서 처리

초보자를 위한 조언

처음엔 단일 Claude로 충분합니다.

서브에이전트는 다음 상황이 생겼을 때 도입하세요:

메인 컨텍스트가 자꾸 넘쳐서 압축이 반복될 때
동일한 탐색 작업을 여러 번 반복할 때
특정 도구만 쓰는 안전한 리뷰어가 필요할 때

한 줄 요약

Sub-agents = Claude가 다른 Claude에게 작업 위임. 독립 컨텍스트에서 실행되므로 메인 대화를 깨끗하게 유지하면서 병렬 처리 가능. 단, 토큰 비용은 에이전트 수만큼 증가.

비용 관리 & 절약 팁

고급

토큰 비용 구조를 이해하고 효율적으로 Claude Code를 사용하는 방법을 배웁니다.

14. 비용 관리 & 절약 팁

Claude Code를 더 스마트하게, 더 저렴하게 쓰는 방법을 알아봅니다.

비용 구조 한눈에 보기

Claude Code의 비용 방식은 크게 두 가지입니다.

구분	방식	특징
Claude.ai Pro / Max	정액제 구독	월 고정 요금, API 비용 별도 없음
Anthropic API	종량제	사용한 토큰 수만큼 요금 발생

토큰이란?

**토큰(token)**은 Claude가 텍스트를 처리하는 단위입니다.

영어 기준: 단어 약 1개 = 1~2 토큰
한국어 기준: 글자 약 2~3자 = 1 토큰
대략적으로: 4글자(영어) ≈ 1 토큰

비용이 많이 드는 상황

1. 긴 파일을 반복해서 읽을 때

Claude가 같은 파일을 여러 번 읽으면 그때마다 토큰이 소모됩니다. 10,000줄짜리 로그 파일을 통째로 읽히면 한 번에 수만 개의 토큰이 사용됩니다.

2. 컨텍스트를 오래 유지할 때

3. 고성능 모델을 사용할 때

Opus 모델은 Sonnet보다 강력하지만 토큰당 비용도 높습니다. 간단한 작업에 Opus를 쓰는 것은 비효율적입니다.

4. 자동화(CI/CD)에서 무분별하게 실행할 때

GitHub Actions 등으로 자동화하면 사람의 개입 없이 대량의 토큰이 소모될 수 있습니다.

절약 팁 5가지

팁 1: `/compact`로 컨텍스트 정리하기

대화가 길어졌을 때 /compact 명령어를 실행하면 이전 내용을 요약해서 컨텍스트 크기를 줄여줍니다.

/compact 코드 변경 사항과 테스트 결과 중심으로 요약해줘

이렇게 하면 중요한 정보는 유지하면서 불필요한 대화 내용은 압축됩니다.

CLAUDE.md에 압축 방식을 미리 지정할 수도 있습니다:

# Compact instructions

When you are using compact, please focus on test output and code changes

팁: /clear를 쓰면 컨텍스트를 완전히 초기화할 수 있습니다. 전혀 다른 작업을 시작할 때 유용합니다.

팁 2: 불필요한 파일 참조 피하기

막연한 요청은 Claude가 불필요하게 많은 파일을 읽게 만듭니다.

비효율적인 요청	효율적인 요청
"이 코드베이스를 개선해줘"	"auth.ts의 login 함수에 입력 유효성 검사를 추가해줘"
"버그를 찾아줘"	"세션 만료 후 로그인이 실패하는 문제를 src/auth/에서 확인해줘"

구체적인 요청일수록 Claude가 필요한 파일만 읽어서 토큰 소모가 줄어듭니다.

팁 3: Haiku 모델 활용하기

모든 작업에 고성능 모델을 쓸 필요는 없습니다.

모델	용도	비용
Haiku	간단한 질문, 파일 요약, 단순 작업	낮음
Sonnet	일반 코딩 작업 (기본 추천)	중간
Opus	복잡한 아키텍처 설계, 어려운 추론	높음

모델 전환은 세션 중에도 가능합니다:

/model haiku

또는 시작할 때 지정:

claude --model haiku

opusplan 모드: 계획 단계에서는 Opus, 실행 단계에서는 Sonnet으로 자동 전환되는 하이브리드 모드입니다.

/model opusplan

팁 4: Fast Mode 이해하고 활용하기

/fast 명령어로 Fast Mode를 켜면 Opus 4.6이 약 2.5배 빠르게 응답합니다.

/fast

참고: Fast Mode는 구독 플랜의 기본 사용량에 포함되지 않고 추가 사용(extra usage)으로 청구됩니다.

팁 5: `/cost`로 주기적으로 확인하기

API 사용자라면 현재 세션의 토큰 사용량을 확인할 수 있습니다:

/cost

출력 예시:

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    0 lines added, 0 lines removed

구독자는 /stats로 사용 패턴을 확인할 수 있습니다.

상태 표시줄(status line)을 설정하면 컨텍스트 사용량을 실시간으로 볼 수도 있습니다.

모델별 비용 비교 (간략)

모델	특징	API 기준
Haiku	빠르고 저렴, 간단한 작업	가장 저렴
Sonnet	균형 잡힌 성능, 일반 코딩 작업	중간
Opus	최고 성능, 복잡한 추론	가장 비쌈
Opus (Fast Mode)	Opus 속도 2.5배, 토큰 비용 높음	Opus보다 비쌈

정확한 토큰 가격은 Anthropic 가격 페이지를 참고하세요.

Claude.ai Max 플랜의 장점

Claude.ai Pro 또는 Max 구독자는 API 종량제 비용 없이 Claude Code를 사용할 수 있습니다.

월정액 안에 Claude Code 사용 포함
추가 API 키 불필요
비용 걱정 없이 다양한 실험 가능
Max 플랜의 경우 더 높은 사용량 한도

단, Fast Mode와 1M 컨텍스트 초과 분은 추가 사용(extra usage)으로 청구될 수 있습니다.

팀 비용 관리

API를 팀 단위로 사용하는 경우:

Workspace 지출 한도 설정: Anthropic Console에서 팀 전체 지출 한도를 설정할 수 있습니다.
사용량 대시보드: Console에서 팀원별 비용과 사용량을 확인할 수 있습니다.
에이전트 팀 주의: Agent Teams(여러 Claude 인스턴스 동시 실행) 기능은 표준 세션보다 약 7배 많은 토큰을 소모합니다.

정리: 비용 절약 체크리스트

✅ 작업이 끝나면 /clear로 컨텍스트 초기화
✅ 관련 없는 작업은 새 세션에서 시작
✅ 구체적인 파일명과 함수명을 명시
✅ 간단한 작업은 Haiku 모델 사용
✅ Fast Mode는 필요할 때만 켜기
✅ /cost 또는 /stats로 주기적으로 확인
✅ CLAUDE.md에 compact 지침 설정

Headless & GitHub Actions

고급

CI/CD 파이프라인에 Claude Code를 통합하는 자동화 방법을 알아봅니다.

15. Headless 모드 & GitHub Actions 자동화

Claude Code를 사람 없이 자동으로 실행하는 방법을 배웁니다.

Headless 모드란?

보통 Claude Code는 터미널에서 대화형으로 사용합니다. 사람이 직접 질문하고, Claude가 답하고, 다시 사람이 피드백을 주는 방식이죠.

Headless = 사람 없이 자동 실행

이전에는 "headless mode"라고 불렸지만, 공식적으로는 Agent SDK CLI라고도 합니다. -p 플래그와 모든 CLI 옵션은 동일하게 작동합니다.

언제 사용하나요?

상황	예시
CI/CD 파이프라인	PR이 열릴 때마다 자동으로 코드 리뷰
자동화 스크립트	매일 밤 코드 품질 리포트 생성
배치 처리	여러 파일을 한꺼번에 마이그레이션
반복 작업	테스트 실패 시 자동 수정 시도

기본 사용법

-p (또는 --print) 플래그를 붙이면 비대화형(non-interactive) 모드로 실행됩니다.

가장 간단한 형태

claude -p "이 프로젝트가 무엇을 하는지 설명해줘"

도구 권한 허용하기

Claude가 파일을 읽고 수정할 수 있도록 도구를 허용합니다:

claude -p "auth.py의 버그를 찾아서 수정해줘" --allowedTools "Read,Edit,Bash"

JSON 출력 받기

스크립트에서 결과를 파싱하기 쉽도록 JSON 형식으로 출력할 수 있습니다:

claude -p "이 프로젝트를 요약해줘" --output-format json

출력 형식 옵션:

text (기본값): 일반 텍스트
json: JSON 구조체로 결과 반환 (세션 ID, 메타데이터 포함)
stream-json: 실시간 스트리밍 JSON

실용적인 예시: 자동 커밋

claude -p "스테이징된 변경 사항을 검토하고 적절한 커밋 메시지로 커밋해줘" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

대화 이어가기

# 첫 번째 요청
claude -p "이 코드베이스의 성능 문제를 검토해줘"

# 이전 대화 이어서
claude -p "이제 데이터베이스 쿼리에 집중해줘" --continue

GitHub Actions 연동

공식 액션 소개

Anthropic이 공식으로 제공하는 GitHub Action이 있습니다:

저장소: github.com/anthropics/claude-code-action
버전: anthropics/claude-code-action@v1

빠른 시작

Claude Code 터미널에서 다음 명령어를 실행하면 설정을 자동으로 안내해줍니다:

/install-github-app

저장소 관리자 권한이 필요합니다.

수동 설정 방법

Claude GitHub 앱 설치: github.com/apps/claude에서 저장소에 앱을 설치합니다.
API 키 등록: 저장소 Settings → Secrets에 ANTHROPIC_API_KEY를 추가합니다.
워크플로우 파일 추가: .github/workflows/ 폴더에 YAML 파일을 만듭니다.

예시 1: @claude 멘션으로 PR 리뷰 자동화

PR 댓글이나 이슈에 @claude를 멘션하면 Claude가 자동으로 응답합니다.

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # @claude 멘션에 자동으로 응답

사용 예시:

@claude 이 PR의 보안 취약점을 검토해줘
@claude 이 함수에 엣지 케이스가 있는지 확인해줘
@claude 이 이슈를 기반으로 기능을 구현해줘

예시 2: PR이 열릴 때 자동 코드 리뷰

name: 코드 리뷰
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "/review"
          claude_args: "--max-turns 5"

예시 3: 스케줄 기반 코드 분석

name: 일일 리포트
on:
  schedule:
    - cron: "0 9 * * *"  # 매일 오전 9시

jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "어제의 커밋과 열린 이슈를 요약해줘"
          claude_args: "--model sonnet"

워크플로우 파라미터 설명

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}  # 필수
    prompt: "작업 지시사항"        # 선택 (없으면 @claude 멘션에 반응)
    claude_args: "--max-turns 10"  # 선택 (추가 CLI 인자)

파라미터	설명	필수 여부
`anthropic_api_key`	Anthropic API 키	필수
`prompt`	Claude에게 전달할 지시사항	선택
`claude_args`	추가 CLI 인자 (`--max-turns`, `--model` 등)	선택
`trigger_phrase`	트리거 구문 (기본값: `@claude`)	선택

GitLab CI/CD 연동 (간략)

GitLab을 사용한다면 .gitlab-ci.yml에 Claude Code 작업을 추가할 수 있습니다.

GitLab 연동은 현재 베타 단계입니다.

stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
  before_script:
    - apk add --no-cache git curl bash
    - curl -fsSL https://claude.ai/install.sh | bash
  script:
    - claude -p "${AI_FLOW_INPUT:-'변경 사항을 검토하고 개선사항을 제안해줘'}"
      --permission-mode acceptEdits
      --allowedTools "Bash Read Edit Write"

GitLab CI/CD 변수에 ANTHROPIC_API_KEY를 등록하는 것을 잊지 마세요.

⚠️ 비용 주의사항

자동화는 토큰 소모가 매우 큽니다.

CI/CD 파이프라인은 사람의 감독 없이 실행되므로 비용이 예상보다 빠르게 쌓일 수 있습니다.
--max-turns 옵션으로 최대 반복 횟수를 제한하세요.
워크플로우에 타임아웃을 설정하세요.
불필요한 트리거를 줄이세요.

claude_args: "--max-turns 5 --model sonnet"

API 비용 외에 GitHub Actions 실행 시간 비용도 발생합니다 (GitHub Actions 무료 한도를 초과할 경우).

보안 주의사항

API 키를 코드에 직접 넣지 마세요. 항상 GitHub Secrets를 사용하세요.

# 올바른 방법
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

# 절대 하지 말 것
anthropic_api_key: "sk-ant-api03-..."

Claude의 제안을 머지하기 전에 항상 검토하세요.
액션 권한은 필요한 것만 허용하세요.

입문자에게

이 기능은 지금 당장 필요하지 않습니다.

지금은 "이런 것도 가능하구나"라고 알아두는 것으로 충분합니다.

핵심 정리

Headless 모드: claude -p "작업내용" --output-format json
GitHub Actions: anthropics/claude-code-action@v1
트리거: @claude 멘션 또는 자동 프롬프트
비용 제어: --max-turns, 타임아웃, 모델 선택
보안: API 키는 반드시 Secrets 사용

다음 단계 & 리소스

고급

CC101을 마친 후 더 깊이 배울 수 있는 리소스와 학습 경로를 안내합니다.

16. 다음 단계 & 리소스

CC101을 마친 당신에게. 이제 진짜 시작입니다.

여기까지 오셨군요

잠깐 돌아보면, 이런 것들을 배웠습니다:

Claude Code가 무엇이고 어떻게 작동하는지
설치와 인증 설정
CLAUDE.md로 프로젝트 맞춤 설정
기본 명령어와 워크플로우
MCP로 외부 도구 연결
Hooks와 Skills로 자동화
플러그인 생태계 탐색
비용 관리와 최적화
Headless 모드와 CI/CD 연동

이 지식은 단순히 도구 하나를 배운 것이 아닙니다. AI와 협업하는 새로운 개발 방식을 익힌 것입니다.

다음 학습 경로

입문 완료 (지금 여기)

✅ Claude Code 설치 & 인증
✅ CLAUDE.md 작성
✅ 기본 명령어 (/help, /cost, /compact, /model)
✅ 파일 읽기, 코드 수정, 테스트 실행
✅ 플러그인 기본 사용

중급 목표

MCP(Model Context Protocol) 설정

MCP를 통해 Claude Code를 외부 서비스와 연결할 수 있습니다.

# MCP 서버 추가
claude mcp add

고급 목표

Skills 제작

자주 쓰는 작업을 재사용 가능한 Skills로 만듭니다.

# .claude/skills/fix-issue/SKILL.md
---
name: fix-issue
description: GitHub 이슈를 분석하고 수정
---
다음 GitHub 이슈를 분석하고 수정해줘: $ARGUMENTS

1. gh issue view로 이슈 세부사항 확인
2. 관련 파일 검색
3. 수정 사항 구현
4. 테스트 작성 및 실행
5. PR 생성

Agent Teams 활용

여러 Claude 인스턴스를 동시에 실행해 복잡한 작업을 병렬로 처리합니다.

# Agent Teams 활성화 (환경변수 설정 필요)
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

비용이 많이 들 수 있으므로 신중하게 사용하세요.

CI/CD 완전 자동화

섹션 15에서 배운 GitHub Actions를 실제 프로젝트에 적용합니다.

# 예시: 모든 PR에 자동 코드 리뷰
on:
  pull_request:
    types: [opened, synchronize]

공식 리소스

공식 문서

리소스	URL
공식 문서 (영어)	docs.anthropic.com/en/docs/claude-code
GitHub 저장소	github.com/anthropics/claude-code
공식 플러그인	github.com/anthropics/claude-plugins-official
Anthropic 콘솔	platform.claude.com

gptaku_plugins 커뮤니티

CC101 제작팀이 운영하는 플러그인 커뮤니티입니다. 실전에서 검증된 플러그인들을 공유합니다.

리소스	URL
GitHub	github.com/fivetaku/gptaku_plugins

이 저장소가 도움이 됐다면 Star 를 눌러주세요! 커뮤니티 성장에 큰 힘이 됩니다.

첫 실전 프로젝트 추천

CC101을 마쳤다면 바로 실전에 뛰어들어 보세요. 아래는 입문자에게 추천하는 프로젝트들입니다.

1. 포트폴리오 사이트 만들기

가장 동기부여가 되는 프로젝트입니다. Claude Code에게 요구사항을 설명하고 전체 웹사이트를 만들어 보세요.

"HTML/CSS/JS로 개발자 포트폴리오 사이트를 만들어줘.
섹션: 소개, 기술 스택, 프로젝트, 연락처.
미니멀하고 다크 테마로 만들어줘."

2. 기존 코드 리팩토링

이미 있는 코드를 Claude Code와 함께 개선해보세요.

"이 파일의 코드를 리뷰하고 개선해줘.
가독성, 성능, 에러 처리에 집중해줘.
@src/utils/dataProcessor.js"

3. 테스트 코드 자동 생성

테스트가 없는 프로젝트에 테스트를 추가하는 것은 Claude Code가 특히 잘하는 작업입니다.

"auth.ts의 모든 함수에 대한 단위 테스트를 작성해줘.
Jest를 사용하고, 엣지 케이스도 포함해줘."

4. 레거시 코드 마이그레이션

오래된 코드를 현대적인 방식으로 변환합니다.

"이 CommonJS 모듈들을 ES Modules로 마이그레이션해줘.
각 파일을 변환하고 테스트로 검증해줘."

막히면 어떻게 하나요?

1단계: 공식 문서 확인

대부분의 답은 공식 문서에 있습니다.

https://docs.anthropic.com/en/docs/claude-code

Claude Code 안에서도 도움을 받을 수 있습니다:

/help

2단계: Claude Code에게 직접 물어보기

Claude Code 자체가 가장 강력한 도움말입니다.

"Claude Code에서 MCP 서버를 추가하는 방법을 알려줘"
"이 에러 메시지의 의미가 뭔지 설명해줘: [에러 내용]"

3단계: 커뮤니티

GitHub Issues: github.com/anthropics/claude-code/issues
gptaku_plugins: github.com/fivetaku/gptaku_plugins

4단계: Anthropic 지원

계정이나 결제 관련 문제는 Anthropic 콘솔에서 지원을 요청하세요.

마지막으로

Claude Code는 빠르게 발전하는 도구입니다. 오늘 배운 것이 몇 달 후에는 달라져 있을 수 있습니다. 중요한 것은 기본 원리를 이해하는 것입니다.

CC101을 마친 여러분은 그 첫걸음을 내딛었습니다. 앞으로의 여정이 기대됩니다.

빠른 참조 카드

공식 문서:    https://docs.anthropic.com/en/docs/claude-code
GitHub:       https://github.com/anthropics/claude-code
플러그인:     https://github.com/anthropics/claude-plugins-official
커뮤니티:     https://github.com/fivetaku/gptaku_plugins
콘솔:         https://platform.claude.com

다음 목표:
  중급 → MCP 설정, Hooks 커스터마이징, 플러그인 탐색
  고급 → Skills 제작, Agent Teams, CI/CD 완전 자동화

Claude Code로 AI 코딩 시작하기

Claude Code란?

01. Claude Code란?

한 줄 정의

Claude.ai 웹 vs Claude Code vs Cursor — 핵심 차이

CLI(터미널)라서 강력한 이유

Claude Code가 직접 할 수 있는 것들

실제로 어떻게 작동하나? (예시)

어떤 사람에게 맞는가?

Claude Code가 잘 맞는 사람

이런 분에게도 추천

이런 분에게는 맞지 않을 수 있음

어디서 사용할 수 있나?

한 줄 요약

제품군 & 가격

02. 제품군 & 가격

Claude Code를 쓰는 방법 3가지

방법 1. Claude.ai 구독 (Pro / Max) — 개인 입문자 추천

방법 2. Anthropic API 직접 사용 — 개발자 / 자동화 목적

방법 3. 엔터프라이즈 클라우드 — 기업 보안 요건이 있는 팀

Pro vs Max 플랜 비교

입문자 추천: Max $100

비용 구조 설명

구독 플랜 (Pro / Max)

API 직접 사용

⚠️ 비용 주의사항

API 사용 시 주의할 점

비용 절감 팁

어떤 플랜으로 시작할까?

요금 페이지

설치 & 인증

03. 설치 & 인증

설치 전 확인사항

지원 운영체제

하드웨어 요구사항

Node.js가 필요한가요?

설치 방법

macOS / Linux / WSL (Windows Subsystem for Linux)

Windows

Alpine Linux 추가 패키지

설치 후 인증 (로그인)

인증 흐름 요약

자격 증명 보안

첫 실행 확인

자동 업데이트

흔한 설치 문제 & 해결법

문제 1: curl: command not found (curl이 없다는 오류)

문제 2: claude: command not found (설치 후에도 명령어를 못 찾는 경우)

문제 3: Windows에서 Git이 없다는 오류

다음 단계

플러그인 설치

04. 플러그인 추천 설치

플러그인이란?

공식 플러그인 마켓플레이스

공식 마켓에서 플러그인 설치하기

공식 마켓에서 제공하는 주요 플러그인 카테고리

gptaku_plugins — 한국 입문자 전용 플러그인 모음

포함된 플러그인

설치 방법

1단계: 마켓플레이스 추가 및 플러그인 설치

2단계: 설치 확인

3단계: 플러그인 사용해보기

플러그인 관리

⭐ CC101이 도움이 됐다면 Star 부탁드려요!

다음 단계

핵심 개념

05. 핵심 개념 이해하기

Claude Code는 어떻게 작동하나요?

핵심 개념 5가지

1. Context (컨텍스트) — Claude의 작업 기억

2. Tools (도구) — Claude가 실제로 할 수 있는 일

3. Permissions (권한) — 무엇을 허용할지 설정

4. Memory (메모리) — CLAUDE.md로 프로젝트 기억시키기

5. Session (세션) — 대화의 시작과 끝

"왜 가끔 멈추거나 확인을 요청하나요?"

초보자가 알아야 할 권한 모드 3가지

모드 전환 방법

모드 비교 예시

체크포인트: 실수해도 되돌릴 수 있어요

다음 단계

Claude Code로
AI 코딩 시작하기

문제 1: `curl: command not found` (curl이 없다는 오류)

문제 2: `claude: command not found` (설치 후에도 명령어를 못 찾는 경우)

`/memory` 명령어 활용

1. `/compact` — 가장 중요한 명령어

2. `Ctrl+C` — 멈추고 싶을 때

3. `/clear` — 새로 시작할 때

4. `Shift+Enter` — 긴 지시사항 입력

5. `/cost` — 비용 확인