Claude Code CLI — 실전 학습 가이드

00큰 그림

먼저 이것부터

Claude Code는 "채팅"이 아니라
내 터미널에서 도는 에이전트다.

웹 채팅과의 결정적 차이는 파일을 읽고 쓰고, 명령을 실행하고, 결과를 보고 다시 판단한다는 점입니다. 이 루프를 이해하면 나머지 옵션들이 왜 존재하는지 전부 설명됩니다.

1 — 컨텍스트

무엇을 아는가

현재 디렉터리의 파일, CLAUDE.md, 대화 히스토리, MCP로 붙인 외부 도구. 컨텍스트 윈도가 유한하다는 게 모든 관리 명령(/compact, /clear, subagent)의 이유입니다.

2 — 도구

무엇을 할 수 있는가

Read / Edit / Write / Bash / Grep / Glob / WebFetch / Agent. 각 도구 호출마다 권한 확인이 붙고, 그 확인을 어떻게 처리할지가 permission mode입니다.

3 — 검증

제대로 했는지 확인

테스트, 빌드, 린트, 스크린샷. 검증 수단을 손에 쥐여주면 결과 품질이 계단식으로 올라갑니다. "고쳐줘"보다 "고치고 ./gradlew test 통과할 때까지 해줘"가 훨씬 강력한 이유.

읽는 순서 제안

처음이면 01 → 02 → 04만 보고 바로 실습하세요. 자동화·확장(05~08)은 필요해질 때 돌아오면 됩니다. 맨 아래 7일 실습 코스가 이 순서를 그대로 따라갑니다.

0190초 시작

설치 · 로그인 · 첫 세션

설치는 한 줄, 확인도 한 줄.

네이티브 설치가 권장입니다. 백그라운드 자동 업데이트가 되는 유일한 방식이라서요.

macOS / Linux / WSL

# 네이티브 설치 (권장, 자동 업데이트 O)

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

# 안정 채널로 (약 1주 지연, 큰 리그레션 스킵)

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

Windows PowerShell

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

# winget (자동 업데이트 X)

PS> winget install Anthropic.ClaudeCode

Homebrew / npm

# stable 채널 cask (자동 업데이트 X)

$ brew install --cask claude-code

# 최신 채널을 원하면 claude-code@latest

# npm (Node 22+ 필요, 같은 네이티브 바이너리를 받음)

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

설치 확인

claude --version 이 2.1.xxx (Claude Code) 를 뱉으면 성공. 더 자세히 보려면 세션을 켜지 않고 진단만 돌리는 claude doctor.
로그인

그냥 claude 를 실행하면 브라우저가 열립니다. 또는 claude auth login. API 과금(Console 계정)으로 붙이려면 claude auth login --console. Pro / Max / Team / Enterprise / Console 계정이 필요하고, 무료 플랜은 사용할 수 없습니다.
프로젝트 폴더에서 첫 세션

git 리포지터리 루트에서 켜는 게 가장 좋습니다. Claude가 git 상태를 읽고, 체크포인트(되돌리기)도 활성화됩니다.
프로젝트 기억 만들기

세션 안에서 /init 을 실행하면 프로젝트를 스캔해서 CLAUDE.md 초안을 만들어 줍니다. 04번 섹션에서 자세히.

첫날의 팁

세션 안에서 /powerup 을 쳐보세요. 애니메이션 데모가 붙은 짧은 인터랙티브 레슨으로 기능들을 하나씩 알려줍니다. 그리고 ? (빈 입력창에서) 는 단축키 패널을 토글합니다.

02Tier S
매일 쓰는 것

사용 빈도 최상위

이 여덟 개로
전체 사용량의 90%가 끝난다.

알파벳 순 --help 를 외우려 하지 마세요. 아래 여덟 개를 손에 익히면 나머지는 "그때 찾아 쓰는 것"이 됩니다. 각 항목의 게이지는 실제 체감 사용 빈도입니다.

한 줄 치트시트	이럴 때
claude	지금 이 폴더에서 작업 시작
claude -c	아까 하던 대화 이어서
Shift+Tab	계획 모드 ↔ 자동 수락 ↔ 수동 전환
Esc / Esc Esc	지금 멈춰 / 아까 상태로 되돌려
@ · !	파일 지정 / 셸 명령 바로 실행
/compact	대화가 길어져서 컨텍스트가 빡빡할 때
claude -p "…"	스크립트·파이프에서 한 방 질의
/model · /effort	모델·추론 강도 조절

~~claude~~ · ~~claude "질문"~~

기본. 인자 없이 켜면 인터랙티브 세션, 문자열을 붙이면 그 프롬프트로 시작합니다. 중요한 건 어디서 켜느냐입니다 — 현재 디렉터리가 Claude의 작업 범위이자 설정 탐색 기준점입니다.

첫 프롬프트 예시

$ claude "이 프로젝트 구조를 설명하고, 빌드 진입점과 CI 스크립트가 어디인지 알려줘"

# 여러 폴더를 함께 보게 하려면 (모노레포)

$ claude --add-dir ../sdk-android ../sdk-ios

# 세션에 이름 붙이기 — /resume 목록에서 찾기 쉬워짐

$ claude -n "vk-id-integration"

알아두면 --add-dir 는 파일 접근 권한만 줍니다. 그 폴더의 .claude/ 설정이나 CLAUDE.md는 대부분 로드되지 않습니다. 매번 쓰기 귀찮으면 settings.json 의 permissions.additionalDirectories 에 박아두세요.

~~Shift+Tab~~ — 권한 모드 순환

가장 저평가된 단축키입니다. Claude가 얼마나 자율적으로 움직일지를 키 하나로 바꿉니다. 큰 작업은 plan 으로 시작해서 계획을 승인받고, 리팩터링 구간에서는 acceptEdits 로 흐름을 끊지 않게 하는 식으로 씁니다.

모드	동작	쓰는 순간
default (UI 표기: Manual)	매 도구 호출마다 물어봄	낯선 리포, 운영 코드
plan	읽기만 하고 계획을 세워 승인 요청. 파일을 안 건드림	큰 변경의 시작점
acceptEdits	파일 편집은 자동 승인, 명령 실행은 물어봄	반복 수정, 마이그레이션
auto	분류기가 안전한 건 통과, 위험한 건 차단	긴 자율 작업. 승인/차단 중간 지점
dontAsk	미리 허용한 도구만 실행, 나머지는 그냥 거부	화이트리스트 운영
bypassPermissions	전부 통과 위험	격리된 컨테이너·샌드박스 전용

계획 모드로 시작하는 습관

$ claude --permission-mode plan

# 세션 안에서 바로 계획 모드 진입 + 과제 전달

> /plan Firebase Remote Config로 보상형 광고 노출 간격 A/B 테스트를 붙이는 계획을 세워줘.

기존 광고 매니저 코드를 최대한 건드리지 않는 방향으로.

