00. 시작하기 전에

첫 일주일 사이 사람들이 비슷한 지점에서 멈춥니다. 그 네 곳을 미리 짚어드립니다.

처음 Claude Code를 켜놓고 한참 멍했던 기억이 있습니다. 광고를 보고 깐 도구가 아니라, 비즈니스를 운영하다 보니 자연스럽게 흘러들어온 도구였습니다. 검은 화면을 띄워놓고 처음 든 생각은 셋이었습니다. 이걸 내 일에 어떻게 붙이지? 좋다고들 하는데 정말 내 생산성이 올라가나? 어디서부터 손대야 하지? 같은 자리에 멈춰 선 분이 적지 않을 거라 짐작합니다. 이 가이드는 그 막막함을 풀어보려고 적기 시작한 메모가 출발점입니다. 그래서 첫 일주일에 가장 자주 부딪히는 네 가지 질문부터 차례로 정리해보겠습니다.

Q1. Cowork와는 어떻게 다른가요?

같은 회사 제품이라 비슷해 보이지만, 두 도구는 쓰는 결이 정반대입니다. 한쪽은 무언가를 만드는 데, 다른 한쪽은 이미 있는 일을 처리하는 데 특화돼 있습니다.

쉽게 비교하자면 이렇습니다.

• Claude Code: 빈 폴더에서 시작해 앱·문서·자동화를 만들어냅니다. 비유하면 설계 도면을 들고 직접 짓는 건축 인력입니다. 텍스트 명령으로 파일을 직접 읽고 쓰며, 컴퓨터 전체에 자유롭게 접근합니다.
• Claude Cowork: 이미 있는 메일·문서·일정 같은 업무를 정리해 줍니다. 책상 옆에 앉은 비서에 가깝습니다. 격리된 가상 환경(샌드박스) 안에서 화면을 클릭하며 작업합니다.

왜 Cowork는 안전하지만 느릴까

Cowork의 격리 환경은 보안 측면에선 장점이지만, 작동 원리상 토큰과 시간 모두를 더 씁니다. 화면을 보고 → 스크린샷을 찍고 → AI가 이미지를 분석하고 → 클릭 위치를 계산하는 과정을 매번 반복해야 하기 때문입니다. 글자 한 줄이면 끝날 일을 그림으로 처리하는 셈이라, 같은 결과를 얻는 데 비용이 몇 배로 듭니다.

Claude Code는 그 단계를 건너뜁니다. 텍스트로 곧장 파일을 다루기 때문에 같은 작업이 더 적은 토큰으로, 훨씬 짧은 시간에 끝납니다. 그리고 결과물이 "사람이 봤다"가 아니라 "파일이 실제로 바뀌었다"라서 나중에 재현하거나 자동화로 잇기도 쉽습니다.

💡 두 도구를 함께 써본 결론: 받은 걸 처리할 땐 Cowork, 새로 만들 땐 Claude Code. 굳이 한쪽만 고를 필요는 없습니다. 도구상자 안에 둘 다 있다고 생각하세요.

Q2. 데스크톱 앱·VS Code 확장을 두고 굳이 터미널을 써야 할까요?

처음 데스크톱 앱이 나왔을 때 "이제 터미널 안 써도 되겠다" 싶었던 분들이 많습니다. 실제로 2026년 4월 시점에서 기능 차이는 거의 사라졌습니다. 그런데도 일주일쯤 진지하게 써본 사람들이 슬그머니 터미널로 돌아옵니다. 이유는 셋입니다.

이유 1: 동시에 여러 일을 시키는 흐름

가장 큰 차이는 병렬성입니다. 터미널 창을 네 개 띄워놓고 각각 다른 일을 맡겨보세요.

• 창 1 → 화면 디자인 손보기
• 창 2 → 백엔드 API 다듬기
• 창 3 → 테스트 자동 실행
• 창 4 → README·문서 정리

네 개의 Claude가 동시에 각자 일하는 동안, 사람은 결과를 받는 순서대로 다음 지시를 던지면 됩니다. tmux로 한 화면에 패널을 나누면 어느 창이 멈췄는지·어느 창이 결과를 뱉었는지 깜빡임만 봐도 알 수 있습니다. 데스크톱 앱에서도 세션을 여럿 띄울 순 있지만 한 화면에 늘어놓고 흐름을 한눈에 보는 건 터미널만 가능합니다.

이유 2: 터미널에서만 열리는 영역

GUI 환경에서는 구조적으로 닫혀 있는 영역이 있습니다.

• cat error.log | claude -p "원인 짚어줘" 처럼 다른 도구의 출력을 그대로 넘기는 파이프 연결
• cron으로 매일 아침 데이터를 자동 점검하는 정기 작업
• shell alias·함수와 자연스럽게 엮어 쓰는 스크립트화

처음엔 별 차이가 없어 보이지만, 반복 작업이 늘수록 GUI에선 길이 막힙니다.

이유 3: 안정성

기능은 평준화됐지만 안정성은 아직 차이가 보입니다.

차이는 좁혀지는 중이지만 지금 가장 안정적이고 가벼운 곳은 터미널입니다.

그래도 데스크톱부터 시작해도 괜찮은 경우

도구 선택보다 작업 흐름이 우선입니다. 부담이 적은 입구로 들어와서, 반복이 늘어날 때 터미널로 옮겨도 늦지 않습니다.

💡 자연어로 명령하면 되는 시대입니다. 터미널은 더 이상 개발자 전용이 아닙니다. 한 번만 그 문턱을 넘으면 다음 풍경이 달라집니다.

Q3. 설치는 했는데 무엇부터 해야 하나요?

질문을 그대로 받기보다, 한 번 뒤집어보겠습니다. "무엇부터 할까"가 아니라 "무엇을 만들고 싶은가"가 먼저입니다. 이 순서를 거꾸로 놓으면 어떤 튜토리얼을 따라가도 손에 남는 게 없습니다. 공식 예제로 To-Do 앱을 만들고 다 만든 직후 "이거 왜 만들었지?" 싶어 폴더째 지운 경험은 거의 모두가 공유합니다. 도구는 익혔는데 동기가 비어 있는 상태죠.

이 함정에서 빠져나오는 길은 두 가지입니다.

먼저, 남이 만든 결과물을 둘러보세요. SNS·유튜브·블로그에서 사례를 보다 보면 "이거 나도 해보고 싶다"는 장면이 반드시 한두 개 떠오릅니다. 그게 진짜 출발점입니다. 막연한 "공부해야지"가 아니라 구체적인 한 장면이 머릿속에 박히는 게 핵심입니다.

그다음, "만들어줘" 대신 "물어봐" 하세요. 어렴풋이 잡힌 아이디어를 곧장 명령으로 바꾸지 말고, 먼저 Claude에게 던져보세요.

"이런 걸 하고 싶은데, 어떤 방식이 가능해?"
"이 프로젝트를 시작하려면 뭐가 필요해?"
"비슷한 사례나 참고 구조가 있을까?"

Claude Code는 시킨 일만 처리하는 도구가 아니라 같이 생각하는 파트너에 가깝습니다. 대화하는 동안 가능과 불가능, 빠른 길과 우회로가 자연스럽게 보입니다. 첫 한두 시간을 "만들기"가 아니라 "묻기"에 쓰는 편이, 결과적으로 가장 빠른 입문 동선입니다.

설치·기본 명령어·CLAUDE.md 같은 기초 설정은 다음 섹션부터 차례로 다룹니다. 만들고 싶은 게 정해진 뒤에 읽어도 늦지 않습니다.

Q4. Pro 요금제($20)면 충분할까요?

짧게 답하면: 본격적으로 쓰실 거라면 충분하지 않습니다. 길게 풀면 다음과 같습니다.

Pro의 현실: 5시간 한도는 생각보다 빨리 찹니다

집중 모드에 들어가면 1시간 만에 한도에 도달하는 경우도 흔합니다. 한 번 막히면 그날 작업의 리듬 자체가 끊기고, 풀릴 때까지 기다리며 다른 일을 하다가 흐름을 잃기 쉽습니다. 게다가 Pro의 기본 모델은 Sonnet 4.6이고, 가장 강력한 Opus 4.7은 사실상 손이 닿지 않습니다: 한도가 너무 빨리 소진되기 때문입니다.

Max로 올라가면 Opus 4.7이 기본이고 1M 토큰 컨텍스트 창도 자동으로 따라옵니다. "한도가 무서워서 좋은 모델을 못 쓴다"는 상태에서 벗어나는 게 첫 번째 변화입니다.

Max를 적어도 한 달은 경험해보시길

Claude Code의 진짜 생산성은 긴 작업을 끊기지 않고 이어갈 때 드러납니다. 한 세션으로 충분하던 게 며칠 만에 부족해지고, 사용량 곡선이 가팔라지죠. 다음 세 가지가 같이 늘어나는 식입니다.

1. 파일과 맥락이 쌓이면서 한 번 호흡이 길어집니다
2. 만들고 → 확인하고 → 다시 고치는 사이클이 반복됩니다
3. 복잡한 설계나 디버깅에는 Opus 모델 손을 빌리고 싶어집니다

이 흐름이 보이기 시작하면 Pro의 5배 사용량이 들어 있는 Max $100이 현실적인 선택지입니다. 한 달만 써본 뒤 다시 Pro로 돌아갈지 결정해도 늦지 않습니다. "이게 이렇게까지 되는 거였어?" 라는 순간을 한 번 겪고 나면, 판단 기준이 분명해집니다.

어떤 플랜을 고를까

⚠️ Pro는 "체험판"이라고 생각하시면 마음이 편합니다. 잠재력 확인에는 충분해도, 실제로 생산성을 뽑아내려면 Max 영역에 들어가야 길이 보입니다. 한 달을 더 망설일 시간에 한 달을 Max로 돌려보면, 답이 그 안에 들어 있습니다.

01. Claude Code란?

내 컴퓨터 안의 파일을 직접 읽고 정리해 결과물을 남겨두는 AI 에이전트입니다. 코딩을 몰라도 됩니다.

출처: Claude Code overview — Anthropic 공식 문서

🌀 요즘 왜 Claude Code 얘기가 다시 늘었을까? 2025년 후반부터 코딩 보조 도구의 무게중심이 "자동완성"에서 "위임"으로 옮겨갔습니다. 줄을 채워주는 코파일럿형 도구와 달리, Claude Code는 작업을 통째로 맡기는 방식입니다. "터미널 하나로 PR을 만든다"는 한국 개발자 후기가 늘면서, 비개발 직군(마케터·기획자·연구자)까지 손을 대는 분위기가 빠르게 퍼지고 있습니다.

30초 요약

가장 짧게 말하면 이렇습니다. Claude Code는 내 폴더에 들어와 일하는 AI입니다. 파일 수십 개를 한 번에 펼쳐 보고, 추려 낸 결과를 새 파일로 저장해 둡니다. 브라우저 안의 Claude.ai가 "대화하는 AI"라면, Claude Code는 내 디스크 위에서 손을 움직이는 AI에 가깝습니다.

Claude.ai와는 어떻게 다른가요?

대화창에서 답을 받느냐, 폴더에 결과를 받느냐: 이 한 줄이 가장 큰 차이입니다. 항목별로 풀어보면 이렇습니다.

• 파일 접근: Claude.ai는 한 번에 한두 개씩 직접 올려야 합니다. Claude Code는 폴더 통째로 자동으로 읽습니다.
• 작업 범위: 전자는 한 대화 분량. 후자는 수십~수백 개 파일을 동시에 다룹니다.
• 결과물 저장: 전자는 복사·붙여넣기로 옮겨야 하고, 후자는 자동으로 파일을 만들거나 고쳐 둡니다.
• 반복 작업: 전자는 매번 새로 지시. 후자는 한 번 일러두면 같은 패턴을 알아서 반복합니다.
• 장기 기억: 전자는 대화창 안에서만 유효. 후자는 CLAUDE.md라는 파일에 내 규칙을 영구 저장합니다.

실제로 어떻게 일하나: 세 장면

세 가지 직군에서 자주 나오는 시나리오를 가져왔습니다. 셋 모두 "이렇게 해줘"라는 한 문장이 시작점입니다.

장면 1 · 부동산 시장 자료 정리 (애널리스트)

data/ 폴더에 있는 분기별 매매 통계 PDF 12개를 읽고,
지역구별 평균 거래가와 전년 대비 증감률을 묶어
quarterly_brief.md 파일로 정리해줘.

→ Claude Code가 PDF 12개를 차례로 읽어 표를 추출하고, 한 파일로 모아 자동 저장합니다.

장면 2 · 주가 데이터 요약 (개인 투자자)

trades/ 폴더의 CSV 거래 내역을 보고
종목별 실현 손익과 보유 기간을 표로 정리해줘.
파이썬 코드도 같이 남겨주면 좋겠어.

→ 코드를 직접 짜지 않아도 됩니다. 결과 표와 재실행용 스크립트가 함께 만들어집니다.

장면 3 · 코드 디버깅 (개발자)

테스트가 빨갛게 뜨는데 원인 찾아서 고쳐줘.

→ 테스트 실행 → 실패 위치 파악 → 코드 수정 → 다시 실행. 사람이 하던 루프를 그대로 이어 받습니다.

잘 맞는 사용자상

다음 세 가지 부류의 사람들에게 특히 효과가 큽니다.

1. 반복적인 파일·문서 작업이 많은 사람: 주간 보고서 양식 통일, 대량 파일 이름 변경, 폴더 구조 정리.
2. 방대한 자료를 자주 다루는 사람: 논문 20편 요약, 경쟁사 웹페이지 일괄 수집·정리.
3. 아이디어를 실물로 빠르게 만들어보고 싶은 사람: 코딩 없이 작은 웹사이트·대시보드·자동화 도구 시도.

이런 메시지가 익숙한 분도 환영입니다.

• "파이썬·엑셀 함수 없이 데이터를 정리하고 싶다"
• "문서 수십 개를 일일이 안 열고 처리하고 싶다"
• 터미널이 낯설어도 괜찮습니다: 데스크톱 앱으로도 충분히 시작할 수 있습니다.

반대로 다음 경우라면 굳이 Claude Code를 고집할 필요는 없습니다.

• 단순 글쓰기·번역·일회성 답변이면 → Claude.ai 웹이 더 가볍습니다.
• 특정 IDE 안에서만 일하는 개발자라면 → Cursor·VS Code 확장을 먼저 검토해보세요.

어디서 돌릴 수 있나요?

같은 엔진을 공유하므로 어디서 시작하든 같은 결과를 얻을 수 있습니다. 다만 자동화·병렬 세션·셸 통합 같은 깊은 기능은 터미널에서 가장 매끄럽게 동작합니다.

5분 체험: 폴더 하나 맡겨보기

말로만 들으면 감이 안 잡힙니다. 작은 폴더 하나를 던져보는 것이 가장 빠른 길입니다. 코드 프로젝트가 아니어도 됩니다.

mkdir -p ~/Desktop/claude-test
cd ~/Desktop/claude-test
claude

Claude Code가 열리면 이렇게 입력해보세요.

이 폴더에 샘플 회의록 파일 3개를 만들고,
각 파일의 결정사항만 모아 summary.md로 정리해줘.
작업이 끝나면 어떤 파일을 만들었는지도 알려줘.

이 실습에서 다음을 직접 확인하실 수 있습니다.

• 현재 폴더를 기준으로 파일을 만들고 고치는 흐름
• 결과를 대화창이 아니라 실제 파일에 남기는 방식
• 마음에 안 들면 곧장 이어서 수정 지시할 수 있는 자유도

summary.md의 문체를 더 간결하게 바꾸고,
끝에 액션아이템 표를 한 칸 추가해줘.

말로 시키고 → 파일이 바뀌고 → 결과를 보고 → 다시 시키는 루프. 이 작은 사이클이 Claude Code의 본질입니다. 코딩이든, 문서 작업이든, 데이터 정리든 모두 같은 패턴으로 흘러갑니다.

한 줄로 마무리

Claude Code = "내 폴더 안에 들어와 파일을 읽고, 정리하고, 결과물을 남겨두는 AI"

코딩을 익힐 필요 없습니다. 파이썬을 몰라도 됩니다. 하고 싶은 일을 말로 설명하시면 됩니다. 다음 섹션에서는 어떤 일들을 시킬 수 있는지를 직군별 사례로 더 들여다봅니다.

02. Claude Code로 할 수 있는 것들

이름엔 "Code"가 붙어 있지만, 손에 쥐어보면 코딩에만 쓰이는 도구가 아닙니다. 터미널 위에서 돌아가는 범용 AI 에이전트라고 보는 편이 정확합니다.

Claude.ai와 비교: 한 줄로 압축하면

대화 상대인지, 같이 일하는 동료인지: 이 한 줄이 둘의 차이를 가장 잘 설명합니다. 풀어보면 다섯 가지 항목에서 갈라집니다.

• 파일 접근: 첨부 한 건 vs 폴더 통째 읽기·수정
• 작업 범위: 대화 한 차례 vs 수십 개 파일 동시
• 외부 실행: 불가 vs 터미널 명령 직접
• 반복 자동화: 수동 vs Skills·Hooks로 자동
• 장기 기억: 대화 안에서만 vs CLAUDE.md에 영구 저장

핵심 차이를 한 문장으로 옮기면: Claude.ai는 대화 상대, Claude Code는 옆자리에서 같이 일하는 AI 동료입니다.

코딩 영역에서 할 수 있는 일

익숙한 작업을 자연어로

작성·수정·리팩토링·테스트·리뷰. 개발자가 매일 하는 동작 거의 전부를 한국어 한 문장으로 지시할 수 있습니다. 한 줄짜리 커밋 메시지부터 수십 파일에 걸친 구조 변경까지, 단위만 다를 뿐 흐름은 같습니다.

바이브코딩: "분위기"로 코드를 만들기

Andrej Karpathy가 2025년에 이름 붙인 개념입니다. 코드를 직접 치지 않고 자연어로 묘사해 소프트웨어를 만드는 방식입니다. 개발자와 바이브코더의 차이를 표 대신 흐름으로 적어보면 이렇습니다.

• 개발자는 코드를 직접 쓰고, 에러 메시지를 분석해 고칩니다. 바이브코더는 "이거 에러 나는데 고쳐줘"로 끝냅니다.
• 개발자의 핵심 역할은 구현, 바이브코더는 기획과 검수입니다.
• 개발자는 프로그래밍 언어를 익혀야 하고, 바이브코더는 요구사항을 명확하게 전달하는 능력이 자산입니다.

이 방식으로 실제 만들 수 있는 것: 프로토타입, MVP, 개인 도구, 작은 웹사이트, 데이터 자동화. 이 가이드 사이트도 그 흐름으로 만들었습니다.

⚠️ 한계도 솔직히: 대규모 상용 서비스, 결제·인증 같은 민감한 영역은 반드시 전문 개발자의 검수가 필요합니다. 바이브코딩으로 첫 버전을 빨리 띄우되, 트래픽이 붙기 시작하면 사람과 같이 가는 게 안전합니다.

더 잘 굴리는 네 가지 습관

1. 기획에 절반의 무게를 두세요. "앱 만들어줘"보다 "사진을 날짜별로 정리해 주는 웹앱 만들어줘"가 훨씬 좋은 결과를 냅니다.
2. 작게 시작해 키우세요. 한 번에 완성품을 요구하지 말고, "로그인 화면 먼저 → 다음은 목록 화면" 식으로 쌓으세요.
3. 결과를 직접 굴려보세요. AI가 만든 코드는 반드시 한 번 실행해보고 넘어가세요.
4. 되돌릴 수 있는 길을 항상 열어두세요. Git 커밋만 잘 찍어두면 어떤 시도도 손쉽게 원복할 수 있습니다.

코딩 너머에서 할 수 있는 일: 직군별 시나리오

여기부터가 진짜입니다. 비개발자에게 더 효과가 큰 영역입니다. 6개 묶음으로 나눠보겠습니다.

리서치 & 분석

• 여러 웹페이지를 동시에 읽고 마크다운으로 정리
• 경쟁사 분석, 시장 조사, 기술 동향 파악
• PDF 논문·보고서 수십 개 일괄 요약

이 폴더의 자료를 읽고 핵심 주장·근거·반대 근거를 표로 정리해줘.
출처 파일명도 같이 표시하고, 불확실한 내용은 "추정"으로 표시해줘.

💡 멀티에이전트 리서치 구조를 쓰면 여러 출처를 병렬로 조사해 종합 보고서까지 자동으로 만들어집니다.

문서 & 콘텐츠 제작

• 블로그, 뉴스레터, SNS 글 초안
• 제안서, 보고서, 발표 자료
• 한↔영 번역과 자동 저장

draft.md를 블로그 글로 다듬어줘.
제목 3개 후보, 도입부, 본문 소제목, 마지막 요약까지 포함해줘.
과장된 표현은 줄이고 실무자가 바로 이해하는 톤으로.

데이터 처리

• CSV·Excel 분석과 변환: 파이썬은 옵션입니다
• 파일 수백 개 일괄 처리(이름 변경, 형식 변환, 폴더 통일)
• JSON·XML 파싱과 가공

@sales.csv를 분석해서 월별 매출·상위 5개 상품·이상치 행을 찾아줘.
analysis.md로 저장하고, 어떤 기준으로 골랐는지도 같이 설명해줘.

학습 보조

• 강의 자료·책 내용 구조화
• 퀴즈, 플래시카드 자동 생성
• 개념 설명 + 비유 + 연습 문제 묶음

@lecture.pdf를 초보자용 학습 노트로 바꿔줘.
핵심 개념, 쉬운 비유, 확인 문제 10개, 오답 해설까지 넣어줘.

비즈니스 워크플로우

• 미팅 녹취 → 요약·결정사항·담당자별 액션 아이템
• 주간·월간 보고서 자동화
• 이메일 초안, 고객 응대 템플릿

meetings/ 폴더에 들어 있는 이번 주 회의록을 읽고
결정사항·담당자별 액션 아이템·다음 주 리스크를 weekly-report.md로 모아줘.

개인 AI 워크스페이스

CLAUDE.md에 역할과 규칙을 적어두면 단순 AI 채팅이 아니라 내 작업 방식에 맞춰 길든 에이전트 시스템이 됩니다. 자세한 설계는 나만의 AI 워크스페이스 섹션에서 다룹니다.

실전 케이스: 이 가이드는 어떻게 만들어졌나

코드를 한 줄도 직접 치지 않았습니다.

흐름을 단계별로 보면 이렇습니다.

1. 기획: "한국어 Claude Code 입문 가이드를 만들고 싶다"는 한 문장에서 출발. 아이디에이션 워크스페이스에서 섹션 구성·UX·기술 스택을 정리한 뒤 전체 구조를 결정.
2. 콘텐츠 제작: 공식 문서를 모아 Claude가 핵심을 뽑고, 한·영 마크다운으로 구조화.
3. 개발: Next.js 사이트 코드 전부를 Claude Code가 작성. 다크/라이트 모드, 한영 토글, 모바일 대응까지 대화만으로.
4. 배포: Vercel 배포, Cloudflare DNS 연결, 도메인 매핑 모두 Claude Code가 직접.
5. 운영·보완: 초안 뒤로는 "이 부분 추가", "이건 다르게" 같은 짧은 지시만으로 지속 개선. 지금 이 글을 다듬는 작업도 같은 흐름의 연장선입니다.

비개발자 시나리오: 시간 기준 비교

상황: 매주 팀 미팅 후 회의록을 정리해야 한다

기존 방식:
  미팅 종료 → 메모 정리 30분 → 이메일 작성 10분 → 공유
  총 소요: 약 40분

Claude Code 방식:
  미팅 녹취 텍스트 붙여넣기
  → "요약·결정사항·담당자별 액션 아이템 정리해줘"
  → 마크다운 파일 저장 + 이메일 초안 자동 생성
  총 소요: 약 3분

다시 한 번 줄이면: Claude Code는 코딩 도구라기보다 "내 컴퓨터를 다룰 줄 아는 범용 AI 에이전트"에 가깝습니다. 코딩은 그 위에서 할 수 있는 일 중 하나일 뿐입니다.

03. 요금제 안내

Claude Code는 유료 구독 안에서 동작합니다(Free 플랜에는 들어 있지 않습니다). 일주일만 진지하게 써보시면 답이 보이는데, 결론부터 말씀드리면: 본격적으로 쓰실 거라면 Max (5x)가 가장 무난합니다.

출처: Anthropic 가격 페이지

어디서 시작할까: 한 줄 가이드

먼저 결론부터 보여드리겠습니다. 자세한 비교는 그 아래에서 풉니다.

플랜별 차이를 한눈에

가격은 자주 바뀝니다. 정확한 숫자는 claude.com/pricing을 확인하세요. 아래 표는 비교용 스냅샷입니다.

💡 1M 컨텍스트 켜는 법: /model opus[1m] 또는 /model sonnet[1m]. Max·Team·Enterprise는 Opus 1M이 자동으로 들어가지만, Sonnet 1M은 모든 플랜에서 추가 사용량으로 청구됩니다.

왜 Max (5x)인가: 솔직한 이유 셋

1. Pro의 5시간 한도는 생각보다 빠르게 찹니다. 집중 작업이면 1시간에 도달하기도 해서, 막히면 그날 흐름 자체가 끊깁니다.
2. Pro에서 Opus 4.7을 쓰는 건 이론상 가능, 현실적으론 어렵습니다. 한도가 너무 빨리 빠지기 때문입니다. Max로 가면 Opus가 기본입니다.
3. 긴 대화·여러 파일·반복 수정이 쌓이면 토큰이 빠르게 누적됩니다. Max (5x)가 대부분 개인 사용자에게 충분한 여유를 줍니다.

그래도 Pro로 시작해도 되는 경우

Pro가 무조건 나쁘다는 얘기는 아닙니다. 아래에 가까우면 Pro로 시작해서 감을 잡으셔도 충분합니다.

• 하루 10~20분 정도 명령어와 흐름만 익혀보고 싶다
• 작은 문서 정리, README 수정, 단편적인 질문이 주된 용도다
• 한 번에 한 파일만 만지작거리는 가벼운 작업이 대부분이다

반대로 다음 패턴이라면 Pro로는 곧 답답해집니다.

• 한 호흡에 여러 시간을 이어가는 개발·리서치·자동화
• Opus 모델로 복잡한 설계·디버깅을 길게 끌고 가야 함
• 여러 파일·전체 코드베이스를 매일 읽어 들이는 흐름

"Max로 올라갈 때가 됐다"는 신호

다음 항목 중 두 가지 이상이 본인 얘기 같다면, 플랜 비용보다 중단 비용이 더 클 수 있습니다.

□ 하루에 Claude Code 사용 시간이 1시간을 넘어간다
□ "한도 때문에 멈춤" 메시지를 이미 본 적이 있다
□ 긴 문서·여러 파일·코드베이스 전체를 자주 읽힌다
□ Opus가 필요한 작업(아키텍처 설계, 어려운 디버깅)이 있다
□ 한 작업을 만들고 → 검증하고 → 다시 고치는 사이클이 잦다
□ MCP·자동화를 실제 업무에 끼우기 시작했다

Claude Code는 몰아서 깊게 쓸수록 생산성이 나오는 도구입니다. 사용량 여유가 곧 결과물 품질에 직접 영향을 주는 셈입니다.

비용 구조: 큰 그림

월정액 결제 → 한도 안에서 자유 사용
한도 초과    → 추가 응답 제한 (별도 과금 없음)

• 토큰을 일일이 셀 필요는 없습니다. 한도는 5시간 윈도우와 주간 윈도우 두 가지로 운영됩니다.
• /usage로 세션 비용·플랜 한도·활동 통계를 한 번에 봅니다 (/cost·/stats는 같은 명령의 alias).
• Max에서 Opus 사용량이 임계를 넘으면 자동으로 Sonnet으로 전환돼 작업이 끊기지 않습니다.

