Claude Code 실전 가이드

Anthropic 공식 CLI 코딩 에이전트 Claude Code를 처음 쓰는 사람을 위한 실전 가이드 — 전 30편. 설치·첫 대화부터 권한·Git·모델·Hooks·MCP·Subagents·팀 운영까지.

1. Claude Code가 무엇인지 먼저 이해하기

01핵심 개념

Claude Code는 단순한 채팅창이 아닙니다. 프로젝트 폴더 안에서 코드를 읽고, 명령을 실행하고, 파일을 수정할 수 있는 에이전트형 CLI 도구입니다.

일반적인 AI 채팅과 Claude Code의 차이:

일반 AI 채팅

사용자가 코드를 복사해서 붙여넣음

Claude Code

Claude가 프로젝트 파일을 직접 읽음

일반 AI 채팅

설명 중심

Claude Code

설명, 수정, 실행, 검토 가능

일반 AI 채팅

파일 수정은 사용자가 직접 함

Claude Code

Claude가 파일 수정 제안을 하거나 직접 수정 가능

일반 AI 채팅

프로젝트 전체 맥락 파악이 어려움

Claude Code

코드베이스 구조를 탐색할 수 있음

02CLI란 무엇인가

CLI는 Command Line Interface의 줄임말입니다. 쉽게 말하면 터미널에서 명령어로 사용하는 프로그램입니다.

Claude Code는 보통 이런 식으로 실행합니다.

cd ~/my-project
claude

그러면 현재 프로젝트 폴더 안에서 Claude Code가 실행됩니다.

즉, Claude Code는 웹사이트에 들어가서 쓰는 도구가 아니라, 개발자가 실제로 작업하는 터미널과 프로젝트 폴더 안에서 함께 일하는 도구입니다.

03Claude Code가 할 수 있는 일

초보자는 처음부터 모든 기능을 알 필요가 없습니다. 처음에는 아래 5가지만 이해하면 충분합니다.

코드 읽기

프로젝트 파일을 분석함 (예: "이 프로젝트 구조를 설명해줘.")

코드 검색

필요한 파일이나 함수 위치를 찾음 (예: "로그인 로직이 어디에 있는지 찾아줘.")

코드 수정

파일을 직접 수정하거나 수정안을 제안함 (예: "회원가입 입력 검증을 추가해줘.")

명령 실행

테스트, 빌드, lint 등을 실행함 (예: "테스트를 실행하고 실패 원인을 분석해줘.")

Git 보조

변경사항 확인, 커밋 메시지 작성, PR 준비를 도와줌 (예: "git diff를 보고 리뷰해줘.")

중요한 점은 Claude Code가 실제 파일과 터미널 명령을 다룰 수 있다는 것입니다. 그래서 편리하지만, 동시에 안전하게 써야 합니다.

04Claude Code의 3단계 구조

Claude Code는 크게 3개의 층으로 이해하면 쉽습니다.

Extension Layer
- MCP
- Hooks
- Skills
- Plugins

Delegation Layer
- Subagents

Core Layer
- 기본 대화
- 파일 읽기
- 파일 수정
- 명령 실행

05Core Layer

가장 기본이 되는 대화 공간입니다. 여기에서 사용자는 Claude에게 질문합니다.

이 프로젝트가 어떤 구조인지 설명해줘.

Claude는 파일을 읽고, 필요한 내용을 정리하고, 답변합니다.

초보자는 처음에 Core Layer만 잘 써도 충분합니다.

06Delegation Layer

큰 작업을 작은 작업으로 나누어 처리하는 층입니다. 예를 들어 이런 상황에서 유용합니다.

전체 코드베이스에서 인증 관련 파일을 찾아보고,
보안상 위험한 부분을 정리해줘.

이런 작업은 범위가 넓습니다. Claude Code는 필요할 때 별도의 subagent에게 탐색이나 분석을 맡길 수 있습니다.

초보자는 지금 당장 깊게 몰라도 됩니다. 나중에 큰 프로젝트를 다룰 때 배우면 됩니다.

07Extension Layer

Claude Code를 외부 도구와 연결하거나 자동화하는 층입니다. 대표적으로 아래 기능들이 있습니다.

MCP

GitHub, DB, Sentry 같은 외부 도구 연결

Hooks

특정 상황에서 명령을 자동 실행

Skills

특정 작업에 필요한 전문 지식 추가

Plugins

설정과 기능을 패키지처럼 배포

초보자는 처음부터 MCP, hooks, plugins를 설정하지 않아도 됩니다. 먼저 기본 대화, 파일 읽기, 수정 승인 흐름부터 익히는 것이 좋습니다.

08실제 사용 흐름

Claude Code의 가장 기본적인 사용 흐름은 다음과 같습니다.

프로젝트 폴더로 이동한다.
claude 명령어로 실행한다.
Claude에게 프로젝트를 읽게 한다.
설명을 받는다.
수정이 필요하면 먼저 계획을 요청한다.
계획을 확인한 뒤 수정하게 한다.
git diff로 변경사항을 확인한다.

터미널에서는 보통 이렇게 시작합니다.

cd ~/my-project
claude

Claude Code 안에서는 이렇게 요청할 수 있습니다.

이 프로젝트의 전체 구조를 초보자도 이해할 수 있게 설명해줘.
먼저 중요한 폴더와 파일부터 정리해줘.
아직 파일은 수정하지 마.

09좋은 첫 질문의 3가지 이유

위 요청은 초보자에게 좋은 첫 질문입니다.

프로젝트 이해부터 시작

바로 수정하지 않아서 안전함

중요한 파일을 먼저 파악

전체 구조를 빠르게 이해할 수 있음

"수정하지 마"라고 명시

실수로 파일이 바뀌는 일을 줄임

10초보자에게 가장 중요한 사용 원칙

Claude Code를 처음 쓸 때는 아래 흐름을 반복하는 것이 좋습니다.

1설명 요청

2계획 요청

3수정 승인

4변경사항 확인

5테스트 실행

11버그 수정 예시

예를 들어 버그를 고치고 싶다면 이렇게 말합니다.

로그인 오류가 발생하고 있어.
먼저 관련 파일을 찾아서 원인을 설명해줘.
아직 코드는 수정하지 말고, 수정 계획만 제안해줘.

그다음 계획이 마음에 들면 이렇게 말합니다.

좋아. 방금 제안한 계획대로 수정해줘.
수정 후 어떤 파일을 바꿨는지도 정리해줘.

수정 후에는 반드시 이렇게 확인합니다.

변경사항을 git diff 기준으로 요약해줘.
위험한 변경이나 의도치 않은 수정이 있는지도 확인해줘.

12예시 프롬프트 ① · ②

프로젝트 처음 볼 때

이 프로젝트를 처음 보는 개발자라고 생각하고 설명해줘.
1. 프로젝트의 목적
2. 주요 폴더 구조
3. 실행 방법으로 보이는 명령어
4. 먼저 읽어야 할 파일
순서로 정리해줘.
아직 파일은 수정하지 마.

특정 기능을 찾을 때

로그인 기능이 어디에서 처리되는지 찾아줘.
관련 파일과 함수 이름을 정리해줘.
아직 수정하지 말고 구조만 설명해줘.

13예시 프롬프트 ③ · ④

수정 전에 계획을 받을 때

회원가입 입력 검증을 추가하고 싶어.
먼저 현재 구조를 확인한 뒤,
어떤 파일을 어떻게 수정할지 계획만 작성해줘.
내가 승인하기 전까지 파일은 수정하지 마.

변경 후 검토할 때

방금 수정한 내용을 검토해줘.
git diff 기준으로 변경된 파일, 변경 이유, 위험 요소를 정리해줘.
테스트가 필요하면 어떤 테스트를 실행해야 하는지도 알려줘.

14초보자가 자주 하는 실수 ①

실수 1. 바로 "고쳐줘"라고 말한다

나쁜 예:

로그인 안 돼. 고쳐줘.

이렇게 말하면 Claude가 너무 넓은 범위를 추측할 수 있습니다.

좋은 예:

로그인 오류가 있어.
먼저 관련 파일을 찾아 원인을 설명해줘.
아직 수정하지 말고 수정 계획만 제안해줘.

15초보자가 자주 하는 실수 ②

실수 2. 파일 수정 후 확인하지 않는다

Claude가 수정한 뒤에는 반드시 확인해야 합니다.

git status
git diff

Claude Code 안에서는 이렇게 요청할 수 있습니다.

git diff를 기준으로 변경사항을 요약해줘.
의도치 않은 변경이 있는지도 확인해줘.

16초보자가 자주 하는 실수 ③

실수 3. 민감 정보를 그대로 보여준다

아래 파일은 조심해야 합니다.

.env
.env.local
credentials.json
private-key.pem
id_rsa
config/secrets.yml

Claude에게 이런 식으로 말하는 습관이 좋습니다.

민감 정보 파일은 읽지 말고,
필요하면 어떤 값이 필요한지만 설명해줘.

17초보자가 자주 하는 실수 ④

실수 4. 큰 작업을 한 번에 맡긴다

나쁜 예:

전체 프로젝트를 리팩터링하고 테스트까지 다 고쳐줘.

좋은 예:

먼저 리팩터링이 필요한 부분을 찾아줘.
그다음 우선순위를 정리하고,
1단계 작업 계획만 제안해줘.

Claude Code는 강력하지만, 큰 작업일수록 단계별로 나누는 것이 안전합니다.

18체크리스트

Claude Code를 처음 사용할 때 아래 항목을 확인하세요.

Claude Code는 터미널에서 쓰는 CLI 도구

□

프로젝트 폴더 안에서 실행 필수

□

Claude가 파일을 읽고 수정 가능

□

수정 전 계획 요청 필수

□

민감 정보 파일 보호

□

변경 후 git status, diff 확인

□

큰 작업은 단계별로 나누기

□

섹션 01 · 마무리

이 단원에서 기억할 것

Claude Code는 단순한 질문 답변 도구가 아닙니다. 프로젝트 안에서 코드를 읽고, 수정하고, 명령을 실행할 수 있는 개발 에이전트입니다.

초보자는 처음부터 고급 기능을 배울 필요가 없습니다. 먼저 아래 흐름만 익히면 됩니다.

설명 요청 → 계획 확인 → 수정 승인 → 변경사항 확인

이 흐름을 지키면 Claude Code를 훨씬 안전하게 사용할 수 있습니다.

다음 단원

2단원. 설치 전 준비사항 확인하기

2. 설치 전 준비사항 확인하기

01핵심 개념

Claude Code를 설치하기 전에 먼저 확인할 것은 5가지입니다.

운영체제

Claude Code가 실행 가능한 환경인지 확인

터미널

Claude Code는 기본적으로 CLI 도구이므로 터미널이 필요

계정 또는 인증 방식

Claude Code를 사용하려면 로그인 또는 조직 인증이 필요

작업할 프로젝트 폴더

Claude Code는 프로젝트 폴더 안에서 가장 잘 작동

안전 설정 습관

파일 수정, 명령 실행, 비용 발생 가능성이 있기 때문

02왜 필요한가

Claude Code는 일반 앱처럼 "설치 후 클릭해서 실행"하는 도구가 아닙니다. 보통 이런 흐름으로 사용합니다.

1프로젝트 폴더로 이동

2터미널에서 claude 실행

3로그인

4Claude가 프로젝트 파일을 읽음

5필요하면 파일 수정 또는 명령 실행

그래서 설치 전에 환경을 확인하지 않으면 문제가 생길 수 있습니다.

03설치 전에 발생할 수 있는 문제들

OS가 맞지 않음

오래된 macOS, 오래된 Linux 배포판

터미널이 익숙하지 않음

명령어를 어디에 입력해야 할지 모름

인증 준비가 안 됨

로그인 또는 Console 권한이 없음

프로젝트 폴더가 정리되지 않음

Claude가 너무 많은 파일을 읽음

민감 정보가 섞여 있음

.env, API key, private key 노출 위험

비용 구조를 모름

API 사용량 또는 구독 한도 관리 실패

설치 자체는 어렵지 않습니다. 하지만 설치 전 준비가 부족하면 첫 사용 경험이 복잡해집니다.

04시스템 요구사항

공식 문서 기준으로 Claude Code는 다음 환경에서 실행됩니다.

macOS

macOS 13.0 이상

Windows

Windows 10 1809 이상 또는 Windows Server 2019 이상

Linux

Ubuntu 20.04 이상, Debian 10 이상, Alpine Linux 3.19 이상

메모리

4GB RAM 이상

CPU

x64 또는 ARM64

네트워크

인터넷 연결 필요

Shell

Bash, Zsh, PowerShell, CMD

지역

Anthropic 지원 국가 필요

이 정보는 작성 시점 기준이며, 실제 설치 전에는 공식 문서와 claude --version, claude doctor를 함께 확인하세요.

05macOS에서 환경 확인하기

macOS에서는 터미널을 열고 다음 명령어를 실행합니다.

sw_vers
uname -m

예상 결과는 대략 이런 형태입니다.

ProductVersion: 14.x.x
arm64

ProductVersion이 13.0 이상이면 기본 조건을 만족합니다. arm64는 Apple Silicon, x86_64는 Intel Mac입니다.

06Windows PowerShell에서 환경 확인하기

Windows에서는 PowerShell을 열고 다음 명령어를 실행합니다.

systeminfo | findstr /B /C:"OS Name" /C:"OS Version"
$PSVersionTable.PSVersion

Windows에서는 PowerShell 또는 CMD를 사용할 수 있습니다. 공식 문서는 Windows에서 PowerShell용 설치 방식과 CMD용 설치 방식을 구분해서 안내하며, 네이티브 Windows에서는 Claude Code가 Bash 도구를 쓸 수 있도록 Git for Windows 설치를 권장합니다.

07Linux / WSL에서 환경 확인하기

Linux 또는 WSL에서는 다음 명령어를 실행합니다.

cat /etc/os-release
uname -m

Ubuntu라면 이런 정보가 보입니다.

NAME="Ubuntu"
VERSION_ID="22.04"

Ubuntu 20.04 이상이면 기본 조건을 만족합니다. Windows 사용자는 가능하면 WSL 환경에서 Linux 방식으로 사용하는 것도 선택지입니다.

08터미널 준비하기

Claude Code는 기본적으로 터미널에서 실행합니다. 대표적인 터미널은 아래와 같습니다.

macOS

Terminal, iTerm2, Warp 등

Windows

Windows Terminal, PowerShell, CMD, WSL

Linux

기본 Terminal, GNOME Terminal, Konsole 등

IDE 사용자

VS Code Terminal, JetBrains Terminal

Claude Code는 기본적으로 별도 설정 없이 대부분의 터미널에서 작동합니다. 초보자는 처음에 복잡한 설정을 하지 않아도 됩니다.

09터미널 기본 명령어

초보자는 아래 3가지 기본 명령어만 할 수 있으면 충분합니다.

cd

폴더 이동

ls

현재 폴더의 파일 목록 보기

pwd

현재 위치 확인

Windows PowerShell에서는 ls와 cd도 그대로 사용할 수 있습니다.

10계정과 인증 방식 준비하기

Claude Code를 사용하려면 인증이 필요합니다. 대표적인 인증 방식은 다음과 같습니다.

Claude Pro / Max

개인 사용자

Claude Team / Enterprise

팀 또는 회사 사용자

Claude Console

API 기반 과금이나 조직 관리가 필요한 사용자

Amazon Bedrock / Google Vertex AI / Microsoft Foundry

기업 클라우드 환경 사용자

초보자라면 보통 개인 사용자는 Claude Pro 또는 Max 계정, 팀 사용자는 회사에서 초대한 Team 또는 Enterprise 계정, 개발자/조직 사용자는 Claude Console 계정입니다.

11비용 발생 가능성 이해하기

Claude Code는 사용 방식에 따라 비용이나 사용량 제한에 영향을 줄 수 있습니다. 특히 아래 작업은 사용량이 커질 수 있습니다.

큰 코드베이스 전체 분석

읽는 파일과 컨텍스트가 많음

긴 세션 유지

대화 기록과 파일 내용이 누적됨

여러 번 테스트 실패 분석

명령 출력과 재시도가 많음

subagents, MCP, plugins 사용

추가 도구와 에이전트가 토큰을 사용

고성능 모델 사용

모델별 비용 또는 사용량 제한 차이

12비용 최적화 습관

초보자는 처음부터 비용 최적화를 깊게 알 필요는 없습니다. 대신 아래 습관을 가지면 됩니다.

처음에는 작은 질문부터 한다.
전체 프로젝트를 한 번에 다 읽게 하지 않는다.
/cost 또는 /usage 계열 명령으로 사용량을 확인한다.
큰 작업은 계획부터 요청한다.
자동화 기능은 충분히 익힌 뒤 사용한다.

13프로젝트 폴더 준비하기

Claude Code는 보통 프로젝트 루트 폴더에서 실행합니다. 예를 들어 프로젝트 구조가 이렇게 되어 있다면:

my-project/
├── src/
├── tests/
├── package.json
├── README.md
└── .git/

이 폴더 안에서 실행합니다.

cd ~/my-project
claude

14프로젝트 루트에서 실행해야 하는 이유

전체 구조 파악

Claude가 주요 폴더와 설정 파일을 찾기 쉬움

Git 상태 확인

git status, git diff 확인 가능

테스트 실행

프로젝트 명령어를 올바른 위치에서 실행 가능

파일 수정 범위 명확

어디까지 수정 대상인지 분명해짐

설치 전에는 프로젝트 폴더에서 pwd, ls, git status를 실행해 볼 수 있습니다. git status가 작동하지 않으면 Git 저장소가 아닐 수 있습니다.

15민감 정보 파일 확인하기

Claude Code는 프로젝트 파일을 읽을 수 있습니다. 그래서 설치 전에 민감 정보 파일이 있는지 확인해야 합니다. 특히 아래 파일은 조심하세요.

.env
.env.local
.env.production
credentials.json
service-account.json
private-key.pem
id_rsa
id_rsa.pub
*.key
*.pem

설치 전 프로젝트에서 ls -a로 확인해 볼 수 있습니다.

16민감 정보 보호 방법

민감 파일이 있다면 Claude Code를 사용할 때 이렇게 말하는 습관을 들이세요.

.env, API key, private key, credentials 파일은 읽지 마.
필요하면 어떤 환경 변수가 필요한지만 이름으로 설명해줘.

Claude Code는 기본적으로 읽기 전용 권한에서 시작하고, 파일 편집이나 명령 실행이 필요할 때 사용자의 승인을 요청합니다. 사용자가 제안된 코드와 명령을 승인하기 전에 직접 검토할 책임이 있습니다.

17Git 준비하기

Claude Code를 제대로 쓰려면 Git 사용 습관이 중요합니다. 설치 전 아래 명령어가 작동하는지 확인하세요.

git --version
git status

Git 저장소가 아니라면 이런 메시지가 나올 수 있습니다.

fatal: not a git repository

Claude Code를 쓰기 전 프로젝트가 이미 Git으로 관리되고 있다면 좋습니다. 아니라면 중요한 파일을 백업하거나, Git 저장소를 만든 뒤 작업하는 편이 안전합니다.

18안전한 작업 흐름

초보자에게 가장 안전한 작업 흐름은 다음과 같습니다.

1작업 전 git status 확인

2Claude에게 수정 계획 요청

3수정 승인

4git diff 확인

5테스트 실행

6커밋

19설치 전 준비 체크리스트 ①

아래 항목을 확인한 뒤 다음 단원에서 설치를 진행하세요.

내 OS가 Claude Code 지원 범위에 들어간다

□

터미널 또는 PowerShell을 열 수 있다

□

cd, ls, pwd 정도의 기본 명령어를 사용할 수 있다

□

Claude 계정, 구독, Console, 또는 회사 인증 방식이 준비되어 있다

□

작업할 프로젝트 폴더가 있다

□

프로젝트 루트 폴더가 어디인지 안다

□

20설치 전 준비 체크리스트 ②

Git이 설치되어 있다

□

git status를 실행해 봤다

□

.env, API key, credentials 파일 위치를 알고 있다

□

민감 정보는 Claude에게 읽히거나 붙여넣지 않기로 했다

□

비용 또는 사용량 제한이 생길 수 있음을 이해했다

□

21초보자가 자주 하는 실수 ①

실수 1. 아무 폴더에서나 실행한다

나쁜 예:

cd ~
claude

홈 폴더에서 실행하면 Claude가 프로젝트 맥락을 제대로 잡기 어렵습니다.

좋은 예:

cd ~/my-project
claude

항상 작업할 프로젝트 루트 폴더에서 실행하세요.

22초보자가 자주 하는 실수 ②

실수 2. 민감 파일이 있는지 확인하지 않는다

나쁜 요청:

내 .env 파일을 읽고 설정을 고쳐줘.

좋은 요청:

.env 파일은 읽지 말고,
이 프로젝트에 필요한 환경 변수 이름만 추정해서 설명해줘.

23초보자가 자주 하는 실수 ③

실수 3. Git 상태를 확인하지 않고 수정한다

나쁜 흐름:

이 프로젝트 전체를 정리해줘.

좋은 흐름: 먼저 터미널에서

git status

그다음 Claude Code 안에서:

현재 변경사항이 있는지 먼저 확인해줘.
그다음 수정 계획만 제안해줘.
아직 파일은 수정하지 마.

24초보자가 자주 하는 실수 ④

실수 4. 비용 구조를 모르고 큰 작업을 맡긴다

나쁜 예:

프로젝트 전체를 다 읽고 모든 문제를 고쳐줘.

좋은 예:

먼저 프로젝트 구조만 간단히 파악해줘.
중요한 파일 5개만 골라서 설명해줘.
아직 수정하지 마.

큰 작업은 나누어 요청해야 합니다.

섹션 02 · 마무리

이 단원에서 기억할 것

Claude Code 설치 전에는 아래 5가지를 먼저 확인해야 합니다.

🖥️OS

⌨️터미널

🔐계정

📁프로젝트 폴더

🔒민감 정보와 Git 상태

설치보다 중요한 것은 안전하게 사용할 준비입니다.

핵심 원칙

프로젝트 루트에서 실행 · 민감 정보 보호 · 수정 전 계획 · 수정 후 확인

3. Claude Code 설치하고 버전 확인하기

01핵심 개념

이번 단원에서는 Claude Code를 실제로 설치합니다.

초보자는 아래 순서대로 진행하면 됩니다.

1. 내 OS에 맞는 설치 명령어를 고른다.
2. 터미널에 설치 명령어를 입력한다.
3. claude --version으로 설치 여부를 확인한다.
4. claude doctor로 환경 상태를 점검한다.
5. claude를 실행해 로그인한다.

Claude Code 공식 문서는 현재 설치 방식으로 Native Install, Homebrew, WinGet을 안내합니다.

주의

이 정보는 작성 시점 기준입니다. 설치 명령어, 지원 OS, 업데이트 방식은 바뀔 수 있으므로 설치 전에는 공식 문서를 확인하세요.

02왜 필요한가

Claude Code는 터미널에서 실행되는 도구입니다. 설치가 제대로 되었는지 확인하지 않으면 다음 단계에서 문제가 생깁니다.

명령어를 찾지 못함

command not found: claude

잘못된 터미널에서 명령 실행

PowerShell 명령을 CMD에 입력

오래된 버전 사용

최신 기능이 동작하지 않음

로그인 문제

인증 상태를 확인하지 못함

프로젝트에서 실행 실패

PATH 또는 셸 설정 문제

그래서 설치 후 바로 코딩 작업을 시작하지 말고, 먼저 버전 확인 → 환경 진단 → 로그인 확인을 해야 합니다.

03설치 방법 한눈에 보기

macOS

Native Install 또는 Homebrew / curl 또는 brew

Linux

Native Install / curl

WSL

Native Install / WSL 터미널 안에서 curl

Windows PowerShell

Native Install / irm

Windows CMD

Native Install / curl + install.cmd

Windows 패키지 관리자

WinGet / winget

공식 문서는 Native Install을 추천 설치 방식으로 표시합니다. Native 설치는 자동 업데이트를 지원하며, Homebrew와 WinGet 설치는 자동 업데이트되지 않으므로 별도 업그레이드 명령을 실행해야 합니다.

04macOS에 설치하기

macOS에서는 Native Install을 사용할 수 있습니다.

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

이 명령은 공식 설치 스크립트를 내려받아 실행합니다. 터미널에 붙여넣기 전에 공식 문서의 명령어와 같은지 확인하세요.

Homebrew를 쓰는 사용자는 안정 채널을 권장합니다.

brew install --cask claude-code

Homebrew에는 안정 채널인 claude-code와 최신 채널인 claude-code@latest가 있습니다. 안정 채널은 보통 최신보다 약간 늦고, 최신 채널은 새 버전을 빠르게 받습니다. 최신 채널을 원하면:

brew install --cask claude-code@latest

초보자는 보통 안정 채널을 권장합니다.

05Linux / WSL에 설치하기

Linux와 WSL에서는 macOS와 같은 Native Install 명령을 사용합니다.

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

WSL을 쓰는 경우에는 PowerShell이 아니라 WSL 터미널 안에서 설치하고 실행해야 합니다.

설치 후 터미널을 다시 열거나, PATH가 갱신되도록 셸을 다시 시작합니다.

exec "$SHELL"

그다음 확인합니다.

claude --version

06Windows PowerShell에 설치하기

Windows PowerShell에서는 아래 명령을 사용합니다.

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

PowerShell 프롬프트는 보통 이렇게 생겼습니다.

PS C:\Users\YourName>

irm 명령이 인식되지 않으면 CMD에 PowerShell 명령을 입력한 것일 수 있습니다. 설치 후 새 PowerShell을 열고 확인합니다.

claude --version

07Windows CMD에 설치하기

CMD에서는 아래 명령을 사용합니다.

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

CMD 프롬프트는 보통 이렇게 생겼습니다.

C:\Users\YourName>

PowerShell과 CMD를 헷갈리면 설치 오류가 날 수 있습니다. 초보자는 가능하면 Windows Terminal에서 PowerShell을 열고 PowerShell용 명령을 쓰는 편이 더 쉽습니다.

08Windows에서 Git for Windows는 꼭 필요한가

필수는 아니지만, 설치해두면 좋습니다.

공식 문서는 Windows 네이티브 환경에서 Git for Windows를 권장합니다. Git for Windows가 있으면 Claude Code가 Git Bash를 Bash 도구로 사용할 수 있고, 없으면 PowerShell 도구를 사용합니다. WSL 환경에서는 Git for Windows가 필요하지 않습니다.

Windows 네이티브

권장

Windows PowerShell만 사용

없어도 가능

WSL

필요 없음

Git Bash 기반 명령을 쓰고 싶음

설치 권장

09설치 확인하기

설치가 끝나면 가장 먼저 버전을 확인합니다.

claude --version

PowerShell에서도 같습니다.

claude --version

정상 설치되었다면 버전 정보가 출력됩니다.

2.x.x

공식 문서는 더 자세한 설치 및 구성 점검에는 claude doctor를 실행하라고 설명합니다.

10환경 진단하기

버전 확인 후에는 진단 명령을 실행합니다.

claude doctor

Windows PowerShell에서도 같습니다.

claude doctor

claude doctor는 설치 상태, 환경 구성, 문제 가능성을 점검하는 데 사용합니다. 초보자는 설치 직후 한 번 실행해두면 좋습니다.

문제가 없다면 다음 단계로 넘어갑니다.

claude

11로그인하기

Claude Code를 처음 실행하면 로그인 안내가 나옵니다.

claude

Claude Code 안에서 다시 로그인해야 할 때는 다음 명령을 입력할 수 있습니다.

/login

공식 문서는 Claude 구독 계정, Claude Console 계정, 또는 지원되는 클라우드 제공자를 통해 로그인할 수 있다고 안내합니다.

터미널에서 인증 상태를 확인하려면 다음 명령을 사용할 수 있습니다.

claude auth status

12프로젝트 폴더에서 실행하기

설치와 로그인이 끝났다면 프로젝트 폴더로 이동합니다.

cd /path/to/your/project
claude

예를 들어 macOS나 Linux에서는 다음처럼 실행할 수 있습니다.

cd ~/my-project
claude

Windows PowerShell에서는 다음처럼 실행할 수 있습니다.

cd C:\Users\YourName\my-project
claude

첫 질문은 안전하게 시작하세요.

이 프로젝트의 구조를 설명해줘.
중요한 폴더와 파일만 먼저 정리해줘.
아직 파일은 수정하지 마.

13업데이트하기

Native Install로 설치한 경우 Claude Code는 자동 업데이트를 지원합니다. 반면 Homebrew와 WinGet 설치는 자동 업데이트되지 않으므로 수동 업그레이드가 필요합니다.

수동 업데이트는 다음 명령을 사용합니다.

claude update

Homebrew 안정 채널로 설치했다면:

brew upgrade claude-code

Homebrew 최신 채널로 설치했다면:

brew upgrade claude-code@latest

WinGet으로 설치했다면:

winget upgrade Anthropic.ClaudeCode

14안정 채널과 최신 채널 선택하기

초보자는 보통 stable 또는 안정 채널을 쓰는 것이 좋습니다.

stable

안정성을 우선 / 초보자, 실무 프로젝트

latest

새 기능을 빠르게 받음 / 실험적 기능을 테스트하는 사용자

Native Install에서는 stable 채널을 지정해 설치할 수 있습니다.

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

Windows PowerShell에서는 다음과 같습니다.

& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable

15특정 버전 설치하기

팀에서 특정 버전을 맞춰야 하는 경우가 있습니다.

예를 들어 특정 버전을 설치하려면 다음처럼 실행합니다.

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

Windows PowerShell에서는 다음과 같습니다.

& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 2.1.89

다만 초보자는 특별한 이유가 없다면 특정 버전을 고정하지 않는 편이 좋습니다. 팀 프로젝트에서만 팀 리더나 문서의 지시에 따라 버전을 맞추세요.

16설치가 안 될 때 확인할 것

문제 1. `claude: command not found`

설치 후 터미널이 PATH를 아직 반영하지 못했을 수 있습니다.

macOS / Linux / WSL에서는 터미널을 새로 열거나 다음을 실행합니다.

exec "$SHELL"

그다음 다시 확인합니다.

claude --version

17문제 2, 3 진단하기

문제 2. PowerShell과 CMD 명령을 헷갈렸다

PowerShell에서는:

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

CMD에서는:

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

irm이 인식되지 않으면 CMD에 PowerShell 명령을 넣은 것입니다. && 오류가 나오면 PowerShell에 CMD 명령을 넣은 것일 수 있습니다.

문제 3. Windows에서 Bash 관련 문제가 난다

Windows 네이티브 환경에서는 Git for Windows 설치를 고려하세요. Git Bash가 있으면 Claude Code가 Bash 도구를 사용할 수 있습니다.

Git Bash 경로를 못 찾는 경우에는 나중에 설정 파일에서 경로를 지정할 수 있습니다.

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

18제거가 필요한 경우

제거 명령은 실제 파일을 삭제합니다. 따라서 설치를 되돌리거나 재설치해야 하는 경우에만 실행하세요.

Native Install을 macOS, Linux, WSL에서 제거하려면:

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

Windows PowerShell에서는:

Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

Homebrew로 설치했다면:

brew uninstall --cask claude-code

WinGet으로 설치했다면:

winget uninstall Anthropic.ClaudeCode

19실제 설치 예시

macOS 초보자 추천 흐름

curl -fsSL https://claude.ai/install.sh | bash
claude --version
claude doctor
cd ~/my-project
claude

Claude Code 안에서:

이 프로젝트 구조를 설명해줘.
아직 파일은 수정하지 마.

20Windows와 WSL 예시

Windows PowerShell 초보자 추천 흐름

irm https://claude.ai/install.ps1 | iex
claude --version
claude doctor
cd C:\Users\YourName\my-project
claude

WSL 초보자 추천 흐름

curl -fsSL https://claude.ai/install.sh | bash
claude --version
claude doctor
cd ~/my-project
claude

WSL에서는 Windows 경로인 /mnt/c/...에서 작업할 수도 있지만, Linux 개발 도구를 많이 쓴다면 /home/... 아래 프로젝트에서 작업하는 편이 더 단순합니다.

21초보자가 자주 하는 실수

실수 1. 설치 후 바로 큰 작업을 맡긴다

나쁜 예: 전체 프로젝트 분석하고 버그 다 고쳐줘.

좋은 예: 먼저 이 프로젝트 구조만 설명해줘. 아직 파일은 수정하지 마.

실수 2. 버전 확인을 하지 않는다

설치 후 반드시 확인하세요. claude --version / 문제가 생겼을 때는 claude doctor를 실행합니다.

실수 3. PowerShell과 CMD를 구분하지 않는다

터미널 앞에 PS가 있으면 PowerShell입니다(PS C:UsersYourName>). PS가 없으면 CMD일 가능성이 큽니다(C:UsersYourName>).

22더 많은 실수들

실수 4. 프로젝트 폴더가 아닌 곳에서 실행한다

나쁜 예:

cd ~
claude

좋은 예:

cd ~/my-project
claude

Claude Code는 현재 폴더를 기준으로 프로젝트를 이해합니다. 반드시 작업할 프로젝트 루트에서 실행하세요.

실수 5. 삭제 명령을 가볍게 실행한다

아래 명령은 실제 파일을 삭제합니다. rm -rf ~/.claude / 이런 명령은 설정, 세션 기록, 허용 권한 등을 지울 수 있습니다. 초보자는 공식 문서나 팀 지시 없이 실행하지 않는 것이 안전합니다.

23체크리스트

내 OS에 맞는 설치 명령어를 골랐다

□

PowerShell과 CMD를 구분했다

□

설치 명령어를 공식 문서 기준으로 확인했다

□

claude --version을 실행했다

□

claude doctor를 실행했다

□

claude를 실행해 로그인했다

□

프로젝트 루트 폴더에서 실행했다

□

첫 질문에서 "아직 파일은 수정하지 마"라고 명시했다

□

업데이트 명령어를 알고 있다

□

삭제 명령은 신중하게 실행해야 함을 이해했다

□

섹션 03 · 마무리

이 단원에서 기억할 것

Claude Code 설치 후에는 바로 코딩을 맡기지 말고 아래 순서로 확인하세요.

1설치

2claude --version

3claude doctor

4claude

5로그인 및 첫 질문

초보자에게 가장 안전한 첫 질문은 다음과 같습니다.

이 프로젝트 구조를 설명해줘. 중요한 폴더와 파일만 먼저 정리해줘. 아직 파일은 수정하지 마.

다음 단원

4단원. 첫 번째 세션 시작하기

4. 첫 번째 세션 시작하기

01핵심 개념

이번 단원에서는 Claude Code를 처음 실행하고, 첫 질문을 안전하게 던지는 방법을 배웁니다.

첫 세션의 목표는 코드를 바로 수정하는 것이 아닙니다. 목표는 먼저 Claude Code가 프로젝트를 이해하게 만드는 것입니다.

1프로젝트 폴더로 이동

2claude 실행

3로그인 확인

4프로젝트 구조 질문

5중요한 파일 확인

6수정 없이 설명만 받기

02왜 필요한가

Claude Code는 현재 폴더를 기준으로 프로젝트를 이해합니다. 그래서 첫 세션을 아무 위치에서 시작하면 프로젝트 구조를 제대로 파악하지 못할 수 있습니다.

나쁜 시작:

cd ~
claude

좋은 시작:

cd ~/my-project
claude

프로젝트 디렉터리에서 실행해야 Claude Code가 프로젝트 파일을 직접 읽고 구조를 파악할 수 있습니다.

03첫 세션 시작 전 확인하기

Claude Code를 실행하기 전에 프로젝트 폴더에서 아래 명령어를 먼저 실행하세요.

pwd
ls
git status

각 명령어의 의미:

pwd

현재 내가 어느 폴더에 있는지 확인

현재 폴더의 파일 목록 확인

git status

Git 변경사항이 있는지 확인

04변경사항이 많을 때

git status에서 이미 수정된 파일이 많다면, Claude Code를 시작하기 전에 어떤 변경사항인지 먼저 확인하는 것이 좋습니다.

git diff

첫 세션에서는 특히 아래 원칙을 지키세요.

현재 상태 확인 → Claude 실행 → 설명 요청 → 수정은 나중에

05Claude Code 실행하기

프로젝트 폴더에서 다음 명령을 실행합니다.

claude

정상적으로 실행되면 Claude Code 화면이 열립니다. 처음 사용하는 경우 로그인 안내가 나올 수 있습니다.

Claude Code 안에서 로그인 명령을 직접 입력해야 한다면:

/login

06첫 질문은 이렇게 시작하기

첫 질문은 절대 "고쳐줘"로 시작하지 마세요. 먼저 프로젝트를 이해시키는 질문이 좋습니다.

07첫 세션에서 하지 말아야 할 요청

첫 세션에서는 Claude가 프로젝트를 아직 충분히 이해하지 못했습니다. 아래 요청은 너무 빠릅니다.

나쁜 예

전체 프로젝트를 리팩터링해줘.
버그 다 찾아서 고쳐줘.
테스트 실패하는 것 전부 수정해줘.
코드 스타일을 전부 바꿔줘.

좋은 예

먼저 프로젝트 구조를 파악해줘.
수정이 필요해 보이는 부분이 있으면 바로 고치지 말고,
후보만 정리해줘.

08Claude의 답변을 받은 뒤 해야 할 일

Claude가 프로젝트 구조를 설명하면 바로 수정 요청을 하지 말고, 먼저 답변을 검증하세요.

다음 질문을 이어서 할 수 있습니다.

방금 설명한 내용 중에서 추측한 부분과
실제 파일을 보고 확인한 부분을 구분해줘.

핵심 파일 5개만 골라서,
각 파일이 어떤 역할을 하는지 설명해줘.
아직 수정하지 마.

이 프로젝트를 실행하려면 어떤 명령어가 필요해 보이는지 알려줘.
명령어를 바로 실행하지 말고 후보만 정리해줘.

이렇게 하면 Claude가 너무 빠르게 수정이나 실행으로 넘어가는 것을 막을 수 있습니다.

09첫 번째 명령 실행은 신중하게 하기

Claude Code는 테스트, 빌드, lint 같은 명령을 실행할 수 있습니다. 하지만 첫 세션에서는 명령을 바로 실행하게 하지 말고, 먼저 후보를 확인하세요.

좋은 요청

이 프로젝트에서 테스트를 실행하는 명령어가 무엇인지 찾아줘.
아직 실행하지 말고 후보만 알려줘.

승인 예시

좋아. npm test를 실행해줘.
실행 결과를 요약하고, 실패하면 원인 후보만 정리해줘.
아직 파일은 수정하지 마.

피해야 할 요청

테스트 돌리고 실패하면 알아서 다 고쳐줘.

설치, 삭제, 배포, 데이터베이스 마이그레이션 명령은 더 조심해야 합니다.

10첫 번째 코드 수정은 언제 해야 하나

첫 세션에서 바로 큰 수정은 하지 않는 것이 좋습니다. 수정이 필요하다면 아주 작은 작업부터 시작하세요.

예시: 작은 문서 수정

README.md에 프로젝트 실행 방법을 한 문단 추가하고 싶어.
먼저 어떤 내용을 추가할지 계획만 보여줘.
아직 수정하지 마.

계획 승인

좋아. README.md만 수정해줘.
다른 파일은 건드리지 마.
수정 후 변경 내용을 요약해줘.

초보자는 개별 변경을 확인하는 흐름이 안전합니다.

11변경사항 확인하기

Claude가 파일을 수정했다면 반드시 확인합니다.

터미널에서

git status
git diff

Claude Code 안에서 요청

방금 변경한 내용을 git diff 기준으로 설명해줘.
1. 변경된 파일
2. 변경 이유
3. 의도치 않은 변경 가능성
4. 테스트 필요 여부
순서로 정리해줘.

권장 흐름

1수정 요청

2변경 요약 받기

3git diff 확인

4테스트 실행

5커밋 여부 결정

12첫 세션에서 알아두면 좋은 명령어

Claude Code 안에서는 /를 입력하면 사용 가능한 명령어를 볼 수 있습니다. 초보자가 첫날 알아두면 좋은 명령은 다음과 같습니다.

/help

사용 가능한 도움말 확인

/login

로그인 또는 계정 재인증

/resume

이전 대화 다시 열기

/clear

현재 작업과 관련 없는 컨텍스트 정리

/compact

긴 대화를 요약해 컨텍스트 압축

/usage

현재 사용량 확인

명령 입력 예시

/help

/usage

/resume

13세션 종료하기

작업이 끝났다면 Claude Code를 종료합니다.

종료 명령

Ctrl+C

종료 전 요청

종료하기 전에는 아래 질문을 해두면 좋습니다.

이번 세션에서 확인한 내용과 변경한 내용을 요약해줘.
다음에 이어서 작업할 때 먼저 해야 할 일도 정리해줘.

종료 전 Git 확인

수정한 파일이 있다면 종료 전 반드시 확인합니다.

git status
git diff

14이전 세션 이어가기

Claude Code는 세션을 저장하므로 이전 대화를 이어갈 수 있습니다.

가장 최근 세션 이어가기

claude -c

또는 긴 옵션으로:

claude --continue

세션 목록에서 선택하기

claude --resume

Claude Code 안에서

/resume

이전 대화를 불러올 수 있습니다.

15첫 세션 실전 예시 (1~3단계)

1단계. 프로젝트 폴더로 이동

cd ~/my-project
pwd
ls
git status

2단계. Claude Code 실행

claude

3단계. 첫 질문 입력

이 프로젝트를 처음 보는 개발자라고 생각하고 설명해줘.
1. 프로젝트의 목적
2. 주요 폴더 구조
3. 핵심 파일
4. 실행 또는 테스트 명령어 후보
5. 먼저 읽어야 할 파일
순서로 정리해줘.
아직 파일은 수정하지 마.
명령어도 실행하지 마.

16첫 세션 실전 예시 (4~7단계)

4단계. 핵심 파일만 더 자세히 보기

핵심 파일 5개만 골라서 각각의 역할을 설명해줘.
파일을 수정하지 말고 읽기만 해줘.

5단계. 실행 명령어 후보 확인

이 프로젝트를 실행하거나 테스트하는 명령어 후보를 알려줘.
아직 실행하지 말고, 어떤 파일을 근거로 판단했는지도 함께 설명해줘.

6단계. 세션 요약 받기

이번 세션에서 파악한 내용을 요약해줘.
다음 세션에서 이어서 할 만한 작업 3가지만 추천해줘.

7단계. 종료 전 Git 상태 확인

git status

첫 세션에서는 파일을 수정하지 않았기 때문에 변경사항이 없어야 정상입니다.

17초보자가 자주 하는 실수 ①

실수 1. 첫 질문부터 수정 요청을 한다

나쁜 예:

이 프로젝트 문제점 찾아서 전부 고쳐줘.

좋은 예:

이 프로젝트의 구조와 핵심 파일을 먼저 설명해줘.
아직 수정하지 마.

실수 2. 명령어 실행을 한 번에 맡긴다

나쁜 예:

필요한 명령어 다 실행해서 세팅해줘.

좋은 예:

필요해 보이는 설치, 실행, 테스트 명령어 후보를 먼저 정리해줘.
아직 실행하지 마.

18초보자가 자주 하는 실수 ②

실수 3. 변경사항 확인 없이 종료한다

파일을 수정했다면 종료 전 반드시 확인합니다.

git status
git diff

Claude에게도 요약을 요청하세요.

이번 세션에서 변경된 파일과 변경 이유를 정리해줘.

실수 4. 세션을 구분하지 않는다

서로 다른 작업을 한 세션에서 계속 이어가면 컨텍스트가 섞입니다. 아래 작업은 각각 다른 세션으로 나누는 것이 좋습니다.

인증 버그 수정
결제 기능 추가
README 문서 정리
대규모 리팩터링

작업이 바뀌면 새 세션을 시작하거나 /clear를 고려하세요.

19체크리스트

프로젝트 루트 폴더로 이동했다

□

pwd, ls, git status를 확인했다

□

claude 명령으로 첫 세션을 시작했다

□

로그인 상태를 확인했다

□

첫 질문에서 프로젝트 구조 설명을 요청했다

□

"아직 파일은 수정하지 마"라고 명시했다

□

명령어 실행 전 후보만 먼저 요청했다

□

수정이 있었다면 git status, git diff를 확인했다

□

세션 종료 전 요약을 요청했다

□

claude -c, claude --resume, /resume의 차이를 이해했다

□

섹션 04 · 마무리

이 단원에서 기억할 것

첫 세션의 목표는 수정이 아니라 이해입니다. 코드를 바꾸기 전에 먼저 Claude Code가 프로젝트를 충분히 이해하게 만드는 것이 중요합니다.

가장 안전한 첫 질문은 다음과 같습니다.

이 프로젝트가 무엇을 하는지 설명해줘. 중요한 폴더와 파일을 먼저 정리해줘. 아직 파일은 수정하지 마. 명령어도 실행하지 마.

첫 세션의 기본 흐름을 항상 기억하세요.

1프로젝트 폴더 이동

2git status 확인

3claude 실행

4구조 설명 요청

5수정 없이 이해

6세션 요약

다음 단원

5단원. Claude Code와 안전하게 대화하는 법

5. Claude Code 300% 활용하는 법

01핵심 개념

Claude Code를 잘 쓰는 사람과 못 쓰는 사람의 차이는 질문을 어떻게 하느냐에서 갈립니다.

초보자는 보통 이렇게 요청합니다:

이거 고쳐줘.

하지만 Claude Code를 잘 쓰는 사람은 이렇게 요청합니다:

먼저 관련 파일을 찾아서 원인을 설명해줘.
아직 수정하지 말고, 수정 계획만 제안해줘.
내가 승인하면 그때 최소 범위로 수정해줘.

Claude Code는 단순 답변 도구가 아니라, 코드베이스를 읽고, 명령을 실행하고, 파일을 수정할 수 있는 에이전트형 CLI입니다. 이를 효과적으로 활용하려면 설정, 권한, hooks, MCP, subagents 같은 시스템을 이해하고 실제 개발 흐름에 맞게 써야 합니다.

027가지 활용법 개요

이 단원에서는 초보자가 바로 이득을 얻을 수 있는 7가지 활용법을 배웁니다.

1️⃣질문을 작업 단위로 나누기

2️⃣설명 → 계획 → 실행 → 검토 흐름 사용

3️⃣먼저 탐색을 Claude에게 시키기

4️⃣좋은 프롬프트 템플릿 사용

5️⃣세션을 목적별로 나누기

6️⃣Git 기준으로 변경사항 확인

7️⃣반복 작업을 Claude에게 맡기기

03왜 필요한가

Claude Code를 그냥 쓰면 편합니다. 하지만 제대로 쓰면 결과가 달라집니다.

사용 방식

결과

"고쳐줘"

Claude가 범위를 추측함

"전체 프로젝트 봐줘"

비용과 컨텍스트가 커짐

"알아서 해줘"

원하지 않은 수정 가능성 증가

"관련 파일만 찾고 계획부터"

정확도와 안정성 증가

"git diff 기준으로 리뷰"

변경사항 검토가 쉬워짐

"테스트 실패 원인만 분석"

불필요한 수정 감소

Claude Code의 핵심은 한 번에 크게 맡기는 것이 아니라, 작업을 잘게 나누고 Claude를 단계적으로 움직이는 것입니다.

04300% 활용 공식

가장 기본이 되는 공식은 이것입니다.

탐색 → 계획 → 실행 → 검토 → 반복

각 단계에서 Claude에게 시킬 일은 다릅니다.

탐색

관련 파일 찾기 — "관련 파일을 찾아줘. 아직 수정하지 마."

계획

수정 방향 정하기 — "어떤 파일을 어떻게 바꿀지 계획만 작성해줘."

실행

최소 범위 수정 — "계획대로 수정해줘. 다른 파일은 건드리지 마."

검토

변경사항 확인 — "git diff 기준으로 변경사항을 리뷰해줘."

반복

테스트와 개선 — "실패한 테스트 원인을 분석하고 다음 수정안을 제안해줘."

이 흐름을 쓰면 Claude가 갑자기 큰 수정을 하거나, 엉뚱한 파일을 건드릴 가능성이 줄어듭니다.

05활용법 1. "먼저 찾고, 나중에 고치게" 하기

초보자가 가장 많이 하는 실수는 Claude에게 바로 수정부터 맡기는 것입니다.

나쁜 예:

로그인 오류 고쳐줘.

좋은 예:

로그인 오류가 발생하고 있어.
먼저 로그인 관련 파일과 함수만 찾아줘.
아직 코드는 수정하지 말고,
오류 원인 후보를 근거와 함께 정리해줘.

이렇게 하면 Claude가 먼저 프로젝트를 읽고 이해합니다. 그다음 수정 계획을 요청합니다.

06수정 계획 요청과 승인

계획 요청:

좋아.
가장 가능성이 높은 원인 1개를 기준으로
어떤 파일을 어떻게 수정할지 계획만 작성해줘.
아직 수정하지 마.

최종 승인:

좋아. 방금 계획대로 수정해줘.
수정 범위는 관련 파일로만 제한해줘.
수정 후 변경사항을 요약해줘.

07활용법 2. Claude에게 역할을 지정하기

Claude Code에게 역할을 지정하면 답변 품질이 좋아집니다.

단순한 요청:

이 코드 봐줘.

역할 지정:

너는 시니어 백엔드 개발자처럼 이 코드를 리뷰해줘.
보안, 예외 처리, 유지보수성 관점에서 문제를 찾아줘.
아직 수정하지 말고 리뷰만 해줘.

상황별 역할 예시:

버그 수정

시니어 디버깅 엔지니어

코드 리뷰

시니어 코드 리뷰어

성능 개선

성능 최적화 전문가

보안 점검

보안 리뷰어

테스트 작성

테스트 엔지니어

문서 작성

기술 문서 편집자

리팩터링

아키텍처 리뷰어

08역할 지정 예시

너는 테스트 엔지니어처럼 행동해줘.
이 기능에 필요한 테스트 케이스를 먼저 목록으로 정리해줘.
아직 테스트 파일은 작성하지 마.

09활용법 3. 원하는 출력 형식을 정해주기

Claude에게 출력 형식을 지정하면 결과를 바로 쓰기 쉬워집니다.

나쁜 예:

프로젝트 설명해줘.

좋은 예:

이 프로젝트를 아래 형식으로 설명해줘.
1. 프로젝트 목적
2. 주요 폴더 구조
3. 핵심 파일 5개
4. 실행 명령어 후보
5. 테스트 명령어 후보
6. 처음 볼 사람이 읽어야 할 순서
아직 파일은 수정하지 마.

10출력 형식의 3가지 유형

코드 리뷰 — 표 형식:

git diff를 보고 코드 리뷰해줘.
아래 표 형식으로 정리해줘.
| 파일 | 문제 | 심각도 | 이유 | 수정 제안 |

버그 분석 — 원인 후보 형식:

오류 로그를 분석해줘.
아래 형식으로 답해줘.
1. 가장 가능성 높은 원인
2. 근거
3. 확인해야 할 파일
4. 실행해볼 명령어
5. 수정 전 주의사항

출력 형식을 정하면 Claude의 답변이 덜 산만해집니다.

11활용법 4. 큰 작업은 "작업 패키지"로 나누기

큰 작업을 한 번에 맡기면 실패 확률이 높아집니다.

나쁜 예:

결제 기능 추가해줘.

좋은 예:

결제 기능을 추가하려고 해.
먼저 작업을 5개 이하의 작은 작업 패키지로 나눠줘.
각 작업마다 수정 파일, 위험도, 테스트 방법을 함께 적어줘.
아직 수정하지 마.

12작업 패키지 분할 예시

Claude는 이런 식으로 나눌 수 있습니다:

현재 결제 관련 구조 탐색
결제 API 타입 정의
결제 요청 함수 추가
UI 버튼 연결
테스트 추가

그다음 하나씩 진행합니다:

1번 작업만 진행해줘.
관련 파일을 찾고 구조만 설명해줘.
아직 수정하지 마.

이 방식의 장점:

실패 범위가 작아짐

한 번에 한 부분만 수정

리뷰가 쉬움

변경사항이 작음

비용 관리가 쉬움

불필요한 탐색 감소

품질이 좋아짐

Claude가 목표를 잃지 않음

13활용법 5. Claude에게 "근거"를 요구하기

Claude가 답을 줄 때는 항상 근거를 요구하는 습관이 좋습니다.

나쁜 예:

어디를 고치면 돼?

좋은 예:

어디를 고쳐야 하는지 알려줘.
각 판단의 근거가 된 파일명, 함수명, 코드 흐름을 함께 설명해줘.

코드베이스 분석에서는 특히 중요합니다:

이 프로젝트의 인증 흐름을 설명해줘.
추측하지 말고, 실제로 확인한 파일과 함수 기준으로 설명해줘.
확실하지 않은 부분은 "확실하지 않음"이라고 표시해줘.

이렇게 하면 Claude가 모호한 부분을 단정하는 일을 줄일 수 있습니다.

14활용법 6. 세션을 목적별로 나누기

Claude Code는 세션 안에서 대화 맥락을 유지합니다. 하지만 너무 많은 작업을 한 세션에 넣으면 맥락이 섞입니다.

좋지 않은 세션:

프로젝트 구조 분석 ↓
로그인 버그 수정 ↓
결제 기능 추가 ↓
README 수정 ↓
성능 개선

좋은 세션:

세션 1: 프로젝트 구조 분석
세션 2: 로그인 버그 수정
세션 3: 결제 기능 추가
세션 4: README 문서 정리

작업별로 세션을 나누면 Claude의 집중도가 좋아집니다.

15세션 관리 명령어

세션 이어가기:

claude -c

세션 목록에서 고르기:

claude --resume

Claude Code 안에서:

/resume

새 작업으로 넘어갈 때는 기존 맥락을 정리하는 것도 좋습니다:

/clear

16활용법 7. Git을 Claude의 검토 도구로 쓰기

Claude Code를 잘 쓰려면 Git을 함께 써야 합니다.

작업 전:

git status

작업 후:

git diff

Claude Code 안에서는 이렇게 요청합니다:

git diff를 기준으로 변경사항을 리뷰해줘.
1. 변경된 파일
2. 변경된 이유
3. 의도치 않은 변경 가능성
4. 버그 가능성
5. 추가 테스트가 필요한 부분
순서로 정리해줘.

17커밋 메시지 작성 요청

커밋 메시지도 Claude에게 요청할 수 있습니다:

현재 git diff를 기준으로 커밋 메시지를 작성해줘.
형식은 Conventional Commits로 해줘.
본문에는 변경 이유를 짧게 포함해줘.

예상 출력:

fix(auth): handle missing access token

로그인 응답에 access token이 없는 경우를 처리하도록 수정했습니다.
인증 실패 시 명확한 에러 메시지를 반환합니다.

18활용법 8. 반복 작업은 템플릿으로 만들기

자주 쓰는 요청은 템플릿으로 저장해두면 좋습니다.

버그 수정 템플릿:

다음 버그를 분석해줘.
증상: [여기에 증상 입력]
조건:
- 먼저 관련 파일을 찾아줘.
- 아직 수정하지 마.
- 원인 후보를 가능성 높은 순서로 정리해줘.
- 각 원인마다 근거 파일과 확인 방법을 적어줘.
- 마지막에 수정 계획을 제안해줘.

19템플릿 2: 코드 리뷰 & 기능 추가

코드 리뷰 템플릿:

현재 변경사항을 코드 리뷰해줘.
기준:
1. 버그 가능성
2. 보안 문제
3. 예외 처리
4. 성능 문제
5. 유지보수성
출력 형식: | 파일 | 문제 | 심각도 | 이유 | 수정 제안 |
아직 파일은 수정하지 마.

기능 추가 템플릿:

다음 기능을 추가하려고 해.
기능 설명: [여기에 기능 입력]
먼저 아래 내용을 정리해줘.
1. 관련 파일
2. 현재 구조
3. 구현 계획
4. 수정 범위
5. 테스트 방법
6. 위험 요소
아직 수정하지 마.

20템플릿 3: 테스트 작성

테스트 작성 템플릿:

이 기능에 대한 테스트를 작성하려고 해.
먼저 테스트 케이스 목록만 작성해줘.
각 테스트 케이스마다 목적, 입력값, 기대 결과를 정리해줘.
아직 테스트 파일은 만들지 마.

21실전 사용 예시 ① · 탐색

상황: 로그인 버튼을 눌렀는데 에러가 납니다.

1단계. 탐색 요청:

로그인 버튼을 눌렀을 때 에러가 발생해.
먼저 로그인 흐름과 관련된 파일을 찾아줘.
아직 수정하지 말고,
관련 파일과 함수 역할만 정리해줘.

2단계. 원인 분석 요청:

좋아.
이제 로그인 실패 원인 후보를 가능성 높은 순서로 정리해줘.
각 원인마다 근거 파일, 확인 방법, 예상 수정 범위를 적어줘.

22실전 사용 예시 ② · 계획과 실행

3단계. 계획 요청:

가장 가능성 높은 원인 1개를 기준으로 수정 계획을 작성해줘.
수정할 파일, 수정 내용, 테스트 방법을 포함해줘.
아직 수정하지 마.

4단계. 실행 승인:

좋아.
방금 계획대로 수정해줘.
수정 범위를 최소화하고,
다른 파일은 건드리지 마.

23실전 사용 예시 ③ · 검토와 테스트

5단계. 변경사항 검토:

git diff 기준으로 변경사항을 리뷰해줘.
의도치 않은 변경, 버그 가능성, 추가 테스트 필요 여부를 정리해줘.

6단계. 테스트 요청:

이 변경사항을 확인하기 위해 어떤 테스트를 실행해야 하는지 알려줘.
명령어를 바로 실행하지 말고 후보만 보여줘.

7단계. 테스트 실행 승인:

좋아. 제안한 테스트 명령어를 실행해줘.
실패하면 원인만 분석하고, 아직 추가 수정은 하지 마.

24실전 흐름의 가치

이 흐름을 쓰면 Claude Code를 단순 자동 수정 도구가 아니라, 분석가 + 개발자 + 리뷰어 + 테스트 보조자처럼 활용할 수 있습니다.

바로 시키지 말고, 먼저 찾게 하고, 계획하게 하고, 검토하게 하라.

25초보자가 자주 하는 실수 ①

실수 1. "알아서 해줘"라고 말한다

나쁜 예:

알아서 좋은 구조로 바꿔줘.

좋은 예:

먼저 개선 후보를 3개만 제안해줘.
각 후보의 장점, 단점, 위험도를 설명해줘.
아직 수정하지 마.

실수 2. 한 번에 너무 큰 작업을 맡긴다

나쁜 예:

전체 프로젝트 리팩터링해줘.

좋은 예:

리팩터링 후보를 찾아줘.
우선순위가 높은 파일 3개만 고르고,
각각 왜 리팩터링이 필요한지 설명해줘.
아직 수정하지 마.

26초보자가 자주 하는 실수 ②

실수 3. 출력 형식을 지정하지 않는다

나쁜 예:

리뷰해줘.

좋은 예:

아래 표 형식으로 리뷰해줘.
| 파일 | 문제 | 심각도 | 수정 제안 |

실수 4. 수정 후 diff를 확인하지 않는다

수정 후에는 반드시 확인해야 합니다:

git status
git diff

Claude에게도 요청합니다:

git diff 기준으로 변경사항을 요약하고,
위험한 변경이 있는지 확인해줘.

27초보자가 자주 하는 실수 ③

실수 5. 민감 정보를 그대로 보여준다

아래 파일은 읽히거나 붙여넣지 않는 것이 좋습니다:

🔒.env

🔒.env.local

🔒credentials.json

🔒private-key.pem

🔒id_rsa

🔒service-account.json

좋은 요청:

.env 파일은 읽지 마.
필요한 환경 변수 이름만 추정해서 설명해줘.

28체크리스트

Claude Code를 제대로 쓰고 있는지 확인하세요.

바로 수정 요청하지 않고 먼저 탐색을 요청했다

□

"아직 수정하지 마"를 필요한 곳에 명시했다

□

작업을 작은 단위로 나눴다

□

Claude에게 역할을 지정했다

□

원하는 출력 형식을 정했다

□

판단 근거를 파일명과 함수명 기준으로 요청했다

□

수정 전 계획을 받았다

□

수정 후 git diff를 확인했다

□

테스트 명령어는 실행 전 후보를 먼저 받았다

□

민감 정보 파일을 읽히지 않았다

□

작업별로 세션을 나누었다

□

섹션 05 · 마무리

이 단원에서 기억할 것

Claude Code를 300% 활용하는 핵심은 이 한 줄입니다:

바로 시키지 말고, 먼저 찾게 하고, 계획하게 하고, 검토하게 하라.

가장 강력한 기본 프롬프트는 다음과 같습니다:

먼저 관련 파일을 찾아줘.
아직 수정하지 마.
원인을 설명하고,
수정 계획만 제안해줘.
내가 승인하면 그때 최소 범위로 수정해줘.
수정 후에는 git diff 기준으로 변경사항을 리뷰해줘.

이 흐름을 익히면 Claude Code를 단순한 자동완성 도구가 아니라 프로젝트 분석, 버그 수정, 리팩터링, 테스트, 코드 리뷰까지 도와주는 개발 파트너로 사용할 수 있습니다.

다음 단원

6단원. 파일을 읽고 코드베이스를 이해시키는 법

6. 파일을 읽고 코드베이스를 이해시키는 법

01핵심 개념

Claude Code를 잘 쓰려면 파일을 많이 읽히는 것보다 필요한 파일을 정확히 읽히는 것이 중요합니다.

초보자는 보통 이렇게 요청합니다.

프로젝트 전체를 분석해줘.

하지만 좋은 요청은 이렇게 시작합니다.

이 기능과 관련된 파일만 먼저 찾아줘.
아직 수정하지 말고,
어떤 파일을 읽었는지와 그 이유를 함께 설명해줘.

이 단원의 목표는 Claude에게 코드베이스를 이렇게 이해시키는 것입니다.

무작정 전체 읽기

필요한 파일 찾기

추측으로 설명

읽은 파일 근거로 설명

바로 수정

구조 이해 후 계획

02왜 필요한가

코드베이스가 조금만 커져도 Claude에게 모든 파일을 한 번에 읽게 하는 방식은 비효율적입니다.

나쁜 방식

"전체 프로젝트 분석해줘"

너무 넓고 오래 걸림

"모든 파일 읽어줘"

컨텍스트 낭비가 큼

"어디 고쳐야 해?"

Claude가 추측할 가능성 증가

"알아서 찾아서 수정해줘"

원하지 않는 파일을 건드릴 수 있음

좋은 방식

03Claude가 파일을 이해하는 기본 방식

초보자는 내부 도구 이름을 모두 외울 필요는 없습니다. 다만 아래 개념은 알아두면 좋습니다.

파일 읽기

특정 파일 내용을 확인 (예: package.json, README.md 읽기)

파일 검색

이름이나 패턴으로 파일 찾기 (예: auth, login, user 관련 파일 찾기)

코드 검색

함수명, 변수명, 문자열 찾기 (예: loginUser, JWT, TODO 검색)

폴더 구조 파악

프로젝트 전체 구조 확인 (처음 보는 프로젝트 분석)

지침 파일 활용

프로젝트 규칙 기억 (CLAUDE.md 작성)

처음에는 이렇게 요청하면 됩니다.

먼저 프로젝트 구조를 가볍게 파악해줘.
읽은 파일과 읽은 이유를 함께 설명해줘.
아직 파일은 수정하지 마.

04첫 번째 탐색 요청하기

처음 보는 프로젝트에서는 바로 기능이나 버그를 묻기보다, 프로젝트 지도를 만들어야 합니다.

이 프로젝트를 처음 보는 개발자라고 생각하고 구조를 설명해줘.

다음 순서로 정리해줘.

1. 프로젝트의 목적
2. 주요 폴더 구조
3. 핵심 설정 파일
4. 실행 진입점으로 보이는 파일
5. 테스트 관련 파일
6. 먼저 읽어야 할 파일 5개

아직 파일은 수정하지 마.
명령어도 실행하지 마.

이 요청의 장점

"처음 보는 개발자"

설명 수준이 쉬워짐

"순서로 정리"

답변이 구조화됨

"핵심 파일 5개"

범위가 줄어듦

"수정하지 마"

안전한 탐색이 됨

"명령어도 실행하지 마"

첫 세션에서 불필요한 실행 방지

05파일을 직접 지정해서 읽히기

이미 읽고 싶은 파일을 알고 있다면 직접 지정하는 것이 가장 좋습니다.

README.md와 package.json을 읽고,
이 프로젝트의 실행 방법과 주요 의존성을 설명해줘.
아직 파일은 수정하지 마.

특정 파일 여러 개를 지정할 수도 있습니다.

다음 파일들을 읽고 역할을 비교해줘.

- src/app.ts
- src/server.ts
- src/routes/auth.ts

각 파일이 어떤 책임을 갖는지 표로 정리해줘.
아직 수정하지 마.

출력 형식을 함께 지정하면 더 좋습니다.

아래 표 형식으로 정리해줘.

| 파일 | 역할 | 중요한 함수 | 다른 파일과의 관계 | 주의할 점 |

06관련 파일을 찾아달라고 하기

파일명을 모를 때는 Claude에게 먼저 찾게 해야 합니다.

예시: 로그인 기능 찾기

로그인 기능이 어디에서 처리되는지 찾아줘.

조건:
- 관련 파일 후보를 먼저 찾아줘.
- 파일을 수정하지 마.
- 각 파일이 로그인 흐름에서 어떤 역할을 하는지 설명해줘.
- 추측한 부분과 실제 파일에서 확인한 부분을 구분해줘.

예시: 결제 기능 찾기

결제 관련 코드가 어디에 있는지 찾아줘.

다음 키워드를 기준으로 검색해줘.
- payment
- billing
- checkout
- invoice
- subscription

관련 파일을 찾은 뒤,
파일별 역할과 전체 결제 흐름을 설명해줘.
아직 수정하지 마.

예시: 에러 메시지 찾기

다음 에러 메시지가 어디에서 발생하는지 찾아줘.

"Invalid access token"

관련 파일, 함수, 호출 흐름을 정리해줘.
아직 수정하지 마.

이런 방식은 Claude가 무작정 전체 파일을 읽는 대신, 키워드 기반으로 관련 부분부터 좁혀가게 만듭니다.

07"읽은 근거"를 요구하기

Claude에게 코드베이스를 설명시킬 때는 항상 근거를 요구하세요.

나쁜 요청

인증 구조 설명해줘.

좋은 요청

인증 구조를 설명해줘.
단, 실제로 확인한 파일명과 함수명을 근거로 설명해줘.
확실하지 않은 부분은 추측하지 말고 "확인 필요"라고 표시해줘.

더 좋은 요청

인증 구조를 아래 형식으로 정리해줘.

1. 전체 흐름
2. 관련 파일
3. 주요 함수
4. 데이터 흐름
5. 실제 파일에서 확인한 근거
6. 아직 확인이 필요한 부분

아직 파일은 수정하지 마.

이렇게 하면 Claude의 답변이 더 검증 가능해집니다.

08코드베이스 지도 만들기

중간 규모 이상의 프로젝트라면 먼저 "코드베이스 지도"를 만들어두면 좋습니다.

이 프로젝트의 코드베이스 지도를 만들어줘.

아래 형식으로 정리해줘.

1. 앱 진입점
2. 라우팅 구조
3. 상태 관리 방식
4. API 통신 구조
5. 인증 구조
6. DB 또는 저장소 접근 구조
7. 테스트 구조
8. 빌드와 배포 관련 파일
9. 초보자가 먼저 읽을 파일 순서

아직 파일은 수정하지 마.
명령어도 실행하지 마.

출력 예시는 이런 형태가 좋습니다.

앱 진입점

src/main.ts — 앱 시작점 (높음)

라우팅

src/routes/* — URL별 요청 처리 (높음)

인증

src/auth/* — 로그인, 토큰 처리 (높음)

테스트

tests/* — 테스트 코드 (중간)

설정

package.json, .env.example — 실행 환경 (높음)

이런 지도를 만들어두면 이후 작업이 훨씬 빨라집니다.

09파일을 읽는 순서 정하기

코드베이스를 볼 때는 순서가 중요합니다. 무작정 src 전체를 읽기보다, 보통 아래 순서가 좋습니다.

README.md
↓
package.json / pyproject.toml / go.mod 등
↓
환경 예시 파일
↓
앱 진입점
↓
라우팅 또는 main module
↓
핵심 도메인 코드
↓
테스트 코드

Claude에게 이렇게 요청할 수 있습니다.

이 프로젝트를 이해하기 위한 파일 읽기 순서를 추천해줘.

조건:
- 최대 10개 파일만 골라줘.
- 각 파일을 왜 먼저 읽어야 하는지 설명해줘.
- 실제로 존재하는 파일만 기준으로 해줘.
- 아직 파일은 수정하지 마.

이 요청은 초보자에게 특히 유용합니다. 어떤 파일부터 봐야 할지 모르기 때문입니다.

10CLAUDE.md로 프로젝트 설명을 저장하기

매번 같은 설명을 반복하고 싶지 않다면 프로젝트 루트에 CLAUDE.md를 만들 수 있습니다.

CLAUDE.md는 프로젝트 루트에 추가하는 Markdown 파일이며, Claude Code는 세션 시작 시 이를 읽어 코딩 표준, 아키텍처 결정, 선호 라이브러리, 리뷰 체크리스트 같은 지침으로 활용합니다.

초보자용 CLAUDE.md 예시:

# Project Guide

## 프로젝트 개요
이 프로젝트는 사용자 로그인, 회원가입, 결제 기능을 제공하는 웹 애플리케이션이다.

## 주요 명령어
- 개발 서버 실행: npm run dev
- 테스트 실행: npm test
- 린트 실행: npm run lint

## 주요 폴더
- src/routes: 라우팅
- src/components: UI 컴포넌트
- src/lib: 공통 유틸리티
- tests: 테스트 코드

## 작업 규칙
- 파일을 수정하기 전에 먼저 수정 계획을 설명한다.
- .env 파일은 읽지 않는다.
- 큰 리팩터링은 작은 단계로 나눈다.
- 수정 후 git diff 기준으로 변경사항을 요약한다.

작성 후 Claude에게 이렇게 말할 수 있습니다.

CLAUDE.md를 참고해서 이 프로젝트의 구조를 설명해줘.
부족한 내용이 있으면 보완 제안만 해줘.
아직 수정하지 마.

단, CLAUDE.md는 강제 보안 장치가 아닙니다. 특정 작업을 반드시 차단하려면 권한 설정이나 hook 같은 별도 장치를 사용해야 합니다.

11민감 파일은 읽지 않게 하기

Claude Code가 파일을 읽을 수 있다는 것은 편리하지만, 민감 정보에는 주의해야 합니다.

읽히면 안 되는 파일 예시

.env
.env.local
.env.production
credentials.json
service-account.json
private-key.pem
id_rsa
*.key
*.pem

Claude에게 항상 이렇게 말하는 습관이 좋습니다.

.env, credentials, private key 파일은 읽지 마.
필요하면 환경 변수 이름만 추정해서 설명해줘.

더 확실히 막으려면 설정에서 읽기 권한을 거부할 수 있습니다. .claude/settings.json의 permissions.deny에 규칙을 넣어 민감 파일 접근을 막을 수 있습니다.

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)"
    ]
  }
}

초보자는 처음부터 복잡한 권한 설정을 모두 할 필요는 없습니다. 다만 민감 파일은 절대 Claude에게 붙여넣지 않는 습관이 필요합니다.

12특정 줄이나 파일을 정확히 가리키기

IDE를 함께 쓰면 특정 파일이나 코드 범위를 Claude에게 더 정확히 알려줄 수 있습니다.

VS Code에서 선택한 코드가 있을 때 Claude가 하이라이트된 코드를 볼 수 있습니다. Mac은 Option+K, Windows/Linux는 Alt+K로 파일 경로와 줄 번호가 포함된 mention을 삽입할 수 있습니다.

예시

@app.ts#20-45 부분을 설명해줘.
이 함수가 어떤 입력을 받고 어떤 출력을 반환하는지 정리해줘.
아직 수정하지 마.

IDE를 쓰지 않는다면 파일명과 함수명을 직접 적어도 됩니다.

src/auth/login.ts 파일의 loginUser 함수를 설명해줘.
이 함수가 호출하는 다른 함수도 함께 정리해줘.

13큰 파일을 읽힐 때의 요령

큰 파일은 한 번에 전부 분석시키기보다 목적을 정해야 합니다.

나쁜 예

이 파일 전체 설명해줘.

좋은 예

이 파일에서 인증 처리와 관련된 부분만 설명해줘.
다음 기준으로 정리해줘.

1. 관련 함수
2. 입력값
3. 반환값
4. 외부 의존성
5. 주의할 예외 상황

또는 이렇게 요청할 수 있습니다.

이 파일을 전체 요약하지 말고,
먼저 구조만 훑어서 섹션별 역할을 알려줘.
그다음 내가 선택한 섹션만 자세히 설명해줘.

큰 파일은 단계적으로 접근해야 컨텍스트 낭비가 줄어듭니다.

14코드 흐름을 따라가게 하기

특정 기능을 이해하려면 "파일 설명"보다 "흐름 설명"이 더 중요합니다.

예시: 로그인 흐름

로그인 요청이 들어온 뒤부터 응답이 반환될 때까지의 흐름을 추적해줘.

아래 형식으로 정리해줘.

1. 시작 지점
2. 호출되는 함수 순서
3. 각 함수가 하는 일
4. DB 또는 외부 API 호출 여부
5. 에러가 발생할 수 있는 지점
6. 실제 확인한 파일과 함수

아직 수정하지 마.

예시: API 요청 흐름

사용자 정보 조회 API의 흐름을 추적해줘.
라우트, 컨트롤러, 서비스, 저장소 계층이 있다면 순서대로 설명해줘.
실제 파일명과 함수명을 근거로 정리해줘.

예시: 프론트엔드 버튼 클릭 흐름

로그인 버튼을 클릭했을 때 어떤 코드가 실행되는지 추적해줘.
컴포넌트, 상태 변경, API 호출, 에러 처리 순서로 설명해줘.
아직 수정하지 마.

15테스트 파일로 기능 이해하기

테스트 파일은 기능을 이해하는 데 매우 좋은 자료입니다.

이 기능과 관련된 테스트 파일을 찾아줘.
테스트가 설명하는 동작을 기준으로 기능 요구사항을 정리해줘.
아직 테스트를 수정하지 마.

테스트를 읽으면 다음을 알 수 있습니다.

기대 동작

기능이 어떤 결과를 내야 하는지

예외 상황

실패나 에러를 어떻게 처리하는지

입력값

어떤 데이터가 들어오는지

경계 조건

빈 값, 잘못된 값, 권한 없음 등

누락된 테스트

아직 검증하지 않은 부분

테스트 기반으로 기능을 이해시키는 요청:

결제 기능의 테스트 파일을 읽고,
현재 결제 기능의 요구사항을 역으로 정리해줘.

아래 형식으로 작성해줘.

| 테스트 이름 | 검증하는 동작 | 입력 | 기대 결과 | 누락 가능성 |

16문서와 코드가 다를 때 확인하기

README나 문서가 실제 코드와 다를 수 있습니다. 이럴 때는 Claude에게 문서와 코드를 비교하게 하세요.

README.md의 실행 방법과 실제 package.json의 scripts를 비교해줘.
서로 다른 부분이 있으면 표로 정리해줘.
아직 파일은 수정하지 마.

또는:

문서에 적힌 API 경로와 실제 라우트 파일의 경로가 일치하는지 확인해줘.
불일치가 있으면 근거 파일과 함께 정리해줘.
아직 수정하지 마.

문서와 코드가 다르면 바로 수정하기보다 먼저 차이를 정리하는 것이 좋습니다.

17코드베이스 이해용 프롬프트 모음

프로젝트 전체 구조 파악

이 프로젝트의 전체 구조를 설명해줘.

조건:
- 중요한 폴더와 파일만 다뤄줘.
- 실제로 확인한 파일을 근거로 설명해줘.
- 아직 파일은 수정하지 마.
- 마지막에 초보자가 읽을 파일 순서를 추천해줘.

특정 기능 찾기

[기능 이름] 기능이 어디에서 구현되어 있는지 찾아줘.

조건:
- 관련 파일 후보를 먼저 정리해줘.
- 각 파일의 역할을 설명해줘.
- 실제 확인한 함수명을 포함해줘.
- 아직 수정하지 마.

에러 발생 위치 찾기

다음 에러가 어디에서 발생하는지 찾아줘.

에러 메시지:
[에러 메시지 입력]

조건:
- 에러 문자열을 검색해줘.
- 직접 발생 위치와 호출 흐름을 구분해줘.
- 수정하지 말고 원인 후보만 정리해줘.

18코드베이스 이해용 프롬프트 모음 (계속)

코드 흐름 추적

[기능 이름]이 실행되는 흐름을 추적해줘.

아래 형식으로 정리해줘.

1. 시작 지점
2. 호출 순서
3. 주요 함수
4. 데이터 흐름
5. 에러 처리
6. 확인한 파일과 함수

파일 읽기 순서 추천

이 프로젝트를 이해하기 위한 파일 읽기 순서를 추천해줘.
최대 10개 파일만 골라줘.
각 파일을 왜 읽어야 하는지 설명해줘.
아직 수정하지 마.

문서와 코드 비교

README.md의 설명과 실제 코드가 일치하는지 확인해줘.
불일치가 있으면 근거 파일과 함께 표로 정리해줘.
아직 수정하지 마.

19실전 예시: 로그인 기능 이해시키기

상황: 로그인 기능을 수정해야 하지만, 어디에 있는지 모릅니다.

1단계. 관련 파일 찾기

로그인 기능이 어디에서 구현되어 있는지 찾아줘.

검색 키워드:
- login
- auth
- token
- session
- password

관련 파일을 찾고,
각 파일이 로그인 흐름에서 어떤 역할을 하는지 설명해줘.
아직 수정하지 마.

2단계. 흐름 추적하기

로그인 요청이 들어온 뒤 응답이 반환될 때까지 흐름을 추적해줘.

다음 형식으로 정리해줘.

1. 요청 시작 지점
2. 호출되는 함수 순서
3. 토큰 생성 또는 세션 처리 위치
4. 에러 처리 위치
5. 실제 확인한 파일과 함수

3단계. 위험 지점 찾기

로그인 흐름에서 버그가 생기기 쉬운 지점을 찾아줘.

기준:
- 입력 검증
- 비밀번호 검증
- 토큰 생성
- 세션 저장
- 에러 메시지
- 예외 처리

아직 수정하지 말고,
문제 후보와 근거만 정리해줘.

4단계. 수정 계획 받기

가장 우선순위가 높은 문제 1개를 골라서 수정 계획을 작성해줘.

포함할 내용:
1. 수정할 파일
2. 수정 이유
3. 수정 방식
4. 테스트 방법
5. 위험 요소

아직 파일은 수정하지 마.

이 흐름을 따르면 Claude가 코드베이스를 충분히 이해한 뒤 수정할 수 있습니다.

20초보자가 자주 하는 실수

실수 1. 전체 프로젝트를 한 번에 읽히려고 한다

나쁜 예:

모든 파일을 읽고 설명해줘.

좋은 예:

먼저 프로젝트 구조를 파악하고,
핵심 파일 10개만 골라서 읽을 순서를 추천해줘.
아직 수정하지 마.

실수 2. 근거 없이 설명만 받는다

나쁜 예:

인증 구조 설명해줘.

좋은 예:

인증 구조를 설명해줘.
실제 확인한 파일명과 함수명을 근거로 포함해줘.
확실하지 않은 부분은 확인 필요라고 표시해줘.

실수 3. 검색 키워드를 주지 않는다

나쁜 예:

결제 기능 찾아줘.

좋은 예:

결제 기능을 찾아줘.
payment, billing, checkout, invoice, subscription 키워드로 관련 파일을 찾아줘.

21초보자가 자주 하는 실수 (계속)

실수 4. 민감 파일을 읽히게 한다

나쁜 예:

.env 파일을 읽고 설정을 설명해줘.

좋은 예:

.env 파일은 읽지 마.
대신 .env.example이나 README를 기준으로 필요한 환경 변수 이름만 설명해줘.

실수 5. 읽기와 수정을 섞는다

나쁜 예:

로그인 구조 설명하고 문제 있으면 고쳐줘.

좋은 예:

로그인 구조만 먼저 설명해줘.
문제가 있어 보이면 수정하지 말고 후보만 정리해줘.

22체크리스트

Claude Code를 처음 사용할 때 아래 항목을 확인하세요.

프로젝트 전체를 무작정 읽히지 않았다

□

관련 파일 후보를 먼저 찾게 했다

□

검색 키워드를 구체적으로 제공했다

□

"아직 수정하지 마"라고 명시했다

□

읽은 파일과 근거를 함께 설명하게 했다

□

실제 확인한 부분과 추측한 부분을 구분하게 했다

□

민감 파일을 읽지 않도록 요청했다

□

큰 파일은 목적을 정해서 읽혔다

□

코드 흐름을 파일 단위가 아니라 실행 순서로 추적하게 했다

□

필요한 경우 CLAUDE.md에 프로젝트 규칙을 정리했다

□

섹션 06 · 마무리

이 단원에서 기억할 것

Claude Code에게 코드베이스를 이해시키는 핵심은 이것입니다.

전체를 읽히지 말고, 필요한 파일을 찾게 하고, 읽은 근거를 기준으로 설명하게 하라.

가장 자주 쓸 기본 프롬프트는 다음과 같습니다.

이 기능과 관련된 파일을 먼저 찾아줘.
아직 수정하지 마.
각 파일의 역할과 실제 확인한 근거를 설명해줘.
확실하지 않은 부분은 "확인 필요"라고 표시해줘.
그다음 수정이 필요하다면 계획만 제안해줘.

이 습관을 들이면 Claude Code가 프로젝트를 더 정확하게 이해하고, 불필요한 파일 읽기와 위험한 수정을 줄일 수 있습니다.

다음 단원

7단원. Plan Mode로 수정 전에 계획부터 세우기

7. Plan Mode로 수정 전에 계획부터 세우기

01핵심 개념

Plan Mode는 Claude Code에게 바로 수정하지 말고 먼저 조사하고 계획을 세우게 하는 모드입니다.

일반 모드와 Plan Mode의 흐름 차이:

일반 모드

요청 → Claude가 파일 읽기 → 수정 제안 또는 수정 실행

Plan Mode

요청 → Claude가 조사 → 계획 작성 → 사용자가 검토 → 승인 후 수정

Plan Mode에서 Claude는 변경을 제안하기 전에 조사하고 계획을 작성하며, 파일 편집은 승인 전까지 하지 않습니다. 탐색을 위한 파일 읽기나 셸 명령은 권한 프롬프트를 거쳐 실행될 수 있습니다.

02왜 필요한가

Claude Code는 파일을 수정하고 명령을 실행할 수 있습니다. 그래서 큰 작업을 바로 맡기면 위험합니다.

나쁜 요청:

인증 구조를 전부 리팩터링해줘.

좋은 요청:

Plan Mode로 인증 구조 리팩터링 계획을 먼저 세워줘.
관련 파일을 조사하고,
수정할 파일, 수정 이유, 위험 요소, 테스트 방법을 정리해줘.
아직 수정하지 마.

02왜 필요한가 (계속)

Plan Mode가 필요한 상황들:

여러 파일을 수정해야 함

변경 범위를 먼저 확인해야 함

처음 보는 코드베이스

구조 파악 없이 수정하면 위험함

리팩터링

의도치 않은 동작 변경 가능성이 큼

인증, 결제, 권한 기능

실수 비용이 큼

테스트 실패 원인이 복잡함

바로 수정하면 원인과 증상이 섞임

팀 프로젝트

계획을 먼저 공유하고 리뷰할 수 있음

03Plan Mode 켜는 방법 ① 세션 중 Shift+Tab

Claude Code 실행 중에 Shift+Tab을 눌러 모드를 바꿀 수 있습니다.

모드의 기본 순환:

default → acceptEdits → plan

세 가지 모드가 순환합니다:

default — 기본 모드. Claude가 자유롭게 파일을 수정할 수 있음
acceptEdits — Claude가 제안만 하고, 사용자가 수동으로 승인
plan — 계획 모드. 조사와 계획만 수행

03Plan Mode 켜는 방법 ② /plan 붙이기

한 번의 요청에만 Plan Mode를 사용할 수도 있습니다.

Claude Code 안에서 특정 요청 앞에 /plan을 붙입니다:

/plan 로그인 기능 리팩터링 계획을 세워줘.
관련 파일을 조사하고 수정 계획만 작성해줘.

이 방법은 대부분의 작업은 일반 모드로 하고, 필요한 순간에만 계획 모드를 사용할 때 유용합니다.

03Plan Mode 켜는 방법 ③ 시작할 때 Plan Mode로

터미널에서 처음부터 Plan Mode로 시작할 수도 있습니다.

claude --permission-mode plan

또는:

claude -p plan

이렇게 실행하면 Claude Code 세션이 처음부터 Plan Mode로 시작되어, 모든 요청이 Plan Mode로 처리됩니다.

04Plan Mode에서 Claude가 하는 일

Plan Mode의 기본 흐름은 다음과 같습니다:

관련 파일을 찾는다.
필요한 내용을 읽는다.
현재 구조를 이해한다.
변경 목표를 정리한다.
수정할 파일과 이유를 제안한다.
위험 요소와 테스트 방법을 정리한다.
사용자의 승인을 기다린다.

04Plan Mode에서 확인할 항목

초보자는 Plan Mode에서 Claude에게 아래 내용을 반드시 포함하게 하세요:

수정할 파일
수정하지 않을 파일
변경 이유
예상 영향
위험 요소
테스트 방법
롤백 방법

좋은 Plan Mode 요청 예시:

/plan 회원가입 입력 검증을 추가하려고 해.
1. 관련 파일 / 2. 현재 동작 / 3. 수정할 파일
4. 수정 내용 / 5. 수정하지 않을 파일
6. 위험 요소 / 7. 테스트 방법
아직 파일은 수정하지 마.

05계획의 품질 확인하기

Claude가 계획을 작성하면 바로 승인하지 마세요. 아래 기준으로 검토해야 합니다.

범위

좋은 계획: 수정 파일이 명확함 | 나쁜 계획: "여러 파일 수정"처럼 모호함

이유

좋은 계획: 왜 수정하는지 설명함 | 나쁜 계획: 그냥 바꾸겠다고 함

위험

좋은 계획: 부작용 가능성을 적음 | 나쁜 계획: 위험 요소가 없음

테스트

좋은 계획: 확인 명령이 있음 | 나쁜 계획: 테스트 계획이 없음

되돌리기

좋은 계획: Git diff로 확인 가능 | 나쁜 계획: 되돌릴 방법이 불명확

제한

좋은 계획: 건드리지 않을 파일을 명시함 | 나쁜 계획: 전체 프로젝트를 만지려 함

05계획이 부족할 때

계획이 부족하면 이렇게 요청하세요:

계획이 아직 너무 넓어.
수정 범위를 더 줄여줘.
1. 반드시 수정해야 하는 파일
2. 수정하지 않을 파일
3. 가장 작은 변경 단위
4. 실패했을 때 되돌리는 방법

06승인 후 선택지 이해하기

Plan Mode에서 계획이 준비되면 Claude Code는 어떻게 진행할지 묻습니다. 가능한 선택지:

계획을 계속 수정하기
각 편집을 수동으로 검토하기
편집을 자동으로 승인하기
Auto Mode로 진행하기

또한 Ctrl+G로 제안된 계획을 텍스트 편집기에서 직접 수정할 수 있습니다.

초보자에게 추천하는 선택: Approve and review each edit manually (각 편집 수동 검토)

06승인 방식별 추천도

계획 계속 수정

추천도: 높음 | 계획이 불명확할 때 안전

각 편집 수동 검토

추천도: 높음 | 변경을 하나씩 확인 가능

편집 자동 승인

추천도: 중간 | 익숙한 프로젝트에서만 권장

Auto Mode로 진행

추천도: 낮음 | 초보자에게는 통제가 어려울 수 있음

07실전 예시: 버그 수정 ① 원인 조사

상황: 로그인 시 Invalid access token 에러가 납니다.

1단계. Plan Mode로 원인 조사 요청:

/plan 로그인 시 "Invalid access token" 에러가 발생해.
1. 에러 메시지가 발생하는 위치
2. 관련 파일과 함수
3. 가능한 원인 후보
4. 가장 가능성 높은 원인
5. 수정할 파일 / 6. 수정 방식
7. 테스트 방법 / 8. 위험 요소
아직 파일은 수정하지 마.

07실전 예시: 버그 수정 ② 계획 좁히기

2단계. 계획을 더 좁히기:

좋아.
수정 범위를 더 작게 줄여줘.
가장 가능성 높은 원인 1개만 기준으로
최소 수정 계획을 다시 작성해줘.

3단계. 승인하기:

좋아.
방금 계획대로 진행해줘.
수정할 파일은 계획에 나온 파일로만 제한해줘.
각 편집은 내가 확인할 수 있게 해줘.

07실전 예시: 버그 수정 ③ 변경사항 검토

4단계. 변경사항 검토:

git diff 기준으로 변경사항을 리뷰해줘.
1. 변경된 파일
2. 변경 이유
3. 버그 가능성
4. 의도치 않은 변경 가능성
5. 실행해야 할 테스트

08실전 예시: 기능 추가 ① 계획 작성

상황: 회원가입 폼에 비밀번호 확인 필드를 추가하고 싶습니다.

/plan 회원가입 폼에 비밀번호 확인 필드를 추가하려고 해.
1. 현재 회원가입 UI 구조
2. 현재 validation 구조
3. 수정할 컴포넌트
4. 수정할 validation 로직
5. 추가하거나 수정할 테스트
6. 사용자에게 보여줄 에러 메시지
7. 위험 요소 / 8. 수정 범위
아직 파일은 수정하지 마.

08실전 예시: 기능 추가 ② 계획 검토 및 단계별 진행

계획이 나온 뒤 더 초보자 친화적으로 요청합니다:

계획을 더 초보자 친화적으로 설명해줘.
각 수정 파일마다 왜 필요한지,
수정하지 않아도 되는 대안은 없는지도 함께 알려줘.

그 다음 단계별로 나누어 진행합니다:

좋아.
1단계인 UI 수정만 먼저 진행해줘.
validation과 테스트는 아직 수정하지 마.
수정 후 git diff 기준으로 요약해줘.

큰 기능은 한 번에 승인하지 말고, 계획을 단계별로 나누어 실행하세요.

09실전 예시: 리팩터링 ① 나쁜 요청

리팩터링은 Plan Mode가 가장 필요한 작업입니다.

나쁜 요청:

이 코드 구조 깔끔하게 리팩터링해줘.

좋은 요청:

/plan auth 모듈을 리팩터링하려고 해.
목표:
- 동작은 바꾸지 않는다.
- 중복 코드를 줄인다.
- 함수 이름을 더 명확하게 한다.
- 테스트가 깨지지 않게 한다.

09실전 예시: 리팩터링 ② 계획 수립

계획에는 아래 내용을 포함하게 하세요:

1. 현재 auth 모듈 구조
2. 중복 또는 복잡한 부분
3. 리팩터링 후보
4. 우선순위
5. 가장 작은 1차 작업
6. 수정할 파일
7. 수정하지 않을 파일
8. 테스트 방법
아직 파일은 수정하지 마.

리팩터링 계획은 반드시 작게 나누세요:

전체 리팩터링을 한 번에 하지 말고,
가장 안전한 1단계만 골라줘.
동작 변경이 없는 작업만 선택해줘.

10Plan Mode와 일반 대화의 차이

목적

일반 대화: 바로 답변 또는 작업 | Plan Mode: 먼저 조사하고 계획

수정 가능성

일반 대화: 요청에 따라 바로 수정 가능 | Plan Mode: 승인 전 소스 편집 없음

적합한 작업

일반 대화: 작은 질문, 간단한 설명 | Plan Mode: 큰 수정, 리팩터링, 기능 추가

초보자 안전성

일반 대화: 요청 방식에 따라 다름 | Plan Mode: 더 안전함

검토 흐름

일반 대화: 사용자가 직접 통제해야 함 | Plan Mode: 계획 검토 흐름이 자연스러움

Plan Mode는 "Claude를 느리게 쓰는 기능"이 아닙니다. 오히려 큰 작업에서는 실패를 줄여서 전체 시간을 줄이는 기능입니다.

11Plan Mode에서도 주의할 점

Plan Mode라고 해서 모든 위험이 사라지는 것은 아닙니다. Plan Mode에서도 권한 프롬프트는 기본 모드와 동일하게 적용되며, 탐색 과정에서 파일 읽기나 셸 명령 실행이 사용될 수 있습니다.

초보자는 아래를 지키세요:

민감 파일은 읽지 말라고 말한다.
명령어 실행 전 후보만 먼저 달라고 한다.
계획이 넓으면 더 좁히라고 한다.
승인 후에도 git diff를 확인한다.
테스트 명령어는 실행 전 확인한다.

11민감 정보 및 명령어 제한

민감 정보 관련 요청 예시:

Plan Mode로 조사하되,
.env, credentials, private key 파일은 읽지 마.
필요하면 환경 변수 이름만 추정해서 설명해줘.

명령어 실행 제한 예시:

탐색 과정에서 명령어가 필요하면 바로 실행하지 말고,
먼저 실행할 명령어 후보와 이유를 알려줘.

12계획을 더 좋게 만드는 질문

계획이 너무 넓을 때:

계획이 너무 넓어.
가장 작은 안전한 변경 단위로 다시 나눠줘.
첫 번째 단계만 실행 가능한 수준으로 작성해줘.

위험 요소가 부족할 때:

위험 요소가 부족해.
이 변경으로 깨질 수 있는 기능,
영향받는 테스트,
되돌리는 방법을 추가해줘.

12테스트 및 근거 보강

테스트 계획이 부족할 때:

테스트 계획을 더 구체화해줘.
실행할 명령어 후보,
수동 확인 방법,
추가해야 할 테스트 케이스를 나눠서 적어줘.

근거가 부족할 때:

각 수정 제안의 근거가 된 파일명과 함수명을 표시해줘.
추측한 부분은 "확인 필요"라고 구분해줘.

13추천 프롬프트 ① 버그 수정 및 기능 추가

버그 수정용:

/plan 다음 버그를 수정하려고 해.
증상: [여기에 증상 입력]
조건:
- 먼저 관련 파일을 조사해줘.
- 아직 파일은 수정하지 마.
- 원인 후보를 가능성 높은 순서로 정리해줘.
- 가장 작은 수정 계획을 제안해줘.
- 수정할 파일과 수정하지 않을 파일을 구분해줘.

13추천 프롬프트 ② 기능 추가 및 리팩터링

기능 추가용:

/plan 다음 기능을 추가하려고 해.
기능: [여기에 기능 설명]
계획에 포함할 내용:
1. 관련 파일 / 2. 현재 구조 / 3. 수정할 파일
4. 새로 만들 파일 / 5. 테스트 방법
6. 위험 요소 / 7. 단계별 실행 순서
아직 수정하지 마.

13추천 프롬프트 ③ 리팩터링 및 코드 리뷰

리팩터링용:

/plan 다음 영역을 리팩터링하려고 해.
대상: [대상 모듈 또는 파일]
원칙:
- 동작은 바꾸지 않는다.
- 변경 범위는 작게 유지한다.
- 테스트가 깨지지 않아야 한다.
- 먼저 1단계 계획만 작성한다.
아직 수정하지 마.

14Plan Mode와 Git을 함께 쓰기

Plan Mode를 쓰기 전후에는 Git 상태를 확인하는 것이 좋습니다.

작업 전:

git status

작업 후:

git diff

Claude Code 안에서 계획과 실제를 비교할 때:

Plan Mode에서 제안한 계획과 실제 git diff를 비교해줘.
1. 계획대로 수정된 부분
2. 계획과 달라진 부분
3. 추가로 변경된 파일
4. 위험한 변경 가능성
5. 되돌려야 할 부분

이 질문은 매우 중요합니다. 계획과 실제 수정이 다를 수 있기 때문입니다.

15Plan Mode를 기본값으로 설정하기

Plan Mode를 자주 쓴다면 프로젝트 기본 모드로 설정할 수 있습니다.

.claude/settings.json 예시:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

16초보자가 자주 하는 실수 ① ②

실수 1. 계획을 보자마자 바로 승인한다

계획은 반드시 검토해야 합니다:

이 계획에서 수정 범위가 너무 넓은 부분이 있는지 확인해줘.
가장 위험한 변경부터 지적해줘.

실수 2. Plan Mode에서 너무 큰 목표를 준다

나쁜 예: /plan 전체 프로젝트 구조를 개선해줘.

좋은 예:

/plan auth 모듈의 중복 코드를 줄이는 1단계 계획만 세워줘.
동작 변경은 하지 않는 방향으로 작성해줘.

16초보자가 자주 하는 실수 ③ ④ ⑤

실수 3. 테스트 계획 없이 승인한다

이 계획을 검증하기 위한 테스트 방법을 추가해줘.
자동 테스트와 수동 확인 방법을 나눠서 적어줘.

실수 4. 민감 파일을 제한하지 않는다

.env, credentials, private key 파일은 읽지 마.
필요하면 필요한 환경 변수 이름만 설명해줘.

실수 5. 승인 후 diff를 확인하지 않는다

git diff 기준으로 계획과 실제 변경사항이 일치하는지 확인해줘.

17체크리스트

큰 작업 전에 Plan Mode를 켔다

□

/plan 또는 Shift+Tab 사용법을 이해했다

□

수정 전 관련 파일을 조사하게 했다

□

수정할 파일과 수정하지 않을 파일을 구분하게 했다

□

위험 요소를 계획에 포함시켰다

□

테스트 방법을 계획에 포함시켰다

□

계획이 너무 넓으면 다시 좁혔다

□

민감 파일을 읽지 말라고 명시했다

□

승인 후 각 편집을 검토했다

□

수정 후 git diff로 계획과 실제 변경을 비교했다

□

섹션 07 · 마무리

이 단원에서 기억할 것

Plan Mode의 핵심은 다음과 같습니다:

수정 전에 먼저 조사하고, 계획을 검토한 뒤, 작게 승인하라.

가장 자주 쓸 기본 프롬프트:

/plan 이 작업을 하기 전에 관련 파일을 조사하고 계획을 작성해줘.
계획에는 아래 내용을 포함해줘.
1. 관련 파일 / 2. 현재 구조 / 3. 수정할 파일
4. 수정하지 않을 파일 / 5. 수정 이유
6. 위험 요소 / 7. 테스트 방법
8. 가장 작은 1단계 작업
아직 파일은 수정하지 마.

Plan Mode는 Claude Code를 안전하게 쓰기 위한 장치이면서, 동시에 결과 품질을 높이는 도구입니다. 큰 작업일수록 바로 실행하지 말고 Plan Mode → 검토 → 작은 승인 → diff 확인 순서로 진행하세요.

다음 단원

8단원. 파일 수정과 명령 실행을 안전하게 다루기

8. 파일 수정과 명령 실행을 효율적으로 통제하는 법

01핵심 개념

Claude Code를 잘 쓰는 핵심은 모든 작업을 막는 것이 아닙니다. 핵심은 수정 범위와 명령 실행 범위를 작게 통제하면서 빠르게 반복하는 것입니다.

초보자가 기억할 공식:

작게 수정한다
↓
바로 확인한다
↓
필요한 명령만 실행한다
↓
결과를 보고 다음 수정으로 넘어간다

나쁜 방식은 "전체 프로젝트를 고쳐줘", 좋은 방식은 "src/auth/login.ts 파일만 수정하고 git diff로 검토"입니다.

02왜 필요한가

Claude Code는 빠릅니다. 하지만 빠르기 때문에 통제하지 않으면 원하지 않는 파일까지 수정될 수 있습니다.

이 파일만 수정해줘

변경 범위가 작아짐

명령어 후보만 먼저 알려줘

실행을 통제할 수 있음

git diff 기준으로 검토해줘

변경사항을 빠르게 확인할 수 있음

효율적인 사용자는 Claude에게 모든 권한을 한 번에 주지 않습니다. 대신 작은 승인 단위를 만듭니다.

큰 작업 1개 → 작은 수정 3~5개 → 각 수정마다 diff 확인 → 필요한 테스트만 실행

03Claude Code가 다루는 작업 구분하기

Claude Code 작업은 크게 4가지로 나눌 수 있습니다.

읽기

파일 분석, 구조 파악 | 읽을 범위 지정

수정

파일 편집, 코드 추가 | 수정할 파일 지정

명령 실행

테스트, 빌드, lint | 실행 전 후보 확인

Git 작업

diff 확인, 커밋 메시지 | 커밋 전 검토

가장 위험한 흐름은 수정 → 명령 실행 → 실패 → 자동 재수정 → 반복입니다. 초보자는 항상 읽기와 수정, 실행을 분리해야 합니다.

04파일 수정은 "최소 범위"로 시키기

파일 수정 요청에는 반드시 4가지를 넣으세요.

수정할 파일
수정하지 않을 파일
수정 목적
수정 후 확인 방법

나쁜 예: 로그인 버그 고쳐줘.

좋은 예:

로그인 버그를 수정해줘.
조건:
- src/auth/login.ts 파일만 수정해줘.
- 다른 파일은 수정하지 마.
- 수정 후 git diff 기준으로 요약해줘.

05수정할 파일과 수정하지 않을 파일을 같이 말하기

Claude에게 "무엇을 할지"만 말하면 범위가 넓어질 수 있습니다. "무엇을 하지 말지"도 같이 말해야 합니다.

이 방식의 장점:

수정할 파일 지정

범위가 작아짐

수정하지 않을 파일 지정

의도치 않은 변경 감소

목적 지정

불필요한 리팩터링 방지

변경 후 요약 요청

리뷰가 쉬워짐

06여러 파일 수정은 단계로 나누기

여러 파일을 수정해야 한다면 한 번에 승인하지 마세요.

나쁜 예: 회원가입 기능을 완성해줘. 필요한 파일은 전부 수정해도 돼.

좋은 예: 먼저 작업을 3단계로 나누고, 각 단계마다 수정할 파일, 수정 내용, 테스트 방법, 위험 요소를 정리한 뒤, 한 단계씩 실행합니다.

여러 파일 수정은 다음 흐름이 좋습니다:

1타입 또는 validation 수정

2diff 확인

3UI 연결

4diff 확인

5테스트 추가 및 실행

07명령 실행은 "후보 → 승인 → 실행"으로 다루기

명령어는 바로 실행시키지 말고 먼저 후보를 받으세요.

나쁜 예: 테스트 돌리고 실패하면 고쳐줘.

좋은 예: 이 변경사항을 확인하기 위해 실행할 테스트 명령어 후보를 알려달라고 하고, 각 명령어가 무엇을 확인하는지도 설명받은 뒤 하나만 승인합니다.

명령 실행 순서:

명령어 후보 요청
↓
명령어 의미 확인
↓
하나만 승인
↓
실행 결과 요약
↓
실패 원인 분석
↓
수정 계획 요청

08명령어 위험도 구분하기

모든 명령어가 같은 위험도를 갖는 것은 아닙니다.

낮음

git status, git diff, ls | 비교적 안전

중간

npm test, npm run lint, npm run build | 실행 전 목적 확인

높음

npm install, pip install, brew install | 의존성 변경 여부 확인

매우 높음

rm -rf, sudo, DB migration, deploy | 초보자는 바로 승인 금지

민감

.env 출력, API key 확인 | 실행 금지

09Git 명령은 Claude에게 자주 시켜도 좋다

파일 수정 후 가장 자주 써야 하는 명령은 Git 확인 명령입니다.

git status
git diff

Claude Code 안에서는 이렇게 요청합니다.

git status와 git diff를 확인한 뒤 현재 변경사항을 요약해줘.
변경된 파일, 변경 내용, 의도한 변경인지, 위험한 변경 가능성, 테스트 필요 여부를 정리해줘.

커밋 메시지 요청: git diff를 기준으로 Conventional Commits 형식의 커밋 메시지를 작성해달라고 하세요.

10권한 설정으로 반복 확인 줄이기

매번 같은 안전한 명령을 승인하는 것이 번거롭다면, 일부 도구나 명령을 허용할 수 있습니다.

프로젝트 설정에서 권한을 지정하는 예시:

{
  "permissions": {
    "allow": [
      "Read",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(npm test)",
      "Bash(npm run lint)"
    ],
    "deny": [
      "Read(./.env)",
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(git push *)"
    ]
  }
}

초보자에게 추천하는 허용 범위는 작게 시작하는 것입니다. 효율은 "자주 쓰는 안전한 작업만 허용하고, 위험한 작업은 계속 통제하는 것"입니다.

11dangerously-skip-permissions는 초보자가 쓰지 않기

CLI에는 권한 프롬프트를 건너뛰는 --dangerously-skip-permissions 옵션이 있습니다.

나쁜 예:

claude --dangerously-skip-permissions

이 옵션은 편해 보이지만, Claude가 파일 수정과 명령 실행을 너무 쉽게 진행할 수 있습니다.

초보자에게 더 좋은 방식:

claude --permission-mode plan

또는 Claude Code 안에서 /plan 먼저 수정 계획을 작성해달라고 요청하세요.

12수정 후 반드시 확인해야 할 것

파일 수정이 끝나면 터미널에서:

git status
git diff

필요하면 테스트도 실행합니다.

Claude에게는 수정한 내용을 아래 형식으로 검토해달라고 요청하세요:

변경된 파일
각 파일의 변경 내용
원래 목표와 일치하는지
의도치 않은 변경 가능성
추가 테스트 필요 여부
되돌려야 할 부분이 있는지

13수정 후 확인할 구체적 항목

특히 아래 항목을 꼼꼼히 확인해야 합니다.

수정 파일 수

너무 많은 파일이 바뀌었는지 확인

lock file 변경

의존성 변화 여부 확인

설정 파일 변경

실행 환경에 영향 가능

테스트 파일 변경

실제 기능보다 테스트만 맞춘 것은 아닌지

삭제된 코드

필요한 로직이 사라졌는지 확인

.env 관련 변경

민감 정보 노출 가능

14테스트 실패 후 바로 수정하지 않기

테스트가 실패하면 바로 "고쳐줘"라고 하지 마세요. 먼저 원인을 분리해야 합니다.

나쁜 예: 테스트 실패했네. 알아서 고쳐줘.

좋은 예: 테스트 실패 원인을 분석해달라고 하되, 아직 파일은 수정하지 말고, 실패한 테스트 이름, 실패 원인을 가능성 높은 순서로, 코드 문제와 테스트 기대값 문제를 구분해 설명해달라고 요청하세요.

테스트 실패 대응 흐름:

실패 로그 요약 → 원인 후보 정리 → 코드/테스트 문제 구분
→ 수정 계획 → 최소 수정 → 재테스트

15실전 워크플로우: 작은 버그 수정

상황: 로그인 시 access token이 없으면 앱이 터집니다.

1단계. 수정 계획 요청

관련 파일을 찾고 수정 계획만 작성해달라고 요청합니다. 아직 파일은 수정하지 말고, 수정할 파일과 수정하지 않을 파일을 구분해달라고 합니다.

2단계. 작은 수정 승인

src/auth/login.ts 파일만 수정하고, access token이 없을 때 명확한 에러를 반환하도록 합니다. 다른 파일은 수정하지 않습니다.

3단계. diff 확인

git diff를 확인하고 변경사항을 요약해달라고 요청합니다.

4단계. 테스트 후보 확인

이 변경사항을 검증할 테스트 명령어 후보를 받고, 아직 실행하지 않습니다.

5단계. 테스트 실행 승인

가장 좁은 범위의 테스트 명령어 1개만 실행하고, 실패하면 원인만 분석하라고 합니다.

16실전 워크플로우: lint 자동 수정

상황: lint 오류가 여러 개 있습니다.

나쁜 요청: lint 오류 다 고쳐줘.

좋은 요청:

lint 명령어 후보를 알려달라고 하고, 아직 실행하지 말라고 합니다.
npm run lint를 실행해달라고 승인하되, 실패하면 오류를 파일별로 분류해달라고 합니다.
자동으로 고칠 수 있는 formatting 문제만 수정하고, 로직 변경이 필요한 문제는 수정하지 말라고 합니다.
git diff를 보고 formatting 변경과 로직 변경을 구분해달라고 요청합니다.

17실전 워크플로우: 빌드 실패 분석

상황: 빌드가 실패합니다.

이 프로젝트의 빌드 명령어 후보를 찾아달라고 하고, package.json이나 설정 파일을 근거로 설명해달라고 합니다. 아직 명령어는 실행하지 말라고 합니다.
npm run build를 실행해달라고 승인하되, 실패하면 실패 로그를 요약하고 원인 후보만 정리해달라고 합니다. 아직 파일은 수정하지 말라고 합니다.
빌드 실패 원인을 직접적인 에러 메시지, 관련 파일, 가능성 높은 원인, 확인해야 할 코드, 최소 수정 계획 순서로 정리해달라고 요청합니다.
가장 가능성 높은 원인 1개만 수정하고, 수정 범위를 최소화한 뒤 git diff로 요약해달라고 합니다.

18실전 워크플로우: 패키지 설치

패키지 설치는 lock file과 의존성 구조를 바꿀 수 있습니다. 바로 승인하지 마세요.

이 기능 구현에 새 패키지가 필요한지 판단해달라고 하고, 먼저 기존 의존성으로 가능한지 확인해달라고 합니다. 설치 명령어는 아직 실행하지 말라고 합니다.
이 패키지를 설치하면 어떤 파일이 바뀔 수 있는지, 되돌리려면 어떤 명령이나 git 작업이 필요한지도 설명해달라고 요청합니다.
설치 명령어를 실행해달라고 승인하되, 설치 후 git diff를 확인해서 변경된 파일을 요약해달라고 합니다.

초보자는 가능하면 새 패키지를 추가하기 전에 기존 코드로 해결할 수 있는지 먼저 물어보세요.

19초보자가 자주 하는 실수

실수 1. 한 번에 너무 많은 파일을 수정시킨다

나쁜 예: 전체 프로젝트에서 타입 에러를 전부 수정해줘.

좋은 예: 타입 에러를 파일별로 분류하고, 가장 영향 범위가 작은 파일 1개만 먼저 수정 계획을 세워달라고 요청합니다.

실수 2. 명령어를 바로 실행하게 한다

나쁜 예: 필요한 명령어 다 실행해줘.

좋은 예: 필요한 명령어 후보를 먼저 알려달라고 하고, 각 명령어의 목적과 위험도를 설명해달라고 합니다. 아직 실행하지 말라고 합니다.

20초보자가 자주 하는 실수 (계속)

실수 3. 테스트 실패 후 자동 수정 루프를 만든다

나쁜 예: 테스트가 통과할 때까지 계속 고쳐줘.

좋은 예: 테스트 실패 원인을 분석하고, 가장 작은 수정 계획만 제안해달라고 하며, 내가 승인하기 전까지 수정하지 말라고 합니다.

실수 4. Git diff를 확인하지 않는다

수정 후에는 반드시 git status와 git diff를 확인하고, Claude에게 변경사항을 리뷰해달라고 요청합니다.

실수 5. 위험한 명령어를 승인한다

rm -rf, sudo, git reset --hard, npm publish, prisma migrate deploy 같은 명령은 초보자가 바로 승인하면 안 됩니다. 먼저 설명을 요구하세요.

21실전 프롬프트 모음

파일 하나만 수정시킬 때:

[파일 경로] 파일만 수정해줘.
목표: [수정 목표]
제한: - 다른 파일은 수정하지 마.
      - 수정 후 git diff 기준으로 요약해줘.

명령어 후보만 받을 때:

이 작업을 확인하기 위해 실행할 명령어 후보를 알려줘.
- 아직 실행하지 마.
- 각 명령어의 목적을 설명해줘.
- 위험도가 높은 명령어는 표시해줘.

실행 결과 분석할 때:

방금 실행한 명령어 결과를 분석해줘. 아래 형식으로 정리해줘.
1. 성공 여부  2. 핵심 메시지  3. 실패 원인 후보
4. 다음에 확인할 파일  5. 수정이 필요한지 여부
아직 파일은 수정하지 마.

테스트 실패 후 계획만 받을 때:

테스트 실패 원인을 분석해줘.
- 아직 수정하지 마.
- 실패한 테스트를 목록화해줘.
- 코드 문제와 테스트 문제를 구분해줘.
- 최소 수정 계획만 제안해줘.

diff 리뷰 요청할 때:

현재 git diff를 리뷰해줘.
기준: 원래 목표 일치, 의도치 않은 변경, 버그 가능성,
      테스트 충분성, 되돌려야 할 부분

22체크리스트

수정할 파일을 명확히 지정했다

□

수정하지 않을 파일도 지정했다

□

한 번에 하나의 목적만 수정하게 했다

□

명령어 실행 전 후보를 먼저 받았다

□

위험한 명령어는 바로 승인하지 않았다

□

테스트 실패 후 바로 자동 수정하지 않았다

□

수정 후 git status를 확인했다

□

수정 후 git diff를 확인했다

□

Claude에게 diff 리뷰를 요청했다

□

패키지 설치 전 lock file 변경 확인했다

□

.env, credentials 파일을 읽히지 않았다

□

반복 안전 명령만 권한 설정을 고려했다

□

섹션 08 · 마무리

이 단원에서 기억할 것

파일 수정과 명령 실행을 잘 다루는 핵심은 이것입니다.

크게 맡기지 말고, 작게 시키고, 바로 확인하고, 다시 반복하라.

가장 자주 쓸 기본 프롬프트는 다음과 같습니다.

먼저 수정할 파일과 수정하지 않을 파일을 구분해줘.
파일을 수정하기 전에 계획을 보여줘.
내가 승인하면 계획에 나온 파일만 수정해줘.
명령어가 필요하면 실행 전에 후보와 이유를 알려줘.
수정 후 git diff 기준으로 변경사항을 리뷰해줘.

Claude Code를 효율적으로 쓰는 사람은 모든 것을 자동화하지 않습니다. 자주 반복되는 안전한 작업은 빠르게 허용하고, 위험한 작업은 작게 나누어 통제합니다.

다음 단원

9단원. CLAUDE.md로 프로젝트 규칙 알려주기

9. CLAUDE.md로 프로젝트 규칙 알려주기

01핵심 개념

CLAUDE.md는 Claude Code에게 이 프로젝트에서 항상 알아야 할 규칙과 맥락을 알려주는 파일입니다. 쉽게 말하면, Claude Code용 프로젝트 설명서입니다.

CLAUDE.md는 다음과 같은 내용을 담습니다.

프로젝트 구조
빌드 명령어
테스트 명령어
코딩 규칙
수정 전 확인 절차
민감 파일 주의사항
팀 작업 방식

Claude Code가 세션 시작 시 읽는 지속 지침 파일입니다. 각 세션은 새 컨텍스트로 시작하므로, 세션 간 프로젝트 지식을 전달하기 위해 CLAUDE.md와 auto memory가 사용됩니다.

02왜 필요한가

CLAUDE.md가 없으면 매번 같은 설명을 반복해야 합니다. 예를 들어 매 세션마다 이런 내용을 말해야 할 수 있습니다.

이 프로젝트는 pnpm을 써.
테스트는 pnpm test로 실행해.
.env 파일은 읽지 마.
수정 전에는 계획부터 보여줘.
커밋 전에는 git diff를 확인해.

CLAUDE.md가 있으면 좋은 점입니다.

반복 설명 감소

매번 같은 규칙을 말하지 않아도 됨

프로젝트 이해 속도 증가

Claude가 구조와 명령어를 빨리 파악함

실수 감소

잘못된 패키지 매니저나 테스트 명령 사용 방지

팀 규칙 공유

팀원이 같은 기준으로 Claude Code 사용

수정 품질 향상

아키텍처, 네이밍, 테스트 규칙을 반영하기 쉬움

03CLAUDE.md에 넣어야 할 내용

초보자는 처음부터 완벽하게 작성하려고 하지 않아도 됩니다. 아래 7가지만 넣어도 충분합니다.

1. 프로젝트 개요
2. 주요 폴더 구조
3. 실행 명령어
4. 테스트 명령어
5. 코딩 규칙
6. 작업 절차
7. 금지 또는 주의사항

이 정도만 있어도 Claude Code의 작업 품질이 달라집니다.

04CLAUDE.md 파일 위치

프로젝트에서 가장 기본적인 위치는 프로젝트 루트입니다. 또는 .claude 폴더 안에 둘 수도 있습니다.

위치별 용도와 공유 여부는 다음과 같습니다.

./CLAUDE.md

프로젝트 공통 규칙 (팀 공유)

./.claude/CLAUDE.md

프로젝트 공통 규칙 (팀 공유)

./CLAUDE.local.md

개인용 프로젝트 메모 (공유하지 않음)

~/.claude/CLAUDE.md

모든 프로젝트에 적용할 개인 선호 (개인용)

초보자는 처음에는 프로젝트 루트의 CLAUDE.md 하나로 시작하면 됩니다.

05자동으로 CLAUDE.md 시작하기

처음부터 직접 쓰기 어렵다면 Claude Code에게 초안을 만들게 할 수 있습니다. Claude Code 안에서 /init 명령을 실행하면 코드베이스를 분석해 빌드 명령어, 테스트 지침, 프로젝트 규칙을 포함한 시작용 CLAUDE.md를 생성합니다. 이미 CLAUDE.md가 있으면 덮어쓰기보다 개선 제안을 합니다.

초보자에게 추천하는 흐름입니다.

1/init 명령 실행

2검토 생성된 CLAUDE.md 검토, 개선안만 제시 요청

3수정 승인 CLAUDE.md를 짧고 명확하게 정리 요청

06좋은 CLAUDE.md 작성 원칙

좋은 CLAUDE.md는 길지 않습니다. 명확하고, 구체적이고, 자주 쓰는 정보만 담습니다. 파일당 200줄 이하를 목표로 합니다.

좋은 규칙:

- 이 프로젝트는 pnpm을 사용한다.
- 테스트는 pnpm test로 실행한다.
- 인증 관련 코드는 src/features/auth에 있다.
- 파일을 수정하기 전에 수정 계획을 먼저 설명한다.

나쁜 규칙:

- 코드를 잘 작성한다.
- 예쁘게 정리한다.
- 적당히 테스트한다.
- 알아서 안전하게 한다.

나쁜 표현

좋은 표현

코드를 깔끔하게 작성

함수는 50줄을 넘기지 않도록 우선 검토한다

테스트 잘 돌리기

수정 후 pnpm test 후보를 먼저 제안한다

보안 조심

.env, credentials, *.pem 파일은 읽지 않는다

알아서 리팩터링

리팩터링 전 변경 범위와 위험 요소를 먼저 설명한다

07CLAUDE.md는 명령서가 아니라 프로젝트 정보다

CLAUDE.md는 Claude에게 프로젝트 맥락을 주는 파일입니다. 너무 강한 명령문처럼 쓰기보다, 사실 중심으로 쓰는 것이 좋습니다.

좋은 예:

## 프로젝트 정보
- 이 저장소는 pnpm을 사용한다.
- 기본 테스트 명령어는 pnpm test이다.
- 인증 코드는 src/features/auth에 있다.
- API 클라이언트는 src/lib/api.ts에 있다.

덜 좋은 예:

너는 반드시 언제나 절대로 pnpm만 사용해야 한다.
절대 실수하지 마라.
무조건 내 말을 따라라.

CLAUDE.md는 강제 보안 장치가 아닙니다. CLAUDE.md와 auto memory는 Claude에게 전달되는 컨텍스트이지, 강제 설정이 아닙니다. 특정 행동을 반드시 차단하려면 권한 설정이나 hook 같은 장치를 사용해야 합니다.

08초보자용 CLAUDE.md 템플릿

# CLAUDE.md

## 프로젝트 개요
이 프로젝트는 [프로젝트 목적]을 위한 애플리케이션이다.

## 기술 스택
- 언어: [예: TypeScript]
- 프레임워크: [예: Next.js]
- 패키지 매니저: [예: pnpm]
- 테스트 도구: [예: Vitest, Jest, Playwright]

## 주요 명령어
- 개발 서버: [예: pnpm dev]
- 테스트: [예: pnpm test]
- 린트: [예: pnpm lint]
- 빌드: [예: pnpm build]

## 주요 폴더
- src: 애플리케이션 소스 코드
- src/components: UI 컴포넌트
- src/features: 기능 단위 코드
- src/lib: 공통 유틸리티
- tests: 테스트 코드

## 작업 규칙
- 파일을 수정하기 전에 먼저 수정 계획을 설명한다.
- 큰 작업은 작은 단계로 나눈다.
- 수정할 파일과 수정하지 않을 파일을 구분한다.
- 수정 후 git diff 기준으로 변경사항을 요약한다.
- 테스트 명령어는 실행 전에 후보와 이유를 먼저 설명한다.

## 코드 스타일
- 기존 코드 스타일을 우선 따른다.
- 불필요한 대규모 리팩터링을 하지 않는다.
- 기능 변경과 포맷팅 변경을 가능한 한 분리한다.
- 새 패키지를 추가하기 전에 기존 의존성으로 해결 가능한지 확인한다.

## 주의사항
- .env, .env.local, credentials, private key 파일은 읽지 않는다.
- API key, token, password 같은 민감 정보를 출력하지 않는다.
- 삭제, 배포, DB migration 명령은 실행 전에 반드시 설명한다.
- package.json이나 lock file 변경 전에는 이유를 먼저 설명한다.

작성 후 Claude에게 검토를 요청하세요.

09프로젝트 유형별 예시 ① 웹 프론트엔드

웹 프론트엔드 프로젝트의 예시입니다.

# CLAUDE.md

## 프로젝트 개요
이 프로젝트는 React 기반 프론트엔드 애플리케이션이다.

## 주요 명령어
- 개발 서버: pnpm dev
- 테스트: pnpm test
- 린트: pnpm lint
- 빌드: pnpm build

## 주요 폴더
- src/components: 공통 UI 컴포넌트
- src/pages 또는 src/app: 라우팅
- src/features: 기능 단위 코드
- src/lib: API 클라이언트와 유틸리티
- tests: 테스트 코드

## 작업 규칙
- UI 변경 전 관련 컴포넌트와 사용 위치를 먼저 찾는다.
- 스타일 변경과 로직 변경은 가능하면 분리한다.
- 접근성에 영향을 줄 수 있는 변경은 설명한다.
- 수정 후 필요한 테스트 명령어 후보를 제안한다.

## 주의사항
- .env 파일은 읽지 않는다.
- 새 UI 라이브러리 추가 전 기존 컴포넌트로 가능한지 확인한다.

10프로젝트 유형별 예시 ② 백엔드 API

백엔드 API 프로젝트의 예시입니다.

# CLAUDE.md

## 프로젝트 개요
이 프로젝트는 REST API 서버다.

## 주요 명령어
- 개발 서버: pnpm dev
- 테스트: pnpm test
- 린트: pnpm lint
- 빌드: pnpm build

## 주요 폴더
- src/routes: API 라우트
- src/controllers: 요청 처리
- src/services: 비즈니스 로직
- src/repositories: 데이터 접근
- tests: 테스트 코드

## 작업 규칙
- API 변경 전 라우트, 서비스, 테스트를 함께 확인한다.
- 응답 형식이 바뀌면 영향받는 테스트를 확인한다.
- DB migration은 바로 실행하지 않고 먼저 계획을 설명한다.
- 에러 처리는 기존 패턴을 따른다.

## 주의사항
- credentials, private key, .env 파일은 읽지 않는다.
- 운영 DB에 영향을 줄 수 있는 명령은 실행하지 않는다.

11프로젝트 유형별 예시 ③ 라이브러리

라이브러리 프로젝트의 예시입니다.

# CLAUDE.md

## 프로젝트 개요
이 프로젝트는 재사용 가능한 라이브러리 패키지다.

## 주요 명령어
- 테스트: pnpm test
- 타입 체크: pnpm typecheck
- 빌드: pnpm build
- 릴리스 검증: pnpm lint && pnpm test && pnpm build

## 주요 폴더
- src: 라이브러리 소스 코드
- examples: 사용 예시
- tests: 테스트 코드
- docs: 문서

## 작업 규칙
- public API 변경 전 breaking change 여부를 설명한다.
- 타입 정의 변경 시 사용 예시와 테스트를 함께 확인한다.
- 릴리스 관련 파일은 수정 전 반드시 이유를 설명한다.
- 문서와 코드 예시가 일치하는지 확인한다.

## 주의사항
- npm publish 명령은 실행하지 않는다.
- package.json version 변경은 승인 전 수행하지 않는다.

12팀용 CLAUDE.md와 개인용 CLAUDE.local.md 분리하기

팀 프로젝트에서는 모두가 공유해야 할 규칙과 개인 취향을 분리해야 합니다.

팀 공통 규칙은 CLAUDE.md에 둡니다.

## 팀 공통 규칙
- 패키지 매니저는 pnpm을 사용한다.
- PR 전 pnpm lint와 pnpm test를 실행한다.
- 인증 관련 코드는 src/features/auth에 둔다.

개인 취향은 CLAUDE.local.md에 둡니다.

## 개인 작업 선호
- 설명은 한국어로 받는다.
- 수정 전 항상 단계별 계획을 먼저 요청한다.
- 테스트 명령어는 직접 승인한 뒤 실행한다.

CLAUDE.local.md는 .gitignore에 추가하여 공유하지 않는 것이 좋습니다.

13CLAUDE.md에 넣으면 안 좋은 내용

CLAUDE.md에 모든 것을 넣으면 오히려 품질이 떨어질 수 있습니다.

너무 긴 아키텍처 문서 전체

컨텍스트를 많이 차지함

오래된 명령어

Claude가 잘못된 명령을 사용할 수 있음

개인 취향

팀원에게 불필요함

비밀번호, API key

민감 정보 노출 위험

일회성 작업 지시

다음 세션에 불필요함

서로 충돌하는 규칙

Claude가 어떤 규칙을 따를지 불명확함

나쁜 예:

## 비밀 정보
- DATABASE_URL=postgres://...
- API_KEY=sk-...

좋은 예:

## 환경 변수
- 필요한 환경 변수 이름은 .env.example을 참고한다.
- 실제 .env 파일은 읽지 않는다.
- API key, token, password 값은 출력하지 않는다.

14CLAUDE.md와 권한 설정의 차이

CLAUDE.md는 Claude에게 알려주는 문서입니다. 권한 설정은 Claude가 할 수 있는 일을 제한하는 설정입니다. 중요합니다.

구분

CLAUDE.md

권한 설정

목적

프로젝트 맥락 제공

행동 허용/차단

형식

Markdown

JSON

예시

".env 파일은 읽지 않는다"

"Read(./.env)" 거부

강제성

낮음

높음

초보자 용도

규칙과 명령어 설명

민감 파일 차단

CLAUDE.md에 이렇게 쓰는 것은 좋습니다.

- .env 파일은 읽지 않는다.

하지만 더 확실히 막으려면 .claude/settings.json에 권한을 설정합니다.

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)"
    ]
  }
}

15CLAUDE.md가 제대로 로드되는지 확인하기

Claude Code 안에서 /memory 명령을 사용하면 현재 세션에 로드된 CLAUDE.md, CLAUDE.local.md, rules 파일을 확인할 수 있습니다.

Claude가 CLAUDE.md를 따르지 않는 것 같으면 이렇게 확인하세요.

/memory

그다음 Claude에게 물어볼 수 있습니다.

현재 세션에서 로드된 CLAUDE.md 내용을 기준으로,
이 프로젝트의 작업 규칙을 요약해줘.

문제가 있으면 다음을 확인합니다.

Claude가 규칙을 모름

/memory에 파일이 보이는지 확인

규칙이 안 지켜짐

문장이 너무 모호하지 않은지 확인

다른 규칙과 충돌

상위/하위 폴더의 CLAUDE.md 확인

너무 긴 파일

핵심 규칙만 남기기

반드시 실행돼야 하는 작업

hook 또는 권한 설정 고려

16큰 프로젝트에서 CLAUDE.md 나누기

처음에는 하나의 CLAUDE.md면 충분합니다. 하지만 프로젝트가 커지면 규칙을 나눌 수 있습니다.

my-project/
├── CLAUDE.md
├── frontend/
│   └── CLAUDE.md
├── backend/
│   └── CLAUDE.md
└── infra/
    └── CLAUDE.md

초보자 기준으로는 이렇게 시작하세요.

작은 프로젝트 → 루트 CLAUDE.md 하나
큰 프로젝트 → frontend/backend처럼 큰 영역별 CLAUDE.md 추가
팀 프로젝트 → 공통 규칙과 개인 규칙 분리

주의할 점은 규칙 충돌입니다. 이런 충돌이 있으면 Claude가 혼란스러울 수 있으므로 오래되거나 충돌하는 지침을 정기적으로 정리하는 것이 좋습니다.

17다른 문서 가져오기

CLAUDE.md에 모든 내용을 직접 넣지 않고, 다른 파일을 가져올 수 있습니다. @path/to/import 문법으로 다른 파일을 import할 수 있으며, 상대 경로와 절대 경로가 모두 가능합니다.

예시:

# CLAUDE.md

## 프로젝트 규칙
이 저장소는 pnpm을 사용한다.
수정 전에는 계획을 먼저 설명한다.

## 추가 문서
@docs/architecture.md
@docs/testing.md

초보자에게 추천하는 방식은 이렇습니다.

CLAUDE.md에는 핵심 규칙만 둔다.
긴 문서는 docs/ 폴더에 둔다.
필요한 문서만 @로 가져온다.

단, import가 많아지면 컨텍스트가 커질 수 있으므로 처음에는 짧은 CLAUDE.md 하나로 시작하는 것이 좋습니다.

18팀에서 CLAUDE.md 운영하기

팀에서는 CLAUDE.md를 단순한 개인 메모가 아니라 AI 작업 가이드로 관리하는 것이 좋습니다.

팀용 운영 원칙:

1. 팀 공통 규칙만 CLAUDE.md에 넣는다.
2. 개인 취향은 CLAUDE.local.md에 넣는다.
3. 명령어가 바뀌면 CLAUDE.md도 같이 수정한다.
4. PR에서 CLAUDE.md 변경을 리뷰한다.
5. 민감 정보는 절대 넣지 않는다.

팀용 CLAUDE.md에 넣으면 좋은 것:

패키지 매니저

pnpm 사용

테스트 명령

pnpm test

PR 전 확인

pnpm lint && pnpm test

아키텍처 규칙

feature 단위 폴더 구조

금지 사항

.env 읽기 금지, DB migration 자동 실행 금지

리뷰 기준

보안, 예외 처리, 테스트 누락 확인

19CLAUDE.md 업데이트가 필요한 순간

처음 만든 CLAUDE.md를 계속 그대로 두면 오래된 문서가 됩니다. 다음 상황에서는 업데이트해야 합니다.

패키지 매니저 변경

npm → pnpm

테스트 명령 변경

npm test → pnpm test

폴더 구조 변경

src/pages → src/app

새 규칙 도입

import alias, 네이밍 규칙

Claude가 같은 실수를 반복

해당 규칙을 명확히 추가

팀원이 같은 질문을 반복

프로젝트 설명 보강

민감 파일 구조 변경

접근 금지 파일 추가

Claude가 같은 실수를 두 번째로 하거나, 코드 리뷰에서 Claude가 알아야 할 내용이 발견되거나, 매 세션 같은 설명을 반복하게 될 때 CLAUDE.md에 추가하는 것이 좋습니다.

20초보자가 자주 하는 실수

실수 1. CLAUDE.md를 너무 길게 쓴다

나쁜 예: 전체 아키텍처 문서 500줄, 모든 회의 기록, 모든 API 명세, 오래된 TODO 목록

좋은 예: 핵심 규칙, 패키지 매니저, 테스트 명령, 수정 전 계획 규칙, .env 읽기 금지

실수 2. 모호한 표현을 쓴다

나쁜 예: "좋은 코드를 작성한다", "테스트를 잘 한다"

좋은 예: "새 기능을 추가할 때 관련 테스트 후보를 먼저 제안한다", "수정 후 git diff 기준으로 변경사항을 요약한다"

실수 3. 개인 취향을 팀 파일에 넣는다

나쁜 예: "모든 설명은 한국어로 한다", "답변은 항상 아주 자세하게 한다"

팀원 모두에게 필요한 규칙이 아니라면 CLAUDE.local.md에 넣는 것이 좋습니다.

실수 4. 민감 정보를 넣는다

나쁜 예: "실제 API key는 sk-...", "DB 비밀번호는 ..."

좋은 예: "실제 .env 파일은 읽지 않는다", "필요한 환경 변수 이름은 .env.example을 기준으로 확인한다"

실수 5. 강제 규칙과 안내 규칙을 혼동한다

CLAUDE.md에 썼다고 해서 100% 강제되는 것은 아닙니다. 강제하고 싶은 것은 권한 설정을 함께 사용하세요.

21체크리스트

프로젝트 루트에 CLAUDE.md를 만들었다

□

프로젝트 목적을 짧게 적었다

□

주요 명령어를 적었다

□

주요 폴더 구조를 적었다

□

수정 전 계획 요청 규칙을 적었다

□

수정 후 git diff 확인 규칙을 적었다

□

테스트 명령어를 적었다

□

민감 파일 주의사항을 적었다

□

개인 취향은 CLAUDE.local.md로 분리했다

□

너무 길거나 오래된 내용은 넣지 않았다

□

/memory로 로드 여부를 확인했다

□

강제 차단이 필요한 항목은 권한 설정도 고려했다

□

섹션 09 · 마무리

이 단원에서 기억할 것

CLAUDE.md는 Claude Code에게 매번 반복해서 설명할 내용을 저장하는 파일입니다.

핵심은 이것입니다.

자주 반복하는 설명은 CLAUDE.md에 넣고, 강제로 막아야 하는 행동은 권한 설정으로 막는다.

초보자는 아래 기본 항목들만 기억해도 됩니다.

프로젝트 개요
주요 명령어 (개발 서버, 테스트, 린트, 빌드)
주요 폴더 구조
작업 규칙 (계획 먼저, git diff 확인, 단계별 진행)
주의사항 (.env, credentials, 삭제/배포 명령 등)

잘 만든 CLAUDE.md는 Claude Code를 매번 처음부터 교육하지 않아도 되게 해줍니다. 프로젝트가 커질수록 CLAUDE.md의 효과도 커집니다.

다음 단원

10단원. 설정 파일 구조 이해하기

10. 설정 파일 구조 이해하기

01핵심 개념

Claude Code의 설정은 사용자 전체 설정, 프로젝트 공통 설정, 프로젝트 개인 설정, 회사 관리 설정으로 나뉩니다.

초보자는 이렇게 이해하면 됩니다.

내 모든 프로젝트에 적용할 설정

~/.claude/settings.json

이 프로젝트 팀원 모두에게 적용할 설정

.claude/settings.json

이 프로젝트에서 나만 쓸 설정

.claude/settings.local.json

회사나 조직이 강제로 적용하는 설정

managed settings

02왜 필요한가

설정 파일 구조를 모르면 여러 문제가 생깁니다.

설정을 잘못된 위치에 넣음

개인 설정을 팀 공유 파일에 넣음

팀원에게 불필요한 설정이 공유됨

내 output style, 내 실험 설정이 커밋됨

민감 파일 차단이 안 됨

.env 접근 금지 규칙을 빼먹음

권한 설정이 꼬임

어느 설정에서 허용했는지 모름

회사 정책과 충돌

managed settings가 덮어쓰는 이유를 모름

Claude가 예상과 다르게 동작

local 설정이 project 설정을 덮어씀

설정 구조를 이해하면 Claude Code를 더 효율적으로 통제할 수 있습니다.

03설정 파일 위치 한눈에 보기

가장 중요한 설정 파일은 세 가지입니다.

설정 파일

위치

사용자 설정

~/.claude/settings.json

프로젝트 공유 설정

.claude/settings.json

프로젝트 로컬 설정

.claude/settings.local.json

각 파일의 Git 포함 여부:

사용자 설정

아니오 (프로젝트 밖)

프로젝트 공유 설정

예 (팀 공유용)

프로젝트 로컬 설정

아니오 (개인 전용)

04폴더 구조로 보기

프로젝트 안의 설정 파일은 이렇게 배치됩니다.

my-project/
├── .claude/
│   ├── settings.json
│   └── settings.local.json
├── CLAUDE.md
├── package.json
└── src/

사용자 전체 설정은 프로젝트 밖에 있습니다.

~/.claude/settings.json

Windows에서는 ~/.claude가 보통 이렇게 해석됩니다.

%USERPROFILE%.claude

05설정 우선순위 이해하기

Claude Code 설정은 같은 항목이 여러 곳에 있을 때 우선순위를 따릅니다.

우선순위 1

Managed settings (회사나 조직이 강제로 적용)

우선순위 2

CLI flags (이번 실행에서만 임시 적용)

우선순위 3

.claude/settings.local.json (이 프로젝트에서 나만 적용)

우선순위 4

.claude/settings.json (이 프로젝트 팀 전체 적용)

우선순위 5

~/.claude/settings.json (내 모든 프로젝트 기본값)

06우선순위 이해하기 · 실전 예시

사용자 설정에 이렇게 되어 있어도:

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

프로젝트 설정에 이렇게 되어 있으면:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

해당 프로젝트에서는 프로젝트 설정이 우선합니다.

내 전체 기본값보다 프로젝트 규칙이 우선이다. 프로젝트 공통 규칙보다 내 로컬 설정이 우선이다. 하지만 회사 관리 설정은 내가 덮어쓸 수 없다.

07사용자 설정: `~/.claude/settings.json`

모든 프로젝트에 적용하고 싶은 개인 설정을 넣습니다.

{
  "outputStyle": "Explanatory",
  "permissions": {
    "defaultMode": "plan"
  }
}

개인 output style

모든 프로젝트에서 같은 답변 스타일 사용

기본 permission mode

항상 Plan Mode로 시작하고 싶을 때

개인적으로 자주 쓰는 도구 설정

프로젝트와 무관한 개인 설정

개인 환경 변수

모든 세션에서 필요한 값

08프로젝트 공유 설정: `.claude/settings.json`

팀원 모두가 지켜야 하는 프로젝트 설정을 넣습니다.

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm -rf *)",
      "Bash(git push *)"
    ],
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(pnpm test)",
      "Bash(pnpm lint)"
    ],
    "defaultMode": "plan"
  }
}

민감 파일 접근 차단

팀 전체 보안 규칙

프로젝트 테스트 명령 허용

반복 승인 줄이기

위험 명령 차단

실수 방지

팀 공통 hooks

같은 품질 검사 적용

프로젝트 플러그인

팀 전체 도구 표준화

09프로젝트 로컬 설정: `.claude/settings.local.json`

이 프로젝트에서 나만 쓰는 설정을 넣습니다.

{
  "outputStyle": "Explanatory",
  "env": {
    "DEBUG": "app:*"
  }
}

내 실험 설정

팀원에게 공유할 필요 없음

내 터미널 환경 변수

다른 사람 환경과 다름

개인 output style

팀 규칙이 아님

임시 권한 허용

테스트 후 제거 가능

10초보자용 최소 설정 예시

처음부터 복잡하게 설정하지 않아도 됩니다. 초보자는 프로젝트에 .claude/settings.json 하나만 만들어도 충분합니다.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "defaultMode": "plan",
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(pnpm test)",
      "Bash(pnpm lint)",
      "Bash(pnpm build)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(git push *)",
      "Bash(npm publish *)"
    ]
  }
}

11최소 설정의 의미

위 설정은 세 가지를 합니다.

defaultMode: "plan"

기본적으로 계획부터 세우게 함

allow

자주 쓰는 안전한 명령은 반복 승인 줄임

deny

민감 파일과 위험 명령은 차단

초보자는 복잡한 설정을 한 번에 만들 필요가 없습니다. 처음에는 민감 파일 차단, 위험 명령 차단, Plan Mode 기본값만 설정해도 충분합니다.

12`$schema`는 왜 넣는가

설정 파일 맨 위에 $schema를 넣으면 편집기에서 자동완성이나 검증 도움을 받을 수 있습니다.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json"
}

$schema를 추가하면 VS Code, Cursor 등 JSON Schema를 지원하는 편집기에서 자동완성과 inline validation을 사용할 수 있습니다.

초보자는 설정 파일을 만들 때 $schema를 넣어두는 것이 좋습니다.

13권한 설정 구조 이해하기

가장 자주 쓰는 설정은 permissions입니다. 기본 구조는 다음과 같습니다.

{
  "permissions": {
    "allow": [],
    "deny": [],
    "ask": [],
    "defaultMode": "plan"
  }
}

allow

허용할 도구나 명령

deny

차단할 도구나 명령

ask

실행 전 물어볼 도구나 명령

defaultMode

Claude Code 시작 시 기본 권한 모드

14권한 설정 구조 · 실전 예시

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(pnpm test)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Bash(rm -rf *)",
      "Bash(git push *)"
    ],
    "ask": [
      "Bash(pnpm install *)",
      "Bash(docker *)"
    ],
    "defaultMode": "plan"
  }
}

이렇게 하면 git status, git diff, pnpm test는 빠르게 실행할 수 있고, .env 읽기와 위험 명령은 막을 수 있습니다.

15권한 모드 설정하기

defaultMode는 Claude Code가 어떤 권한 모드로 시작할지 정합니다.

default

기본 승인 흐름

plan

수정 전 계획 우선 (추천)

acceptEdits

편집을 더 쉽게 허용

bypassPermissions

권한 확인 우회 (비추천)

터미널에서 한 번만 Plan Mode로 실행하고 싶다면:

claude --permission-mode plan

16설정 파일은 언제 적용되는가

Claude Code는 설정 파일 변경을 감지해 대부분의 키를 실행 중인 세션에도 다시 로드합니다.

권한 설정 변경

대체로 바로 반영

hooks 변경

대체로 바로 반영

model 변경

/model 또는 재시작 확인

outputStyle 변경

/clear 또는 재시작 확인

설정을 바꾼 뒤에는 Claude Code 안에서 이렇게 확인하세요.

/status

17`/status`로 현재 설정 확인하기

설정이 제대로 적용되는지 확인하려면 Claude Code 안에서 /status를 사용합니다.

User settings

~/.claude/settings.json이 로드됨

Project settings

.claude/settings.json이 로드됨

Project local settings

.claude/settings.local.json이 로드됨

Enterprise managed settings

회사 관리 설정이 로드됨

오류 메시지

JSON 문법 또는 validation 문제

18설정 파일 문법 오류 피하기

settings.json은 JSON 파일입니다. 쉼표, 따옴표, 주석에 주의해야 합니다.

나쁜 예 (마지막 쉼표):

{
  "permissions": {
    "defaultMode": "plan",
  }
}

좋은 예:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

JSON에서는 주석도 사용할 수 없습니다. 설정을 수정한 뒤 문제가 생기면 /status로 오류를 확인하세요.

19팀 프로젝트에서 추천하는 설정 구조

팀 프로젝트에서는 아래처럼 나누는 것이 좋습니다.

팀 전체 규칙

.claude/settings.json

개인 실험 설정

.claude/settings.local.json

내 모든 프로젝트 기본 설정

~/.claude/settings.json

각 파일의 역할을 명확히 하면 팀원 간의 설정 충돌을 줄일 수 있습니다.

20`CLAUDE.md`와 `settings.json`의 차이

초보자가 가장 많이 헷갈리는 부분입니다.

파일 형식

CLAUDE.md

Markdown

settings.json

JSON

목적

Claude에게 프로젝트 맥락 설명

Claude Code 동작 설정

강제성

낮음

높음

적합한 내용

코딩 규칙, 아키텍처 설명

권한, 환경 변수, hooks

설명과 규칙은 CLAUDE.md, 실제 허용과 차단은 settings.json

21환경 변수는 어디에 넣을까

Claude Code 설정에는 env를 넣을 수 있습니다.

{
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "app:*"
  }
}

하지만 주의해야 합니다. env에는 실제 API 키나 비밀번호를 넣지 않는 것이 좋습니다.

민감 정보는 .env나 비밀 관리 도구에서 관리하고, Claude가 읽지 못하게 차단하는 편이 좋습니다.

22outputStyle 설정하기

답변 스타일을 바꾸고 싶다면 outputStyle을 설정할 수 있습니다.

{
  "outputStyle": "Explanatory"
}

Claude Code 안에서 설정 메뉴를 열려면:

/config

초보자는 output style을 팀 공유 설정에 넣기보다 개인 로컬 설정에 넣는 것이 좋습니다.

팀 전체 답변 스타일

필요할 때만 .claude/settings.json

내 개인 답변 스타일

.claude/settings.local.json

23설정을 CLI 옵션으로 임시 적용하기

설정 파일을 바꾸지 않고 이번 실행에서만 옵션을 줄 수 있습니다.

claude --permission-mode plan

이 명령은 이번 세션만 Plan Mode로 시작합니다.

CLI 옵션과 파일 설정의 관계:

일회성 실험

CLI flag

계속 쓸 개인 설정

~/.claude/settings.json

팀과 공유할 설정

.claude/settings.json

24설정이 합쳐지는 방식

설정은 단순히 "위 파일이 아래 파일을 완전히 덮어쓴다"가 아닙니다.

예: 사용자 설정에 allow 배열이 있으면:

"allow": ["Bash(git status)"]

프로젝트 설정에 다른 배열이 있으면:

"allow": ["Bash(pnpm test)"]

둘 다 적용되어 합쳐질 수 있습니다.

목록 설정은 합쳐질 수 있다. 단일 값 설정은 우선순위 높은 값이 이긴다.

25상태 파일 `~/.claude.json`은 직접 수정하지 않기

~/.claude.json이라는 파일도 있습니다. 하지만 초보자가 직접 수정할 파일은 아닙니다.

~/.claude.json에는 OAuth 세션, 사용자 및 로컬 scope MCP 서버 구성, 프로젝트별 상태, 허용된 도구, trust settings, 캐시 등이 저장됩니다.

~/.claude/settings.json

직접 수정 가능

.claude/settings.json

직접 수정 가능

.claude/settings.local.json

직접 수정 가능

~/.claude.json

초보자는 직접 수정 비추천

초보자는 설정을 바꿀 때 settings.json 계열만 수정하세요.

26초보자가 자주 하는 실수 ①

실수 1. 개인 설정을 팀 공유 파일에 넣는다

나쁜 예:

{
  "outputStyle": "내 개인 스타일",
  "env": {
    "MY_LOCAL_DEBUG": "1"
  }
}

팀 공유 파일인 .claude/settings.json에는 팀 전체에 필요한 설정만 넣으세요. 개인 설정은 .claude/settings.local.json에 넣습니다.

27초보자가 자주 하는 실수 ② · ③

실수 2. 민감 정보를 `env`에 넣는다

나쁜 예:

{
  "env": {
    "API_KEY": "real-secret-key"
  }
}

실수 3. JSON 문법을 틀린다

나쁜 예 (마지막 쉼표):

{
  "permissions": {
    "defaultMode": "plan",
  }
}

28초보자가 자주 하는 실수 ④

실수 4. 너무 많은 명령을 allow에 넣는다

나쁜 예:

{
  "permissions": {
    "allow": [
      "Bash(*)"
    ]
  }
}

좋은 예:

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(pnpm test)"
    ]
  }
}

처음에는 필요한 명령만 좁게 허용하세요.

29초보자가 자주 하는 실수 · 확인

실수 5. 설정이 적용됐는지 확인하지 않는다

설정 후에는 반드시 확인합니다.

/status

문제가 있으면 Claude에게 이렇게 물어보세요.

현재 설정 파일에 오류가 있는지 확인해줘.
어떤 설정 source가 로드됐는지도 설명해줘.

섹션 10 · 마무리

이 단원에서 기억할 것

설정 파일 구조의 핵심은 이것입니다.

개인 기본값은 사용자 설정에, 팀 공통 규칙은 프로젝트 설정에, 나만 쓰는 실험은 로컬 설정에 넣는다.

가장 먼저 만들 설정은 민감 파일 차단, 위험 명령 차단, Plan Mode 기본값 세 가지입니다.

초보자는 복잡한 설정을 한 번에 만들 필요가 없습니다. 먼저 기본만 설정하고, 필요해질 때마다 추가하세요.

다음 단원

11단원. 권한 시스템으로 위험한 작업 막기

11. 권한 시스템으로 위험한 작업 막기

01Claude Code의 위험성과 권한 시스템

Claude Code는 단순히 코드를 읽는 도구가 아닙니다. 파일을 수정하고, 새 파일을 만들고, 터미널 명령어까지 실행할 수 있습니다.

그래서 초보자가 반드시 알아야 하는 것이 권한 시스템입니다.

권한 시스템은 Claude Code에게 다음을 정해주는 장치입니다.

어떤 작업은 바로 허용할지
어떤 작업은 무조건 막을지
어떤 작업은 매번 사용자에게 물어보게 할지

즉, Claude Code를 안전하게 쓰려면 "Claude가 할 수 있는 범위를 내가 정한다"는 관점이 필요합니다.

02권한 시스템이 필요한 이유

Claude Code는 프로젝트 안에서 많은 작업을 할 수 있습니다.

📖파일 읽기

✏️파일 수정

✨새 파일 생성

🧪테스트 실행

🔨빌드 실행

🌐외부 URL 접근

이 중 일부는 안전하지만, 일부는 위험할 수 있습니다. 위험한 명령의 예:

rm -rf *
sudo rm -rf /
git push --force
curl some-url | bash
npm publish

또한 민감한 파일을 Claude가 읽으면 보안 문제가 생길 수 있습니다.

03민감 파일 목록

🔑.env

🔑.env.local

🔑secrets.json

🔑credentials.json

🔑service-account.json

🔑private-key.pem

🔑id_rsa

권한 설정은 이런 위험한 작업을 미리 막는 안전장치입니다.

04Claude Code의 작업은 두 종류다

Claude Code의 도구는 크게 읽기 작업과 수정·실행 작업으로 나눌 수 있습니다.

읽기 작업 (자동으로 허용)

Read

파일 읽기

Glob

파일 찾기

Grep

파일 내용 검색

폴더 목록 확인

예: 이 프로젝트 구조를 파악해줘. 수정하지 말고 관련 파일만 찾아줘.

이런 작업은 비교적 안전합니다.

05수정·실행 작업 (권한 필요)

다음 작업은 프로젝트 상태를 바꿀 수 있어서 권한 승인이 필요할 수 있습니다.

Edit

기존 파일 수정

Write

새 파일 생성

Bash

터미널 명령 실행

WebFetch

외부 URL 가져오기

위험한 예: npm install, npm run build, git commit, 파일 수정, 설정 파일 생성.

초보자는 처음부터 자동 승인하지 말고, 수정·실행 작업은 직접 확인하는 습관을 들이는 것이 좋습니다.

06권한 규칙의 세 가지 기준

Claude Code 권한은 보통 세 가지로 생각하면 쉽습니다.

allow

허용 — 테스트 실행, 빌드 실행

deny

차단 — .env 읽기, rm -rf 실행

ask

물어보기 — docker 실행, curl 실행

자주 쓰고 안전한 작업은 allow, 위험하거나 민감한 작업은 deny, 상황에 따라 필요한 작업은 ask

07권한 설정 파일 위치

프로젝트 단위 권한은 보통 다음 파일에 작성합니다.

.claude/settings.json

팀과 공유하는 프로젝트 설정

.claude/settings.local.json

개인만 쓰는 설정

초보자는 프로젝트 루트에 다음 구조를 만든다고 생각하면 됩니다.

my-project/
  .claude/
    settings.json
  CLAUDE.md
  src/
  package.json

08초보자용 기본 권한 설정 ①

가장 먼저 사용할 만한 안전한 설정은 다음과 같습니다.

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "LS",
      "Bash(npm run test:*)",
      "Bash(npm run lint:*)",
      "Bash(npm run build)"
    ],

이 부분은 파일 읽기, 검색, 목록 확인을 허용하고, 테스트, 린트, 빌드는 허용합니다.

09초보자용 기본 권한 설정 ②

    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Read(credentials/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Bash(curl:*)",
      "Bash(wget:*)",
      "Edit(.git/**)",
      "Edit(node_modules/**)"
    ],
    "ask": [
      "Bash(git:*)",
      "Bash(npm install:*)",
      "WebFetch"
    ],
    "defaultMode": "default"
  }
}

deny: .env, secrets, credentials 읽기 금지, 위험한 명령 차단.

ask: git, npm install, WebFetch는 실행 전 물어보기.

10민감 파일은 반드시 deny로 막기

Claude Code가 실수로 민감 정보를 읽지 않도록 해야 합니다.

특히 다음 파일은 차단하는 것이 좋습니다.

"deny": [
  "Read(.env*)",
  "Read(*secret*)",
  "Read(*credential*)",
  "Read(**/private-key*)",
  "Read(**/id_rsa*)"
]

주의: .gitignore에 들어 있다고 해서 Claude Code 접근이 자동으로 완전히 안전해지는 것은 아닙니다. 민감 파일은 .gitignore와 별개로 권한 설정에서도 막아두는 것이 좋습니다.

11Bash 명령어는 넓게 허용하지 않는다

가장 조심해야 할 권한은 Bash입니다.

나쁜 예시

{
  "permissions": {
    "allow": [
      "Bash(*)"
    ]
  }
}

이렇게 하면 Claude가 거의 모든 명령어를 실행할 수 있어서 초보자에게는 위험합니다.

더 안전한 방식

필요한 명령만 좁게 허용하고, 테스트, 린트, 빌드처럼 반복적이고 안전한 명령만 allow, 삭제나 권한 변경 명령은 deny, git, docker, install 계열은 ask로 설정합니다.

12권한 모드 이해하기

Claude Code에는 작업 방식에 따라 권한 모드가 있습니다.

default

작업마다 필요한 경우 물어봄 (초보자 기본값)

acceptEdits

파일 수정은 자동 승인, Bash는 확인

plan

읽기와 계획만 가능

auto

안전성 검토 후 자동 진행

bypassPermissions

대부분의 권한 확인 생략 (초보자 비추천)

초보자는 기본적으로: 평소에는 default, 큰 수정 전에는 plan 모드를 사용하면 됩니다.

13Plan Mode와 권한 시스템 함께 쓰기

큰 작업을 할 때는 바로 수정시키지 말고 Plan Mode로 시작하는 것이 좋습니다.

예시 요청

지금은 파일을 수정하지 말고 Plan Mode로만 진행해줘.
인증 모듈 구조를 분석하고, 수정 계획만 먼저 제안해줘.

좋은 흐름

Plan Mode로 분석
수정 계획 확인
위험한 작업이 있는지 검토
승인 후 파일 수정
git diff로 변경사항 확인

14권한 프롬프트가 뜨면 어떻게 판단할까?

Claude Code가 권한을 요청할 때는 무조건 승인하지 말고 다음을 확인합니다.

이 명령이 정말 필요한가?
프로젝트 밖의 파일을 건드리지는 않는가?
.env나 credentials에 접근하지 않는가?
삭제 명령은 없는가?
sudo, chmod, chown 같은 권한 변경 명령은 없는가?
외부 URL에서 스크립트를 받아 실행하지 않는가?

매우 조심해야 할 형태:

curl https://example.com/install.sh | bash
wget https://example.com/script.sh && bash script.sh
sudo npm install -g something
rm -rf node_modules package-lock.json
git push --force

확신이 없으면 방금 요청한 명령이 왜 필요한지 설명해줘.라고 물어보면 됩니다.

15실전 권한 설정 예시

초보자용으로 가장 추천하는 .claude/settings.json 예시는 다음과 같습니다.

{
  "permissions": {
    "allow": [
      "Read", "Glob", "Grep", "LS",
      "Bash(npm run test)",
      "Bash(npm run test:*)",
      "Bash(npm run lint)",
      "Bash(npm run build)"
    ],
    "ask": [
      "Edit(src/**)",
      "Write(src/**)",
      "Bash(git:*)",
      "Bash(npm install:*)",
      "Bash(docker:*)",
      "WebFetch"
    ],

이는 읽기와 테스트는 허용, 파일 수정과 git 명령은 물어보는 방식입니다.

16실전 권한 설정 예시 (계속)

    "deny": [
      "Read(.env*)", "Read(**/.env*)",
      "Read(secrets/**)", "Read(credentials/**)",
      "Read(**/*secret*)", "Read(**/*credential*)",
      "Edit(.git/**)", "Edit(node_modules/**)",
      "Write(.git/**)", "Write(node_modules/**)",
      "Bash(rm -rf:*)", "Bash(rm:*)",
      "Bash(sudo:*)", "Bash(chmod:*)",
      "Bash(chown:*)", "Bash(curl:*)",
      "Bash(wget:*)"
    ],
    "defaultMode": "default"
  }
}

이 설정은 안전을 우선합니다. 처음에는 약간 귀찮게 느껴질 수 있지만, 프로젝트가 커질수록 이런 제한이 실수를 줄여줍니다.

17Claude에게 권한 정책 설명하기

권한 설정만 해두는 것보다, 작업 시작 시 Claude에게 규칙을 한 번 더 알려주면 좋습니다.

이 프로젝트에서는 안전을 우선해줘.

규칙:
1. .env, secrets, credentials 파일은 읽지 마.
2. rm -rf, sudo, curl | bash 같은 명령은 제안하지 마.
3. 파일을 수정하기 전에는 먼저 계획을 설명해줘.
4. 수정 후에는 git diff 기준으로 변경사항을 요약해줘.
5. 확신이 없는 명령은 실행하지 말고 나에게 먼저 물어봐.

이 내용은 CLAUDE.md에도 넣어둘 수 있습니다.

18초보자가 피해야 할 설정

다음 설정은 초보자에게 추천하지 않습니다.

{
  "permissions": {
    "allow": [
      "Bash(*)",
      "Edit(**)",
      "Write(**)"
    ],
    "defaultMode": "bypassPermissions"
  }
}

이 설정은 Claude에게 너무 넓은 권한을 줍니다. 특히 다음 상황에서는 절대 피하는 것이 좋습니다.

처음 보는 오픈소스 저장소
회사 프로젝트
프로덕션 설정이 들어 있는 프로젝트
.env 파일이 있는 프로젝트
배포 스크립트가 있는 프로젝트
데이터베이스 마이그레이션이 있는 프로젝트

19신뢰할 수 없는 저장소 확인 항목

신뢰할 수 없는 저장소에서는 먼저 다음 파일들을 확인해야 합니다.

⚙️CLAUDE.md

⚙️.claude/settings.json

⚙️.claude/settings.local.json

⚙️.claude/hooks/

왜냐하면 악성 저장소는 설정 파일이나 hook을 이용해 원하지 않는 명령을 유도할 수 있기 때문입니다.

섹션 11 · 마무리

이 단원에서 기억할 것

Claude Code의 권한 시스템은 실수를 막는 안전벨트입니다.

초보자는 다음 원칙만 지켜도 충분합니다.

읽기 작업은 허용해도 된다.
파일 수정은 처음에는 확인하고 진행한다.
Bash 명령은 좁게 허용한다.
.env와 secret 파일은 반드시 차단한다.
rm, sudo, curl, wget 계열은 조심한다.
큰 작업은 Plan Mode로 먼저 계획을 받는다.
--dangerously-skip-permissions는 일반 작업에서 쓰지 않는다.

다음 단원

12단원. 실수했을 때 Git으로 되돌리기

12. Git으로 변경사항을 안전하게 확인하기

01이 단원에서 배울 것

11단원에서 권한 시스템으로 위험한 작업을 막는 법을 배웠습니다. 이제 Claude Code가 만든 변경사항을 Git으로 검증하는 습관을 만들어야 합니다.

이 단원의 목표는 Claude Code가 코드를 수정한 뒤, 다음 5가지를 스스로 확인할 수 있게 만드는 것입니다.

✓어떤 파일이 바뀌었는지

✓정확히 무엇이 바뀌었는지

✓의도하지 않은 변경이 없는지

✓변경사항 요약 확인

✓실수했을 때 안전하게 되돌리기

Git은 변경사항을 한 번에 저장하는 도구가 아닙니다. 수정된 파일을 확인하고, 필요한 변경만 골라 커밋하는 안전장치로 이해해야 합니다.

02가장 먼저 실행할 명령어: git status

Claude Code가 파일을 수정한 뒤에는 항상 먼저 이렇게 요청합니다.

git status를 실행해서 현재 변경된 파일을 요약해줘.
수정된 파일, 새로 생긴 파일, 삭제된 파일을 구분해서 설명해줘.

직접 터미널에서 확인할 수도 있습니다.

git status

git status는 현재 작업 디렉터리와 스테이징 영역의 차이, 그리고 아직 Git이 추적하지 않는 파일을 보여줍니다.

초보자는 git status 결과를 볼 때 아래 세 가지 상태만 보면 됩니다.

modified

기존 파일이 수정됨 — 의도한 파일인지 확인

new file / untracked

새 파일이 생김 — Claude가 만든 파일인지 확인

deleted

파일이 삭제됨 — 실수 삭제인지 반드시 확인

주의할 점은 git status만으로는 무엇이 바뀌었는지까지는 알 수 없다는 것입니다. git status는 "어떤 파일이 바뀌었는지"를 보는 명령어이고, "파일 안에서 무엇이 바뀌었는지"는 다음의 git diff로 확인합니다.

03실제 변경 내용 확인하기: git diff

변경된 파일 목록을 확인했다면 다음은 차이를 봅니다.

git diff

Claude에게는 이렇게 요청하면 좋습니다.

git diff를 확인해서 변경사항을 초보자도 이해할 수 있게 설명해줘.
파일별로 무엇이 추가됐고, 무엇이 삭제됐고, 이 변경이 왜 필요한지 정리해줘.

초보자는 diff에서 아래 기호만 먼저 이해하면 됩니다.

- 삭제된 줄
+ 추가된 줄

예를 들어 다음 diff가 있다면:

- const timeout = 3000;
+ const timeout = 10000;

이는 timeout 값을 3초에서 10초로 늘린 것입니다. 이때 Claude에게 이렇게 물어볼 수 있습니다.

이 diff에서 동작이 바뀌는 부분만 골라줘.
단순 포맷팅 변경과 실제 로직 변경을 구분해줘.

이 질문이 중요한 이유는 Claude가 여러 파일을 수정하다 보면, 실제 기능 변경과 포맷팅 변경이 섞일 수 있기 때문입니다.

04스테이징 전 diff와 스테이징 후 diff 구분하기

Git에는 "작업 중인 변경"과 "커밋에 포함할 변경"이 나뉘어 있습니다.

아직 git add를 하지 않은 상태에서 보는 diff:

git diff

스테이징한 뒤, 커밋에 들어갈 내용을 확인하려면:

git diff --staged

초보자에게 권장하는 흐름은 다음과 같습니다.

git status
git diff
git add <파일명>
git diff --staged
git commit

Claude에게는 이렇게 요청합니다.

아직 git add 하지 말고, 먼저 git diff만 검토해줘.
문제가 없어 보이면 어떤 파일을 스테이징해야 하는지 제안해줘.

그리고 스테이징 후에는 다시 확인합니다.

git diff --staged를 확인해서 이번 커밋에 들어갈 내용만 요약해줘.
불필요한 파일이 포함됐는지도 확인해줘.

05Claude Code에게 커밋 전 검토 요청하기

Claude Code는 Git 작업과 직접 연결되어 커밋 메시지 작성과 PR 생성까지 도울 수 있습니다. 하지만 초보자는 Claude에게 바로 "커밋해줘"라고 하기보다, 먼저 검토와 실행을 분리해야 합니다.

커밋하기 전 검토 요청 프롬프트:

커밋하기 전에 현재 변경사항을 검토해줘.
1. git status로 변경된 파일 목록을 확인해줘.
2. git diff로 실제 변경 내용을 확인해줘.
3. 의도하지 않은 변경, 위험한 변경, 민감정보 노출 가능성이 있는지 봐줘.
4. 테스트가 필요한 부분을 알려줘.
5. 커밋 메시지를 제안하되, 아직 커밋은 하지 마.

여기서 핵심은 마지막 문장입니다.

아직 커밋은 하지 마.

06커밋 메시지 작성 요청하기

변경사항이 안전하다고 판단되면 커밋 메시지를 요청합니다.

이번 변경사항에 맞는 커밋 메시지를 3개 제안해줘.
프로젝트가 conventional commit을 쓰는지 먼저 확인하고,
가능하면 그 형식에 맞춰줘.

conventional commit 예시:

fix: handle empty user profile response
feat: add validation for signup form
refactor: simplify auth token parsing

Claude에게 바로 커밋까지 맡기고 싶다면 다음처럼 말합니다.

git status와 git diff --staged를 다시 확인한 뒤,
문제가 없으면 제안한 메시지로 커밋해줘.
커밋 전에 마지막으로 포함 파일 목록을 보여줘.

07실수했을 때 되돌리는 기본 흐름

Git 되돌리기는 위험할 수 있으므로, 초보자는 먼저 상황을 구분해야 합니다.

아직 커밋하지 않은 파일 수정 되돌리기

특정 파일의 수정사항을 버리고 싶다면:

git restore <파일명>

Claude에게는 이렇게 요청합니다.

아직 커밋하지 않은 변경 중에서 되돌려도 안전한 파일이 있는지 확인해줘.
되돌리기 명령은 바로 실행하지 말고 먼저 제안만 해줘.

git add만 취소하기

파일 수정은 유지하되, 스테이징만 취소하려면:

git restore --staged <파일명>

이 명령은 "커밋 후보에서 빼는 것"이지, 파일 내용을 삭제하는 것이 아닙니다.

08최근 커밋을 되돌리고 싶을 때

커밋 자체를 조정할 때는 더 조심해야 합니다. 초보자에게는 아래 원칙을 세웁니다.

원칙

원격 저장소에 push한 커밋은 혼자 reset하지 않습니다. 먼저 Claude에게 상황을 설명하고, revert가 나은지 reset이 나은지 비교하게 합니다.

안전한 질문 예시 (아직 push하지 않은 경우):

방금 만든 커밋을 되돌리고 싶어.
아직 push는 하지 않았어.
reset, revert, amend 중 어떤 방법이 안전한지 설명하고,
실행 명령은 내가 승인하기 전까지 실행하지 마.

이미 push했다면:

이미 원격 저장소에 push한 커밋을 되돌리고 싶어.
히스토리를 바꾸지 않는 안전한 방법을 우선으로 제안해줘.

09Claude Code 권한과 Git 안전선 연결하기

이 단원은 11단원 권한 시스템과 연결됩니다. Claude Code는 기본적으로 읽기 전용 권한에서 시작하며, 파일 편집·테스트 실행·명령 실행 같은 추가 작업이 필요하면 명시적 승인을 요청합니다.

또한 .git 디렉터리는 보호 경로에 포함되므로, 위험한 Git 명령도 자동 승인되지 않습니다. 초보자용 권장 원칙은 다음과 같습니다.

자동 승인

git status, git diff, git log

승인 요청

git add, git commit, git push

거부

git reset --hard, git clean -fd, git push --force

이 설정은 초보자 학습용입니다. 실제 프로젝트에서는 팀 정책과 브랜치 전략에 맞게 조정해야 합니다.

10PR을 만들기 전 확인하기

Claude Code는 PR 생성도 도와줄 수 있습니다. 초보자용 PR 생성 전 프롬프트는 다음과 같습니다.

PR을 만들기 전에 현재 변경사항을 검토해줘.
1. git status 확인
2. git diff --staged 확인
3. 테스트 필요 여부 확인
4. PR 제목 제안
5. PR 설명 초안 작성
6. 리뷰어가 주의해야 할 위험 요소 정리
아직 PR은 만들지 마.

PR 설명 초안은 다음 구조가 좋습니다.

## 변경 요약
-
## 테스트
-
## 리뷰어가 확인할 점
-
## 위험 요소
-

11초보자용 안전 루틴

Claude Code로 코드를 수정한 뒤에는 아래 루틴을 반복합니다.

git status
git diff

그다음 Claude에게 묻습니다.

현재 변경사항을 검토해줘.
의도한 변경과 의도하지 않은 변경을 나눠서 설명해줘.

문제가 없으면 스테이징합니다.

git add <파일명>

스테이징 후 다시 확인합니다.

git diff --staged

마지막으로 커밋합니다.

git commit -m "메시지"

초보자에게 가장 중요한 습관은 이 한 문장입니다.

Claude가 코드를 바꿨다고 바로 믿지 말고, Git으로 증거를 확인한다.

섹션 12 · 마무리

12단원 핵심 정리

git status는 어떤 파일이 바뀌었는지 확인하는 명령어입니다.

git diff는 파일 안에서 무엇이 바뀌었는지 확인하는 명령어입니다.

git diff --staged는 커밋에 실제로 들어갈 변경사항을 확인하는 명령어입니다.

Claude Code에게 커밋을 맡기더라도, 커밋 전에는 반드시 변경 파일 목록과 diff 요약을 확인해야 합니다.

되돌리기 명령은 상황에 따라 위험도가 다르므로, 특히 reset --hard, clean -fd, push --force는 초보자 단계에서 자동 승인하지 않는 것이 안전합니다.

다음 단원

13단원. 모델 선택을 쉽게 이해하기

13. 모델 선택을 쉽게 이해하기

01모델 선택을 어렵게 생각하지 않기

Claude Code의 모델 선택은 처음에는 복잡해 보입니다. opus, sonnet, haiku, default, opusplan, sonnet[1m] 같은 이름이 나오기 때문입니다.

하지만 초보자는 아래처럼 이해하면 됩니다.

Haiku

빠르고 저렴한 모델 — 간단한 질문, 파일 요약, 짧은 탐색

Sonnet

균형형 모델 — 일반 코딩, 버그 수정, 테스트 작성

Opus

고성능 모델 — 복잡한 설계, 대형 리팩터링, 어려운 원인 분석

1M context

긴 세션·큰 코드베이스용 — 많은 파일을 오래 다루는 작업

opusplan

계획은 Opus, 실행은 Sonnet — 복잡한 계획 후 효율적인 구현

sonnet은 일상적인 코딩 작업용 최신 Sonnet, opus는 복잡한 추론 작업용 최신 Opus, haiku는 단순 작업용 빠르고 효율적인 Haiku를 가리키는 alias입니다. opusplan은 plan mode에서는 Opus를 쓰고 실행 단계에서는 Sonnet으로 전환하는 특수 모드입니다.

02현재 기준 주요 모델 감각

작성 시점 기준 공식 모델 개요에서는 최신 비교 모델로 Claude Opus 4.8, Claude Sonnet 4.6, Claude Haiku 4.5를 제시합니다. Opus 4.8은 복잡한 추론과 agentic coding에 가장 강한 모델, Sonnet 4.6은 속도와 지능의 균형형 모델, Haiku 4.5는 가장 빠른 모델입니다.

초보자용으로 바꾸면 다음과 같습니다.

Haiku

빠른 조수 — "이 파일 뭐 하는지 설명해줘", "TODO만 찾아줘"

Sonnet

기본 개발자 — "버그 고쳐줘", "테스트 추가해줘", "API 로직 수정해줘"

Opus

시니어 설계자 — "인증 구조를 리팩터링해줘", "복잡한 장애 원인을 분석해줘"

모델 가격도 다릅니다. Opus 4.8은 입력 100만 토큰당 $5, 출력 100만 토큰당 $25이고, Sonnet 4.6은 입력 $3·출력 $15, Haiku 4.5는 입력 $1·출력 $5입니다. 가격은 바뀔 수 있으므로 작성 시점 기준으로만 적고, 실제 교육에서는 공식 가격표 확인을 습관화해야 합니다.

03기본값을 그대로 써도 되는 경우

초보자는 처음부터 모델을 자주 바꿀 필요가 없습니다. Claude Code에는 default 선택지가 있고, 이 값은 계정 유형이나 환경에 맞는 권장 기본 모델입니다.

공식 문서에 따르면:

Max, Team Premium, Enterprise pay-as-you-go, Anthropic API는 기본값이 Opus 4.8
Pro, Team Standard, Enterprise subscription seats는 Sonnet 4.6
Bedrock·Vertex·Foundry는 Sonnet 4.5가 기본값

초보자에게는 이 원칙이 가장 안전합니다.

처음에는 default를 쓴다. 느리거나 비싸면 Sonnet 또는 Haiku로 낮춘다. 어려운 문제에서 막히면 Opus로 올린다.

Claude에게는 이렇게 물어보면 됩니다.

현재 작업이 어떤 모델에 적합한지 판단해줘.
빠른 모델, 균형 모델, 고성능 모델 중 무엇을 쓰면 좋을지
이유와 함께 설명해줘.

04현재 모델 확인하고 바꾸기

Claude Code에서 모델을 확인하거나 바꾸려면 세션 안에서 다음 명령을 씁니다.

/model

특정 모델로 바로 바꾸고 싶다면 이렇게 입력합니다.

/model sonnet
/model opus
/model haiku

세션 시작 시에는 터미널에서 다음처럼 입력합니다.

claude --model sonnet

환경 변수로도 설정할 수 있습니다.

ANTHROPIC_MODEL=opus

다만 모델을 바꾸면 다음 응답에서 기존 대화 기록을 새 모델이 다시 읽게 됩니다. 긴 세션에서는 비용과 시간이 늘 수 있으므로, 모델 전환은 필요한 순간에만 하는 것이 좋습니다.

05언제 Haiku를 쓰면 좋은가

Haiku는 빠르고 비용 효율적인 모델입니다. 공식 모델 비교에서도 Haiku 4.5는 가장 빠른 모델로 분류됩니다.

Haiku가 적합한 상황:

이 파일의 역할만 요약해줘
이 폴더에서 설정 파일이 어디 있는지 찾아줘
README를 읽고 실행 방법만 정리해줘
이 에러 로그에서 핵심 키워드만 뽑아줘

하지만 Haiku에게 너무 복잡한 판단을 맡기면 결과 품질이 부족할 수 있습니다. 예를 들어 인증 구조 변경, 데이터베이스 마이그레이션, 대형 리팩터링 계획처럼 실수 비용이 큰 작업은 Haiku보다 Sonnet 또는 Opus가 낫습니다.

읽기, 요약, 짧은 탐색은 Haiku로 충분할 수 있다. 코드 수정과 설계 판단은 Sonnet 이상을 쓴다.

06언제 Sonnet을 쓰면 좋은가

Sonnet은 Claude Code에서 가장 많이 쓰기 좋은 균형형 선택지입니다. 공식 문서도 sonnet alias를 일상적인 코딩 작업용 최신 Sonnet 모델로 설명합니다.

Sonnet이 적합한 상황:

이 버그의 원인을 찾고 수정 계획을 세워줘
회원가입 폼에 입력 검증을 추가해줘
기존 테스트 스타일을 참고해서 테스트를 추가해줘
lint 오류를 분석하고 안전한 수정안을 제안해줘

대부분의 초보자는 Sonnet을 기본 개발 모델로 생각하면 됩니다.

일반 개발 작업 = Sonnet

Sonnet으로 충분하지 않은 신호:

같은 문제를 여러 번 수정해도 실패한다

더 깊은 원인 분석이 필요함

여러 모듈의 구조를 동시에 바꿔야 한다

설계 판단이 필요함

Claude가 계획을 자주 바꾼다

고성능 모델이 유리할 수 있음

보안·결제·권한 로직을 다룬다

실수 비용이 크므로 신중해야 함

이런 경우 Opus로 올리거나, plan mode와 함께 opusplan을 쓰는 것이 좋습니다.

07언제 Opus를 써야 하는가

Opus는 복잡한 추론과 장기 작업에 적합합니다. 공식 모델 개요는 Opus 4.8을 복잡한 추론, long-horizon agentic coding, 높은 자율성이 필요한 작업에 가장 강한 모델로 설명합니다.

Opus가 필요한 상황:

이 코드베이스의 인증 구조를 분석하고 리팩터링 계획을 세워줘
장애 원인을 로그, 코드, 설정을 함께 보고 추론해줘
결제 로직 변경이 보안상 안전한지 검토해줘
여러 접근법을 비교하고 가장 안전한 설계를 제안해줘

Opus를 쓰기 좋은 대표 상황:

대형 리팩터링

여러 파일과 의존성을 동시에 봐야 함

아키텍처 설계

단순 코드 수정이 아니라 구조 판단이 필요함

어려운 버그

증상과 원인이 멀리 떨어져 있을 수 있음

보안·권한·결제

실수 비용이 크므로 추론 품질이 중요함

다만 Opus는 비용이 더 클 수 있습니다. 특히 최신 Opus와 Sonnet 모델에서는 effort 조절이 모델을 바꾸는 것보다 좋은 조절 수단이 될 때가 있습니다.

08opusplan으로 계획과 실행 나누기

opusplan은 초보자에게 매우 유용한 선택지입니다. plan mode에서는 Opus를 사용해 복잡한 추론과 아키텍처 결정을 처리하고, 실행 단계에서는 Sonnet으로 전환해 구현을 진행합니다.

즉, 이런 감각입니다.

계획은 똑똑하게, 실행은 효율적으로.

사용 방법:

claude --model opusplan

또는 세션 중에:

/model opusplan

091M context는 언제 필요한가

sonnet[1m], opus[1m]처럼 [1m]이 붙은 모델은 긴 세션이나 큰 코드베이스를 다룰 때 쓰는 선택지입니다. Opus 4.6 이상과 Sonnet 4.6은 1백만 토큰 context window를 지원하며, 사용 가능 여부는 모델과 플랜에 따라 달라집니다.

초보자는 이렇게 판단하면 됩니다.

파일 1~3개 수정

거의 필요 없음

작은 버그 수정

거의 필요 없음

프로젝트 전체 구조 분석

도움이 될 수 있음

긴 세션을 계속 이어감

도움이 될 수 있음

대형 리팩터링

필요할 수 있음

1M context가 있다고 해서 무조건 좋은 것은 아닙니다. 더 많은 내용을 넣으면 모델이 읽어야 할 양도 늘고, 비용과 시간이 커질 수 있습니다. 먼저 필요한 파일만 읽게 하고, 그래도 부족할 때 1M context를 고려하는 것이 안전합니다.

10effort는 모델 선택의 보조 장치다

최신 Claude Code에서는 모델뿐 아니라 effort도 중요합니다. effort level은 adaptive reasoning을 제어하며, 낮은 effort는 단순 작업에서 빠르고 저렴하고, 높은 effort는 복잡한 문제에서 더 깊은 추론을 제공합니다.

Opus 4.8과 Opus 4.7은 low, medium, high, xhigh, max를 지원하고, Opus 4.6과 Sonnet 4.6은 low, medium, high, max를 지원합니다.

초보자 기준:

low

짧은 요약, 간단한 탐색

medium

비용을 줄이고 싶은 일반 작업

high

기본 코딩 작업

xhigh

복잡한 설계, 어려운 버그

max

매우 어려운 문제를 한 번 깊게 볼 때

설정은 다음처럼 합니다.

/effort
/effort high

시작할 때 지정하려면:

claude --model opus --effort xhigh

중요한 점은 이것입니다.

모델을 바꾸기 전에 effort를 조절해보는 것도 방법이다.

11ultrathink는 남용하지 않기

Claude Code 문서에는 한 번의 턴에서 더 깊은 추론을 요청하는 방법으로 ultrathink 키워드가 나옵니다. 프롬프트 안에 ultrathink를 포함하면 해당 턴에서 더 깊은 reasoning을 요청하지만, API로 전달되는 effort level 자체가 바뀌는 것은 아닙니다.

사용 예시:

ultrathink.
이 버그의 원인을 로그와 코드 흐름 기준으로 깊게 분석해줘.
수정은 아직 하지 말고 가능한 원인 후보를 우선순위별로 정리해줘.

하지만 매번 ultrathink를 붙이면 비용과 시간이 늘고, 단순 작업에도 과한 추론을 하게 됩니다. 기억할 원칙은 다음과 같습니다.

단순 작업에는 쓰지 않는다. 복잡한 원인 분석이나 중요한 설계 판단에만 쓴다.

12모델명은 외우지 말고 확인한다

모델명은 자주 바뀝니다. 공식 문서도 alias는 provider별 권장 버전을 가리키며 시간이 지나면서 업데이트될 수 있고, 특정 버전에 고정하려면 전체 모델 이름을 쓰거나 환경 변수를 설정하라고 설명합니다.

예를 들어 Anthropic API에서 현재 opus는 Opus 4.8, sonnet은 Sonnet 4.6으로 해석되지만, Bedrock·Vertex·Foundry에서는 alias가 다른 버전으로 해석될 수 있습니다.

따라서 교육 가이드에는 이렇게 적는 것이 안전합니다.

이 가이드의 모델명은 작성 시점 기준이다.
실제 사용 전에는 /model 화면과 공식 문서를 확인한다.

팀 문서에는 특정 모델명을 박아두기보다 다음처럼 쓰는 편이 좋습니다.

일반 개발 작업

sonnet

복잡한 설계/리팩터링

opus 또는 opusplan

간단한 탐색/요약

haiku

긴 세션/대형 코드베이스

opus[1m] 또는 sonnet[1m]

이렇게 쓰면 모델 버전이 바뀌어도 가이드가 덜 낡습니다.

13초보자용 모델 선택 규칙

초보자는 아래 규칙만 따라도 충분합니다.

기본값으로 시작한다.
일반 개발은 Sonnet을 쓴다.
단순 탐색과 요약은 Haiku를 고려한다.
복잡한 설계와 어려운 버그는 Opus를 쓴다.
큰 작업은 opusplan으로 계획과 실행을 나눈다.
모델명이 바뀔 수 있으므로 /model에서 항상 확인한다.
비용이 걱정되면 다음 단원에서 /usage로 사용량을 확인한다.

실전 프롬프트 예시:

이 작업에 적합한 Claude Code 모델을 추천해줘.

작업 내용:
- 여러 파일을 수정해야 할 수 있음
- 기존 구조를 먼저 이해해야 함
- 테스트도 추가해야 함

haiku, sonnet, opus, opusplan 중 무엇이 적합한지
비용, 속도, 정확성 관점에서 비교해줘.
아직 모델은 바꾸지 말고 추천만 해줘.

14실전 예시 ①②

예시 1. 간단한 파일 요약

/model haiku

src/auth/session.ts 파일이 어떤 역할을 하는지
초보자도 이해할 수 있게 요약해줘.
수정은 하지 마.

예시 2. 일반 버그 수정

/model sonnet

로그인 실패 시 에러 메시지가 표시되지 않는 문제를 조사해줘.
먼저 원인을 설명하고, 수정 계획을 제안한 뒤,
내가 승인하면 수정해줘.

15실전 예시 ③④

예시 3. 대형 리팩터링 계획

/model opusplan

Plan mode로 인증 모듈 리팩터링 계획을 세워줘.
관련 파일을 읽고, 영향 범위와 위험 요소를 정리해줘.
아직 파일은 수정하지 마.

예시 4. 어려운 장애 분석

/model opus
/effort xhigh

ultrathink.
최근 배포 이후 결제 완료 콜백이 간헐적으로 실패해.
로그, 라우터, 결제 서비스 코드를 함께 보고
가능한 원인을 우선순위별로 분석해줘.
수정은 아직 하지 마.

섹션 13 · 마무리

13단원 핵심 정리

Claude Code의 모델 선택은 "가장 좋은 모델 하나를 고르는 문제"가 아닙니다. 작업 난이도에 맞게 모델을 고르는 문제입니다.

모델 선택 기준

haiku는 빠른 탐색과 요약에 적합합니다.

sonnet은 일반적인 코딩 작업에 적합합니다.

opus는 복잡한 추론, 설계, 어려운 버그에 적합합니다.

opusplan은 계획은 고성능 모델로 세우고 실행은 효율적으로 진행하는 절충안입니다.

/model로 현재 모델을 확인하고 바꿀 수 있습니다.

/effort는 모델 안에서 추론 강도를 조절하는 보조 장치입니다.

모델명과 기본값은 바뀔 수 있으므로 항상 공식 문서와 /model 화면을 확인합니다.

다음 14단원에서는 비용을 확인하고 낭비를 줄이는 법을 다룹니다.

14. 비용을 확인하고 낭비를 줄이는 법

01비용은 무엇 때문에 발생하는가

Claude Code 비용은 기본적으로 토큰 사용량에 따라 발생합니다. 토큰은 Claude가 읽는 입력, 생성하는 출력, 도구 사용 과정에서 주고받는 정보, 긴 대화 컨텍스트 등을 계산하는 단위입니다.

초보자는 이렇게 이해하면 됩니다.

큰 파일을 많이 읽음

Claude가 읽어야 할 양이 많아짐

긴 세션을 계속 이어감

이전 대화까지 계속 컨텍스트에 남음

고성능 모델 사용

토큰당 가격이 더 높을 수 있음

긴 답변을 반복 생성

출력 토큰이 늘어남

테스트·로그 출력이 길어짐

터미널 결과까지 컨텍스트에 들어감

MCP, subagent, agent team 과다 사용

별도 도구와 별도 컨텍스트가 늘어남

비용은 "Claude에게 얼마나 많이 읽히고, 얼마나 많이 생각하게 하고, 얼마나 많이 출력하게 했는가"에 따라 커진다.

02현재 사용량 확인하기: /usage

Claude Code 세션 안에서 비용과 사용량을 확인하려면 다음 명령을 사용합니다.

/usage

초보자가 볼 항목은 세 가지입니다.

Total cost

현재 세션의 예상 비용

Total duration

API 호출 또는 실제 작업 시간

Total code changes

실제 코드 변경량

주의할 점은 /usage의 달러 수치가 로컬에서 계산한 추정치라는 것입니다. 실제 청구 확인은 Claude Console의 사용량 페이지를 기준으로 봐야 합니다.

03/usage 결과 읽기

예시 화면은 이런 식으로 이해하면 됩니다.

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

초보자용 확인 프롬프트는 다음과 같습니다.

현재 /usage 결과를 보고 비용이 커진 원인을
초보자도 이해할 수 있게 설명해줘.
모델, 컨텍스트, 도구 사용, 긴 출력 중
무엇이 영향을 줬는지 나눠서 봐줘.

04/cost가 아니라 /usage로 설명하기

기존 글이나 예전 가이드에서는 비용 확인을 /cost라고 부르는 경우가 있을 수 있습니다. 하지만 최신 Claude Code 비용 관리 문서에서 비용 추적 항목은 /usage 명령을 기준으로 설명되어 있습니다.

따라서 이 가이드에서는 다음처럼 정리합니다.

최신 Claude Code에서는 비용과 사용량 확인을
/usage 기준으로 설명한다.
예전 자료에서 /cost라고 되어 있으면
/usage를 먼저 확인한다.

교육용 문서에는 이렇게 적으면 됩니다.

사용량 확인: /usage
요금제 크레딧 한도 확인 또는 설정: /usage-credits

05상황 1. 프로젝트 전체를 무작정 읽게 하는 경우

초보자가 자주 하는 요청은 다음과 같습니다.

이 프로젝트 전체를 분석해줘.

이 요청은 편해 보이지만, Claude가 많은 파일을 읽게 만들어 비용이 커질 수 있습니다.

더 좋은 요청은 다음과 같습니다.

로그인 기능과 관련된 파일만 먼저 찾아줘.
파일을 수정하지 말고, 관련 가능성이 높은
파일 5개만 이유와 함께 알려줘.

또는 이렇게 제한합니다.

전체 프로젝트를 읽지 말고,
package.json, README, src/auth 폴더만
먼저 확인해줘.

06상황 2. 긴 세션을 계속 이어가는 경우

Claude Code는 대화가 길어질수록 이전 대화, 파일 내용, 도구 결과가 컨텍스트에 쌓입니다. 관련 없는 작업으로 전환할 때는 /clear를 사용해 새로 시작하는 것이 좋습니다.

작업이 바뀔 때는 이렇게 합니다.

/clear

다만 세션을 나중에 찾고 싶다면 먼저 이름을 붙입니다.

/rename auth-bugfix

초보자 규칙은 간단합니다.

같은 작업은 같은 세션에서 이어가고, 다른 작업으로 넘어가면 새 세션을 시작한다.

07상황 3. 로그와 테스트 출력이 너무 긴 경우

테스트 실패 로그 전체를 그대로 Claude에게 던지면 비용이 커집니다.

나쁜 예시는 다음과 같습니다.

이 테스트 로그 전체를 분석해줘.

더 좋은 요청은 다음과 같습니다.

이 로그에서 첫 번째 실패 원인만 분석해줘.
중복 stack trace는 무시하고,
실제 에러 메시지와 관련 파일만 봐줘.

초보자 단계에서는 먼저 이렇게 요청하는 습관을 들이면 됩니다.

로그 전체를 다 읽지 말고,
ERROR, FAIL, Exception이 포함된 줄 주변만
확인해줘.

08상황 4. 고성능 모델을 모든 작업에 쓰는 경우

Opus 같은 고성능 모델은 복잡한 설계와 어려운 버그에는 유리하지만, 모든 작업에 항상 필요하지는 않습니다.

초보자용 모델 비용 감각은 다음과 같습니다.

파일 요약, 짧은 탐색

Haiku

일반 버그 수정, 테스트 작성

Sonnet

복잡한 설계, 대형 리팩터링

Opus 또는 opusplan

09모델 선택으로 비용 줄이기

13단원의 모델 선택을 비용 관점에서 다시 정리하면 다음과 같습니다.

간단한 작업 = haiku
일반 개발 = sonnet
어려운 판단 = opus
계획은 깊게, 실행은 효율적으로 = opusplan

세션 중 모델을 바꾸려면 다음 명령을 사용합니다.

/model sonnet

/model haiku

비용을 아끼는 실전 프롬프트는 다음과 같습니다.

이 작업을 비용 효율적으로 진행하고 싶어.
먼저 haiku나 sonnet으로 충분한지 판단해줘.
Opus가 꼭 필요한 경우에만 이유를 설명해줘.

10effort를 낮춰 비용 줄이기

모델을 바꾸는 것 외에 /effort도 비용 관리에 중요합니다. medium은 비용 민감 작업에서 토큰 사용량을 줄이는 데 적합하고, high는 대부분의 코딩 작업에 균형적이며, xhigh와 max는 더 깊은 추론 대신 더 많은 토큰 사용을 감수합니다.

설정 명령은 다음과 같습니다.

/effort medium

/effort high

비용을 줄이고 싶을 때는 이렇게 요청합니다.

이 작업은 비용을 아끼고 싶어.
가능하면 medium effort로 진행하고,
정확도가 부족해지는 지점이 있으면
그때 high로 올리자.

11컨텍스트를 줄이는 습관

비용을 줄이는 가장 강력한 방법은 Claude가 읽는 양을 줄이는 것입니다.

나쁜 요청

전체 코드베이스를 보고 문제를 찾아줘.

좋은 요청

로그인 실패 문제만 조사해줘.
먼저 관련 파일 후보를 찾고,
상위 3개 파일만 읽은 뒤 원인을 추정해줘.

더 좋은 요청

src/auth/login.ts와 src/auth/session.ts만
먼저 읽어줘.
그 안에서 원인을 못 찾으면 다음에 읽을
파일을 제안해줘.

12/compact와 /clear 사용하기

Claude Code는 컨텍스트 한도에 가까워지면 자동 compaction으로 대화 기록을 요약해 비용을 최적화합니다.

수동으로 요약하려면 다음 명령을 씁니다.

/compact

요약할 때 보존할 내용을 지정할 수도 있습니다.

/compact 지금까지의 결정사항, 수정한 파일,
테스트 결과만 보존해줘.

차이는 이렇게 이해하면 됩니다.

/compact

같은 작업을 계속하지만 대화가 길어진 경우

/clear

완전히 다른 작업으로 넘어가는 경우

/resume

이전 세션으로 돌아가야 하는 경우

13MCP와 플러그인 비용 주의하기

MCP는 강력하지만, 연결이 많을수록 Claude가 고려해야 할 도구가 늘어날 수 있습니다. 적극적으로 사용하지 않는 MCP 서버는 /mcp에서 비활성화하는 것이 좋습니다.

초보자 규칙은 다음과 같습니다.

처음부터 MCP를 많이 연결하지 않는다.
필요한 도구만 연결하고,
안 쓰는 서버는 꺼둔다.

확인 명령은 다음과 같습니다.

/context

/mcp

14CLAUDE.md를 너무 길게 쓰지 않기

CLAUDE.md는 매 세션마다 프로젝트 규칙을 Claude에게 알려주는 좋은 도구지만, 너무 길면 매번 컨텍스트를 차지합니다. CLAUDE.md가 세션 시작 시 컨텍스트에 로드되므로, 너무 많은 지침을 넣으면 관련 없는 작업에서도 토큰을 소비하게 됩니다.

초보자용 CLAUDE.md 원칙은 다음과 같습니다.

항상 필요한 규칙만 CLAUDE.md에 넣는다.
특정 작업용 긴 지침은 나중에 skills로
분리한다.

좋은 CLAUDE.md에는 이 정도만 넣으면 됩니다.

14CLAUDE.md 좋은 예시

# Project Rules
## Commands
- Test: npm test
- Lint: npm run lint
- Build: npm run build

## Coding Rules
- TypeScript strict mode를 유지한다.
- 기존 코드 스타일을 따른다.
- 수정 전 관련 테스트를 확인한다.

## Safety
- .env 파일은 읽거나 수정하지 않는다.
- 커밋 전 git diff를 요약한다.

15Status line으로 비용과 컨텍스트 계속 보기

비용을 자주 확인하고 싶다면 status line을 설정할 수 있습니다. Claude Code의 status line은 화면 하단에 표시되는 커스텀 바이며, 컨텍스트 사용량, 비용, git 상태 등을 계속 보여줄 수 있습니다.

설정은 다음처럼 시작합니다.

/statusline show model name, context percentage,
cost, and git branch

초보자에게 추천하는 표시 항목은 네 가지입니다.

model

비싼 모델을 계속 쓰고 있는지 확인

context percentage

세션이 너무 커졌는지 확인

cost

현재 비용 감각 확인

git branch

엉뚱한 브랜치에서 작업 방지

16팀 비용 관리

개인 사용자는 /usage와 모델 선택만으로도 충분한 경우가 많지만, 팀에서는 지출 한도와 사용량 보고가 필요합니다.

팀 문서에는 다음 규칙을 넣는 것이 좋습니다.

일반 개발은 sonnet을 기본으로 한다.

opus는 설계, 보안, 장애 분석에만 사용한다.

긴 작업은 plan mode로 먼저 범위를 좁힌다.

MCP 서버는 필요한 팀만 활성화한다.

월별 사용량은 Console 또는 /usage 기준으로 점검한다.

17백그라운드 토큰 사용량 이해하기

Claude Code는 사용자가 아무것도 입력하지 않아도 일부 백그라운드 기능에 토큰을 사용할 수 있습니다. 일반적으로 세션당 $0.04 미만의 적은 양이지만, 아래 습관은 도움이 됩니다.

작업이 끝났으면 세션을 정리한다.
오래된 세션을 불필요하게 계속 붙잡지
않는다.
다른 작업으로 넘어갈 때 /clear를 사용한다.

18비용 절약 실전 루틴

Claude Code를 실행한 뒤 큰 작업을 시작하기 전에는 이렇게 요청합니다.

이번 작업을 비용 효율적으로 진행해줘.
규칙:
1. 전체 프로젝트를 무작정 읽지 마.
2. 먼저 관련 파일 후보만 찾아줘.
3. 수정 전에 계획을 제안해줘.
4. 긴 로그는 핵심 에러만 읽어줘.
5. 일반 작업은 sonnet 기준으로 진행해줘.
6. Opus가 필요하면 먼저 이유를 설명해줘.

작업 중간에는 사용량을 확인합니다.

/usage

19비용 절약 중간 점검과 정리

작업 중간에는 이렇게 점검합니다.

현재 세션에서 비용이 커질 만한 요인을
찾아줘.
긴 컨텍스트, 너무 많은 파일 읽기,
모델 선택, 도구 사용 중 무엇이 문제인지
알려줘.

작업이 길어졌다면 압축합니다.

/compact 지금까지의 목표, 결정사항,
수정 파일, 테스트 결과만 보존해줘.

작업이 바뀌면 새로 시작합니다.

/clear

20비용을 줄이는 프롬프트 예시

파일 탐색 비용 줄이기

전체 프로젝트를 읽지 말고,
로그인 기능과 관련된 파일 후보만 먼저
찾아줘.
후보 파일 5개와 이유만 알려줘.

diff 검토 비용 줄이기

git diff 전체를 자세히 설명하지 말고,
동작이 바뀐 부분과 위험한 변경만
요약해줘.
포맷팅 변경은 따로 묶어줘.

21비용 절약 프롬프트 예시 계속

로그 분석 비용 줄이기

이 로그에서 첫 번째 실패 원인만 봐줘.
중복 stack trace는 생략하고,
실제 에러 메시지와 관련 파일 경로만
정리해줘.

모델 비용 줄이기

이 작업은 비용을 아끼고 싶어.
haiku나 sonnet으로 충분하면 그 모델을
추천하고,
opus가 꼭 필요한 경우에만 이유를
설명해줘.

22긴 세션 정리하기

지금까지의 대화에서 앞으로 필요한
내용만 요약해줘.
목표, 수정한 파일, 남은 작업,
주의사항만 남겨줘.
그다음 /compact에 넣을 요약문을
만들어줘.

섹션 14 · 마무리

비용을 줄이기 위한 핵심 정리

Claude Code 비용은 주로 토큰 사용량에 따라 결정됩니다. 세션 사용량 확인은 /usage를 사용하며, 비용 수치는 로컬 추정치이므로 실제 청구 확인은 Claude Console을 기준으로 봐야 합니다.

비용은 큰 파일 읽기, 긴 세션, 긴 로그, 고성능 모델, 과도한 MCP와 subagent 사용에서 커지기 쉽습니다. 일반 개발은 Sonnet, 간단한 탐색은 Haiku, 복잡한 설계와 어려운 버그는 Opus를 사용하세요.

작업이 길어지면 /compact, 작업이 바뀌면 /clear를 사용하고, 구체적인 프롬프트와 plan mode로 잘못된 탐색을 줄입니다.

다음 단원

15단원. 컨텍스트를 관리하고 세션을 오래 쓰는 법

15. 컨텍스트를 관리하고 세션을 오래 쓰는 법

01컨텍스트란 무엇인가

컨텍스트는 Claude가 현재 답변을 만들 때 참고할 수 있는 작업 기억 공간입니다. 여기에는 사용자의 요청, Claude의 답변, 읽은 파일 내용, 도구 실행 결과, 에러 로그, 이전 결정사항 등이 들어갑니다.

초보자는 이렇게 이해하면 됩니다.

컨텍스트 = Claude가 지금 기억하고 있는 작업판

작업판에 필요한 정보가 잘 정리되어 있으면 Claude는 좋은 답변을 합니다. 반대로 오래된 로그, 끝난 작업, 관련 없는 파일 내용이 계속 쌓이면 Claude가 헷갈리기 시작합니다.

02컨텍스트가 쌓이면 생기는 문제

Claude Code 세션을 오래 이어가면 다음 문제가 생길 수 있습니다.

이전에 결정한 내용을 잊은 것처럼 답함

중요한 정보가 묻혔을 수 있음

이미 끝난 작업을 다시 언급함

오래된 컨텍스트가 남아 있음

답변이 느려짐

읽어야 할 컨텍스트가 커졌을 수 있음

비용이 증가함

매 요청마다 처리할 토큰이 많아짐

엉뚱한 파일을 다시 읽음

작업 초점이 흐려졌을 수 있음

핵심은 이것입니다.

세션을 오래 쓰는 능력은 오래 기억시키는 능력이 아니라, 필요한 것만 남기는 능력이다.

03현재 컨텍스트 상태 확인하기

컨텍스트 사용량을 보려면 다음 명령을 사용합니다.

/context

그다음 Claude에게 이렇게 물어봅니다.

현재 컨텍스트에서 공간을 많이 차지하는 요소를 설명해줘.
읽은 파일, 긴 로그, MCP, CLAUDE.md, 대화 기록 중 무엇이 큰지 나눠서 알려줘.

컨텍스트가 너무 커졌다면 바로 수정하지 말고 먼저 진단합니다.

지금 세션을 계속 이어가도 되는지 판단해줘.
계속 이어가야 하는지, /compact 해야 하는지, /clear로 새로 시작해야 하는지 추천해줘.

04/compact로 필요한 내용만 압축하기

/compact는 긴 대화를 요약해서 세션을 계속 이어가기 위한 명령입니다. 작업은 이어가되, 불필요한 세부 대화와 오래된 출력은 줄이고 핵심만 남기고 싶을 때 사용합니다.

/compact

초보자에게 추천하는 방식은 그냥 /compact만 쓰는 것이 아니라, 무엇을 남길지 명확히 적는 것입니다.

/compact 지금까지의 목표, 결정사항, 수정한 파일, 테스트 결과, 남은 작업만 보존해줘.

버그 수정 중이라면 이렇게 쓰고, 리팩터링 중이라면 다르게 쓸 수 있습니다. /compact는 같은 작업을 계속할 때 적합합니다.

05compact 사용 판단 기준

같은 버그를 계속 수정 중

사용

같은 기능 구현을 이어가는 중

사용

리팩터링이 길어졌지만 목표가 동일함

사용

완전히 다른 작업으로 넘어감

/clear가 더 적합

06/clear로 새 작업 시작하기

/clear는 현재 대화 컨텍스트를 비우고 새로 시작하는 명령입니다. 관련 없는 작업으로 전환할 때 /clear를 사용하세요. 오래된 컨텍스트는 이후 모든 메시지에서 토큰을 낭비할 수 있기 때문입니다.

/clear

초보자는 다음 상황에서 /clear를 쓰면 됩니다.

07clear 사용 상황

로그인 버그 수정 후 결제 기능으로 넘어감

작업 주제가 다름

프론트엔드 작업 후 백엔드 배포 문제로 넘어감

필요한 파일과 맥락이 다름

이전 대화가 너무 길고 헷갈림

새 컨텍스트가 더 안전함

Claude가 자꾸 이전 작업을 언급함

오래된 정보가 방해됨

작업 전환 전에는 세션 이름을 붙여두는 것이 좋습니다.

/rename auth-bugfix

그다음 새 작업으로 넘어갑니다.

08clear 사용 규칙

같은 작업이면 /compact, 다른 작업이면 /clear, 나중에 돌아올 작업이면 /rename 후 /clear

09세션을 이어가기 1 · 가장 최근 세션

작업을 하루 안에 끝내지 못할 수도 있습니다. Claude Code는 이전 대화를 이어갈 수 있습니다.

가장 최근 세션을 이어가려면 다음 명령을 쓰세요.

claude -c

이 명령은 현재 디렉터리에서 가장 최근 대화를 이어가는 방식입니다.

10세션을 이어가기 2 · 목록에서 고르기

세션 목록에서 골라 이어가고 싶다면 다음을 씁니다.

claude --resume

Claude Code 안에서 세션을 고르고 싶다면 다음을 씁니다.

/resume

초보자에게 추천하는 세션 관리 방식은 먼저 세션 이름을 붙이고, 나중에 이어갈 때 claude --resume 또는 가장 최근 세션이면 claude -c를 사용하는 것입니다.

11세션을 오래 쓰기 위한 작업 기록 습관

세션을 오래 쓰려면 Claude에게 "기억해줘"라고만 하지 말고, 중간중간 작업 상태를 구조화해야 합니다.

좋은 요청은 다음과 같습니다.

지금까지의 작업 상태를 정리해줘.
1. 목표
2. 확인한 파일
3. 수정한 파일
4. 아직 해결되지 않은 문제
5. 다음에 해야 할 작업
6. 주의해야 할 위험 요소

그다음 이 요약을 기준으로 compact합니다.

12긴 로그와 테스트 출력은 컨텍스트를 망친다

테스트 실패 로그, 빌드 로그, 서버 로그는 매우 길어질 수 있습니다. 긴 로그 전체를 붙여넣거나 Claude에게 계속 읽게 하면 컨텍스트가 빠르게 커집니다.

나쁜 요청은 다음과 같습니다.

이 로그 전체를 보고 문제를 찾아줘.

더 좋은 요청은 다음과 같습니다.

이 로그에서 첫 번째 실패 원인만 봐줘.
중복 stack trace는 무시하고, 실제 에러 메시지와 관련 파일 경로만 정리해줘.

또는 터미널에서 먼저 줄입니다.

13로그 처리 방식

Claude에게는 이렇게 요청합니다.

긴 로그 전체를 읽지 말고,
실패 원인과 관련된 줄만 기준으로 분석해줘.
추가 로그가 필요하면 어떤 부분이 필요한지 먼저 말해줘.

컨텍스트를 아끼는 핵심은 "많이 주기"가 아니라 "필요한 것만 주기"입니다.

14파일 읽기도 단계적으로 시키기

초보자는 Claude에게 자주 이렇게 요청합니다.

이 프로젝트 전체를 분석해줘.

이 요청은 컨텍스트를 크게 만들 수 있습니다. 더 안전한 방식은 단계적 탐색입니다.

전체 프로젝트를 읽지 말고,
먼저 로그인 기능과 관련된 파일 후보만 찾아줘.
상위 5개 파일과 이유만 알려줘.

그다음 필요한 파일만 읽힙니다.

15파일 탐색 이후 단계

src/auth/login.ts와 src/auth/session.ts만 먼저 읽어줘.
원인을 못 찾으면 다음에 읽을 파일을 제안해줘.

대형 코드베이스를 탐색할 때는 subagent를 쓰는 것도 좋은 방법입니다. 큰 코드베이스 탐색은 메인 컨텍스트를 파일 읽기로 채울 수 있으므로, subagent에 조사를 위임하면 subagent가 별도 컨텍스트에서 파일을 읽고 요약만 돌려줍니다.

subagent를 사용해서 인증 시스템의 토큰 갱신 흐름을 조사해줘.
메인 대화에는 핵심 파일 목록, 흐름 요약, 위험 요소만 반환해줘.

161M context는 만능이 아니다

일부 모델과 플랜에서는 1M context window를 사용할 수 있습니다. Opus 4.6 이상과 Sonnet 4.6은 긴 세션과 큰 코드베이스를 위한 1백만 토큰 context window를 지원합니다.

/model opus[1m]

/model sonnet[1m]

하지만 1M context가 있다고 해서 아무 파일이나 전부 읽히면 안 됩니다. 더 큰 컨텍스트가 항상 더 좋은 것은 아니며, 토큰 수가 증가하면 정확도와 회상 성능이 떨어질 수 있습니다.

1M context는 큰 작업을 위한 안전망이지, 무분별하게 파일을 읽기 위한 허가증이 아니다.

171M context 필요 판단

작은 버그 수정

낮음

파일 1~3개 수정

낮음

프로젝트 구조 전체 분석

중간

대형 리팩터링

높음

긴 세션을 며칠 이어감

높음

18status line으로 컨텍스트를 계속 보기

컨텍스트 사용량을 자주 확인하고 싶다면 status line을 설정할 수 있습니다. Claude Code의 status line은 화면 하단에 표시되는 커스텀 바이며, context window usage, 비용, git 상태 등을 표시할 수 있습니다.

간단히 설정하려면 다음처럼 요청합니다.

/statusline show model name, context percentage, cost, and git branch

초보자에게 추천하는 status line 항목은 다음입니다.

19status line 권장 항목

모델명

비싼 모델을 계속 쓰고 있는지 확인

컨텍스트 비율

세션이 너무 커졌는지 확인

비용

사용량 감각 유지

Git 브랜치

엉뚱한 브랜치에서 작업 방지

20언제 새 세션을 시작해야 하는가

세션을 오래 이어가는 것이 항상 좋은 것은 아닙니다. 아래 상황에서는 새 세션이 더 안전합니다.

작업 주제가 완전히 바뀜

/clear

Claude가 이전 작업을 계속 끌고 옴

/clear

긴 로그와 파일 읽기가 많이 쌓임

/compact 후 계속 또는 새 세션

계획이 크게 바뀜

새 세션 또는 plan mode

같은 작업을 다음날 이어감

/resume

여러 기능을 동시에 작업해야 함

별도 세션 또는 worktree

초보자 기준으로는 하나만 기억하면 됩니다.

한 세션에는 하나의 목표만 둔다.

21컨텍스트 관리 실전 루틴 1

작업 시작 시:

이번 세션의 목표는 로그인 실패 원인 분석이야.
전체 프로젝트를 읽지 말고 관련 파일 후보만 먼저 찾아줘.

22컨텍스트 관리 실전 루틴 2

작업 중간 점검:

지금까지 확인한 사실, 수정한 파일, 남은 의문을 정리해줘.
불필요하게 컨텍스트를 차지하는 내용이 있는지도 알려줘.

세션이 길어졌을 때:

/compact 목표, 결정사항, 수정 파일, 테스트 결과, 남은 작업만 보존해줘.

23컨텍스트 관리 실전 루틴 3

다른 작업으로 넘어갈 때:

/rename auth-login-debug

/clear

다음날 이어갈 때:

claude --resume

24초보자용 좋은 프롬프트 모음 1

컨텍스트 진단

현재 세션의 컨텍스트가 너무 커졌는지 판단해줘.
계속 진행, /compact, /clear 중 무엇이 적절한지 이유와 함께 추천해줘.

compact 전 정리

/compact 전에 보존해야 할 내용을 정리해줘.
목표, 결정사항, 수정 파일, 테스트 결과, 남은 작업, 주의사항만 남겨줘.

25초보자용 좋은 프롬프트 모음 2

compact 실행

/compact 방금 정리한 핵심 내용만 보존해줘.
특히 수정한 파일, 실패한 테스트, 다음 단계는 반드시 남겨줘.

새 세션 시작 전 정리

이 세션을 종료하기 전에 나중에 이어갈 수 있도록 작업 요약을 만들어줘.
다음 세션 첫 프롬프트로 그대로 붙여넣을 수 있게 작성해줘.

26초보자용 좋은 프롬프트 모음 3

세션 재개 후

이전 세션 요약을 기준으로 현재 상태를 다시 파악해줘.
먼저 git status를 확인하고, 남은 작업을 순서대로 제안해줘.

섹션 15 · 마무리

15단원 핵심 정리

컨텍스트는 Claude가 현재 참고하는 작업 기억입니다. 세션이 길어질수록 대화, 파일 내용, 로그, 도구 결과가 쌓입니다. 컨텍스트가 커지면 비용이 늘고, 답변 품질이 떨어질 수 있습니다. 같은 작업을 계속할 때는 /compact로 핵심만 남기고, 다른 작업으로 넘어갈 때는 /clear로 새로 시작합니다. 나중에 돌아올 작업은 /rename으로 이름을 붙인 뒤 정리합니다. 이전 작업은 claude -c, claude --resume, /resume으로 이어갈 수 있습니다. 큰 코드베이스 탐색은 필요한 파일만 단계적으로 읽히거나 subagent에 위임합니다. 1M context는 큰 작업에 도움이 되지만, 불필요한 정보를 많이 넣어도 된다는 뜻은 아닙니다. status line을 설정하면 컨텍스트 비율, 비용, 모델, Git 브랜치를 계속 확인할 수 있습니다.

다음 단원

16단원. 확장 추론과 effort를 언제 써야 하는가

16. Ultra Think 300% 활용하기

01Ultra Think란 무엇인가

Ultra Think는 Claude Code에게 이번 요청만 더 깊게 분석해 달라고 지시하는 실전 프롬프트 패턴입니다.

기본 사용법은 간단합니다.

ultrathink.

이 문제를 깊게 분석해줘.
수정은 아직 하지 말고, 가능한 원인과 확인 순서를 먼저 정리해줘.

Ultra Think를 쉽게 말하면 다음과 같습니다.

Ultra Think = 중요한 한 번의 판단을 깊게 보는 모드

02Ultra Think의 3가지 중요한 점

Ultra Think는 세 가지 특성을 정확히 이해해야 합니다.

실제 키워드

ultrathink

적용 범위

해당 프롬프트 한 번

바뀌지 않는 것

세션 전체 effort 설정

즉, ultrathink는 /effort xhigh처럼 세션 설정을 바꾸는 명령이 아닙니다. 특정 질문 하나를 더 깊게 보게 하는 요청입니다.

03Ultra Think를 써야 하는 상황

Ultra Think는 단순 작업이 아니라 실수 비용이 큰 작업에 써야 합니다.

원인이 불명확한 버그

증상과 실제 원인이 다른 파일에 있을 수 있음

여러 파일이 얽힌 리팩터링

숨은 의존성과 부작용을 먼저 봐야 함

인증·권한 로직

권한 우회 가능성을 조심해야 함

결제 로직

실패 시 금전·정산 문제가 생길 수 있음

보안 관련 변경

민감정보 노출과 접근 제어를 검토해야 함

장애 원인 분석

로그, 설정, 최근 변경사항을 함께 봐야 함

초보자는 이렇게 기억하면 됩니다.

단순히 "코드 수정"이 아니라 "판단이 중요한 작업"에 Ultra Think를 쓴다.

04Ultra Think를 쓰면 안 되는 상황

Ultra Think를 매번 붙이면 좋을 것 같지만, 그렇지 않습니다. 공식 문서에서도 effort와 reasoning은 토큰 사용량, 속도, 능력 사이의 trade-off가 있다고 설명합니다.

Ultra Think를 쓰지 않아도 되는 작업은 다음과 같습니다.

README 요약

"핵심만 5줄로 요약해줘"

파일 위치 찾기

"관련 파일 후보 5개만 찾아줘"

간단한 diff 설명

"동작 변경만 요약해줘"

짧은 코드 설명

"이 함수 역할만 설명해줘"

명확한 오타 수정

"이 오타만 수정해줘"

Ultra Think는 매번 붙이는 주문이 아닙니다. 중요한 순간에 쓰는 고성능 도구입니다.

05Ultra Think 기본 공식

Ultra Think를 잘 쓰려면 ultrathink만 던지면 안 됩니다. 상황, 목표, 제약, 출력 형식을 같이 줘야 합니다.

기본 공식은 다음과 같습니다.

ultrathink.

상황:
- 

목표:
- 

제약:
- 파일 수정은 아직 하지 마.
- 명령 실행도 내가 승인하기 전까지 하지 마.
- 가능한 원인을 우선순위별로 정리해줘.

먼저 해줘:
1. 문제를 어떻게 이해했는지 요약해줘.
2. 가능한 원인 후보를 나눠줘.
3. 확인해야 할 파일을 우선순위로 정리해줘.
4. 위험한 수정 방향을 경고해줘.
5. 안전한 다음 단계를 제안해줘.

이 공식의 핵심은 마지막 부분입니다. Ultra Think는 깊게 생각시키는 도구이지, 바로 실행시키는 도구가 아닙니다. 분석 → 계획 → 승인 → 실행 흐름으로 써야 합니다.

06버그 분석용 Ultra Think

원인이 잘 안 보이는 버그에는 Ultra Think가 특히 유용합니다.

ultrathink.

이 버그의 원인을 깊게 분석해줘.

증상:
- 로그인은 성공했다고 나오지만 세션이 유지되지 않음
- 새로고침하면 다시 로그인 페이지로 이동함

최근 변경사항:
- auth middleware 수정
- cookie 옵션 변경
- 배포 환경의 HTTPS 설정 변경

제약:
- 아직 파일은 수정하지 마.
- 먼저 가능한 원인을 우선순위별로 정리해줘.
- 각 원인을 확인할 방법도 함께 알려줘.
- 가장 먼저 읽어야 할 파일 3개만 제안해줘.

07버그 분석 시 핵심 원칙

버그 분석에서 Ultra Think를 쓸 때의 핵심은 바로 고치지 않게 하는 것입니다.

나쁜 요청:

ultrathink. 이 버그 고쳐줘.

좋은 요청:

ultrathink.

이 버그의 원인을 먼저 분석해줘.
수정은 하지 말고, 가능한 원인과 확인 순서를 먼저 제안해줘.

좋은 출력 형식까지 지정하면 더 안정적입니다.

출력 형식:
1. 가장 가능성 높은 원인
2. 확인해야 할 근거
3. 읽어야 할 파일
4. 실행해볼 명령
5. 수정 전 주의사항

08리팩터링용 Ultra Think

리팩터링은 "코드 모양만 바꾸는 작업"처럼 보이지만, 실제로는 숨은 의존성을 건드릴 수 있습니다. 특히 인증, 상태 관리, DB 접근, API 레이어를 리팩터링할 때는 Ultra Think로 먼저 계획을 세우는 것이 안전합니다.

ultrathink.

인증 모듈 리팩터링이 안전한지 먼저 분석해줘.

목표:
- auth 관련 로직을 service 계층으로 분리
- controller에서 token 처리 로직 제거
- 기존 API 응답 형식은 유지

확인할 것:
1. 영향 받는 파일
2. 숨은 의존성
3. 테스트가 필요한 부분
4. 되돌리기 어려운 변경
5. 단계별 실행 순서

제약:
- 아직 파일은 수정하지 마.
- 먼저 계획만 제시해줘.
- 위험도가 높은 변경은 별도로 표시해줘.

09리팩터링 계획 추가 요청

리팩터링용 Ultra Think에서는 "한 번에 다 바꾸기"를 막아야 합니다.

추가로 이렇게 요청하면 좋습니다.

리팩터링을 한 번에 하지 말고,
작은 커밋 단위로 나눠줘.
각 단계마다 git diff로 확인할 수 있게 계획해줘.

10보안·권한·결제 로직용 Ultra Think

보안, 권한, 결제 로직은 단순 기능 구현보다 위험합니다. 작동하는 것처럼 보여도 권한 우회, 민감정보 노출, 중복 결제, 잘못된 환불 같은 문제가 생길 수 있습니다.

이런 작업에서는 Ultra Think를 강하게 쓰는 것이 좋습니다.

ultrathink.

이 변경은 권한/보안 로직과 관련되어 있어.
비용보다 정확성이 중요해.

다음을 먼저 검토해줘:
1. 권한 우회 가능성
2. 민감정보 노출 가능성
3. 기존 테스트로 잡히지 않는 위험
4. 잘못 수정했을 때의 장애 범위
5. 안전한 수정 순서
6. 반드시 추가해야 할 테스트

제약:
- 파일 수정은 내가 승인하기 전까지 하지 마.
- 위험한 명령은 실행하지 마.
- 확신이 낮은 부분은 추측이라고 표시해줘.

11결제 로직 검토용 프롬프트

결제 로직에서는 이렇게 씁니다.

ultrathink.

결제 완료 webhook 처리 로직을 검토해줘.

중점 확인:
1. 중복 webhook이 들어왔을 때 중복 결제가 생기는지
2. 결제 성공/실패 상태 전환이 안전한지
3. 서명 검증이 누락될 가능성이 있는지
4. DB 트랜잭션이 필요한 구간이 있는지
5. 테스트해야 할 edge case

아직 수정하지 말고 분석과 수정 계획만 제시해줘.

이 파트의 원칙은 분명합니다.

보안·권한·결제 작업은 "되게 만들기"보다 "잘못되지 않게 만들기"가 먼저다.

12장애 분석용 Ultra Think

장애 분석은 단순 버그 수정과 다릅니다. 로그, 배포 이력, 환경 변수, 설정, 최근 커밋, 외부 서비스 상태까지 함께 봐야 할 수 있습니다.

ultrathink.

최근 배포 이후 API 응답 시간이 급격히 늘었어.
장애 원인을 깊게 분석해줘.

현재 증상:
- 특정 API만 느림
- 로컬에서는 재현 안 됨
- 배포 직후부터 발생
- 에러는 없고 timeout만 증가

먼저 해줘:
1. 가능한 원인을 계층별로 나눠줘.
2. 가장 먼저 확인할 로그와 파일을 정리해줘.
3. 바로 수정하면 위험한 부분을 경고해줘.
4. 임시 대응과 근본 해결을 나눠줘.

13장애 분석 시 핵심

장애 분석에서는 "원인 하나만 단정"하게 하면 위험합니다.

좋은 요청은 다음과 같습니다.

원인을 하나로 단정하지 말고,
가능성 높은 후보를 우선순위로 정리해줘.
각 후보마다 확인 방법과 반증 방법을 같이 제시해줘.

14Ultra Think와 Plan Mode 같이 쓰기

Ultra Think는 깊은 판단을 돕고, Plan Mode는 수정 전 안전장치를 제공합니다. 공식 common workflows 문서도 편집 전에 plan을 세워 변경사항이 디스크에 닿기 전에 검토하고, 큰 코드베이스 탐색은 subagent에 위임해 메인 컨텍스트를 깨끗하게 유지하는 패턴을 안내합니다.

가장 안전한 조합은 다음입니다.

ultrathink.

Plan Mode로 먼저 접근해줘.
관련 파일을 조사하고, 수정 계획과 위험 요소를 정리해줘.
내가 승인하기 전까지 파일은 수정하지 마.

이 조합의 핵심은 다음입니다.

Ultra Think = 깊게 판단하기 / Plan Mode = 실행 전에 멈추기

15대형 작업용 Ultra Think + Plan Mode

대형 작업에서는 이렇게 구체화합니다.

ultrathink.

Plan Mode로 인증 모듈 리팩터링 계획을 세워줘.

계획에 포함할 것:
1. 현재 구조 요약
2. 변경 대상 파일
3. 수정 순서
4. 각 단계의 위험도
5. 필요한 테스트
6. rollback 방법
7. 커밋을 나눌 기준

아직 파일은 수정하지 마.

둘을 같이 쓰면 "깊게 생각한 뒤 바로 수정"이 아니라, 깊게 생각한 뒤 계획을 보여주고 승인받는 흐름이 됩니다.

16Ultra Think와 Git diff 검토

Claude Code가 파일을 수정한 뒤에도 Ultra Think를 사용할 수 있습니다. 특히 커밋 전에 현재 diff가 안전한지 깊게 검토할 때 유용합니다.

ultrathink.

현재 git diff를 깊게 검토해줘.

다음을 구분해줘:
1. 의도한 변경
2. 의도하지 않은 변경
3. 동작이 바뀌는 로직 변경
4. 단순 포맷팅 변경
5. 테스트가 필요한 변경
6. 배포 전 위험 요소
7. 커밋에 포함하면 안 되는 파일

아직 git add, commit, push는 하지 마.

17커밋 전 diff 검토 추가 패턴

스테이징 후에는 이렇게 요청합니다.

ultrathink.

git diff --staged를 기준으로 이번 커밋에 들어갈 내용을 검토해줘.
커밋 메시지를 제안하되, 아직 커밋은 하지 마.

Git 검토에서 Ultra Think를 쓰면 좋은 경우:

변경 파일이 많음

의도하지 않은 수정이 섞일 수 있음

로직 변경과 포맷팅이 섞임

실제 위험 변경을 분리해야 함

보안·권한 파일이 포함됨

더 깊은 검토가 필요함

테스트 없이 수정됨

누락된 테스트를 찾아야 함

18Ultra Think 프롬프트를 강하게 만드는 7가지 요소

Ultra Think의 품질은 프롬프트 구조에 따라 크게 달라집니다.

1. 상황을 준다

배포 후에만 발생, 로컬에서는 안 됨

2. 목표를 준다

원인 후보 좁히기, 안전한 수정 순서

3. 제약을 준다

파일 수정 금지, 위험 명령 실행 금지

4. 우선순위를 요구

가능성 높은 순서로 정리해줘

5. 확인 방법을 요구

각 원인의 확인·반증 방법 제시

6. 위험 요소를 요구

반드시 조심할 위험 요소 따로 정리

7. 실행을 막는다

승인 전까지 파일 수정·명령 실행 금지

Ultra Think의 핵심은 "더 깊게 생각해줘"가 아니라, 무엇을 기준으로 깊게 볼지 지정하는 것입니다.

19Ultra Think 남용 시 생기는 문제

Ultra Think를 남용하면 다음 문제가 생깁니다.

응답이 느려짐

단순 작업에도 깊게 분석하려고 함

비용 증가

thinking token도 비용에 포함될 수 있음

과잉 분석

간단한 문제를 복잡하게 볼 수 있음

작업 리듬 저하

빠르게 처리할 일을 오래 붙잡게 됨

판단 흐림

중요한 작업과 단순 작업의 구분 사라짐

따라서 단순 작업에는 이렇게 말하는 편이 좋습니다.

깊게 분석하지 말고 핵심만 짧게 답해줘.

20Ultra Think와 effort의 차이

이제 effort를 연결해서 이해하겠습니다.

성격

프롬프트 키워드 / Claude Code 설정

적용 범위

해당 요청 한 번 / 세션 또는 설정 범위

실제 입력

ultrathink / /effort high, /effort xhigh 등

목적

한 번 깊게 분석 / 전체 추론 강도 조절

좋은 사용

중요한 단발 판단 / 작업 난이도에 맞춘 기본 설정

쉽게 말하면 다음과 같습니다.

Ultra Think = 이번 질문만 깊게 봐줘 / effort = 이 세션의 기본 사고 강도를 바꿔줘

21effort 명령어와 설정

세션 안에서 effort를 바꾸려면 다음 명령을 사용합니다.

/effort

직접 지정할 수도 있습니다.

/effort low

/effort medium

/effort high

/effort xhigh

/effort max

시작할 때 지정하려면 터미널에서 이렇게 실행합니다.

claude --effort high

claude --model opus --effort xhigh

22effort 단계별 사용 기준

공식 문서는 effort level을 토큰 사용량과 능력 사이의 균형으로 설명합니다. 초보자용 기준은 다음과 같습니다.

low

파일 위치 찾기, 짧은 요약 | 코드 수정, 설계 판단 피하기

medium

간단한 설명, 작은 변경 검토 | 보안·결제·권한은 피하기

high

일반 버그 수정, 테스트 작성 | 매우 어려운 장애 분석 피하기

xhigh

리팩터링, 어려운 버그, agentic coding | 단순 요약은 피하기

max

고위험 장애, 복잡한 설계 검토 | 반복 사용, 단순 작업 피하기

23Ultra Think와 effort 조합법

Ultra Think와 effort는 따로 쓰는 것이 아니라 조합할 수 있습니다.

일반 분석

/effort high

이 버그의 원인을 분석하고 수정 계획을 제안해줘.

중요한 한 번의 판단

/effort high

ultrathink.

이 수정 방향이 안전한지 깊게 검토해줘.
숨은 부작용과 테스트 누락을 중심으로 봐줘.

24대형 리팩터링과 고위험 검토

대형 리팩터링

/effort xhigh

ultrathink.

Plan Mode로 먼저 리팩터링 계획을 세워줘.
영향 범위, 위험 요소, 테스트 전략, 커밋 분리 기준을 포함해줘.
아직 수정하지 마.

고위험 보안·결제 검토

/effort xhigh

ultrathink.

이 결제 webhook 변경이 안전한지 검토해줘.
중복 처리, 서명 검증, 상태 전환, 트랜잭션, rollback을 봐줘.
파일 수정은 아직 하지 마.

실전 감각은 다음과 같습니다.

일반 작업 = high / 복잡한 작업 = xhigh / 중요한 한 번의 판단 = ultrathink 추가

25max는 신중하게 쓰기

max는 가장 깊은 reasoning을 제공할 수 있지만, 항상 좋은 선택은 아닙니다. 공식 문서도 max는 demanding task에서 성능을 개선할 수 있지만 token spending에 제한이 없고, diminishing returns와 overthinking이 생길 수 있으므로 넓게 적용하기 전에 테스트하라고 설명합니다.

초보자는 max를 바로 쓰기보다 먼저 이렇게 물어보는 것이 좋습니다.

이 문제에 max effort가 필요한지 먼저 판단해줘.
필요하다면 이유, 예상 비용 증가 요인, xhigh로 충분하지 않은 이유를 설명해줘.
아직 max로 바꾸지는 마.

max를 고려할 만한 상황:

장애 원인이 전혀 안 잡힘

고려 가능

보안 사고 분석

고려 가능

대형 마이그레이션 설계

고려 가능

결제 데이터 정합성 문제

고려 가능

26ultracode와 헷갈리지 않기

/effort 메뉴에는 ultracode도 보일 수 있습니다. 하지만 ultracode는 모델 effort level이 아닙니다.

공식 문서에 따르면 ultracode는 Claude Code 설정이며, 모델에는 xhigh를 보내고 substantive task에는 dynamic workflow를 오케스트레이션합니다. 또한 session-only 설정이고, effortLevel, --effort, CLAUDE_CODE_EFFORT_LEVEL의 일부가 아닙니다.

구분은 다음과 같습니다.

ultrathink

한 번의 프롬프트를 더 깊게 분석

/effort xhigh

세션의 추론 강도를 높임

/effort max

가장 깊은 effort, 신중히 사용

ultracode

Claude Code가 workflow까지 더 강하게 구성

초보자는 처음부터 ultracode를 기본으로 쓰지 않아도 됩니다. 먼저 ultrathink와 /effort high, /effort xhigh만 제대로 익히면 충분합니다.

27실전 프롬프트 모음 ①

버그 원인 분석

ultrathink.

이 버그의 원인을 깊게 분석해줘.

증상: (증상 입력)
최근 변경: (변경사항 입력)

제약:
- 아직 파일 수정 금지
- 원인 후보를 우선순위로 정리
- 각 후보의 확인·반증 방법 포함
- 먼저 읽을 파일 3개만 제안

리팩터링 계획

ultrathink.

이 리팩터링 계획을 세워줘.

목표: (리팩터링 목표)

포함할 것:
1. 영향 범위
2. 숨은 의존성
3. 단계별 수정 순서
4. 테스트 전략
5. rollback 방법
6. 커밋 분리 기준

아직 파일은 수정하지 마.

28실전 프롬프트 모음 ②

보안 검토

ultrathink.

이 변경이 보안상 안전한지 검토해줘.

중점 확인:
1. 권한 우회 가능성
2. 민감정보 노출 가능성
3. 인증/인가 경계
4. 로그에 남으면 안 되는 값
5. 테스트 누락
6. 안전한 수정 순서

수정은 아직 하지 말고 검토 결과만 제시해줘.

결제 로직 검토

ultrathink.

결제 처리 로직을 깊게 검토해줘.

확인할 것:
1. 중복 결제 가능성
2. webhook 재시도 처리
3. 서명 검증
4. DB 트랜잭션
5. 실패 상태 처리
6. 환불/취소 edge case

파일 수정 전 계획만 제시해줘.

29실전 프롬프트 모음 ③

Git diff 검토

ultrathink.

현재 git diff를 깊게 검토해줘.

구분:
1. 의도한 변경
2. 의도하지 않은 변경
3. 실제 동작 변경
4. 단순 포맷팅
5. 테스트 필요 항목
6. 커밋 제외 대상
7. 배포 전 위험 요소

아직 git add, commit, push는 하지 마.

max effort 필요 여부 판단

이 문제에 max effort가 필요한지 판단해줘.
xhigh로 충분한지, max가 필요한지, 비용 대비 이점이 있는지 비교해줘.
아직 effort는 바꾸지 마.

30초보자용 판단표

파일 위치 찾기

Ultra Think 불필요, low/medium

README 요약

Ultra Think 불필요, low

일반 버그 수정

high

원인이 불명확한 버그

xhigh + ultrathink

대형 리팩터링

xhigh + ultrathink + Plan Mode

보안·권한 검토

xhigh 또는 max 검토 + ultrathink

결제 로직 검토

xhigh + ultrathink

장애 원인 분석

xhigh + ultrathink, 필요 시 max 검토

커밋 전 diff 검토

변경 규모가 크면 ultrathink

반복 작업

Ultra Think 남용 금지, medium/high

섹션 16 · 마무리

16단원에서 기억할 것

Ultra Think의 실제 프롬프트 키워드는 ultrathink입니다. ultrathink는 해당 요청 한 번을 더 깊게 분석하게 하는 키워드이며, 세션 전체 effort 설정을 바꾸지 않습니다.

Ultra Think는 원인 불명 버그, 대형 리팩터링, 보안, 권한, 결제, 장애 분석처럼 판단이 중요한 작업에 씁니다. 단순 요약, 파일 위치 찾기, 짧은 diff 설명에는 쓰지 않습니다.

Ultra Think를 쓸 때는 상황, 목표, 제약, 출력 형식, 실행 금지를 함께 적어야 합니다. Plan Mode와 함께 쓰면 깊게 분석한 뒤 바로 수정하지 않고 계획을 먼저 검토할 수 있습니다.

/effort는 세션의 추론 강도를 조절하는 설정입니다. low, medium, high, xhigh, max는 비용·속도·추론 깊이의 균형이 다르며, max는 항상 좋은 선택이 아니고 과잉 분석과 비용 증가가 생길 수 있습니다.

다음 단원

17단원. 버그 수정 워크플로우 만들기

17. 버그 수정 워크플로우 만들기

01버그 수정의 기본 흐름

Claude Code로 버그를 고칠 때는 10단계 프로세스를 기본으로 삼습니다.

1증상 설명 정확히 설명

2재현 방법 알려주기

3에러 로그 stack trace 제공

4파일 탐색 관련 파일 찾기

5원인 정리 우선순위 순

그 다음 단계:

수정 계획을 먼저 받는다.
최소 범위로 수정한다.
테스트를 추가하거나 실행한다.
git diff로 변경사항을 검토한다.
커밋 전 최종 위험 요소를 확인한다.

02가장 흔한 초보자 실수

초보자가 가장 많이 하는 실수는 이 단계들을 건너뛰고 바로 이렇게 요청하는 것입니다.

이 버그 고쳐줘.

이렇게 요청하면 Claude가 너무 넓은 범위를 추측할 수 있습니다.

훨씬 더 좋은 요청은 다음과 같습니다.

로그인 후 새로고침하면 다시 로그인 페이지로 이동하는 버그가 있어.
먼저 원인을 분석해줘.
수정은 아직 하지 말고,
재현 방법, 관련 파일, 가능한 원인, 확인 순서를 정리해줘.

버그 수정은 속도가 아니라 정확한 원인 확인이 먼저입니다.

03증상을 잘 설명하는 법

Claude가 버그를 잘 고치려면 "무엇이 잘못됐는지"를 정확히 알아야 합니다.

나쁜 설명:

로그인이 이상해.

좋은 설명:

로그인 폼에서 올바른 이메일과 비밀번호를 입력하면
서버 응답은 200으로 오지만,
프론트엔드에서는 로그인 상태가 유지되지 않아.
새로고침하면 다시 /login으로 이동해.

좋은 버그 설명에는 다음 항목이 들어가야 합니다.

기대 동작

로그인 후 대시보드에 머물러야 함

실제 동작

새로고침하면 로그인 페이지로 이동

발생 위치

/login, AuthProvider, session middleware

발생 조건

배포 환경에서만 발생

최근 변경

cookie 옵션, middleware 수정

에러 메시지

401 Unauthorized, Session expired

04버그 설명 정보 요청 템플릿

Claude에게 버그 정보를 정리하면서 보내려면 다음 템플릿을 사용합니다.

아래 버그 설명을 보고,
정보가 부족한 부분이 있는지 먼저 질문해줘.
바로 수정하지 말고, 원인 분석에 필요한 정보를 목록으로 정리해줘.

증상:
- (설명)

기대 동작:
- (설명)

실제 동작:
- (설명)

최근 변경사항:
- (설명)

에러 메시지:
- (설명)

05재현 방법을 먼저 고정하기

버그 수정에서 가장 중요한 것은 재현입니다. 재현이 안 되면 수정이 맞는지 확인하기 어렵습니다.

좋은 요청은 다음과 같습니다.

이 버그를 재현하는 절차를 먼저 정리해줘.
내가 제공한 증상에서 빠진 정보가 있으면 질문하고,
재현 가능한 최소 단계로 줄여줘.

재현 단계 예시:

1. 로컬 서버 실행: npm run dev
2. 브라우저에서 /login 접속
3. 테스트 계정으로 로그인
4. /dashboard 이동 확인
5. 새로고침
6. 다시 /login으로 이동하는지 확인

06재현 명령어와 간헐적 버그

테스트 명령어가 있을 때:

재현 명령어:
npm test -- auth

실패 로그:
...

간헐적 버그일 때:

이 버그는 항상 발생하지 않고 간헐적으로 발생해.
간헐적 버그로 가정하고,
가능한 원인과 로그를 추가해야 할 위치를 제안해줘.
아직 파일은 수정하지 마.

07에러 로그와 stack trace 다루기

에러 로그는 중요하지만, 너무 길면 컨텍스트를 낭비합니다. 핵심 부분부터 제공하세요.

나쁜 요청:

이 로그 전체 보고 고쳐줘.

좋은 요청:

아래 로그에서 첫 번째 실패 원인을 분석해줘.
중복 stack trace는 무시하고,
실제 에러 메시지, 관련 파일, 실패한 테스트만 기준으로 봐줘.

Claude에게 로그를 줄 때는 다음을 포함하면 좋습니다.

첫 번째 에러

뒤의 에러는 연쇄 실패일 수 있음

stack trace 상단

실제 실패 위치일 가능성이 높음

실패한 테스트명

어떤 동작이 깨졌는지 알 수 있음

최근 변경 파일

원인 후보를 좁힐 수 있음

실행 명령어

재현 가능성을 높임

08로그 분석 요청 템플릿

테스트 실패 로그를 분석할 때 다음 템플릿을 사용하면 효율적입니다.

이 테스트 실패를 분석해줘.

실행 명령어:
npm test -- auth

첫 번째 실패:
...

stack trace:
...

요청:
1. 가장 가능성 높은 원인을 설명해줘.
2. 관련 파일 후보를 3개만 제안해줘.
3. 수정 전 확인해야 할 내용을 정리해줘.
4. 아직 파일은 수정하지 마.

09관련 파일 찾기 — 범위 제한하기

초보자는 버그가 생기면 프로젝트 전체를 읽히려는 경향이 있습니다.

나쁜 요청:

프로젝트 전체를 보고 버그를 찾아줘.

이 방식은 컨텍스트와 비용을 크게 늘립니다. 더 좋은 요청은 범위를 좁힙니다.

전체 프로젝트를 읽지 말고,
이 버그와 관련 있을 가능성이 높은 파일 후보만 찾아줘.

조건:
- 로그인 상태 유지와 관련된 파일
- session, cookie, auth middleware 관련 파일
- 테스트 파일이 있다면 함께 제안

출력:
1. 파일 경로
2. 관련 있어 보이는 이유
3. 먼저 읽어야 할 우선순위

10단계별 파일 읽기

Claude가 후보 파일을 제안하면, 모든 파일을 한 번에 읽지 말고 단계적으로 진행합니다.

제안한 파일 중 우선순위 1~3번만 먼저 읽어줘.
그 안에서 원인을 못 찾으면 다음 파일을 제안해줘.

이 방식은 다음 장점이 있습니다.

한 번에 읽는 파일 수가 적어 빠릅니다.
우선순위 높은 파일에서 답을 찾을 가능성이 높습니다.
Claude의 컨텍스트를 낭비하지 않습니다.

11원인 후보를 우선순위로 정리하기

버그 수정에서 위험한 태도는 "이게 원인일 거야"라고 너무 빨리 단정하는 것입니다.

Claude에게는 항상 원인 후보를 여러 개로 나누고, 근거와 확인 방법을 함께 요구합니다.

가능한 원인을 우선순위별로 정리해줘.

각 원인마다 다음을 포함해줘:
1. 왜 가능성이 높은지
2. 확인할 파일
3. 확인할 코드 위치
4. 반증 방법
5. 수정한다면 예상 변경 범위

아직 수정하지 마.

12어려운 버그를 위한 깊은 분석

어려운 버그라면 16단원의 Ultra Think를 함께 사용합니다.

ultrathink.

이 버그의 원인을 깊게 분석해줘.
원인을 하나로 단정하지 말고,
가능성 높은 후보를 우선순위로 정리해줘.
각 후보마다 확인 방법과 반증 방법을 함께 제시해줘.

원인 후보 표 예시:

우선순위 1

cookie secure 설정 문제 — 배포 환경에서만 발생

우선순위 2

session 저장소 불일치 — 새로고침 후 상태 사라짐

우선순위 3

frontend auth state 초기화 — 서버 200인데 UI 로그아웃

13수정 계획을 먼저 받기

원인 후보를 확인했다면 바로 수정하지 말고, 수정 계획을 먼저 받습니다.

요청 예시:

수정 계획을 먼저 제안해줘.

포함할 것:
1. 수정할 파일
2. 수정할 함수 또는 코드 위치
3. 변경 이유
4. 예상 부작용
5. 추가 또는 수정할 테스트
6. 되돌리는 방법

아직 파일은 수정하지 마.

버그 수정은 "생각나는 대로 수정"이 아니라 "검증 가능한 계획을 세운 뒤 수정"입니다.

14Plan Mode로 안전하게 시작

Plan Mode를 사용하면 Claude가 파일을 읽고 계획을 제안하지만, 승인 전에는 편집하지 않습니다.

방법 1. Claude 대화에서:

Plan Mode로 접근해줘.
버그 원인을 확인하고 수정 계획을 작성해줘.
내가 승인하기 전까지 파일은 수정하지 마.

방법 2. 터미널에서:

claude --permission-mode plan

이 방식은 파일 수정 전에 검토할 시간을 줍니다.

15최소 수정 원칙

버그 수정은 가능한 작게 해야 합니다. 버그 하나를 고치면서 리팩터링, 포맷팅, 네이밍 변경까지 한 번에 섞으면 검토가 어려워집니다.

Claude에게는 이렇게 제한합니다.

이번 수정은 버그 원인을 해결하는 최소 변경만 해줘.
리팩터링, 포맷팅 변경, 이름 변경은 하지 마.
동작 변경이 필요한 부분만 수정해줘.

좋은 버그 수정 원칙:

최소 변경

원인 해결에 필요한 부분만 수정

동작 유지

관련 없는 동작은 바꾸지 않음

테스트 우선

가능하면 실패 테스트를 먼저 추가

diff 작게

리뷰 가능한 범위로 유지

한 커밋 한 목적

버그 수정과 리팩터링을 섞지 않음

16단계별 수정 실행

Claude에게 실행을 맡길 때는 단계를 나누어 진행합니다.

방금 제안한 계획 중 1단계만 적용해줘.
최소 변경으로 수정하고,
수정 후 어떤 파일을 바꿨는지 요약해줘.

이 방식의 장점:

문제가 생기면 바로 롤백할 수 있습니다.
각 단계의 효과를 검증할 수 있습니다.
전체 수정 과정이 투명합니다.

17테스트 추가하기

버그 수정에서 가장 좋은 테스트는 수정 전에는 실패하고, 수정 후에는 통과하는 테스트입니다.

테스트 추가 요청:

이 버그를 재현하는 테스트를 먼저 추가해줘.
기존 테스트 스타일을 확인하고,
수정 전에는 실패해야 하는 테스트로 작성해줘.
아직 구현 코드는 수정하지 마.

이미 수정한 뒤라면:

이번 버그가 다시 발생하지 않도록 regression test를 추가해줘.
기존 테스트 패턴을 따르고,
성공 케이스와 실패 케이스를 구분해서 작성해줘.

18테스트가 필요한 버그 유형

버그 유형에 따라 테스트 포인트가 달라집니다.

로그인 세션 문제

새로고침 후 인증 유지

입력 검증 문제

빈 값, 잘못된 형식, 경계값

권한 문제

허용 사용자와 거부 사용자

결제 문제

중복 webhook, 실패 상태, 재시도

API 에러 처리

400, 401, 500 응답

테스트를 바로 추가하기 어렵다면 최소한 이렇게 요청합니다.

이 버그에 대해 어떤 테스트를 추가해야 하는지 제안해줘.
단위 테스트, 통합 테스트, E2E 테스트 중 무엇이 적합한지도 알려줘.

19테스트 실행과 실패 로그 분석

수정 후에는 테스트를 실행합니다.

전체 테스트 실행:

npm test

20긴 실패 로그 다루기

실패 로그가 길면 전체를 다 읽지 말고 핵심만 제공합니다.

전체 로그를 다 읽지 말고,
첫 번째 FAIL 블록과 관련 stack trace만 기준으로 분석해줘.
추가 로그가 필요하면 어떤 부분이 필요한지 말해줘.

이 방식은:

Claude의 컨텍스트를 절약합니다.
첫 번째 실패가 다른 실패의 원인일 가능성이 높습니다.
답변 속도가 더 빠릅니다.

21git diff 검토하기

테스트가 통과해도 끝이 아닙니다. Git으로 변경사항을 확인해야 합니다.

터미널에서:

git status
git diff

Claude에게 검토 요청:

현재 git diff를 검토해줘.

확인할 것:
1. 버그 수정과 직접 관련 있는 변경인지
2. 불필요한 포맷팅 변경이 섞였는지
3. 의도하지 않은 파일이 수정됐는지
4. 테스트가 추가됐는지
5. 위험한 동작 변경이 있는지
6. 커밋 전에 확인할 사항

22중요한 버그의 깊은 검토

중요한 버그라면 Ultra Think를 붙여 더 깊게 검토합니다.

ultrathink.

현재 git diff를 깊게 검토해줘.
이번 변경이 실제 원인을 해결하는지,
증상만 가리는 수정은 아닌지,
테스트가 충분한지 확인해줘.
아직 commit은 하지 마.

23원인 해결 vs 증상 완화 구분

버그 수정에서 가장 위험한 것은 증상만 숨기는 수정입니다.

예를 들어 에러가 난다고 try/catch로 모두 삼켜버리면, 화면은 조용해져도 실제 데이터 문제는 남아 있을 수 있습니다.

Claude에게는 이렇게 요청합니다.

이번 수정이 근본 원인을 해결하는지,
아니면 증상만 숨기는 workaround인지 구분해줘.

근거:
1. 어떤 코드 경로가 바뀌었는지
2. 실패 조건이 어떻게 해결됐는지
3. 같은 문제가 다시 발생할 수 있는 조건
4. 추가로 필요한 테스트

좋은 버그 수정 보고서:

원인

(설명)

수정

(설명)

검증

(설명)

남은 위험

(설명)

추가 테스트

(설명)

24간헐적 버그를 다루는 법

간헐적 버그는 항상 재현되지 않기 때문에 더 어렵습니다.

간헐적 버그 예시:

가끔 로그인 실패

race condition, token 만료

특정 시간에만 실패

timezone, cron, cache

배포 환경에서만 실패

env, cookie secure, proxy

일부 사용자만 실패

데이터 상태, 권한 차이

테스트가 가끔 실패

async 처리, mock 누락

25간헐적 버그 분석 요청

간헐적 버그 분석 요청 예시:

이 버그는 간헐적으로 발생해.

ultrathink.

다음을 기준으로 분석해줘:
1. race condition 가능성
2. cache 또는 session 문제
3. 환경 변수 차이
4. 시간대/timezone 문제
5. 외부 API 지연
6. 테스트 flakiness 가능성

바로 수정하지 말고,
관측을 위해 어떤 로그나 테스트를 추가해야 하는지 먼저 제안해줘.

간헐적 버그에서는 바로 수정하기보다 관측 가능성을 높이는 것이 먼저일 때가 많습니다.

26debugger subagent 활용

큰 코드베이스에서 버그 원인을 찾다 보면 메인 컨텍스트가 파일 읽기로 가득 찰 수 있습니다. subagent에 위임하면 별도 컨텍스트에서 파일을 읽고 요약만 반환하므로 메인 컨텍스트를 깨끗하게 유지할 수 있습니다.

조사 요청:

debugger subagent를 사용해서 이 버그를 조사해줘.

목표:
- 에러 메시지와 stack trace 분석
- 재현 단계 확인
- 실패 위치 분리
- 가능한 원인 후보 정리
- 최소 수정 계획 제안

메인 대화에는 핵심 요약만 반환해줘.
아직 파일은 수정하지 마.

수정까지 맡길 때:

debugger subagent로 원인을 분석한 뒤,
수정이 필요하면 최소 변경만 제안해줘.
내가 승인하기 전까지 Edit는 실행하지 마.

27CLAUDE.md에 버그 수정 규칙 넣기

자주 반복되는 버그 수정 규칙은 CLAUDE.md에 짧게 적어두면 좋습니다.

CLAUDE.md 예시:

# Bug Fix Workflow

- 버그 수정 전에는 항상 재현 방법을 먼저 확인한다.
- 원인을 단정하지 말고 가능한 원인 후보와 근거를 제시한다.
- 파일 수정 전에는 수정 계획을 먼저 보여준다.
- 수정은 최소 변경으로 한다.
- 관련 테스트를 먼저 실행하고, 가능하면 regression test를 추가한다.
- 커밋 전에는 git status와 git diff를 요약한다.
- 보안, 권한, 결제 관련 버그는 ultrathink로 먼저 분석한다.

너무 길게 쓰지 말고, 항상 적용할 규칙만 남깁니다.

28완료 기준 만들기

버그 수정은 "에러가 안 보인다"에서 끝나면 안 됩니다. 완료 기준을 만들어야 합니다.

완료 기준 예시:

재현 절차가 설명됨
원인이 근거와 함께 설명됨
최소 수정이 적용됨
관련 테스트가 통과함
regression test가 추가되었거나 생략 이유가 설명됨
git diff 검토가 끝남
남은 위험 요소가 정리됨

Claude에게 완료 검토 요청:

이 버그 수정이 완료됐다고 볼 수 있는지 검토해줘.

기준:
1. 재현 가능했는가
2. 원인이 확인됐는가
3. 최소 수정인가
4. 테스트가 충분한가
5. diff에 불필요한 변경이 없는가
6. 남은 위험이 있는가

29커밋 전 최종 프롬프트

버그 수정이 끝났다면 커밋 전에 마지막으로 이렇게 요청합니다.

커밋 전에 최종 검토해줘.

실행할 것:
1. git status 확인
2. git diff 확인
3. 수정 파일 목록 요약
4. 버그 원인과 수정 내용 요약
5. 테스트 실행 결과 요약
6. regression test 추가 여부 확인
7. 위험 요소와 남은 TODO 확인
8. 커밋 메시지 3개 제안

아직 commit은 하지 마.

30커밋 메시지 예시

좋은 커밋 메시지 예시:

fix: preserve session after login refresh

fix(auth): handle secure cookie settings in production

test(auth): add regression coverage for session persistence

커밋까지 맡기려면 승인 후에만 진행합니다.

검토 결과 문제가 없으면,
제안한 첫 번째 커밋 메시지로 커밋해줘.
커밋 직전에 포함 파일 목록을 다시 보여줘.

31실전 전체 프롬프트 템플릿

아래 템플릿은 버그가 생겼을 때 그대로 붙여넣어 쓸 수 있습니다.

버그 수정 워크플로우로 진행해줘.

증상:
- 

기대 동작:
- 

실제 동작:
- 

재현 단계:
1. 
2. 
3. 

실행 명령어:
- 

에러 로그:
- 

최근 변경사항:
- 

진행 규칙:
1. 바로 수정하지 마.
2. 먼저 원인 후보를 우선순위로 정리해줘.
3. 관련 파일 후보를 5개 이하로 제안해줘.
4. 확인 방법과 반증 방법을 함께 알려줘.
5. 수정 계획을 먼저 제시해줘.
6. 내가 승인하면 최소 변경만 적용해줘.
7. 가능하면 regression test를 추가해줘.
8. 수정 후 테스트를 실행하고 git diff를 검토해줘.

32난이도별 버그 분석 옵션

어려운 버그라면 첫 줄에 추가:

ultrathink.

더 안전하게 진행하려면 Plan Mode로 시작:

Plan Mode로 진행해줘.

이 두 옵션을 결합할 수도 있습니다.

ultrathink.
Plan Mode로 진행해줘.

33버그 유형별 프롬프트 예시 ①

로그인 버그

로그인 후 새로고침하면 로그아웃되는 문제가 있어.

먼저 원인을 분석해줘.
cookie, session, auth middleware, frontend auth state를 기준으로
가능한 원인을 우선순위로 정리해줘.
아직 수정하지 마.

테스트 실패

npm test 실행 시 auth 관련 테스트가 실패해.

첫 번째 실패 원인만 분석해줘.
연쇄 실패는 무시하고,
실패한 assertion과 관련 코드 위치를 찾아줘.
수정 계획을 먼저 제안해줘.

34버그 유형별 프롬프트 예시 ②

배포 환경에서만 발생하는 버그

이 버그는 로컬에서는 재현되지 않고 배포 환경에서만 발생해.

ultrathink.

환경 변수, cookie secure 설정, proxy, HTTPS, DB 연결 차이를 기준으로
가능한 원인을 정리해줘.
바로 수정하지 말고 확인 순서부터 제안해줘.

권한 버그

일반 사용자가 관리자 페이지에 접근할 수 있는 권한 버그가 있어.

ultrathink.

권한 우회 가능성을 중심으로 분석해줘.
인증과 인가가 분리되어 있는지,
서버 측 검증이 누락된 곳이 있는지 확인해줘.
수정은 아직 하지 마.

35버그 유형별 프롬프트 예시 ③

결제 버그

결제 webhook이 중복으로 들어오면 주문 상태가 이상해지는 문제가 있어.

ultrathink.

중복 webhook, idempotency, DB transaction, 상태 전환 순서를 기준으로 분석해줘.
수정 전 테스트 케이스와 안전한 수정 순서를 먼저 제안해줘.

36초보자용 버그 수정 체크리스트

버그를 고칠 때마다 아래 체크리스트를 확인합니다.

[ ]

증상을 구체적으로 설명했는가?

[ ]

기대 동작과 실제 동작을 구분했는가?

[ ]

재현 단계가 있는가?

[ ]

실행 명령어와 첫 번째 에러 로그를 제공했는가?

[ ]

관련 파일을 무작정 전체 탐색하지 않았는가?

[ ]

원인 후보와 근거를 먼저 받았는가?

[ ]

수정 계획을 승인한 뒤 수정했는가?

[ ]

최소 변경만 했는가?

[ ]

버그 수정의 핵심 정리

버그 수정은 "고쳐줘"가 아니라 재현 → 원인 분석 → 계획 → 최소 수정 → 테스트 → diff 검토 순서로 진행합니다.

증상, 기대 동작, 실제 동작, 재현 단계, 에러 로그, 최근 변경사항을 구체적으로 알려야 합니다. Claude에게 바로 수정시키지 말고, 먼저 원인 후보와 확인 방법을 요청하세요.

관련 파일은 전체 프로젝트가 아니라 우선순위가 높은 파일부터 단계적으로 읽힙니다. 수정 전에는 계획을 받고, 위험한 작업은 Plan Mode로 진행합니다.

수정은 최소 변경으로 제한하고, 리팩터링이나 포맷팅 변경을 섞지 않습니다. 가능하면 수정 전 실패하고 수정 후 통과하는 regression test를 추가하세요.

어려운 버그, 간헐적 버그, 보안·권한·결제 버그는 ultrathink를 사용합니다.

큰 코드베이스에서는 debugger subagent로 원인 탐색을 위임할 수 있습니다. CLAUDE.md에는 반복되는 버그 수정 규칙과 테스트 명령어를 짧게 적어두세요.

다음 단원

18단원. 기능 추가 워크플로우 만들기

18. 기능 추가 워크플로우 만들기

4부 · 섹션 18

기능 추가 워크플로우

새 기능을 안전하게 추가하는 정해진 흐름을 따라 구현합니다.

요구사항 정리 → 관련 파일 탐색 → 계획 승인 → 단계별 구현 → 테스트 → 문서 → diff 검토

01기능 추가의 기본 흐름

기능 추가는 아래 순서를 기본으로 합니다.

1. 만들 기능을 구체적으로 설명한다.
2. 사용자가 기대하는 동작을 정리한다.
3. 변경 범위를 먼저 찾는다.
4. 관련 파일과 기존 패턴을 조사한다.
5. 구현 계획을 받는다.
6. 계획을 검토하고 승인한다.
7. 작은 단계로 구현한다.
8. 테스트를 추가하거나 수정한다.
9. 문서나 README가 필요한지 확인한다.
10. git diff로 최종 변경사항을 검토한다.

나쁜 요청 vs 좋은 요청

나쁜 예:

알림 기능 추가해줘.

좋은 예:

사용자가 댓글을 받으면 알림 목록에 표시되는 기능을 추가하고 싶어.
먼저 바로 구현하지 말고, 요구사항을 정리하고 관련 파일을 찾아줘.
그다음 구현 계획을 제안해줘.

만들기 전에 무엇을 만들지 확정한다.

02요구사항을 먼저 정리하기

기능 추가는 요구사항이 모호하면 결과도 흔들립니다. Claude에게 구현을 맡기기 전에 먼저 요구사항을 정리하게 합니다.

아래 기능 요청을 구현하기 전에 요구사항으로 정리해줘.

기능:
- 사용자가 댓글을 받으면 알림 목록에 표시한다.

정리할 것:
1. 사용자 관점의 동작
2. 필요한 화면 변화
3. 필요한 API 변화
4. 데이터 저장 여부
5. 권한 또는 보안 고려사항
6. 테스트해야 할 케이스

아직 파일은 수정하지 마.

요구사항 정리 구분

사용자 동작

댓글을 받으면 알림이 생긴다

화면

헤더 알림 아이콘에 unread count 표시

API

알림 목록 조회 API 추가

데이터

notifications 테이블 또는 컬렉션 필요

권한

본인 알림만 조회 가능

테스트

댓글 생성 시 알림 생성 확인

사용자 시나리오로 설명하기

사용자 시나리오:
1. A 사용자가 B 사용자의 글에 댓글을 단다.
2. B 사용자는 알림 목록에서 새 댓글 알림을 본다.
3. B가 알림을 클릭하면 해당 글로 이동한다.
4. 읽은 알림은 unread count에서 제외된다.

03불분명한 요구사항은 질문하게 만들기

기능 추가에서 Claude가 임의로 결정하면 나중에 수정이 커질 수 있습니다. 따라서 요구사항이 부족하면 먼저 질문하게 해야 합니다.

이 기능을 구현하기 전에 불분명한 요구사항을 질문해줘.
추측해서 구현하지 말고, 결정이 필요한 항목을 목록으로 정리해줘.

Claude가 물어봐야 할 항목들

알림은 DB에 저장해야 하나?

실시간 알림이 필요한가, 새로고침 후 조회만 하면 되는가?

읽음 처리는 어떻게 할 것인가?

알림 삭제 기능도 필요한가?

모바일 UI도 수정해야 하는가?

기존 notification 모델이 있는가?

좋은 기능 추가는 빠른 구현보다 빠른 요구사항 확정이 먼저다.

04관련 파일 찾기

요구사항이 정리되면 관련 파일을 찾습니다. 전체 프로젝트를 무작정 읽지 말고 이 기능과 관련 있을 가능성이 높은 파일 후보만 찾습니다.

전체 프로젝트를 무작정 읽지 말고,
이 기능과 관련 있을 가능성이 높은 파일 후보만 찾아줘.

기능:
- 댓글 생성 시 알림 생성
- 알림 목록 조회
- unread count 표시

출력:
1. 파일 경로
2. 관련 있어 보이는 이유
3. 먼저 읽어야 할 우선순위
4. 수정 가능성이 있는지 여부

상위 파일 조사하기

우선순위 1~5번 파일만 먼저 읽어줘.
그 안에서 기존 패턴을 찾고,
새 기능을 어디에 추가하는 것이 자연스러운지 설명해줘.

아직 파일은 수정하지 마.

기능 추가 초반에는 파일을 많이 수정하는 것보다 기존 구조를 파악하는 것이 중요합니다.

05기존 패턴을 먼저 따르게 하기

새 기능은 프로젝트의 기존 스타일과 맞아야 합니다. API 라우터, 서비스 계층, 테스트 구조, 네이밍 규칙이 이미 있다면 Claude가 그 패턴을 따라야 합니다.

새 기능을 구현하기 전에 기존 패턴을 조사해줘.

확인할 것:
1. 비슷한 기능이 이미 있는지
2. API 라우트 구조
3. 서비스 또는 repository 계층 구조
4. 테스트 파일 위치와 작성 스타일
5. 에러 처리 방식
6. 네이밍 규칙

아직 구현하지 말고 패턴만 요약해줘.

CLAUDE.md 기능 개발 규칙 예시

# Feature Development Rules

- 새 기능은 기존 폴더 구조와 네이밍 규칙을 따른다.
- 기존 API 응답 형식과 에러 처리 방식을 유지한다.
- 구현 전 관련 파일과 기존 유사 기능을 먼저 조사한다.
- 파일 수정 전 구현 계획을 제시한다.
- 기능 추가 시 관련 테스트와 문서 업데이트 여부를 확인한다.

06구현 계획 세우기

관련 파일과 기존 패턴을 확인했다면, 바로 구현하지 말고 계획을 받습니다.

이 기능의 구현 계획을 세워줘.

포함할 것:
1. 수정할 파일
2. 새로 만들 파일
3. 데이터 모델 변경 여부
4. API 변경 여부
5. UI 변경 여부
6. 테스트 계획
7. 문서 업데이트 필요 여부
8. 위험 요소
9. 단계별 구현 순서

아직 파일은 수정하지 마.

Plan Mode 활용

Plan Mode로 이 기능 추가 계획을 세워줘.
관련 파일을 조사하고, 구현 단계와 위험 요소를 정리해줘.
내가 승인하기 전까지 파일은 수정하지 마.

또는 터미널에서 시작할 때:

claude --permission-mode plan

07기능을 작은 단계로 나누기

기능 추가는 한 번에 끝내려고 하면 위험합니다. DB, API, UI, 테스트, 문서를 한 번에 수정하면 diff가 커지고 검토가 어려워집니다.

이 기능을 작은 구현 단계로 나눠줘.

조건:
- 각 단계는 git diff로 검토 가능해야 함
- 한 단계에서 너무 많은 파일을 수정하지 말 것
- 테스트 가능한 단위로 나눌 것
- 각 단계마다 완료 기준을 포함할 것

알림 기능 예시 (7단계)

1단계: notification 데이터 모델 추가

2단계: 댓글 생성 시 notification 생성

3단계: 알림 목록 조회 API 추가

4단계: unread count API 또는 응답 추가

5단계: 헤더 UI에 unread count 표시

6단계: 읽음 처리 기능 추가

7단계: 테스트와 문서 업데이트

먼저 1단계만 구현해줘.
완료 후 수정 파일과 git diff 요약을 보여줘.

08데이터 모델 변경이 있는 기능

기능 추가에서 DB 스키마나 데이터 모델이 바뀌면 더 조심해야 합니다.

이 기능에 데이터 모델 변경이 필요한지 먼저 판단해줘.

확인할 것:
1. 기존 모델로 충분한지
2. 새 테이블/컬렉션이 필요한지
3. migration이 필요한지
4. 기존 데이터와 호환되는지
5. rollback이 가능한지
6. 테스트 데이터가 필요한지

아직 migration 파일은 만들지 마.

Ultra Think로 검토하기

ultrathink.

이 기능의 데이터 모델 변경이 안전한지 검토해줘.
기존 데이터 호환성, migration 순서, rollback 전략,
테스트 케이스를 정리해줘. 아직 파일은 수정하지 마.

DB 변경은 코드 변경보다 되돌리기 어렵습니다. 먼저 계획하고, 작게 적용하고, rollback을 생각합니다.

09API 변경이 있는 기능

API를 추가하거나 바꾸는 기능은 클라이언트와 서버가 함께 영향을 받습니다.

이 기능에 필요한 API 변경을 설계해줘.

포함할 것:
1. endpoint
2. request 형식
3. response 형식
4. 에러 응답
5. 인증/권한 조건
6. 기존 API와의 호환성
7. 테스트 케이스

아직 구현하지 마.

API 설계 예시

GET /api/notifications
응답:
{
  "items": [...],
  "unreadCount": 3
}

API 권한 검토

이 API는 누가 호출할 수 있어야 해?
본인 데이터만 조회되도록 서버 측 권한 검사가 필요한지 확인해줘.

권한이 걸린 API라면 Ultra Think를 붙입니다.

ultrathink.
이 API 설계가 권한상 안전한지 검토해줘.
다른 사용자의 알림을 조회하거나 수정할 수 있는 우회 경로가 있는지 확인해줘.

10UI 변경이 있는 기능

UI 기능은 화면 동작, 상태 관리, 에러 처리, 로딩 상태까지 고려해야 합니다.

이 기능의 UI 구현 계획을 세워줘.

확인할 것:
1. 수정할 컴포넌트
2. 필요한 상태값
3. 로딩 상태
4. 에러 상태
5. 빈 상태
6. 접근성 고려사항
7. 기존 디자인 패턴
8. 테스트 방법

아직 파일은 수정하지 마.

UI 상태 예시

알림 목록을 불러오는 중

empty

알림이 없음

error

목록 조회 실패

unread

읽지 않은 알림

read

읽은 알림

clicked

알림 클릭 후 이동

기존 UI 컴포넌트 패턴을 먼저 확인하고,
그 패턴을 따라 알림 UI를 구현하는 계획을 세워줘.
새 디자인 시스템을 만들지 말고 기존 컴포넌트를 재사용해줘.

11테스트 계획 세우기

기능 추가에는 테스트가 따라와야 합니다. 기존 테스트 파일을 확인하고, 프로젝트의 테스트 스타일과 프레임워크, assertion 패턴에 맞춰 테스트를 작성합니다.

이 기능에 필요한 테스트 계획을 세워줘.

구분:
1. 단위 테스트
2. 통합 테스트
3. E2E 테스트
4. 권한 테스트
5. 실패/에러 케이스
6. edge case

기존 테스트 스타일을 먼저 확인하고,
어떤 테스트를 추가해야 하는지 제안해줘.

기능 유형별 테스트 포인트

알림 기능

댓글 생성 시 알림 생성, 읽음 처리

검색 기능

키워드, 빈 결과, 특수문자

권한 기능

허용 사용자와 거부 사용자

결제 기능

성공, 실패, 중복 요청, webhook 재시도

업로드 기능

파일 크기, 확장자, 실패 처리

테스트부터 작성하기 (TDD)

이 기능의 테스트를 먼저 작성해줘.
기존 테스트 스타일을 따르고,
구현 전에는 실패할 수 있는 테스트로 만들어줘.
아직 구현 코드는 수정하지 마.

12단계별 구현 요청하기

계획을 승인했다면 한 단계씩 구현합니다. 각 단계마다 변경사항을 검토합니다.

계획의 1단계만 구현해줘.

규칙:
- 최소 변경으로 구현
- 관련 없는 리팩터링 금지
- 포맷팅 변경만 따로 만들지 않기
- 수정 후 변경 파일 목록 요약
- 테스트가 필요하면 실행 전 먼저 알려주기

각 단계 후 검토

방금 변경한 내용의 git diff를 요약해줘.
의도한 변경과 의도하지 않은 변경을 구분해줘.

다음 단계로 진행

이제 2단계를 진행해줘.
1단계에서 정한 구조를 유지하고,
새로운 설계 변경이 필요하면 먼저 설명해줘.

큰 기능은 "한 번에 구현"보다 "작게 반복"이 안전합니다.

13구현 중 요구사항이 바뀌면 멈추기

기능을 만들다 보면 처음 계획과 다른 사실이 발견될 수 있습니다. 이때 Claude가 임의로 방향을 바꾸면 안 됩니다.

구현 중 기존 계획과 다른 사실이 발견되면,
바로 수정하지 말고 멈춰서 알려줘.

알려줄 것:
1. 무엇이 예상과 달랐는지
2. 기존 계획에 어떤 영향이 있는지
3. 선택 가능한 대안
4. 추천안
5. 내가 결정해야 할 사항

기존 구조 재사용 검토

기존 notification 관련 코드가 있으면 새 구조를 만들지 말고,
먼저 기존 구조를 재사용할 수 있는지 검토해줘.

Claude가 예상과 다른 구조를 발견하면, 구현을 계속하기보다 계획을 업데이트해야 합니다.

14문서 업데이트 확인하기

기능을 추가하면 문서도 바뀌어야 할 수 있습니다. 기능 구현 후 문서 업데이트가 필요한지 확인합니다.

이번 기능 추가로 문서 업데이트가 필요한지 확인해줘.

확인할 문서:
1. README
2. API 문서
3. .env.example
4. 개발자 가이드
5. changelog
6. 사용자 도움말

필요한 경우 어떤 문서를 어떻게 바꿔야 하는지 제안해줘.
아직 수정하지 마.

기능 변경별 문서 업데이트

새 API 추가

API 문서

새 환경 변수 추가

.env.example, README

새 명령어 추가

README

설정 방식 변경

개발자 가이드

사용자 화면 변경

사용자 가이드 또는 릴리스 노트

코드 변경은 끝났으니, 문서 업데이트만 별도 단계로 진행해줘.
수정 전 어떤 문서를 바꿀지 먼저 제안해줘.

15권한·보안 검토하기

새 기능은 보안 문제를 만들 수 있습니다. 특히 사용자의 데이터, 결제, 권한, 관리자 기능, 파일 업로드와 관련된 기능은 반드시 검토해야 합니다.

이 기능 추가가 보안상 안전한지 검토해줘.

확인할 것:
1. 인증이 필요한 API인지
2. 본인 데이터만 접근 가능한지
3. 관리자 권한 검사가 필요한지
4. 민감정보가 응답이나 로그에 노출되는지
5. 입력 검증이 필요한지
6. rate limit이 필요한지
7. 테스트가 충분한지

아직 추가 수정은 하지 말고 검토 결과만 알려줘.

고위험 기능의 Ultra Think 검토

ultrathink.

이 기능은 사용자 권한과 개인정보에 관련되어 있어.
권한 우회, 데이터 노출, 입력 검증 누락 가능성을 깊게 검토해줘.
수정은 아직 하지 마.

16subagent로 영향 범위 조사하기

큰 기능은 관련 파일이 많을 수 있습니다. 이때 메인 대화에서 모든 파일을 읽으면 컨텍스트가 커집니다. subagent에 위임하면 별도 컨텍스트에서 파일을 읽고 요약만 반환해 메인 컨텍스트를 깨끗하게 유지할 수 있습니다.

subagent를 사용해서 이 기능의 영향 범위를 조사해줘.

기능:
- 댓글 알림 기능

조사할 것:
1. 댓글 생성 흐름
2. 사용자 알림 관련 기존 코드
3. 인증/권한 처리
4. 테스트 파일 위치
5. UI 표시 위치

메인 대화에는 핵심 파일 목록과 구현 후보만 요약해서 반환해줘.
아직 파일은 수정하지 마.

subagent 조사 시 추가 제약

조사할 때 vendor 폴더는 무시하고,
기존 notification 구조가 있으면 새 구조를 만들지 말고
재사용 가능성을 먼저 확인해줘.

17기능 완료 기준 만들기

기능 추가는 "화면에 보인다"에서 끝나면 안 됩니다. 완료 기준을 먼저 만들어야 합니다.

이 기능의 완료 기준을 만들어줘.

포함할 것:
1. 사용자 시나리오가 충족되는지
2. API 또는 UI 동작이 검증되는지
3. 권한 조건이 지켜지는지
4. 테스트가 추가되었는지
5. 문서 업데이트가 필요한지
6. git diff에 불필요한 변경이 없는지
7. 남은 위험 요소가 정리되었는지

완료 기준 예시

댓글 생성 시 알림이 생성된다.

알림 목록에서 본인의 알림만 조회된다.

unread count가 읽음 처리 후 감소한다.

권한 없는 사용자는 다른 사용자의 알림을 볼 수 없다.

관련 단위 테스트와 통합 테스트가 통과한다.

README 또는 API 문서가 필요한 경우 업데이트된다.

18테스트 실행과 결과 검토

구현 후에는 테스트를 실행합니다. 관련 테스트를 먼저 실행하고 실패 원인을 분석합니다.

npm test

관련 테스트만 먼저 실행할 수도 있습니다.

npm test -- notifications

관련 테스트를 먼저 실행해줘.
실패하면 첫 번째 실패 원인만 분석하고,
연쇄 실패는 따로 구분해줘.

테스트 통과 후 검토

테스트 결과를 기준으로 이 기능이 완료 기준을 충족하는지 검토해줘.
부족한 테스트나 edge case가 있으면 알려줘.

자주 빠지는 edge case

알림

알림이 0개인 상태

검색

빈 검색어, 특수문자

pagination 마지막 페이지

권한

다른 사용자 데이터 접근

업로드

용량 초과, 허용되지 않은 확장자

결제

중복 webhook, 실패 후 재시도

19git diff로 최종 검토하기

기능이 동작하고 테스트도 통과했다면 Git으로 변경사항을 확인합니다.

git status
git diff

현재 git diff를 검토해줘.

확인할 것:
1. 기능 추가와 직접 관련 있는 변경인지
2. 의도하지 않은 파일이 수정됐는지
3. 포맷팅 변경이 섞였는지
4. 테스트가 충분히 추가됐는지
5. 문서 업데이트가 필요한데 빠졌는지
6. 보안 또는 권한상 위험이 있는지
7. 커밋을 나눠야 하는지

변경사항을 커밋으로 나누기

이번 변경을 커밋 단위로 나눠줘.
예를 들어 model/API/UI/test/docs 기준으로 분리할 수 있는지 제안해줘.
아직 git add나 commit은 하지 마.

기능이 커질수록 diff 검토와 커밋 분리는 더 중요해집니다.

20PR 설명 만들기

기능 추가는 보통 PR로 리뷰를 받습니다. PR 생성 전에 설명 초안을 작성해 리뷰어가 중점적으로 봐야 할 부분을 명확히 합니다.

PR을 만들기 전에 설명 초안을 작성해줘.

포함할 것:
1. 변경 요약
2. 사용자에게 보이는 변화
3. 구현 세부사항
4. 테스트 결과
5. 리뷰어가 중점적으로 봐야 할 부분
6. 남은 위험 요소
7. 관련 이슈

PR 설명 템플릿

## 변경 요약
-

## 사용자에게 보이는 변화
-

## 구현 내용
-

## 테스트
-

## 리뷰어 확인 사항
-

## 위험 요소 / 남은 TODO
-

21CLAUDE.md에 기능 추가 규칙 넣기

기능 추가 규칙이 반복된다면 CLAUDE.md에 짧게 적어둡니다. 다만 CLAUDE.md는 모든 세션에서 컨텍스트를 차지하므로 간결하게 작성합니다.

# Feature Development Workflow

- 새 기능은 구현 전에 요구사항을 먼저 정리한다.
- 관련 파일과 기존 유사 기능을 먼저 조사한다.
- 파일 수정 전 구현 계획을 제시한다.
- 큰 기능은 작은 단계로 나누어 구현한다.
- 관련 없는 리팩터링이나 포맷팅 변경을 섞지 않는다.
- 새 API에는 권한 검사를 포함한다.
- 기능 추가 시 테스트와 문서 업데이트 필요 여부를 확인한다.
- 커밋 전 git status와 git diff를 요약한다.

CLAUDE.md는 200줄 이하를 목표로 간결하게 작성합니다.

22실전 전체 프롬프트 템플릿

아래 템플릿은 새 기능을 추가할 때 그대로 사용할 수 있습니다.

기능 추가 워크플로우로 진행해줘.

기능 설명:
-

사용자 시나리오:
1.
2.
3.

기대 동작:
-

제약 조건:
- 기존 API 응답 형식은 가능하면 유지
- 기존 코드 스타일과 폴더 구조를 따를 것
- 관련 없는 리팩터링 금지
- 파일 수정 전 계획 먼저 제시

진행 순서:
1. 요구사항을 정리해줘.
2. 불분명한 점을 질문해줘.
3. 관련 파일 후보를 찾아줘.
4. 기존 유사 기능과 패턴을 조사해줘.
5. 구현 계획을 단계별로 제안해줘.
6. 테스트 계획을 세워줘.
7. 내가 승인하면 1단계부터 최소 변경으로 구현해줘.
8. 각 단계 후 git diff를 요약해줘.
9. 마지막에 테스트와 문서 업데이트 필요 여부를 확인해줘.

아직 파일은 수정하지 마.

복잡한 기능 추가

복잡한 기능이라면 첫 줄에 추가합니다.

ultrathink.

Plan Mode 함께 사용

Plan Mode까지 같이 쓰려면 이렇게 시작합니다.

ultrathink.

Plan Mode로 기능 추가 계획을 세워줘.
내가 승인하기 전까지 파일은 수정하지 마.

23기능 유형별 프롬프트 예시

알림 기능

댓글이 달리면 글 작성자에게 알림이 생기는 기능을 추가하고 싶어.

먼저 요구사항을 정리하고,
댓글 생성 흐름, 사용자 모델, 알림 관련 기존 코드가 있는지 찾아줘.
아직 구현하지 말고 계획만 제안해줘.

검색 기능

게시글 검색 기능을 추가하고 싶어.

요구사항:
- 제목과 본문에서 검색
- 빈 검색어 처리
- pagination 유지
- 기존 목록 API와 호환

먼저 관련 API와 쿼리 구조를 조사하고,
구현 계획과 테스트 케이스를 제안해줘.

관리자 기능

관리자가 사용자를 비활성화할 수 있는 기능을 추가하고 싶어.

ultrathink.

권한 검사를 중심으로 요구사항과 위험 요소를 정리해줘.
일반 사용자가 이 기능을 우회할 수 없는지 확인해야 해.
아직 파일은 수정하지 마.

파일 업로드 기능

프로필 이미지 업로드 기능을 추가하고 싶어.

먼저 다음을 설계해줘:
1. 허용 파일 형식
2. 최대 파일 크기
3. 저장 위치
4. 보안 검증
5. 실패 처리
6. 테스트 케이스

구현은 내가 승인한 뒤에 진행해줘.

결제 기능

구독 결제 기능을 추가하고 싶어.

ultrathink.

결제 성공, 실패, webhook, 중복 요청, 환불, 권한, DB 정합성을 기준으로
요구사항과 구현 계획을 먼저 정리해줘.
아직 파일은 수정하지 마.

24초보자용 기능 추가 체크리스트

기능을 추가할 때마다 아래 체크리스트를 확인합니다.

기능 설명구체적인가?

사용자 시나리오있는가?

기대 동작정리됐는가?

불분명한 점질문했는가?

관련 파일찾았는가?

기존 패턴확인했는가?

구현 계획받았는가?

단계 분할했는가?

데이터 모델확인했는가?

API 설계검토했는가?

UI 상태고려했는가?

테스트 계획세웠는가?

문서 업데이트확인했는가?

git status검토했는가?

커밋 분리필요한가?

섹션 18 · 마무리

18단원 핵심 정리

기능 추가는 "만들어줘"가 아니라 요구사항 정리 → 관련 파일 탐색 → 계획 승인 → 단계별 구현 → 테스트 → 문서 → diff 검토 순서로 진행합니다.

기능명보다 사용자 시나리오를 설명하는 것이 좋습니다.
불분명한 요구사항은 Claude가 추측하지 말고 질문하게 해야 합니다.
전체 프로젝트를 무작정 읽히지 말고 관련 파일 후보부터 좁힙니다.
기존 유사 기능, API 구조, 테스트 스타일을 먼저 조사합니다.
구현 전에는 Plan Mode로 계획을 받고, 승인 후 작은 단계로 구현합니다.
DB, API, 권한, 결제, 개인정보가 관련된 기능은 Ultra Think로 위험 요소를 검토합니다.
새 기능에는 테스트 계획이 필요하며, 가능하면 구현 전 실패하는 테스트부터 작성합니다.
기능 추가 후에는 문서 업데이트가 필요한지 확인합니다.
마지막에는 git status, git diff로 의도하지 않은 변경을 검토합니다.
큰 코드베이스에서는 subagent로 영향 범위를 조사해 메인 컨텍스트를 유지합니다.

다음 단원

19단원. 리팩터링과 코드 리뷰 요청하기

19. 리팩터링과 코드 리뷰 요청하기

01리팩터링과 기능 추가를 구분하기

리팩터링은 새 기능을 만드는 작업이 아닙니다. 기존 동작을 유지하면서 코드 구조, 중복, 이름, 책임 분리, 테스트 가능성을 개선하는 작업입니다.

기능 추가

새로운 동작을 만든다

버그 수정

잘못된 동작을 고친다

리팩터링

기존 동작은 유지하고 내부 구조를 개선한다

코드 리뷰

변경사항의 위험과 개선점을 찾는다

나쁜 요청:

이 코드 좀 깔끔하게 바꿔줘.

좋은 요청:

이 코드를 리팩터링하고 싶어.
목표: 기존 동작은 유지
중복된 validation 로직 제거
함수 책임 분리
테스트는 기존 그대로 통과해야 함
먼저 수정하지 말고 리팩터링 계획을 제안해줘.

리팩터링의 첫 번째 원칙: 동작 변경 금지

02리팩터링 전 계획 세우기

리팩터링은 변경 범위가 커지기 쉽습니다. 따라서 먼저 Plan Mode로 접근하는 것이 안전합니다. 공식 common workflows 문서도 "Plan before editing"을 권장하며, 변경사항이 디스크에 닿기 전에 계획을 검토하고 싶다면 Plan Mode를 사용하라고 안내합니다. 또한 큰 코드베이스 탐색은 subagent에 위임해 메인 컨텍스트를 깨끗하게 유지할 수 있습니다.

요청 예시:

Plan Mode로 리팩터링 계획을 세워줘.
대상: src/auth 폴더
목표: token parsing 로직 분리
session validation 중복 제거
기존 API 응답 형식 유지
계획에 포함할 것:
1. 현재 구조 요약
2. 리팩터링 대상 파일
3. 바꾸면 안 되는 동작
4. 단계별 수정 순서
5. 각 단계의 테스트 방법
6. 위험 요소
7. rollback 방법
내가 승인하기 전까지 파일은 수정하지 마.

시작할 때부터 plan mode로 들어가고 싶다면:

claude --permission-mode plan

리팩터링은 구현보다 계획이 먼저다.

03변경 범위 제한하기

리팩터링은 "조금만 정리하려고 했는데 프로젝트 전체가 바뀌는" 일이 자주 생깁니다. 그래서 범위를 명확히 제한해야 합니다.

나쁜 요청:

전체 코드베이스 리팩터링해줘.

좋은 요청:

src/auth/session.ts 파일만 리팩터링해줘.
제한: 공개 함수 이름은 바꾸지 마
API 응답 형식은 유지해줘
테스트가 깨지면 멈추고 원인을 설명해줘
관련 없는 포맷팅 변경은 하지 마.

파일 기준

src/auth/session.ts만 수정

폴더 기준

src/auth/** 안에서만 수정

동작 기준

API 응답 형식 유지

테스트 기준

기존 테스트 통과 유지

커밋 기준

한 단계당 하나의 목적

위험 기준

DB migration 제외

04리팩터링 대상 찾기

무엇을 리팩터링해야 할지 모를 때는 먼저 후보를 찾게 합니다.

요청 예시:

리팩터링 후보를 찾아줘.
기준:
1. 중복 코드
2. 너무 긴 함수
3. 책임이 많은 파일
4. 이름이 모호한 함수
5. 에러 처리가 반복되는 부분
6. 테스트하기 어려운 구조
출력: 파일 경로, 문제 설명, 리팩터링 난이도, 위험도, 순서
아직 파일은 수정하지 마.

우선순위 1

session.ts — token 검증 중복, 위험도 중간

우선순위 2

authMiddleware.ts — 책임 과다, 위험도 높음

우선순위 3

validators.ts — 함수 이름 모호, 위험도 낮음

초보자는 낮은 위험도부터 시작하는 것이 좋습니다.

05동작 유지 조건을 명확히 적기

리팩터링에서 가장 중요한 것은 "기존 동작 유지"입니다. Claude에게 이 조건을 명확히 알려야 합니다.

리팩터링 조건:
- 기존 public API는 유지한다
- 함수의 입력과 출력은 바꾸지 않는다
- 에러 메시지 형식은 유지한다
- 기존 테스트는 모두 통과해야 한다
- 성능 특성이 나빠지면 안 된다
- 관련 없는 파일은 수정하지 않는다

특히 API나 라이브러리 코드는 더 엄격하게:

이 모듈은 외부에서 import해서 쓰는 코드야.
export된 함수명, 타입, 반환값은 바꾸지 말고,
내부 구현만 정리해줘.

UI 컴포넌트라면:

UI 동작과 화면 결과는 바꾸지 말고,
컴포넌트 분리와 상태 관리 구조만 개선해줘.

06작은 단계로 리팩터링하기

리팩터링은 한 번에 크게 하면 리뷰가 어렵습니다. 작은 테스트 가능한 단위로 진행해야 합니다.

단계를 나누는 요청:

이 리팩터링을 작은 단계로 나눠줘.
조건:
- 각 단계는 git diff로 검토 가능해야 함
- 한 단계에서 너무 많은 파일을 수정하지 말 것
- 각 단계 후 테스트할 수 있어야 함
- 동작 변경과 구조 변경을 섞지 말 것

단계 예시:

1단계: 중복 validation 함수를 하나로 합치기
2단계: token parsing 함수를 별도 파일로 분리하기
3단계: auth middleware에서 session service 호출로 변경하기
4단계: 기존 테스트 실행
5단계: 필요한 regression test 추가

한 단계씩 요청:

계획의 1단계만 적용해줘.
최소 변경으로 진행하고,
완료 후 수정 파일과 git diff 요약을 보여줘.

07리팩터링 중 테스트 실행하기

리팩터링은 동작을 바꾸지 않아야 하므로 테스트가 중요합니다.

리팩터링 전 테스트 명령어 확인:

리팩터링 전에 관련 테스트 명령어를 먼저 찾아줘.
테스트 명령어를 확인한 뒤,
수정 후 어떤 테스트를 실행해야 하는지 제안해줘.

수정 후 테스트:

관련 테스트를 실행해줘.
실패하면 첫 번째 실패 원인만 분석하고,
리팩터링이 동작을 바꿨는지 확인해줘.

Claude는 기존 테스트 파일을 보고 프로젝트의 테스트 스타일, 프레임워크, assertion 패턴을 맞출 수 있으며, edge case를 제안할 수 있습니다.

테스트가 부족한 경우:

이 리팩터링을 안전하게 하기 위해 부족한 테스트가 있는지 확인해줘.
기존 테스트 스타일을 따르는 regression test가 필요하면 제안해줘.
아직 테스트 파일은 수정하지 마.

08리팩터링 후 diff 검토하기

리팩터링 후에는 반드시 Git diff를 확인합니다.

git status
git diff

Claude에게 이렇게 요청합니다:

현재 git diff를 검토해줘.
확인할 것:
1. 동작 변경이 섞였는지
2. 리팩터링 범위를 벗어난 파일이 수정됐는지
3. 불필요한 포맷팅 변경이 섞였는지
4. public API가 바뀌었는지
5. 테스트가 필요한 부분이 있는지
6. 커밋을 나눠야 하는지
아직 git add나 commit은 하지 마.

큰 리팩터링이라면 Ultra Think를 사용합니다:

ultrathink.
현재 git diff를 깊게 검토해줘.
이 변경이 순수 리팩터링인지,
동작 변경이 섞였는지,
테스트로 확인되지 않은 위험이 있는지 분석해줘.

09코드 리뷰는 언제 요청해야 하는가

코드 리뷰는 작업 마지막에만 하는 것이 아닙니다. 아래 순간마다 요청할 수 있습니다.

구현 전

계획이 안전한지 검토

1단계 완료 후

방향이 맞는지 확인

테스트 실패 후

원인이 리팩터링 때문인지 확인

커밋 전

diff 최종 검토

PR 전

리뷰어 관점으로 위험 요소 정리

기본적인 요청:

현재 변경사항을 코드 리뷰해줘.
보안, 성능, 유지보수성, 테스트 누락 관점에서 봐줘.
아직 수정은 하지 말고 리뷰 의견만 제시해줘.

우선순위별로 결과받기:

리뷰 결과를 다음 형식으로 정리해줘.
1. Critical: 반드시 수정해야 하는 문제
2. Warning: 수정하는 것이 좋은 문제
3. Suggestion: 개선하면 좋은 제안
4. Question: 확인이 필요한 설계 의문

10`/code-review` 사용하기

Claude Code는 /code-review, /debug, /batch, /loop, /claude-api 같은 bundled skill을 모든 세션에서 제공하며, /skill-name 형식으로 직접 호출할 수 있습니다. /code-review는 고정 로직 명령이 아니라 prompt 기반 skill로, Claude가 도구를 사용해 작업을 오케스트레이션합니다.

기본 사용:

/code-review

더 구체적으로 요청:

/code-review 현재 git diff를 기준으로 리뷰해줘.
보안, 에러 처리, 테스트 누락, 성능 문제를 우선적으로 봐줘.

초보자에게는 읽기 전용 리뷰를 기본으로 권장합니다:

/code-review
리뷰만 해줘.
파일 수정은 하지 마.

자동 수정은 다음 조건에서만 고려합니다:

git status가 깨끗한 상태에서 시작했다
변경사항을 되돌릴 수 있다
리뷰 결과가 작고 명확하다
수정 후 git diff를 반드시 검토한다
테스트를 실행한다

안전한 요청:

코드 리뷰 결과를 먼저 보여줘.
자동 수정은 하지 마.
각 항목을 내가 승인하면 하나씩 수정하자.

11직접 코드 리뷰 프롬프트 만들기

/code-review를 쓰지 않고 직접 리뷰를 요청할 수도 있습니다.

현재 변경사항을 senior engineer 관점에서 코드 리뷰해줘.
범위: git diff 기준, 수정된 파일 중심, 새로 추가된 테스트 포함
중점:
1. 버그 가능성
2. 보안 문제
3. 권한 검증 누락
4. 에러 처리
5. 성능 문제
6. 중복 코드
7. 테스트 누락
8. 유지보수성
형식: Critical / Warning / Suggestion / 칭찬할 점 / 최종 판단

더 엄격하게:

리뷰어가 PR을 막을 수 있는 수준의 문제만 먼저 찾아줘.
스타일 취향이나 사소한 네이밍은 뒤로 미뤄줘.

더 부드럽게:

초보자에게 설명하듯 리뷰해줘.
문제점뿐 아니라 왜 문제인지와 어떻게 고치면 좋은지도 설명해줘.

12보안 관점 코드 리뷰

권한, 인증, 결제, 개인정보, 파일 업로드, 관리자 기능이 포함되면 보안 리뷰를 별도로 요청해야 합니다.

보안 관점으로 코드 리뷰해줘.
확인할 것:
1. 인증이 필요한 API에 인증 검사가 있는지
2. 본인 데이터만 접근 가능한지
3. 관리자 권한 우회 가능성이 있는지
4. 입력 검증이 충분한지
5. 민감정보가 로그나 응답에 노출되는지
6. secret, API key, token이 코드에 포함됐는지
7. 에러 메시지가 내부 정보를 노출하지 않는지
8. rate limit이나 abuse 방지가 필요한지
수정은 아직 하지 말고 리뷰 결과만 알려줘.

중요한 변경이면 Ultra Think를 붙입니다:

ultrathink.
이 변경은 권한 로직과 관련되어 있어.
권한 우회 가능성을 중심으로 깊게 리뷰해줘.
수정은 아직 하지 마.

13성능 관점 코드 리뷰

리팩터링이 성능을 나쁘게 만들 수도 있습니다. 특히 반복문, DB 쿼리, API 호출, 렌더링이 관련되면 성능 리뷰를 요청합니다.

성능 관점으로 코드 리뷰해줘.
확인할 것:
1. 불필요한 반복문
2. N+1 query 가능성
3. 중복 API 호출
4. 캐시가 필요한 부분
5. 비동기 처리 문제
6. 대량 데이터에서 느려질 코드
7. React라면 불필요한 re-render 가능성
8. 메모리 사용량 증가 가능성
수정은 아직 하지 말고,
위험도와 근거를 함께 알려줘.

성능 리뷰는 추측으로 끝나면 안 됩니다:

성능 문제가 의심되는 부분은
측정 방법이나 확인할 로그/테스트도 함께 제안해줘.

14유지보수성 관점 코드 리뷰

리팩터링의 핵심 목적은 유지보수성 향상입니다.

유지보수성 관점으로 코드 리뷰해줘.
확인할 것:
1. 함수가 너무 많은 책임을 갖고 있는지
2. 이름이 의도를 잘 드러내는지
3. 중복 로직이 있는지
4. 추상화가 과하거나 부족한지
5. 테스트하기 쉬운 구조인지
6. 새 개발자가 이해하기 쉬운지
7. 에러 처리 패턴이 일관적인지
8. 프로젝트 기존 스타일과 맞는지

리뷰 결과는 바로 수정하지 않고 먼저 검토합니다:

유지보수성 개선 제안을 위험도 낮은 순서로 정리해줘.
각 제안이 실제로 가치 있는지,
단순 취향인지 구분해줘.

15code-reviewer subagent 만들기

반복적으로 코드 리뷰를 한다면 code-reviewer subagent를 만들 수 있습니다. 이는 읽기 전용 코드 리뷰어로 설계합니다.

저장 위치: .claude/agents/code-reviewer.md

예시 파일:

---
name: code-reviewer
description: 코드 품질, 보안, 유지보수성을 검토하는 읽기 전용 코드 리뷰어. 코드 수정 후 즉시 사용.
tools: Read, Grep, Glob, Bash
model: inherit
---

당신은 senior code reviewer입니다.

리뷰 절차:
1. git diff를 실행해 최근 변경사항을 확인합니다.
2. 수정된 파일에 집중합니다.
3. 코드 수정은 하지 않습니다.
4. 리뷰 결과만 제공합니다.

리뷰 체크리스트:
- 코드가 명확하고 읽기 쉬운가
- 함수와 변수 이름이 적절한가
- 중복 코드가 없는가
- 에러 처리가 적절한가
- secret, API key, token 노출이 없는가
- 입력 검증이 충분한가
- 테스트 커버리지가 충분한가
- 성능 문제가 없는가

출력 형식:
- Critical: 반드시 수정해야 하는 문제
- Warning: 수정하는 것이 좋은 문제
- Suggestion: 고려할 만한 개선
- Good: 잘된 점

사용 예시:

code-reviewer subagent로 현재 변경사항을 리뷰해줘.
수정하지 말고 리뷰 결과만 알려줘.

16리뷰 subagent는 읽기 전용이 안전하다

코드 리뷰어는 기본적으로 수정 권한이 없어야 합니다. 리뷰어가 발견과 수정을 동시에 하면, 사용자가 검토하기 전에 변경이 섞일 수 있습니다.

좋은 도구 구성:

tools: Read, Grep, Glob, Bash

피하는 구성:

tools: Read, Grep, Glob, Bash, Edit, Write

리뷰와 수정은 분리합니다:

code-reviewer가 문제를 찾는다
사용자가 수정할 항목을 고른다
Claude가 선택된 항목만 수정한다
테스트를 실행한다
다시 리뷰한다

이 흐름이 초보자에게 가장 안전합니다.

17리뷰 결과를 수정으로 연결하기

리뷰를 받았다면 바로 전체 수정하지 말고, 우선순위를 정합니다.

리뷰 결과 중 반드시 수정해야 하는 항목만 골라줘.
Critical과 Warning을 분리하고,
각 항목의 수정 난이도와 위험도를 알려줘.

그다음 하나씩 수정합니다:

Critical 1번만 수정해줘.
다른 리뷰 항목은 아직 건드리지 마.
수정 후 git diff를 요약해줘.

리뷰 반영 후 다시 확인합니다:

방금 수정한 내용이 리뷰 항목을 해결했는지 확인해줘.
새로운 문제가 생겼는지도 봐줘.

자동으로 전부 수정하는 나쁜 요청:

리뷰 나온 거 다 고쳐줘.

더 안전한 요청:

리뷰 항목을 우선순위로 정리해줘.
내가 승인한 항목만 하나씩 수정해줘.

18PR 리뷰 요청하기

PR을 만들기 전에는 리뷰어 관점에서 변경사항을 정리하게 합니다.

요청 예시:

PR을 만들기 전에 리뷰어 관점으로 변경사항을 검토해줘.
확인할 것:
1. PR 목적이 명확한지
2. 변경 범위가 너무 크지 않은지
3. 테스트 결과가 충분한지
4. 리뷰어가 집중해야 할 파일
5. 위험한 변경
6. 커밋을 나눠야 하는지
7. PR 설명에 들어갈 내용

PR 설명 템플릿:

## 변경 요약
-

## 리팩터링 목적
-

## 동작 변경 여부
- 없음 / 있음

## 테스트
-

## 리뷰어가 볼 부분
-

## 위험 요소
-

리팩터링 PR에서는 "동작 변경 없음"을 명확히 적는 것이 좋습니다.

19GitHub Actions 기반 코드 리뷰

팀 단위에서는 GitHub Actions로 Claude Code 리뷰를 자동화할 수 있습니다. 초보자 가이드에서는 자동화보다 로컬 흐름을 먼저 익히는 것이 좋습니다.

20CLAUDE.md에 리팩터링·리뷰 규칙 넣기

반복되는 규칙은 CLAUDE.md에 짧게 적어둡니다.

# Refactoring Rules

- 리팩터링은 기존 동작을 유지해야 한다.
- public API, 응답 형식, 에러 메시지는 명시 승인 없이 바꾸지 않는다.
- 큰 리팩터링은 Plan Mode로 계획을 먼저 제시한다.
- 변경은 작은 단계로 나누고 각 단계 후 테스트한다.
- 관련 없는 포맷팅이나 네이밍 변경을 섞지 않는다.
- 커밋 전 git status와 git diff를 검토한다.

# Code Review Rules

- 리뷰는 git diff 기준으로 수행한다.
- Critical, Warning, Suggestion으로 우선순위를 나눈다.
- 보안, 권한, 에러 처리, 테스트 누락을 우선 검토한다.
- 리뷰어 subagent는 기본적으로 읽기 전용으로 둔다.
- 리뷰 항목은 사용자가 승인한 것만 수정한다.

21실전 템플릿: 리팩터링 워크플로우

리팩터링 워크플로우로 진행해줘.
대상:
- 목표:
- 유지해야 할 동작:
- 바꾸면 안 되는 것:
  - public API
  - 응답 형식
  - 에러 메시지
  - 기존 테스트 기대값
진행 규칙:
1. 바로 수정하지 마.
2. 먼저 현재 구조를 요약해줘.
3. 리팩터링 후보와 위험도를 정리해줘.
4. 작은 단계로 계획을 세워줘.
5. 내가 승인하면 1단계만 수정해줘.
6. 각 단계 후 관련 테스트를 실행해줘.
7. git diff로 동작 변경이 섞였는지 검토해줘.
8. 커밋을 나눌 기준을 제안해줘.

복잡한 리팩터링이라면:

ultrathink.
Plan Mode로 먼저 리팩터링 계획을 세워줘.
내가 승인하기 전까지 파일은 수정하지 마.

22실전 템플릿: 코드 리뷰 워크플로우

코드 리뷰 워크플로우로 진행해줘.
대상: 현재 git diff
리뷰 관점:
1. correctness
2. security
3. permission/auth
4. error handling
5. performance
6. maintainability
7. test coverage
8. documentation 필요 여부
출력 형식:
- Critical: 반드시 수정
- Warning: 수정 권장
- Suggestion: 개선 제안
- Question: 확인 필요
- Good: 잘된 점
규칙:
- 파일 수정은 하지 마.
- 리뷰 결과만 제시해줘.
- 각 항목에 근거와 파일 위치를 포함해줘.
- 수정 제안은 구체적으로 하되, 적용은 내가 승인한 뒤에 해줘.

23리팩터링 유형별 프롬프트

중복 코드 제거

중복 validation 로직을 리팩터링하고 싶어.
먼저 중복 위치를 찾아주고,
공통 함수로 분리해도 동작이 유지되는지 분석해줘.
아직 파일은 수정하지 마.

긴 함수 분리

이 함수가 너무 길어.
동작을 유지하면서 책임별로 나눌 수 있는지 계획을 세워줘.
함수 분리 후 테스트해야 할 케이스도 알려줘.

타입 정리

any 타입 사용을 줄이고 싶어.
먼저 any가 사용된 위치를 찾고,
위험도가 낮은 순서로 타입 개선 계획을 제안해줘.
동작 변경은 하지 마.

24리팩터링 유형별 프롬프트 (계속)

에러 처리 개선

에러 처리 패턴을 일관되게 만들고 싶어.
기존 에러 처리 방식을 먼저 조사하고,
새 패턴을 만들지 말고 기존 패턴에 맞춰 개선 계획을 세워줘.

성능 리팩터링

이 코드의 성능을 개선하고 싶어.
먼저 병목 가능성을 분석하고,
측정 방법을 제안해줘.
성능 개선 명목으로 동작을 바꾸지 않도록 주의해줘.

초보자용 리팩터링·코드 리뷰 체크리스트:

리팩터링 목표가 명확한가?
기존 동작 유지 조건을 적었는가?
변경 범위를 파일/폴더 기준으로 제한했는가?
Plan Mode로 계획을 먼저 받았는가?
한 번에 너무 많은 파일을 수정하지 않았는가?
public API, 응답 형식, 에러 메시지를 바꾸지 않았는가?
관련 테스트를 실행했는가?
git diff에서 동작 변경이 섞였는지 확인했는가?
리뷰를 Critical, Warning, Suggestion으로 나눴는가?
보안, 권한, 에러 처리, 테스트 누락을 확인했는가?
리뷰 항목을 한 번에 전부 수정하지 않았는가?
커밋을 나눌 필요가 있는지 확인했는가?

섹션 19 · 마무리

이 단원에서 기억할 것

리팩터링은 기존 동작을 유지하면서 내부 구조를 개선하는 작업입니다. 리팩터링 전에는 Plan Mode로 계획을 먼저 세우는 것이 안전합니다.

변경 범위는 파일, 폴더, public API, 테스트 기준으로 제한해야 합니다. 큰 리팩터링은 작은 테스트 가능한 단계로 나눠 진행합니다.

수정 후에는 반드시 관련 테스트를 실행하고 git diff를 검토합니다. 코드 리뷰는 커밋 전뿐 아니라 계획 단계, 중간 단계, PR 전에도 요청할 수 있습니다.

/code-review는 Claude Code의 bundled skill로 사용할 수 있으며, 초보자는 자동 수정형 리뷰보다 읽기 전용 리뷰를 기본으로 삼는 것이 안전합니다.

보안, 권한, 결제, 개인정보 관련 변경은 별도 보안 리뷰와 Ultra Think를 사용합니다. 반복적인 리뷰는 code-reviewer subagent로 분리할 수 있고, 리뷰어 subagent는 읽기 전용으로 두는 것이 좋습니다.

다음 단원

20단원. 테스트, 린트, 빌드를 Claude와 함께 돌리기

20. 테스트, 린트, 빌드를 Claude와 함께 돌리기

01이 단원에서 배울 것

이 단원의 목표는 Claude Code에게 아래 작업을 안전하게 맡기는 것입니다.

1. 프로젝트의 테스트, 린트, 빌드 명령어를 찾게 한다.
2. 관련 테스트만 먼저 실행한다.
3. 실패 로그에서 첫 번째 원인을 분석하게 한다.
4. lint 오류를 안전하게 고친다.
5. build 실패 원인을 단계적으로 좁힌다.
6. 자동 수정 전에 계획을 먼저 받는다.
7. 수정 후 다시 테스트, 린트, 빌드를 실행한다.
8. 마지막에 git diff로 변경사항을 검토한다.

테스트·린트·빌드는 "마지막에 한 번 돌리는 절차"가 아니라, Claude Code가 수정한 내용이 안전한지 확인하는 검증 루틴입니다.

02명령어를 CLAUDE.md에 적어두기

Claude가 테스트를 실행하려면 프로젝트에서 어떤 명령을 쓰는지 알아야 합니다. 가장 좋은 방법은 CLAUDE.md에 명령어를 적어두는 것입니다.

예시

# Project Commands

## Test
- 전체 테스트: npm test
- auth 테스트: npm test -- auth

## Lint
- npm run lint

## Build
- npm run build

## Type Check
- npm run typecheck

03명령어를 모를 때 찾게 하기

이미 명령어를 모른다면 Claude에게 먼저 찾게 합니다.

이 프로젝트의 테스트, 린트, 빌드 명령어를 찾아줘.

확인할 파일:
- package.json
- README
- Makefile
- pyproject.toml
- composer.json
- Cargo.toml
- docs 폴더

아직 명령은 실행하지 말고,
후보 명령어와 근거만 정리해줘.

명령어를 찾은 뒤에는 실행 전에 안전성을 확인합니다.

찾은 명령어 중 지금 실행해도 안전한 것을 구분해줘.
테스트, 린트, 빌드, 배포/삭제/외부 호출 가능성이 있는 명령을 나눠줘.
아직 실행하지 마.

04테스트는 전체보다 관련 테스트부터

초보자는 기능을 수정한 뒤 바로 전체 테스트를 돌리려는 경우가 많습니다. 하지만 대형 프로젝트에서는 시간이 오래 걸리고 로그도 길어집니다. 먼저 관련 테스트만 실행하는 것이 좋습니다.

언어별 관련 테스트 실행

npm test -- auth

pytest tests/test_auth.py

go test ./internal/auth

Claude에게 요청하기

이번 변경과 관련된 테스트만 먼저 실행해줘.
전체 테스트가 필요하면 그 이유를 설명하고,
실행 전 어떤 명령을 돌릴지 알려줘.

수정 범위가 작다면 더 제한합니다.

수정한 파일과 직접 관련된 테스트만 찾아서 실행해줘.
테스트가 없으면 어떤 테스트를 추가해야 하는지 먼저 제안해줘.

05테스트 실패 로그 분석하기

테스트가 실패하면 Claude에게 전체 로그를 무작정 고치게 하지 않습니다.

나쁜 요청

테스트 실패했어. 다 고쳐줘.

좋은 요청

테스트 실패 로그에서 첫 번째 실패 원인만 분석해줘.
연쇄 실패는 따로 구분하고,
근본 원인과 수정 계획을 먼저 제안해줘.
아직 파일은 수정하지 마.

중요한 원칙

첫 번째 실패부터 본다.
연쇄 실패를 근본 원인으로 착각하지 않는다.

06테스트 실패 분석 템플릿

테스트 실패 로그를 분석할 때는 다음 형식을 사용하면 좋습니다.

테스트 실패를 분석해줘.

실행 명령어:
- npm test -- auth

첫 번째 실패:
- (실패 메시지)

관련 stack trace:
- (스택 추적)

요청:
1. 실패한 테스트가 무엇을 검증하는지 설명해줘.
2. 실제 실패 원인을 추정해줘.
3. 관련 파일 후보를 3개 이하로 제안해줘.
4. 수정 계획을 먼저 제시해줘.
5. 아직 파일은 수정하지 마.

로그가 길면 이렇게 제한합니다.

전체 로그를 다 읽지 말고,
첫 번째 FAIL 블록과 그 주변 stack trace만 기준으로 분석해줘.
추가 로그가 필요하면 어떤 부분이 필요한지 말해줘.

07테스트 실패를 고칠 때의 안전 흐름

테스트 실패를 고칠 때는 아래 순서를 따릅니다.

실패한 테스트가 무엇을 검증하는지 이해한다.
테스트가 맞는지, 구현이 틀린지 구분한다.
원인 후보를 정리한다.
수정 계획을 먼저 받는다.
최소 변경으로 수정한다.
같은 테스트를 다시 실행한다.
관련 테스트까지 확장해서 실행한다.
git diff를 확인한다.

Claude에게 요청하기

이 테스트 실패를 고치기 전에,
테스트 기대값이 맞는지 구현이 틀린지 먼저 판단해줘.
수정이 필요하면 최소 변경 계획을 제시해줘.

테스트 자체가 잘못되었을 수도 있으므로, 바로 구현을 바꾸면 안 됩니다.

테스트를 수정해야 하는 경우와 구현을 수정해야 하는 경우를 비교해줘.
어느 쪽이 더 타당한지 근거를 들어 설명해줘.
아직 수정하지 마.

08Regression Test 추가하기

버그를 고쳤다면 같은 문제가 다시 생기지 않도록 regression test를 추가하는 것이 좋습니다.

이번 버그가 다시 발생하지 않도록 regression test를 추가해줘.

조건:
- 기존 테스트 스타일을 따를 것
- 수정 전에는 실패했을 테스트여야 함
- 수정 후에는 통과해야 함
- 테스트 이름은 버그 상황을 설명해야 함

먼저 테스트 계획을 제안하고,
내가 승인하면 테스트 파일을 수정해줘.

테스트가 없는 프로젝트라면 이렇게 묻습니다.

이 프로젝트에 테스트 구조가 부족해 보여.
이번 변경을 검증할 수 있는 가장 작은 테스트 방법을 제안해줘.
단위 테스트, 통합 테스트, 수동 확인 중 무엇이 적절한지 알려줘.

09린트 실행하기

린트는 코드 스타일, 잠재적 오류, 규칙 위반을 잡는 도구입니다.

일반적인 명령어

npm run lint

pnpm lint

ruff check .

eslint .

Claude에게 요청하기

먼저 명령어를 확인시킵니다.

이 프로젝트의 lint 명령어를 확인해줘.
package.json이나 README에서 근거를 찾고,
아직 실행하지 말고 명령어 후보만 알려줘.

그다음 실행합니다.

lint 명령어를 실행해줘.
실패하면 오류를 유형별로 분류하고,
자동 수정 가능한 것과 사람이 판단해야 하는 것을 구분해줘.

10린트 오류 유형 분류

린트 오류는 보통 다음으로 나뉩니다.

포맷팅

줄바꿈, 세미콜론 — 자동 수정 가능

미사용 변수

unused variable — 삭제 또는 사용 여부 판단

타입 관련

no-explicit-any — 설계 판단 필요

import 순서

sort-imports — 자동 수정 가능

위험 패턴

no-floating-promises — 사람이 검토 필요

11린트 자동 수정은 조심하기

많은 프로젝트에는 자동 수정 명령이 있습니다.

npm run lint -- --fix

eslint . --fix

ruff check . --fix

하지만 자동 수정은 예상보다 많은 파일을 바꿀 수 있습니다. 따라서 먼저 계획을 받습니다.

lint 자동 수정을 하기 전에,
어떤 명령을 실행할지와 어떤 파일이 바뀔 가능성이 있는지 설명해줘.
아직 --fix는 실행하지 마.

실행 후에는 반드시 diff를 봅니다.

lint --fix 실행 후 git diff를 검토해줘.
포맷팅 변경, 실제 로직 변경, 의도하지 않은 변경을 구분해줘.

--fix는 편리하지만, 실행 후 반드시 git diff로 확인합니다.

12빌드 실행하기

빌드는 코드가 실제 배포 가능한 상태인지 확인하는 과정입니다.

일반적인 명령어

npm run build

pnpm build

cargo build

go build ./...

Claude에게 요청하기

이 프로젝트의 build 명령어를 찾아줘.
명령어 후보와 근거를 먼저 보여주고,
내가 승인하면 실행해줘.

빌드 실패 시:

빌드 실패 로그를 분석해줘.
첫 번째 실제 에러를 기준으로 원인을 설명하고,
타입 오류, import 오류, 환경 변수 오류, 설정 오류를 구분해줘.
아직 파일은 수정하지 마.

13빌드 실패 유형 분석

빌드 실패는 보통 다음 유형으로 나뉩니다.

타입 오류

TypeScript compile error — 타입 정의, 반환값 확인

import 오류

module not found — 경로, export, alias 확인

환경 변수 오류

missing env — .env.example, config 확인

의존성 오류

package missing — package.json, lockfile 확인

설정 오류

bundler config error — vite, webpack, tsconfig 확인

테스트 포함 빌드 실패

build script runs tests — 실패 단계 분리

14타입 체크를 따로 실행하기

TypeScript, Python, Rust, Go 같은 프로젝트에서는 빌드 전에 타입 체크를 따로 돌리는 것이 도움이 됩니다.

언어별 타입 체크

npm run typecheck

tsc --noEmit

mypy .

cargo check

Claude에게 요청하기

이 프로젝트에 typecheck 명령어가 있는지 확인해줘.
있다면 build 전에 typecheck를 먼저 실행하는 흐름을 제안해줘.

타입 오류는 린트 오류보다 실제 동작과 더 직접적으로 연결될 수 있습니다.

타입 오류를 분석해줘.
단순 타입 캐스팅으로 덮지 말고,
실제 데이터 구조와 함수 반환값이 맞는지 먼저 확인해줘.

나쁜 수정

any로 바꿔서 통과시켜줘.

좋은 수정

타입 오류를 any로 덮지 말고,
정확한 타입을 추론해서 수정 계획을 제안해줘.

15긴 명령은 배경에서 돌리기

빌드, 전체 테스트, E2E 테스트, 개발 서버는 오래 걸릴 수 있습니다. Claude Code는 background bash command를 지원하며, 명령을 백그라운드로 실행하면 Claude가 즉시 task ID를 받고 다른 요청을 계속 처리할 수 있습니다.

요청 예시

전체 테스트는 오래 걸릴 수 있으니 background로 실행해줘.
진행 중에는 관련 파일을 검토하고,
완료되면 결과 로그를 읽어서 첫 번째 실패만 분석해줘.

직접 shell mode로 빠르게 실행할 수도 있습니다. 입력 앞에 !를 붙이면 Claude를 거치지 않고 shell command를 직접 실행할 수 있습니다.

! npm test

다만 긴 출력은 컨텍스트를 많이 차지하므로, 긴 테스트는 필요한 범위만 실행하거나 결과 요약을 요청하는 것이 좋습니다.

16실행 순서 정하기

일반적인 검증 순서는 다음이 안전합니다.

관련 테스트
lint
typecheck
build
전체 테스트

하지만 프로젝트마다 다를 수 있습니다. Claude에게 순서를 정하게 합니다.

이번 변경을 검증하기 위한 명령 실행 순서를 제안해줘.

고려할 것:
1. 가장 빠른 검증부터
2. 실패 원인을 쉽게 좁힐 수 있는 순서
3. 오래 걸리는 명령은 나중에
4. 전체 테스트는 필요한 경우 마지막
5. 각 명령의 예상 목적

아직 실행하지 마.

빠르고 좁은 검증부터, 느리고 넓은 검증은 마지막에 합니다.

17실패가 여러 개일 때 처리하기

테스트, 린트, 빌드가 모두 실패하면 당황하기 쉽습니다. 이때 한 번에 다 고치면 안 됩니다.

실패가 여러 개 있어도 한 번에 다 고치지 마.
먼저 실패를 유형별로 분류하고,
가장 근본 원인으로 보이는 것 하나만 선택해줘.

분류 순서 가이드

compile/type error

먼저 처리

import/module error

먼저 처리

테스트 assertion 실패

타입 오류 해결 후

lint 포맷팅 오류

나중에 처리

snapshot 실패

변경 의도 확인 후

E2E 실패

단위/빌드 통과 후

Claude에게 요청

실패 로그를 유형별로 분류해줘.
근본 원인일 가능성이 높은 순서로 정리하고,
첫 번째 원인만 수정 계획을 제안해줘.
아직 파일은 수정하지 마.

18자동 수정 전 확인 절차

Claude가 테스트나 lint 실패를 고치려고 할 때, 자동 수정 전에 반드시 계획을 받습니다.

자동 수정 전에 계획을 먼저 보여줘.

포함할 것:
1. 어떤 실패를 고칠 것인지
2. 원인으로 보는 근거
3. 수정할 파일
4. 수정 방식
5. 예상 부작용
6. 수정 후 실행할 명령
7. 되돌리는 방법

내가 승인하기 전까지 파일은 수정하지 마.

수정 승인 후에도 범위를 제한합니다.

계획의 1번 항목만 수정해줘.
다른 실패는 아직 건드리지 마.
수정 후 관련 테스트만 다시 실행해줘.

19Snapshot 테스트는 함부로 업데이트하지 않기

프론트엔드 프로젝트에서는 snapshot 테스트가 실패할 수 있습니다. 이때 자동으로 snapshot을 업데이트하면 실제 UI 변경을 놓칠 수 있습니다.

나쁜 요청

snapshot 업데이트해서 통과시켜줘.

좋은 요청

snapshot 실패 원인을 먼저 분석해줘.
의도한 UI 변경인지, 버그인지, 테스트가 깨진 것인지 구분해줘.
snapshot 업데이트가 필요한 경우 이유를 설명하고,
내가 승인하기 전까지 업데이트하지 마.

snapshot 업데이트 전 확인할 것

UI 변경이 의도된 것인가?
변경된 snapshot이 사용자에게 보이는 동작과 일치하는가?
관련 컴포넌트 테스트가 충분한가?
단순히 실패를 숨기는 업데이트는 아닌가?

20빌드 실패와 환경 변수

빌드 실패가 코드 문제가 아니라 환경 변수 문제일 수 있습니다.

예시

Missing required environment variable: DATABASE_URL

이때 .env를 읽거나 수정하게 하면 위험합니다. 민감 파일은 보호해야 합니다.

Claude에게 요청하기

빌드 실패가 환경 변수 때문인지 확인해줘.
.env 파일은 읽지 말고,
.env.example, README, config schema만 확인해서 필요한 변수 이름을 추정해줘.

좋은 수정 요청

.env 파일은 수정하지 마.
필요하다면 .env.example에 누락된 변수 이름과 설명만 추가하는 계획을 제안해줘.

21Package Lockfile 변경 주의하기

테스트나 빌드를 고치다가 package-lock.json, pnpm-lock.yaml, yarn.lock 같은 lockfile이 바뀔 수 있습니다.

lockfile 변경은 의도적일 수도 있지만, 의존성 설치나 버전 변경이 섞였을 가능성도 있습니다.

lockfile이 변경됐는지 확인해줘.
변경됐다면 왜 바뀌었는지,
이번 작업에 필요한 변경인지 설명해줘.
아직 커밋하지 마.

의존성 설치가 필요한 경우:

새 dependency 설치가 정말 필요한지 먼저 판단해줘.
기존 dependency로 해결할 수 있는지 확인하고,
설치가 필요하다면 이유와 영향 범위를 설명해줘.

테스트를 통과시키기 위해 새 패키지를 설치하기 전에 반드시 이유를 확인합니다.

22Hooks로 자동화하기

테스트, 린트, 포맷팅은 반복 작업입니다. 반복되는 검증은 hooks로 자동화할 수 있습니다.

hooks는 Claude Code lifecycle의 특정 시점에 실행되는 사용자 정의 shell command입니다. 예를 들어 파일 편집 후 포맷팅, 명령 실행 전 차단, 완료 시 검증 등을 자동화할 수 있습니다.

파일 수정 후 포맷팅 자동화

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

초보자는 처음부터 복잡한 hook을 만들기보다 아래 정도부터 시작합니다.

1️⃣Edit/Write 후 formatter 실행

2️⃣완료 전 관련 lint 실행

3️⃣위험한 명령 차단

4️⃣Claude가 입력을 기다릴 때 알림

23Hooks는 신중하게 적용하기

hooks는 강력하지만 잘못 설정하면 작업 흐름을 망칠 수 있습니다.

위험한 예

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm test"
          }
        ]
      }
    ]
  }
}

파일을 한 번 수정할 때마다 전체 테스트가 실행되면 너무 느려질 수 있습니다.

더 안전한 접근

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --quiet"
          }
        ]
      }
    ]
  }
}

또는 팀 규칙으로 이렇게 정합니다.

formatter는 자동 실행 가능.
전체 테스트와 build는 사용자가 승인한 뒤 실행.

24CLAUDE.md에 검증 규칙 넣기

반복되는 테스트·린트·빌드 규칙은 CLAUDE.md에 적어둡니다.

# Verification Workflow

## Commands
- Test related files first: npm test -- 
- Full test: npm test
- Lint: npm run lint
- Type check: npm run typecheck
- Build: npm run build

## Rules
- 수정 후 관련 테스트를 먼저 실행한다.
- 전체 테스트는 관련 테스트가 통과한 뒤 실행한다.
- lint --fix는 실행 전 사용자 승인을 받는다.
- snapshot update는 원인을 설명하고 승인받은 뒤 실행한다.
- build 실패 시 첫 번째 실제 에러부터 분석한다.
- .env 파일은 읽거나 수정하지 않는다.
- 커밋 전 git status와 git diff를 요약한다.

25전체 프롬프트 템플릿

아래 템플릿은 기능 구현이나 버그 수정 후 그대로 사용할 수 있습니다.

검증 워크플로우로 진행해줘.

이번 변경:
- (수정 내용)

진행 순서:
1. 관련 테스트 명령어를 찾아줘.
2. 관련 테스트만 먼저 실행해줘.
3. 실패하면 첫 번째 실패 원인만 분석해줘.
4. lint 명령어를 확인하고 실행해줘.
5. lint 실패는 자동 수정 가능/판단 필요로 나눠줘.
6. typecheck가 있으면 실행해줘.
7. build 명령어를 확인하고 실행해줘.
8. 전체 테스트가 필요한지 판단해줘.
9. 마지막에 git status와 git diff를 검토해줘.

규칙:
- 명령 실행 전 어떤 명령을 실행할지 알려줘.
- 자동 수정은 내가 승인하기 전까지 하지 마.
- lint --fix, snapshot update, dependency install은 승인 없이 실행하지 마.
- .env 파일은 읽거나 수정하지 마.

26초보자용 체크리스트

마지막으로 20단원의 핵심을 체크리스트로 정리합니다.

테스트, 린트, 빌드 명령어를 CLAUDE.md에 적었는가?

☐

명령어를 실행하기 전에 Claude가 무엇을 실행할지 설명했는가?

☐

이 단원에서 기억할 것

테스트, 린트, 빌드는 Claude Code가 만든 변경사항을 검증하는 핵심 루틴입니다. 먼저 프로젝트의 테스트·린트·빌드 명령어를 CLAUDE.md에 적어두는 것이 좋습니다.

명령어를 모르면 Claude에게 package.json, README, Makefile 등을 확인하게 하고, 실행 전 후보와 근거를 먼저 받습니다. 테스트는 전체 테스트보다 관련 테스트부터 실행하며, 실패 로그는 첫 번째 실제 실패부터 분석하고 연쇄 실패와 근본 원인을 구분합니다.

lint 오류는 자동 수정 가능한 것과 사람이 판단해야 하는 것으로 나누고, lint --fix, snapshot update, dependency install은 승인 없이 실행하지 않습니다. build 실패는 타입, import, 환경 변수, 의존성, bundler 설정 문제로 나누어 분석합니다.

긴 테스트나 빌드는 background command로 실행하고, hooks를 통해 자동화할 수 있으며, 마지막에는 항상 git status와 git diff로 의도하지 않은 변경을 확인합니다.

다음 단원

21단원. Slash Commands와 단축키로 빠르게 작업하기

21. Slash Commands와 단축키로 빠르게 작업하기

01Slash Command는 "대화 중 조작 버튼"이다

Claude Code를 처음 쓰는 사람은 모든 것을 문장으로 요청하려고 합니다.

지금까지 대화가 너무 길어진 것 같은데 중요한 내용만 남기고 정리해줘.

하지만 Claude Code에는 같은 목적을 더 짧게 실행하는 명령이 있습니다.

/compact

즉, slash command는 반복되는 조작을 짧게 실행하는 버튼에 가깝습니다.

일반 프롬프트 vs Slash Command

목적

일반: Claude에게 작업을 설명 | Command: Claude Code 기능을 직접 실행

예시

일반: "현재 모델을 바꿔줘" | Command: /model

장점

일반: 유연함 | Command: 빠르고 일관적

사용 시기

일반: 작업 설명 | Command: 세션·설정·비용 제어

초보자는 모든 명령을 외울 필요가 없습니다. /help, /usage, /model, /status, /context, /compact, /clear, /diff, /permissions, /config 정도만 익히면 충분합니다.

02가장 먼저 외울 명령어 10개

/usage는 세션 비용, 플랜 사용량, 활동 통계를 보여주는 중심 명령입니다. /cost와 /stats는 /usage의 별칭으로 기존 사용자에게 친숙합니다.

/help

명령어가 기억나지 않을 때 | 사용 가능한 명령 목록 확인

/status

현재 상태 확인 | 버전, 모델, 계정, 연결 상태 확인

/usage

비용·사용량 확인 | 토큰, 비용, 플랜 사용량 확인

/model

모델 변경 | 작업 난이도에 따라 모델 전환

/effort

추론 강도 조절 | 모델이 깊게 생각할지 조절

/context

컨텍스트 사용량 확인 | 대화창이 얼마나 찼는지 확인

/compact

대화 압축 | 중요 내용만 요약해 컨텍스트 축소

/clear

새 대화 시작 | 이전 세션 남기고 현재 컨텍스트 비우기

/config

설정 변경 | 테마, 모델, 출력 스타일 등 조정

/permissions

권한 관리 | Bash, Edit, Write 허용 범위 변경

03세션 관리 명령어

Claude Code는 한 번의 채팅이 아니라 "작업 세션"으로 움직입니다. 세션을 이어가거나, 새로 시작하거나, 되돌리는 명령을 알아야 합니다.

/clear [name]

새 대화 시작 | 예: /clear auth-fix-before-refactor

/resume [session]

이전 대화로 돌아가기 | 예: /resume

/rename [name]

현재 세션 이름 지정 | 예: /rename payment-bug-fix

/branch [name]

현재 대화 분기 | 예: /branch alternate-approach

/rewind

이전 지점으로 되돌리기 | 예: /rewind

/export [filename]

대화 내보내기 | 예: /export session-notes.md

/exit

세션 종료 | 예: /exit

초보자에게 가장 중요한 것은 /clear와 /resume입니다. 새 작업을 시작할 때는 /clear로 컨텍스트를 비우고, 이전 작업으로 돌아가야 할 때는 /resume을 사용합니다.

실전 예시

/rename login-bug-investigation
/context
/compact focus on login bug root cause and files already inspected
/clear payment-refactor-start

04비용, 모델, 추론 강도 확인 명령어

Claude Code는 세션이 길어질수록 컨텍스트와 비용이 커질 수 있습니다. 비용·모델·추론 강도 명령은 자주 써야 합니다.

/usage

사용량과 비용 확인 | 긴 작업 전후에 확인

/cost

/usage 별칭 | 기존 습관 있으면 사용 가능

/model

모델 변경 | 복잡한 설계·디버깅 전 확인

/effort

추론 강도 변경 | 어려운 문제는 높이고, 단순 편집은 낮춤

/fast

빠른 응답 모드 전환 | 속도가 더 중요할 때 사용

/context

컨텍스트 사용량 확인 | 50% 이상부터 신경 쓰기 시작

초보자용 판단 기준

단순 질문 → 현재 모델 그대로
작은 수정 → 현재 모델 + 낮은 effort
복잡한 버그 → 좋은 모델 + 높은 effort
대형 리팩터링 → /plan 먼저, 필요하면 모델·effort 조정
긴 세션 → /context 확인 후 /compact 또는 /clear

/model은 모델 선택기를 열거나 지정한 모델로 전환하며, /effort는 low, medium, high, xhigh, max, auto 같은 추론 강도 선택에 사용됩니다.

05설정과 권한 확인 명령어

Claude Code는 파일을 읽고, 수정하고, 명령어를 실행할 수 있습니다. 그래서 빠른 작업보다 중요한 것이 "안전한 작업"입니다.

/config

전체 설정 UI 열기 | 모델, 테마, 출력 스타일 변경 시

/settings

/config 별칭 | 설정을 열 때

/permissions

권한 규칙 관리 | Bash, Edit, Write 허용 범위 변경

/allowed-tools

/permissions 별칭 | 허용 도구 관리 시

/status

현재 상태 확인 | 계정, 모델, 연결 상태, 버전 확인

/doctor

설치·환경 진단 | 이상 동작, 인증, 설정 문제 확인

/terminal-setup

터미널 키 설정 | Shift+Enter 등이 동작 안 할 때

초보자 권장 습관

새 프로젝트 시작 → /status
권한이 너무 자주 물어봄 → /permissions
터미널 입력이 불편함 → /terminal-setup
설치나 인증이 이상함 → /doctor

06개발 작업에서 자주 쓰는 명령어

이전 단원에서 배운 테스트, 린트, 빌드, 리뷰 흐름과 연결되는 명령어들입니다.

/plan [description]

Plan Mode 진입 | 대형 수정 전 계획부터 세울 때

/diff

변경사항 확인 | Claude 수정 후 검토할 때

/code-review

코드 리뷰 | diff의 버그·정확성 문제 찾을 때

/code-review --fix

리뷰 결과 적용 | 발견사항을 working tree에 반영

/security-review

보안 리뷰 | 인증, 입력값, 민감정보 관련 변경 전

/init

CLAUDE.md 초기화 | 프로젝트 규칙 파일 생성 시

/memory

메모리 관리 | CLAUDE.md와 자동 메모리 관리 시

/mcp

MCP 연결 관리 | GitHub, DB, 외부 도구 연결 전

/hooks

hook 설정 확인 | 자동 포맷팅·검사 흐름 볼 때

실전 작업 흐름

/init
/plan add validation to signup form
/diff
/code-review high
/usage

07빠른 입력 접두사: `/`, `!`, `@`

Claude Code에서는 /만 중요한 것이 아닙니다. 입력의 맨 앞이나 중간에서 자주 쓰는 접두사가 있습니다.

접두사

의미와 예시

slash command 실행 | 예: /context

shell command 실행 | 예: ! git status

파일 경로 참조 | 예: @src/auth.ts

실전 사용법

Git 상태를 Claude 대화 안에 포함해 확인하고 싶다면:

! git status

특정 파일을 가리키며 질문하려면:

@src/auth.ts 이 파일의 인증 흐름을 초보자도 이해할 수 있게 설명해줘.

08단축키는 "작업 속도"보다 "흐름 유지"가 중요하다

단축키는 많이 외우는 것보다 자주 끊기는 순간을 줄이는 데 목적이 있습니다.

Ctrl+C

현재 작업 중단 또는 입력 지우기 | Claude 잘못 가고 있을 때 멈춤

Esc

응답 또는 도구 호출 중단 | 중간에 방향 바꿀 때

Ctrl+D

세션 종료 | EOF로 종료

Ctrl+L

화면 다시 그리기 | 터미널 화면 깨졌을 때

Ctrl+O

transcript viewer 토글 | 도구 사용 내역 자세히 보기

Ctrl+R

명령 기록 검색 | 예전에 쓴 프롬프트 찾기

Ctrl+B

실행 중 작업 백그라운드 전환 | 긴 작업 뒤로 보내고 계속

Ctrl+T

task list 토글 | 진행 중 작업 목록 보기

Shift+Tab / Alt+M

권한 모드 순환 | normal, accept edits, plan 등 모드 전환

Alt/Option+P

모델 전환 | 프롬프트 지우지 않고 모델 변경

Alt/Option+T

extended thinking 토글 | 어려운 문제에서 깊은 추론

Alt/Option+O

fast mode 토글 | 빠른 응답 모드 전환

단축키는 플랫폼과 터미널에 따라 달라질 수 있습니다. macOS에서 Option/Alt 계열 단축키를 제대로 쓰려면 터미널에서 Option을 Meta 키로 설정해야 하는 경우가 있습니다.

09프롬프트 편집 단축키

긴 프롬프트를 작성할 때는 커서를 움직이고, 일부를 지우고, 다시 붙여넣는 단축키가 유용합니다.

Ctrl+A

현재 줄의 시작으로 이동

Ctrl+E

현재 줄의 끝으로 이동

Ctrl+K

커서부터 줄 끝까지 삭제

Ctrl+U

커서부터 줄 시작까지 삭제

Ctrl+W

이전 단어 삭제

Ctrl+Y

삭제한 텍스트 붙여넣기

Alt+B

한 단어 뒤로 이동

Alt+F

한 단어 앞으로 이동

Windows에서는 Ctrl+Backspace도 이전 단어 삭제로 동작합니다.

10여러 줄 입력 방법

Claude Code에서 Enter는 기본적으로 메시지를 제출합니다. 여러 줄 프롬프트를 작성하려면 별도 입력법을 사용합니다.

Ctrl+J

모든 터미널에서 안전한 방법

+ Enter

모든 터미널에서 동작하는 이스케이프 방식

Shift+Enter

지원 터미널에서 동작

Option+Enter

macOS Option 설정 후 동작

Shift+Enter는 대부분의 최신 터미널에서 동작하지만, VS Code, Cursor, Windsurf, Alacritty, Zed에서는 /terminal-setup을 먼저 실행해야 할 수 있습니다.

초보자 권장 순서

1순위: Shift+Enter
안 되면: Ctrl+J
그래도 헷갈리면: \ + Enter

11단축키를 바꾸고 싶다면 `/keybindings`

기본 단축키가 손에 맞지 않거나 터미널과 충돌하면 /keybindings를 사용합니다.

/keybindings

사용자 지정 단축키는 Claude Code v2.1.18 이상에서 사용할 수 있습니다. /keybindings를 실행하면 ~/.claude/keybindings.json 파일을 만들거나 열 수 있습니다. 이 파일의 변경사항은 Claude Code를 재시작하지 않아도 자동 감지되어 적용됩니다.

초보자는 처음부터 단축키를 많이 바꾸지 않는 편이 좋습니다. 먼저 기본 단축키에 익숙해지고, 정말 자주 충돌하는 것만 바꿈으로써 손가락 기억을 형성하는 것이 효율적입니다.

12Custom slash command는 이제 Skills와 연결해서 이해한다

예전 자료에서는 custom slash command를 .claude/commands/에 만드는 방식으로 설명하는 경우가 많습니다. 최신 공식 문서에서는 custom command가 skills로 통합되었습니다.

.claude/commands/deploy.md 파일과 .claude/skills/deploy/SKILL.md는 둘 다 /deploy를 만들며, 기존 .claude/commands/ 파일도 계속 동작합니다. 다만 새로 만들 때는 skills 방식이 더 확장성이 좋습니다.

개념 정리

반복 프롬프트를 짧게 호출

slash command

팀의 전문 지식과 절차 재사용

skill

큰 작업을 분리해서 맡김

subagent

Slash command는 사용자가 직접 호출하는 명시적 작업에 적합하고, skill은 Claude가 상황에 맞게 자동으로 적용하는 전문 지식, subagent는 별도 컨텍스트에서 처리할 작업에 적합합니다.

13초보자용 필수 명령어 표

상황

명령어 → 다음 행동

명령어 기억 안 남

/help → 목록에서 검색

현재 모델·계정·버전

/status → 이상하면 /doctor

비용 확인

/usage → 너무 크면 /compact 또는 /clear

대화 길어짐

/context → 필요하면 /compact

새 작업 시작

/clear → 이전 작업 이름 붙여 저장

대형 수정 전

/plan → 계획 승인 후 실행

수정 결과 확인

/diff → 문제 있으면 리뷰 요청

코드 품질 확인

/code-review → 필요하면 --fix

보안 검토

/security-review → 인증·권한·입력값 변경 시

설정 변경

/config → 모델, 테마, 출력 스타일

권한 불편

/permissions → allow, ask, deny 규칙 조정

터미널 입력 문제

/terminal-setup → Shift+Enter 등 설정

단축키 변경

/keybindings → 충돌나는 키만 수정

14실전 루틴: 하루 작업 시작부터 마무리까지

작업 시작

/status
/usage
/context

현재 상태, 비용, 컨텍스트를 확인합니다.

큰 작업 전

/plan implement password reset flow

계획을 먼저 받고, 파일 수정 범위를 확인합니다.

작업 중

@src/auth.ts 비밀번호 재설정 흐름과 관련된 부분만 확인해줘.
! npm test

필요한 파일만 참조하고, 테스트 결과를 대화에 포함합니다.

수정 후

/diff
/code-review high

변경사항을 확인하고 리뷰를 받습니다.

마무리

/usage
/compact focus on final implementation summary and remaining risks

비용을 확인하고, 다음 세션에서 이어갈 핵심 내용을 남깁니다.

섹션 21 · 마무리

이 단원에서 기억할 것

Slash command는 Claude Code를 빠르게 조작하는 명령 체계입니다. 모든 명령을 외울 필요 없이 자주 쓰는 것부터 시작하면 됩니다.

설정·비용·컨텍스트 제어는 slash command로, 작업은 일반 프롬프트로 나눈다.

단축키는 작업 속도를 높이는 기능이지만, 더 중요한 목적은 흐름을 끊지 않는 것입니다. 기본 단축키에 익숙해진 뒤 필요한 것만 커스터마이징하면 충분합니다.

최신 기준으로는 비용 확인을 /usage 중심으로 설명하고, /cost는 별칭으로 안내합니다. Custom slash command는 별도 독립 기능보다 skills와 연결해서 이해하는 것이 현재 공식 문서 흐름에 맞습니다.

다음 단원

22단원. 프롬프트 엔지니어링 기초 — 좋은 질문의 기술

22. Hooks로 반복 작업 자동화하기

01Hooks는 "Claude에게 부탁하는 것"이 아니라 "반드시 실행되는 규칙"이다

Claude에게 이렇게 말할 수 있습니다.

파일을 수정한 뒤에는 항상 prettier를 실행해줘.

하지만 이건 프롬프트입니다. Claude가 대화 흐름 속에서 기억하고 실행해야 합니다. 세션이 길어지거나 컨텍스트가 압축되면 빠뜨릴 수 있습니다.

Hooks는 다릅니다. Claude가 파일을 수정한 뒤 자동으로 prettier를 실행합니다. Claude가 "기억해서 실행하는 것"이 아니라 Claude Code가 정해진 이벤트에서 반드시 실행합니다.

Hook의 핵심 장점: LLM이 선택해서 실행하기를 기대하는 대신, 특정 행동이 항상 일어나도록 보장하는 결정론적 제어

02프롬프트와 hooks의 차이

실행 주체

프롬프트: Claude의 판단 | Hook: Claude Code의 이벤트 시스템

실행 보장

프롬프트: 보장되지 않음 | Hook: 조건이 맞으면 자동 실행

적합한 작업

프롬프트: 설명, 계획, 리뷰, 판단 | Hook: 포맷팅, 검사, 로그, 차단, 알림

예시

프롬프트: "테스트도 같이 돌려줘" | Hook: 파일 수정 후 npm test 자동 실행

위험

프롬프트: 잊을 수 있음 | Hook: 잘못 만들면 매번 실행되어 방해될 수 있음

기준은 단순합니다.

한 번만 부탁할 일 → 프롬프트 | 매번 반드시 실행돼야 할 일 → Hook | 상황에 따라 판단이 필요한 일 → 프롬프트 + Hook 또는 agent hook

초보자는 먼저 shell command로 동작하는 command hook부터 익히면 됩니다.

03Hook이 실행되는 대표 시점

Hook은 Claude Code의 특정 이벤트에 붙습니다. 초보자는 아래 6개만 먼저 알면 됩니다.

SessionStart

세션 시작 또는 재개 시 → 프로젝트 컨텍스트 다시 주입

UserPromptSubmit

사용자가 프롬프트를 제출했을 때 → 현재 브랜치 정보 추가

PreToolUse

도구 실행 전 → 위험한 명령 차단

PostToolUse

도구 실행 성공 후 → 포맷팅, lint, 로그

Notification

Claude가 알림을 보낼 때 → 입력 대기 알림

Stop

Claude가 응답을 끝내려 할 때 → 테스트 통과 여부 확인

공식 hook reference는 더 많은 이벤트를 제공합니다. 예를 들어 PostToolUseFailure, PostToolBatch, SubagentStart, SubagentStop, ConfigChange, CwdChanged, FileChanged, PreCompact, PostCompact, SessionEnd 등이 있습니다. 하지만 초보자용 가이드에서는 PreToolUse와 PostToolUse를 중심으로 학습하는 것이 좋습니다.

04Hook 설정 위치

프로젝트에서 사용할 hook은 보통 프로젝트 루트의 .claude/settings.json에 넣습니다.

my-project/
├── .claude/
│   ├── settings.json
│   └── hooks/
│       └── protect-files.sh
├── src/
└── package.json

설정 기본 구조입니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'file edited'"
          }
        ]
      }
    ]
  }
}

/hooks 명령으로 현재 등록된 hooks를 읽기 전용으로 확인할 수 있습니다. 수정은 settings JSON 파일에서 합니다.

05Hook 설정을 읽는 법

다음 설정을 한 줄씩 해석해봅시다.

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

PostToolUse

도구가 성공적으로 실행된 뒤

matcher: Edit|Write

Claude가 파일을 수정하거나 새로 썼을 때만

type: command

shell command를 실행

command

실제 실행할 명령어

matcher는 hook이 실행될 대상을 좁히는 필터입니다. Bash는 Bash 도구에만, Edit|Write는 파일 수정 도구에만, mcp__github__.*는 GitHub MCP 도구에만 매칭할 수 있습니다. MCP tool 이름은 mcp__<server>__<tool> 형식을 따릅니다.

06초보자용 첫 번째 hook: 파일 수정 후 자동 포맷팅

가장 쉬운 hook은 "Claude가 파일을 수정하면 자동으로 formatter를 실행하기"입니다.

.claude/settings.json에 다음을 추가합니다.

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

이 hook은 Claude가 파일을 수정한 뒤 수정된 파일 경로를 꺼내 prettier --write에 넘깁니다. 주의할 점은 jq가 필요하다는 것입니다. macOS는 brew install jq, Ubuntu/Debian은 apt-get install jq로 설치할 수 있습니다.

07조금 더 안전한 포맷팅 hook

초보자용으로는 command를 너무 길게 쓰는 것보다 script 파일로 분리하는 편이 좋습니다.

먼저 파일을 만듭니다.

mkdir -p .claude/hooks
touch .claude/hooks/format-edited-file.sh
chmod +x .claude/hooks/format-edited-file.sh

.claude/hooks/format-edited-file.sh

#!/usr/bin/env bash
set -euo pipefail

input="$(cat)"
file_path="$(echo "$input" | jq -r '.tool_input.file_path // empty')"

if [ -z "$file_path" ]; then
  exit 0
fi

case "$file_path" in
  *.js|*.jsx|*.ts|*.tsx|*.json|*.md|*.css)
    npx prettier --write "$file_path"
    ;;
esac

그다음 .claude/settings.json에 연결합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format-edited-file.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

Hook script를 프로젝트 기준으로 안정적으로 참조하려면 ${CLAUDE_PROJECT_DIR}를 사용하면 됩니다.

08보안 hook: 민감한 파일 수정 막기

Hooks는 자동화뿐 아니라 안전장치로도 쓸 수 있습니다. 예를 들어 Claude가 .env, .git, package-lock.json 같은 파일을 수정하지 못하게 막을 수 있습니다.

.claude/hooks/protect-files.sh

#!/usr/bin/env bash
set -euo pipefail

input="$(cat)"
file_path="$(echo "$input" | jq -r '.tool_input.file_path // empty')"

if [ -z "$file_path" ]; then
  exit 0
fi

case "$file_path" in
  *.env|*.env.*|.env|.git/*|package-lock.json|pnpm-lock.yaml|yarn.lock|*.pem|*.key)
    echo "Blocked by project hook: protected file cannot be edited: $file_path" >&2
    exit 2
    ;;
esac

exit 0

실행 권한을 줍니다.

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

그다음 .claude/settings.json에 연결합니다.

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

여기서는 PreToolUse를 사용합니다. 파일이 수정된 뒤가 아니라, 수정되기 전에 검사해야 하기 때문입니다.

09Exit code를 이해해야 한다

Command hook은 종료 코드로 Claude Code에 결과를 알려줍니다.

성공 → 계속 진행

차단 → 이 작업을 막음

그 외

비차단 오류 → hook 오류로 기록되지만 작업은 계속될 수 있음

다만 모든 이벤트가 같은 방식으로 차단되는 것은 아닙니다. PreToolUse에서 exit code 2를 반환하면 도구 실행 전이므로 차단할 수 있습니다. 반면 PostToolUse는 이미 도구가 실행된 뒤라 같은 방식으로 되돌릴 수 없습니다.

초보자는 이렇게 기억하면 됩니다.

막고 싶다 → PreToolUse | 끝난 뒤 처리하고 싶다 → PostToolUse | Claude가 멈추기 전에 확인하고 싶다 → Stop | 알림을 받고 싶다 → Notification

10Lint hook: 수정 후 검사하기

포맷팅은 자동 수정이 가능하지만, lint나 typecheck는 시간이 오래 걸릴 수 있습니다. 처음에는 가벼운 검사부터 붙이는 것이 좋습니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --quiet"
          }
        ]
      }
    ]
  }
}

하지만 이 설정은 파일을 하나 수정할 때마다 전체 lint가 실행되어 느려질 수 있습니다.

작은 프로젝트

수정 후 전체 lint 실행 가능

중간 프로젝트

변경 파일만 포맷팅, lint는 수동 실행

큰 프로젝트

async hook 또는 별도 CI에 맡김

팀 프로젝트

hook은 최소화하고 CI를 최종 기준으로 사용

11비동기 hook: 오래 걸리는 작업은 뒤에서 돌리기

기본적으로 hook은 완료될 때까지 Claude의 실행을 막습니다. 테스트나 외부 API 호출처럼 오래 걸리는 작업은 작업 흐름을 느리게 만들 수 있습니다.

이럴 때는 async: true를 사용할 수 있습니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/run-tests-async.sh",
            "args": [],
            "async": true,
            "timeout": 300
          }
        ]
      }
    ]
  }
}

Async hook은 Claude의 실행을 막지 않고 백그라운드에서 실행됩니다. 다만 이미 작업이 진행된 뒤 완료되므로, tool call을 차단하거나 permission decision을 반환하는 용도로는 사용할 수 없습니다.

반드시 끝나야 다음 단계로 가야 함 → async 사용 금지 | 알림, 로그, 백그라운드 테스트 → async 가능 | 위험한 명령 차단 → 반드시 동기 PreToolUse

12알림 hook: Claude가 입력을 기다릴 때 알려주기

Claude가 권한 승인이나 다음 입력을 기다릴 때 알림을 보내도록 만들 수 있습니다.

macOS 예시:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'"
          }
        ]
      }
    ]
  }
}

Linux 예시:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

Notification hook의 matcher를 비워두면 모든 notification type에 반응합니다. 특정 상황만 받고 싶다면 permission_prompt, idle_prompt, auth_success 같은 matcher를 사용할 수 있습니다.

13컨텍스트 보강 hook: 압축 후 중요한 규칙 다시 넣기

세션이 길어지면 /compact 또는 자동 compaction으로 대화가 요약됩니다. 이때 중요한 프로젝트 규칙이 약해질 수 있습니다.

예를 들어 압축 후마다 다음 내용을 다시 넣을 수 있습니다.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

SessionStart hook에 compact matcher를 붙이면 compaction 이후 중요한 컨텍스트를 다시 주입할 수 있습니다. 다만 정적인 프로젝트 규칙은 hook보다 CLAUDE.md에 두는 편이 낫습니다.

14Hook 입력은 JSON이다

Hook script는 Claude Code로부터 JSON을 stdin으로 받습니다.

예를 들어 Bash 실행 전 hook은 이런 입력을 받을 수 있습니다.

{
  "session_id": "abc123",
  "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
  "cwd": "/home/user/my-project",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

그래서 shell script에서는 보통 이렇게 시작합니다.

input="$(cat)"
tool_name="$(echo "$input" | jq -r '.tool_name // empty')"
command="$(echo "$input" | jq -r '.tool_input.command // empty')"
file_path="$(echo "$input" | jq -r '.tool_input.file_path // empty')"

15위험한 Bash 명령 차단하기

이번에는 rm -rf 같은 위험한 명령을 막는 hook입니다.

.claude/hooks/block-dangerous-bash.sh

#!/usr/bin/env bash
set -euo pipefail

input="$(cat)"
command="$(echo "$input" | jq -r '.tool_input.command // empty')"

if echo "$command" | grep -Eq 'rm[[:space:]]+-rf|sudo|chmod[[:space:]]+777|curl .* | sh|wget .* | sh'; then
  echo "Blocked by hook: dangerous bash command: $command" >&2
  exit 2
fi

exit 0

.claude/settings.json에 PreToolUse로 연결합니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-dangerous-bash.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

공식 reference는 PreToolUse hook에서 Bash 명령을 검사하고 permissionDecision: "deny"를 반환하는 구조화 JSON 방식도 보여줍니다. 초보자에게는 먼저 exit code 2 방식이 이해하기 쉽고, 이후 더 세밀한 제어가 필요할 때 JSON output으로 넘어가면 됩니다.

16Hook과 권한 시스템은 함께 써야 한다

Hooks는 권한 시스템을 대체하지 않습니다. 권한 시스템은 "Claude가 어떤 도구를 쓸 수 있는지"를 관리하고, hooks는 "특정 상황에서 무엇을 자동 실행하거나 차단할지"를 관리합니다.

.env 읽기 자체를 막기

permissions deny

.env 수정 시도도 막기

PreToolUse hook

파일 수정 후 prettier 실행

PostToolUse hook

Bash 명령을 실행 전 검사

PreToolUse hook

승인 요청을 자동 처리

PermissionRequest hook

팀 전체 정책 강제

managed settings + permissions + hooks

Hooks를 추가하더라도 권한 설정은 계속 중요합니다.

17Prompt hook과 agent hook은 언제 쓰나

대부분의 초보자는 command hook만으로 충분합니다. 하지만 어떤 자동화는 단순한 shell 조건으로 판단하기 어렵습니다.

예를 들어 "Claude가 작업을 끝냈다고 말했는데, 실제로 요청한 모든 일을 끝낸 게 맞나?"는 단순 grep만으로 판단하기 어렵습니다. 이럴 때 prompt hook이나 agent hook을 쓸 수 있습니다.

command

shell command 실행 → 가장 먼저 배울 것

prompt

빠른 LLM 판단 → 간단한 yes/no 판단

agent

도구 접근이 있는 subagent 검증 → 파일을 읽고 검사해야 할 때

http

외부 URL 호출 → 알림, webhook, 내부 API

mcp_tool

연결된 MCP tool 호출 → MCP를 이미 쓰는 팀

Agent hook은 실험적이며 production workflow에서는 command hook을 우선하는 것이 좋습니다.

18잘못 설정했을 때의 위험

Hooks는 강력하지만 위험합니다. 특히 command hook은 사용자 계정 권한으로 shell command를 실행합니다. 설정에 넣기 전에 반드시 검토하고 테스트해야 합니다.

모든 파일 수정마다 전체 테스트 실행

세션이 매우 느려짐

rm, mv, chmod 같은 명령을 hook에 직접 넣음

파일 손상 가능

변수에 따옴표를 안 씀

공백·특수문자 경로에서 오작동

.env 내용을 stdout으로 출력

민감정보가 transcript에 남을 수 있음

PostToolUse에서 차단하려 함

이미 실행된 뒤라 막기 어려움

hook 출력을 JSON으로 내면서 다른 echo도 섞음

JSON 파싱 실패 가능

팀 공유 설정에 개인 경로 사용

다른 사람 환경에서 실패

너무 많은 hook을 한꺼번에 추가

원인 추적이 어려움

공식 보안 권장사항도 입력값 검증, shell 변수 quoting, path traversal 차단, 절대 경로 사용, 민감 파일 회피를 강조합니다.

19Hook 디버깅 방법

Hook이 작동하지 않으면 먼저 /hooks로 등록 여부를 확인합니다.

/hooks

그다음 debug log를 켭니다.

claude --debug-file /tmp/claude.log

다른 터미널에서 로그를 봅니다.

tail -f /tmp/claude.log

Hook 실행 세부 정보, 매칭된 hook, exit code, stdout, stderr는 debug log에 기록됩니다. 디버깅 순서는 다음과 같습니다.

/hooks에서 hook이 보이는지 확인
matcher가 맞는지 확인
script에 실행 권한이 있는지 확인
jq가 설치되어 있는지 확인
command를 터미널에서 직접 실행
claude --debug-file로 stdout/stderr 확인

20초보자용 추천 hook 조합

처음부터 복잡한 자동화를 만들지 말고, 아래 순서로 늘리는 것이 좋습니다.

1단계: 알림만 추가

{
  "hooks": {
    "Notification": [
      { "matcher": "", "hooks": [{ "type": "command", "command": "echo 'Claude Code needs attention' >&2" }] }
    ]
  }
}

2단계: 파일 수정 후 포맷팅

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format-edited-file.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

3단계: 민감 파일 보호

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

4단계: 위험한 Bash 명령 차단

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-dangerous-bash.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

이 네 가지면 초보자에게 필요한 자동화의 대부분을 커버합니다.

21실전 워크플로우 예시

상황: Claude에게 기능 추가를 맡긴다

회원가입 폼에 이메일 형식 검증과 에러 메시지를 추가해줘.
수정 전 관련 파일을 먼저 찾고, 계획을 설명한 뒤 진행해.

Hook이 없는 경우

Claude가 파일을 수정한 뒤 사용자가 직접 포맷팅, lint, 테스트, diff 확인을 해야 합니다.

npx prettier --write src/...
npm run lint
npm test
git diff

Hook이 있는 경우

1Claude Edit/Write

2PostToolUse hook 자동 실행

3prettier 자동 포맷팅

4필요하면 lint/test 수동 실행

보호 파일을 수정하려고 하면 hook이 차단합니다.

1Claude Edit .env

2PreToolUse hook → protect-files.sh

3exit 2 → 수정 차단

이것이 hooks의 핵심입니다. 반복 작업은 자동으로 돌리고, 위험한 작업은 실행 전에 막습니다.

섹션 22 · 마무리

이 단원에서 기억할 것

Hooks는 Claude Code의 반복 작업 자동화 장치입니다. 프롬프트는 Claude에게 "해달라"고 부탁하는 것이고, hook은 특정 이벤트에서 "반드시 실행되도록 설정하는 것"입니다.

초보자는 먼저 PostToolUse로 파일 수정 후 포맷팅을 자동화하고, PreToolUse로 민감 파일 수정과 위험한 Bash 명령을 차단하는 것부터 시작하면 됩니다.

1. 자동 수정은 PostToolUse | 2. 위험 차단은 PreToolUse | 3. 오래 걸리는 작업은 신중하게 async | 4. 민감정보와 파괴적 명령은 hook에서도 절대 가볍게 다루지 않기

Hooks는 잘 쓰면 Claude Code를 팀 규칙에 맞게 움직이는 자동화 레이어가 됩니다. 하지만 shell command가 사용자 권한으로 실행되므로, 처음에는 작고 안전한 hook부터 시작해야 합니다. /hooks로 등록 여부를 확인하고, 문제가 생기면 claude --debug-file로 로그를 확인합니다.

23. MCP로 외부 도구 연결하기

01MCP는 무엇인가

MCP는 Model Context Protocol의 약자다. AI 모델이 외부 도구, 데이터, API와 연결되는 방식을 표준화한 프로토콜이다.

MCP 없이 기본 기능만 사용하면:

Claude Code 기본 기능
→ 프로젝트 파일 읽기
→ 코드 수정
→ Bash 명령 실행

MCP를 연결하면:

MCP를 연결한 Claude Code
→ GitHub PR 읽기
→ Sentry 오류 확인
→ PostgreSQL 스키마 조회
→ Jira 티켓 확인
→ Figma 디자인 정보 참고
→ 내부 API 호출

02MCP의 3가지 구성 요소

MCP 서버는 크게 세 가지 기능을 제공합니다.

Resource

Claude가 읽을 수 있는 외부 자료 (예: GitHub 이슈, DB 스키마, API 문서)

Tool

Claude가 실행할 수 있는 외부 기능 (예: PR 조회, DB 쿼리, Sentry 오류 검색)

Prompt

slash 명령처럼 호출할 수 있는 작업 템플릿 (예: /mcp__github__pr_review 456)

03MCP가 필요한 이유

실제 개발 작업은 코드만 보고 끝나지 않습니다. MCP가 없으면 반복적으로 외부 정보를 복사해서 붙여넣어야 합니다.

이 기능은 어떤 Jira 티켓에서 시작됐지?
현재 PR에 어떤 리뷰가 달렸지?
프로덕션에서 실제로 어떤 에러가 많이 나고 있지?
이 테이블 스키마가 어떻게 생겼지?
Figma 디자인과 현재 구현이 맞나?

MCP를 연결하면 Claude가 이 정보를 직접 가져와 작업 흐름 안에 넣을 수 있습니다.

04MCP 없이 작업할 때 vs 연결했을 때

MCP 없이 작업할 때

1. 사용자가 Sentry에 들어간다.
2. 에러 내용을 복사한다.
3. Claude Code에 붙여넣는다.
4. Claude가 원인을 추론한다.
5. 사용자가 다시 Sentry에서 추가 정보를 찾는다.
6. 다시 붙여넣는다.

MCP를 연결했을 때

1. Claude에게 "최근 24시간 auth 서비스 오류를 확인해줘"라고 요청
2. Claude가 Sentry MCP 도구를 사용
3. 에러, 스택 트레이스, 배포 시점 정보를 함께 분석
4. 관련 코드 수정 계획을 제안

MCP는 Claude Code를 "코드 수정 도구"에서 "개발 도구 체인과 연결된 작업 에이전트"로 확장합니다.

05MCP를 언제 써야 하는가

초보자는 MCP를 "멋있어 보이는 모든 외부 연결"로 생각하면 안 됩니다. 필요할 때만 붙여야 합니다.

한 번만 확인할 정보

굳이 MCP 필요 없음

자주 복사해서 붙여넣는 정보

MCP 연결 후보

GitHub PR, 이슈를 자주 다룸

GitHub MCP 유용

프로덕션 오류를 자주 분석함

Sentry MCP 유용

DB 스키마와 데이터를 자주 확인함

DB MCP 유용

실전 기준: 반복해서 붙여넣는 외부 정보가 있다면 MCP 고려

06MCP 연결 전략

초보자는 먼저 읽기 전용 MCP부터 시작해야 합니다.

GitHub PR 조회, Sentry 오류 조회, DB 스키마 조회처럼 "읽기만 해도 도움이 되는 연결"이 좋습니다.

연결 시 판단 기준:

반복해서 붙여넣는 외부 정보가 있다 → MCP 고려
Claude가 직접 조회하면 작업 시간이 줄어든다 → MCP 고려
읽기 전용 권한으로 충분하다 → MCP 시작하기 좋음
쓰기 권한이 필요하다 → 신중하게 권한 설계 후 연결

07MCP 서버란 무엇인가

MCP에서 외부 도구를 연결하려면 MCP 서버가 필요합니다. 여기서 서버는 꼭 클라우드 서버를 뜻하지 않습니다.

Claude Code
   ↓
MCP 서버
   ↓
GitHub / Sentry / DB / Jira / 내부 API

MCP 서버는 Claude Code에게 "내가 제공할 수 있는 도구 목록"을 알려줍니다. Claude는 사용자의 요청을 보고 필요한 도구를 선택해 호출합니다.

08연결 방식: HTTP, stdio, SSE, WebSocket

Claude Code의 MCP 서버 연결 방식은 여러 가지가 있습니다. 초보자는 HTTP와 stdio만 먼저 이해하면 됩니다.

HTTP

원격 MCP 서버에 URL로 연결 (클라우드 서비스 연결에 가장 흔함)

stdio

로컬 명령어를 실행해 연결 (로컬 도구, DB CLI, 직접 만든 서버에 적합)

SSE

예전 원격 연결 방식 (가능하면 HTTP 우선)

WebSocket

양방향 지속 연결 (서버가 먼저 이벤트를 밀어줘야 할 때)

공식 문서는 원격 MCP 서버 연결에는 HTTP를 권장합니다.

09가장 기본적인 MCP 연결 명령

원격 HTTP MCP 서버를 추가하는 기본 형식입니다.

claude mcp add --transport http <name> <url>

실제 예시:

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

연결 후 Claude Code 안에서 상태를 확인합니다.

/mcp

10MCP 관리 명령어

MCP 서버는 터미널 명령과 Claude Code 안의 /mcp 명령으로 관리합니다.

claude mcp list

구성된 MCP 서버 목록 확인

claude mcp get <name>

특정 서버 세부 정보 확인

claude mcp remove <name>

서버 제거

claude mcp reset-project-choices

프로젝트 범위 서버 승인 선택 초기화

/mcp

Claude Code 안에서 서버 상태와 인증 확인

11Scope: local, project, user

MCP 서버를 추가할 때는 "어디에 적용할 것인가"를 정해야 합니다.

local

현재 프로젝트에서 나만 사용 (~/.claude.json 저장, 공유 안 함)

project

현재 프로젝트 팀 전체 (.mcp.json 저장, 공유 가능)

user

내 모든 프로젝트 (~/.claude.json 저장, 공유 안 함)

초보자 기준:

처음 테스트 → local
팀 전체가 같이 써야 함 → project
내 모든 프로젝트에서 쓸 개인 도구 → user
API key나 개인 토큰 포함 → project에 직접 넣지 않기

12Project scope 예시

팀 전체가 같은 MCP 서버를 써야 한다면 project scope를 사용합니다.

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

그러면 프로젝트 루트에 .mcp.json이 생성되거나 업데이트됩니다.

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

project-scoped 서버를 사용하기 전에 승인이 필요합니다.

13환경 변수로 민감정보 분리하기

API key나 토큰은 .mcp.json에 그대로 적으면 안 됩니다. 대신 환경 변수를 사용합니다.

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${INTERNAL_API_KEY}"
      }
    }
  }
}

이렇게 하면 .mcp.json에는 구조만 공유하고, 실제 토큰은 각자 환경 변수로 넣습니다.

export INTERNAL_API_KEY="your-token"

14GitHub MCP 연결 예시

GitHub MCP를 연결하면 PR, 이슈, 리뷰 흐름을 Claude Code 안에서 다룰 수 있습니다.

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

연결 후 다음처럼 요청할 수 있습니다.

Review PR #456 and suggest improvements.
Create a new issue for the bug we just found.
Show me all open PRs assigned to me.

처음부터 쓰기 권한이 있는 토큰을 주지 않는 편이 좋습니다. 먼저 읽기 전용 또는 최소 권한 토큰으로 시작합니다.

15Sentry MCP 연결 예시

Sentry MCP는 프로덕션 오류 분석에 유용합니다.

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

Claude Code 안에서 인증합니다.

/mcp

그다음 다음처럼 요청합니다.

What are the most common errors in the last 24 hours?
Show me the stack trace for error ID abc123.
Which deployment introduced these new errors?

16PostgreSQL MCP 연결 예시

데이터베이스는 강력하지만 위험합니다. 초보자는 반드시 읽기 전용 계정을 사용해야 합니다.

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:[email protected]:5432/analytics"

연결 후 다음처럼 요청할 수 있습니다.

Show me the schema for the orders table.
Find customers who haven't made a purchase in 90 days.
What's our total revenue this month?

17DB 연결 시 안전 원칙

운영 DB에는 다음 원칙을 반드시 적용합니다.

read-only 계정 사용
production DB 직접 연결은 최소화
LIMIT 없는 쿼리 금지
개인정보 컬럼 접근 제한
쓰기 권한은 초보자 단계에서 연결하지 않기

18OAuth 인증은 /mcp에서 처리한다

일부 원격 MCP 서버는 OAuth 인증을 요구합니다. 이 경우 서버를 추가한 뒤 Claude Code 안에서 /mcp를 실행해 브라우저 인증 흐름을 진행합니다.

/mcp

초보자는 이렇게 기억하면 됩니다.

서버 추가 후 인증 필요 → /mcp
브라우저가 열림 → 로그인
토큰은 Claude Code가 관리
안 되면 claude mcp get <name>으로 상태 확인

19MCP Resource를 @ 기호로 참조하기

MCP 서버는 Claude가 읽을 수 있는 resource를 제공합니다. 이 resource는 파일처럼 @로 참조할 수 있습니다.

Can you analyze @github:issue://123 and suggest a fix?
Please review @docs:file://api/authentication.
Compare @postgres:schema://users with @docs:file://database/user-model.

@를 입력하면 연결된 MCP 서버의 resource도 파일과 함께 자동완성에 나타날 수 있습니다.

20MCP Prompt를 slash command처럼 쓸 수 있다

MCP 서버가 prompt를 제공하면 Claude Code에서 slash command처럼 사용할 수 있습니다.

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug in login flow" high

일반 slash command는 Claude Code 자체 명령이고, MCP prompt command는 연결된 외부 MCP 서버가 제공하는 명령입니다.

21MCP 출력 한도와 컨텍스트 관리

MCP는 외부 데이터를 가져오므로 출력이 커질 수 있습니다. 기본 최대 출력 한도는 25,000 토큰입니다.

export MAX_MCP_OUTPUT_TOKENS=50000
claude

하지만 초보자는 한도를 무작정 올리지 않는 것이 좋습니다.

좋은 요청: 최근 24시간 auth 서비스의 상위 5개 오류만 보여줘.

나쁜 요청: Sentry 로그 전부 가져와줘.

좋은 요청: orders 테이블의 컬럼과 인덱스만 보여줘.

나쁜 요청: DB 전체 스키마를 다 가져와줘.

22MCP Tool Search는 왜 중요한가

MCP 서버를 많이 연결하면 Claude가 알아야 할 도구 설명도 많아집니다. Claude Code는 Tool Search를 사용해 이를 관리합니다.

Tool Search는 세션 시작 시 도구 이름만 로드하고, Claude가 실제로 필요할 때 관련 도구 정의를 검색해 가져옵니다. 기본적으로 활성화되어 있습니다.

export ENABLE_TOOL_SEARCH=auto:5 claude

또는 완전히 끌 수 있습니다.

export ENABLE_TOOL_SEARCH=false claude

23특정 서버의 도구를 항상 미리 로드하기

특정 서버의 도구를 항상 미리 로드해야 한다면 alwaysLoad를 사용할 수 있습니다.

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

alwaysLoad: true는 해당 서버의 모든 도구를 세션 시작 시 로드합니다. 자주 필요한 소수의 도구에만 사용하세요.

24초보자가 피해야 할 과한 연결

MCP는 많이 연결할수록 좋은 기능이 아닙니다. 잘못 연결하면 비용, 보안, 혼란이 커집니다.

GitHub, Jira, Sentry, DB, Slack, Figma를 한 번에 연결

Claude가 도구 선택을 헷갈릴 수 있음

운영 DB 쓰기 권한 연결

데이터 손상 위험

개인 토큰을 .mcp.json에 직접 저장

팀 저장소에 유출 가능

검증 안 된 MCP 서버 설치

prompt injection, 데이터 유출 위험

초보자용 원칙: 한 번에 하나씩 연결하고, 먼저 읽기 전용으로 연결합니다.

25MCP와 Hooks, Skills, Subagents의 차이

6부의 기능들은 서로 역할이 다릅니다.

Slash command

사용자가 빠르게 명령 실행 (/context, /model)

Hooks

특정 이벤트에서 자동 실행 (파일 수정 후 prettier)

MCP

외부 도구 연결 (GitHub, Sentry, DB)

Skills

프로젝트별 전문 지식 제공 (회사 API 사용법)

Subagents

큰 작업을 분리 처리 (보안 리뷰 agent, 테스트 agent)

26실전 워크플로우: Sentry 오류 분석

1단계: Sentry MCP 연결

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

2단계: 인증 확인

/mcp

3단계: 오류 조회 요청

최근 24시간 auth 서비스의 상위 5개 오류를 확인해줘.

4단계: 코드와 연결

이 오류들이 어떤 파일과 관련 있는지 찾아 수정 계획을 세워줘.

5단계: 안전한 검토

/diff
/code-review high

27실전 워크플로우: GitHub PR 리뷰하기

1단계: GitHub MCP 연결

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer ${GITHUB_TOKEN}"

2단계: 상태 확인

/mcp

3단계: PR 리뷰 요청

PR #456을 읽고 버그, 보안, 테스트, 유지보수성 관점으로 리뷰해줘.

4단계: 수정 계획

실제로 수정해야 할 항목만 우선순위별로 정리해줘.

28실전 워크플로우: DB 스키마 기반 구현

1단계: 읽기 전용 DB 연결

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "${DATABASE_READONLY_URL}"

2단계: 스키마 조회

@postgres:schema://users와 @postgres:schema://orders를 참고해서
주문 내역 화면에 필요한 API 응답 구조를 제안해줘.

3단계: 구현 계획

현재 코드베이스에서 관련 파일을 찾고 수정 계획을 세워줘.

4단계: 안전한 구현

/plan implement order history API based on current DB schema

29MCP 문제 해결 체크리스트

MCP가 작동하지 않으면 아래 순서로 확인합니다.

서버가 목록에 없음

claude mcp list

서버 세부 정보 필요

claude mcp get <name>

Claude Code 안에서 상태 확인

/mcp

인증 필요

/mcp에서 OAuth 진행

환경 변수 오류

${VAR} 값이 실제로 설정되어 있는지 확인

출력이 잘림

MAX_MCP_OUTPUT_TOKENS 또는 요청 범위 축소

30초보자용 MCP 도입 순서

처음부터 많은 MCP를 연결하지 말고 아래 순서로 늘립니다.

/mcp와 claude mcp list 사용법 익히기
Sentry 또는 GitHub 중 하나만 읽기 중심으로 연결
토큰을 환경 변수로 분리
project scope와 local scope 차이 이해
DB는 반드시 read-only로 연결
팀 공유가 필요할 때만 .mcp.json 사용
출력이 커지면 요청 범위를 줄이고 /context 확인

가장 안전한 첫 실습은 Sentry나 GitHub처럼 "읽기 중심"으로 시작하는 것입니다.

섹션 23 · 마무리

이 단원에서 기억할 것

MCP는 Claude Code를 외부 도구와 연결하는 표준 프로토콜입니다. GitHub, Sentry, PostgreSQL, Jira, Figma, 내부 API 같은 도구를 연결하면 Claude가 단순히 코드만 보는 것이 아니라 실제 개발 환경의 맥락까지 함께 참고할 수 있습니다.

초보자는 다음 기준만 기억하세요.

외부 정보를 자주 복사해서 붙여넣는다 → MCP 연결 후보

MCP는 강력하지만, 많이 연결할수록 좋은 기능은 아닙니다. 먼저 하나의 안전한 서버를 읽기 전용으로 연결해 작은 성공 경험을 만들고, 그다음 팀 워크플로우에 맞는 도구만 추가하는 방식이 가장 좋습니다.

다음 단원

24단원. 대규모 프로젝트 관리: 여러 에이전트 동시 실행

24. Subagents로 큰 작업을 나눠 맡기기

섹션 24 · 정의

Subagent란 무엇인가

Subagents는 Claude Code에서 큰 작업을 작은 전문 작업으로 나눠 맡기는 기능입니다. 앞 단원의 MCP가 외부 도구를 연결하는 통로였다면, subagents는 작업을 별도의 Claude 인스턴스에 위임하는 방식입니다.

공식 문서 기준으로 subagent는 특정 유형의 작업을 처리하는 특화된 AI 어시스턴트입니다. 각 subagent는 별도의 컨텍스트 윈도우에서 실행되고, 사용자 정의 시스템 프롬프트, 특정 도구 접근 권한, 독립적인 권한 설정을 가질 수 있습니다.

Claude가 작업이 subagent 설명과 맞다고 판단하면 위임하고, subagent는 독립적으로 일한 뒤 요약만 주 대화로 반환한다.

01일을 나눠 맡기는 보조 작업자

Claude Code를 오래 쓰다 보면 한 세션 안에 너무 많은 정보가 쌓입니다. 예를 들어 이렇게 한 번에 시키는 경우입니다.

인증 코드도 읽고,
DB 모델도 읽고,
API 라우트도 읽고,
테스트도 돌리고,
에러 로그도 분석하고,
수정 계획도 세우고,
마지막에는 코드까지 바꿔줘.

이렇게 시키면 메인 대화의 컨텍스트가 빠르게 커집니다. 읽은 파일, 검색 결과, 테스트 로그, 중간 판단이 모두 같은 대화창에 쌓이기 때문입니다.

02Subagent로 나누면

Subagent를 사용하면 다음처럼 나눌 수 있습니다.

메인 대화:
- 전체 목표를 관리한다.
- 최종 결정을 내린다.
- 수정 승인 여부를 판단한다.

Subagent 1: 인증 관련 파일만 찾는다.
Subagent 2: DB 모델만 분석한다.
Subagent 3: API 라우트만 분석한다.

메인 대화: 세 subagent의 요약을 받아 종합한다.

subagents는 깨끗한 컨텍스트로 시작하고, 지정된 도구와 모델로 작업한 뒤, 결과만 기본 대화로 반환해 컨텍스트 오버플로를 막습니다.

03왜 탐색과 분석을 분리하는가

초보자는 보통 Claude에게 모든 파일을 읽게 하고 그 자리에서 바로 수정하게 합니다. 하지만 실제 개발에서는 탐색과 결정을 분리하는 편이 안전합니다.

탐색

관련 파일 찾기, 에러 로그 읽기, 실패 원인 후보 수집, 비슷한 패턴 검색

결정

바꿀 파일 선택, 접근 방식 판단, 수정 범위 제한, 테스트 전략 결정

탐색은 많은 파일과 로그를 읽어 컨텍스트를 많이 소비합니다. 반면 결정은 핵심 요약만 있으면 됩니다. Subagent는 이 둘을 분리하는 데 적합합니다.

04Subagent를 써야 하는 상황 ①

모든 작업에 subagent가 필요한 것은 아닙니다. 기준은 메인 대화에 남길 가치가 없는 대량 정보가 생기는가입니다.

파일 하나 설명

낮음 — 메인 대화에서 바로 처리 가능

작은 버그 수정

낮음 — 왕복이 많고 빠른 수정이 중요

테스트 로그 수백 줄 분석

높음 — 로그를 메인 컨텍스트에 다 넣을 필요 없음

대형 코드베이스 구조 파악

높음 — 탐색 결과를 요약만 받는 편이 좋음

05Subagent를 써야 하는 상황 ②

보안 리뷰

높음 — 별도 관점으로 집중 검토 가능

DB·API·UI 병렬 분석

높음 — 독립 영역을 나눠 탐색 가능

대화에 이미 있는 내용의 짧은 질문

낮음 — subagent 시작 비용이 불필요

반복적으로 같은 전문 리뷰 필요

높음 — custom subagent로 재사용 가능

주 대화는 빈번한 왕복, 반복 개선, 빠른 작은 변경에 적합합니다. Subagent는 자세한 출력이 주 컨텍스트에 필요 없거나, 도구를 제한해야 하거나, 독립적으로 끝낸 뒤 요약을 반환할 수 있는 작업에 적합합니다.

06내장 Subagent 유형

Claude Code에는 기본으로 쓸 수 있는 내장 subagent가 있습니다. 초보자는 먼저 이 셋을 이해하면 됩니다.

Explore

빠른 읽기 전용 탐색 — 관련 파일 찾기, 구조 파악, 패턴 검색

Plan

계획 수립용 읽기 전용 조사 — 구현 전 코드베이스 조사

General-purpose

탐색과 수정 모두 가능 — 복잡한 다단계 작업

Explore는 코드베이스 검색·분석에 최적화된 빠른 읽기 전용 에이전트이고, Plan은 plan mode 중 컨텍스트 수집에, general-purpose는 탐색과 수정이 모두 필요하거나 여러 종속 단계가 있는 작업에 씁니다.

07가장 쉬운 사용법: 자연어로 위임

처음에는 custom subagent를 만들 필요가 없습니다. 프롬프트에서 명시적으로 subagent를 사용해줘라고 말하면 됩니다.

Use an explore agent to find all authentication-related files.
Do not modify anything. Return only the important files and why they matter.

한국어로는 이렇게 씁니다.

Explore subagent를 사용해서 인증 관련 파일을 찾아줘.
파일은 수정하지 말고, 중요한 파일 목록과 각 파일의 역할만 요약해줘.

자동 위임이 충분하지 않을 때는 자연어로 이름을 지정하거나, @ mention으로 특정 subagent 실행을 보장하거나, --agent 플래그로 전체 세션을 특정 agent로 실행할 수 있습니다.

08@ mention으로 특정 subagent 호출

특정 subagent를 반드시 쓰고 싶다면 @ mention을 사용합니다.

@"code-reviewer (agent)" look at the auth changes.

수동으로 입력할 때는 이렇게 쓸 수도 있습니다.

@agent-code-reviewer 최근 auth 변경사항을 리뷰해줘.

@ mention은 어떤 subagent를 실행할지를 고정합니다. 다만 subagent에게 전달되는 세부 작업 프롬프트는 Claude가 현재 요청을 바탕으로 작성합니다.

09Foreground와 background 실행

Foreground

subagent가 끝날 때까지 메인 대화가 기다림 — 짧고 중요한 분석

Background

뒤에서 실행되고 사용자는 계속 작업 — 오래 걸리는 리뷰·테스트·조사

Foreground subagent는 완료될 때까지 주 대화를 차단하고 권한 프롬프트를 사용자에게 전달합니다. Background subagent는 동시에 실행되며, 이미 부여된 권한으로 작업하고 그렇지 않은 도구 호출은 자동 거부됩니다. 실행 중인 작업은 Ctrl+B로 background로 보낼 수 있습니다.

Run a thorough security review in the background while I continue working on the frontend.

10병렬 탐색 예시

Subagent의 가장 큰 장점은 독립적인 탐색을 병렬로 나눌 수 있다는 점입니다.

다음 세 영역을 별도 subagent로 병렬 조사해줘.

1. 인증 흐름
2. 결제 모델
3. API 라우트

각 subagent는 파일을 수정하지 말고,
관련 파일 목록, 핵심 흐름, 위험한 부분만 요약해서 반환해줘.
마지막에 세 결과를 종합해서 수정 계획을 제안해줘.

독립적인 조사는 여러 subagent가 동시에 수행하게 하고 Claude가 결과를 종합하는 패턴이 좋습니다. 연구 경로가 서로 의존하지 않을 때 가장 잘 작동합니다. 초보자는 반드시 수정하지 말라는 조건을 넣는 편이 안전합니다.

11Subagent 체인: 순서대로 맡기기

모든 작업이 병렬에 적합하지는 않습니다. 어떤 작업은 앞 단계 결과가 다음 단계의 입력이 됩니다.

1. code-analyzer subagent로 성능 문제를 찾아줘.
2. 그 결과를 바탕으로 optimizer subagent에게 수정 계획을 세우게 해줘.
3. 수정 전에는 내 승인을 받아줘.

다단계 워크플로우에서는 subagent를 순차적으로 사용해, 첫 결과를 Claude가 받아 다음 subagent에 맥락으로 전달합니다. 초보자용 체인은 이렇게 기억하면 됩니다.

Explore → Plan → Implement

12비용과 컨텍스트 절약

Subagent는 컨텍스트를 절약할 수 있지만, 무조건 비용이 줄지는 않습니다. 각 subagent도 모델을 쓰고 토큰을 소비합니다. Subagent가 유리한 경우는 다음과 같습니다.

대량 탐색 결과를 메인 대화에 다 남기지 않아도 될 때
파일 수가 많고 요약만 필요할 때
여러 관점을 독립적으로 조사해야 할 때
탐색은 저렴한 모델로, 최종 판단은 좋은 모델로 나누고 싶을 때

subagent의 model 필드는 sonnet, opus, haiku, 전체 모델 ID, 또는 inherit를 쓸 수 있고, 지정하지 않으면 기본값은 inherit입니다.

13Custom subagent는 언제 만드는가

매번 같은 역할을 반복해서 맡긴다면 custom subagent를 만들면 좋습니다.

매번 "보안 관점으로만 봐줘"라고 말한다
매번 "테스트 실패 원인을 찾아줘"라고 말한다
매번 "DB 쿼리 성능을 확인해줘"라고 말한다
매번 "변경된 코드만 리뷰해줘"라고 말한다

Custom subagent는 YAML frontmatter가 있는 Markdown 파일이며, /agents 명령으로 만들거나 직접 파일을 추가할 수 있습니다. /agents 인터페이스는 보기·생성·편집·삭제·중복 확인 기능을 제공합니다.

14Subagent 저장 위치

.claude/agents/

현재 프로젝트 — 팀과 공유할 프로젝트 전용 agent

~/.claude/agents/

내 모든 프로젝트 — 개인적으로 자주 쓰는 agent

--agents CLI 플래그

현재 세션만 — 테스트, 자동화 스크립트

plugin agents/

플러그인 제공 — 플러그인으로 설치되는 agent

managed settings

조직 전체 — 회사 정책으로 배포

같은 이름이 여러 범위에 있으면 우선순위가 높은 위치가 적용됩니다. 프로젝트 subagent는 버전 관리에 포함해 팀과 공유하기 적합합니다.

15도구 권한은 최소로 준다

Subagent를 만들 때 가장 중요한 안전장치는 도구 제한입니다. 이렇게 하면 파일을 읽고 검색할 수 있지만 수정은 할 수 없습니다.

tools: Read, Grep, Glob

Bash까지 허용하면 테스트나 git diff를 실행할 수 있습니다. 하지만 Bash는 강력하므로 필요할 때만 넣습니다.

tools: Read, Grep, Glob, Bash

상속된 도구 중 쓰기 도구만 제거할 수도 있습니다.

disallowedTools: Write, Edit

subagent는 기본적으로 주 대화의 도구를 상속하지만, tools를 허용 목록으로, disallowedTools를 거부 목록으로 써서 제한할 수 있습니다. 둘 다 쓰면 disallowedTools가 먼저 적용되고, 이후 tools가 남은 풀에서 해결됩니다.

16보안 리뷰어 subagent 예시

보안 리뷰어는 읽기 중심으로 두는 것이 안전합니다. 파일 .claude/agents/security-reviewer.md를 이렇게 만듭니다.

---
name: security-reviewer
description: Expert security reviewer. Use proactively after changes to auth, data handling, payments, or API boundaries.
tools: Read, Grep, Glob, Bash
model: inherit
permissionMode: plan
---

You are a senior security engineer. Review only. Do not edit files.
Check for: hardcoded secrets, missing authorization, SQL injection, unsafe file handling, overbroad permissions.
Output: Severity / File / Risk / Evidence / Recommended fix.

이 agent는 보안 이슈를 찾지만 파일을 수정하지 않습니다. 초보자에게는 찾기와 수정을 분리하는 편이 안전합니다.

17테스트 러너 subagent 예시

테스트 로그는 컨텍스트를 많이 잡아먹습니다. 따라서 테스트 실행과 실패 요약은 subagent에게 맡기기 좋습니다. .claude/agents/test-runner.md를 만듭니다.

---
name: test-runner
description: Runs project tests and summarizes only failing tests and likely root causes.
tools: Read, Grep, Glob, Bash
permissionMode: default
maxTurns: 8
---

Identify the test command, run the smallest relevant test first.
If tests fail, summarize only: test name, exact error, likely cause, related files.
Avoid pasting huge logs. Keep output concise.

이렇게 하면 긴 로그 전체가 메인 대화에 들어오지 않고, 실패 요약만 돌아옵니다.

18DB 분석 subagent 예시

23단원에서 MCP로 DB를 연결했다면, DB 관련 subagent를 별도로 만들 수 있습니다. .claude/agents/db-analyst.md입니다.

---
name: db-analyst
description: Analyzes database schema, query patterns, and migration risks.
tools: Read, Grep, Glob
mcpServers:
  - postgres
model: inherit
permissionMode: plan
---

Inspect schema via MCP. Identify mismatch, missing indexes, unsafe migrations.
Never modify data. Never run destructive SQL.

mcpServers 필드는 subagent가 쓸 MCP 서버를 제한합니다. 주 대화에 MCP 도구 설명을 노출하지 않고 특정 subagent에만 도구를 주고 싶을 때 유용합니다.

19Skills와 함께 쓰는 subagent

25단원에서 자세히 다루지만, subagent는 skills와 함께 쓸 수 있습니다.

---
name: api-developer
description: Implements API endpoints following team conventions.
tools: Read, Edit, Grep, Glob, Bash
skills:
  - api-conventions
  - error-handling-patterns
model: inherit
---

skills 필드는 시작 시 subagent 컨텍스트에 특정 skill 콘텐츠를 주입합니다. 실행 중에 찾아 로드하길 기대하지 않고, 필요한 도메인 지식을 처음부터 넣어주는 방식입니다. 초보자는 아직 skill을 만들지 않았다면 이 필드는 비워둬도 됩니다.

20Subagent 관리 명령

Subagent는 /agents로 관리합니다. Running 탭에서는 실행 중인 subagent를 보고 열거나 중지할 수 있고, Library 탭에서는 내장·사용자·프로젝트·플러그인 subagent를 확인하고 생성·편집·삭제·중복 확인을 할 수 있습니다.

/agents

subagent 관리 UI 열기

/agents create

새 subagent 만들기

/agents edit

기존 subagent 수정

/agents delete

subagent 삭제

claude agents

터미널에서 agent 목록 확인

21CLI에서 임시 subagent 정의하기

빠른 테스트나 자동화에서는 파일을 만들지 않고 --agents 플래그로 세션 시작 시 subagent를 정의할 수 있습니다.

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on quality and security.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

--agents는 파일 기반 subagent와 같은 frontmatter 필드를 가진 JSON을 받으며, 이렇게 정의한 subagent는 해당 세션에만 존재하고 디스크에 저장되지 않습니다. 초보자에게는 파일 기반 정의가 더 이해하기 쉽습니다.

22Subagent와 다른 방식의 차이

Main REPL

빠른 질문·반복 수정 — 같은 대화 컨텍스트

Subagent

특정 작업을 격리해 위임 — 단일 세션 안의 별도 작업자

Background agent

오래 걸리는 독립 작업 — 사용자가 계속 작업하는 동안 별도 실행

Agent team

여러 독립 세션의 협업 — 메시지와 작업 목록으로 조율

Dynamic workflow

수십~수백 agent 규모의 반복 가능한 오케스트레이션

초보자는 이렇게 기억하면 됩니다. 작은 작업은 Main REPL, 탐색 격리는 Subagent, 오래 걸리는 작업은 Background, 여러 작업자 협업은 Agent team, 대규모 반복은 Workflow입니다.

23초보자용 위임 프롬프트 ①

Subagent에게 일을 맡길 때는 범위를 좁혀야 합니다. 파일 탐색은 이렇게 합니다.

Explore subagent로 결제 기능 관련 파일을 찾아줘.
- 파일을 수정하지 말 것
- 관련성 높은 파일만 추릴 것
- 각 파일 역할을 한 줄로 설명할 것
- 확실하지 않은 파일은 "불확실"로 분리할 것

버그 원인 조사는 이렇게 합니다.

Subagent로 이 테스트 실패의 원인을 조사해줘.
- 테스트 로그 전체를 붙여넣지 말 것
- 실패한 테스트 이름, 에러, 관련 파일, 원인 후보만 요약
- 수정은 하지 말 것

24초보자용 위임 프롬프트 ②

병렬 탐색과 코드 리뷰는 이렇게 씁니다.

세 subagent를 병렬로 사용해 조사해줘.
1. 인증 코드  2. DB 모델  3. API 라우트
각자: 관련 파일 / 핵심 흐름 / 위험 지점 / 다음 확인할 것 만 보고.
마지막에 종합해서 수정 계획만 제안.

code-reviewer subagent로 최근 변경을 리뷰해줘.
- git diff 기준 변경 파일만 우선
- Critical / Warning / Suggestion으로 구분
- 실제 버그·보안·테스트 누락 중심, 파일 수정 금지

25Subagent 결과를 받을 때 확인할 것

Subagent 결과를 그대로 믿고 바로 수정하면 안 됩니다. 메인 대화에서 다시 검토해야 합니다.

범위

요청한 범위만 조사했는가

근거

파일 경로와 구체적 근거가 있는가

불확실성

추측과 확정 사실을 구분했는가

중복·누락

다른 결과와 겹치거나 중요한 영역이 빠지지 않았는가

수정 가능성

바로 구현해도 될 만큼 계획이 구체적인가

26Subagent 사용 시 흔한 실수

모든 작업을 subagent에 맡김

느려지고 비용 증가 → 큰 탐색·리뷰에만

수정 권한을 너무 넓게 줌

원치 않는 수정 위험 → 처음엔 읽기 전용

description을 모호하게

자동 위임 안 됨 → 언제 쓸지 명확히

결과 형식 미지정

요약이 길고 산만 → 출력 형식 지정

병렬 작업이 서로 의존

결과 충돌·중복 → 독립 영역만 병렬화

로그 전체 반환

메인 컨텍스트 다시 커짐 → "요약만 반환" 명시

여러 subagent가 자세한 결과를 반환하면 그 결과가 다시 주 대화 컨텍스트를 많이 소비할 수 있습니다. 짧고 구조화된 요약을 요구하는 것이 중요합니다.

27실전 워크플로우: 대형 버그 조사

로그인 후 리다이렉트가 가끔 실패하는 상황입니다. 나쁜 요청은 너무 넓습니다.

로그인 리다이렉트 버그를 고쳐줘.

좋은 요청은 탐색을 병렬로 나누고 수정을 멈춥니다.

로그인 후 리다이렉트가 가끔 실패하는 문제를 조사해줘.
세 subagent를 병렬로:
1. 인증 흐름  2. 라우팅/리다이렉트  3. 세션/쿠키 처리
각자 파일 수정 말고 관련 파일·핵심 흐름·원인 후보만 요약.
결과를 받은 뒤 메인 대화에서 수정 계획만 제안해줘.

28실전 워크플로우: 대형 리팩터링 준비

인증 모듈을 새 구조로 리팩터링하기 전, subagent로 분리 조사합니다.

인증 모듈 리팩터링을 준비하려고 해. subagent로 분리 조사해줘.
1. 현재 인증 진입점과 주요 흐름
2. 토큰 발급/검증/갱신 로직
3. 권한 체크와 라우트 보호 방식
4. 관련 테스트 구조
각자 수정 말고 요약만. 마지막에 위험도와 단계별 계획을.

이후 Plan Mode와 연결하면 탐색은 subagents가 맡고, 실제 수정 계획은 Plan Mode로 검토합니다.

/plan refactor auth module based on the subagent findings

29실전 워크플로우: 리뷰와 수정 분리

리뷰 subagent는 찾기만 하고, 메인 Claude가 승인된 항목만 수정하게 하면 안전합니다.

code-reviewer subagent로 최근 변경을 리뷰해줘.
파일 수정 말고, 반드시 git diff 기준으로만.

리뷰 결과가 나오면 메인 대화에서 판단합니다.

Critical 항목만 실제 수정 계획으로 바꿔줘.
Warning과 Suggestion은 이번 PR 범위에서 제외해.

Critical 2개만 최소 범위로 수정하고, /diff 기준으로 설명해줘.

섹션 24 · 마무리

이 단원에서 기억할 것

Subagents는 큰 작업을 별도의 전문 작업자로 나눠 맡기는 기능입니다. 가장 큰 장점은 탐색과 로그 분석처럼 컨텍스트를 많이 먹는 작업을 메인 대화에서 분리하고, 요약만 받아 최종 판단에 사용하는 것입니다.

초보자는 이 원칙만 기억하면 됩니다. 관련 파일 찾기는 Explore, 수정 전 조사는 Plan, 긴 로그 분석은 test-runner, 보안·리뷰는 읽기 전용 custom subagent, 독립 영역 여러 개는 병렬 subagents, 앞 단계가 다음 입력이면 체인, 실제 수정 전에는 메인 대화에서 계획 승인입니다.

작은 수정은 메인 대화에서 빠르게, 큰 탐색·대량 로그·전문 리뷰·병렬 분석만 subagent로.

다음 단원

25단원. Skills와 Plugins는 언제 써야 하는가

25. Skills와 Plugins는 언제 써야 하는가

01Skills와 Plugins를 한 문장으로 이해하기

먼저 둘의 역할을 단순하게 구분하자.

Skill = Claude에게 특정 작업 지식이나 절차를 가르치는 단위
Plugin = skills, agents, hooks, MCP 등을 묶어서 배포하는 패키지

즉, skill은 "지식과 절차"에 가깝고, plugin은 "배포 단위"에 가깝다.

Skill

Claude가 필요할 때 불러 쓰는 지식·절차

API 작성 규칙, 배포 절차, 코드 리뷰 체크리스트

예시

Plugin

여러 확장 기능을 묶은 설치 가능한 패키지

GitHub plugin, Sentry plugin, 팀 내부 개발 plugin

예시

업로드 원문도 Claude Code의 Extension Layer에서 MCP는 외부 서비스 연결, hooks는 자동화, skills는 도메인 전문 지식, plugins는 이 모든 것을 배포 가능한 형태로 패키징한다고 설명한다.

02Skill은 언제 쓰는가

Skill은 Claude에게 반복적으로 알려주는 "작업 지식"을 파일로 분리한 것이다.

예를 들어 매번 이런 말을 하고 있다면 skill 후보다.

우리 API는 항상 Zod로 입력값을 검증하고,
에러 응답은 { code, message } 형식을 사용하고,
컨트롤러에는 비즈니스 로직을 넣지 말고 service 계층에 넣어줘.

이걸 매번 프롬프트에 쓰면 번거롭고, CLAUDE.md에 너무 많이 넣으면 모든 세션에서 컨텍스트를 잡아먹는다. Skill로 만들면 Claude가 관련 작업에서만 불러 쓴다.

공식 문서도 skill 본문은 사용될 때만 로드되므로, 긴 참고 자료는 실제로 필요할 때까지 거의 비용이 들지 않는다고 설명한다.

03Skill을 만들어야 하는 경우

같은 지시문을 계속 붙여넣음

높음 · 반복 프롬프트를 줄일 수 있음

팀 API 규칙이 있음

높음 · Claude가 구현할 때 자동 참고 가능

배포 절차가 여러 단계임

높음 · /deploy 같은 명령으로 재사용 가능

코드 리뷰 체크리스트가 있음

높음 · 리뷰 기준을 일관되게 유지

특정 도메인 지식이 많음

높음 · 필요한 시점에만 로드 가능

한 번만 쓸 프롬프트

낮음 · 그냥 대화에 입력하면 됨

단순한 한 줄 명령

낮음 · slash command 또는 일반 프롬프트로 충분

별도 컨텍스트에서 조사해야 함

낮음 · subagent가 더 적합

업로드 문서도 도메인 전문 지식이 자동으로 활성화되어야 하거나, 여러 팀원이 같은 지식을 필요로 하거나, 같은 패턴과 규칙을 반복 설명하고 있다면 skill을 만들라고 정리한다. 반대로 명시적 호출을 제어하고 싶으면 slash command, 별도 컨텍스트가 필요하면 subagent, 일회성 프롬프트라면 그냥 입력하는 편이 낫다고 설명한다.

04CLAUDE.md와 Skill의 차이

CLAUDE.md는 프로젝트의 기본 규칙을 Claude에게 알려주는 파일이다. Skill은 특정 작업에 필요한 절차나 전문 지식을 필요할 때만 불러오는 파일이다.

역할

CLAUDE.md = 프로젝트 기본 규칙 / Skill = 특정 작업 지식·절차

로드 시점

CLAUDE.md = 세션 시작 시 기본 참고 / Skill = 관련 작업 또는 직접 호출 시

적합한 내용

CLAUDE.md = 빌드 명령, 테스트 명령, 코딩 규칙 요약 / Skill = 배포 절차, 리뷰 체크리스트, API 작성법

길이

CLAUDE.md = 짧게 유지 / Skill = 지원 파일로 확장 가능

호출 방식

CLAUDE.md = 자동 참고 / Skill = 자동 또는 /skill-name 직접 호출

기준은 단순하다.

항상 알아야 하는 짧은 규칙 → CLAUDE.md
특정 상황에만 필요한 절차 → Skill

05CLAUDE.md 적합 예시

다음은 CLAUDE.md에 적합하다.

## Project commands

- Test: npm test
- Lint: npm run lint
- Build: npm run build

## Rules

- Do not edit .env files.
- Use TypeScript strict mode.

반면 다음은 skill에 적합하다.

## How to add a new API endpoint

1. Create route file.
2. Add request validation.
3. Add service method.
4. Add test cases.
5. Update OpenAPI docs.

06Skill과 slash command의 차이

공식 문서 기준으로 custom commands는 skills로 통합되었다. .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md는 둘 다 /deploy를 만들며, 기존 .claude/commands/ 파일도 계속 동작한다. 새로 만들 때는 skill 방식이 더 확장성이 좋다.

초보자 기준으로는 이렇게 구분하면 된다.

내가 직접 /deploy처럼 호출하고 싶다

Skill with direct invocation

Claude가 상황에 맞게 자동으로 적용하길 원한다

Skill with automatic invocation

아주 간단한 명령 템플릿만 필요하다

Slash command 스타일 skill

긴 참고 문서와 예시 파일까지 묶고 싶다

Skill directory

즉, 최신 흐름에서는 "custom slash command를 만든다"는 말을 "skill을 만들어 /skill-name으로 호출한다"로 이해하면 된다.

07첫 번째 Skill 만들기

예시로 "변경사항 요약 skill"을 만들어보자.

mkdir -p .claude/skills/summarize-changes

.claude/skills/summarize-changes/SKILL.md

---
description: Summarizes uncommitted git changes and flags risky parts. Use when the user asks what changed, wants a commit summary, or asks to review the current diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes in 2-3 bullet points.

Then list risks, if any:
- missing tests
- hardcoded values
- error handling gaps
- security-sensitive changes
- files that should be reviewed manually

If there are no uncommitted changes, say so clearly.

사용법은 두 가지다.

What did I change?

또는 직접 호출한다.

/summarize-changes

공식 문서의 첫 skill 예시도 SKILL.md가 YAML frontmatter와 Markdown instruction으로 구성되고, directory name이 사용자가 입력하는 command가 되며, description이 Claude가 자동으로 skill을 로드할지 판단하는 기준이라고 설명한다.

08Skill 파일 구조

가장 단순한 skill은 SKILL.md 하나만 있으면 된다.

.claude/
└── skills/
    └── api-conventions/
        └── SKILL.md

조금 커지면 supporting files를 둔다.

.claude/
└── skills/
    └── api-conventions/
        ├── SKILL.md
        ├── reference.md
        ├── examples.md
        └── checklists/
            └── endpoint-review.md

공식 문서에 따르면 skill은 여러 파일을 포함할 수 있고, SKILL.md는 핵심 개요와 navigation만 담고, 긴 API 문서나 예시는 별도 파일로 분리하는 것이 좋다. 공식 문서는 SKILL.md를 500줄 이하로 유지하고 자세한 자료는 supporting file로 옮기라고 권장한다.

09Skill 저장 위치

Skill은 저장 위치에 따라 적용 범위가 달라진다.

.claude/skills/<name>/SKILL.md

현재 프로젝트 · 프로젝트 전용 규칙

~/.claude/skills/<name>/SKILL.md

내 모든 프로젝트 · 개인 작업 습관

plugin 내부 skills/

plugin이 활성화된 곳 · 팀·조직 배포

enterprise managed settings

조직 전체 · 회사 정책

공식 문서 기준으로 project skill은 현재 프로젝트에만, personal skill은 모든 프로젝트에 적용된다. 이름이 충돌하면 enterprise, personal, project 순서로 우선순위가 적용되고, plugin skill은 plugin-name:skill-name namespace를 사용해 충돌을 피한다.

초보자 기준은 다음과 같다.

내 개인 습관 → ~/.claude/skills/
현재 프로젝트 규칙 → .claude/skills/
팀에 배포할 기능 묶음 → plugin

10Skill frontmatter 이해하기

Skill의 위쪽 --- 영역을 frontmatter라고 한다.

---
name: api-conventions
description: API design patterns for this codebase. Use when creating or modifying API endpoints.
disable-model-invocation: false
allowed-tools: Read Grep
---

Skill instructions here.

가장 중요한 필드는 description이다. Claude가 이 skill을 언제 사용할지 판단하는 기준이기 때문이다.

name

표시 이름 · 생략 가능

description

skill 용도와 호출 시점 · 반드시 구체적으로 작성

disable-model-invocation

Claude의 자동 호출 금지 · 직접 호출 전용 skill에 사용

allowed-tools

skill에서 미리 허용할 도구 · 처음에는 최소화

disallowed-tools

skill에서 금지할 도구 · 위험 도구 차단에 사용

context

inline 또는 fork 실행 · 고급 사용

argument-hint

호출 인수 안내 · /deploy staging 같은 skill에 유용

공식 문서는 모든 frontmatter 필드가 선택 사항이지만, Claude가 언제 skill을 적용할지 알 수 있도록 description을 권장한다고 설명한다. 또한 description과 when_to_use 텍스트는 context 사용량을 줄이기 위해 listing에서 일정 길이로 잘린다.

11자동 호출과 직접 호출

Skill은 두 방식으로 실행될 수 있다.

자동 호출:
Claude가 대화 내용을 보고 관련 skill을 알아서 로드한다.

직접 호출:
/skill-name 으로 사용자가 직접 실행한다.

예를 들어 API 규칙 skill은 자동 호출이 좋다.

---
description: API design conventions for this codebase. Use when creating or modifying API routes, request validation, response formats, or service-layer code.
---

반면 배포 skill은 직접 호출 전용이 안전하다.

---
description: Deploy the application to production.
disable-model-invocation: true
---

공식 문서도 task content처럼 배포, 커밋, 코드 생성 같은 특정 action은 직접 /skill-name으로 호출하는 것이 적합하며, Claude가 자동으로 실행하지 못하게 하려면 disable-model-invocation: true를 사용할 수 있다고 설명한다.

12Dynamic context injection

Skill 안에는 shell command 결과를 삽입할 수 있다.

## Current branch

!`git branch --show-current`

## Current diff

!`git diff HEAD`

이렇게 하면 Claude가 skill을 볼 때 명령 결과가 이미 포함된다.

예를 들어 commit summary skill은 다음처럼 만들 수 있다.

---
description: Creates a commit summary from the current git diff. Use when the user asks for a commit message or change summary.
---

## Current branch

!`git branch --show-current`

## Current diff

!`git diff HEAD`

## Instructions

Create a concise commit summary.

Use this format:
- Type:
- Scope:
- Summary:
- Risk:
- Tests needed:

공식 문서도 !`git diff HEAD` 형태의 dynamic context injection을 사용하면 Claude Code가 명령을 실행하고, 그 출력을 skill content 안에 삽입한 뒤 Claude에게 전달한다고 설명한다.

주의할 점은 민감정보다. env, secret, token, production data를 출력하는 명령은 skill에 넣지 않는다.

13프로젝트별 전문 지식 Skill 예시 ① · API 규칙

.claude/skills/api-conventions/SKILL.md

---
description: API design and implementation conventions for this codebase. Use when creating or modifying API endpoints, validation, service methods, or response formats.
---

# API conventions

When creating or modifying API endpoints:

1. Validate all request input before using it.
2. Keep business logic in the service layer.
3. Return errors in this format:
   - code
   - message
   - details, only when safe
4. Do not leak internal exception messages to API clients.
5. Add or update tests for success and failure cases.

## File patterns

- Routes: src/routes/**
- Services: src/services/**
- Validation schemas: src/schemas/**
- Tests: tests/api/**

## Output expectation

When you propose an API change, include:
- files to edit
- validation changes
- service changes
- tests to add
- security risks

14프로젝트별 전문 지식 Skill 예시 ② · 리뷰 체크리스트

.claude/skills/review-checklist/SKILL.md

---
description: Project-specific code review checklist. Use when reviewing diffs, pull requests, or completed feature changes.
---

# Review checklist

Review changes for:

## Correctness
- edge cases
- null or undefined handling
- async error handling
- regression risks

## Security
- missing authorization
- unsafe input usage
- hardcoded secrets
- sensitive data exposure

## Tests
- success path
- failure path
- boundary cases
- integration impact

## Maintainability
- duplicated logic
- unclear naming
- excessive file scope
- inconsistent patterns

Return findings by severity:
- Critical
- Warning
- Suggestion

15프로젝트별 전문 지식 Skill 예시 ③ · 배포 절차

.claude/skills/deploy-checklist/SKILL.md

---
description: Deployment checklist for this project. Use only when the user explicitly asks to prepare or review a deployment.
disable-model-invocation: true
---

# Deployment checklist

Before deployment:

1. Confirm target environment.
2. Run tests.
3. Run lint.
4. Run build.
5. Check migration status.
6. Review environment variables.
7. Summarize rollback plan.

Do not run deployment commands unless the user explicitly approves.

배포처럼 위험한 작업은 자동 호출을 막고, 명시적 승인 흐름을 유지하는 것이 좋다.

16Supporting file을 쓰는 좋은 방식

Skill이 길어지면 SKILL.md에 모든 내용을 넣지 말고 supporting file로 나눈다.

.claude/skills/security-review/
├── SKILL.md
├── SECURITY_PATTERNS.md
├── AUTH_CHECKLIST.md
└── EXAMPLES.md

SKILL.md

---
description: Security review guidance for authentication, authorization, data handling, and API boundary changes.
---

# Security review skill

Use this skill when reviewing security-sensitive changes.

For detailed vulnerability patterns, see [SECURITY_PATTERNS.md](SECURITY_PATTERNS.md).
For authentication and authorization review steps, see [AUTH_CHECKLIST.md](AUTH_CHECKLIST.md).
For examples of good and bad findings, see [EXAMPLES.md](EXAMPLES.md).

Return only actionable findings with file paths and severity.

이렇게 하면 Claude는 처음부터 모든 긴 문서를 다 읽지 않고, 필요할 때만 관련 파일을 참고할 수 있다.

17Skill과 Subagent를 함께 쓰는 경우

Skill은 지식이고, subagent는 작업자다. 둘은 함께 쓰면 강력하다.

예를 들어 24단원에서 만든 security-reviewer subagent에 security-review skill을 미리 로드할 수 있다.

.claude/agents/security-reviewer.md

---
name: security-reviewer
description: Reviews authentication, authorization, API, and data-handling changes for security issues.
tools: Read, Grep, Glob, Bash
skills:
  - security-review
permissionMode: plan
---

You are a senior security reviewer.

Use the loaded security-review skill as your checklist.
Do not edit files.
Return only actionable findings.

공식 subagent 문서에서는 subagent frontmatter의 skills 필드를 통해 시작 시 특정 skill을 subagent context에 주입할 수 있다고 설명한다. 업로드 원문도 최신 버전에서는 subagents가 부모 세션에서 사용할 수 있는 전체 skill graph를 상속한다고 정리한다.

18Plugin은 언제 쓰는가

Plugin은 skills, agents, hooks, MCP 서버 등을 하나로 묶어 설치 가능한 패키지로 만든 것이다.

공식 문서 기준으로 plugin은 Claude Code를 skills, agents, hooks, MCP 서버로 확장하고, 프로젝트와 팀 사이에서 공유할 수 있게 해준다. 빠른 실험이나 개인 설정은 .claude/ standalone configuration으로 시작하고, 팀과 공유하거나 버전 관리가 필요해지면 plugin으로 전환하는 것이 권장된다.

개인 프로젝트에서만 쓸 skill 하나

낮음 · .claude/skills/로 충분

한 팀이 여러 프로젝트에서 같은 규칙 사용

높음 · 설치·업데이트가 쉬움

skills + agents + hooks를 함께 배포

높음 · 하나의 패키지로 묶을 수 있음

사내 MCP 서버 설정을 공유

높음 · 팀 전체 도구 연결 표준화

커뮤니티에 배포하고 싶음

높음 · marketplace 배포 가능

실험 중인 hook 하나

낮음 · 먼저 standalone으로 검증

이름 충돌을 피해야 함

높음 · plugin namespace 사용 가능

업로드 문서도 plugin은 사용자 지정 commands, subagents, skills, hooks, MCP 서버를 포함할 수 있는 배포용 Claude Code 확장 기능이라고 정리한다.

19Standalone 설정과 Plugin의 차이

저장 위치

Standalone = 프로젝트 또는 사용자 .claude/ / Plugin = plugin directory

적합한 용도

Standalone = 개인 실험, 프로젝트 전용 설정 / Plugin = 팀 공유, 버전 관리, 배포

skill 이름

Standalone = /deploy / Plugin = /plugin-name:deploy

충돌 가능성

Standalone = 이름 충돌 가능 / Plugin = namespace로 충돌 방지

업데이트

Standalone = Git 또는 파일 복사 / Plugin = marketplace, version 관리

초보자 추천

Standalone = 먼저 시작할 방식 / Plugin = 나중에 패키징할 방식

공식 문서도 standalone은 개인 workflow, 프로젝트별 customization, 빠른 실험, 짧은 skill 이름이 필요할 때 적합하고, plugin은 팀·커뮤니티 공유, 여러 프로젝트 재사용, versioned release, marketplace 배포에 적합하다고 설명한다.

초보자 기준은 다음과 같다.

1단계: .claude/skills/에서 skill 하나 만들기
2단계: .claude/agents/와 함께 써보기
3단계: 팀에서도 반복해서 필요해짐
4단계: plugin으로 패키징

20Plugin 기본 구조

Plugin은 대략 이런 구조를 가진다.

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── api-conventions/
│       └── SKILL.md
├── agents/
│   └── code-reviewer.md
├── hooks/
│   └── hooks.json
├── commands/
│   └── legacy-command.md
└── .mcp.json

업로드 문서의 plugin 구조도 이와 유사하게 .claude-plugin/plugin.json, commands/, agents/, skills/, hooks/, .mcp.json을 포함할 수 있다고 정리한다.

공식 plugins reference도 plugin manifest가 skills, commands, agents, hooks, MCP servers, output styles, LSP servers, dependencies 등을 선언할 수 있다고 설명한다.

21최소 plugin manifest

my-plugin/.claude-plugin/plugin.json

{
  "name": "team-dev-kit",
  "description": "Team development conventions, review agents, and automation for Claude Code.",
  "version": "1.0.0",
  "author": {
    "name": "Your Team"
  }
}

공식 문서 기준으로 plugin manifest는 plugin의 identity, description, version을 정의하며, Claude Code는 이 metadata를 plugin manager에서 표시한다. name은 고유 식별자이자 skill namespace로 사용되어 /my-first-plugin:hello 같은 이름을 만든다.

22Plugin에 skill 넣기

Plugin 구조:

team-dev-kit/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── api-conventions/
        └── SKILL.md

skills/api-conventions/SKILL.md

---
description: Team API conventions. Use when creating or modifying API endpoints.
---

# Team API conventions

- Validate inputs.
- Keep business logic in services.
- Return consistent error responses.
- Add tests for success and failure cases.

Plugin이 활성화되면 이 skill은 namespace가 붙어 호출된다.

/team-dev-kit:api-conventions

Plugin namespace는 이름 충돌을 줄인다. 여러 팀이 각각 deploy, review, api-conventions 같은 흔한 이름을 써도 plugin 이름이 앞에 붙으면 충돌이 줄어든다.

23Plugin에 agent와 hook까지 넣는 예시

Plugin은 skill 하나만 넣을 수도 있지만, 팀용으로는 여러 구성요소를 함께 묶는 경우가 많다.

team-dev-kit/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── api-conventions/
│   │   └── SKILL.md
│   └── security-review/
│       └── SKILL.md
├── agents/
│   ├── code-reviewer.md
│   └── security-reviewer.md
└── hooks/
    └── hooks.json

예를 들어 팀 plugin은 다음을 제공할 수 있다.

api-conventions skill

API 구현 규칙

security-review skill

보안 리뷰 기준

code-reviewer agent

변경사항 리뷰

security-reviewer agent

보안 민감 변경 검토

hook

파일 수정 후 formatter 실행 또는 민감 파일 보호

MCP 서버

사내 도구 연결

공식 plugin discovery 문서도 plugins가 skills, agents, hooks, MCP servers로 Claude Code를 확장한다고 설명한다.

24Plugin 설치와 관리

Plugin은 /plugin으로 관리한다.

/plugin

자주 쓰는 명령은 다음과 같다.

/plugin

plugin UI 열기

/plugin install <name>@<marketplace>

plugin 설치

/plugin enable <name>@<marketplace>

plugin 활성화

/plugin disable <name>@<marketplace>

plugin 비활성화

/plugin uninstall <name>@<marketplace>

plugin 제거

/plugin marketplace add <source>

marketplace 추가

/plugin marketplace list

marketplace 목록 확인

/reload-plugins

plugin 변경사항 다시 로드

공식 discovery 문서에 따르면 공식 marketplace인 claude-plugins-official은 Claude Code 시작 시 자동으로 사용 가능하며, /plugin의 Discover tab에서 탐색하거나 /plugin install github@claude-plugins-official처럼 설치할 수 있다.

25공식 marketplace와 community marketplace

공식 문서 기준으로 plugin marketplace는 누군가 만든 plugin catalog다. 먼저 marketplace를 추가하고, 그 안에서 원하는 plugin을 개별 설치하는 방식이다. 공식 marketplace는 자동으로 제공되며, community marketplace는 직접 추가해야 한다.

claude-plugins-official

Anthropic이 curated한 공식 marketplace

claude-community

검토를 통과한 community plugin catalog

internal marketplace

회사나 팀이 직접 운영하는 plugin catalog

Community marketplace 추가 예시는 다음과 같다.

/plugin marketplace add anthropics/claude-plugins-community

설치 예시는 다음과 같다.

/plugin install some-plugin@claude-community

공식 문서는 community marketplace의 plugin이 automated validation과 safety screening을 통과하고 catalog에서 특정 commit SHA에 pin된다고 설명한다.

26Plugin으로 설치하면 좋은 것들

공식 marketplace에는 여러 유형의 plugin이 있다.

Code intelligence

TypeScript, Python, Rust LSP / 정의 이동, 참조 찾기, type error 확인

External integrations

GitHub, GitLab, Jira, Figma, Sentry / 외부 도구 연결

Security review

security guidance / 변경사항 보안 검토

Development workflow

commit, PR review, SDK tools / 반복 개발 절차 지원

Output styles

learning, explanatory style / 응답 방식 변경

공식 discovery 문서는 code intelligence plugin이 Claude에게 LSP 기반 code navigation, diagnostics, type 정보 등을 제공하고, external integration plugin은 GitHub, GitLab, Jira, Figma, Sentry 같은 MCP 서버 설정을 묶어 제공한다고 설명한다.

초보자는 직접 plugin을 만들기 전에, 먼저 공식 marketplace에서 필요한 plugin을 설치해보는 것이 좋다.

27Plugin dependency와 version 관리

팀 plugin을 만들기 시작하면 dependency 관리가 중요해진다.

예를 들어 deploy-kit plugin이 secrets-vault plugin에 의존한다고 하자. secrets-vault가 새 버전에서 MCP tool 이름을 바꾸면 deploy-kit이 깨질 수 있다.

공식 dependency 문서는 plugin이 plugin.json이나 marketplace entry에서 다른 plugin dependency를 선언할 수 있고, 기본적으로 최신 버전을 따라가지만 version constraint를 사용하면 검증된 범위에 고정할 수 있다고 설명한다.

예시는 다음과 같다.

{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

초보자는 처음부터 dependency까지 다룰 필요는 없다. 다만 팀 plugin을 배포하기 시작하면 "업데이트가 자동으로 들어와도 안전한가"를 반드시 생각해야 한다.

28Skill, Plugin, MCP, Hook, Subagent 선택 기준

지금까지 배운 기능이 많아졌기 때문에 선택 기준을 다시 정리하자.

프로젝트 기본 규칙을 항상 알려주고 싶다

CLAUDE.md

특정 작업 절차를 필요할 때만 불러오고 싶다

Skill

내가 직접 짧은 명령으로 실행하고 싶다

Skill 직접 호출

작업 후 formatter를 항상 실행하고 싶다

Hook

GitHub, Sentry, DB 같은 외부 도구를 연결하고 싶다

MCP

큰 탐색·리뷰를 별도 컨텍스트에 맡기고 싶다

Subagent

skill, agent, hook, MCP를 팀에 배포하고 싶다

Plugin

응답 톤과 형식만 바꾸고 싶다

Output style

실전 기준은 다음과 같다.

지식 → Skill
자동 실행 → Hook
외부 연결 → MCP
작업 위임 → Subagent
팀 배포 → Plugin
항상 읽을 기본 규칙 → CLAUDE.md

29초보자가 처음부터 깊게 몰라도 되는 부분

25단원에서 가장 중요한 것은 "언제 분리할지"를 아는 것이다. 처음부터 plugin marketplace를 만들거나, dependency version constraint를 설계하거나, 복잡한 LSP plugin을 작성할 필요는 없다.

초보자 단계에서는 아래만 하면 충분하다.

1. CLAUDE.md를 짧게 유지한다.
2. 반복 절차가 생기면 .claude/skills/로 분리한다.
3. 위험한 작업은 자동 호출하지 않게 설정한다.
4. 여러 프로젝트에서 반복되면 plugin을 고려한다.
5. 팀에 배포하기 전에는 local/plugin-dir로 충분히 테스트한다.

지금 당장 몰라도 되는 고급 영역은 다음과 같다.

plugin marketplace 직접 운영

팀 배포 단계에서 필요

plugin dependency version constraint

plugin이 많아졌을 때 필요

LSP plugin 제작

언어 서버를 직접 연결해야 할 때 필요

background monitors

실시간 이벤트 반응이 필요할 때 필요

enterprise managed plugin policy

조직 운영 단계에서 필요

plugin submission

커뮤니티 배포 단계에서 필요

30실전 워크플로우: 반복 프롬프트를 skill로 바꾸기

1단계: 반복 프롬프트 찾기

API endpoint 만들 때마다 입력값 검증, 에러 형식, 테스트까지 챙겨줘.

2단계: skill 생성

mkdir -p .claude/skills/api-conventions

.claude/skills/api-conventions/SKILL.md

---
description: API endpoint implementation rules. Use when creating or modifying API routes, validation, services, or API tests.
---

# API endpoint rules

When implementing API endpoints:

1. Validate all external input.
2. Keep business logic in services.
3. Use consistent error response format.
4. Add tests for success and failure cases.
5. Avoid leaking internal details.

Before editing, list:
- files to change
- validation updates
- service updates
- tests to add

3단계: 테스트

새로운 user profile update API를 추가해줘.
프로젝트 규칙에 맞춰 계획부터 세워줘.

Claude가 자동으로 skill을 적용하는지 본다. 자동 적용이 안 되면 직접 호출한다.

/api-conventions user profile update API를 추가하는 계획을 세워줘.

31실전 워크플로우: skill이 많아지면 plugin으로 묶기

프로젝트가 커지면 다음 파일들이 생길 수 있다.

.claude/
├── skills/
│   ├── api-conventions/
│   ├── security-review/
│   ├── testing-strategy/
│   └── deploy-checklist/
├── agents/
│   ├── code-reviewer.md
│   └── security-reviewer.md
└── hooks/
    └── protect-files.sh

이 구성이 한 프로젝트에서만 쓰이면 그대로 두면 된다.

하지만 여러 프로젝트에서 반복된다면 plugin으로 묶는다.

team-dev-kit/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── api-conventions/
│   ├── security-review/
│   ├── testing-strategy/
│   └── deploy-checklist/
├── agents/
│   ├── code-reviewer.md
│   └── security-reviewer.md
└── hooks/
    └── hooks.json

공식 문서도 이미 .claude/ directory에 skills나 hooks가 있다면 plugin으로 전환해 공유와 배포를 쉽게 할 수 있다고 설명한다.

32Plugin을 팀에 배포하기 전 체크리스트

이름

plugin name이 명확하고 충돌 가능성이 낮은가

설명

어떤 문제를 해결하는지 description에 드러나는가

version

업데이트 기준이 되는 version이 있는가

skills

자동 호출되는 skill과 직접 호출 전용 skill을 구분했는가

agents

도구 권한이 최소화되어 있는가

hooks

위험한 shell command가 없는가

MCP

토큰과 URL이 안전하게 처리되는가

namespace

/plugin-name:skill 형태가 팀원에게 이해되는가

테스트

--plugin-dir 또는 local marketplace로 설치 테스트했는가

보안

민감정보가 포함되어 있지 않은가

Plugin은 설치되는 순간 팀원의 Claude Code 환경에 영향을 줄 수 있다. 특히 hooks와 MCP 서버가 포함된 plugin은 더 신중하게 검토해야 한다.

33Skill과 Plugin 사용 시 흔한 실수 ① · ②

모든 규칙을 CLAUDE.md에 넣음

컨텍스트 낭비 / 절차는 skill로 분리

skill description이 모호함

자동 호출이 잘 안 됨 / "언제 쓸지"를 앞에 명확히 작성

skill 본문이 너무 김

로드 후 매 턴 비용 증가 / supporting files로 분리

배포 skill이 자동 호출됨

위험한 작업이 의도치 않게 제안될 수 있음 / disable-model-invocation: true

34Skill과 Plugin 사용 시 흔한 실수 ③ · ④

hook을 skill처럼 사용

실행 보장과 지식 제공이 섞임 / 자동 실행은 hook, 지식은 skill

plugin을 너무 빨리 만듦

관리 부담 증가 / 먼저 standalone으로 검증

plugin에 개인 토큰 포함

보안 사고 위험 / 환경 변수와 MCP 인증 사용

plugin dependency를 무제한 최신으로 둠

상위 plugin 변경으로 깨질 수 있음 / 안정화 후 version constraint 고려

공식 plugin을 검토 없이 설치

권한·MCP 영향 파악 어려움 / /plugin에서 구성요소 확인

35초보자용 추천 순서

처음부터 plugin 개발자가 되려고 하지 말고, 아래 순서로 익히면 된다.

CLAUDE.md를 짧게 정리한다.
반복되는 지시문을 하나 찾는다.
.claude/skills/<name>/SKILL.md로 분리한다.
/skill-name으로 직접 호출해본다.
description을 조정해 자동 호출이 잘 되는지 본다.
필요하면 supporting file을 추가한다.
subagent에 skill을 연결해본다.
여러 프로젝트에서 반복되면 plugin으로 묶는다.
팀 배포 전 hooks, MCP, 권한을 검토한다.

섹션 25 · 마무리

이 단원의 핵심 정리

Skills는 Claude에게 프로젝트별 전문 지식과 반복 절차를 제공하는 기능이다. 같은 지시문, 체크리스트, 작업 절차를 반복해서 붙여넣고 있다면 skill로 분리한다. CLAUDE.md는 항상 필요한 짧은 기본 규칙만 담고, 특정 작업에만 필요한 긴 절차는 skill로 옮긴다.

Plugins는 skills, agents, hooks, MCP 서버 등을 묶어 팀이나 여러 프로젝트에 배포하는 패키지다. 개인 실험이나 프로젝트 전용 설정은 .claude/ standalone으로 시작하고, 여러 프로젝트에서 재사용하거나 팀에 배포해야 할 때 plugin으로 전환한다.

마지막으로 기준을 이렇게 잡으면 된다.

항상 필요한 기본 규칙 → CLAUDE.md / 반복되는 작업 지식 → Skill / 명시적으로 실행할 절차 → 직접 호출 skill / 항상 실행되어야 하는 자동화 → Hook / 외부 도구 연결 → MCP / 큰 작업 분리 → Subagent / 팀 배포와 버전 관리 → Plugin

초보자는 skill 하나를 제대로 만드는 것부터 시작하면 된다. Plugin은 그 skill과 agent, hook이 팀 전체에서 반복적으로 필요해졌을 때 포장하는 단계다.

가이드 완료

Claude Code 가이드 25편 완료. 다음 단원이 있다면 진행하세요.

26. IDE와 함께 사용하는 방법

01IDE 연동은 Claude Code를 IDE 안에서 더 편하게 쓰는 방식

Claude Code의 기본은 터미널 CLI입니다.

cd my-project
claude

하지만 실제 개발자는 대부분 VS Code, Cursor, Windsurf, IntelliJ, PyCharm, WebStorm 같은 IDE에서 코드를 봅니다. IDE 연동은 Claude Code가 IDE와 연결되어 다음 정보를 더 잘 활용하게 해줍니다.

현재 열려 있는 파일
선택한 코드 범위
IDE diagnostics
diff viewer
파일 경로 @-mention
여러 세션 탭
Plan review

즉, IDE 연동은 Claude Code를 "터미널에서만 쓰는 도구"가 아니라 코드 에디터와 붙어 있는 개발 보조자로 만드는 기능입니다.

02터미널 사용과 IDE 사용의 차이 (상)

구분

터미널 CLI

강점

빠른 실행, 스크립트, 원격 서버, 자동화

적합한 작업

테스트, 빌드, Git, CI, 대형 명령

인터페이스

대화형 터미널

03터미널 사용과 IDE 사용의 차이 (하)

구분

IDE 연동

강점

시각적 diff, 선택 영역 공유, 파일 탐색

적합한 작업

코드 읽기, 수정 검토, 선택 코드 질문

인터페이스

패널, 탭, diff viewer

04초보자의 권장 워크플로우

초보자에게 가장 좋은 방식은 다음과 같습니다.

Claude Code 기본 개념 학습 → 터미널 CLI
실제 코드 수정과 리뷰 → IDE 연동
긴 로그, 테스트, Git 명령 → 터미널
선택한 코드 설명, diff 검토 → IDE

05VS Code에서 Claude Code 설치하기

VS Code에서는 Claude Code 확장을 설치해 사용할 수 있습니다. 요구사항은 VS Code 1.98.0 이상과 Anthropic 계정입니다. 확장에는 CLI도 포함되어 있어, 고급 기능이 필요하면 VS Code의 integrated terminal에서 claude를 실행할 수 있습니다.

다음 순서로 설치합니다.

1. Extensions 열기
   - macOS: Cmd+Shift+X
   - Windows/Linux: Ctrl+Shift+X
2. "Claude Code" 검색
3. Install 클릭
4. Spark 아이콘으로 Claude Code 열기
5. 브라우저에서 로그인

06VS Code에서 Claude를 여는 방법

방법

설명

Editor Toolbar Spark icon

현재 파일을 보면서 빠르게 Claude 열기

Activity Bar Spark icon

세션 목록 보기

Command Palette

"Claude Code" 명령 검색

Status Bar

하단 Claude Code 표시 클릭

Integrated terminal

claude 실행

07VS Code에서 선택 코드 질문하기

IDE 연동의 가장 큰 장점은 "현재 보고 있는 코드"를 쉽게 Claude에게 넘길 수 있다는 점입니다.

예를 들어 어떤 파일에서 20~40줄을 선택한 뒤 Claude에게 묻습니다.

이 선택한 코드가 어떤 역할을 하는지 설명해줘.

VS Code 확장은 선택한 텍스트를 Claude가 자동으로 볼 수 있게 해줍니다. 더 명확하게 파일 경로와 줄 번호를 프롬프트에 넣고 싶다면 macOS에서는 Option+K, Windows/Linux에서는 Alt+K를 눌러 @file.ts#5-10 같은 참조를 삽입할 수 있습니다.

08선택 코드 질문 예시

실전 예시는 다음과 같습니다.

@src/auth/session.ts#15-80
이 코드에서 세션 만료 처리가 어떻게 동작하는지 설명해줘.

@src/api/users.ts#30-120
이 API에서 입력값 검증이 빠진 부분이 있는지 확인해줘.

09IDE diff viewer로 수정 검토하기

터미널에서 Claude가 파일을 수정하면 git diff로 확인하는 습관이 중요합니다. IDE 연동을 쓰면 이 과정을 더 시각적으로 볼 수 있습니다.

VS Code 확장에서는 Claude가 파일을 수정하려고 할 때 원본과 제안 변경사항을 side-by-side diff로 보여주고, 사용자가 accept, reject, 또는 추가 지시를 할 수 있습니다.

10IDE diff viewer 사용 흐름

초보자 기준으로는 다음 흐름이 좋습니다.

1. Claude에게 수정 계획 요청
2. Plan 또는 diff 확인
3. IDE diff viewer에서 변경 줄 검토
4. 이상하면 reject 또는 수정 요청
5. 승인 후 테스트 실행
6. 마지막에 git diff 재확인

11VS Code에서 Plan Mode 사용하기

IDE 안에서 Plan Mode를 쓰면 수정 전 계획을 문서처럼 검토하기 쉽습니다.

/plan refactor the authentication module

VS Code 확장에서는 Plan Mode에서 Claude가 무엇을 할지 설명하고, 사용자가 승인하기 전까지 변경하지 않습니다.

12Plan Mode 요청 예시

좋은 요청 예시는 다음과 같습니다.

/plan add password reset flow

조건:
- 수정 전 관련 파일만 먼저 조사
- DB migration 필요 여부 확인
- 테스트 계획 포함
- 보안 위험 별도 정리

13VS Code prompt box의 자주 쓰는 기능

기능

설명

Permission mode

normal, Plan, auto-accept 등 전환

Command menu

/로 명령 메뉴 열기

Context indicator

컨텍스트 사용량 확인

Extended thinking

어려운 문제에서 깊은 추론 토글

Multi-line input

Shift+Enter로 줄바꿈

File attachment

파일 첨부 또는 @-mention

14VS Code 유용한 단축키

단축키

용도

Cmd+Esc / Ctrl+Esc

editor와 Claude 사이 focus 전환

Cmd+Shift+Esc / Ctrl+Shift+Esc

새 Claude 대화를 editor tab으로 열기

Option+K / Alt+K

현재 파일·선택 범위 @-mention 삽입

Cmd+Shift+T / Ctrl+Shift+T

최근 닫은 Claude session tab 다시 열기

Shift+Enter

여러 줄 입력

15VS Code에서 CLI도 함께 쓰기

IDE 확장을 쓰더라도 CLI를 버릴 필요는 없습니다. VS Code의 integrated terminal을 열고 그대로 실행하면 됩니다.

claude

VS Code integrated terminal에서 claude를 실행하면 CLI가 IDE와 자동 통합되어 diff viewing과 diagnostic sharing 같은 기능을 사용할 수 있습니다. 외부 terminal을 쓰고 있다면 Claude Code 안에서 /ide를 실행해 VS Code에 연결할 수 있습니다.

16VS Code CLI와 IDE 활용 분담

실전에서는 이렇게 나눕니다.

코드 줄 단위 질문 → VS Code panel
긴 명령, 테스트, 빌드 → integrated terminal
시각적 변경 검토 → IDE diff viewer
세션 전체 제어 → CLI 또는 panel 둘 다 가능

17VS Code 설정: 확장 설정과 Claude Code 설정 구분

설정 종류

위치

VS Code extension settings

VS Code Settings → Extensions → Claude Code

Claude Code settings

~/.claude/settings.json, .claude/settings.json

VS Code extension settings는 VS Code 안에서의 동작을 제어하고, Claude Code settings는 CLI와 확장이 함께 사용하는 설정입니다.

18설정 구분 요점

초보자는 이렇게 기억하면 됩니다.

VS Code 화면 동작 → VS Code 설정
Claude Code 권한·hooks·MCP → Claude Code settings.json

19JetBrains IDE에서 Claude Code 사용하기

JetBrains 계열 IDE를 쓰는 경우 전용 Claude Code plugin을 설치합니다.

지원되는 IDE는 다음과 같습니다.

IntelliJ IDEA
PyCharm
Android Studio
WebStorm
PhpStorm
GoLand

20JetBrains 설치 절차

1. Settings → Plugins 열기
2. "Claude Code" 검색
3. Install
4. IDE restart
5. IDE terminal에서 claude 실행

21JetBrains에서 사용하는 방법

JetBrains에서는 IDE integrated terminal에서 claude를 실행하면 통합 기능이 활성화됩니다.

claude

외부 터미널에서 Claude Code를 실행 중이라면 세션 안에서 다음을 입력합니다.

/ide

22JetBrains 주요 기능

기능

설명

Quick launch

IDE에서 Claude Code 빠르게 열기

Diff viewing

변경사항을 IDE diff viewer에서 확인

Selection context

현재 선택 영역이나 탭을 Claude에 공유

File reference shortcut

현재 파일 범위를 @src/auth.ts#L1-99 형태로 삽입

Diagnostic sharing

IDE lint·syntax error를 Claude에게 공유

23JetBrains diff 설정

JetBrains에서 Claude의 변경사항을 IDE diff viewer로 보고 싶다면 /config에서 diff tool 설정을 확인합니다.

/config

그다음 diff tool을 다음 중 하나로 설정합니다.

auto      → IDE diff viewer 사용
terminal  → 터미널 안에서 diff 확인

24WSL2와 JetBrains 사용 시 주의

Windows에서 WSL2와 JetBrains를 함께 쓰면 IDE가 감지되지 않는 경우가 있습니다.

대표 증상:

No available IDEs detected

주된 원인은 WSL2의 NAT networking 또는 Windows Firewall이 WSL2와 Windows host의 IDE 사이 연결을 막는 것입니다. JetBrains plugin 설정에서 Claude command를 WSL용으로 지정할 수 있습니다.

wsl -d Ubuntu -- bash -lic "claude"

25WSL2 감지 문제 — 방법 1. Windows Firewall 허용

WSL 안에서 IP를 확인합니다.

hostname -I

Windows PowerShell을 관리자 권한으로 열고, 예시처럼 firewall rule을 만듭니다.

New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16

IP 대역은 자신의 WSL2 subnet에 맞게 조정해야 합니다.

26WSL2 감지 문제 — 방법 2. Mirrored networking 사용

Windows 11 22H2 이상이라면 .wslconfig에 다음을 추가할 수 있습니다.

[wsl2]
networkingMode=mirrored

그다음 PowerShell에서 WSL을 재시작합니다.

wsl --shutdown

27JetBrains ESC 키 문제

JetBrains terminal에서 Esc가 Claude Code 작업 중단으로 동작하지 않을 수 있습니다. 이 경우 IDE가 Esc를 "editor로 focus 이동" 단축키로 먼저 가져가기 때문입니다.

해결 방법:

Settings → Tools → Terminal
→ "Move focus to the editor with Escape" 해제

28IDE에서 코드 탐색하기

IDE 연동을 쓰면 Claude에게 "파일 전체를 다 뒤져봐"라고 하기보다 현재 보고 있는 파일과 선택 영역을 중심으로 질문하는 편이 좋습니다.

나쁜 요청:

이 프로젝트 전체 구조를 다 분석해줘.

좋은 요청:

현재 선택한 auth middleware를 기준으로
이 함수가 호출되는 흐름을 찾아줘.
관련 파일은 최대 5개만 보고,
수정은 하지 말고 요약만 해줘.

29더 좋은 코드 탐색 요청

@src/middleware/auth.ts#20-88
이 코드가 요청을 거부하는 조건을 정리해줘.
그리고 이 조건과 연결된 테스트 파일을 찾아줘.
수정은 하지 마.

IDE에서는 "선택 영역 → 질문 → 관련 파일 소수 탐색 → 계획" 흐름이 가장 안정적입니다.

30IDE에서 코드 수정 요청

IDE에서 Claude에게 수정 요청을 할 때도 바로 "고쳐줘"보다 범위를 제한하는 것이 좋습니다.

@src/api/login.ts#10-90

이 함수에 입력값 검증을 추가해줘.

조건:
- 수정 전 계획을 먼저 설명
- 기존 응답 형식 유지
- 새 dependency 추가 금지
- 관련 테스트가 있으면 함께 업데이트
- 변경 후 diff 기준으로 설명

31수정 후 변경사항 확인

수정 후에는 IDE diff viewer에서 확인하고, 필요하면 다음처럼 요청합니다.

이 diff에서 변경 범위가 과한 부분이 있는지 확인해줘.
불필요한 리팩터링은 되돌리고, 입력값 검증에 필요한 부분만 남겨줘.

Claude가 수정했더라도 최종 확인은 사용자가 해야 합니다.

git diff
npm test
npm run lint

32IDE에서 리뷰 흐름 만들기

IDE 연동의 장점은 변경사항을 눈으로 보면서 리뷰할 수 있다는 점입니다. 추천 흐름은 다음과 같습니다.

1. Claude에게 계획 요청
2. IDE diff viewer로 변경사항 확인
3. /diff 또는 git diff로 전체 diff 재확인
4. /code-review 실행
5. 테스트·lint 실행
6. 커밋 전 다시 git status 확인

33IDE 리뷰 프롬프트 예시

현재 변경사항을 리뷰해줘.

중점:
- 실제 버그 가능성
- 보안 문제
- 테스트 누락
- 과한 변경
- 유지보수성

스타일 취향은 제외하고,
수정이 필요한 항목만 Critical / Warning / Suggestion으로 나눠줘.

34IDE diagnostic을 활용하기

JetBrains plugin은 IDE의 diagnostic error, 예를 들어 lint error나 syntax error를 Claude에게 자동 공유할 수 있습니다. VS Code도 IDE와 CLI가 통합되면 diagnostic sharing 같은 기능을 활용할 수 있습니다.

좋은 요청은 다음과 같습니다.

IDE diagnostic에 표시된 TypeScript 오류를 기준으로 원인을 설명해줘.
수정 전에는 어떤 파일을 바꿀지 먼저 말해줘.

35IDE diagnostic 해결 요청

현재 파일의 lint 오류를 고쳐줘.
단, 스타일 변경은 최소화하고 오류 해결에 필요한 줄만 바꿔줘.

36큰 붙여넣기는 IDE에서도 피하기

초보자가 자주 하는 실수는 긴 로그나 파일 전체를 Claude prompt box에 그대로 붙여넣는 것입니다.

10,000자 이상을 붙여넣으면 Claude Code가 입력창을 usable하게 유지하기 위해 [Pasted text] placeholder로 접습니다. VS Code integrated terminal은 매우 큰 paste에서 문자를 누락할 수 있으므로, 큰 파일이나 긴 로그는 파일로 저장한 뒤 Claude에게 그 파일을 읽게 하는 방식을 권장합니다.

37로그 파일 처리 방법

나쁜 방식:

여기에 5만 줄 로그 붙여넣기

좋은 방식:

npm test 2>&1 | tee test-output.log

그다음 Claude에게 요청합니다.

@test-output.log 를 읽고 실패한 테스트 이름, 에러 메시지, 원인 후보만 요약해줘.
전체 로그를 다시 출력하지는 마.

38IDE와 권한 설정

IDE에서 쓰더라도 Claude Code의 권한 시스템은 그대로 중요합니다. 예를 들어 .env, secrets, credentials 파일은 계속 보호해야 합니다.

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)"
    ]
  }
}

39IDE에서 auto-accept는 신중하게 사용

IDE diff viewer가 편하다고 해서 모든 변경을 자동 수락하면 안 됩니다. JetBrains 공식 문서는 auto-edit permission이 활성화된 상태에서 Claude Code가 IDE configuration file을 수정할 수 있으면, IDE가 자동 실행할 수 있는 설정 파일과 결합되어 위험이 커질 수 있다고 경고합니다.

초보자 기준은 다음과 같습니다.

학습 단계 → manual approval
작은 안전한 변경 → accept edits 가능
대형 리팩터링 → Plan Mode + manual approval
IDE 설정 파일 변경 → 반드시 수동 검토
보안·배포·환경변수 관련 파일 → 자동 수락 금지

40IDE가 연결되지 않을 때 확인할 것

문제가 생기면 먼저 아래 순서로 확인합니다.

증상

확인할 것

VS Code 확장이 보이지 않음

VS Code reload 또는 재시작

로그인 화면 반복

브라우저 인증, 환경 변수 상속 확인

ANTHROPIC_API_KEY가 인식 안 됨

terminal에서 code .로 VS Code 실행

JetBrains에서 Claude command not found

claude --version, plugin 설정의 command path

41IDE 연결 문제 해결 (계속)

JetBrains IDE not detected

plugin enabled, IDE restart, integrated terminal, WSL 설정

diff가 IDE에 안 뜸

/config에서 diff tool 확인

Esc가 중단이 안 됨

JetBrains terminal ESC 설정

큰 paste가 이상함

파일로 저장 후 @file 참조

설정이 안 먹힘

/status로 setting sources 확인

원인 불명

/doctor 또는 claude doctor

42초보자용 IDE 사용 루틴 — 작업 시작

작업을 시작할 때:

cd my-project
code .

VS Code를 터미널에서 열면 환경 변수가 IDE에 잘 전달될 가능성이 높습니다. API key가 shell에 있는데 확장이 로그인 prompt를 보이면, VS Code가 shell environment를 상속하지 않았을 수 있으므로 code .로 실행하거나 Claude 계정으로 로그인하는 것이 좋습니다.

43초보자용 IDE 사용 루틴 — 파일 선택 후 질문

@src/auth/session.ts#10-70
이 코드의 역할과 위험한 edge case를 설명해줘.
수정은 하지 마.

44초보자용 IDE 사용 루틴 — 계획 요청

/plan fix session expiration handling

조건:
- 관련 파일만 조사
- 수정 전 계획 제시
- 테스트 계획 포함

45초보자용 IDE 사용 루틴 — 변경 검토

이 diff를 기준으로 변경사항을 설명해줘.
의도하지 않은 리팩터링이 있는지 확인해줘.

46초보자용 IDE 사용 루틴 — 테스트와 최종 리뷰

테스트:

npm test
npm run lint

최종 리뷰:

/code-review high

47VS Code와 JetBrains 선택 기준

사용 환경

48IDE 연동 시 좋은 프롬프트 패턴 ① · ②

선택 코드 설명

선택한 코드의 역할을 설명해줘.
입력, 출력, 예외 상황, 호출 관계로 나눠서 정리해줘.
수정은 하지 마.

작은 수정

선택한 함수에 null 처리만 추가해줘.
기존 구조는 바꾸지 말고, 변경 후 diff 기준으로 설명해줘.

49IDE 연동 시 좋은 프롬프트 패턴 ③ · ④

리팩터링 전 계획

이 파일을 바로 고치지 말고,
먼저 리팩터링 계획만 세워줘.

포함할 것:
- 바꿀 파일
- 바꾸지 않을 파일
- 위험한 부분
- 테스트 계획

리뷰

현재 diff를 리뷰해줘.
실제 버그, 보안 문제, 테스트 누락만 지적하고,
취향이나 스타일 의견은 제외해줘.

50IDE 사용 시 흔한 실수 (상)

실수

문제

선택 범위 없이 "이거 봐줘"라고 함

Claude가 범위를 잘못 잡을 수 있음

큰 로그를 prompt에 붙여넣음

누락·컨텍스트 낭비

auto-accept를 항상 켬

위험한 변경 승인 가능

IDE 설정 파일 변경을 가볍게 승인

IDE 자동 실행 위험

51IDE 사용 시 흔한 실수 (하)

실수

해결

terminal과 IDE project root가 다름

같은 project root에서 실행

/config diff tool을 확인 안 함

auto 또는 terminal 선택

WSL2 문제를 Claude 문제로 오해

WSL2 firewall 또는 mirrored networking 확인

.env 보호 없이 사용

permissions.deny 설정

52IDE 사용의 핵심 정리 (상)

IDE 연동은 Claude Code를 더 편하게 쓰는 방법이지, 터미널 CLI를 대체하는 기능만은 아닙니다. 터미널은 명령 실행, 테스트, Git, 자동화에 강하고, IDE는 파일 선택, 시각적 diff, 코드 리뷰, diagnostic 공유에 강합니다.

초보자는 다음 흐름으로 쓰면 됩니다.

1. IDE에서 파일과 코드 범위를 선택한다.
2. Claude에게 선택 범위 기준으로 질문한다.
3. 큰 수정 전에는 /plan을 사용한다.
4. IDE diff viewer로 변경사항을 검토한다.
5. 테스트와 lint는 터미널에서 실행한다.
6. /diff 또는 git diff로 최종 확인한다.
7. 민감 파일과 IDE 설정 파일은 자동 수락하지 않는다.

53IDE 사용의 핵심 정리 (하)

정리하면 다음과 같습니다.

터미널 CLI → 실행과 자동화
VS Code / JetBrains → 시각적 검토와 코드 컨텍스트
/ide → 외부 터미널과 IDE 연결
/config → diff tool과 기본 동작 확인
/status 또는 /doctor → 설정과 연결 문제 진단

IDE와 Claude Code를 함께 쓸 때 가장 중요한 원칙은 "편해졌다고 검토를 생략하지 않는 것"입니다. IDE diff viewer, Plan Mode, 권한 설정, 테스트 실행을 함께 사용해야 안전한 실전 워크플로우가 됩니다.

섹션 26 · 마무리

이 단원에서 기억할 것

IDE와 Claude Code는 함께 쓸 때 가장 강합니다. 하지만 편의성이 안전성을 대체해서는 안 됩니다.

선택 범위 → 질문 → Plan Mode → IDE diff 검토 → 테스트

이 흐름을 지키면 IDE에서도 실수를 줄일 수 있습니다.

다음 단원

27단원. (7부 계속)

27. 이미지와 멀티모달 입력 활용하기

01멀티모달 입력은 말로 설명하기 어려운 상황에 쓰는 기능

코드와 로그는 텍스트로 설명하기 쉽습니다. 하지만 시각적 상태, 화면 레이아웃, 에러 메시지, 다이어그램은 말로 설명하기 어렵습니다.

이럴 때 이미지를 넣으면 Claude가 화면 자체를 보고 분석할 수 있습니다.

버튼이 오른쪽으로 밀려 있어요.

모바일 화면에서 입력창이 잘립니다.

에러 모달이 뜨는데 정확히 어느 부분이 문제인지 모르겠습니다.

이 ERD를 보고 Prisma 모델을 만들어야 합니다.

Figma 목업처럼 Tailwind 컴포넌트를 만들고 싶습니다.

02멀티모달 입력이 필요한 상황

초보자는 이렇게 기억하면 됩니다.

텍스트로 충분히 설명 가능

텍스트로 질문

화면 상태가 중요함

이미지 첨부

디자인·레이아웃·다이어그램이 중요함

이미지 첨부

이미지 속 텍스트가 핵심임

확대/선명도 확인 후 첨부

03이미지 입력 방법 3가지

Claude Code에서 이미지를 넣는 방법은 세 가지입니다.

드래그 앤 드롭

이미지 파일을 Claude Code 창에 끌어다 놓기 (저장된 스크린샷, 목업 파일)

클립보드 붙여넣기

캡처 후 붙여넣기 (에러 화면, UI 버그)

파일 경로 전달

이미지 경로를 프롬프트에 적기 (프로젝트 안 이미지, 디자인 캡처 파일)

파일 경로 전달은 이렇게 합니다.

예시

이 이미지의 UI 문제를 분석해줘: /path/to/screenshot.png

04파일 경로 사용 예시

경로 전달 방식의 다양한 사용 예시입니다.

@docs/screenshots/login-error.png
이 화면에서 사용자가 헷갈릴 수 있는 부분을 찾아줘.

또는 이렇게 여러 이미지를 함께 제공할 수 있습니다.

방금 붙여넣은 [Image #1]을 기준으로
현재 로그인 폼의 레이아웃 문제를 설명해줘.

05붙여넣기 단축키 주의사항

이미지 붙여넣기 단축키는 터미널과 OS에 따라 다릅니다.

일반 터미널

Ctrl+V

iTerm2

Cmd+V도 가능

Windows / WSL

Alt+V 사용 가능

WSL에서 Ctrl+V가 터미널에 잡힘

Alt+V 사용

06붙여넣기 단축키 사용 팁

붙여넣은 이미지는 커서 위치에 [Image #N] 칩으로 삽입됩니다.

기본은 Ctrl+V입니다. 만약 단축키가 작동하지 않으면 다음 순서로 시도합니다.

Ctrl+V 기본 시도
iTerm2 사용자라면 Cmd+V 시도
Windows/WSL 사용자라면 Alt+V 시도
터미널이 단축키를 가로채면 다른 붙여넣기 키를 시도

07첨부된 이미지의 참조 방식

이미지를 붙여넣으면 Claude Code 입력창에 다음처럼 표시됩니다.

[Image #1]

이미지가 여러 개면 번호로 구분됩니다.

[Image #1] [Image #2] [Image #3]

이 번호를 프롬프트에서 직접 사용할 수 있습니다.

예시

[Image #1]은 현재 화면이고, [Image #2]는 목표 디자인이야. 두 화면의 차이를 분석하고 구현해야 할 CSS 변경사항을 정리해줘.

08이미지가 특히 유용한 상황

에러 화면 분석

이 에러 화면이 의미하는 원인을 설명해줘.

UI 버그 디버깅

모바일에서 버튼이 잘리는 이유를 추정해줘.

디자인 구현

이 목업을 React + Tailwind 컴포넌트로 구현할 계획을 세워줘.

다이어그램 분석

이 아키텍처 다이어그램의 흐름을 설명해줘.

ERD 분석

이 ERD와 맞는 Prisma schema를 제안해줘.

접근성 리뷰

이 화면에서 접근성 문제가 될 수 있는 부분을 찾아줘.

시각적 회귀 검토

이전 화면과 현재 화면의 차이를 비교해줘.

09에러 화면 캡처해서 질문하기

에러 화면을 붙여넣을 때는 단순히 "이게 뭐야?"라고 묻는 것보다, 어떤 상황에서 발생했는지 함께 적어야 합니다.

나쁜 예시

이 에러 뭐야?

좋은 예시

[Image #1]은 로그인 버튼을 누른 직후 나온 에러 화면이야.

상황:
- 브라우저: Chrome
- 환경: local dev
- 직전 작업: auth middleware 수정
- 기대 동작: 로그인 후 /dashboard로 이동
- 실제 동작: 이 에러 화면 표시

요청:
1. 에러 메시지에서 핵심 원인을 해석해줘.
2. 관련될 가능성이 높은 파일을 추정해줘.
3. 바로 수정하지 말고 확인 순서를 먼저 제안해줘.

10에러 화면과 함께 로그 제공하기

더 좋은 예시는 로그와 함께 주는 것입니다.

[Image #1]은 브라우저 에러 화면이고,
@server.log 는 같은 시각의 서버 로그야.

두 정보를 함께 보고 원인 후보를 우선순위로 정리해줘.
수정은 아직 하지 마.

이미지만 보면 화면 상태는 알 수 있지만, 코드 실행 흐름은 모를 수 있습니다. 따라서 발생 조건, 기대 동작, 실제 동작, 관련 로그를 같이 주는 것이 좋습니다.

11UI 스크린샷 분석 요청하기 · 나쁜 예

UI 스크린샷은 보이는 문제를 찾는 데 강합니다. 다만 Claude가 정확히 무엇을 봐야 하는지 지정해야 합니다.

나쁜 예시

이 화면 어때?

12UI 스크린샷 분석 요청하기 · 좋은 예

좋은 예시

[Image #1]은 현재 모바일 로그인 화면이야.

다음 관점으로 리뷰해줘.
1. 레이아웃 깨짐
2. 버튼 위치
3. 입력창 간격
4. 텍스트 가독성
5. 접근성 문제
6. 구현 파일 후보

수정은 하지 말고, 문제 목록과 우선순위만 정리해줘.

13UI 스크린샷과 함께 구현 파일 제공하기

구현까지 요청할 때는 다음처럼 합니다.

[Image #1]은 목표 디자인이고,
현재 구현 파일은 @src/components/LoginForm.tsx 이야.

요청:
1. 이미지와 현재 컴포넌트 구조를 비교해줘.
2. 필요한 변경사항을 Tailwind class 중심으로 정리해줘.
3. 바로 수정하지 말고 계획만 세워줘.

이미지 기반 구현은 한 번에 완벽히 맞추기 어렵습니다. 처음에는 차이 분석 → 계획 → 최소 수정 → 스크린샷 재검토 흐름으로 진행합니다.

14목업 기반 구현 요청하기

디자인 목업을 보고 컴포넌트를 만들 때는 여러 상태를 함께 주는 것이 좋습니다.

[Image #1] 기본 상태
[Image #2] hover 상태
[Image #3] loading 상태
[Image #4] error 상태

프롬프트는 다음처럼 작성합니다.

이 네 이미지를 기준으로 Button 컴포넌트를 구현하려고 해.

조건:
- React + TypeScript
- Tailwind 사용
- 상태: default, hover, loading, disabled, error
- 새 라이브러리 추가 금지
- 접근성 속성 포함
- 먼저 컴포넌트 API를 제안하고, 내가 승인하면 구현해줘.

15좋은 이미지 프롬프트의 구조

이미지를 넣을 때는 다음 네 가지를 함께 적습니다.

이 이미지가 무엇인지
어떤 상황에서 나온 것인지
Claude가 봐야 할 관점
원하는 출력 형식

템플릿은 다음과 같습니다.

구조 템플릿

[Image #1]은 _______ 화면이야. / 상황: / 분석 관점: / 출력 형식:

16좋은 이미지 프롬프트 템플릿

상세한 템플릿은 다음과 같습니다.

[Image #1]은 _______ 화면이야.

상황:
- 사용자가 한 행동:
- 기대 동작:
- 실제 동작:
- 관련 파일:
- 관련 로그:

분석 관점:
1. 원인 후보
2. 관련 코드 위치
3. 재현 방법
4. 수정 전 확인할 것

출력 형식:
- 확실한 사실
- 추정
- 추가 확인 필요
- 수정 계획

이 구조를 쓰면 Claude가 이미지를 그냥 설명하는 데 그치지 않고, 개발 작업으로 연결하기 쉽습니다.

17이미지 품질이 결과를 좌우한다

좋은 결과를 위해서는 이미지가 선명해야 하고, 중요한 텍스트가 읽을 수 있어야 하며, 지원 형식은 JPEG, PNG, GIF, WebP입니다. GIF 애니메이션은 지원되더라도 첫 프레임만 사용됩니다.

해상도

텍스트가 읽힐 정도로 충분히 선명하게

크롭

문제 영역을 포함하되, 주변 맥락도 조금 남기기

압축

너무 강한 JPEG 압축 피하기

텍스트

작은 글씨는 확대 캡처

다크모드

색 대비가 보이게 캡처

여러 상태

전후 비교, 정상/비정상 화면 함께 첨부

18이미지 캡처의 좋은 예와 나쁜 예

나쁜 캡처의 특징:

에러 메시지가 너무 작고 흐림
문제 영역만 잘려서 주변 컨텍스트 없음
민감정보가 그대로 노출됨

좋은 캡처의 특징:

문제 영역과 주변 UI가 함께 보임
에러 메시지가 읽힘
필요 없는 개인정보는 가림
전후 비교 이미지가 함께 있음

19이미지도 토큰과 비용을 사용한다

이미지는 공짜 컨텍스트가 아닙니다. 이미지는 대략 가로 픽셀 × 세로 픽셀 / 750 정도의 토큰을 사용하며, 이미지 토큰도 모델의 입력 토큰 비용에 포함됩니다.

또한 고해상도 이미지는 이전 모델 대비 최대 약 3배 많은 이미지 토큰을 사용할 수 있습니다. 불필요하게 큰 이미지는 미리 줄이는 것이 좋습니다.

20이미지 비용 효율 기준

초보자 기준은 다음과 같습니다.

작은 UI 문제

문제 영역 중심으로 캡처

전체 레이아웃 문제

전체 화면 캡처

텍스트가 핵심

글씨가 읽히도록 확대

많은 이미지 비교

필요한 것만 2~4장

긴 세션

/context와 /usage 확인

21여러 이미지를 함께 넣는 법

Claude는 여러 이미지를 함께 보고 비교할 수 있습니다.

예시는 다음과 같습니다.

[Image #1]은 목표 디자인이고,
[Image #2]는 현재 구현 화면이야.

두 이미지의 차이를 다음 기준으로 비교해줘.
1. spacing
2. typography
3. color
4. alignment
5. missing states
6. implementation priority

22여러 이미지 비교 예시 · 정상과 버그

또는 다음처럼 정상 화면과 버그 화면을 비교합니다.

[Image #1]은 정상 화면,
[Image #2]는 버그가 발생한 화면이야.

차이를 비교해서 어떤 CSS나 상태 조건이 원인일지 추정해줘.
수정 전 확인할 파일 후보를 알려줘.

23이미지와 코드 파일을 함께 주기

이미지만 주면 Claude는 화면은 이해하지만 실제 코드 위치를 모를 수 있습니다. 코드 파일을 함께 주면 분석 품질이 좋아집니다.

[Image #1]은 깨진 모바일 화면이고,
@src/components/Header.tsx 가 관련 컴포넌트야.

요청:
1. 화면에서 보이는 문제를 설명해줘.
2. Header.tsx에서 관련될 가능성이 높은 부분을 찾아줘.
3. CSS/Tailwind class 기준으로 수정 계획을 세워줘.
4. 바로 수정하지 말고 계획만 말해줘.

24이미지, 파일, 수정의 흐름

더 좋은 흐름은 다음입니다.

[Image #1] 화면 분석
→ 관련 파일 찾기
→ 수정 계획
→ 승인
→ 코드 수정
→ 테스트/스크린샷 재확인

이 흐름은 Plan Mode와 연결됩니다.

/plan fix the mobile header layout based on [Image #1]

25ERD와 데이터베이스 스키마 이미지 활용

ERD 이미지는 DB 모델 설계에 유용합니다.

[Image #1]은 새 결제 기능의 ERD야.

요청:
1. 엔티티와 관계를 표로 정리해줘.
2. Prisma schema 초안을 제안해줘.
3. cascade delete가 위험한 관계를 표시해줘.
4. migration 전에 확인해야 할 질문을 정리해줘.

26ERD와 현재 코드 비교하기

현재 코드와 비교할 수도 있습니다.

[Image #1]은 목표 ERD이고,
@prisma/schema.prisma 는 현재 스키마야.

두 구조를 비교해서 누락된 모델, 필드, relation을 정리해줘.
수정은 하지 말고 migration 계획만 세워줘.

주의할 점: ERD 이미지에서 작은 글씨가 잘 안 보일 수 있습니다. 테이블명과 컬럼명이 핵심이라면 확대 이미지나 원본 PDF를 함께 제공합니다.

27아키텍처 다이어그램 분석

아키텍처 다이어그램은 시스템 구조 이해에 유용합니다.

[Image #1]은 현재 서비스 아키텍처 다이어그램이야.

다음 형식으로 설명해줘.
1. 주요 컴포넌트
2. 요청 흐름
3. 데이터 저장 위치
4. 외부 의존성
5. 장애 지점
6. 보안상 주의할 경계

28아키텍처 다이어그램과 코드베이스 연결

코드베이스와 연결할 때는 다음처럼 묻습니다.

[Image #1]의 아키텍처 흐름과 현재 코드베이스가 일치하는지 확인해줘.

먼저 관련 파일을 찾아보고,
다이어그램과 실제 코드가 다른 부분만 요약해줘.
수정은 하지 마.

이 경우 탐색량이 커질 수 있으므로 subagent를 연결해도 좋습니다.

29Subagent와 함께 아키텍처 분석하기

Explore subagent를 사용해서
[Image #1]의 API gateway, auth service, billing service에 해당하는 파일을 찾아줘.
요약만 반환하고 수정하지 마.

30PDF도 시각 자료로 다룰 수 있다

Claude Code는 PDF 문서를 페이지 단위로 읽고 분석할 수 있으며, 특정 페이지 범위를 지정할 수 있습니다.

예시는 다음과 같습니다.

Analyze this PDF: /path/to/document.pdf

또는:

Read pages 1-5 of the PDF: /path/to/report.pdf

Claude는 PDF의 텍스트뿐 아니라 그림, 차트, 표도 분석할 수 있습니다.

31PDF 분석 시 주의할 점

PDF는 생각보다 많은 컨텍스트를 사용합니다. 표준 PDF는 최대 요청 크기 32MB, 최대 페이지 수 600페이지가 기준이며, 200K 컨텍스트 모델은 요청당 최대 100페이지입니다. 다만 복잡한 표, 작은 글씨, 많은 그래픽이 있는 PDF는 페이지 한도보다 먼저 컨텍스트를 채울 수 있습니다.

초보자는 PDF 전체를 한 번에 넣기보다 페이지 범위를 좁힙니다.

32PDF 분석 요청 · 나쁜 예와 좋은 예

나쁜 요청

이 300페이지 PDF 전체 분석해줘.

좋은 요청

이 PDF의 12~18페이지만 읽고,
인증 플로우와 관련된 요구사항만 요약해줘.

더 좋은 요청

이 PDF의 12~18페이지를 읽고 다음 형식으로 정리해줘.

- 요구사항 ID
- 관련 화면
- API 영향
- DB 영향
- 구현 전 질문

33PDF 속 차트·표·이미지 분석

PDF가 단순 텍스트 문서라면 텍스트 추출만으로도 충분할 수 있습니다. 하지만 차트, 표, 다이어그램, 스캔 이미지가 중요하다면 시각 분석이 필요합니다.

이 PDF의 5페이지 차트를 분석해줘.
단순 요약이 아니라, 차트가 말하는 추세와 구현 요구사항에 영향을 줄 수 있는 부분을 정리해줘.

또는:

이 PDF의 8페이지 표를 읽고,
API response schema로 바꿀 수 있는 필드 목록을 제안해줘.

34PDF 분석의 기술적 고려사항

PDF의 시각 분석에서 중요한 점은, 각 페이지가 이미지로도 처리되기 때문에 차트, 다이어그램, 비텍스트 요소에 대한 질문도 가능하다는 것입니다.

단, 특정 API 환경(Bedrock Converse API)에서는 전체 시각 PDF 분석을 위해 citations 옵션이 필요할 수 있으며, citations가 없으면 기본 텍스트 추출 모드로 처리될 수 있습니다.

35민감 정보는 반드시 가리고 첨부하기

스크린샷에는 생각보다 많은 민감정보가 들어갑니다.

계정 정보

이메일, 사용자명, 조직명

인증 정보

토큰, API key, session id

인프라 정보

서버 주소, 내부 도메인, IP

고객 정보

이름, 전화번호, 주소, 결제 정보

코드 정보

private repo 이름, branch 이름

운영 정보

production URL, admin panel, 로그 ID

36이미지 올리기 전 보안 체크리스트

이미지를 올리기 전에는 다음을 확인합니다.

이메일 주소 가렸는가
API key/token/session id 가렸는가
고객 개인정보 가렸는가
내부 URL/IP/도메인 가렸는가
결제·주문·계약 정보 가렸는가
브라우저 탭과 주소창에 민감정보가 없는가
터미널 prompt에 사용자명·서버명이 노출되지 않았는가

이 단원에서는 "이미지를 잘 쓰는 법"만큼 "보여주면 안 되는 것을 가리는 법"이 중요합니다.

37안전한 스크린샷 준비법

캡처 전에는 가능한 한 불필요한 영역을 줄입니다.

좋은 순서:

문제 화면을 재현한다.
민감 정보가 있는 탭, 주소창, 사이드바를 확인한다.
필요한 영역만 캡처한다.
토큰, 이메일, 고객정보를 가린다.
글자가 읽히는지 확인한다.
Claude Code에 붙여넣는다.

38운영체제별 스크린샷 캡처 방법

macOS: Cmd+Ctrl+Shift+4로 선택 영역을 클립보드에 캡처한 뒤 Claude Code에 붙여넣습니다.

Windows: Snipping Tool이나 Win+Shift+S로 선택 영역을 캡처한 뒤 붙여넣을 수 있습니다.

각 운영체제별 방법을 미리 숙지하면 효율적인 캡처와 붙여넣기 흐름을 만들 수 있습니다.

39민감정보를 가릴 때의 나쁜 예와 좋은 예

나쁜 예

검은색 반투명 박스로 토큰을 흐리게 처리
브라우저 주소창을 그대로 둠
고객 이메일 일부만 가림
터미널에 production host가 그대로 보임

좋은 예

민감정보 영역을 완전히 덮음
주소창과 탭 제목까지 확인
이메일·토큰·고객 ID 전체 제거
필요하면 샘플 값으로 대체

40민감정보 마스킹 안내 프롬프트

프롬프트에 다음처럼 명시할 수도 있습니다.

민감정보는 모두 가린 스크린샷이야.
가려진 값은 실제 값으로 추정하지 말고,
화면 구조와 에러 메시지만 기준으로 분석해줘.

41이미지 기반 요청에서 하지 말아야 할 것 · 1~3

실수 1. 이미지 하나만 던지고 "고쳐줘"

원인 파악이 불충분 → 상황, 기대 동작, 관련 파일 추가

실수 2. 흐릿한 스크린샷 사용

텍스트 오인식 가능 → 확대·고해상도 캡처

실수 3. 화면 전체를 무조건 캡처

컨텍스트 낭비, 민감정보 노출 → 문제 영역 중심으로 캡처

42이미지 기반 요청에서 하지 말아야 할 것 · 4~8

실수 4. 민감정보를 안 가림

보안 위험 → 캡처 전/후 마스킹

실수 5. 이미지에서 바로 코드 수정 요청

과한 추정 가능 → 먼저 분석과 계획 요청

실수 6. 여러 이미지를 순서 없이 첨부

비교 기준 혼란 → [Image #1], [Image #2] 의미 지정

실수 7. PDF 전체를 한 번에 분석

비용·컨텍스트 증가 → 페이지 범위 지정

실수 8. OCR처럼 100% 정확하다고 가정

작은 글씨 오인 가능 → 중요한 텍스트는 별도 복사 제공

43이미지 기반 디버깅 워크플로우 · 1단계

1단계: 화면 캡처

에러 화면, 관련 UI, console 메시지 일부를 캡처합니다.

민감정보는 가립니다.

44이미지 기반 디버깅 워크플로우 · 2~3단계

2단계: 상황 설명

[Image #1]은 결제 버튼 클릭 후 나온 에러 화면이야.

상황:
- local 환경
- Stripe test mode
- 직전 변경: checkout API 수정
- 기대 동작: checkout session 생성
- 실제 동작: 화면의 에러 표시

3단계: 원인 후보 요청

이미지의 에러 메시지와 화면 상태를 보고
원인 후보를 우선순위로 정리해줘.
수정은 하지 말고, 확인할 파일과 로그를 먼저 제안해줘.

45이미지 기반 디버깅 워크플로우 · 4~5단계

4단계: 관련 파일 제공

@src/api/checkout.ts
@src/components/CheckoutButton.tsx
이 두 파일과 [Image #1]을 함께 보고 원인을 좁혀줘.

5단계: 계획 후 수정

/plan fix checkout error shown in [Image #1]

46UI 구현 워크플로우 · 1~2단계

1단계: 목표 이미지와 현재 구현 비교

[Image #1]은 목표 디자인,
[Image #2]는 현재 구현 화면이야.

차이를 분석해줘.
수정은 하지 말고, 우선순위만 정리해줘.

2단계: 관련 컴포넌트 연결

@src/components/ProfileCard.tsx
@src/components/ProfileCard.module.css

이 파일들과 두 이미지를 비교해서
어떤 스타일 변경이 필요한지 계획해줘.

47UI 구현 워크플로우 · 3~4단계

3단계: 최소 수정

좋아. 목표 디자인과 가장 차이가 큰 spacing과 typography만 먼저 수정해줘.
색상 변경은 아직 하지 마.

4단계: 재검토

수정 후 다시 스크린샷을 붙여넣습니다.

[Image #3]은 수정 후 화면이야.
[Image #1] 목표 디자인과 비교해서 남은 차이를 정리해줘.

48접근성 리뷰에 이미지 활용하기

이미지로 접근성 문제를 찾을 수도 있습니다.

[Image #1]은 회원가입 화면이야.

접근성 관점으로 리뷰해줘.
1. 색 대비
2. label과 input 관계
3. 버튼 상태 구분
4. 에러 메시지 위치
5. 키보드 사용자가 헷갈릴 부분
6. 스크린리더 설명이 필요해 보이는 부분

코드 수정은 하지 말고 체크리스트만 만들어줘.

49접근성 리뷰 · 이미지와 코드 함께 하기

이미지만으로는 실제 ARIA 속성이나 DOM 구조를 알 수 없습니다. 접근성 리뷰는 코드 파일과 함께 하는 것이 좋습니다.

[Image #1]과 @src/components/SignupForm.tsx를 함께 보고
시각적 문제와 코드상 접근성 문제를 분리해서 정리해줘.

50이미지와 브라우저 자동화 연결

23단원에서 MCP, 26단원에서 IDE 연동을 배웠다면, 이미지 입력은 브라우저 자동화와도 연결됩니다. 예를 들어 Playwright나 Chrome 연동으로 화면을 캡처하고, 그 스크린샷을 분석해 UI 문제를 찾는 흐름입니다.

브라우저에서 회원가입 페이지를 열고,
모바일 viewport로 스크린샷을 찍은 다음,
레이아웃 깨짐과 접근성 문제를 분석해줘.

이 방식은 수동으로 이미지를 붙여넣는 것보다 자동화에 가깝습니다. 다만 초보자 단계에서는 먼저 직접 캡처 → 붙여넣기 → 분석 요청부터 익히는 것이 좋습니다.

51이미지 입력과 Plan Mode를 함께 쓰기

이미지 기반 작업은 추정이 섞일 수 있습니다. 그래서 바로 수정하지 말고 Plan Mode를 함께 쓰는 편이 안전합니다.

[Image #1]을 기준으로 모바일 레이아웃 문제를 고치려고 해.

/plan으로 먼저 진행해줘.

조건:
- 이미지에서 확실히 보이는 문제와 추정을 분리
- 관련 파일을 먼저 찾기
- 수정 범위 최소화
- 테스트 또는 확인 방법 포함

52이미지 입력과 Plan Mode 분리 사용

또는 명령을 분리합니다.

/plan fix mobile layout issue shown in [Image #1]

Plan Mode는 파일 수정 전에 조사와 계획을 강제하기 때문에, 이미지 해석에서 생길 수 있는 과한 수정 위험을 줄입니다.

53이미지 입력 후 결과 검증하기

이미지를 보고 코드를 수정했다면 반드시 결과를 다시 확인해야 합니다.

Claude가 수정한 diff 확인
앱 실행
같은 화면 다시 캡처
수정 전/후 이미지 비교
테스트와 lint 실행

54이미지 기반 수정 후 검증 프롬프트

프롬프트 예시는 다음과 같습니다.

[Image #1]은 수정 전,
[Image #2]는 수정 후야.

두 이미지를 비교해서
문제가 해결됐는지, 새로 생긴 UI 문제가 있는지 확인해줘.

코드 검증도 함께 합니다.

git diff 기준으로 이번 UI 수정이 목표 문제 해결에 필요한 범위를 넘었는지 리뷰해줘.

55초보자용 프롬프트 모음 · 에러 화면

에러 화면

[Image #1]은 에러 화면이야.

상황:
- 어떤 행동 후 발생:
- 기대 동작:
- 실제 동작:
- 관련 파일:
- 관련 로그:

요청:
1. 에러 메시지 해석
2. 원인 후보
3. 확인할 파일
4. 수정 전 점검 순서

56초보자용 프롬프트 모음 · UI 버그

UI 버그

[Image #1]은 모바일 화면에서 깨진 UI야.

다음 기준으로 분석해줘.
- 깨진 위치
- 가능한 CSS 원인
- 관련 컴포넌트 후보
- 수정 우선순위
- 확인 방법

바로 수정하지 말고 계획만 제안해줘.

57초보자용 프롬프트 모음 · 디자인 구현

디자인 구현

[Image #1]은 목표 디자인이야.

React + TypeScript + Tailwind로 구현할 계획을 세워줘.
먼저 컴포넌트 구조, props, 상태, 접근성 고려사항을 제안해줘.
내 승인 전에는 파일을 수정하지 마.

58초보자용 프롬프트 모음 · 전후 비교

전후 비교

[Image #1]은 기존 화면,
[Image #2]는 변경 후 화면이야.

의도한 변경과 의도하지 않은 변경을 분리해서 정리해줘.

59초보자용 프롬프트 모음 · ERD 분석

ERD 분석

[Image #1]은 데이터베이스 ERD야.

엔티티, relation, cardinality, nullable 필드, 위험한 cascade 관계를 정리해줘.
그다음 Prisma schema 초안을 제안해줘.

60초보자용 프롬프트 모음 · PDF 분석

PDF 분석

이 PDF의 10~15페이지만 읽어줘.

목표:
- 구현 요구사항 추출
- API 영향
- DB 영향
- UI 영향
- 개발 전에 물어봐야 할 질문 정리

61문제 해결 체크리스트 · 1~4

이미지 붙여넣기가 안 됨

터미널이 단축키를 가로챔 → Ctrl+V, iTerm2 Cmd+V, Windows/WSL Alt+V 시도

이미지가 너무 작게 분석됨

해상도 부족 → 확대 캡처 또는 원본 파일 경로 제공

글자를 잘못 읽음

흐림, 압축, 작은 글씨 → 텍스트를 별도로 복사해 함께 제공

결과가 일반적임

질문이 모호함 → 상황·관점·출력 형식 지정

62문제 해결 체크리스트 · 5~8

비용이 많이 듦

큰 이미지·많은 이미지 → 필요한 부분만 crop, 이미지 수 줄이기

PDF가 너무 무거움

페이지·차트·표가 많음 → 페이지 범위 지정, 문서 분할

민감정보 노출 우려

캡처 범위가 넓음 → 마스킹 후 첨부

코드 수정이 과함

이미지에서 추정한 내용이 많음 → Plan Mode와 수동 승인 사용

섹션 27 · 마무리

이 단원의 핵심 정리

이미지와 멀티모달 입력은 말로 설명하기 어려운 시각적 문제를 Claude Code에 정확히 전달하는 방법입니다. 에러 화면, UI 버그, 디자인 목업, 아키텍처 다이어그램, ERD, PDF처럼 화면 자체가 중요한 작업에서 특히 유용합니다.

핵심 기준

이미지 입력 방법

드래그 앤 드롭, 붙여넣기, 파일 경로

붙여넣기 기본

Ctrl+V

iTerm2

Cmd+V도 가능

Windows/WSL

Alt+V도 가능

여러 이미지

[Image #1], [Image #2]로 의미 지정

핵심 기준 (계속)

좋은 질문

상황 + 관점 + 출력 형식

민감정보

반드시 가리고 첨부

큰 이미지/PDF

비용과 컨텍스트 주의

수정 전

Plan Mode 사용

수정 후

전후 이미지와 diff로 검증

이미지는 강력하지만, Claude가 화면만 보고 모든 코드 맥락을 알 수 있는 것은 아닙니다. 가장 좋은 사용법은 이미지 + 상황 설명 + 관련 파일 + 로그 + Plan Mode를 함께 쓰는 것입니다.

다음 단원

28단원. Claude Code와 브라우저 자동화 연결하기

28. 문제가 생겼을 때 디버깅하는 법

01이 단원의 목표

이 단원은 Claude Code를 쓰다가 문제가 생겼을 때 무작정 재설치하거나 설정을 지우기 전에, 어디서 문제가 생겼는지 단계별로 좁혀가는 방법을 다룹니다.

업로드한 통합 가이드 목차에서도 28단원은 설치 문제, 인증 문제, 권한 문제, 명령 실행 실패, MCP / hook / plugin 문제 분리하기를 핵심 주제로 잡고 있습니다.

공식 문서 기준으로 문제가 어디서 생겼는지 모르겠다면 Claude Code 안에서는 /doctor를 먼저 실행하고, Claude Code 자체가 시작되지 않는다면 터미널에서 claude doctor를 실행하는 것이 기본 진단 출발점입니다. /doctor는 설치 상태, 설정 유효성, MCP 구성, 컨텍스트 사용량을 한 번에 점검합니다.

02디버깅의 첫 원칙: "어느 층에서 막혔는지"부터 나눈다

Claude Code 문제는 대부분 다음 중 하나입니다.

설치 문제
인증 문제
네트워크 / 프록시 문제
설정 문제
권한 문제
명령 실행 문제
컨텍스트 / 성능 문제
검색 / 파일 탐색 문제
MCP 문제
Hook 문제
Plugin 문제
IDE 연동 문제

문제를 한 번에 고치려고 하지 말고, 먼저 분류해야 합니다.

03나쁜 접근 vs 좋은 접근

나쁜 접근

Claude Code가 이상해. 재설치해야 하나?

좋은 접근

claude 명령은 실행되는가?
로그인은 되는가?
특정 프로젝트에서만 문제인가?
특정 MCP나 hook을 켰을 때만 문제인가?
새 빈 설정에서도 재현되는가?

공식 troubleshooting 문서도 증상별로 설치·로그인 문제, 설정 미적용, API 오류, IDE 문제, 성능·검색 문제를 나눠서 보라고 안내합니다.

04가장 먼저 실행할 진단 명령

문제가 생겼을 때는 아래 순서로 확인합니다.

claude --version
claude doctor

Claude Code 안에 이미 들어와 있다면 다음을 실행합니다.

/status
/doctor
/context

설정·확장 기능 문제라면 다음도 봅니다.

/memory
/permissions
/hooks
/mcp
/skills
/agents
/plugin

05기본 진단 명령어 표

claude --version

Claude Code 실행 가능 여부와 버전 / 설치 후, 업데이트 후

claude doctor

설치·환경 상태 / Claude Code가 시작되지 않을 때

/doctor

현재 세션의 설치·설정·MCP·컨텍스트 진단 / 원인 불명 문제

/status

활성 설정 소스, 인증 상태, 관리 설정 여부 / 설정이 예상과 다를 때

06기본 진단 명령어 표 (계속)

/context

현재 컨텍스트 구성 / 대화가 길거나 지시가 안 먹힐 때

/permissions

현재 권한 규칙 / Tool not permitted 문제

/hooks

hook 등록 상태 / hook이 안 돌 때

/mcp

MCP 서버 연결 상태 / MCP tool이 안 보일 때

07기본 진단 명령어 표 (계속 2)

/debug [문제]

세션 debug logging과 진단 / 복합 문제 분석

claude --debug

상세 debug 출력 / plugin, hook, MCP 로딩 문제

/debug [issue]는 현재 세션에서 debug logging을 활성화하고, Claude가 로그와 설정 경로를 바탕으로 문제를 진단하도록 돕습니다.

08설치 문제 디버깅

설치 문제는 보통 다음 증상으로 나타납니다.

command not found: claude
'claude' is not recognized
설치 스크립트가 HTML을 반환함
TLS / SSL 오류
EACCES 또는 permission denied
WSL에서 npm 또는 Node 경로가 꼬임

공식 설치 문제 해결 문서는 command not found, PATH 문제, 권한 문제, 네트워크 문제, TLS 오류, Windows shell 명령 혼동, WSL 문제를 별도로 구분합니다.

09claude 명령을 찾지 못할 때

먼저 버전을 확인합니다.

claude --version

안 된다면 PATH를 확인합니다.

macOS / Linux:

echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

없으면 추가합니다.

10PATH 추가 (Zsh)

echo 'export PATH="$HOME/.local/bin:$PATH"' » ~/.zshrc
source ~/.zshrc

11PATH 추가 (Bash)

echo 'export PATH="$HOME/.local/bin:$PATH"' » ~/.bashrc
source ~/.bashrc

12PATH 확인 (Windows PowerShell)

$env:PATH -split ';' | Select-String '\.local\\bin'

공식 문서 기준으로 native installer는 macOS/Linux에서는 ~/.local/bin/claude, Windows에서는 %USERPROFILE%.localinclaude.exe에 Claude Code를 설치합니다. 설치는 되었지만 명령을 찾지 못한다면 이 경로가 PATH에 들어 있는지 확인해야 합니다.

13여러 설치가 충돌할 때

Claude Code를 npm, Homebrew, native installer, WinGet 등으로 여러 번 설치하면 버전이 꼬일 수 있습니다.

macOS / Linux:

which -a claude
ls -la ~/.local/bin/claude
ls -la ~/.claude/local/
npm -g ls @anthropic-ai/claude-code 2>/dev/null

Windows PowerShell:

where.exe claude
Test-Path "$env:USERPROFILE.localinclaude.exe"

14불필요한 설치 제거

공식 문서는 여러 Claude Code 설치가 있으면 version mismatch나 예기치 않은 동작이 생길 수 있으므로 하나만 남기라고 안내합니다. native installer 위치인 ~/.local/bin/claude 또는 Windows의 %USERPROFILE%.localinclaude.exe가 권장됩니다.

불필요한 npm global 설치 제거:

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

legacy local npm 설치 제거:

rm -rf ~/.claude/local

15네트워크·프록시·TLS 문제

설치가 다운로드 단계에서 실패하면 먼저 다운로드 서버에 접근 가능한지 확인합니다.

curl -sI https://downloads.claude.ai/claude-code-releases/latest

HTTP/2 200이 나오면 접근 가능합니다. 아무 출력이 없거나 timeout, DNS 오류가 나오면 네트워크, 프록시, 방화벽 문제일 수 있습니다. 공식 문서도 설치 프로그램이 downloads.claude.ai에서 다운로드하므로 이 URL에 접근 가능한지 확인하라고 안내합니다.

16프록시 설정 (macOS / Linux)

회사 프록시 뒤에 있다면 환경 변수를 설정합니다.

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash

17프록시 설정 (Windows PowerShell)

$env:HTTP_PROXY = 'http://proxy.example.com:8080'
$env:HTTPS_PROXY = 'http://proxy.example.com:8080'
irm https://claude.ai/install.ps1 | iex

TLS 오류가 난다면 시스템 CA 인증서, 회사 TLS inspection, NODE_EXTRA_CA_CERTS 설정을 확인합니다. 공식 설치 문서는 unable to get local issuer certificate나 SELF_SIGNED_CERT_IN_CHAIN 같은 오류가 회사 프록시의 TLS inspection에서 나올 수 있다고 설명합니다.

18WSL 설치 문제

WSL에서 npm 설치를 사용했다면 Windows npm을 잘못 잡는 경우가 많습니다.

which npm
which node

경로가 /mnt/c/...로 시작하면 Windows 쪽 Node/npm을 쓰고 있는 것입니다. WSL 안에서는 Linux 경로인 /usr/... 또는 ~/.nvm/...를 쓰는 편이 안전합니다.

업로드 문서도 WSL 경로 문제에서 which npm이 /mnt/c가 아니라 /usr로 시작해야 한다고 정리합니다.

19WSL npm platform 문제

npm 기반 설치에서 platform mismatch가 나면 다음을 쓸 수 있습니다.

npm config set os linux
npm install -g @anthropic-ai/claude-code --force

다만 공식 문서는 native installer를 사용했다면 이 WSL npm 문제 섹션은 건너뛰라고 설명합니다. npm 설치 문제는 npm 기반 설치에만 해당합니다.

20nvm 로드 설정

nvm이 로드되지 않는다면 shell 설정에 추가합니다.

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. $NVM_DIR/nvm.sh
[ -s "$NVM_DIR/bash_completion" ] && \. $NVM_DIR/bash_completion

21인증 문제 디버깅

인증 문제는 다음 증상으로 나타납니다.

Not logged in
OAuth error
Invalid code
403 Forbidden
토큰 만료
조직 비활성화 메시지
Bedrock / Vertex / Foundry credential 오류

가장 먼저 현재 인증 상태를 확인합니다.

claude auth status

또는 Claude Code 안에서:

/status

22로그인 다시 하기

로그인을 다시 합니다.

claude auth login

또는 세션 안에서:

/login

공식 문서 기준으로 로그인 문제가 명확하지 않으면 /logout으로 완전히 로그아웃하고 Claude Code를 닫은 뒤, claude를 다시 실행해 인증 절차를 새로 완료하는 것이 대부분의 경우를 해결합니다.

23인증 초기화 흐름

기본 재로그인:

/logout

그다음 Claude Code를 닫고 다시 시작합니다.

claude

터미널에서 직접 계정을 바꾸려면:

claude auth logout
claude auth login

업로드 문서도 계정 또는 조직 간 전환 시 claude auth logout && claude auth login을 사용하라고 정리합니다.

24WSL2, SSH, 컨테이너에서 OAuth가 실패할 때

WSL2, SSH, container 환경에서는 브라우저가 다른 host에서 열려 redirect가 Claude Code의 local callback server로 돌아오지 못할 수 있습니다. 이 경우 브라우저가 code를 보여주면 그 code를 터미널 prompt에 붙여넣으면 됩니다. 공식 문서도 WSL2, SSH, container에서는 browser redirect가 자동으로 돌아오지 않을 수 있으므로 code를 복사해 터미널에 붙여넣으라고 안내합니다.

브라우저가 열리지 않으면 c를 눌러 OAuth URL을 복사합니다.

25WSL2에서 Windows Chrome 열기

WSL2에서 Windows Chrome을 직접 열고 싶다면:

export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

26ANTHROPIC_API_KEY가 OAuth보다 우선하는 문제

로그인은 했는데 이상한 조직 오류가 나거나, 예전 회사 계정처럼 동작한다면 환경 변수에 오래된 API key가 남아 있을 수 있습니다.

echo $ANTHROPIC_API_KEY

구독 로그인으로 쓰고 싶다면 unset합니다.

unset ANTHROPIC_API_KEY
claude

영구 설정 파일도 확인합니다.

grep -n "ANTHROPIC_API_KEY" ~/.zshrc ~/.bashrc ~/.profile 2>/dev/null

27권한 문제 디버깅

권한 문제는 보통 다음 메시지로 나타납니다.

Tool not permitted
Permission denied
Claude가 파일을 읽지 못함
Bash 실행 승인이 계속 뜸
특정 파일 수정이 거부됨

먼저 현재 권한 상태를 봅니다.

/permissions
/status
/doctor

28권한 설정 파일 위치

공식 debug configuration 문서는 /permissions가 현재 적용 중인 allow / deny 규칙을 보여주고, /status는 활성 settings sources와 managed settings 여부를 보여준다고 설명합니다.

권한 설정 파일 위치를 확인합니다.

사용자 설정

~/.claude/settings.json

프로젝트 설정

.claude/settings.json

로컬 개인 설정

.claude/settings.local.json

공식 settings 문서 기준으로 Claude Code 설정 scope는 managed, user, project, local로 나뉘며, project 설정은 repository에 공유되고 local 설정은 현재 repository에서 사용자 개인에게만 적용됩니다.

29설정이 적용되지 않을 때

설정을 넣었는데 Claude가 무시하는 것처럼 보이면, 실제로 설정이 로드됐는지 확인합니다.

/status
/doctor

그리고 설정 파일 위치를 다시 봅니다.

자주 하는 실수:

~/.claude.json에 permissions, hooks, env를 넣음

올바른 위치:

~/.claude/settings.json
.claude/settings.json
.claude/settings.local.json

공식 debug configuration 문서는 ~/.claude.json은 app state와 UI toggle을 담는 파일이고, permissions, hooks, env는 ~/.claude/settings.json에 들어가야 한다고 설명합니다.

30명령 실행 실패 디버깅

Claude가 Bash 명령을 실행했는데 실패했다면, 먼저 "Claude 문제"인지 "프로젝트 명령 문제"인지 나눕니다.

예를 들어 npm test 실패는 Claude Code 자체 문제가 아니라 프로젝트 테스트 실패일 수 있습니다.

직접 터미널에서 실행합니다.

npm test

Claude에게는 전체 로그를 그대로 붙여넣지 말고 파일로 저장해 읽게 합니다.

npm test 2>&1 | tee test-output.log

31명령 실행 실패 처리

Claude에게는 다음처럼 요청합니다.

@test-output.log 를 읽고 실패한 테스트 이름, 핵심 에러 메시지, 원인 후보만 요약해줘.
전체 로그를 다시 출력하지 마.

명령이 멈춘 것처럼 보이면 Ctrl+C를 눌러 취소합니다. 공식 troubleshooting 문서는 Claude Code가 응답하지 않으면 Ctrl+C로 현재 operation 취소를 시도하고, 그래도 안 되면 터미널을 닫고 재시작한 뒤 같은 디렉터리에서 claude --resume으로 이어갈 수 있다고 설명합니다.

32Bash 권한과 실제 shell 문제 구분하기

Bash 명령 실패는 세 종류로 나눠야 합니다.

권한 거부

Tool not permitted / /permissions 확인

shell 환경 문제

command not found: npm / 직접 터미널에서 실행

프로젝트 오류

test/lint/build 실패 / 로그 분석

예를 들어 Claude가 npm run test를 실행하지 못한다면 먼저 확인합니다.

which npm
npm --version
npm run test

33Bash 문제 분류 요청

Claude에게는 이렇게 요청합니다.

이건 Claude Code 권한 문제인지, shell 환경 문제인지, 프로젝트 테스트 실패인지 분리해서 봐줘.
먼저 실행할 확인 명령어만 제안해줘.

34컨텍스트·성능 문제 디버깅

대화가 길어지면 다음 문제가 생길 수 있습니다.

응답이 느려짐
이전 결정을 잊음
수정 방향이 흔들림
Context length exceeded
Autocompact 관련 오류

먼저 확인합니다.

/context
/usage

35컨텍스트 문제 해결 흐름

/context로 어떤 내용이 많은지 확인
/compact로 핵심만 보존
큰 로그와 파일은 요약만 남기기
관련 없는 작업이면 /clear
큰 탐색은 subagent로 분리

공식 troubleshooting 문서는 high CPU 또는 memory 사용 시 /compact를 정기적으로 사용하고, 큰 작업 사이에 Claude Code를 재시작하며, 큰 build directory를 .gitignore에 추가하는 방법을 제시합니다.

36Autocompact 실패 처리

Auto-compaction이 계속 실패한다면 큰 파일이나 tool output이 컨텍스트를 즉시 다시 채우는 상황일 수 있습니다. 공식 문서는 이때 파일을 작은 line range나 function 단위로 읽게 하거나, /compact keep only the plan and the diff처럼 초점을 지정하거나, 큰 파일 작업을 subagent로 옮기거나, 필요하면 /clear를 사용하라고 안내합니다.

37검색·파일 탐색 문제 디버깅

Claude가 파일을 못 찾거나, @file mention이 이상하거나, custom agents / skills가 파일을 못 찾으면 ripgrep 문제일 수 있습니다.

확인할 증상:

검색 결과가 너무 적음
@파일 자동완성이 안 됨
Grep 결과가 비어 있음
custom skill이나 agent가 파일을 못 찾음

시스템 ripgrep을 설치합니다.

38ripgrep 설치

macOS:

brew install ripgrep

Ubuntu / Debian:

sudo apt install ripgrep

Windows:

winget install BurntSushi.ripgrep.MSVC

그다음 환경 변수를 설정합니다.

export USE_BUILTIN_RIPGREP=0

공식 troubleshooting 문서는 Search tool, @file mention, custom agents, custom skills가 파일을 못 찾을 때 bundled ripgrep이 시스템에서 실행되지 않을 수 있으므로 platform별 ripgrep을 설치하고 USE_BUILTIN_RIPGREP=0을 설정하라고 안내합니다.

39WSL 검색 문제

WSL에서는 프로젝트 위치도 중요합니다. /mnt/c/ 아래 Windows 파일 시스템에서 작업하면 검색이 느리거나 결과가 적을 수 있습니다. 공식 문서는 WSL에서 가능하면 프로젝트를 Linux 파일 시스템인 /home/ 아래로 옮기고, 검색 범위를 디렉터리나 파일 타입으로 좁히라고 안내합니다.

40MCP 문제 디버깅

MCP 문제는 다음 증상으로 나타납니다.

/mcp에 서버가 안 보임
서버가 failed 상태
connected인데 tools가 0개
OAuth 인증이 안 됨
project scope 서버가 승인되지 않음
MCP tool output이 너무 큼

먼저 상태를 확인합니다.

/mcp

터미널에서도 확인합니다.

claude mcp list
claude mcp get <name>

41MCP 진단 정보

공식 debug configuration 문서는 /mcp가 설정된 모든 서버, 연결 상태, 현재 프로젝트 승인 여부를 보여준다고 설명합니다. project-scoped server는 1회 승인이 필요하고, prompt를 닫았다면 /mcp에서 다시 승인해야 합니다.

42MCP가 안 보일 때 흔한 원인

.mcp.json이 있는데 안 보임

파일 위치가 잘못됨 / repository root에 .mcp.json 배치

settings.json에 mcpServers를 넣었는데 안 보임

settings.json은 project MCP config 위치가 아님 / .mcp.json 또는 claude mcp add --scope user 사용

project MCP 서버가 안 뜸

승인 prompt를 닫음 / /mcp에서 승인

43MCP가 안 보일 때 흔한 원인 (계속)

특정 디렉터리에서만 실패

상대 경로가 launch dir 기준으로 해석됨 / absolute path 사용

env가 안 들어감

settings.json env를 기대함 / .mcp.json의 per-server env 사용

connected인데 tool이 0개

서버가 tool list를 반환하지 않음 / /mcp에서 reconnect, claude --debug mcp 확인

공식 debug configuration 문서는 project MCP config는 .claude/ 안이 아니라 repository root의 .mcp.json에 있어야 하며, settings.json은 mcpServers key를 읽지 않는다고 설명합니다.

44MCP 서버가 실행되지 않을 때

로컬 stdio MCP 서버라면 직접 실행해봅니다.

npx -y some-mcp-server

또는 .mcp.json의 command와 args를 그대로 터미널에서 테스트합니다.

debug 출력으로 확인합니다.

claude --debug mcp

공식 debug configuration 문서는 서버가 connected인데 tools가 0개라면 /mcp에서 reconnect를 시도하고, 계속 0개라면 claude --debug mcp로 서버의 stderr 출력을 확인하라고 설명합니다.

45MCP 보안 고려사항

MCP 서버가 외부 content를 가져오는 경우 prompt injection 위험도 고려해야 합니다. 공식 MCP 문서는 서버를 연결하기 전에 신뢰할 수 있는 서버인지 검증하고, 외부 content를 가져오는 서버는 prompt injection risk를 만들 수 있다고 경고합니다.

46Hook 문제 디버깅

Hook 문제는 보통 다음 증상으로 나타납니다.

hook이 아예 안 보임
hook이 보이지만 실행되지 않음
matcher가 맞지 않음
exit code 때문에 차단됨
script 권한이 없음
JSON 파싱 실패

먼저 현재 hook 목록을 봅니다.

/hooks

공식 debug configuration 문서는 /hooks가 현재 세션에 등록된 모든 hook을 event별로 보여준다고 설명합니다.

47Hook이 실행되지 않을 때 체크리스트

설정 위치

좋음: .claude/settings.json의 "hooks" key / 나쁨: .claude/hooks.json 단독 파일

matcher 타입

좋음: "Edit|Write" / 나쁨: ["Edit", "Write"]

tool 이름 대소문자

좋음: "Bash" / 나쁨: "bash"

script 실행 권한

좋음: chmod +x script.sh / 나쁨: 실행 권한 없음

48Hook 체크리스트 (계속)

shebang

좋음: #!/usr/bin/env bash / 나쁨: 없음

JSON 파싱

좋음: jq -r 사용 / 나쁨: echo만으로 추정

debug 확인

좋음: claude --debug hooks / 나쁨: 추측으로 수정

공식 debug configuration 문서는 hook matcher가 배열이면 schema error가 되고, matcher는 "Edit|Write"처럼 단일 string이어야 하며, tool 이름은 Bash, Edit, Write, Read처럼 대소문자를 맞춰야 한다고 설명합니다.

49Hook debug 모드

실시간 hook 평가를 보고 싶다면 다음으로 시작합니다.

claude --debug hooks

공식 문서에 따르면 debug log에는 각 이벤트, 검사된 matcher, hook의 exit code와 output이 기록됩니다.

50Hook script 자체 테스트

Hook script가 문제인지 확인하려면 Claude Code 밖에서 직접 실행합니다.

예를 들어 protect-files.sh가 JSON stdin을 기대한다면:

echo '{"tool_input":{"file_path":".env"}}' | .claude/hooks/protect-files.sh
echo $?

exit code가 2라면 blocking hook으로 동작할 수 있습니다. 업로드 문서도 민감 파일 접근 차단 예시에서 exit code 2는 tool call을 차단하고, exit code 1은 hook failure만 의미하는 non-blocking error라고 정리합니다.

51Plugin 문제 디버깅

Plugin 문제는 다음 증상으로 나타납니다.

plugin이 설치됐는데 skill이 안 보임
plugin의 agent가 안 보임
plugin hook이 안 돈다
plugin MCP 서버가 안 뜬다
변경했는데 반영이 안 된다
특정 디렉터리에서만 plugin이 안 보인다

먼저 plugin 상태를 봅니다.

/plugin

또는 debug로 시작합니다.

claude --debug

52Plugin debug 출력

공식 plugin reference는 claude --debug가 어떤 plugin이 로드되는지, plugin manifest 오류, skill·agent·hook registration, MCP server initialization을 보여준다고 설명합니다.

53Plugin 변경이 반영되지 않을 때

Skill의 SKILL.md 변경은 현재 세션에 바로 반영될 수 있지만, plugin의 다른 구성요소는 다릅니다.

hooks/
.mcp.json
agents/
output-styles/

이런 구성요소를 바꿨다면 다음을 실행합니다.

/reload-plugins

또는 Claude Code를 재시작합니다.

공식 plugin reference에 따르면 plugin의 hooks/, .mcp.json, agents/, output-styles/ 변경은 자동 반영되지 않으며, /reload-plugins 또는 Claude Code 재시작이 필요합니다.

54project-scope skills 로드 문제

project-scope skills-directory plugin은 Claude Code를 시작한 현재 디렉터리의 .claude/skills/에서만 로드됩니다. repository root에 plugin이 있는데 subdirectory에서 Claude Code를 시작하면 놓칠 수 있으므로, repository root에서 실행하거나 /reload-plugins를 사용합니다.

55Plugin 구조가 잘못됐을 때

좋은 구조:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
├── agents/
├── hooks/
├── .mcp.json
└── scripts/

나쁜 구조:

my-plugin/
└── .claude-plugin/
    ├── plugin.json
    ├── skills/
    ├── agents/
    └── hooks/

공식 plugin reference는 plugin.json만 .claude-plugin/ 안에 있고, commands, agents, hooks 같은 components는 plugin root level에 있어야 한다고 설명합니다.

56IDE 연동 문제 디버깅

IDE 문제는 26단원에서 자세히 다뤘지만, 여기서는 빠른 체크리스트만 정리합니다.

VS Code 확장이 안 보임

확장 설치, reload window, VS Code 버전

Claude가 IDE에 연결 안 됨

IDE terminal에서 claude 실행 또는 /ide

diff가 IDE에 안 뜸

/config에서 diff tool 확인

JetBrains가 감지되지 않음

plugin 설치, IDE restart, WSL2 firewall

57IDE 문제 체크리스트 (계속)

ESC가 안 먹음

JetBrains terminal focus 설정

API key가 확장에 안 잡힘

code .로 shell env를 상속해 실행

공식 troubleshooting 문서는 VS Code extension not connecting, JetBrains plugin 또는 IDE not detected 문제는 각 surface별 troubleshooting으로 분리해 보라고 안내합니다.

58설정을 깨끗한 상태에서 테스트하기

문제가 설정 때문인지 확인하려면 "깨끗한 설정"으로 실행합니다.

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

이 세션은 일반적인 사용자·프로젝트 설정, hooks, MCP servers, plugins, memory 없이 시작됩니다. 공식 debug configuration 문서는 원인을 좁히기 어려울 때 CLAUDE_CONFIG_DIR을 빈 디렉터리로 지정하고, .claude, .mcp.json, CLAUDE.md가 없는 디렉터리에서 실행해 clean session과 비교하라고 안내합니다.

59clean session 판단 기준

판단 기준은 다음과 같습니다.

clean session에서는 정상 → 기존 ~/.claude 또는 프로젝트 .claude 설정 문제
clean session에서도 실패 → 설치, 네트워크, 인증, managed settings, 환경 변수 문제

문제가 기존 설정 때문이라면 파일을 하나씩 되돌려 넣으며 원인을 찾습니다.

60설정 재설정은 마지막 수단이다

설정을 지우는 것은 마지막 수단입니다. 먼저 백업합니다.

mkdir -p ~/claude-backup
cp -R ~/.claude ~/claude-backup/claude-dir 2>/dev/null
cp ~/.claude.json ~/claude-backup/claude.json 2>/dev/null
cp -R .claude ~/claude-backup/project-claude-dir 2>/dev/null
cp .mcp.json ~/claude-backup/project-mcp.json 2>/dev/null

61설정 선택적 초기화

사용자 설정 초기화:

rm ~/.claude.json
rm -rf ~/.claude/

프로젝트 설정 초기화:

rm -rf .claude/
rm .mcp.json

업로드 문서도 사용자 설정 재설정과 프로젝트 설정 재설정 명령을 분리해서 제시합니다. 초보자는 전체 삭제보다 clean session 테스트를 먼저 하는 편이 안전합니다.

62흔한 오류 메시지별 대응 ①

command not found: claude

PATH 또는 설치 문제 / claude --version, PATH 확인

Authentication failed

토큰 만료 또는 잘못된 인증 / claude auth status, claude auth login

Not logged in

로그인 필요 / /login 또는 claude auth login

Tool not permitted

권한 규칙에 막힘 / /permissions, settings 확인

63흔한 오류 메시지별 대응 ②

MCP server failed to start

MCP command/env/path 문제 / /mcp, claude mcp get <name>

Context length exceeded

대화·도구 출력이 너무 큼 / /context, /compact, /clear

Rate limit exceeded 또는 429

사용량 제한 또는 일시적 throttling / 기다린 뒤 재시도, /usage 확인

529 Overloaded

서버 과부하 / 자동 재시도 후 계속되면 나중에 재시도

64흔한 오류 메시지별 대응 ③

Request too large

입력이 너무 큼 / 파일·이미지·PDF 범위 축소

model not found

모델 접근 권한 또는 모델명 문제 / /model, plan/계정 확인

공식 error reference는 Claude Code runtime error message별 의미와 복구 방법을 정리하며, API 5xx, 529, 429, 인증, 네트워크, 요청 크기, 모델 접근 문제 등을 분류합니다. 또한 transient failure는 error가 표시되기 전까지 최대 10회 exponential backoff로 자동 재시도될 수 있다고 설명합니다.

65Claude가 "이상하게 답하는" 문제

항상 오류 메시지가 나오는 것은 아닙니다. 때로는 Claude가 다음처럼 보입니다.

프로젝트 규칙을 무시함
이전에 결정한 내용을 잊음
이미 알려준 파일을 다시 찾음
엉뚱한 도구를 사용함
너무 넓게 수정하려 함

이때는 먼저 컨텍스트와 memory를 확인합니다.

/context
/memory
/status

66CLAUDE.md 로드 확인

CLAUDE.md가 실제로 로드됐는지 봅니다.

/memory

공식 debug configuration 문서는 memory file이 /memory에 없으면 파일 위치를 확인해야 하고, subdirectory CLAUDE.md는 세션 시작 시가 아니라 Claude가 해당 디렉터리의 파일을 Read tool로 읽을 때 on-demand로 로드된다고 설명합니다.

또한 CLAUDE.md 지시가 너무 길거나 모호하거나 충돌하면 준수율이 떨어질 수 있습니다. 프로젝트 규칙은 짧고 구체적으로 유지하고, 반드시 막아야 하는 것은 permissions나 hooks로 강제합니다.

67문제 보고용 정보 모으기

문제를 다른 사람에게 물어보거나 이슈로 보고하려면 다음 정보를 모옵니다.

claude --version
claude doctor

Claude Code 안에서:

/status
/doctor
/context

MCP 문제:

claude mcp list
claude mcp get <name>

68문제 보고용 정보 모으기 (계속)

Hook 문제:

claude --debug hooks

Plugin 문제:

claude --debug

성능·메모리 문제라면 /heapdump를 사용할 수 있습니다. 공식 troubleshooting 문서는 memory usage가 계속 높으면 /heapdump가 JavaScript heap snapshot과 memory breakdown을 ~/Desktop 또는 Linux의 home directory에 생성하며, memory issue를 GitHub에 보고할 때 두 파일을 첨부하라고 안내합니다.

69민감정보 제거

단, 로그를 공유하기 전에는 반드시 민감정보를 제거합니다.

API key
OAuth token
세션 ID
내부 URL
고객 정보
.env 내용
DB connection string

70초보자용 문제 분리 흐름

문제가 생기면 아래 순서로 움직입니다.

claude --version
claude doctor
Claude Code가 켜지면 /status
/doctor
/context
문제 종류에 따라: 권한 → /permissions / MCP → /mcp, claude mcp get / Hook → /hooks, claude --debug hooks / Plugin → /plugin, /reload-plugins, claude --debug / 검색 → ripgrep 설치와 USE_BUILTIN_RIPGREP=0 / 성능 → /compact, /clear, /heapdump
clean session으로 재현 여부 확인
그래도 안 되면 /feedback 또는 GitHub issue

71상황별 빠른 처방전: 설치 직후 못 찾음

설치 직후 claude가 안 됨:

claude --version
echo $PATH
which -a claude

PATH 또는 중복 설치를 확인합니다.

로그인이 반복됨:

claude auth status
claude auth logout
claude auth login

환경 변수 ANTHROPIC_API_KEY가 OAuth를 덮어쓰는지 확인합니다.

72상황별 빠른 처방전: 파일 못 찾음

Claude가 파일을 못 찾음:

brew install ripgrep        # macOS
sudo apt install ripgrep    # Ubuntu/Debian
winget install BurntSushi.ripgrep.MSVC  # Windows
export USE_BUILTIN_RIPGREP=0

WSL이면 프로젝트를 /home/ 아래로 옮깁니다.

73상황별 빠른 처방전: 권한 / MCP / Hook

Tool not permitted:

/permissions
/status
/doctor

settings.json, settings.local.json, managed settings 우선순위를 확인합니다.

MCP tool이 안 보임:

/mcp

claude mcp list
claude mcp get <name>
claude --debug mcp

.mcp.json 위치와 승인 상태, 상대 경로, env 위치를 확인합니다.

74상황별 빠른 처방전: Hook / Plugin

Hook이 안 돎:

/hooks

claude --debug hooks

matcher가 string인지, tool 이름 대소문자가 맞는지, script 실행 권한이 있는지 봅니다.

Plugin 변경이 안 먹힘:

/reload-plugins

또는 재시작합니다.

claude --debug

75디버깅 요청 프롬프트: 설정 문제

설정 문제:

내 Claude Code 설정이 예상대로 동작하지 않아.
다음 순서로 진단해줘.
1. /status 결과 해석
2. /doctor 결과 해석
3. /permissions 결과 해석
4. 어떤 설정 파일이 우선 적용되는지 설명
5. 수정 전에 원인 후보만 정리

76디버깅 요청 프롬프트: MCP / Hook / 성능

MCP 문제:

MCP 서버가 /mcp에서 failed 상태야.
claude mcp get 결과와 .mcp.json을 기준으로
다음만 분석해줘.
- command 문제
- args 문제
- env 문제
- 인증 문제
- project approval 문제
- 상대 경로 문제
수정은 하지 말고 확인 순서만 제안해줘.

77디버깅 요청 프롬프트: Hook / 성능

Hook 문제:

내 PostToolUse hook이 실행되지 않아.
다음 항목을 기준으로 settings.json을 검토해줘.
- hooks key 위치
- event 이름
- matcher 형식
- tool 이름 대소문자
- script path
- 실행 권한
- exit code 의미
수정 전 원인 후보를 우선순위로 정리해줘.

78디버깅 요청 프롬프트: 성능 문제

성능 문제:

Claude Code 세션이 느려졌어.
먼저 /context 결과를 기준으로
무엇이 컨텍스트를 많이 차지하는지 분석하고,
보존해야 할 내용과 버려도 되는 내용을 분리해줘.
그다음 /compact에 넣을 문장을 제안해줘.

79디버깅할 때 하지 말아야 할 것

바로 전체 재설치

원인을 못 찾고 같은 문제 반복 / claude doctor부터

설정 파일을 모두 삭제

개인 설정·MCP·skills 손실 / 백업 후 clean session 비교

로그 전체를 붙여넣음

컨텍스트 낭비, 민감정보 노출 / 파일로 저장 후 필요한 부분만

권한 문제를 모두 allow로 해결

보안 위험 / 필요한 명령만 allow

80디버깅할 때 하지 말아야 할 것 (계속)

MCP 토큰을 .mcp.json에 직접 저장

유출 위험 / 환경 변수 또는 OAuth

hook 오류를 Claude 탓으로 봄

script path·matcher 문제일 수 있음 / /hooks, --debug hooks

plugin 수정 후 재로드 안 함

변경사항 미반영 / /reload-plugins

WSL /mnt/c에서 대형 repo 검색

느림·결과 누락 가능 / /home/ 아래로 이동

81최종 복구 루틴

문제가 복잡하면 다음 루틴을 그대로 따라갑니다.

1. 기본 확인:

claude --version
claude doctor

2. 중복 설치 확인:

which -a claude 2>/dev/null || where.exe claude

3. 인증 확인:

claude auth status

4. 깨끗한 설정으로 비교:

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

82최종 복구 루틴 (Claude Code 안)

Claude Code 안에서:

/status
/doctor
/context
/permissions
/mcp
/hooks
/plugin

문제별 debug:

claude --debug
claude --debug hooks
claude --debug mcp

그래도 해결되지 않으면 /feedback을 사용하거나 GitHub issue를 확인합니다. 이때 version, OS, shell, install method, claude doctor 결과, 관련 debug log, 재현 단계를 함께 준비합니다.

섹션 28 · 마무리

이 단원의 핵심 정리

Claude Code 문제 해결의 핵심은 재설치가 아니라 분리 진단입니다. 먼저 Claude Code가 실행되는지, 인증이 되는지, 특정 프로젝트 설정 때문인지, MCP·hook·plugin 같은 확장 기능 때문인지 나눠야 합니다.

가장 중요한 명령은 다음입니다.

claude --version / claude doctor / /status / /doctor / /context / /permissions / /mcp / /hooks / /plugin / /debug

문제별 기준을 정리하면 다음과 같습니다.

핵심 정리 (계속)

설치 문제: PATH, 중복 설치, 네트워크, 권한 확인
인증 문제: claude auth status, logout/login, ANTHROPIC_API_KEY 확인
권한 문제: /permissions, settings scope 확인
명령 실패: Claude 권한 문제인지 프로젝트 명령 문제인지 분리
성능 문제: /context, /compact, /clear
검색 문제: ripgrep과 WSL 파일 위치 확인
MCP 문제: /mcp, claude mcp get, .mcp.json 위치 확인
Hook 문제: /hooks, matcher, exit code, --debug hooks
Plugin 문제: /plugin, /reload-plugins, claude --debug
원인 불명: clean session으로 비교

핵심

디버깅을 잘한다는 것은 모든 문제를 바로 고치는 것이 아니라, 문제 범위를 빠르게 줄이는 것입니다. Claude Code가 복잡해질수록 /doctor, /status, /context, clean session 비교가 가장 강력한 기본기가 됩니다.

29. 팀에서 Claude Code를 안전하게 쓰는 법

01핵심 개념

이 단원은 개인 생산성보다 팀 운영, 보안, 비용, 리뷰 체계에 초점을 둡니다. 혼자 Claude Code를 쓸 때는 편의성이 중요하지만, 팀에서 쓸 때는 "누가 어떤 권한으로 무엇을 실행할 수 있는가", "어떤 설정을 공유하고 어떤 설정은 개인에게 맡길 것인가", "AI가 만든 변경사항을 어떻게 검토할 것인가"가 더 중요합니다.

업로드한 통합 가이드 목차에서도 29단원은 공유 설정과 개인 설정 분리, 권한 정책, 비용 관리, 리뷰와 승인 흐름, 팀용 CLAUDE.md 작성법을 다루도록 설계되어 있습니다.

02"속도"가 아니라 "일관성과 안전성"

개인이 Claude Code를 쓸 때는 다음이 중요합니다.

빠르게 파일 찾기
빠르게 수정하기
빠르게 테스트 돌리기
빠르게 리뷰 받기

팀에서는 여기에 다음이 추가됩니다.

모든 팀원이 같은 규칙을 따르는가
민감 파일을 읽거나 수정하지 못하게 막았는가
위험한 bash 명령을 제한했는가
AI가 만든 코드를 사람이 검토하는가
비용과 토큰 사용량을 확인하는가
MCP, hooks, plugins를 신뢰 가능한 것만 쓰는가

공식 보안 문서는 Claude Code 사용 시 제안된 명령을 승인 전에 검토하고, 중요한 파일 변경을 확인하며, 외부 웹 서비스나 스크립트를 다룰 때 VM 같은 격리 환경을 고려하라고 권장합니다. MCP 서버는 신뢰할 수 있는 공급자나 직접 작성한 서버를 사용하고, 권한 설정으로 MCP 접근도 제한할 수 있습니다.

03팀에서 먼저 정해야 할 5가지

Claude Code를 팀에 도입할 때는 기능부터 켜기보다 운영 원칙을 먼저 정합니다.

설정 범위

무엇을 팀 공통으로 강제하고, 무엇을 개인 설정으로 둘 것인가

권한 정책

어떤 파일과 명령은 허용, 질문, 차단할 것인가

리뷰 흐름

AI가 만든 변경사항을 누가 어떻게 검토할 것인가

비용 기준

모델, 컨텍스트, subagent, MCP 사용량을 어떻게 관리할 것인가

확장 기능

hooks, MCP, skills, plugins를 누가 검토하고 배포할 것인가

04최소한 정해야 할 5가지

초보 팀은 처음부터 엔터프라이즈급 정책을 모두 만들 필요는 없습니다. 하지만 최소한 다음은 정해야 합니다.

1. .env, credentials, secrets는 절대 읽거나 수정하지 않는다.
2. 대형 변경은 반드시 /plan으로 시작한다.
3. AI가 만든 변경은 git diff와 테스트를 거친다.
4. main branch push, production deploy는 자동 승인하지 않는다.
5. 팀 공통 규칙은 CLAUDE.md와 .claude/settings.json에 둔다.

05공유 설정과 개인 설정 분리 ①

팀 운영의 첫 번째 원칙은 공유할 것과 공유하지 않을 것을 분리하는 것입니다.

공식 설정 문서에 따르면 Claude Code의 공식 설정 파일은 계층형 settings.json 구조를 사용합니다. 사용자 설정은 ~/.claude/settings.json, 팀과 공유하는 프로젝트 설정은 .claude/settings.json, 개인 실험이나 개인 취향은 .claude/settings.local.json에 둡니다. .claude/settings.local.json은 생성 시 git ignore 처리되어 개인 설정으로 쓰기 좋습니다. 조직 차원의 managed settings는 사용자나 프로젝트 설정으로 재정의할 수 없습니다.

06공유 설정과 개인 설정 분리 ②

설정 파일의 범위와 용도는 다음과 같습니다.

~/.claude/settings.json

사용자 전체, 커밋하지 않음, 개인 기본 설정

.claude/settings.json

현재 프로젝트 팀 전체, 커밋함, 팀 공통 권한·hooks·환경 규칙

.claude/settings.local.json

현재 프로젝트 개인, 커밋하지 않음, 개인 실험·로컬 경로·취향

managed settings

조직 전체, 관리자 배포, 회사 보안 정책 강제

07초보 팀의 설정 분리 규칙

초보자 팀에서는 이렇게 나누면 됩니다.

팀원이 모두 따라야 함 → .claude/settings.json
나만 쓰는 설정 → .claude/settings.local.json
모든 프로젝트에서 나만 쓰는 설정 → ~/.claude/settings.json
보안팀이 반드시 강제해야 함 → managed settings

업로드 문서도 설정 안티패턴으로 "모든 설정을 user settings에 넣는 것"과 "개인 취향을 commit하는 것"을 지적하고, 팀 표준은 project settings에 두고 개인 설정은 settings.local.json에 두라고 정리합니다.

08팀 공통 .claude/settings.json 예시 ①

팀 공통 설정은 너무 넓게 허용하지 않는 것이 중요합니다.

다음은 .claude/settings.json 파일의 기본 구조입니다.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(npm test:*)",
      "Bash(npm run test:*)",
      "Bash(npm run lint:*)",
      "Bash(npm run build:*)",
      "Edit(src/**)",
      "Edit(tests/**)",
      "Write(src/**)",
      "Write(tests/**)"
    ],

09팀 공통 .claude/settings.json 예시 ②

    "ask": [
      "Bash(npm install:*)",
      "Bash(pnpm add:*)",
      "Bash(yarn add:*)",
      "Bash(docker:*)",
      "WebFetch"
    ],
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(secrets/**)",
      "Read(config/credentials*)",
      "Read(**/*secret*)",
      "Read(**/*token*)",
      "Edit(.env)",
      "Edit(.env.*)",
      "Edit(secrets/**)",
      "Edit(.git/**)",
      "Edit(package-lock.json)",
      "Write(.env)",
      "Write(.env.*)",
      "Write(secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Bash(chmod 777:*)",
      "Bash(git push --force:*)",
      "Bash(git push origin main:*)",
      "Bash(kubectl delete:*)",
      "Bash(terraform apply:*)"
    ]
  }
}

이 설정의 목표는 "Claude가 일상 개발에 필요한 읽기, 검색, 테스트, lint, build는 할 수 있게 하되, 민감 파일과 위험 명령은 막는 것"입니다.

10개인 설정에 넣어야 할 것

팀 공통 설정에 개인 취향을 넣으면 안 됩니다. 예를 들어 다음은 개인 설정에 가깝습니다.

내가 선호하는 output style
내가 자주 쓰는 모델
내 로컬 머신 경로
내 개인 MCP 서버
내 개인 실험 hook
내 색상·터미널 표시 설정

.claude/settings.local.json 예시:

{
  "outputStyle": "Explanatory",
  "env": {
    "DEBUG": "app:*"
  }
}

11설정 파일에 넣으면 안 되는 것

팀 공통 설정에 들어가면 안 되는 예시는 다음과 같습니다.

{
  "env": {
    "DATABASE_URL": "postgres://user:password@localhost:5432/mydb",
    "GITHUB_TOKEN": "ghp_xxx"
  }
}

민감정보는 설정 파일에 직접 넣지 않고, 각자의 shell environment, secret manager, OAuth, MCP 인증 흐름으로 분리합니다.

12Managed settings는 언제 필요한가

작은 팀은 .claude/settings.json만으로 시작할 수 있습니다. 하지만 다음 상황에서는 managed settings가 필요합니다.

개발자가 로컬 설정으로 보안 정책을 우회하면 안 되는 경우
MCP 서버 허용 목록을 중앙에서 관리해야 하는 경우
hooks를 승인된 것만 실행하게 해야 하는 경우
회사 전체에서 같은 권한 정책을 강제해야 하는 경우
SSO, compliance, audit 요구사항이 있는 경우

공식 문서에 따르면 managed settings는 Anthropic 서버, macOS MDM managed preferences, Windows registry, 또는 파일 기반 system directory로 배포할 수 있고, 사용자·프로젝트 설정이 이를 재정의할 수 없습니다.

13조직용 managed settings 예시

보안팀 또는 플랫폼팀은 다음처럼 최소 정책을 둘 수 있습니다.

/etc/claude-code/managed-settings.json

{
  "permissions": {
    "deny": [
      "Read(**/.env*)",
      "Read(**/secrets/**)",
      "Read(**/credentials/**)",
      "Read(**/*.pem)",
      "Read(**/*.key)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Bash(git push --force:*)",
      "Bash(kubectl delete:*)",
      "Bash(terraform apply:*)"
    ]
  },
  "disableBypassPermissionsMode": true,
  "allowedMcpServers": ["github", "sentry", "linear"],
  "deniedMcpServers": ["untrusted-browser", "unknown-db"]
}

이 예시는 회사 차원에서 절대 허용하지 않을 파일과 명령을 막고, MCP 서버를 허용 목록 중심으로 관리하는 구조입니다.

14권한 정책 설계: deny를 먼저

팀 권한 정책을 만들 때는 "무엇을 허용할까?"보다 "무엇을 절대 막을까?"를 먼저 정합니다.

.env, .env.*

API key, DB URL, token 포함 가능

secrets/**

인증서, key, credential 포함 가능

.git/**

repository 내부 구조 손상 위험

package-lock.json 등 lockfile

의도치 않은 dependency 변경 위험

rm -rf, sudo, chmod 777

파괴적 명령

git push --force

원격 history 손상

production deploy 명령

운영 장애 위험

cloud resource 삭제 명령

인프라 손상 위험

15권한 모드별 기준

팀에서 사용할 권한 모드별 상황은 다음과 같습니다.

신규 입사자, 초보자

default

익숙한 프로젝트에서 작은 수정

acceptEdits 가능

대형 리팩터링 계획

plan

민감 코드, 결제, 인증, 인프라

plan 또는 수동 승인

CI 자동화

제한된 headless 실행

운영 배포, DB migration

자동 승인 금지

팀에서는 다음 규칙을 기본으로 삼으면 좋습니다.

대형 변경 → plan
민감 영역 → plan
파일 수정 → 승인 후 실행
Bash 실행 → 명령 확인 후 승인
운영 영향 → Claude 단독 실행 금지

16위험한 Bash 명령 정책

팀에서는 Bash 허용 규칙을 넓게 쓰면 안 됩니다.

나쁜 예시:

{
  "permissions": {
    "allow": ["Bash(*)"]
  }
}

좋은 예시:

{
  "permissions": {
    "allow": [
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Bash(npm run build:*)"
    ],
    "ask": ["Bash(npm install:*)", "Bash(docker:*)"],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Bash(git push --force:*)",
      "Bash(kubectl delete:*)",
      "Bash(terraform apply:*)"
    ]
  }
}

17Hooks로 팀 품질 게이트 만들기

팀에서는 "Claude에게 매번 포맷팅해달라고 말하는 것"보다 hooks로 자동화하는 편이 안정적입니다.

예를 들어 파일 수정 후 prettier를 실행합니다.

.claude/hooks/format-edited-file.sh

#!/usr/bin/env bash
set -euo pipefail

input="$(cat)"
file_path="$(echo "$input" | jq -r '.tool_input.file_path // empty')"

case "$file_path" in
  *.js|*.jsx|*.ts|*.tsx|*.json|*.md|*.css)
    npx prettier --write "$file_path"
    ;;
esac

18Settings.json에서 hooks 설정하기

.claude/settings.json에 hooks를 등록합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format-edited-file.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

공식 hooks 문서는 hooks 위치별 scope를 정리하며, .claude/settings.json에 있는 hooks는 단일 프로젝트에 적용되고 repo에 커밋해 공유할 수 있다고 설명합니다.

19ConfigChange hook으로 설정 변경 감시하기

팀에서 특히 중요한 것은 세션 중 설정이 바뀌는 상황입니다. 공식 보안 문서는 팀 보안 모범 사례로 managed settings 사용, 승인된 권한 구성을 version control로 공유, 팀원 교육, OpenTelemetry metrics를 통한 사용 모니터링, ConfigChange hooks로 세션 중 설정 변경을 감사하거나 차단하는 방식을 제시합니다.

초보자용 정책은 다음과 같습니다.

팀 공통 설정 변경 → PR로 검토
개인 설정 변경 → settings.local.json
권한 완화 변경 → 보안 담당자 리뷰
MCP 서버 추가 → 팀 리뷰
hook 추가 → script 내용 리뷰
plugin 추가 → 구성요소 확인 후 설치

20MCP는 "허용 목록"으로 운영

MCP는 강력하지만 외부 시스템과 연결되기 때문에 팀 운영에서는 가장 조심해야 합니다.

팀에서 MCP를 추가할 때는 다음을 문서화합니다.

서버 이름

어떤 MCP 서버인가

공급자

공식, 사내, 검증된 커뮤니티인가

권한

읽기 전용인가, 쓰기 가능인가

데이터 범위

어떤 repo, issue, DB, 로그에 접근하는가

인증 방식

OAuth, token, env, secret manager 중 무엇인가

저장 위치

local, project, user, managed 중 어디인가

제거 방법

문제가 생기면 어떻게 끄는가

21팀용 .mcp.json 예시

팀이 GitHub와 Sentry만 공통으로 쓰게 하고 싶다면 project scope로 관리할 수 있습니다.

.mcp.json

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

여기서 실제 토큰은 .mcp.json에 넣지 않고 환경 변수로 분리합니다. 팀 저장소에는 구조만 공유하고, 개인 토큰이나 운영 credential은 절대 커밋하지 않습니다.

22Skills와 project 지식 공유

팀에서 반복되는 도메인 규칙은 CLAUDE.md에 모두 넣기보다 skills로 분리합니다.

예를 들어 API 구현 규칙은 skill로 만듭니다.

.claude/
└── skills/
    └── api-conventions/
        └── SKILL.md

업로드 문서도 project skills는 git에 커밋되어 팀원이 pull하면 별도 설치 없이 자동으로 받으며, 팀 전체의 전문 지식을 표준화할 수 있다고 설명합니다.

23CLAUDE.md와 Skills의 역할 분리

CLAUDE.md는 짧은 기본 규칙, skill은 특정 작업 절차로 나누는 것이 좋습니다.

항상 필요한 짧은 규칙

CLAUDE.md

API 구현 절차

skill

보안 리뷰 체크리스트

skill

배포 절차

직접 호출 전용 skill

반복 리뷰 작업

subagent

팀 배포 패키지

plugin

24팀용 CLAUDE.md 작성법

팀용 CLAUDE.md는 길수록 좋은 문서가 아닙니다. 세션마다 읽히는 기본 규칙이므로 짧고 명확해야 합니다.

좋은 CLAUDE.md의 구조는 다음과 같습니다.

# Project Guide for Claude Code

## Project overview
This repository contains the web application and API for the product.

## Commands
- Install: `npm install`
- Test: `npm test`
- Lint: `npm run lint`
- Build: `npm run build`

## Coding rules
- Use TypeScript strict mode.
- Keep business logic in `src/services`.
- Keep route handlers thin.
- Add tests for behavior changes.
- Do not introduce new dependencies without approval.

## Security rules
- Never read or edit .env, credentials, secrets, private keys.
- Do not print tokens, API keys, customer data.
- Ask before changing auth, billing, permissions, migrations, deployment.

## Workflow rules
- For large changes, use /plan before editing.
- After editing, run relevant tests and lint.
- Before final answer, summarize changed files and risks.

25CLAUDE.md에 넣지 말아야 할 것

CLAUDE.md에는 다음을 넣지 않습니다.

API key, token, password

민감정보 노출

너무 긴 architecture 문서

컨텍스트 낭비

모든 스타일 규칙 세부사항

skill이나 문서 링크로 분리

개인 취향

팀원에게 강제됨

불확실한 규칙

Claude가 잘못 적용할 수 있음

실행하면 안 되는 배포 명령

자동화 오해 가능

업로드 문서도 모든 정보를 CLAUDE.md에 넣으면 세션마다 context를 낭비하므로 500줄 미만으로 유지하라고 정리합니다.

26리뷰와 승인 흐름 만들기

팀에서 AI가 만든 코드는 사람이 만든 코드와 같은 수준으로 리뷰해야 합니다. 기본 흐름은 다음과 같습니다.

1. 요구사항 정리
2. /plan으로 수정 계획 작성
3. 사람이 계획 승인
4. Claude가 최소 범위로 수정
5. 테스트·lint·build 실행
6. /diff 또는 git diff 검토
7. /code-review 또는 security-review 실행
8. 사람이 PR 리뷰
9. CI 통과 후 merge

대형 변경은 "설명 → 계획 → 승인 → 실행 → 확인" 흐름을 유지해야 합니다.

27팀 PR 규칙 예시

팀 PR template에 Claude Code 사용 여부와 검증 항목을 넣습니다.

.github/pull_request_template.md

## Summary
Describe what changed.

## Claude Code usage
- [ ] Claude Code was not used
- [ ] Claude Code was used for exploration only
- [ ] Claude Code suggested code changes
- [ ] Claude Code generated or edited code

## Verification
- [ ] I reviewed the full diff manually
- [ ] I ran tests
- [ ] I ran lint
- [ ] I ran build, if relevant
- [ ] I checked for secrets or credentials
- [ ] I checked security-sensitive changes

## Risk areas
- Auth / permissions:
- Billing / payments:
- Database / migrations:
- Deployment / infrastructure:
- Customer data:

Claude가 만든 코드라고 해서 자동으로 거부할 필요는 없습니다. 하지만 "AI가 만든 변경사항을 사람이 확인했다"는 절차는 명확해야 합니다.

28보안 민감 변경의 별도 승인

다음 영역은 항상 추가 검토를 요구합니다.

인증

계정 탈취, 세션 처리 문제

권한

privilege escalation 위험

결제

금전 손실, 규정 문제

개인정보

데이터 유출 위험

DB migration

데이터 손실 가능

인프라

서비스 장애 가능

배포 스크립트

운영 영향

암호화·토큰

보안 경계 손상

29보안 민감 변경 프롬프트 예시

프롬프트도 명확히 쓰는 것이 중요합니다.

이 변경은 인증 관련 코드야.

조건:
- 바로 수정하지 말고 /plan으로 시작
- 보안 위험을 별도 섹션으로 정리
- 권한 체크 누락 가능성 확인
- 테스트 계획 포함
- 내가 승인하기 전에는 파일 수정 금지

30비용 관리 원칙

팀에서 Claude Code 비용은 "한 사람이 얼마나 많이 쓰는가"보다 "어떤 작업 방식이 비용을 키우는가"를 봐야 합니다.

공식 비용 문서는 Claude Code 비용이 API token consumption에 기반하며, 팀 비용 관리를 위해 /usage, context 관리, 모델 선택, extended thinking 조절, MCP overhead 감소 등을 권장합니다.

팀 비용을 키우는 대표 패턴은 다음입니다.

긴 세션을 계속 이어감

컨텍스트 비용 증가

로그 전체를 붙여넣음

불필요한 토큰 증가

PDF나 대형 문서를 통째로 읽힘

컨텍스트 폭증

모든 작업에 최고 모델 사용

비용 증가

subagent/agent team을 남발

병렬 토큰 비용 증가

MCP 서버 도구를 너무 많이 로드

도구 설명 컨텍스트 차지

CLAUDE.md가 너무 김

매 세션 기본 비용 증가

31팀 비용 모니터링 방법

개발자 개인은 세션에서 다음을 확인합니다.

/usage
/context

팀 관리자는 analytics와 monitoring을 사용합니다. 공식 analytics 문서에 따르면 Claude for Teams와 Enterprise는 usage metrics, contribution metrics, leaderboard, CSV export를 제공합니다.

공식 monitoring 문서는 claude_code.cost.usage metric으로 팀 또는 개인의 usage trend, high-usage session, skill·plugin·agent type별 비용 attribution을 볼 수 있다고 설명합니다.

32비용을 줄이는 팀 규칙

1. 새 작업은 /clear로 시작한다.
2. 긴 세션은 /compact를 사용한다.
3. 로그는 파일로 저장하고 요약만 요청한다.
4. 대형 문서는 필요한 범위만 읽게 한다.
5. 반복 규칙은 CLAUDE.md가 아니라 skill로 분리한다.
6. 테스트 로그 분석은 subagent에 맡긴다.
7. MCP 서버는 필요한 것만 연결한다.
8. 고난도 설계에만 높은 effort와 상위 모델을 쓴다.

업로드 문서도 긴 세션에서는 /compact를 적극적으로 사용하고, subagents와 간단한 작업에는 저렴한 모델을 쓰라고 정리합니다.

33팀 인증과 계정 운영

팀에서 Claude Code를 쓰는 방법은 크게 네 가지입니다.

Claude for Teams

작은 팀, 중앙 결제와 팀 관리 필요

Claude for Enterprise

SSO, domain capture, role-based permissions, managed policy 필요

Claude Console

API 기반 billing을 선호하는 팀

Bedrock / Vertex AI / Foundry

기존 클라우드 거버넌스를 쓰는 조직

공식 IAM 문서는 팀과 조직의 Claude Code access 방법을 제시합니다. Teams는 self-service plan으로 collaboration, admin tools, billing management에 적합하고, Enterprise는 SSO, domain capture, role-based permissions을 제공합니다.

34데이터 사용과 보안 설명 공유하기

팀원이 가장 많이 묻는 질문은 "우리 코드가 학습에 쓰이는가?"입니다.

공식 data usage 문서에 따르면 Free, Pro, Max 같은 consumer plan은 사용자가 모델 개선용 데이터 사용을 허용할 수 있지만, Team, Enterprise, API, 3rd-party platform 같은 commercial 사용자는 고객이 별도로 model improvement에 제공하기로 선택하지 않는 한 Claude Code로 보낸 코드나 프롬프트가 generative model training에 사용되지 않습니다.

팀 교육 문서에는 다음처럼 쓰면 됩니다.

- 회사 코드는 승인된 계정과 조직 정책 안에서만 사용한다.
- 개인 계정으로 회사 저장소를 분석하지 않는다.
- /feedback 사용 전 transcript에 민감정보가 없는지 확인한다.
- 민감 파일은 permissions.deny로 읽기와 수정을 막는다.
- 외부 MCP 서버는 승인된 목록만 사용한다.

35팀원 온보딩 체크리스트

새 팀원이 Claude Code를 쓰기 전에는 다음을 확인합니다.

1. 승인된 인증 방식으로 로그인
2. claude --version 확인
3. claude doctor 확인
4. repository root에서 claude 실행
5. /status로 settings source 확인
6. /permissions로 권한 정책 확인
7. /mcp로 연결된 MCP 서버 확인
8. /usage로 사용량 화면 이해
9. CLAUDE.md 읽기
10. 작은 read-only 작업으로 첫 실습

36온보딩 첫 실습

첫 실습은 수정 작업이 아니라 읽기 전용으로 시작합니다.

이 프로젝트 구조를 읽고,
주요 디렉터리와 테스트 명령어를 요약해줘.
파일은 수정하지 마.

그다음 작은 수정으로 넘어갑니다.

/plan add a small validation test for the login form

37팀 표준 워크플로우 예시

일상 개발 흐름은 다음처럼 고정합니다.

1. claude -c 또는 새 세션 시작
2. /status
3. /context
4. 작업 설명
5. 큰 작업이면 /plan
6. 승인 후 수정
7. 테스트·lint·build
8. /diff
9. /code-review
10. PR 생성

프롬프트 예시는 다음과 같습니다.

로그인 폼 validation을 추가하려고 해.
팀 규칙:
- 수정 전 /plan
- 새 dependency 추가 금지
- 기존 응답 형식 유지
- 관련 테스트 추가
- 수정 후 npm test와 npm run lint 실행
- 마지막에 변경 파일과 위험 요소 요약

38팀에서 auto-accept를 어떻게 다룰 것인가

acceptEdits나 auto-accept는 편하지만, 팀에서는 기준을 정해야 합니다.

문서 오탈자 수정

가능

테스트 파일 소규모 추가

가능

src 코드 수정

상황에 따라

인증·결제·권한 코드

비권장

DB migration

비권장

배포·인프라 코드

금지

lockfile 변경

수동 검토

secrets, env, credentials

금지

39AI 생성 코드 표시 정책

팀마다 AI 사용 표시 정책은 다를 수 있습니다. 최소한 내부적으로는 다음을 남기는 것이 좋습니다.

PR description에 Claude Code 사용 여부
어떤 작업에 사용했는지
사람이 검토한 항목
테스트 결과
보안 민감 영역 여부

커밋 메시지에 AI 사용 표시를 강제할지 여부는 팀 정책에 맞춘다. 중요한 것은 "표시 자체"보다 "검토 책임"입니다.

AI가 제안했더라도 merge 책임은 사람에게 있습니다.

40팀용 리뷰 프롬프트 표준화 ①

팀에서 자주 쓰는 리뷰 프롬프트는 skill이나 command로 표준화합니다.

예시:

현재 diff를 팀 기준으로 리뷰해줘.

중점:
1. 실제 버그 가능성
2. 보안 문제
3. 테스트 누락
4. 과한 변경
5. 유지보수성

제외:
- 개인 취향
- 단순 스타일 논쟁
- 이미 lint가 처리할 문제

출력:
- Critical
- Warning
- Suggestion
- Tests to add

41팀용 리뷰 프롬프트 표준화 ②

이 프롬프트는 .claude/skills/review-checklist/SKILL.md로 분리할 수 있습니다.

---
description: Team code review checklist. Use when reviewing diffs, PRs, or completed code changes.
---

Review changes for correctness, security, tests, and maintainability.

Do not focus on style issues handled by lint.

Return findings in this format:
- Critical
- Warning
- Suggestion
- Tests to add

42보안 리뷰 프롬프트 표준화

보안 민감 변경에는 별도 리뷰 프롬프트를 둡니다.

이 diff를 보안 관점으로 리뷰해줘.

중점:
- 인증 우회
- 권한 체크 누락
- 사용자 입력 검증 누락
- SQL injection 가능성
- IDOR 가능성
- 민감정보 로그 출력
- token/session 처리 문제
- 파일 업로드 위험
- 결제/권한 경계 손상

결과는 심각도, 파일 경로, 근거, 수정 제안으로 정리해줘.
파일은 수정하지 마.

팀에서는 이걸 security-reviewer subagent나 skill로 만들어 재사용합니다.

43팀에서 hooks를 배포할 때의 검토 기준

Hook은 shell command를 실행할 수 있으므로 코드 리뷰 대상입니다.

Hook PR checklist:

- 어떤 이벤트에서 실행되는가
- matcher가 너무 넓지 않은가
- command가 안전한가
- 민감정보를 stdout/stderr로 출력하지 않는가
- 파일 경로를 따옴표로 감쌌는가
- exit code 2를 의도적으로 쓰는가
- 로컬 환경 의존성이 너무 강하지 않은가
- 실패 시 개발 흐름을 과하게 막지 않는가

공식 hooks 문서는 matcher가 Edit|Write처럼 exact string 목록이나 regex로 동작할 수 있고, 팀 hook은 matcher를 넓게 잡기보다 필요한 도구와 이벤트에만 붙이는 편이 안전하다고 설명합니다.

44팀에서 plugins를 설치할 때의 검토 기준

Plugin은 skills, agents, hooks, MCP를 함께 포함할 수 있으므로 설치 전 구성요소를 확인해야 합니다.

검토 항목:

1. 어떤 skills를 추가하는가
2. 어떤 agents를 추가하는가
3. 어떤 hooks를 실행하는가
4. 어떤 MCP 서버를 연결하는가
5. 외부 network 접근이 있는가
6. shell command를 실행하는가
7. credential을 요구하는가
8. 팀 policy와 충돌하지 않는가

팀에서는 plugin marketplace를 자유롭게 열기보다 승인된 marketplace 또는 internal marketplace 중심으로 운영하는 것이 좋습니다.

45Subagents와 agent team 비용·권한 기준

Subagents는 컨텍스트를 분리하고 탐색을 위임하는 데 좋지만, 팀에서 남발하면 비용과 검토 복잡도가 늘어납니다.

업로드 문서는 subagents는 결과만 보고받는 집중 작업에 적합하고, agent teams는 여러 teammate가 직접 메시지를 주고받고 공유 작업 목록으로 조율하므로 비용이 더 높다고 정리합니다.

팀 규칙 예시:

- 로그 분석, 보안 리뷰, 테스트 실패 요약은 subagent 사용 가능
- 3개 이상 subagent 병렬 실행은 이유를 명시
- agent team은 대형 리팩터링이나 PR 리뷰처럼 명확한 목적이 있을 때만 사용
- 수정 권한이 있는 subagent는 최소 권한으로 제한
- 보안 리뷰 subagent는 기본적으로 read-only

46저장소별 위험도에 따른 정책

모든 repository에 같은 정책을 적용할 필요는 없습니다. 위험도에 따라 다르게 둡니다.

문서 저장소

비교적 자유롭게 사용

프론트엔드 앱

일반 코드 수정 허용, 배포 설정 수동 검토

백엔드 API

권한·DB·인증 변경 수동 검토

결제 시스템

Plan Mode와 보안 리뷰 필수

인프라 저장소

자동 승인 금지

데이터 파이프라인

데이터 접근과 로그 출력 제한

실험용 repo

sandbox 또는 낮은 권한 정책

production hotfix repo

변경 범위와 승인 매우 엄격하게

47팀 정책 문서 예시 ①

docs/claude-code-policy.md

# Claude Code Team Policy

## Allowed use
Claude Code may be used for:
- code exploration
- implementation planning
- test generation
- refactoring suggestions
- documentation updates
- code review assistance

## Restricted use
Do not use Claude Code to:
- read or modify secrets
- execute production deployment
- run destructive infrastructure commands
- change database migrations without review
- push directly to main
- bypass code review

48팀 정책 문서 예시 ②

## Required workflow
For non-trivial changes:
1. Start with /plan.
2. Review the plan.
3. Apply minimal changes.
4. Run tests and lint.
5. Review git diff.
6. Create a PR.
7. Get human approval before merge.

## Sensitive areas
Extra review is required for:
- authentication
- authorization
- billing
- customer data
- migrations
- infrastructure
- deployment

이 문서를 CLAUDE.md에서 참조합니다.

## Team policy
Follow `docs/claude-code-policy.md`.

49팀 운영을 위한 최소 파일 구성

초보 팀은 아래 구성만으로도 충분히 안전하게 시작할 수 있습니다.

repo/
├── CLAUDE.md
├── docs/
│   └── claude-code-policy.md
├── .claude/
│   ├── settings.json
│   ├── skills/
│   │   ├── review-checklist/
│   │   │   └── SKILL.md
│   │   └── api-conventions/
│   │       └── SKILL.md
│   └── hooks/
│       ├── format-edited-file.sh
│       └── protect-files.sh
├── .mcp.json
└── .github/
    └── pull_request_template.md

구성별 역할은 다음과 같습니다.

CLAUDE.md

짧은 프로젝트 기본 규칙

docs/claude-code-policy.md

팀 운영 정책

.claude/settings.json

팀 공통 권한·hooks

.claude/skills/

팀 반복 지식

.claude/hooks/

자동 포맷팅·보안 차단

.mcp.json

팀 공통 MCP 구조

PR template

AI 변경 검토 절차

50팀 도입 순서

처음부터 모든 기능을 켜지 않습니다.

1단계: CLAUDE.md 작성
2단계: .claude/settings.json으로 민감 파일 deny
3단계: 팀 PR template에 Claude Code 사용 항목 추가
4단계: /plan, /diff, /usage, /permissions 교육
5단계: 작은 팀 5~10명 파일럿
6단계: 비용과 리뷰 품질 확인
7단계: hooks로 formatter와 보호 규칙 추가
8단계: GitHub/Sentry 같은 읽기 중심 MCP 추가
9단계: skills와 subagents 표준화
10단계: 필요하면 managed settings와 plugin 배포

업로드 문서도 엔터프라이즈 아키텍트용 가이드에서 전체 배포 전에 5~10명의 개발자로 파일럿을 시작하라고 권장합니다.

51팀원 교육용 핵심 명령어

/status

현재 계정, 모델, 설정 source 확인

/permissions

어떤 도구와 명령이 허용되는지 확인

/usage

비용과 사용량 확인

/context

컨텍스트가 과하게 쌓였는지 확인

/compact

긴 세션 정리

/clear

새 작업 시작

/plan

수정 전 계획

/diff

변경사항 확인

/code-review

변경사항 리뷰

/mcp

외부 도구 연결 상태 확인

/hooks

자동화 hook 확인

/doctor

문제 진단

팀원에게 모든 고급 기능을 가르치기보다 이 명령어부터 익히게 합니다.

52팀에서 금지할 프롬프트 예시

다음 요청은 팀 정책상 막거나, 최소한 수동 검토가 필요합니다.

금지된 프롬프트:

권한 프롬프트 없이 알아서 전부 수정해줘.
테스트 실패하면 알아서 다 고치고 push까지 해줘.
.env 파일 읽고 DB 접속해서 원인 찾아줘.
production에 바로 deploy해줘.
terraform apply 실행해줘.

대신 다음처럼 바꿉니다.

수정 전에 계획만 세워줘.
민감 파일은 읽지 마.
관련 테스트와 검증 방법을 먼저 제안해줘.
내 승인 전에는 파일을 수정하지 마.

53팀에서 권장할 프롬프트 예시 ①

기능 추가

새 기능을 추가하려고 해.

먼저 /plan으로 진행해줘.
조건:
- 관련 파일만 조사
- 수정 범위 최소화
- 새 dependency 추가 금지
- 테스트 계획 포함
- 보안 영향 별도 정리
- 내가 승인하기 전에는 수정하지 말 것

54팀에서 권장할 프롬프트 예시 ②

버그 수정

이 버그를 고치기 전에 원인 후보를 조사해줘.

조건:
- 파일 수정 금지
- 관련 파일과 근거만 정리
- 가장 가능성 높은 원인 1~3개 제시
- 확인할 테스트 명령 제안

리뷰

현재 diff를 팀 기준으로 리뷰해줘.

중점:
- 실제 버그
- 보안 위험
- 테스트 누락
- 과한 변경
- 유지보수성

스타일 취향은 제외해줘.

55사고가 났을 때 대응 절차

Claude Code로 인해 잘못된 변경이 들어갔거나 민감정보 노출이 의심되면 즉시 다음을 합니다.

1. 해당 세션 중지
2. git status / git diff 확인
3. 민감정보가 출력·커밋·로그에 남았는지 확인
4. 관련 token 즉시 rotate
5. 잘못된 commit revert
6. PR 또는 branch 접근 제한
7. /feedback 사용 전 transcript 민감정보 확인
8. settings, hooks, permissions 재검토
9. 재발 방지 정책 추가

보안 사고 대응에서 중요한 것은 "Claude가 왜 그랬는가"보다 "어떤 권한과 설정이 허용했는가"입니다.

56팀 성숙도별 운영 모델

1단계

개인 사용, 기본 권한, 수동 리뷰

2단계

팀 CLAUDE.md, project settings, PR template

3단계

hooks, skills, MCP 허용 목록

4단계

managed settings, analytics, OTel monitoring

5단계

internal plugins, approved MCP catalog, enterprise rollout

초보 팀은 2단계까지만 제대로 해도 충분합니다.

CLAUDE.md
.claude/settings.json
PR template
/plan과 /diff 습관

이 네 가지가 가장 먼저입니다.

57팀 운영 체크리스트 · 도입 전

도입 전에 확인할 사항:

- 인증 방식 결정
- 팀 CLAUDE.md 작성
- 민감 파일 deny 설정
- 위험 Bash 명령 deny 설정
- PR template 업데이트
- /plan, /diff, /usage 교육

파일럿 중에 확인할 사항:

- 비용 추적
- 자주 발생하는 권한 요청 확인
- Claude가 자주 헷갈리는 프로젝트 규칙 수집
- CLAUDE.md 과도한 내용 제거
- 반복 프롬프트를 skills로 분리

58팀 운영 체크리스트 · 확대 전 및 운영 중

확대 전에 확인할 사항:

- MCP 허용 목록 정리
- hooks script 리뷰
- plugin 설치 기준 정리
- managed settings 필요 여부 판단
- analytics 또는 OTel monitoring 설정

운영 중에 정기적으로 확인할 사항:

- /permissions 정기 점검
- MCP 서버 정기 점검
- 비용 spike 확인
- 보안 민감 PR 샘플 리뷰
- 팀 정책 문서 업데이트

섹션 29 · 마무리

팀에서 Claude Code를 안전하게 쓰는 법

팀에서 Claude Code를 안전하게 쓰려면 개인 생산성 도구가 아니라 팀 개발 인프라로 다뤄야 합니다. 핵심은 공유 설정과 개인 설정을 분리하고, 민감 파일과 위험 명령을 차단하며, AI가 만든 변경사항을 사람이 검토하는 흐름을 만드는 것입니다.

가장 중요한 기준은 다음입니다.

팀 공통 규칙 → CLAUDE.md, .claude/settings.json / 개인 취향 → .claude/settings.local.json / 조직 강제 정책 → managed settings

초보 팀이 처음 시작할 때 필요한 최소 세트는 다음입니다.

1. 짧은 CLAUDE.md
2. 안전한 .claude/settings.json
3. PR template
4. /plan → 수정 → 테스트 → /diff → 리뷰 흐름
5. 민감 파일과 위험 명령 deny

핵심

이 다섯 가지만 지켜도 Claude Code를 팀에서 훨씬 안전하고 일관되게 사용할 수 있습니다.

30. 고급 기능 로드맵과 빠른 참조

01이제부터는 "모두 배우기"가 아니라 "필요할 때 꺼내 쓰기"다

초보자가 Claude Code를 잘 쓰기 위해 반드시 알아야 하는 핵심은 이미 앞 단원에서 다뤘습니다. 아래는 지금까지 배운 핵심 영역입니다.

기본 실행 · 파일 읽기 · Plan Mode
수정과 명령 실행 · CLAUDE.md · settings.json
permissions · Git diff · 모델·비용·컨텍스트
테스트·lint·build · slash command · hooks
MCP · subagents · skills/plugins
IDE · 디버깅 · 팀 운영

30단원에서 다루는 기능들은 대부분 "고급 진입" 영역입니다. 당장 전부 쓸 필요는 없습니다. 대신 아래 기준으로 이해하면 됩니다.

02필요할 때 꺼내 보는 기준표

30단원의 고급 기능들은 다음 기준으로 "필요할 때" 찾아보면 됩니다.

오래 걸리는 작업을 터미널 밖으로 보내고 싶다

Background agents

여러 Claude Code 세션을 한 화면에서 관리하고 싶다

Agent View

웹이나 모바일에서 코딩 작업을 맡기고 싶다

Claude Code on the web

수십~수백 개 agent가 필요한 대규모 작업을 돌리고 싶다

Dynamic workflows

회사 전체 정책과 보안을 강제하고 싶다

Enterprise deployment

최신 기능 변화가 궁금하다

/release-notes, changelog

매일 쓰는 명령만 빠르게 보고 싶다

Quick reference

03고급 기능 로드맵

초보자에서 고급 사용자로 넘어갈 때는 다음 순서가 자연스럽습니다.

1단계: CLI 기본 사용
2단계: Plan Mode + Git diff + 테스트
3단계: CLAUDE.md + permissions
4단계: /usage + /context + /compact
5단계: hooks + MCP
6단계: subagents + skills
7단계: IDE + 팀 운영
8단계: background agents + Agent View
9단계: Claude Code on the web
10단계: dynamic workflows
11단계: enterprise managed settings + monitoring

처음부터 8~11단계로 가지 않아도 됩니다. 실제 생산성은 대부분 1~7단계에서 이미 크게 올라갑니다. 8단계 이후는 "작업 규모가 커졌을 때" 쓰는 확장 기능입니다.

04Background Agents: 오래 걸리는 작업을 뒤로 보내기

Background agent는 Claude Code 세션을 터미널에 묶어두지 않고 계속 실행하게 하는 기능입니다. /background [prompt] 또는 /bg는 현재 세션을 background agent로 detach해서 터미널을 비우고, 이후 claude agents로 모니터링할 수 있습니다. /exit은 background session에 attach된 상태에서는 세션을 종료하지 않고 detach하며, /stop은 attach된 background session을 멈춥니다.

기본 사용 예시:

/background 전체 테스트 실패 원인을 조사하고 요약해줘.

또는 터미널에서 바로 시작:

claude --bg "investigate the flaky test and summarize likely causes"

--bg는 세션을 background agent로 시작하고 즉시 session ID와 관리 명령을 출력합니다. --exec와 함께 쓰면 Claude 세션이 아니라 shell command를 background job으로 실행할 수 있습니다.

claude --bg --exec 'pytest -x'

05Background bash와 background agent를 구분하기

비슷해 보이지만 두 기능은 다릅니다.

Background bash

긴 shell command를 뒤에서 실행 — npm test, pytest, docker build

Background agent

Claude Code 세션 전체를 뒤에서 실행 — 버그 조사, PR 리뷰, 문서 생성

Claude Code는 bash command를 background로 실행할 수 있고, 이 경우 즉시 background task ID를 반환합니다. Ctrl+B를 누르면 실행 중인 Bash tool invocation을 background로 보낼 수 있으며, tmux 사용자는 prefix 키 때문에 Ctrl+B를 두 번 눌러야 할 수 있습니다.

긴 테스트 명령만 뒤로 → background bash
Claude에게 긴 조사 작업을 맡김 → background agent
여러 작업을 동시에 관리 → Agent View

06Agent View: 여러 background session을 한 화면에서 관리하기

Agent View는 여러 Claude Code background session을 한 화면에서 보는 운영 화면입니다. claude agents를 실행하면 Agent View가 열리고, 각 session이 실행 중인지, 사용자 입력을 기다리는지, 완료됐는지 확인할 수 있습니다. 각 background session은 터미널에 붙어 있지 않아도 계속 실행되는 하나의 Claude Code 대화입니다.

claude agents

새 작업 dispatch

입력창에 prompt를 넣어 새 background session 시작

상태 확인

Working, Needs input, Completed 등 확인

peek

세션 전체에 들어가지 않고 최근 출력만 확인

Agent View 안에서 필요한 답변만 전달

attach

특정 세션 전체 대화로 들어가기

detach

다시 Agent View로 돌아오기

shell job 실행

! <command>로 background shell job 실행

prompt를 입력하면 새 background session이 하나 생기며, 또 다른 prompt를 입력하면 기존 세션에 후속 질문을 보내는 것이 아니라 새 session을 병렬로 시작합니다. 따라서 여러 작업을 동시에 보낼 수 있지만, 각 session은 quota를 독립적으로 사용합니다.

07Agent View를 언제 쓰나

Agent View는 다음 상황에 적합합니다.

버그 3개를 각각 따로 조사시키고 싶다.
PR 리뷰, 테스트 실패 분석, 문서 업데이트를 동시에 맡기고 싶다.
긴 작업을 던져두고 중간중간 상태만 확인하고 싶다.
터미널 창 여러 개를 열지 않고 background session을 관리하고 싶다.

예시 prompt:

Investigate why login tests are flaky.

Review the current PR for security risks.

Find outdated API docs and propose updates.

Agent View는 research preview이며, Claude Code v2.1.139 이상이 필요하고 인터페이스와 단축키는 기능 발전에 따라 바뀔 수 있습니다. 따라서 팀 운영에서 Agent View 자체를 품질 게이트로 보지 말고, 최종 검증은 여전히 테스트, diff review, PR review, hooks 결과로 판단해야 합니다.

08Claude Code on the web: 클라우드에서 코딩 작업 맡기기

Claude Code on the web은 브라우저에서 코딩 작업을 맡기는 research preview 기능입니다. Anthropic이 관리하는 cloud infrastructure에서 task가 실행되며, Pro, Max, Team 사용자와 Enterprise premium seat 또는 Chat + Claude Code seat 사용자에게 제공됩니다. 브라우저를 닫아도 세션은 유지되고, Claude 모바일 앱에서도 모니터링할 수 있습니다.

이동 중에 간단한 버그 수정 요청

적합

여러 repo의 backlog를 병렬 처리

적합

GitHub PR 자동 생성

적합

로컬 환경, custom hooks, MCP가 핵심

터미널이 더 적합

민감한 로컬 파일 접근 필요

터미널 또는 승인된 enterprise 환경

복잡한 architecture 논의

터미널/IDE가 더 안정적

공식 web 문서는 cloud environment, setup scripts, network access, Docker, session 관리, PR auto-fix, --remote, --teleport 같은 terminal-web 이동 기능을 다룹니다.

09Terminal과 Web을 오가는 기능

/teleport 또는 /tp는 Claude Code on the web session을 현재 terminal로 가져오는 명령이고, /remote-control 또는 /rc는 로컬 세션을 claude.ai에서 remote control 가능하게 만듭니다. /web-setup은 local gh CLI credentials를 사용해 GitHub 계정을 Claude Code on the web과 연결합니다.

자주 쓰는 흐름:

claude --remote "fix the failing CI on this branch"

/teleport

/remote-control

web

브라우저/모바일에서 작업 맡기기

terminal

로컬 환경과 extension layer를 최대한 활용

teleport

web session을 terminal로 가져오기

remote-control

로컬 세션을 다른 기기에서 제어

10Dynamic Workflows: 수십~수백 agent를 오케스트레이션하기

Dynamic workflows는 subagent를 대규모로 오케스트레이션하는 고급 기능입니다. dynamic workflow는 Claude가 작성한 JavaScript script가 여러 subagent를 조정하고, runtime이 이를 background에서 실행하는 방식입니다. 코드베이스 감사, 대형 migration, 교차 검증이 필요한 research처럼 한 대화가 직접 조율하기 어려운 작업에 적합합니다.

dynamic workflows는 research preview이며 Claude Code v2.1.154 이상이 필요합니다. 모든 paid plan, Anthropic API access, Bedrock, Vertex AI, Microsoft Foundry에서 사용할 수 있고, Pro에서는 /config의 Dynamic workflows row에서 켜야 합니다.

11Workflow와 subagent의 차이

subagents, skills, workflows의 차이는 "누가 다음 단계를 결정하는가"로 설명할 수 있습니다.

정체

Subagent=Claude가 부르는 작업자 · Skill=Claude가 따르는 지식·절차 · Workflow=runtime이 실행하는 script

계획 보관 위치

Subagent/Skill=Claude 대화 흐름 · Workflow=workflow script

중간 결과

Subagent=Claude context로 돌아옴 · Skill=Claude context에 남음 · Workflow=script 변수에 남고 최종 결과만 반환 가능

반복성

Subagent=agent 정의 재사용 · Skill=instruction 재사용 · Workflow=orchestration 자체 재실행

규모

Subagent=몇 개 작업 위임 · Skill=작업 절차 단위 · Workflow=수십~수백 agent 규모

subagent와 skill은 Claude가 turn by turn으로 조율하지만, workflow는 script가 loop, branching, intermediate result를 들고 실행합니다. 따라서 Claude의 context에는 최종 답변만 남길 수 있습니다.

작은 위임 → subagent · 반복 절차 → skill · 대규모 병렬 orchestration → workflow

12Workflow 실행과 모니터링

Claude Code에는 /deep-research라는 built-in workflow가 있고, workflow 실행 중에는 /workflows로 진행 상황을 볼 수 있습니다. /workflows view는 phase별 agent 수, token total, elapsed time을 보여주며, phase나 agent로 drill down해서 prompt, tool call, result를 볼 수 있습니다.

/deep-research What changed in the Node.js permission model between v20 and v22?

/workflows

직접 workflow를 만들고 싶다면 prompt에 workflow라는 단어를 넣어 요청할 수 있습니다.

Create a workflow to audit all API endpoints for missing authorization checks. Do not edit files. Return a prioritized report with file paths and evidence.

또는 /effort ultracode를 켤 수 있습니다. ultracode는 xhigh reasoning effort와 automatic workflow orchestration을 결합한 설정이며, 더 많은 token과 시간이 들어가므로 routine work로 돌아오면 /effort high로 낮추는 것이 좋습니다.

13Workflow 사용 시 주의사항

Workflow는 강력하지만 초보자가 남용하면 안 됩니다.

비용이 커질 수 있음

많은 agent가 동시에 실행됨

결과 검증 필요

대규모 자동 조사도 오류 가능

mid-run 사용자 입력 제한

단계별 승인에는 별도 workflow가 나음

script를 읽어야 함

중요한 작업은 raw script 확인 필요

팀 정책 적용 필요

enterprise에서는 disable 가능

작은 작업에는 과함

subagent나 일반 대화가 더 빠름

workflow는 최대 16개 concurrent agents, run당 최대 1,000 agents 같은 제한이 있고, workflow 자체는 filesystem이나 shell에 직접 접근하지 않으며 agents가 읽기·쓰기·명령 실행을 담당합니다. 또한 많은 agent를 spawn하므로 같은 작업을 대화로 처리하는 것보다 의미 있게 더 많은 token을 쓸 수 있습니다.

14Enterprise 배포 로드맵

팀 규모가 커지면 개인 설정과 project settings만으로는 부족해집니다. Enterprise 단계에서는 중앙 정책, 보안 통제, 비용 모니터링, 감사 로그가 중요합니다. 조직 관리자는 permission rules, sandboxing, managed policy CLAUDE.md, MCP server control, plugin marketplace control, customization lockdown, hook restrictions, Agent View 비활성화, 최소 버전 정책을 설정할 수 있습니다.

인증

SSO, 조직 계정, provider 선택

정책

managed settings

권한

allow, ask, deny, bypass 차단

Sandbox

filesystem/network isolation

MCP

허용/차단 서버 목록

Plugins

허용 marketplace와 internal plugin

Hooks

managed hooks만 허용할지 여부

Agent View

background agents 허용 여부

비용

OTel, analytics, usage dashboard

데이터

retention, training, compliance

15Enterprise에서 꺼야 할 수도 있는 기능

모든 고급 기능이 모든 조직에 맞는 것은 아닙니다. 공식 settings 문서에는 background agents와 Agent View를 끄는 disableAgentView, remote control을 막는 disableRemoteControl, skill shell execution을 막는 disableSkillShellExecution, workflows를 끄는 disableWorkflows 같은 정책 항목이 있습니다.

{
  "disableAgentView": true,
  "disableRemoteControl": true,
  "disableWorkflows": true,
  "disableSkillShellExecution": true
}

회사 정책상 제어가 어려운 기능은 먼저 끄고, 파일럿 팀에서 안전 기준을 만든 뒤 단계적으로 켭니다.

16사용량과 비용 모니터링

조직에서는 /usage만으로는 부족할 수 있습니다. Claude Code가 OpenTelemetry를 통해 metrics, logs/events, optional traces를 export할 수 있고, 이를 조직의 monitoring backend에 연결해 세션, tool, token, cost 사용량을 추적할 수 있습니다.

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
claude

팀 단계에서는 다음 정도만 봐도 충분합니다.

누가 가장 많이 쓰는가
어떤 repo에서 비용이 많이 나는가
어떤 MCP/plugin/subagent가 비용을 키우는가
오류가 많은 tool은 무엇인가
workflow나 background agents가 과하게 쓰이는가

17변경 로그 확인법

Claude Code는 변화가 빠른 도구입니다. 따라서 guide에는 "현재 기준"을 고정해서 쓰되, 독자에게 최신 확인 방법을 알려줘야 합니다.

세션 안에서 확인:

/release-notes

터미널에서 버전 확인:

claude --version

업데이트:

claude update

/release-notes는 interactive version picker를 열어 특정 버전의 release notes 또는 전체 버전을 볼 수 있게 합니다. /usage는 session cost, plan usage limits, activity stats를 보여주고 /cost, /stats는 /usage의 aliases입니다.

모델명, 가격, preview 기능, command 이름은 항상 바뀔 수 있다.
문서에는 "작성 시점 기준"을 표시한다.
독자에게 /release-notes와 claude --version 확인법을 알려준다.

18최신 기능을 반영할 때의 기준

Changelog를 볼 때는 모든 항목을 가이드에 넣지 않습니다. 다음 기준으로 선별합니다.

높음

명령 이름 변경, 보안 정책, 기본 모델 변경, 권한 동작 변경

중간

UI 개선, 성능 개선, 새 slash command

낮음

내부 버그 수정, 특정 플랫폼 edge case

별도 주석

research preview, 점진적 rollout, plan별 제한

예를 들어 changelog v2.1.157에는 .claude/skills directory plugin 자동 로드, claude plugin init <name>, /plugin autocomplete 등이 추가됐고, v2.1.158에는 Bedrock, Vertex, Foundry에서 Opus 4.7/4.8 auto mode opt-in이 추가됐습니다. 이런 항목은 기능 설명에 영향을 주므로 guide 업데이트 후보가 됩니다.

19명령어 치트시트 (1) · 시작과 세션

현재 폴더에서 시작

claude

질문과 함께 시작

claude "explain this project"

단일 질의 후 종료

claude -p "query"

최근 세션 이어가기

claude -c

특정 세션 재개

claude -r "<session>"

세션 종료

/exit

새 작업 시작

/clear [name]

이전 세션 선택

/resume

세션 이름 지정

/rename auth-refactor

세션 분기

/branch [name]

20명령어 치트시트 (2) · 작업 제어

계획부터 세우기

/plan [description]

변경사항 확인

/diff

코드 리뷰

리뷰 결과 적용

/code-review --fix

cleanup 전용 리뷰

/simplify

보안 리뷰

/security-review

앱 실행 검증

/run, /verify

되돌리기

/rewind

빠른 side question

/btw <question>

/code-review는 correctness bugs와 cleanup 관점의 review를 수행하고, --fix로 findings를 working tree에 적용할 수 있습니다. /simplify는 v2.1.154부터 correctness bug를 찾기보다 cleanup-only review로 분리됐습니다.

21명령어 치트시트 (3) · 비용·모델·컨텍스트

사용량·비용 확인

/usage

기존 alias

/cost, /stats

모델 선택

/model

추론 강도 선택

/effort

빠른 모드

/fast

컨텍스트 사용량 확인

/context

컨텍스트 압축

/compact

새 context로 시작

/clear

session recap

/recap

/usage는 session cost, plan usage limits, activity stats를 보여주며, Pro/Max/Team/Enterprise plan에서는 skill, subagent, plugin, MCP server별 usage breakdown도 포함합니다. /cost와 /stats는 /usage aliases입니다.

22명령어 치트시트 (4) · 설정·확장

설정 확인

/status

설정 UI

/config, /settings

권한 관리

/permissions

CLAUDE.md 관리

/memory

hook 확인

/hooks

MCP 확인

/mcp

subagent 관리

/agents

skill 목록

/skills

skill 다시 로드

/reload-skills

plugin 관리

/plugin

plugin 다시 로드

/reload-plugins

문제 진단

/doctor, /debug

23명령어 치트시트 (5) · Background·Agent View·Workflow

현재 세션 background로 보내기

/background, /bg

background session 보기

claude agents

background session 중지

/stop

background task 보기

/tasks, /bashes

shell job background 실행

claude --bg --exec 'pytest -x'

workflow 보기

/workflows

built-in research workflow

/deep-research <question>

web session 가져오기

/teleport, /tp

remote control 켜기

/remote-control, /rc

GitHub web setup

/web-setup

24명령어 치트시트 (6) · 파일·디렉터리·Git

Git 상태 확인

! git status

diff 확인

! git diff 또는 /diff

파일 참조

@src/file.ts

추가 디렉터리 접근

/add-dir <path>

project 초기화

/init

PR review

/review [PR]

PR autofix

/autofix-pr [prompt]

PR session 가져오기

claude --from-pr 123

/autofix-pr은 현재 branch의 open PR을 감지해 CI failure나 review comment를 고치는 web session을 spawn할 수 있고, /review는 local session에서 PR을 review합니다.

25명령어 치트시트 (7) · 단축키

Ctrl+C

현재 작업 취소 또는 입력 지우기

Esc

현재 응답/도구 호출 중단

Ctrl+D

세션 종료

Ctrl+L

화면 다시 그리기

Ctrl+R

prompt history search

Ctrl+B

실행 중 Bash를 background로 보내기

Shift+Tab

권한 모드 순환

Alt/Option+P

모델 전환

Alt/Option+T

thinking toggle

Ctrl+J

줄바꿈

단축키 도움말

Ctrl+R history search는 기본적으로 모든 프로젝트의 prompt를 검색하며, Ctrl+S로 현재 session, current project, all projects 범위를 순환할 수 있습니다. background bash는 Ctrl+B로 뒤로 보낼 수 있습니다.

26파일 구조 빠른 참조

CLAUDE.md

프로젝트 기본 규칙

.claude/settings.json

팀 공통 설정

.claude/settings.local.json

개인 로컬 설정

~/.claude/settings.json

사용자 전체 설정

.mcp.json

project MCP 서버

.claude/skills/

project skills

~/.claude/skills/

personal skills

.claude/agents/

project subagents

~/.claude/agents/

personal subagents

.claude/hooks/

hook scripts

.claude/workflows/

project workflows

~/.claude/workflows/

personal workflows

저장한 workflow는 .claude/workflows/에 두면 project shared command가 되고, ~/.claude/workflows/에 두면 모든 project에서 개인용 command가 됩니다. 이름이 충돌하면 project workflow가 우선합니다.

27기능 선택 빠른 판단표 (1)

코드베이스 설명

일반 프롬프트 + Read/Glob/Grep

큰 수정 전 계획

/plan

세션이 길어짐

/context → /compact

비용 확인

/usage

반복 지식 재사용

Skill

항상 실행할 자동화

Hook

외부 도구 연결

MCP

28기능 선택 빠른 판단표 (2)

큰 탐색 분리

Subagent

여러 background 작업 관리

Agent View

긴 작업을 터미널 밖으로

Background agent

대규모 병렬 조사

Workflow

팀 배포

Plugin

조직 정책 강제

Managed settings

문제 해결

/doctor, /debug

29초보자가 외우면 좋은 최소 세트

정말 최소로만 외운다면 이 정도면 됩니다.

꼭 기억할 slash command:

/help · /status · /usage · /context · /compact
/clear · /plan · /diff · /code-review
/permissions · /mcp · /hooks · /agents
/skills · /plugin · /doctor · /release-notes

꼭 기억할 터미널 명령:

claude
claude --version
claude doctor
claude update
claude -c
claude -p "query"
claude agents
claude mcp list
claude mcp get <name>
claude plugin list

30고급 기능은 이렇게 접근한다

고급 기능을 배울 때는 항상 작은 실험부터 합니다.

Background agent

문서 요약 같은 안전 작업부터

Agent View

읽기 전용 조사 2~3개부터

Workflow

/deep-research로 먼저 감각 익히기

Web

작은 PR 생성부터

MCP

읽기 전용 GitHub/Sentry부터

Hooks

echo나 formatter부터

Enterprise

파일럿 팀부터

바로 production deploy, DB migration, 대규모 자동 수정으로 가지 않습니다. Claude Code의 고급 기능은 강력하지만, 강력한 기능일수록 권한, 비용, 검증 절차가 필요합니다.

31마지막 실전 루틴 (1) · 기본 루틴

일상 개발에서 가장 안정적인 루틴입니다.

/status
/context
작업 설명
큰 작업이면 /plan
수정 승인
테스트·lint·build
/diff
/code-review
/usage
/compact 또는 /clear

32마지막 실전 루틴 (2) · 대형 작업과 팀

대형 작업에서는 기본 루틴을 이렇게 확장합니다.

Explore subagent로 관련 영역 조사
/plan으로 수정 계획
필요하면 background agent나 Agent View로 병렬 조사
정말 큰 규모면 workflow 고려
수정 후 tests, lint, build
/code-review 또는 /security-review
PR review

팀 작업에서는 이렇게 고정합니다: CLAUDE.md 확인 → .claude/settings.json 권한 확인 → /plan 승인 → 최소 범위 수정 → CI와 사람 리뷰 → 민감 변경은 별도 보안 리뷰.

33이 통합 가이드 전체 핵심 요약

Claude Code는 단순한 채팅형 코딩 도우미가 아닙니다. 코드베이스를 읽고, 파일을 수정하고, 명령을 실행하고, hooks, MCP, subagents, skills, plugins, workflows로 확장되는 에이전트형 CLI입니다. 숙련된 사용자는 탐색과 전문 작업을 delegation layer로 넘기고 extension layer를 workflow에 맞게 설정합니다.

설정은 동작을 정한다.
권한은 위험을 막는다.
CLAUDE.md는 프로젝트 규칙을 알려준다.
Plan Mode는 큰 수정 전 안전장치다.
Git diff는 최종 검증의 출발점이다.
비용은 /usage와 /context로 관리한다.
Hooks는 반복 작업을 자동화한다.
MCP는 외부 도구를 연결한다.
Subagents는 큰 탐색을 분리한다.
Skills는 반복 지식을 재사용한다.
Plugins는 팀 배포 단위다.
IDE는 시각적 검토를 돕는다.
Agent View와 workflows는 대규모 작업용이다.
팀에서는 정책, 권한, 리뷰, 비용 관리가 필수다.

34마무리

여기까지 오면 Claude Code를 "그냥 코드 고쳐주는 도구"가 아니라, 내 개발 흐름을 함께 운영하는 작업 파트너로 다룰 준비가 된 것입니다.

처음에는 /plan, /diff, /usage, /context, /permissions만 잘 써도 충분합니다. 익숙해지면 hooks로 반복 작업을 자동화하고, MCP로 외부 도구를 연결하고, subagents와 skills로 큰 작업을 나누고, 팀에서는 설정과 리뷰 흐름을 표준화하면 됩니다.

마지막 원칙

Claude에게 맡기되, 최종 책임과 판단은 개발자가 가진다. 좋은 도구는 사람을 대체하는 것이 아니라, 더 차분하고 정확하게 일하게 만듭니다. 이 가이드가 Claude Code를 안전하고 자신 있게 쓰는 출발점이 되길 바랍니다.

실무에서 쓰는 AI 도구,한 장씩 넘기며 익히세요

Claude Code 실전 가이드

1. Claude Code가 무엇인지 먼저 이해하기

01핵심 개념

02CLI란 무엇인가

03Claude Code가 할 수 있는 일

04Claude Code의 3단계 구조

05Core Layer

06Delegation Layer

07Extension Layer

08실제 사용 흐름

09좋은 첫 질문의 3가지 이유

10초보자에게 가장 중요한 사용 원칙

11버그 수정 예시

12예시 프롬프트 ① · ②

프로젝트 처음 볼 때

특정 기능을 찾을 때

13예시 프롬프트 ③ · ④

수정 전에 계획을 받을 때

변경 후 검토할 때

14초보자가 자주 하는 실수 ①

실수 1. 바로 "고쳐줘"라고 말한다

15초보자가 자주 하는 실수 ②

실수 2. 파일 수정 후 확인하지 않는다

16초보자가 자주 하는 실수 ③

실수 3. 민감 정보를 그대로 보여준다

17초보자가 자주 하는 실수 ④

실수 4. 큰 작업을 한 번에 맡긴다

18체크리스트

이 단원에서 기억할 것

2. 설치 전 준비사항 확인하기

01핵심 개념

02왜 필요한가

03설치 전에 발생할 수 있는 문제들

04시스템 요구사항

05macOS에서 환경 확인하기

06Windows PowerShell에서 환경 확인하기

07Linux / WSL에서 환경 확인하기

08터미널 준비하기

09터미널 기본 명령어

10계정과 인증 방식 준비하기

11비용 발생 가능성 이해하기

12비용 최적화 습관

13프로젝트 폴더 준비하기

14프로젝트 루트에서 실행해야 하는 이유

15민감 정보 파일 확인하기

16민감 정보 보호 방법

17Git 준비하기

18안전한 작업 흐름

19설치 전 준비 체크리스트 ①

20설치 전 준비 체크리스트 ②

21초보자가 자주 하는 실수 ①

실수 1. 아무 폴더에서나 실행한다

22초보자가 자주 하는 실수 ②

실수 2. 민감 파일이 있는지 확인하지 않는다

23초보자가 자주 하는 실수 ③

실수 3. Git 상태를 확인하지 않고 수정한다

24초보자가 자주 하는 실수 ④

실수 4. 비용 구조를 모르고 큰 작업을 맡긴다

이 단원에서 기억할 것

3. Claude Code 설치하고 버전 확인하기

01핵심 개념

02왜 필요한가

03설치 방법 한눈에 보기

04macOS에 설치하기

05Linux / WSL에 설치하기

06Windows PowerShell에 설치하기

07Windows CMD에 설치하기

08Windows에서 Git for Windows는 꼭 필요한가

09설치 확인하기

10환경 진단하기

11로그인하기

12프로젝트 폴더에서 실행하기

13업데이트하기

14안정 채널과 최신 채널 선택하기

15특정 버전 설치하기

16설치가 안 될 때 확인할 것

문제 1. claude: command not found

17문제 2, 3 진단하기

문제 2. PowerShell과 CMD 명령을 헷갈렸다

실무에서 쓰는 AI 도구,
한 장씩 넘기며 익히세요

문제 1. `claude: command not found`