⏵⏵ plan mode · 계획을 검토하고 승인하면 그때부터 파일을 수정합니다

--dangerously-skip-permissions

bypassPermissions 와 동일합니다. 인터넷이 차단된 격리 샌드박스가 아니면 쓰지 마세요. "권한 팝업이 귀찮다"의 정답은 이게 아니라 auto 모드 + /fewer-permission-prompts(허용 목록 자동 제안)입니다. 중간 지점이 필요하면 --allow-dangerously-skip-permissions 로 모드 순환에만 추가해 두고 필요할 때 전환하는 방법도 있습니다.

~~Esc~~ · ~~Esc Esc~~ — 끼어들고 되돌리기

잘못된 방향으로 10분 달리게 두는 것이 가장 비싼 실수입니다. 이상하면 즉시 Esc. 지금까지 한 작업은 유지되고, 바로 방향을 다시 잡을 수 있습니다.

키	동작
Esc	진행 중인 응답·도구 호출을 중단 (대화는 유지). 다이얼로그가 열려 있으면 다이얼로그만 닫힘
Esc Esc	입력창에 글이 있으면 초안 비우기 → 빈 입력창에서 누르면 rewind 메뉴(코드·대화를 이전 체크포인트로 복원 / 여기까지 요약)
Ctrl+C	중단. 실행 중인 게 없으면 첫 번째는 입력 비우기, 두 번째는 종료
Ctrl+O	트랜스크립트 뷰어 — 어떤 도구를 어떤 인자로 불렀는지 전부 펼쳐 봄. 디버깅의 시작점
Ctrl+B	실행 중인 Bash 명령/에이전트를 백그라운드로 (tmux는 두 번)
Ctrl+T	Claude가 만든 to-do 체크리스트 토글
Ctrl+R	프롬프트 히스토리 역방향 검색
Ctrl+G	긴 프롬프트를 기본 에디터에서 작성

체크포인트 Claude의 파일 편집은 자동으로 체크포인트가 찍힙니다. 단 Bash로 실행한 변경, 서브에이전트 편집, 외부에서 바꾼 파일은 복원 대상이 아닙니다. git을 대체하지 않습니다 — 커밋은 커밋대로 하세요.

-c / -r — 이어서 하기

터미널을 닫아도 대화는 남습니다. 매번 처음부터 설명하는 건 순수한 낭비입니다.

이어가기 3종

# 이 디렉터리의 가장 최근 대화 이어가기

$ claude -c

# 목록에서 골라 재개 (이름·세션ID·PR 번호로도 가능)

$ claude -r

$ claude -r "vk-id-integration" "러시아 빌드 쪽 마무리하자"

$ claude --from-pr 1234

# 이어가되 원본 세션은 보존 (새 세션 ID로 분기)

$ claude -c --fork-session

# 스크립트에서 이어가기 — 파이프라인 2단계 처리에 유용

$ claude -c -p "방금 수정한 부분만 타입 에러 검사해줘"

@ · ! · 이미지 붙여넣기

컨텍스트를 정확히 주는 세 가지 방법. "어디에 있는지 찾아봐"에 토큰을 쓰지 말고 그냥 지목하세요.

세션 안에서

# @ : 파일/디렉터리 자동완성. 여러 개 지목 가능

> @app/build.gradle.kts @app/src/main/AndroidManifest.xml 이 두 파일 기준으로

minSdk를 24로 올릴 때 깨질 수 있는 지점을 짚어줘

# ! : 셸 모드. Claude를 거치지 않고 바로 실행하고, 출력이 컨텍스트에 들어감

> ! ./gradlew :app:assembleDebug

… 빌드 실패 로그 …

↳ v2.1.186부터 Claude가 출력을 보고 알아서 답합니다 (두 번 물을 필요 없음)

# 이미지: Ctrl+V (iTerm2는 Cmd+V, Windows/WSL은 Alt+V)