한도에 걸렸을 때: 업그레이드 전에 체크할 다섯 가지

플랜을 올리기 전에 작업 습관을 먼저 살펴보세요. 다음 흐름이 종종 답이 됩니다.

1. /compact로 현재 세션을 압축한다
2. 무관한 작업이면 /clear로 새 세션을 시작한다
3. 단순 작업은 /model로 Sonnet·Haiku에 맡긴다
4. 폴더 전체 대신 필요한 파일만 @파일명으로 지정한다
5. 반복 작업은 Skills로 묶어 프롬프트 낭비를 줄인다

그래도 같은 벽에 자주 부딪히면 그때 Max (5x)로 옮기는 편이 깔끔합니다.

토큰을 아끼는 네 가지 작은 습관

• 작업 사이마다 /clear: 이전 컨텍스트를 지워 들고 다닐 짐을 줄입니다.
• Sonnet 우선: 대부분 작업에 충분하고 Opus보다 가볍습니다.
• 요청을 좁히기: "코드베이스 전체 개선" 대신 파일·함수 단위로 콕 짚어주세요.
• MCP 정리: 안 쓰는 외부 연결은 꺼두는 게 좋습니다.

03과 20의 역할 분담

이 섹션은 "무엇을 살까"를 다룹니다. 실제로 쓰면서 토큰을 줄이는 운영법(CLAUDE.md 다이어트, permissions.deny 룰, 컨텍스트 압축)은 20. 비용 관리 & 절약 팁에서 깊이 다룹니다. 두 섹션을 짝지어 보시면 비용 곡선이 눈에 띄게 완만해집니다.

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

04. 설치 & 인증

명령어 한 줄을 붙여넣고, 브라우저 한 번 클릭하면 끝납니다. 부담스러워 보이는 건 처음 한 번뿐입니다.

출처: Set up Claude Code — Anthropic 공식 문서

💡 터미널이 처음이라도 괜찮습니다. 아래 명령어를 그대로 복사(Cmd+C/Ctrl+C)해서 붙여넣고(Cmd+V/Ctrl+V) Enter만 누르세요. 어떤 의미인지 지금 다 알 필요는 없습니다.

• macOS: Cmd+Space → "terminal" 입력 → Enter
• Windows: Win+R → "powershell" 입력 → Enter

시작 전 환경 점검

어떤 OS에서 돌까요?

하드웨어는 무엇이 필요한가요

• RAM 4GB 이상이면 충분합니다
• 인터넷 연결 필수

Node.js를 따로 깔아야 하나요?

아닙니다. Claude Code는 네이티브 인스톨러를 쓰기 때문에 Node.js 의존성이 없습니다. 예전에 보던 npm install -g 방식도 동작은 하지만(특히 sudo를 붙이는 경우)권한 문제로 권장되지 않습니다. 가급적 아래 네이티브 명령으로 시작하세요.

OS별 설치 방법

macOS · Linux · WSL에서

가장 간단한 방법은 한 줄짜리 인스톨러입니다.

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

평소 Homebrew를 쓰고 계시다면 이쪽도 가능합니다.

brew install --cask claude-code

Windows에서: 네 가지 입구

윈도우 사용자는 골라잡을 수 있는 길이 여러 개입니다. 어느 쪽이든 마지막 결과는 같습니다.

입구 ① · WSL을 깔고 Linux처럼 (추천)

기능이 가장 매끄럽게 동작합니다. 처음 설정에 한 단계 더 들 뿐입니다.

# PowerShell을 관리자 권한으로 열고
wsl --install

재부팅 뒤 Ubuntu가 자동으로 잡힙니다. Ubuntu 터미널에서 위쪽 Linux 명령을 그대로 쓰세요.

입구 ② · PowerShell 직접 설치

WSL 없이 즉시 시작할 수 있지만 일부 기능이 제한될 수 있습니다.

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

입구 ③ · CMD에서

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

입구 ④ · WinGet

winget install Anthropic.ClaudeCode

Windows 로컬 세션을 쓰려면 Git for Windows가 깔려 있어야 합니다.

WSL과 PowerShell 사이에서 망설인다면

처음부터 코드 작업이 많을 거라면 WSL, "Downloads 폴더 정리" 같은 가벼운 흐름으로 감을 잡고 싶다면 PowerShell: 이 정도 기준으로 충분합니다.

Linux 패키지 매니저 (apt · dnf · apk)

배포판 저장소에서도 받을 수 있습니다. 키 등록 등 자세한 단계는 공식 setup 가이드를 참고하세요.

# Debian · Ubuntu
sudo apt install claude-code

# Fedora · RHEL
sudo dnf install claude-code

# Alpine
apk add claude-code

⚠️ 패키지 매니저로 설치한 버전은 자동 업데이트되지 않습니다. sudo apt upgrade claude-code 같은 명령으로 직접 갱신하세요.

Alpine Linux 추가 패키지

네이티브 인스톨러를 쓰면 다음 라이브러리들이 같이 필요합니다.

apk add libgcc libstdc++ ripgrep

로그인: 설치 직후 한 번이면 됩니다

설치가 끝났다면 곧장 실행하세요.

claude

처음 실행 시 브라우저가 저절로 열리고 OAuth 로그인 페이지가 뜹니다. Pro·Max·Team·Enterprise 구독 중인 Claude.ai 계정으로, 또는 Anthropic Console 계정으로 로그인하면 됩니다(Free 플랜은 Claude Code를 지원하지 않습니다). 일부 환경에서는 Bedrock·Vertex·Foundry 같은 외부 제공자도 사용할 수 있습니다.

인증 흐름을 그림으로

자격 증명은 어디에 보관되나요

• macOS: API 키와 OAuth 토큰은 시스템 키체인(암호화 저장소)에 들어갑니다
• 다른 OS: 사용자 디렉터리 내 보호된 위치에 저장됩니다
• 다시 로그인하려면 claude 실행 후 /login

첫 실행이 잘 됐는지 확인하기

claude --version

버전 번호가 떠오르면 정상입니다. 더 자세한 진단은 다음 명령으로: 설치 타입·버전·환경 상태를 한 번에 보여줍니다.

claude doctor

업데이트는 어떻게 처리되나

네이티브 인스톨러로 깔았다면 시작 시점에 새 버전을 백그라운드로 받아서 다음 실행 때 자동 적용합니다. Homebrew·WinGet·apt·dnf·apk로 설치한 버전은 자동 업데이트되지 않으므로 직접 갱신해야 해요.

claude update              # 네이티브 인스톨러
brew upgrade claude-code   # Homebrew
winget upgrade Anthropic.ClaudeCode  # WinGet

처음 만나는 벽: 자주 쓰이는 세 가지 트러블슈팅

사례 ① · curl: command not found

curl 자체가 시스템에 없어서 인스톨러 한 줄이 동작하지 않는 경우입니다(요즘은 드물지만 일부 미니멀한 Linux에서 발생).

# Ubuntu / Debian
sudo apt-get install curl

# Alpine
apk add curl

curl을 깐 뒤 위쪽 인스톨러 명령을 다시 실행하세요.

사례 ② · claude: command not found

설치는 됐는데 셸이 실행 파일 위치를 못 찾는 상황입니다. PATH 등록 문제입니다.

# 현재 셸에 PATH 즉시 반영
source ~/.bashrc          # bash
source ~/.zshrc           # zsh

그래도 안 보이면 터미널 창을 완전히 닫고 새로 여세요. 신규 PATH는 새 셸에서 반영됩니다.

사례 ③ · Windows에서 "Git이 없습니다" 메시지

Windows 로컬 세션은 Git에 의존하는 부분이 있습니다. git-scm.com에서 Git for Windows를 설치하고 다시 시도하세요.

설치가 끝났다면

남은 건 폴더 하나를 골라 들어가는 일입니다.

# 작업할 폴더로 이동 후 실행
claude

코드 프로젝트만 가능한 게 아닙니다. 문서·리서치·업무 자료: 어떤 폴더든 시작 지점이 될 수 있습니다. Claude Code가 폴더를 한 번 훑어보고 다음 지시를 기다립니다.

05. 초보자 워크플로우

Claude Code를 처음 켜놓고 무엇부터 칠지 막막했던 경험은 거의 다들 공유합니다. 한 시간만 같이 따라가보면, 다음부터는 손이 알아서 움직입니다.

한눈에 보면 위의 여섯 박자입니다. 처음이라면 그대로 따라 해보시고, 익숙해지면 자기 호흡대로 늘이거나 줄이세요.

첫 세션: 여섯 박자로 흘러가는 흐름

처음이라면 아래 순서를 그대로 한 번 따라 해보세요. 한 박자씩 짧게 끊어 적었습니다.

① 작업할 폴더로 들어가기

# 예시: 바탕화면의 my-project 폴더로 이동
cd ~/Desktop/my-project

Claude Code는 현재 폴더를 기준으로 파일을 읽고 씁니다. 어느 폴더에서 켜느냐가 곧 그날 작업 범위가 됩니다. 폴더가 아직 없다면 mkdir로 만들고 cd로 들어가도 됩니다.

② Claude Code 실행

claude

claude를 입력하고 Enter. 대화형 모드가 뜨면 준비 끝입니다.

③ 프로젝트를 한 번 훑게 하기

처음 들어간 폴더라면 먼저 폴더 구조부터 파악시키는 게 시간을 절반으로 줄입니다. CLAUDE.md를 같이 만들어 두면 이후 작업에서 매번 같은 설명을 반복할 필요가 없습니다.

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

이미 진행 중인 프로젝트라면 이렇게 짧게 시작해도 좋습니다.

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

💡 CLAUDE.md는 프로젝트의 규칙·기술 스택·주의사항을 적어두는 메모장입니다. git에 커밋해두면 팀원이나 미래의 자신이 같은 맥락에서 시작할 수 있습니다.

④ 일을 시키기

원하는 작업을 자연어로 말하시면 됩니다.

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

⑤ 결과 보고 피드백하기

Claude가 파일을 고치면 변경 내용을 보여줍니다. 마음에 안 드는 부분이 있으면 곧장 이어서 말하세요.

> 좋은데, 에러 메시지는 한국어로 바꿔줘
> 이 부분은 다른 방식으로 가보자 — [이유 설명]

⑥ 세션 마무리

> /quit

Ctrl+D도 같은 동작입니다.

좋은 프롬프트의 다섯 가지 습관

습관 ①: 모호한 표현을 좁혀 쓰세요

같은 요청도 디테일이 더해지면 결과 품질이 확연히 달라집니다. 모호한 쪽 vs 좁힌 쪽을 짝지어 보면 이렇습니다.

• "코드 고쳐줘" → "login.js 42번 줄에서 발생하는 TypeError 고쳐줘"
• "기능 추가해줘" → "비밀번호 분실 시 이메일로 재설정 링크를 보내는 기능 추가해줘"
• "더 좋게 만들어줘" → "이 함수, 1000건에서 3초 걸리는데 1초 이내로 줄여줘"
• "테스트 만들어줘" → "auth.js의 login에 단위 테스트. 성공·실패·이메일 형식 오류 케이스 포함"

핵심은 "무엇을 어디서 어떻게" 세 가지를 한 문장에 같이 넣는 것입니다.

습관 ②: 한 호흡에는 한 가지 일만

여러 가지를 한 번에 던지면 Claude도 사람처럼 우선순위를 잃습니다.

# 손이 미끄러지는 흐름
> 로그인 만들고, 회원가입도 추가하고, 비밀번호 찾기도 만들고,
  이메일 인증도 넣고, 소셜 로그인도 추가해줘

# 결과가 깔끔한 흐름
> 먼저 이메일·비밀번호 로그인 기능만 만들어줘
(완료 확인 후)
> 이제 회원가입 기능을 이어서 추가해줘

습관 ③: 결과물의 형태를 미리 일러주기

같은 질문도 어떤 형태로 받고 싶은지에 따라 답이 달라집니다.

> 이 코드를 설명해줘           → 텍스트 설명
> 이 코드를 파일로 저장해줘     → 파일 작성
> 이 코드를 개선해서 덮어써줘   → 파일 직접 수정
> 버그를 표로 정리해줘          → 표 형식

습관 ④: @로 파일을 직접 던지기

@ 뒤에 파일 경로를 붙이면 Claude가 그 파일을 곧장 읽습니다. "이 파일 한 번 봐줘"라고 풀어 쓰는 단계를 건너뛸 수 있습니다.

> @회의록.txt 에서 액션아이템만 뽑아줘
> @계약서.pdf 핵심 조항만 정리해줘
> @시세.csv 분석해서 인사이트 3개 뽑아줘
> @src/auth/login.js 이 파일에서 버그 찾아줘
> @README.md 보고 프로젝트 구조를 파악해줘

폴더째 던질 수도 있습니다.

> @docs/ 이 폴더 문서 모두 읽고 목차 만들어줘
> @reports/2026/ 월별 보고서 비교해서 트렌드 분석해줘

💡 대화창에서 @를 입력하면 자동완성이 뜹니다. 한글 파일명도 그대로 됩니다.

습관 ⑤: 막히면 전제부터 다시 묻기

기대했던 결과가 안 나올 때, 같은 프롬프트를 반복하지 마시고 "내가 가진 가정을 다시 살펴봐 줘"라고 한 번 던져보세요. 종종 진짜 원인이 거기서 드러납니다.

도메인별 실전 시나리오

문서·업무

> @회의록-260225.txt
  오늘 회의 요약과 담당자별 액션 아이템을 표로 정리해줘

> @보고서초안.docx
  논리 흐름 점검해줘. 데이터가 필요한데 빠진 부분도 표시해줘

> ~/Downloads/meeting-260225.mp3 파일이 있어.
  음성을 텍스트로 변환하고 요약해줘

Claude Code가 STT에 필요한 도구를 직접 깔고 실행합니다. 파이썬 라이브러리를 미리 알아둘 필요는 없습니다.

데이터·분석 (부동산·시장 도메인 예시)

> @apt-prices-2026Q1.csv
  서울 25개 자치구의 평균 매매가와 전년 대비 증감률 표로 정리해줘.
  상승률 상위 5개 구는 따로 강조해줘.

> @경쟁사A.html @경쟁사B.html @경쟁사C.html
  세 곳 랜딩페이지의 강점·약점을 표로 비교해줘. 디자인 톤도 같이.

개발

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

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

> @src/payment/ 폴더 코드를 리뷰해줘.
  보안 취약점·개선 포인트를 함께 알려줘.

Plan Mode: 위험한 작업 직전의 안전벨트

Plan Mode는 Claude가 파일을 건드리지 않고 계획만 세우는 모드입니다. 큰 변경을 시작하기 전에 그림을 한 번 보고 결정할 수 있습니다.

켜는 방법

Shift+Tab 두 번    또는    > /plan

언제 켜는 게 이득일까

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

한 번 따라 해보기

# 처음부터 Plan Mode로 들어가기
claude --permission-mode plan

# 또는 진행 중에 전환
> Shift+Tab (두 번)

# 계획 받기
> 인증 시스템을 JWT에서 OAuth2로 옮기는 계획을 세워줘

# 계획이 마음에 들면 일반 모드로 전환 후 실행

⚠️ 처음 만나는 위험들: 네 가지

민감 정보를 대화창에 넣지 마세요

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

API 키·비밀번호·개인 인증서는 환경변수나 .env로 분리하시고, 대화창에 직접 입력하지 마세요.

권한 요청을 무심코 허용하지 마세요

sudo나 시스템 파일 수정 권한을 Claude가 요청하면: 이유부터 물어보는 습관이 안전합니다.

> 왜 sudo가 필요해? 다른 방법은 없어?

--dangerously-skip-permissions는 격리 환경에서만

이 옵션은 모든 권한 확인을 건너뜁니다. 컨테이너 같은 격리 환경 밖에서는 쓰지 마세요.

큰 변경 전에는 반드시 git 커밋

리팩토링·마이그레이션 전에 한 번 커밋해두는 작은 습관이, 며칠치 작업을 살리는 보험이 됩니다.

세션을 잘 정리하는 작은 기술들

긴 작업에는 이름을 붙이세요

> /rename housing-price-analysis

나중에 이어할 때:

claude --resume housing-price-analysis

호흡이 길어지면 압축을

응답이 느려지는 신호입니다. 주기적으로 한 번씩 눌러주세요.

> /compact

무관한 새 작업은 초기화부터

> /clear

첫날 15분 루틴: "감각"만 익히면 충분합니다

처음이라면 결과물 완성도보다 흐름의 결을 익히는 게 먼저입니다.

1분  작업 폴더 만들기
3분  claude 실행 후 폴더 구조 설명 요청
4분  샘플 파일 하나 만들고 수정 요청
3분  마음에 안 드는 부분 피드백
2분  /compact, /clear, /quit 차례로 한 번씩
2분  오늘 배운 명령을 CLAUDE.md에 기록

실제로 던질 한 줄:

이 폴더를 연습용 워크스페이스로 쓸 거야.
샘플 회의록 파일 하나를 만들고, 요약된 summary.md도 같이 만들어줘.
끝나면 내가 오늘 배운 명령어를 CLAUDE.md에 기록해줘.

오늘의 목표는 산출물 품질이 아니라: 지시 → 확인 → 재지시의 사이클을 손끝으로 한 번 굴려보는 것입니다.

한 줄로 줄이면

좁혀 말하고 → 한 번에 한 가지 → 결과를 직접 확인 → 피드백을 짧게 반복.

막히는 순간이 오면 다음 섹션 트러블슈팅에서 길을 이어가세요.

06. 플러그인 추천 설치

기본만으로도 Claude Code는 강력합니다. 다만 작업이 늘어날수록 "매번 같은 일을 짜는 게 싫어지는 순간"이 옵니다. 그때부터가 플러그인의 영역입니다.

플러그인은 "스마트폰의 앱"과 비슷합니다

스마트폰 본체로도 전화·메시지·카메라가 다 되지만, 앱을 깔면 사진 편집이나 가계부 같은 영역이 새로 열립니다. 플러그인도 똑같습니다. Claude Code 위에 얹어 쓰는 기능 꾸러미이고, 한 꾸러미 안에는 보통 다음 네 가지 중 한두 개가 들어 있습니다.

• Skills: /플러그인명:명령어 형태의 커스텀 명령어
• Agents: 특정 역할을 맡는 AI 에이전트
• Hooks: 파일 저장·명령 실행 같은 이벤트에 자동으로 반응하는 핸들러
• MCP 서버: GitHub·Figma 같은 외부 서비스와 연결하는 다리

공식 마켓플레이스를 가장 먼저

Anthropic이 운영하는 claude-plugins-official 마켓은 Claude Code를 시작한 순간부터 따로 등록 없이 바로 사용할 수 있습니다. 안에서 /plugin을 입력하면 Discover 탭이 열립니다. 카탈로그를 둘러보다가 끌리는 걸 골라 설치하시면 됩니다.

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

카테고리별 대표 선수

• 외부 서비스 연동: notion, slack, github : Notion·Slack·GitHub을 Claude와 직접 잇기
• 출력 스타일: explanatory-output-style : 응답 형식을 요약·체크리스트 등으로 다듬기
• 개발 워크플로: commit-commands : Git 커밋 메시지 작성 보조

/plugin install typescript-lsp@claude-plugins-official
/plugin install pyright-lsp@claude-plugins-official

설치 흐름: 3단계로 끝납니다

① 마켓에서 직접 골라 설치

Claude Code 안에서 한 줄이면 됩니다.

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

GitHub 연동을 예로 들면 다음과 같습니다.

/plugin install github@claude-plugins-official

/plugin만 입력해서 Discover 탭에서 목록을 보고 고르셔도 좋습니다.

ℹ️ 플러그인은 한 번에 한 개씩 설치됩니다. 여러 개를 깔려면 명령을 반복해주세요.

② 설치 결과 확인

/plugin list

/plugin에서 Installed 탭으로 들어가도 같은 정보를 볼 수 있습니다.

③ 새 버전이 나왔을 때

/plugin update

⚠️ 설치·업데이트 직후에는 Claude Code를 한 번 재시작해주세요. 새로 들어온 명령·훅·MCP가 실행 컨텍스트에 반영됩니다.

설치한 직후: "작은 첫 사용"이 중요합니다

플러그인은 설치 자체보다 첫 사용에서 신뢰가 결정됩니다. 처음부터 중요한 작업을 맡기지 마시고, 읽기 전용으로 가벼운 요청을 한 번 던져보세요.

• GitHub → "내 저장소의 열린 이슈 다섯 개를 요약하고 우선순위를 제안해줘"
• Notion → "최근 회의록 페이지 하나를 읽고 결정사항만 정리해줘"
• Slack → "#팀채널의 오늘 주요 논의를 다섯 줄로 압축해줘"
• Chrome DevTools → "localhost:3000을 열고 콘솔 오류·네트워크 실패가 있는지 확인해줘"

읽기 전용 요청이 잘 동작했다면, 그제서야 쓰기·수정 권한이 필요한 작업으로 한 단계씩 넓혀가는 편이 안전합니다.

일상적인 플러그인 관리 명령

자주 쓰게 되는 명령은 다섯 개 정도입니다.

• /plugin: 매니저 화면 열기 (Discover · Installed · Marketplaces · Errors 탭 전환)
• /plugin list: 깔린 플러그인 한눈에 보기
• /plugin disable 플러그인명: 잠시 끄기
• /plugin enable 플러그인명: 다시 켜기
• /plugin uninstall 플러그인명: 완전히 제거

다음으로: 핵심 개념 한 바퀴

공식 플러그인 하나를 읽기 전용으로 작게 시험해봤다면 준비는 충분합니다. 이제 Claude Code가 안쪽에서 어떤 흐름으로 동작하는지: Context, Permissions, Memory 같은 개념을 한 바퀴 살펴볼 차례입니다.

07. 핵심 개념 이해하기

도구의 내부 동작 방식을 한 번 들여다보면, 이후 사용 방식이 자연스럽게 달라집니다. 어렵지는 않습니다: 한 페이지 분량의 그림 다섯 개입니다.

Claude Code는 어떤 결로 일하나요?

Claude Code는 챗봇이 아니라 에이전트(Agent)입니다. 일을 시키면 스스로 계획을 세우고, 파일을 읽고, 수정하고, 결과를 확인하는 흐름을 자동으로 굴립니다. 이 사이클을 보통 에이전트 루프(Agentic Loop)라고 부릅니다.

사용자의 한 문장
     ↓
① 상황 파악 — 파일 읽기·코드 검색·현재 상태 확인
     ↓
② 행동      — 파일 수정·명령 실행·웹 검색
     ↓
③ 결과 확인 — 테스트 실행·오류 점검·재수정
     ↓
완료 (또는 ①로 돌아가 반복)

예를 들어 "reports/ 폴더 문서를 요약해줘"라고 하면: 폴더 목록 확인 → 문서 본문 읽기 → 요약 작성 → 빠진 부분 보완. 이 흐름이 한 호흡에 자동으로 이어집니다.

다섯 개의 줄기: 알아두면 좋은 기본 개념

① Context: Claude의 작업 기억

지금 Claude가 머릿속에 들고 있는 모든 것이 컨텍스트입니다. 대화 내역, 읽은 파일, 명령 결과, CLAUDE.md 지시까지 다 들어갑니다. 그런데 이 기억에는 토큰 한계가 있어서 길어지면 자동으로 오래된 내용부터 정리합니다.

# 컨텍스트 현황 보기
/context

# 오래된 내용을 요약해 압축
/compact

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

💡 자주 참조할 규칙은 CLAUDE.md에 적어두세요. 매번 컨텍스트를 차지하지 않고도 Claude가 일관되게 따릅니다.

"컨텍스트가 찼다"는 신호

다음과 같은 증상이 보이면 /compact나 새 세션이 도움이 됩니다.

• 좀 전에 합의한 규칙을 다시 어깁니다
• 같은 파일을 거듭 읽으면서도 결론이 흔들립니다
• 답변은 길어지는데 실제 수정 속도는 느려집니다
• 이미 실패한 접근을 또 시도합니다
• "현재 상태를 다시 설명해달라"는 요청이 늘어납니다

이때 한 줄이면 정리됩니다.

/compact 결정사항·바뀐 파일·남은 작업만 중심으로 압축해줘

② Tools: Claude가 실제로 할 수 있는 동작

Claude Code는 말만 하지 않습니다. 도구(Tools)를 통해 실제 동작을 일으킵니다. 큰 분류로 다섯 갈래입니다.

• 파일 작업: 읽기, 편집, 새 파일 생성, 이름 변경
• 검색: 패턴 매칭, 정규식, 코드베이스 탐색
• 실행: 셸 명령, 서버 기동, 테스트, Git
• 웹: 검색, 공식 문서 조회, 오류 메시지 검색
• 코드 분석: 편집 후 타입 오류 감지, 정의·참조 탐색

③ Permissions: 허용 범위를 직접 정하기

강력한 도구일수록 안전 장치가 필요합니다. Claude Code는 작업 종류마다 허용 여부를 사용자가 직접 통제할 수 있습니다. 파일 읽기는 기본 허용, 수정과 셸 실행은 확인을 받습니다.

규칙은 세 가지입니다.

• Allow: 묻지 않고 자동 실행
• Ask: 매번 승인 여부를 묻기
• Deny: 절대 실행하지 않음

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

⚠️ 우선순위는 Deny > Ask > Allow. 거부 규칙이 항상 최상위입니다.

④ Memory: CLAUDE.md로 장기 기억 만들기

세션이 끝나면 대화는 사라집니다. 그래서 CLAUDE.md가 등장합니다. 매 세션 시작 시 자동으로 읽히는 지시서이자 메모장입니다.

위치에 따라 작용 범위가 달라집니다.

• ./CLAUDE.md: 현재 프로젝트에만 적용 (팀 공유 가능)
• ~/.claude/CLAUDE.md: 내 모든 프로젝트에 적용 (전역)
• ./CLAUDE.local.md: 나만의 프로젝트 설정 (git에 안 올라감)

자세한 작성법은 08. CLAUDE.md 완전 정복에서 깊게 다룹니다.

⑤ Session: 대화의 시작과 끝

한 번 켜고 끄기까지의 한 덩어리가 세션입니다.

• 새 세션을 시작하면 이전 대화는 사라집니다 (CLAUDE.md는 그대로)
• 세션 중에 만든 파일·설정은 디스크에 그대로 남습니다

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

# 이전 세션 목록에서 골라 재개
claude --resume

# 같은 시점에서 다른 갈래를 시도하고 싶을 때 (포크)
claude --continue --fork-session

"왜 가끔 멈추고 확인을 받죠?"

이건 버그가 아니라 일부러 만든 안전 장치입니다. 파일을 고치거나 명령을 실행하기 전에 의도를 한 번 더 점검하기 위함입니다. 되돌리기 어려운 작업(삭제·배포·DB 변경 등)일수록 이 단계의 가치가 커집니다.

권한 모드 세 가지: Shift+Tab으로 순환

Shift+Tab 한 번이면 모드가 다음 단계로 돌아갑니다. 입문자 입장에서 알아둘 건 세 가지입니다.

• Default (기본): 파일 수정·셸 실행 전에 매번 확인. 처음 쓰거나 중요한 작업일 때.
• Auto-Accept (자동 수락): 파일 수정은 자동, 셸 실행은 여전히 확인. 익숙해진 후 속도를 높일 때.
• Plan Mode (계획): 읽기와 분석만, 어떤 변경도 일으키지 않음. 큰 작업 직전 그림을 보고 싶을 때.

모드 전환

# Shift+Tab → Default → Auto-Accept → Plan → Default → ...

# Plan Mode로 바로 진입
/plan

같은 요청, 모드별 차이

"폴더 내 문서에서 '구버전 문구'를 '신규 문구'로 일괄 교체해줘"