> [Image #1] 이 레이아웃에서 하단 버튼이 잘리는데, 어느 XML을 봐야 할까?

셸 모드 팁 ! 뒤에서 Tab 은 이 프로젝트에서 이전에 실행한 ! 명령을 자동완성합니다. 경로에 / 가 들어가면 파일 경로 드롭다운도 뜹니다. 나가려면 빈 입력에서 Esc.

~~/context~~ · ~~/compact~~ · ~~/clear~~

컨텍스트가 꽉 차면 응답 품질이 떨어지고 비용이 오릅니다. 이 세 개가 그 관리 도구입니다. 차이를 정확히 알아두면 좋습니다.

/context

지금 컨텍스트를 무엇이 얼마나 먹고 있는지 색깔 그리드로 보여줍니다. MCP 서버가 범인인 경우가 정말 많습니다. /context all 로 항목별 전개.

/compact

대화를 요약해서 압축. 작업은 계속 이어갑니다. 요약 방향을 지정할 수 있습니다 — /compact 결정 사항과 남은 TODO 중심으로.

/clear

컨텍스트를 비우고 새 대화. 프로젝트 기억(CLAUDE.md)은 유지됩니다. 작업을 바꿀 때는 compact가 아니라 clear가 맞습니다. 별칭 /new, /reset.

비용 /compact 는 프롬프트 캐시를 무효화합니다. 반대로 CLAUDE.md 수정, 출력 스타일 변경, 권한 모드 변경, 스킬 호출은 캐시를 유지합니다. 모델 전환·MCP 연결/해제·플러그인 토글은 캐시를 날립니다 — 작업 중간에 자꾸 모델을 바꾸면 그만큼 비쌉니다.

-p — 한 방 질의 (헤드리스)

응답만 출력하고 종료합니다. 인터랙티브 세션이 아니니 파이프와 스크립트에 그대로 꽂힙니다. CI, Jenkins, git hook, 알림 봇의 재료가 되는 옵션입니다.

파이프로 흘려넣기

$ cat build.log | claude -p "실패한 Gradle task와 원인만 3줄로 뽑아줘"

$ git diff | claude -p "이 diff의 커밋 메시지를 conventional commits 형식 한 줄로"

# JSON으로 받아서 jq로 처리

$ claude -p --output-format json "변경된 파일 목록만 알려줘" | jq -r .result

# 안전장치: 턴 수와 비용 상한

$ claude -p --max-turns 3 --max-budget-usd 0.50 "…"

속도 --bare 를 붙이면 훅·스킬·플러그인·MCP·CLAUDE.md 자동 탐색을 모두 건너뛰고 시작합니다. 스크립트에서 수천 번 호출할 때 체감 차이가 큽니다. 대신 필요한 컨텍스트는 --append-system-prompt 등으로 직접 넣어야 합니다.

~~/model~~ · ~~/effort~~ · ~~/fast~~

"느려요" / "비싸요" / "이건 못 풀어요" 의 대부분은 이 두 축으로 해결됩니다. 모델은 무엇으로 생각하느냐, effort는 얼마나 오래 생각하느냐입니다.

모델과 추론 강도

# 별칭: opus / sonnet / haiku / fable, 또는 전체 이름

$ claude --model sonnet --effort high

# 세션 안에서: 인자 없이 치면 피커/슬라이더가 뜸

> /model ← s 키를 누르면 "이번 세션만" 적용

> /effort ← low · medium · high · xhigh · max · ultracode

# 과부하/모델 은퇴 대비 폴백 체인

$ claude --fallback-model sonnet,haiku

effort 고르는 기준

low/medium — 정형 작업, 파일 이동, 문서 정리.
high — 대부분의 코딩 작업의 기본값.
xhigh / max — 원인 불명 버그, 아키텍처 설계, 성능 문제.
ultracode — xhigh + 워크플로 자동 오케스트레이션.

effort ≠ fast mode

/fast (또는 Option+O)는 같은 모델을 더 빠른 인프라로 돌립니다. 추론량이 아니라 지연시간을 줄이는 것이고, 대신 단가가 올라갑니다. 생각을 더 시키고 싶으면 effort, 기다리는 게 답답하면 fast mode.

한 번만 깊게 매번 xhigh로 태우기 아까우면 프롬프트에 ultrathink 라고 적어서 그 턴만 깊게 생각시킬 수 있습니다. Option+T / Alt+T 는 확장 사고 토글입니다.

03세션

이어가기 · 분기 · 격리

세션은 브랜치처럼 다뤄라.

대화 하나가 작업 하나입니다. 섞이면 컨텍스트가 오염되고, 오염되면 결과가 나빠집니다. Claude Code는 대화를 분기하고, 격리하고, 백그라운드로 떼어내는 수단을 전부 갖고 있습니다.

하려는 것	방법	결과
같은 대화 계속	claude -c	가장 최근 대화 로드
다른 방향 시도	/branch [이름]	현재 지점에서 분기해 거기로 이동. 원본은 `/resume` 로 복귀 가능
사본을 따로 돌리기	/fork [프롬프트]	대화를 복사해 백그라운드 세션으로. 나는 여기서 계속 작업
곁가지 조사 위임	/subtask	서브에이전트가 조사해서 이 대화로 결과 보고
이 세션을 떼어내기	/background	터미널을 돌려받고 세션은 계속 실행. 별칭 `/bg`
가벼운 질문 하나	/btw 질문	히스토리에 남지 않는 오버레이 답변. 작업 중에도 가능
작업 디렉터리 이동	/cd <경로>	캐시를 유지한 채 세션을 옮김
격리된 작업 공간	claude -w <이름>	git worktree를 만들어 그 안에서 시작

worktree — 동시 작업의 정석

# .claude/worktrees/<이름> 에 격리된 체크아웃 생성

$ claude -w feature-social-login "로그인 화면에 VK ID 버튼을 추가해줘"

# PR에서 브랜치를 따와 worktree 생성

$ claude -w "#1234"

# tmux/iTerm2 패널까지 같이 (worktree 필수)

$ claude -w hotfix --tmux

/btw — 컨텍스트를 더럽히지 않는 질문

> /btw 방금 그 설정 파일 이름이 뭐였지?

┌ 사이드 질문 ─────────────────────┐

│ app/src/main/res/xml/network_ │

│ security_config.xml 입니다. │

└ space 닫기 · c 복사 · f 세션분리 ┘

# 특징: 현재 대화 전체를 보지만 도구는 못 씀.

# 서브에이전트의 정반대 (도구는 있고 컨텍스트는 없음)

실무 규칙 하나

작업이 바뀌면 /clear, 방향이 갈리면 /branch, 오래 걸리는 조사는 /fork 또는 서브에이전트. 하나의 세션에서 두 가지 일을 하지 않는 것만 지켜도 체감 품질이 달라집니다.

04권한 규칙

허용 · 차단 · 격리

모드는 스위치, 규칙은 계약서.

Shift+Tab 이 "지금 이 순간 얼마나 믿을지"라면, 권한 규칙은 "무엇을 영구히 허용/금지할지"입니다. 팀 단위로 굴릴 때는 규칙이 훨씬 중요합니다.

플래그로 임시 지정

# 물어보지 않고 바로 실행할 도구 (허용)

$ claude --allowedTools "Bash(git log *)" "Bash(git diff *)" "Read"

# 차단. 도구 이름만 쓰면 컨텍스트에서 아예 제거됨

$ claude --disallowedTools "Edit" "Bash(rm *)" "mcp__*"

# 애초에 쥐여줄 도구를 제한 (내장 도구만 대상)

$ claude --tools "Read,Grep,Glob" ← 읽기 전용 조사 전용 세션

--allowedTools vs --tools

--allowedTools 는 "물어보지 마"(승인 생략)입니다. 도구는 그대로 다 있습니다.
--tools 는 "이것만 존재해"(도구 목록 자체를 제한)입니다.
읽기 전용 리뷰 봇을 만들 때는 --tools 쪽이 맞습니다.

규칙 문법

Tool — 모든 사용
Bash(git push *) — 특정 명령 패턴
Read(./secrets/**) — 경로 패턴
Agent(model:opus) — 파라미터 매칭
mcp__* — 모든 MCP 도구
영구 적용은 .claude/settings.json 의 permissions 에.

.claude/settings.json — 프로젝트에 커밋해서 팀 공유

{

"permissions": {

"allow": ["Bash(./gradlew test*)", "Bash(git status)", "Read"],

"ask": ["Bash(git push *)"],

"deny": ["Read(./**/*.keystore)", "Bash(rm -rf *)"]

},

"defaultMode": "plan",

"effortLevel": "high"

}

/permissions

스코프별 규칙 조회·추가·삭제, 작업 디렉터리 관리, auto 모드에서 최근 차단된 항목 검토까지 한 화면에서.

/fewer-permission-prompts

내 트랜스크립트를 스캔해서 자주 물어봤던 읽기 전용 명령을 골라 프로젝트 허용 목록으로 제안합니다. 팝업 피로의 정답.

--safe-mode

CLAUDE.md·스킬·플러그인·훅·MCP·커스텀 에이전트를 전부 끄고 시작. "내 설정 중 뭔가가 망가졌다"를 이등분하는 도구.

민감 정보

키스토어, .env, 인증서, 프로비저닝 프로파일은 deny 규칙과 permissions.deny / 설정의 파일 제외 항목으로 선제적으로 막아두세요. 프롬프트 인젝션(외부에서 읽어온 문서·이슈 본문에 "이걸 실행해"가 숨어 있는 경우)은 실제로 존재하는 위험이며, 신뢰할 수 없는 콘텐츠를 읽히는 세션에서는 권한을 좁히는 게 유일한 방어입니다.

05프로젝트 기억

CLAUDE.md · rules · auto memory

같은 설명을 두 번 하지 않는 장치.

"우리 팀은 이렇게 한다"를 매번 타이핑하는 건 낭비입니다. CLAUDE.md 는 세션이 시작될 때 자동으로 로드되는 프로젝트 지침서입니다. 단, 무한정 넣으면 매 요청마다 비용이 붙습니다. 여기서 요령이 갈립니다.

초안 생성 — /init

프로젝트를 스캔해서 CLAUDE.md 초안을 만듭니다. 환경 변수 CLAUDE_CODE_NEW_INIT=1 을 주면 스킬·훅·개인 메모리까지 안내하는 인터랙티브 플로우로 동작합니다.
다듬기 — /memory

CLAUDE.md 편집, auto memory 켜기/끄기, 저장된 자동 메모리 항목 조회. 세션 중에 # 로 시작하는 한 줄을 보내면 그 자리에서 기억으로 추가됩니다.
계층화 — 디렉터리별로 쪼개기

모노레포에서는 루트에 공통 규칙, 각 패키지에 하위 CLAUDE.md를 두면 필요한 것만 로드됩니다. 경로별 규칙은 .claude/rules/ 로 분리할 수도 있습니다.
다이어트 — /doctor

CLAUDE.md가 커지면 /doctor 가 코드에서 유추 가능한 내용(디렉터리 구조, 의존성 목록, 아키텍처 개요)을 잘라내고, 남은 항목을 온디맨드 로드되는 스킬·하위 CLAUDE.md로 옮겨줍니다. 함정·근거·도구 기본값과 다른 관례는 남깁니다.

✕ 이런 건 넣지 말자

이 프로젝트는 Android 앱입니다.
app/ 폴더에 소스가 있고
build.gradle.kts 로 빌드합니다.
의존성: Retrofit, Room, Hilt…

Claude가 파일을 열어보면 30초 안에 알아내는 정보입니다. 매 요청마다 토큰만 태웁니다.

✓ 이런 걸 넣자

· 빌드는 반드시 ./gradlew :app:assembleQaDebug
(assembleDebug 는 서명 설정이 없어서 실패)
· SDK 버전 올릴 때 sdk-version.properties 도 같이
· 커밋 메시지는 [ANIP-123] 접두어 필수
· Jenkins 잡 이름은 절대 수정 금지

파일을 봐도 알 수 없는 함정, 관례, 금지사항. 이게 CLAUDE.md의 본래 용도입니다.

AGENTS.md

이미 AGENTS.md 를 쓰고 있다면 그대로 인식됩니다. 여러 도구를 함께 쓰는 팀은 한쪽을 심볼릭 링크로 걸어 단일 소스로 유지하는 방식이 깔끔합니다.

.claude/rules/

규칙을 파일 단위로 분리하고 경로 조건을 붙일 수 있습니다. "iOS 폴더를 만질 때만 이 규칙"처럼요. 프로젝트 간 공유는 심볼릭 링크로.

auto memory

Claude가 대화에서 알게 된 것을 스스로 기록합니다. /memory 에서 켜고 끄고, 저장된 내용을 감사(audit)할 수 있습니다. 무엇이 저장됐는지 주기적으로 확인하는 습관을 권합니다.

우선순위

지침이 잘 안 먹으면 순서를 확인하세요. 사용자 프롬프트 > 스킬 > CLAUDE.md 순으로 영향력이 큽니다. "항상 지켜야 하는 것"은 CLAUDE.md에, "특정 작업할 때만 필요한 절차"는 스킬로 옮기는 게 정석입니다.

06자동화

headless · CI · 스케줄

사람이 안 보는 곳에서 돌리기.

-p 를 중심으로 출력 포맷, 스키마, 예산 상한, 인증을 조합하면 CI 파이프라인의 한 스텝이 됩니다. 여기가 CLI가 웹 UI를 이기는 지점입니다.

CI에서 쓰는 실전 패턴

#!/usr/bin/env bash

# Jenkins / GitHub Actions 스텝: PR diff 리뷰

set -euo pipefail

RESULT=$(claude -p \

--output-format json \

--max-turns 5 --max-budget-usd 1.00 \

--permission-mode dontAsk \

--allowedTools "Read" "Grep" "Glob" \

"이번 변경분에서 P1급 버그만 골라 파일:라인과 함께 알려줘. 없으면 NONE.")

echo "$RESULT" | jq -r .result | tee review.txt

grep -q NONE review.txt || exit 1

출력 포맷 3종

text — 기본. 사람이 읽거나 그대로 파이프.
json — 결과 한 덩어리. jq 로 처리.
stream-json — 실시간 스트리밍. --verbose 와 함께 쓰며, 진행 상황 UI를 붙일 때.

구조화 출력 — --json-schema

에이전트가 작업을 마친 뒤 스키마에 맞는 JSON을 강제로 받아냅니다. 파싱 실패로 파이프라인이 깨지는 사고를 없애는 옵션입니다.
claude -p --json-schema '{"type":"object", …}' "…"

인증 — CI에서

claude setup-token 으로 장수명 OAuth 토큰을 발급해 시크릿에 넣습니다(구독 계정 필요). API 과금으로 갈 거면 ANTHROPIC_API_KEY. 상태 확인은 claude auth status — 로그인이면 exit 0, 아니면 1을 반환하므로 스크립트에서 바로 분기할 수 있습니다.

시스템 프롬프트 조정

--append-system-prompt 는 기본 프롬프트 뒤에 덧붙이고(코딩 어시스턴트 정체성 유지), --system-prompt 는 전부 교체합니다(도구 가이드·안전 지침까지 사라짐). 비코딩 파이프라인이 아니면 append 쪽을 쓰세요. 파일 버전은 각각 -file 접미사.

세션을 안 끄고 반복시키기

명령	동작	예시
/loop [간격] [프롬프트]	세션이 열려 있는 동안 프롬프트를 주기 반복. 간격을 생략하면 Claude가 스스로 페이스 조절	/loop 5m 배포 끝났는지 확인해줘
/goal <조건>	조건이 충족될 때까지 턴을 넘기며 계속 작업	/goal 모든 유닛 테스트가 통과할 때까지
/schedule	Routine 생성 — 스케줄·GitHub 이벤트·API 호출로 클라우드 세션 트리거	매일 아침 PR 다이제스트

쓰임새 아침 PR 요약, 야간 CI 실패 분석, 주간 의존성 감사, PR 머지 후 문서 동기화 — 사람이 잊는 일들에 잘 맞습니다.

07확장

Skills · Subagents · MCP · Hooks · Plugins

다섯 개의 확장점,
헷갈리기 쉬운 다섯 개.

이름이 비슷해서 처음엔 다 같아 보입니다. 판단 기준은 하나입니다 — "언제 로드되고, 컨텍스트를 얼마나 먹고, 누가 실행하는가."