Default     → 파일마다 "수정해도 될까요?" 확인
Auto-Accept → 파일은 자동 수정, 명령(git commit 등)만 확인
Plan        → "어느 파일 어느 줄을 어떻게 바꿀지" 미리 보여주고 실제 수정은 보류

"모든 JavaScript 파일에서 console.log를 지워줘"

Default     → 파일마다 확인
Auto-Accept → 파일은 자동, git commit 같은 명령만 확인
Plan        → 어느 파일의 몇 번째 줄을 지울지만 보여주고 보류

💡 처음엔 Default로 어떤 일을 시키는지 감각을 익히고, 익숙해지면 Auto-Accept로 옮기는 흐름이 안전합니다.

체크포인트: 잘못 수정돼도 되돌릴 수 있습니다

파일을 수정하기 직전 Claude는 스냅샷을 자동으로 남깁니다. 실수가 났다면 두 가지 방법이 있습니다.

• Esc를 두 번 연속으로 눌러 직전 상태로 복구
• 또는 한 줄로: "방금 한 것 취소해줘"

여기까지 잡히면 Claude Code의 동작이 머릿속에서 예측 가능해집니다. 다음 섹션에서는 이 모든 것의 중심축인: CLAUDE.md를 제대로 쓰는 법으로 들어갑니다.

08. CLAUDE.md 완전 정복

Claude Code의 장기 기억을 책임지는 한 장의 메모지입니다. 한 번 잘 써두면, 그 뒤로는 같은 설명을 두 번 다시 할 필요가 없습니다.

출처: Memory & CLAUDE.md — Anthropic 공식 문서

왜 필요한가요?: 같은 말을 반복하지 않기 위해

세션이 끝나면 Claude Code는 대화를 잊어버립니다. 다음에 켜면 처음 만난 사이로 돌아갑니다. 그 빈자리를 메우는 게 CLAUDE.md입니다. Claude Code가 켜질 때마다 자동으로 읽어 들이는 지시서 겸 프로젝트 설명서입니다.

비유하자면 이런 차이입니다.

[CLAUDE.md 없을 때]
"이 프로젝트는 Next.js로 만들었고, TypeScript를 써.
 탭 대신 스페이스 2칸이고, 커밋 메시지는 한국어야."
→ 매 세션 다시 설명

[CLAUDE.md 있을 때]
↑ 위 내용이 파일 한 장에 박혀 있음
→ 자동으로 기억된 채로 작업 시작

어디에 두느냐가 곧 적용 범위입니다

위치마다 영향력이 다릅니다. 가까운 위치일수록 우선합니다.

• ./CLAUDE.md: 현재 프로젝트 전용 (Git 공유 가능)
• ./.claude/CLAUDE.md: 같은 효과, 숨김 폴더에 두는 변형
• ./CLAUDE.local.md: 나만의 프로젝트 설정 (자동으로 .gitignore에 들어감)
• ~/.claude/CLAUDE.md: 내 모든 프로젝트에 공통 적용 (전역)

가장 흔한 출발점은 프로젝트 루트의 ./CLAUDE.md입니다. 두 가지 방법이 있습니다.

# 빈 파일을 만들고 직접 작성
touch CLAUDE.md

# Claude에게 초안을 만들게 하기
/init

/init을 쓰면 현재 폴더를 한 번 분석해 초안을 자동으로 적어 줍니다. 빈 페이지 공포에 가장 좋은 처방입니다.

무엇을 적어야 잘 적은 걸까?

정해진 양식은 없습니다. 마크다운 자유 형식이고, 다음 다섯 묶음을 채우면 효과가 큽니다.

💡 여기서 말하는 '프로젝트'는 코드 프로젝트만이 아닙니다. 리서치 폴더, 콘텐츠 폴더, 업무 자동화 폴더 어디에서도 똑같이 작동합니다.

묶음 ① 작업 개요

이 폴더가 어떤 작업을 위한 곳인지 한두 줄.

## 작업 개요
이 폴더는 경쟁사 시장 조사 리서치 프로젝트입니다.
조사 결과는 reports/ 폴더에 마크다운으로 저장합니다.

묶음 ② 도구·환경

어떤 도구·자료·저장 방식을 쓰는지.

## 작업 환경
- 주요 도구: Notion(기획), Google Docs(초안), Canva(디자인)
- 자료 저장 위치: docs/ 폴더 (마크다운 형식)
- 참고 언어: 한국어 우선, 영어 자료는 요약 번역

묶음 ③ 작업 규칙

스타일·명명 규칙·출처 기준 같은 가드레일.

## 작업 규칙
- 글 어조: 친근하고 명확하게 (과장 표현 금지)
- 파일명: YYYY-MM-DD_주제.md 형식
- 출처가 없는 통계·수치 사용 금지
- 항상 한국어로 작성

묶음 ④ 금지 사항

해서는 안 되는 것을 명시적으로 적어두면 사고가 줄어듭니다.

## 절대 하지 말 것
- 출처 없는 통계 인용
- 검증 안 된 정보를 사실처럼 기술
- 고객·파트너 실명을 문서에 노출
- 이전 버전 파일 덮어쓰기 (항상 날짜 포함 파일명 사용)

묶음 ⑤ 자주 쓰는 작업의 형식

반복되는 결과물의 골격을 박아두면 품질이 일정해집니다.

## 자주 쓰는 작업
- 리서치 보고서: "요약 → 핵심 인사이트 5개 → 출처 목록" 순서로
- 회의록 정리: "결정사항 → 액션아이템(담당·기한) → 미결 이슈"
- 문서 검토: 먼저 요약 제시, 수정 필요한 부분은 이유와 함께 표시

도메인별 즉시 사용 템플릿: 복사해서 빈칸만 채우세요

템플릿 A: 부동산·시장 분석 워크스페이스

# 시장 분석 프로젝트 규칙 (CLAUDE.md)

## 프로젝트 목적
- 목표: [지역·기간·타깃을 한 줄로]
- 산출물: report.md(요약), data.md(원자료), brief.md(임원 1쪽 브리프)

## 자료·폴더 규칙
- 원문 자료는 sources/ 폴더 (파일명: YYYY-MM-DD_출처_제목.md)
- 가공 데이터는 data/ 폴더에 csv·xlsx로 보관
- 내 메모·가설은 notes/ 폴더에 분리해 보관 (원문과 섞지 않기)

## 출처·신뢰도
- 모든 수치에 출처와 측정 기준을 함께 기록
- 출처 등급: A(공공기관·1차) / B(업계 보고서·2차) / C(블로그·의견)
- 추정치는 "추정" 표시, 산식도 같이 기록

## 결과물 형식
- 한국어, 문장은 짧게
- 결과물 기본 구조: ① 5줄 요약 ② 핵심 인사이트 5개 ③ 반대 시나리오·리스크 3개 ④ 다음 액션 3개

템플릿 B: 콘텐츠 제작 워크스페이스

# 콘텐츠 제작 규칙 (CLAUDE.md)

## 브랜드 톤
- 친근하지만 과장 금지 ("완벽·혁명·무조건" 표현 금지)
- 독자: [타깃 독자 한 줄], 전문 용어는 괄호 안에 짧게 풀이

## 채널별 형식
- 블로그: 제목 후보 3안 → 본문(소제목 4~6) → 체크리스트 → CTA 1개
- 인스타: 카드뉴스 7~9장 (장당 한 문장), 마지막 장 요약+링크
- 뉴스레터: 3줄 요약 → 본문 600~900자 → 다음 주제 예고

## 금지·주의
- 경쟁사 실명 언급 금지 (필요 시 "A사·B사")
- 통계·수치는 출처 없으면 "예시"로 표시

## 파일 출력
- 초안: drafts/YYYY-MM-DD_주제_채널.md
- 최종: final/ 폴더, 상단에 버전·검수자·발행일 메타데이터

템플릿 C: 비즈니스 운영 워크스페이스

# 운영 문서 규칙 (CLAUDE.md)

## 회사·제품 맥락
- 제품: [제품명] / 고객: [타깃] / 핵심 가치: [한 줄]
- 자주 쓰는 용어 정의는 아래에 누적: [용어: 정의]

## 커뮤니케이션 스타일
- 이메일·메시지: 존댓말, 3문단(요약 → 상세 → 다음 단계)
- 고객 불만 응대: "공감 1문장 → 사실 확인 질문 2개 → 해결 옵션 2개"

## 문서 템플릿
- 회의록: 회의 목적 / 결정사항 / 액션아이템(담당·기한) / 이슈
- 제안서: 문제정의 → 해결안 → 일정·범위 → 비용 → 리스크

## 보안·민감 정보
- 개인정보·결제정보는 마스킹 (예: 010-****-1234)
- 외부 공유 전 "대외비 문구·고객명 점검 목록" 먼저 출력

# 프로젝트 지침

## 프로젝트 개요
[1~2줄]
예: 소상공인 재고 관리 SaaS. Next.js 14 App Router + TypeScript + Supabase.

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

## 코딩 규칙
- 컴포넌트: PascalCase
- 함수·변수: camelCase
- 상수: UPPER_SNAKE_CASE
- `any` 금지, 모든 함수 반환 타입 명시

## 자주 쓰는 명령
pnpm dev, pnpm build, pnpm test, pnpm lint

## 절대 하지 말 것
- npm·yarn 사용 (pnpm 통일)
- any 타입
- 환경 변수 코드에 하드코딩

## Git 커밋 규칙
- 한국어, "타입: 변경 내용" (예: feat: 사용자 로그인 페이지 추가)

전역 메모리: 모든 프로젝트가 공유하는 규칙

~/.claude/CLAUDE.md에 적은 내용은 어떤 폴더에서 Claude Code를 켜든 자동으로 적용됩니다.

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

특히 잘 어울리는 내용은 다음과 같습니다.

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

## 개인 선호
- 설명은 항상 한국어로
- 코드 변경 전 무엇을 할지 먼저 알려주기
- 되돌리기 어려운 변경은 한 번 더 확인

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

우선순위: 가까운 규칙이 이깁니다

여러 CLAUDE.md가 동시에 적용될 때 어느 게 우선일까요. 답은 단순합니다: 구체적인 쪽입니다.

높음 → 낮음
① CLAUDE.local.md     (나만의 프로젝트 설정)
② ./CLAUDE.md         (프로젝트 공용 설정)
③ ~/.claude/CLAUDE.md (개인 전역 설정)
④ 엔터프라이즈 관리 설정 (회사 IT 정책 푸시)

전역에서 "스페이스 2칸"이라고 정해뒀어도, 프로젝트 CLAUDE.md에서 "탭 사용"으로 바꾸면 프로젝트 쪽이 이깁니다.

💡 @path/to/file 임포트 문법으로 다른 파일을 끌어올 수 있습니다 (@README.md, @~/.claude/personal.md 등).

운영 팁: 잘 쓴 CLAUDE.md vs 아쉬운 CLAUDE.md

길이가 아니라 검사 가능성이 핵심입니다

좋은 규칙은 "지켰는지 확인할 수 있는" 규칙입니다. 아래는 같은 의도를 표현한 두 가지 방식의 차이입니다.

• "좋은 코드를 작성해줘" → "TypeScript strict 기준을 지키고, any는 사용하지 마"
• "친절하게 답해줘" → "최종 답변은 한국어로, 변경 파일과 검증 결과만 간결히"
• "보안에 신경 써줘" → "API 키·토큰·비밀번호를 코드에 하드코딩 금지. .env.local 사용"
• "문서를 잘 써줘" → "문서는 제목 → 요약 → 절차 → 체크리스트 순서로"

/memory로 즉석 편집

세션 도중 CLAUDE.md를 빠르게 손보고 싶다면:

/memory

파일 선택기가 열리고 그 자리에서 수정하실 수 있습니다.

다른 파일을 끌어오는 import

# 프로젝트 지침

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

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

새 프로젝트의 첫 한 발은: CLAUDE.md부터

/init

직접 부탁해도 됩니다.

이 폴더는 경쟁사 시장 조사 리서치 프로젝트야.
결과물은 reports/ 폴더에 마크다운으로 저장하고,
모든 주장에 출처를 달아줘. 한국어 작성.
이 내용을 바탕으로 CLAUDE.md를 만들어줘.

🖥️ 개발자라면: "이 프로젝트는 Next.js 14 + TypeScript + Tailwind, pnpm 사용. CLAUDE.md 만들어줘."

한 페이지 요약

CLAUDE.md 한 장만 제대로 써둬도 매 세션 들이는 설명 시간이 사라집니다. Claude Code가 "진짜 같이 일하는 팀원"처럼 느껴지는 순간이 바로 여기서 시작됩니다.

09. 명령어 모음

처음엔 외울 게 많아 보이지만, 실제로 첫 주에 쓰게 되는 명령은 다섯 손가락 안쪽입니다. 나머지는 필요한 순간에 한 번씩 다시 들춰봅니다.

출처: Slash Commands — Anthropic 공식 문서

명령어는 세 갈래로 나뉩니다

입력하는 위치를 기준으로 세 가지를 구분하면 머릿속이 정리됩니다.

• CLI 명령어: Claude Code 밖의 터미널에서 입력 (claude, claude --version 등)
• 슬래시 명령어: Claude Code 안의 대화창에서 입력 (/help, /compact 등)
• 키보드 단축키: 대화 중 손가락으로 (Ctrl+C, Shift+Enter 등)

첫 주에 쓰는 다섯 손가락

명령을 다 외울 필요는 없습니다. 이 다섯 가지만 손에 익으면 첫 주는 충분합니다.

• claude: 시작
• /compact: 대화가 길어졌을 때 정리
• /clear: 완전히 새로운 작업으로 전환
• Ctrl+C: 멈추고 싶을 때
• /quit: 끝낼 때

나머지는 필요할 때 /help로 찾으시면 됩니다.

갈래 ①: CLI 명령어 (터미널에서 입력)

Claude Code를 켜고 제어할 때 쓰는 명령들입니다. 빈도 높은 순으로 보면 이렇습니다.

켜기·끄기·확인

• claude: 대화형 모드 시작
• claude "질문": 시작과 동시에 한 줄 질문 (예: claude "이 프로젝트 설명해줘")
• claude -p "질문": 답변만 출력하고 종료 (스크립트에 좋습니다)
• claude -c: 가장 최근 세션 이어서
• claude --version (또는 -v): 버전 확인
• claude --help: 도움말 보기
• claude update: 최신 버전으로 업데이트

모델 골라 켜기

# 정확한 ID로
claude --model claude-opus-4-7
claude --model claude-sonnet-4-6

# 짧게 별칭으로
claude --model opus     # Opus 4.7 (Max·Team Premium 기본)
claude --model sonnet   # Sonnet 4.6 (Pro·Team Standard 기본)
claude --model haiku    # 가벼운 작업용

시작 시점에 자주 끼우는 옵션

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

# 이름 붙은 세션 재개
claude --resume 세션이름

# 목록에서 골라 재개
claude --resume

💡 처음엔 그냥 claude만 쳐도 충분합니다. 옵션은 필요해질 때 하나씩 익혀도 늦지 않습니다.

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

대화창에서 /로 시작하면 특별한 기능이 열립니다. 자주 쓰이는 것들을 묶어 정리했습니다.

일상에서 매일 쓰게 되는 것들

• /help: 사용 가능한 명령어 전부 보기
• /compact: 대화 내용 압축 (긴 세션 필수)
• /clear: 대화 완전 초기화
• /usage: 세션 비용·플랜 한도·활동 통계 (/cost·/stats는 alias)
• /model: 사용 중인 모델 변경
• /permissions: 권한 설정 보기·관리
• /memory: CLAUDE.md 편집
• /quit 또는 /exit: 종료

가끔 쓸 일이 생기는 것들

• /plan: Plan Mode 진입
• /init: 프로젝트에 CLAUDE.md 초안 생성
• /doctor: 설치 상태 점검
• /config: 설정 화면(테마·모델·에디터 모드 등)
• /branch 또는 /fork: 현재 시점에서 대화 분기
• /context: 컨텍스트 토큰 사용량 시각화
• /rename [이름]: 세션에 이름 붙이기 (--resume 이름으로 재개)
• /bug: Anthropic에 버그 리포트 전송
• /login / /logout: 계정 로그인·로그아웃
• /rewind: 대화·코드를 이전 시점으로 되돌리기

슬래시 명령은 인자도 받습니다

> /compact
→ 일반 압축

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

> /model
→ 모델 선택 화면 열기

💡 대화창에서 /만 입력하시면 자동완성이 뜹니다.

분기·실험을 위한 작은 도구들

대화 흐름을 바꾸거나, 실패가 우려되는 시도를 안전하게 굴릴 때 쓰는 기법들입니다.

/branch (또는 /fork): 원본을 두고 곁가지를 만들기

큰 리팩토링이나 구조 변경 전에 분기해두면, 잘 안 되더라도 /resume으로 돌아갈 수 있습니다.

> /branch
→ 현재 시점에서 새 분기 시작
→ 원본은 /resume으로 복귀 가능

언제 좋을까요.

• 여러 구현 방안 중 하나만 먼저 시험하고 싶을 때
• "이렇게 바꾸면 어떨까" 싶지만 실패가 걱정될 때
• 같은 문제를 다른 접근으로 비교해보고 싶을 때

/compact: 호흡이 길어졌을 때

응답이 느려지면 압축으로 같은 세션을 이어가세요. 완전히 새 세션이 필요하면 /clear로요.

> /compact 변경 사항과 결정 위주로 정리해줘
→ 같은 세션에서 컨텍스트만 가벼워짐

/context: 지금 컨텍스트가 얼마나 차 있는지

> /context
→ [■■■■■■■□□□] 70% (143,000 / 200,000 tokens)

80%를 넘었다면 /compact로 줄이거나 /clear로 새로 시작하시는 편이 좋습니다.

/rename: 세션에 라벨 붙이기

중요한 작업에는 이름을 달아두면 다음에 빠르게 찾을 수 있습니다.

> /rename housing-research-2026Q2

# 다음 날 터미널에서
$ claude --resume housing-research-2026Q2

갈래 ③: 키보드 단축키

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

핵심

• Ctrl+C: 작업 취소 (Claude가 엉뚱하게 갈 때 즉시 멈추기)
• Ctrl+D: Claude Code 종료
• Ctrl+L: 터미널 화면만 지우기 (대화는 유지)
• Ctrl+R: 이전 입력 검색
• Ctrl+G: 외부 에디터에서 입력 다듬기
• Ctrl+T: 작업 목록 보기·숨기기

입력 도우미

• Shift+Enter: 줄바꿈 (긴 지시사항)
• Option+Enter (macOS): 줄바꿈 (macOS 기본 키)
• \ + Enter: 줄바꿈 (모든 터미널 호환)
• ↑ / ↓ 화살표: 이전·다음 입력 탐색
• Esc Esc (두 번): 이전 상태로 되감기

모드 전환

• Shift+Tab: Plan Mode ↔ 일반 모드
• Option+P (macOS) / Alt+P: 모델 변경
• Option+T (macOS) / Alt+T: 확장 사고 모드 토글
• Ctrl+B: 현재 작업을 백그라운드로 두고 새 대화 창 열기

첫날 5개: 이걸로 일주일 버팁니다

새로 시작하셨다면 다음 다섯 가지면 일주일은 족히 굴러갑니다.

① /compact: 대화의 호흡 정리

> /compact

길어지면 응답이 느려지고 오래된 내용을 잊습니다. 호흡이 길어졌다 싶으면 한 번씩 눌러주세요. 습관처럼이 핵심.

② Ctrl+C: 즉시 멈추기

방향이 어긋나거나 위험한 명령에 손가락이 미끄러졌을 때, 망설이지 말고 누르세요.

③ /clear: 새 작업으로 전환

> /clear

전혀 다른 주제로 넘어갈 때 이전 맥락이 따라오면 오히려 방해가 됩니다. 깔끔하게 비우고 시작하세요.

④ Shift+Enter: 긴 요청 여러 줄 쓰기

한 줄로 압축하기 힘든 요청은 줄을 바꿔가며 적는 편이 결과 품질도 더 좋아집니다.

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

⑤ /usage: 비용과 한도 확인

> /usage

세션 비용·플랜 한도·활동 통계를 한 번에 봅니다. /cost·/stats도 같은 명령의 alias입니다.

alias cc='claude'
alias ccd='claude --dangerously-skip-permissions'
alias ccr='claude --resume --dangerously-skip-permissions'

source ~/.zshrc

function cc { claude @args }
function ccd { claude --dangerously-skip-permissions @args }
function ccr { claude --resume --dangerously-skip-permissions @args }

한 페이지 치트시트

[ 터미널 ]
  claude                    → 시작
  claude -v                 → 버전 확인
  claude --help             → 도움말
  claude -c                 → 마지막 세션 이어서
  claude --resume [이름]    → 이름 붙은 세션 재개
  claude --add-dir [경로]   → 추가 디렉토리 포함

[ alias (설정 후) ]
  cc / ccd / ccr            → 각각 기본·자동승인·재개+자동승인

[ 대화창 ]
  /help                → 명령어 전체 목록
  /compact             → 대화 압축 (자주 쓰세요!)
  /clear               → 대화 초기화
  /branch (/fork)      → 분기 생성
  /context             → 컨텍스트 사용량 확인
  /usage               → 비용·한도·통계 (/cost·/stats alias)
  /model               → 모델 변경
  /rename [이름]        → 세션 이름 붙이기
  /bug                 → 버그 리포트 전송
  /quit                → 종료

[ 키보드 ]
  Ctrl+C               → 작업 취소
  Ctrl+D               → 종료
  Ctrl+B               → 백그라운드 전환·새 창
  Shift+Enter          → 줄바꿈
  ↑↓                   → 이전 입력 탐색
  Esc Esc              → 이전 상태로 되감기

10. 세션 & 컨텍스트 관리

한 호흡이 길어지면 사람도 흐릿해지고, AI도 마찬가지입니다. 세션을 적당히 끊고·붙이고·되감는 작은 기술 몇 가지가 결과 품질을 좌우합니다.

컨텍스트 윈도우: "메모지의 크기"

이해를 돕는 두 갈래의 설명입니다.

비유로 풀면. Claude는 지금까지 오간 모든 내용을 메모지에 적어가며 작업합니다. 그 메모지의 크기는 무한이 아닙니다. 대화가 길어질수록 위에 있던 내용부터 가장자리로 밀려납니다. "분명 아까 말했는데 왜 모르지"가 일어나는 정확한 이유입니다: 누가 잊은 게 아니라, 메모지에서 잘려나간 것입니다.

기술적으로 풀면. 컨텍스트 윈도우는 모델이 한 번에 다룰 수 있는 토큰 최대치입니다. Claude Code는 슬라이딩 윈도우로 작동하므로, 한도를 넘어서면 가장 오래된 토큰부터 잘립니다.

두 설명이 결국 한 그림입니다.

대화가 길어지면:
  초반 내용이 밀려나기 시작
  → 앞에서 한 작업을 기억 못하기도
  → 답변 품질이 흐려지기 시작
  → 같은 실수를 반복하기 시작

가만 두면 점점 엉킵니다. 가끔은 손으로 정리해줘야 합니다.

/compact: 메모지를 짧게 다시 쓰기

/compact

지금까지의 대화를 요약해 컨텍스트를 줄여줍니다. 핵심은 살리되 부피만 깎는 동작입니다.

• 중요한 결정·결과는 요약에 들어갑니다
• 세션은 끊지 않고 그대로 이어집니다
• 언제 누르나: 호흡이 길어졌다 싶을 때, 답변이 어슴푸레해질 때

압축 방향은 사람이 잡아줄 수도 있습니다.

/compact 리서치 결과와 주요 발견사항 중심으로 요약해줘
/compact 작성 중인 보고서의 구조와 진행 상황 중심으로
/compact 결론·근거·미해결 질문만 남겨줘

끊긴 흐름을 다시 잇는 두 가지 방법

--continue: 가장 최근 흐름을 그대로

claude --continue

마지막에 종료한 세션을 그대로 들고 옵니다.

• 터미널을 닫았다 다시 연 순간
• 어제 작업을 오늘 이어가는 아침

--resume: 목록에서 골라서

claude --resume

이전 세션 목록을 보여주고 골라서 잇습니다.

• 여러 프로젝트를 번갈아 다룰 때
• 며칠 전 특정 세션으로 돌아가야 할 때

새 세션을 열되 맥락은 잃지 않는 템플릿

긴 세션을 억지로 끌고 가는 것보다, 핵심 요약을 들고 새로 시작하는 편이 더 정확할 때가 많습니다. 이런 한 장이면 충분합니다.

현재 작업:
- 프로젝트·폴더:
- 목표:
- 지금까지 완료:
- 아직 남은 일:
- 반드시 지킬 규칙:
- 참고할 파일:

위 내용을 바탕으로 현재 상태부터 파악하고,
바로 수정하지 말고 다음 작업 계획부터 제안해줘.

새 세션이 더 나을 때 vs 이어가는 게 더 나을 때

상황별 권장 흐름을 글로 풀어 정리하면 다음과 같습니다.

• 완전히 다른 주제·프로젝트라면: 새 세션
• Claude가 앞에서 한 약속을 잊기 시작하면: 새 세션 + 핵심 다시 전달
• 같은 오류를 반복한다면: 새 세션(컨텍스트가 오염됐을 수 있습니다)
• 대화가 길어졌지만 같은 작업이라면: /compact 후 계속
• 어제 일을 오늘 잇는 거라면: --continue

큰 작업 전에는: Plan Mode 한 번 거치기

여러 파일을 동시에 손대거나 되돌리기 어려운 변경이 예상되면, 실행 전에 계획부터 검토받을 수 있습니다.

Shift + Tab  →  Plan Mode 전환

Plan Mode에서 Claude는: ① 실행 계획만 보여주고 파일은 건드리지 않습니다 → ② "이렇게 하려고 하는데 맞나요?" 확인을 받습니다 → ③ 승인된 뒤에야 진짜로 실행합니다.

특히 잘 어울리는 상황: 여러 파일 동시 수정, 폴더 구조 개편, 대량 치환, 되돌리기 어려운 변경 직전.

병렬 세션: 손이 늘어나는 느낌

터미널을 여러 개 열어 동시에 다른 일을 맡길 수 있습니다.

터미널 1: claude (시장 통계 리서치)
터미널 2: claude (분석 리포트 작성)
터미널 3: claude (요약본 슬라이드 정리)

각 세션이 독립적으로 굴러갑니다.

⚠️ 같은 파일을 두 세션에서 동시에 수정하면 충돌이 납니다. 담당 파일·역할을 미리 나누는 것이 안전한 출발점입니다.

호흡 좋은 대화의 두 가지 습관

① 한 번에 한 가지만

가장 흔한 초보자 실수가 한 번에 모든 걸 요청하는 것입니다.

# 흐트러지기 쉬운 흐름
> 로그인·대시보드·DB 연동·API·테스트·배포 다 해줘

# 결과가 좋은 흐름
> 먼저 프로젝트 구조를 잡아줘
(확인)
> 로그인 기능부터 만들어줘
(확인)
> 다음으로 대시보드 추가해줘

한 턴에 한 작업, 확인 뒤 다음. 돌아가는 것처럼 보여도 결과적으로 더 빠르고 정확합니다.

② 며칠 단위 작업이라면 진행 상황을 CLAUDE.md에 남기기

# 현재 진행 상황
- 로그인 기능: 완료
- 대시보드: 레이아웃만 완성, 데이터 연동 필요
- 다음 할 일: 대시보드에 실시간 데이터 연결

새 세션이라도 Claude가 CLAUDE.md를 읽고 곧장 맥락을 잡습니다.

자주 만나는 두 장면: 짧은 대처

장면 ①: 답변이 갑자기 이상해질 때

1) /compact로 한 번 줄여본다
2) 그래도 이상하면 → 새 세션
3) 새 세션엔 핵심만:
   "현재 [프로젝트명] 작업 중. 지금까지 [요약]을 했고,
    다음으로 [작업]을 해야 한다."