확장점	정체	언제 쓰나	컨텍스트 비용
Skill	절차를 적은 마크다운. Claude가 상황을 보고 스스로 호출하거나 `/이름` 으로 직접 호출	"릴리즈 노트 만드는 우리 방식"처럼 반복되는 절차	필요할 때만 로드 저렴
Subagent	별도 컨텍스트로 도는 하위 에이전트. 도구·모델·권한을 따로 지정	출력이 많은 조사를 격리하거나 병렬 리서치	본 대화 오염 없음
MCP 서버	외부 시스템을 도구로 연결 (Jira, Sentry, DB, Slack…)	코드 밖의 데이터가 필요할 때	항상 로드 비쌈
Hook	수명주기 이벤트에 붙는 스크립트 (편집 후 포맷, 보호 파일 차단, 알림)	모델 판단에 맡기지 말고 기계적으로 강제할 것	거의 0
Plugin	위의 것들을 묶어 배포하는 패키지 + 마켓플레이스	팀에 세팅을 동일하게 배포	담긴 내용에 따름

MCP 붙이기

$ claude mcp ← 서버 추가/관리

$ claude mcp login sentry ← OAuth를 셸에서 처리

$ claude mcp logout sentry

# 세션 한정으로 특정 설정만 사용

$ claude --mcp-config ./mcp.json --strict-mcp-config

# 세션 안에서 상태 확인 / 재연결 / 끄기

> /mcp

> /mcp disable all ← 컨텍스트 다이어트

서브에이전트 즉석 정의

$ claude --agents '{

"reviewer": {

"description": "코드 리뷰 담당",

"prompt": "너는 시니어 리뷰어다.

버그와 경계조건만 지적해라."

}

}'

# 파일로 두려면 .claude/agents/reviewer.md

# (frontmatter 로 model·tools·permission 지정)

컨텍스트 비용 감각

MCP 서버를 5개 붙여두면 아무것도 안 해도 모든 요청에 도구 정의가 실려 갑니다. /context 로 확인해 보고, 상시로 안 쓰는 서버는 /mcp disable. 도구가 아주 많은 서버라면 MCP tool search로 지연 로딩되게 두는 편이 낫습니다.

플러그인 설치

/plugin 으로 메뉴, 또는
claude plugin install code-review@claude-plugins-official
공식 마켓플레이스에 코드 인텔리전스, 보안 리뷰, 외부 연동, 출력 스타일 등이 있습니다.

로컬 개발

--plugin-dir ./my-plugin (디렉터리 또는 .zip)
--plugin-url https://…/p.zip
세션 한정 로드라 실험에 좋습니다. 변경 반영은 /reload-plugins, 스킬만이면 /reload-skills.

훅 시작점

/hooks 로 현재 설정 확인.
가장 흔한 세 가지: 편집 후 포맷터 실행(PostToolUse), 보호 파일 편집 차단(PreToolUse), 작업 완료 알림(Notification / Stop).

08병렬 작업

background · agent view · batch · teams

한 사람이 여러 개를 동시에 굴리는 법.

Claude가 3분간 생각하는 동안 터미널을 쳐다볼 이유가 없습니다. 백그라운드로 떼어내고, 한 화면에서 전부 감시하는 것이 여기서 배울 전부입니다.

백그라운드 에이전트

# 즉시 반환하고 백그라운드에서 작업

$ claude --bg "flaky한 테스트를 찾아서 원인 분석 리포트를 남겨줘"

✓ session 7c5dcf5d 시작됨

# 모든 세션을 한 화면에서 — 무엇이 돌고, 무엇이 나를 기다리는지

$ claude agents

$ claude logs 7c5dcf5d ← 출력 보기

$ claude attach 7c5dcf5d ← 이 터미널로 붙기

$ claude stop 7c5dcf5d ← 중지

$ claude agents --json ← 스크립트로 상태 폴링

# Claude 세션이 아니라 그냥 셸 명령을 백그라운드 잡으로

$ claude --bg --exec './gradlew test --continue'

/batch

코드베이스 전역 변경을 5~30개 독립 단위로 쪼개고, 각 단위를 별도 worktree의 백그라운드 서브에이전트에게 맡깁니다. 각자 구현·테스트·PR 생성까지.

/batch src/ 아래 Java 파일을 Kotlin으로 마이그레이션해줘

서브에이전트

기본적으로 백그라운드에서 돕니다. 조사·리서치처럼 출력이 많고 본 대화에 남길 필요 없는 일에 씁니다. /tasks 로 현재 세션의 백그라운드 작업 목록 확인.

agent teams

여러 팀메이트가 서로 대화하며 협업합니다(경쟁 가설 검증, 병렬 리뷰). 토큰을 많이 씁니다. 표시 방식은 --teammate-mode: in-process / tmux / iterm2.

고르는 기준

파일 충돌이 없는 독립 작업 N개 → /batch 또는 worktree + --bg.
결과만 받아오면 되는 조사 → 서브에이전트.
서로 의견을 주고받아야 하는 문제 → agent teams.
같은 파일을 여러 에이전트가 만지게 하는 조합은 피하세요. worktree로 격리하지 않으면 반드시 충돌합니다.

092026 신기능

알아두면 좋은 최근 변화

지난 몇 달에 생긴 것들.

업데이트가 빠릅니다. --help 에 안 나오는 기능도 많고, 문서가 유일한 출처인 경우도 있습니다. 세션 안에서 /release-notes 로 버전별 변경점을 훑는 습관을 권합니다.

모델 Week 27

Claude Sonnet 5

Pro / Team Standard / Enterprise 구독 시트의 새 기본 모델. 네이티브 1M 토큰 컨텍스트, adaptive thinking 기본 활성. Max·Team Premium·API 쪽 기본값은 Opus 계열. 최상위 티어로 Fable 5 / Mythos 계열이 별도로 있습니다.

진단 Week 28

/doctor 가 고쳐준다

읽기 전용 진단에서 수리까지 하는 체크업으로 바뀌었습니다. 중복 설치, PATH 문제, 깨진 설정 파일, 안 쓰는 스킬·MCP·플러그인의 컨텍스트 비용, 느린 훅, CLAUDE.md 비대화까지 잡아줍니다. 별칭 /checkup.

세션 Week 29

/fork

현재 대화를 복사해서 백그라운드 세션으로 띄우고, 나는 여기서 계속 작업합니다. "이 방향도 한번 시도해보게 하고 나는 다른 걸 하자"에 정확히 맞는 도구.

접근성 Week 29

--ax-screen-reader

장식용 테두리와 애니메이션을 없애고 평문 선형 출력으로 렌더링합니다. VoiceOver·NVDA 대응. 로그로 남길 때도 깔끔합니다.

리뷰

/code-review · ultrareview

/code-review 는 현재 diff에서 정확성 버그와 정리 대상을 찾습니다. --fix 로 바로 적용, --comment 로 GitHub PR 인라인 코멘트. 더 깊게는 claude ultrareview — 클라우드의 멀티에이전트 리뷰를 CI에서도 비대화식으로 실행 가능(--json).