장면 ②: 작업을 잠깐 멈추고 자리를 떠야 할 때

작업 중 → Ctrl+C로 중단
→ 터미널 닫기
→ 다음에: claude --continue

Claude가 중단된 지점의 상태를 들고 있습니다.

💡 비용과도 직접 연결됩니다: 컨텍스트가 길수록 토큰이 더 든다는 뜻입니다. /compact를 주기적으로 쓰면 속도가 회복되고 비용도 함께 줄어듭니다. 자세한 운영법은 20. 비용 관리에서 이어집니다.

11. GitHub 시작하기

🖥️ 코드를 다루는 분에게 가장 효과가 큰 섹션입니다. 코딩 작업이 없으시다면 아래 비개발자용 파일 안전망까지만 읽고 다음 섹션으로 넘어가셔도 충분합니다. Git은 명령어를 외우는 일이 아니라, "되돌릴 수 있다"는 안심을 얻는 일이라고 보시면 됩니다.

비개발자라면: 굳이 Git 안 가도 되는 안전망 셋

코딩이 없어도 파일이 사라지거나 잘못 덮어써지는 사고는 누구에게나 일어납니다. Git까지 가지 않아도 다음 세 가지면 충분히 든든합니다.

• Google Docs·Notion의 "버전 기록": 클릭 한 번으로 어제·지난주 버전으로 복구
• 작업 전 폴더 통째 스냅샷: Claude에게 "reports/ 폴더를 reports_backup_오늘날짜로 복사해줘"라고 한 줄
• 방금 한 작업 되돌리기: Claude Code 세션 중 Esc Esc를 두 번 연속 누르기

💡 Git에 흥미가 생기셨다면: Git은 코드뿐 아니라 어떤 파일이든 버전 관리가 됩니다. 리서치 자료, 분기별 보고서, 기획안까지 "오늘 자정의 모습"으로 되돌릴 수 있는 안전망이 생깁니다.

Git·GitHub가 왜 필요할까요

Claude Code로 작업하면 파일이 끊임없이 바뀝니다. Git이 없는 환경에서 자주 마주치는 장면들: 한 번씩 겪어보신 적이 있을 것입니다.

• 어제 잘 되던 코드가 오늘 왜 안 되는지 모르겠다
• Claude가 실수로 중요한 코드를 덮었는데 되돌릴 길이 없다
• 팀원과 같은 파일을 만지다 서로의 작업이 사라졌다
• "어제 분명 이거 고쳤는데"가 증명이 안 된다

Git은 모든 변경 기록을 저장해 언제든 과거의 어떤 상태로든 돌아갈 수 있게 합니다. GitHub는 그 기록을 클라우드에 백업하고 팀과 공유해주는 플랫폼입니다. 둘이 하나의 짝입니다.

Claude Code 사용자에게 이 한 쌍은 선택이 아닙니다. 안전망이 깔려 있어야 과감하게 시킬 수 있고, 과감하게 시킬 수 있어야 진짜 생산성이 나옵니다.

Google Drive와 Git: 결정적인 한 가지 차이

Git을 처음 쓰는 분이 가장 헷갈리는 지점이자, 한 번만 이해하면 평생 안 헷갈리는 지점입니다.

• Google Drive: 파일을 수정하면 자동으로 클라우드에 올라감
• Git: 직접 저장하고, 직접 올려야 함

이 한 줄이면 Git의 모든 동선이 풀립니다. Git은 항상 두 박자로 움직입니다.

1. 저장(Commit): 변경 내용을 내 컴퓨터에 기록
2. 올리기(Push): 기록한 내용을 GitHub에 업로드

💡 왜 두 박자인가 하면: 인터넷이 없는 환경에서도 로컬 저장이 되고, 올릴 준비가 된 변경만 골라 한 번에 묶어 올릴 수 있기 때문입니다. "저장 ≠ 즉시 공개"라는 점이 자유도이자 안전장치가 됩니다.

5분 셋업: Claude Code에 자연어로

Git 명령어를 외울 필요는 없습니다. 자연어로 한 문장이면 대부분의 Git 작업이 처리됩니다. 더 친절한 흐름이 필요하면 /plugin에서 Git 관련 플러그인을 찾아 설치할 수도 있습니다.

처음 한 번만

"이 폴더를 Git으로 관리하고 GitHub에 올릴 수 있게 셋업해줘"

이 한 줄이 안에서 처리하는 흐름은 다음과 같습니다.

• Git 설치 확인 (없으면 설치 안내)
• GitHub CLI(gh) 설치 확인
• GitHub 로그인 (브라우저가 자동으로 열립니다)
• 프로젝트 폴더 설정: 새 프로젝트면 새 저장소 생성, 기존 프로젝트면 GitHub에서 가져오기, 현재 폴더면 그 자리를 저장소로

이미 처리된 단계는 자동으로 건너뜁니다. 처음부터 끝까지 5분이면 충분하고, 한 번 끝내면 다음부터는 셋업을 다시 신경 쓸 일이 거의 없습니다.

매일 쓰는 동작 세 가지

동작 ① · 저장하기 (Commit)

"저장해줘"

바뀐 파일 목록을 보여주고, 짧은 설명(커밋 메시지)을 묻습니다. 메시지는 "6개월 뒤의 내가 이 줄을 봐도 무슨 작업인지 알 수 있게" 쓰는 것이 핵심입니다.

예시:
  "로그인 페이지 디자인 수정"
  "버그 수정: 비밀번호 검증 오류"

저장이 끝나면 안내가 따라옵니다.

✅ 저장 완료!
아직 내 컴퓨터에만 있습니다.
GitHub에 올리려면 "올려줘"라고 하세요.

동작 ② · GitHub에 올리기 (Push)

"올려줘"

저장된 내용을 GitHub로 업로드합니다. 끝나면 저장소 링크가 같이 따라옵니다. 자주 만나는 오류는 자동으로 처리됩니다.

• 팀원이 먼저 올린 내용과 겹치면 자동으로 합쳐서 올리기 (--rebase)
• SSH 인증 오류는 HTTPS로 자동 전환
• 처음 푸시하는 브랜치는 upstream을 자동으로 설정

동작 ③ · 검토 요청하기 (Pull Request)

팀원에게 검토를 받고 싶을 때:

"검토 요청해줘"

자동 처리 흐름은: Branch 생성 → 저장 & 업로드 → PR 생성 → 링크 제공 → 원래 작업 상태로 복귀입니다. PR 본문도 변경 요약을 자동으로 채워주기 때문에, "무슨 변경인지 한 줄"만 덧붙이시면 됩니다.

자연어 ↔ Git 명령어 매핑

하고 싶은 것                    이렇게 말하세요
─────────────────────────────────────────────────
처음 설정                       "깃 시작해줘"
지금 상태 확인                   "지금 어떤 상태?"
                               "뭐가 바뀌었어?"
저장하기 (Commit)               "저장해줘"
                               "세이브해줘"
GitHub에 올리기 (Push)          "올려줘"
                               "업로드해줘"
검토 요청하기 (PR)               "검토 요청해줘"
                               "팀원한테 보여주고 싶어"
용어 설명 부탁                   "commit이 뭐야?"
                               "push랑 commit 차이 알려줘"

💡 더 구조화된 Git 온보딩이 필요하시면 /plugin에서 Git 관련 플러그인을 둘러보세요. 같은 흐름을 슬래시 명령으로 묶거나, 팀 컨벤션(브랜치 네이밍·커밋 메시지)까지 자동화하는 형태도 있습니다.

Git 용어 빠른 해설: 비유로 외우기

처음 보는 단어가 나오면 잠깐 펼쳐 보세요. 외우지 마시고 그때그때 다시 와서 보는 습관이 더 빠릅니다.

• Repository: 프로젝트 저장소 → "GitHub의 공유 폴더"
• Commit: 저장하기 → "파일을 포장해 라벨 붙이기"
• Push: 올리기 → "포장한 파일을 택배로 GitHub에 보내기"
• Pull: 가져오기 → "GitHub에서 최신 내용 받아오기"
• Branch: 작업 공간 → "원본을 건드리지 않는 개인 작업실"
• Pull Request: 검토 요청 → "Google Docs '수정 제안' 모드"
• Merge: 합치기 → "수정 제안을 원본에 반영"
• Clone: 복사해서 가져오기 → "공유 폴더를 내 컴퓨터로 다운로드"

모르는 용어를 만나면 그 자리에서 곧장 물어보세요.

"push랑 commit 차이가 뭐야?"

하루 루틴: 이대로 따라가도 충분합니다

[ 시작 ]
  claude 실행 → "깃 시작해줘"  (첫 날 한 번만)

[ 작업 중간 ]
  코드 수정 → "저장해줘" → "올려줘"
  큰 작업 전엔 "지금 어떤 상태?"로 점검

[ 마무리 ]
  "저장해줘" → "올려줘"   (반드시 두 박자 모두)

[ 팀 협업 ]
  기능 완성 → "검토 요청해줘" → PR 링크 공유

이 루틴만 지키시면 Claude Code로 만진 모든 작업이 안전하게 보관됩니다. 망가져도 어제 자정으로 돌아갈 수 있고, "어제 이거 고쳤는데"가 증명되는 환경이 만들어집니다.

.gitignore: API 키를 GitHub에 올리지 않기

Git 입문에서 가장 흔하고 가장 비싼 실수가 .env에 들어 있는 API 키를 그대로 올리는 것입니다. 공개 저장소에 한 번 올라간 키는 회수가 사실상 불가능합니다.

Claude Code에 "저장해줘"라고 하면 프로젝트 타입을 감지해 .gitignore를 자동으로 만들어 줍니다. 이미 있으면 건드리지 않습니다. 직접 작성하시려면 다음 정도가 시작점입니다.

# .gitignore 예시
.env
.env.local
node_modules/
.DS_Store

⚠️ 실수로 키를 올리셨다면: 저장소에서 지우는 것보다 해당 서비스에서 키를 즉시 회수(revoke)·재발급하는 것이 먼저입니다. 캐시·미러·포크에 이미 흩어져 있다고 보시는 편이 안전합니다.

위험한 Git 명령은: 이렇게 풀어 말하세요

Git은 강력하지만 몇몇 명령은 작업물을 통째로 지울 수 있습니다. Claude에게도 다음과 같이 "안전 안내장"을 깔아두는 습관이 좋습니다.

• "전부 되돌려" → "변경 내용을 먼저 보여주고, 어떤 파일을 되돌릴지 물어봐줘"
• git checkout . → "git restore .을 쓰되 실행 전에 git diff부터 보여줘"
• git reset --hard → "커밋되지 않은 변경이 있는지 확인하고, 백업 브랜치를 만든 뒤 진행해줘"
• git push --force → "force push가 필요한 이유와 영향받는 브랜치를 먼저 설명해줘"

요즘 Git에서는 파일 복구에 git restore가 의도를 더 분명히 드러냅니다. 명령어를 외우는 것이 어려우시면 Claude에게 이렇게 풀어 말해도 같은 결과가 나옵니다.

"방금 만진 파일 중 src/auth/login.js만 이전 상태로 되돌리고 싶어.
먼저 diff를 보여주고, 되돌려도 되는지 확인받은 뒤 진행해줘."

💡 직접 Git 명령을 쓰고 싶으시면 Claude에 그대로 말씀하셔도 됩니다: git commit·git push를 그 자리에서 실행해줍니다. Git이 낯선 분은 자연어("저장해줘", "올려줘")로 시작해 익숙해진 뒤 정식 명령으로 넘어가는 흐름을 권합니다. 두 길은 결국 같은 자리에 도착합니다.

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

처음 며칠 사이 마주치는 벽들은 거의 정해져 있습니다. 이 섹션은 그 벽들을 한 자리에 모아둔 응급실 같은 페이지입니다. 처음부터 다 읽지 마시고, 막히는 순간에 와서 검색하듯 쓰세요.

케이스 ①: claude 명령을 못 찾는다 (command not found)

보이는 화면

$ claude
zsh: command not found: claude

무엇이 일어난 걸까

설치는 됐는데 셸이 실행 파일 위치를 모르는 상태입니다. 다음 셋 중 하나로 풀립니다.

풀이 ㉠: 네이티브 인스톨러 다시 (가장 깔끔)

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

설치 후 터미널 창을 완전히 닫았다 새로 여세요.

풀이 ㉡: PATH 확인

which claude         # 설치 위치 확인
echo $PATH           # 현재 PATH 확인

~/.local/bin이 PATH에 없다면 .zshrc나 .bashrc에 한 줄 추가:

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

추가 후 source ~/.zshrc로 적용하세요.

풀이 ㉢: 진단 명령

claude doctor

케이스 ②: 로그인이 막힐 때

어떤 증상으로 보이나

• 브라우저가 안 열린다
• 인증 화면에서 멈춘다
• 로그인했는데도 인증 오류가 뜬다

풀이 흐름

단계 ㉠ · 브라우저 팝업이 안 뜨면

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

단계 ㉡ · 로그아웃 후 재인증

# Claude Code 안에서
> /logout

# 또는 터미널에서 (인증·세션 정보는 ~/.claude.json에 저장됩니다)
claude auth logout
claude

단계 ㉢ · 그래도 안 된다면 진단부터

> /doctor

단계 ㉣ · 최후의 수단 (모든 설정 삭제)

# ⚠️ 위 단계로 안 풀릴 때만
rm ~/.claude.json
rm -rf ~/.claude/
claude

⚠️ 이 명령은 모든 설정·세션·플러그인 정보를 지웁니다. 먼저 /doctor부터 시도하세요. 가능하면 삭제 전에 cp ~/.claude.json ~/.claude.json.backup으로 백업을 남기시고요. 프로젝트 폴더의 .claude/와 홈 디렉터리의 ~/.claude/를 헷갈리지 마세요.

케이스 ③: 응답이 너무 느리다

대화가 길어질수록 Claude가 처리할 짐(컨텍스트)이 무거워집니다. 정상 동작이지만, 작업 흐름엔 방해가 됩니다.

풀이 네 가지: 가벼운 순서로

• /compact: 가장 효과적. 대화를 압축해 속도를 회복합니다.
• /clear: 완전히 새로 시작해도 되는 경우.
• 모델 변경: /model로 Sonnet 또는 Haiku로. Opus가 모든 작업에 필요한 건 아닙니다.
• MCP 정리: /mcp에서 안 쓰는 외부 연결을 비활성화.

케이스 ④: 원하는 대로 안 고쳐준다

대부분 다음 셋 중 하나입니다: 지시가 모호하거나, 프로젝트 맥락이 부족하거나, 같은 흐름이 길어져 혼란이 쌓였거나.

풀이 ㉠ · 지시를 좁혀 쓰기

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

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

풀이 ㉡ · 반복되는 요구를 CLAUDE.md로 이관

같은 말을 두 번 이상 했다면 CLAUDE.md로 옮길 신호입니다.

> /memory

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

풀이 ㉢ · 두 번 같은 실수가 반복되면 새 세션

> /clear

새 세션에서 더 좁은 지시로 다시 시작하세요.

케이스 ⑤: 파일을 잘못 고친 것 같다

풀이 ㉠ · Claude Code 안에서 되감기 (가장 빠름)

Esc 두 번    또는    > /rewind

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

풀이 ㉡ · git으로 복구

git diff                                # 변경 내용 확인
git checkout -- src/auth/login.js       # 특정 파일만 되돌리기
git checkout .                          # 모든 변경 취소

풀이 ㉢ · 큰 작업 직전엔 git commit을 습관처럼

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

케이스 ⑥: 비용이 갑자기 부풀었다

흔한 원인 네 가지를 먼저 짚어보세요.

• 대화가 길어져 컨텍스트가 두꺼워졌다
• 큰 폴더 전체를 맥락 없이 읽혔다
• Opus를 계속 켜둔 채 일했다
• 여러 세션·서브에이전트를 동시에 돌렸다

지금 한도부터 보기

> /usage

세션 비용·플랜 한도·활동 통계를 한 번에. /cost·/stats도 같은 명령의 alias입니다.

줄이는 네 가지 길

• /compact를 호흡처럼: 컨텍스트가 짧아지면 비용이 같이 줄어듭니다
• 단순 작업은 Sonnet·Haiku로: /model로 즉시 전환
• 큰 폴더 전체 대신 필요한 파일만 @파일명으로
• 무관한 작업 사이엔 /clear로 새로

자동화를 돌릴 때는 예산 한도

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

케이스 ⑦: 권한 요청이 너무 자주 뜬다

풀이 ㉠ · 자주 쓰는 도구는 항상 허용

> /permissions

권한 화면에서 특정 도구를 Always Allow로 설정.

풀이 ㉡ · 파일 수정 자동 허용

Shift+Tab → Auto-Accept Edit Mode

현재 세션 동안 파일 수정 요청을 자동 승인합니다.

풀이 ㉢ · 권한 모드를 글로 외워두기

• 기본 모드 (Ask): 첫 사용·중요한 작업에 안전
• Plan Mode: 파일 수정 없이 계획만 검토
• Auto-Accept: 신뢰 가능한 작업에서 속도 우선

⚠️ --dangerously-skip-permissions는 모든 권한 확인을 건너뜁니다. 격리 컨테이너가 아니면 쓰지 마세요. 시스템 파일을 실수로 건드릴 위험이 있습니다.

케이스 ⑧: 한글이 깨진다

터미널이 UTF-8을 쓰지 않을 때 발생합니다.

macOS · Linux

.zshrc 또는 .bashrc에:

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

추가 뒤 source ~/.zshrc로 적용합니다. 터미널 앱별 설정도 한 번 봐주세요.

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

Windows · WSL

sudo locale-gen ko_KR.UTF-8

케이스 ⑨: 맥락을 잃었을 때

세션이 끊기거나 터미널을 닫았다 다시 연 상황입니다.

풀이 ㉠ · 이전 세션 이어가기

claude --continue                       # 가장 최근 세션
claude --resume                         # 목록에서 선택
claude --resume housing-research-2026Q2 # 이름으로 직행

풀이 ㉡ · 중요한 세션은 미리 이름을 붙여두기

> /rename housing-research-2026Q2

풀이 ㉢ · 끊겨도 살아남을 정보는 CLAUDE.md에

# 현재 진행 중인 작업
- 목표: 2026Q1 시장 경쟁 보고서 완성
- 완료: A사·B사 분석
- 진행 중: C사 분석, 비교표 작성
- 참고 폴더: research/competitors/

케이스 ⑩: 코드가 예상보다 너무 많이 바뀌었다

"간단히 수정해달라" 했는데 Claude가 관련 없는 파일까지 한 번에 손댄 상황입니다.

• ① 즉시 멈추기: Ctrl+C 또는 Esc로 중단
• ② 이전으로 되감기: Esc Esc 또는 /rewind
• ③ git으로 확인·복구

git status                # 변경 파일 목록
git diff                  # 변경 내용 상세
git checkout -- 파일경로  # 특정 파일만 복구
git checkout .            # 전부 취소

• ④ 예방책으로 Plan Mode: 큰 작업 전엔 Shift+Tab 두 번 또는 claude --permission-mode plan
• ⑤ 지시를 좁히기: "auth.js의 login 함수만 손대고 다른 파일은 건드리지 마", "리팩토링은 하지 말고 버그만 고쳐줘"

케이스 ⑪: 일부만 고쳐달라 했는데 전체를 새로 썼다

문서 일부 수정을 부탁했는데 처음부터 다시 쓴 경우입니다. 셋이면 됩니다.

• 즉시 Esc Esc 또는 /rewind로 되감기
• 범위를 더 좁혀 다시: "도입부 두 번째 단락에서 '하지만'으로 시작하는 문장만 부드럽게. 나머지는 건드리지 마"
• 큰 작업이면 Plan Mode로 먼저: Claude가 "어디를 어떻게 바꿀지" 보여주는 단계를 먼저 거치세요

케이스 ⑫: 한국어로만 검색해서 정보가 빈약하다

검색 언어를 명시적으로 일러두시면 됩니다.

"영어·한국어 자료를 모두 검색해서 정리해줘"
"주로 영어 자료를 찾되, 핵심은 한국어로 요약해줘"
"글로벌 트렌드는 영어로, 국내 현황은 한국어로 조사해줘"

언어를 지정하지 않으면 한국어 대화 맥락을 따라 한국어 위주로 찾는 경향이 있습니다.

케이스 ⑬: AI가 추천한 패키지가 의심스럽다 🖥️ 개발자

슬롭스쿼팅(Slopsquatting)이란

AI 모델이 존재하지 않는 패키지를 자신 있게 추천(hallucination)할 때, 공격자가 그 이름으로 악성 코드를 담은 패키지를 npm·PyPI에 미리 올려두는 공격 패턴입니다. Claude가 react-auth-helper를 추천했지만, 실제로 그것이 없거나 같은 이름의 악성 패키지가 등록돼 있을 수 있습니다.

설치 전 점검 네 가지

• npm 정보 먼저

npm info 패키지이름   # 다운로드 수·최근 업데이트·의존성 확인

배포된 지 며칠 안 됐거나 다운로드가 극소수면 잠시 멈추고 의심해보세요.

• 출처 함께 요청

"이 패키지가 정말 존재하는지 npmjs.com 링크와 GitHub 저장소 주소도 함께 알려줘"

• 잘 알려진 것 우선: 비슷한 기능이라면 GitHub star 많고 오래된 패키지, Anthropic·Microsoft·Vercel·Meta 같은 검증된 조직 우선
• 설치 후 진입점 검토

cat node_modules/패키지명/index.js | head -100

케이스 ⑭: Claude 작업 후 보안이 걱정될 때 🖥️ 개발자

커밋 전 8가지 체크포인트

보안 체크리스트:
□ ① 하드코딩된 시크릿 없는가? (API 키·비밀번호·토큰)
□ ② 사용자 입력이 검증되는가? (SQL 인젝션·XSS)
□ ③ 동적 코드 실행 함수 사용 없는가? (eval 계열)
□ ④ 파일 경로가 사용자 입력을 그대로 안 쓰는가? (path traversal)
□ ⑤ 에러 메시지에 내부 구조가 노출되지 않는가?
□ ⑥ 외부 URL 요청에 도메인 검증이 있는가? (SSRF)
□ ⑦ 의존성 패키지가 갑자기 추가되지 않았는가?
□ ⑧ 기존 인증·권한 로직이 우회되지 않는가?

git add -p로 줄 단위 검토

git add .은 Claude가 만진 모든 변경을 한꺼번에 스테이징합니다. 대신 git add -p를 쓰면 변경 덩어리(hunk)마다 포함 여부를 골라 들일 수 있습니다.

git add -p
# y → 포함  n → 제외  s → 더 작게 분리  d → 이 파일 나머지 제외  q → 종료

의심해야 할 작업 패턴: 글로 외워두기

• 요청하지 않은 파일도 함께 수정됨 → 의도치 않은 사이드 이펙트 가능
• 기존 코드를 통째로 대체하면서 주석은 없음 → 무엇이 바뀌었는지 파악 어려움
• .env·package.json 같은 설정 파일이 갑자기 수정됨 → 환경변수·의존성 변화 점검
• 테스트 파일만 삭제 또는 비활성화 → 기존 검증 우회 가능성
• 처음 보는 패키지 추가 → 슬롭스쿼팅 의심 (케이스 ⑬ 참고)
• 빈 catch 블록으로 에러 처리 감쌈 → 예외가 조용히 사라짐

⚠️ 원칙: Claude가 만든 코드도 외부에서 받은 코드처럼 검토하세요. AI가 썼다고 안전이 보장되는 것은 아닙니다.

한 페이지 예방 체크리스트

[ 시작 전 ]
□ 작업 폴더로 이동했나? (cd ~/Documents/my-project)
□ 중요 작업이면 git commit 했나?
□ CLAUDE.md에 프로젝트 규칙이 있나?

[ 작업 중 ]
□ 지시가 충분히 좁혀져 있나?
□ 한 번에 너무 많이 시키지 않았나?
□ 호흡이 길어졌으면 /compact 했나?
□ 이상하면 즉시 Ctrl+C로 멈췄나?

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

💡 풀리지 않으면: 안에서 /doctor로 설치 진단을, /bug로 Anthropic에 직접 제보하실 수 있습니다.

13. 디버깅: 에러를 만났을 때

에러가 나도 당황하지 않는 3단계 워크플로우.

빨간 글씨로 가득 찬 터미널 앞에서 머리가 하얘진 경험은 누구나 한 번쯤 있습니다. 처음 며칠은 저도 에러 메시지의 첫 줄만 보고 검색창부터 열었는데, 정작 답은 화면 아래쪽에 더 많이 적혀 있었습니다. 당황하지 않는 게 절반이고, 나머지 절반은 재현 → 가설 → 검증이라는 정해진 박자에 몸을 맡기는 일입니다. 이 박자를 한 번만 손에 익히면 다음부터는 에러가 무서운 신호가 아니라 그냥 다음 단계 안내문처럼 읽힙니다.

1단계: 에러가 났을 때: 바로 보여주기

에러가 나면 그대로 Claude에게 보여주세요. 메시지를 이해할 필요는 없습니다.

방법 1: 텍스트 복사 붙여넣기

> 이런 에러가 납니다:
  TypeError: Cannot read property 'name' of undefined
  at UserList.render (src/components/UserList.js:23)

방법 2: 스크린샷 붙여넣기

에러 화면을 캡처해 Ctrl+V (Mac: Cmd+V)로 대화창에 바로 붙여넣으세요. Claude가 이미지를 읽고 분석합니다.

방법 3: 상황을 설명하기

에러 메시지가 없거나 캡처하기 어려울 땐, 뭘 하다가 어떤 증상이 나왔는지 구체적으로 설명하세요.

> 로그인 버튼을 누르면 화면이 새하얘지면서 아무것도 안 나와.
  아까 회원가입 기능 추가한 뒤부터 이러기 시작했어.

> pnpm dev로 서버 시작하면 처음엔 되는데, 상품 목록 페이지로 이동하면 터미널에 빨간 글씨가 나와.

> 어제까지는 정상이었는데 오늘 파일 3개 수정한 뒤부터 빌드가 안 돼.
  뭘 바꿨는지는 기억이 안 나.

좋은 설명의 공통점은 "언제부터 / 뭘 하면 / 어떤 증상이". 이 세 가지가 들어가면 Claude가 훨씬 정확히 원인을 찾습니다.

💡 팁: 에러 메시지가 영어로 길게 나와도 겁먹지 마세요. 통째로 복붙하면 됩니다. 해석은 Claude가 합니다.

2단계: "안 되는데 뭐가 문제인지 모르겠어요"

에러 메시지도 없이 그냥 안 될 때가 제일 답답합니다. 이럴 때 쓰는 방법들입니다.

되돌려서 원인 찾기

> /rewind

동작하던 시점으로 돌아갑니다. "아까는 됐는데 지금은 안 돼"라면 이게 가장 빠릅니다.

체크포인트로 직전 상태 복구

Esc Esc (두 번)를 누르면 Claude가 마지막 수정 직전으로 돌립니다.

뭘 바꿨는지 확인하기

> 방금 뭐 바꿨는지 보여줘

Claude가 변경 내역(diff)을 보여줍니다. 어디서 문제가 생겼는지 단서를 찾을 수 있습니다.

단계별로 좁혀서 찾기

> 하나씩 되돌려보면서 어디서 깨지는지 찾아줘

Claude가 변경사항을 하나씩 되돌리며 문제 지점을 찾아줍니다. 여러 파일을 한꺼번에 수정한 뒤 문제가 났을 때 특히 유용합니다.

실제 예제: 흰 화면 버그를 끝까지 고치기

아래처럼 재현 → 관찰 → 최소 수정 → 검증 순서로 진행하면 Claude가 훨씬 덜 헤맵니다.

1. 재현 조건 전달

상품 목록 페이지에서 새로고침하면 흰 화면이 나와.
개발 서버는 켜져 있고, 브라우저 콘솔에는 아래 에러가 보여:

TypeError: Cannot read properties of undefined (reading 'map')
at ProductList (src/components/ProductList.tsx:23)

먼저 원인을 추정하지 말고 관련 파일을 읽고 재현 경로를 정리해줘.

2. 관찰 결과를 요청

수정 전에 원인을 2~3개 가설로 나누고,
각 가설을 확인하려면 어떤 파일/명령을 봐야 하는지 알려줘.

Claude가 바로 고치기보다 원인을 좁히게 만드는 단계입니다. 특히 상태값, API 응답, 렌더링 순서 문제는 여기서 많이 잡힙니다.

3. 최소 수정만 지시

가장 가능성 높은 원인 하나만 고쳐줘.
UI 구조 변경이나 리팩토링은 하지 말고,
흰 화면을 막는 최소 수정만 적용해줘.

4. 검증까지 요구

수정 후 다음을 확인해줘.
1. 개발 서버에서 상품 목록 페이지가 렌더링되는지
2. 콘솔 오류가 사라졌는지
3. 빈 상품 목록일 때도 깨지지 않는지

버그 수정 요청의 핵심은 "고쳐줘"가 아니라 어떤 증상이 없어져야 성공인지까지 알려주는 것입니다.

3단계: "고쳐줬는데 또 같은 문제야"

같은 에러가 반복되면 접근 방식을 바꿔야 합니다.

CLAUDE.md에 주의사항 기록하기

> CLAUDE.md에 "이 프로젝트에서 날짜는 항상 dayjs를 사용할 것" 추가해줘

한 번 겪은 문제의 원인을 CLAUDE.md에 적어두면, Claude가 다음부터 같은 실수를 하지 않습니다. 프로젝트의 규칙을 쌓아가는 것입니다.

이전 에러와 비교 요청하기

> 이전에 이런 에러가 났었는데, 같은 원인인지 확인해줘

같은 증상이라도 원인은 다를 수 있습니다. Claude에게 비교 분석을 요청하세요.

새 세션으로 다시 시작하기

대화가 길어지면 Claude가 이전 맥락에 끌려 같은 방향만 시도할 수 있습니다.

# 현재 세션 종료
/quit

# 새 세션 시작
claude

새 세션에선 핵심 컨텍스트만 다시 전달하세요.

> @CLAUDE.md 읽고, src/auth/login.js에서 토큰 만료 에러가 반복되는데 고쳐줘

비개발자가 흔히 하는 실수

"전체 다 고쳐줘"

범위가 넓으면 Claude도 헤맵니다. 범위를 좁혀서 말하세요.

에러를 무시하고 다음 기능 요청

에러 난 상태에서 새 기능을 시키면, 새 코드가 깨진 코드 위에 쌓입니다. 에러부터 고치고 다음으로 넘어가세요.

# 비추천
> (에러 무시하고) 이제 결제 기능 만들어줘

# 추천
> 이 에러 먼저 고쳐줘
(해결 후)
> 이제 결제 기능 만들어줘

같은 에러에 같은 방법 반복

Claude가 같은 방법을 두세 번 시도해도 안 되면, 방향을 바꿔달라고 말하세요.

> 이 방법은 안 되는 것 같아. 다른 방법으로 해봐
> 아예 다른 라이브러리를 써서 해결해봐

디버깅 프롬프트 템플릿

막힐 때는 아래 템플릿을 그대로 채워 넣으세요.

증상:
-

언제부터:
-

재현 방법:
1.
2.
3.

에러 메시지:
```text
여기에 전체 에러 붙여넣기
```

요청:
먼저 관련 파일을 읽고 원인 가설을 3개 이하로 정리해줘.
그 다음 가장 작은 수정부터 적용하고, 수정 후 검증 명령까지 실행해줘.

한 줄 요약

에러가 나면 보여주고 → 원인 모르면 되돌리고 → 반복되면 기록하고 새로 시작하세요.

14. 알아두면 유용한 기능들

Claude Code를 더 편하게 쓰게 해주는 기능들을 모았습니다.

출처: Permission Modes — Anthropic 공식 문서

입력을 편하게

이미지 입력

에러 스크린샷, UI 디자인 시안 같은 것을 Claude에게 바로 보여줄 수 있습니다.

• Ctrl+V: 클립보드 이미지 붙여넣기 (macOS에서도 Cmd+V가 아닌 Ctrl+V)
• 드래그 앤 드롭: 이미지 파일을 터미널 창으로 끌어다 놓기
• 파일 경로: "이 이미지 분석해줘: /path/to/image.png"
• 지원 형식: JPEG, PNG, GIF, WebP (최대 5MB)

> 이 스크린샷에서 에러 원인 찾아줘 [Ctrl+V로 붙여넣기]
> @design-mockup.png 이 시안대로 만들어줘

언제 특히 좋습니까?

좋은 요청 예시:

> @screenshot.png를 보고 모바일에서 텍스트가 겹치는 원인을 찾아줘.
  바로 수정하지 말고 어떤 CSS가 문제인지 먼저 설명해줘.

주의할 점:

• 민감 정보가 보이는 스크린샷은 먼저 가리세요.
• 이미지 하나만 던지지 말고 "무엇을 봐야 하는지"를 함께 말하세요.

음성 입력 (/voice)

타이핑 대신 말로 지시할 수 있습니다.

• /voice 입력 후 스페이스바를 누른 채 말하기
• 한국어 포함 20개 언어 지원
• 음성과 타이핑 혼합 사용 가능
• Beta 기능 (점진적 확대 중)

💡 긴 설명을 타이핑하기 귀찮을 때 특히 유용합니다.

음성 입력은 초안 설명에 좋고, 정확한 파일명·명령어·코드 조각은 타이핑으로 보완하는 편이 안전합니다.

말로 설명:
"로그인 화면이 너무 복잡해서 줄이고 싶어. 이메일 로그인만 남기고 소셜 로그인은 아래로 빼고 싶어."

타이핑으로 보완:
"수정 대상은 src/app/login/page.tsx만. 다른 파일은 건드리지 마."

실수 복구

체크포인트 (Esc Esc)

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

• Esc 키를 두 번 누르면 직전 상태로 복구
• 별도 설정 없이 자동 동작
• git을 몰라도 쓸 수 있는 가장 빠른 복구 방법

이럴 때 바로 쓰세요:

• Claude가 요청하지 않은 파일까지 수정하기 시작함
• 디자인을 크게 바꿨는데 마음에 들지 않음
• 에러를 고치려다 더 많은 에러가 생김

Esc Esc는 직전 단계 복구에 가깝습니다. 여러 단계 전으로 돌아가려면 /rewind가 더 적합합니다.

/rewind

대화와 코드를 이전 시점으로 되돌립니다.

• 여러 단계를 거슬러 올라가야 할 때 유용
• Esc Esc가 직전 한 단계 복구라면, /rewind는 원하는 시점까지 복구

> /rewind
→ 시점 목록이 나타나면 원하는 곳을 선택

추천 사용법:

> /rewind
> "로그인 UI 변경 전 시점으로 돌아가고 싶어"

되돌린 뒤에는 바로 새 작업을 시키지 말고, 먼저 현재 상태를 확인하세요.

> 지금 변경된 파일이 남아 있는지 확인해줘

세션이 길어질 때

자동 압축 (auto-compact)

대화가 길어지면 Claude가 오래된 내용을 알아서 정리합니다.

• 별도 설정 없이 자동 동작
• CLAUDE.md에 적어둔 규칙은 삭제되지 않고 보존
• 수동으로 하려면 방향을 지정할 수 있습니다.

> /compact API 변경 중심으로 정리해줘

자동 메모리 (Auto Memory)

Claude가 작업 중 중요한 정보를 자동으로 기억합니다.

• CLAUDE.md와는 별개로 자동 동작
• 세션이 바뀌어도 이전 작업 맥락을 기억
• /memory로 저장된 메모리를 확인/편집할 수 있습니다

자동 메모리에만 의존하지 마세요. 프로젝트에서 반드시 지켜야 하는 규칙은 CLAUDE.md에 직접 적는 편이 더 안정적입니다.

Extended Thinking (/effort)

복잡한 문제에서 Claude가 더 깊이 생각하게 합니다.

• 기본적으로 켜져 있음 (Opus 4.7 기본값은 xhigh, Sonnet 4.6/Opus 4.6 기본값은 high)
• 사용 가능한 레벨: low · medium · high · xhigh(Opus 4.7) · max
• /effort high: 균형 잡힌 추론 (대부분의 작업에 적합)
• /effort low: 짧고 단순한 질문에 빠르게 응답
• /effort (인자 없음): 인터랙티브 슬라이더
• 프롬프트에 "ultrathink"를 넣으면 해당 턴만 더 깊이 사고하라는 힌트가 추가됩니다

언제 바꿉니까?

깊게 생각하게 한다고 항상 좋은 것은 아닙니다. 단순 작업에는 느려질 뿐입니다.

안전하게 쓰기

권한 모드 (Permission Modes)

Claude가 파일을 수정하거나 명령을 실행하기 전에 확인을 받습니다.

• 세션 안에서: /permissions로 전환
• CLI 시작 시: claude --permission-mode plan (또는 acceptEdits 등)
• 처음엔 default로 쓰면서 익숙해지세요

이런 것도 됩니다

Computer Use: Claude가 화면을 보고 마우스/키보드를 직접 조작합니다. 앱 테스트, GUI 자동화에 쓰입니다. (Research Preview, macOS)

Remote Control: 터미널에서 시작한 작업을 폰이나 다른 기기에서 이어갈 수 있습니다. QR 코드 스캔으로 연결합니다.

Chrome 연동: Claude가 Chrome 브라우저를 직접 제어합니다. 웹 테스트, 데이터 추출, 폼 자동 입력에 쓰입니다.

예약 작업 (/loop): 특정 프롬프트를 정해진 간격으로 반복 실행합니다. 모니터링, 정기 체크에 유용합니다.

기능별 빠른 선택표

기능을 많이 아는 것보다, 문제가 생겼을 때 어떤 기능을 꺼낼지 아는 게 중요합니다.

15. 프롬프트 잘 쓰는 법

결과 품질의 80%는 프롬프트에서 갈립니다. 모델은 그 다음입니다.

같은 모델, 같은 코드베이스인데 어떤 날은 한 방에 끝나고 어떤 날은 다섯 번을 고쳐도 안 맞는 경험이 있으실 겁니다. 저는 그 차이가 모델 버전이나 운에 있다고 한참 오해했는데, 결국 차이는 프롬프트의 정보 밀도였습니다. 맥락 · 범위 · 출력 형식 · 예시 네 가지를 한 줄씩만 더 적어주면, 같은 모델이 전혀 다른 사람처럼 일합니다. 외울 건 없고, 다음 그림 한 장만 머릿속에 두면 충분합니다.

Claude Code를 처음 만진 사람과 두 달 쓴 사람의 차이는 모델 선택이 아니라 프롬프트 한 줄에서 나옵니다. 이 섹션은 그 한 줄을 어떻게 쓰는지를 정리합니다.

좋은 프롬프트의 4요소

1) 맥락(Context): 왜, 무엇을 위해

Claude는 당신의 머릿속을 모릅니다. 같은 코드라도 누가 보는지에 따라 답이 달라집니다.

나쁜 예) 이 함수 고쳐줘.
좋은 예) 이 함수는 결제 실패율을 줄이려고 만든 건데,
        timeout이 자주 나서 retry 로직이 필요해.

2) 범위(Scope): 어디까지 손대도 되나

범위를 안 정하면 Claude는 "관련 있어 보이는" 곳까지 다 건드립니다. 그것이 바로 작업이 산으로 가는 가장 흔한 원인입니다.

좋은 예) src/auth/login.ts 안의 validateEmail 함수만 수정해.
        다른 파일은 절대 건드리지 마.

3) 예시(Examples): 입력과 기대 출력

말로 100줄 설명하는 것보다 입력 1개 + 출력 1개가 더 정확합니다.

입력: "kim.user@example.com"
기대 출력: { valid: true, domain: "example.com" }

입력: "wrong@email"
기대 출력: { valid: false, reason: "missing TLD" }

4) 검증 요청(Verification): 어떻게 확인하나

"테스트도 같이 짜줘", "변경 후 lint 돌려서 통과시켜줘"를 마지막에 붙이는 것만으로 결과 품질이 한 단계 올라갑니다.

좋은 예) 수정 후 npm test 돌려서 통과시키고,
        실패하면 어디가 문제인지 알려줘.

Before / After 비교

자주 쓰는 프롬프트 템플릿

템플릿 1: 새 기능 추가

[맥락] 이 프로젝트는 ___ 를 만드는 중이고
[목표] 지금 ___ 기능을 추가하고 싶어.
[범위] 수정 대상은 ___ 파일만.
[예시] 입력 ___ 일 때 ___ 가 나와야 해.
[검증] 추가 후 ___ 테스트 돌려서 통과시켜줘.

템플릿 2: 버그 수정

[증상] ___ 했더니 ___ 가 일어남.
[기대] 원래는 ___ 가 일어나야 함.
[재현] ___ 단계로 재현 가능.
[제약] ___ 파일/함수 안에서만 고치고,
       동작 변경 없는 리팩터링은 하지 마.

템플릿 3: 리팩터링

[대상] ___ 파일의 ___ 부분만.
[목적] 가독성 / 성능 / 테스트 용이성 중 어느 것?
[금지] 외부 인터페이스(함수 시그니처) 변경 금지.
[검증] 기존 테스트가 그대로 통과해야 함.

템플릿 4: 문서·리서치 (비개발자용)

[맥락] 나는 ___ 분야에서 ___ 자료를 찾고 있어.
[입력] @file1.pdf, @file2.md 를 참고해.
[형식] 결과는 ___ 표 / ___ 단락 / ___ 슬라이드 개요 중 하나로.
[필터] ___ 는 빼고, ___ 만 남겨줘.
[길이] 한국어 기준 ___자 이내.

안티패턴: 이렇게 쓰면 망합니다

한 발짝 더: 입력 보강

프롬프트만으로 부족하면 입력을 함께 던지세요. 14번 섹션에서 다룬 기능들과 자연스럽게 이어집니다.

실전 예시: 같은 일을 다르게

상황: "주식 보유 종목 일일 리포트를 만들고 싶다"

모호한 버전 (1점)

주식 종목 정리 좀 해줘.

보통 버전 (5점)

@portfolio.csv 읽고 보유 종목 정리해줘. 표로 만들어줘.

4요소 적용 버전 (9점)

[맥락] 나는 매일 아침 보유 종목을 빠르게 훑어보고 싶어.
[입력] @portfolio.csv 에 종목코드와 보유수량이 있어.
[범위] 외부 API는 호출하지 말고, 파일에 있는 데이터만 사용해.
[형식] 마크다운 표 1개:
       | 종목명 | 코드 | 수량 | 평균 매입가 | 메모 |
       종목명/코드 알파벳순 정렬.
[필터] 수량 0인 종목은 제외.
[검증] 표 아래에 "총 종목 수: N개" 한 줄 추가해서
       시각적으로 확인할 수 있게.

같은 도구, 같은 모델인데 결과 차이는 분명합니다.

한 줄 요약

Claude는 똑똑한 신입사원입니다. 신입에게 일을 맡기듯 설명하면, 신입처럼 일을 해냅니다.

16. Plan Mode & 안전한 실수 복구

"되돌릴 수 있다"는 안전감이 실험 속도를 만듭니다.

저도 처음에는 "일단 시키면 알아서 잘하겠지" 하고 큰 변경을 통째로 던졌다가, 한참 뒤에 폴더 구조가 엉켜 있는 걸 보고 한숨을 쉰 적이 한두 번이 아닙니다. 그때 깨달은 건 단순합니다. 실행 전 합의 한 번, 변경 직전 체크포인트 한 번: 이 두 동작만 끼워 넣으면 같은 작업이 훨씬 과감해집니다. Plan Mode는 "지금 이렇게 가도 돼?"를 묻는 자리고, 체크포인트는 "잘못되면 여기로 돌아오자"는 약속입니다. 둘을 함께 쓰면 실험 속도가 오히려 빨라집니다.

큰 변경 앞에서 망설이는 이유는 거의 늘 같습니다: "잘못되면 되돌리기 힘들 것 같아서". Plan Mode와 Checkpoint는 그 두려움을 거의 0으로 만들어줍니다.

Plan Mode: 먼저 합의, 나중에 실행

무엇인가

Claude가 파일을 한 줄도 건드리지 않고 계획만 보여주는 모드입니다. 마음에 들면 그때 실행합니다.

켜는 법

Shift + Tab  (권한 모드 사이클을 돌려 plan에 도달)
또는
claude --permission-mode plan
또는
세션 안에서: /permissions → plan

처음엔 Shift+Tab 두 번이면 들어가는 경우가 많지만, 시작 모드에 따라 다릅니다. 좌측 하단 표시를 보고 확인하세요.

언제 켭니까?

• 여러 파일을 동시에 바꾸는 큰 변경
• 데이터 마이그레이션, 스키마 수정
• 처음 보는 라이브러리/프레임워크 도입
• 비용 큰 작업(긴 빌드, 외부 API 호출 다수)

흐름

1) Plan Mode 켜기
2) "결제 모듈에 retry 로직 넣을 건데, 어떻게 할 건지 계획 보여줘"
3) Claude가 단계별 계획을 출력
4) 마음에 들면 → 일반 모드로 돌아가 실행
5) 별로면 → 계획만 다듬고 다시 검토

opusplan: Plan은 똑똑하게, 실행은 가볍게

/model opusplan은 Plan 단계는 Opus, 실행 단계는 Sonnet으로 자동 전환되는 공식 alias입니다.

/model opusplan

비용 절약 효과:

• Plan은 한 번, 짧게 (Opus 가격이지만 토큰 적게)
• 실행은 길게 (Sonnet 가격으로 다수 토큰)
• 결과적으로 Opus만 쓸 때보다 절반 이하 비용

💡 단, opusplan의 Plan 단계는 200K 컨텍스트를 사용합니다. 1M 컨텍스트가 자동 적용되지 않으니 매우 큰 코드베이스를 분석시키려면 별도 고려가 필요합니다.

Checkpoint: Esc Esc로 즉시 되돌리기

Claude가 파일을 수정하기 직전에 자동으로 스냅샷을 저장합니다. 별 설정이 없어도 동작합니다.

Esc 키를 두 번 누르면 → 직전 상태로 복구

이럴 때 바로 쓰세요:

• 의도와 다르게 파일이 수정되기 시작함
• 디자인을 크게 바꿨는데 마음에 안 듦
• 에러를 고치려다 더 많은 에러가 생김

git을 모르는 사람도 즉시 쓸 수 있는, 가장 빠른 복구 방법입니다.

/rewind: 여러 단계 전으로 되돌리기

Esc Esc가 "직전 한 단계"라면, /rewind는 원하는 시점까지 되돌립니다.

/rewind
→ 시점 목록이 나타남
→ 원하는 지점 선택

대화와 코드를 함께 되감습니다. "로그인 UI 변경 전으로", "테스트 추가 전으로" 같은 자연어 시점도 인식합니다.

되돌린 직후엔 현재 상태부터 확인하세요. 바로 새 작업을 시키면 어디서부터인지 헷갈립니다.

> 지금 변경된 파일이 남아 있는지, 깨끗한 상태인지 확인해줘

/checkpoint: 명시적 저장점

/rewind의 alias로 /checkpoint, /undo도 사용할 수 있습니다. 같은 명령입니다.

자동 체크포인트와는 별개로 "여기는 꼭 돌아오고 싶은 지점"을 명시적으로 저장하고 싶다면, 그 시점에서 git commit을 하나 더 만드는 편이 안전합니다.

> 지금 상태로 git에 'checkpoint: before payment refactor' 메시지로 커밋해줘

세 가지 비교

세 가지를 겹쳐 쓰는 게 정석입니다.

안전망 3종 세트

큰 작업을 시작하기 전에 다음 순서를 떠올리세요.

1. git commit: 세션 넘어서도 안전한 가장 마지막 안전망
2. Plan Mode: 실행 전에 합의해 큰 사고 자체를 막음
3. Checkpoint / /rewind: 작은 실수는 즉시 회수

이 셋을 가진 사람은 큰 변경도 망설이지 않습니다. 실험 속도가 곧 결과 속도입니다.

실전 워크플로우: 큰 리팩터링

1) git status 확인 → 모든 변경사항 commit
   "이 시점부터 변경할 거야. 깨끗한 상태로 commit 먼저 해줘"

2) Plan Mode 켜기 (Shift+Tab)
   "src/payment/ 전체를 retry 로직 포함 구조로 리팩터링.
    어떤 파일을 어떻게 바꿀지 계획만 보여줘"

3) 계획 확인 → 마음에 들면 일반 모드로 복귀

4) 실행 시작 → Claude가 파일 수정
   중간에 어색하면 Esc Esc로 직전 단계 회수

5) 결과 검증 → 테스트, 빌드 확인

6) OK → git commit
   별로 → /rewind로 시작점까지 되돌리기

이 흐름이 몸에 익으면, "큰 변경"이라는 단어 자체가 무겁지 않게 됩니다.

자주 하는 실수

한 줄 요약

안전망이 있는 사람은 실험을 두려워하지 않습니다. Plan, Checkpoint, Git: 세 가지면 충분합니다.

17. Statusline & 비용 가시화

보이지 않는 비용은 통제할 수 없습니다. 터미널 하단을 비용 대시보드로 만드세요.

Max 플랜으로 올라간 첫 달, 한도 경고를 받고서야 "내가 오늘 얼마나 썼지?"를 묻기 시작했던 기억이 납니다. 운전석에 계기판이 없는 차로 고속도로에 올라간 셈이었죠. 해법은 단순합니다. 현재 모델·토큰·세션 시간이 한 줄로 보이게 하는 것. 터미널 하단 한 줄짜리 statusline만 켜둬도, 큰 작업을 던지기 전에 무의식적으로 한 번 흘끗 보게 됩니다. 그 흘끗 한 번이 매월 청구서를 바꿔놓습니다.

대부분의 비용 사고는 "지금 얼마 쓰고 있는지 모르고 있던" 순간에 일어납니다. Statusline은 그 순간을 없애줍니다.

Statusline이란

Claude Code 터미널 하단에 늘 떠 있는 한 줄 상태표시입니다. 기본적으로 이런 정보가 보입니다:

별도 설정 없이 자동으로 표시됩니다.

왜 보이게 둬야 하나

/statusline: 커스터마이징

기본 표시가 부족하거나 더 보고 싶다면 /statusline으로 인터랙티브 메뉴를 엽니다.

/statusline

• 표시할 항목 토글 (모델 · 토큰 · 비용 · 모드 · 디렉터리 · git 브랜치 · 시간)
• 색상 / 강조 설정
• 5시간 / 7일 사용량 윈도우 시각화

설정은 ~/.claude/settings.json 또는 프로젝트 .claude/settings.json에 저장됩니다.

/usage 와의 차이

/usage (alias /cost, /stats)는 상세 리포트를 띄우는 명령이고, Statusline은 상시 표시입니다. 둘은 보완 관계입니다.

Statusline에서 이상 신호 → /usage로 정밀 진단, 이 흐름이 정석입니다.

비용 절감 워크플로우

Statusline을 보면서 다음 트리거에 반응하면 토큰 낭비의 90%는 막을 수 있습니다.

5시간 / 7일 사용량 가시화

구독자는 Claude Code 사용량이 5시간 윈도우와 7일 윈도우에 묶입니다. 한도 가까워지면 답변이 느려지거나 막힙니다.

Statusline에 이 두 값을 띄워두면 "오늘 더 쓸 수 있나"를 한눈에 알 수 있습니다.

/statusline → "5h limit", "7d limit" 항목 활성화

💡 한도 표시는 Pro / Max / Team 등 구독 플랜에서 의미가 있습니다. API 사용자는 노출되지 않습니다.

실전 시나리오: 비개발 작업도 가시화가 필요합니다

주식 리서치 세션

오전 9시) Statusline에 'sonnet · 12% · $0.04 · default'
         → 보유 종목 10개 뉴스 요약 시작

10시 30분) 'sonnet · 78% · $0.31 · default'
          → 80% 가까워짐. /compact 발동
          "지금까지의 종목별 결론만 남기고 뉴스 원문은 빼줘"

11시) 'sonnet · 22% · $0.31 · default'
       → 다시 깨끗한 컨텍스트로 재무제표 분석 시작

Statusline 없이 일했다면, 11시쯤 답변이 느려지고 어디가 잘렸는지 모른 채 계속 갔을 것입니다.

부동산 매물 비교

입력 데이터가 많을 때(매물 수십 개) 토큰이 빠르게 차오릅니다.
Statusline 토큰 50% 도달 → 매물 그룹별로 새 세션을 분리해
종합 비교는 마지막에 한 번에.

자주 하는 실수

추천 설정: 작업별

한 줄 요약

보이는 것만 통제할 수 있습니다. Statusline을 켜둔 사람과 그렇지 않은 사람의 토큰 비용 차이는 두 자릿수 %입니다.

15. MCP & 외부 도구 연결

Notion·Slack·Google Sheets·GitHub·DB. Claude의 손이 닿는 영역을 외부로 넓혀주는 표준 인터페이스입니다. 한 번 연결해두면 매번 복붙하던 자료들이 자동으로 흘러 들어옵니다.

출처: MCP & Integrations — Anthropic 공식 문서

MCP를 한 줄로

MCP(Model Context Protocol)는 Claude가 외부 도구·데이터 소스와 이야기할 수 있게 만드는 오픈 표준입니다. 기본 Claude Code는 파일과 터미널만 다루지만, MCP를 끼우면: Notion 문서를 직접 읽고, Slack 메시지를 요약하고, Sheets를 업데이트하고, 개발자라면 GitHub PR 리뷰·DB 쿼리·Sentry 에러 분석까지: 손이 늘어납니다.

비유: Claude에게 USB 포트를 달아주는 셈입니다. 꽂으면 곧장 사용 가능해집니다.

"복붙 노가다"가 사라지는 자리

MCP가 끼이기 전후를 하나씩 짝지어보면 차이가 분명해집니다.

업무·리서치 사용자가 흔히 마주치는 장면들

• Notion 회의록 페이지를 일일이 복사 → "오늘 회의 Notion 페이지에 정리해줘" 한 마디로 끝
• Google Sheets에 데이터 수동 입력 → "이 데이터를 Sheets에 정리해줘"
• 사이트 방문해 정보 복사·붙여넣기 → "이 5개 사이트 비교표 만들어줘"
• Slack 스레드 복사해 요약 부탁 → "#마케팅 오늘 논의 요약하고 공지 초안 써줘"

어떤 일까지 가능한가요: 다섯 갈래 예시

GitHub: PR·이슈를 직접 다루기

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

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

Sentry: 프로덕션 에러 분석

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

# /mcp로 인증 완료 후
> "지난 24시간 주요 에러는 뭐야?"
> "에러 ID abc123의 스택트레이스 보여줘"
> "이 에러들이 어느 배포에서 시작됐어?"

PostgreSQL: DB 직접 쿼리

# 가능하면 읽기 전용 계정으로!
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

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

Slack: 메시지 읽고 보내기

채널 맥락을 그대로 넘길 수 있습니다. 버그 리포트 스레드가 올라오면 그 흐름을 곧장 읽고 작업으로 이어집니다.

Notion·Asana·Figma 등

공식 MCP 가이드에서 사용 가능한 서버 목록과 연결 방법을 한눈에 확인하실 수 있습니다.

설치: 네 가지 입구

입구 ① · 원격 HTTP 서버 (가장 흔한 길)

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

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

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