아티팩트

공유 가능한 라이브 페이지

세션 결과를 claude.ai 위의 살아있는 페이지로 만들어 공유합니다. 열어보는 사람의 MCP 커넥터로 실시간 데이터를 당겨오는 것도 가능. Team·Enterprise 중심.

브라우저 / 화면

--chrome, computer use

--chrome 으로 Chrome 확장을 붙이면 로컬 웹앱 테스트, 콘솔 로그 디버깅, 폼 자동 입력, 데모 GIF 녹화까지 합니다. GUI로만 확인 가능한 것에 대해 computer use도 연구 프리뷰로 제공됩니다.

원격

--remote-control · --cloud · --teleport

--rc 로 로컬 세션을 claude.ai/모바일 앱에서 조작. --cloud "작업" 은 클라우드 세션으로 던지고, --teleport 는 웹 세션을 내 터미널로 끌어옵니다. 퇴근 후 진행 상황 확인에 실용적입니다.

알아두면 재미있는 것들

/insights 내 세션들을 분석해 작업 패턴과 마찰 지점 리포트 · /recap 자리를 비운 사이 무슨 일이 있었는지 한 줄 요약 · /powerup 애니메이션 데모가 붙은 기능 학습 레슨 · /color blue 프롬프트 바 색 변경(여러 터미널을 띄웠을 때 구분용) · /export 대화 텍스트로 내보내기 · /copy 2 두 번째 최신 응답 복사 · :heart: 이모지 숏코드 · /radio Claude FM lo-fi 라디오.

10레퍼런스

전체 목록 · 빈도순 정렬

찾아 쓰는 표.

알파벳 순이 아니라 실제로 손이 가는 순서로 묶었습니다. 검색창에 한글로 "worktree", "예산", "권한" 처럼 쳐도 걸립니다.

/

서브커맨드

명령	설명	빈도
claude	인터랙티브 세션 시작. 문자열을 붙이면 그 프롬프트로 시작
claude update	즉시 업데이트. 네이티브 설치는 백그라운드 자동 업데이트가 기본
claude doctor	세션을 켜지 않고 설치·설정 진단만 출력 (읽기 전용)
claude agents	에이전트 뷰 — 모든 병렬 백그라운드 세션 모니터링·디스패치. `--json`, `--cwd`
claude mcp	MCP 서버 설정. `mcp login/logout <서버>` 로 OAuth 처리
claude auth login/logout/status	로그인·로그아웃·상태(JSON, exit code로 분기 가능). `--console` 은 API 과금 계정
claude plugin	플러그인 설치·관리 (별칭 `plugins`)
claude attach / logs / stop / rm / respawn	백그라운드 세션 붙기 · 로그 · 중지 · 목록 제거 · 재시작
claude setup-token	CI·스크립트용 장수명 OAuth 토큰 발급 (구독 필요, 저장하지 않고 출력만)
claude ultrareview [대상]	클라우드 멀티에이전트 코드 리뷰를 비대화식 실행. `--json`, `--timeout`
claude install [버전]	네이티브 바이너리 설치/재설치. `stable`, `latest`, `2.1.118`
claude remote-control	Remote Control 서버 모드로 실행 (로컬 세션 없이)
claude project purge [경로]	프로젝트의 로컬 상태 전부 삭제 — 트랜스크립트·로그·히스토리. `--dry-run`
claude auto-mode defaults / reset	auto 모드 분류기 기본 규칙 출력 / 사용자 설정 초기화
claude daemon status / stop	백그라운드 세션 수퍼바이저 상태 확인·중지 (응답 없을 때 복구용)
claude gateway	SSO·정책을 앞단에 두는 자체 호스팅 게이트웨이 서버 (관리자용)

플래그 — 상시 사용

플래그	설명
-c, --continue	이 디렉터리의 가장 최근 대화 이어가기
-r, --resume [값]	세션 ID·이름으로 재개, 또는 인터랙티브 피커
-p, --print	응답만 출력하고 종료. 파이프·스크립트용 (헤드리스)
--model <모델>	`opus` / `sonnet` / `haiku` / `fable` 별칭 또는 전체 이름
--effort <레벨>	`low·medium·high·xhigh·max·ultracode`. 세션 한정, 저장되지 않음
--permission-mode <모드>	`default(manual)·acceptEdits·plan·auto·dontAsk·bypassPermissions`
--add-dir <경로…>	추가 작업 디렉터리. 파일 접근만 부여하고 설정은 로드하지 않음
-w, --worktree [이름]	격리된 git worktree에서 시작. `#123` 이나 PR URL도 가능
-n, --name <이름>	세션 표시 이름. `--resume <이름>` 으로 되돌아올 수 있음
--verbose	턴별 전체 출력 표시
-v, --version	버전 출력

플래그 — 권한 · 도구

플래그	설명
--allowedTools <도구…>	승인 없이 실행할 도구. 패턴 지원 `"Bash(git log *)"`
--disallowedTools <도구…>	차단. 이름만 쓰면 컨텍스트에서 제거, `Bash(rm *)` 처럼 범위 지정하면 해당 호출만 거부
--tools <목록>	사용 가능한 내장 도구 자체를 제한. `""` 전부 비활성, `"default"` 전체, `"Bash,Edit,Read"`
--dangerously-skip-permissions	모든 권한 확인 생략 = `bypassPermissions`. 격리 환경 전용
--allow-dangerously-skip-permissions	bypass를 `Shift+Tab` 순환에만 추가(시작 모드는 아님)
--permission-prompt-tool <도구>	비대화 모드에서 권한 확인을 처리할 MCP 도구 지정
--safe-mode	모든 커스터마이즈(CLAUDE.md·스킬·플러그인·훅·MCP·테마) 비활성화로 시작. 설정 문제 이등분용

플래그 — 자동화 · 헤드리스

플래그	설명
--output-format <형식>	`text`(기본) · `json` · `stream-json`. print 모드 전용
--input-format <형식>	`text`(기본) 또는 `stream-json`(실시간 스트리밍 입력)
--json-schema <스키마>	작업 완료 후 스키마에 맞는 JSON을 검증해 반환. 잘못된 스키마면 에러로 종료
--max-turns <n>	에이전트 턴 수 제한(무한루프 방지). 초과 시 에러 종료. 기본값 없음
--max-budget-usd <금액>	API 지출 상한(예산 캡). 서브에이전트 비용도 합산됨
--bare	훅·LSP·플러그인·MCP·auto memory·CLAUDE.md 자동 탐색을 건너뛰고 최소 모드로 빠르게 시작
--bg, --background	백그라운드 에이전트로 시작하고 즉시 반환. `-p` 와 함께 쓸 수 없음
--exec <명령>	Claude 세션 대신 셸 명령을 PTY 백그라운드 잡으로 실행
--system-prompt / --system-prompt-file	기본 시스템 프롬프트를 전부 교체. 도구 가이드·안전 지침도 사라짐
--append-system-prompt / -file	기본 프롬프트 뒤에 덧붙임. 대부분의 경우 이쪽이 정답
--append-subagent-system-prompt	모든 서브에이전트 프롬프트에 덧붙임 (`-p` 전용)
--include-partial-messages	스트리밍 부분 메시지 포함. `-p` + `stream-json` 필요
--include-hook-events	훅 수명주기 이벤트를 출력 스트림에 포함
--forward-subagent-text	서브에이전트의 텍스트·사고 블록까지 스트림에 내보내 개별 트랜스크립트 재구성
--no-session-persistence	세션을 디스크에 저장하지 않음 (재개 불가). `-p` 전용
--exclude-dynamic-system-prompt-sections	머신별 정보(cwd·env·메모리 경로)를 첫 사용자 메시지로 이동 → 여러 사용자 간 프롬프트 캐시 재사용률 상승
--fallback-model <목록>	과부하·모델 은퇴 시 폴백. 쉼표로 순서 지정 `sonnet,haiku`
--init / --init-only / --maintenance	Setup 훅을 특정 matcher로 먼저 실행 / 실행만 하고 종료

플래그 — 설정 · 확장 · 환경

플래그	설명
--settings <파일\|JSON>	설정 파일 또는 인라인 JSON. 이 세션에서 동일 키를 덮어씀 (최대 2MiB)
--setting-sources <소스>	불러올 설정 스코프 지정: `user,project,local`
--mcp-config <설정…>	JSON 파일/문자열에서 MCP 서버 로드
--strict-mcp-config	`--mcp-config` 의 서버만 사용, 나머지 MCP 설정 무시
--agents <JSON>	서브에이전트를 인라인 JSON으로 정의 (frontmatter 필드 + `prompt`)
--agent <이름>	이 세션에서 사용할 에이전트 지정
--plugin-dir <경로> / --plugin-url <URL>	세션 한정 플러그인 로드 (디렉터리·zip·원격 zip). 반복 지정 가능
--advisor <모델>	중요한 순간에 2차 모델에게 조언을 구하는 advisor 활성화
--chrome / --no-chrome	Chrome 브라우저 연동 활성화 / 비활성화
--ide	유효한 IDE가 하나면 시작 시 자동 연결
--tmux	worktree용 tmux 세션 생성 (`-w` 필수, iTerm2 네이티브 패널 우선)
--teammate-mode <모드>	agent team 팀메이트 표시 방식: `in-process`(기본) · `auto` · `tmux` · `iterm2`
--session-id <UUID>	세션 ID 직접 지정
--fork-session	재개할 때 원본 대신 새 세션 ID 생성 (`-r`/`-c` 와 함께)
--from-pr [값]	PR 번호·URL로 연결된 세션을 필터해 피커 열기 (GitHub·GitLab·Bitbucket)
--cloud "작업"	claude.ai에 새 웹 세션 생성 (구 `--remote`)
--teleport	웹 세션을 로컬 터미널로 가져오기
--remote-control, --rc [이름]	Remote Control을 켠 인터랙티브 세션 — claude.ai·모바일에서 조작
--disable-slash-commands	이 세션의 모든 스킬·명령 비활성화
--ax-screen-reader	스크린 리더 친화 평문 출력 (테두리·애니메이션 제거)
-d, --debug [필터]	디버그 모드. 카테고리 필터 가능 `"api,mcp"` / `"!statsig"`
--debug-file <경로>	디버그 로그를 특정 파일에 기록 (디버그 모드 자동 활성화)
--betas <베타…>	API 요청에 베타 헤더 포함 (API 키 사용자 전용)
--channels	(연구 프리뷰) 채널 알림을 수신할 MCP 서버 지정

슬래시 명령 — 자주 쓰는 순서

명령	설명
/clear	컨텍스트를 비우고 새 대화 (프로젝트 기억은 유지). 별칭 `/new` `/reset`
/compact [지시]	대화를 요약해 컨텍스트 확보. 요약 방향 지정 가능
/context [all]	컨텍스트 사용량을 색상 그리드로. 최적화 제안 포함
/plan [설명]	계획 모드 진입. 설명을 붙이면 바로 그 과제로 시작
/model [모델]	모델 전환 + 기본값 저장. `s` 키로 이번 세션만
/effort [레벨\|auto]	추론 강도. 인자 없으면 슬라이더
/diff	인터랙티브 diff 뷰어 — 미커밋 변경 + 턴별 diff
/code-review [레벨] [--fix] [--comment]	현재 diff의 정확성 버그·정리 대상 리뷰. `ultra` 는 클라우드 심층 리뷰
/init	프로젝트를 스캔해 `CLAUDE.md` 초안 생성
/memory	CLAUDE.md 편집, auto memory 켜기/끄기 및 항목 조회
/permissions	allow / ask / deny 규칙 관리. 별칭 `/allowed-tools`
/mcp [reconnect\|enable\|disable]	MCP 서버 연결·인증 관리
/resume	이전 대화로 복귀
/branch [이름]	현재 지점에서 대화 분기 후 이동 (원본 보존)
/fork [프롬프트]	대화를 복사해 백그라운드 세션으로. 나는 계속 작업
/background [프롬프트]	현재 세션을 백그라운드로 분리하고 터미널 반환. 별칭 `/bg`
/btw [질문]	히스토리에 남지 않는 사이드 질문 (작업 중에도 가능, 도구 사용 없음)
/tasks	현재 세션의 백그라운드 작업·서브에이전트 목록
/rewind	코드·대화를 체크포인트로 복원, 또는 일부 구간 요약
/doctor	설치·설정 체크업 + 수리 제안. 별칭 `/checkup`
/debug [설명]	이 세션의 디버그 로깅을 켜고 로그를 읽어 문제 분석
/usage	플랜 한도를 무엇이 소모하는지 분해. 별칭 `/cost`
/config [key=value]	설정 UI, 또는 값 직접 지정 `/config theme=dark`
/add-dir <경로> · /cd <경로>	작업 디렉터리 추가 / 세션 자체를 이동(캐시 유지)
/batch <지시>	대규모 변경을 5~30개 단위로 쪼개 worktree별 백그라운드 서브에이전트에게 분배
/loop [간격] [프롬프트]	프롬프트 주기 반복. 별칭 `/proactive`
/goal <조건>	조건이 충족될 때까지 턴을 이어가며 작업
/fewer-permission-prompts	트랜스크립트를 분석해 읽기 전용 명령 허용 목록 제안
/hooks · /plugin · /reload-skills	훅 확인 · 플러그인 관리 · 스킬 재스캔(재시작 없이)
/export [파일] · /copy [N]	대화 내보내기 · N번째 최신 응답 복사
/insights · /recap · /powerup	세션 패턴 리포트 · 한 줄 요약 · 기능 학습 레슨
/security-review	현재 diff의 보안 취약점 검사
/deep-research <질문>	웹 검색을 팬아웃해 교차 검증하고 인용이 붙은 리포트 합성
/help · /exit	도움말 · 종료(별칭 `/quit`)