입구 ② · 로컬 stdio 서버

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

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

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

입구 ③ · SSE 서버 (스트리밍)

claude mcp add --transport sse <이름> <URL> \
  --header "Authorization: Bearer <TOKEN>"

입구 ④ · JSON으로 한 번에

복잡한 옵션을 넣을 때 편합니다.

# HTTP 서버 + OAuth 사전 설정
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

# stdio 서버 + 환경변수
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

--client-secret은 OAuth 클라이언트 시크릿을 별도 안전 저장소에 둘 때 씁니다.

매일 쓰는 관리 명령

claude mcp list           # 등록된 서버 목록
claude mcp get github     # 특정 서버 상세
claude mcp remove github  # 서버 제거
/mcp                      # 안에서 상태 확인

설정이 저장되는 위치: 스코프 셋

--scope <local|project|user>로 지정합니다. 어디에 두느냐에 따라 적용 범위가 달라집니다.

• local (기본값): ~/.claude.json(현재 프로젝트 섹션). 내 계정의 현재 프로젝트만 적용
• project: .mcp.json(프로젝트 루트). Git 커밋해서 팀 공유
• user: ~/.claude.json(전역 섹션). 내 계정의 모든 프로젝트에 적용

ℹ️ local과 user는 같은 파일에 들어가지만 섹션이 다릅니다. 헷갈리면 claude mcp list로 어디 들어 있는지 확인해보세요.

# 팀 공유용
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

# 모든 프로젝트에서 쓸 개인 전역
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

팀 프로젝트에서는 .mcp.json을 Git에 커밋해두시면 팀원 모두 동일한 환경에서 시작할 수 있습니다.

입문자에게 권하는 세 가지

처음 한두 개로 감을 잡으시려면 다음 셋이 좋습니다.

권장 ㉠ · Notion MCP

claude mcp add --transport http notion https://mcp.notion.com/mcp

사라지는 일: 회의록·리서치 결과 수동 복사, 페이지 붙여넣기, DB 수동 업데이트.

활용 예시:

• "Notion '회의록' DB의 지난 7일 항목을 가져와 결정사항·액션아이템만 모아 weekly.md로 만들어줘"
• "이 리서치 결과를 Notion '경쟁사 분석' 페이지에 추가해줘"

권장 ㉡ · Slack MCP

claude.ai 계정으로 로그인한 뒤 claude.ai/settings/connectors에서 설정합니다.

사라지는 일: 채널 스레드 수동 읽기, 요약용 복붙, 공지 초안 직접 쓰기.

활용 예시:

• "#마케팅 채널 오늘 스레드를 읽고, 쟁점 3개와 합의된 다음 액션을 슬랙 공지 초안으로 만들어줘"

권장 ㉢ · Google Chrome (웹 리서치)

같은 커넥터 페이지에서 켜시면 됩니다.

사라지는 일: 사이트 방문해 정보 수동 복사, 여러 곳 비교를 위한 탭 전환.

활용 예시:

• "경쟁사 5곳을 훑고, 오늘의 주요 변화·새 기능·가격 변경만 표로 정리해줘"

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

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

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

공식 커넥터: 클릭 한 번으로

claude.ai 계정으로 로그인한 환경이라면 claude.ai/settings/connectors에서 켠 서버가 Claude Code에 자동으로 따라옵니다. 현재 공식 지원 커넥터는 두 가지입니다.

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

OAuth가 필요한 서버: 두 박자

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

# 박자 ① — 서버 추가
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 박자 ② — Claude Code 안에서 인증
> /mcp

# 브라우저가 열리고 → 로그인 → 자동 완료

토큰은 자동으로 저장·갱신됩니다.

MCP 프롬프트를 직접 명령으로

MCP 서버가 프롬프트를 제공하면 /mcp__서버명__프롬프트명 형식으로 바로 실행됩니다.

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

⚠️ 안전: MCP를 깔기 전 확인할 것들

신뢰할 수 없는 서버는 함부로 설치하지 마세요. MCP 서버는 Claude를 통해 내 파일·DB·외부 서비스에 접근할 수 있고, 외부 콘텐츠를 가져오는 서버는 프롬프트 인젝션 위험까지 있습니다.

설치 전 다음 체크리스트로 한 번 거르시면 좋습니다.

□ 공식 제공 서버인가? 아니면 신뢰할 만한 조직이 관리하나?
□ GitHub 저장소의 최근 커밋이 너무 오래되지 않았나?
□ README에 필요한 권한·데이터 접근 범위가 설명되어 있나?
□ 토큰·키를 어디에 저장하는지 명확한가?
□ DB 연결은 읽기 전용 계정을 쓸 수 있나?
□ 팀 프로젝트라면 .mcp.json 커밋 전 팀원에게 공유했나?

DB MCP는 가능한 한 읽기 전용 계정을 따로 만들기를 권합니다. 분석·리포트 용도엔 쓰기 권한이 필요한 경우가 드뭅니다.

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

한 줄로

MCP = Claude의 손을 외부로 늘려주는 플러그인. GitHub·DB·Slack을 Claude가 직접 다루는 순간, "복사-붙여넣기" 노가다가 사라집니다.

MCP가 "외부 세계와 연결"이라면, 다음 섹션 Hooks는 "Claude Code 자체 동작을 자동화"하는 영역입니다.

16. Hooks: 내 작업을 지켜주는 안전벨트

AI가 rm -rf를 실행하거나 git push --force로 히스토리를 날리면? Hooks가 그 사고를 실행 직전에 막아 세웁니다. LLM의 판단이 아니라 코드로 100% 차단하는 장치입니다.

출처: Hooks — Anthropic 공식 문서

왜 Hooks가 있어야 할까

Claude Code는 강력합니다. 파일을 만들고·고치고·지우고, Git 명령도 실행합니다. 그래서 바이브코딩 중에 다음 같은 일이 진짜로 일어납니다.

• rm -rf 한 방에 프로젝트 폴더가 사라짐
• git reset --hard로 미커밋 작업이 통째로 증발
• git push --force로 팀원 코드가 덮어씌워짐
• DROP TABLE로 데이터베이스가 날아감

이 사고들이 한 번이라도 닥치면 그날의 작업이 끝나는 것이 아니라 며칠치 작업이 끝납니다. Hooks는 이런 위험 명령을 실행 직전에 코드로 가로챕니다. 사람의 판단도, AI의 판단도 아닌: 그저 정해진 패턴이 매치되면 멈추는 단순한 안전벨트입니다.

Hook이 뭐 하는 건가요

Hook은 Claude Code의 특정 이벤트가 발생할 때 자동으로 실행되는 셸 커맨드입니다. 공식 Hooks 페이지에는 약 29개의 이벤트가 정의돼 있습니다. 입문자 입장에서 알아둘 것은 다음 10개 정도입니다.

• PreToolUse: 도구 실행 직전 (위험 명령 차단)
• PostToolUse: 도구 실행 직후 (자동 포매팅·로그)
• Stop: Claude가 응답 완료 시 (완료 알림)
• Notification: Claude가 알림 보낼 때 (데스크톱 알림)
• SessionStart: 세션 시작·재개 시 (컨텍스트 주입)
• SessionEnd: 세션 종료 시 (정리·사용량 기록)
• UserPromptSubmit: 프롬프트 제출 시 (입력 전처리)
• PreCompact: 컨텍스트 압축 전 (중요 정보 보존)
• SubagentStart: 서브에이전트 시작 (위임 로그·예산 체크)
• SubagentStop: 서브에이전트 종료 (결과 검증·요약)

ℹ️ 이벤트 카덴스: 세션당 1회(SessionStart/SessionEnd), 턴당 1회(UserPromptSubmit/Stop), 도구 호출마다(PreToolUse/PostToolUse).

핵심 약속: exit 0 = 허용, exit 2 = 차단(stderr 메시지가 Claude에게 전달됩니다). 차단은 PreToolUse·UserPromptSubmit·Stop·PreCompact·SubagentStop 같은 "사전" 이벤트에서만 의미가 있고, PostToolUse처럼 이미 실행된 이벤트는 차단 불가입니다.

어디에 설정을 둘까

세 곳 중 하나에 두시면 됩니다. 위치마다 적용 범위가 다릅니다.

• ~/.claude/settings.json: 내 모든 프로젝트 (개인 전용)
• .claude/settings.json: 현재 프로젝트 (팀과 Git 공유)
• .claude/settings.local.json: 현재 프로젝트 (개인 전용)

💡 /hooks 커맨드로 인터랙티브 설정도 가능하지만, 아래 예시를 그대로 복사·붙여넣는 편이 빠릅니다.

첫 Hook ㉠: Safety Hook (위험 명령 차단)

이 한 개로 대부분의 사고가 막힙니다. 시작은 가볍게 가셔도 됩니다.

• 최소 버전: rm, git reset --hard, git push --force 세 가지만 차단 (처음 Hook을 써보는 분에게)
• 확장 버전: Git·DB·프로덕션 접근까지 차단 (실제 프로젝트에서 오래 쓸 분에게)

아래 예시는 확장 버전입니다. 부담스러우시면 위 세 가지만 남기셔도 충분히 효과가 있습니다.

단계 ① · 스크립트 파일 만들기

~/.claude/hooks/block_dangerous.py를 만드세요.

#!/usr/bin/env python3
"""위험한 명령어를 자동 차단하는 Safety Hook"""
import json, re, sys

BLOCKED_PATTERNS = [
    # 파일 삭제 — rm 대신 trash (휴지통, 복구 가능)
    (r"\brm\s+", "rm 대신 trash를 사용하세요 (brew install trash)"),
    (r"\bunlink\s+", "unlink 대신 trash를 사용하세요"),

    # Git 히스토리 파괴
    (r"git\s+reset\s+--hard", "git reset --hard는 커밋하지 않은 작업을 삭제합니다"),
    (r"git\s+push\s+.*--force", "git push --force는 원격 히스토리를 덮어씁니다"),
    (r"git\s+push\s+.*-f\b", "git push -f는 원격 히스토리를 덮어씁니다"),
    (r"git\s+clean\s+-.*f", "git clean -f는 추적되지 않은 파일을 영구 삭제합니다"),
    (r"git\s+checkout\s+\.\s*$", "git checkout .은 모든 변경사항을 삭제합니다"),
    (r"git\s+stash\s+drop", "git stash drop은 스태시를 영구 삭제합니다"),
    (r"git\s+branch\s+-D", "git branch -D는 브랜치를 강제 삭제합니다"),

    # 데이터베이스 파괴
    (r"DROP\s+(DATABASE|TABLE)", "DROP은 데이터를 영구 삭제합니다"),
    (r"TRUNCATE\s+TABLE", "TRUNCATE는 모든 데이터를 삭제합니다"),
]

data = json.load(sys.stdin)
if data.get("tool_name") != "Bash":
    sys.exit(0)

command = data.get("tool_input", {}).get("command", "")
for pattern, reason in BLOCKED_PATTERNS:
    if re.search(pattern, command, re.IGNORECASE):
        print(f"차단됨: {reason}", file=sys.stderr)
        sys.exit(2)

sys.exit(0)

단계 ② · 실행 권한 부여

chmod +x ~/.claude/hooks/block_dangerous.py

단계 ③ · ~/.claude/settings.json에 등록

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/block_dangerous.py"
          }
        ]
      }
    ]
  }
}

동작 흐름: rm -rf node_modules가 들어왔을 때

1. PreToolUse 이벤트 → block_dangerous.py 실행
2. 명령어가 rm 패턴에 매치
3. exit 2로 차단 + "rm 대신 trash를 사용하세요" 메시지 전달
4. Claude가 메시지를 받고 trash node_modules로 대안 실행

💡 trash는 파일을 휴지통으로 보내 실수해도 복구할 수 있습니다. macOS는 brew install trash, 그 외 OS는 npm install -g trash-cli로 설치하세요.

차단 패턴 추가: 입맛 따라 늘리기

BLOCKED_PATTERNS 리스트에 줄만 추가하시면 됩니다.

# 예시: chmod 777 차단
(r"chmod\s+777", "chmod 777은 보안상 위험합니다"),

# 예시: 프로덕션 SSH 접속 차단
(r"ssh\s+.*prod", "프로덕션 서버 접근이 차단되었습니다"),

첫 Hook ㉡: 완료 알림

Claude의 응답이 끝나는 순간을 소리로 알려줍니다. 다른 창을 보고 있어도 놓치지 않습니다.

macOS: 시스템 사운드

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Frog.aiff"
          }
        ]
      }
    ]
  }
}

Stop과 Notification에 다른 사운드를 지정하면 "끝남"과 "확인 필요"를 귀로 구분할 수 있습니다.

사용 가능한 macOS 사운드 목록:

ls /System/Library/Sounds/

macOS: 데스크톱 알림 팝업

소리 대신(또는 함께) 화면 알림을 띄우실 수도 있습니다.

{
  "type": "command",
  "command": "osascript -e 'display notification \"작업이 완료되었습니다\" with title \"Claude Code\"'"
}

Linux

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

두 Hook을 한 번에 설정하기

Safety Hook + 완료 알림을 하나의 settings.json에 합친 모습입니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/block_dangerous.py"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Frog.aiff"
          }
        ]
      }
    ]
  }
}

이미 다른 설정이 있다면 hooks 키만 추가·병합하세요. /hooks 커맨드로 등록 결과를 확인하실 수 있습니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "FILE=\"$(jq -r '.tool_input.file_path // empty')\"; if [[ \"$FILE\" == customers/* || \"$FILE\" == invoices/* ]]; then echo \"차단: 민감 폴더입니다\" >&2; exit 2; fi"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "cat ~/업무규칙.txt"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "모든 태스크가 완료되었는지 확인하세요. 미완료 항목이 있으면 계속 작업하세요."
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/pre-tool-use",
            "timeout": 30,
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

안 풀릴 때: 자주 만나는 네 가지

• Hook이 실행되지 않을 때 → /hooks에서 이벤트 확인, matcher 대소문자 점검
• 스크립트가 실행되지 않을 때 → chmod +x로 실행 권한 부여
• JSON 파싱 오류 → ~/.zshrc의 echo 구문을 인터랙티브 셸 조건부로 감싸기
• 모든 파일 수정이 차단될 때 → PreToolUse Hook의 exit 2 조건을 다시 확인

디버깅: claude --debug 또는 Ctrl+O로 Hook 실행 로그를 살펴보세요.

한 줄로

Safety Hook + 완료 알림: 이 두 개만 깔아두셔도 바이브코딩이 한층 안전하고 편해집니다. rm 한 방에 프로젝트 날리는 사고는 미리 막아두시는 것이 가장 쌉니다.

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

17. Skills & 플러그인 만들기

자주 하는 일을 한 번 적어두면, 이후로는 한 줄 명령으로 끝납니다. 같은 설명을 두 번 다시 타이핑하지 않아도 되는 영역입니다.

출처: Skills — Anthropic 공식 문서

Skill: 한 줄로 정리

Skill은 Claude Code에 새 능력을 더하는 재사용 가능한 워크플로우입니다. SKILL.md 파일 한 장만 만들면 Claude가 도구로 인식합니다. /스킬이름으로 직접 실행하시거나, 상황에 맞춰 자동 활성화시킬 수도 있습니다.

쉽게 말씀드리면: 자주 쓰는 작업 절차를 문서화해두는 일입니다. 그 한 번의 정리가 있으면 다음부턴 한 마디로 시킬 수 있습니다.

ℹ️ 기존 .claude/commands/의 커스텀 슬래시 커맨드는 Skills로 통합됐습니다. 옛 파일도 그대로 동작합니다.

일반 대화와 비교: 어디가 다를까

같은 일을 시키는 두 방식의 차이를 짝지어보면 이렇습니다.

• 실행: 매번 설명 타이핑 vs /skill-name 한 번
• 일관성: 매번 결과가 흔들림 vs 항상 동일한 절차
• 팀 공유: 어렵다 vs Git 커밋으로 자연스럽게
• 인자 전달: 설명 속에 묻힘 vs $ARGUMENTS로 명확하게
• 도구 제한: Claude의 판단에 맡김 vs 허용된 도구만

"복붙 노가다"가 사라지는 자리

• 회의 끝날 때마다 녹음 정리 부탁 → /meeting 파일명 한 번
• 주간 보고서 형식 매번 설명 → /weekly-report 한 번
• 번역 요청마다 언어·형식 명시 → /translate ko en README.md
• 경쟁사 분석마다 형식 설명 → /competitor-analysis 회사명
• SNS 게시물마다 브랜드 톤 설명 → /sns-post 주제
• 이메일마다 회사 정보 입력 → /email-draft 목적

첫 Skill 만들기: 세 박자

박자 ① · 디렉터리 만들기

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

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

박자 ② · SKILL.md 적기

.claude/skills/commit/SKILL.md:

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

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

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

박자 ③ · 실행

# 직접 실행
/commit

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

Skill 폴더의 모양

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

💡 SKILL.md는 500줄 이내로 간결하게. 상세 내용은 별도 파일로 분리하시는 편이 나중에 유지보수가 쉽습니다.

Frontmatter 옵션: 자주 쓰는 것들

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

세 가지 패턴을 기준으로 외워두시면 충분해요.

• (기본값): 사용자도 쓸 수 있고 Claude가 자동으로 띄울 수도 있습니다 (일반 워크플로우)
• disable-model-invocation: true: 사용자만 실행 가능, 자동 실행은 차단 (배포·전송 등 부작용 있는 작업)
• user-invocable: false: 메뉴에 안 뜨고 Claude만 자동 사용 (배경 지식·컨벤션)

실용 예시: 네 가지

예시 ① · 회의록 자동 정리

.claude/skills/meeting/SKILL.md:

---
name: meeting
description: 회의 녹음 파일을 받아 텍스트로 변환하고 회의록·액션아이템을 정리합니다. 회의 후 정리할 때 사용.
argument-hint: [녹음 파일 경로]
disable-model-invocation: true
---

$ARGUMENTS 파일을 처리해서 회의록을 만드세요:

1. 음성 변환 도구(whisper 등)가 없으면 설치
2. $ARGUMENTS 파일을 텍스트로 변환
3. 다음 형식으로 회의록 작성:
   - 날짜 / 참석자
   - 주요 논의 내용 (3~5줄 요약)
   - 결정 사항
   - 담당자별 액션아이템 (이름: 할 일, 기한)
4. 원본 파일명과 같은 이름으로 .md 파일 저장

실행:

/meeting ~/Downloads/meeting-260225.mp3

파이썬·변환 도구를 미리 알고 계실 필요 없습니다. Claude Code가 필요한 것을 알아서 깔고 굴립니다. 결과 모양도 SKILL.md에 박아두시면 매번 일정하게 나옵니다.

# 회의록: meeting-260225

## 5줄 요약
- 신규 랜딩페이지 목표 전환율 3%
- 가격표 문구 단순화 결정
- 다음 주까지 A/B 테스트 초안 준비

## 결정사항
| 항목 | 결정 |
|------|------|
| 랜딩페이지 방향 | 기능 설명보다 사용 사례 중심 |

## 액션아이템
| 담당 | 할 일 | 기한 |
|------|------|------|
| 민수 | A/B 테스트 문안 2안 작성 | 금요일 |

좋은 Skill의 핵심은 결과물의 모양까지 함께 정해 두는 것입니다.

예시 ② · SNS 콘텐츠 자동화

.claude/skills/sns-post/SKILL.md:

---
name: sns-post
description: 주어진 내용을 SNS 게시물로 변환합니다. 블로그·인스타그램·LinkedIn 포스팅이 필요할 때 사용.
argument-hint: [주제 또는 원고 내용]
---

$ARGUMENTS를 SNS 게시물로 변환하세요:

1. 인스타그램 버전 (해시태그 10개, 이모지 포함, 친근한 어조, 300자 이내)
2. LinkedIn 버전 (전문적 어조, 인사이트 강조, 500자 이내)
3. 트위터·X 버전 (140자 이내, 핵심만 간결하게)

각 버전을 구분선으로 나눠 출력하세요.

실행:

/sns-post 우리 팀이 새 제품 출시에 성공했습니다. 6개월의 개발 끝에...

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

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

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

/review src/auth/login.ts

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

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

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

/fix-issue 123

예시 ③ · 번역 자동화

.claude/skills/translate/SKILL.md:

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

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

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

실행:

/translate README.md ko

한 단계 위: 동적 컨텍스트 주입

! + 백틱 문법으로 스킬 실행 직전에 셸 명령을 실행해 결과를 컨텍스트에 끼워 넣을 수 있습니다.

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

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

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

실행 흐름은: ① 백틱 안의 명령이 먼저 실행되고 → ② 실제 데이터가 프롬프트에 끼워지고 → ③ Claude가 그 PR 내용을 보고 요약을 씁니다.

Skill이 저장되는 위치: 우선순위

• 엔터프라이즈: 관리형 설정 (조직 전체 적용)
• 개인: ~/.claude/skills/<이름>/SKILL.md (내 모든 프로젝트)
• 프로젝트: .claude/skills/<이름>/SKILL.md (현 프로젝트)
• 플러그인: <플러그인>/skills/<이름>/SKILL.md (플러그인 활성화 시)

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

💡 직접 만들기 막막하시면: 개인용으로 작은 Skill 하나 먼저 굴려보고, 두세 프로젝트에서 반복적으로 쓰게 되면 그때 플러그인으로 묶는 흐름이 안전합니다.

플러그인으로 묶기

여러 프로젝트에서 같은 Skill 묶음을 재사용하시려면 플러그인 패키징이 자연스럽습니다.

폴더 구조

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

plugin.json

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

로컬 테스트

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

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

Standalone vs 플러그인: 어떤 길로?

• 개인 워크플로우, 빠른 실험 → Standalone (.claude/skills/)
• 여러 프로젝트에서 재사용 → 플러그인
• 배포보다 먼저: 개인 환경에서 충분히 테스트해 보기

Claude는 어떻게 Skill을 자동으로 찾을까

Claude는 description 필드를 보고 언제 그 Skill을 쓸지 판단합니다. "어떤 상황에서 쓰는지"가 또렷할수록 잘 찾아갑니다.

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

# 아쉬운 예
description: review tool

자동 실행을 막고 싶으시면 disable-model-invocation: true를 넣으세요.

안 풀릴 때

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

한 줄로

Skill = 자주 하는 작업을 /커맨드 한 줄로 만들어두는 기록. 팀에 배포할 땐 플러그인으로 묶으시면 됩니다.

다음 섹션에서는 만들어둔 Skill을 여러 Claude가 동시에 굴리는: Sub-agents의 세계로 들어갑니다.

18. Sub-agents

"팀장이 혼자 다 하지 않고, 일을 나눠 맡기는 방식." Claude도 같은 흐름이 가능합니다: 한 Claude가 여러 Claude에게 일을 위임해서 병렬로 처리하는 영역입니다.

출처: Sub-agents — Anthropic 공식 문서

Sub-agent를 한 줄로

Sub-agent(서브에이전트)는 메인 Claude가 특정 작업을 별도의 Claude 인스턴스에 떼어 주는 기능입니다. 각각의 서브에이전트는 다음 네 가지 특성을 갖습니다.

• 독립된 컨텍스트 창: 메인과 분리되어 있습니다
• 커스텀 시스템 프롬프트: 특정 역할에만 집중하게 만들 수 있습니다
• 제한된 도구: 필요한 것만 쓰게 줄여둘 수 있습니다
• 요약 결과만 반환: 작업이 끝나면 메인으로 핵심만 돌아옵니다

비유: 팀장이 프로젝트를 받았을 때, 리서치는 A에게·번역은 B에게·교정은 C에게 분담하는 그림입니다. 그것이 Sub-agent의 작동 방식과 정확히 같습니다.

그림으로 한 번 더

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

각 서브에이전트가 독립 컨텍스트에서 실행되고,
요약된 결과만 메인으로 돌아옴 → 메인 대화는 깨끗하게 유지

어떨 때 써야 좋을까

Sub-agent가 잘 맞는 상황

• 대용량 출력이 나오는 작업: 테스트 로그·문서 페치 결과가 메인 컨텍스트를 낭비할 때
• 독립적인 여러 파일을 동시에 손볼 때: 병렬이 더 빠릅니다
• 특정 도구만 써야 하는 작업: 읽기 전용 리뷰어, DB 쿼리 전용 에이전트 등
• 탐색과 구현을 분리하고 싶을 때: 탐색 결과가 메인 흐름을 오염시키지 않게

오히려 일반 대화가 나은 상황

• 잦은 피드백이 필요한 작업: 서브는 독립 실행이라 중간 개입이 어렵습니다
• 빠른 단순 수정: 시작 오버헤드가 부담
• 여러 단계가 컨텍스트를 공유해야 할 때: 계획·구현·테스트가 긴밀히 묶인 경우

내장된 세 가지: 처음부터 들어 있는 친구들

Claude Code는 다음 세 종을 기본 탑재하고 있습니다.

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

코드를 탐색해야 할 때는 Claude가 자동으로 Explore를 띄웁니다. 수천 줄짜리 탐색 결과가 메인 대화를 오염시키지 않고, 요약만 메인으로 돌아옵니다.

직접 만들기: 두 갈래

갈래 ㉠ · /agents 인터랙티브 메뉴 (권장)

/agents

흐름은 단순합니다.

1. Create new agent 선택
2. User-level(모든 프로젝트) 또는 Project-level(현 프로젝트) 선택
3. Generate with Claude → 역할 설명
4. 허용 도구 선택
5. 모델 선택 (Haiku/Sonnet/Opus)
6. 저장

갈래 ㉡ · 파일 직접 작성

.claude/agents/ 폴더에 마크다운을 두면 곧장 사용할 수 있습니다. 세 가지 예를 짧게 보여드리겠습니다.

리서치 요약 에이전트 (.claude/agents/researcher.md):

---
name: researcher
description: 자료 폴더를 읽고 핵심 요약·인사이트·다음 질문을 정리합니다. 리서치가 필요할 때 자동으로 사용.
tools: Read, Grep, Glob
model: sonnet
---

당신은 리서치 어시스턴트입니다.
- 결론을 먼저 5줄로 요약
- 근거가 되는 문장·출처 파일명을 함께 표기
- "추정·가정"은 명확히 라벨링
- 마지막에 다음 조사 질문 5개를 제안

번역 에이전트 (.claude/agents/translator.md):

---
name: translator
description: 파일·문장을 지정 언어로 번역하고, 마크다운 구조를 유지합니다.
tools: Read, Write
model: sonnet
---

번역 규칙:
- 고유명사·제품명·코드·명령어는 원문 유지
- 문장 톤은 "친절하지만 과장 금지"
- 표·목차·링크 구조는 유지

최종 점검(QA) 에이전트 (.claude/agents/editor-qa.md):

---
name: editor-qa
description: 최종 문서의 오탈자·표기 통일·금지어·링크 누락을 점검합니다.
tools: Read, Grep, Glob
model: haiku
---

점검 체크리스트:
- 날짜·숫자 표기 통일 (예: 2026-02-26)
- 금지어("완벽·혁명·무조건") 탐지
- 링크(https://) 누락·깨짐 의심 구간 표시
- "다음 액션"이 빠졌으면 추가 제안

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

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

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

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

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

Frontmatter: 핵심 네 필드만

공식 스펙의 핵심은 name·description·tools·model 네 가지입니다. 그 밖의 옵션은 버전에 따라 변경될 수 있으니 공식 sub-agents 가이드를 함께 참고해 주세요.

---
name: my-agent           # 소문자 + 하이픈 (필수)
description: 설명        # Claude가 언제 위임할지 판단 기준 (필수)
tools: Read, Grep, Glob  # 허용 도구 (생략 시 메인의 도구 상속)
model: sonnet            # haiku · sonnet · opus · inherit
---

여기 아래에 시스템 프롬프트(역할·규칙·체크리스트)를 적습니다.

inherit는 메인 대화의 모델을 그대로 따라갑니다. 읽기 전용 탐색·요약에는 Haiku가 빠르고 저렴합니다. 복잡한 추론은 Sonnet·Opus를 권합니다.

어디에 저장될까: 우선순위

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

실용 예시: 세 장면

장면 ① · 경쟁사 동시 분석 (병렬 리서치)

"경쟁사 A·B·C를 각각 별도 에이전트로 동시에 분석해줘.
 각 에이전트는 웹사이트·가격·리뷰를 조사하고
 결과를 하나의 비교표로 통합해줘"

3개 리서치 에이전트가 동시에 돌고, 결과가 한 표로 합쳐지는 흐름입니다. 순차 처리 대비 약 3배 빠릅니다.

장면 ② · PDF 20개 병렬 요약

"Downloads 폴더의 PDF 20개를 5개씩 나누어
 4개 에이전트가 동시에 요약하고
 결과를 하나의 보고서로 합쳐줘"

요약 로그가 방대해도 메인 대화는 깨끗하게 유지됩니다. 처리 속도는 약 4배입니다.

장면 ③ · 역할 분담: 리서치 → 검토 → 번역 연쇄

"researcher 에이전트로 sources/ 폴더를 읽고 1페이지 요약해줘"
"editor-qa 에이전트로 final/ 폴더 품질 점검, 수정 필요 항목만 리스트업해줘"
"translator 에이전트로 drafts/post.md를 영어로 번역해 drafts/post.en.md로 저장해줘"

각 전담 에이전트가 차례로 일을 하고, 메인 Claude는 흐름만 조율합니다.

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

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

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

영구 메모리: 학습이 다음 세션까지 따라오게

Claude Code는 작업하면서 배운 내용을 자동으로 ~/.claude/projects/<project>/memory/에 기록합니다(Auto Memory). 서브에이전트도 자체 메모리를 유지할 수 있습니다. 자세한 frontmatter 필드와 저장 경로는 공식 가이드의 "Enable persistent memory" 섹션을 함께 보시면 정확합니다(필드 이름은 버전에 따라 달라질 수 있습니다).

포그라운드 vs 백그라운드

• 포그라운드: 완료까지 대기. 권한 요청이 사용자에게 전달됩니다
• 백그라운드: 동시 실행. 다른 작업을 계속할 수 있습니다

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

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

⚠️ 백그라운드 서브에이전트는 MCP 도구를 쓸 수 없다는 점만 기억해두세요.

⚠️ 비용: 늘어난 손은 늘어난 청구서

서브에이전트는 각각 독립된 Claude 인스턴스라, 에이전트마다 토큰을 씁니다. 세 가지를 미리 알고 들어가시면 좋습니다.

• 3개 병렬 실행 = 토큰 사용량 대폭 증가
• 결과가 메인으로 돌아올 때 추가 토큰 소모
• 무분별한 남용은 비용 곡선을 가파르게 올립니다

비용을 누르는 작은 습관:

• 읽기 전용 탐색은 Haiku 모델로
• 반환할 결과의 양을 명시적으로 지정 ("핵심 5개만")
• 단순 작업은 굳이 서브로 빼지 말고 메인에서

입문자에게: 처음엔 단일 Claude로 충분합니다

다음 신호가 보이기 시작하면 그때 서브에이전트를 도입하시면 됩니다.

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

첫 커스텀: 검토자(editor-qa)부터

코드를 수정하는 역할보다 읽기 전용 검토자가 안전한 출발점입니다.

/agents
→ Create new agent
→ Project-level
→ 역할: "문서의 오탈자·링크 누락·표기 통일 문제만 찾아주는 검토자"
→ 도구: Read, Grep, Glob
→ 모델: Haiku 또는 Sonnet

사용 예시:

"editor-qa 에이전트로 content/ko 폴더를 읽고
오탈자·제목 번호 누락·링크 깨짐 의심 항목만 보고해줘.
파일은 수정하지 말고 목록만 줘."

이렇게 독립 검토에서 손맛을 익힌 뒤 구현·수정 역할로 넓혀가는 편이 무난합니다.

한 줄로

Sub-agent = Claude가 다른 Claude에게 일을 떼어주는 기능. 독립 컨텍스트에서 돌기 때문에 메인 대화가 깨끗하게 유지되고 병렬 처리가 됩니다. 단, 에이전트 수만큼 토큰 비용이 늘어납니다.

19. 나만의 AI 워크스페이스 설계하기

CLAUDE.md·Skills·Hooks를 익혔다면, 이제 그것들을 한 자리에 묶어 보실 차례입니다. 도구 모음을 넘어서: "나만의 자동화 사무실"을 만드는 단계입니다.

워크스페이스란

일반적인 AI 사용은 "질문 → 답변"의 1회성 흐름입니다. 매번 처음부터 시작합니다. 반면 워크스페이스는 역할이 정해진 AI가 나만의 규칙으로, 일관된 방식으로 굴러가는 시스템입니다. 한 번 깔아두면 다음 날에도, 한 달 뒤에도 같은 결로 일이 진행됩니다.

구성 요소를 한 줄씩으로 보면 이렇습니다.

• CLAUDE.md: AI의 역할·규칙·지식이 들어가는 장기 기억
• 폴더 구조: 작업물이 자연스럽게 쌓이는 자리
• Skills: 반복 작업을 /명령어 한 줄로 묶어둔 레시피
• Hooks: 놓치면 안 되는 품질 기준을 코드로 강제

설계 철학: 한 줄로

"모든 규칙을 CLAUDE.md에 욱여넣지 마세요. Skills로 분산하고, Hooks로 강제하세요."

각각의 역할을 짧게 정리하면:

• CLAUDE.md: 변하지 않는 역할과 원칙
• Skills: 반복되는 작업의 흐름
• Hooks: 사람의 판단으로는 자주 놓치는 안전 기준

도메인별 워크스페이스: 세 가지 청사진

청사진 ㉠ · 시장·부동산 리서치 워크스페이스

CLAUDE.md 핵심:
  - 출처 없는 주장 금지
  - 모든 수치에 출처 등급 표기 (A~E)
  - 분기별 보고서는 reports/ 폴더에 자동 저장

폴더 구조:
  inbox/      → 통계청·부동산원 자료 보관
  reports/    → 완성된 분기 보고서
  sources/    → 출처 모음·신뢰도 기록

Skills:
  /quarterly [지역]   → 지역별 분기 매매가 분석
  /summary [파일]     → 보고서 1쪽 브리프 변환

청사진 ㉡ · 콘텐츠 제작 워크스페이스

CLAUDE.md 핵심:
  - 브랜드 톤 정의 (친근·실용적, 전문 용어 최소화)
  - 타깃 독자 정의
  - 채널별 콘텐츠 형식 템플릿

폴더 구조:
  drafts/     → 초안
  published/  → 발행 완료
  templates/  → 재사용 형식

Skills:
  /blog [주제]        → 블로그 포스트 초안
  /newsletter [내용]  → 뉴스레터 형식 변환
  /sns [내용]         → 인스타그램·트위터 버전

💡 리서치 워크스페이스에는 멀티에이전트 구성을, 콘텐츠 작업에는 공식 문서 기반 자료 수집 구조를 함께 설계해 두시면 좋습니다.

청사진 ㉢ · 비즈니스 운영 워크플로우

CLAUDE.md 핵심:
  - 회사·팀 정보, 주요 프로젝트 현황
  - 이메일 톤 (공식·친근함 수준)
  - 보고서 형식 템플릿

Skills:
  /meeting [녹취]     → 요약 + 결정사항 + 액션 아이템
  /report [주제]      → 주간 보고서 초안
  /email [상황]       → 이메일 초안

실제 사례 공개: 이 가이드의 워크스페이스

본 가이드(cc101)가 만들어진 워크스페이스 구성을 그대로 보여드리겠습니다.

CLAUDE.md 핵심

# 아이디에이션 워크스페이스

## 역할
아이디어 발굴·검증·실행을 돕는 AI 파트너

## 핵심 원칙
- 한국어 전용
- 리서치 없이 주장 금지 (할루시네이션 방지)
- 모든 출처 등급 표기 (A~E)
- 검증 없이 "될 것 같다" 발언 금지
- 아이디어는 반드시 문서화 (휘발 방지)

## 검증 방식 — 4 페르소나 Council
- Visionary: 잠재력·비전
- Pragmatist: 실현 가능성·리소스
- Critic: 리스크·약점
- User Advocate: 사용자 가치

## 폴더 구조
10-inbox/      → 참고 자료
20-sparks/     → 아이디어 포착
30-research/   → 리서치 결과
40-foundry/    → 검증 결과
50-blueprints/ → MVP 설계
60-ventures/   → 실행 중
70-playbook/   → 경험 축적
90-shelf/      → 보류 아이디어

사용 중인 Skill 네 개

/spark [아이디어]   → 아이디어 포착 + ICE 스코어 평가
/research [주제]    → 7단계 딥리서치
/validate           → 4페르소나 Council 검증
/insight [내용]     → 교훈 Playbook 저장

이 워크스페이스에서 실제로 만들어진 결과물

• 새 프로젝트 아이디어 포착·검증
• 3개 AI가 섹션 구성을 토론하는 agent-council
• 공식 문서 57개를 훑은 리서치
• Next.js 사이트 개발과 배포
• 이후 대화를 통한 지속 보완 (지금 이 글의 다듬기도 같은 흐름의 연장선입니다)

나만의 워크스페이스: 네 박자로 시작

박자 ① · 목적부터 좁히기

먼저 자문해 보시면 좋습니다.

□ 어떤 작업을 반복하고 있나?
□ AI에게 어떤 역할을 맡기고 싶나?
□ 어떤 규칙을 일관되게 지키고 싶나?
□ 결과물이 어디에 쌓이면 좋을까?

박자 ② · CLAUDE.md 한 장

처음에는 다음 정도면 충분합니다. 빈 칸만 채워가시면 됩니다.

# [워크스페이스 이름]

## 역할
[AI에게 부여할 역할과 목적 — 1~2문장]

## 핵심 규칙
- [절대 지켜야 할 것 1]
- [절대 지켜야 할 것 2]
- [절대 하지 말아야 할 것]

## 폴더 구조
- [폴더명]/  → [용도]
- [폴더명]/  → [용도]

## 주요 작업 방식
[반복되는 워크플로우 설명]

박자 ③ · 폴더 구조: 번호 prefix가 쉬워요

mkdir -p 01-inbox 02-work 03-output 04-archive

번호를 앞에 붙이면 정렬 순서가 자동으로 유지돼서 작업 흐름을 한눈에 보기 좋습니다.

박자 ④ · 세 번 반복하는 일은 Skill로

같은 작업을 세 번 이상 하시게 되면 그것이 Skill 후보입니다. 자세한 작성법은 17번 섹션에서 다룹니다.

30분 실습: 내 첫 워크스페이스

거창하게 시작할 필요 없습니다. 아래는 "회의록·보고서 정리"용 업무 워크스페이스의 30분짜리 시작 흐름입니다.

1) 폴더 만들기

mkdir -p ~/Documents/ai-workspace/{inbox,meetings,reports,templates,archive}
cd ~/Documents/ai-workspace
claude

2) CLAUDE.md 만들기

Claude에게 이렇게 말씀하시면 됩니다.

"이 폴더는 업무 문서 정리 워크스페이스야.
inbox는 원본 자료, meetings는 회의록, reports는 완성 보고서,
templates에는 반복 양식을 둘 거야.

회의록은 항상 결정사항·액션아이템·미결 이슈 순서로,
보고서는 5줄 요약·핵심 근거·다음 액션 순서로 작성해.
이 규칙을 CLAUDE.md로 만들어줘."

3) 첫 Skill: 회의록 요약기

"meetings/ 폴더의 회의록 하나를 받아
결정사항·액션아이템·미결 이슈 형식으로 정리하는
meeting-summary Skill을 만들어줘."

4) 첫 실행

"/meeting-summary meetings/2026-04-29-team.md"

5) 결과가 아쉬우면 그 자리에서 개선

"액션아이템에는 항상 담당자·기한 열을 포함하게
CLAUDE.md와 meeting-summary Skill을 업데이트해줘."

한 사이클을 굴려보시면 워크스페이스의 핵심이 손에 잡힙니다. 폴더 구조가 작업물을 모으고, CLAUDE.md가 기준을 잡고, Skills가 반복을 줄여줍니다.

MCP와의 조합: 손이 더 길어집니다

여기에 MCP까지 끼우면 워크스페이스의 영향 반경이 훨씬 넓어집니다.

• Web Search: 자동 리서치
• GitHub: 코드 관리 자동화
• Slack: 팀 커뮤니케이션 통합
• Google Sheets: 데이터 자동 집계

자세한 연결 방법은 15. MCP & 외부 도구 연결에서 이어집니다.

워크스페이스는 한 번에 완성되지 않습니다. 쓰면서 불편한 게 보이면 CLAUDE.md를 고치고, 반복 작업이 보이면 Skill을 하나 더하세요. 매주 조금씩 진화하는 사무실: 이것이 워크스페이스 설계의 진짜 묘미입니다.

20. 비용 관리 & 절약 팁

같은 결과를 더 가볍게, 더 싸게: 그게 Claude Code 운영의 묘미입니다. 한 번 손에 익으면 비용 곡선이 눈에 띄게 평평해집니다.

출처: Customize your status line — Anthropic 공식 문서

Max는 "Pro의 5배·20배" 두 티어로 제공됩니다. 정확한 가격과 시간 환산은 claude.com/pricing에서 확인하세요.

비용 구조: 두 갈래

Claude Code 비용 방식은 크게 두 갈래입니다. 본인이 어느 쪽인지부터 분명히 해두시면 절약 전략이 바로 갈라집니다.

• Claude.ai Pro · Max 구독자: 정액제. 구독료에 Claude Code가 포함되어 있어 API 비용이 따로 청구되지 않습니다. /usage (또는 alias /cost·/stats)로 세션 비용·플랜 한도·활동 통계를 한 번에 보세요.
• Anthropic API 사용자: 종량제. 사용한 토큰 수만큼 요금이 듭니다. 정확한 단가와 평균 사용량은 claude.com/pricing에서 확인하세요.

이 섹션은 "어떤 플랜을 살까"가 아니라: 이미 쓰고 있는 상태에서 사용량을 줄이는 운영법에 무게를 뒀습니다. 플랜 선택 자체는 03. 요금제 안내에서 다룹니다.

토큰: 비용의 단위

토큰(token)은 Claude가 텍스트를 처리하는 단위입니다. 영어는 단어 1개가 보통 12 토큰, 한국어는 글자 23자가 1 토큰 정도. 대략적으로 4글자(영어) ≈ 1 토큰이라고 외워두시면 됩니다.

파일을 읽히거나, 질문하거나, 답변을 받을 때마다 토큰이 빠져나갑니다. 대화의 호흡이 길어질수록 더 많이 씁니다.

비용이 갑자기 부푸는 네 가지 장면

• 긴 파일을 반복해 읽힐 때: 같은 파일을 여러 번 읽으면 매번 토큰이 나갑니다. 1만 줄짜리 로그를 통째로 읽히면 한 번에 수만 토큰이 듭니다.
• 호흡이 길어진 세션을 그대로 이어갈 때: 이전 내용 전체가 컨텍스트에 따라옵니다. 무관한 작업을 같은 세션에서 계속 하면 짐만 무거워집니다.
• 고성능 모델을 일상적으로 쓸 때: Opus는 강력하지만 토큰당 비용이 높습니다. 간단한 작업에 Opus는 사치입니다.
• 자동화를 풀어둔 채 방치할 때: 사람의 감독 없이 반복 실행되면 토큰이 빠르게 쌓입니다.

절약하는 일곱 가지 작은 습관

습관 ① · /compact로 컨텍스트 정리

대화가 길어졌다 싶으면 압축이 가장 빠른 길입니다. 중요한 정보는 살리고 부피만 깎습니다.

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

CLAUDE.md에 압축 방향을 미리 박아두실 수도 있습니다.

# Compact instructions

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

💡 /clear는 컨텍스트를 통째로 초기화합니다. 전혀 다른 작업으로 넘어갈 때 깔끔하게 쓰세요.

습관 ② · 막연한 요청을 좁혀 쓰기

요청이 모호하면 Claude가 파일을 과도하게 읽게 됩니다. 짝지어 비교해 보면 차이가 분명합니다.

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

좁혀 쓸수록 꼭 필요한 파일만 읽힙니다.

습관 ③ · Haiku를 적극 활용

모든 작업에 고성능 모델이 필요한 것은 아닙니다. 작업 성격에 따라 모델을 갈아 끼우는 습관이 가장 큰 절약입니다.

• Haiku: 간단한 질문, 파일 요약, 단순 작업 (가장 저렴)
• Sonnet: 일반 코딩 작업 (기본 추천)
• Opus: 복잡한 아키텍처 설계, 어려운 추론 (최고 성능, 가장 비쌈)

세션 중에도 자유롭게 전환됩니다.

/model haiku

또는 시작 시점에 지정:

claude --model haiku

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

/model opusplan

Plan 모드의 Opus 단계는 표준 200K 컨텍스트로 동작합니다. 1M 컨텍스트 자동 확장은 opusplan엔 적용되지 않으니 큰 코드베이스에서는 Plan 단계의 분석 범위를 좁혀 시작하세요.

습관 ④ · Fast Mode는 결정적인 순간에만

/fast로 켜면 Opus 4.6이 약 2.5배 빠르게 응답합니다. 다만 토큰당 비용이 더 높습니다. 빠른 반복·실시간 디버깅처럼 속도가 결과 품질을 좌우하는 순간에만 잠깐 켜세요.

/fast

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

습관 ⑤ · /usage로 자주 들여다보기

세션 비용·플랜 한도·활동 통계를 한 번에 봅니다. /cost·/stats도 같은 명령의 alias입니다(여는 탭만 다릅니다).

/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

상태 표시줄(status line)을 설정해두시면 컨텍스트 사용량이 실시간으로 보입니다.

습관 ⑥ · CLAUDE.md 다이어트

CLAUDE.md는 Claude가 매 응답마다 들여다보는 파일입니다. 길수록 매번 더 많은 토큰을 씁니다. 실측해보면: 과도한 CLAUDE.md(약 19,000 토큰)를 핵심만 남긴 버전(약 9,000 토큰)으로 정리하면 같은 작업의 비용이 거의 절반으로 떨어집니다.

다이어트 기준은 다음과 같습니다.

[ 삭제해도 되는 것 ]
- 긴 배경 설명 ("이 프로젝트는 2023년부터...")
- 당연한 반복 ("항상 최선을 다해주세요")
- 예시 코드 블록 여러 개 (하나만 남기거나 삭제)
- 모호한 규칙 ("좋은 코드를 작성하세요")

[ 반드시 남길 것 ]
- 금지 사항 (절대 하지 말아야 할 것)
- 프로젝트 기술 스택 (1~3줄 요약)
- 자주 참조하는 파일 경로
- 언어·포맷 규칙 (구체적인 것만)

대부분의 CLAUDE.md는 정리하면 50% 이상 줄어듭니다.

습관 ⑦ · 권한 deny 룰로 대용량 폴더 차단

node_modules, .next, dist 같은 폴더를 Claude가 실수로 통째로 읽지 않게 권한 deny 룰을 걸어두세요. 공식 권한 시스템은 gitignore 문법을 그대로 받습니다.

.claude/settings.json(팀 공유) 또는 ~/.claude/settings.json(개인)에 추가:

{
  "permissions": {
    "deny": [
      "Read(./node_modules/**)",
      "Read(./.next/**)",
      "Read(./dist/**)",
      "Read(./build/**)",
      "Read(./coverage/**)"
    ]
  },
  "respectGitignore": true
}

respectGitignore(기본 true)는 @-mention 파일 picker가 .gitignore 패턴을 존중하게 만듭니다. 빌드 결과물은 자연스럽게 picker에서 빠집니다.

특히 효과가 큰 경우는: ① 모노레포처럼 파일 수가 많은 프로젝트, ② "이 프로젝트를 전체적으로 분석해줘"를 자주 던지는 작업 패턴, ③ Claude를 스크립트·정기 작업으로 반복 실행하는 환경.

⚠️ Read deny 룰은 Claude의 내장 파일 도구만 막습니다. Bash(cat·grep 등)로 같은 경로에 접근하는 것은 막지 못합니다. 더 강한 격리가 필요하면 sandboxing을 켜세요.

모델별 비용: 한눈 비교

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

정확한 단가는 Anthropic 가격 페이지를 참고하세요.

Claude.ai Max 플랜의 장점

Claude.ai Pro 또는 Max 구독자는 API 종량제 없이 Claude Code를 씁니다.

• 월정액 안에 Claude Code 사용 포함
• 별도 API 키 불필요
• 비용 걱정 줄이고 실험 자유도 ↑
• Max는 더 높은 사용량 한도

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

팀 비용 관리

API를 팀 단위로 쓰신다면 다음 셋을 챙기세요.

• Workspace 지출 한도 설정: Anthropic Console에서 팀 전체 지출 한도 지정
• 사용량 대시보드: Console에서 팀원별 비용·사용량 확인
• 병렬 작업 주의: 여러 세션·서브에이전트를 동시에 굴리면 토큰이 빠르게 쌓입니다

💡 C0 단계에서는 병렬 실행보다: 한 세션을 짧게 유지하고 /compact·/clear·명확한 파일 지정으로 비용을 누르는 편이 효과가 큽니다.

비용 절약 체크리스트: 한 페이지

✅ 작업이 끝나면 /clear로 컨텍스트 초기화
✅ 무관한 작업은 새 세션에서 시작
✅ 구체적인 파일명·함수명 명시
✅ 단순 작업은 Haiku 모델 사용
✅ Fast Mode는 결정적인 순간에만
✅ /usage로 주기적 점검 (/cost·/stats는 alias)
✅ CLAUDE.md에 compact 지침 설정
✅ CLAUDE.md는 핵심만 남기고 주기적으로 다이어트
✅ permissions.deny + respectGitignore로 대용량 폴더 차단

21. Headless 모드 & 자동화 참고

사람이 옆에 없을 때도 Claude Code가 일하도록 만드는 영역입니다. 매일 아침 브리핑, 주간 보고서, 파일 일괄 정리: 한 번 깔아두면 손이 비는 시간이 늘어납니다.

출처: Claude Code GitHub Actions — Anthropic 공식 문서

📌 이 섹션은 두 갈래로 나뉩니다

• Headless 모드 (기본): 비개발자도 쓰는 자동화. 뉴스 요약·주간 보고서·파일 일괄 처리.
• 자동 실행 시 주의점: 사람이 보지 않는 작업은 비용과 권한을 반드시 좁혀두세요.

Headless 모드란

평소 Claude Code는 터미널에서 대화형으로 굴리지만: Headless 모드는 사람 없이 자동 실행하는 방식입니다. 스크립트 안에서 Claude Code를 프로그램처럼 호출하실 수 있습니다.

Headless = 사람 없이 자동 실행

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

어떤 장면에 잘 어울릴까

• 일일 브리핑: 매일 아침 업계 뉴스를 자동 요약
• 주간 보고서: 한 주치 회의록으로 요약 보고서 자동 작성
• 파일 배치 처리: 폴더 안 PDF·문서를 한꺼번에 요약
• 콘텐츠 초안: 아이디어 폴더에서 다음 주 콘텐츠 캘린더 자동 생성

기본 사용법: -p 플래그 한 줄

-p (또는 --print)를 붙이면 비대화형으로 실행됩니다.

가장 단순한 형태

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

도구 권한 허용

파일을 읽고 쓸 수 있게 도구를 허용합니다.

claude -p "~/Downloads의 PDF를 모두 읽어 요약집.md로 정리해줘" --allowedTools "Read,Write,Bash"

JSON 출력 받기

스크립트에서 결과를 파싱하기 쉽게 JSON으로 받으실 수도 있습니다.

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

출력 형식 옵션:

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

비개발자 자동화: 세 가지 즉시 사용 예

일일 뉴스·업계 동향 요약

claude -p "inputs/links.txt를 읽고 오늘의 업계 뉴스 요약을 daily/brief_오늘날짜.md로 저장해줘" \
  --allowedTools "Read,Write"

주간 액션아이템 취합

claude -p "meetings/ 폴더의 지난 7일 회의록을 읽고 미완료 액션아이템만 표로 정리해 weekly/this-week.md로 저장해줘" \
  --allowedTools "Read,Write"

콘텐츠 캘린더 초안

claude -p "ideas/ 폴더를 읽고 다음 주 평일 5일치 콘텐츠 캘린더를 만들어 drafts/next-week.md로 저장해줘" \
  --allowedTools "Read,Write"

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

대화 이어가기

# 첫 번째 요청
claude -p "이 폴더의 문서들을 분석해줘"

# 가장 최근 대화 그대로 이어서
claude -p "그 중에서 핵심 결론 부분만 따로 모아줘" --continue

# 여러 대화 중 골라서 이어서 (선택 메뉴)
claude --resume

--continue는 마지막 세션을 자동 복귀, --resume은 이전 세션 목록에서 선택. JSON 출력(--output-format json)은 result 필드에 답변을, 메타데이터에 세션 ID를 담아 자동화 스크립트에서 다음 호출에 그대로 넘길 수 있습니다.

매일 아침 자동 실행: cron 한 줄

macOS·Linux에서는 cron으로 간단한 정기 실행을 만들 수 있습니다.

crontab -e

매일 오전 9시에 전날 회의록을 요약하려면:

0 9 * * * cd ~/Documents/ai-workspace && claude -p "meetings/ 폴더의 어제 회의록을 읽고 daily/brief.md로 요약해줘" --allowedTools "Read,Write" --max-turns 3

처음에는 자동 실행 결과를 곧장 외부로 보내지 마시고 파일로만 저장하세요. 며칠 결과 품질을 확인한 뒤 Slack·이메일·Notion 같은 외부 전송을 붙이는 편이 안전합니다.

자동화를 켜기 전 빠른 점검:

□ 결과 파일만 생성하는가?
□ --max-turns로 반복 횟수를 제한했는가?
□ 민감 정보가 외부로 전송되지 않는가?
□ 실패했을 때 로그를 확인할 수 있는가?

⚠️ 비용: 자동 실행은 토큰을 빠르게 먹습니다

사람이 옆에 없는 자동 실행은 비용 곡선이 가파릅니다. 다음 셋이 핵심입니다.

• --max-turns로 최대 반복을 제한: 무한 루프 방지
• 워크플로우에 타임아웃 설정
• 불필요한 트리거 줄이기

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

보안: 두 가지만은 꼭

• API 키를 코드에 직접 넣지 마세요. 환경 변수나 Secrets 저장소를 사용하셔야 합니다.

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

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

• Claude의 제안은 머지 전에 반드시 검토. 자동화는 편하지만, 검토 없는 자동 머지가 가장 큰 사고의 출발점입니다.
• 액션 권한은 필요한 것만으로 좁혀두세요.

입문자에게

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

Headless 모드는 Claude Code를 어느 정도 익힌 뒤에 도입하시는 것이 좋습니다. 기본 사용법·CLAUDE.md 설정·MCP 연동을 먼저 익히시고, 자동화는 그다음 단계로 충분합니다. 지금은 "이런 것도 가능하구나"로 알아두는 정도면 충분합니다.

한 페이지 요약

Headless 모드: claude -p "작업내용" --output-format json
트리거:        cron 또는 직접 실행 스크립트
비용 제어:     --max-turns, 타임아웃, 모델 선택
보안:          API 키는 코드에 직접 저장하지 않기

23. Git Worktree로 병렬 작업하기

한 저장소에서 여러 Claude를 동시에 돌리는 정석. 충돌 없이 컨텍스트만 분리합니다.