중요 claude --help 는 모든 플래그를 보여주지 않습니다. 도움말에 없다고 해서 없는 옵션이 아닙니다. 정확한 최신 목록은 공식 CLI 레퍼런스를 보거나, 세션 안에서 그냥 Claude에게 물어보세요 — 자기 문서를 직접 읽어옵니다.

11프롬프트

같은 도구, 다른 결과

결과 차이의 대부분은
옵션이 아니라 문장에서 온다.

네 가지만 지키면 됩니다. 검증 수단을 준다 · 먼저 탐색시킨다 · 구체적으로 쓴다 · 일찍 끼어든다.

✕ 검증 수단이 없다

로그인 버그 고쳐줘

무엇이 "고쳐진 것"인지 판단할 방법이 없습니다. Claude는 그럴듯한 코드를 쓰고 끝냅니다.

✓ 성공 조건을 준다

로그인 실패 버그를 고쳐줘.
재현 방법: 만료된 토큰으로 앱 재시작.
./gradlew :app:testQaDebugUnitTest 가
통과할 때까지 반복해줘.

에이전트가 스스로 루프를 돌 수 있게 됩니다. 이게 가장 큰 차이를 만드는 한 가지입니다.

✕ 바로 구현시킨다

결제 모듈을 새 SDK로 마이그레이션해줘

코드베이스를 이해하기 전에 코드를 쓰기 시작합니다. 되돌리는 비용이 더 큽니다.

✓ 탐색 → 계획 → 구현

먼저 결제 관련 파일을 전부 찾아서
현재 흐름을 정리해줘. 아직 코드는 쓰지 마.
그다음 마이그레이션 계획을 단계별로 제시하고,
내가 승인하면 1단계만 구현해.

Shift+Tab → plan 모드가 이걸 강제해 주는 장치입니다.

✕ 모호한 지시

코드 좀 깔끔하게 정리해줘

"깔끔"의 정의가 없어서 취향에 따라 대규모 리팩터링이 시작될 수 있습니다.

✓ 범위와 기준 명시

@app/src/main/java/.../BuildManager.kt 만.
중복된 null 체크를 제거하고,
함수 하나가 40줄을 넘지 않게 쪼개줘.
public API 시그니처는 바꾸지 마.

"하지 말 것"을 적는 게 "할 것"보다 효과적인 경우가 많습니다.

잘 먹히는 문장 패턴

· "먼저 …를 조사하고, 코드는 아직 쓰지 마"
· "…가 통과할 때까지 반복해줘"
· "세 가지 방안을 장단점과 함께 제시하고 추천을 골라줘"
· "내가 뭘 놓쳤는지 반대 입장에서 검토해줘"
· "필요한 정보가 부족하면 질문부터 해줘"
· "ultrathink" — 이 턴만 깊게 생각시키기

역질문을 시키는 기법

요구사항이 스스로도 명확하지 않을 때, 사양을 쓰게 하지 말고 인터뷰를 시키세요.

"타요 체크 앱에 정산 기능을 붙이려고 해. 구현하기 전에, 결정해야 할 것들을 나한테 하나씩 질문해줘."

훨씬 빠르게 좋은 스펙에 도달합니다.

피해야 할 패턴

거대한 한 방 프롬프트. "앱 전체를 리팩터링하고 테스트도 다 짜고 문서도 만들어줘" 는 거의 항상 실패합니다. 컨텍스트가 터지고, 중간에 방향이 어긋나도 알아챌 지점이 없기 때문입니다. 쪼개고, 검증하고, 커밋하세요.

13막힐 때

증상 → 원인 → 조치

거의 다 이 중 하나다.

지시를 무시하는 것 같다 / CLAUDE.md 를 안 따른다

① CLAUDE.md가 너무 길면 지침이 묻힙니다 → /doctor 로 다이어트. ② /compact 이후 지침이 흐려졌을 수 있습니다 → /clear 후 새로 시작. ③ 정말 중요한 규칙이면 문장으로 다시 말하는 게 가장 확실합니다(사용자 프롬프트 > 스킬 > CLAUDE.md).

응답이 갑자기 나빠졌다

/context 를 먼저 보세요. 컨텍스트가 꽉 찼거나, MCP 서버가 절반을 먹고 있는 경우가 많습니다. 자동 폴백으로 다른 모델이 돌고 있을 수도 있으니 /model 로 현재 모델을 확인하세요. 커스터마이즈가 원인인지 갈라보려면 claude --safe-mode.

권한 팝업이 너무 많이 뜬다

/fewer-permission-prompts → 제안된 허용 목록을 프로젝트 설정에 반영. 긴 자율 작업은 auto 모드로. --dangerously-skip-permissions 는 격리 환경에서만.

비용·한도가 빨리 소모된다

/usage 로 무엇이 소모하는지 분해해 보세요(스킬·서브에이전트·플러그인·MCP별). 효과 큰 조치 순서: ① 안 쓰는 MCP 서버 끄기 ② CLAUDE.md 다이어트 ③ 작업 전환 시 /clear ④ 정형 작업은 낮은 effort·작은 모델 ⑤ 출력 많은 조사는 서브에이전트에 위임. 모델을 자주 바꾸면 프롬프트 캐시가 깨져 비용이 오릅니다.

파일을 고쳤다는데 실제로 안 바뀌었다 / 되돌리고 싶다

/diff 로 확인, /rewind 로 복원. 단 Bash로 실행한 변경, 서브에이전트 편집, 외부 변경은 체크포인트 대상이 아닙니다. 중요한 지점마다 커밋하는 게 여전히 최선입니다.

Windows에서 뭔가 이상하다

Git for Windows가 없으면 Bash 대신 PowerShell 도구로 동작합니다. Git Bash를 찾지 못하면 settings.json 의 env.CLAUDE_CODE_GIT_BASH_PATH 에 경로를 지정하세요. Linux 툴체인이나 샌드박싱이 필요하면 WSL 2 쪽이 낫습니다.

백그라운드 세션이 응답하지 않는다

claude daemon status 로 수퍼바이저 상태 확인 → claude daemon stop --any --keep-workers 로 재시작(세션은 유지). 바이너리를 업데이트했으면 claude respawn --all.

이 기능이 내 버전에 있는지 모르겠다

claude -v 로 버전 확인 → /release-notes 로 변경점 확인 → claude update. 그리고 가장 빠른 방법: 세션 안에서 Claude에게 직접 물어보세요. 자기 공식 문서를 읽어와서 답합니다.

Claude Code는 "채팅"이 아니라내 터미널에서 도는 에이전트다.