같은 저장소에서 두세 개의 일을 번갈아 진행하다 보면 "방금 어디까지 작업했더라?"로 한참 헤매는 순간이 옵니다. 저는 한동안 폴더를 통째로 복사해서 임시로 나눠 쓰다가, worktree를 알게 된 뒤로 작업 흐름이 완전히 달라졌습니다. 같은 저장소를 여러 폴더로 펼쳐 놓고, 폴더마다 다른 Claude를 앉히는 방식입니다. 충돌은 없고 컨텍스트만 깔끔하게 갈리니, 한 화면에서 디자인·API·문서 작업이 동시에 진행되는 풍경이 가능해집니다.

같은 코드베이스에서 동시에 두세 가지 일을 시키고 싶다면, 같은 디렉토리에서 두 세션을 띄우는 건 위험합니다. Worktree가 정답입니다.

Git Worktree가 뭔가요?

Git이 공식 지원하는 기능입니다. 하나의 저장소를 여러 디렉토리에 동시에 체크아웃합니다.

# 기본: 저장소 한 개 = 디렉토리 한 개 = 브랜치 한 개
~/repos/my-repo  (main 브랜치)

# Worktree 추가: 디렉토리만 늘리고 저장소는 공유
~/repos/my-repo        (main)
~/repos/my-repo-feat   (feature-A)
~/repos/my-repo-fix    (bugfix-X)

세 디렉토리가 모두 같은 .git을 가리키지만, 각자 다른 브랜치에서 일합니다.

왜 Claude Code와 잘 맞나요?

같은 코드베이스, 다른 컨텍스트, 충돌 없음: 이게 핵심입니다.

기본 명령

새 worktree 만들기

# 메인 저장소 안에서 실행
cd ~/repos/my-repo

# 새 디렉토리 ~/repos/my-repo-feat 에 feature-A 브랜치를 체크아웃
git worktree add ../my-repo-feat -b feature-A

목록 보기

git worktree list

# 출력 예
# /home/me/repos/my-repo        abc1234 [main]
# /home/me/repos/my-repo-feat   def5678 [feature-A]

정리하기

# 작업이 끝난 worktree 삭제 (디렉토리는 비워둬야 함)
git worktree remove ../my-repo-feat

# 외부에서 디렉토리를 직접 지운 경우
git worktree prune

공식 권장 흐름

1. 메인 트리는 main 브랜치 전용으로 둡니다 (배포·동기화·빠른 점검용)
2. 작업은 worktree에서: feature-X, bugfix-Y 별로 디렉토리 분리
3. 각 worktree에서 claude 시작 → 별도 세션
4. 끝나면 PR 머지 후 worktree 제거

cd ~/repos/my-repo-feat
claude

# 다른 터미널에서:
cd ~/repos/my-repo-fix
claude

두 Claude가 같은 코드베이스를 알면서도 서로 간섭하지 않습니다.

주의할 점

CLAUDE.md는 어떻게 되나요?

각 worktree는 자기 디렉토리의 CLAUDE.md를 봅니다.

• 프로젝트 공통 규칙 → 메인 저장소 CLAUDE.md에 (Git에 commit되어 있으므로 모든 worktree에 동일)
• worktree 전용 규칙 → 그 디렉토리 안의 CLAUDE.md에 (commit 안 함)
• 사용자 공통 규칙 → ~/.claude/CLAUDE.md

비개발 활용: 같은 자료, 다른 관점

코드만 worktree가 필요한 게 아닙니다. 연구 노트 저장소도 같은 패턴으로 쓸 수 있습니다.

시나리오 1: 투자 리서치

# 본 저장소 ~/research/markets
git worktree add ../markets-macro  -b macro-thesis
git worktree add ../markets-stocks -b stocks-deep-dive

• 메인 트리: 거시 지표·뉴스 클리핑·시장 구조
• macro-thesis 트리: 매크로 가설 정리, 보고서 초안
• stocks-deep-dive 트리: 종목별 재무·산업 분석

각 트리에서 Claude는 자기 폴더만 보므로 컨텍스트가 섞이지 않습니다.

시나리오 2: 부동산 매물 비교

git worktree add ../listings-seoul    -b seoul
git worktree add ../listings-bundang  -b bundang

지역별 매물·시세 자료를 별도 트리에 두고, 마지막에 메인 트리에서 종합 비교. 한 트리가 다른 트리를 모르므로 비교 단계에서 객관성이 유지됩니다.

시나리오 3: 책 한 권을 여러 챕터로

git worktree add ../book-ch3 -b chapter-3
git worktree add ../book-ch7 -b chapter-7

긴 글을 동시에 여러 챕터로 진행. 각 챕터에 다른 Claude 세션을 붙이면, 톤·구조 실험을 동시에 할 수 있습니다.

자주 하는 실수

한 줄 요약

한 저장소에서 컨텍스트만 분리하고 싶을 때, Worktree만큼 깔끔한 답은 없습니다.

24. Custom Slash Commands & Output Styles

같은 일을 두 번 시키면 슬래시 명령으로. 응답 형식은 프로젝트별로 고정.

같은 지시를 세 번째 타이핑하면서 "이거 매번 똑같이 적고 있네" 싶은 순간이 옵니다. 슬래시 명령은 그 인식이 든 순간 바로 만들면 됩니다. 한 줄짜리 별명일 뿐인데, 그 한 줄이 매일 반복되던 5분짜리 입력을 0초로 줄여줍니다. 출력 스타일도 마찬가지입니다. 프로젝트마다 답변 형식이 달라야 한다면 한 번 적어두고 나서는 신경 쓸 필요가 없습니다. 외부에 공유 가능한 작은 자산이 하나씩 쌓이는 셈이죠.

매주 같은 정리, 같은 표 형식, 같은 프롬프트를 또 입력하고 있다면: 슬래시 명령으로 옮길 시간입니다.

Custom Slash Commands가 뭔가요?

자주 쓰는 프롬프트를 /내명령어 형태로 저장해 한 번에 호출합니다. 17번 섹션의 Skills와 같은 메커니즘입니다 (Custom Commands는 Skills로 통합됨).

저장 위치:

💡 자세한 Skills 작성법은 17. Skills & 플러그인 만들기 참조. 본 섹션은 비개발 분야의 실전 예시에 집중합니다.

가장 단순한 형태

.claude/skills/morning-brief/SKILL.md:

---
name: morning-brief
description: 보유 종목 일일 브리핑
---

@portfolio.csv 를 읽고 다음 형식으로 브리핑해줘:

| 종목 | 코드 | 어제 종가 변화 | 메모 |
|---|---|---|---|

- 종목명/코드 알파벳순
- 변화는 +x.x% / -x.x% 형식
- 메모 칸은 공란 (내가 채울 자리)

이제 어떤 세션에서든:

/morning-brief

매번 같은 형식으로 결과가 나옵니다.

Output Styles가 뭔가요?

응답 자체의 톤·길이·형식을 프로젝트별로 고정하는 기능입니다. 슬래시 명령은 "무슨 일을 할지", Output Style은 "어떻게 답할지"를 정합니다.

저장 위치:

.claude/output-styles/
├── concise.md       # 짧고 명확한 응답
├── tutorial.md      # 단계별 설명 풍부
└── research.md      # 출처 포함 긴 단락

활성화:

/output-style concise

이후 모든 응답이 그 스타일을 따릅니다. /output-style default로 해제.

예시 Output Style: 짧고 명확하게

.claude/output-styles/concise.md:

---
name: concise
description: 짧고 정확한 응답. 코딩 작업 기본.
---

# Concise Style

- 본론부터 시작. 인사·서론 금지.
- 한 줄 요약 → 필요한 경우만 세부 설명.
- 코드는 변경 부분만. 전체 파일 다시 출력 금지.
- 확인 질문은 1개만. 여러 가정 동시에 묻지 말 것.
- 한국어로 답하되, 코드/명령은 영어 원문.

비개발 실전 예시: 4가지

코드만이 아니라 일상 업무·리서치도 슬래시 명령과 출력 스타일로 정형화할 수 있습니다.

1) 주식 일일 리포트

.claude/skills/daily-stock/SKILL.md:

---
name: daily-stock
description: 보유 종목 뉴스 + 거래량 변화 일일 정리
---

@watchlist.md 의 종목들에 대해 다음을 수행:

1) 각 종목의 어제자 주요 뉴스 1~2개 (가능하면 출처 표기)
2) 거래량 평균 대비 어제 변화 (있으면)
3) 다음 형식 표:

| 종목 | 뉴스 요약 | 거래량 변화 | 주의 신호 |
|---|---|---|---|

주의 신호 칸: 거래량 +50% 이상이거나 부정 뉴스가 있으면 "⚠"

호출: /daily-stock

💡 외부 데이터 접근이 필요하면 MCP 서버(15-mcp 참조) 또는 @ 첨부로 입력을 보강하세요.

2) 부동산 매물 비교

.claude/output-styles/listings.md:

---
name: listings
description: 부동산 매물은 항상 표 + 동일 컬럼으로
---

# Listings Style

매물 정보를 다룰 때는 무조건 다음 컬럼을 가진 마크다운 표:

| 매물 | 위치 | 평수 | 가격 | 층/향 | 특이사항 |

- 가격 단위는 "X억Y" 또는 "X만원/월"
- 층은 "5/15층" 형식 (현재/총)
- 특이사항: 풀옵션·반려동물·주차 등 한 줄
- 표 아래에 "총 N건, 평균 가격 ___" 한 줄 요약

활성화: /output-style listings

3) 경제지표 다이제스트

.claude/skills/weekly-econ/SKILL.md:

---
name: weekly-econ
description: 매주 월요일 주요 경제지표 다이제스트
---

@indicators.md 의 항목별로 다음 형식:

## [지표명]
- 직전 값: ___
- 컨센서스: ___ (있으면)
- 이번 발표: ___ (없으면 "예정")
- 의미 한 줄: ___

마지막에 "이번 주 가장 주목할 지표 1개"를 굵게 표시.

호출: /weekly-econ

4) 회의록 정리

.claude/skills/meeting-notes/SKILL.md:

---
name: meeting-notes
description: 회의록을 액션 아이템 우선으로 정리
---

@$ARGUMENTS 파일을 읽고 다음 순서로 정리:

1) ## 액션 아이템 (담당자·기한 포함)
2) ## 결정 사항
3) ## 논의 요약 (3줄 이내)
4) ## 미정 / 다음 회의 안건

화자 표기는 "이름:" 형식 그대로 유지.
잡담·인사·여담은 모두 제외.

호출: /meeting-notes meeting-2026-04-30.md

슬래시 명령 vs Output Style: 언제 무엇?

둘은 자유롭게 조합할 수 있습니다. "Listings Output Style"이 켜진 상태에서 /daily-stock을 호출하면, 표 형식 규칙이 자동 적용됩니다.

동적 컨텍스트: ! + 백틱

Skills 본문에서 ! 접두 + 백틱으로 명령 실행 결과를 그대로 컨텍스트에 주입할 수 있습니다.

오늘 날짜: !`date +%Y-%m-%d`

현재 디렉터리 파일:
!`ls -la`

매 호출 시점의 시스템 상태가 자동으로 들어갑니다. (자세한 사용법과 보안 옵션은 17-skills 참조)

만들 때 흔한 함정

한 줄 요약

두 번 같은 일을 시켰다면, 세 번째는 슬래시 명령으로. 매번 같은 형식이 필요하다면, Output Style로.

25. Voice·Mobile·Sandbox 실전 활용

키보드 없이도, 위험 코드도, 안전하게.

Claude Code가 책상 앞에서만 동작한다면 절반밖에 못 쓰는 셈입니다. 출퇴근 지하철에서 떠오른 아이디어는 도착할 때쯤 휘발되고, 검증 안 된 명령을 본 시스템에서 바로 돌리는 건 늘 마음이 무겁습니다. 음성으로 받아치고, 모바일로 이어가고, 위험한 건 샌드박스에 가두는 — 이 세 가지 동선만 익혀도 도구가 처음으로 "내 24시간"과 같은 박자로 움직이기 시작합니다.

Claude Code는 더 이상 책상 위 도구가 아닙니다. 폰에서, 차에서, 위험한 환경에서도 쓸 수 있습니다.

/voice: 음성 입력

타이핑 대신 말로 지시합니다.

/voice
→ 스페이스바를 누른 채 말하기

• 한국어 포함 다수 언어 지원
• 음성과 타이핑 혼용 가능 (Beta)
• 짧은 명령보다 긴 설명에 유리

💡 음성은 초안용. 정확한 파일명·명령어·코드는 타이핑으로 보완하는 편이 안전합니다.

잘 맞는 상황

• 긴 요구사항을 머리에서 정리해 풀어낼 때
• 키보드를 못 쓰는 상황 (이동 중, 식사 중)
• 화면 보고 분석하면서 동시 지시할 때

잘 안 맞는 상황

• 정확한 영문 함수명·경로 입력
• 짧고 단순한 명령
• 잡음 많은 환경

/mobile: QR로 폰에서 이어가기

세션을 폰으로 옮겨 이어 작업할 수 있습니다.

/mobile
→ QR 코드 출력
→ 폰에서 스캔
→ 같은 세션이 폰 화면에 열림

데스크톱이 잠겨도 작업은 폰에서 계속됩니다. 결과는 다시 데스크톱에 동기화됩니다.

⚠️ 모바일 인증 토큰은 만료가 짧습니다. 세션이 끊기면 다시 QR 발급.

잘 맞는 상황

• 회의 들어가야 하는데 작업이 막바지일 때
• 출퇴근길에 짧게 모니터링·승인
• 외부 미팅 중 빠른 점검

잘 안 맞는 상황

• 코드를 길게 직접 타이핑해야 할 때
• 화면이 작아 컨텍스트가 길면 가독성 떨어짐
• 보안이 중요한 작업 (공공 Wi-Fi)

/sandbox: 위험 코드를 격리해서 시험

검증 안 된 스크립트, 처음 호출하는 외부 API, 권한이 큰 명령은 샌드박스에서 먼저 돌립니다.

/sandbox
→ 격리된 환경에서 명령 실행
→ 결과만 메인 세션으로 가져옴

샌드박스에서 일어난 일은 호스트 파일시스템에 영향을 주지 않습니다.

언제 쓰나요?

💡 보안 민감한 코드는 샌드박스 + Plan Mode + Git commit 3중 안전망이 정석입니다.

비개발 실전 시나리오 3가지

시나리오 1: 출퇴근길 부동산

07:50 (지하철)
폰에서 /mobile QR 스캔 → 어제 데스크톱에서 진행한 매물 검토 세션 열기

08:00
부동산 사이트 매물 링크 3개를 폰으로 던지고
음성으로(/voice 폰 버전): "이 세 매물의 가격·평수·층 비교 표 만들어줘.
주말에 보러 갈 우선순위 매겨줘"

08:15
회사 도착 → 데스크톱 열어 보면 어떤 한 매물 비교가 표로 정리되어 있음.
자세한 분석은 책상에서 이어서.

시나리오 2: 장중 주식 메모

12:30 (점심 후 산책)
음성으로 메모:
/voice "지금 A종목이 거래량 평소 두 배인데, 뉴스는 별 게 없는 거 같아.
공시 확인해보고, 비슷한 패턴이 최근 한 달 안에 있었는지 메모만 해둬"

저녁 18:00 (책상)
세션 열어보면 메모와 함께 공시·과거 패턴 분석이 정리되어 있음.
판단·매매는 사람이.

시나리오 3: 샌드박스에서 데이터 스크래핑 안전 실험

처음 보는 사이트의 공개 데이터 50개를 가져오고 싶음.
스크립트는 GPT가 짠 거라 검증이 안 됐음.

1) /sandbox
2) Claude에게 "이 스크립트 sandbox에서 돌려서 데이터 5건만 가져와봐.
   에러나면 멈추고 알려줘."
3) 5건 결과 확인 → 정상 동작
4) 메인 세션으로 결과만 복사 → 50건으로 확장

만약 스크립트에 무한 루프나 위험 명령이 있어도 호스트는 안전합니다.

결합 워크플로우: 세 가지 동시에

출퇴근(/mobile) + 음성(/voice) + 위험 작업(/sandbox)

예: 차에서 폰으로 음성으로 "처음 보는 데이터 소스 시험해봐. 샌드박스에서 안전하게 5건만 받아와봐."

세 명령이 하나의 흐름으로 이어집니다.

보안·프라이버시 체크리스트

자주 하는 실수

한 줄 요약

책상 앞이 아닐 때도, 안전하지 않은 코드 앞에서도, Claude Code는 같이 갈 수 있습니다.

22. 다음 단계 & 리소스

가이드를 끝까지 읽으셨다면, 이 페이지는 "끝"이 아니라 시작점"입니다. 이제부터가 본 게임입니다.

출처: Claude Code overview — Anthropic 공식 문서

잠깐 돌아보면: 어떤 것을 익히셨을까

여기까지 오신 시점에서 자연스럽게 손에 쥐고 계신 것들을 짧게 짚어보겠습니다.

• Claude Code가 무엇이고 어떻게 작동하는지
• 설치와 인증 설정
• CLAUDE.md로 프로젝트 맞춤 설정
• 기본 명령어와 일상 워크플로우
• MCP로 외부 도구를 잇는 개념
• Hooks와 Skills가 필요한 상황
• 공식 플러그인을 조심스럽게 시도하는 법
• 비용 관리와 운영의 작은 습관들
• 자동화의 위치와 주의할 지점

이것은 단순히 도구 하나의 사용법을 외운 것이 아닙니다. AI에게 일을 맡기고, 결과를 확인하고, 다시 좁혀 요청하는: 새로운 일의 결을 익힌 것입니다.

다음 학습: 세 칸으로 나눠보기

칸 ① · 입문 완료 (지금 여기)

✅ 설치와 인증
✅ CLAUDE.md 작성
✅ 기본 명령어 (/help, /usage, /compact, /model)
✅ 파일 읽기·수정·문서 생성
✅ 플러그인 기본 사용

칸 ② · 중급: 실전 응용

가이드의 기초를 묶어 실제 업무에 끼워 보실 차례입니다.

나만의 워크플로우 자동화

CLAUDE.md + Hooks + Skills를 한 번에 묶으면 반복 업무가 한 줄 명령으로 줄어듭니다. 예시: 매주 보고서 초안 자동 생성, 회의록 정리, 반복 문서 포맷 통일.

작은 프로젝트의 한 사이클

자동화 플러그인을 여러 개 한꺼번에 끼우기보다, 한 프로젝트를 작은 단계로 나눠 끝까지 돌려보는 습관이 더 큰 역할을 합니다.

1) 목적 정하기 — 무엇을 만들지 한 문장으로
2) 자료 모으기 — 필요한 파일·링크·예시를 한 폴더에
3) 첫 결과물  — 가장 작은 버전부터
4) 직접 확인  — 실행·읽기·화면 확인
5) 좁혀서 수정 — 마음에 안 드는 부분만
6) 기록하기   — 배운 점을 CLAUDE.md·메모로 남기기

공식 문서나 현재 프로젝트 파일을 근거로 요청하시면 결과가 한층 안정적입니다. 잘 된 프롬프트와 실패한 프롬프트를 따로 모아두시면 다음 작업이 훨씬 빨라집니다.

멀티 세션은 "나중에"

처음에는 한 터미널·한 작업으로 충분합니다. 같은 파일을 여러 세션에서 동시에 수정하면 충돌이 납니다. 병렬 작업은 Git과 복구 방법에 익숙해진 뒤에 시도하시는 편이 안전합니다.

칸 ③ · 참고: 나중에 볼 주제

C0 단계에서는 곧장 구현하지 않으셔도 됩니다. 이름만 알아두시고, 실제로 필요해질 때 해당 섹션을 다시 펼치세요.

• MCP 서버 만들기: 외부 서비스와 잇는 표준이 있다는 정도
• Hooks 심화: 반복 확인 작업을 자동으로 굴릴 수 있다는 정도
• Skills 제작: 자주 쓰는 프롬프트를 파일로 저장할 수 있다는 정도
• Headless 자동화: 사람이 보지 않아도 실행되니 비용·권한 관리가 핵심이라는 정도

공식 리소스

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

Claude Code를 잘 쓰는 결: 두 묶음으로

도구를 익혔다면, 이제 언제 어떻게 쓰는가가 더 중요해집니다. 두 묶음으로 나눠 정리하면 머릿속 정리가 쉬워집니다.

묶음 ①: 마음껏 굴려도 좋은 작업

다음 영역에서는 결과 품질이 비교적 안정적입니다.

• 반복적인 보일러플레이트 코드 생성 (패턴이 명확해 실수 가능성 낮음)
• 테스트 코드 작성 (시그니처 기반으로 정확)
• 범위가 명확한 코드 리팩토링 (특정 파일·함수를 콕 짚어주면 안전)
• 에러 메시지 분석·수정 (로그 + 코드 맥락 결합에 강함)
• 문서화·주석 추가 (기존 코드 기반이라 할루시네이션 적음)
• 정규식·SQL 쿼리·설정 파일 (구문이 명확한 작업에 강함)
• 익숙하지 않은 언어·프레임워크 탐색 (빠른 온보딩에 효과적)
• 레거시 코드 이해와 주석 추가 (맥락 파악·설명에 탁월)

묶음 ②: 검토를 더 두텁게 해야 할 작업

다음은 두 번 보고 한 번 머지하시는 편이 안전합니다.

• 인증·보안 관련 코드 (미묘한 취약점이 끼기 쉬움)
• 결제·금융 로직 (정확성이 절대적으로 중요)
• 여러 파일을 동시에 손대는 대규모 리팩토링 (사이드 이펙트 위험)
• DB 스키마 변경·마이그레이션 (데이터 손실 가능성)
• 프로덕션 배포 스크립트 (실수 시 영향 범위 큼)
• 외부 API 연동·시크릿 처리 (키 노출, 잘못된 엔드포인트 위험)

매 작업마다 지키는 다섯 줄

1. 작업 전 git commit: 언제든 롤백 가능한 상태 유지
2. 범위 좁히기: "이 파일의 이 함수만"처럼 구체적으로
3. 생성된 코드 직접 읽어보기: 이해 못 한 코드는 쓰지 않기
4. 보안·결제 코드는 반드시 별도 검토
5. 큰 작업은 Plan Mode로 계획 먼저 (Shift+Tab)

첫 실전 프로젝트: 다섯 가지 출발점

가이드가 끝났다면 곧장 작은 한 가지로 들어가 보세요. 코딩 여부와 관계없이 시작 가능한 다섯 가지를 골랐습니다.

어떤 걸 골라야 할까

본인 일상에 가까운 쪽을 고르시면 됩니다.

• 회의가 많다 → 회의록 자동 정리 워크플로우
• 글을 자주 쓴다 → 내 업무용 Skills 만들기
• 시장·경쟁사를 자주 본다 → 경쟁사 분석 보고서
• 웹사이트가 필요하다 → 포트폴리오 사이트 만들기
• 기존 코드가 있다 → 작은 파일 하나 리팩토링

망설여진다면 회의록 자동 정리부터 시작하세요. 코딩 지식이 거의 필요 없고, 반복 절감 효과가 가장 빨리 보입니다.

출발점 ① · 회의록 자동 정리

"~/Downloads/meeting-260225.mp3 파일 있어.
 회의 내용 변환하고, 요약 + 담당자별 액션아이템 정리해서
 meeting-260225.md로 저장해줘"

녹음 파일을 텍스트로 바꾸는 도구 설치부터 정리까지 알아서 처리합니다.

출발점 ② · 내 업무용 Skill

매주 반복하시는 일을 /명령어 한 줄로 줄여보십시오.

"매주 월요일마다 지난 주 작업 내용 정리하는 Skill 만들어줘.
 GitHub 커밋 내역과 메모 파일 기반으로 주간 보고서 초안을 생성하는 방식으로."

출발점 ③ · 경쟁사 분석 보고서

"경쟁사 A·B·C 웹사이트를 분석해서
 주요 기능·가격·타깃 고객·차별화 포인트를 비교표로 정리해줘.
 competitor-analysis.md로 저장해줘"

출발점 ④ · 포트폴리오 사이트 🖥️ 개발자

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

출발점 ⑤ · 기존 코드 리팩토링 🖥️ 개발자

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

7일 실천 플랜: 처음 일주일이 핵심입니다

가이드를 읽고 그치지 않으려면, 첫 일주일에 작게라도 직접 써보는 습관이 중요합니다.

Day 1 — 감 잡기      : 연습 폴더에서 파일 생성·수정 요청
Day 2 — 규칙 만들기  : 내 작업 폴더에 CLAUDE.md 작성
Day 3 — 실제 자료    : 회의록·문서·CSV 하나 정리
Day 4 — 복구 익히기  : Esc Esc, /rewind, git diff
Day 5 — 반복 줄이기  : 자주 하는 요청 하나를 Skill로
Day 6 — 외부 연결    : Notion·GitHub·Chrome 중 하나 연결 테스트
Day 7 — 정리         : 잘 된 프롬프트·실패한 프롬프트를 CLAUDE.md에 반영

첫 주의 목표는 "큰 프로젝트 완성"이 아닙니다. 내 업무에서 반복되는 한 가지를 줄이는 것입니다.

막혔을 때의 네 박자

1. 공식 문서 확인: 대부분의 답이 여기 있습니다. code.claude.com/docs. 안에서는 /help도 가능합니다.
2. Claude Code에게 직접 묻기: Claude Code 자체가 가장 강력한 도움말입니다. "MCP 서버 추가 방법 알려줘", "이 에러 메시지 의미 설명해줘"
3. 공식 이슈 확인: github.com/anthropics/claude-code/issues
4. Anthropic 지원: 계정·결제 관련은 콘솔에서 지원 요청

마지막으로

Claude Code는 빠르게 발전하는 도구입니다. 오늘 익힌 디테일이 몇 달 뒤에는 또 달라져 있을 수 있습니다. 중요한 것은: 표면의 명령이 아니라 그 아래의 결을 익히는 것입니다.

AI와 함께 일한다는 것은 단순히 작업을 빠르게 처리한다는 뜻이 아닙니다. AI의 강점(넓은 지식·반복·패턴)과 사람의 강점(판단력·창의·도메인 지식)을 묶는 새로운 협업 방식입니다. 여기까지 읽으신 분은 그 첫걸음을 이미 떼셨습니다.

앞으로의 여정이 기대됩니다.

한 페이지 참조 카드

공식 문서  : https://code.claude.com/docs
GitHub     : https://github.com/anthropics/claude-code
플러그인   : https://github.com/anthropics/claude-plugins-official
콘솔       : https://platform.claude.com

다음 목표
  입문 → CLAUDE.md 작성·기본 명령어 숙달·플러그인 마켓 둘러보기
  중급 → 작은 실전 프로젝트·MCP 기본 설정·Hooks 하나 적용
  참고 → Skills 제작·Headless 실행·정기 자동화는 필요 시 다시

29. 업데이트 노트

책처럼 차분하게 읽되, 살아있는 가이드입니다.

이 가이드는 제가 현장에서 Claude Code를 직접 써 보며 배운 것들과 Anthropic 공식 문서를 토대로 정리해 다시 쓴 글입니다. 처음 터미널을 열기 전에 한 번 통독해 두면 시행착오가 줄어들기를 바라는 마음으로 만들었습니다.

앞으로도 새로운 기능이 나오거나 현장에서 더 배우는 부분이 있을 때마다 본문을 조금씩 다듬어 가며 계속 업데이트할 예정입니다.

알림 받기

별도의 RSS·이메일 구독 인프라는 아직 없습니다. 새 업데이트가 궁금하시다면 아래 경로를 연락 부탁드립니다.

• 메일 lee.kkhwan@gmail.com
• 사이트 sionlab.co.kr

피드백·오탈자 제보·새 챕터 요청 모두 환영합니다. 감사합니다