시작하기 전에

Claude Code를 시작하기 전에 가장 많이 받는 질문 4가지에 답합니다.

00. 시작하기 전에

검은 화면을 처음 켜본 사람의 마음으로, 가장 자주 멈추는 네 지점을 짚으며 첫 페이지를 엽니다.

지금은 SIONLAB이라는 플랫폼을 운영하며 여러 시스템을 기획하고 있지만, 처음 Claude Code를 봤을 때는 몇 시간 넘게 화면만 쳐다봤습니다. 광고를 보고 설치한 것도 아니고, 누가 설치해 준 것도 아니었습니다. 제가 필요해서 직접 설치하고 하나씩 해 보려는데, 첫 화면에서 커서만 깜빡이는 걸 보고 손가락이 멈췄습니다. "이게 정말 동작은 하는 건지, 내가 배워도 되는 건지" 막막함이 앞섰습니다.

이 책을 펼친 분들도 저와 비슷한 지점에서 멈췄을 거라 생각합니다. 여기 묶어 둔 네 가지 질문은 강의에서 자주 받은 질문이기도 하지만, 그보다 먼저 제가 처음에 가장 오래 멈춰 있었던 네 지점입니다. 인터넷 여기저기에 답은 흩어져 있었지만, 그 답이 왜 그런지까지 붙들고 이해하지 못하면 다음 막힘에서 다시 헤매게 되더군요. 그래서 이 장에는 결론만이 아니라 그 결론에 닿기까지 제가 거친 시행착오도 함께 적었습니다.

Q1. 같은 회사 도구인데 Cowork와 결이 다른 이유는?

건축 인력과 비서 — 같은 도구상자, 다른 쓰임새.

비교

Q2. 데스크톱 앱이 편한데 굳이 검은 화면으로 옮기면 무엇을 얻나요?

병렬·파이프·안정성 — 익숙함을 잠깐 내려놓을 만한 세 이유.

선택

Q3. 첫 명령을 쳐봤는데 아무 것도 안 일어나면 정상인가요?

"무엇부터"보다 먼저 "무엇을"이 와야 합니다.

첫 발

Q4. 1주일 써보니 토큰이 다 떨어지는데 제가 잘못 쓰고 있나요?

정상입니다. 그리고 그 시점이 갈아탈 신호입니다.

비용

💡 이 네 질문을 묶은 이유 — 강의에서 질문 주신 분들의 90%가 이 네 가지 중 하나에서 멈춰 있었습니다. 각 답은 30초로 끝낼 수도 있지만, 이 장에서는 조금 더 자세히 풀어보겠습니다.

Q1. 같은 회사 도구인데 Cowork와 결이 다른 이유는?

처음 두 도구 이름을 나란히 봤을 때 자연스럽게 든 생각은 "같은 모델이면 차이도 적겠지"였습니다. 실제로 써보니 정반대였습니다. 같은 부엌에 놓인 칼과 국자처럼, 같은 회사가 만들었어도 손에 쥐는 순간 할 일이 갈렸습니다.

한 줄로 요약하면 Claude Code는 만드는 도구, Cowork는 처리하는 도구입니다. "만든다"는 빈 폴더에서 시작해 무언가가 새로 생기는 일을 말합니다. "처리한다"는 이미 있는 일거리를 정돈해 다음 사람에게 넘기는 일을 말합니다. 두 행위는 닮아 보이지만 손가락이 움직이는 방향이 다릅니다.

조금 더 풀어보겠습니다.

Claude Code: 텍스트 명령으로 컴퓨터의 폴더와 파일에 직접 접근합니다. 비유하자면 설계 도면을 들고 직접 망치를 잡는 건축 인력입니다. 빈 땅에 기둥을 세우는 일이 더 익숙합니다.
Claude Cowork: 격리된 가상 환경(샌드박스) 안에서 화면을 보고 클릭하며 일합니다. 책상 옆에 앉은 비서가 메일함을 정리하고 일정을 잡아주는 풍경에 가깝습니다.

왜 Cowork는 안전하지만 느리고 비쌀까

Cowork의 격리 환경은 잘못된 명령이 내 컴퓨터에 닿지 않게 막아주는 장치입니다. 보안 측면에서는 분명한 장점이지만, 작동 원리를 따져보면 비용이 따라옵니다. Cowork는 매 순간 화면을 캡처해 → AI가 이미지를 해석하고 → 클릭할 좌표를 계산해 → 그 좌표를 클릭하는 순서를 반복합니다. 한 줄 텍스트로 끝낼 일을 매번 그림으로 풀어내는 셈이라 같은 작업에 토큰도 시간도 몇 배가 듭니다.

Claude Code는 그 단계를 건너뜁니다. 파일 이름과 줄 번호를 텍스트로 직접 다루기 때문에 같은 결과가 더 적은 토큰으로, 훨씬 짧은 시간에 끝납니다. 그리고 결과물이 "AI가 봤다"가 아니라 "파일이 실제로 바뀌었다"라서 다음 자동화로 잇거나 한 달 뒤에 재현하기도 쉽습니다.

💡 한 번은 이런 일이 있었습니다. 강의에서 Cowork와 Claude Code로 같은 작업(.csv 파일 100건 정리)을 동시에 시켜본 적이 있습니다. Cowork가 화면을 띄워 한 줄씩 처리하는 동안 Claude Code는 이미 파일을 다 손보고 진단 리포트까지 출력했습니다. 같은 모델인데 어떤 도구를 골랐느냐만 달랐을 뿐입니다.

두 도구를 함께 써야 하는 시점

직장에서 받은 메일 정리·문서 요약 같은 일은 Cowork 쪽이 자연스럽고, 새 프로젝트를 시작하거나 코드를 손볼 때는 Claude Code가 자연스럽습니다. 하나만 골라서 쓰는 게 아니라 책상 위에 둘 다 두고 상황에 맞게 집어드는 것이 합리적인 운영입니다.

저는 한동안 두 도구를 번갈아 쓰면서 어떤 작업에 어떤 도구를 써야 할지 자주 헷갈렸습니다. 메일 답장을 Code에게 시켜 어색한 결과가 나오기도 했고, 새 스크립트를 Cowork에게 시켜 한참을 빙빙 돌기도 했습니다. 한 달쯤 지나니 고민 없이 도구가 정해지더군요. 그 감각이 붙기 전까지는 위 표를 메모처럼 옆에 두고 매번 한 번씩 확인하는 편이 낫습니다.

상황	어울리는 도구	그 이유
메일·일정·기존 문서 정돈	Cowork	클릭 위주 처리, 안전
새 앱·자동화·반복 스크립트	Claude Code	텍스트 직접 조작, 빠름
분석 → 보고서 → 자동 발송	두 도구 연결	만들기는 Code, 처리·발송은 Cowork

Q2. 데스크톱 앱이 편한데 굳이 검은 화면으로 옮기면 무엇을 얻나요?

데스크톱 앱이 처음 나왔을 때 저도 "이제 터미널은 안녕"이라고 생각했습니다. 실제로 2026년 5월 시점에서 단순 기능 차이는 거의 사라졌습니다. 그런데도 일주일쯤 진지하게 두 환경을 오간 분들은 슬그머니 터미널로 돌아오시더군요. 이유는 셋입니다. 그리고 그 셋은 화면에 보이는 차이가 아니라 흐름의 차이입니다.

이유 1: 동시에 여러 일이 굴러가는 흐름

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

창 1 → 화면(프론트엔드) 손보기
창 2 → 백엔드 API 다듬기
창 3 → 테스트를 자동으로 돌리기
창 4 → README·문서 정리

네 개의 Claude가 같은 시간에 각자 일하는 동안, 사람은 결과가 떨어지는 순서대로 다음 지시를 던지면 됩니다. tmux를 써서 한 화면을 네 패널로 쪼개두면, 어느 패널이 멈췄는지·어느 패널이 결과를 뱉었는지를 깜빡임만 봐도 분간할 수 있습니다. 데스크톱 앱에서도 세션을 여럿 띄우는 것 자체는 가능하지만, 한 화면에 늘어놓고 흐름을 한눈에 잡는 일은 터미널만의 영역입니다.

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

GUI에서는 구조적으로 닿을 수 없는 길이 셋 있습니다.

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

처음에는 별 차이가 없어 보입니다. 하지만 같은 일을 두 번 해본 순간부터 길이 갈립니다. 두 번 한 일은 곧 세 번이 되고, 세 번이 된 일은 자동화 후보가 됩니다. 자동화의 입구가 GUI에선 닫혀 있지만 터미널에선 열려 있습니다.

이유 3: 안정성 — 좁혀지지만 아직은 차이가 있는

기능은 평준화됐지만 안정성에는 아직 차이가 보입니다. 제가 직접 양쪽을 같이 굴리며 메모해 둔 차이는 다음과 같습니다.

환경	Hooks	MCP 연결	체감 무게
터미널 (CLI)	안정적	안정적	가볍고 반응 빠름
데스크톱 앱	PostToolUse 버그 보고	다수 연결 시 성능 저하	상대적으로 무거움
VS Code 확장	일부 버그 보고	연결 버그 보고	에디터 위라 더 무거움

차이는 분기마다 좁혀집니다. 다만 지금 이 순간 가장 안정적이고 가벼운 곳은 여전히 터미널입니다.

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

원칙은 분명하지만, 모든 사람이 첫날부터 검은 화면을 켜야 하는 건 아닙니다. 부담의 입구가 사람마다 다릅니다.

상황	적당한 시작점	옮길 시점
터미널 자체가 낯설고 무섭다	데스크톱 앱으로 파일 읽기·수정 감각 먼저	같은 작업을 세 번 했을 때
이미 VS Code로 작업 중이다	VS Code 확장으로 현재 파일 단위부터	여러 폴더가 엮이기 시작할 때
여러 폴더·자동화·병렬을 자주 쓴다	처음부터 CLI	—

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

💡 한 번은 이런 일이 있었습니다. 한 수강생분이 "터미널은 까매서 무서워요"라고 하셨는데, 같이 데스크톱 앱으로 일주일 쓰신 뒤 본인이 먼저 "이제 터미널 켜볼게요" 하셨습니다. 결정적 트리거는 같은 보고서를 세 번째 만들었을 때였다고 합니다. 세 번째 반복이 자동화 욕구를 만들고, 그 욕구가 터미널 문턱을 넘게 합니다.

옮길 시점을 알아채는 신호 세 가지

데스크톱·VS Code에서 잘 쓰고 계신 분이 "이제 터미널로 옮겨볼까" 싶어지는 순간은 보통 셋 중 하나입니다. 본인이 어느 신호에 와 있는지 점검해 보세요.

같은 일을 세 번 한 순간 — "또?"라는 짜증이 들면 자동화 후보입니다
세션을 두 개 이상 띄우고 싶어진 순간 — 화면 하나에 다 보이지 않는 일이 늘어났다는 신호
다른 도구의 출력을 그대로 클로드에게 던지고 싶어진 순간 — 파이프(|)가 풀어줄 일입니다

세 신호가 하나도 안 떠오르면 굳이 옮기지 않으셔도 됩니다. 필요한 시점이 오면 자연스럽게 옮기게 됩니다.

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

Q3. 첫 명령을 쳐봤는데 아무 것도 안 일어나면 정상인가요?

이 질문, 강의장에서 가장 자주 받는 질문입니다. 답부터 말씀드리면 대개 정상입니다. 그리고 더 중요한 답이 있습니다 — "무엇부터 할까"보다 "무엇을 만들고 싶은가"가 먼저입니다. 이 순서를 거꾸로 놓으면 어떤 튜토리얼을 따라가도 손에 남는 게 없습니다.

공식 예제로 To-Do 앱을 따라 만들고 다 만든 직후 "이거 왜 만들었지?" 싶어 폴더째 지운 경험담을 자주 듣습니다. 도구는 익혔는데 동기가 비어 있는 상태입니다. 클로드 코드는 빈손으로 시작해도 따라갈 만큼 친절하지만, 따라갈 동기가 없으면 30분 뒤 모든 게 날아갑니다.

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

1단계 — 남이 만든 결과물부터 둘러보기

X·유튜브·블로그·Threads에서 사례를 한 시간만 돌아보세요. "이거 나도 해보고 싶다"는 장면이 반드시 한두 개 떠오릅니다. 그게 진짜 출발점입니다. 막연한 "공부해야지"가 아니라 구체적인 한 장면이 머릿속에 박히는 게 핵심입니다. 추상적 동기는 사흘이면 흐려지지만, 구체적인 한 장면은 한 달이 지나도 살아 있습니다.

내가 자주 본 신호:

"이런 자료가 있었으면 좋겠는데" — 콘텐츠 생성 욕구
"이 반복 작업이 짜증난다" — 자동화 욕구
"이 데이터 좀 정리되면 좋겠다" — 분석 욕구

세 욕구 중 하나가 머리에 박히면 클로드 코드가 그 욕구를 받아 적을 도구가 됩니다.

2단계 — "만들어줘" 대신 "물어봐"

어렴풋이 잡힌 아이디어를 곧장 명령으로 바꾸지 마세요. 먼저 클로드에게 물어보십시오.

"이런 걸 하고 싶은데, 어떤 방식이 가능해?"
"이 프로젝트를 시작하려면 뭐가 필요해?"
"비슷한 사례나 참고할 만한 구조가 있을까?"
"내 환경(WSL2/Mac/Windows)에서는 어떻게 다를까?"

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

💡 한 번은 이런 일이 있었습니다. 첫 강의 때 "오늘 To-Do 앱을 만듭니다" 하고 시작했더니 끝나고 나서 "왜 만든 건지 모르겠어요"라는 후기가 절반이었습니다. 다음 회차부터는 첫 30분을 "여러분이 진짜 짜증나는 반복 작업 한 가지를 적어보세요"로 바꿨습니다. 만족도가 즉시 두 배가 됐습니다. 도구가 아니라 욕구가 출발점입니다.

그래서 첫 명령이 조용해도 괜찮은 이유

claude를 입력했을 때 화면이 잠깐 멈춰 있어도 정상입니다. 모델이 환경을 읽고, CLAUDE.md를 찾고, 권한을 확인하는 시간입니다. 시계로 30초쯤 기다려보세요. 그래도 답이 없으면 그때 점검 순서로 넘어가세요 — which claude, node -v, ~/.zshrc(혹은 ~/.bashrc)의 마지막 줄.

이 셋만 확인해도 첫날 만나는 막힘의 9할은 풀립니다. 그래도 안 풀리면 그건 가이드 12장(자주 하는 실수)에서 다룹니다. 지금은 "조용한 화면이 정상이다"만 머리에 두고 다음 장으로 넘어가셔도 됩니다.

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

Q4. 1주일 써보니 토큰이 다 떨어지는데 제가 잘못 쓰고 있나요?

이 질문도 자주 받습니다. 잘못 쓰는 게 아니라, 제대로 쓰기 시작했다는 신호입니다. 그리고 그 신호가 플랜을 갈아탈 시점이라는 얘기이기도 합니다. 짧게 답하면: 본격 사용에는 Pro $20이 충분하지 않습니다. 길게 풀어보겠습니다.

한 가지 먼저 짚자면, "잘못 쓰고 있는지"를 의심하는 분들의 패턴은 거의 비슷했습니다. 답을 받자마자 다음 질문을 던지고, 끝까지 가보고, 안 되면 처음부터 다시 시키는 식이었습니다. 그게 잘못이 아니라 몰입의 모양새입니다. 한도는 그 몰입을 5시간 단위로 끊어 놓는 장치일 뿐, 사용자의 잘못이 아닙니다.

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

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

Max로 올라가면 무엇이 바뀌는가

Max로 올라가면 Opus 4.7이 기본이고 1M 토큰 컨텍스트 창도 자동으로 따라옵니다. "한도가 무서워서 좋은 모델을 못 쓴다"는 상태에서 벗어나는 것이 첫 번째 변화입니다. 두 번째 변화는 더 미묘합니다 — 한도가 사라지면 사람의 명령 패턴 자체가 바뀝니다. "10분만 짧게 시킬게"가 아니라 "이 작업을 끝까지 가보자"로 호흡이 길어집니다.

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

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

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

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

어떤 플랜을 고를까 — 내 상황별 권장

내 상황	권하는 플랜	이유
"일단 클로드 코드가 뭔지 맛보고 싶다"	Pro $20	잠재력 확인용으로 충분
"업무·프로젝트에 본격적으로 쓰고 싶다"	Max $100 (강력 추천)	Opus 4.7 + 5배 한도
"거의 매일 하루 종일 켜놓고 산다"	Max $200	끊김 없는 흐름 보장

💡 한 번은 이런 일이 있었습니다. Pro로 한 달 버티시던 분이 "이거 한도 때문에 마음 편히 못 쓰겠다"라며 Max로 갈아타셨는데, 다음 주에 "한도 신경 안 쓰니까 일을 더 길게 시키게 된다"라고 하시더군요. 플랜은 도구가 아니라 사용자의 사고 길이를 바꿉니다. 이게 Max가 단순한 한도 확장이 아닌 이유입니다.

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

이 장을 덮기 전에

내가 Cowork와 클로드 코드를 어떤 작업에 각각 쓸지 한 줄씩 적어 봤다
데스크톱·VS Code·터미널 중 내 입구를 정했다 (지금은 어느 하나여도 됩니다)
"내가 만들고 싶은 한 장면"을 한 줄로 적어 봤다
지금 내 플랜이 Pro인지 Max인지 확인했고, 한도 알림을 켜뒀다

다음 장(01 클로드 코드란?)에서는 방금 받으신 첫 답변이 왜 웹 챗봇과 본질적으로 다른지를 짚습니다. 차이의 실마리는 "내 폴더"에 있습니다.

Claude Code란?

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

01. 클로드 코드, 한 줄로 정리하면

"내 폴더 안으로 들어와서 일하는 AI." 이 한 줄을 한 장으로 풀어 보겠습니다. 코딩 지식은 필요하지 않습니다.

Claude Code 공식 문서 개요 페이지 출처: Claude Code overview — Anthropic 공식 문서

💡 요즘 왜 클로드 코드 얘기가 다시 늘었을까. 2025년 후반부터 코딩 보조 도구의 무게중심이 "줄을 채워주는 자동완성"에서 "한 덩어리 일을 통째로 위임하는 에이전트"로 옮겨갔습니다. "터미널 하나로 PR 한 개를 끝낸다"는 실전 후기가 한국어 커뮤니티에서도 늘면서, 마케터·기획자·연구자처럼 비개발 직군까지 검은 화면을 켜기 시작한 분위기입니다. 이 흐름의 한복판에 있는 도구가 클로드 코드입니다.

한 장면으로 머릿속에 박는 30초 정의

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

그림으로 그려보면 이렇습니다. 같은 모델이 한쪽에선 답을 화면에 띄우고, 다른 한쪽에선 결과를 파일로 남겨둡니다. 이 차이가 뒤에 이어지는 모든 변화의 시작점입니다.

💡 한 번은 이런 일이 있었습니다. Claude.ai 탭에서 한 시간을 들여 회의록 30개의 결정사항을 추리고 나서, 그 결과를 메모장에 붙여넣다가 따옴표가 깨졌습니다. 같은 일을 클로드 코드에 시켰을 때는 "결정사항만 모아 summary.md로 저장해줘" 한 줄로 끝났습니다. "답을 받아서 옮기는 사람"과 "파일이 생긴 폴더를 확인하는 사람"의 거리가 두 도구의 차이입니다.

같은 모델, 다른 쓰임새 — 웹 챗봇과의 다섯 갈래 비교

대화창에서 답을 받느냐, 폴더에 결과를 받느냐. 이 한 줄이 가장 큰 차이입니다. 표로 정리하기 전에 다섯 항목을 읽어보시면 두 도구의 결이 더 또렷해집니다.

파일 접근: 웹은 한 번에 한두 개씩 직접 올려야 합니다. 클로드 코드는 폴더 전체를 알아서 읽습니다.
작업 범위: 웹은 한 번의 대화 분량. 클로드 코드는 수십~수백 개 파일을 같은 시간에 다룹니다.
결과물 저장: 웹은 복사·붙여넣기 신세. 클로드 코드는 결과를 자동으로 파일로 남깁니다.
반복 작업: 웹은 매번 새로 시작. 클로드 코드는 한 번 알려주면 같은 패턴을 알아서 반복합니다.
장기 기억: 웹은 한 대화 안에서만. 클로드 코드는 CLAUDE.md라는 파일에 내 규칙을 영구 저장합니다.

항목	웹 (Claude.ai)	클로드 코드
파일 접근	직접 올리기 (1~2개)	폴더째 자동
작업 범위	한 대화 분량	수십~수백 파일
결과물	복사·붙여넣기	파일 자동 생성·수정
반복	매번 다시 지시	패턴화된 반복
기억	대화창 안에서만	`CLAUDE.md`에 영구

핵심 차이를 한 줄로 정리하면 이렇습니다. 웹은 답을 보여줍니다. 클로드 코드는 결과물을 폴더에 둡니다. 같은 모델이지만 손에 잡히는 결이 다릅니다.

직군별 풍경 세 장면 — 같은 도구, 다른 결

세 장면 모두 시작점은 "이렇게 해줘"라는 한 문장입니다. 직군이 다를 뿐 클로드 코드가 받는 명령의 모양은 거의 같습니다.

장면 1 · 분기 보고서 정리 (애널리스트)

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

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

장면 2 · 거래 내역 요약 (개인 투자자)

trades/ 폴더의 CSV 거래 내역을 보고
종목별 실현 손익과 보유 기간을 표로 정리해줘.
재실행할 수 있게 파이썬 코드도 같이 남겨줘.

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

장면 3 · 빨간 테스트 잡기 (개발자)

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

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

💡 한 번은 이런 일이 있었습니다. 강의에 오신 마케터분이 "PDF 30개 읽기"를 시켰는데 절반쯤 처리하다가 한 PDF의 표가 이상하다고 멈췄습니다. 클로드 코드가 그 한 장만 다른 도구로 다시 읽어보겠다고 제안한 뒤 마저 끝냈습니다. "막히면 멈추고 우회로를 제안한다"는 것 자체가 자동완성과 에이전트의 결정적 차이입니다.

어떤 사람에게 효과가 큰가 — 세 부류

다음 세 부류에 특히 잘 붙습니다.

반복적인 파일·문서 작업이 잦은 사람 — 주간 보고 양식 통일, 대량 파일 이름 정리, 폴더 구조 정돈
방대한 자료를 자주 다루는 사람 — 논문 20편 요약, 경쟁사 페이지 일괄 수집·정리, 데이터 빠른 진단
아이디어를 실물로 빠르게 시도해보고 싶은 사람 — 코딩 없이 작은 웹사이트·대시보드·자동화 도구 시범 제작

다음 문장이 익숙하시면 환영입니다.

"파이썬·엑셀 함수 없이 데이터를 정리하고 싶다"
"문서 수십 개를 일일이 열지 않고 처리하고 싶다"
"반복되는 보고서 양식이 매번 흐트러져서 짜증난다"

터미널이 낯설어도 괜찮습니다. 데스크톱 앱으로도 충분히 시작할 수 있습니다. 0장에서 정리한 신호 세 개("같은 일 세 번", "세션 두 개", "파이프 욕구") 중 하나가 들리면 그때 터미널로 옮겨도 늦지 않습니다.

반대로 다음 경우에는 굳이 클로드 코드를 고집할 필요가 없습니다.

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

어디서 돌릴 수 있나 — 입구 네 곳

데스크톱 앱

GUI 그대로, 터미널 없이 시작.

입문자 추천

터미널 (CLI)

자동화·병렬·셸 통합이 가장 매끄럽습니다.

가장 강력

VS Code / Cursor 확장

평소 쓰는 IDE 안에서 바로.

에디터 안에서

웹 브라우저

claude.ai/code 접속만으로.

설치 없이

환경	한 줄 설명	누구에게
데스크톱 앱	GUI 그대로, 터미널 불필요	입문자 추천
터미널 (CLI)	가장 강력하고 빠른 기본 환경	자동화·병렬을 자주 쓰는 분
VS Code / Cursor 확장	평소 쓰는 에디터 안에서 바로	이미 IDE에 정착한 분
웹 브라우저	`claude.ai/code` 접속만으로	설치 없이 잠깐 써볼 분

같은 엔진을 공유하므로 어디서 시작하든 같은 결과를 받을 수 있습니다. 다만 자동화·병렬 세션·셸 통합 같은 깊은 기능은 터미널에서 가장 매끄럽게 동작합니다. 입구를 정하지 못하셨다면 데스크톱 앱부터 시작해도 무방합니다 — 0장에서 짚었듯, 옮길 시점은 손이 알려줍니다.

iOS Claude 앱(모바일), Slack @Claude, Chrome 디버깅 통합도 같은 엔진을 공유합니다.

5분 체험 — 폴더 하나를 던져보기

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

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

클로드 코드가 열리면 다음을 입력해 보세요.

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

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

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

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

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

💡 한 번은 이런 일이 있었습니다. 위 실습을 해본 한 분이 "summary.md를 직접 열어서 손으로 고치고 다시 시켰더니 클로드가 그 변화를 알아채고 다음 결과를 거기에 맞췄어요"라고 하셨습니다. 파일이 결과물이자 다음 입력이 되는 구조 — 이게 웹 챗봇과 가장 다른 지점입니다.

한 줄로 마무리하면

클로드 코드 = "내 폴더 안에 들어와서 파일을 읽고, 정리하고, 결과물을 남기는 AI"

코딩을 익힐 필요가 없습니다. 파이썬을 몰라도 됩니다. 하고 싶은 일을 말로 설명하시면 됩니다. 그 결과는 대화창이 아니라 여러분의 폴더에 떨어집니다. 다음 장(02 클로드 코드로 할 수 있는 것들)에서는 이 도구로 직군별로 어떤 일을 풀어내고 있는지 더 들여다봅니다.

이 장을 덮기 전에

"내 폴더 안의 어떤 파일을 클로드에게 던져볼지" 한 줄로 적어 봤다
위의 5분 체험 명령을 입력해 summary.md가 실제로 생긴 것을 확인했다
데스크톱 앱·터미널·VS Code 중 내 입구를 정했다
Claude.ai 웹과 클로드 코드를 어떤 작업에 쓸지 한 줄씩 적어 봤다

Claude Code로 할 수 있는 것들

개발 너머의 Claude Code. 비개발자도 할 수 있는 리서치, 문서, 데이터 처리, 개인 워크스페이스까지.

02. 클로드 코드, 사실 코딩보다 이쪽에서 더 썼습니다

이름엔 "Code"가 붙어 있지만, 손에 쥐어보면 코딩에만 쓰이는 도구가 아닙니다. 터미널 위에서 돌아가는 범용 AI 에이전트라고 보는 편이 정확합니다. 저도 처음엔 코딩 도구인 줄 알고 들어왔다가, 어느 순간 회의록 정리와 강의 자료 번역에 더 많이 쓰고 있더라고요.

Claude.ai 채팅과 비교해서 뭐가 다른 건가요

"그냥 채팅창 쓰면 안 되나요?"라는 질문을 강의에서 정말 많이 받습니다. 결론부터 말씀드리면, 됩니다. 다만 아래 차이를 보고 나면 "아, 이건 채팅으로 못 하겠다"는 순간이 생깁니다.

무엇이 다른가	Claude.ai 채팅	Claude Code
파일 접근	첨부 한 건씩	폴더 통째로 읽기·수정
작업 범위	대화 한 차례	수십 개 파일 동시 처리
외부 실행	불가	터미널 명령 직접 실행
반복 자동화	매번 수동	Skills·Hooks로 한 번 설정하면 계속
장기 기억	대화 안에서만	`CLAUDE.md`에 영구 저장

처음 이 표를 봤을 때 내가 멈췄던 칸은 "폴더 통째로"였습니다. 채팅은 파일을 한 개씩 첨부해야 하고, 그것도 매 대화마다 다시 올려야 합니다. 40개짜리 강의 자료 폴더를 전부 요약해 달라고 했을 때, 채팅으로는 40번 업로드를 반복해야 했는데 Claude Code는 폴더 경로 하나로 끝났습니다.

한 문장으로 정리하면 Claude.ai는 대화 상대, Claude Code는 옆자리에서 같이 일하는 AI 동료입니다.

코딩 영역에서 할 수 있는 일

자연어로 지시하면 됩니다

작성

새 함수·파일을 한국어 묘사로 만들어냅니다

수정

버그·요구 변경에 따라 기존 코드를 다듬습니다

리팩토링

동작은 같게 두고, 구조만 정돈합니다

테스트

단위·통합 테스트 케이스를 자동으로 작성합니다

리뷰

PR 본문·변경 요약·잠재 위험을 함께 정리합니다

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

💡 한 번은 이런 일이 있었습니다. 강의에서 한 분이 "저 파이썬 못 하는데 데이터 분석 스크립트 만들 수 있나요?"라고 물었습니다. 그분이 @data.csv를 던지고 "이 파일에서 월별 합계 뽑아줘"라고 했더니, 파이썬 스크립트를 작성하고 실행해서 결과를 보여주기까지 40초가 채 안 걸렸습니다. 그분이 코드 한 줄도 이해 못 해도 됩니다. 결과물만 받으면 됩니다.

바이브코딩: 분위기로 만드는 소프트웨어

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

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

이 방식으로 실제 만들 수 있는 것: 프로토타입, MVP, 개인 도구, 작은 웹사이트, 데이터 자동화.

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

더 잘 굴리는 네 가지 습관

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

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

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

리서치 & 분석

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

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

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

저는 경쟁사 분석 보고서 작업을 할 때 이 방식을 처음 써봤는데, 평소 이틀 걸리던 작업이 세 시간으로 줄었습니다. 그 차이가 워크플로우를 완전히 바꿔놓았습니다.

리서치 작업에서 @폴더명을 쓰면 폴더 안의 모든 문서를 한꺼번에 읽힐 수 있습니다. PDF, 마크다운, 텍스트 파일이 섞여 있어도 상관없습니다. "이 자료들을 읽고 공통된 핵심 주장 세 개를 뽑아줘"라고 하면 Claude가 파일 하나하나를 열어보고 종합합니다.

문서 & 콘텐츠 제작

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

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

강의 자료 번역도 이 흐름입니다. 한국어 강의 자료를 @lecture-ko.md로 던지고 "영어로 번역해서 lecture-en.md로 저장해줘"라고 하면, 파일이 생깁니다. 번역 품질을 검토하고 "이 용어는 원문 그대로 두고, 예시만 영어권 독자에게 맞게 바꿔줘" 식으로 이어가면 됩니다.

제가 가이드 영문 버전을 처음 만들 때도 이 방식을 썼습니다. 23개 섹션을 하나씩 던지는 게 아니라 content/ko/ 폴더째로 참조하도록 하고, "모든 파일을 같은 파일명으로 content/en/에 영문 번역해줘"라고 했더니 한 번에 처리했습니다. 번역 품질은 섹션별로 검토했지만 타이핑은 전혀 하지 않았습니다.

데이터 처리

CSV·Excel 분석과 변환 (파이썬 없이도 가능)
파일 수백 개 일괄 처리(이름 변경, 형식 변환, 폴더 통일)
JSON·XML 파싱과 가공

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

"파이썬 할 줄 몰라도 되냐"는 질문에 대한 답은 "네"입니다. Claude Code가 필요한 코드를 작성하고 실행까지 합니다. 결과만 받으면 됩니다. 다만 결과가 기대와 다를 때 "어떤 기준으로 이상치를 골랐는지"를 물어볼 수 있는 호기심은 있어야 합니다. 파이썬 문법을 몰라도, "왜 이 데이터를 이상치로 판단했는지"는 물어볼 수 있어야 합니다.

학습 보조

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

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

💡 한 번은 이런 일이 있었습니다. 강의 수강생 한 분이 자격증 시험을 준비하면서 두꺼운 교재를 PDF로 갖고 있었는데, "이거 다 읽을 시간이 없어요"라고 했습니다. 그래서 @textbook.pdf를 던지고 "챕터별 핵심 개념 5개씩, 기출 유형 예상 문제 3개씩으로 요약해줘"라고 했더니 30분 만에 구조화된 노트가 나왔습니다. 그분은 그 노트로 2주 뒤에 합격했습니다.

비즈니스 워크플로우

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

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

매주 금요일 이 명령 한 줄이면 주간 보고서가 나옵니다. 처음 이걸 자동화해놓고 나서, 회의록 정리를 위해 남아있던 금요일 오후가 없어졌습니다. 그 시간에 다른 일을 합니다.

개인 AI 워크스페이스

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

예를 들어 저는 CLAUDE.md에 "보고서는 항상 결론 먼저, 그 다음 근거"라고 적어두었습니다. 이제 따로 말하지 않아도 Claude가 그 구조로 씁니다.

또 다른 사례로, 유튜브 채널 관리 용도로 CLAUDE.md에 "섬네일 제목은 6자 이내, 행동 동사로 시작"이라고 적어두었더니 썸네일 초안을 부탁할 때마다 그 규칙이 자동으로 적용됩니다. 매번 같은 말을 반복하지 않아도 됩니다. 이게 개인 AI 워크스페이스의 핵심입니다: 한 번 정해두면 계속 적용.

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

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

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

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

이 작업을 하면서 가장 놀랐던 건 "내가 해야 할 일"의 성격이 바뀐 점이었습니다. 예전엔 "어떻게 만들지"를 고민했다면, 이제는 "무엇을 만들지, 왜 이걸 만드는지"를 고민합니다. 실행은 Claude Code가 맡습니다.

실제로 가이드 초안을 쓸 때, 저는 주제와 방향만 정해주고 Claude Code가 마크다운 파일 구조를 잡고 초안을 채웠습니다. 저는 그 초안을 읽으며 "이 부분은 더 구체적으로", "이 예시는 빼줘", "여기 강의 사례를 넣어줘"라는 피드백만 줬습니다. 편집자처럼 일했고, 실제 타이핑은 거의 하지 않았습니다.

시간 기준으로 보는 비교: 회의록 정리

매주 팀 미팅 후 회의록을 정리해야 하는 상황을 예로 들어봅니다. 두 가지 방식의 소요 시간 차이가 이 도구를 쓸 이유를 요약합니다.

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

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

1년 52주를 계산하면, 기존 방식에서 회의록 정리에만 약 34시간이 쓰입니다. Claude Code 방식으로 바꾸면 그 시간이 2.6시간이 됩니다. 31.4시간을 다른 데 쓸 수 있습니다.

물론 처음 설정하는 데 시간이 듭니다. 회의록을 어느 폴더에 넣을지, 어떤 형식으로 받고 싶은지 Claude에게 한 번 설명해야 합니다. 그 설명을 CLAUDE.md에 적어두면 다음 주부터는 "이번 주 회의록 정리해줘" 한 마디면 됩니다. 처음 20분의 투자가 매주 37분을 돌려줍니다.

한 줄로 줄이면

Claude Code는 코딩 도구라기보다 "내 컴퓨터를 다룰 줄 아는 범용 AI 에이전트"에 가깝습니다. 코딩은 그 위에서 할 수 있는 일 중 하나일 뿐입니다. 가장 많이 쓰는 기능이 코딩이 아닌 사람도 많습니다. 저도 그 중 하나입니다.

이 장을 덮기 전에

내가 매주 반복하는 작업 중 "Claude Code로 자동화하면 좋겠다"는 것 하나를 떠올렸다
"코딩을 못 해도 된다"는 것을 바이브코딩 개념을 통해 이해했다
Claude.ai 채팅과 Claude Code의 차이를 한 문장으로 말할 수 있다
파일 6개 이상을 한 번에 처리해야 하는 상황에서 어떤 도구를 쓸지 알겠다

다음 장(03 제품군 & 가격)에서는 이 모든 기능을 얼마에, 어떤 플랜으로 쓸 수 있는지 솔직하게 정리합니다. 처음엔 Pro인지 Max인지 헷갈리는 게 당연한데, 결론을 먼저 드리고 이유를 설명하는 방식으로 짚겠습니다.

제품군 & 가격

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

03. 요금제 안내

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

Anthropic 공식 가격 페이지의 Free·Pro·Max 카드 출처: Anthropic 가격 페이지

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

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

내가 어떤 사용자인가	권하는 첫 선택
"한 번 맛만 보고 싶다"	Pro로 일주일 체험
"업무·프로젝트에 진짜로 쓸 거다"	Max (5x) — 가장 균형 잡힌 선택
"매일 하루 종일 켜놓고 산다"	Max (20x)

플랜별 차이를 한눈에

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

Plan

Pro

$20 /월

사용량기본 1배
기본 모델Sonnet 4.6
Opus 1M제한적 · Max 이상 권장
어울리는 사람체험·가벼운 사용

항목	Pro	Max (5x)	Max (20x)
월 비용	$17(연) / $20(월)	From $100	(Max 상위)
사용량	기본 1배	Pro의 5배	Pro의 20배
기본 모델	Sonnet 4.6	Opus 4.7	Opus 4.7
Opus 1M 컨텍스트	제한적 (Max 이상 권장)	자동 포함	자동 포함
Sonnet 1M 컨텍스트	추가 사용량	추가 사용량	추가 사용량
Claude Code	포함	포함	포함
Claude.ai 웹	포함	포함	포함
어울리는 사람	체험·가벼운 사용	Claude Code 주 사용자	헤비 유저

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

Pro의 5시간 한도는 생각보다 빠르게 찹니다. 집중 작업이면 1시간에 도달하기도 해서, 막히면 그날 흐름 자체가 끊깁니다.
Pro에서 Opus 4.7을 쓰는 건 이론상 가능, 현실적으론 어렵습니다. 한도가 너무 빨리 빠지기 때문입니다. Max로 가면 Opus가 기본입니다.
긴 대화·여러 파일·반복 수정이 쌓이면 토큰이 빠르게 누적됩니다. 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으로 전환돼 작업이 끊기지 않습니다.

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

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

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

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

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

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

03과 20의 역할 분담

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

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

이 장을 떠나기 전에

내 사용 패턴이 Pro에 맞는지 Max (5x)에 맞는지 파악했다
한도에 닿으면 흐름이 끊긴다는 점을 이해했다 (단순한 일시 정지가 아니다)
/usage 또는 /cost로 사용량을 확인하는 법을 안다
한도에 닿았을 때의 대응책을 안다: /compact, /clear, 또는 /model로 Sonnet 전환

다음 장(04. 설치 & 인증)에서 Claude Code를 실제로 머신에서 실행시킵니다. 설치 자체는 명령 한 줄이지만, 문제가 생겼을 때 무엇을 확인해야 하는지 알면 시간을 많이 아낄 수 있습니다.

설치 & 인증

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

터미널에 처음 명령어를 쳤을 때: 설치부터 첫 실행까지

명령어 한 줄을 붙여넣고, 브라우저 한 번 클릭하면 끝납니다. 부담스러워 보이는 건 처음 한 번뿐입니다. 그리고 "처음 한 번"을 같이 걸어드리는 게 이 장의 목적입니다.

Claude Code 공식 설치 가이드 페이지 출처: 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에서 동작하나요

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

하드웨어 기준이 있나요

RAM 4GB 이상이면 충분합니다
인터넷 연결 필수 (설치 중, 실행 중 모두)

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

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

OS별 설치: 어느 길로 들어가든 결과는 같습니다

macOS · Linux · WSL에서

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

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

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

brew install --cask claude-code

💡 한 번은 이런 일이 있었습니다. WSL2 환경에서 강의를 진행하다가 curl 명령 다음에 아무것도 안 나오는 상황이 있었습니다. 알고 보니 프록시 설정이 문제였습니다. 그때부터 설치 전에 curl -I https://claude.ai로 연결 확인을 먼저 하는 습관이 생겼습니다. 응답이 오면 인터넷 연결은 정상입니다.

Windows에서: 네 가지 입구

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

WSL 깔고 Linux처럼

가장 매끄럽게 동작합니다. 설정 한 단계가 더 필요하지만 권장드립니다.

입구 ① · 권장

PowerShell 직접 설치

즉시 시작 가능. 일부 기능은 제한될 수 있음.

입구 ②

CMD에서

한 줄 명령으로 끝. curl 한 줄.

입구 ③

WinGet

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 vs PowerShell, 뭘 고르면 되나요

처음 Windows에서 Claude Code를 시작하려는 분들이 가장 많이 하는 질문입니다. 간단한 기준을 드리겠습니다.

선택 기준	WSL	PowerShell 직접 설치
코드·자동화·Git 작업이 잦다	✓	—
Linux 예제와 동일하게 굴러야 한다	✓	—
문서 정리, 간단한 파일 작업부터	—	✓
Windows 폴더에 바로 접근하고 싶다	—	✓

처음부터 코드 작업이 많다면 WSL, "Downloads 폴더 정리" 같은 가벼운 흐름으로 감을 잡고 싶다면 PowerShell. 이 정도 기준으로 충분합니다. 나중에 WSL로 바꾸는 것도 어렵지 않습니다.

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 같은 외부 제공자도 사용할 수 있습니다.

로그인 흐름을 그림으로

브라우저가 자동으로 열리지 않으면 터미널에 표시된 URL을 직접 복사해서 브라우저 주소창에 붙여넣으세요. 그 URL로 로그인하면 터미널이 자동으로 인증 완료 상태가 됩니다.

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

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

설치가 잘 됐는지 확인하는 두 가지 명령

claude --version

버전 번호가 떠오르면 정상입니다. 더 자세한 진단은 다음 명령을 쓰세요.

claude doctor

claude doctor는 설치 타입·버전·환경 상태를 한 번에 보여줍니다. "뭔가 이상한 것 같다"는 느낌이 들 때 이 명령 한 줄이면 대부분 원인이 드러납니다.

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

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

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

업데이트를 너무 미루면 새 기능을 못 쓰는 것보다, 구버전에서만 나타나는 이상한 동작을 만날 수 있습니다. 월 1회 정도 claude update를 습관으로 만들어두면 편합니다.

처음 만나는 벽: 가장 흔한 세 가지 상황

상황 ① · `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는 새 셸에서 반영됩니다.

💡 한 번은 이런 일이 있었습니다. 강의 중 한 분이 claude 명령을 쳤더니 "command not found"가 떴습니다. 설치는 확실히 됐는데 셸이 못 찾는 상황이었습니다. which claude를 쳐서 경로를 확인하고, node -v로 Node 환경이 정상인지 보고(npm 설치를 선택한 경우에 한정. 네이티브 인스톨러는 Node 불필요.), ~/.zshrc 마지막 줄을 확인하는 세 단계로 5분 만에 해결했습니다. nvm을 쓰면서 다른 노드 버전으로 셸이 떨어져 있었던 게 원인이었습니다. 지금도 설치 직후 문제가 생기면 이 순서대로 점검합니다.

상황 ③ · Windows에서 "Git이 없습니다" 메시지

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

설치가 끝났다면

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

# 작업할 폴더로 이동 후 실행
cd ~/Desktop/my-project
claude

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

처음 켰을 때 아무 말도 안 하고 기다리고 있으면 정상입니다. 거기에 작업 지시를 치면 됩니다. 입력 대기 상태가 맞습니다.

이어서 알아두면 좋은 것들

처음 작업 지시로 좋은 문장

설치 직후 첫 문장이 막막하다면 이걸 그대로 입력해보세요.

이 폴더를 훑어보고 어떤 파일이 있는지 요약해줘.

아무것도 없는 빈 폴더라도 괜찮습니다. "빈 폴더입니다. 어떤 작업을 시작하면 될까요?"라고 물어봐 줄 겁니다. 거기서 "샘플 회의록 파일 하나 만들어줘"라고 이어가면 됩니다.

첫 세션에서 실수해도 됩니다

Claude Code는 파일을 수정하기 직전에 내용을 보여주고 허용 여부를 묻습니다. "이렇게 바꿔도 됩니까?" 하고 물어보는 방식입니다. 처음에는 이 확인 단계를 통해 어떤 작업을 하는지 눈으로 볼 수 있습니다. 허용하기 싫으면 "n"만 입력하면 됩니다.

실수가 났다 싶으면 Esc를 두 번 눌러 직전 상태로 돌아갈 수 있고, 또는 "방금 한 것 취소해줘"라고 말하면 Claude가 원복 작업을 합니다.

설치 경로별 업데이트 방법 정리

설치 방법에 따라 업데이트 명령이 다릅니다. 나중에 찾느라 헤매지 않도록 미리 기록해두세요.

설치 방법	업데이트 명령	자동 업데이트
네이티브 인스톨러 (curl)	`claude update`	자동 (다음 실행 시 적용)
Homebrew	`brew upgrade claude-code`	수동
WinGet	`winget upgrade Anthropic.ClaudeCode`	수동
apt / dnf / apk	`sudo apt upgrade claude-code`	수동

네이티브 인스톨러가 가장 편합니다. 새 버전이 나오면 실행 시 백그라운드로 다운로드해두고, 다음 실행 때 조용히 적용됩니다.

CLAUDE.md를 지금 만들어두면 좋습니다

설치 직후에 CLAUDE.md를 만들어두는 것을 권장합니다. Claude에게 "이 프로젝트의 규칙과 나의 선호 방식을 CLAUDE.md에 기록해줘"라고 하면 됩니다. 처음엔 내용이 거의 없어도 괜찮습니다. "한국어로만 대답해줘"라는 한 줄만 있어도 됩니다. 세션을 쌓아가면서 채워갈 수 있습니다.

CLAUDE.md는 세션이 시작할 때마다 자동으로 읽힙니다. 매번 같은 설명을 반복하지 않아도 되는 핵심 메모장입니다.

연결이 안 된다면: 네트워크 점검 순서

회사 네트워크, VPN, 방화벽 환경에서는 Claude Code가 Anthropic 서버에 접속하지 못하는 경우가 있습니다. 이럴 때 점검하는 순서입니다.

curl -I https://api.anthropic.com — 응답이 오면 서버 연결 OK
VPN을 끄고 재시도
방화벽 정책으로 막혀 있으면 IT팀에 api.anthropic.com:443 허용 요청
프록시 환경이면 HTTPS_PROXY 환경변수를 설정한 뒤 실행

대부분 VPN을 끄거나 프록시 설정을 추가하면 해결됩니다. 사내 환경에서 쓰려면 IT팀과 한 번 확인이 필요할 수 있습니다.

이 장을 덮기 전에

claude --version이 버전 번호를 출력하는지 확인했다
claude doctor로 환경 상태를 한 번 확인해봤다
처음 claude를 실행했을 때 브라우저 로그인 흐름을 완료했다
어떤 OS 설치 경로를 사용했는지 기억하고 있다 (업데이트 방법이 다르다)

다음 장(05 초보자 워크플로우)에서는 방금 열린 터미널에서 무엇을 타이핑해야 하는지, 첫 세션의 여섯 박자를 같이 걸어봅니다.

초보자 워크플로우

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

첫날 터미널을 켰을 때: 어디서 시작하는지 모르는 사람을 위한 워크플로우

첫 세션에서 아무것도 안 하고 멍하니 터미널을 바라본 경험이 있으신가요? 저는 있습니다. 화면이 깜박이고 커서만 있는데 무엇을 쳐야 할지 몰랐습니다. 그 순간을 줄여드리는 게 이 장의 목적입니다.

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

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

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

작업 폴더로 이동

cd ~/Desktop/my-project

Claude Code 실행

claude 입력 후 Enter

프로젝트 파악 요청

CLAUDE.md를 함께 만들어 둡니다

작업 요청

자연어로 원하는 작업을 전달합니다

결과 확인과 피드백

아쉬운 부분이 있으면 바로 이어서 말씀하세요

세션 마무리

/quit 또는 Ctrl+D

① 작업할 폴더로 들어가기

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

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

처음 시작할 때 어떤 폴더든 괜찮습니다. 빈 폴더도 됩니다. "이 폴더에서 뭘 할지 모르겠어요"라고 Claude에게 말해도 됩니다. 같이 정할 수 있습니다.

② Claude Code 실행

claude

claude를 입력하고 Enter. 대화형 모드가 뜨면 준비 끝입니다. 처음에는 설정 화면이 잠깐 뜰 수 있습니다. 테마, 자동 업데이트 설정 정도입니다. 그냥 기본으로 두셔도 충분합니다.

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

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

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

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

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

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

💡 한 번은 이런 일이 있었습니다. 강의에서 한 분이 "프로젝트 파악 요청을 꼭 해야 하나요?"라고 물었습니다. 안 해도 된다고 했더니 그분은 바로 "로그인 기능 만들어줘"라고 했습니다. Claude가 만들어 준 코드가 기존 파일 구조와 전혀 맞지 않아서 전부 다시 해야 했습니다. 프로젝트 파악 5분이 재작업 1시간을 막습니다. 지금도 새 폴더에 들어갈 때는 꼭 먼저 파악을 요청합니다.

④ 일을 시키기

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

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

처음에는 작게 시작하세요. 한 번에 너무 많은 걸 요청하면 결과가 흩어집니다. "로그인 화면 먼저"가 "로그인·회원가입·비밀번호찾기·소셜로그인 다 해줘"보다 훨씬 나은 결과를 냅니다.

⑤ 결과 보고 피드백하기

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

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

피드백이 구체적일수록 다음 결과가 좋아집니다. "더 좋게 해줘"보다 "이 함수의 반응 속도가 느린데 최적화해줘"가 훨씬 명확한 지시입니다.

⑥ 세션 마무리

> /quit

Ctrl+D도 같은 동작입니다. 세션이 끝나면 대화는 사라지지만, 파일과 CLAUDE.md는 그대로 남습니다. 다음 세션에서 이어갈 수 있습니다.

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

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

같은 요청도 디테일이 더해지면 결과 품질이 확연히 달라집니다.

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

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

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

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

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

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

한 번에 한 가지, 그 다음 한 가지. 이게 의외로 전체 속도를 높입니다. 한 번에 몰아치면 재수정이 더 많아집니다.

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

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

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

출력 형태를 명시하면 후처리가 줄어듭니다.

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

@ 뒤에 파일 경로를 붙이면 Claude가 그 파일을 곧장 읽습니다.

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

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

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

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

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

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

"이게 왜 안 되는지 모르겠어. 한 번 처음부터 같이 생각해줘"라고 해도 됩니다. Claude는 대화를 되짚어보며 어디서 전제가 틀렸는지 찾아줍니다.

도메인별 실전 시나리오

문서·업무

> @회의록-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)

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

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

켜는 방법

Shift+Tab 두 번    또는    > /plan

언제 켜는 게 이득일까

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

Plan Mode를 켜면 Claude는 "무엇을 어떻게 바꿀지"를 먼저 설명합니다. 그 계획이 마음에 들면 일반 모드로 전환해서 실행합니다. 마음에 안 들면 계획 단계에서 방향을 바꿀 수 있습니다. 실수가 훨씬 줄어드는 방식입니다.

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

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

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

API 키·비밀번호·개인 인증서는 환경변수나 .env로 분리하시고, 대화창에 직접 입력하지 마세요. 실수로 한 번 넣은 정보는 대화 기록에 남습니다.

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

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

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

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

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

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

리팩토링·마이그레이션 전에 한 번 커밋해두는 작은 습관이, 며칠치 작업을 살리는 보험이 됩니다. "지금 상태를 git에 저장해줘"라고 Claude에게 부탁해도 됩니다.

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

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

> /rename housing-price-analysis

나중에 이어할 때:

claude --resume housing-price-analysis

세션 이름을 붙여두면 여러 프로젝트를 동시에 진행할 때 어느 맥락인지 헷갈리지 않습니다.

호흡이 길어지면 압축을

응답이 느려지거나 앞에서 합의한 내용을 다시 어기는 신호가 오면 컨텍스트가 찼다는 뜻입니다.

> /compact

"결정사항·바뀐 파일·남은 작업만 중심으로 압축해줘"처럼 구체적인 지시를 함께 주면 더 깔끔하게 정리됩니다.

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

> /clear

이전 대화와 완전히 다른 주제를 시작할 때는 컨텍스트를 비우세요. 이전 작업의 잔상이 새 작업에 끼어드는 걸 막을 수 있습니다.

첫날 15분 루틴

처음이라면 결과물 완성도보다 흐름의 결을 익히는 게 먼저입니다. 딱 15분만 투자하면 됩니다.

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

실제로 던질 한 줄:

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

오늘의 목표는 산출물 품질이 아니라 지시 → 확인 → 재지시의 사이클을 손끝으로 한 번 굴려보는 것입니다. 이 사이클이 몸에 붙으면, 나머지는 자연스럽게 따라옵니다.

💡 한 번은 이런 일이 있었습니다. 강의에서 "첫 세션 15분 루틴"을 같이 해봤는데, 절반 이상이 15분 안에 기대보다 훨씬 많은 것을 해냈습니다. 루틴이 끝난 뒤 "이것도 되나요?"를 연발하며 스스로 탐색하기 시작했습니다. 막막함이 사라지는 순간이었습니다. 첫 15분이 전환점이었습니다.

멀티 세션: 여러 작업을 동시에 굴릴 때

Claude Code는 한 터미널에서 한 세션만 쓰는 게 기본이지만, 여러 터미널 창을 열어서 동시에 작업을 진행할 수 있습니다. 저는 보통 이렇게 씁니다.

터미널 창 1: 코드 개발 세션
터미널 창 2: 문서 정리 세션
터미널 창 3: 데이터 분석 세션

각 세션은 독립된 컨텍스트를 가집니다. 세션 1의 코드 작업이 세션 2의 문서 작업에 영향을 주지 않습니다. 단, 파일 시스템은 공유됩니다. 같은 파일을 두 세션에서 동시에 수정하면 충돌이 날 수 있으니 주의하세요.

더 체계적으로 병렬 작업을 하려면 Git Worktree를 활용하는 방법이 있습니다. 같은 저장소에서 여러 Claude 세션을 충돌 없이 돌리는 방법은 나중에 다루는 워크트리 섹션에서 자세히 설명합니다.

어려운 상황에서의 대응 패턴

Claude가 계속 같은 실수를 반복할 때

가끔 Claude가 같은 실수를 두세 번 반복하는 경우가 있습니다. 이럴 때는 프롬프트 방식을 바꾸는 것보다 맥락을 리셋하는 게 더 효과적인 경우가 많습니다.

> 잠깐, 지금까지 한 작업을 멈추고.
  처음부터 다시 생각해줘.
  내가 원하는 건 [명확한 설명]. 이 방향이 맞는지 확인해줘.

또는 /clear로 완전히 초기화하고 새 접근을 시도해보세요.

너무 긴 답변이 돌아올 때

"자세히 설명해줘"라고 하면 너무 긴 답변이 올 수 있습니다. 이럴 때는 출력 형태를 제한하는 게 도움이 됩니다.

> 핵심만 3줄로 요약해줘
> 실행 가능한 명령어만 알려줘, 설명은 최소화해서
> 결론 먼저, 이유는 필요할 때 물어볼게

짧고 행동 중심으로 받으면 확인하고 피드백하는 속도가 빨라집니다.

파일을 너무 많이 건드릴 것 같을 때

Plan Mode를 켜고 먼저 계획을 확인하세요. 또는 이렇게 물어봐도 됩니다.

> 이 작업에서 어떤 파일을 건드리게 되는지 먼저 목록만 알려줘

파일 목록을 확인한 뒤에 "그 파일들만 건드려도 되는지" 판단하고, 괜찮으면 실행을 허용합니다. 이 확인 단계 하나가 실수를 많이 막아줍니다.

세션 운영의 실전 팁

시작할 때 컨텍스트 설정을 먼저

새 세션을 시작할 때 Claude에게 맥락을 먼저 설명하면 이후 작업이 훨씬 매끄럽습니다.

> 오늘은 @project/src/ 폴더에 있는 React 컴포넌트 리팩토링을 할 거야.
  현재 기술 스택은 React 19, TypeScript, Tailwind CSS야.
  한국어로 대화하고 싶어. 코드 변경 전에 반드시 내 확인을 받아줘.

이 다섯 줄로 세션 전체의 기본 규칙이 잡힙니다. 이걸 CLAUDE.md에 넣어두면 매 세션마다 자동으로 적용됩니다.

작업 도중 방향이 바뀔 때

중간에 "아 이건 다른 방향으로 가야겠다"는 생각이 들면 주저 없이 말하세요.

> 잠깐, 방향을 바꾸고 싶어. 지금까지 한 건 놔두고,
  대신 [새로운 방향]으로 접근해줘.

Claude는 중간에 방향을 바꿔도 잘 따라옵니다. 이미 바뀐 파일이 걱정된다면 "방향 바꾸기 전에 현재 상태를 git에 커밋해줘"라고 먼저 요청하세요.

하루 작업을 마무리할 때

세션을 닫기 전에 이렇게 마무리하면 다음 날 이어가기가 훨씬 쉽습니다.

> 오늘 작업 내용 요약해줘:
  - 무엇을 완료했는지
  - 무엇이 미완인지
  - 내일 이어가야 할 것
  - 주의할 사항
  이걸 TODO.md에 저장해줘.

TODO.md가 생기면 내일 세션 시작 시 @TODO.md로 불러오면 됩니다. "어제 어디서 멈췄더라?"를 기억에 의존하지 않아도 됩니다.

특정 작업에 쓸 프롬프트를 재사용하고 싶을 때

같은 형태의 작업을 반복한다면 프롬프트를 파일로 저장해두는 게 편합니다.

prompts/weekly-report.md에 다음처럼 저장해두면:

meetings/ 폴더에서 이번 주 회의록을 읽고
결정사항·담당자별 액션 아이템·다음 주 리스크를 weekly-report.md로 모아줘.
형식은 항상 결론 먼저, 상세는 접힌 섹션으로 처리해줘.

매주 @prompts/weekly-report.md 실행해줘라고 하면 됩니다. 복잡한 지시를 매번 입력하지 않아도 됩니다. 이게 바로 Skills로 발전시킬 수 있는 씨앗이기도 합니다.

모델을 선택하는 기준

Claude Code에서는 작업에 따라 모델을 선택할 수 있습니다. 기본적으로 Pro는 Sonnet, Max는 Opus 4.7이 기본 모델입니다. 상황에 따라 바꿔 쓰는 것이 비용과 품질을 함께 최적화하는 방법입니다.

> /model sonnet   # 빠르고 가벼운 작업
> /model opus     # 복잡한 설계·추론이 필요할 때
> /model opus[1m] # 긴 문서·코드베이스 전체를 다룰 때

저는 보통 이렇게 씁니다:

Sonnet: 파일 정리, 번역, 간단한 수정, 문서 초안
Opus: 아키텍처 설계, 복잡한 버그 디버깅, 긴 맥락이 필요한 분석
Opus 1M: 전체 코드베이스 리뷰, 수십 개 파일을 한 번에 처리하는 작업

1M 컨텍스트 모델은 더 많은 사용량을 소비합니다. 꼭 필요한 작업에만 쓰는 게 합리적입니다. 대부분의 일상 작업은 Sonnet으로 충분합니다.

좋은 워크플로우의 결

결국 잘 굴리는 워크플로우는 이 흐름에 수렴합니다.

폴더로 이동해서 맥락 설정 — 어디서 작업하는지, 무엇을 만드는지 Claude에게 알려줍니다.
작게 쪼개서 요청 — 한 번에 하나, 완료를 확인하고 다음으로 넘어갑니다.
결과를 직접 확인 — Claude가 만든 것을 눈으로 보고 실행해봅니다.
구체적인 피드백 — "더 좋게"가 아니라 "이 부분, 이 이유로, 이렇게 바꿔줘"라고 합니다.
주기적으로 상태 점검 — /compact, 커밋, TODO.md로 현재 위치를 명확히 유지합니다.

처음엔 이 흐름이 낯설고 번거롭게 느껴질 수 있습니다. 하지만 일주일만 이 패턴으로 작업해보면 손이 기억합니다. 그때부터는 흐름을 의식적으로 생각하지 않아도 자연스럽게 따라가게 됩니다.

프롬프트 패턴 모음: 상황별로 바로 쓰는 문장들

자주 쓰게 되는 프롬프트 패턴을 정리했습니다. 그대로 복사해서 쓰셔도 됩니다.

작업 시작

이 프로젝트를 처음 보는 사람이 이해할 수 있게 CLAUDE.md를 만들어줘.
기술 스택, 폴더 구조, 핵심 규칙 세 가지를 포함해서.

파일 분석

@[파일명] 이 파일의 주요 역할과 개선할 수 있는 부분을 설명해줘.
실행 가능한 개선 제안 3개를 우선순위 순서로 알려줘.

버그 수정 요청

아래 에러가 발생했어. 원인을 설명하고 수정 방법을 알려줘.
[에러 메시지 붙여넣기]

수정 전에 어떤 파일을 건드릴지 먼저 알려줘.

새 기능 추가

[기능 설명]을 추가하고 싶어.
먼저 구현 방법을 Plan Mode로 계획해줘.
계획이 확인되면 실행하겠다고 말할게.

코드 리뷰 요청

@[파일명] 이 파일을 리뷰해줘.
- 잠재적인 버그
- 성능 문제
- 보안 취약점
- 코드 품질 개선점

각 항목을 심각도(높음/중간/낮음)와 함께 표로 정리해줘.

문서 정리

@[폴더명] 이 폴더의 문서들을 읽고
목차 + 각 문서의 핵심 요약(3줄 이내) + 연관 관계를 index.md로 만들어줘.

데이터 분석

@[데이터파일] 이 데이터를 분석해줘.
1. 전체 개요 (행 수, 컬럼, 기본 통계)
2. 이상치 탐지
3. 주요 패턴 3가지
4. 추가 조사가 필요한 영역

결과를 analysis-[날짜].md로 저장해줘.

워크플로우를 망치는 나쁜 습관들

강의를 하면서 공통으로 빠지는 함정들이 보입니다. 알아두면 처음부터 피할 수 있습니다.

함정 ① 너무 큰 작업을 한 번에 요청하는 것

가장 흔한 실수입니다. "전체 프로젝트 리팩토링해줘"처럼 범위가 너무 큰 작업을 던지면 결과가 예측 불가능해집니다.

좋지 않은 예:

이 프로젝트 전체를 최신 버전으로 업그레이드하고,
코드 품질을 개선하고, 테스트도 추가하고,
문서도 업데이트해줘.

좋은 예:

package.json에서 가장 낡은 의존성 세 개가 뭔지 알려줘.

→ 확인 후: "이 세 개를 업그레이드할 때 주의할 점 알려줘." → 확인 후: 하나씩 업그레이드.

함정 ② 피드백 없이 계속 진행하는 것

Claude가 작업을 하는 동안 "그래 계속해"만 하다 보면, 방향이 조금씩 틀어지는 걸 모르고 나중에 크게 되돌려야 하는 상황이 됩니다. 중간중간 확인하는 게 결국 빠릅니다.

긴 작업 중에는 10~15분 단위로 "지금까지 한 게 뭔지 요약해줘"라고 한 번씩 체크하는 습관이 도움이 됩니다.

함정 ③ Git 커밋을 미루는 것

"완성되면 커밋하자"는 생각이 함정입니다. 큰 작업을 시작하기 전, 중요한 변경이 생길 때마다 커밋을 찍어두는 게 안전합니다.

Claude에게 "지금 상태로 커밋해줘. 메시지는 [내용 설명]으로."라고 하면 됩니다. 커밋 메시지도 Claude가 작성해줍니다.

함정 ④ 모호한 "더 좋게 해줘" 피드백

"이거 더 좋게 해줘"는 Claude에게 너무 넓은 허가를 주는 표현입니다. Claude는 나름대로 "더 좋게"를 해석해서 예상치 못한 방향으로 바꿀 수 있습니다.

대신 이렇게 쓰세요:

이 함수의 응답 속도를 개선해줘. 현재 1000건 처리에 3초인데 1초 이내로.
알고리즘을 바꾸되, 외부 API 의존성은 추가하지 말고.

무엇을 개선하는지, 측정 기준은 무엇인지, 제약 조건은 무엇인지가 담기면 훨씬 좋은 결과가 나옵니다.

자주 쓰는 슬래시 명령 정리

작업 중에 자주 쓰게 되는 슬래시 명령들입니다. 처음부터 다 외울 필요는 없습니다. 막힐 때 여기 와서 찾으세요.

명령	용도
`/compact`	컨텍스트가 길어졌을 때 압축
`/clear`	새 작업 시작 전 초기화
`/quit`	세션 종료
`/plan`	Plan Mode 진입
`/rename [이름]`	세션에 이름 붙이기
`/context`	현재 컨텍스트 사용량 확인
`/usage`	세션 비용·플랜 한도 확인
`/model`	모델 변경 (sonnet, opus 등)

/help를 입력하면 전체 명령 목록이 나옵니다. 모르는 게 있으면 > /[명령어]는 어떨 때 쓰는 건지 설명해줘라고 Claude에게 물어봐도 됩니다.

한 줄로 줄이면

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

이 장을 덮기 전에

작업 폴더로 이동해서 claude를 실행해봤다
첫 지시를 입력하고 응답을 받아봤다
/compact, /clear, /quit 명령을 한 번씩 써봤다
CLAUDE.md가 무엇인지 이해했다
"한 번에 한 가지"라는 원칙을 기억하고 있다

다음 장(06 플러그인 설치)에서는 이 워크플로우를 더 편리하게 만들어주는 플러그인들을 살펴봅니다. 설치 한 줄이면 기능이 새로 열리는 경험을 해보실 수 있습니다.

플러그인 설치

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

한국어 추천

플러그인이 달라지게 한 순간: 설치 한 줄로 열리는 기능들

기본만으로도 Claude Code는 강력합니다. 그런데 강의에서 함께 GitHub 플러그인을 설치한 날, 뭔가 달라진 걸 느꼈습니다. "저장소에 열린 이슈 다섯 개 요약해줘"라고 했더니 Claude가 바로 GitHub API를 호출해서 결과를 가져왔습니다. 그전까지는 링크를 복사해서 Claude에게 붙여넣어야 했는데요. 그 차이가 생각보다 컸습니다.

그날 이후로 강의장에서 가장 자주 받는 질문이 "플러그인은 언제부터 깔아야 해요?"가 되었습니다. 답은 늘 같습니다 — 같은 작업을 두 번 했을 때가 그 시점입니다. 한 번은 우연, 두 번은 패턴, 세 번부터는 자동화가 기다리고 있다는 신호입니다. 플러그인은 그 자동화의 입구를 한 줄로 열어주는 도구입니다.

플러그인이 뭔가요: 스마트폰 앱에 가장 가까운 비유

기능

Skills

형태/플러그인명:명령어
언제내가 직접 호출
예/lint, /summarize

기능

Agents

형태역할 가진 AI
언제복잡한 작업 위임
예reviewer, researcher

기능

Hooks

형태이벤트 핸들러
언제자동으로 트리거
예저장 시 lint, 커밋 전 검사

기능

MCP 서버

형태외부 서비스 다리
언제외부 데이터 필요할 때
예GitHub, Figma, Notion

스마트폰 본체로도 전화·메시지·카메라가 다 됩니다. 앱을 깔면 가계부, 사진 편집, 날씨 알림 같은 영역이 새로 열립니다. 플러그인이 바로 그겁니다. Claude Code 위에 얹어 쓰는 기능 꾸러미입니다.

한 꾸러미 안에는 보통 다음 네 가지 중 한두 개가 들어 있습니다.

Skills — /플러그인명:명령어 형태의 커스텀 명령어. 내가 직접 호출합니다.
Agents — 특정 역할을 맡는 AI 에이전트. 리뷰어, 리서처처럼 역할이 있는 조력자입니다.
Hooks — 파일 저장·명령 실행 같은 이벤트에 자동으로 반응하는 핸들러. 명시적으로 호출하지 않아도 됩니다.
MCP 서버 — GitHub·Figma·Notion 같은 외부 서비스와 연결하는 다리. 이게 있어야 Claude가 외부 서비스의 데이터를 직접 읽고 씁니다.

이 네 가지를 미리 다 이해할 필요는 없습니다. 설치하고 써보면서 자연스럽게 파악됩니다.

어디서 찾나요: 공식 마켓플레이스부터

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 커밋 메시지 작성을 도와줍니다. 변경 내용을 보고 적절한 메시지를 제안합니다.

🖥️ 개발자용: 코드 인텔리전스 플러그인

코드 인텔리전스 영역에는 LSP 기반 플러그인이 잘 어울립니다.

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

타입 오류를 실시간으로 감지하고, 정의·참조 탐색 같은 IDE 기능을 Claude가 직접 활용할 수 있게 됩니다. 코드를 읽을 때 더 정확한 판단이 가능해집니다.

설치 흐름: 세 단계면 끝납니다

① 마켓에서 골라 설치하기

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 → "#general 채널의 오늘 주요 논의를 다섯 줄로 압축해줘"
commit-commands → "지금 스테이징된 변경 사항에 맞는 커밋 메시지를 제안해줘"

읽기 전용 요청이 잘 동작한 걸 확인한 뒤에야, 쓰기·수정 권한이 필요한 작업으로 한 단계씩 넓혀가는 편이 안전합니다.

💡 한 번은 이런 일이 있었습니다. GitHub 플러그인을 처음 설치하고 바로 "이 이슈를 닫고 PR을 머지해줘"라고 했습니다. Claude가 실제로 실행했고, 아직 검토가 안 된 PR이 머지됐습니다. 그때부터 새 플러그인은 항상 읽기 전용 요청으로 먼저 테스트하는 습관이 생겼습니다. 쓰기 권한은 충분히 확인한 뒤에 줍니다.

일상적인 플러그인 관리

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

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

플러그인이 많아지면 Errors 탭을 주기적으로 확인하는 게 좋습니다. MCP 서버가 응답을 못 하거나 설정이 틀렸을 때 여기에 오류가 표시됩니다.

플러그인을 쓸 때 알아두면 좋은 것들

권한 설정을 꼭 확인하세요

플러그인을 설치할 때 어떤 권한을 요구하는지 확인하세요. GitHub 플러그인은 저장소 읽기 권한부터 쓰기 권한까지 설정할 수 있습니다.

/permissions

허용·거부·확인 세 단계로 각 동작의 허용 범위를 직접 설정할 수 있습니다. 처음엔 "확인" 단계로 두고, 신뢰가 쌓이면 "허용"으로 바꾸는 방식을 권합니다.

MCP 서버는 쓸 때만 켜두세요

MCP 서버는 외부 서비스와 연결을 유지합니다. 쓰지 않는 연결이 많으면 응답 속도가 느려지고 불필요한 토큰을 소비할 수 있습니다. 필요할 때만 활성화하는 습관이 좋습니다.

/plugin disable [사용하지 않는 플러그인명]

작업 목적에 따라 플러그인 세트를 바꾸는 것도 방법입니다. 코딩 작업을 할 때는 typescript-lsp를, 콘텐츠 작업을 할 때는 notion과 slack을 켜두는 식으로요.

플러그인 오류가 나면

/plugin → Errors 탭에서 오류 목록을 확인하세요. 대부분 인증 만료(재로그인 필요), 서비스 다운타임, 네트워크 문제 중 하나입니다.

# 플러그인 재시작 시도
/plugin disable 플러그인명
/plugin enable 플러그인명

그래도 해결이 안 되면 재설치가 빠릅니다.

/plugin uninstall 플러그인명
/plugin install 플러그인명@claude-plugins-official

재설치 후에는 Claude Code를 한 번 재시작하는 게 좋습니다. 새 설정이 완전히 반영되도록 하기 위해서입니다. 재시작 없이 쓰다가 이상한 동작을 경험하는 경우가 간혹 있습니다.

자신만의 플러그인 만들기 (미리보기)

공식 마켓의 플러그인만 쓰는 게 전부가 아닙니다. 자주 하는 작업을 직접 플러그인(Skills)으로 만들 수도 있습니다.

처음엔 그냥 쓰세요. 익숙해지면 반복하는 패턴이 보이고, 그때 자동화할 무언가가 생깁니다. 처음부터 자동화를 목표로 하지 않아도 됩니다. 플러그인 사용 → 패턴 발견 → Skills 제작 순서로 자연스럽게 흘러갑니다.

예를 들어 매주 하는 "회의록 요약 → 주간 보고서 생성" 작업을 /weekly-report라는 Skills로 만들어두면, 매번 긴 프롬프트를 입력할 필요가 없어집니다. 명령어 한 줄로 끝납니다.

이 부분은 17장 "Skills & 플러그인 만들기"에서 자세히 다룹니다.

플러그인이 없었다면 못 했을 일들

플러그인이 실제로 어떤 경험 차이를 만드는지, 비교로 보여드리겠습니다.

전: 플러그인 없이 GitHub 이슈 분석

작업 흐름:
1. GitHub 웹에서 이슈 목록 열기
2. 각 이슈를 클릭해서 내용 읽기
3. 중요한 내용을 복사해서 Claude 채팅에 붙여넣기
4. 분석 받기
5. 다음 이슈 반복

소요 시간: 이슈 하나당 5~10분
10개 이슈 = 50~100분

후: GitHub 플러그인으로 이슈 분석

> 이번 주 열린 이슈 전체를 우선순위별로 분석해줘.

소요 시간: 30초~2분

차이는 "직접 읽고 복사하는 시간"입니다. 플러그인은 그 단계를 없앱니다.

전: 플러그인 없이 주간 보고서 작성

작업 흐름:
1. GitHub에서 닫힌 이슈 목록 확인
2. Notion에서 회의록 확인
3. Slack에서 결정사항 확인
4. 세 가지를 통합해서 보고서 작성
5. Notion에 올리고 Slack에 링크 공유

소요 시간: 40~60분

후: 플러그인 조합으로 주간 보고서

> GitHub, Notion, Slack 데이터 종합해서 주간 보고서 만들고 공유해줘.

소요 시간: 5~10분 (검토 포함)

이 차이가 매주 반복됩니다.

플러그인 트러블슈팅 가이드

플러그인이 응답하지 않을 때

증상: 설치는 됐는데 요청을 해도 반응이 없거나 "서비스에 연결할 수 없습니다"라는 메시지.

점검 순서:

/plugin list에서 플러그인 상태 확인 — Enabled인지 확인
/plugin → Errors 탭에서 오류 메시지 확인
인터넷 연결 확인 (특히 VPN이나 방화벽 환경)
플러그인 재시작: /plugin disable [이름] → /plugin enable [이름]
그래도 안 되면: /plugin uninstall [이름] → 재설치

MCP 서버가 자꾸 끊길 때

증상: 처음엔 동작하다가 얼마 지나면 연결이 끊기고 다시 연결해야 하는 상황.

원인: 대부분 인증 토큰 만료, 서비스 점검, 또는 네트워크 타임아웃.

해결:

GitHub: /github:reauth로 재인증
Notion: /notion:reconnect
일반적인 경우: Claude Code 재시작이 가장 빠른 해결책

플러그인이 예상치 않은 동작을 할 때

가장 흔한 경우는 쓰기 권한이 있는데 원치 않는 항목을 생성하거나 수정하는 것입니다.

대응:

즉시 중단: Ctrl+C
원복 가능한지 확인: 최근 생성/수정된 항목 확인
권한 재검토: /permissions에서 해당 플러그인의 허용 범위를 좁히기

플러그인을 도입하는 순서 제안

처음 플러그인을 시작한다면 이 순서를 권합니다.

먼저 기본 워크플로우를 익히세요. 플러그인 없이 Claude Code만으로 2~3주 써보면, 어떤 플러그인이 필요한지 자연스럽게 보입니다.
하나씩 추가하세요. 여러 개를 한꺼번에 설치하면 어떤 플러그인이 어떤 역할을 하는지 헷갈립니다.
읽기 전용으로 먼저 테스트하세요. 쓰기 권한은 신뢰가 쌓인 다음에 주세요.
쓰지 않는 건 꺼두세요. MCP 서버는 연결을 유지하므로 필요할 때만 활성화하는 게 깔끔합니다. 사용하지 않는 MCP 서버가 많으면 Claude Code 시작이 느려지고, 간혹 응답 속도에도 영향을 줍니다. 정기적으로 /plugin list에서 쓰지 않는 것을 비활성화하세요.

주요 플러그인 심층 살펴보기

처음 설치해볼 만한 플러그인들을 좀 더 자세히 살펴보겠습니다. 각 플러그인이 실제로 어떤 흐름으로 작동하는지, 어떤 순간에 가장 쓸모가 있는지를 중심으로 설명합니다.

GitHub 플러그인

설치: /plugin install github@claude-plugins-official

GitHub 플러그인이 하는 일은 Claude가 저장소에 직접 접근하는 것입니다. 이 플러그인이 있으면 "이 PR을 보고 문제 없으면 머지해줘"라고 할 수 있습니다. 플러그인 없이는 PR 링크를 복사해서 Claude에게 붙여넣고, 판단을 받고, 다시 GitHub에 가서 직접 머지해야 합니다. 그 왕복이 없어지는 것입니다.

자주 쓰는 요청 패턴:

이 저장소에서 지난 7일간 열린 이슈를 우선순위별로 정리해줘.
중요도 판단 기준: 레이블, 댓글 수, 작성자 권한.

main 브랜치와 feature/login 브랜치를 비교해서
무엇이 바뀌었는지 비개발자도 이해할 수 있는 언어로 요약해줘.

이번 스프린트에서 닫힌 이슈를 모아서 릴리즈 노트 초안을 만들어줘.
기술적인 내용은 사용자 관점으로 번역해줘.

💡 GitHub 플러그인을 쓸 때 주의할 점: 처음엔 읽기 권한만 부여하세요. 쓰기 권한(이슈 생성, PR 머지, 코드 푸시)은 충분히 신뢰가 쌓인 뒤에 추가하는 게 안전합니다. /permissions에서 세부 조정이 가능합니다.

Notion 플러그인

설치: /plugin install notion@claude-plugins-official

Notion을 팀 문서함이나 프로젝트 관리 도구로 쓰고 있다면, 이 플러그인이 Claude를 Notion 편집자로 만들어줍니다. 읽기뿐만 아니라 페이지를 새로 만들고, 내용을 업데이트하고, 데이터베이스에 항목을 추가하는 것까지 가능합니다.

가장 유용한 시나리오는 주간 정리 자동화입니다.

이번 주에 업데이트된 [프로젝트명] 관련 Notion 페이지를 모두 읽고
주간 업데이트 요약을 새 페이지로 만들어줘.
팀 공유 DB에 올려줘.

회의록 자동 생성도 자주 씁니다.

오늘 회의 내용을 정리해서 Notion의 [회의록 DB]에 새 페이지로 추가해줘.
형식은 기존 페이지 형식을 따라줘.

Slack 플러그인

설치: /plugin install slack@claude-plugins-official

Slack을 팀 커뮤니케이션으로 쓴다면, 이 플러그인이 채널 내용을 읽거나 메시지를 보내는 것을 가능하게 합니다. 개인적으로 가장 자주 쓰는 용도는 채널 모니터링입니다.

#dev 채널의 오늘 논의 중 결정사항이나 할 일로 이어질 것들을 뽑아줘.
나에게 관련된 것이 있으면 따로 표시해줘.

팀 스탠드업 메시지를 작성해줘.
어제 한 일: @TODO.md의 완료 항목
오늘 할 일: @TODO.md의 미완 항목
블로커: 없음

commit-commands 플러그인

설치: /plugin install commit-commands@claude-plugins-official

이 플러그인은 단순하지만 매일 쓰게 됩니다. 현재 스테이징된 변경 내용을 보고 적절한 커밋 메시지를 제안합니다. Conventional Commits 형식(feat:, fix:, docs: 등)을 기본으로 따릅니다.

/commit-commands:suggest

또는 그냥 이렇게 물어보는 것도 됩니다.

지금 staged된 변경 사항을 보고 커밋 메시지 3개를 제안해줘.
Conventional Commits 형식으로.

커밋 메시지 작성이 귀찮은 분들께는 이것만으로도 플러그인 설치할 이유가 됩니다.

플러그인 조합 사례: 실제 워크플로우

플러그인 하나씩 쓰는 것도 좋지만, 여러 개를 조합하면 더 강력한 자동화가 됩니다. 실제로 제가 쓰는 주간 정리 워크플로우를 예로 들겠습니다.

주간 업무 정리 자동화

매주 금요일 오후에 하는 작업입니다.

1단계: GitHub에서 이번 주 닫힌 이슈와 머지된 PR 목록 가져오기
2단계: Notion에서 이번 주 회의록 페이지 읽기
3단계: Slack #dev 채널의 주요 결정사항 추출
4단계: 세 가지를 종합해서 주간 보고서 작성
5단계: 주간 보고서를 Notion 주간보고 DB에 추가하고 Slack #general에 공유

이걸 한 번의 대화로 처리합니다.

GitHub, Notion, Slack 데이터를 조합해서 이번 주 주간 보고서를 만들어줘.
GitHub에서 이번 주 닫힌 이슈와 머지된 PR,
Notion에서 [2026-W19 회의록] 페이지,
Slack #dev에서 오늘 주요 논의를 가져와서 통합 보고서로 만들어줘.
완성되면 Notion [주간보고 DB]에 추가하고 Slack #general에 링크 공유해줘.

이전엔 이 과정에 40분 정도 걸렸습니다. 지금은 명령 한 줄 + 결과 검토 5분입니다.

플러그인 없이 MCP 서버를 직접 연결하는 방법

플러그인 마켓에 원하는 서비스가 없거나, 사내 시스템을 연결해야 할 때는 MCP 서버를 직접 설정할 수 있습니다.

MCP(Model Context Protocol)는 Claude와 외부 서비스를 연결하는 표준 프로토콜입니다. 설정 파일에 서버 정보를 추가하면 됩니다.

~/.claude/settings.json에 다음과 같이 추가합니다.

{
  "mcpServers": {
    "my-internal-tool": {
      "command": "node",
      "args": ["/path/to/mcp-server.js"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

이미 만들어진 MCP 서버들도 많습니다. GitHub, Slack, Notion, Jira, Figma, PostgreSQL, Google Drive 등의 공식·비공식 MCP 서버가 존재합니다. modelcontextprotocol/servers 저장소와 Anthropic Directory에서 목록을 확인할 수 있습니다.

🖥️ 개발자용: 직접 MCP 서버 만들기

내부 API나 데이터베이스를 연결해야 한다면 MCP 서버를 직접 만들 수 있습니다.

기본 구조:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';

const server = new Server({ name: 'my-tool', version: '1.0.0' });

server.setRequestHandler('tools/list', async () => ({
  tools: [{
    name: 'get-data',
    description: '내부 DB에서 데이터 조회',
    inputSchema: { type: 'object', properties: { query: { type: 'string' } } }
  }]
}));

server.setRequestHandler('tools/call', async (request) => {
  if (request.params.name === 'get-data') {
    const result = await internalDB.query(request.params.arguments.query);
    return { content: [{ type: 'text', text: JSON.stringify(result) }] };
  }
});

자세한 내용은 MCP & 외부 도구 연결 섹션에서 다룹니다.

잠깐 정리

여기까지가 플러그인의 기본기입니다. 아래부터는 실전 사례, 보안 패턴, 팀 운영 같은 심화 주제를 이어서 다룹니다.

플러그인으로 해결한 실전 문제들

문제 1: 매일 같은 GitHub 이슈를 수동으로 확인하는 것이 지쳐서

이전에는 매일 아침 GitHub에 들어가서 새 이슈를 확인하고, 우선순위를 판단하고, 담당자를 배정하는 데 30분이 걸렸습니다. GitHub 플러그인을 설치한 뒤 아침에 이것 하나를 실행합니다.

어제 이후로 열린 새 이슈를 가져와서:
1. 버그인지 기능 요청인지 분류해줘
2. 심각도를 기준으로 우선순위를 정해줘 (기준: 사용자 영향도, 재현 가능성, 기존 이슈와 중복 여부)
3. 담당자 제안: 이슈 내용을 보고 팀원 중 누가 처리하기 적합한지 알려줘
결과를 표 형식으로 정리해줘.

이 작업이 5분으로 줄었습니다. 남은 시간은 실제 문제를 해결하는 데 씁니다.

문제 2: 회의가 끝날 때마다 같은 형식으로 회의록을 만드는 것이 번거로워서

Notion 플러그인과 회의 녹취 흐름을 결합했습니다.

이 회의 내용을 Notion [회의록 DB]에 다음 형식으로 추가해줘:
- 제목: [날짜] [주제]
- 참석자: [목록]
- 결정사항: (번호 목록)
- 액션 아이템: (담당자 태깅 포함)
- 다음 회의까지 확인할 것: (체크리스트)
기존 페이지 형식과 동일하게.

회의가 끝나면 녹취 텍스트를 붙여넣고 이 명령을 실행합니다. 2분이면 됩니다.

문제 3: 코드 리뷰 코멘트가 너무 많아서 전체 흐름을 파악하기 어려워서

GitHub 플러그인으로 PR 코멘트를 분석합니다.

[PR 번호]의 모든 코멘트를 읽고:
1. 핵심 지적 사항 (여러 리뷰어가 공통으로 지적한 것)
2. 해결이 필요한 것 vs 논의 중인 것
3. 빠르게 고칠 수 있는 것 vs 설계 변경이 필요한 것
으로 분류해서 요약해줘.

리뷰가 20개가 있어도 3분이면 전체 맥락이 잡힙니다.

외부 서비스 없이 쓸 수 있는 플러그인들

MCP 서버나 외부 서비스 연동이 필요 없는 플러그인들도 있습니다. 로컬에서만 작동하기 때문에 별도 인증이나 설정이 거의 없습니다.

explanatory-output-style

응답 스타일을 바꿔줍니다. 설치 후 이렇게 씁니다.

이 코드를 설명해줘. [출력 스타일: 초보자용 단계별 설명]

또는 전역 설정으로:

앞으로 모든 설명을 초보자가 이해할 수 있는 단계별 형식으로 해줘.

문서화 작업이나 강의 자료 만들 때 특히 유용합니다.

chrome-devtools (또는 playwright)

로컬에서 실행 중인 웹 앱을 Claude가 직접 확인하도록 해줍니다.

localhost:3000을 열고 콘솔 오류가 있는지 확인해줘.
있으면 어떤 파일의 몇 번 줄에서 나는지 알려줘.

화면을 직접 보면서 "이 버튼이 제대로 동작하는지 확인해줘"도 됩니다. 테스트 자동화의 시작점으로 쓸 수 있습니다.

플러그인을 쓸 때 주의할 권한 패턴

플러그인이 강력한 만큼, 잘못된 권한 설정은 예상치 못한 결과를 만들 수 있습니다. 경험에서 배운 권한 패턴을 정리합니다.

단계적 권한 부여

설치 직후: 읽기 전용만 허용. Claude가 데이터를 읽고 분석하는 것만 가능.
1주일 사용 후: 생성 권한 추가. 새 이슈·페이지·메시지 생성 허용.
충분히 익숙해진 후: 수정·삭제 권한 추가. 기존 항목 변경 허용.

이렇게 단계를 밟으면 실수가 큰 영향을 미치기 전에 잡을 수 있습니다.

Deny 규칙 먼저 설정하기

허용하는 것보다 거부할 것을 먼저 정하는 게 안전합니다.

/permissions

여기서 "절대 하면 안 되는" 동작들을 Deny로 설정해두세요. 예를 들어:

Production 환경 데이터 수정 거부
팀 외부로 메시지 전송 거부
민감 정보가 있는 폴더 접근 거부

이 규칙들은 플러그인이 뭘 하든 상관없이 항상 적용됩니다.

실제로 저는 다음 Deny 규칙을 항상 설정해둡니다:

main 또는 production 브랜치 직접 푸시 거부
조직 외부 사용자에게 이메일·메시지 전송 거부
프로덕션 DB의 삭제 또는 수정 거부

이 세 가지만 있어도 대부분의 큰 실수를 막을 수 있습니다.

팀과 함께 플러그인 쓰기

혼자 쓸 때와 팀이 함께 쓸 때 플러그인의 역할이 조금 달라집니다.

팀 공유 플러그인 설정

CLAUDE.md에 팀 공통으로 쓰는 플러그인 설정을 기록해두면 새 팀원이 합류했을 때 설정 시간을 줄일 수 있습니다.

## 팀 플러그인 설정

필수 플러그인 (합류 후 바로 설치):
- `/plugin install github@claude-plugins-official`
- `/plugin install notion@claude-plugins-official`
- `/plugin install commit-commands@claude-plugins-official`

GitHub 플러그인 권한:
- 저장소: [팀 저장소명]에만 접근 허용
- 권한 수준: 읽기 + PR 생성, 이슈 생성
- 머지, 삭제는 항상 수동 확인 후 진행

팀 공통 프롬프트 관리

자주 쓰는 팀 프롬프트를 저장소에 포함시켜두면 팀 전체가 일관된 방식으로 씁니다.

prompts/
  weekly-report.md      # 주간 보고서 생성
  issue-triage.md       # 이슈 우선순위 분석
  pr-review.md          # PR 리뷰 요청
  release-notes.md      # 릴리즈 노트 생성

각 파일에 프롬프트 템플릿을 저장해두고, @prompts/weekly-report.md 실행해줘로 호출합니다.

플러그인과 보안

플러그인을 쓸 때 가장 신경 써야 할 부분은 보안입니다. 외부 서비스와 연결하는 만큼 주의가 필요합니다.

API 키 관리

플러그인 인증에 쓰는 API 키는 Claude Code가 안전하게 관리합니다. macOS에서는 시스템 키체인에 저장됩니다. 직접 파일에 적어두거나 CLAUDE.md에 넣으면 안 됩니다.

API 키를 어딘가에 입력하라는 메시지가 나오면, Claude Code의 공식 설정 흐름을 통해서만 입력하세요. 다른 방식으로 요청하는 것은 의심해야 합니다.

데이터 처리 범위

플러그인이 처리하는 데이터는 Claude API를 통해 Anthropic 서버로 전송될 수 있습니다. 다음 사항을 확인하세요:

회사 기밀 데이터를 플러그인을 통해 외부 서비스와 연결하는 경우 IT 정책 확인
Notion, Slack, GitHub의 민감 채널/저장소는 플러그인 접근 범위에서 제외하는 것 고려
Enterprise 요금제를 사용하면 데이터 처리에 대한 계약 조건이 다릅니다

자신만의 Skills 만들기 미리보기

플러그인을 쓰다 보면 "이 패턴을 자동화할 수 없을까"라는 생각이 드는 순간이 옵니다. 그때 Skills를 만들면 됩니다.

Skills는 반복하는 프롬프트 패턴을 슬래시 명령어로 만드는 것입니다. 예를 들어 매주 쓰는 GitHub 이슈 분석 패턴을 /triage로 만들면:

/triage

한 줄로 실행됩니다. 내부적으로 복잡한 프롬프트가 실행되지만 사용 시점에는 단순합니다.

플러그인을 2~3주 쓰다 보면 "이 요청 패턴을 매번 입력하기 귀찮다"는 순간이 옵니다. 그때 Skills를 만들 준비가 된 것입니다. 그 시점이 언제인지 자연스럽게 알게 됩니다.

Skills 만드는 방법은 17. Skills & 플러그인 만들기에서 자세히 다룹니다.

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

/plugin install github@claude-plugins-official을 실행해봤거나, 적어도 /plugin을 입력해서 Discover 탭을 확인했다
플러그인의 네 가지 유형(Skills, Agents, Hooks, MCP 서버)의 차이를 대략 이해했다
"읽기 전용으로 먼저 테스트한다"는 원칙을 기억했다
/plugin list로 현재 설치된 플러그인 목록을 확인했다

다음 장(07 핵심 개념)에서는 Claude Code가 안에서 어떻게 동작하는지 — Context, Tools, Permissions, Memory, Session — 다섯 가지 개념을 한 페이지씩 살펴봅니다.

핵심 개념

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

Claude Code가 일하는 방식: 한 번 들여다보면 달라지는 것들

도구의 내부 동작을 한 번 들여다보면, 이후 사용 방식이 자연스럽게 달라집니다. 처음 이 개념들을 이해했을 때 "그래서 그런 거였구나"라는 순간이 연달아 왔습니다. 어렵지는 않습니다. 다섯 개의 그림입니다. 강의장에서 이 다섯 개를 한 시간만 짚어 드려도 그다음 한 달의 막힘이 절반으로 줄어들곤 했습니다. 외울 필요는 없으니 한 번 머리에 그려보시기를 바랍니다.

Claude Code는 에이전트입니다: 한 번에 이해하는 흐름

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

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

"reports/ 폴더 문서를 요약해줘"라고 하면: 폴더 목록 확인 → 문서 본문 읽기 → 요약 작성 → 빠진 부분 보완. 이 흐름이 한 호흡에 자동으로 이어집니다. 사용자가 각 단계를 지시할 필요가 없습니다.

이게 채팅과 다른 점입니다. 채팅은 한 번 묻고 한 번 답하는 구조입니다. Claude Code는 완료될 때까지 자율적으로 단계를 밟습니다.

🖥️ 개발자 시나리오: 버그 수정의 결

"테스트가 빨갛게 뜨는데 고쳐줘"의 내부 흐름:

테스트 실행 → 어떤 메시지가 떴는지 확인
관련 소스 파일을 찾아 읽기
코드 수정
다시 테스트해서 통과 여부 확인
통과 안 되면 2단계로 돌아가 반복

다섯 개의 핵심 개념

① Context: Claude의 작업 기억

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

# 컨텍스트 현황 보기
/context

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

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

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

컨텍스트가 찼다는 신호들

이런 증상이 보이면 /compact나 새 세션이 도움이 됩니다.

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

💡 한 번은 이런 일이 있었습니다. 강의에서 한 분이 3시간짜리 세션을 이어가다가 "Claude가 갑자기 이상한 말을 하기 시작했어요"라고 했습니다. 보니까 컨텍스트가 가득 찬 상태였습니다. /compact를 누르고 "지금까지의 결정사항·바뀐 파일·남은 작업만 요약해줘"라고 했더니 Claude가 다시 정상으로 돌아왔습니다. 컨텍스트는 용량이 있는 기억입니다. 가득 차면 성능이 떨어집니다.

컨텍스트 관리 전략

주기적 압축: 30분~1시간마다 한 번씩 /compact 실행
집중 압축: 압축 시 "이 주제 중심으로 압축해줘"라고 구체적으로 지시
세션 분리: 완전히 다른 주제면 /clear로 새로 시작
CLAUDE.md 활용: 매 세션마다 반복해야 하는 규칙은 CLAUDE.md에 저장

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

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

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

이 도구들이 실제로 어떻게 쓰이는지 보면, Claude Code가 왜 채팅과 다른지 이해됩니다. 채팅은 텍스트만 돌려줍니다. Claude Code는 파일을 만들고, 명령을 실행하고, 결과를 확인하고, 다시 수정합니다.

도구 사용은 사용자의 허가 하에 이루어집니다. 어떤 도구를 쓸지, 허용 범위를 어디까지 줄지는 사용자가 결정합니다. 이것이 다음 개념으로 이어집니다.

사용할 수 있는 도구 범위는 플러그인을 통해 확장됩니다. 기본 도구만으로도 대부분의 작업이 가능하지만, GitHub 플러그인을 설치하면 "GitHub 저장소 읽기/쓰기" 도구가 추가됩니다. Notion 플러그인을 설치하면 "Notion 페이지 읽기/쓰기" 도구가 생깁니다. 플러그인이 도구를 확장하는 방식입니다.

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

강력한 도구일수록 안전 장치가 필요합니다. Claude Code는 작업 종류마다 허용 여부를 사용자가 직접 통제할 수 있습니다.

규칙은 세 가지입니다.

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

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

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

처음 Claude Code를 쓸 때는 파일 읽기는 자동 허용, 파일 수정과 셸 명령 실행은 확인(Ask)으로 시작하는 게 권장됩니다. 익숙해진 뒤에 자동 허용 범위를 넓히면 됩니다.

권한 설정은 세 수준으로 관리됩니다:

전역 설정 (~/.claude/settings.json): 내 모든 프로젝트에 적용
프로젝트 설정 (.claude/settings.json): 이 프로젝트에만 적용
로컬 설정 (.claude/settings.local.json): 이 프로젝트에만, git에 안 올라감

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

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

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

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

CLAUDE.md를 처음 만들 때 제가 추천하는 내용들:

## 기본 규칙
- 항상 한국어로 대화한다
- 코드 수정 전에 반드시 변경 계획을 설명한다
- 파일 수정은 한 번에 하나씩만

## 프로젝트 정보
- 기술 스택: Next.js 16, TypeScript, Tailwind CSS v4
- 배포: Vercel
- 코딩 스타일: named export, 인라인 타입

## 주의사항
- package.json 직접 수정 금지
- main 브랜치 직접 푸시 금지

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

⑤ Session: 대화의 시작과 끝

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

새 세션을 시작하면 이전 대화는 사라집니다 (CLAUDE.md는 그대로)
세션 중에 만든 파일·설정은 디스크에 그대로 남습니다
세션에 이름을 붙이면 나중에 같은 맥락에서 이어갈 수 있습니다

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

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

# 이름 붙인 세션 재개
claude --resume project-a

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

세션을 잘 관리하는 작은 습관이 생산성을 높입니다:

긴 작업에는 /rename으로 이름을 붙여두세요
하루 작업 시작 시 claude --continue로 어제 맥락을 이어가세요
완전히 다른 주제면 /clear로 새로 시작하세요

세션 이름을 잘 붙여두면 여러 프로젝트를 동시에 진행할 때 맥락 전환이 쉬워집니다. "shopping-mall-redesign"과 "api-refactor"처럼 구체적인 이름을 붙여두고, 필요할 때 claude --resume shopping-mall-redesign으로 바로 돌아올 수 있습니다. 사람도 업무 컨텍스트를 전환할 때 메모가 필요하듯, Claude도 세션 이름이 그 역할을 합니다.

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

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

처음에는 이 확인이 번거롭게 느껴질 수 있습니다. 하지만 세 번쯤 "잠깐, 그거 아니야"를 발동한 뒤엔 이 단계가 고마워집니다. 특히 큰 작업을 한창 진행 중일 때 방향이 살짝 틀어진 것을 잡아주는 게 이 확인 단계입니다.

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

Default

파일 수정·셸 실행 전에 매번 확인. 가장 안전한 모드.

기본 · 처음 쓸 때

Auto-Accept

파일 수정은 자동, 셸 실행은 여전히 확인. 속도와 안전 중간.

익숙해진 후

Plan Mode

읽기·분석만, 어떤 변경도 일으키지 않음. 그림 그리기 전용.

큰 작업 직전

Shift+Tab 한 번이면 모드가 다음 단계로 돌아갑니다.

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

같은 요청, 모드별 차이

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

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

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

🖥️ 개발자용: console.log 일괄 삭제 예시

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

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

코드베이스 전체를 건드리는 작업은 Plan Mode로 미리 범위를 확인하고 실행하는 게 실수를 크게 줄입니다.

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

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

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

이 기능 덕분에 "혹시 실수하면 어떡하지"라는 걱정 없이 과감하게 시도해볼 수 있습니다. 실험 속도가 빨라지는 핵심 이유 중 하나입니다. 체크포인트가 없었다면 많은 사람들이 Claude Code를 더 조심스럽게, 더 작은 단위로만 쓰게 됐을 겁니다.

단, 체크포인트는 Git 커밋을 대체하지 않습니다. 체크포인트는 단일 작업 내에서의 되돌리기입니다. 큰 작업을 시작하기 전에는 Git 커밋도 함께 해두는 게 좋습니다. 체크포인트는 "방금 한 것"을 되돌리고, Git은 "어제까지 한 것"을 지키는 역할을 합니다. 두 가지를 함께 쓰는 게 가장 안전합니다.

실전에서 개념이 드러나는 순간들

이 개념들이 실제로 어떤 맥락에서 느껴지는지, 구체적인 상황으로 보여드리겠습니다.

컨텍스트: "왜 갑자기 이상한 말을 하죠?"

긴 작업 중에 Claude가 이전에 합의한 것을 어기거나 방금 읽은 파일을 또 읽는다면 컨텍스트가 가득 찬 것입니다. 이럴 때 그냥 계속하면 점점 이상한 방향으로 흘러갑니다.

해결: /compact를 실행하고 "결정사항·남은 작업·변경된 파일 중심으로 압축해줘"라고 하세요. 대부분 이것만으로 정상 궤도로 돌아옵니다.

Tools: "이거 혼자 다 하는 거예요?"

처음 Claude Code를 쓰는 분들이 가장 놀라는 부분입니다. "이 폴더 전체를 분석해줘"라고 했더니 파일 하나하나를 열어보고, 코드를 실행하고, 결과를 정리해서 보여주는 것을 보고 "이게 AI가 맞나요?"라는 질문을 자주 받습니다.

맞습니다. 도구를 쓰기 때문입니다. Claude 모델 자체가 파일을 읽는 게 아니라, 파일 읽기 도구를 호출하고 그 결과를 바탕으로 다음 행동을 결정합니다. 이 도구-행동 사이클이 에이전트 루프입니다.

Permissions: "이걸 허용해도 될까요?"

Claude가 "sudo 명령으로 시스템 설정을 바꿔도 될까요?"라고 물어볼 때, 자동으로 "네"를 누르지 마세요. 왜 필요한지 물어보세요.

> 왜 sudo가 필요한지 설명해줘. 그 작업을 sudo 없이 할 방법은 없는지도 알려줘.

이 한 번의 질문이 의도치 않은 시스템 변경을 막는 경우가 꽤 됩니다.

Memory: "왜 매번 같은 말을 해야 하죠?"

"한국어로 대화해줘"를 매 세션마다 말해야 한다면 CLAUDE.md에 넣어두세요. "코드 수정 전에 계획을 먼저 설명해줘"도 넣어두세요. 한 번 적어두면 모든 세션에서 적용됩니다.

처음엔 CLAUDE.md가 비어 있는 게 당연합니다. 세션을 하면서 "이건 매번 말해야 하는 것 같은데"라는 생각이 들 때마다 CLAUDE.md에 추가하세요. 시간이 지나면서 자신만의 AI 동료 설정서가 됩니다.

Session: "어제 하던 거 이어서 할 수 있나요?"

네. claude --continue로 가장 최근 세션을 이어가거나, claude --resume [이름]으로 이름 붙인 세션을 재개할 수 있습니다. 세션이 끝나면 대화는 사라지지만, 파일과 CLAUDE.md는 그대로입니다. 다음 날 들어와도 "어디까지 했더라?"는 파일을 보면 됩니다.

하루 작업 마지막에 "오늘 한 것, 미완 상태, 내일 이어갈 것을 TODO.md에 정리해줘"라고 하면 다음 날 맥락 복구가 훨씬 쉽습니다.

이 개념들을 언제 다시 꺼내볼까

지금 당장 다 외울 필요는 없습니다. 하지만 이런 상황이 오면 이 장을 다시 꺼내보세요.

이런 상황일 때	다시 볼 개념
Claude가 갑자기 엉뚱한 말을 할 때	Context (컨텍스트가 찼을 가능성)
"어떻게 이걸 자동으로 했지?"라는 생각이 들 때	Tools (에이전트 루프 이해)
"이거 허용해도 되나?"라는 의문이 들 때	Permissions (권한 설정 확인)
"매번 같은 말을 반복하는 것 같다"는 느낌	Memory (CLAUDE.md 업데이트)
"어제 하던 작업을 이어가고 싶다"	Session (--resume, --continue 활용)

개념들이 연결되는 방식

이 다섯 개념은 독립적으로 존재하는 게 아닙니다. 실제 작업에서 하나로 연결되며, 서로가 서로를 지지합니다.

Claude가 작업을 받으면 (Session)
  → 현재 맥락을 확인하고 (Context)
  → 계획을 세운 뒤 도구를 씁니다 (Tools)
  → 허가된 범위 안에서만 (Permissions)
  → 다음 세션에서도 기억할 것은 CLAUDE.md에 기록 (Memory)

이 흐름이 머릿속에 있으면, 작업 중에 Claude가 왜 이렇게 행동하는지 대부분 예측 가능해집니다. "왜 이걸 물어보는 거지?"라는 당황이 줄어들고, 더 능동적으로 방향을 잡을 수 있습니다.

예를 들어 Claude가 "이 파일을 수정해도 될까요?"라고 물어볼 때, 이제는 "Permission 확인 단계구나"라고 이해할 수 있습니다. 느려지거나 맥락을 잃어가는 것 같을 때는 "Context가 차고 있구나"라고 알 수 있습니다. 개념이 행동의 언어가 됩니다.

이 다섯 개념은 Claude Code를 쓰는 전체 기간 동안 계속 돌아오게 될 기준점입니다. 지금 당장 완전히 이해하지 않아도 됩니다. 쓰다 보면 점점 더 명확해집니다.

이 장을 덮기 전에

에이전트 루프의 네 단계(Read → Plan → Edit → Verify)를 머릿속에 그릴 수 있다
컨텍스트가 찼다는 신호 다섯 가지 중 두 개 이상을 기억하고 있다
/compact, /context, /permissions 명령 중 하나 이상을 실제로 써봤다
CLAUDE.md의 위치(전역, 프로젝트, 로컬)를 이해했다
Default, Auto-Accept, Plan Mode의 차이를 설명할 수 있다

다음 장(08 CLAUDE.md 완전 정복)에서는 장기 기억 시스템인 CLAUDE.md를 어떻게 작성하고 관리하는지 깊이 다룹니다. 이 장에서 나온 Memory 개념의 연장선입니다.

이 다섯 개념을 안다고 해서 Claude Code를 완벽하게 쓸 수 있는 건 아닙니다. 하지만 왜 이렇게 동작하는지 이해하는 사람과 모르는 사람의 사용 경험은 시간이 지날수록 차이가 커집니다. 막히는 상황에서 어디를 봐야 할지 아는 것, 그게 이 장의 가장 큰 가치입니다.

CLAUDE.md 완전 정복

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

핵심

08. CLAUDE.md — "처음 만난 사람" 신세를 끝내는 법

세션이 끝날 때마다 Claude가 모든 걸 잊어버리는 게 불편하셨다면, 이 파일 한 장이 그 문제를 해결합니다. 딱 한 번 제대로 써두면, 다음부터는 처음 만난 사람처럼 처음부터 다시 설명하는 일이 사라집니다.

CLAUDE.md 작성법을 소개하는 공식 메모리 가이드 출처: Memory & CLAUDE.md — Anthropic 공식 문서

처음 이 다이어그램을 봤을 때 멈췄던 건 "왜 세 단계가 필요하지?"였습니다. 쓰다 보니 이유가 있었습니다. 전역 설정(글쓰기 언어, 코드 스타일 선호)은 어느 프로젝트에나 따라다니고, 프로젝트 설정은 그 프로젝트에서만 쓰이고, 나만의 로컬 설정은 팀원에게 보이지 않아야 하니까요. 계층이 없으면 어느 규칙이 이기는지 알 수가 없습니다.

"매번 같은 말을 반복하고 있다" 싶었을 때

강의에서 가장 많이 공감받은 순간이 있습니다. 새 세션을 열 때마다 "이 프로젝트는 TypeScript를 써요", "커밋 메시지는 한국어로 해주세요", "pnpm 써요"를 다시 입력하는 것입니다. 3분짜리 반복이 매일 쌓이면 한 달에 한 시간이 넘습니다.

CLAUDE.md는 그 반복을 끊는 파일입니다. Claude Code가 켜질 때마다 자동으로 읽어서, 이미 알고 있는 상태로 작업이 시작됩니다.

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

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

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

💡 한 번은 이런 일이 있었습니다. 강의에서 만난 한 분이 매 세션 "이 프로젝트는 React + TypeScript고, Tailwind 써요, pnpm이고요, 커밋은 한국어로 해주세요"를 복붙하고 계셨습니다. 그게 당연한 줄 아셨던 거죠. CLAUDE.md 하나 만들고 나서 첫 마디가 "이게 진작에 있었으면 좋았을 텐데"였습니다. 그 분이 넣으신 내용 중 제일 유용했던 건 "수정 전에 무엇을 할지 먼저 알려줘"였습니다. 코드가 갑자기 바뀌는 게 불안했는데, 그 한 줄이 불안을 없앴다고 하셨습니다.

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

위치가 가까울수록 우선합니다.

./CLAUDE.md: 현재 프로젝트 전용 (Git 공유 가능). 공식이 ./.claude/CLAUDE.md도 지원.
./CLAUDE.local.md: 나만의 프로젝트 설정. /init 실행 시 personal 옵션을 고르면 .gitignore에도 자동 추가됩니다.
~/.claude/CLAUDE.md: 내 모든 프로젝트에 공통 적용 (전역)
관리 정책(Enterprise managed): 조직 IT가 배포한 CLAUDE.md (macOS는 /Library/Application Support/ClaudeCode/CLAUDE.md, Linux/WSL은 /etc/claude-code/CLAUDE.md, Windows는 C:\Program Files\ClaudeCode\CLAUDE.md). 사용자가 끌 수 없습니다.

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

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

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

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

처음 써봤을 때 당황했던 것: "뭘 적으면 되지?"

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

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

묶음 ① 작업 개요

이 폴더가 어떤 작업을 위한 곳인지 한두 줄. 길게 쓸 필요가 없고, Claude가 "이게 무슨 프로젝트야"를 자동으로 알 수 있을 정도면 됩니다.

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

묶음 ② 도구·환경

어떤 도구·자료·저장 방식을 쓰는지. 처음엔 한 줄이라도 있으면 없는 것보다 훨씬 낫습니다.

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

묶음 ③ 작업 규칙

스타일·명명 규칙·출처 기준 같은 가드레일. "친절하게 해줘" 같은 모호한 지시보다, "출처 없는 통계는 쓰지 마"처럼 확인 가능한 형태가 훨씬 잘 작동합니다.

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

묶음 ④ 금지 사항

해서는 안 되는 것을 명시적으로 적어두면 사고가 줄어듭니다. 한 번 겪은 실수가 생기면 바로 여기에 추가하는 습관이 좋습니다.

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

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

반복되는 결과물의 골격을 박아두면 품질이 일정해집니다. "회의록 써줘"라고 했을 때 어떤 형식으로 나와야 하는지 Claude가 알고 있으면 훨씬 편합니다.

## 자주 쓰는 작업
- 리서치 보고서: "요약 → 핵심 인사이트 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)
- 외부 공유 전 "대외비 문구·고객명 점검 목록" 먼저 출력

🖥️ 개발자용 템플릿 (Next.js + TypeScript)

# 프로젝트 지침

## 프로젝트 개요
[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

처음 WSL2 환경에서 이걸 설정했을 때, 제일 먼저 넣은 줄은 "설명은 항상 한국어로"였습니다. 한국어로 물어봐도 영어로 답하는 경우가 간혹 있었거든요. 그 한 줄로 그 문제가 사라졌습니다. 그다음으로 넣은 게 "되돌리기 어려운 변경은 실행 전에 한 번 더 확인해줘"였는데, 이 두 줄이 전역 설정의 70%를 커버한다고 느낍니다.

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

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

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

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

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

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

로드 순서: 위에서 아래로 모두 읽어 concat됨. 뒤에 읽힌 게 우선입니다.
① 관리 정책 (Enterprise managed) — 가장 먼저 로드, 못 끔
② ~/.claude/CLAUDE.md (개인 전역 설정)
③ ./CLAUDE.md (또는 ./.claude/CLAUDE.md) — 프로젝트 공용 설정
④ ./CLAUDE.local.md — 나만의 프로젝트 설정 (가장 우선)

전역에서 "스페이스 2칸"으로 정해뒀어도, 프로젝트 CLAUDE.md에서 "탭 사용"으로 바꾸면 프로젝트 설정이 우선합니다. 같은 디렉터리 안에서는 CLAUDE.md가 먼저 읽히고 CLAUDE.local.md가 그 뒤를 덮어씁니다.

💡 관리 정책은 "정책"의 성격이라 사용자가 못 끄지만, 로드 순서로 보면 가장 먼저 들어옵니다. 그 위에 나머지가 차곡차곡 쌓입니다.

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

잘 쓴 CLAUDE.md vs 아쉬운 CLAUDE.md: 실전에서 배운 차이

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

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

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

💡 한 번은 이런 일이 있었습니다. 강의 중 CLAUDE.md 리뷰를 하는데 "항상 깔끔하게 코딩해줘"라고 적힌 걸 봤습니다. 의도는 좋지만, '깔끔함'의 기준이 사람마다 다르고 Claude도 마찬가지입니다. 바꿨더니 달라졌습니다: "함수는 20줄 이하로, 들여쓰기는 2칸 스페이스, 변수명은 동사+명사 형태." 세 줄이지만 세 줄 다 확인 가능한 기준입니다. 그 뒤부터 리뷰 때 "이 함수 너무 길다"는 말이 사라졌습니다.

`/memory`로 즉석 편집

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

/memory

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

다른 파일을 끌어오는 import

긴 내용을 CLAUDE.md에 다 넣는 것보다, 별도 파일로 분리하고 @로 참조하는 방식이 관리에 편합니다.

# 프로젝트 지침

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

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

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

/init

직접 부탁해도 됩니다.

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

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

처음 3개월 쓰면서 가장 자주 추가한 것들

강의 수강생들과 함께 쓴 CLAUDE.md를 보면, 시간이 지나면서 쌓이는 내용이 있습니다. 처음부터 이걸 넣으면 시행착오가 줄어듭니다.

"수정 전에 뭘 할지 먼저 말해줘" Claude가 갑자기 파일을 바꾸기 시작하면 불안합니다. 이 한 줄이 그 불안을 없앱니다.

"에러가 나면 고치기 전에 원인을 먼저 설명해줘" 바로 고쳐주면 왜 에러가 났는지 모르게 됩니다. 원인 설명 먼저를 넣으면 실력도 함께 늡니다.

"코드 외 파일(이미지, 설정, 환경변수)은 건드리지 마" 처음에 이걸 몰라서 .env.local 파일이 덮어써진 적이 있었습니다. 한 번 겪고 나서 바로 넣었습니다.

"완료됐다고 하기 전에 빌드가 되는지 확인해줘" "다 됐습니다"라고 했는데 빌드 에러가 나는 상황이 줄어듭니다.

CLAUDE.md를 팀이 함께 쓸 때: 운영 노하우

혼자 쓰는 건 어렵지 않은데, 팀으로 넓어지면 충돌이 생깁니다. 제가 겪은 패턴과 해결법입니다.

공용(./CLAUDE.md)과 개인(./CLAUDE.local.md) 분리

팀 전체가 지켜야 하는 규칙은 ./CLAUDE.md에 두고, 개인 취향은 ./CLAUDE.local.md에 두세요. .local 파일은 .gitignore에 자동으로 들어가니 팀원에게 보이지 않습니다.

./CLAUDE.md         # 팀 규칙 — Git에 포함
./CLAUDE.local.md   # 내 취향 — Git에서 자동 제외

규칙이 충돌할 때

전역 설정이 "스페이스 2칸"인데 프로젝트가 "탭"이면, 프로젝트가 이깁니다. 단, 이 충돌이 숨어 있으면 원인을 찾기 어렵습니다. 처음 프로젝트 CLAUDE.md를 만들 때 "이 프로젝트에서 전역 설정보다 우선하는 것들" 섹션을 한 줄 넣어두면 나중에 찾기 쉽습니다.

팀원이 실수로 CLAUDE.md를 덮어쓰지 않으려면

Git으로 관리하면 히스토리가 남습니다. 그것으로 충분하지만, 변경이 잦은 팀이라면 CLAUDE.md 변경 시 PR 리뷰를 받는 규칙을 추가하는 것도 방법입니다.

CLAUDE.md가 너무 길어지면

어느 순간 파일이 300줄을 넘기 시작합니다. 그러면 Claude가 읽는 데 컨텍스트를 많이 씁니다. 두 가지 전략이 있습니다.

분리해서 참조하기

## 세부 코딩 규칙
자세한 내용은 @docs/coding-standards.md를 참고하세요.

## API 설계 원칙
@docs/api-design.md를 따릅니다.

핵심 규칙만 CLAUDE.md에 두고, 세부 내용은 별도 문서로 분리한 뒤 @ 임포트로 연결합니다.

자주 쓰는 것 위로, 드물게 쓰는 것 아래로

Claude는 파일 앞쪽을 더 중요하게 읽습니다. 매일 필요한 규칙(커밋 형식, 언어 설정, 금지 사항)을 위에 두고, 특수 상황에서만 쓰는 것은 아래로 내리세요.

한 페이지 요약

항목	핵심
역할	Claude의 장기 기억·프로젝트 지시서
위치	프로젝트 루트의 `CLAUDE.md`
전역	`~/.claude/CLAUDE.md`
자동 생성	`/init`
편집	`/memory` 또는 텍스트 편집기
형식	자유 마크다운
핵심 원칙	모호한 지시 말고 확인 가능한 기준으로
우선순위	CLAUDE.local > ./CLAUDE > ~/.claude/CLAUDE > managed (위가 가장 우선)
파일 분리	길어지면 `@` 임포트로 문서 분리

CLAUDE.md 한 장만 제대로 써둬도 매 세션 들이는 설명 시간이 사라집니다. 처음엔 어색하지만, 한 달 뒤에는 "이게 없었던 때가 있었나?" 싶어집니다. 가장 좋은 CLAUDE.md는 완벽한 것이 아니라, 지금 겪는 불편함이 담긴 것입니다. 쓰면서 쌓아가세요.

CLAUDE.md 실전 운영: 6개월 동안 발견한 패턴들

처음 만들 때와 6개월 뒤에 보면 파일이 완전히 달라져 있습니다. 제가 관찰한 진화 패턴입니다.

1개월차: 기본 설정 넣기

보통 이런 것들로 시작합니다.

- 설명은 한국어로
- 커밋 메시지는 한국어로
- pnpm 사용

단순하지만 이것만 있어도 매 세션 반복 설명이 줄어듭니다.

3개월차: 사고 패턴이 쌓임

실수를 한 번씩 겪으면서 금지 사항이 늘어납니다.

- .env 파일 절대 건드리지 말 것
- 수정 전 plan 먼저 보여줄 것
- 빌드 확인 없이 "완료됐습니다" 하지 말 것
- node_modules 건드리지 말 것

이 단계의 CLAUDE.md는 "내가 당한 것의 기록"입니다.

6개월차: 워크플로우가 들어감

반복 작업의 패턴이 보이기 시작하면 작업 형식도 들어갑니다.

## 작업 시작 루틴
1. git status로 현재 상태 확인
2. 할 일 목록 요약해서 보여주기
3. 가장 작은 것부터 시작하기

## 작업 마무리 루틴
1. 변경된 파일 목록 보여주기
2. 빌드 또는 테스트 확인
3. 커밋 메시지 제안하기

이 단계가 되면 새 세션에서도 대화를 길게 열지 않아도 됩니다.

자주 묻는 것들: 강의에서 모인 질문들

강의를 진행하면서 CLAUDE.md에 대해 가장 자주 나온 질문들입니다. 답을 정리했습니다.

"CLAUDE.md가 있어도 Claude가 안 읽는 것 같아요"

두 가지를 확인하세요. 첫째, 파일이 프로젝트 루트에 있는지 (Claude Code를 실행한 폴더). 둘째, /memory를 실행해서 파일이 목록에 뜨는지. 목록에 안 뜬다면 위치 문제입니다. .claude/ 폴더 안에 넣는 것도 방법입니다.

"규칙을 적었는데 Claude가 가끔 어기는 것 같아요"

규칙이 모호하면 그렇습니다. "항상 한국어로"는 잘 지켜지는데, "좋은 코드로"는 기준이 없으니 들쑥날쑥합니다. 어겼을 때 바로 "CLAUDE.md의 이 규칙을 왜 따르지 않았어?"라고 물어보면 원인을 찾는 데 도움이 됩니다. 그 답을 보고 규칙을 더 구체적으로 고치세요.

"CLAUDE.md가 너무 길어지면 느려지나요?"

직접 연관은 아니지만, 길면 컨텍스트를 많이 씁니다. 1000줄 넘어가기 시작하면 분리를 고려하세요. @docs/rules.md처럼 별도 파일로 빼고 임포트로 연결하면 됩니다. 핵심 규칙 100줄, 세부 규칙은 별도 파일 참조 구조가 가장 균형이 좋았습니다.

"팀이 다 같이 쓰려면 어떻게 해요?"

./CLAUDE.md는 Git에 커밋하면 팀 전체가 공유합니다. 단, 개인 취향(예: "나는 탭보다 스페이스가 좋다")은 ./CLAUDE.local.md에 따로 두세요. 팀 합의가 된 것만 ./CLAUDE.md에 넣는 게 원칙입니다. 처음에 팀이 모여 30분만 합의하면 그 뒤가 훨씬 편합니다.

"잘 쓴 CLAUDE.md를 구경할 수 있을까요?"

공개된 오픈소스 프로젝트들이 .claude/ 폴더에 CLAUDE.md를 두는 경우가 늘고 있습니다. GitHub에서 filename:CLAUDE.md로 검색해보면 다양한 스타일을 볼 수 있습니다. 단, 그대로 복사하지 말고 "왜 이 규칙을 넣었을까?"를 생각하면서 참고하는 것이 좋습니다.

비개발자가 CLAUDE.md를 쓸 때 특히 효과적인 것들

코드를 다루지 않는 분들이 CLAUDE.md로 가장 크게 개선을 경험한 항목들입니다.

글쓰기 스타일 고정

매번 "친근하게 써줘", "너무 딱딱하지 않게"를 말하지 않아도 됩니다.

## 글쓰기 스타일
- 존댓말, 따뜻하지만 전문적인 어조
- 문장은 3줄 이하로 짧게
- 형용사·부사보다 명사·동사 위주
- "~합니다" 종결 선호, "~인 것 같습니다" 금지

결과물 형식 고정

항상 같은 형식의 결과물이 필요하면 한 번만 넣어두면 됩니다.

## 보고서 형식
1. 3줄 요약 (핵심 메시지만)
2. 배경 (2~3문단)
3. 핵심 발견 5가지 (번호 목록)
4. 권고사항 3가지 (실행 가능한 것으로)
5. 참고 자료 (출처 포함)

이 형식을 CLAUDE.md에 넣으면 "보고서 써줘" 한 마디에 이 구조가 자동으로 나옵니다.

반복 확인 질문 제거

매번 확인해야 하는 것들을 규칙으로 박아두면 물어볼 필요가 없어집니다.

## 결과물 출력 전 확인 사항
- 출처가 없는 통계나 수치가 있으면 "(출처 필요)" 표시
- 길이: A4 기준 1~2쪽 이내 (초과 시 요약 먼저 제시)
- 고객명·파트너명이 들어갔는지 확인 (있으면 "[고객명]"으로 마스킹)

💡 한 번은 이런 일이 있었습니다. 마케팅팀 수강생이 매주 경쟁사 분석 보고서를 만들었는데, 매번 "출처 꼭 달아줘", "너무 길지 않게 해줘"를 반복했습니다. CLAUDE.md에 이 두 가지를 넣고 나서 첫 달에 3시간 넘게 절약했다고 했습니다. 산술적으로 계산하면 연간 36시간입니다. 한 장짜리 파일이 만드는 차이입니다.

유형별 CLAUDE.md 진단: 내 파일은 어느 단계인가

강의에서 수강생 CLAUDE.md를 리뷰할 때 자주 보이는 네 가지 유형입니다. 어디에 해당하는지 보고 개선 방향을 잡으세요.

유형 A: 빈 파일 또는 없음

가장 흔한 초기 상태입니다. 매 세션 처음부터 설명하거나, 자주 쓰는 프롬프트를 메모장에 저장해두고 복붙합니다.

개선 방향: /init 한 번 실행해서 초안 만들기. 5분이면 됩니다.

유형 B: 역할 설명만 있음

"이 프로젝트는 쇼핑몰 사이트입니다. React + TypeScript를 씁니다."처럼 역할 설명은 있지만 규칙이 없는 상태입니다.

개선 방향: "절대 하지 말 것" 섹션 추가. 지금까지 Claude와 일하면서 불편했던 것 3가지를 금지 사항으로 적으세요.

유형 C: 규칙은 있지만 모호함

"좋은 코드 작성", "빠른 응답", "친절하게" 같은 주관적 기준이 대부분인 상태입니다.

개선 방향: 각 규칙을 "지켰는지 어떻게 확인하나?"라는 질문으로 검토하세요. 확인 불가능한 것들을 구체적인 기준으로 바꾸세요.

유형 D: 규칙이 있고 구체적임

검사 가능한 기준, 금지 사항, 작업 형식이 모두 있는 상태. 대부분의 세션이 처음부터 잘 돌아갑니다.

개선 방향: 이 단계에서는 "너무 길어지고 있지 않은가"를 점검하세요. 100줄이 넘으면 분리를 고려합니다.

CLAUDE.md를 꾸준히 발전시키는 습관

CLAUDE.md는 한 번 잘 만들고 끝이 아닙니다. 사용하면서 계속 채워가야 합니다.

"다음에 또 이러면 바로 고쳐야지" 메모

세션 중에 Claude가 원하지 않는 방향으로 가거나, 같은 설명을 두 번 이상 하게 됐다면, 그 자리에서 메모해 두세요.

오늘 추가할 것:
- TypeScript의 any 타입을 제안했다 → 금지 사항에 추가
- README 형식을 물어봤다 → 기본 형식 템플릿 추가

작업이 끝난 뒤 5분만 써서 CLAUDE.md에 반영하세요.

매달 한 번 돌아보기

한 달에 한 번, CLAUDE.md를 훑어보면서 "이게 아직 맞는 규칙인가?"를 체크합니다. 프로젝트가 바뀌면 규칙도 바뀌어야 합니다. 오래된 규칙이 새 작업을 방해하는 경우도 있습니다.

팀이라면: 분기별 CLAUDE.md 회고

팀 전체가 쓰는 ./CLAUDE.md는 분기 회고 때 함께 검토하는 것이 좋습니다. "이 규칙이 실제로 도움이 됐나?", "추가해야 할 것은?", "이제 필요 없어진 것은?" 세 가지 질문으로 15분이면 정리됩니다.

처음 시작할 때의 최소 CLAUDE.md

복잡하게 생각하지 마세요. 처음에는 이것만 있어도 충분합니다.

# 프로젝트 지침

## 기본 설정
- 모든 답변은 한국어로
- 작업 전에 계획부터 간략히 설명
- 되돌리기 어려운 변경은 실행 전 확인

## 이 프로젝트에 대해
[프로젝트를 한 줄로 설명]

## 하지 말 것
- [가장 걱정되는 것 하나]

이 7줄이면 시작입니다. 나머지는 쓰면서 채웁니다.

CLAUDE.md로 Claude Code와의 관계가 달라지는 이유

사람과 오래 일하면 서로 알게 됩니다. "이 사람은 보고할 때 3줄 요약을 먼저 원한다", "이 사람은 내가 먼저 선택지를 제안하면 싫어한다". 이런 것들을 파악하는 데 보통 몇 달이 걸립니다.

Claude Code는 기본적으로 매 세션이 첫 만남입니다. CLAUDE.md는 그 학습 곡선을 건너뛰는 방법입니다. 내가 어떻게 일하고 싶은지, 무엇을 원하고 무엇을 싫어하는지를 파일에 적어두면, 처음 만난 날부터 3개월 된 협업처럼 시작할 수 있습니다.

처음에는 "AI한테 이런 걸 왜 설명해야 하지"라는 느낌이 들 수 있습니다. 하지만 회사에 새 팀원이 왔을 때도 우리는 "이 팀에서는 이렇게 일합니다"를 설명합니다. CLAUDE.md는 그 온보딩 문서입니다. 새 세션을 열 때마다 같은 온보딩을 반복하는 대신, 한 번 만들어두고 자동으로 적용되게 하는 것입니다.

시나리오별 CLAUDE.md 차이: 코드 vs 글쓰기 vs 리서치

같은 파일이지만 용도에 따라 담는 내용이 달라집니다.

코드 작업용

## 기술 환경
- Node.js 22, TypeScript strict
- pnpm, Next.js 15, Tailwind v4

## 코딩 규칙
- 함수당 최대 20줄
- any 타입 금지
- 수정 전 영향받는 파일 목록 먼저 보여주기

## 빌드·배포
- 변경 후 반드시 pnpm build 확인
- 환경변수는 .env.local에만

글쓰기·콘텐츠용

## 글쓰기 스타일
- 한국어, 존댓말
- 문장은 2줄 이하, 단락은 5줄 이하
- "~인 것 같다" "~라고 생각됩니다" 금지

## 독자
- 비개발자, IT에 어느 정도 익숙한 30-40대
- 전문 용어 사용 시 괄호 안에 풀이 추가

## 결과물 파일
- drafts/ 폴더, YYYY-MM-DD_제목.md 형식

리서치용

## 리서치 원칙
- 모든 주장에 출처 명시
- 출처 없는 수치는 "(출처 미확인)" 표시
- 상반된 의견·반론도 반드시 포함

## 파일 구조
- sources/: 원문 자료
- notes/: 분석·가설
- reports/: 최종 결과물

## 결과물 형식
요약(3줄) → 핵심 발견(5개) → 반론·리스크 → 다음 액션

세 가지 용도 모두 담는 구조를 전역 설정에 넣기보다, 용도별 폴더에 맞춤 CLAUDE.md를 두는 것이 장기적으로 더 깔끔합니다.

자동으로 CLAUDE.md를 개선하는 루프

세션이 끝날 때 이 한 마디를 습관으로 만드세요.

"오늘 대화에서 내가 두 번 이상 설명해야 했던 것,
 또는 Claude가 내가 원하지 않는 방향으로 간 것을
 CLAUDE.md에 추가해줘."

Claude가 대화 히스토리를 보고 빠진 규칙을 제안합니다. 동의하면 CLAUDE.md에 반영하고, 아니면 넘어갑니다. 1~2분이면 됩니다. 이 루프를 한 달 유지하면 CLAUDE.md가 내 실제 작업 패턴에 맞춰 자동으로 성장합니다.

CLAUDE.md가 바꾸는 대화의 질

CLAUDE.md가 없을 때와 있을 때, 같은 첫 마디에서 대화가 어떻게 달라지는지 실제로 비교해보면 차이가 눈에 보입니다.

없을 때

사용자: 로그인 페이지 만들어줘
Claude: 어떤 기술 스택을 사용하시나요?
        React인가요, Vue인가요?
        TypeScript를 쓰시나요?
        ...

3~5턴의 질문·답변이 먼저 오갑니다. 실제 작업은 그 다음입니다.

있을 때

# CLAUDE.md 내용:
- Next.js 15 + TypeScript + Tailwind
- 컴포넌트는 /components 폴더에
- 페이지는 app/ 폴더 (App Router 방식)

사용자: 로그인 페이지 만들어줘
Claude: app/login/page.tsx를 만들겠습니다.
        이메일·비밀번호 입력 필드와 제출 버튼을 포함하고,
        /components/LoginForm.tsx로 폼을 분리하겠습니다.
        진행할까요?

첫 응답부터 실제 작업 계획이 나옵니다.

이 차이는 단순히 시간 절약이 아닙니다. 10~15분이 쌓이는 것도 있지만, 더 중요한 건 집중이 끊기지 않는다는 것입니다. 기술 스택을 다시 설명하는 동안 머릿속의 맥락이 흐트러집니다. CLAUDE.md는 그 흐트러짐을 막습니다.

마지막으로: 완벽한 CLAUDE.md는 없습니다

처음부터 완벽하게 만들려고 하면 시작을 못합니다. 5줄짜리 CLAUDE.md라도 없는 것보다 낫고, 3개월 쓴 200줄짜리보다 지금 당장 만든 10줄짜리가 더 가치 있습니다. 규칙을 잘못 적었다면 고치면 됩니다. 빠졌다면 추가하면 됩니다.

지금 이 순간 가장 불편한 것 하나를 CLAUDE.md에 적는 것으로 시작하세요. 그것으로 충분합니다.

CLAUDE.md로 해결되는 가장 흔한 불편 10가지

실제 수강생들이 CLAUDE.md 작성 후 해결됐다고 말한 것들입니다.

매 세션 기술 스택 다시 설명하기 → "기술 환경" 섹션
커밋 메시지가 영어로 나오는 것 → "커밋 메시지는 한국어" 규칙
파일을 갑자기 바꿔버리는 것 → "수정 전 계획 먼저 보여주기" 규칙
"다 됐습니다"인데 빌드가 안 되는 것 → "완료 전 빌드 확인" 규칙
답변이 너무 길어지는 것 → "변경 파일과 결과만 간결히" 규칙
같은 에러를 반복하는 것 → "금지 사항" 섹션에 원인 기록
폴더 구조를 마음대로 바꾸는 것 → "폴더 구조 변경 금지" 규칙
문서 형식이 매번 달라지는 것 → "결과물 형식" 섹션
.env 파일을 건드리는 것 → "환경 설정 파일 금지" 규칙
팀 컨벤션을 무시하는 것 → Git에 공유된 ./CLAUDE.md 규칙

이 중에 지금 당장 불편한 것이 있다면, 그것부터 CLAUDE.md에 넣으세요. 목록을 전부 채우려 하지 마시고, 오늘 가장 아픈 것 하나만 먼저입니다.

부록: CLAUDE.md 관련 자주 쓰는 명령어 모음

CLAUDE.md를 관리할 때 필요한 명령어들을 한 곳에 모았습니다.

# 프로젝트 CLAUDE.md 초안 자동 생성
/init

# 세션 중 CLAUDE.md 빠르게 편집
/memory

# 전역 CLAUDE.md 파일 직접 편집 (macOS/Linux)
nano ~/.claude/CLAUDE.md
# 또는
code ~/.claude/CLAUDE.md

# 다른 파일을 CLAUDE.md에서 참조 (파일 안에서)
@README.md
@docs/coding-rules.md
@package.json

# CLAUDE.md 없이 시작하는 폴더에 한 줄로 요청
"이 폴더에 대한 CLAUDE.md를 만들어줘. 
 현재 파일 구조를 읽고 프로젝트를 파악해서 초안을 작성해줘."

CLAUDE.md 상태 점검 체크리스트

지금 쓰고 있는 CLAUDE.md가 잘 작동하는지 빠르게 점검하는 방법입니다.

새 세션을 열고 다음을 확인하세요:

□ 기술 스택·환경을 다시 묻지 않고 바로 시작하는가
□ 커밋 메시지 형식을 자동으로 맞추는가
□ "절대 하지 말 것"이 실제로 지켜지는가
□ 결과물 형식이 CLAUDE.md에 적은 대로 나오는가
□ 수정 전에 계획을 먼저 보여주는가 (그렇게 설정했다면)

하나라도 "아니오"라면 그 부분 규칙을 더 구체적으로 고치세요.

이 점검을 새 프로젝트 시작 첫 주에 한 번, 그 다음 한 달 뒤에 한 번 더 하면 CLAUDE.md 품질이 빠르게 올라갑니다. 규칙이 실제로 작동하는지 확인하는 것이 CLAUDE.md를 발전시키는 가장 효율적인 방법입니다.

이 장을 덮기 전에

현재 작업 중인 폴더에 CLAUDE.md 파일이 있는지 확인했다 (없으면 /init으로 만들었다)
파일 안에 "절대 하지 말 것" 항목을 최소 하나 이상 적었다
"좋게 해줘" 같은 모호한 지시를 하나 골라 확인 가능한 기준으로 바꿔봤다
전역 설정(~/.claude/CLAUDE.md)에 "설명은 한국어로" 정도는 넣었다
/memory 명령어를 한 번 실행해서 편집 화면이 뜨는 걸 확인했다

다음 장(09 명령어 모음)에서는 지금 만든 CLAUDE.md가 실제로 어떤 세션 명령어들과 함께 동작하는지를 다룹니다. CLAUDE.md가 "기억"이라면, 명령어는 그 기억을 꺼내고 관리하는 손잡이입니다.

명령어 모음

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

09. 명령어 모음 — 처음 일주일을 버티게 해주는 손잡이들

처음 켰을 때 명령어 목록을 보고 "이걸 다 외워야 해?"라고 느끼셨다면 정상입니다. 실제로 첫 주에 쓰게 되는 건 다섯 개 안팎이고, 나머지는 "아 이런 게 있었지" 하고 필요할 때 찾아보면 됩니다.

Claude Code 공식 슬래시 명령어 레퍼런스 출처: Slash Commands — Anthropic 공식 문서

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

CLI 명령어

Claude Code 밖에서 입력. claude, claude --version 등 실행 명령.

터미널에서

슬래시 명령어

Claude Code 안에서 / 로 시작. /help, /compact 같은 세션 명령.

대화창 안에서

키보드 단축키

Ctrl+C, Shift+Enter 등 입력 속도를 올리는 단축키.

대화 중 빠르게

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

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

첫 주에 쓰는 다섯 손가락

처음에 이 다섯 개만 몸에 익히세요. 목록 전체를 외우려 하면 오히려 아무것도 안 씁니다. 저도 처음에 그 실수를 했습니다 — 전부 정리하려다 정작 실행은 미루게 됩니다.

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

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

💡 한 번은 이런 일이 있었습니다. 첫 강의 날, 한 분이 claude를 쳤는데 아무 반응이 없었습니다. 알고 보니 Node.js 버전 충돌로 인해 Claude Code가 제대로 설치되지 않은 상태였습니다. 그 자리에서 claude --version부터 쳐봤더니 "command not found"가 나왔습니다. 그때 만든 점검 순서: 1번 — which claude, 2번 — node -v, 3번 — npm list -g로 설치 여부 확인. 설치 문제 절반이 이 세 단계에서 잡힙니다.

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

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

켜기·끄기·확인

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

이 중에 매일 쓰는 건 claude 하나입니다. --version은 뭔가 이상할 때 처음으로 체크하는 명령이고, 나머지는 특수한 상황에서만 꺼냅니다.

모델 골라 켜기

# 정확한 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    # 가벼운 작업용
claude --model opus[1m]    # Opus 4.7 1M 컨텍스트 (대형 코드베이스용)
claude --model sonnet[1m]  # Sonnet 4.6 1M 컨텍스트 (대형 코드베이스용)

제가 쓰는 패턴은 이렇습니다. 평소엔 그냥 claude로 시작합니다. 설계나 복잡한 리팩토링을 다루는 날엔 claude --model opus로 시작합니다. 간단한 파일 변환이나 반복 작업은 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: 종료

처음 2주 동안 쓴 명령을 돌아보면 /compact와 Ctrl+C가 90%입니다. 대화가 길어지면 /compact, 방향이 틀어지면 Ctrl+C. 이 두 개를 몸에 익히는 것이 첫 단계입니다.

가끔 쓸 일이 생기는 것들

/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 변경 사항과 결정 위주로 정리해줘
→ 같은 세션에서 컨텍스트만 가벼워짐

💡 한 번은 이런 일이 있었습니다. 강의에서 한 분이 /compact를 너무 빨리 눌렀다가 작업 기억이 날아간 적이 있었습니다. 3시간 짜리 리서치 맥락이 사라진 것이죠. 그 뒤로 제가 강의에서 강조하는 것: /compact 전에 반드시 인자를 넣어서 무엇을 남길지 지정하세요. /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: 권한 모드 순환 (default → acceptEdits → plan)
Option+P (macOS) / Alt+P: 모델 변경
Option+T (macOS) / Alt+T: 확장 사고 모드 토글
Ctrl+B: 현재 작업을 백그라운드로 두고 새 대화 창 열기

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

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

① `/compact`: 대화의 호흡 정리

> /compact

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

② `Ctrl+C`: 즉시 멈추기

방향이 어긋났을 때, 또는 위험한 명령을 잘못 눌렀을 때, 망설이지 말고 누르세요. 처음엔 "멈춰도 되나"는 불안이 있는데, 이걸 빠르게 누를 수 있게 되면 Claude Code가 훨씬 편해집니다. 잘못된 방향을 빨리 멈추는 것이 좋은 결과를 만드는 핵심 습관입니다.

③ `/clear`: 새 작업으로 전환

> /clear

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

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

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

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

⑤ `/usage`: 비용과 한도 확인

> /usage

세션 비용·플랜 한도·활동 통계를 한 번에 봅니다. /cost·/stats도 같은 명령의 alias입니다. 처음 한 달은 이걸 가끔 들여다보면서 "내가 얼마나 쓰고 있나"를 감 잡는 게 좋습니다.

명령어를 잘 쓴다는 것: 두 가지 마음가짐

명령어를 많이 외우는 것이 목표가 아닙니다. 두 가지 마음가짐이 더 중요합니다.

첫째, 막힐 때 /help를 바로 여는 습관

특정 명령을 몰라도 됩니다. 필요한 순간에 /help를 열면 됩니다. 이걸 거리낌 없이 할 수 있게 되면 명령어 공부에 시간을 따로 안 써도 됩니다.

둘째, 불편할 때 명령어를 떠올리는 감각

"응답이 느려졌네" → /compact, "방향이 틀어졌네" → Ctrl+C, "다른 일로 넘어가야겠네" → /clear. 이 감각이 생기면 명령어가 진짜 도구가 됩니다.

이 두 가지가 갖춰지면, 나머지 명령어는 자연스럽게 필요할 때 손에 들어옵니다.

상황별 어떤 명령을 쓸까: 빠른 선택표

상황	추천 명령
Claude Code 시작	`claude`
대화가 길어졌을 때	`/compact`
완전히 새 주제로	`/clear`
실행 중 멈추고 싶을 때	`Ctrl+C`
세션 끝낼 때	`/quit` 또는 `Ctrl+D`
어제 작업 이어가기	`claude --continue`
특정 세션으로 돌아가기	`claude --resume [이름]`
계획만 보고 실행은 나중에	`claude --permission-mode plan`
비용·한도 확인	`/usage`
세션에 이름 붙이기	`/rename [이름]`
대화 분기 만들기	`/branch` 또는 `/fork`
설치 상태 점검	`/doctor`
CLAUDE.md 편집	`/memory`

🖥️ 개발자용: 터미널 alias로 명령어 단축하기

긴 옵션을 매번 치는 게 부담된다면 alias로 묶어두세요.

macOS · Linux (zsh)

~/.zshrc에 추가하시고:

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

새 셸에 적용:

source ~/.zshrc

Windows (PowerShell)

$PROFILE에 함수 정의:

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

PowerShell을 다시 시작하면 적용됩니다.

Alias 한 줄 설명

cc: 기본 실행 (항상)
ccd: 권한 확인을 자동 승인 (신뢰하는 프로젝트·빠른 작업용)
ccr: 이전 세션 재개 + 권한 자동 승인 (어제 작업 잇기)

⚠️ --dangerously-skip-permissions는 모든 권한 확인을 자동 승인합니다. 본인이 만든 프로젝트나 격리 환경에서만 쓰세요.

한 페이지 치트시트

[ 터미널 ]
  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              → 이전 상태로 되감기

이 장을 덮기 전에

claude --version을 터미널에서 쳐서 버전이 출력되는 걸 확인했다
대화를 열고 /help를 입력해서 명령어 목록이 뜨는 걸 봤다
/compact를 한 번 실행해서 어떤 결과가 나오는지 느껴봤다
Ctrl+C로 작업을 중단해봤다 (실행 중에 누르면 즉시 멈추는 걸 확인)
대화창에서 /를 입력했을 때 자동완성이 뜨는 걸 확인했다

다음 장(10 세션 & 컨텍스트 관리)에서는 이 명령어들이 실제 세션 흐름에서 어떻게 맞물리는지를 다룹니다. /compact를 언제 누를지, 새 세션을 언제 여는 게 더 나은지 — 명령어 너머의 판단 기준을 다룹니다.

명령어 심화: 자주 묻는 것들

강의에서 명령어 관련해서 반복되는 질문들을 모았습니다.

"/compact 하면 뭐가 날아가나요?"

중요한 결정과 현재 작업 상태는 요약에 들어갑니다. 날아가는 건 대화의 세부 과정 — 중간 시도, 취소된 요청, 탐색한 경로들입니다. 중요한 맥락이 날아갈까 걱정된다면, 인자를 써서 무엇을 남길지 지정하세요:

/compact 현재 진행 중인 API 연동 작업과 아직 해결 안 된 인증 오류 중심으로 요약해줘

"세션 이름을 붙이면 뭐가 달라지나요?"

나중에 claude --resume [이름]으로 그 세션을 그대로 불러올 수 있습니다. 이름 없이도 claude --resume으로 목록에서 고를 수 있지만, 이름이 있으면 긴 목록에서 찾기가 훨씬 빠릅니다. 프로젝트 이름 + 날짜 조합이 실용적입니다. 예: housing-analysis-may2026.

"/clear vs /compact 언제 뭘 써야 하나요?"

간단하게 구분하면 이렇습니다:

상황	명령
같은 프로젝트, 대화만 길어짐	`/compact`
완전히 다른 주제·프로젝트	`/clear`
대화가 이상한 방향으로 오염됨	`/clear` 후 핵심만 다시 전달
속도가 느려졌지만 맥락은 유지하고 싶음	`/compact`

"Plan Mode는 어떻게 켜나요?"

두 가지 방법이 있습니다.

# 처음 시작할 때부터 Plan Mode로
claude --permission-mode plan

# 대화 중에 전환
Shift+Tab

Plan Mode에서 Claude는 파일을 건드리지 않고 계획만 보여줍니다. 큰 변경 전에 "이렇게 하려고 하는데 방향이 맞나요?" 확인을 받는 용도입니다.

"Ctrl+C와 /quit의 차이가 뭔가요?"

Ctrl+C: 실행 중인 작업을 즉시 중단 (Claude Code 자체는 열려 있음)
/quit 또는 Ctrl+D: Claude Code 자체를 종료

작업이 잘못된 방향으로 가고 있을 때는 Ctrl+C. 세션을 완전히 닫을 때는 /quit입니다.

"Esc Esc가 뭔가요?"

Esc 키를 두 번 연속으로 누르면 Claude가 마지막으로 수정하기 직전 상태로 파일을 되돌립니다. Git 없이 쓸 수 있는 가장 빠른 복구 방법입니다. "방금 그거 마음에 안 든다"는 순간에 바로 쓸 수 있습니다.

명령어 조합 패턴: 실전에서 자주 나오는 흐름

명령어 하나씩을 아는 것과, 흐름에서 어떻게 조합하는지를 아는 것은 다릅니다.

패턴 1: 긴 리서치 세션 관리

아침에 시작:
  claude --resume research-project    # 어제 세션 재개
  /context                             # 컨텍스트 얼마나 남았는지 확인

중간중간:
  /compact 지금까지 발견한 핵심 인사이트 중심으로   # 30% 남을 때마다

끝낼 때:
  /rename research-project-2026may     # 세션 이름 붙이기 (이미 있으면 생략)
  /quit

패턴 2: 위험한 변경 전 안전망

  claude --permission-mode plan        # Plan Mode로 시작
  (변경 계획 확인)
  Shift+Tab                            # 일반 모드로 전환
  (실제 실행)
  claude --resume                      # 문제 생기면 다시 돌아와서

패턴 3: 새 기능 실험

  /branch                              # 원본 보전하고 분기 생성
  (실험적 변경)
  (잘 됐으면 그대로 진행)
  (잘 안 됐으면 Ctrl+C 후 --resume으로 원본 복귀)

패턴 4: 멀티 프로젝트 하루 루틴

터미널 1: claude --resume client-a-project     # 클라이언트 A 작업
터미널 2: claude --resume internal-tools       # 내부 도구 작업
터미널 3: claude                               # 새 아이디어 실험용

각 창마다 /rename으로 이름 붙여두면 다음 날도 바로 재개 가능

에디터 모드: 텍스트 에디터로 입력하기

긴 지시사항이나 여러 줄로 나뉜 복잡한 요청은 터미널 안에서 타이핑하기 불편합니다. /config에서 외부 에디터를 지정하거나, Ctrl+G를 눌러 현재 설정된 에디터로 입력을 열 수 있습니다.

# 에디터 설정 (예: VS Code)
# /config에서 설정하거나 환경변수로

# 대화 중 에디터로 입력 열기
Ctrl+G
→ VS Code (또는 설정된 에디터)가 열림
→ 작성 후 저장하면 대화창에 자동 붙여넣기

이 방법이 특히 좋은 경우:

여러 파일에 걸친 복잡한 변경 사항을 설명할 때
마크다운 형식의 긴 프롬프트를 작성할 때
코드 조각을 포함한 지시사항을 쓸 때

입력 단축키 모음: 타이핑 효율 올리기

CLI 명령어나 슬래시 명령어 외에, 입력 자체를 빠르게 하는 방법들입니다.

이전 입력 재사용

↑ (위 화살표): 바로 이전 입력 불러오기
↑↑: 두 번 전 입력
Ctrl+R: 입력 히스토리 검색

같은 프롬프트를 조금 수정해서 다시 쓸 때 특히 유용합니다.

특수 입력 방식

\Enter: 줄바꿈 (모든 터미널에서 작동)
Shift+Enter: 줄바꿈 (Claude Code 전용)
Ctrl+G: 외부 에디터 열기

빠른 취소와 복구

Ctrl+C: 현재 실행 취소 (입력 중이면 입력만 취소)
Esc Esc: 마지막 변경 되돌리기

명령어 실수를 줄이는 세 가지 습관

처음에 실수하기 쉬운 패턴과 그 해결책입니다.

습관 1: 확인 전에 `/compact` 누르지 않기

/compact는 되돌리기가 쉽지 않습니다. 누르기 전에 "지금 작업에서 어떤 맥락이 가장 중요한가"를 한 번 생각하세요. 그 맥락을 인자로 넣어주는 것이 안전합니다.

습관 2: 중요한 세션엔 `/rename` 먼저

길어질 것 같은 세션이라면 시작할 때 바로 이름을 붙이세요. 나중에 이름을 찾으려면 목록을 뒤져야 합니다.

> /rename [프로젝트명]-[오늘날짜]

습관 3: `/doctor`는 뭔가 이상할 때 첫 번째 확인

설치 문제, 인증 오류, 버전 충돌 — 이유를 모르겠을 때 /doctor를 먼저 실행하면 환경 문제의 50% 이상이 잡힙니다.

> /doctor
→ 설치 상태, 인증, 버전 등 한 번에 점검

비개발자를 위한 명령어 필수 목록

코드를 다루지 않는 분들은 이것만 알면 됩니다.

명령	언제	왜
`claude`	매일 시작할 때	Claude Code 켜기
`/compact`	대화가 길어졌을 때	느려지거나 이상한 답변 나올 때
`/clear`	다른 작업으로 넘어갈 때	이전 맥락 완전히 지우기
`Ctrl+C`	Claude가 잘못된 방향으로 갈 때	즉시 멈추기
`/quit`	오늘 작업 끝낼 때	Claude Code 종료
`/memory`	CLAUDE.md 수정 필요할 때	파일 편집기 열기
`/usage`	비용 궁금할 때	사용량·한도 확인

이 일곱 개면 Claude Code를 일상 도구로 쓰는 데 부족함이 없습니다.

명령어 배경 지식: 왜 이런 구조로 만들어졌나

"왜 슬래시 명령과 CLI 명령이 나뉘어져 있지?"라는 질문을 강의에서 자주 받습니다. 이유가 있습니다.

CLI 명령어는 Claude Code가 실행되기 전, 즉 터미널에서 어떻게 시작할지를 제어합니다. 어떤 모델로, 어떤 세션을 이어서, 어떤 권한 모드로 — 이건 시작 전에 결정해야 하는 것들입니다.

슬래시 명령어는 이미 실행 중인 Claude Code 안에서, 대화 흐름을 조절하는 도구입니다. /compact로 메모리를 정리하거나, /model로 모델을 바꾸거나, /branch로 실험 공간을 만드는 것들 — 이건 실행 중에 필요한 것들입니다.

키보드 단축키는 타이핑을 대체합니다. 명령어를 타이핑하는 것보다 빠르게 자주 쓰는 동작을 수행합니다.

이 세 갈래를 구분하고 나면, 처음 보는 명령이 나와도 "이게 어느 갈래인지"를 먼저 파악할 수 있습니다.

슬래시 명령어 자동완성 활용하기

대화창에서 /를 입력하면 자동완성 목록이 뜹니다. 이 목록에는 두 가지 명령이 섞여 있습니다.

내장 명령어: Claude Code 자체 기능 (/help, /compact, /model 등)
커스텀 명령어: .claude/commands/ 폴더에 만들어둔 나만의 슬래시 명령어

커스텀 명령어는 자주 쓰는 프롬프트를 /report, /analyze 같은 슬래시 명령으로 만들어 재사용하는 기능입니다. 자세한 내용은 고급 섹션에서 다룹니다. 지금은 "내장 명령어 외에도 내 것을 만들 수 있다"는 것만 알면 됩니다.

참고: 2026년 현재 .claude/commands/도 정식 동작하지만 공식은 Skills(.claude/skills/<name>/SKILL.md) 사용을 권장합니다. 17장 Skills 참고.

실전 예: 처음 3일의 명령어 일지

처음 사흘 동안 실제로 어떤 명령어가 몇 번 나왔는지 강의 수강생 사례를 바탕으로 정리했습니다.

1일차 (주로 탐색)

claude               ×1  (첫 실행)
claude --version     ×2  (버전 확인, 문제 점검)
/help               ×5  (뭐가 있는지 둘러보기)
Ctrl+C              ×3  (엉뚱하게 갈 때)
/quit               ×2  (끝낼 때)

거의 탐색입니다. 이 단계에서 /help를 여러 번 본 것이 나중에 다 도움이 됩니다.

2일차 (실제 작업 시작)

claude               ×2
/compact            ×3  (대화가 길어지기 시작)
/clear              ×1  (다른 주제로 전환)
Shift+Enter         ×8  (여러 줄 입력)
Ctrl+C              ×2

/compact가 처음 등장했습니다. 길어지는 대화를 정리하기 시작한 것입니다.

3일차 (루틴이 잡히기 시작)

claude --continue    ×1  (어제 작업 이어서)
/compact            ×4
/rename             ×1  (세션에 이름 붙이기 발견)
/usage              ×1  (비용 궁금해서)
Shift+Enter         ×15
Ctrl+C              ×1

3일차에는 /compact가 습관이 되고, --continue로 어제 작업을 이어가기 시작합니다. 이 패턴이 자리 잡히면 Claude Code가 실제 작업 도구가 됩니다.

명령어로 해결하지 못하는 것들

명령어를 잘 안다고 모든 게 해결되지는 않습니다. 명령어 너머에 있는 것들을 알아두면 기대치가 맞춰집니다.

Claude의 판단은 명령어로 제어 안 됩니다 /model opus로 더 좋은 모델을 쓸 수 있지만, 그 모델이 좋은 판단을 내리는 건 프롬프트와 컨텍스트에 달려 있습니다. 명령어는 도구를 선택하는 것이고, 도구를 잘 쓰는 건 여전히 사람의 몫입니다.

세션 기억은 명령어로 연장 안 됩니다 /compact는 컨텍스트를 줄여주지만, 세션이 끝나면 초기화됩니다. 중요한 맥락은 CLAUDE.md에 적어두는 것이 확실합니다.

속도는 명령어로 높이기 어렵습니다 /effort low가 있지만, 근본적인 응답 속도는 서버 상황과 모델에 달려 있습니다. /compact로 컨텍스트를 줄이는 것이 속도 개선에 실질적으로 도움이 됩니다.

단축키 커스터마이징

Claude Code는 키 바인딩을 커스터마이징할 수 있습니다. 기본 단축키가 다른 도구와 충돌하거나, 더 자주 쓰는 키로 바꾸고 싶을 때 유용합니다.

~/.claude/keybindings.json에서 설정합니다. 자세한 설정 방법은 /config에서 확인하거나, 공식 문서를 참고하세요.

마지막으로: 명령어 공부에 쓰는 시간을 줄이는 방법

명령어를 미리 다 외우려 하지 마세요. 실제로 필요한 순간에 찾는 것이 훨씬 효율적입니다.

명령어 사용 빈도 현실 체크

6개월 동안 실제 세션 로그를 보면 이런 분포가 됩니다.

명령	사용 비율	설명
`claude` (시작)	매일	절대적 1위
`Ctrl+C`	거의 매일	방향 수정의 핵심 도구
`/compact`	매일 여러 번	긴 세션 필수
`Shift+Enter`	매일 여러 번	여러 줄 입력
`/clear`	2-3일에 한 번	주제 전환 시
`/quit`	매일	세션 종료
`/usage`	주 1-2회	비용 모니터링
`claude --resume`	주 3-4회	이전 세션 재개
`/rename`	프로젝트 시작 시	세션 이름 관리
`/branch`	월 5-10회	실험이 필요할 때
`/doctor`	문제 발생 시	환경 점검
기타 모든 명령	합쳐서 5% 미만	특수 상황에서만

이 표를 보면 "뭐를 주로 연습해야 하는가"가 명확해집니다. 상위 여섯 개가 90%입니다.

처음 켠 날부터 쓸 수 있는 명령어 카드

이 카드를 프린트하거나 북마크해두세요.

가장 먼저 알아야 할 것
─────────────────────────────────
시작    : claude
멈추기  : Ctrl+C
정리    : /compact
초기화  : /clear
종료    : /quit (또는 Ctrl+D)
도움말  : /help

─────────────────────────────────
이틀 뒤면 알게 되는 것
─────────────────────────────────
이어서  : claude --continue
줄바꿈  : Shift+Enter
비용    : /usage
이름    : /rename [이름]
재개    : claude --resume [이름]

─────────────────────────────────
한 달 뒤 자연스럽게 쓰는 것
─────────────────────────────────
분기    : /branch
계획    : claude --permission-mode plan
모델    : /model 또는 claude --model [이름]
점검    : /doctor
되감기  : Esc Esc

상황이 생기면 이 카드 보고 찾으세요. 외울 필요 없습니다.

명령어 관련 소소한 팁들

마지막으로 강의에서 "아 그런 거 있었어요?" 반응이 나오는 것들을 모았습니다.

/ 입력 후 Tab 또는 방향키 자동완성 목록에서 Tab 키 또는 방향키로 선택할 수 있습니다. 자주 쓰는 명령은 첫 글자만 치고 Tab 누르는 것이 타이핑보다 빠릅니다.

슬래시 명령어는 대소문자 구분 없음 /COMPACT, /Compact, /compact 모두 같은 명령입니다.

--version과 -v는 같음 짧은 별칭이 있는 옵션은 길게 칠 필요가 없습니다. claude --version보다 claude -v가 빠릅니다.

/usage에서 /cost와 /stats도 같은 화면 이름이 세 개인 이유는 사람마다 다른 이름으로 기억하기 때문입니다. 셋 다 같은 화면으로 연결됩니다.

Ctrl+C 두 번이면 더 강하게 중단 한 번에 멈추지 않는 경우가 있습니다. 두 번 연속으로 누르면 더 확실히 중단됩니다.

/branch의 다른 이름은 /fork 같은 기능의 두 이름입니다. 어떤 이름이 더 기억에 남는지에 따라 고르세요.

--add-dir로 다른 폴더도 포함

claude --add-dir /path/to/other/folder

현재 작업 폴더 외에 참고할 폴더를 추가로 지정할 때 씁니다. 여러 프로젝트를 동시에 참조해야 할 때 유용합니다.

/login과 /logout 계정을 바꾸거나 재인증이 필요할 때 씁니다. 보통은 설치 후 한 번만 로그인하면 되지만, 여러 Anthropic 계정을 번갈아 쓰는 경우에 유용합니다. 기업용 계정과 개인 계정을 구분해서 쓰는 분들이 주로 이 명령을 씁니다.

작업 목록 Ctrl+T Claude가 여러 단계 작업을 실행할 때, Ctrl+T로 현재 어느 단계를 수행 중인지 목록을 볼 수 있습니다. 긴 작업이 돌아갈 때 진행 상황을 파악하는 데 좋습니다.

세션 & 컨텍스트 관리

컨텍스트 윈도우 개념부터 /compact, --resume, Plan Mode, 병렬 세션까지 실전 운용법.

실전 팁

10. 세션 & 컨텍스트 관리 — "분명 말했는데 왜 모르지"를 끝내는 법

대화가 길어지면 사람도 흐릿해지고, Claude도 마찬가지입니다. 이 흐릿해짐의 원인을 알고 나면, 고치는 방법도 명확해집니다.

컨텍스트 윈도우: 메모지에 무한히 쓸 수는 없다

대화가 쌓임

메모지에 한 줄씩 더해갑니다

한도에 근접

초반 내용이 가장자리로 밀려납니다

/compact 실행

대화를 요약해 메모지를 다시 씁니다

요약된 상태로 이어가기

핵심 결정·맥락만 남기고 이어갑니다

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

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

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

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

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

💡 한 번은 이런 일이 있었습니다. 강의 중 한 분이 "Claude가 처음엔 완벽하게 내 스타일을 따르더니 2시간 지나니까 갑자기 영어로 답하고, 내가 정해준 형식도 무시하기 시작했어요"라고 했습니다. 세션을 켜둔 채 4시간 동안 리서치를 하면서 컨텍스트가 가득 찬 것이었습니다. /context로 확인해봤더니 92%였습니다. /compact 한 번으로 해결됐습니다. 그 뒤로 저는 강의에서 항상 말합니다: "/compact는 창문을 닦는 것과 같다. 흐릿해지면 닦아라."

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

/compact

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

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

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

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

방향을 지정하지 않으면 Claude가 알아서 중요하다고 판단한 것들을 남깁니다. 하지만 내가 중요하게 여기는 맥락이 날아갈 수 있습니다. 중요한 세션일수록 인자를 넣는 습관이 좋습니다.

`/compact`를 잘 쓰는 타이밍

"언제 /compact를 눌러야 하지?"라는 질문은 거의 모든 수강생이 합니다. 네 가지 신호를 보세요.

신호 ①: 응답 속도가 눈에 띄게 느려질 때

대화 초반과 비교해서 응답에 걸리는 시간이 길어지고 있다면, 컨텍스트가 무거워진 신호입니다.

신호 ②: 아까 말한 것을 또 물어볼 때

"이미 앞에서 Next.js 쓴다고 했는데 또 묻네?" 이런 순간이 오면 /context로 확인해보세요.

/context
→ [■■■■■■■□□□] 73%

70% 넘으면 /compact 타이밍입니다.

신호 ③: 앞에서 합의한 규칙을 어기기 시작할 때

"한국어로 써달라고 했는데 갑자기 영어로", "커밋 메시지 형식 정해줬는데 무시하기 시작했다" — 이게 나오면 초반 지시가 잘려나간 것입니다.

신호 ④: 같은 실수를 반복할 때

한 번 고쳤는데 또 같은 패턴으로 돌아오면, 수정 내용이 컨텍스트에서 밀려났을 가능성이 높습니다.

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

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

claude --continue

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

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

이걸 처음 쓴 날, "어제 작업이 그대로 있다"는 감각이 꽤 신선했습니다. 매 아침 세션을 새로 시작하는 습관이 있었는데, --continue를 쓰면서 전날 맥락을 들고 시작하는 게 훨씬 더 생산적이라는 걸 알게 됐습니다.

`--resume`: 목록에서 골라서

claude --resume

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

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

세션에 /rename으로 이름을 붙여두면 목록 탐색이 훨씬 쉬워집니다.

# 이름으로 직접 재개
claude --resume housing-analysis-2026Q2

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

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

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

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

이 템플릿을 새 세션에 붙여넣으면, Claude가 처음부터 다시 듣는 것이 아니라 요약을 읽고 곧장 맥락을 잡습니다. 세션이 지저분해졌거나 같은 에러가 반복될 때 특히 효과적입니다.

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

상황	권장 방법
완전히 다른 주제·프로젝트	새 세션 (`/clear` 또는 새 터미널)
Claude가 앞 약속 잊기 시작	새 세션 + 핵심 다시 전달
같은 오류를 반복	새 세션 (컨텍스트 오염 가능성)
같은 작업이지만 대화가 길어짐	`/compact` 후 계속
어제 일을 오늘 잇는 것	`--continue`
특정 며칠 전 세션으로 복귀	`--resume`

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

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

Shift + Tab  →  Plan Mode 전환

Plan Mode에서 Claude는:

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

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

💡 한 번은 이런 일이 있었습니다. 수강생 한 분이 "데이터베이스 스키마 전체를 리팩토링해줘"라고 했더니 Claude가 바로 30개 파일을 수정하기 시작했습니다. 중간에 멈췄는데 일부는 변경되고 일부는 아직인 상태가 돼서 복구에 2시간이 걸렸습니다. Plan Mode로 시작했으면 수정 전에 어떤 파일을 어떻게 바꿀지 목록을 먼저 봤을 것입니다. 이 일 이후로 저는 강의에서 "파일 5개 이상 건드는 작업은 Plan Mode 먼저"를 원칙으로 가르칩니다.

병렬 세션: 터미널 여러 개로 손이 늘어나는 느낌

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

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

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

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

병렬 세션이 특히 효과적인 경우:

리서치(세션 1)와 초안 작성(세션 2)을 동시에 돌릴 때
여러 섹션을 각 세션에 나눠 처리할 때
한 세션이 오래 걸리는 작업을 하는 동안 다른 세션에서 별도 작업을 할 때

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

① 한 번에 한 가지만

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

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

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

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

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

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

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

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

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

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

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

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

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

컨텍스트와 비용의 관계

컨텍스트 관리는 비용과도 직결됩니다. 컨텍스트가 길수록 매 응답마다 더 많은 토큰이 들어갑니다.

예를 들어: 100,000 토큰의 컨텍스트를 유지하면서 응답을 받으면, 매 응답마다 100,000 토큰에 해당하는 입력 비용이 발생합니다. /compact로 50,000 토큰으로 줄이면, 그 다음부터는 절반의 입력 비용으로 같은 작업을 합니다.

[비용 관점에서의 /compact 효과]
컨텍스트 100K → /compact → 컨텍스트 30K
→ 이후 응답당 입력 비용 70% 절감

그래서 /compact는 단순히 "느릴 때 쓰는 것"이 아니라, 비용을 절약하는 도구이기도 합니다. 자세한 비용 관리는 20장에서 다룹니다.

세션 관리 전략: 작업 유형별 권장 패턴

리서치 작업

아침: claude --continue (또는 --resume)
중간: 새 발견사항 생길 때마다 /compact로 요약 업데이트
끝: "오늘 발견한 것들을 CLAUDE.md의 진행 상황에 추가해줘"

코드 작업

아침: claude (신선한 세션)
작업 중: 기능 단위로 끊고, 완성된 것은 git commit
큰 변경 전: claude --permission-mode plan 또는 /branch
세션 길어지면: /compact 또는 새 세션 + 핵심 재전달

문서·콘텐츠 작업

아침: claude --continue (어제 작업 이어서)
섹션별로 끊기: 섹션 완성 → 저장 → /compact 또는 새 섹션은 새 세션
큰 구조 변경: Plan Mode 먼저

세션 관리 요약: 한 페이지

상황	도구	이유
대화가 길어짐	`/compact`	컨텍스트 줄이고 세션 유지
어제 작업 잇기	`--continue`	가장 최근 세션 재개
특정 세션 재개	`--resume [이름]`	이름 붙인 세션 복귀
완전히 새 시작	`/clear`	이전 맥락 없이 깔끔하게
큰 변경 전 안전망	Plan Mode	계획 검토 후 실행
병렬 작업	터미널 여러 개	독립적 세션 동시 실행
며칠짜리 작업 맥락	CLAUDE.md 진행 상황	세션 넘어서도 기억 유지
세션 오염 시	새 세션 + 핵심 재전달	깨끗한 컨텍스트에서 재시작

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

이 장을 덮기 전에

/context를 입력해서 컨텍스트 사용량이 숫자로 보이는 걸 확인했다
/compact를 한 번 실행해서 대화 내용이 요약되는 걸 경험했다
claude --continue를 써서 이전 세션이 재개되는 걸 확인했다
Shift+Tab으로 모드를 순환(default → acceptEdits → plan)해보고, Plan Mode에서 Claude가 계획만 보여주는 걸 느꼈다
대화가 길어졌을 때 /compact가 필요하다는 신호 네 가지를 기억했다

다음 장(11 GitHub 시작하기)에서는 세션 관리와 다른 차원의 안전망, Git과 GitHub를 다룹니다. 세션이 기억을 관리한다면, Git은 파일의 역사를 관리합니다.

자주 묻는 것들: 세션 관리 Q&A

"새 세션과 `/compact`는 어느 쪽이 낫나요?"

상황에 따라 다릅니다. 같은 작업을 계속 이어가는 경우라면 /compact가 낫습니다. 맥락이 오염됐거나 완전히 다른 작업으로 넘어가는 경우라면 새 세션이 낫습니다. 판단이 안 서면: 지금 Claude가 이상한 답을 하고 있나요? 이상하다면 새 세션. 그냥 느릴 뿐이라면 /compact.

"`/compact`를 너무 자주 하면 문제가 생기나요?"

기술적으로 제한은 없지만, 너무 자주 하면 중요한 맥락이 잘려나갈 수 있습니다. 컨텍스트가 50% 미만일 때는 /compact보다 그냥 계속하는 것이 낫습니다. 70% 이상일 때 한 번 하는 것이 균형입니다.

"세션 이름은 어떻게 지으면 좋나요?"

프로젝트명-날짜 패턴이 실용적입니다. 예: market-research-2026may, login-feature-may07. 나중에 목록에서 찾을 때 날짜가 있으면 구분이 쉽습니다.

"컨텍스트 한도에 걸리면 어떤 증상이 나오나요?"

네 가지를 보세요: 응답 속도 느려짐, 앞에서 한 말 다시 묻기, 합의한 규칙 어기기, 같은 실수 반복. 이 중 하나라도 나타나면 /context로 확인해보세요.

"병렬 세션은 토큰이 두 배로 드나요?"

각 세션이 독립적으로 과금됩니다. 두 세션이 동시에 돌면 각각 토큰을 씁니다. 하지만 같은 시간에 두 배 결과가 나오므로, 시간당 생산성 면에서는 오히려 효율적입니다.

세션 관리가 습관이 되면 달라지는 것들

처음에는 "왜 이렇게 신경 써야 하지?"라는 느낌이 드는 게 자연스럽습니다. 하지만 세션 관리가 몸에 익고 나면:

긴 작업에서 "갑자기 이상해졌다"는 현상이 사라집니다
/compact가 습관이 되면 비용이 줄고 속도가 유지됩니다
--continue로 매일 전날 작업을 이어가면 리듬이 생깁니다
Plan Mode를 쓰면 되돌리기 어려운 실수가 눈에 띄게 줄어듭니다

이 네 가지가 자리 잡히면 Claude Code와의 협업이 안정됩니다.

세션 관리는 Claude Code를 다루는 기술 중에서 배우기 가장 쉽고, 효과는 가장 빠르게 보이는 것입니다. 오늘 /compact를 한 번 써봤다면, 이미 절반은 시작한 것입니다.

GitHub 시작하기

Claude Code에 필수인 Git & GitHub 사용법. 저장해줘, 올려줘만 말하면 됩니다.

필수

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 사용자에게 이 한 쌍은 선택이 아닙니다. 안전망이 깔려 있어야 과감하게 시킬 수 있고, 과감하게 시킬 수 있어야 진짜 생산성이 나옵니다.

💡 한 번은 이런 일이 있었습니다. 강의에서 한 분이 2주 동안 만든 프로젝트를 Claude가 실수로 파일을 덮어써서 날린 적이 있었습니다. Git 없이 작업하고 있었거든요. 그 분이 충격을 받은 건 당연했는데, 문제는 Claude가 "보호가 필요한 순간"이 항상 예고 없이 온다는 것입니다. Git은 그 예고 없는 순간을 위한 것입니다. 그 다음 수업에서 Git 셋업을 가장 먼저 했고, 그 뒤로 비슷한 사고가 없었습니다.

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

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

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

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

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

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

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

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

처음 한 번만

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

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

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

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

매일 쓰는 동작 세 가지

저장하기

Commit · 지금까지의 변경을 한 점으로 묶습니다

올리기

Push · 내 컴퓨터의 점들을 GitHub로 올립니다

검토 요청

Pull Request · 동료가 변경을 검토한 뒤 합칩니다

동작 ① · 저장하기 (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을 쓰면서 달라지는 것들

처음 Git을 쓰기 시작한 수강생들이 1개월 뒤에 가장 자주 하는 말이 있습니다. "이제 Claude에게 과감하게 시킬 수 있어요." 이 한마디에 Git의 가치가 담겨 있습니다.

안전망이 없으면 Claude에게 "이 기능을 완전히 바꿔줘"라고 하기가 무섭습니다. 잘못되면 복구가 안 되니까요. 하지만 Git으로 커밋이 돼 있으면 최악의 경우 git revert 한 줄로 어제로 돌아올 수 있습니다. 그 안심이 실험을 가능하게 합니다.

가장 창의적인 작업은 "실패해도 된다"는 환경에서 나옵니다. Git은 Claude Code와 함께 그 환경을 만드는 도구입니다.

Git 관련 자주 하는 실수들

커밋 메시지를 "수정", "변경", "업데이트"로만 쓰기

6개월 뒤에 이 커밋을 보면 아무 정보가 없습니다. "무엇을 왜 바꿨는지"가 담기도록 쓰세요.

나쁜 예: "수정"
좋은 예: "로그인 버튼 클릭 시 로딩 스피너 추가"

나쁜 예: "업데이트"
좋은 예: "비밀번호 최소 8자 유효성 검사 추가 (보안 요구사항 반영)"

하루 작업을 한꺼번에 커밋하기

작업 단위로 나눠서 커밋하면, 특정 변경만 되돌리거나 어느 시점에서 문제가 생겼는지 추적하기 쉬워집니다. 완벽하게 나눌 필요는 없고, 기능 단위나 의미 있는 덩어리 단위로 커밋하는 것으로 충분합니다.

Push 없이 Commit만 하기

Commit은 내 컴퓨터에만 있는 상태입니다. 컴퓨터가 망가지거나 분실되면 날아갑니다. 중요한 작업이 끝날 때마다 Push까지 하는 습관이 백업 역할을 합니다.

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

이 장을 덮기 전에

현재 프로젝트 폴더에서 "깃 시작해줘"를 실행해 Git이 셋업됐는지 확인했다
"저장해줘"로 첫 커밋을 만들었다 (커밋 메시지를 의미 있게 썼다)
"올려줘"로 GitHub에 푸시해서 저장소 링크를 받았다
.gitignore에 .env가 포함돼 있는지 확인했다
"지금 어떤 상태?"를 물어봐서 변경 파일 목록이 보이는 걸 확인했다

다음 장(12 자주 하는 실수 & 해결법)에서는 Git과 세션을 갖춰도 막히는 순간들, 즉 실제로 자주 겪는 에러와 그 대처법을 다룹니다.

Git을 처음 쓰는 분께: 막히는 순간들과 대처법

"GitHub 계정이 없어요"

먼저 github.com에서 계정을 만드세요. 이메일만 있으면 됩니다. 무료 계정으로 공개·비공개 저장소 모두 만들 수 있습니다. 비공개(private) 저장소는 나만 볼 수 있으니 코드 유출 걱정 없이 쓸 수 있습니다.

"Git이 설치 안 됐다고 나와요"

"Git을 설치해줘"

Claude Code가 운영체제에 맞는 설치 방법을 안내합니다. macOS라면 Homebrew로, Ubuntu/WSL이라면 apt로, Windows라면 Git for Windows로 설치합니다. 설치 후 git --version으로 확인합니다.

"push할 때 비밀번호를 물어봐요"

GitHub는 2021년부터 비밀번호 대신 토큰(Personal Access Token)을 씁니다. 토큰 발급이 번거롭다면 GitHub CLI(gh auth login)로 한 번에 처리하는 것이 편합니다. Claude에게 "GitHub 인증 설정해줘"라고 하면 안내해줍니다.

"git push했는데 팀원 변경과 충돌났어요"

가장 흔한 상황입니다. Claude에게 "충돌 해결해줘"라고 하면 어떤 파일이 충돌이 났는지 보여주고 해결 방법을 제안합니다. 처음에는 당황스럽지만, 몇 번 겪으면 패턴이 보입니다.

Branch: 실험을 안전하게 하는 방법

Branch는 원본을 두고 별도 작업 공간을 만드는 것입니다. 혼자 작업할 때도 유용하고, 팀 작업에서는 필수입니다.

"새 기능 작업을 위한 브랜치 만들어줘"
→ feature/login-page 같은 이름으로 브랜치가 생성됨
→ 이 브랜치에서 작업하면 main 브랜치는 영향받지 않음

브랜치가 특히 유용한 상황:

새 기능을 만드는데 중간에 긴급 버그 수정이 필요할 때 (브랜치를 main으로 전환)
같은 프로젝트에서 여러 기능을 동시에 개발할 때
실험적인 변경이 잘 안 됐을 때 (브랜치 버리면 끝)

"이 브랜치 작업이 완성됐어. main에 합쳐줘"
→ PR 없이 바로 합치거나, PR을 만들어 검토 후 합치기

자주 쓰는 Git 상황과 자연어 요청

더 구체적인 상황에서 어떻게 말하면 되는지 모아봤습니다.

상황	이렇게 말하세요
특정 파일만 커밋	"src/components/Login.tsx만 저장해줘"
커밋 취소	"마지막 커밋 취소해줘 (파일은 그대로)"
다른 브랜치 변경 가져오기	"main 브랜치 최신 내용 가져와줘"
작업 임시 저장	"지금 작업 임시로 저장해줘 (stash)"
이전 버전 보기	"3일 전 login.tsx가 어땠는지 보여줘"
특정 파일만 되돌리기	"login.tsx만 마지막 커밋 상태로 돌려줘"
저장소 복사	"이 GitHub 저장소 내 컴퓨터로 가져와줘"

이 표의 모든 작업을 Claude가 처리합니다. 명령어를 알면 더 정밀한 제어가 되지만, 자연어만으로도 90%가 해결됩니다.

Git + CLAUDE.md: 프로젝트 규칙을 팀과 공유하는 방법

CLAUDE.md를 Git으로 관리하면 팀 전체가 같은 규칙 위에서 작업합니다.

# 팀의 CLAUDE.md를 저장소에 포함
./CLAUDE.md         # Git에 포함 → 팀 전체 적용

# 나만의 설정은 gitignore로 제외
./CLAUDE.local.md   # .gitignore에 자동 포함 → 내 컴퓨터에만

새 팀원이 저장소를 clone하면 CLAUDE.md도 같이 내려받고, 처음부터 팀 규칙이 적용된 상태로 시작합니다. 온보딩이 절반으로 줄어드는 효과입니다.

Git 도입 전후 비교: 강의장에서 본 변화

강의에서 Git을 도입하기 전과 후의 변화를 정리했습니다.

도입 전

"Claude가 뭔가 잘못됐는데 어떻게 됐는지 모르겠다"
"어제까지 됐던 기능이 오늘 갑자기 안 된다"
"혼자 작업하면 되는데 팀원이 같은 파일 만지면 날아간다"
"뭔가 큰 변경 요청하기가 무섭다"

도입 후

이전 상태 복구: 터미널 3줄
변경 추적: 자연어로 "어제 뭐가 바뀌었어?"
팀 작업: 브랜치로 분리, 충돌 자동 처리
과감한 실험: 커밋 후 "다 바꿔봐"도 두렵지 않음

Git이 없으면 Claude Code는 강력하지만 불안한 도구입니다. Git이 있으면 강력하고 안심이 되는 도구가 됩니다.

GitHub Actions: 저장하면 자동으로 테스트하기

Git을 좀 더 쓰다 보면 "올릴 때마다 테스트가 자동으로 돌면 좋겠다"는 생각이 듭니다. GitHub Actions가 그걸 해줍니다.

"GitHub에 올릴 때마다 자동으로 빌드 테스트가 돌게 설정해줘"

Claude Code가 .github/workflows/ 폴더에 설정 파일을 만들어줍니다. 이후 Push할 때마다 GitHub가 자동으로 빌드를 돌리고, 결과를 PR에 표시합니다.

이건 지금 당장 필요한 게 아닙니다. 하지만 "이런 것도 된다"를 알아두면, Git이 단순한 백업 도구 이상임을 느끼게 됩니다.

혼자 쓸 때도 브랜치가 유용한 이유

"혼자 작업하는데 브랜치가 필요한가요?"라는 질문을 자주 받습니다. 필요합니다. 이유가 있습니다.

첫째, 실험의 자유입니다. "이렇게 바꾸면 어떨까" 싶은 생각이 날 때, 브랜치를 만들면 main이 영향받지 않습니다. 잘 되면 merge, 안 되면 브랜치 삭제. 깔끔합니다.

둘째, 병렬 작업입니다. 기능 A를 작업하다가 급한 버그가 생기면, main으로 돌아가 버그부터 고치고 다시 기능 A 브랜치로 돌아올 수 있습니다. 세션 관리의 /branch와 비슷한 개념입니다.

셋째, 히스토리 정리입니다. 기능 단위로 브랜치를 만들면 "이 기능은 이 시점에 완성됐다"는 히스토리가 깔끔하게 정리됩니다.

브랜치를 쓰지 않아도 Git은 돌아가지만, 브랜치를 쓰기 시작하면 "왜 진작에 안 썼지"라는 생각이 듭니다.

커밋을 얼마나 자주 해야 하나요

정해진 답은 없지만, 두 가지 기준이 도움이 됩니다.

"이게 잘못되면 여기서부터 다시 해야 한다"는 순간마다 커밋하세요.

새 기능을 시작하기 전, 큰 변경을 하기 전, 오늘 작업을 마무리할 때 — 이 세 순간은 반드시 커밋입니다.

너무 자주 해도 됩니다.

"너무 자주 커밋하면 히스토리가 지저분해지지 않나요?" 걱정하는 분들이 있는데, 로컬에서 자주 커밋하고 push 전에 정리하는 방법도 있습니다. 하지만 처음엔 그냥 자주 커밋하는 것이 낫습니다. 덜 커밋해서 작업을 날리는 것보다, 자주 커밋해 히스토리가 길어지는 편이 훨씬 낫습니다.

자주 하는 실수 & 해결법

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

12. 처음 며칠을 넘기는 응급실 매뉴얼

처음 일주일 사이에 만나는 벽은 거의 정해져 있습니다. 이 장은 그 벽들을 한 자리에 모아둔 응급실 같은 페이지입니다. 처음부터 끝까지 정독하지 마시고, 막히는 순간에 와서 검색하듯 쓰십시오.

💡 강의장에서 손이 가장 많이 올라온 14가지 막힘을 모았습니다. 매 케이스에는 제가 직접 그 벽에 부딪혔을 때의 짧은 기록도 같이 적었습니다. 같은 에러 메시지라도 사람마다 막히는 결이 조금씩 다른데, 그 결을 알아채는 데 도움이 되었으면 합니다. 검은 화면 앞에서 답답할 때 한 케이스만 펼쳐서 1분 안에 다음 손길이 잡히도록, 단계도 짧게 끊어 놓았습니다.

케이스 ①: `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 명령을 쳤더니 command not found가 떴습니다. nvm을 쓰면서 셸을 새로 띄울 때마다 다른 노드 버전으로 떨어져 있어서 PATH가 매번 바뀌던 상황이었죠. 그날 만든 점검 순서가 지금도 1번 — which claude, 2번 — node -v, 3번 — ~/.zshrc 마지막 줄입니다. 이 셋만 체크해도 첫날 막힘의 9할이 풀립니다.

⚠️ macOS·WSL 모두에서 which claude가 빈 결과면 PATH 문제, ~/.local/bin/claude 같은 결과가 나오는데 실행이 안 되면 권한(chmod +x) 문제. 둘은 풀이가 다릅니다.

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

어떤 증상으로 보이나

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

풀이 흐름

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

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 Code가 자꾸 인증을 요구해서 살펴보니, 회사 VPN이 OAuth 콜백 URL을 막고 있었습니다. VPN을 잠깐 끄고 인증한 다음 다시 켜니 끝. 인증 실패의 30%는 사실 네트워크 환경 문제이고, Claude 자체 문제가 아닙니다. 먼저 의심할 곳은 본인이 사는 네트워크입니다.

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

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

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

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

느림의 결을 구분해 두면 도움이 됩니다

"느리다"가 다 같은 느림이 아닙니다. 다음 셋 중 어디에 해당하는지 한 번 짚어보세요.

첫 응답까지 30초 이상 — 컨텍스트가 무겁다는 신호. /compact가 먼저
중간에 한 글자씩 떨어진다 — 네트워크가 흔들리는 중. 와이파이·테더링 점검
아예 멈춰 있다 — 도구 호출이 막힌 상태. /doctor 또는 Ctrl+C 후 재시작

💡 한 번은 이런 일이 있었습니다. 분명 같은 작업인데 어제는 빨랐고 오늘은 느렸습니다. 이유는 단순했어요 — 어제는 /compact를 두 번 했고 오늘은 한 번도 안 했습니다. 긴 작업을 한 호흡으로 끝내려 하지 마시고, 30분마다 한 번씩 압축하는 리듬을 들이시는 편이 결과적으로 더 빠릅니다.

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

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

풀이 ㉠ · 지시를 좁혀 쓰기

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

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

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

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

> /memory

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

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

> /clear

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

💡 한 번은 이런 일이 있었습니다. "리팩토링해줘"라는 한 줄이 만든 사고가 가장 자주 나옵니다. 한 수강생은 이 한 줄로 100줄짜리 파일이 280줄이 되어 돌아온 적이 있습니다. 다시 시작할 때 "리팩토링하지 말고 이 함수의 버그만 고쳐줘"라고 좁히니 5줄만 바뀌었습니다. "개선"·"리팩토링"·"최적화"는 모호해서 위험한 단어입니다. 이 셋이 입에서 나올 때는 한 번 더 쪼개세요.

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

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

Esc 두 번    또는    > /rewind

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

풀이 ㉡ · git으로 복구

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

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

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

💡 한 번은 이런 일이 있었습니다. 큰 변경을 시키기 전에 git commit을 안 했다가, 한 시간 작업이 한 번에 날아간 적이 있습니다. 그 뒤로 만든 알리아스가 gwip(git add . && git commit -m "wip $(date +%H%M)")입니다. 큰 작업 직전에 한 번, 큰 작업 직후에 한 번 — 이 리듬이 손에 붙으면 사고의 99%는 1분 안에 복구됩니다.

되감기 vs git 복구 — 어느 쪽을 먼저 잡을까

상황별로 어느 손이 빠른지 정리해 두면 손이 망설이지 않습니다.

상황	먼저 잡을 손	이유
한 차례 대화 안에서 방금 잘못된 것 같다	`Esc Esc` 또는 `/rewind`	대화 + 코드를 함께 되돌립니다
어제 작업 결과를 오늘 보니 이상하다	`git diff` → `git restore`	세션은 이미 닫혔습니다
어디까지 되돌릴지 헷갈린다	`git reflog` 한 번 보고	모든 HEAD 이동 기록이 남아 있습니다
여러 파일이 동시에 망가졌다	`git stash` → 정리 → 부분 복구	한 번에 끄집어내 두고 골라 적용

이 표를 응급실 책상 위에 한 번 인쇄해 두시면, 사고 직후 1초 안에 다음 손길이 나옵니다.

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

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

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

지금 한도부터 보기

> /usage

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

줄이는 네 가지 길

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

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

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

ℹ️ 공식 CLI 옵션 이름은 버전에 따라 달라질 수 있으니, 최신 옵션은 claude --help로 확인하시기 바랍니다.

비용 폭증 패턴 셋 — 미리 알아두면 막을 수 있습니다

비용이 갑자기 늘어난 분들의 사례를 모아보면 셋 중 하나입니다.

"전체 코드베이스 봐줘"라는 한 줄 — 큰 폴더 전체를 컨텍스트에 올리는 순간 토큰이 한 번에 몇 만 단위로 뜁니다. 대신 @필요한_파일로 좁히세요.
밤새 자동화를 돌려둔 경우 — 새벽에 무한 루프가 돌아 한도가 다 빠진 경험담이 적지 않습니다. 자동화엔 반드시 --max-budget-usd나 max-iterations 같은 안전장치를 거세요.
Opus 모드를 끄는 걸 잊은 경우 — 한 번 Opus로 올렸다가 끄지 않고 단순 작업을 시키면 비용이 5배가 됩니다. /model을 자주 확인하시는 편이 안전합니다.

💡 한 번은 이런 일이 있었습니다. 한 분이 "갑자기 한도가 빨리 떨어진다"고 메일을 주셔서 같이 점검했더니 자동화 스크립트가 무한 루프에 걸려 있었습니다. 8시간 동안 같은 작업을 1초마다 반복해 한 달치 한도를 하루 만에 다 썼더군요. 자동화에는 반드시 종료 조건과 예산 한도를 같이 두십시오.

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

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

> /permissions

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

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

Shift+Tab → Auto-Accept Edit Mode

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

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

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

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

💡 한 번은 이런 일이 있었습니다. "권한 요청이 짜증나서" --dangerously-skip-permissions를 쓰시던 분이 한 달 뒤 "어디로 갔는지 모르는 파일"이 생겨서 저에게 물어보신 적이 있습니다. 안전장치를 통째로 끄면 어떤 일이 일어나는지 추적할 수 없습니다. "자주 뜨는 권한"의 답은 권한 끄기가 아니라 자주 쓰는 도구만 Always Allow로 등록하는 쪽입니다.

권한 모드를 상황별로 골라 쓰는 작은 표

세 모드를 상황 단위로 정리해 두면 손이 헷갈리지 않습니다.

상황	권장 모드	이유
처음 보는 프로젝트, 신뢰가 안 잡힌 상태	기본(Ask)	매 작업을 사람이 한 번씩 확인
큰 변경을 시키기 전 검토부터	Plan Mode	파일을 안 건드리고 계획만 받아봄
신뢰 가능한 반복 작업 (git·테스트 등)	Auto-Accept	속도 우선, 사고는 git이 복구
단발성 자동화 스크립트	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

💡 한 번은 이런 일이 있었습니다. WSL에서 한글이 깨져서 한 시간을 헤매다가 .bashrc에 LANG을 명시했더니 즉시 풀렸습니다. 그 뒤로 새 머신을 셋업할 때마다 가장 먼저 추가하는 한 줄입니다. 한글이 깨지면 클로드의 답도 깨져 보입니다 — 도구 탓이 아니라 터미널 탓이 99%입니다.

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

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

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

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

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

> /rename housing-research-2026Q2

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

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

💡 한 번은 이런 일이 있었습니다. 일주일짜리 프로젝트를 진행하던 분이 어느 날 노트북이 멎어서 모든 세션이 사라졌다고 토로하셨습니다. 그런데 CLAUDE.md에 진행 상태를 적어두는 습관이 있던 분이라, 새 세션을 열고 "CLAUDE.md 읽고 어디까지 진행됐는지 정리해줘"로 5분 만에 복귀하셨습니다. 세션은 휘발성 메모리, CLAUDE.md는 디스크 메모리라고 외워두시면 좋습니다.

맥락을 잃지 않기 위한 3중 안전장치

세션·CLAUDE.md·git 커밋 메시지를 함께 굴리시면 어떤 사고가 나도 5분 안에 복귀할 수 있습니다.

안전장치	무엇을 담는가	언제 쓰는가
세션 이름 (`/rename`)	한 줄짜리 식별자	세션 목록에서 빠르게 찾을 때
CLAUDE.md 진행 상태	어디까지 했는지·다음 할 일	새 세션을 열어도 5분 안에 복귀
git 커밋 메시지	코드의 어느 시점	코드까지 잃었을 때 한 줄로 시간 여행

세 줄을 함께 남겨두는 습관이, 한 줄도 안 남기는 습관보다 두 배 정도 더 안전합니다. 시간 비용은 한 작업당 1분도 안 됩니다.

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

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

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

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

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

💡 한 번은 이런 일이 있었습니다. 백엔드 개발자분이 "버그 하나 고쳐줘"라고 시켰는데 클로드가 "이참에 코드 정리도 하면 좋겠네요" 하고 30개 파일을 수정한 일이 있었습니다. 다행히 git이 깨끗한 상태였기에 git restore . 한 줄로 되돌아왔습니다. "이참에"는 클로드가 자주 쓰는 친절한 단어인데, 사용자에겐 사고의 시작이기도 합니다. Plan Mode를 켜두는 습관이 가장 안전한 예방책입니다.

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

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

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

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

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

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

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

도메인별 권장 검색 언어

분야에 따라 정보의 무게가 한쪽에 쏠려 있습니다. 다음 표를 옆에 두시면 매번 망설이지 않아도 됩니다.

분야	1차 검색 언어	보완 언어	이유
최신 라이브러리·SDK 사용법	영어	한국어 (실전 후기)	공식 문서는 영어가 표준
한국 시장·정책·규제	한국어	영어 (글로벌 비교)	1차 자료가 한국어
클라우드·인프라 트러블슈팅	영어	한국어 (블로그 사례)	StackOverflow가 압도적
디자인·UX 패턴	영어	일본어 (Note 등)	사례 데이터베이스가 영어 중심
학술·논문 인용	영어	한국어 (학회지)	arXiv·Google Scholar

💡 한 번은 이런 일이 있었습니다. "최신 React 패턴 정리해줘"라고 한국어로 시켰더니 2년 전 블로그 글 위주로 정리해 왔습니다. "영어 자료를 우선 검색해서 2025년 이후 글만 정리해줘"로 바꾸자 결과가 한 단계 깊어졌습니다. "언어"는 검색 결과의 시간축까지 영향을 줍니다 — 한국어 자료는 글로벌 자료보다 1~2년 늦게 따라오기 마련이니까요.

케이스 ⑬: 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

의심 신호 다섯 — 패키지 이름을 본 즉시 점검할 것

다음 다섯 신호 중 하나라도 걸리면 설치를 잠깐 멈추고 사람 눈으로 한 번 더 확인하세요.

이름이 미묘하게 비슷한 기존 패키지가 있다 — 예: 진짜 react-helmet이 있는데 추천된 건 react-helment. 한 글자 차이가 가장 흔한 슬롭스쿼팅 패턴입니다.
최근 2주 안에 처음 등록된 패키지다 — npm info의 첫 발행일이 너무 가깝다면 의심.
다운로드 수가 한 자리/두 자리 — 진짜 유용한 라이브러리라면 다운로드가 이렇게 적을 이유가 없습니다.
저자(maintainer)가 한 명이고 이력이 비어 있다 — npm 페이지에서 maintainer를 클릭해 다른 패키지가 있는지 확인.
README가 거의 비어 있거나 자동 생성된 것 같다 — 진지한 라이브러리는 README가 비어 있지 않습니다.

💡 한 번은 이런 일이 있었습니다. 강의에서 한 수강생분이 클로드가 추천한 react-cool-loader라는 패키지를 설치했는데, 같은 이름의 진짜 패키지는 react-cool-onload였습니다. 다행히 설치 직후 npm info로 다운로드가 12회임을 보고 즉시 제거했습니다. 설치 직후 1분 안에 npm info를 한 번 보는 습관이 슬롭스쿼팅 1차 방어선입니다.

케이스 ⑭: 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가 썼다고 안전이 보장되는 것은 아닙니다.

보안 검토를 빠르게 끝내는 3단계 흐름

8가지 체크리스트를 한 번에 다 보면 부담스럽습니다. 시간이 부족할 때는 다음 3단계로 줄여서 통과시키세요.

1단계 (30초) — git diff 한 번만 보고 "내가 시키지 않은 파일이 변경됐는가?" 확인. 한 줄이라도 의외의 파일이 보이면 거기서 멈춤.
2단계 (2분) — .env·config·package.json 세 파일만 따로 열어 봅니다. 시크릿이나 의존성이 들어가 있으면 즉시 점검.
3단계 (5분) — Claude에게 직접 점검을 시킵니다.

방금 변경한 코드를 보안 관점에서 다시 검토해줘.
하드코딩된 시크릿, 인젝션 가능 지점, eval 계열 호출,
경로 직접 사용, 빈 catch 블록, 추가된 의존성 — 이 여섯 가지만 짚어줘.

이 3단계로 90%의 잠재적 사고는 커밋 전에 걸러집니다. 시간이 있으면 8가지 체크리스트로, 없으면 3단계로 — 그날 작업의 무게에 맞춰 선택하시면 됩니다.

💡 한 번은 이런 일이 있었습니다. 한 분이 "그저 한 줄 고쳐달라"고 시켰는데 Claude가 친절하게 .env 파일을 새로 만들어 API 키를 거기 옮겨 놓았습니다. 본인은 모르고 그대로 커밋했고, 다행히 push 전에 git diff 검토 단계에서 발견됐습니다. 커밋 전 1분의 git diff가, GitHub에 시크릿을 노출시키고 사후 수습하는 것보다 훨씬 쌉니다.

부록 A — 응급실에 자주 함께 오는 곁가지 증상 6가지

위 14개 케이스 외에도 강의장에서 자주 들리는 곁가지 증상들이 있습니다. 본 케이스만큼은 아니지만 미리 알아두시면 작업 흐름이 끊기지 않습니다.

A1. "응답은 오는데 한국어가 어색하다"

대화 초반에 영어로 시작했다가 중간에 한국어로 바뀐 경우, 클로드가 두 언어 모두를 답변에 섞어 쓰는 경향이 있습니다. CLAUDE.md에 다음 한 줄을 추가해 주세요.

# 출력 언어
- 모든 답변은 한국어로
- 코드 주석도 한국어
- 명령어와 파일명만 영어 그대로

A2. "폴더 자동 인식이 안 된다"

claude 명령을 친 위치가 프로젝트 루트가 아니면 자동 인식 범위가 좁아집니다. 항상 cd로 프로젝트 루트로 이동한 뒤 시작하시는 편이 안전합니다. 한 단계 위에서 시작하면 클로드가 무엇을 보고 있는지 매번 헷갈립니다.

A3. "터미널 색상이 깨져 보인다"

TERM 환경변수가 잘못된 경우입니다.

echo $TERM    # xterm-256color가 아니면 의심
export TERM=xterm-256color

A4. "복사해도 붙여넣어지지 않는다"

WSL이나 SSH 환경에서 흔합니다. 클립보드 통합 도구(xclip, pbcopy, wl-copy)가 없거나 설정이 안 된 경우. macOS는 기본, WSL은 clip.exe 등으로 우회 가능합니다.

A5. "MCP 서버가 갑자기 끊긴다"

> /mcp

상태가 disconnected면 해당 MCP의 종속(Node·Python·OS 권한)을 점검합니다. 재연결만으로 풀리는 경우가 절반.

A6. "스킬·서브에이전트가 인식 안 된다"

스킬 파일은 .claude/skills/<이름>/SKILL.md 형식이어야 합니다. 폴더 이름과 파일 이름이 정확해야 하고, frontmatter의 name 필드와 폴더 이름이 일치해야 합니다.

💡 곁가지 6가지는 본 케이스만큼 자주는 아니지만, 막히면 시간이 더 길게 듭니다. 한 번 책갈피를 끼워두시면 다음에 같은 증상이 와도 1분 안에 분기를 잡을 수 있습니다.

부록 B — 환경별 특수 증상 안내

운영체제·터미널·셸 조합에 따라 같은 증상이 다른 모양으로 옵니다. 자주 마주치는 환경별 차이를 모아둡니다.

B1. macOS

Homebrew와 nvm 충돌: 두 가지로 노드를 설치한 경우 which node가 두 개 위치를 잡거나 셸이 다른 버전으로 떨어집니다. nvm use 한 줄을 .zshrc에 추가하시거나, Homebrew 노드를 제거하시는 편이 깔끔합니다.
"클로드가 응답이 없다"가 사실은 시스템 권한 문제인 경우가 있습니다. 시스템 환경설정 → 개인 정보 보호 및 보안 → "전체 디스크 접근"에 터미널 앱을 추가해 주세요.

B2. Windows + WSL2

경로 혼동이 가장 흔한 사고입니다. WSL 안의 /home/사용자 경로와 Windows의 C:\Users\사용자 경로는 같지 않습니다. 클로드에게 작업을 시킬 때는 WSL 안의 경로(~로 시작)에 머무르시는 편이 사고가 적습니다.
I/O 속도: /mnt/c/는 /home/보다 10배 느립니다. 큰 작업은 반드시 /home/ 아래에서.
WSL 시간 동기화: 절전 후 깨어났을 때 시각이 어긋나면 인증 토큰 검증이 실패합니다. sudo hwclock -s로 시간 동기화.

B3. Linux 데스크톱 / 서버

SSH로 원격 서버에서 클로드 코드를 띄울 때는 인증 흐름이 복잡합니다. 첫 인증은 가까운 머신에서 받고, ~/.claude.json을 SSH로 옮기는 편이 빠를 때가 많습니다.
tmux/screen 안에서 색상이 깨질 때: ~/.tmux.conf에 set -g default-terminal "screen-256color" 한 줄.

B4. 도커 컨테이너 안에서 굴릴 때

컨테이너 안에 node가 없거나 너무 오래된 버전인 경우가 흔합니다. Dockerfile에서 node:20 이상을 베이스로. 네이티브 인스톨러를 쓰면 Node가 필요 없지만, Docker 베이스 이미지는 빌드 도구 때문에 Node 포함 이미지를 쓰는 경우가 많습니다.
컨테이너 안에서 인증 흐름이 막히면, 먼저 호스트에서 인증한 뒤 ~/.claude.json을 볼륨 마운트로 컨테이너에 노출하시는 편이 깔끔합니다.

B5. 회사 네트워크 / VPN 환경

VPN이 OAuth 콜백 URL을 막아 인증이 무한 루프에 빠지는 경우가 가장 흔합니다. 잠깐 VPN 끄고 인증 → VPN 다시 켜기.
사내 프록시가 있는 경우 HTTPS_PROXY·HTTP_PROXY 환경변수를 셋업해야 클로드가 외부 API에 닿을 수 있습니다.
사내 보안 정책으로 npm/PyPI 접속이 막히는 경우, Claude가 패키지 설치를 시도하다 무한 대기에 빠지기도 합니다. 미러 레지스트리 URL을 CLAUDE.md에 명시해 두시면 좋습니다.

💡 환경별 증상은 책으로 다 담을 수 없을 만큼 많지만, 위 다섯 환경이 강의장에서 받은 질문의 80%를 차지합니다. 본인 환경이 어디에 가까운지 한 번 표기해 두시면, 다음 막힘에서 분기 점프가 빠릅니다.

14개 케이스를 모은 한 줄짜리 진단 트리

위 케이스들을 풀이 시점에 다시 펼쳐보기엔 양이 많습니다. 막히는 순간 한 줄로 분기를 잡을 수 있도록 트리를 한 번 정리해 드리겠습니다.

무엇이 막히고 있는가?
├─ 명령 자체가 안 먹는다 ─────────────── 케이스 ①
├─ 로그인이 안 된다 ───────────────────── 케이스 ②
├─ 동작은 하는데 너무 느리다 ──────────── 케이스 ③
├─ 결과가 마음에 안 든다 ─────────────── 케이스 ④
├─ 파일이 잘못 바뀌었다 ──────────────── 케이스 ⑤·⑩·⑪
├─ 비용·한도가 빨리 빠진다 ──────────── 케이스 ⑥
├─ 권한·보안이 신경 쓰인다 ──────────── 케이스 ⑦·⑭
├─ 한글·인코딩이 깨진다 ──────────────── 케이스 ⑧
├─ 세션·맥락을 잃었다 ────────────────── 케이스 ⑨
├─ 검색 결과가 빈약하다 ──────────────── 케이스 ⑫
└─ 추천된 패키지가 의심스럽다 ────────── 케이스 ⑬

이 트리를 책상 옆에 한 장 인쇄해 두시거나 CLAUDE.md 한 줄에 메모해 두시면, 다음에 막힐 때 1초 만에 분기로 점프할 수 있습니다.

한 페이지 예방 체크리스트

[ 시작 전 ]
□ 작업 폴더로 이동했나? (cd ~/Documents/my-project)
□ 중요 작업이면 git commit 했나?
□ CLAUDE.md에 프로젝트 규칙이 있나?
□ 지금 사용 중인 모델은 적절한가? (/model)
□ 한도와 예산을 확인했는가? (/usage)

[ 작업 중 ]
□ 지시가 충분히 좁혀져 있나?
□ 한 번에 너무 많이 시키지 않았나?
□ 호흡이 길어졌으면 /compact 했나?
□ 이상하면 즉시 Ctrl+C로 멈췄나?
□ 위험 작업 직전에 git commit·이름표(`/rename`)를 남겼나?

[ 작업 후 ]
□ 변경 내용을 확인했나? (git diff)
□ 테스트가 통과하는가?
□ 중요한 세션이면 이름을 붙였나? (/rename)
□ CLAUDE.md에 새로 알게 된 규칙을 한 줄 추가했나?
□ 보안에 민감한 변경이 있다면 케이스 ⑭ 체크리스트를 통과했나?

응급실에서 한 걸음 더 나아가는 7가지 습관

처음 며칠을 응급실에서 버티신 분들을 위한 다음 단계입니다. 이 일곱 습관이 손에 붙기 시작하면 여기 적힌 14개 케이스 중 절반은 미리 막힙니다. 한 번에 다 들이려 하지 마시고, 이번 주에는 한 가지만 손에 붙여보십시오.

1. 큰 작업 직전 `git commit` — 한 줄짜리 보호막

가장 효과 큰 한 줄입니다. 응급실 방문 횟수가 절반으로 줄어듭니다. gwip이라는 이름으로 알리아스를 만들어 두시면 손에 더 빨리 붙습니다.

alias gwip='git add . && git commit -m "wip $(date +%H%M)"'

매 작업 전 gwip 한 번이면 됩니다. 형식이 깨졌든 메시지가 부실하든 상관없습니다 — 되돌릴 지점만 만들어두면 그게 보험입니다.

2. 30분에 한 번 `/compact` — 호흡을 끊지 않는 리듬

호흡을 끊지 않으면서 컨텍스트를 가볍게 유지하는 리듬입니다. 너무 자주 누르면 핵심 맥락이 날아가고, 너무 늦게 누르면 응답이 느려집니다. 30분 간격이 제 경험상 균형점이었습니다.

3. "개선"·"리팩토링" 대신 구체적 동사

"개선해줘"·"리팩토링해줘"·"최적화해줘" — 이 셋은 모호해서 위험합니다. 대신 다음 형태로 바꿔보세요.

"이 함수의 NullPointerException만 고쳐줘. 다른 부분은 건드리지 마"
"for 루프를 forEach로 바꿔줘. 로직은 동일하게"
"에러 메시지 문자열만 한국어로 바꿔줘. 에러 코드는 그대로"

구체적 동사 + 범위 제한 + 변하지 않을 부분 명시 — 이 세 박자가 갖춰지면 사고가 거의 안 납니다.

4. CLAUDE.md에 진행 상태 한 줄

세션이 사라져도 5분 안에 복귀할 수 있는 디스크 메모리입니다. 매 작업 마무리에 다음 한 줄만 적어두십시오.

# 현재 진행
- 마지막 작업: 2026-05-06 인증 모듈 리팩토링
- 다음 할 일: 토큰 만료 시 자동 갱신 로직
- 막힌 지점: 만료 시각 비교에서 타임존 처리

5. 자동화에는 항상 예산·종료 조건

무한 루프 방지입니다. claude -p 자동화에는 다음 셋을 반드시 같이 거십시오.

--max-budget-usd 1.00 (예산 한도)
최대 반복 횟수 (스크립트 안에 명시적 카운터)
종료 조건 (성공·실패 모두에 명확한 종결)

6. 새 패키지는 `npm info` 한 번 확인

슬롭스쿼팅 1차 방어선입니다. 케이스 ⑬에서 다룬 의심 신호 다섯 개를 손에 붙여두시면, 1분 만에 안전 여부 판정이 가능합니다.

7. 의심스러운 변경은 `git add -p`로 줄 단위 검토

AI가 만든 코드도 외부 코드처럼 다루십시오. git add .로 한꺼번에 스테이징하지 마시고, git add -p로 hunk마다 골라 들이는 습관이 후반에 큰 사고를 막습니다.

💡 한 번은 이런 일이 있었습니다. 강의 마지막 회차에 한 분이 "이번 주에 클로드가 만든 거 절반은 git으로 되돌렸어요"라고 하셨습니다. 처음엔 의기소침해 보였는데, 곧 "그래도 되돌릴 수 있어서 마음 편히 시도하게 됐어요"로 끝맺으셨습니다. 실수를 줄이는 게 목표가 아니라 실수를 빨리 되돌리는 게 목표입니다. 응급실 매뉴얼이 그래서 필요합니다.

이 장을 덮기 전에

14개 케이스 중 내가 이번 주에 만난 케이스에 책갈피를 끼웠다
진단 트리를 책상 옆이나 CLAUDE.md에 한 줄로 옮겨 적었다
시작 전 / 작업 중 / 작업 후 체크리스트를 한 번 훑어 봤다
응급실 7가지 습관 중 이번 주에 들일 한 개를 골랐다

다음 장(13 디버깅: 에러를 만났을 때)에서는 응급실에 오기 전, 에러 메시지를 마주한 첫 1분에 어떻게 호흡을 잡을지를 다룹니다. 응급실은 마지막 보루이고, 첫 호흡이 응급실 방문을 막습니다.

💡 풀리지 않으면: 안에서 /doctor로 설치 진단을, /bug로 Anthropic에 직접 제보하실 수 있습니다. 한국어 커뮤니티에서는 GitHub Discussions나 슬랙 채널에 같은 증상을 묻는 게 가장 빠릅니다. 같은 증상을 먼저 만나신 분이 이미 답을 가지고 있을 확률이 의외로 높습니다.

💡 마지막 한 줄 — 처음 며칠 사이에 응급실을 자주 방문하시는 게 정상입니다. 강의장에서 한 달 이상 쓰신 분들은 이 페이지를 거의 안 펼치게 되시고, 대신 자기 CLAUDE.md에 "내 응급실 매뉴얼"이 자라납니다. 응급실은 졸업하는 페이지라고 생각하시면 마음이 편합니다.

디버깅: 에러를 만났을 때

에러가 났을 때 당황하지 않고 해결하는 3단계 워크플로우.

13. 에러와 마주쳤을 때 — 당황이 절반, 방법이 나머지 절반

빨간 글씨로 가득 찬 화면 앞에서 처음 느끼는 건 당황입니다. 그리고 그 당황이 지나가면, 에러는 그냥 "다음 단계를 알려주는 안내판"으로 보이기 시작합니다.

처음 Claude Code를 쓰기 시작했을 때 에러를 만나면 화면 전체를 캡처해서 검색창에 올렸습니다. 정작 Claude에게 보여주면 되는데, 그 생각을 못 했던 겁니다. 이상하게 들리지만, 에러가 났을 때 가장 빠른 첫 단계는 그걸 이해하려는 노력을 잠깐 내려놓고 그냥 보여주는 것입니다.

에러를 받았을 때 가장 먼저 할 일

에러 화면 앞에서 해야 할 일은 이해가 아니라 전달입니다.

에러 메시지 전체를 복사해서 붙여넣기

이런 에러가 나고 있어:
TypeError: Cannot read property 'name' of undefined
at UserList.render (src/components/UserList.js:23:18)
at processChild (/node_modules/react-dom/cjs/react-dom-server.node.development.js:4019:14)
...

중요한 것: 잘라내지 마세요. 긴 에러일수록 아래쪽에 실제 원인이 있는 경우가 많습니다. 에러 메시지가 길어도 Claude는 괜찮습니다.

스크린샷으로 보여주기

말로 설명하기 어려운 UI 깨짐, 레이아웃 오류는 캡처 후 Ctrl+V로 직접 붙여넣으세요. 터미널 에러라도 전체 화면이 보이는 스크린샷이 텍스트 복사보다 빠를 때가 있습니다.

상황을 말로 풀어쓰기

에러 메시지가 없는 "그냥 안 됨" 상황이라면, 다음 세 가지를 담아서 설명하세요.

언제부터: "어제 오후에 로그인 기능 추가한 뒤부터"
뭘 하면: "로그인 버튼을 누르면"
어떤 증상: "화면이 하얗게 되고 아무것도 안 나옴"

이 세 가지가 들어가면 Claude가 원인을 좁히는 속도가 달라집니다.

💡 한 번은 이런 일이 있었습니다. 옆자리에서 한 분이 2시간 동안 TypeScript 에러와 씨름하고 있었습니다. 에러 메시지를 검색해서 Stack Overflow를 뒤지고 있었는데, 제가 옆에서 "그냥 Claude한테 붙여넣어봐요"라고 했습니다. 30초 만에 "이 변수의 타입이 string | undefined인데 undefined가 들어왔을 때 처리가 없습니다"라는 답이 나왔습니다. 2시간짜리 문제가 30초에 해결됐습니다. 그분은 "왜 처음부터 이렇게 안 했지"라고 하셨습니다.

에러 메시지가 없는 경우: 증상만 있을 때

"그냥 안 돼"가 제일 난감합니다. 특히 "어제까지는 됐는데 오늘은 안 된다"는 경우, 원인을 찾는 두 가지 방법이 있습니다.

방법 ①: 마지막으로 변경한 것부터 확인

방금 어떤 파일들을 바꿨는지 diff로 보여줘.
그리고 이 변경 중 어떤 게 문제를 일으킬 수 있는지 추정해줘.

에러가 나기 직전에 무엇을 바꿨는지 아는 것이 원인 찾기의 출발점입니다. 기억이 안 나도 Claude가 git diff나 변경 내역을 볼 수 있습니다.

방법 ②: 작동하던 시점으로 되돌리기

/rewind

또는

Esc Esc (두 번)

작동하던 상태로 돌아간 다음, 한 번에 하나씩 다시 적용하면서 어느 시점에서 깨지는지를 찾습니다.

방법 ③: 좁혀가기

지금 로그인 기능만 안 된다면, 회원가입은 되는지 먼저 확인해줘.
그리고 로그인 API 호출 자체는 되는지 콘솔 로그를 추가해서 확인해줘.

범위를 좁혀가는 것이 빠른 원인 찾기의 핵심입니다.

구체적 사례: "흰 화면" 버그 처음부터 끝까지

실제 디버깅 대화가 어떻게 흘러가는지 보여드립니다.

처음 보고

[상황]
상품 목록 페이지를 새로고침하면 흰 화면이 납니다.
개발 서버는 켜져 있고, 브라우저 콘솔에 아래 에러가 있습니다:

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

[요청]
수정하기 전에, 관련 파일을 읽고 이 에러가 왜 나는지
가능한 원인을 두세 가지로 정리해줘.

원인 분석 요청

그 가설들 중 가장 가능성이 높은 것과
그걸 확인하려면 어떤 걸 봐야 하는지 알려줘.

Claude가 바로 고치기 전에 원인을 공유하게 만드는 단계입니다. 여기서 상태값, API 타이밍, 데이터 구조 문제가 많이 잡힙니다.

최소한의 수정

가장 가능성 높은 원인만 고쳐줘.
UI 구조나 다른 기능은 건드리지 말고,
흰 화면 에러만 막는 가장 작은 수정으로.

"가장 작은 수정"이 핵심입니다. 한 번에 여러 개를 고치면 어떤 수정이 효과가 있었는지 모르게 됩니다.

검증 요청

수정 후에 다음 세 가지를 확인해줘:
1. 상품 목록 페이지가 정상 렌더링되는지
2. 브라우저 콘솔에 에러가 사라졌는지
3. 상품이 0개일 때도 깨지지 않는지 (빈 배열 테스트)

버그 수정 요청에서 가장 중요한 것은 "고쳐줘"가 아니라 성공 기준을 명확하게 제시하는 것입니다.

같은 에러가 반복될 때

한 번 고쳤는데 같은 에러가 다시 나온다면, 접근 방식을 바꿔야 합니다.

패턴을 CLAUDE.md에 기록

이 에러가 왜 났는지 원인과 해결 방법을 CLAUDE.md에 추가해줘.
다음에 같은 상황이 오면 바로 피할 수 있도록.

예를 들어:

# CLAUDE.md 추가 내용
## 자주 만나는 에러 패턴
- 날짜 처리: 반드시 dayjs 라이브러리 사용 (moment.js 금지)
- API 응답: 항상 Optional Chaining (?.) 사용 후 접근
- 이미지: public/ 폴더는 '/images/...' 경로 사용, not './images/...'

이게 쌓이면 프로젝트의 에러 백과사전이 됩니다.

새 세션 + 핵심만 전달

대화가 길어지면 Claude가 이전 맥락에 끌려 같은 방향을 반복합니다.

/quit   # 현재 세션 종료
claude  # 새로 시작

@CLAUDE.md 읽어줘.
그리고 지금 src/auth/LoginForm.tsx에서 토큰 만료 에러가 계속 나고 있어.
이전에 시도한 방법과 다른 접근으로 해결해줘.

새 세션에서 새로운 시각으로 보는 것이 효과적입니다.

💡 한 번은 이런 일이 있었습니다. 한 수강생이 같은 에러를 세 세션에 걸쳐 고치려 했는데 계속 재발했습니다. 대화 히스토리를 보니 Claude가 매번 같은 방향으로 수정하고 있었습니다. 새 세션을 열고 "지금까지 시도한 것들은 다 안 됐어. 완전히 다른 접근 방법으로 봐줘"라고 했더니 바로 다른 원인을 찾았습니다. 세 번째 시도에서 같은 방향이 나온다면 그건 다른 원인이 있다는 신호입니다.

초보자가 자주 빠지는 디버깅 실수

실수 1: 에러를 이해하려다 시간을 보내기

에러 메시지를 분석하고 이해한 다음 Claude에게 물어보려는 경향이 있습니다. 순서를 바꾸세요. 이해 전에 먼저 보여주고, 그 다음 Claude가 설명해주는 것을 이해하는 것이 훨씬 빠릅니다.

실수 2: 에러를 요약해서 전달하기

"타입 에러가 나요"보다 에러 메시지 전체가 훨씬 더 유용합니다. 요약하면 정보가 손실됩니다.

실수 3: 에러 나는 상태에서 새 기능 요청

에러가 있는 채로 새 기능을 추가하면, 새 코드가 깨진 기반 위에 쌓입니다. 나중에 원인을 찾기가 두 배로 어려워집니다. 에러 먼저, 그 다음 새 기능입니다.

# 피해야 할 패턴
[에러 있음]
→ "이제 결제 기능 만들어줘"
→ "이제 이메일 발송 추가해줘"
→ 에러가 섞여 원인을 찾을 수 없게 됨

# 올바른 패턴
[에러 있음]
→ "이 에러 먼저 고쳐줘"
[에러 해결]
→ "이제 결제 기능 만들어줘"

실수 4: 같은 방법을 세 번 이상 시도하기

두 번 같은 방법을 시도해서 안 되면, 세 번째는 다른 방법을 써야 합니다.

> 이 방법은 두 번 시도해도 안 됐어.
  완전히 다른 접근 방법이 있다면 제안해줘.
  라이브러리를 바꾸는 것도 고려해줘.

에러 종류별 빠른 참고

자주 만나는 에러 패턴을 미리 알면 첫 반응이 빨라집니다.

에러	주로 의미하는 것	빠른 질문
`Cannot read properties of undefined`	값이 없는데 접근함	"어디서 undefined가 들어오는지 찾아줘"
`is not a function`	함수가 아닌 것을 호출함	"이게 왜 함수가 아닌지 확인해줘"
`Module not found`	import 경로 잘못됨	"이 경로가 맞는지 파일 구조 보고 확인해줘"
`Unexpected token`	문법 오류	"문법 오류를 찾아서 고쳐줘"
`Network Error`	API 요청 실패	"API 요청이 왜 실패하는지 확인해줘"
`Port already in use`	포트 충돌	"다른 포트로 실행하거나 기존 프로세스 종료해줘"
`TypeScript type error`	타입 불일치	"타입 에러를 찾아서 올바른 타입으로 고쳐줘"

디버깅 프롬프트 템플릿

막힐 때 이 템플릿을 채워서 그대로 보내세요.

[증상]
- 

[언제부터]
- 

[재현 방법]
1. 
2. 
3. 

[에러 메시지]
```
여기에 에러 전체 붙여넣기
```

[요청]
먼저 관련 파일들을 읽고, 원인 가설을 최대 3개로 정리해줘.
그 다음 가장 가능성 높은 것부터 가장 작은 수정으로 시작해줘.
수정 후 검증 방법도 알려줘.

이 장을 덮기 전에

에러를 만나면 전체 메시지를 복사해서 Claude에게 바로 보내는 습관을 만들었다
"언제부터 / 뭘 하면 / 어떤 증상이" 세 가지를 포함해서 에러를 설명해봤다
디버깅 프롬프트 템플릿을 북마크했다 (막힐 때 바로 쓸 수 있게)
에러 해결 후 CLAUDE.md에 원인과 패턴을 한 줄 기록했다
같은 에러 반복 시 새 세션으로 전환하는 방법을 확인했다

다음 장(14 알아두면 유용한 기능들)에서는 에러 외에 Claude Code를 더 편하게 쓰게 해주는 기능들, 이미지 입력·음성·자동 복구·권한 설정을 다룹니다.

에러 상황 유형별 대처 전략

에러는 크게 두 가지로 나뉩니다: 명확한 에러와 조용한 에러.

명확한 에러 (빨간 메시지)

터미널이나 브라우저 콘솔에 빨간 글씨로 나오는 에러. 정보가 많으므로 오히려 다루기 쉽습니다. 전체를 복사해서 그대로 Claude에게 보내세요.

이 에러 전체 보여줄게:
[에러 메시지 전체 붙여넣기]

이 에러를 수정 전에, 왜 이게 나는지 원인부터 2-3가지로 설명해줘.

조용한 에러 (증상만 있음)

에러 메시지 없이 "버튼을 눌러도 아무 일이 없다", "숫자가 이상하게 나온다", "느리다" 같은 증상만 있는 경우. 이때는 현상을 정확하게 묘사하는 것이 첫 번째 단계입니다.

에러 메시지는 없는데, 이런 현상이 있어:
- 로그인 버튼을 누르면 클릭 반응이 없음
- 콘솔에는 아무것도 안 나옴
- 네트워크 탭에서 API 요청이 보이지 않음

클릭 이벤트가 제대로 연결됐는지부터 확인해줘.

현상을 여러 각도에서 관찰해 적어두면, Claude가 원인을 훨씬 빠르게 좁힙니다.

에러 기록의 힘: 같은 실수를 두 번 하지 않는 방법

에러를 고쳤을 때 그냥 넘어가는 것과, 한 줄 기록을 남기는 것의 차이는 3개월 뒤에 나타납니다.

기록하는 방법:

이 에러를 고쳤으니, CLAUDE.md에 다음을 추가해줘:
- 에러 유형: [에러 이름]
- 원인: [발생 원인 한 줄]
- 해결: [해결 방법 한 줄]
- 예방: [앞으로 이 에러를 피하려면]

예시:

# 자주 만나는 에러
## undefined.map() 에러
- 원인: API 데이터 로딩 전에 렌더링 시도
- 해결: Optional Chaining 또는 early return 추가
- 예방: 배열 데이터는 항상 초기값을 빈 배열로 선언

이게 쌓이면 CLAUDE.md가 프로젝트의 에러 가이드북이 됩니다. 새 세션에서도 이 가이드북이 읽혀 같은 에러가 줄어듭니다.

디버깅 중 사람이 해야 할 것 vs Claude가 해야 할 것

디버깅을 Claude에게 전적으로 맡기는 것과, 역할을 나누는 것은 결과가 다릅니다.

Claude가 잘하는 것

에러 메시지 해독 및 설명
같은 에러 패턴과 유사 사례 인식
가능한 원인 목록 제시
특정 파일의 코드 분석
수정 후 검증 코드 작성

사람이 해야 할 것

"이게 실제로 일어났는지" 직접 테스트
"이 수정이 내가 원하는 방향인지" 판단
"왜 이 에러가 나는 환경인지" 비즈니스 맥락 설명
"이 해결책이 다른 부분에 영향을 주는지" 확인

에러를 Claude에게 던지고 "고쳐줘"로 끝나면, 같은 에러를 반복하게 됩니다. 원인을 함께 이해하면 다음에는 빨라집니다.

자주 묻는 것들

"에러 메시지가 너무 길어서 다 복사하기 힘들어요"

길어도 다 복사하는 게 낫습니다. 대부분의 에러에서 진짜 원인은 메시지 중간이나 아래쪽에 있습니다. 첫 줄만 있으면 Claude가 추측으로 접근해야 하고, 그러면 틀릴 확률이 높습니다.

"에러를 고쳤는데 다시 나와요"

두 가지 가능성: 수정이 완전하지 않았거나, 다른 원인이 있습니다. 이럴 때는 새 세션에서 "이전에 이렇게 고쳤는데 에러가 재발했어. 이전 접근 말고 다른 원인이 있는지 봐줘"라고 해보세요.

"영어 에러 메시지를 이해 못해도 되나요?"

됩니다. 통째로 붙여넣으세요. 해석은 Claude가 합니다. 오히려 해석하려다 요점을 놓치는 경우가 있습니다.

"에러가 너무 많을 때 어디서부터 봐야 하나요?"

빌드 에러나 타입 에러가 수십 개씩 쏟아질 때는 이렇게 물어보세요:

에러가 너무 많아. 전체 에러 목록을 보여줄게.
어떤 순서로 고치는 게 맞는지, 또 어떤 에러가 다른 에러의 원인인지 분석해줘.
가장 근본 원인부터 고치는 것으로 시작해줘.

에러는 종종 연쇄 반응입니다. 근본 원인 하나를 고치면 20개 에러가 동시에 사라지는 경우도 있습니다.

"에러 없이 기능이 이상하게 동작할 때는?"

"동작은 하는데 이상해"는 에러 메시지가 없어서 어렵습니다. 이럴 때는 의도한 동작과 실제 동작을 나란히 설명하세요:

로그인 기능이 동작은 하는데 이상해.
의도: 로그인 성공 후 /dashboard 페이지로 이동해야 함
실제: 로그인 성공 후 /login 페이지에 그대로 있음

코드를 보고 왜 리다이렉트가 안 되는지 찾아줘.

"의도 vs 실제" 형식이 Claude가 버그를 찾는 데 가장 빠른 방법 중 하나입니다.

디버깅 속도를 높이는 세 가지 원칙

원칙 1: 먼저 보여주고, 나중에 이해하기 에러를 이해한 다음 Claude에게 물어보려 하면 시간이 두 배로 늘어납니다. 이해 전에 먼저 보여주세요.

원칙 2: 범위를 좁히는 질문을 하기 "왜 안 되지?"보다 "로그인만 안 되는지 확인해줘"가 훨씬 빠릅니다. 범위를 좁혀가는 질문이 넓은 질문보다 빠른 답을 만들어냅니다.

원칙 3: 한 번에 하나만 고치기 여러 곳을 동시에 고치면 어떤 수정이 효과가 있었는지 알 수 없습니다. 느려 보여도 한 번에 하나가 전체적으로 더 빠릅니다.

알아두면 유용한 기능들

이미지 입력, 음성 지시, 실수 복구, 자동 압축 등 터미널 경험을 높여주는 기능 모음.

14. 알아두면 유용한 기능들 — 손에 익을수록 편해지는 것들

처음부터 다 알 필요는 없습니다. 막히는 순간이 생겼을 때, "아 이런 게 있었지" 하고 꺼내쓰는 도구들입니다.

Claude Code 공식 권한 모드 페이지 출처: Permission Modes — Anthropic 공식 문서

입력을 편하게

스크린샷·디자인을 바로 보여주고, 길어지는 입력은 음성으로.

이미지·음성

실수 복구

잘못된 변경을 한 단계 또는 여러 단계 전으로.

체크포인트·rewind

세션이 길어질 때

컨텍스트 한도 근처에서 자동으로 요약·기억.

auto-compact·메모리

안전하게 쓰기

민감 명령은 격리, 권한은 단계별로.

권한·샌드박스

이미지를 그대로 보여주기

스크린샷이나 디자인 시안을 Claude에게 직접 전달할 수 있습니다. 말로 설명하기 어려운 UI 문제나 시각적 요구사항은 이미지가 훨씬 빠릅니다.

붙여넣는 방법은 세 가지입니다:

Ctrl+V     : 클립보드 이미지를 그대로 붙여넣기
드래그앤드롭: 이미지 파일을 터미널 창으로 끌기
파일 경로  : "@screenshot.png 이걸 보고 분석해줘"

지원 형식: JPEG, PNG, GIF, WebP (파일당 최대 5MB)

처음 이 기능을 알았을 때 가장 먼저 한 건 에러 화면 캡처를 붙여넣는 것이었습니다. 텍스트로 설명하면 세 줄이 필요한 것이 이미지 하나로 끝났습니다.

이미지로 요청할 때 잘 되는 패턴

"이미지만 보내기"보다 "이미지 + 무엇을 봐야 하는지"가 훨씬 빠른 결과를 만듭니다.

나쁜 예:
[이미지만 붙여넣기]

좋은 예:
[이미지 붙여넣기]
"이 화면에서 모바일에서 텍스트가 겹치는 이유를 찾아줘.
 수정은 나중에 하고 원인만 먼저 설명해줘."

이미지가 잘 작동하는 상황 세 가지:

UI 깨짐 확인: 레이아웃, 겹침, 색상 어긋남은 텍스트보다 이미지가 정확
에러 화면 전달: 복사하기 힘든 에러 팝업도 그대로 전달
디자인 구현 요청: 여백, 폰트 크기, 색상 계층을 한 번에

💡 한 번은 이런 일이 있었습니다. 강의에서 한 분이 모바일 레이아웃 깨짐 문제를 텍스트로 설명하는 데 20분을 썼습니다. "버튼이 겹쳐요"라고 하면 Claude가 어떻게 겹치는지 몰라서 계속 다시 물어보는 상황이었습니다. 스크린샷을 찍어 붙여넣었더니 30초 만에 "flex 컨테이너의 min-width가 없어서 overflow가 발생하고 있습니다"라는 답이 나왔습니다. 20분이 30초가 됐습니다.

음성으로 설명하기

타이핑이 부담스러운 긴 설명은 말로 할 수 있습니다. 음성 입력은 iOS Claude 앱과 웹(claude.ai/code)의 마이크 버튼을 사용합니다. (터미널 Claude Code에는 별도의 /voice 슬래시 커맨드가 없습니다.)

마이크 버튼 누르고 말하기 → 자동으로 텍스트 변환 → 전송

한국어를 포함한 다국어를 지원하고, 음성으로 전달한 뒤 타이핑으로 보완하는 혼합 방식도 됩니다.

음성 입력은 구체적인 파일명이나 변수명 없이 "어떤 느낌인지"를 설명할 때 가장 빛납니다. 그 다음 타이핑으로 정밀하게 보완합니다.

음성으로:
"로그인 화면이 너무 복잡해보여. 소셜 로그인을 아래로 내리고 이메일만 위에 남겨두고 싶어."

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

방금 수정이 마음에 안 들 때: Esc Esc

Claude가 파일을 수정하기 직전 상태를 자동으로 저장해둡니다. Esc 키를 두 번 연속으로 누르면 그 직전 상태로 돌아갑니다.

별도 설정 없이 자동으로 동작합니다. git을 몰라도 됩니다.

이럴 때 바로 누르세요:

Claude가 범위를 넘어 예상치 않은 파일까지 수정했을 때
디자인 변경을 해줬는데 방향이 틀렸을 때
에러를 고치려다 오히려 에러가 더 많아졌을 때

Esc Esc는 직전 한 단계로 돌아갑니다. 여러 단계 전으로 가야 한다면 /rewind가 맞습니다.

더 먼 시점으로 돌아가기: /rewind

대화 기록과 파일 변경을 함께 원하는 시점으로 되돌립니다.

/rewind 실행 → 시점 목록 확인 → 원하는 지점 선택

Esc Esc가 "방금 전으로"라면, /rewind는 "어느 시점으로든" 가능합니다.

되돌리고 나서 바로 새 작업을 시키기보다, 현재 상태를 먼저 확인하는 것이 안전합니다.

> /rewind
(시점 선택)
> 지금 어떤 파일이 변경된 상태인지 확인해줘

컨텍스트가 자동으로 관리되는 두 가지 방법

자동 압축 (auto-compact)

컨텍스트가 한도에 가까워지면 Claude가 자동으로 오래된 내용을 정리합니다. 아무것도 설정하지 않아도 작동합니다.

단, 자동 압축은 Claude가 중요하다고 판단한 것을 남기는 방식입니다. 내가 중요하게 여기는 맥락이 날아갈 수 있습니다. 중요한 세션이라면 70%가 되기 전에 직접 /compact 이것 중심으로 요약해줘를 쓰는 편이 안전합니다.

자동 메모리 (Auto Memory)

Claude가 작업 중 중요해 보이는 정보를 자동으로 메모리에 저장합니다. 새 세션에서도 이 정보를 읽어 맥락을 이어갑니다.

/memory로 저장된 메모리를 확인하거나 편집할 수 있습니다.

하지만 자동 메모리에 프로젝트 핵심 규칙을 맡기는 것은 위험합니다. 규칙은 CLAUDE.md에 직접 적는 것이 훨씬 안정적입니다.

무엇을 어디에 넣을지	권장 위치
개인 작업 선호	Auto Memory
프로젝트 고유 규칙	`./CLAUDE.md`
팀 공통 규칙	Git에 포함된 `./CLAUDE.md`
일회성 세션 메모	세션 안 또는 `/compact` 요약

생각 깊이 조절하기: /effort

어려운 문제나 복잡한 설계를 다룰 때 Claude가 더 깊이 생각하도록 조절할 수 있습니다.

/effort low     → 단순 작업, 빠른 답변
/effort high    → 복잡한 문제, 깊은 추론
/effort xhigh   → Opus 4.7에서만, 가장 깊은 사고

사용할 수 있는 레벨: low · medium · high · xhigh(Opus 4.7만) · max. 모델별로 가용 레벨이 다르니 현재 모델에서 어떤 레벨이 잡히는지는 /effort로 한 번 확인해 보세요.

인자 없이 /effort만 입력하면 슬라이더로 레벨을 직접 선택할 수 있습니다.

깊게 생각한다고 항상 좋은 건 아닙니다. 단순한 텍스트 수정이나 파일 이름 바꾸기에 xhigh를 쓰면 오히려 느려집니다.

작업 유형	추천 레벨
오탈자 수정, 형식 변환	`low` 또는 기본값
일반 기능 구현, 문서 작성	기본값
아키텍처 설계, 까다로운 버그	`high`
복잡한 알고리즘, 고위험 의사결정	`high` 또는 `xhigh`

권한 모드: Claude가 뭘 할 수 있는지 제어하기

Claude가 파일을 수정하거나 명령을 실행할 때 어떻게 확인을 받을지 설정합니다.

모드	동작 방식	적합한 상황
`default`	모든 변경마다 확인	처음 시작, 낯선 프로젝트
`acceptEdits`	파일 편집은 자동 승인, 명령어는 확인	신뢰하는 프로젝트에서 속도 올리기
`plan`	계획만 보여주고 파일 건드리지 않음	큰 변경 전 검토
`auto`	안전 검사 후 자동 승인 (Pro 미지원)	자동화된 워크플로우
`bypassPermissions`	모든 확인 없이 진행	컨테이너 등 격리 환경 전용

적용 방법:

# 세션 시작 시
claude --permission-mode acceptEdits

# 세션 중에 변경
/permissions

💡 한 번은 이런 일이 있었습니다. WSL2에서 큰 프로젝트를 작업할 때 파일마다 확인 요청이 와서 리듬이 끊겼습니다. acceptEdits 모드로 바꿨더니 파일 편집은 자동 승인되고 셸 명령만 확인이 왔습니다. 속도가 훨씬 빨라졌습니다. 하지만 새 프로젝트나 팀 환경에서는 여전히 default로 시작합니다. 무엇이 허용되는지 먼저 파악하고, 익숙해진 뒤 모드를 바꾸는 것이 순서입니다.

확장 기능들: 아직 Research Preview 단계이지만

아래 기능들은 아직 일부 사용자에게만 열려 있거나 Preview 단계입니다. 지금 당장은 아니어도 "이런 방향으로 가고 있다"는 것을 알아두면 됩니다.

Computer Use: Claude가 화면을 직접 보고 마우스와 키보드를 조작합니다. GUI 테스트나 반복 클릭 작업 자동화에 쓰입니다. (Research Preview, macOS 우선) · 참고로 Computer Use는 Claude API에서 제공하는 도구이고, 터미널 Claude Code 자체 기능과는 별개입니다.

Remote Control: QR 코드를 스캔하면 폰에서도 현재 Claude Code 세션을 이어갈 수 있습니다. 이동 중에 지시 내용을 보내거나 결과를 확인하는 용도입니다.

Chrome 연동: Claude가 Chrome 브라우저를 직접 제어합니다. 웹 페이지 테스트, 특정 데이터 추출, 폼 자동 채우기 작업에 씁니다.

예약 실행 (Routines · /schedule): 지정한 프롬프트를 정해진 시각·간격으로 자동 실행합니다. 정기 점검, 상태 모니터링, 반복 리포트 생성에 활용됩니다. (/loop는 공식 내장이 아니라 일부 플러그인(superpowers 등)이 제공하는 커맨드입니다.)

기능별 빠른 선택표

"지금 이 상황에서 뭘 써야 하지?"라는 질문에 바로 답하는 표입니다.

지금 이런 상황이라면	이 기능을 쓰세요
화면 깨짐을 말로 설명하기 어렵다	이미지 입력 (Ctrl+V)
긴 설명을 타이핑하기 귀찮다	iOS·웹의 마이크 버튼으로 음성 입력
방금 Claude가 바꾼 게 마음에 안 든다	`Esc Esc`
여러 단계 전 상태로 돌아가야 한다	`/rewind`
응답이 느려지고 맥락이 흐려지기 시작	`/compact`
복잡한 설계 문제를 다뤄야 한다	`/effort high`
Claude가 파일을 너무 자유롭게 건드린다	권한 모드 확인 `/permissions`
브라우저에서 실제 동작을 시험해야 한다	Chrome 연동

기능을 많이 외우는 것보다 "이 상황에 뭘 꺼내야 하는가"를 아는 것이 더 중요합니다.

사용 빈도와 상황의 관계

6개월 동안 실제로 쓰면서 느낀 각 기능의 쓰임새입니다.

매일 쓰게 되는 것들: 이미지 입력, Esc Esc

한 주에 몇 번: /compact 수동, /effort 조절

필요할 때 한 번씩: /rewind, iOS·웹 음성 입력, 권한 모드

특수 상황: Computer Use, Remote Control, Chrome 연동, Routines(/schedule)

처음부터 모두 익히려 하면 오히려 아무것도 안 쓰게 됩니다. 이미지 입력과 Esc Esc만 먼저 손에 익히는 것으로 시작하세요.

이 장을 덮기 전에

스크린샷을 Ctrl+V로 대화창에 붙여넣어봤다
Esc Esc를 실행해서 이전 수정 상태로 돌아가는 것을 경험했다
/rewind를 실행해서 시점 목록이 나타나는 것을 확인했다
/permissions 또는 /effort를 한 번 실행해서 현재 설정을 봤다
기능별 빠른 선택표를 보면서 지금 상황에 맞는 기능을 하나 골라봤다

이 가이드의 핵심 섹션이 여기서 마무리됩니다. 이후 장들에서는 더 고급 기능들, MCP, Hooks, 워크트리 등을 다룹니다. 지금까지 익힌 것들이 기반이 되면, 나머지는 자연스럽게 따라옵니다.

프롬프트 잘 쓰는 법

결과 품질의 80%는 프롬프트에서 갈립니다. 4요소 · 템플릿 · 안티패턴.

15. 프롬프트가 틀리면 모델이 아무 소용없습니다

결과가 이상할 때 모델 탓을 먼저 하게 됩니다. 그런데 대부분은 프롬프트 문제였습니다.

강의에서 처음 하는 질문이 있습니다. "지난 한 주 Claude를 쓰면서 결과가 마음에 안 들었던 적이 있나요?" 거의 모두가 손을 듭니다. 그다음에 "그때 프롬프트를 다시 읽어봤나요?"라고 물으면, 손을 내립니다. 경험상 그 순간이 가장 중요한 학습 포인트입니다. 프롬프트는 코드처럼 정확해야 합니다. 컴파일러가 세미콜론 하나에도 멈춰 서듯 정확함이 필요한데, Claude는 멈추는 대신 빈칸을 추측으로 채웁니다. 그 추측이 맞을 때는 천재처럼 보이고, 빗나갈 때는 엉터리처럼 보입니다. 하지만 그건 모델의 문제가 아니라 정보의 문제입니다.

이 섹션에서 다루는 내용은 단순합니다. 프롬프트에 무엇을 담아야 하는지, 어떤 패턴이 결과를 망가뜨리는지, 그리고 같은 요청을 다르게 쓰면 어떻게 달라지는지.

프롬프트를 처음 작성하는 사람과 두 달째 쓰는 사람의 결과물 차이는 모델 선택에서 나오지 않습니다. 네 가지 정보를 한 줄씩 더 담느냐 담지 않느냐에서 갈립니다.

4요소: 맥락·범위·예시·검증

맥락(Context) — "왜" 하는 작업인지

Claude는 지금 내가 무슨 프로젝트를 하고 있는지, 이 함수가 어디에 쓰이는지, 내가 어떤 배경을 가진 사람인지 알지 못합니다. 아무것도 알려주지 않으면 가장 범용적인 답을 내놓습니다. 가장 범용적인 답은 대개 내 상황에 딱 맞는 답이 아닙니다.

맥락은 "왜"를 담는 자리입니다. 이 작업을 왜 하는지, 이 코드가 어디서 쓰이는지, 나는 어떤 제약 안에 있는지.

나쁜 예) 이 함수 고쳐줘.

좋은 예) 이 함수는 결제 실패율을 줄이기 위해 만든 건데,
        네트워크 timeout이 자주 발생해서 retry 로직이 필요해.
        외부 결제 API를 다루는 코드라 side effect에 민감해.

💡 한 번은 이런 일이 있었습니다. 강의 중 한 분이 "로그인 버그 고쳐줘"라고만 입력하고 Claude가 로그인 함수 전체를 재작성한 뒤 당황했습니다. 그분이 원했던 건 이메일 유효성 검사 한 줄이었는데, Claude는 더 나은 방향으로 개선하겠다며 비밀번호 해시 로직까지 손댔죠. 그날부터 그분은 프롬프트 첫 줄에 항상 "무엇을 원하는가"와 "무엇을 원하지 않는가"를 함께 쓰기 시작했습니다. 결과가 달라졌습니다.

범위(Scope) — 어디까지 손대도 되는가

범위를 명시하지 않으면 Claude는 관련 있어 보이는 것들을 재량껏 건드립니다. 선의로 하는 행동이지만, 결과는 종종 작업이 너무 넓게 퍼지는 것입니다. 한 파일을 고쳐달라고 했는데 세 파일이 바뀌어 있거나, 로직만 수정해달라고 했는데 파일 구조까지 바뀌는 경우입니다.

범위는 짧고 구체적일수록 강력합니다.

좋은 예) src/auth/login.ts 파일 안의 validateEmail 함수만 수정해.
        다른 파일은 절대 건드리지 마.
        함수 시그니처(파라미터·반환 타입)는 변경 금지.

처음엔 이게 과한 것처럼 느껴집니다. 하지만 두 번 정도 범위 초과를 경험하면 자연스럽게 습관이 됩니다.

예시(Examples) — 말보다 입출력 한 쌍

"이런 형태로 만들어줘"를 100줄 설명하는 것보다, 입력 하나와 기대 출력 하나를 보여주는 편이 훨씬 정확합니다. Claude는 패턴을 보고 일반화하는 능력이 뛰어나서, 예시 한 쌍만 보여주면 설명 한 단락을 대신합니다.

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

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

형식뿐 아니라 "이 경우는 어떻게 처리하나요?"라는 엣지 케이스 전달에도 예시가 가장 빠릅니다.

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

요청 끝에 "어떻게 확인할지"를 붙이면 Claude가 스스로 확인 과정을 포함시킵니다. 이것 하나로 결과물 완성도가 달라집니다.

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

또는) 변경 후 결과를 예시 두 개로 보여줘서
      내가 직접 확인할 수 있게 해줘.

Before / After: 같은 요청, 다른 결과

처음엔 차이가 과장처럼 보입니다. 실제로 해보면 차이가 납니다.

Before (모호한 요청)	After (4요소 적용)
"이 코드 좀 더 깔끔하게 해줘"	"src/utils/parser.ts의 parseDate 함수만 리팩터링. 동작은 그대로 유지하고, 가독성을 위해 if-else를 early return으로 바꿔줘. 변경 후 기존 테스트가 통과하는지 확인."
"버그가 있는 것 같아"	"/login 페이지에서 비밀번호 5글자 이하면 에러가 떠야 하는데 안 떠. 입력: 'abc' → 기대: 에러 메시지 표시. 현재: 그냥 제출됨. 원인 찾아줘."
"보고서 만들어줘"	"@meeting-notes.md를 읽고, 액션 아이템만 담당자별로 정리한 마크다운 표를 만들어. 회의 분위기·잡담은 빼고, 미정 항목은 'TBD'로 표시."

자주 쓰는 프롬프트 템플릿

실제로 반복 사용하는 형태입니다. 빈칸만 채우는 구조라 처음에 외우기 어렵지 않습니다.

템플릿 1: 새 기능 추가

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

템플릿 2: 버그 수정

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

템플릿 3: 리팩터링

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

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

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

안티패턴: 이렇게 쓰면 결과가 무너집니다

안티패턴	실제로 일어나는 일	대신
"다 알아서 해줘"	Claude가 추측으로 채움. 그 추측이 틀렸을 때 디버깅이 두 배 걸림	한 가지 작업으로 좁히기
"그냥 좋게 해줘"	"좋다"의 기준이 없어서 Claude가 임의의 기준으로 평가	가독성? 속도? 줄 수?: 1개만
"전체적으로 개선해줘"	변경 범위가 폭주해서 리뷰가 불가능해짐	파일·함수 단위로 쪼개기
"버그 있어 고쳐줘"	Claude가 어떤 버그인지 추측하며 엉뚱한 곳을 고침	증상·기대·재현 3종
"최신 트렌드 반영해줘"	"트렌드"의 정의가 없어서 일관성 없는 결과	참고 링크/예시 같이 주기

💡 한 번은 이런 일이 있었습니다. 제가 직접 "auth 모듈 리팩터링해줘"라고만 보냈다가, Claude가 JWT 라이브러리를 교체하고 미들웨어 구조까지 바꿔버린 적이 있습니다. 작업 의도와 완전히 달랐고, 되돌리는 데 30분이 걸렸습니다. 그 뒤로 리팩터링 요청에는 항상 "무엇을 바꾸지 말아야 하는지"를 먼저 적습니다. 금지 사항을 명시하는 것이 허용 사항을 나열하는 것보다 훨씬 효과적입니다.

입력 보강: 프롬프트만으로 부족할 때

프롬프트 텍스트만으로 설명하기 어려운 상황이 있습니다. 그때는 다른 입력 방식을 함께 쓰세요.

상황	함께 쓸 기능
UI나 화면 배치 설명이 어렵다	스크린샷 붙여넣기 (Ctrl+V)
긴 요구사항을 말로 풀어 설명하고 싶다	`/voice` 음성 입력
기존 파일을 읽고 분석시키고 싶다	`@filename` 참조
외부 문서를 근거로 삼고 싶다	URL 첨부

이 기능들은 14번 섹션에서 다룬 것들과 자연스럽게 이어집니다.

실전 예시: 같은 요청, 세 가지 버전

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

모호한 버전 (1점)

주식 종목 정리 좀 해줘.

Claude가 "정리"를 어떻게 해석할지 알 수 없습니다. 표가 나올 수도, 텍스트 요약이 나올 수도 있습니다.

보통 버전 (5점)

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

형식은 지정했지만 열이 몇 개인지, 정렬은 어떻게 할지, 비어 있는 항목은 어떻게 처리할지 여전히 불분명합니다.

4요소 적용 버전 (9점)

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

같은 도구, 같은 모델인데 결과의 완성도는 분명하게 다릅니다. 9점짜리 프롬프트는 후처리 없이 바로 씁니다. 1점짜리는 결과를 받아도 다시 손을 봐야 합니다.

한 줄 확인: 보내기 전에

프롬프트를 보내기 전에 딱 두 가지만 확인하세요.

"이 프롬프트만 읽은 사람이 내가 원하는 것을 알 수 있나?"
"Claude가 범위를 초과하면 어떤 피해가 생기고, 그걸 막는 말이 들어 있나?"

이 두 질문에 "예"가 나오면 보내도 됩니다.

💡 한 번은 이런 일이 있었습니다. 강의 마지막에 수강생이 이런 말을 했습니다. "프롬프트 쓰는 게 이메일 쓰는 것보다 더 많이 생각하게 되네요." 맞습니다. 좋은 프롬프트는 내가 원하는 것을 한 번 명확히 정리하는 행위이기도 합니다. 그 명확성이 Claude에게 전달될 뿐 아니라, 내 머릿속에도 작업을 정리해줍니다. 그래서 프롬프트를 잘 쓰는 사람은 결과뿐 아니라 사고 방식도 달라집니다.

이 장을 덮기 전에

오늘 보낸 프롬프트 하나를 꺼내서 맥락·범위·예시·검증이 각각 들어 있는지 점검해봤다
"이렇게 하지 마"를 명시한 제약 조건을 프롬프트에 넣어봤다
Before/After 비교 표의 "After" 형태 중 하나를 직접 써봤다
결과가 만족스럽지 않았을 때 모델 탓이 아니라 프롬프트를 먼저 점검해봤다

다음 장(16 Plan Mode & 안전한 실수 복구)에서는 좋은 프롬프트를 쓰는 것과 별개로, 실행 전에 계획을 먼저 검토받는 방법을 다룹니다. 프롬프트가 완벽해도 작업 범위가 크면 먼저 계획을 보고 싶을 때가 있습니다. 그것이 Plan Mode입니다.

Plan Mode & 안전한 실수 복구

되돌릴 수 있다는 안전감이 실험 속도를 만듭니다. Plan, Checkpoint, /rewind.

16. 실행 버튼을 누르기 전에 한 번 멈추는 법

"되돌릴 수 있다"는 안전감이 실험 속도를 만듭니다. 되돌릴 수 없다는 두려움은 실험 자체를 막습니다.

처음 Claude Code를 쓰기 시작했을 때, 저는 큰 변경 앞에서 늘 머뭇거렸습니다. "폴더 구조를 바꿔달라고 하면 어디까지 건드릴까?", "결제 모듈을 리팩터링해달라고 했다가 테스트가 다 깨지면?" 그 머뭇거림이 실험을 늦추고, 결과적으로 일 속도도 늦췄습니다. 나중에 깨달은 건 그 머뭇거림이 능력의 문제가 아니라 안전망의 부재에서 온다는 것이었습니다.

지금은 큰 변경 앞에서 세 가지를 씁니다. 실행 전 계획 합의(Plan Mode), 단계별 되감기(/rewind), 그리고 세션을 넘나드는 복구 지점(git commit). 이 세 가지를 쓰고 나서부터는 "잘못되면 어쩌지"가 아니라 "일단 해보자"가 먼저 나옵니다.

큰 변경 앞에서 망설이는 이유는 거의 한 가지입니다. "잘못되면 되돌리기 힘들 것 같다"는 느낌. Plan Mode와 Checkpoint는 그 느낌을 실제로 없애줍니다.

Plan Mode: 코드보다 계획이 먼저입니다

Plan Mode가 하는 일

Claude가 파일을 한 줄도 건드리지 않고 어떻게 할 것인지 계획만 보여주는 모드입니다. 마음에 들면 그때 실행합니다. 마음에 들지 않으면 계획 단계에서 방향을 잡습니다.

이게 중요한 이유는 간단합니다. 실행 중에 방향을 틀면 이미 수정된 파일들을 되돌려야 하지만, 계획 단계에서 방향을 틀면 아무것도 되돌릴 게 없습니다.

켜는 법

Shift + Tab  (권한 모드 사이클을 돌려 plan에 도달)

또는

claude --permission-mode plan

또는

세션 안에서: /permissions → plan

처음엔 Shift+Tab 두 번이면 들어가는 경우가 많습니다. 좌측 하단 표시를 보고 "plan"이 나오는지 확인하세요.

언제 Plan Mode를 켜야 하나

여러 파일을 동시에 바꾸는 리팩터링
데이터 마이그레이션, 스키마 수정처럼 롤백 비용이 큰 작업
처음 써보는 라이브러리나 프레임워크 도입
외부 API 호출이 많은 작업 (취소가 어려운 부작용)
팀 코드베이스에서 큰 구조 변경

Plan Mode 실제 흐름

1) Shift+Tab으로 Plan Mode 켜기
2) "결제 모듈에 retry 로직 넣을 건데, 어떻게 할 건지 계획 보여줘"
3) Claude가 단계별 계획을 출력 — 어떤 파일을 어떻게 바꿀지
4) 계획이 마음에 들면 → 일반 모드로 돌아가 실행
5) 놓친 부분이 보이면 → 계획 단계에서 추가 지시 후 재검토

💡 한 번은 이런 일이 있었습니다. 결제 모듈 retry 로직을 추가하다가 Plan 없이 바로 시작했더니, Claude가 retry 로직뿐 아니라 에러 핸들링 패턴 전체를 바꿔버렸습니다. 결과물은 더 나아 보였지만, 다른 모듈과 인터페이스가 달라졌고 팀원이 작업 중인 코드와 충돌이 났습니다. 그 뒤로 구조에 영향을 줄 것 같은 작업은 반드시 Plan을 먼저 보고 시작합니다. Plan 출력에서 "아, 이 파일도 건드리려 했구나"를 미리 발견해서 범위를 좁히는 게 훨씬 쌉니다.

opusplan: 설계는 Opus로, 실행은 Sonnet으로

/model opusplan은 Plan 단계는 Opus, 실행 단계는 Sonnet으로 자동 전환되는 공식 alias입니다.

/model opusplan

비용 구조:

Plan은 한 번, 짧게 (Opus 가격이지만 토큰이 적게 사용됨)
실행은 길게 (Sonnet 가격으로 많은 토큰 사용)
결과적으로 Opus만 쓸 때보다 절반 이하 비용

이름처럼 Plan을 Opus로 잡고 나머지를 Sonnet으로 실행하는 패턴입니다. 중요한 설계 결정은 가장 좋은 모델이 내리게 하고, 반복적인 실행 작업은 더 가벼운 모델에 맡깁니다.

💡 단, opusplan의 Plan 단계는 200K 컨텍스트를 사용합니다. 1M 컨텍스트가 자동 적용되지 않으니 매우 큰 코드베이스를 분석시키려면 별도 고려가 필요합니다.

Esc Esc: 방금 한 것을 즉시 되돌리기

Claude가 파일을 수정하기 직전에 자동으로 스냅샷을 저장합니다. 별도 설정이 없어도 동작합니다.

Esc 키를 두 번 누르면 → 직전 상태로 복구

이럴 때 바로 씁니다:

의도와 다르게 파일이 수정되기 시작할 때
디자인을 바꿨는데 이전이 더 좋아 보일 때
에러를 고치려다 더 많은 에러가 생겼을 때
범위가 예상보다 넓어지는 것을 발견했을 때

git을 전혀 모르는 사람도 즉시 쓸 수 있는, 가장 빠른 복구 방법입니다.

💡 한 번은 이런 일이 있었습니다. 강의에서 한 분이 네비게이션 컴포넌트 스타일을 변경하다가, Claude가 공통 레이아웃 전체를 건드리기 시작하는 걸 눈치챘습니다. 두 파일이 수정된 상태였고, 이미 원본이 어떤 모양이었는지 기억이 안 났습니다. Esc를 두 번 눌렀더니 즉시 돌아왔습니다. "이거 진짜예요?" 하며 놀라던 표정이 기억납니다. 그 뒤로 Esc Esc는 Claude Code를 쓸 때 가장 먼저 알려주는 단축키가 됐습니다.

/rewind: 원하는 시점까지 되돌리기

Esc Esc가 "방금 한 것 하나"라면, /rewind는 원하는 시점까지 대화와 코드를 함께 되감습니다.

/rewind
→ 시점 목록이 나타남
→ 원하는 지점 선택

"로그인 UI 변경 전으로", "테스트 추가 전으로" 같은 자연어 시점도 인식합니다.

되돌린 직후에는 현재 상태를 한 번 확인하세요. 바로 새 작업을 시키면 어디서부터인지 헷갈립니다.

> 지금 변경된 파일이 남아 있는지, 깨끗한 상태인지 확인해줘

/checkpoint, /undo도 같은 명령의 alias입니다. 셋 다 동작은 동일합니다.

"여기는 꼭 돌아오고 싶다"는 지점이 생기면, 그때 git commit을 명시적으로 남기는 게 가장 안전합니다.

> 지금 상태로 git에 'checkpoint: before payment refactor' 메시지로 커밋해줘

세 가지 복구 도구 비교

복구

Esc Esc

범위직전 1단계
속도즉시
추천방금 수정이 마음에 안 들 때

복구

/rewind

범위원하는 시점까지
속도빠름
추천여러 단계 거슬러 가야 할 때

복구

git revert / reset

범위임의 커밋
속도보통
추천세션을 넘어서 복구할 때

도구	범위	속도	추천 상황
Esc Esc	직전 1단계	즉시	방금 수정이 마음에 안 들 때
/rewind	원하는 시점까지	빠름	여러 단계 거슬러 가야 할 때
git revert / reset	임의 커밋	보통	세션을 넘어서 복구할 때

세 가지를 겹쳐 쓰는 것이 정석입니다. Esc Esc는 즉흥적 되돌리기, /rewind는 세션 내 타임머신, git은 세션을 넘는 영구 기록입니다.

안전망 3종 세트

큰 작업 앞에서 이 순서를 떠올려두세요.

git commit: 세션이 끊겨도 안전한 마지막 안전망. 커밋이 있으면 어떤 상황에서도 돌아올 수 있습니다.
Plan Mode: 실행 전에 합의해 큰 사고 자체를 막습니다. 파일을 한 줄도 건드리기 전에 방향을 확인합니다.
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 없이 바로 실행	의도와 다른 변경이 여러 파일에 퍼짐. 되돌리는 비용이 큼
Plan만 보고 아무 의심 없이 OK	계획에 숨어 있는 가정·전제를 못 잡음. 실행 중에 발견하면 더 복잡해짐
`/rewind` 후 바로 새 작업	어디서부터인지 헷갈려 두 번 작업하게 됨. 상태 확인이 먼저
git commit 안 하고 큰 작업 진행	세션이 끊기면 회수 불가. 세션 밖 안전망은 git뿐
Esc Esc를 모르는 상태로 사용	직전 단계만 되돌림. 여러 단계 전이라면 /rewind 필요

이 장을 덮기 전에

Shift+Tab을 눌러서 Plan Mode 표시가 하단에 뜨는 것을 확인해봤다
테스트 목적으로 작은 변경을 시키고 Esc를 두 번 눌러서 되돌려봤다
/rewind를 입력해서 시점 목록이 어떻게 나타나는지 확인해봤다
큰 작업 전에 git commit을 먼저 남기는 습관을 한 번 실천해봤다

다음 장(17 Statusline & 비용 가시화)에서는 계획과 복구만큼 중요한 또 다른 것을 다룹니다. 지금 얼마나 쓰고 있는지 보이게 만드는 것. 안전하게 실험하려면 비용이 눈에 들어와야 합니다.

Statusline & 비용 가시화

보이지 않는 비용은 통제할 수 없습니다. 터미널 하단을 비용 대시보드로 만드는 법.

17. 비용은 보여야 통제됩니다

계기판 없는 차로 고속도로에 올라가는 사람은 없습니다. 터미널도 마찬가지입니다.

Max 플랜으로 업그레이드한 첫 달, 한도 경고 이메일을 받았을 때 처음으로 "내가 오늘 얼마나 썼지?"를 물었습니다. 작업에 빠져 있다 보면 토큰이 차오르는 걸 모릅니다. 어느 날 갑자기 답변이 느려지거나, 월말에 청구서가 예상보다 많이 나옵니다. 둘 다 "보이지 않아서" 생기는 일입니다.

해법은 생각보다 단순합니다. 터미널 하단 한 줄에 지금 어떤 모델을 쓰고 있는지, 토큰이 얼마나 차올랐는지, 이 세션에서 얼마를 썼는지를 띄워두는 것. 그 한 줄이 있으면 큰 작업을 시작하기 전에 무의식적으로 한 번 흘끗 보게 됩니다. 그 짧은 흘끗이 매달 청구서를 바꿉니다.

보이는 것만 통제할 수 있습니다. 비용을 통제하려면 먼저 보여야 합니다.

Statusline: 터미널 하단의 비용 계기판

Claude Code를 열면 터미널 하단에 늘 떠 있는 한 줄 상태표시가 Statusline입니다. 처음 쓸 때는 별로 눈에 들어오지 않다가, 한 번 의식적으로 보기 시작하면 그 뒤로는 자연스럽게 확인하게 됩니다.

기본적으로 표시되는 내용:

항목	의미
모델	지금 쓰는 모델 (sonnet / opus / opusplan 등)
토큰 사용량	현재 컨텍스트 윈도우의 몇 % 찼는지
세션 비용	이번 세션에서 누적된 비용 (구독자는 한도 대비)
현재 모드	default / acceptEdits / plan / auto 등

별도 설정 없이 Claude Code를 열면 자동으로 표시됩니다.

보이지 않으면 어떤 일이 생기나

실제로 Statusline을 껐을 때와 켰을 때의 차이를 하나씩 짝지어보면:

안 보고 일할 때	보면서 일할 때
토큰이 90% 넘었는데 모르고 계속 → auto-compact 발동 → 맥락 일부 손실	80% 도달 시 `/compact`로 의도적으로 정리
Opus로 단순 작업 30분 진행 → 청구서 깜짝	Statusline에 'opus' 보이는 순간 sonnet으로 전환
acceptEdits 모드인 줄 모르고 위험 명령 실행	모드 표시로 즉시 감지
세션이 길어진 줄 모름	누적 비용 보고 새 세션 분리 결정

차이는 간단합니다. 보이면 손이 가고, 보이지 않으면 그냥 지나갑니다.

💡 한 번은 이런 일이 있었습니다. 강의에서 한 분이 "Sonnet인 줄 알고 두 시간 작업했는데 알고 보니 처음부터 Opus였다"고 했습니다. 요금제를 쓰는 분이라 직접 비용이 발생하는 상황은 아니었지만, 그날 이후 모델 표시를 항상 확인하게 됐다고 했습니다. 무엇을 쓰고 있는지 모르는 상태에서는 의도적인 선택이 불가능합니다.

/statusline: 더 보고 싶다면

기본 표시가 부족하거나 필요에 따라 더 보고 싶다면 /statusline으로 인터랙티브 메뉴를 엽니다.

/statusline

표시할 항목을 토글할 수 있습니다:

모델 · 토큰 사용량 · 세션 비용 · 현재 모드
현재 디렉터리 · git 브랜치 · 경과 시간
5시간 사용량 윈도우 · 7일 사용량 윈도우

색상과 강조 설정도 가능합니다. 설정 내용은 ~/.claude/settings.json 또는 프로젝트 .claude/settings.json에 저장됩니다. 한 번 설정하면 다음에 켤 때도 유지됩니다.

플러그인은 subagentStatusLine 키로 서브에이전트 전용 statusline도 따로 줄 수 있습니다.

/usage: 더 자세히 보고 싶을 때

/usage(alias: /cost, /stats)는 상세 리포트를 띄우는 명령입니다. Statusline은 상시 표시, /usage는 필요할 때 호출하는 방식입니다.

도구	시점	정보량
Statusline	항상	핵심 4~6개 항목
`/usage`	호출 시	세션 비용 전체, 한도 대비, 활동 통계, 모델별 분포

Statusline에서 이상 신호를 감지하고 → /usage로 정밀 진단하는 흐름이 정석입니다. Statusline이 "뭔가 많이 쓴 것 같다"는 감을 주면, /usage가 "어디서 얼마를 썼는지"를 보여줍니다.

비용 절감 워크플로우

Statusline을 보면서 다음 트리거에 반응하면 토큰 낭비의 90%는 막을 수 있습니다.

트리거	행동
토큰 사용 80%	`/compact 핵심만 정리해줘`
토큰 사용 95%	즉시 `/clear` 또는 git commit 후 새 세션
모델이 opus인데 단순 작업	`/model sonnet`
세션 비용이 평소 두 배	잠깐 멈추고 무엇 때문인지 점검

이 네 가지 반응이 몸에 익으면 예상 밖의 청구서가 나올 확률이 크게 줄어듭니다.

5시간 / 7일 사용량 윈도우

구독 플랜(Pro, Max, Team)은 Claude Code 사용량이 5시간 윈도우와 7일 윈도우에 묶입니다. 한도 가까워지면 답변이 느려지거나 막힙니다.

Statusline에 이 두 값을 띄워두면 "오늘 더 쓸 수 있나"를 한눈에 알 수 있습니다.

/statusline → "5h limit", "7d limit" 항목 활성화

💡 한도 표시는 구독 플랜에서만 의미가 있습니다. API 직접 사용자는 토큰·비용 항목이 더 관련이 있습니다.

비개발 작업에도 필요합니다

Statusline이 코딩 작업에만 필요한 것처럼 보이지만, 리서치·문서 작업에서도 중요합니다. 긴 텍스트를 다루거나 파일을 많이 읽는 작업은 토큰이 예상보다 빠르게 찹니다.

주식 리서치 세션 사례

오전 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%에 도달하면 매물을 그룹별로 새 세션으로 나눠서 처리하고, 종합 비교는 마지막에 한 번에 모으는 방식이 안정적입니다.

💡 한 번은 이런 일이 있었습니다. 경쟁사 10곳의 최근 블로그 포스트를 요약하는 리서치를 진행했는데, 7번째 회사부터 답변 품질이 이상해졌습니다. 나중에 확인하니 토큰이 95%를 넘어 auto-compact가 발동된 상태였습니다. 앞의 요약들이 잘려 나간 채 작업이 이어지고 있었던 것입니다. 그날부터 리서치 세션을 시작할 때는 Statusline 토큰 항목을 제일 먼저 확인합니다.

자주 하는 실수

실수	실제 결과
Statusline을 끔/숨김	토큰 한도 초과 자각 못함. 맥락 손실이 언제 일어났는지 모름
세션 비용만 보고 안심	토큰은 한도, 비용은 누적: 둘 다 봐야 함. 비용이 낮아도 토큰이 꽉 찰 수 있음
표시 항목을 너무 많이	시야가 산만해져서 결국 안 보게 됨. 4~5개로 핵심만
한 번 설정 후 그대로	작업 종류에 따라 필요한 항목이 다름. 리서치 세션과 코딩 세션이 다름

추천 설정: 작업별

작업	권장 표시 항목
일반 코딩	모델 · 토큰% · 모드
비용 민감 작업 (Opus, 긴 컨텍스트)	+ 세션 비용 · 5h 한도
비개발 리서치·문서 작업	모델 · 토큰% · 7d 한도
자동화·헤드리스	모델 · 모드 · 세션 비용

처음에는 기본 표시로 시작하고, 일주일 정도 써보면서 "이게 더 있었으면 좋겠다"는 항목을 하나씩 추가하는 방식이 가장 자연스럽습니다.

이 장을 덮기 전에

Claude Code 터미널 하단의 Statusline에 어떤 항목이 표시되는지 확인해봤다
/statusline을 입력해서 어떤 항목을 토글할 수 있는지 메뉴를 열어봤다
/usage를 입력해서 이번 세션의 상세 리포트를 한 번 확인해봤다
토큰이 80%를 넘으면 /compact를 쓰겠다는 트리거를 하나 정해봤다

다음 장(15 MCP & 외부 도구 연결)에서는 Claude Code가 파일과 터미널을 넘어 외부 서비스와 연결되는 방법을 다룹니다. 비용을 의식적으로 관리하면서 외부 도구까지 연결하면, 반복적인 복붙 작업이 대부분 사라집니다.

MCP & 외부 도구 연결

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

참고

15. Claude의 손이 닿는 곳을 넓혀보세요

Notion·Slack·Google Sheets·GitHub·DB. 연결 한 번으로 매번 하던 복붙이 사라집니다. 저는 처음 Notion MCP를 연결했을 때, 그동안 왜 그걸 손으로 옮겼을까 싶었습니다.

MCP를 한 줄로 설명하면

MCP(Model Context Protocol)는 Claude가 외부 도구·데이터 소스와 직접 대화할 수 있게 만드는 오픈 표준입니다. 기본 Claude Code는 내 컴퓨터의 파일과 터미널만 다룹니다. MCP를 끼우면 Notion 문서를 직접 읽고, Slack 메시지를 요약하고, Sheets를 업데이트하고, GitHub PR을 열 수 있습니다. 개발자라면 DB 쿼리, Sentry 에러 분석, CI 결과 확인까지 손이 닿습니다.

비유하자면 Claude에게 USB 포트를 달아주는 셈입니다. 기기를 꽂기만 하면 곧장 쓸 수 있고, 빼면 없던 것처럼 돌아갑니다. 포트 하나가 아니라 여러 개를 동시에 꽂을 수도 있고, 작업마다 필요한 것만 꽂아 쓸 수도 있습니다.

💡 한 번은 이런 일이 있었습니다. 강의 준비를 하면서 경쟁 서비스 5곳의 랜딩페이지를 비교하는 리서치가 필요했습니다. 전에는 각 사이트를 열고, 주요 카피를 복사하고, 스프레드시트에 붙여넣고, 항목별로 정리하는 작업을 한 시간 넘게 했습니다. Chrome MCP를 연결한 뒤에는 "이 5개 사이트를 방문해서 메인 카피, 가격, CTA 버튼 텍스트를 표로 정리해줘"라고 한 마디 했더니 5분 만에 끝났습니다. 그때 MCP가 단순한 편의 기능이 아니라 작업 방식 자체를 바꾼다는 걸 실감했습니다.

복붙 노가다가 사라지는 자리

MCP를 끼우기 전과 후를 짝지어 보면 차이가 분명해집니다.

업무·리서치 사용자가 흔히 마주치는 장면들

Notion 회의록 페이지를 일일이 복사 → "오늘 회의 Notion 페이지에 정리해줘" 한 마디로 끝
Google Sheets에 데이터 수동 입력 → "이 데이터를 Sheets에 정리해줘"
사이트 방문해 정보 복사·붙여넣기 → "이 5개 사이트 비교표 만들어줘"
Slack 스레드 복사해 요약 부탁 → "#마케팅 오늘 논의 요약하고 공지 초안 써줘"
이메일 내용 복사해 대응 초안 작성 → "이 이메일 스레드 읽고 답장 초안 써줘"

🖥️ 개발자용 노가다 해소 예시

JIRA 티켓 복붙 → "ENG-4521 구현해줘"
Sentry 스택트레이스 수동 복사 → "지난 24시간 주요 에러 분석"
DB 스키마 설명 후 쿼리 요청 → "users에서 90일 미접속 유저 찾아줘"
PR 내용 복사해 리뷰 부탁 → "PR #456 리뷰해줘"
CI 결과 확인 후 수동 정리 → "마지막 배포 이후 실패한 테스트 목록 보여줘"

어떤 일까지 가능한가: 다섯 갈래 예시

GitHub: PR·이슈를 직접 다루기

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

# 연결 후 가능해지는 요청들
> "PR #456 검토하고 개선점 제안해줘"
> "방금 발견한 버그를 새 이슈로 만들어줘"
> "나에게 할당된 오픈 PR 목록 보여줘"
> "이번 주 머지된 PR 중 가장 변경 규모가 큰 것 3개 보여줘"

처음 연결하고 나서 내가 멈췄던 건 "나에게 할당된 오픈 PR" 목록이었습니다. 그동안 GitHub 알림을 열고, 탭을 돌면서 보던 것이 터미널 안에서 한 줄로 정리돼 나왔을 때, 그제야 컨텍스트 전환 비용이 생각보다 컸다는 걸 알았습니다.

Sentry: 프로덕션 에러 분석

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

# /mcp로 인증 완료 후
> "지난 24시간 주요 에러는 뭐야?"
> "에러 ID abc123의 스택트레이스 보여줘"
> "이 에러들이 어느 배포에서 시작됐어?"
> "가장 많이 발생하는 에러 상위 5개 분석해줘"

PostgreSQL: DB 직접 쿼리

# 가능하면 읽기 전용 계정으로!
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

# 연결 후
> "이번 달 총 매출 얼마야?"
> "orders 테이블 스키마 보여줘"
> "90일째 구매 안 한 고객 찾아줘"
> "지난 7일 신규 가입자 중 구매까지 이어진 비율 계산해줘"

이 중에 매일 쓰는 건 스키마 확인과 비활성 사용자 분석입니다. 스키마는 개발 중에 반복적으로 필요하고, 비활성 사용자 분석은 마케팅 작업과 붙어 있습니다. 쿼리를 직접 짜지 않아도 자연어로 물어볼 수 있다는 게 핵심입니다.

Slack: 메시지 읽고 보내기

채널 맥락을 그대로 넘길 수 있습니다. 버그 리포트 스레드가 올라오면 그 흐름을 곧장 읽고 작업으로 이어집니다. "#마케팅 채널 오늘 논의에서 미해결 질문만 모아줘"도 됩니다.

Notion·Asana·Figma 등

공식 MCP 가이드에서 현재 사용 가능한 서버 목록과 연결 방법을 한눈에 확인할 수 있습니다. 서버 수가 계속 늘고 있어서 처음 연결할 때와 한 달 후에 다시 보면 새 서버가 추가돼 있는 경우가 많습니다.

설치: 네 가지 입구

원격 HTTP 서버

대부분의 공식 MCP는 이 방식.

입구 ① · 가장 흔한 길

로컬 stdio 서버

PC에 설치된 도구·DB와 직접 연결.

입구 ②

SSE 서버

실시간으로 결과가 흘러오는 케이스.

입구 ③ · 스트리밍

JSON으로 한 번에

여러 서버를 설정 파일로 한 번에 등록.

입구 ④

입구 ① · 원격 HTTP 서버 (가장 흔한 길)

대부분의 공식 MCP 서버가 이 방식입니다. URL만 있으면 됩니다.

# 기본 문법
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 서버

내 컴퓨터에서 프로세스가 직접 실행되는 형태입니다. 로컬 파일, 내부 DB, 자체 작성 스크립트와 연결할 때 씁니다.

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

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

처음에는 stdio 방식이 복잡해 보입니다. 익숙해지면 로컬 도구를 연결하는 가장 직접적인 방법이라는 걸 알게 됩니다.

입구 ③ · 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에 커밋해두면 팀원 모두 동일한 환경에서 시작할 수 있습니다. 처음 입사한 팀원이 git clone 하면 MCP 설정도 자동으로 따라옵니다. 스코프를 잘 분리해두면 "내 로컬에서는 되는데 팀원 환경에서는 안 돼요"가 줄어듭니다.

처음 써보는 분에게 권하는 세 가지

한두 개로 감을 잡으려면 다음 셋이 좋습니다.

권장 ㉠ · Notion MCP

claude mcp add --transport http notion https://mcp.notion.com/mcp

사라지는 일: 회의록·리서치 결과 수동 복사, 페이지 붙여넣기, DB 수동 업데이트.

실제로 쓸 수 있는 요청 예시:

"Notion '회의록' DB의 지난 7일 항목을 가져와 결정사항·액션아이템만 모아 weekly.md로 만들어줘"
"이 리서치 결과를 Notion '경쟁사 분석' 페이지에 추가해줘"
"Notion에서 담당자가 나인 태스크만 뽑아서 오늘 할 일 목록 만들어줘"

Notion MCP를 처음 썼을 때 가장 놀랐던 건 페이지 생성이었습니다. "미팅 결과를 정리해줘"라고 했더니 Notion 페이지가 직접 만들어졌습니다. 그전까지는 Claude가 텍스트를 만들어주면 그걸 복사해서 붙여넣는 2단계를 거쳤는데, 그 단계가 사라졌습니다.

권장 ㉡ · Slack MCP

claude.ai 계정으로 로그인한 뒤 claude.ai/settings/connectors에서 설정합니다.

사라지는 일: 채널 스레드 수동 읽기, 요약용 복붙, 공지 초안 직접 쓰기.

실제로 쓸 수 있는 요청 예시:

"#마케팅 채널 오늘 스레드를 읽고, 쟁점 3개와 합의된 다음 액션을 슬랙 공지 초안으로 만들어줘"
"#개발 채널에서 오늘 언급된 버그 보고들만 모아줘"
"지난 주 내가 받은 DM 중 답장 못 한 것들 정리해줘"

권장 ㉢ · Google Chrome (웹 리서치)

같은 커넥터 페이지에서 켜면 됩니다.

사라지는 일: 사이트 방문해 정보 수동 복사, 여러 곳 비교를 위한 탭 전환.

실제로 쓸 수 있는 요청 예시:

"경쟁사 5곳을 훑고, 오늘의 주요 변화·새 기능·가격 변경만 표로 정리해줘"
"이 상품 리뷰 20개를 읽고 반복되는 불만 사항 3가지로 정리해줘"
"이 블로그 포스트 10개의 공통 주제와 각자 독특한 관점을 비교해줘"

🖥️ 개발자 권장 셋 (GitHub · PostgreSQL · Sentry)

GitHub MCP

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

PR 복붙·이슈 수동 조회·리뷰 컨텍스트 전달이 같이 사라집니다.

이 중에 매일 쓰는 건 PR 리뷰입니다. 브라우저를 열지 않고도 터미널 안에서 "PR #123 코드 검토해줘"가 되면, 컨텍스트 전환 비용이 사라집니다. PR 댓글을 남기는 것도 Claude에게 시킬 수 있습니다.

PostgreSQL · DB MCP

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

스키마 설명·쿼리 결과 복붙·SQL 수동 실행을 줄입니다.

읽기 전용 계정을 따로 만드는 걸 강하게 권합니다. 분석·리포트 작업에는 쓰기 권한이 불필요합니다. 실수 하나로 데이터가 날아가는 것보다 처음부터 제한하는 편이 훨씬 낫습니다.

Sentry MCP

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

스택트레이스 복붙·에러 발생 시점 수동 조회를 줄입니다. 인증은 /mcp로 하면 브라우저가 열리고 자동으로 완료됩니다.

공식 커넥터: 클릭 한 번으로

claude.ai 계정으로 로그인한 환경이라면 claude.ai/settings/connectors에서 켠 서버가 Claude Code에 자동으로 따라옵니다. 현재 공식 지원 커넥터:

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

두 가지 모두 클릭 몇 번으로 켤 수 있습니다. 처음 MCP를 써보는 분이라면, 커맨드 없이 바로 쓸 수 있는 이 둘이 진입장벽이 가장 낮은 선택입니다.

OAuth가 필요한 서버: 두 박자

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

# 박자 ① — 서버 추가
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 박자 ② — Claude Code 안에서 인증
> /mcp

# 브라우저가 열리고 → 로그인 → 자동 완료

토큰은 자동으로 저장·갱신됩니다. 한 번 인증하면 다음에 다시 할 필요가 없습니다. 토큰이 만료되면 Claude가 재인증이 필요하다고 알려줍니다.

MCP 프롬프트를 직접 명령으로

MCP 서버가 프롬프트 템플릿을 제공하면 /mcp__서버명__프롬프트명 형식으로 바로 실행됩니다.

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

자주 쓰는 MCP 명령이 있다면 이 형식을 기억해두면 편합니다. 매번 자연어로 설명하는 것보다 훨씬 빠르게 동일한 작업을 실행할 수 있습니다.

처음 연결할 때 자주 막히는 지점들

MCP를 처음 설치할 때 막히는 포인트들이 있습니다. 미리 알고 가면 덜 당황합니다.

OAuth 인증이 안 끝나는 경우: /mcp를 입력하면 브라우저가 열려야 합니다. 팝업 차단이 되어 있으면 열리지 않습니다. 브라우저 팝업 차단 설정을 확인하세요.

stdio 서버가 바로 꺼지는 경우: 커맨드가 실행 가능한지 확인하세요. npx -y @some/package는 처음 실행 시 설치가 필요해서 잠깐 느릴 수 있습니다. 인터넷 연결 상태를 확인하세요.

claude mcp list에 서버가 안 나오는 경우: --scope를 지정했다면 지정한 스코프로 등록됐습니다. 기본값은 local이니 claude mcp list가 현재 프로젝트 디렉터리에서 실행됐는지 확인하세요.

💡 한 번은 이런 일이 있었습니다. WSL2 환경에서 GitHub MCP를 연결하려다 OAuth 인증 단계에서 막혔습니다. /mcp를 입력했더니 브라우저가 열렸는데, WSL2에서 열린 Windows 브라우저와 인증 콜백이 제대로 연결되지 않았습니다. 해결은 간단했습니다 — WSL2 환경에서는 wslview 또는 xdg-open이 기본 브라우저 핸들러로 설정되어야 합니다. export BROWSER=wslview를 .bashrc에 추가하고 나서 인증이 정상적으로 됐습니다. WSL2 사용자라면 미리 알아두면 좋은 포인트입니다.

⚠️ 안전: MCP를 설치하기 전 확인할 것들

신뢰할 수 없는 서버는 함부로 설치하지 마세요. MCP 서버는 Claude를 통해 내 파일·DB·외부 서비스에 접근할 수 있습니다. 외부 콘텐츠를 가져오는 서버는 프롬프트 인젝션 위험도 있습니다.

설치 전 다음 체크리스트로 한 번 거르세요:

□ 공식 제공 서버인가? 아니면 신뢰할 만한 조직이 관리하나?
□ GitHub 저장소의 최근 커밋이 너무 오래되지 않았나?
□ README에 필요한 권한·데이터 접근 범위가 설명되어 있나?
□ 토큰·키를 어디에 저장하는지 명확한가?
□ DB 연결은 읽기 전용 계정을 쓸 수 있나?
□ 팀 프로젝트라면 .mcp.json 커밋 전 팀원에게 공유했나?

DB MCP는 가능한 한 읽기 전용 계정을 따로 만들기를 권합니다. 분석·리포트 용도엔 쓰기 권한이 필요한 경우가 드뭅니다.

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

💡 한 번은 이런 일이 있었습니다. 커뮤니티에서 공유된 MCP 서버를 아무 확인 없이 설치했다가, 해당 서버가 내 ~/.claude.json을 읽을 수 있는 권한을 요청한다는 걸 나중에 알게 됐습니다. 그 이후부터는 서버 소스코드를 직접 보거나, 최소한 GitHub 스타 수와 최근 커밋 날짜를 확인한 뒤 설치합니다. 공식 MCP 서버 레지스트리에 등록된 것을 먼저 쓰는 게 가장 안전합니다.

연결하고 나서 처음 쓸 때: 감을 잡는 3단계

MCP를 처음 연결하고 나서 어디서 시작해야 할지 막막할 수 있습니다. 다음 순서로 감을 잡아가면 편합니다.

1단계 — 간단한 읽기부터: "Notion에서 오늘 업데이트된 페이지 목록 보여줘" 같은 읽기 전용 요청으로 시작합니다. 연결이 제대로 됐는지 확인하는 단계입니다.

2단계 — 요약·분석 요청: "이 주의 Slack 메시지 중 액션아이템을 뽑아줘" 같은 분석 요청으로 MCP의 진짜 가치를 경험합니다.

3단계 — 쓰기 요청: 충분히 익숙해진 뒤 "이 내용을 Notion 페이지로 만들어줘" 같은 쓰기 요청을 시도합니다. 쓰기는 되돌리기 어려울 수 있으니 중요한 데이터에는 신중하게 접근하세요.

실전 워크플로우: 일주일 써보니 달라진 것들

처음 MCP를 연결하고 일주일이 지나면 달라지는 것들이 있습니다. 직접 겪어본 변화들입니다.

회의가 끝난 직후

전에는 회의가 끝나면 30분 정도 회의록을 정리하는 시간이 필요했습니다. 메모 앱을 열고, 회의에서 나온 결정사항을 추려내고, Notion 템플릿에 맞게 붙여넣고, 담당자별 액션아이템을 분리하는 과정이었습니다.

Notion MCP를 연결한 뒤로는:

> 방금 회의 노트를 보여줄게. 아래 내용으로 Notion '회의록' 데이터베이스에
  오늘 날짜로 새 항목을 만들어줘.
  - 결정사항만 추려서 '결정사항' 필드에
  - 담당자별 할 일은 '액션아이템' 필드에
  - 다음 회의 날짜가 언급됐으면 '다음 회의' 필드에

[회의 노트 내용]

5분도 안 걸립니다. 회의록 작성 시간이 아니라 회의 내용 검토 시간이 됐습니다.

경쟁사 모니터링

매주 월요일 아침에 경쟁사 동향을 확인하는 루틴이 있었습니다. 각 경쟁사 블로그, 트위터, 채용공고를 돌면서 변화를 파악하는 작업이었습니다. 보통 한 시간 정도 걸렸습니다.

Chrome MCP를 연결한 뒤로는:

> 다음 5개 사이트를 방문해서 지난 7일 이내 변화를 정리해줘:
  1. [경쟁사A 블로그]
  2. [경쟁사B 공지]
  3. [경쟁사C 채용]
  4. [경쟁사D 제품 페이지]
  5. [경쟁사E 가격 페이지]

  각 사이트별로: 새로운 기능, 가격 변화, 채용 동향이 있으면 정리해줘.
  없으면 "변화 없음"으로.

15분이면 됩니다. 그 시간에 이미 파악한 내용을 어떻게 대응할지 생각할 수 있습니다.

Slack 스레드 처리

팀 채널에 하루에도 수십 개의 스레드가 올라옵니다. 퇴근 전에 모두 처리하기 어렵습니다.

Slack MCP를 연결한 뒤로는:

> 오늘 #general과 #dev 채널에서 내가 멘션된 메시지들을 모아서
  긴급도(오늘 중/이번 주/참고용)로 분류해줘.
  각 항목에 대해 필요한 액션이 뭔지도 한 줄로.

15분짜리 채널 확인이 3분으로 줄었습니다.

MCP를 여러 개 함께 쓸 때

MCP는 하나만 연결하는 것보다 여러 개를 함께 쓸 때 더 강력해집니다.

예시: Slack + Notion + GitHub를 동시에 연결한 상태

> #dev 채널에서 오늘 올라온 버그 보고를 읽고:
  1. GitHub에 각 버그를 이슈로 등록해줘 (우선순위: high)
  2. Notion '버그 트래커' 데이터베이스에도 동일한 내용으로 항목 추가해줘
  3. #dev 채널에 "버그 보고 접수 완료, 이슈 번호: [번호들]" 로 답장해줘

이런 종류의 워크플로우를 MCP 없이 수동으로 했다면 30분 이상 걸렸을 것입니다. 세 서비스를 오가며 복붙하는 작업이었을 테니까요. MCP를 연결하면 이게 한 번의 요청으로 끝납니다.

여러 서버를 함께 쓸 때 한 가지 유의할 점이 있습니다. 각 서버의 응답이 컨텍스트에 쌓입니다. 많은 데이터를 가져오는 요청을 연달아 하면 토큰이 빠르게 찰 수 있습니다. Statusline 토큰 항목을 보면서 작업하세요.

MCP 서버를 직접 만들 수도 있습니다

공식 MCP 서버 목록에 원하는 도구가 없다면 직접 만들 수 있습니다. Anthropic이 공개한 MCP SDK를 사용하면 파이썬이나 TypeScript로 서버를 작성할 수 있습니다.

직접 만드는 경우는 주로 이럴 때입니다:

사내 전용 시스템(ERP, 그룹웨어 등)을 Claude와 연결하고 싶을 때
기존 공개 서버의 기능이 부족해서 확장하고 싶을 때
팀 고유의 워크플로우를 자동화하고 싶을 때

입문자라면 커스텀 MCP 서버보다 기존 서버로 먼저 감을 잡는 것을 권합니다. 기존 서버를 쓰면서 "이 기능이 있었으면 좋겠다"는 포인트가 생겼을 때 직접 만들기를 시도하면 방향이 명확해집니다.

MCP를 쓰기 전 필요한 것들

MCP를 처음 설정하기 전에 확인할 사항들입니다.

Node.js가 설치되어 있어야 합니다

stdio 방식의 MCP 서버는 npx 커맨드로 실행됩니다. Node.js가 설치되어 있어야 합니다.

node --version  # v18 이상 권장
npm --version

설치가 안 되어 있다면 nodejs.org에서 LTS 버전을 설치하세요. WSL2 환경이라면 nvm을 사용하는 것을 권합니다.

# nvm으로 설치하는 경우
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts
nvm use --lts

Python도 있으면 좋습니다

일부 stdio 서버는 Python으로 작성돼 있습니다. Python 3.10 이상이면 대부분 커버됩니다.

python3 --version

API 키 준비

Notion, Airtable 등 일부 서버는 API 키가 필요합니다. 해당 서비스의 개발자 설정에서 발급하면 됩니다. API 키는 환경변수로 전달하거나 --env 옵션으로 지정합니다.

# 예시: Airtable API 키 설정
claude mcp add --transport stdio --env AIRTABLE_API_KEY=pat_xxxx airtable \
  -- npx -y airtable-mcp-server

실용 요청 모음: 바로 쓸 수 있는 프롬프트들

MCP를 연결하고 나서 바로 써볼 수 있는 요청들입니다. 복사해서 상황에 맞게 수정하면 됩니다.

Notion MCP 연결 후

[일일 요약]
Notion '작업 현황' 데이터베이스에서 오늘 업데이트된 항목들을 가져와서
완료된 것 / 진행 중 / 차단된 것으로 분류해줘.

[주간 보고]
Notion '회의록' DB의 이번 주 항목들을 읽고
결정사항과 액션아이템만 모아서 주간 요약 문서 만들어줘.

[태스크 생성]
이 요구사항으로 Notion '스프린트' 데이터베이스에
담당자를 '이국환', 우선순위를 'High'로 설정해서 새 태스크를 추가해줘.

Slack MCP 연결 후

[채널 요약]
#프로덕트 채널 오늘 대화를 읽고
결정사항, 미해결 질문, 다음 액션 세 가지로 요약해줘.

[멘션 처리]
오늘 내가 멘션된 메시지를 모두 가져와서
답장이 필요한 것과 그냥 참고용을 구분해줘.

[공지 초안]
오늘 팀 회의에서 결정된 내용을 바탕으로
#general 채널에 올릴 공지 초안을 작성해줘.

Chrome MCP 연결 후

[리서치]
다음 3개 사이트에서 '가격' 페이지를 방문해서
요금제 이름, 월 가격, 포함된 주요 기능을 표로 비교해줘.

[모니터링]
이 뉴스 사이트 5곳의 메인 페이지를 읽고
오늘 가장 많이 언급된 토픽 3개를 정리해줘.

자주 하는 실수

처음 MCP를 쓰면서 자주 만나는 실수들입니다.

실수	결과	대신
너무 많은 서버를 한 번에 등록	뭐가 어디에 있는지 헷갈림	하나씩, 쓰면서 늘리기
쓰기 권한 있는 계정으로 DB 연결	실수로 데이터 변경 위험	읽기 전용 계정 사용
OAuth 인증 없이 요청	"인증이 필요합니다" 에러	`/mcp`로 먼저 인증
서버 스코프 혼동	팀 공유가 안 되거나 다른 프로젝트에 영향	`claude mcp list`로 확인
신뢰 불분명한 서버 설치	내 데이터 보안 위험	공식 레지스트리 먼저

MCP를 팀에 도입할 때

개인으로 쓰는 것과 팀으로 쓰는 것은 다릅니다. 팀에 도입할 때 미리 알면 좋은 것들을 정리했습니다.

.mcp.json 파일로 팀 설정 공유

팀 프로젝트에서 MCP를 쓴다면 설정을 .mcp.json으로 관리하고 Git에 커밋하세요. 팀원이 새로 합류하면 클론 후 자동으로 동일한 환경을 갖게 됩니다.

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

이 파일은 프로젝트 루트에 두고 Git에 커밋합니다. 개인 API 키는 이 파일에 넣지 말고 환경변수로 관리하세요. .mcp.json에 시크릿이 노출되면 Git 히스토리에 남습니다.

팀원이 처음 쓸 때 확인 절차

프로젝트 스코프 MCP 서버는 팀원이 처음 열 때 "이 프로젝트에서 다음 MCP 서버를 사용합니다. 허용하시겠습니까"라는 확인을 표시합니다. 이것은 의도적인 보안 안전장치입니다. 허용하면 이후에는 표시되지 않습니다.

API 키 관리

팀 환경에서 API 키를 어떻게 관리할지 미리 합의하세요. 개인 키를 쓸지, 팀 공용 키를 만들지, 키를 어디에 저장할지.

작은 팀이라면 각자 개인 키를 쓰는 것이 가장 간단합니다. 환경변수로 전달하면 코드에 노출되지 않습니다.

비개발자를 위한 MCP 시작 가이드

개발자가 아닌 분들이 MCP를 처음 접하면 "이게 나한테도 필요한가"라는 의문이 드는 경우가 있습니다. 대답은 "Notion이나 Slack을 쓰고 있다면 지금 당장 써볼 수 있다"입니다.

설치할 것도 없습니다. claude.ai/settings/connectors에서 Slack 또는 Chrome을 클릭 몇 번으로 켜면 됩니다. 커맨드 라인은 전혀 몰라도 됩니다.

첫 번째 요청으로 추천하는 것: "오늘 팀채널에 올라온 메시지들을 읽고, 오늘 중으로 내가 답해야 할 것들을 목록으로 만들어줘."

이것 하나만 해도 MCP가 어떤 가치를 주는지 바로 이해가 됩니다.

클릭 몇 번으로 설정이 끝나고, 자연어로 요청을 보내면 됩니다. 전용 앱이나 웹사이트를 따로 열지 않아도 됩니다. Slack 탭을 열었다가 Claude로 돌아오는 맥락 전환이 사라집니다. 이 작은 변화가 하루에 수십 번 반복되면, 누적 시간 차이가 생각보다 크게 납니다.

MCP를 처음 쓰는 분이 가장 놀라는 지점은 생각보다 간단하다는 것입니다. 복잡한 설정 없이, 클릭 한 번에 연결되는 서버부터 시작해서 서서히 확장해 나가면 됩니다. 처음부터 모든 도구를 다 연결하려 하지 않아도 됩니다. 지금 반복적으로 손이 가는 작업 하나를 고르고, 그 작업에 맞는 서버를 하나 연결하는 것으로 충분합니다.

한 달 뒤에도 계속 쓰게 만드는 패턴

MCP를 처음 연결하고 며칠 신나게 쓰다가 어느 순간 그냥 안 쓰게 되는 경우가 있습니다. 이런 패턴이 생기면 꾸준히 쓰기 어렵습니다:

매번 똑같은 프롬프트를 손으로 입력해야 한다
MCP를 쓰는 것이 직접 하는 것보다 더 오래 걸린다고 느껴진다
어떤 도구가 연결되어 있는지 잊어버린다

이 패턴을 끊는 가장 좋은 방법은 16번 섹션에서 다룰 Skills와 조합하는 것입니다. 자주 쓰는 MCP 요청을 Skills로 저장해두면 /weekly-report처럼 한 줄로 꺼내 쓸 수 있습니다.

그전에 간단하게 할 수 있는 것: CLAUDE.md에 자주 쓰는 MCP 요청을 메모로 남겨두기.

# 자주 쓰는 MCP 요청

## Notion
- 오늘 회의록 → DB에 정리: "Notion '회의록' DB에 오늘 날짜로 새 항목을 만들어줘."
- 주간 요약 → Notion에서 가져오기: "이번 주 회의록 항목들을 읽고 결정사항만 모아줘."

## Slack
- 오늘 멘션 확인: "오늘 내가 멘션된 메시지를 답장 필요/참고용으로 분류해줘."
- 채널 요약: "#채널명 오늘 대화 요약해줘."

## Chrome
- 경쟁사 변화 파악: "경쟁사A/B/C 블로그에서 최근 7일 변화 정리해줘."

이 메모를 CLAUDE.md에 두면, 세션을 시작할 때마다 Claude가 어떤 MCP가 쓸 수 있는지 알고 있는 상태가 됩니다.

MCP가 바꾸는 것: 도구를 쓰는 방식이 아니라 도구를 인식하는 방식

MCP를 몇 주 써보고 나서 깨달은 게 있습니다. 바뀌는 건 작업 속도만이 아닙니다. 문제를 바라보는 방식이 바뀝니다.

예전에는 Slack에 어떤 메시지가 왔는지 확인하려면 Slack을 열어야 했습니다. GitHub에 어떤 PR이 열려 있는지 보려면 GitHub 탭을 열어야 했습니다. Notion에 무언가를 정리하려면 Notion으로 전환해야 했습니다.

MCP가 연결된 뒤로는 이 모든 것이 "터미널에서 물어보는 것"으로 바뀌었습니다. 맥락 전환이 줄어들고, 작업 흐름이 끊기지 않습니다.

더 중요한 변화는 반복 작업을 마주할 때 자동으로 연결 가능성을 떠올리게 된다는 것입니다. 전에는 당연히 직접 해야 한다고 생각했던 것들이 MCP 연결 하나로 바뀌는 걸 경험하면, 이후에도 비슷한 기회를 찾게 됩니다. 그게 MCP가 주는 가장 큰 변화입니다.

처음 연결 후 2주가 분기점입니다

경험상 MCP를 처음 쓰고 2주가 중요합니다. 처음 일주일은 신기해서 열심히 씁니다. 두 번째 주에 "익숙해졌다"는 이유로 다시 직접 하는 패턴으로 돌아가는 경우가 많습니다.

두 번째 주에도 계속 쓰게 만드는 포인트는 딱 하나입니다. 반복이 보이면 바로 요청으로 만들기. "아, 이거 지난 주에도 했는데" 하는 순간에 그 요청을 CLAUDE.md에 적어두거나 Skills로 저장하면, 그 이후로는 자연스럽게 계속 씁니다. 한 번 저장해둔 워크플로우는 매번 생각할 필요가 없어지니까요.

한 줄로

MCP가 "외부 세계와 연결"이라면, 아직 연결되지 않은 도구들이 내 작업 흐름에 얼마나 많은지 돌아보게 됩니다. 처음 한 개를 연결하면 다음이 보이기 시작합니다.

이 장을 덮기 전에

Notion, Slack, Chrome 중 하나를 골라서 직접 MCP를 연결해봤다
claude mcp list를 실행해서 등록된 서버 목록을 확인해봤다
연결한 서버로 실제 읽기 요청 한 가지를 직접 해봤다
DB MCP를 쓸 계획이라면 읽기 전용 계정을 따로 만들었다

다음 장(16 Hooks: 자동화의 핵심)에서는 MCP가 "외부 세계와 연결"이었다면, Hooks는 "Claude Code 자체 동작을 제어"하는 방법을 다룹니다. 위험한 명령을 실행 직전에 막고, 작업이 끝나면 자동으로 알림을 받는 것들이 여기서 나옵니다.

Hooks: 자동화의 핵심

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

참고

16. Hooks: Claude가 실수하기 전에 먼저 잡아두는 장치

AI가 rm -rf를 실행하거나 git push --force로 히스토리를 날리면? Hooks가 그 사고를 실행 직전에 막아 세웁니다. LLM의 판단이 아니라 코드로 100% 차단하는 장치입니다.

Claude Code 공식 Hooks 페이지의 Hook lifecycle 섹션 출처: Hooks — Anthropic 공식 문서

Hooks를 쓰기 전에 있었던 일

바이브코딩을 하다 보면 Claude에게 "알아서 잘 해줘"라고 넓게 맡기는 순간이 옵니다. 대부분은 잘 됩니다. 그런데 가끔, 정말 가끔, 생각지 못한 일이 일어납니다.

rm -rf 한 방에 프로젝트 폴더가 사라짐
git reset --hard로 미커밋 작업이 통째로 증발
git push --force로 팀원 코드가 덮어씌워짐
DROP TABLE로 데이터베이스가 날아감

이 사고가 한 번이라도 닥치면 그날의 작업이 아니라 며칠치 작업이 통째로 날아갑니다. Claude가 나쁜 의도로 한 게 아닙니다. "이게 맞겠지"라고 추론한 것이 틀렸을 뿐입니다. 그런데 그 한 번이 치명적입니다.

Hooks는 이런 위험 명령을 실행 직전에 코드로 가로챕니다. AI의 판단도, 사람의 판단도 아닌: 그저 패턴이 매치되면 멈추는 단순한 안전벨트입니다. 패턴은 변하지 않습니다. 작업이 신날 때도 똑같이 멈춥니다.

Hook이 뭐 하는 건가요

Hook은 Claude Code의 특정 이벤트가 발생할 때 자동으로 실행되는 셸 커맨드입니다. 공식 Hooks 페이지에는 20여 개의 이벤트가 정의돼 있습니다. 입문자 입장에서 알아둘 것은 다음 10개 정도입니다.

PreToolUse: 도구 실행 직전 (위험 명령 차단)
PostToolUse: 도구 실행 직후 (자동 포매팅·로그)
Stop: Claude가 응답 완료 시 (완료 알림)
Notification: Claude가 알림 보낼 때 (데스크톱 알림)
SessionStart: 세션 시작·재개 시 (컨텍스트 주입)
SessionEnd: 세션 종료 시 (정리·사용량 기록)
UserPromptSubmit: 프롬프트 제출 시 (입력 전처리)
PreCompact: 컨텍스트 압축 전 (중요 정보 보존)
SubagentStart: 서브에이전트 시작 (위임 로그·예산 체크)
SubagentStop: 서브에이전트 종료 (결과 검증·요약)
WorktreeCreate: Worktree가 생성될 때 (--worktree 또는 isolation: "worktree"). 기본 git 동작을 대체 가능
WorktreeRemove: Worktree가 제거될 때 (세션 종료 또는 서브에이전트 완료 시)

ℹ️ 이벤트 카덴스: 세션당 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 파일을 만듭니다

실행 권한 부여

chmod +x 로 스크립트에 실행 권한을 부여합니다

settings에 등록

~/.claude/settings.json 의 hooks 섹션에 연결합니다

단계 ① · 스크립트 파일 만들기

~/.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`가 들어왔을 때

PreToolUse 이벤트 → block_dangerous.py 실행
명령어가 rm 패턴에 매치
exit 2로 차단 + "rm 대신 trash를 사용하세요" 메시지 전달
Claude가 메시지를 받고 trash node_modules로 대안 실행

💡 trash는 파일을 휴지통으로 보내 실수해도 복구할 수 있습니다. macOS는 brew install trash, 그 외 OS는 npm install -g trash-cli로 설치하세요.

💡 한 번은 이런 일이 있었습니다. 강의 중 빌드 최적화 작업을 하다가 Claude가 node_modules를 지우고 다시 설치하려는 계획을 세웠습니다. rm -rf node_modules && npm install이 계획에 들어 있었습니다. Safety Hook이 없었다면 그냥 실행됐을 텐데, Hook이 rm 패턴을 잡아서 멈췄습니다. Claude에게 "trash를 써줘"라고 안내가 갔고, trash node_modules && npm install로 실행됐습니다. 차이는 복구 가능 여부입니다. rm으로 지우면 돌아올 수 없고, trash로 보내면 실수했을 때 꺼낼 수 있습니다.

차단 패턴 추가: 입맛 따라 늘리기

BLOCKED_PATTERNS 리스트에 줄만 추가하면 됩니다.

# 예시: chmod 777 차단
(r"chmod\s+777", "chmod 777은 보안상 위험합니다"),

# 예시: 프로덕션 SSH 접속 차단
(r"ssh\s+.*prod", "프로덕션 서버 접근이 차단되었습니다"),

# 예시: 특정 환경변수 노출 차단
(r"echo\s+\$\w*TOKEN", "토큰을 터미널에 출력하지 마세요"),

# 예시: 직접 프로덕션 DB 접근 차단
(r"psql.*prod\.db\.com", "프로덕션 DB 직접 접근은 차단됩니다. staging을 쓰세요"),

패턴은 Python 정규표현식입니다. 막고 싶은 것이 생길 때마다 한 줄씩 추가하는 방식으로 관리하면 됩니다.

첫 Hook ㉡: 완료 알림

Claude의 응답이 끝나는 순간을 소리로 알려줍니다. 긴 작업을 Claude에게 맡기고 다른 일을 하다가 "끝났나?"를 계속 확인하는 게 아니라, 소리로 바로 알 수 있습니다.

💡 한 번은 이런 일이 있었습니다. 컨텍스트 분석 작업을 Claude에게 맡기고 다른 창을 보다가 5분 뒤에 "아, 끝났나?"라고 돌아온 적이 여러 번 있었습니다. 그 5분 동안 Claude는 이미 결과를 내놓고 기다리고 있었습니다. 완료 알림 Hook을 단 뒤로는 소리가 나는 순간 돌아옵니다. 대기 시간이 줄었습니다.

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' '작업이 완료되었습니다'"
}

WSL2 (Windows Subsystem for Linux) 알림

WSL2 환경이라면 PowerShell을 통해 Windows 알림을 띄울 수 있습니다.

{
  "type": "command",
  "command": "powershell.exe -Command \"New-BurntToastNotification -Text 'Claude Code', '작업이 완료되었습니다'\""
}

BurntToast 모듈이 없다면 PowerShell에서 아래 명령으로 설치합니다: Install-Module -Name BurntToast

두 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 커맨드로 등록 결과를 확인할 수 있습니다.

한 단계 더: 추가 Hook 활용 예시

민감 폴더 보호

customers/, invoices/ 같은 폴더를 Claude가 못 만지게 차단:

{
  "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"
          }
        ]
      }
    ]
  }
}

세션을 시작할 때마다 업무 규칙 파일을 자동으로 Claude의 컨텍스트에 넣어줍니다. 매번 "우리 팀 규칙은..." 하고 설명할 필요가 없어집니다.

프롬프트 기반 Hook

판단이 필요한 상황에는 type: "prompt" Hook이 잘 맞습니다.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "모든 태스크가 완료되었는지 확인하세요. 미완료 항목이 있으면 계속 작업하세요."
          }
        ]
      }
    ]
  }
}

HTTP Hook: 외부 검증 서비스 호출

명령 실행 대신 HTTP 엔드포인트로 이벤트를 보낼 수도 있습니다. 사내 보안 검증 서버나 감사 로그 수집기에 유용합니다.

{
  "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"]
          }
        ]
      }
    ]
  }
}

allowedEnvVars는 헤더·URL에 보간할 환경변수를 명시적으로 허용하는 안전장치입니다.

PostToolUse Hook: 파일 수정 후 자동 포매팅

Python 파일이 수정될 때마다 자동으로 lint를 실행합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "FILE=$(echo '$JSON' | python3 -c \"import json,sys; print(json.load(sys.stdin).get('tool_input',{}).get('file_path',''))\"); if [[ \"$FILE\" == *.py ]]; then python3 -m black \"$FILE\" 2>/dev/null; fi"
          }
        ]
      }
    ]
  }
}

SessionEnd Hook: 비용 기록

세션이 끝날 때마다 사용량을 로그로 남깁니다.

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date): session ended\" >> ~/.claude/session-log.txt"
          }
        ]
      }
    ]
  }
}

Hook이 차단할 때 Claude는 어떻게 반응하나요

Hook이 exit 2로 차단하고 stderr에 메시지를 보내면, Claude는 그 메시지를 받아서 다른 방법을 시도합니다. 이것이 Hooks의 핵심 동작입니다. 단순히 막는 게 아니라, 올바른 방향으로 유도하는 것입니다.

예시 흐름을 보면:

저는 "이 임시 파일들 전부 지워줘"라고 요청합니다. Claude가 rm -rf /tmp/cache/ 실행을 시도합니다. Safety Hook이 rm 패턴을 감지해서 exit 2로 차단하고 "rm 대신 trash를 사용하세요"를 stderr로 출력합니다. Claude는 그 메시지를 받아서 "죄송합니다, rm이 차단됐습니다. trash를 사용할게요"라고 하고, trash /tmp/cache/를 실행합니다.

Claude는 차단됐다고 포기하지 않습니다. 제공된 대안 메시지를 보고 다른 방법으로 재시도합니다. 그래서 대안이 담긴 구체적인 에러 메시지가 중요합니다.

이 동작은 Hook이 단순한 방화벽이 아니라 코칭 도구라는 걸 보여줍니다. "이건 안 돼. 저걸 써"라고 알려주는 것입니다.

Hooks를 점진적으로 도입하는 방법

처음부터 완벽한 Hooks 세트를 만들려다 지치는 경우가 있습니다. 다음 접근이 더 실용적입니다.

첫 번째 주에는 완료 알림만 설정합니다. 완료 알림 Hook 하나만으로 바로 가치를 얻고, Hook이 어떻게 동작하는지 감을 잡습니다. 리스크가 없어서 실수해도 소리가 안 나는 것뿐입니다.

두 번째 주에는 Safety Hook 최소 버전을 추가합니다. rm, git reset --hard, git push --force 세 가지만 차단하는 것부터 시작합니다. 패턴 세 개는 파악하기 쉬워서 문제가 생겨도 바로 확인할 수 있습니다.

세 번째와 네 번째 주에는 실제 경험 기반으로 확장합니다. 직접 쓰면서 "이게 막혔으면 좋았을 텐데" 하는 순간을 기억해뒀다가 패턴을 추가합니다. 미리 상상하는 것보다 실제 경험에서 나온 패턴이 훨씬 유효합니다.

한 달 후에는 팀과 공유합니다. 충분히 검증된 Hook 설정을 .claude/settings.json에 넣고 팀과 공유합니다. 팀원들의 경험에서 나온 패턴을 추가로 받아서 더 강화합니다. 이 흐름대로 한 달 뒤에는 팀 전체가 충분히 검증된 안전망을 갖게 됩니다.

Hooks가 없어도 Claude Code는 작동합니다

Hooks는 선택입니다. 없어도 Claude Code는 완전히 작동합니다. 하지만 한 번이라도 예상치 못한 파일 삭제나 강제 푸시 사고를 경험하면, Hook에 투자한 30분이 그 고통보다 훨씬 가볍다는 걸 알게 됩니다.

입문 단계에서는 Safety Hook과 완료 알림 두 가지만으로도 충분합니다. 코딩을 모르는 분도 이 두 가지는 설정할 수 있습니다. 파이썬 스크립트를 직접 이해하지 않아도 됩니다. 그냥 복사해서 붙여넣으면 작동합니다.

Hooks 개발에서 자주 만나는 네 가지 문제

Hook이 실행되지 않을 때 → /hooks에서 이벤트 이름 확인, matcher 대소문자 점검. Bash는 대문자 B.
스크립트가 실행되지 않을 때 → chmod +x로 실행 권한 부여했는지 확인. ls -la ~/.claude/hooks/로 권한 상태 확인.
JSON 파싱 오류 → ~/.zshrc나 ~/.bashrc에 echo 구문이 있으면 인터랙티브 셸 조건부로 감싸기. Hook은 비인터랙티브 셸로 실행됩니다.
모든 파일 수정이 차단될 때 → PreToolUse Hook의 exit 2 조건을 다시 확인. 너무 넓은 패턴이 의도치 않은 것까지 막고 있을 수 있습니다.

디버깅: claude --debug 또는 Ctrl+O로 Hook 실행 로그를 살펴보세요.

💡 한 번은 이런 일이 있었습니다. Safety Hook을 설정하고 나서 모든 파일 편집이 차단됐습니다. 패닉 상태로 /hooks를 열어봤더니 Edit|Write matcher에 쓴 정규식이 잘못돼서 모든 도구 호출에 매치되고 있었습니다. 실수로 파이프(|)를 OR 연산자로 알고 썼는데, matcher 문자열 안에서는 리터럴 파이프로 처리됩니다. 즉 Edit|Write가 'Edit 또는 Write'로 동작하지 않았습니다. 이런 상황에서는 claude --debug로 어떤 Hook이 어떤 이유로 실행되고 있는지 로그를 확인하면 빠르게 원인을 찾을 수 있습니다.

Hook을 처음 만들 때 권장 순서

처음부터 복잡한 Hook을 만들 필요는 없습니다. 다음 순서로 단계별로 늘려가는 방식이 안전합니다.

1단계 — 완료 알림부터: 아무 리스크 없이 바로 가치를 얻을 수 있습니다. 잘못되도 소리가 안 나는 것뿐입니다.

2단계 — Safety Hook 최소 버전: rm, git reset --hard, git push --force 세 가지만 차단합니다. 패턴 3개는 관리하기 쉽습니다.

3단계 — Safety Hook 확장: 실제로 아찔했던 명령이 있으면 그때 추가합니다. "어떤 패턴을 막아야 하나"를 쓰면서 배우는 게 읽으면서 배우는 것보다 훨씬 빠릅니다.

4단계 — 자동화 Hook: 세션 시작 컨텍스트 주입, PostToolUse 포매팅 등을 필요가 생겼을 때 추가합니다.

Hooks를 팀에 배포할 때

개인 Hook은 ~/.claude/settings.json에 두고, 팀 공통 Hook은 .claude/settings.json에 두고 Git으로 관리합니다.

팀에 Hook을 배포할 때 주의할 점:

Hook 스크립트 파일(.py, .sh)도 함께 커밋하거나, 스크립트 내용을 settings.json에 인라인으로 넣어야 합니다
팀원마다 Python/Node 환경이 다를 수 있습니다. 스크립트 첫 줄에 인터프리터 경로를 명시하세요
chmod +x는 커밋 전에 완료해야 합니다. Git은 실행 권한 비트도 추적합니다

# 실행 권한 포함해 커밋하기
chmod +x .claude/hooks/block_dangerous.py
git add .claude/hooks/block_dangerous.py
git commit -m "chore: add safety hook for dangerous commands"

Hooks 실전 활용 패턴: 더 깊이 써보기

기본 두 가지(Safety Hook + 완료 알림)에 익숙해지면, 실제 작업 흐름에 맞는 커스텀 Hook을 만들 수 있습니다. 직접 써보면서 유용하다고 느낀 패턴들입니다.

패턴 1: 긴 작업 시작 시 자동 git commit

큰 작업을 시작하기 전에 자동으로 현재 상태를 커밋합니다.

#!/usr/bin/env python3
"""큰 작업 시작 전 자동 checkpoint commit"""
import json, sys, subprocess, re

data = json.load(sys.stdin)
if data.get("tool_name") not in ["Edit", "Write"]:
    sys.exit(0)

# 수정 대상 파일이 5개 이상이면 checkpoint 커밋
files = data.get("tool_input", {}).get("file_path", "")
if files:
    result = subprocess.run(
        ["git", "diff", "--name-only"],
        capture_output=True, text=True
    )
    changed = len(result.stdout.strip().split('\n')) if result.stdout.strip() else 0
    if changed >= 5:
        subprocess.run(
            ["git", "commit", "-am", "auto: checkpoint before large edit"],
            capture_output=True
        )
sys.exit(0)

패턴 2: 환경변수 노출 방지

코드에 API 키나 비밀번호가 하드코딩되려는 걸 잡아냅니다.

#!/usr/bin/env python3
"""하드코딩된 시크릿 감지 Hook"""
import json, re, sys

SECRET_PATTERNS = [
    (r'(?i)(api_key|secret|password|token)\s*=\s*["\'][^"\']{8,}["\']',
     "코드에 시크릿이 하드코딩되려 합니다. 환경변수를 사용하세요."),
    (r'sk-[a-zA-Z0-9]{20,}',
     "OpenAI API 키처럼 보이는 값이 있습니다."),
    (r'ghp_[a-zA-Z0-9]{36}',
     "GitHub 토큰처럼 보이는 값이 있습니다."),
]

data = json.load(sys.stdin)
if data.get("tool_name") not in ["Edit", "Write"]:
    sys.exit(0)

content = data.get("tool_input", {}).get("new_content", "") or \
          data.get("tool_input", {}).get("content", "")

for pattern, msg in SECRET_PATTERNS:
    if re.search(pattern, content):
        print(f"⚠️ 보안 경고: {msg}", file=sys.stderr)
        sys.exit(2)

sys.exit(0)

패턴 3: 특정 파일 수정 전 백업

중요한 설정 파일을 수정하기 전에 자동으로 백업합니다.

#!/bin/bash
# 중요 파일 수정 전 자동 백업

FILE=$(echo "$1" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('tool_input',{}).get('file_path',''))" 2>/dev/null)

IMPORTANT_FILES=("config.json" ".env.production" "nginx.conf" "docker-compose.yml")

for f in "${IMPORTANT_FILES[@]}"; do
    if [[ "$FILE" == *"$f"* ]]; then
        BACKUP="$FILE.backup.$(date +%Y%m%d_%H%M%S)"
        cp "$FILE" "$BACKUP" 2>/dev/null
        echo "백업 생성: $BACKUP" >&2
        break
    fi
done

exit 0

패턴 4: 비용 자동 기록

세션이 끝날 때마다 /usage 정보를 파일에 기록합니다.

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date '+%Y-%m-%d %H:%M') - Session ended\" >> ~/.claude/cost-log.txt"
          }
        ]
      }
    ]
  }
}

실전 사례: 팀에서 Hooks를 도입한 뒤 달라진 것들

팀에서 Claude Code를 본격적으로 쓰기 시작했을 때, 첫 번째 공식 정책이 "Safety Hook 필수 설치"였습니다. 이유는 단순했습니다. 팀원 한 명이 git push --force로 원격 브랜치를 덮어쓰는 사고가 났고, 복구에 두 시간이 걸렸습니다.

그 뒤로 Safety Hook을 .claude/settings.json에 넣고 Git으로 관리하기 시작했습니다. 새 팀원이 들어오면 git clone을 하는 순간 자동으로 Hook이 적용됩니다. 추가 설명 없이도 모든 팀원이 동일한 안전망을 갖습니다.

몇 가지 변화가 있었습니다:

첫째: git push --force를 시도하는 일이 아예 사라졌습니다. Hook이 막기 때문이 아니라, 팀원들이 이제 --force-with-lease를 쓰거나 merge 방식으로 작업하는 패턴을 익혔습니다. Hook이 교육 도구가 됐습니다.

둘째: Claude가 rm 명령을 쓰려 할 때 "trash를 써줘"라고 안내가 나오고, Claude가 자연스럽게 trash 명령으로 전환합니다. 이 과정이 반복되면서 팀원들도 수동 작업할 때 rm 대신 trash를 쓰는 습관이 생겼습니다.

셋째: 팀원이 걱정 없이 실험을 더 많이 합니다. "혹시 뭔가 날아가면 어쩌지"라는 불안이 줄어들면 과감한 실험이 늘어납니다. Hook이 속도를 만듭니다.

Hook 설계의 두 원칙

실제로 Hook을 여러 개 만들고 관리하다 보면 두 가지 원칙이 중요하다는 걸 알게 됩니다.

원칙 1 — Hook은 가볍게: Hook이 느리면 Claude의 모든 작업이 느려집니다. PreToolUse Hook은 도구 호출마다 실행됩니다. 파이썬 스크립트라면 모듈 임포트를 최소화하고, 불필요한 외부 호출을 피하세요. 일반적으로 50ms 이내가 적당합니다.

원칙 2 — Hook은 명확하게: exit 2로 차단할 때 stderr에 보내는 메시지가 Claude에게 전달됩니다. "차단됨"만 쓰면 Claude가 왜 차단됐는지 모릅니다. "rm 대신 trash를 사용하세요"처럼 구체적인 대안까지 써주면 Claude가 바로 올바른 방법으로 재시도합니다.

# 좋지 않은 예
print("차단됨", file=sys.stderr)
sys.exit(2)

# 좋은 예
print("차단됨: rm 대신 trash를 사용하세요 (brew install trash)", file=sys.stderr)
sys.exit(2)

Hook 모니터링: 잘 작동하는지 확인하는 법

Hook이 설정돼 있다고 해서 항상 잘 작동하는 건 아닙니다. 주기적으로 확인하는 방법들입니다.

1) /hooks 커맨드로 목록 확인: 세션 안에서 /hooks를 실행하면 현재 등록된 Hook 목록을 볼 수 있습니다. 목록에 없다면 설정 파일을 다시 확인하세요.

2) 테스트 요청 보내기: "echo 'test rm command' 실행해줘"처럼 차단돼야 할 명령을 테스트합니다. 실제 파일을 건드리지 않는 안전한 방법으로 Hook이 작동하는지 확인합니다.

3) --debug 모드: claude --debug로 시작하면 Hook 실행 로그를 볼 수 있습니다. 어떤 Hook이 언제 실행됐는지, 종료 코드가 무엇이었는지 추적됩니다.

claude --debug

Hook이 너무 많아지면

Hook을 열심히 만들다 보면 관리가 복잡해질 수 있습니다. 몇 가지 조직화 팁입니다.

스크립트 폴더로 관리: 여러 Hook 스크립트를 ~/.claude/hooks/ 폴더에 목적별로 나눕니다.

~/.claude/hooks/
├── safety/
│   ├── block_dangerous_commands.py
│   ├── block_sensitive_folders.sh
│   └── check_hardcoded_secrets.py
├── notifications/
│   ├── desktop_notify.sh
│   └── slack_notify.sh
└── automation/
    ├── auto_format.sh
    └── auto_backup.py

통합 Hook 스크립트: 여러 체크를 하나의 스크립트로 통합합니다.

#!/usr/bin/env python3
"""통합 Safety Hook"""
import json, re, sys

data = json.load(sys.stdin)
tool_name = data.get("tool_name", "")
tool_input = data.get("tool_input", {})

# Bash 명령어 체크
if tool_name == "Bash":
    command = tool_input.get("command", "")
    BLOCKED = [
        (r"\brm\s+", "rm → trash"),
        (r"git\s+push\s+.*--force", "push --force 차단"),
        (r"DROP\s+TABLE", "DROP TABLE 차단"),
    ]
    for pattern, msg in BLOCKED:
        if re.search(pattern, command, re.IGNORECASE):
            print(f"차단: {msg}", file=sys.stderr)
            sys.exit(2)

# Edit/Write 파일 체크
if tool_name in ["Edit", "Write"]:
    file_path = tool_input.get("file_path", "")
    PROTECTED = ["/contracts/", "/legal/", "/.env.production"]
    for p in PROTECTED:
        if p in file_path:
            print(f"차단: 보호 경로 ({p})", file=sys.stderr)
            sys.exit(2)

sys.exit(0)

전체 Safety Hook 최종 버전

지금까지 소개한 내용을 바탕으로 실제로 권장하는 Safety Hook 최종 형태입니다. 이 파일 하나로 대부분의 위험 상황을 커버할 수 있습니다.

~/.claude/hooks/safety.py:

#!/usr/bin/env python3
"""
Claude Code Safety Hook
위험 명령어를 실행 직전에 차단합니다.
"""
import json, re, sys

# ─── 차단 패턴 ──────────────────────────────────────────────────
# (패턴, 사유, 대안)
BASH_BLOCKED = [
    # 파일 삭제
    (r"\brm\s+-[rfRF]*\s", "rm -rf 사용 금지", "trash 명령을 사용하세요"),
    (r"\brm\s+[^-]", "rm 사용 금지", "trash 명령을 사용하세요"),
    
    # Git 히스토리 파괴
    (r"git\s+reset\s+--hard", "git reset --hard 사용 금지",
     "git stash 또는 git revert를 사용하세요"),
    (r"git\s+push\s+.*--force(?!-with-lease)", "git push --force 사용 금지",
     "--force-with-lease를 사용하세요"),
    (r"git\s+push\s+.*-f\b", "git push -f 사용 금지",
     "--force-with-lease를 사용하세요"),
    (r"git\s+clean\s+-[a-zA-Z]*f", "git clean -f 사용 금지",
     "git stash로 임시 보관하세요"),
    
    # 데이터베이스 파괴
    (r"DROP\s+(DATABASE|TABLE)\s+", "DROP DATABASE/TABLE 사용 금지",
     "백업 후 진행하거나 관리자에게 확인하세요"),
    (r"TRUNCATE\s+TABLE\s+", "TRUNCATE TABLE 사용 금지",
     "삭제 조건을 확인 후 DELETE 문을 사용하세요"),
    
    # 시스템 위험
    (r"chmod\s+777", "chmod 777 사용 금지",
     "최소 권한 원칙을 적용하세요 (예: chmod 644)"),
    (r">\s*/etc/", "/etc 직접 쓰기 금지",
     "설정 변경은 관리자 권한 및 백업 후 진행하세요"),
]

FILE_PROTECTED = [
    "/etc/passwd", "/etc/hosts", ".env.production",
    "id_rsa", "id_ed25519",
]

def check_bash(command: str):
    for pattern, reason, alt in BASH_BLOCKED:
        if re.search(pattern, command, re.IGNORECASE):
            msg = f"차단: {reason}"
            if alt:
                msg += f"\n→ 대안: {alt}"
            print(msg, file=sys.stderr)
            sys.exit(2)

def check_file(file_path: str):
    for protected in FILE_PROTECTED:
        if protected in file_path:
            print(f"차단: 보호 파일 접근 금지 ({protected})", file=sys.stderr)
            sys.exit(2)

def main():
    try:
        data = json.load(sys.stdin)
    except Exception:
        sys.exit(0)
    
    tool_name = data.get("tool_name", "")
    tool_input = data.get("tool_input", {})
    
    if tool_name == "Bash":
        command = tool_input.get("command", "")
        if command:
            check_bash(command)
    
    elif tool_name in ("Edit", "Write"):
        file_path = tool_input.get("file_path", "")
        if file_path:
            check_file(file_path)
    
    sys.exit(0)

if __name__ == "__main__":
    main()

설치:

# 스크립트 생성
mkdir -p ~/.claude/hooks
# 위 내용을 ~/.claude/hooks/safety.py에 저장
chmod +x ~/.claude/hooks/safety.py

# settings.json에 등록

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/safety.py"
          }
        ]
      }
    ]
  }
}

Hooks로 반복 업무 자동화하기

Safety와 알림 외에도 반복 업무를 자동화하는 데 Hooks를 쓸 수 있습니다.

코드 저장 시 자동 테스트

Python 파일이 저장될 때마다 자동으로 테스트를 실행합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/auto-test.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# auto-test.sh
FILE=$(python3 -c "import json,sys; print(json.load(sys.stdin).get('tool_input',{}).get('file_path',''))" 2>/dev/null)

if [[ "$FILE" == *.py ]]; then
    cd "$(dirname "$FILE")" && python3 -m pytest -x -q 2>&1 | tail -5
fi
exit 0

세션 시작 시 날씨 + 오늘 할 일

#!/bin/bash
# morning-context.sh — 세션 시작 시 컨텍스트 주입

echo "=== 오늘 날짜: $(date '+%Y-%m-%d %A') ==="
echo ""

# Notion이나 로컬 파일에서 오늘 할 일 가져오기
if [ -f ~/today.md ]; then
    echo "=== 오늘 할 일 ==="
    cat ~/today.md
fi

exit 0

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/morning-context.sh"
          }
        ]
      }
    ]
  }
}

이 Hook이 있으면 세션을 시작할 때마다 오늘 날짜와 할 일 목록이 자동으로 Claude의 컨텍스트에 들어갑니다. "오늘 어떤 작업을 해야 하나"를 따로 설명할 필요가 없어집니다.

자주 묻는 것들

Hook이 실행되는 시간이 너무 오래 걸려요

Hook은 도구 호출마다 실행됩니다. 파이썬 스크립트라면 모듈 임포트가 느릴 수 있습니다. 가능하면 내장 모듈(json, re, sys)만 쓰고, 무거운 외부 라이브러리는 피하세요. 타임아웃은 기본 30초이므로 평소엔 문제없지만, 네트워크 요청이 포함된 Hook은 타임아웃을 명시적으로 짧게 잡는 게 좋습니다.

Hook이 Claude에게 정보를 돌려주고 싶어요

exit 0으로 허용하면서 stdout에 출력하면, 그 내용이 Claude의 응답에 포함됩니다. PostToolUse Hook에서 분석 결과를 Claude에게 피드백하는 방식으로 쓸 수 있습니다.

# stdout으로 출력 → Claude가 받음
print("파일 분석 완료: 3개의 잠재적 이슈 발견")
sys.exit(0)  # 허용하면서 정보 전달

팀원마다 다른 Hook을 쓰고 싶어요

팀 공통 Hook은 .claude/settings.json에, 개인 Hook은 ~/.claude/settings.json에 둡니다. 두 설정 파일의 Hook이 병합되어 모두 실행됩니다.

Hooks 사용 전과 후: 직접 비교

Hook을 설치하기 전과 후의 경험을 구체적으로 비교해보면 차이가 분명해집니다.

Safety Hook 없을 때

[나] "node_modules 삭제하고 다시 설치해줘"
[Claude] rm -rf node_modules && npm install 실행
[결과] 작업 완료. 별 문제 없음.

--- 3주 후 ---

[나] "빌드 폴더랑 캐시 전부 날려줘"
[Claude] rm -rf dist/ .cache/ build/ 실행
[결과] ??? 잠깐, dist 폴더에 중요한 파일이 있었는데...
[비용] 복구 시간 1시간

Safety Hook 있을 때

[나] "node_modules 삭제하고 다시 설치해줘"
[Claude] rm 차단 감지 → trash node_modules && npm install 실행
[결과] 작업 완료. 실수했어도 휴지통에서 복구 가능.

--- 3주 후 ---

[나] "빌드 폴더랑 캐시 전부 날려줘"
[Claude] rm 차단 감지 → trash dist/ .cache/ build/ 실행
[결과] 됐다. 혹시 중요한 파일이 있었으면 휴지통에서 꺼낼 수 있음.

차이는 복구 가능성입니다. Hook이 없어도 대부분은 잘 됩니다. Hook이 있으면 잘못됐을 때 돌아올 수 있습니다.

Hook을 쓰면서 실제로 막은 것들

직접 경험한 차단 사례들입니다.

1) 프로덕션 데이터 실수 삭제 방지

리팩터링 중에 Claude가 "테스트 데이터를 정리하겠다"며 날짜 조건이 붙은 DELETE 쿼리를 실행하려 했습니다. Hook에 WHERE 절이 없는 DELETE를 차단하는 패턴이 있었다면 막혔을 텐데, 이 경우는 WHERE 절이 있어서 통과됐습니다.

이 일이 있고 나서 "프로덕션 DB에서는 DELETE 전에 COUNT(*) 먼저 실행"하는 Hook을 추가했습니다. 확인을 강제하는 방식입니다.

2) 환경 변수 노출 방지

Claude가 디버깅 중에 echo $DATABASE_URL을 실행하려 했습니다. 이 명령은 터미널에 DB 접속 정보를 출력합니다. Hook에 민감 환경변수를 echo하는 패턴을 차단하는 규칙을 추가했습니다.

3) 프로덕션 서버 직접 접근 방지

ssh prod.server.com을 차단하는 패턴을 추가했습니다. 프로덕션 서버는 항상 staging을 거쳐서 접근하는 원칙을 Hook으로 강제했습니다.

이런 사례들이 쌓일수록 Safety Hook의 패턴이 팀의 경험을 담은 규칙집이 됩니다. "이런 일이 있었다 → 이 패턴을 추가했다"의 기록입니다.

Hooks JSON 문법 참고

자주 헷갈리는 JSON 구조를 한 번에 정리합니다.

{
  "hooks": {
    "<EventName>": [             // 이벤트 이름 (PreToolUse, Stop 등)
      {
        "matcher": "<pattern>",  // 도구 이름 매칭 (빈 문자열은 전체 매칭)
        "hooks": [
          {
            "type": "command",   // "command" | "prompt" | "http"
            "command": "...",    // type이 command일 때
            "timeout": 30        // 타임아웃 (초, 기본값: 30)
          }
        ]
      }
    ]
  }
}

matcher 예시:

"": 모든 도구에 적용
"Bash": Bash 도구에만 적용
"Edit|Write": Edit 또는 Write 도구에 적용 (주의: 이건 OR가 아니라 파이프 문자 리터럴)
"Read": Read 도구에만 적용

이벤트별 JSON 입력 구조:

PreToolUse는 이런 JSON이 stdin으로 들어옵니다:

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf node_modules"
  }
}

Stop은 이런 JSON이 들어옵니다:

{
  "session_id": "xxx",
  "turn_count": 5,
  "stop_reason": "end_turn"
}

Hooks와 MCP, Skills의 관계

Hooks, MCP, Skills는 각각 다른 층에서 Claude Code를 확장합니다.

기능	역할	예시
MCP	외부 도구와 연결	GitHub PR 읽기, Notion 페이지 생성
Hooks	Claude의 동작을 제어·감시	위험 명령 차단, 작업 완료 알림
Skills	반복 워크플로우 저장	`/commit`, `/meeting`, `/translate`

셋 중 어느 것이 더 중요한가를 따지는 게 아니라, 함께 쓸 때 효과가 납니다.

예를 들어:

MCP로 Slack을 연결하고
Hook으로 "Slack에 메시지 보내기 전에 확인" 체크를 넣고
Skill로 "주간 팀 요약을 Slack에 보내는 루틴"을 저장합니다

이 세 가지가 맞물리면 "매주 금요일 오후에 /weekly-summary 한 번"으로 모든 게 자동화됩니다.

비개발자도 쓸 수 있는 Hooks

Hooks가 코딩 작업에만 필요한 것처럼 보일 수 있습니다. 실제로는 비개발자에게도 유용한 패턴이 있습니다.

중요 문서 수정 방지

계약서, 재무 보고서, 법적 문서가 있는 폴더를 Claude가 수정하지 못하게 막습니다.

#!/bin/bash
FILE=$(python3 -c "import json,sys; print(json.load(sys.stdin).get('tool_input',{}).get('file_path',''))")

# 보호 폴더 목록
if [[ "$FILE" == *"/contracts/"* ]] || [[ "$FILE" == *"/legal/"* ]]; then
    echo "차단: 계약서 폴더는 직접 수정만 가능합니다." >&2
    exit 2
fi
exit 0

작업 완료 후 이메일 또는 Slack 알림

긴 분석 작업이 끝나면 이메일 또는 Slack으로 알림을 받습니다.

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST $SLACK_WEBHOOK -d '{\"text\": \"Claude Code: 작업 완료\"}'"
          }
        ]
      }
    ]
  }
}

SLACK_WEBHOOK 환경변수에 Slack Incoming Webhook URL을 설정하면 됩니다.

Hook 이벤트 전체 목록과 용도

전체 20여 개 이벤트 중 입문자에게 유용한 것들을 정리합니다. 나머지는 필요가 생겼을 때 공식 문서를 참고하세요.

사전 차단 가능한 이벤트들 (exit 2로 실행 막기 가능):

PreToolUse — 모든 도구 실행 직전. Safety Hook의 핵심. 도구 이름과 입력값을 받아서 차단 여부를 결정합니다. Bash, Edit, Write, Read 등 모든 Claude 도구에 적용됩니다.

UserPromptSubmit — 사용자 프롬프트가 제출되는 순간. 프롬프트 전처리나 특정 키워드를 포함한 요청을 차단할 때 씁니다. "전체 데이터베이스를 삭제해줘" 같은 위험한 자연어 요청을 필터링할 수 있습니다.

Stop — Claude가 응답을 마치고 멈추려 할 때. "아직 완료되지 않은 태스크가 있으면 계속해줘"를 강제할 수 있습니다. 자동화 환경에서 중간에 멈추지 않게 하는 데 유용합니다.

PreCompact — 컨텍스트 압축 직전. 압축 전에 중요한 정보를 따로 저장하거나, 특정 조건에서 압축 자체를 막을 수 있습니다.

SubagentStop — 서브에이전트가 멈추려 할 때. 서브에이전트의 결과를 검증하거나 후처리하는 데 씁니다.

사후 처리만 가능한 이벤트들 (차단 불가, 처리 후 행동만):

PostToolUse — 도구 실행 직후. 자동 포매팅, 파일 변경 로그, 테스트 실행 등에 씁니다. 이미 실행된 것을 되돌릴 수는 없지만, 후속 조치를 자동화할 수 있습니다.

SessionStart — 세션 시작 또는 재개 시. 업무 컨텍스트 주입, 환경 확인, 환영 메시지 출력에 씁니다.

SessionEnd — 세션 종료 시. 사용량 기록, 정리 작업, 세션 요약 저장에 씁니다.

Notification — Claude가 알림을 보낼 때. 데스크톱 알림이나 소리로 전환하는 데 씁니다.

PreToolUse에서 받는 JSON 구조

Safety Hook을 만들 때 가장 중요한 것은 어떤 데이터가 들어오는지 아는 것입니다.

Bash 도구 호출 시: 도구 이름은 "Bash", 실행하려는 명령어는 tool_input.command에 들어 있습니다. 이것을 정규식으로 검사해서 차단 여부를 결정합니다.

Edit 도구 호출 시: 도구 이름은 "Edit", 수정하려는 파일 경로는 tool_input.file_path, 변경 내용은 tool_input.new_content에 들어 있습니다.

Write 도구 호출 시: 도구 이름은 "Write", 작성할 파일 경로는 tool_input.file_path, 내용은 tool_input.content에 들어 있습니다.

이 세 가지 구조만 알면 대부분의 Safety Hook을 만들 수 있습니다. 나머지 도구(Read, Glob, Grep 등)는 보통 차단이 필요 없어서 sys.exit(0)으로 바로 통과시키면 됩니다.

Hook 설정이 적용되는 순서

여러 곳에 Hook이 설정돼 있을 때 어떤 순서로 실행되는지 알아두면 혼란을 피할 수 있습니다.

Claude Code는 설정 파일을 여러 곳에서 읽습니다. 전역 설정(~/.claude/settings.json), 프로젝트 설정(.claude/settings.json), 프로젝트 로컬 설정(.claude/settings.local.json) 이렇게 세 곳입니다. Hook은 이 세 곳에서 정의된 것이 모두 합쳐져서 실행됩니다.

같은 이벤트에 여러 Hook이 있으면 순서대로 모두 실행됩니다. 하나라도 exit 2를 반환하면 차단됩니다. 즉, 전역 설정의 Safety Hook과 프로젝트 설정의 폴더 보호 Hook이 둘 다 있으면 두 개 모두 통과해야 실행됩니다. 어느 쪽이 막으면 막힙니다.

이 구조가 유용한 이유는 팀 공통 정책(프로젝트 설정)과 개인 설정(전역 또는 로컬)을 독립적으로 관리할 수 있기 때문입니다. 팀 정책이 강화돼도 내 개인 설정을 변경할 필요가 없고, 개인 설정을 강화해도 팀 설정에 영향을 주지 않습니다.

Hook 경보 메시지를 잘 쓰는 법

Hook이 차단할 때 stderr로 보내는 메시지는 Claude에게 전달됩니다. 이 메시지를 어떻게 쓰느냐에 따라 Claude의 다음 행동이 달라집니다.

좋은 차단 메시지의 세 가지 조건이 있습니다.

첫째, 왜 차단됐는지 설명합니다. "차단됨"이라고만 하면 Claude가 왜 안 되는지 모릅니다. "git push --force는 원격 히스토리를 덮어씁니다"처럼 이유를 씁니다.

둘째, 대안을 제시합니다. "대신 --force-with-lease를 사용하세요"처럼 바로 쓸 수 있는 대안을 줍니다. 대안이 있으면 Claude가 즉시 재시도합니다. 대안이 없으면 Claude가 "어떻게 할까요"라고 되물어옵니다.

셋째, 간결하게 씁니다. 긴 설명보다 짧고 명확한 것이 Claude가 읽고 즉시 반응하기 좋습니다. 두 줄을 넘기면 메시지 핵심이 묻힐 수 있습니다.

이 세 가지를 갖추면 Hook이 막힐 때마다 Claude가 올바른 방향으로 재시도하는 패턴이 자리 잡습니다.

실전에서 유용한 Hook 조합

단독으로 쓰는 것보다 조합했을 때 더 효과적인 패턴들입니다.

Safety Hook + 완료 알림 조합은 가장 기본적인 세트입니다. Safety Hook이 위험을 막고, 완료 알림이 작업 완료를 알려줍니다. 이 두 가지만 있어도 바이브코딩 경험이 크게 달라집니다.

Safety Hook + 자동 체크포인트 커밋 조합은 큰 작업에 유용합니다. 일정 수 이상의 파일이 수정되려 할 때 자동으로 git commit을 만들어두고 진행합니다. 도중에 문제가 생겨도 마지막 자동 커밋으로 돌아올 수 있습니다.

완료 알림 + 비용 기록 조합은 비용 관리에 유용합니다. 작업이 끝날 때마다 알림을 받으면서 동시에 세션 비용을 로그에 기록합니다. 나중에 "이 작업에 얼마나 들었나"를 추적할 수 있습니다.

SessionStart + 자동 컨텍스트 주입 + 오늘 할 일 표시 조합은 매일 아침 세션을 시작할 때 유용합니다. 세션이 시작되는 순간 오늘 날짜, 프로젝트 상태, 오늘 해야 할 일이 자동으로 Claude에게 전달됩니다. 매번 상황 설명을 다시 할 필요가 없어집니다.

팀원에게 Hooks를 처음 설명할 때

새 팀원이 Claude Code를 쓰기 시작할 때 Hooks를 어떻게 설명하면 좋을지를 생각해봤습니다.

가장 효과적인 방법은 직접 시연입니다. rm 명령을 실행하려 하면 어떻게 막히는지, 완료 알림이 어떻게 작동하는지를 직접 보여주면 30초 안에 이해합니다. 개념 설명보다 동작 시연이 훨씬 빠릅니다.

두 번째로 효과적인 방법은 "이게 없어서 생긴 사고" 이야기입니다. "이전에 이런 일이 있었다"는 실제 사례가 "이런 게 필요하다"는 추상적인 설명보다 설득력이 있습니다. 팀에서 실제 사고가 있었다면 그 이야기를 씁니다.

설정은 복잡하게 설명하지 말고 파일 한 개를 주는 게 낫습니다. "이 파일을 ~/.claude/hooks/safety.py에 저장하고, settings.json에 이 내용을 추가해"라고 하면 대부분 10분 안에 설정이 끝납니다. 코드를 이해하지 않아도 됩니다.

Hooks와 Claude의 자율성 균형

Hooks를 처음 배우면 "이렇게 차단해버리면 Claude가 제대로 못 하는 것 아닌가"라는 걱정이 들 수 있습니다. 이 걱정을 풀어두겠습니다.

Hooks는 특정 패턴의 위험한 명령만 차단합니다. rm이 차단되면 trash로 대안을 씁니다. git push --force가 차단되면 --force-with-lease를 씁니다. Claude는 차단 메시지를 읽고 다른 방법을 찾습니다. 작업이 멈추지 않습니다.

오히려 반대 효과가 납니다. Hook이 있다는 것을 Claude도 알고 있기 때문에(차단 메시지를 통해 학습), 이후에는 처음부터 안전한 방법을 사용하려 합니다. 같은 세션에서 rm이 차단된 뒤에는 대부분 자발적으로 trash를 씁니다.

Claude의 자율성은 줄어들지 않습니다. 그 자율성이 안전한 방향으로 정렬될 뿐입니다.

Hooks로 가능한 고급 시나리오

기본적인 사용을 넘어서 가능한 고급 시나리오들입니다. 이런 것까지 된다는 것을 알아두면, 나중에 필요가 생겼을 때 가능성을 떠올릴 수 있습니다.

멀티 에이전트 안전 게이팅: 서브에이전트가 특정 작업을 완료했을 때 결과를 검증하고, 기준에 미달하면 SubagentStop에서 차단해 재시도를 유도합니다.

비용 한도 자동 브레이크: PreToolUse Hook에서 세션 누적 비용을 체크하고, 임계값 초과 시 더 이상의 도구 호출을 차단합니다. 예상보다 많이 쓰는 것을 자동으로 막습니다.

컨텍스트 인식 차단: PreToolUse Hook에서 현재 git 브랜치를 확인하고, main 브랜치에서는 특정 파일 수정을 차단합니다. 브랜치 없이 직접 main에 작업하는 것을 막습니다.

감사 로그 자동화: 모든 도구 호출을 PostToolUse Hook으로 로그 파일에 기록합니다. 나중에 "Claude가 어떤 작업을 했는지" 추적하는 감사 로그가 됩니다.

이런 고급 시나리오는 필요할 때 구현하면 됩니다. 처음에는 Safety Hook과 완료 알림만으로 충분합니다.

실제로 일어난 일: 팀의 첫 Hooks 도입 이야기

팀에서 Claude Code를 본격적으로 쓰기 시작했던 때의 이야기입니다. 처음 몇 주는 Hooks 없이 사용했습니다. 각자 조심하면 된다는 생각이었습니다. 결과는 예상대로였습니다.

어느 날 저녁, 긴 세션 작업 중에 팀원 하나가 Claude에게 "사용하지 않는 의존성 정리해줘"라고 요청했습니다. Claude가 전체적인 정리를 계획하면서 빌드 캐시를 지우는 과정에서 rm -rf 명령을 실행했고, 그 경로에 아직 커밋되지 않은 환경 설정 파일들이 포함돼 있었습니다. 파일들은 사라졌습니다. 복구에 두 시간이 걸렸고, 그날 저녁은 그걸로 끝이었습니다.

다음 날 아침에 Safety Hook 설정 파일을 만들었습니다. rm 패턴 하나만 넣고, chmod +x 하고, settings.json에 등록했습니다. 15분 작업이었습니다. 그 뒤로 같은 사고는 두 번 다시 없었습니다.

두 번째 변화는 완료 알림이었습니다. 긴 분석 작업을 Claude에게 맡기고 다른 창을 보다가 뒤늦게 확인하는 패턴이 있었습니다. 완료 알림 Hook을 단 뒤로는 소리가 나는 순간에 돌아올 수 있었습니다. 대기 시간이 줄었습니다.

세 번째 변화는 팀원들의 태도였습니다. 안전망이 생기니까 더 과감하게 실험했습니다. "혹시 날아가면 어쩌지"라는 걱정이 줄어들면서 더 큰 리팩터링을 시도하고, 더 복잡한 자동화를 실험하기 시작했습니다. 그 실험이 쌓여서 팀의 작업 방식이 바뀌었습니다.

두 달 뒤에 팀원 한 명이 말했습니다. "처음에는 복잡해 보여서 안 쓰고 싶었는데, 지금은 없으면 불안할 것 같아요." 그게 Hooks가 주는 변화입니다.

Hook을 통해 배우는 것들

Hooks를 만들고 관리하면서 자연스럽게 배워지는 것들이 있습니다.

어떤 명령이 위험한지 알게 됩니다. Safety Hook의 차단 패턴을 하나씩 이해하다 보면, 왜 rm 명령이 위험하고 git reset hard가 위험한지, git push force와 git push force with lease의 차이가 무엇인지를 자연스럽게 알게 됩니다. Hook이 학습 도구가 됩니다. 패턴을 직접 쓰면서 배우는 것이기 때문에 이론으로 읽는 것보다 훨씬 잘 기억됩니다.

Claude의 동작 패턴을 이해하게 됩니다. PreToolUse에 들어오는 JSON을 보다 보면 Claude가 각 작업을 어떤 도구로 어떻게 처리하는지 보입니다. 블랙박스처럼 느껴지던 Claude의 내부 동작이 조금씩 투명해집니다. "Claude가 파일을 수정하려면 Edit 도구를 쓰는구나", "터미널 명령은 Bash 도구로 보내는구나"라는 것을 몸으로 익히게 됩니다.

파이썬 스크립팅 기초를 자연스럽게 익힙니다. 코딩을 전혀 모르던 분도 Safety Hook 스크립트를 수정하면서 정규식이 무엇인지, 프로세스 종료 코드가 무엇인지를 맥락 안에서 배웁니다. 책으로 따라가는 것보다 훨씬 빠릅니다. 실제 목적이 있어서 배우는 것이기 때문에 기억에도 잘 남습니다.

Hooks를 처음 설정하는 데 드는 시간

"Hooks 설정이 복잡하지 않나요?"라는 질문을 자주 받습니다. 실제로 해보면 생각보다 짧습니다.

완료 알림 설정: 5분. settings.json에 몇 줄 추가하는 것입니다. 코딩 지식이 전혀 없어도 됩니다. 이 가이드에서 제공하는 JSON을 그대로 복사해서 붙여넣으면 됩니다.

Safety Hook 최소 버전: 15분. 파이썬 파일 하나를 만들고, chmod +x 하고, settings.json에 등록하는 세 단계입니다. 파이썬을 몰라도 됩니다. 파일을 만들고 저장하는 방법만 알면 됩니다.

Safety Hook 확장 버전: 30분. 패턴을 더 추가하는 것이기 때문에 기본 버전보다 조금 더 걸립니다. 하지만 이것도 이 가이드의 예시를 참고해서 원하는 패턴을 골라 넣는 작업입니다.

처음 설정에 쓰는 한 시간이 이후 수십 번의 사고를 막습니다. 시간 대비 효과가 가장 좋은 Claude Code 설정 중 하나입니다.

한 달 뒤의 나를 위한 Hooks 문서화

Hook을 만들고 나서 한 달 뒤에 돌아보면, 왜 이 패턴을 만들었는지 기억이 안 나는 경우가 있습니다. 특히 덜 직관적인 패턴일수록 그렇습니다.

각 차단 패턴 옆에 주석으로 "왜 이걸 막는지"를 써두는 습관이 좋습니다. 파이썬 스크립트 안에 주석으로, 또는 CLAUDE.md에 별도 섹션으로 남겨두는 방법이 있습니다.

예를 들어 "왜 git push force를 막는가: 원격 브랜치의 커밋을 덮어써서 팀원 작업을 날릴 수 있다. 2024년 3월에 실제로 사고가 났고 복구에 두 시간 걸렸다."라는 식으로 적어두면, 나중에 팀에 새로 합류한 사람이 왜 이 패턴이 있는지 이해할 수 있습니다.

팀의 경험이 코드로 기록되는 방식입니다. Hook의 패턴은 단순한 규칙이 아니라 팀이 겪었던 것들의 기록입니다.

Hook 사용 시 자주 받는 질문과 답변

Claude가 Hook 때문에 제대로 작동 못하면 어떻게 하나요: 잘못된 패턴으로 의도하지 않은 차단이 일어나면, settings.json에서 해당 패턴을 임시로 제거하거나 주석 처리하면 됩니다. Hook은 항상 수정할 수 있습니다. Claude가 특정 작업을 못하게 된다면, 그 패턴을 더 좁게 수정하면 됩니다.

여러 프로젝트에 각각 다른 Hook을 쓰고 싶어요: 가능합니다. 프로젝트마다 .claude/settings.json을 두고, 공통 설정은 전역 파일에, 프로젝트별 설정은 각 프로젝트 파일에 두면 됩니다. 두 파일의 Hooks가 합쳐져서 실행됩니다.

Hook 스크립트가 느린 것 같아요: 파이썬 스크립트는 실행마다 인터프리터를 새로 시작합니다. 무거운 라이브러리를 임포트하면 느려집니다. json, re, sys 같은 내장 모듈만 쓰면 보통 10ms 이내입니다. 불필요한 임포트를 제거하면 됩니다.

Hook을 완전히 비활성화하고 싶어요: settings.json에서 hooks 섹션 전체를 삭제하거나 주석으로 만들면 됩니다. JSON에는 주석이 없으니 해당 섹션을 빈 객체로 만들면 됩니다.

Safety Hook을 처음 만든 날

처음 Safety Hook을 만들던 날을 기억합니다. 파이썬 파일을 열고, 차단할 패턴 목록을 생각하면서, "이게 정말 효과가 있을까"라는 의심이 있었습니다. 그냥 Claude가 알아서 조심하지 않을까 싶었습니다.

첫 번째 테스트로 "테스트 파일 지워줘"라고 했더니 Claude가 rm 명령을 실행하려 했습니다. Hook이 잡았습니다. Claude에게 "rm 대신 trash를 사용하세요"라는 메시지가 전달됐고, Claude가 바로 "죄송합니다, trash를 사용할게요"라고 하면서 trash 명령으로 재시도했습니다.

그 순간 이해했습니다. Hook은 Claude를 제한하는 게 아니라, 더 안전한 방법으로 안내하는 것입니다. 차단이 아니라 리다이렉션입니다.

두 번째 깨달음은 심리적 변화였습니다. Safety Hook이 생기고 나서 Claude에게 더 큰 작업을 더 편하게 맡기기 시작했습니다. 전에는 "혹시 실수로 뭔가 날아가면?"이라는 걱정이 있어서 조금씩 맡겼는데, Hook이 있으니까 크게 맡겨도 괜찮다는 생각이 생겼습니다.

그 변화가 작업 속도에 직접 영향을 줬습니다. 안전망 없이 조심조심 하는 것보다, 안전망을 믿고 과감하게 하는 것이 결국 더 빠릅니다.

Hooks에 대한 오해들

몇 가지 흔한 오해를 정리해두겠습니다.

첫 번째 오해: "Hooks를 설정하면 Claude가 너무 많이 막힌다." 실제로는 위험한 명령 몇 가지만 차단합니다. 대부분의 작업은 전혀 영향을 받지 않습니다. 일반 파일 읽기, 코드 분석, 내용 수정 등은 아무런 제한 없이 진행됩니다. Hook이 개입하는 것은 특정 위험 패턴에 매치되는 아주 제한적인 경우입니다.

두 번째 오해: "이미 신중하게 쓰면 Hooks가 필요 없다." 사람이 신중한 것과 자동화된 안전망은 다릅니다. 신중한 사람도 피로하면 실수합니다. 오랜 세션 끝에 집중력이 떨어진 상태에서, 또는 Claude의 계획을 너무 빠르게 OK 누른 순간에 사고가 납니다. Hook은 그 순간에도 작동합니다.

세 번째 오해: "파이썬을 모르면 Safety Hook을 못 만든다." 이 가이드에서 제공하는 스크립트를 그대로 복사해서 쓰면 됩니다. 파이썬을 전혀 몰라도 됩니다. 나중에 패턴을 추가하고 싶으면 그때 배우면 됩니다. 처음부터 다 이해하고 시작할 필요가 없습니다.

Hooks가 주는 가장 큰 선물은 속도입니다

안전망이 생기면 더 빠르게 움직일 수 있습니다. 처음 들으면 거꾸로 들릴 수 있는 말입니다. 안전 장치가 오히려 속도를 높인다고요?

그렇습니다. 두려움이 없어지면 실험을 더 많이 합니다. "이렇게 해도 되나"라는 망설임이 없어지면 "일단 해보자"가 됩니다. 실험이 많아지면 더 빠르게 원하는 결과에 도달합니다.

바이브코딩의 핵심은 빠른 피드백 루프입니다. 시도하고, 결과를 보고, 수정하는 사이클이 빠를수록 좋습니다. 그런데 사이클 중에 "잘못되면 어쩌지"라는 불안이 끼어들면 사이클이 느려집니다. 매 결정 앞에서 한 번씩 더 생각하게 됩니다.

Hooks는 그 불안을 제거합니다. 잘못돼도 복구할 수 있다는 것을 알고, 위험한 명령은 자동으로 막힌다는 것을 알면, 실행 버튼을 주저 없이 누를 수 있습니다. 그 주저함 없음이 속도입니다.

Hooks를 쓸수록 Claude Code가 더 안전해집니다

Hooks의 진짜 가치는 단순히 사고를 막는 것이 아닙니다. Claude Code를 믿고 더 과감하게 쓸 수 있게 해주는 것입니다.

만약 이게 날아가면 어쩌지라는 불안이 없어지면, 더 큰 리팩터링을 시도하고, 더 복잡한 자동화를 실험하고, 더 많이 Claude에게 맡길 수 있습니다. 그 실험의 누적이 결국 더 나은 코드, 더 빠른 작업으로 이어집니다.

안전망이 있는 사람은 더 높이 올라갑니다. Hook이 그 안전망입니다.

한 줄로

Safety Hook + 완료 알림: 이 두 개만 깔아두어도 바이브코딩이 한층 안전하고 편해집니다. rm 한 방에 프로젝트 날리는 사고는 미리 막아두는 것이 가장 쌉니다.

이 장을 덮기 전에

~/.claude/hooks/block_dangerous.py를 만들고 실행 권한을 부여했다
~/.claude/settings.json에 PreToolUse Hook을 등록했다
/hooks 커맨드로 등록된 Hook 목록을 확인해봤다
완료 알림 Hook을 설정하고 작업이 끝날 때 소리가 나는 것을 확인했다

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

Skills & 플러그인 만들기

자주 하는 일을 레시피로 저장하고 /커맨드 하나로 꺼내 씁니다. 팀과 플러그인으로 나눌 수도 있습니다.

참고

17. Skills: 자주 하는 일을 한 번만 정리해두는 방법

자주 하는 일을 한 번 적어두면, 이후로는 한 줄 명령으로 끝납니다. 같은 설명을 두 번 다시 타이핑하지 않아도 되는 영역입니다.

Claude Code 공식 Skills 페이지의 첫 스킬 만들기 출처: Skills — Anthropic 공식 문서

Skills가 해결하는 문제

Claude Code를 쓰다 보면 같은 작업을 반복적으로 요청하게 됩니다. 회의 끝나면 회의록 정리, 코드 변경 후 커밋 메시지 작성, 주간 보고서 생성... 이런 작업을 매번 처음부터 설명하다 보면 프롬프트가 길어지고, 때로는 설명이 달라져서 결과가 일관되지 않습니다.

Skill은 이 반복 프로세스를 파일로 저장해두는 것입니다. 한 번 잘 정리해두면 /회의록, /커밋, /주간보고서 한 줄로 바로 실행됩니다. 결과 형식도 항상 동일하게 나옵니다.

💡 한 번은 이런 일이 있었습니다. 강의를 10주째 운영하면서 매주 질문을 정리하는 작업이 있었습니다. 슬랙에서 질문을 가져와서 유형별로 분류하고, 다음 강의 내용에 반영하는 흐름이었습니다. 처음 몇 주는 매번 Claude에게 "슬랙 메시지를 가져와서 이런 형식으로 정리해줘"라고 설명했는데, 강의 10회가 되면서 이 설명이 점점 달라지고 있었습니다. 어느 날 그 설명을 SKILL.md에 옮겨 두고 /weekly-qa로 만들었습니다. 그 다음 주부터는 세 단어로 작업이 끝났습니다.

Skill: 한 줄로 정리

Skill은 Claude Code에 새 능력을 더하는 재사용 가능한 워크플로우입니다. SKILL.md 파일 한 장만 만들면 Claude가 도구로 인식합니다. /스킬이름으로 직접 실행하거나, 상황에 맞춰 자동 활성화시킬 수도 있습니다.

쉽게 말하면 자주 쓰는 작업 절차를 문서화해두는 일입니다. 그 한 번의 정리가 있으면 다음부턴 한 마디로 시킬 수 있습니다.

ℹ️ 공식 문서는 Skills를 권장하지만, 기존 .claude/commands/의 커스텀 슬래시 커맨드도 정식으로 그대로 동작합니다. 두 메커니즘은 별개이며 동일한 frontmatter를 지원합니다. 같은 이름이 둘 다 있으면 Skill이 우선합니다.

일반 대화와 비교: 어디가 다를까

같은 일을 시키는 두 방식의 차이를 짝지어보면 이렇습니다.

실행: 매번 설명 타이핑 vs /skill-name 한 번
일관성: 매번 결과가 흔들림 vs 항상 동일한 절차
팀 공유: 어렵다 vs Git 커밋으로 자연스럽게
인자 전달: 설명 속에 묻힘 vs $ARGUMENTS로 명확하게
도구 제한: Claude의 판단에 맡김 vs 허용된 도구만

두 번째 차이가 실제로 가장 큰 변화입니다. 같은 프롬프트처럼 보여도 매번 조금씩 다르게 쓰면 결과가 달라집니다. Skill은 그 흔들림을 없앱니다.

"복붙 노가다"가 사라지는 자리

회의 끝날 때마다 녹음 정리 부탁 → /meeting 파일명 한 번
주간 보고서 형식 매번 설명 → /weekly-report 한 번
번역 요청마다 언어·형식 명시 → /translate ko en README.md
경쟁사 분석마다 형식 설명 → /competitor-analysis 회사명
SNS 게시물마다 브랜드 톤 설명 → /sns-post 주제
이메일마다 회사 정보 입력 → /email-draft 목적

이 목록에서 하나라도 "아, 나도 이런 거 매번 하는데"라는 게 있다면, 그게 첫 번째 Skill의 후보입니다.

첫 Skill 만들기: 세 박자

디렉터리 만들기

~/.claude/skills/<이름>/ 폴더를 생성합니다

SKILL.md 적기

frontmatter와 본문을 한 페이지로 정리해 동작을 정의합니다

실행

/skills 메뉴에서 호출하거나 자동 트리거를 확인합니다

박자 ① · 디렉터리 만들기

# 모든 프로젝트에서 사용 (개인용)
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 하나만 있어도 Skill이 됩니다. 나머지 파일들은 필요가 생겼을 때 추가하면 됩니다.

💡 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                     # 이 스킬에서 쓸 모델 지정
argument-hint: [인자 설명]        # 자동완성에 뜨는 인자 힌트
arguments: required               # 인자가 필수인지 여부
effort: high                      # 사고 깊이 (low/medium/high/...)
agent: review-agent               # 특정 서브에이전트로 위임
hooks: [PreToolUse]               # 실행 시점에 걸 훅
paths: ["src/**"]                 # 적용 대상 경로 패턴
shell: bash                       # `!` 백틱 명령을 실행할 셸
---

ℹ️ 전체 필드와 최신 동작은 Skills 공식 문서를 참고하세요. 필드 이름과 기본값은 버전에 따라 달라질 수 있습니다.

세 가지 패턴을 기준으로 외워두시면 충분해요.

(기본값): 사용자도 쓸 수 있고 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에 박아두면 매번 일정하게 나옵니다.

예시 ② · 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개월의 개발 끝에...

🖥️ 개발자용 예시: 코드 리뷰 자동화

.claude/skills/review/SKILL.md:

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

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

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

실행:

/review src/auth/login.ts

🖥️ 개발자용 예시: GitHub 이슈 처리

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

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

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

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

실행:

/fix-issue 123

예시 ③ · 번역 자동화

.claude/skills/translate/SKILL.md:

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

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

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

실행:

/translate README.md ko

한 단계 위: 동적 컨텍스트 주입

! + 백틱 문법으로 스킬 실행 직전에 셸 명령을 실행해 결과를 컨텍스트에 끼워 넣을 수 있습니다. 스킬 폴더 내 보조 파일을 참조할 때는 ${CLAUDE_SKILL_DIR} 환경 변수를 사용합니다.

---
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를 넣으세요.

프롬프트를 Skill로 바꾸는 순간

Claude에게 처음 보내는 프롬프트와 Skill로 저장하는 프롬프트는 다릅니다. 처음 보내는 프롬프트는 탐색하는 단계입니다. 어떤 결과가 나올지 모르고, 여러 번 수정하면서 원하는 결과에 가까워집니다.

Skill로 저장할 시점은 "이 프롬프트면 항상 원하는 결과가 나오는구나"라고 확신이 생겼을 때입니다. 그 확신이 생기면 그 프롬프트를 SKILL.md에 옮기는 것이 자연스럽습니다.

이 전환 시점을 놓치면 다시 처음부터 탐색해야 하는 경우가 생깁니다. "지난번에 어떻게 했더라"를 기억하는 것보다, 당시에 잘 작동했던 프롬프트를 파일로 저장해두는 것이 훨씬 안전합니다.

저장 시 한 가지 규칙: 그 시점의 프롬프트를 "완벽하게" 만들려고 너무 오래 시간을 쓰지 마세요. 80%만 맞아도 저장해두고 쓰면서 개선하는 것이 더 빠릅니다. 완벽한 Skill을 만들려다 결국 아무것도 만들지 않는 것보다 낫습니다.

Skill과 CLAUDE.md의 관계

Skills와 CLAUDE.md는 다른 층에서 Claude를 설정합니다.

CLAUDE.md는 Claude가 프로젝트 전반에서 따라야 할 일반 규칙을 담습니다. "이 프로젝트에서는 항상 한국어로 답변해", "테스트는 반드시 작성해", "커밋 메시지는 Conventional Commits 형식으로" 같은 것들입니다. 세션을 시작할 때 Claude가 자동으로 읽습니다.

Skills는 특정 작업을 위한 절차를 담습니다. CLAUDE.md의 일반 규칙 위에서 동작합니다. /commit Skill을 실행하면 CLAUDE.md의 규칙(한국어로, Conventional Commits)이 자동으로 적용된 상태에서 커밋 절차가 실행됩니다.

둘의 조합: CLAUDE.md에 "이 팀에서 지켜야 할 것"을 쓰고, SKILL.md에 "이 작업을 할 때 따라야 할 절차"를 씁니다. CLAUDE.md가 기본 규칙이라면, Skills는 그 규칙 위에서 작동하는 전문 도구입니다.

안 풀릴 때

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

Skills를 처음 만들 때 흔히 막히는 순간들

Skill을 처음 만드는 분들이 자주 겪는 막힘 지점들을 정리해봤습니다.

SKILL.md를 어디에 둬야 하나: 개인용은 ~/.claude/skills/이름/SKILL.md, 프로젝트용은 .claude/skills/이름/SKILL.md. 디렉터리를 먼저 만들고 SKILL.md를 그 안에 두면 됩니다. mkdir -p ~/.claude/skills/내스킬이름 한 줄로 디렉터리가 생깁니다.

SKILL.md가 인식이 안 될 때: Claude Code를 재시작하면 대부분 해결됩니다. 또는 /skills 명령으로 현재 인식된 스킬 목록을 확인하세요.

인자 전달이 안 될 때: $ARGUMENTS는 대문자로 써야 합니다. 소문자 $arguments는 인식하지 않습니다.

Skill이 너무 많이 자동 실행될 때: description에 "~할 때 사용"을 추가하면 더 명확한 트리거 조건이 됩니다. 또는 disable-model-invocation: true를 넣어서 자동 실행 자체를 막으세요.

좋은 Skill SKILL.md를 쓰는 법

Skill을 만들면서 SKILL.md를 잘 쓰는 것이 중요합니다. 몇 가지 원칙이 있습니다.

결과물의 형태를 명시합니다. "회의록을 작성하세요"보다 "다음 형식으로 작성하세요: 날짜/참석자/결정사항/액션아이템"처럼 구체적인 형식을 줍니다. 형식을 명시하면 매번 동일한 형태가 나옵니다. 형식을 명시하지 않으면 Claude가 매번 다른 구조로 작성합니다.

단계를 번호로 나눕니다. 프로세스가 있다면 1, 2, 3으로 순서를 주세요. Claude는 순서 있는 지시를 순서 없는 설명보다 정확하게 따릅니다.

제약 조건을 씁니다. "외부 API를 호출하지 마", "파일을 수정하지 마", "영어로만 작성해" 같은 금지 조건이 있으면 명시합니다. 없으면 Claude가 재량껏 판단합니다.

예시 출력을 포함합니다. 가능하면 기대하는 출력의 예시를 Skill 폴더의 examples/ 안에 두세요. Claude가 그 파일을 보고 형식을 더 정확하게 따릅니다.

Skills와 다른 기능의 조합

Skills는 단독으로 쓸 때보다 다른 기능과 조합할 때 효과가 극대화됩니다.

Skills + MCP: MCP로 외부 도구를 연결하고, Skill로 그 도구를 쓰는 워크플로우를 저장합니다. Slack MCP를 연결하고 /weekly-summary라는 Skill을 만들면, "주간 요약 보내기" 전체 흐름이 한 줄로 자동화됩니다.

Skills + Hooks: Skill이 실행될 때 Hook으로 안전 체크를 합니다. 배포 Skill이 실행되기 전에 Safety Hook이 위험 명령을 차단하는 조합입니다.

Skills + CLAUDE.md: CLAUDE.md에 "어떤 상황에서 어떤 Skill을 쓰라"는 가이드를 쓰면 Claude가 더 적절하게 Skill을 자동 선택합니다.

첫 번째 Skill 후보 찾기

"어떤 Skill을 먼저 만들어야 하나"라는 질문을 자주 받습니다. 가장 간단한 방법은 지난 일주일 동안 Claude에게 두 번 이상 같은 요청을 했는지 떠올려보는 것입니다.

같은 요청을 두 번 했다면 Skill 후보입니다. 세 번 이상이면 지금 당장 만들어야 합니다.

저의 첫 번째 Skill은 /commit이었습니다. 커밋 메시지를 작성하는 일이 매일 있었고, 매번 "staged 변경사항 보고 Conventional Commits 형식으로 커밋해줘"를 타이핑했습니다. SKILL.md를 만들고 나서 그 타이핑이 없어졌습니다. 그것으로 충분했습니다.

💡 한 번은 이런 일이 있었습니다. 처음 Skill을 팀원에게 소개했을 때, 팀원이 "이게 그냥 텍스트 파일 하나잖아요, 이게 뭐가 대단한 거예요?"라고 했습니다. 한 달 뒤에 보니 그 팀원은 자기 팀에서 쓰는 Skill을 10개 넘게 만들어 플러그인으로 묶어 공유하고 있었습니다. 처음엔 단순해 보이지만, 막상 써보면 왜 필요한지 몸으로 이해하게 됩니다.

Skills를 팀에 도입할 때

개인이 쓰는 것과 팀이 함께 쓰는 것은 다릅니다. 팀 도입 시 미리 알아두면 좋은 것들입니다.

팀 공통 Skills는 프로젝트 루트의 .claude/skills/ 폴더에 두고 Git으로 관리합니다. 새 팀원이 git clone 하면 자동으로 모든 Skill이 사용 가능해집니다. 별도 온보딩 없이 첫날부터 /commit, /review, /meeting 같은 팀 표준 명령을 쓸 수 있습니다.

개인 Skills는 ~/.claude/skills/에 두어서 팀과 공유하지 않습니다. 자신만의 작업 스타일이나 개인 프로젝트에 특화된 Skill들이 여기에 들어갑니다.

팀에 Skill을 처음 소개할 때는 한 번에 모든 Skill을 공개하는 것보다, 가장 많이 반복되는 작업 하나를 먼저 자동화하는 것이 효과적입니다. 그 하나가 작동하는 것을 직접 보면 다른 팀원들이 자연스럽게 "나도 이런 거 만들 수 있나요?"라고 묻게 됩니다.

Skill이 비개발자에게도 가치 있는 이유

Skills가 개발자 전용 기능처럼 보일 수 있지만, 비개발자에게도 매우 유용합니다.

회사에서 매주 반복되는 문서 작업이 있다면 그것이 Skill 후보입니다. 주간 업무 보고서, 회의 결과 정리, 고객 이메일 응답 초안, 경쟁사 동향 요약... 이런 작업들은 형식이 정해져 있고 반복적입니다. 정확히 Skill이 빛나는 영역입니다.

SKILL.md를 작성하는 데 Python이나 JavaScript를 알 필요가 없습니다. 그냥 한글로 "이렇게 해줘"를 적는 것입니다. 작업 절차를 번호로 나열하고, 결과물 형식을 설명하면 됩니다. 그것이 SKILL.md의 전부입니다.

처음 Skill을 만들 때는 이미 Claude에게 보낸 적 있는 좋은 프롬프트를 SKILL.md에 옮기는 것부터 시작하세요. 새로 만들 필요도 없습니다. 잘 작동했던 프롬프트를 그대로 옮기고 $ARGUMENTS를 추가하면 됩니다.

Skills를 잘 쓰는 사람들의 공통점

Claude Code를 1년 이상 쓴 분들을 보면 Skills를 잘 활용하는 분들에게 공통점이 있습니다.

첫째, 반복이 보이면 바로 Skill로 만드는 습관이 있습니다. "어, 이거 어제도 했는데"라고 느끼는 순간 바로 SKILL.md를 열어서 작성합니다. 나중에 만들어야지 하고 미루면 결국 만들지 않게 됩니다. 그 순간의 마찰감이 가장 정확한 신호입니다.

둘째, Skill을 만들 때 결과물 형식을 정확하게 명시합니다. "보고서를 써줘"보다 "다음 형식으로 보고서를 작성해줘: 1. 요약 (3줄), 2. 주요 결정사항, 3. 다음 액션"처럼 구체적으로 씁니다. 형식이 구체적일수록 결과가 일관됩니다.

셋째, 오래된 Skill을 주기적으로 업데이트합니다. 처음 만든 Skill이 몇 달 후에는 맞지 않는 경우가 있습니다. 팀의 규칙이 바뀌거나, 더 좋은 방법을 발견하거나, 새 도구를 도입했을 때 SKILL.md도 함께 업데이트합니다. Skill은 살아있는 문서입니다.

언제 Skill을 쓰면 안 되나

Skill이 만능은 아닙니다. 적합하지 않은 경우도 있습니다.

일회성 작업은 Skill로 만들 필요가 없습니다. "한 번만 할 작업"을 Skill로 만들면 관리 비용이 더 높습니다. 두 번 이상 반복될 것이 확실할 때 만드세요.

매번 맥락이 크게 달라지는 작업도 맞지 않습니다. 전략 기획, 창의적 글쓰기, 새로운 문제 해결 같은 작업은 매번 다른 맥락이 필요해서 템플릿화하기 어렵습니다. 이런 작업은 그때그때 프롬프트를 쓰는 편이 낫습니다.

Skill이 너무 커지면 관리하기 어렵습니다. SKILL.md가 200줄이 넘어가기 시작하면, 작업을 더 작은 단위로 나누거나 별도 파일로 분리하는 것을 고려하세요. Skill은 간결할수록 유지보수가 쉽습니다.

반복 작업 자동화의 가치

매번 같은 설명을 타이핑하는 데 1분이 걸린다면, 10번이면 10분입니다. 주 5일, 매일 같은 설명을 보내면 한 달에 약 1시간이 사라집니다. 그 1시간을 다른 곳에 쓸 수 있습니다.

하지만 Skill의 진짜 가치는 시간 절약이 아닙니다. 일관성입니다. 오늘과 어제의 회의록 형식이 다르면 나중에 검색하거나 비교하기 어렵습니다. Skill을 쓰면 모든 회의록이 동일한 구조를 가집니다. 이 일관성이 나중에 축적될 때 가치가 생깁니다.

두 번째 가치는 인지 부하 감소입니다. "어떻게 시켜야 좋은 결과가 나오지"를 매번 고민하지 않아도 됩니다. 이미 잘 작동하는 Skill이 있으면 그냥 /스킬명을 부릅니다. 생각 없이 좋은 결과가 나옵니다.

세 번째 가치는 팀 지식 문서화입니다. "이 팀에서 커밋 메시지는 어떻게 써야 하나요?"라는 질문에 SKILL.md 파일을 보여주면 됩니다. 팀의 워크플로우가 파일로 기록됩니다.

실전 Skill 예시: 직접 쓰고 있는 것들

직접 만들어 쓰고 있는 Skill들을 소개합니다. SKILL.md 내용이 궁금하다면 각각의 스타일을 참고해보세요.

weekly-qa (주간 수강생 질문 정리): 매주 슬랙에서 수강생 질문을 모아 유형별로 정리하고, 다음 강의에서 다룰 내용을 제안하는 Skill입니다. Slack MCP와 연결해서 "이번 주 #강의-qa 채널에서 질문을 가져와서 유형별로 분류하고, 3개 이상 반복된 주제를 강조 표시해줘"가 한 줄 명령으로 됩니다.

content-draft (콘텐츠 초안 작성): 강의 자료나 블로그 포스트의 초안을 만드는 Skill입니다. 주제와 대상 독자를 인자로 받아서 제목 후보 3개와 본문 구조를 먼저 제안합니다. 바로 작성하는 대신 구조 확인 단계를 넣어서 방향이 틀리는 것을 막습니다.

translate-ko-en (강의 자료 번역): 한국어 강의 자료를 영어로 번역하는 Skill입니다. 단순 번역이 아니라 "기술 용어는 원문 유지, 한국 문화 맥락은 글로벌 독자에게 이해 가능한 형태로 설명, 코드 예시는 그대로 유지"라는 규칙이 들어 있습니다. 이 규칙을 매번 설명하는 대신 Skill로 저장했습니다.

debrief (강의 후 회고): 강의가 끝나면 녹화 영상의 채팅 내용과 피드백을 분석해서 "잘 된 것, 개선할 것, 수강생이 가장 많이 질문한 것" 세 가지로 정리합니다. 매주 같은 형식으로 쌓이니 나중에 비교하기 좋습니다.

이 Skill들의 공통점은 결과물 형식이 구체적이고, 처음 만들고 나서 거의 수정하지 않아도 된다는 것입니다. 형식이 명확하면 Skill도 안정적입니다.

SKILL.md 작성 시 피해야 할 패턴들

잘못 만들어진 SKILL.md는 오히려 결과를 더 나쁘게 만들 수 있습니다. 피해야 할 패턴들입니다.

너무 추상적인 지시: "좋은 커밋 메시지를 만들어줘"보다 "Conventional Commits 형식(feat/fix/docs/refactor)을 따르고, 50자 이내 제목을 작성해줘"가 훨씬 낫습니다. Claude는 추상적인 기준보다 구체적인 규칙을 더 정확하게 따릅니다.

없어야 할 것을 넣기: "완벽한 결과를 만들어줘", "최선을 다해줘" 같은 요청은 효과가 없습니다. 이런 표현 대신 구체적인 품질 기준을 씁니다. "오탈자 없이", "100자 이내로", "3가지만" 같은 것들입니다.

너무 많은 것을 한 번에 요구하기: 하나의 Skill이 10가지를 하려고 하면 모두 어설프게 됩니다. 작업을 쪼개서 각각을 별개의 Skill로 만들거나, 서브 Skill을 호출하는 구조로 만드세요.

테스트 없이 배포하기: Skill을 만들고 나서 반드시 실제로 돌려보고 결과를 확인하세요. 프롬프트가 SKILL.md에서는 완벽해 보여도 실제로 돌리면 예상과 다른 경우가 있습니다. 팀과 공유하기 전에 10번 이상 직접 써보세요.

Skills 발전 단계

처음 Skill을 만들고 나서 어떻게 발전시킬지에 대한 큰 그림입니다.

1단계는 개인 자동화입니다. 자신이 매일 반복하는 작업 1~2개를 Skill로 만들어서 개인 환경에 설치합니다. 이 단계에서 SKILL.md 작성 방법을 익히고 작동 방식을 이해합니다.

2단계는 팀 공유입니다. 충분히 사용해서 잘 작동하는 Skill을 프로젝트 폴더로 옮기고 Git에 커밋합니다. 팀원들이 함께 사용하면서 개선점이 나오면 SKILL.md를 업데이트합니다.

3단계는 플러그인 패키징입니다. 여러 프로젝트에서 재사용하거나 외부에 공유하고 싶은 Skill 묶음이 생기면 플러그인으로 패키징합니다. 플러그인은 하나의 저장소로 관리할 수 있어서 여러 프로젝트에서 동일한 버전을 사용할 수 있습니다.

4단계는 커스텀 확장입니다. 더 복잡한 워크플로우를 위해 스크립트 파일을 추가하거나, 동적 컨텍스트 주입을 활용하거나, MCP와 연결하는 방식으로 Skill을 확장합니다.

대부분의 사용자는 1~2단계로도 충분합니다. 3단계 이상은 필요가 생겼을 때 가면 됩니다.

Skill을 만들고 나서 달라지는 것

처음 Skill을 만들고 나서 일어나는 변화들입니다. 직접 경험한 순서대로입니다.

처음 한 주는 주로 기존에 자주 쓰던 프롬프트를 Skill로 옮기는 작업을 합니다. "어, 이것도 Skill이 되겠는데"라는 생각이 자주 듭니다.

두 번째 주부터는 작업 전에 "이거 Skill 있나"를 먼저 확인하는 습관이 생깁니다. Skill이 있으면 쓰고, 없으면 일단 직접 하면서 "다음엔 Skill로 만들자"는 메모를 남깁니다.

한 달 후에는 자신만의 Skill 라이브러리가 생깁니다. 자주 하는 작업의 80% 이상이 Skill로 커버됩니다. 나머지 20%는 그때그때 새로운 요청이라 Skill로 만들기 어렵거나 불필요한 것들입니다.

세 달 후에는 팀원들이 "어떤 Skill 쓰세요?"라고 묻기 시작합니다. 그때 자신의 Skill들을 보여주면 팀에서 공통 Skill 라이브러리를 만드는 대화가 시작됩니다.

이 과정이 자연스럽게 진행됩니다. 강제로 모든 작업을 Skill로 만들 필요가 없습니다. 반복이 보이는 곳에만 적용하면 충분합니다.

중요한 것은 완벽한 Skill 라이브러리를 구축하는 것이 목표가 아니라는 점입니다. 매일 쓰는 몇 가지 작업이 더 쉬워지는 것이 목표입니다. 그것만으로도 Claude Code를 쓰는 방식이 크게 달라집니다. 처음 시작은 하나로 충분합니다.

지금 이 가이드를 읽으면서 "아, 이거 자동화하면 좋겠다"라는 생각이 든 작업이 있다면 그게 바로 오늘 만들 Skill입니다. 읽기만 하고 지나가지 말고, 지금 바로 SKILL.md 파일을 하나 만들어보세요. 10분이면 됩니다. 그 10분이 앞으로의 수백 번을 바꿉니다.

아직 후보가 없다면 커밋 메시지 자동 작성 Skill부터 시작해보세요. 개발자라면 매일 필요하고, 비개발자라도 git을 쓴다면 유용합니다. 이 가이드의 예시를 그대로 복사해서 시작해도 됩니다. Skill을 한 번 만들고 나면 그 다음은 훨씬 쉽습니다. 무엇을 Skill로 만들어야 할지 자연스럽게 보이기 시작합니다. 처음 Skill 하나가 이 전환점이 됩니다. 시작은 작게, 효과는 크게. 그것이 Skills의 방식입니다. 오늘 하나를 꼭 만들어보세요.

처음 Skill을 만들면서 가장 많이 드는 생각

"이게 이렇게 간단해도 되나"입니다. SKILL.md를 처음 만들면 생각보다 훨씬 단순한 파일임을 알게 됩니다. 특별한 문법이 있는 것도 아니고, 설정이 복잡한 것도 아닙니다. 그냥 YAML 헤더 몇 줄과 한국어 지시사항입니다.

그런데 그 단순함이 강점입니다. 수정하기 쉽고, 이해하기 쉽고, 공유하기 쉽습니다. 나중에 팀원에게 "이거 어떻게 쓰는 거예요?"라는 질문을 받았을 때 SKILL.md를 열어 보여주면 됩니다. 설명할 것도 없습니다. 파일 내용이 곧 설명입니다.

Skill을 만들기 시작한 첫 달은 호기심으로 많이 만들고, 두 번째 달부터는 진짜로 가치 있는 것만 남기는 과정을 거치게 됩니다. 그러고 나면 작지만 확실히 도움이 되는 자신만의 도구 모음이 생깁니다. 그것이 Skills가 주는 가장 실질적인 선물입니다.

한 줄로

Skill = 자주 하는 작업을 /커맨드 한 줄로 만들어두는 기록. 팀에 배포할 땐 플러그인으로 묶으시면 됩니다.

다음 섹션에서는 만들어둔 Skill을 여러 Claude가 동시에 굴리는: Sub-agents의 세계로 들어갑니다.

이 장을 덮기 전에

~/.claude/skills/commit/SKILL.md 파일을 만들어봤다
/commit으로 실제 커밋 하나를 실행해봤다
지난 주에 Claude에게 두 번 이상 한 요청을 떠올려보고, 그것을 Skill로 만들 계획을 세웠다
/skills 명령으로 현재 사용 가능한 Skill 목록을 확인해봤다
팀이나 프로젝트에 공유할 만한 Skill이 있는지 생각해봤다

Sub-agents

메인 대화를 어지럽히지 않고 특정 작업을 위임하는 기본 서브에이전트 개념을 이해합니다.

참고

18. Claude가 Claude에게 일을 떼어줄 때 — Sub-agents 입문

혼자 다 하다가 벽에 부딪힌 순간, 사람은 역할을 나눕니다. 한 대화에 모든 일을 밀어 넣는 게 아니라, 메인 Claude가 특정 역할을 다른 Claude 인스턴스에 위임하는 구조가 Sub-agents입니다. 메인 대화는 깔끔하게 유지되고, 일은 병렬로 돌아갑니다. 처음에는 낯설지만, 쓰고 나면 "왜 이걸 이제 알았지"가 됩니다.

공식 문서의 Built-in subagents 섹션 출처: Sub-agents — Anthropic 공식 문서

💡 한 번은 이런 일이 있었습니다. 강의에서 한 분이 문서 20개를 단일 세션에서 모두 요약하려다가 컨텍스트가 폭발해 세션이 멈추는 상황을 겪었습니다. 그 자리에서 서브에이전트 4개로 쪼개 5개씩 담당하게 했더니 세션은 가뿐해지고 처리 시간은 4분의 1로 줄었습니다. "이게 되는 거예요?" 하던 눈빛이 지금도 기억납니다.

서브에이전트란 무엇인가

Sub-agent(서브에이전트)는 메인 Claude가 특정 작업을 별도의 Claude 인스턴스에 떼어 주는 기능입니다. 잘게 쪼개진 각 인스턴스는 다음 네 가지 특성을 가지고 자기 일만 합니다.

독립된 컨텍스트 창: 메인과 분리되어 있어 서로 간섭하지 않습니다
커스텀 시스템 프롬프트: 그 역할에만 집중하도록 설계할 수 있습니다
제한된 도구: 읽기 전용, 쓰기 전용 등 필요한 것만 쥐어줄 수 있습니다
요약 결과만 반환: 작업이 끝나면 핵심만 메인으로 돌아옵니다

팀장이 프로젝트를 받았을 때 리서치는 A에게, 번역은 B에게, 교정은 C에게 나눠 맡기는 방식입니다. Sub-agent의 작동 방식이 정확히 그 그림입니다.

그림으로 한 번 더

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

각 서브에이전트가 독립 컨텍스트에서 실행되고,
요약된 결과만 메인으로 돌아옴 → 메인 대화는 깨끗하게 유지

처음 이 구조를 그려보았을 때 멈췄던 부분은 "요약 결과만 반환"이었습니다. 탐색 로그가 수천 줄이어도 메인 창엔 5줄 요약만 돌아옵니다. 그 구조 하나가 대화가 지저분해지는 문제를 한 번에 해결합니다.

언제 서브에이전트가 맞고, 언제 단순 대화가 나은가

Sub-agent가 잘 맞는 때

대용량 출력, 독립 파일 동시 작업, 도구 제한, 탐색·구현 분리.

병렬·격리

일반 대화가 나은 때

잦은 피드백, 빠른 단순 수정, 단계가 컨텍스트를 공유해야 할 때.

중간 개입 필요

서브에이전트를 쓰면 유리한 상황

대용량 출력이 쏟아지는 작업: 테스트 로그, 문서 페치 결과가 메인 컨텍스트를 낭비할 때. 결과는 요약해서만 받으면 됩니다
독립적인 파일을 동시에 처리할 때: 같은 코드베이스의 세 모듈을 세 에이전트가 병렬로 보는 경우, 순차 처리 대비 시간이 크게 줄어듭니다
특정 도구만 허용할 때: 읽기 전용 리뷰어, DB 쿼리 전용 에이전트처럼 권한을 좁혀야 하는 경우
탐색과 구현을 분리하고 싶을 때: 탐색 결과가 구현 흐름을 오염시키지 않도록 격리

오히려 단순 대화가 나은 상황

잦은 피드백이 필요한 작업: 서브에이전트는 독립 실행이라 중간 개입이 어렵습니다
빠른 단순 수정: 에이전트 초기화 오버헤드가 작업 자체보다 클 수 있습니다
단계들이 컨텍스트를 촘촘히 공유해야 할 때: 계획·구현·테스트가 하나의 흐름으로 묶여야 할 경우

처음부터 들어있는 내장 서브에이전트 셋

Claude Code는 다음 세 종류를 기본으로 탑재하고 있습니다. 따로 만들지 않아도 이미 동작하고 있습니다.

Explore · 코드베이스 탐색 전용 · 읽기 전용 (Glob/Grep/Read 위주)
Plan · 메인 모델 상속 · 읽기 전용: Plan 모드에서 컨텍스트 수집
general-purpose · 메인 모델 상속 · 모든 도구: 복잡한 다단계 작업

코드베이스를 탐색해야 하는 순간에 Claude는 자동으로 Explore를 띄웁니다. 수천 줄짜리 탐색 결과가 메인 대화창에 쌓이지 않고, 요약만 메인으로 돌아오는 구조입니다.

💡 한 번은 이런 일이 있었습니다. WSL2 환경에서 모노레포를 통으로 분석해달라고 했더니 Explore 에이전트가 자동으로 뜨면서 메인 창엔 "13개 모듈, 핵심 의존성 5개" 한 줄만 돌아왔습니다. 그 전까지는 직접 find 명령을 써서 결과를 복붙했는데, 이 방식이 얼마나 비효율적이었는지 그 순간에야 실감했습니다.

나만의 서브에이전트 만들기: 두 가지 방법

방법 ㉠ · `/agents` 인터랙티브 메뉴 (권장)

/agents

대화창에서 바로 만들 수 있습니다. 순서는 이렇습니다.

Create new agent 선택
User-level(모든 프로젝트에서 사용) 또는 Project-level(이 프로젝트만) 선택
Generate with Claude → 역할을 말로 설명
허용할 도구 선택
모델 선택 (Haiku / Sonnet / Opus)
저장

처음 만들어보는 분이라면 이 방법이 제일 빠릅니다. 역할을 설명하면 Claude가 나머지 구조를 채워줍니다.

방법 ㉡ · 파일 직접 작성

.claude/agents/ 폴더에 마크다운 파일을 두면 즉시 인식됩니다. 실제로 자주 쓰는 세 가지 예를 그대로 가져왔습니다.

리서치 요약 에이전트 (.claude/agents/researcher.md):

---
name: researcher
description: 자료 폴더를 읽고 핵심 요약·인사이트·다음 질문을 정리합니다. 리서치가 필요할 때 자동으로 사용.
tools: Read, Grep, Glob
model: sonnet
---

당신은 리서치 어시스턴트입니다.
- 결론을 먼저 5줄로 요약
- 근거가 되는 문장·출처 파일명을 함께 표기
- "추정·가정"은 명확히 라벨링
- 마지막에 다음 조사 질문 5개를 제안

이 에이전트의 포인트는 description에 "자동으로 사용"이 적혀 있다는 점이다. 메인 Claude가 리서치 관련 요청을 받으면 스스로 이 에이전트를 선택해 위임한다.

번역 에이전트 (.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://) 누락·깨짐 의심 구간 표시
- "다음 액션"이 빠졌으면 추가 제안

QA 에이전트에는 Haiku를 붙였다. 단순 패턴 검색이라 고성능 모델이 필요 없고, 비용도 낮출 수 있기 때문이다.

🖥️ 개발자용: code-reviewer 에이전트

.claude/agents/code-reviewer.md:

---
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를 권합니다.

description은 단순 설명이 아닙니다. 메인 Claude가 "이 작업은 어느 에이전트에 맡길까?"를 판단할 때 쓰는 라우팅 기준입니다. 모호하게 적으면 엉뚱한 에이전트가 호출되거나, 자동 호출이 전혀 안 되기도 합니다.

좋은 description과 나쁜 description

나쁜 예	좋은 예
"파일을 처리합니다"	"CSV 파일을 읽고 데이터 분석 리포트를 생성합니다. 데이터 관련 요청에 자동으로 사용."
"번역을 해줍니다"	"한국어 마크다운을 영어로 번역합니다. 구조와 코드블록을 유지합니다. 번역 요청 시 자동으로 사용."
"코드 작업"	"Python 코드를 리뷰하고 버그를 찾습니다. PR 머지 전 코드 리뷰 요청 시 자동으로 사용."

저장 위치와 우선순위

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

팀과 공유할 에이전트는 .claude/agents/에 두고 Git에 커밋합니다. 개인 작업 전반에 쓸 에이전트는 ~/.claude/agents/에 둡니다. 같은 이름이 충돌할 경우 우선순위 순서대로 먼저 오는 것이 이깁니다.

실전 장면 세 가지

장면 ① · 경쟁사 동시 분석 (병렬 리서치)

"경쟁사 A·B·C를 각각 별도 에이전트로 동시에 분석해줘.
 각 에이전트는 웹사이트·가격·리뷰를 조사하고
 결과를 하나의 비교표로 통합해줘"

3개 리서치 에이전트가 동시에 돌고, 결과가 하나의 표로 합쳐집니다. 순차 처리 대비 약 3배 빠릅니다. 이 흐름을 처음 시도했을 때 놀란 점은 속도만이 아니었습니다. 각 에이전트의 결과물이 단일 세션보다 더 집중돼 있었습니다. 역할이 좁혀지니 산만함이 줄어든 것입니다.

장면 ② · PDF 20개 병렬 요약

"Downloads 폴더의 PDF 20개를 5개씩 나누어
 4개 에이전트가 동시에 요약하고
 결과를 하나의 보고서로 합쳐줘"

요약 로그가 방대해도 메인 대화는 깨끗하게 유지됩니다. 처리 속도는 약 4배입니다. 강의 자료 준비 때 이 방식을 썼더니 기존에 한 시간 걸리던 자료 요약이 15분 안에 끝났습니다. 다만 에이전트 4개가 동시에 돌면 토큰 비용도 4배에 가까워지므로, 수량이 적을 때는 단순 반복이 더 경제적입니다.

장면 ③ · 역할 분담 연쇄 처리

"researcher 에이전트로 sources/ 폴더를 읽고 1페이지 요약해줘"
"editor-qa 에이전트로 final/ 폴더 품질 점검, 수정 필요 항목만 리스트업해줘"
"translator 에이전트로 drafts/post.md를 영어로 번역해 drafts/post.en.md로 저장해줘"

각 전담 에이전트가 자기 역할만 하고, 메인 Claude는 흐름만 조율합니다. 역할이 명확히 분리되어 있으면 어느 단계에서 결과가 이상해졌는지 추적하기도 쉽습니다.

🖥️ 개발자용: 코드베이스 탐색 / 테스트 / 디버깅

병렬 코드베이스 탐색

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

→ Explore 3개가 동시에 돌고, 모듈별 분석 결과만 메인으로.

코드 리뷰 + 수정 연쇄

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

테스트 실행 격리

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

→ 테스트 로그(수천 줄)가 메인에 쌓이지 않습니다.

영구 메모리: 학습이 다음 세션까지 이어지게

Claude Code는 작업하면서 익힌 내용을 자동으로 ~/.claude/projects/<project>/memory/에 기록합니다(Auto Memory). 서브에이전트도 자체 메모리를 유지할 수 있습니다. 정확한 frontmatter 필드와 저장 경로는 공식 가이드의 "Enable persistent memory" 섹션을 함께 보시기 바랍니다. 필드 이름은 버전에 따라 달라질 수 있습니다.

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

포그라운드: 완료까지 기다립니다. 권한 요청이 사용자에게 전달됩니다
백그라운드: 동시에 실행됩니다. 다른 작업을 계속할 수 있습니다

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

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

⚠️ 백그라운드 서브에이전트는 MCP 도구를 쓸 수 없다는 점만 기억해두세요.

비용 현실: 에이전트 수만큼 청구서가 따라옵니다

서브에이전트는 각각 독립된 Claude 인스턴스입니다. 에이전트마다 토큰이 별도로 소비됩니다. 세 가지 현실을 먼저 알고 들어가세요.

3개 병렬 실행 = 토큰 사용량이 최소 3배 이상 증가
결과가 메인으로 집계될 때 추가 토큰 소모
무분별한 남용은 비용 곡선을 가파르게 올립니다

처음 서브에이전트를 알고 흥분해서 5개를 동시에 돌렸다가 하루 만에 월간 예산의 30%를 써버린 적이 있습니다. 그 뒤로 제 규칙은 하나입니다. 단일 세션으로 해결되는 일이라면 서브에이전트를 열지 않습니다.

비용을 누르는 작은 습관들:

읽기 전용 탐색은 Haiku 모델로 지정
반환할 결과의 양을 명시적으로 지정 ("핵심 5개만", "3줄 요약만")
단순 작업은 서브에이전트로 빼지 말고 메인에서 처리

에이전트 디버깅: 예상대로 안 될 때

서브에이전트를 처음 만들면 "왜 내가 원하는 에이전트를 안 쓰지?"라는 상황을 자주 만납니다. 내가 겪은 원인 세 가지입니다.

증상	원인	해결
에이전트가 자동으로 안 불림	description이 모호함	"~할 때 자동으로 사용" 문구 추가
엉뚱한 도구를 씀	tools 필드 누락 → 메인 상속	필요한 도구만 명시
결과가 너무 길게 돌아옴	시스템 프롬프트에 출력 길이 제한 없음	"5줄 이내로 요약" 등 명시
에이전트가 인식이 안 됨	파일 위치나 이름 오류	`.claude/agents/`에 소문자 하이픈 파일명 확인

처음 도입하는 분에게: 단일 Claude로 충분히 시작하세요

서브에이전트가 진짜로 필요해지는 신호는 세 가지입니다. 이 신호가 느껴지기 전까지는 굳이 도입할 필요가 없습니다.

메인 컨텍스트가 자꾸 넘쳐서 /compact가 반복될 때
같은 탐색 작업을 여러 번 반복하게 될 때
특정 도구만 쓰는 안전한 리뷰어가 별도로 필요할 때

첫 번째 커스텀 에이전트: 읽기 전용 검토자로 시작하세요

코드나 문서를 수정하는 역할보다 읽기 전용 검토자가 훨씬 안전한 출발점입니다. 실수가 나도 원본이 바뀌지 않으니 부담이 없습니다.

/agents
→ Create new agent
→ Project-level
→ 역할: "문서의 오탈자·링크 누락·표기 통일 문제만 찾아주는 검토자"
→ 도구: Read, Grep, Glob
→ 모델: Haiku 또는 Sonnet

실제 사용 예시:

"editor-qa 에이전트로 content/ko 폴더를 읽고
오탈자·제목 번호 누락·링크 깨짐 의심 항목만 보고해줘.
파일은 수정하지 말고 목록만 줘."

이렇게 읽기 전용 검토에서 손맛을 익힌 뒤, 구현과 수정 역할로 서서히 넓혀가는 것이 무리 없는 순서입니다.

에이전트 팀 설계: 더 복잡한 구조로 나아가기

처음 서브에이전트를 쓰다 보면 자연스럽게 "이걸 더 체계적으로 쓰고 싶다"는 생각이 듭니다. 에이전트 팀 구조를 설계할 때 내가 쓰는 방식을 공유합니다.

단계별로 역할 배분하기

복잡한 작업일수록 단계를 나누고 각 단계에 에이전트를 붙이는 게 효과적입니다.

수집 단계    → researcher 에이전트 (Read, Grep 전용)
             ↓
정리 단계    → editor-qa 에이전트 (Read, Write)
             ↓
번역 단계    → translator 에이전트 (Read, Write)
             ↓
품질 검사    → reviewer 에이전트 (Read 전용)

메인 Claude는 이 흐름을 조율하고 각 단계의 결과를 받아 다음 단계로 넘깁니다. 메인 컨텍스트에는 단계별 요약만 쌓입니다.

에이전트 수를 너무 늘리지 않기

경험적으로 3~4개가 적당합니다. 5개를 넘기면 다음 문제가 생깁니다:

어느 에이전트가 어떤 일을 했는지 추적이 어려워집니다
비용이 기하급수적으로 커집니다
에이전트 간 결과 통합에서 충돌이 생길 수 있습니다

💡 한 번은 이런 일이 있었습니다. 플랫폼 운영 중 콘텐츠 파이프라인을 자동화하려고 에이전트 7개를 설계했습니다. 첫 실행에서 3개가 서로 같은 파일을 수정하려 충돌하고, 결과 취합 단계에서 오케스트레이터가 컨텍스트 한도에 달했습니다. 그날 배운 건 명확합니다. 에이전트는 "최소한으로, 책임 명확하게"가 원칙입니다. 지금은 같은 파이프라인을 3개 에이전트로 돌리고 있습니다.

비개발자가 쓰는 서브에이전트 패턴

서브에이전트는 개발자만을 위한 기능이 아닙니다. 일상 업무에서도 자연스럽게 쓸 수 있는 패턴 세 가지를 정리했습니다.

패턴 ① · 리서치 → 정리 → 발행 파이프라인

마케터나 콘텐츠 제작자라면 이 흐름이 익숙할 것입니다.

1) researcher 에이전트: 키워드 관련 자료 수집 (Read, Glob)
2) writer 에이전트: 자료 기반 초안 작성 (Read, Write)
3) editor 에이전트: 맞춤법, 톤, 형식 교정 (Read, Write)

매주 같은 주제의 뉴스레터를 발행한다면, 이 파이프라인을 한 번 설계해두면 매주 같은 품질의 초안을 자동으로 받을 수 있습니다.

패턴 ② · 데이터 분석 → 요약 → 보고서

재무나 운영 담당자에게 유용한 패턴입니다.

1) data-reader 에이전트: CSV, Excel 파일 읽기 및 통계 추출 (Read)
2) analyst 에이전트: 패턴 분석과 이상값 탐지 (Read)
3) reporter 에이전트: 경영진 보고서 형식으로 정리 (Read, Write)

패턴 ③ · 다언어 동시 번역

국제적으로 일하는 분들에게 유용합니다.

"한국어 원문 → 영어·일어·중국어를 각각 별도 에이전트로 동시 번역해줘.
 각 번역본은 원문 구조와 코드블록을 그대로 유지해줘."

3개 언어를 순차로 번역하면 15분이 걸리던 일이, 3개 에이전트가 동시에 돌면 5분으로 줄어듭니다.

서브에이전트의 한계와 주의할 점

장점이 많은 만큼 한계도 분명합니다. 다음 경우는 서브에이전트가 오히려 방해가 됩니다.

반복이 없는 일회성 작업

서브에이전트 설계와 초기화에 드는 시간이 작업 자체보다 길다면, 그냥 메인에서 하는 게 빠릅니다.

에이전트 간 즉각적인 소통이 필요한 작업

에이전트 A의 결과를 실시간으로 에이전트 B가 받아야 하는 경우, 현재 구조로는 메인을 통해 순차적으로 전달해야 합니다. 진정한 실시간 협력은 아닙니다.

매우 복잡한 상태를 공유해야 하는 작업

에이전트는 독립된 컨텍스트를 가집니다. 복잡한 전역 상태를 여러 에이전트가 공유해야 한다면, 파일을 통해 중간 결과를 저장하고 다음 에이전트가 읽는 방식으로 우회해야 합니다.

⚠️ 서브에이전트에게 민감한 정보(비밀번호, API 키, 개인 식별 정보)를 건네는 것은 주의가 필요합니다. 각 인스턴스가 별도로 돌더라도 Anthropic의 일반 정책이 동일하게 적용됩니다.

실전 에이전트 레시피 모음: 복사해서 바로 쓰세요

만들어두고 자주 쓰는 에이전트 파일들을 그대로 공개합니다. 필요한 것만 골라서 .claude/agents/ 폴더에 저장하면 즉시 사용할 수 있습니다.

뉴스 요약 에이전트

---
name: news-digest
description: 링크나 텍스트 파일에서 뉴스를 읽고 핵심 요약과 시사점을 정리합니다. 뉴스 요약 요청 시 자동으로 사용.
tools: Read, Glob
model: sonnet
---

당신은 뉴스 에디터입니다.

요약 형식:
- 제목 (원문 그대로)
- 핵심 내용: 3줄 이내
- 시사점: 독자에게 미치는 영향 1줄
- 신뢰도: 출처 기반 A(공식) / B(언론) / C(블로그·SNS)

주의:
- 출처 없는 주장 금지
- 추측은 "~로 보임"으로 명시
- 관계없는 내용은 제외

주간 업무 정리 에이전트

---
name: weekly-wrap
description: 지난 7일간의 파일과 메모를 읽고 주간 업무 요약을 생성합니다. 주간 정리 요청 시 자동으로 사용.
tools: Read, Glob, Write
model: sonnet
---

지난 7일간의 작업을 정리합니다.

출력 형식:
## 이번 주 완료한 일
- (항목별 한 줄)

## 진행 중인 일
- (항목 + 현재 상태)

## 다음 주 할 일
- (우선순위 순서대로)

## 배운 것 / 메모
- (기억할 인사이트)

저장: weekly/YYYY-MM-DD-weekly.md

이미지 설명 에이전트

---
name: image-describer
description: 이미지를 분석하고 텍스트 설명을 생성합니다. 이미지 설명이나 alt 텍스트 생성 요청 시 자동으로 사용.
tools: Read
model: sonnet
---

이미지를 분석하고 다음 세 가지를 출력합니다:

1. 한 줄 설명 (alt 텍스트용, 50자 이내)
2. 상세 설명 (3~5문장, 시각 장애인을 위한 설명)
3. 핵심 키워드 (5개 이내)

주의: 사람이 명확히 식별되는 경우 얼굴 묘사는 "사람이 있습니다" 정도로만.

에이전트 협업 패턴: 세 가지 고전 구조

소프트웨어 개발에서 검증된 협업 패턴이 에이전트 설계에도 그대로 적용됩니다.

파이프라인 패턴 (순서대로 전달)

입력 → 에이전트 A → 에이전트 B → 에이전트 C → 출력

각 단계의 출력이 다음 단계의 입력이 됩니다. 리서치 → 집필 → 교정처럼 순서가 중요한 작업에 적합합니다.

장점: 흐름이 명확하고 추적이 쉽습니다.
단점: 앞 단계가 늦으면 전체가 늦습니다.

팬아웃 패턴 (동시에 분산)

입력 → 오케스트레이터 → 에이전트 A ┐
                       → 에이전트 B ├→ 집계 → 출력
                       → 에이전트 C ┘

독립적인 작업을 병렬로 처리합니다. 경쟁사 분석, 다언어 번역처럼 각각이 독립적인 경우에 적합합니다.

장점: 속도가 가장 빠릅니다.
단점: 에이전트 간 의존성이 없을 때만 사용 가능합니다.

심사 패턴 (검토 후 통과)

입력 → 생성 에이전트 → 검토 에이전트 → 승인 → 출력
                                      → 반려 → 재작성

품질 기준이 중요한 작업에 적합합니다. 작성된 초안을 다른 에이전트가 검토하고, 기준을 통과해야 출력됩니다.

장점: 결과물 품질이 높습니다.
단점: 시간이 더 걸리고 토큰 비용도 늘어납니다.

서브에이전트 × MCP: 조합했을 때 더 강해지는 경우

MCP(Model Context Protocol)와 서브에이전트를 함께 쓰면 에이전트의 영향 반경이 크게 넓어집니다. 외부 서비스에 접근하는 MCP 도구를 에이전트에 붙이면, 에이전트가 Slack에 메시지를 보내거나, GitHub에서 PR을 가져오거나, DB를 쿼리하는 일이 가능해집니다.

단, 포그라운드 에이전트만 MCP 도구를 쓸 수 있습니다. 백그라운드 에이전트에서는 MCP 도구 호출이 막혀 있다는 점을 기억하세요.

MCP 연결 방법은 15. MCP & 외부 도구 연결 섹션에서 자세히 다룹니다.

자주 묻는 것들

서브에이전트가 만든 결과물이 마음에 안 들면?
메인 Claude에게 "그 에이전트 결과를 다시 작업해줘"라고 하면 됩니다. 에이전트의 결과는 메인이 받아서 재처리할 수 있습니다. 특히 첫 실행 결과는 기대보다 낮을 수 있으니, description과 시스템 프롬프트를 조금씩 다듬어가는 게 더 빠른 방법입니다.

같은 에이전트를 여러 프로젝트에서 쓰고 싶으면?
~/.claude/agents/에 두면 모든 프로젝트에서 공유됩니다. 특정 프로젝트에만 맞는 에이전트라면 .claude/agents/에 두고 Git에 커밋합니다.

에이전트가 실수로 파일을 삭제하면?
에이전트의 tools를 Read만으로 제한하면 쓰기와 실행이 막힙니다. 처음에는 항상 도구를 최소한으로 줘야 합니다. 특히 Bash 도구는 파일 삭제나 시스템 변경이 가능하므로, 확신이 없을 때는 포함시키지 않는 게 안전합니다.

에이전트끼리 직접 통신할 수 있나요?
지금 구조에서는 에이전트끼리 직접 통신하지 않습니다. 모든 소통은 메인 Claude를 통해서 이루어집니다. 에이전트 A의 결과를 에이전트 B에게 넘기려면, 메인이 A의 결과를 받아 B에게 전달하거나, 중간 파일에 저장해서 B가 읽게 하는 방식을 써야 합니다.

에이전트 한 개가 오래 걸리면 다른 걸 할 수 있나요?
Ctrl+B로 백그라운드로 전환하면 됩니다. 단, 백그라운드로 전환하면 MCP 도구는 쓸 수 없습니다. 그냥 파일 작업이나 분석이라면 백그라운드가 편합니다.

서브에이전트를 제대로 쓰는 흐름 정리

처음부터 완벽한 에이전트 팀을 설계하려 하지 않아도 됩니다. 다음 순서로 천천히 늘려가는 게 현실적입니다.

1단계: 내장 에이전트(Explore, Plan) 자동 동작을 먼저 관찰하기
       → Claude가 언제 어떤 에이전트를 자동으로 쓰는지 파악

2단계: /agents 메뉴로 읽기 전용 검토자 하나 만들기
       → 실수해도 원본이 안 바뀌는 안전한 환경에서 시작

3단계: 실제 작업에서 "이 에이전트가 반복되네"를 느끼면 만들기
       → 필요해서 만드는 것이지, 있어서 쓰는 게 아님

4단계: 에이전트 2~3개를 연결해 파이프라인 한 번 돌려보기
       → 흐름을 직접 경험해야 감이 옴

5단계: 비용 모니터링 습관 갖기
       → /usage로 에이전트 실행 전후 비용 확인

이 순서대로 쌓아가면 6개월 뒤에는 자신만의 에이전트 팀이 자연스럽게 갖춰져 있을 것입니다.

비개발자 실전 시나리오: 완전한 하루

서브에이전트가 실제 일상에서 어떻게 동작하는지, 하루 업무 흐름으로 보여드리겠습니다.

오전 8:30 — 뉴스 브리핑 에이전트

"news-digest 에이전트로 inputs/links.txt의 링크들을 읽고
 오늘의 업계 뉴스 브리핑을 brief/today.md로 저장해줘"

에이전트가 파일을 읽고 요약을 만드는 동안, 나는 커피를 마신다. 5분 뒤 brief/today.md가 생겨있다.

오전 10:00 — 병렬 경쟁사 분석

"경쟁사 세 곳의 최근 공지를 각각 별도 에이전트로 분석해줘.
 각자 주요 변화와 우리에게 미치는 영향을 3줄씩 정리하고
 결과를 하나의 비교표로 합쳐줘."

3개 에이전트가 동시에 돌아 순차 처리 대비 작업 시간이 3분의 1로 줄었다.

오후 2:00 — 회의록 → 보고서 파이프라인

"meetings/today-strategy.md를 읽고:
 1) meeting-notes 에이전트로 액션아이템·결정사항 정리
 2) weekly-wrap 에이전트로 이번 주 업무와 통합
 reports/weekly-YYYY-MM-DD.md로 저장해줘"

회의 직후 5분 안에 보고서 초안이 나온다. 검토하고 수정만 하면 된다.

오후 5:30 — QA 에이전트로 마감 전 점검

"editor-qa 에이전트로 오늘 작성한 reports/ 폴더 전체를
 오탈자·링크·표기 통일 기준으로 점검하고
 수정 필요 항목 목록만 알려줘."

에이전트가 읽기 전용으로 점검하므로 원본은 그대로입니다. 목록만 받아서 필요한 것만 고칩니다.

이 하루 시나리오에서 에이전트가 총 6개 이상 실행됐지만, 메인 대화 창은 깨끗하게 유지됐고 내가 직접 판단하고 승인하는 구조는 변하지 않았다. 에이전트가 일을 대신하는 게 아니라, 내가 더 중요한 판단에 집중할 수 있게 잡일을 덜어준다는 게 핵심입니다.

에이전트 설계의 세 원칙

수십 개의 에이전트를 만들고 폐기하면서 남은 원칙 세 가지입니다.

첫째, 역할은 하나만. 하나의 에이전트가 여러 역할을 하면 description이 복잡해지고, Claude가 언제 그 에이전트를 쓸지 판단하기 어려워집니다. "요약도 하고 번역도 하고 교정도 하는" 에이전트보다, 각각 전담하는 에이전트 세 개가 낫습니다.

둘째, 도구는 최소한으로. 에이전트에게 필요 이상의 도구를 주면 예상치 못한 일이 일어날 수 있습니다. Read만 필요한 에이전트에 Write까지 줬다가, 에이전트가 원본 파일을 수정하는 상황을 겪은 적이 있습니다. 처음에는 Read부터, 필요해지면 그때 추가합니다.

셋째, 시스템 프롬프트는 짧고 구체적으로. 긴 시스템 프롬프트는 에이전트가 어디에 집중해야 하는지 흐릿하게 만듭니다. 핵심 규칙 3~~5개, 출력 형식 명시, 금지 사항 1~~2개가 가장 잘 작동하는 구조였습니다.

서브에이전트 운영 체크리스트

에이전트를 처음 만들고 실전에 투입하기 전, 이 목록을 한 번 훑어보시기 바랍니다.

만들 때

□ name: 소문자 + 하이픈, 15자 이내
□ description: 언제 어떤 상황에서 쓰이는지 명확히 적혔는가
□ tools: 최소한으로, 진짜 필요한 것만
□ model: 작업 복잡도에 맞는 모델인가 (단순 → Haiku, 복잡 → Sonnet/Opus)
□ 시스템 프롬프트: 역할 1줄 + 출력 형식 + 금지 사항

처음 실행할 때

□ 작은 입력으로 먼저 테스트 (전체 폴더 대신 파일 1개)
□ 결과가 예상과 다르면 description 또는 시스템 프롬프트 수정
□ /usage로 비용 확인
□ 결과물 저장 위치 확인 (파일이 어디에 생겼는지)

정기 점검 (월 1회)

□ 실제로 쓰고 있는 에이전트만 남기기 (쓰지 않으면 삭제)
□ description 업데이트 (일하다 보면 실제 용도가 바뀌기도 함)
□ 모델 선택 재검토 (비용 대비 성능 점검)
□ 팀 공유가 필요한 에이전트는 .claude/agents/로 이동

한 줄로

Sub-agent = Claude가 다른 Claude에게 일을 떼어주는 기능. 독립 컨텍스트에서 돌기 때문에 메인 대화가 깨끗하게 유지되고 병렬 처리가 됩니다. 단, 에이전트 수만큼 토큰 비용이 늘어나고, description이 모호하면 자동 호출이 안 됩니다. 처음엔 읽기 전용 검토자 하나로 시작해 필요해질 때마다 하나씩 늘려가는 게 가장 안전한 길입니다.

이 장을 덮기 전에

Sub-agent가 진짜 필요해지는 세 가지 신호를 기억했다 (컨텍스트 폭발, 반복 탐색, 도구 제한)
내장 에이전트 세 가지(Explore, Plan, general-purpose)가 이미 동작 중임을 확인했다
/agents 메뉴로 읽기 전용 검토자 하나를 만들어봤다
description이 라우팅 기준임을 이해했다 — 모호하면 자동 호출이 안 된다
에이전트 수만큼 토큰 비용이 늘어난다는 점을 인지했다

다음 장(19. 나만의 AI 워크스페이스 설계하기)에서는 Sub-agent를 포함한 CLAUDE.md·Skills·Hooks 전체를 하나의 자동화 사무실로 묶는 법을 다룹니다. 개별 부품을 알았다면, 이제 그것들을 연결할 차례입니다.

참고: 도구별 역할 요약

에이전트를 만들 때 어떤 도구를 허용할지 헷갈린다면 이 표를 참고하세요.

도구	역할	주의
Read	파일 읽기	가장 안전. 읽기 전용 에이전트의 기본
Write	파일 쓰기·수정	원본이 바뀔 수 있음. 확신할 때만
Bash	터미널 명령 실행	가장 강력하고 위험. 최소한으로
Grep	텍스트 패턴 검색	안전. 검색 전담 에이전트에 유용
Glob	파일 목록 검색	안전. 폴더 탐색에 유용
Edit	파일 부분 수정	Write보다 세밀하지만 동일한 주의 필요

에이전트 역할이 "읽고 분석"이라면 Read, Grep, Glob으로도 충분합니다. "작성하고 저장"이 필요하다면 Read, Write를 추가합니다. Bash는 꼭 필요한 경우에만, 필요한 명령만 허용하는 방식으로 제한합니다.

💡 처음 에이전트를 만들 때 Bash 도구를 포함하고 싶다면, 특정 명령만 허용하는 방식을 권장합니다. 예: Bash(git log *), Bash(grep -r *). 전체 Bash를 주면 의도치 않은 파일 삭제나 시스템 변경이 일어날 수 있습니다.

에이전트 버전 관리: 팀으로 쓸 때

혼자 쓸 때와 팀에서 함께 쓸 때 관리 방식이 달라집니다.

혼자 쓸 때

~/.claude/agents/에 두면 됩니다. 이 폴더는 Git 관리 밖이라 개인 설정이 그대로 유지됩니다. 실험적인 에이전트를 만들고 지우기 좋습니다.

팀으로 쓸 때

.claude/agents/에 두고 Git에 커밋합니다. 에이전트 파일이 프로젝트 코드와 함께 버전 관리됩니다. 팀원 누구나 같은 에이전트 구성을 쓸 수 있습니다.

변경할 때는 PR을 통해 검토받는 것이 좋습니다. 에이전트의 tools 권한 확대는 코드 변경만큼 신중하게 다루어야 합니다.

에이전트 히스토리 관리

에이전트 파일에 변경 이력을 간단히 주석으로 남겨두면 나중에 이유를 추적하기 좋습니다.

---
name: researcher
description: 자료 폴더를 읽고 핵심 요약을 정리합니다.
# 2026-04-15: 초기 생성
# 2026-05-01: sonnet → haiku로 변경 (속도 개선)
# 2026-05-10: 다음 질문 항목 추가
tools: Read, Grep, Glob
model: haiku
---

파일이기 때문에 Git blame으로 누가 언제 무엇을 바꿨는지 추적됩니다. 에이전트도 코드처럼 관리하는 습관이 팀 운영에서 특히 중요합니다.

성숙도별 에이전트 활용 단계

사용 기간에 따라 자연스럽게 달라지는 에이전트 활용 수준입니다.

입문 (1~2주차): 내장 에이전트(Explore, Plan)가 자동으로 동작하는 것을 관찰합니다. 어떤 요청에서 어떤 에이전트가 뜨는지 패턴을 파악합니다.

초급 (1개월차): /agents 메뉴로 첫 커스텀 에이전트를 만듭니다. 읽기 전용으로 시작합니다. 단일 에이전트 호출에 익숙해집니다.

중급 (3개월차): 2~3개 에이전트를 연결해 파이프라인을 만듭니다. 비용 모니터링을 습관화합니다. 팀과 에이전트를 공유합니다.

고급 (6개월+): 자신만의 에이전트 팀 구조가 안정화됩니다. 새 프로젝트를 시작할 때 에이전트 설계가 설계의 일부가 됩니다. 에이전트 간 협업 패턴이 자연스럽게 손에 잡힙니다.

지금 어느 단계에 있든, 서두를 필요는 없습니다. 필요가 생길 때 한 단계씩 올라가는 게 가장 오래가는 방법입니다. 그리고 어떤 단계에서든 가장 중요한 건 하나입니다: 에이전트가 한 일은 반드시 사람이 확인하고 승인하는 구조를 유지하는 것. 자동화의 속도와 사람의 판단 사이에서 균형을 잃지 않는 것이 서브에이전트를 오래 잘 쓰는 비결입니다.

나만의 AI 워크스페이스 설계하기

CLAUDE.md, Skills, Hooks를 조합해 나만의 자동화 사무실을 만드는 방법.

참고

19. 나만의 AI 워크스페이스 설계하기 — 처음엔 폴더 하나면 충분합니다

CLAUDE.md를 써봤고, Skills 하나를 만들어봤다면, 이제 그것들을 한 자리에 묶어볼 차례입니다. 거창한 자동화가 아닙니다. "내 일에 맞춰 일관되게 굴러가는 AI 사무실"을 만드는 일입니다. 처음에는 폴더 하나와 CLAUDE.md 한 장이면 충분합니다.

💡 한 번은 이런 일이 있었습니다. 강의에서 "AI를 제대로 쓰고 있는데 왜 매번 같은 말을 반복해야 하냐"고 묻는 분이 있었습니다. 매일 아침 Claude를 열고 "너는 콘텐츠 마케터를 위한 AI야. 항상 이 톤으로, 이 형식으로"라고 다시 설명하고 있었던 것입니다. 워크스페이스가 없으면 AI는 매번 처음부터 시작합니다. 워크스페이스가 있으면 AI는 이미 알고 있는 상태에서 시작합니다. 그 차이가 하루 30분이었습니다.

워크스페이스란 무엇인가

일반적인 AI 사용은 "질문 → 답변"의 1회성 흐름입니다. 매번 처음부터 맥락을 설명해야 합니다. 반면 워크스페이스는 역할이 정해진 AI가 내 규칙으로, 일관된 방식으로 굴러가는 시스템입니다. 한 번 깔아두면 다음 날에도, 한 달 뒤에도 같은 기준으로 일이 진행됩니다.

구성 요소를 한 줄씩으로 정리하면 이렇습니다.

CLAUDE.md: AI의 역할·규칙·지식이 들어가는 장기 기억
폴더 구조: 작업물이 자연스럽게 쌓이는 자리
Skills: 반복 작업을 /명령어 한 줄로 묶어둔 레시피
Hooks: 놓치면 안 되는 품질 기준을 코드로 강제

이 네 가지가 조화를 이루면, AI가 "이 상황에서 내가 해야 할 일"을 스스로 파악하고 일관되게 행동합니다.

설계 철학: 세 가지 역할 분담

"모든 규칙을 CLAUDE.md에 욱여넣지 마세요. Skills로 분산하고, Hooks로 강제하세요."

각각의 역할을 짧게 정리하면:

구성 요소	역할	언제 건드리나
CLAUDE.md	변하지 않는 역할과 원칙	프로젝트 성격이 바뀔 때
Skills	반복되는 작업의 흐름	같은 작업을 3번 이상 했을 때
Hooks	자꾸 놓치는 안전 기준	실수가 반복될 때

CLAUDE.md에 모든 것을 넣으면 두 가지 문제가 생깁니다. 파일이 길어질수록 Claude가 매 응답마다 읽는 토큰이 늘어나고, 규칙이 많아질수록 어떤 규칙이 적용되고 있는지 파악하기 어려워집니다.

도메인별 워크스페이스: 세 가지 청사진

시장·부동산 리서치

매물·시세·뉴스 한 자리. 자료 수집과 비교에 특화.

청사진 ㉠

콘텐츠 제작

아이디어·초안·교정·발행 흐름을 자동화합니다.

청사진 ㉡

비즈니스 운영

CRM·문서·일정의 반복 작업을 한 폴더에.

청사진 ㉢

청사진 ㉠ · 시장·부동산 리서치 워크스페이스

처음 이 청사진을 보여드렸을 때 멈췄던 칸은 "출처 등급 표기"였습니다. 출처 없이 생성된 정보와 공식 통계청 자료를 같은 신뢰도로 대하면 분석이 왜곡됩니다. CLAUDE.md 한 줄이 그 왜곡을 막습니다.

CLAUDE.md 핵심:
  - 출처 없는 주장 금지
  - 모든 수치에 출처 등급 표기 (A~E)
  - 분기별 보고서는 reports/ 폴더에 자동 저장

폴더 구조:
  inbox/      → 통계청·부동산원 자료 보관
  reports/    → 완성된 분기 보고서
  sources/    → 출처 모음·신뢰도 기록

Skills:
  /quarterly [지역]   → 지역별 분기 매매가 분석
  /summary [파일]     → 보고서 1쪽 브리프 변환

청사진 ㉡ · 콘텐츠 제작 워크스페이스

콘텐츠 작업에서 가장 자주 낭비되는 시간은 "아 이 채널은 이렇게 썼는데, 저 채널은 어떻게 쓰지?"를 반복하는 것입니다. CLAUDE.md에 채널별 형식을 박아두면 그 고민이 사라집니다.

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 사이트 개발과 Vercel 배포
이 가이드 자체의 지속적인 다듬기

한 번 제대로 설계된 워크스페이스는 계속 살아있는 결과물을 만들어냅니다. "이걸 언제 다 했지?" 싶을 때가 바로 워크스페이스가 제 역할을 하고 있는 증거입니다.

나만의 워크스페이스: 네 박자로 시작하기

거창하게 시작할 필요가 없습니다. 네 가지를 순서대로 하면 됩니다.

박자 ① · 목적부터 좁히기

먼저 자문해 보시기 바랍니다.

□ 어떤 작업을 반복하고 있나?
□ AI에게 어떤 역할을 맡기고 싶나?
□ 어떤 규칙을 일관되게 지키고 싶나?
□ 결과물이 어디에 쌓이면 좋을까?

이 네 질문에 각각 한 문장씩 답할 수 있으면 CLAUDE.md를 쓸 준비가 된 것입니다.

박자 ② · CLAUDE.md 한 장

처음에는 아래 템플릿 정도면 충분합니다. 빈 칸만 채워가시면 됩니다.

# [워크스페이스 이름]

## 역할
[AI에게 부여할 역할과 목적 — 1~2문장]

## 핵심 규칙
- [절대 지켜야 할 것 1]
- [절대 지켜야 할 것 2]
- [절대 하지 말아야 할 것]

## 폴더 구조
- [폴더명]/  → [용도]
- [폴더명]/  → [용도]

## 주요 작업 방식
[반복되는 워크플로우 설명]

처음에는 짧을수록 좋습니다. 5개 규칙으로 시작해서 필요한 것을 하나씩 더하는 방식이, 처음부터 20개를 적어두는 것보다 훨씬 오래 쓰이는 CLAUDE.md가 됩니다.

박자 ③ · 폴더 구조: 번호 prefix가 쉬워요

mkdir -p 01-inbox 02-work 03-output 04-archive

번호를 앞에 붙이면 정렬 순서가 자동으로 유지됩니다. 작업 흐름이 한눈에 보이고, 어느 폴더에 뭘 두어야 할지 헷갈리지 않습니다.

박자 ④ · 세 번 반복하는 일은 Skill로

같은 작업을 세 번 이상 하게 되면 그것이 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가 반복을 줄여줍니다.

워크스페이스 확장: 단계별로 자라나게

처음부터 완벽한 시스템을 만들려 하면 시작 자체를 못합니다. 단계별로 자라나는 게 맞는 방향입니다.

1단계: 핵심 폴더 + CLAUDE.md (첫 주)

최소한의 구조로 시작합니다.

workspace/
├── CLAUDE.md          ← 역할·규칙·폴더 설명
├── inbox/             ← 들어오는 자료
└── output/            ← 나가는 결과물

이것만 있어도 매번 맥락을 설명하는 시간이 사라집니다.

2단계: 반복 작업 Skills 추가 (2~4주차)

실제로 쓰면서 "이거 또 하네"가 생기면 그때 Skill을 추가합니다.

.claude/
└── skills/
    └── weekly-report/
        └── SKILL.md   ← 주간 보고서 생성 레시피

3단계: 품질 기준 Hooks 추가 (1~2개월차)

놓치는 것이 반복되면 Hooks로 자동화합니다.

.claude/
└── settings.json      ← Hook 설정
    → 저장 전 오탈자 체크
    → 보고서에 출처 없으면 경고

4단계: 서브에이전트 추가 (필요할 때)

컨텍스트가 폭발하거나 병렬 처리가 필요해질 때 에이전트를 추가합니다.

.claude/
└── agents/
    └── researcher.md  ← 리서치 전담 에이전트

이 순서를 지키면 처음부터 복잡한 시스템을 설계하는 것보다 훨씬 안정적인 워크스페이스가 만들어집니다.

MCP와의 조합: 손이 더 길어집니다

워크스페이스에 MCP까지 연결하면 영향 반경이 훨씬 넓어집니다.

Web Search: 자동 리서치, 실시간 정보 수집
GitHub: 코드 관리 자동화, PR 리뷰
Slack: 팀 커뮤니케이션 통합, 알림 자동화
Google Sheets: 데이터 자동 집계, 보고서 연동

자세한 연결 방법은 15. MCP & 외부 도구 연결에서 이어집니다.

자주 하는 설계 실수

오랫동안 워크스페이스를 설계하고 수강생들의 사례를 보면서 반복적으로 보이는 실수들입니다.

실수 ① · 처음부터 너무 완벽하게

"나중에 쓸 것 같은" 폴더와 규칙을 미리 만들어두는 경우입니다. 쓰이지 않는 폴더는 나중에 뭘 어디에 둬야 할지 혼란을 주고, 긴 CLAUDE.md는 토큰만 낭비합니다. 실제로 필요해질 때 추가하는 게 맞습니다.

실수 ② · CLAUDE.md에 모든 것을 넣기

CLAUDE.md는 "매 응답마다 읽히는" 파일입니다. 길수록 비용이 늘어나고 규칙의 우선순위가 흐릿해집니다. 변하지 않는 핵심 원칙만 넣고, 작업별 세부 지침은 Skills의 SKILL.md 안에 두는 게 낫습니다.

실수 ③ · 폴더 구조를 너무 깊게

# 나쁜 예
docs/2026/Q1/Jan/week1/drafts/

3단계 이상 깊어지면 파일을 어디에 뒀는지 잊어버립니다. 최대 2단계가 현실적입니다.

실수 ④ · Skills를 너무 복잡하게 만들기

Skills는 레시피입니다. 레시피가 너무 길면 따르기 어렵습니다. 하나의 Skill이 다섯 가지 이상을 하려 하면 쪼개는 게 낫습니다.

💡 한 번은 이런 일이 있었습니다. 처음 워크스페이스를 구성할 때 48개의 규칙을 CLAUDE.md에 적어뒀습니다. 한 달 뒤 어떤 규칙이 작동하고 어떤 규칙이 무시되는지 모르는 상태가 됐습니다. 지금은 CLAUDE.md를 6개월마다 한 번씩 완전히 다시 씁니다. 실제로 쓰이는 규칙만 살아남습니다.

워크스페이스 유지 보수: 살아있게 두려면

워크스페이스는 한 번 만들고 끝이 아닙니다. 사용하면서 조금씩 진화시켜야 합니다.

주간 점검 (5분)

□ 이번 주에 3번 이상 한 작업이 있나? → Skills 후보
□ CLAUDE.md에서 어기고 싶었던 규칙이 있나? → 수정 또는 삭제
□ 폴더가 지저분해졌나? → 정리

월간 점검 (15분)

□ CLAUDE.md에서 실제로 영향을 주는 규칙은 몇 개인가? → 나머지 삭제
□ Skills 중 안 쓰는 것은? → 삭제 또는 업데이트
□ 새로운 반복 작업이 생겼나? → Skill 추가
□ Hooks가 너무 자주 방해하나? → 조건 완화

이 점검을 꾸준히 하면 워크스페이스가 "만들어둔 것"이 아니라 "살아있는 도구"로 자리잡습니다.

이 장을 덮기 전에

내가 반복하는 작업 한 가지를 골랐다
그 작업을 위한 폴더 구조를 만들었다
기본 CLAUDE.md를 작성했다 (역할·규칙·폴더 설명)
첫 번째 Skill을 만들거나 계획했다
워크스페이스는 처음부터 완벽할 필요 없음을 이해했다

다음 장(20. 비용 관리 & 절약 팁)에서는 워크스페이스를 운영하면서 자연스럽게 마주하게 되는 토큰 비용의 현실과 절약 전략을 다룹니다. 잘 설계된 워크스페이스는 비용도 아껴줍니다 — 이유는 다음 장에서 설명합니다.

워크스페이스 설계의 진짜 묘미

처음 워크스페이스를 만들 때는 "이게 정말 도움이 될까?" 하는 의심이 듭니다. 당연합니다. 빈 폴더에 몇 줄짜리 CLAUDE.md 하나만 있으면 아직 아무것도 자동으로 일어나지 않습니다.

그런데 2주가 지나고 Skills 두 개가 생기고, 한 달이 지나 Hooks 하나가 추가되면, 어느 날 "아, 이게 자동으로 됐네"를 경험하는 순간이 옵니다. 내가 반복적으로 설명하던 것들이 사라지고, 결과물의 형식이 일관해지고, 실수가 줄어드는 것을 체감하는 순간입니다.

워크스페이스의 핵심은 한 번에 완성하는 것이 아니라, 쓰면서 조금씩 진화시키는 것입니다. 이번 주에 불편한 게 보이면 CLAUDE.md를 고치고, 다음 주에 반복 작업이 보이면 Skill을 하나 더하세요. 매주 조금씩 진화하는 사무실과 비슷합니다.

6개월 뒤를 한번 상상해 보시기 바랍니다. 지금 시작한 폴더 하나가, 하루 업무의 절반을 자동으로 처리하는 시스템이 되어있을 수 있습니다. 그 사이에 여러분이 한 일은 "이건 더 좋게 만들어야겠다"를 한 줄씩 적은 것뿐입니다.

워크스페이스는 한 번에 완성되지 않습니다. 쓰면서 불편한 게 보이면 CLAUDE.md를 고치고, 반복 작업이 보이면 Skill을 하나 더하세요. 매주 조금씩 진화하는 사무실과 비슷합니다. 이것이 워크스페이스 설계의 진짜 묘미입니다. 처음에는 폴더 하나로 시작해도 충분합니다. 중요한 건 "시작했다"는 사실 자체입니다. 지금 이 가이드를 읽고 있는 이 순간이, 워크스페이스를 시작하기에 가장 좋은 타이밍입니다. 터미널을 열고, 폴더를 만들고, 한 줄만 적어보세요. 거기서 시작됩니다.

비용 관리 & 절약 팁

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

참고

20. 토큰 청구서를 읽기 전에 — 비용을 이해하고 다루는 법

같은 결과를 덜 쓰고 얻는 것. 절약이 곧 효율입니다. 한 번 손에 익으면 비용 곡선이 눈에 띄게 평평해집니다. 그리고 신기한 점 하나: 비용을 줄이려는 노력이 Claude의 집중도를 함께 높여줍니다.

공식 Statusline 가이드 출처: Customize your status line — Anthropic 공식 문서

Max는 "Pro의 5배·20배" 두 티어로 제공됩니다. 정확한 가격과 시간 환산은 claude.com/pricing에서 확인하세요.

💡 한 번은 이런 일이 있었다. Claude Code를 처음 쓰던 달, API 종량제로 한 달 요금이 예상의 세 배 나왔다. 원인을 뜯어봤더니 대부분 두 가지였다. 큰 코드베이스에 막연한 질문("이 프로젝트 분석해줘")을 반복하는 것, 그리고 CLAUDE.md가 너무 길어서 매 응답마다 수만 토큰이 소비되는 것. 두 가지를 고쳤더니 다음 달에는 같은 작업량을 65%의 비용으로 처리하게 됐다. 절약의 절반은 CLAUDE.md 다이어트였다.

내 요금 구조부터 확인하기

비용 전략은 요금 구조에 따라 방향이 달라집니다. 먼저 어느 쪽인지 파악해 두세요.

구독 방식 (Claude.ai Pro · Max) 월정액 안에 Claude Code 사용이 포함됩니다. API 비용이 따로 청구되지 않습니다. 대신 5시간 롤링 한도(세션 단위)와 주간 한도(7일 단위) 두 가지가 함께 적용됩니다. /usage 명령어로 현재 한도 대비 사용량을 언제든 확인할 수 있습니다.

종량제 방식 (Anthropic API) 사용한 토큰 수만큼 청구됩니다. 입력 토큰과 출력 토큰이 각각 다른 단가로 계산됩니다. 정확한 단가는 claude.com/pricing 참고.

이 장은 "어떤 플랜을 살까"보다 이미 쓰고 있는 상태에서 사용량을 줄이는 운영법에 집중합니다. 플랜 선택 자체는 03. 요금제 안내를 보세요.

토큰이란

토큰은 Claude가 텍스트를 자르는 단위입니다. 영어는 단어 1개가 보통 1~~2 토큰, 한국어는 글자 2~~3자에 1 토큰 정도 됩니다. 대략 영어 4글자 ≈ 1 토큰으로 기억하면 편합니다.

중요한 건 "어디에서 토큰이 나가냐"입니다.

내가 보내는 메시지 → 입력 토큰
Claude의 답변 → 출력 토큰
CLAUDE.md 내용 → 매 응답마다 입력 토큰으로 소비
이전 대화 전체 → 컨텍스트로 붙어서 매번 소비
파일을 읽힐 때 → 파일 크기만큼 입력 토큰 소비

CLAUDE.md를 5,000 토큰짜리로 짰다면, 하루 100번 응답받을 때 CLAUDE.md에서만 50만 토큰이 나갑니다.

비용이 폭증하는 네 가지 패턴

직접 경험하거나 수강생 사례에서 반복적으로 본 패턴들입니다.

패턴 ①: 범위 없이 전체 파일을 통째로

"이 프로젝트를 전체적으로 분석해줘"라는 요청이 가장 비쌉니다. Claude는 보이는 파일을 다 읽으려 하기 때문입니다. 10만 줄짜리 코드베이스를 통째로 읽히면 한 번에 수십만 토큰이 소비됩니다.

패턴 ②: 긴 세션을 무관한 작업까지 이어서

한 세션에서 "앱 기능 추가 → 문서 작성 → 다른 버그 수정"을 연달아 하면, 앱 기능 관련 모든 대화가 문서 작성 단계에도 컨텍스트로 따라옵니다. 무거워질수록 토큰 낭비가 커집니다.

패턴 ③: 고성능이 필요 없는 작업에 고성능 모델

"안녕"에 Opus를 쓰는 셈입니다. 파일 요약, 단순 포맷 변환, 오탈자 검사는 Haiku로 충분합니다. Opus는 아키텍처 설계, 복잡한 알고리즘 구현, 미묘한 논리 추론에만 쓰는 게 합리적입니다.

패턴 ④: 감시 없는 자동 실행

headless 모드나 cron 작업으로 돌리면 사람이 없는 상태에서 에러가 나도 계속 재시도하며 토큰을 소비합니다. --max-turns 설정과 로그 확인 루틴이 없으면 예상치 못한 청구서를 받게 됩니다.

비용을 잡는 일곱 가지 습관

습관 ① · `/compact`으로 숨 쉬기

대화가 길어졌다 싶으면 요약해서 부피를 줄입니다. 핵심은 살리고 전체 로그는 걷어냅니다.

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

CLAUDE.md에 compact 지침을 미리 박아두면 나중에 더 정확하게 압축됩니다.

# Compact instructions

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

/clear는 컨텍스트를 통째로 비웁니다. 완전히 다른 주제로 넘어갈 때는 이게 더 깔끔합니다.

습관 ② · 요청을 좁혀서 구체적으로

모호한 요청 = 과도한 파일 탐색 = 불필요한 토큰 소비. 이 등식을 기억하세요.

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

파일명과 함수명을 명시할수록, Claude는 딱 그 파일만 읽습니다.

습관 ③ · 작업별 모델 선택

같은 일을 Opus로 하는 것과 Haiku로 하는 것의 단가 차이는 수십 배입니다. 작업 성격에 맞춰 모델을 고르는 게 가장 큰 절약입니다.

/model haiku      # 단순 작업, 파일 요약, 빠른 확인
/model sonnet     # 일반 코딩, 문서 작성
/model opus       # 복잡한 추론, 아키텍처 설계

세션 중에도 언제든 바꿀 수 있습니다.

opusplan 모드: Plan 단계는 Opus, 실행 단계는 Sonnet으로 자동 전환됩니다. 높은 품질의 계획과 합리적인 실행 비용을 동시에 잡는 방법입니다.

/model opusplan

습관 ④ · Fast Mode는 진짜 급할 때만

/fast는 Opus 속도를 약 2.5배 높여줍니다. 단, 토큰당 비용도 함께 올라갑니다. 실시간 디버깅, 빠른 반복 실험처럼 속도가 품질을 좌우하는 순간에만 잠깐 쓰세요.

ℹ️ Fast Mode는 구독 플랜의 기본 한도 밖에서 청구됩니다.

습관 ⑤ · `/usage`로 주기적으로 확인

/usage

세션 비용, 플랜 한도 대비 현황, 활동 통계를 한 번에 봅니다. /cost와 /stats는 같은 명령의 별명입니다.

처음에는 하루 한 번만 들여다봐도 됩니다. 어떤 작업이 토큰을 많이 쓰는지 패턴이 눈에 보이기 시작합니다. 보이지 않으면 통제할 수 없습니다.

습관 ⑥ · CLAUDE.md 주기적 다이어트

CLAUDE.md는 매 응답마다 읽힙니다. 길이가 곧 비용입니다. 실제로 측정한 결과: 19,000 토큰짜리 CLAUDE.md를 9,000 토큰으로 줄였더니 같은 작업 비용이 거의 절반이 됐습니다. 그리고 응답 집중도는 오히려 올라갔습니다.

[ 지워도 되는 것 ]
- 배경 설명 ("이 프로젝트는 2023년부터...")
- 당연한 반복 ("항상 최선을 다해주세요")
- 예시 코드 여러 개 (하나만 남기거나 삭제)
- 모호한 규칙 ("좋은 코드를 작성하세요")

[ 반드시 남길 것 ]
- 절대 하지 말아야 할 것 (금지 사항)
- 기술 스택 요약 (1~3줄)
- 자주 참조하는 파일 경로
- 언어·포맷 규칙 (구체적인 것만)

3개월에 한 번씩 CLAUDE.md를 다시 읽고 "지금도 이 규칙이 필요한가?"를 자문해 보세요.

습관 ⑦ · 큰 폴더를 deny 룰로 차단

node_modules, .next, dist 같은 폴더는 Claude가 실수로 통째로 읽을 수 있습니다. 미리 차단해두는 게 안전합니다.

.claude/settings.json 또는 ~/.claude/settings.json:

{
  "permissions": {
    "deny": [
      "Read(./node_modules/**)",
      "Read(./.next/**)",
      "Read(./dist/**)",
      "Read(./build/**)",
      "Read(./coverage/**)"
    ]
  },
  "respectGitignore": true
}

respectGitignore: true(기본값)는 .gitignore 패턴을 Claude의 파일 picker에도 적용합니다. 빌드 산출물은 자동으로 제외됩니다.

⚠️ deny 룰은 Claude의 내장 파일 도구만 막습니다. Bash(cat·grep)로 같은 경로에 접근하는 것은 막지 못합니다. 더 강한 격리가 필요하면 sandboxing을 사용하세요.

모델별 비용 위치

Haiku: 가장 빠르고 저렴. 파일 요약·간단한 질문·단순 작업
Sonnet: 균형 잡힌 성능. 일반 코딩·문서 작업
Opus: 최고 성능. 복잡한 추론·아키텍처 설계 (가장 비쌈)
Opus + Fast: Opus 속도 2.5배, 단가 더 높음

정확한 단가는 claude.com/pricing을 참고하세요.

구독 플랜 사용자에게

Claude.ai Pro 또는 Max 구독자라면 API 종량제 걱정 없이 Claude Code를 쓸 수 있습니다. 월정액에 포함되어 있습니다.

별도 API 키 불필요
비용 걱정 줄고 실험 자유도 올라감
Max는 더 높은 사용량 한도

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

팀 단위 관리

API를 팀으로 쓴다면 이 세 가지를 챙기세요.

Workspace 지출 한도: Anthropic Console에서 팀 전체 한도 지정
사용량 대시보드: 팀원별 비용·사용량 확인 가능
병렬 작업 조심: 서브에이전트 여러 개를 동시에 돌리면 토큰이 빠르게 쌓입니다

비용 최적화의 실제 흐름: 하루 패턴

이렇게 하루를 운영하면 비용 낭비가 눈에 띄게 줄어듭니다.

아침: /usage로 전날 사용량 확인
      → 예상 밖으로 많이 쓴 세션이 있으면 이유 분석

작업 시작: 새 세션 또는 /clear로 깨끗하게 시작
           → 전날 작업 내용이 오늘 컨텍스트에 따라오지 않게

작업 중: 파일명 구체적으로 → "@auth.ts의 login 함수만"
         반복 탐색이 생기면 → 서브에이전트 Explore로 격리
         단순 확인은 → /model haiku로 전환

세션 전환: 작업이 바뀌면 /clear 또는 새 세션
           → "이 작업이 끝났으면 다음 주제는 새 세션"이 기본 습관

긴 작업 중간: /compact으로 주기적 정리
              → "지금까지 진행 상황 중심으로 요약"

하루 마무리: /usage로 오늘 사용량 최종 확인
             → 이상 급등 체크

이 패턴을 꾸준히 유지하면 2주 안에 전달 대비 20~30% 절약이 체감됩니다.

실전 비용 분석: 내 작업을 뜯어보기

Claude Code를 쓰면서 어디서 토큰이 많이 나가는지 파악하는 방법입니다.

1단계: 작업 유형별 분류

하루 작업을 크게 세 가지로 나눠봅니다.

탐색 (Explore): 파일 읽기, 코드 검색, 현황 파악
구현 (Implement): 코드 작성, 문서 생성, 파일 수정
검토 (Review): 결과 확인, 품질 점검, 오탈자 검사

탐색은 대부분 Haiku로 충분합니다. 구현은 Sonnet이 기본. 검토는 읽기 전용이라 Haiku나 Sonnet이면 됩니다. Opus는 설계와 복잡한 추론에만.

2단계: 세션 패턴 점검

다음 질문에 "예"가 많을수록 비용 낭비 가능성이 높습니다.

□ 같은 파일을 하루에 3번 이상 다시 읽게 했다
□ 무관한 두 가지 작업을 같은 세션에서 했다
□ CLAUDE.md를 마지막으로 정리한 게 한 달 넘었다
□ node_modules나 .next 폴더 관련 오류를 봤다
□ 자동화 작업이 조용히 실패하면서 재시도를 반복했다

3단계: 프로젝트별 비용 추적

여러 프로젝트를 병행한다면, 프로젝트별로 세션을 분리해 두면 나중에 "/usage 확인 시 어느 프로젝트가 얼마나 썼는지" 파악하기 쉬워집니다.

서브에이전트 비용: 별도 계산

서브에이전트를 쓰기 시작하면 비용 계산이 복잡해집니다. 각 에이전트는 독립된 인스턴스이고, 에이전트마다 토큰이 별도로 소비됩니다.

서브에이전트 비용 관련 핵심 세 가지:

에이전트 수 × 각 에이전트의 작업 토큰 = 총 비용

병렬 에이전트 3개를 돌리면 단순히 3배가 아니라, 에이전트 간 결과 집계에 추가 토큰이 더 붙습니다. 처음에는 이 점을 몰라서 예상보다 비용이 크게 나오는 경우가 많습니다.

에이전트 모델 선택이 큰 차이를 만든다

리서치 전담 에이전트는 Haiku, 코딩 에이전트는 Sonnet, 설계 에이전트는 Opus. 이 조합이 에이전트 팀 전체를 Opus로 돌리는 것과 비교해 비용이 3~5배 차이 납니다.

반환 결과를 제한하면 집계 비용이 줄어든다

에이전트 시스템 프롬프트에 "결과는 5줄 이내로" "핵심 3가지만"을 명시하면, 에이전트가 메인으로 돌려보내는 결과가 줄어들고 집계 단계의 토큰도 줄어듭니다.

CLAUDE.md 토큰 계산: 직접 해보기

내 CLAUDE.md가 얼마나 많은 토큰을 쓰는지 체감해 보는 방법입니다.

Claude Code 내에서:

"CLAUDE.md 파일의 토큰 수를 대략 계산해줘"

또는 직접 계산:

영어 4글자 ≈ 1 토큰
한국어 2~3글자 ≈ 1 토큰
코드 블록은 비교적 토큰 효율이 낮음

1,000 토큰짜리 CLAUDE.md × 하루 100 응답 = 하루 10만 토큰이 CLAUDE.md에서만 나갑니다. 5,000 토큰이라면 50만 토큰. 이 계산을 해보면 CLAUDE.md 다이어트가 얼마나 직접적인 효과를 내는지 체감됩니다.

프롬프트 캐싱: 종량제 사용자라면 알아둘 것

Anthropic API를 직접 쓰는 분들에게 알아두면 유용한 기능입니다.

Claude는 반복되는 긴 컨텍스트(CLAUDE.md, 프로젝트 파일 등)에 대해 프롬프트 캐싱을 지원합니다. 처음 로딩 후에는 캐시된 내용을 재활용해서 비용이 줄어드는 구조입니다.

Claude Code는 자동으로 캐싱을 활용하려 하지만, 컨텍스트 구조에 따라 효율이 달라집니다. CLAUDE.md가 세션 초반에 한 번만 읽히고 그 뒤로는 캐시에서 가져온다면 비용이 상당히 줄어들 수 있습니다.

자세한 캐싱 동작은 공식 문서를 참고하세요.

비용이 갑자기 늘어났을 때 점검 순서

예상보다 비용이 크게 나왔다면, 이 순서로 점검하세요.

1. /usage 명령으로 최근 세션 비용 확인

가장 비쌌던 세션이 어느 것인지 확인합니다. 날짜와 시간대를 파악해두면 다음 단계로 좁혀가기 쉽습니다.

2. 해당 세션에서 무엇을 했는지 떠올리기

세션이 길었나요? 큰 파일을 여러 번 읽혔나요? 서브에이전트를 많이 돌렸나요? 대부분 이 세 가지 중 하나입니다.

3. CLAUDE.md 크기 확인

wc -c ~/.claude/CLAUDE.md  # 전역
wc -c .claude/CLAUDE.md    # 프로젝트

파일 크기가 10KB를 넘어가면 다이어트를 고민해야 합니다.

4. 자동화 스크립트 확인

headless 모드나 cron 작업이 돌고 있다면, 정상 종료되고 있는지 로그를 확인합니다. 에러 후 무한 재시도 패턴이 비용 폭증의 주범인 경우가 많습니다.

5. 허용된 도구 범위 재점검

서브에이전트나 headless 작업에서 필요 이상으로 넓은 도구를 허용하면, Claude가 더 많은 파일을 읽고 더 많은 작업을 시도합니다.

구독 플랜 vs API: 어느 쪽이 더 저렴할까

이 질문은 사용 패턴에 따라 달라집니다.

구독 플랜이 유리한 경우

매일 꾸준히 쓰는 경우
한 달에 토큰 사용량이 많은 경우
비용 예측이 어려운 탐색적 작업이 많은 경우

API 종량제가 유리한 경우

가끔만 쓰는 경우
특정 프로젝트에만 쓰고 완료 후 안 쓰는 경우
사용량이 매우 적고 예측 가능한 경우

내 경험으로는 Claude Code를 주요 도구로 쓴다면 Pro 이상 구독이 거의 대부분의 경우에 더 경제적입니다. 하루 2~3시간 이상 쓴다면 종량제 비용이 구독료를 금방 넘어갑니다.

비용 인식이 습관이 되면

처음에는 비용을 신경 쓰는 게 번거롭게 느껴질 수 있습니다. 그런데 몇 주 지나면 자연스럽게 달라지는 게 있습니다.

요청을 더 구체적으로 쓰게 됩니다. 파일명을 명시하고, 어떤 부분인지 짚어주게 됩니다. 그게 비용 절약이기도 하지만, 동시에 Claude가 더 정확한 결과를 내게 만드는 방법이기도 합니다.

세션을 자주 정리하게 됩니다. /clear와 /compact를 습관적으로 쓰면 대화가 깔끔하게 유지됩니다. 그게 비용을 낮출 뿐 아니라 Claude의 집중도도 높입니다.

CLAUDE.md가 가벼워집니다. 실제로 효과 있는 규칙만 살아남게 되면서, 짧고 강력한 CLAUDE.md가 만들어집니다.

비용 의식은 단순히 돈을 아끼는 것이 아니라, Claude와 더 효율적으로 협업하는 방법을 발견하는 과정이기도 합니다.

💡 한 번은 이런 일이 있었다. 강의에서 만난 한 분이 한 달 후에 "비용 절약 하려다 보니 프롬프트 실력이 늘었다"는 피드백을 줬다. 구체적으로 쓰고, 파일을 명시하고, 불필요한 탐색을 줄이다 보니 결과 품질도 함께 올라갔다는 것이다. 절약과 품질은 실제로 같은 방향을 가리키고 있었다.

비용 최적화 실험: 한 작업으로 직접 비교해보기

비용 차이를 체감하는 가장 빠른 방법은 같은 작업을 두 방식으로 해보는 것입니다.

실험 방법

/usage로 현재 비용 기록
막연한 요청으로 한 가지 작업 실행 ("이 폴더 분석해줘")
/usage로 비용 증가 확인
/clear로 초기화
구체적인 요청으로 같은 작업 다시 실행 ("01-main.py의 parse_data 함수 로직 설명해줘")
/usage로 비용 증가 다시 확인

두 번의 비용 차이를 보면 "구체적 요청"의 효과가 숫자로 보입니다. 처음 이 실험을 해봤을 때 3~4배 차이를 경험했습니다.

학생·개인 사용자를 위한 현실적 팁

Claude Code를 배우거나 개인 프로젝트에 쓰는 분들에게 맞는 접근입니다.

처음 1개월: API 종량제로 시작하기

얼마나 쓰는지 감을 잡기 전에 구독 플랜을 사는 것보다, 종량제로 시작해서 실제 사용량을 파악하는 게 좋습니다. 생각보다 적게 쓰는 경우도 있고, 생각보다 많이 쓰는 경우도 있습니다.

사용량이 늘면 구독 플랜 검토

하루 1~2시간 이상 꾸준히 쓰게 되면 Pro 구독이 종량제보다 저렴해지는 시점이 옵니다. 그때 전환하면 됩니다.

학습할 때는 작은 예제부터

큰 프로젝트 전체에서 연습하면 토큰이 빠르게 소비됩니다. 학습 목적이라면 작은 파일·작은 기능에서 시작하는 게 비용과 학습 효율 모두에 좋습니다.

오류가 반복되면 멈추기

Claude가 같은 오류를 3번 이상 반복하면 접근 방식을 바꿔야 합니다. 같은 요청을 반복해도 같은 결과가 나오고 토큰만 낭비됩니다. 새 세션에서 다른 각도로 시작하거나, 더 작은 단위로 쪼개 시도해 보세요.

상태 표시줄: 비용을 실시간으로 보기

터미널 하단의 상태 표시줄(status line)을 설정해두면 컨텍스트 사용량이 실시간으로 보입니다. 자세한 설정법은 17번 섹션(Statusline & 비용 가시화)에서 다룹니다.

간단히 요약하면: 상태 표시줄에 현재 컨텍스트 사용량과 비용을 표시하도록 설정하면, /usage 명령을 따로 치지 않아도 얼마나 쓰고 있는지 항상 볼 수 있습니다. 비용 인식을 자동화하는 가장 쉬운 방법입니다.

상태 표시줄은 CLAUDE.md나 ~/.claude/settings.json에서 조정할 수 있습니다. 커스터마이징 방법은 공식 Statusline 가이드를 참고하세요. 비용을 눈앞에 두고 일하면 자연스럽게 더 효율적인 방식을 찾게 됩니다. 숫자가 보여야 행동이 바뀝니다. 이 가이드를 읽은 뒤 바로 해볼 수 있는 첫 번째 행동이 바로 상태 표시줄 설정입니다.

비용 절약 체크리스트

✅ 작업이 끝나면 /clear로 컨텍스트 초기화
✅ 무관한 작업은 새 세션에서 시작
✅ 구체적인 파일명·함수명 명시
✅ 단순 작업은 Haiku 모델 사용
✅ Fast Mode는 결정적인 순간에만
✅ /usage로 주기적 점검 (/cost·/stats도 같은 명령)
✅ CLAUDE.md에 compact 지침 설정
✅ CLAUDE.md는 핵심만 남기고 주기적으로 다이어트
✅ permissions.deny + respectGitignore로 대용량 폴더 차단
✅ 서브에이전트 모델은 역할에 맞게 최적화
✅ 에이전트 반환 결과는 "핵심만"으로 제한

이 장을 덮기 전에

내 요금 구조(구독제 vs 종량제)를 확인했다
/usage로 현재 세션 비용을 직접 확인해봤다
CLAUDE.md에서 지울 수 있는 규칙 하나를 찾았다
작업 성격에 따라 모델을 달리 쓰는 기준을 세웠다

다음 장(21. Headless & 자동화 참고)에서는 비용 관리가 더 중요해지는 사람 없는 자동 실행 시나리오를 다룹니다. 자동화를 시작하기 전에 이 장이 먼저인 게 맞는 순서입니다.

Headless & 자동화 참고

나중에 필요한 자동 실행 방식과 주의점을 참고합니다.

참고

21. 책상 없이도 일하게 만들기 — Headless 모드 & 자동화 실전

퇴근하고 나서도, 잠자는 동안에도, Claude가 맡겨둔 일을 처리하고 있다면. 매일 아침 커피를 내리는 동안 브리핑이 이미 파일로 쌓여 있다면. Headless 모드가 여는 풍경이 바로 그것입니다. 단, 열기 전에 비용과 보안이라는 현실을 먼저 직면해야 합니다.

Claude Code GitHub Actions 공식 가이드 출처: Claude Code GitHub Actions — Anthropic 공식 문서

💡 한 번은 이런 일이 있었다. 강의를 시작하면서 매주 월요일마다 피드백 폴더를 열고, 파일들을 읽고, 요약을 만드는 데 30분씩 썼다. 어느 날 headless 스크립트 하나를 cron에 올렸더니, 월요일 오전 9시에 책상 앞에 앉으면 이미 요약 파일이 만들어져 있었다. 처음에는 "설마 이게 됐겠어?" 하고 파일을 열어봤는데 제대로 정리가 돼 있었다. 지금은 비슷한 방식으로 서너 개의 정기 작업을 자동화해 두었다.

Headless 모드란

평소의 Claude Code는 터미널에서 사람과 주고받는 대화형입니다. 반면 Headless 모드는 사람이 없는 자동 실행입니다. 스크립트 안에서 Claude Code를 프로그램처럼 호출합니다.

공식 문서에서는 claude -p 또는 --print로 호출하는 비대화형(non-interactive) 모드라고 부릅니다. (Agent SDK는 별도 제품이며, 이 CLI 모드와는 다릅니다.) 핵심은 -p 플래그입니다.

대화형: claude (터미널 실행 → 사람이 타이핑)
자동형: claude -p "작업 내용" (스크립트에서 호출)

언제 자동화가 맞는가

세 가지 조건이 갖춰지면 자동화를 고려할 만합니다.

① 반복성: 매일, 매주, 또는 정기적으로 같은 작업을 합니까?

② 예측 가능성: 입력 형태와 출력 형태가 매번 비슷합니까?

③ 긴급성 없음: 결과를 즉시 확인하지 않아도 됩니까?

이 세 가지가 "예"라면 자동화 후보입니다. 하나라도 "아니오"라면 수동으로 하는 게 더 안전합니다.

잘 맞는 자동화 작업:

매일 아침 업계 뉴스를 수집하고 요약하기
매주 금요일 한 주치 회의록을 한 장 보고서로 만들기
폴더 안의 PDF를 일괄 요약하기
아이디어 폴더에서 다음 주 콘텐츠 캘린더 만들기
정기적인 데이터 파일 분석과 리포트 생성

맞지 않는 작업:

판단이 필요한 의사결정 작업
결과를 즉시 검토하고 방향을 수정해야 하는 작업
오류 발생 시 즉각 대응이 필요한 중요 시스템

기본 사용법

`-p` 플래그: 비대화형 실행의 핵심

# 가장 기본적인 형태
claude -p "이 폴더의 파일들을 요약해줘"

# 도구 권한을 명시하며 실행
claude -p "Downloads/의 PDF를 읽어 요약집.md로 저장해줘" \
  --allowedTools "Read,Write"

# 특정 모델 지정
claude -p "회의록을 요약해줘" \
  --allowedTools "Read,Write" \
  --model sonnet

출력 형식 선택

# 일반 텍스트 (기본)
claude -p "..." 

# JSON 구조체 (스크립트 파싱용)
claude -p "..." --output-format json

# 실시간 스트리밍 JSON
claude -p "..." --output-format stream-json

JSON 형식은 세션 ID, 비용 메타데이터, 응답 텍스트가 구조화되어 나옵니다. 자동화 파이프라인에서 다음 단계로 세션 ID를 넘겨야 할 때 유용합니다.

최대 반복 횟수 제한

# Claude가 최대 5번만 도구를 호출하게 제한
claude -p "..." --max-turns 5

자동화에서 --max-turns는 거의 필수입니다. 이 제한이 없으면 에러가 생겼을 때 Claude가 무한히 재시도하면서 토큰을 소비할 수 있습니다.

실전 자동화 레시피 다섯 가지

실제로 검증한 패턴들입니다.

레시피 ① · 일일 뉴스 브리핑

#!/bin/bash
# 매일 오전 8시 실행
DATE=$(date +%Y-%m-%d)
claude -p "inputs/links.txt를 읽고 오늘의 업계 뉴스 요약을 daily/brief-${DATE}.md로 저장해줘" \
  --allowedTools "Read,Write" \
  --max-turns 5 \
  --model haiku

비용을 낮추기 위해 Haiku를 씁니다. 뉴스 요약은 고성능 모델이 필요하지 않습니다.

레시피 ② · 주간 회의록 정리

#!/bin/bash
# 매주 금요일 오후 5시 실행
WEEK=$(date +%Y-W%V)
claude -p "meetings/ 폴더에서 이번 주 회의록을 읽고 
미완료 액션아이템과 결정사항을 정리해 weekly/${WEEK}-summary.md로 저장해줘" \
  --allowedTools "Read,Write" \
  --max-turns 5 \
  --model sonnet

레시피 ③ · PDF 일괄 요약

#!/bin/bash
# 필요할 때 수동 실행
FOLDER=$1  # 인수로 폴더 지정
claude -p "${FOLDER}의 PDF 파일들을 각각 읽고 
파일명_summary.md 형식으로 요약 파일을 같은 폴더에 저장해줘" \
  --allowedTools "Read,Write,Bash" \
  --max-turns 10 \
  --model haiku

레시피 ④ · 콘텐츠 캘린더 초안

#!/bin/bash
# 매주 목요일 오후 실행
NEXT_WEEK=$(date -d "next monday" +%Y-W%V 2>/dev/null || date +%Y-W%V)
claude -p "ideas/ 폴더를 읽고 다음 주 평일 5일치 콘텐츠 캘린더를 만들어 
drafts/calendar-${NEXT_WEEK}.md로 저장해줘" \
  --allowedTools "Read,Write" \
  --max-turns 5

레시피 ⑤ · 대화 이어가기

# 첫 번째 요청
claude -p "이 폴더의 문서들을 분석해줘" --output-format json > result1.json

# 같은 세션에서 이어서
claude -p "핵심 결론만 따로 정리해줘" --continue

# 여러 세션 중 선택해서 이어서
claude --resume

cron으로 정기 실행 설정하기

macOS·Linux에서 cron으로 정기 자동화를 설정합니다.

crontab -e

cron 표현식 기본 형식:

분 시 일 월 요일 명령어
0 9 * * * cd ~/workspace && claude -p "..."

자주 쓰는 cron 표현식:

# 매일 오전 9시
0 9 * * *

# 매주 월요일 오전 9시
0 9 * * 1

# 매주 금요일 오후 5시
0 17 * * 5

# 평일 오전 8시
0 8 * * 1-5

처음에는 반드시 파일 저장만 합니다. Slack·이메일·Notion으로 직접 보내는 것은 며칠 동안 파일 결과를 먼저 확인한 뒤에 붙이세요.

실행 전 체크리스트

□ 결과가 파일로만 저장되는가?
□ --max-turns로 반복을 제한했는가?
□ 민감한 정보가 외부로 전송되지 않는가?
□ 실패 시 로그를 확인할 방법이 있는가?
□ 처음엔 수동으로 한 번 돌려봤는가?
□ 비용 영향을 추정해봤는가?

비용: 자동 실행은 감시가 필요합니다

자동화의 가장 위험한 순간은 "조용히 실패"할 때입니다. 에러가 생겨도 아무 알림이 없고, Claude가 계속 재시도하면서 토큰만 소비합니다.

비용을 통제하는 세 가지:

--max-turns 설정: Claude의 도구 호출 횟수를 제한합니다. 단순 작업은 3~5, 복잡한 작업도 10이면 충분합니다.

Haiku 모델 우선: 자동화된 정보 처리나 요약은 Haiku로 충분합니다. Opus를 자동화에 쓰면 비용이 빠르게 쌓입니다.

실행 빈도 최소화: "매 분마다" 대신 "하루 한 번"이 낫습니다. 꼭 필요한 빈도만 설정하세요.

⚠️ 자동화된 작업은 /usage에서 세션 비용으로 확인할 수 없는 경우가 있습니다. Console에서 API 사용량을 정기적으로 점검하는 습관이 필요합니다.

보안: 자동화 파이프라인에서 지킬 것들

API 키 관리

# 잘못된 방법 — 코드에 직접 하드코딩
ANTHROPIC_API_KEY="sk-ant-api03-..."

# 올바른 방법 — 환경 변수 사용
export ANTHROPIC_API_KEY="$(cat ~/.config/anthropic-key)"

# GitHub Actions에서
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

API 키가 코드에 직접 들어가면 Git 히스토리에 남아 나중에 문제가 됩니다.

최소 권한 원칙

자동화 스크립트에 필요 이상의 도구 권한을 주면 예상치 못한 일이 생깁니다.

# 읽기와 저장만 필요한데 Bash까지 허용 → 위험
--allowedTools "Read,Write,Bash"

# 딱 필요한 것만
--allowedTools "Read,Write"

# Bash가 꼭 필요하면 특정 명령만
--allowedTools "Read,Write,Bash(ls *),Bash(cat *)"

결과 검증 없이 자동 적용 금지

자동화가 생성한 파일을 검토 없이 곧장 발송하거나, 자동 커밋·배포하는 파이프라인은 신중하게 설계해야 합니다. 특히 처음 몇 주는 반드시 사람이 결과를 확인하고 승인하는 단계를 두세요.

자동화 실패 대응 패턴

자동화는 처음엔 잘 돌다가 조용히 멈추는 경우가 있습니다.

로그 남기기

# 실행 결과와 에러를 파일에 기록
claude -p "..." --allowedTools "Read,Write" \
  >> logs/$(date +%Y-%m-%d).log 2>&1

실패 감지

if ! claude -p "..." --max-turns 5 > output.md; then
  echo "$(date): 자동화 실패" >> error.log
  # 필요하면 Slack 알림 추가
fi

흔한 실패 원인과 해결

원인	증상	해결
입력 파일 없음	빈 출력 또는 에러	파일 존재 여부 먼저 확인
토큰 한도 초과	중간에 잘림	--max-turns 줄이거나 입력 범위 축소
API 키 문제	인증 에러	키 유효성 확인
출력 경로 없음	저장 실패	폴더 미리 생성

처음 자동화를 시작하는 분에게

지금 당장 꼭 해야 하는 기능이 아닙니다.

Claude Code 기본 사용법·CLAUDE.md·Skills를 먼저 손에 익히세요. 자동화는 그 다음입니다. 손으로 3~5번 반복한 작업이 생겼을 때, 그 작업을 자동화하는 것이 맞는 순서입니다.

이 섹션은 "나중에 필요해질 때 참고"용입니다. 지금은 있다는 것만 알아두세요.

이 장을 덮기 전에

Headless 모드가 "사람 없는 자동 실행"임을 이해했다
-p 플래그와 --max-turns의 역할을 파악했다
API 키를 코드에 직접 넣으면 안 된다는 것을 확인했다
처음에는 파일 저장만 하고 외부 전송은 검증 후에 붙인다

다음 장(23. Git Worktree로 병렬 작업하기)에서는 자동화와 함께 쓰면 더 강력한 컨텍스트 분리 전략을 다룹니다. 여러 Claude를 동시에 돌릴 때 충돌을 피하는 방법입니다.

자동화의 성숙도: 단계별로 발전하기

자동화를 처음 시작할 때와 6개월 뒤의 방식은 다릅니다. 어디에 있든 다음 단계로 한 발씩 나아가면 됩니다.

단계 0: 수동 실행 가장 안전한 시작점입니다. 스크립트를 직접 실행하고 결과를 매번 확인합니다. 자동화라고 할 수는 없지만, 반복적인 작업을 명령 하나로 줄이는 것만으로도 큰 차이입니다.

단계 1: 파일 저장 자동화 결과를 파일로만 저장합니다. cron으로 정기 실행하되, 그 결과물을 사람이 매일 직접 열어봅니다. 처음 2~4주는 이 단계에서 품질을 검증하는 데 써야 합니다.

단계 2: 내부 알림 추가 결과 파일이 생기면 Slack 채널이나 이메일로 알림을 보냅니다. 아직 사람이 확인하고 판단하는 구조이지만, 알림이 오면 따로 폴더를 열어보는 번거로움이 줄어듭니다.

단계 3: 일부 자동 발송 검증이 충분히 됐다고 판단하는 작업에 한해, 결과물을 자동으로 발송하거나 공유합니다. 이 단계에서는 실패 감지와 로그 확인이 필수입니다.

단계 4: 파이프라인 연결 여러 자동화가 서로 연결되어 결과물이 다음 단계의 입력이 됩니다. 예를 들어, 뉴스 수집 자동화가 끝나면 요약 자동화가 시작되고, 요약이 완성되면 카드뉴스 초안 생성이 트리거되는 식입니다. 이 단계는 각 단계가 충분히 검증된 뒤에만 시도하세요.

자동화 vs 직접 실행: 판단 기준

모든 반복 작업을 자동화할 필요는 없습니다. 판단하는 기준 세 가지입니다.

자동화가 맞는 경우

작업의 입력 형태와 출력 형태가 매번 동일합니다. 결과의 품질이 어느 수준 이상이면 충분합니다. 즉각적인 확인이 필요 없습니다. 실패해도 큰 문제가 없습니다.

직접 실행이 맞는 경우

매번 판단이 필요한 작업입니다. 결과 품질이 매번 달라집니다. 실패 시 즉각적인 대응이 필요합니다. 실수의 비용이 매우 큽니다.

회의록 요약, 뉴스 브리핑, 데이터 파일 정리는 자동화에 적합합니다. 중요한 이메일 초안, 계약서 검토, 코드 머지 결정은 자동화보다 직접 실행이 적합합니다.

Windows 환경에서의 자동화

WSL2 환경이라면 앞서 설명한 cron 방식을 그대로 쓸 수 있습니다. Windows 네이티브 환경에서는 Task Scheduler를 사용합니다.

Task Scheduler 기본 설정 방법:

작업 스케줄러를 열고 새 작업을 만듭니다. 트리거에서 원하는 실행 시간을 설정합니다. 동작에서 프로그램을 wsl.exe로 설정하고 인수에 bash 스크립트 경로를 넣습니다. WSL 내부에서 직접 cron을 쓰는 것이 보통 더 간단합니다.

자동화 효과 측정: 얼마나 시간이 절약되었나

자동화를 도입하기 전과 후의 시간을 비교해보면 동기부여에 도움이 됩니다.

간단한 측정 방법입니다. 자동화 전에 해당 작업에 걸리는 시간을 한 번 재봅니다. 자동화 후 일주일 치 절약 시간을 계산합니다. 그 시간에 더 가치 있는 일을 할 수 있는지 생각해봅니다.

회의록 요약 30분짜리를 매주 자동화하면 1년에 26시간이 생깁니다. 뉴스 브리핑 15분짜리를 매일 자동화하면 1년에 90시간이 생깁니다. 처음에는 자동화 설정에 2~3시간이 걸리더라도 금방 본전을 뽑습니다.

그런데 시간 절약보다 더 중요한 효과가 있습니다. 자동화된 작업은 내가 신경 쓰지 않아도 된다는 안심입니다. 매주 월요일 회의록 정리를 잊을 걱정이 없어집니다. 그 정신적 여유가 실제 시간 절약보다 더 가치 있을 때가 많습니다.

자동화 유지보수: 오래 잘 돌아가려면

처음 만든 자동화 스크립트는 몇 달 뒤에 그대로 동작하지 않는 경우가 많습니다. 입력 파일 형식이 바뀌거나, 폴더 구조가 달라지거나, Claude의 응답 패턴이 변하기도 합니다.

주기적인 점검 습관이 필요합니다. 한 달에 한 번씩 자동화된 결과물의 품질을 직접 확인합니다. 결과가 이상하면 CLAUDE.md나 프롬프트를 업데이트합니다. 입력 경로나 폴더 구조가 바뀌었으면 스크립트를 업데이트합니다.

자동화는 설정 후 잊는 것이 아니라, 정원처럼 주기적으로 돌봐야 하는 것입니다. 그 점검 시간이 절약된 시간에 비하면 훨씬 작습니다.

자동화와 CLAUDE.md의 관계

자동화에서 CLAUDE.md는 특히 중요한 역할을 합니다. 대화형 사용에서는 세션 중에 Claude에게 추가 지시를 내릴 수 있지만, headless 자동 실행에서는 그 기회가 없습니다. CLAUDE.md에 적힌 규칙이 전부입니다.

자동화 전용 CLAUDE.md 작성 팁 세 가지입니다.

첫째, 출력 형식을 구체적으로 명시하세요. "요약해줘"가 아니라 "다음 형식으로 마크다운 파일에 저장해줘: 제목, 3줄 요약, 핵심 결정사항 목록, 다음 할 일 목록"처럼 구체적으로 적어야 합니다. 사람이 없을 때 Claude는 더 명확한 지침에 의존합니다.

둘째, 오류 처리 방침을 적어두세요. 입력 파일이 없을 때 어떻게 해야 하는지, 데이터가 충분하지 않을 때 어떤 메시지를 남겨야 하는지 미리 정해두면, 실패 상황에서도 유용한 결과물이 나옵니다.

셋째, 저장 경로를 명확히 해두세요. "results/" 폴더에 저장해줘보다 "results/YYYY-MM-DD-weekly.md 형식으로 저장해줘"가 훨씬 명확합니다.

자동화 예산 설정: 월별 한도 관리

자동화 작업이 여러 개 돌아가기 시작하면 비용 관리가 중요해집니다. 월별 예산을 미리 정해두고 그 안에서 운영하는 방식을 권합니다.

Anthropic Console에서 Workspace 지출 한도를 설정할 수 있습니다. 예를 들어 자동화에 월 10달러를 예산으로 잡는다면, 그 한도를 넘으면 자동으로 중단되도록 설정합니다. 처음에는 보수적으로 잡고, 실제 사용량을 보면서 조금씩 늘려가는 방식이 안전합니다.

개인 예산 계산 방법입니다. 하루에 돌아가는 자동화 개수와 각각의 예상 토큰 수를 계산합니다. 월간 총 토큰을 모델별 단가와 곱합니다. 여기에 20~30% 여유를 더해 예산을 설정합니다.

처음에는 계산이 어렵습니다. 그냥 낮은 한도로 시작하고, 한 달 뒤 실제 사용량을 보면서 조정하는 게 현실적입니다.

외부 서비스 연동: Slack, 이메일, Notion

자동화 결과물을 파일로만 두지 않고 외부 서비스로 보내고 싶다면, 몇 가지 방법이 있습니다.

Slack 알림 보내기는 curl 명령으로 간단히 할 수 있습니다. Claude가 파일을 생성한 뒤, 쉘 스크립트에서 Slack Webhook URL로 결과물 링크나 내용을 보내는 방식입니다.

이메일 발송은 sendmail이나 msmtp 같은 커맨드라인 이메일 클라이언트를 쓸 수 있습니다. 결과 파일을 첨부하거나 내용을 본문으로 넣어 발송합니다.

Notion API 연동은 claude -p의 결과를 JSON으로 받아 Notion API에 POST하는 스크립트를 만들 수 있습니다. 페이지 생성, 데이터베이스 항목 추가 등이 가능합니다.

단, 이 모든 연동은 자동화 자체가 충분히 검증된 뒤에 붙여야 합니다. 잘못된 결과물이 외부로 발송되는 것이 파일에 저장되는 것보다 훨씬 큰 문제입니다.

팀 자동화: 여러 사람이 함께 쓸 때

개인 자동화와 달리 팀 자동화는 추가로 고려할 점이 있습니다.

누가 자동화를 소유하는지 명확히 해야 합니다. 자동화 스크립트와 설정 파일은 Git에 관리해야 합니다. 자동화가 실패했을 때 누가 알림을 받고 대응하는지 정해야 합니다. 팀원 모두가 자동화가 어떻게 작동하는지 이해해야 합니다.

팀 환경에서는 개인 API 키 대신 팀 공유 키를 쓰고, Console에서 사용량을 모니터링합니다. 자동화 스크립트는 코드 리뷰 과정을 거쳐 배포하는 것이 안전합니다.

자동화가 생성한 결과물의 품질을 정기적으로 팀이 함께 검토하는 회의를 갖는 것도 좋습니다. 아무도 결과물을 보지 않는 자동화는 언제 멈춰도 모르는 자동화입니다.

자동화 설계의 황금 원칙

오랫동안 안정적으로 돌아가는 자동화의 공통점은 다음 다섯 가지입니다.

하나, 작게 시작합니다. 처음부터 복잡한 파이프라인을 만들지 말고, 단일 작업 하나부터 시작합니다.

둘, 사람이 확인하는 단계를 유지합니다. 완전 자동화보다 반자동화(결과물을 사람이 검토하고 승인)가 오래 지속됩니다.

셋, 실패를 예상합니다. 모든 자동화는 언젠가 실패합니다. 실패했을 때 어떻게 할지 미리 계획해두세요.

넷, 결과를 측정합니다. 자동화가 정말 시간을 절약하고 있는지, 품질이 유지되고 있는지 주기적으로 확인합니다.

다섯, 단순하게 유지합니다. 복잡한 자동화는 부서지기 쉽습니다. 더 단순한 방법이 있다면 그쪽을 선택하세요.

이 원칙들은 Claude Code 자동화뿐 아니라 모든 자동화에 적용됩니다. 자동화는 도구입니다. 도구는 사람을 위해 있는 것이지, 사람이 도구에 끌려가서는 안 됩니다.

자동화 아이디어 모음: 직업별로 써먹기

어떤 자동화가 나에게 맞을까 고민이라면 직업별로 가장 효과적인 패턴을 참고하세요.

마케터나 콘텐츠 크리에이터라면 경쟁사 콘텐츠 트래킹을 자동화할 수 있습니다. 매주 주요 경쟁사의 블로그나 SNS를 체크하고 새로운 콘텐츠를 요약합니다. 또한 콘텐츠 아이디어 폴더에서 주간 콘텐츠 캘린더를 자동 생성할 수도 있습니다. 인스타그램, 블로그, 뉴스레터 각각에 맞는 형식으로 변환하는 것도 자동화에 적합합니다.

창업자나 사업주라면 주간 KPI 보고서 자동화를 시도해볼 만합니다. Google Analytics나 수집된 데이터 파일을 읽어 주간 성과를 정리합니다. 고객 피드백을 카테고리별로 분류하고 트렌드를 찾는 작업도 자동화할 수 있습니다. 주요 뉴스와 업계 동향을 매일 아침 브리핑으로 정리하는 것도 인기 있는 패턴입니다.

리서처나 분석가라면 논문이나 보고서 PDF를 매주 자동으로 요약하는 시스템을 구축할 수 있습니다. 특정 키워드로 들어오는 뉴스를 수집하고 분류하는 것도 가능합니다. 각종 데이터 파일의 주간 변화를 분석하고 보고하는 작업도 자동화에 잘 맞습니다.

교사나 강사라면 수강생 질문이나 피드백을 카테고리별로 정리하는 것을 자동화할 수 있습니다. 수업 자료를 다양한 포맷으로 변환하는 것도 반복적인 작업이라 자동화 후보입니다.

자동화 시작 3단계 액션 플랜

이 가이드를 읽고 나서 바로 시작할 수 있는 3단계입니다.

1단계는 후보 작업을 고르는 것입니다. 지금 반복하고 있는 작업 목록을 적어봅니다. 그 중에서 매주 30분 이상 걸리고, 입력과 출력 형태가 일정한 것을 찾습니다. 그 작업이 첫 번째 자동화 후보입니다.

2단계는 수동 실행부터 시작하는 것입니다. 자동화 스크립트를 만들기 전에, claude -p 명령으로 수동으로 먼저 실행해봅니다. 원하는 결과가 나오는 프롬프트를 찾을 때까지 반복합니다. 결과가 만족스러우면 그 명령을 쉘 스크립트로 저장합니다.

3단계는 cron에 올리는 것입니다. 스크립트가 검증되면 cron에 등록합니다. 첫 2주는 결과물을 매일 직접 확인합니다. 품질이 일정하다고 확신이 들면 그때부터 신뢰하고 쓸 수 있습니다.

이 3단계를 하는 데 처음에는 하루나 이틀이 걸릴 수 있습니다. 하지만 한 번 완성되면 그 시간은 수개월 안에 회수됩니다.

자동화를 통한 삶의 질 향상

자동화의 진짜 가치는 시간 절약보다 정신적 여유에 있습니다.

매주 월요일 회의록 정리를 잊을 걱정이 없어지는 것, 경쟁사 동향을 놓칠까봐 불안하지 않아도 되는 것, 매일 아침 뉴스를 읽어야 한다는 부담이 줄어드는 것. 이것들은 직접적인 시간 절약보다 더 큰 가치를 가질 때가 많습니다.

한 수강생은 자동화 도입 후 "업무가 쌓이는 불안감이 줄었다"고 했습니다. 처리해야 할 반복 작업이 자동으로 처리되고 있다는 안심이, 다른 더 중요한 일에 집중할 수 있게 해준다는 것입니다.

결국 자동화는 더 중요한 일을 위한 공간을 만드는 것입니다. Claude Code Headless 모드는 그 공간을 만드는 도구 중 하나입니다. 작은 것부터 시작해서, 점점 넓혀가세요.

자동화와 AI의 미래

AI 자동화 기술은 빠르게 발전하고 있습니다. 지금 당장 완벽한 파이프라인을 만들려 하기보다, 기본 개념과 원칙을 이해하고 작게 시작하는 것이 중요합니다.

Claude Code의 Headless 모드는 현재 많은 기업과 개인이 실제로 사용하는 방식입니다. GitHub Actions와 연동해서 코드 리뷰를 자동화하거나, Slack 봇과 연결해서 팀 업무를 자동화하거나, 데이터 파이프라인에 Claude를 통합하는 사례가 점점 늘고 있습니다.

이 모든 것의 시작은 claude -p 명령 하나입니다. 그 한 줄이 복잡한 자동화 파이프라인의 씨앗입니다.

지금 당장 모든 것을 자동화하려 할 필요는 없습니다. 가장 효과가 크고 가장 안전한 것 하나부터 시작하면 됩니다. 그게 이 섹션의 핵심 메시지입니다.

자동화 도입 후기: 실제 운영 경험

플랫폼을 운영하면서 실제로 자동화한 작업들과 그 경험을 공유합니다.

첫 번째 자동화는 피드백 정리였습니다. 매주 폴더에 쌓이는 피드백 파일들을 읽고 카테고리별로 분류하는 작업입니다. 처음 만드는 데 두 시간이 걸렸고, 이후 매주 30분씩 절약됩니다. 1년이면 24시간 이상 절약입니다.

두 번째는 강의 자료 업데이트 확인이었습니다. 참고한 공식 문서들이 업데이트되면 알려주는 자동화입니다. 매주 특정 페이지들을 체크하고 변경사항이 있으면 요약해서 알려줍니다. 구현이 복잡했지만 최신 정보를 유지하는 데 도움이 됩니다.

세 번째는 일간 뉴스 브리핑입니다. 매일 아침 관심 분야의 뉴스를 수집하고 3줄 요약을 만듭니다. 아침에 커피 한 잔 마시는 동안 요약된 내용을 읽으면 됩니다. 이것이 일상에서 가장 체감이 큰 자동화입니다.

자동화를 통해 배운 가장 중요한 것은, 처음에 예상했던 것보다 훨씬 더 많은 작업이 자동화 가능하다는 것입니다. 단, 처음부터 많이 하려 하면 실패합니다. 하나씩 천천히가 정답입니다.

문제 해결: 자동화에서 자주 막히는 상황

headless 자동화를 처음 시도하면 몇 가지 흔한 장벽을 만납니다. 미리 알아두면 당황하지 않을 수 있습니다.

환경변수 문제가 가장 흔합니다. 터미널에서는 작동하는데 cron에서 안 되는 경우, 환경변수 설정이 cron에는 적용되지 않기 때문입니다. crontab에서 환경변수를 직접 명시하거나, 스크립트 안에서 경로를 절대경로로 지정해야 합니다.

작업 디렉토리 문제도 자주 발생합니다. claude 명령은 현재 디렉토리를 기준으로 파일을 읽고 씁니다. cron에서는 홈 디렉토리가 기준이 될 수 있어 경로가 맞지 않을 수 있습니다. 스크립트 맨 앞에 cd 명령으로 작업 디렉토리를 명시적으로 설정하세요.

권한 문제는 보통 파일을 쓸 수 없는 경우입니다. 출력 폴더가 존재하는지, 쓰기 권한이 있는지 먼저 확인하세요. mkdir -p 명령으로 폴더를 미리 만들어두는 것이 좋습니다.

API 응답이 예상과 다른 경우, 프롬프트를 더 구체적으로 바꾸거나 출력 형식을 명시적으로 지정하면 해결되는 경우가 많습니다. CLAUDE.md에 기대하는 출력 형식과 저장 경로를 구체적으로 적어두는 것도 크게 도움이 됩니다.

Git Worktree로 병렬 작업하기

한 저장소에서 여러 Claude를 동시에 돌리는 정석. 충돌 없이 컨텍스트만 분리합니다.

참고

23. 한 저장소, 여러 Claude — Git Worktree로 병렬 작업하기

같은 코드베이스에서 두 가지 일을 동시에 하다 보면 어느 순간 "지금 어느 브랜치에서 작업 중이었지?"로 멈추는 순간이 옵니다. 그 혼란을 없애는 방법이 Git Worktree입니다. 저장소는 하나인데 폴더는 여러 개로 펼쳐 놓고, 각 폴더에 다른 Claude를 앉히는 방식입니다.

💡 한 번은 이런 일이 있었다. cc101 가이드를 개발할 때, 본문 차별화 작업과 SEO 개선 작업을 동시에 진행해야 했다. 같은 디렉토리에서 두 Claude를 띄웠더니 서로 다른 파일을 수정하면서 결과를 뒤섞어 버렸다. 그날 워크트리를 처음 제대로 써봤다. 한 폴더는 본문 작업, 다른 폴더는 SEO 작업. 두 Claude가 서로를 전혀 모르는 상태에서 각자의 일을 하고, 나는 두 터미널 탭을 오가며 진행 상황을 확인했다.

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을 가리키지만, 각각 다른 브랜치를 체크아웃합니다. 파일을 복사한 것이 아닙니다. 같은 저장소를 서로 다른 각도에서 보는 것입니다.

단일 디렉토리와 Worktree 분리의 차이

같은 코드베이스에서 두 Claude를 단일 디렉토리에서 돌리면 어떤 일이 생기는지 직접 겪어봤습니다.

한 Claude가 auth.ts를 수정하는 동안 다른 Claude가 같은 파일을 읽어 컨텍스트로 가져갑니다. 수정이 반쯤 진행된 파일을 읽게 됩니다. 두 Claude의 작업이 뒤섞이면서 어느 쪽 결과가 맞는지 알 수 없게 됩니다.

Worktree를 쓰면 이 문제가 구조적으로 없어집니다.

상황	단일 디렉토리	Worktree 분리
두 Claude가 같은 파일 수정 시	덮어쓰기 위험	디렉토리가 다르므로 물리적 충돌 없음
컨텍스트 혼합	피처 A 작업 중 B 파일이 보임	각 트리는 자기 브랜치만 봄
브랜치 전환	진행 중인 작업 stash 필요	전환 자체가 불필요

기본 명령어

새 worktree 만들기

# 메인 저장소 안에서 실행
cd ~/repos/my-repo

# 새 디렉토리 ~/repos/my-repo-feat 에 feature-A 브랜치 체크아웃
git worktree add ../my-repo-feat -b feature-A

현재 worktree 목록 확인

git worktree list

# 출력 예
# /home/me/repos/my-repo        abc1234 [main]
# /home/me/repos/my-repo-feat   def5678 [feature-A]

완료된 worktree 정리

# 작업이 끝난 worktree 삭제
git worktree remove ../my-repo-feat

# 폴더를 외부에서 직접 지운 경우
git worktree prune

공식 권장 운영 방법

Anthropic 공식 문서에서 권장하는 방식입니다.

메인 트리는 main 브랜치 전용으로 둡니다. 배포와 동기화, 빠른 점검에만 씁니다. 실제 작업은 모두 worktree에서 합니다. feature-X, bugfix-Y 별로 디렉토리를 분리하고, 각 worktree에서 claude를 시작합니다.

cd ~/repos/my-repo-feat
claude

# 다른 터미널에서:
cd ~/repos/my-repo-fix
claude

두 Claude가 같은 코드베이스를 알면서도 서로 간섭하지 않습니다.

작업이 끝나면 PR로 머지하고 worktree를 제거합니다. 깔끔한 사이클입니다.

💡 Worktree 생성/삭제 시점은 WorktreeCreate / WorktreeRemove Hook으로 자동화할 수 있습니다 (예: 자동 패키지 설치, 환경 변수 복사).

주의할 점

이 부분을 모르면 의도치 않은 문제가 생깁니다.

같은 브랜치를 두 worktree에서 동시에 체크아웃할 수 없습니다. 이것은 Git 자체의 제약입니다. 같은 파일을 두 worktree에서 동시에 수정하면 나중에 머지할 때 충돌이 생깁니다. 디렉토리가 다르다고 충돌이 없어지는 게 아니라, 같은 브랜치에서 같은 파일을 두 사람이 수정한 것과 같습니다.

node_modules, .next, dist 같은 의존성과 빌드 결과물은 worktree 간에 공유되지 않습니다. 각 worktree에서 별도로 설치해야 합니다. 처음에 이 점을 모르고 "왜 빌드가 안 되지?" 하고 헤맸던 경험이 있습니다.

MCP 서버는 scope에 따라 다르게 동작합니다. 자세한 내용은 15-mcp 섹션을 참조하세요.

CLAUDE.md는 어떻게 동작하나

각 worktree는 자기 디렉토리의 CLAUDE.md를 봅니다. 이 점을 이해하면 워크트리별 설정이 가능합니다.

프로젝트 공통 규칙은 메인 저장소의 CLAUDE.md에 넣습니다. Git에 커밋되어 있으므로 모든 worktree에서 동일하게 보입니다.

worktree 전용 규칙은 그 디렉토리 안의 CLAUDE.md에 넣습니다. Git에 커밋하지 않으면 그 워크트리에서만 적용됩니다.

사용자 공통 규칙은 ~/.claude/CLAUDE.md에 넣습니다. 모든 프로젝트에 적용됩니다.

비개발 활용: 코드만이 아닙니다

Worktree는 코드 프로젝트만을 위한 것이 아닙니다. 리서치, 글쓰기, 분석 작업에도 똑같이 쓸 수 있습니다.

투자 리서치: 동시에 여러 관점

git worktree add ../markets-macro  -b macro-thesis
git worktree add ../markets-stocks -b stocks-deep-dive

메인 트리는 거시 지표와 뉴스 클리핑. macro-thesis 트리는 매크로 가설 정리와 보고서 초안. stocks-deep-dive 트리는 종목별 재무와 산업 분석. 각 트리에서 Claude는 자기 폴더만 보므로 분석이 뒤섞이지 않습니다.

부동산 매물 비교

git worktree add ../listings-seoul    -b seoul
git worktree add ../listings-bundang  -b bundang

지역별 매물·시세 자료를 별도 트리에 두고, 마지막에 메인 트리에서 종합 비교. 한 트리가 다른 트리를 모르므로 비교 단계에서 객관성이 유지됩니다.

책 한 권을 여러 챕터로

git worktree add ../book-ch3 -b chapter-3
git worktree add ../book-ch7 -b chapter-7

긴 글을 동시에 여러 챕터로 진행. 각 챕터에 다른 Claude 세션을 붙이면, 톤과 구조 실험을 동시에 할 수 있습니다.

자주 하는 실수

처음 worktree를 쓸 때 자주 만나는 실수들입니다.

메인 트리에서 직접 작업을 시작하면 나중에 머지나 점검할 깨끗한 기준점이 없어집니다. worktree를 너무 많이 만들면(5개 이상) 혼란이 생기고 디스크도 낭비됩니다. 같은 파일을 두 트리에서 동시에 수정하면 머지 시 충돌이 생기고 어느 쪽이 맞는지 헷갈립니다. node_modules를 공유하려 시도하면 패키지 매니저는 일반적으로 디렉토리 단위로 관리하기 때문에 예상대로 작동하지 않습니다. worktree를 삭제한 뒤 prune을 안 하면 git이 빈 항목을 남겨 혼란을 줍니다.

Worktree 적정 수

경험상 동시에 2~3개가 적당합니다. 이 이상 넘어가면 어느 트리에서 무엇을 작업하고 있는지 추적이 어려워집니다. 4개 이상 필요하다는 생각이 든다면, 작업을 더 작은 단위로 나누는 것을 먼저 고려해보세요.

이 장을 덮기 전에

git worktree add 명령어로 새 워크트리를 만들어봤다
같은 브랜치를 두 워크트리에서 체크아웃하면 안 됨을 이해했다
각 워크트리는 자기 CLAUDE.md를 따로 가질 수 있음을 이해했다
의존성(node_modules 등)은 워크트리마다 별도 설치 필요함을 확인했다

다음 장(24. Custom Slash Commands & Output Styles)에서는 반복 작업을 단 한 줄 명령으로 줄이는 법을 다룹니다. 같은 요청을 두 번 이상 했다면 이미 슬래시 명령이 필요한 시점입니다.

Custom Slash Commands & Output Styles

같은 일을 두 번 시키면 슬래시 명령으로. 응답 형식을 프로젝트별로 고정합니다.

참고

24. Custom Slash Commands & Output Styles

같은 일을 두 번 시키면 슬래시 명령으로. 응답 형식은 프로젝트별로 고정.

같은 지시를 세 번째 타이핑하면서 "이거 매번 똑같이 적고 있네" 싶은 순간이 옵니다. 슬래시 명령은 그 인식이 든 순간 바로 만들면 됩니다. 한 줄짜리 별명일 뿐인데, 그 한 줄이 매일 반복되던 5분짜리 입력을 0초로 줄여줍니다. 출력 스타일도 마찬가지입니다. 프로젝트마다 답변 형식이 달라야 한다면 한 번 적어두고 나서는 신경 쓸 필요가 없습니다. 외부에 공유할 수 있는 작은 자산이 하나씩 쌓이는 셈입니다.

매주 같은 정리, 같은 표 형식, 같은 프롬프트를 또 입력하고 있다면: 슬래시 명령으로 옮길 시간입니다.

Custom Slash Commands가 뭔가요?

자주 쓰는 프롬프트를 /내명령어 형태로 저장해 한 번에 호출합니다. 17번 섹션의 Skills와 같은 메커니즘입니다 (Custom Commands는 Skills로 통합됨).

저장 위치 (로드 순서 — 가까운 쪽이 먼저 적용됨):

범위	경로	우선순위
프로젝트 (팀 공유)	`.claude/skills/`	1순위 (가장 가까움)
개인 (모든 프로젝트)	`~/.claude/skills/`	2순위
엔터프라이즈	관리자 정책	3순위 (강제 정책)

💡 Skills/Commands는 일반적으로 프로젝트가 가장 가까운 쪽이 우선입니다. 엔터프라이즈 정책은 별도의 강제 레이어로, 관리자가 적용하는 보안·규정 제약입니다.

💡 자세한 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: 언제 무엇?

상황	답
같은 작업을 반복 호출	Custom Slash (Skills)
응답 형식만 일관되면 됨	Output Style
프로젝트마다 톤이 달라야 함	프로젝트별 Output Style
입력에 따라 내용이 다름	Slash + `$ARGUMENTS` 활용

둘은 자유롭게 조합할 수 있습니다. "Listings Output Style"이 켜진 상태에서 /daily-stock을 호출하면, 표 형식 규칙이 자동 적용됩니다.

동적 컨텍스트: `!` + 백틱

Skills 본문에서 ! 접두 + 백틱으로 명령 실행 결과를 그대로 컨텍스트에 주입할 수 있습니다.

오늘 날짜: !`date +%Y-%m-%d`

현재 디렉터리 파일:
!`ls -la`

매 호출 시점의 시스템 상태가 자동으로 들어갑니다. (자세한 사용법과 보안 옵션은 17-skills 참조)

만들 때 흔한 함정

함정	결과
너무 길게 작성	Skill description이 1,536자 잘림. SKILL.md는 500줄 이내 권장
모호한 description	Claude가 적절히 호출하지 못함
프로젝트 규칙을 개인 폴더에 저장	팀이 공유 못함
절대 경로 하드코딩	다른 환경에서 깨짐
Output Style을 너무 강하게	모든 답변이 부자연스러워짐. 가벼운 가이드 정도가 적당

한 줄 요약

두 번 같은 일을 시켰다면, 세 번째는 슬래시 명령으로. 매번 같은 형식이 필요하다면, Output Style로.

💡 한 번은 이런 일이 있었다. 강의 자료를 만들 때마다 같은 프롬프트를 복붙하고 있었다. "섹션 하나를 강의 슬라이드 형식으로 만들어줘. 핵심 포인트 5개, 예시 2개, 마무리 질문 1개 포함해서." 어느 날 세어봤더니 한 달에 28번을 같은 문장을 타이핑했다. 그날 /lecture 명령 하나를 만들었다. 지금은 타이핑 없이 /lecture [섹션명] 한 줄이면 끝난다.

이 장을 덮기 전에

자주 반복하는 작업 하나를 골랐다
.claude/skills/ 폴더에 첫 번째 Skill 파일을 만들었다
만든 슬래시 명령을 실제로 한 번 호출해봤다
Output Style을 하나 만들고 /output-style 명령으로 활성화해봤다
Skills와 Output Style을 조합해서 쓸 수 있음을 이해했다

다음 장(25. 모바일·웹·샌드박스 실전 활용)에서는 책상 앞이 아닌 상황에서도 Claude Code를 쓰는 방법을 다룹니다. 웹·iOS로 자리를 옮기고, 위험한 코드는 OS 샌드박스에 가두는 동선입니다.

모바일·웹·샌드박스 실전 활용

책상을 떠나도, 위험한 코드 앞에서도 — 웹·iOS·--teleport·Channels·Sandbox로 자리를 옮기는 법.

참고

25. 모바일·웹·샌드박스 실전 활용

책상을 떠나도, 위험한 코드 앞에서도, 같이 갑니다.

Claude Code가 책상 앞에서만 동작한다면 절반밖에 못 쓰는 셈입니다. 출퇴근 지하철에서 떠오른 아이디어는 도착할 때쯤 휘발되고, 검증 안 된 명령을 본 시스템에서 바로 돌리는 건 늘 마음이 무겁습니다. 웹·모바일로 자리를 옮겨 이어가고, 위험한 건 샌드박스에 가두는 — 이 두 흐름만 손에 붙이면 도구가 처음으로 내 일상에 맞춰 움직이기 시작합니다.

Claude Code는 이제 단일 CLI가 아닙니다. Anthropic은 같은 엔진을 여러 표면에 연결해 두었습니다. 같은 CLAUDE.md, 같은 MCP 서버, 같은 Skills가 터미널·VS Code·Desktop 앱·웹·iOS 앱·Slack·GitHub Actions에서 동일하게 동작합니다.

claude.ai/code

브라우저로 긴 작업을 띄워두고, 폰으로 돌아가서 확인합니다.

웹에서 시작

--teleport

터미널에서 시작한 세션을 웹/iOS로, 또는 반대 방향으로 이어받습니다.

자리 옮기기

Sandbox

macOS/Linux는 OS 격리, 위험 코드는 호스트 밖에서.

격리 실행

모바일·웹: 어디서든 이어가기

Claude Code의 모바일 시나리오는 별도 슬래시 명령이 아니라 세션을 다른 표면으로 옮기는 방식입니다. 책상의 터미널 세션과 출퇴근길 폰이 같은 엔진을 공유합니다.

진입점이 여러 개입니다

표면	진입점	잘 맞는 용도
웹	claude.ai/code	로컬에 클론 안 한 저장소, 긴 작업을 띄워두고 자리 비우기
iOS 앱	App Store "Claude"	폰 한 손, 짧은 점검·승인·메모
Desktop 앱	code.claude.com 다운로드	시각적 diff 리뷰, 여러 세션 병렬, 스케줄 작업
VS Code / JetBrains	IDE 확장	인라인 diff, @-mention
터미널 ↔ 다른 표면	`claude --teleport` / `/desktop`	자리 이동

💡 같은 Anthropic 계정으로 로그인하면 됩니다. CLAUDE.md·MCP 설정·Skills는 표면 사이에서 그대로 따라옵니다.

자리를 옮기는 두 가지 방법

터미널 → 웹/iOS로 옮기기. 긴 작업을 클라우드에서 돌리고 싶을 때:

claude --teleport
→ 현재 세션을 웹으로 보냄 → 브라우저나 iOS 앱에서 이어서

웹에서 시작 → 터미널로 끌어오기. 출근길에 폰으로 던져둔 작업을 책상에서 마무리할 때도 같은 --teleport로 가져옵니다. 양방향입니다.

터미널 → Desktop 앱. diff를 시각적으로 보고 싶을 때:

/desktop
→ 현재 세션을 Desktop 앱으로 열기

Remote Control: 폰을 콘솔로

자리를 떴는데 데스크톱 세션이 살아 있을 때, Remote Control로 폰에서 그 세션을 직접 조작합니다. 권한 승인, 짧은 후속 지시 정도가 어울립니다.

Channels: Slack / Telegram / Discord

Channels는 메신저에서 세션으로 메시지를 푸시하는 통로입니다.

슬랙에서 @Claude를 멘션해 버그 리포트 → PR로 받기 (Slack 통합)
텔레그램·디스코드 봇으로 외출 중 알림 받기·짧은 지시 보내기
직접 만든 웹훅도 채널로 붙일 수 있습니다

Routines: 스케줄로 돌리기

폰에서 직접 시키지 않아도 됩니다. Routines는 Anthropic 인프라에서 돌아가는 정기 작업입니다. 오전 PR 리뷰, 야간 CI 실패 분석, 주간 디펜던시 감사 — 컴퓨터가 꺼져 있어도 실행됩니다. 터미널에서 /schedule로 만들 수 있습니다.

💡 로컬 시스템 자원이 꼭 필요한 작업은 Desktop 앱의 scheduled tasks가 더 맞습니다. 같은 머신에서 돌리고, 같은 파일·도구에 접근합니다.

Sandbox: 위험 코드를 호스트 밖에서

검증 안 된 스크립트, 처음 호출하는 외부 API, 권한이 큰 명령은 샌드박스에서 먼저 돌립니다.

Claude Code의 샌드박스는 별도 슬래시 명령이 아니라 OS 수준 격리 모드입니다. 표면별로 다른 백엔드를 씁니다.

OS	격리 백엔드	비고
macOS	Seatbelt	13.0 이상에서 지원
Linux	landlock	커널 5.13 이상
WSL 2	landlock	WSL 1은 미지원
Windows 네이티브	AppContainer	Git for Windows 권장

켜는 법

세션 단위로 켜려면 CLI 플래그:

claude --sandbox

기본값으로 두고 싶으면 settings.json에:

{
  "permissions": {
    "defaultMode": "plan"
  },
  "sandbox": "auto"
}

샌드박스 안에서 일어난 파일 수정·네트워크 호출은 호스트에 영향을 주지 못합니다. 결과만 본 세션으로 끌어옵니다.

언제 쓰나요

상황	이유
GitHub에서 처음 본 스크립트	실행 전에 격리 환경에서 동작 확인
외부 API에 처음 토큰 사용	키 노출·잘못된 엔드포인트 위험 격리
시스템 레벨 명령	rm·chmod·mv 등 사고 시 회복 어려움
미검증 npm 패키지	postinstall 스크립트 위험

💡 보안 민감한 코드는 Sandbox + Plan Mode + Git commit 3중 안전망이 정석입니다.

음성·이미지 입력은 어떻게 되나요?

자주 받는 질문입니다. 2026-05 기준 상황은 이렇습니다.

음성 입력: 별도 /voice 슬래시 명령은 없습니다. 음성으로 지시하려면 iOS Claude 앱 또는 **웹(claude.ai/code)**의 마이크 버튼을 씁니다. 받아 적은 텍스트가 세션 프롬프트로 들어갑니다.
이미지 입력: 터미널은 이미지 파일 경로 첨부, Desktop 앱·웹·iOS 앱은 드래그·붙여넣기·카메라 입력을 지원합니다.
Chrome 연동: 라이브 웹앱을 디버깅할 때는 Chrome 통합을 씁니다. 음성과는 별개의 도구입니다.

음성은 초안용으로 받아 적고, 정확한 파일명·명령어·코드는 타이핑으로 보완하는 편이 안전합니다.

비개발 실전 시나리오 3가지

시나리오 1: 출퇴근길 부동산

07:50 (지하철)
폰에서 Claude iOS 앱 열기 → 어제 데스크톱에서 진행한 매물 검토 세션 이어받기

08:00
부동산 사이트 매물 링크 3개를 폰으로 던지고
마이크로 음성 입력:
"이 세 매물의 가격·평수·층 비교 표 만들어줘.
주말에 보러 갈 우선순위 매겨줘"

08:15
회사 도착 → 데스크톱 터미널에서 `claude --teleport`로 같은 세션을
다시 끌어와 자세한 분석을 이어서.

시나리오 2: 장중 주식 메모

12:30 (점심 후 산책)
폰 마이크로 메모:
"지금 A종목이 거래량 평소 두 배인데, 뉴스는 별 게 없는 거 같아.
공시 확인해보고, 비슷한 패턴이 최근 한 달 안에 있었는지 메모만 해둬"

저녁 18:00 (책상)
같은 세션 열어보면 메모와 함께 공시·과거 패턴 분석이 정리되어 있음.
판단·매매는 사람이.

시나리오 3: 샌드박스에서 데이터 스크래핑 안전 실험

처음 보는 사이트의 공개 데이터 50개를 가져오고 싶음.
스크립트는 검증이 안 됐음.

1) claude --sandbox 로 세션 시작
2) Claude에게: "이 스크립트 돌려서 데이터 5건만 가져와봐.
   에러나면 멈추고 알려줘."
3) 5건 결과 확인 → 정상 동작
4) 호스트 세션으로 결과만 옮긴 뒤 50건으로 확장

스크립트에 무한 루프나 위험 명령이 있어도 호스트는 안전합니다.

결합 워크플로우

출퇴근 (iOS 앱·웹) + Channels 알림 + Sandbox 안전 실행

예: Slack에서 @Claude로 "이 데이터 소스를 sandbox에서 5건만 시험해봐" 메시지 → Routines가 새벽에 실행 → 결과를 Slack에 다시 답장.

세 표면이 하나의 흐름으로 이어집니다.

보안·프라이버시 체크리스트

항목	권장
음성 데이터	Anthropic 정책상 일정 기간 후 삭제. 민감 정보 발화 자제
모바일 세션	사용 안 하면 즉시 종료. 공공 Wi-Fi 대신 4G/5G 권장
Sandbox 격리 수준	OS 레벨 격리. 그래도 비밀번호·키는 직접 넣지 말 것
Channels 토큰	토큰을 settings.json에 평문으로 두지 말고 환경 변수로 분리
Remote Control 권한	자리 비울 때 항상 잠금 + 승인 모드

자주 하는 실수

실수	결과
음성으로 정확한 코드 받아쓰게 함	함수명·경로 오타
모바일에서 큰 리팩터링	화면 작아 실수 잦음. 모바일은 모니터링·승인용
검증 안 된 외부 코드 호스트 세션에서 실행	사고 시 회복 어려움 — Sandbox 먼저
Sandbox 결과를 무조건 신뢰	격리는 안전망일 뿐. 결과 검증은 사람이

한 줄 요약

책상 앞이 아닐 때도, 안전하지 않은 코드 앞에서도, Claude Code는 같이 갈 수 있습니다.

💡 한 번은 이런 일이 있었다. 출근 지하철에서 폰의 Claude 앱을 열어 어제 작업을 이어보려다 처음 --teleport를 써봤다. 어제 데스크톱에서 띄워둔 세션이 폰에서 그대로 열리는 걸 보고 놀랐다. 그날부터 출퇴근길은 짧은 작업을 점검하는 시간이 됐다. 한 가지 주의: 지하철에서 API 키 관련 작업은 절대 안 한다.

이 장을 덮기 전에

웹(claude.ai/code) 또는 iOS 앱에 한 번 로그인해봤다
claude --teleport로 세션을 다른 표면으로 옮겨봤다
claude --sandbox가 어떤 OS 격리(Seatbelt/landlock/AppContainer)를 쓰는지 확인했다
Channels(Slack/Telegram/Discord) 중 어울리는 통로를 골라봤다
모바일은 모니터링·승인용, 정밀 작업은 책상에서라는 용도 구분을 파악했다

다음 장(22. 가이드를 마치며 — 지금 알고 있는 것들)에서는 이 가이드 전체를 마무리하며 지금까지 익힌 것들을 정리하고, 앞으로의 학습 경로를 안내합니다.

다음 단계 & 리소스

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

참고

22. 가이드를 마치며 — 지금 알고 있는 것들

여기까지 읽으셨다면, 책 한 권을 끝까지 붙잡은 것입니다. 남은 것은 단 하나입니다. 꺼내 쓰는 것.

Claude Code 공식 문서의 Next steps & 리소스 섹션 출처: Claude Code overview — Anthropic 공식 문서

지금 손에 쥐고 있는 것들

이 가이드를 읽으며 자연스럽게 익힌 것들입니다. 목록으로 적어보면 생각보다 많습니다.

Claude Code가 무엇이고 다른 AI 도구와 어떻게 다른지 이해했습니다. 설치와 인증을 마쳤습니다. 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과 복구 방법에 익숙해진 뒤에 시도하세요.

참고: 나중에 볼 주제

지금 당장 구현하지 않아도 됩니다. 이름만 알아두고, 실제로 필요해질 때 해당 섹션을 다시 펼치세요.

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 연동과 시크릿 처리는 키 노출이나 잘못된 엔드포인트 위험이 있습니다.

매 작업마다 지키는 다섯 줄

작업 전 git commit — 언제든 롤백 가능한 상태 유지
범위 좁히기 — "이 파일의 이 함수만"처럼 구체적으로
생성된 코드 직접 읽어보기 — 이해 못 한 코드는 쓰지 않기
보안·결제 코드는 반드시 별도 검토
큰 작업은 Plan Mode로 계획 먼저 (Shift+Tab)

첫 실전 프로젝트: 다섯 가지 출발점

가이드가 끝났다면 지금 당장 작은 한 가지로 들어가 보세요.

어떤 것을 고를까

본인 일상에 가장 가까운 것을 고르세요.

회의가 많다면 회의록 자동 정리 워크플로우가 좋습니다. 글을 자주 쓴다면 내 업무용 Skills 만들기를 시도해보세요. 시장이나 경쟁사를 자주 본다면 경쟁사 분석 보고서를 만들어 보세요. 웹사이트가 필요하다면 포트폴리오 사이트 만들기를 해보세요. 기존 코드가 있다면 작은 파일 하나를 리팩토링해보세요.

망설여진다면 회의록 자동 정리부터 시작하세요. 코딩 지식이 거의 필요 없고, 반복 절감 효과가 가장 빨리 보입니다.

출발점들

회의록 자동 정리

"~/Downloads/meeting-260225.mp3 파일이 있어.
 회의 내용을 변환하고, 요약 + 담당자별 액션아이템을 정리해서
 meeting-260225.md로 저장해줘"

내 업무용 Skill 만들기

매주 반복하는 일을 /명령어 한 줄로 줄여보세요.

"매주 월요일마다 지난 주 작업 내용을 정리하는 Skill 만들어줘.
 GitHub 커밋 내역과 메모 파일 기반으로 주간 보고서 초안을 생성하는 방식으로."

경쟁사 분석 보고서

"경쟁사 A·B·C 웹사이트를 분석해서
 주요 기능·가격·타깃 고객·차별화 포인트를 비교표로 정리해줘.
 competitor-analysis.md로 저장해줘"

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에 반영

첫 주의 목표는 큰 프로젝트 완성이 아닙니다. 내 업무에서 반복되는 한 가지를 줄이는 것입니다.

막혔을 때의 네 박자 — 첫 한 달은 이 순서로

가이드 12장에서 다룬 응급실 매뉴얼이 있어도, 가이드 덮은 직후 첫 한 달은 막힘에서 빠져나오는 호흡을 따로 익히는 시기입니다. 다음 네 박자를 외워두시면 본 게임에서 흐름이 끊기지 않습니다. 이 흐름이 몸에 익으면 막힘이 두렵지 않게 됩니다.

공식 문서 확인: 대부분의 답이 여기 있습니다. code.claude.com/docs. 안에서는 /help도 가능합니다.
Claude Code에게 직접 묻기: Claude Code 자체가 가장 강력한 도움말입니다. "MCP 서버 추가 방법 알려줘", "이 에러 메시지 의미 설명해줘"
공식 이슈 확인: github.com/anthropics/claude-code/issues
Anthropic 지원: 계정·결제 관련은 콘솔에서 지원 요청

이 가이드를 다 읽은 당신에게

💡 한 번은 이런 일이 있었다. 첫 강의 기수에 함께 했던 한 분이 6개월 뒤 연락을 해왔다. "처음에는 터미널이 두려웠는데, 지금은 Claude 없이 일하는 걸 상상을 못하겠어요." 그 분은 코드를 한 줄도 모르는 마케터였다. 지금은 회의록 자동 정리, 경쟁사 분석, 콘텐츠 캘린더가 모두 자동화된 워크스페이스로 일하고 있다. 가이드를 끝까지 읽고 작은 것 하나를 시작했을 뿐인데.

Claude Code는 빠르게 발전하는 도구입니다. 오늘 익힌 디테일이 몇 달 뒤에는 또 달라져 있을 수 있습니다. 중요한 것은 표면의 명령이 아니라 그 아래의 결을 익히는 것입니다.

AI와 함께 일한다는 것은 단순히 작업을 빠르게 처리한다는 뜻이 아닙니다. AI의 강점(넓은 지식·반복·패턴)과 사람의 강점(판단력·창의·도메인 지식)을 묶는 새로운 협업 방식입니다. 여기까지 읽으신 분은 그 첫걸음을 이미 떼셨습니다.

이 가이드에서 배운 것들이 실제 일하는 방식을 바꾸는 데 도움이 되기를 바랍니다. 막히면 돌아오세요. 이 가이드는 여기 있습니다. 그리고 한 가지 더 — 가이드를 읽고 실제로 일하는 방식이 바뀌신 분이 있다면, 그 변화를 채널에 한 줄 적어주시면 다음 가이드의 재료가 됩니다. 한 분의 변화가 다음 분의 출발점이 되는 흐름을 만들고 싶었습니다.

가이드 덮은 그 자리에서 시작할 수 있는 한 가지

여기까지 읽으셨다면 한 가지를 부탁드리고 싶습니다. 지금 이 페이지를 닫기 전에 터미널을 한 번 켜시고, 한 명령을 쳐보세요. 어떤 명령이든 상관없습니다. claude --version도 좋고, claude 한 줄로 들어가서 "안녕"이라고 인사를 건네셔도 좋습니다. 가이드를 끝까지 읽고도 첫 명령을 못 친 분이 강의장에서 의외로 많았습니다.

가이드 닫기 전 첫 명령이 1년 뒤를 결정합니다. 그 한 명령이 가이드를 책에서 도구로 바꾸는 순간입니다. 도구가 된 이상 다시 책으로 돌아가지 않습니다. 책장에 꽂힌 가이드는 6개월 뒤에 다시 안 펼치게 되지만, 손에 잡힌 도구는 매일 같이 일합니다.

💡 한 번은 이런 일이 있었습니다. 강의 마지막 회차 막바지에 "이제 첫 명령 쳐보세요"라고 했더니, 한 분이 진지하게 "강의 끝나고 집에서 천천히 해볼게요"라고 답하셨습니다. 그래서 그 자리에서 함께 첫 명령을 쳐드렸습니다. "집에 가서"는 영영 오지 않는 약속이라는 게 강의장에서 배운 진실이었습니다. 지금 이 자리에서, 이 페이지가 열려 있는 채로, 한 번만 쳐보시기를 바랍니다.

다 읽으신 분이 가장 자주 하시는 질문 다섯 개

가이드를 끝낸 분들이 강의장에서 마지막에 가장 자주 던지신 질문 다섯 가지입니다. 답은 짧지만, 답에 도달한 경위는 길었습니다.

Q1. "이걸 다 외워야 하나요?"

아니요. 외울 필요가 전혀 없습니다. 가이드는 책상 위에 두고 막히면 펼치는 사전입니다. 매일 쓰는 명령은 5개도 안 되고, 나머지는 막힐 때 한 번씩 검색하는 것으로 충분합니다. 클로드 코드 자체가 본인의 가장 좋은 도움말이 됩니다 — /help를 쳐서 모르는 명령을 물어보시면 됩니다.

Q2. "처음 한 주는 어떻게 보내면 좋을까요?"

가이드 7일 실천 플랜을 그대로 따라가시는 게 가장 쉽습니다. 그 7일이 아무것도 안 하기보다 천 배 낫습니다. 완벽한 첫 주를 만들려고 하지 마시고, 첫 명령을 쳐보는 것에 의미를 두십시오. "오늘은 그냥 한 명령만 쳐본다"라는 작은 약속이 가장 잘 지켜지는 약속이었습니다.

Q3. "코딩 못 하는데 정말 쓸 수 있어요?"

네. 강의장 수강생의 절반 이상이 코딩을 못 하시는 분들이었고, 그분들이 6개월 뒤에 가장 깊이 쓰시는 경우도 많았습니다. 코딩보다 중요한 건 "내가 무엇을 하고 싶은지를 말로 정확히 표현하는 능력"입니다. 이건 어떤 직군이든 평생 써온 능력입니다. 클로드 코드는 그 능력을 코드로 옮겨주는 통역사입니다.

Q4. "회사에서 써도 되나요? 보안은 어떻게 하죠?"

회사 정책에 따라 다릅니다. 일반적으로 안전한 사용 방향은 셋입니다 — (1) 회사 코드는 회사 가이드라인을 먼저 확인. (2) --permission-mode plan으로 검토만. (3) 개인 사이드 프로젝트로 익숙해진 다음 회사에 도입. 가이드 12장 케이스 ⑭의 보안 체크리스트를 매 커밋 전에 한 번씩 돌리는 습관이면 대부분의 회사 환경에서 안전합니다.

Q5. "다음 가이드는 어디서 보나요?"

이 가이드는 입문서이고, 다음 단계 자료는 클로드 코드를 1~2개월 쓰신 다음에 보시는 게 효과가 큽니다. 너무 일찍 다음 자료를 찾으시면 본인 손에 도구가 익기 전이라 흡수가 안 됩니다. 한 달은 가이드 안에서 충분히 굴러보시고, 그다음 위에 적은 학습 리소스로 넘어가시기를 권합니다.

💡 한 번은 이런 일이 있었습니다. 강의 마지막 회차에 "이거 다 외워야 하죠?"라고 진지하게 물으신 분이 계셨습니다. "한 줄도 외우실 필요 없어요"라고 답해드렸더니 표정이 풀어지시더군요. 가이드는 책이고, 책은 외우는 게 아니라 펼치는 것입니다. 막힐 때 펼치는 습관 하나만 들이시면 가이드는 일 년 뒤까지 본인 옆을 지킵니다.

가이드를 덮은 분께 드리는 다섯 가지 약속

가이드를 끝까지 읽으신 분께 다섯 가지를 약속드립니다. 모두 강의장에서 6개월 이상 쓰신 분들에게 실제로 일어난 일들이고, 본인에게도 똑같이 일어날 거라 믿어도 됩니다.

약속 1 — 한 달 안에 일하는 시간이 줄어듭니다

도구가 손에 붙으면 같은 결과물을 만드는 데 드는 시간이 절반으로 줄어듭니다. 처음 한 주는 오히려 더 느립니다 — 새로운 도구를 익히는 비용이 들기 때문이지요. 그 한 주를 넘기시면 내려가는 곡선이 시작됩니다. 한 달이 지나면 본인이 들이는 시간이 절반쯤이 됩니다. 한 달 만에 알아채실 수 있는 첫 변화입니다.

약속 2 — 두 달 안에 결과물의 결이 바뀝니다

시간이 줄어드는 게 첫 변화라면, 결과물의 결이 깊어지는 게 두 번째 변화입니다. 같은 보고서를 써도 더 자세하게 쓰게 되고, 같은 코드를 짜도 테스트와 문서가 함께 따라옵니다. 본인이 더 부지런해진 게 아닙니다. "같은 시간에 더 많이 할 수 있다"는 여유가 결과물에 반영되는 것입니다.

약속 3 — 세 달 안에 동료들이 본인을 다르게 봅니다

이 변화가 가장 늦게 옵니다. 본인은 도구를 쓰면서 매일 일한 것뿐인데, 세 달쯤 지나면 동료들이 "어떻게 그렇게 빠르게 해?"라고 묻기 시작합니다. 그 시점이 가이드의 진짜 보상이 도착하는 순간입니다. 도구를 익힌 게 아니라 일하는 방식이 바뀌었다는 게 다른 사람들 눈에 보이는 단계입니다.

약속 4 — 여섯 달 안에 본인이 누군가의 가이드가 됩니다

여섯 달쯤 지나면 본인 옆자리 사람이 "그거 어떻게 하는 거예요?"라고 묻기 시작합니다. 그때 본인이 이 가이드를 한 부분씩 다시 펼쳐서 설명하시게 됩니다. 가이드를 읽은 사람이 가이드를 쓰는 사람으로 바뀌는 시점입니다. 그 자리에 닿은 분들이 강의장에서 다시 강사로 돌아오시기도 했습니다.

약속 5 — 일 년 안에 일에 대한 태도가 바뀝니다

마지막은 가장 큰 변화입니다. 일 년쯤 지나면 본인이 일을 대하는 태도 자체가 달라집니다. "이 일을 누가 할 수 있는가"가 아니라 "이 일을 어떻게 풀 수 있는가"로 질문이 바뀝니다. 도구가 본인의 한계를 넓혀주기 때문입니다. 강의장에서 가장 많이 듣는 후기가 "예전에는 못 한다고 거절했을 일을 지금은 시도라도 해보게 됐어요"였습니다.

💡 한 번은 이런 일이 있었습니다. 첫 강의에서 "저는 코딩 못해요"라고 하셨던 마케터분이 1년 뒤 "직접 사이트 하나 만들어 봤어요"라며 돌아오셨습니다. 그 분의 표정이 1년 전과 완전히 달라져 있었습니다. 도구가 사람을 바꾸는 것은 아닙니다. 도구가 사람의 한계를 넓혀주는 것입니다.

90일 로드맵 — 첫 일주일 다음에 오는 것

7일이 지나면 본 게임이 시작됩니다. 그다음 12주는 어떻게 흘러야 자연스러운지, 강의장에서 본 분들의 평균 궤적을 정리해 둡니다. 본인 속도와 다르더라도 괜찮습니다 — 방향을 보는 표로만 쓰십시오.

Week 2~4 (3주차까지) — 한 워크플로우를 깊게

첫 주에 만든 작은 자동화 한 가지를 매일 굴리며 깎는 단계입니다. 새 기능을 추가하는 것이 아니라, 같은 자동화를 매일 쓰면서 마찰을 줄이는 일에 집중합니다. 보고서 정리 자동화라면 매주 보고서 형식이 미세하게 바뀔 때마다 CLAUDE.md를 한 줄씩 추가하고, 그 한 줄이 다음 주에 정말 효과를 내는지를 봅니다. 도구는 손에 붙는 데 시간이 걸리고, 그 시간이 진짜 차별화의 시작입니다.

Week 5~8 (2개월차) — 두 번째 워크플로우 + Hooks

첫 자동화가 손에 붙으면 두 번째를 시작하셔도 좋습니다. 이 시점에 보통 Hooks가 자연스럽게 들어옵니다. 매번 같은 검토 단계가 반복되면 PostToolUse Hook으로 자동 검사. 매번 같은 알림이 필요하면 Stop Hook으로 자동 알림. Hooks는 일을 줄이는 게 아니라 실수를 줄이는 도구입니다. 일이 줄지 않아도 마음이 가벼워지는 차이가 분명합니다.

Week 9~12 (3개월차) — 팀에 공유 가능한 Skills

3개월쯤 지나면 본인만의 작업 패턴이 생기고, 그 패턴이 팀에서도 통한다는 것이 보입니다. 이 시점에 Skills를 만드는 게 자연스러워집니다. 본인이 매주 반복하는 한 가지 작업을 /슬래시-커맨드로 묶어서 팀원에게 공유해 보세요. 팀에서 한 명만 잘 써도 팀 평균이 올라가는 시점이 옵니다. 강의장에서 가장 보람 있는 순간은 "제가 만든 Skill이 팀 슬랙에서 다른 사람한테 도움이 됐어요"라는 후기를 받을 때였습니다.

💡 한 번은 이런 일이 있었습니다. 한 마케팅팀 리더분이 3개월차에 만든 "주간 보고 자동화 Skill"이 팀 전체로 퍼져, 6개월 뒤에는 그 회사 다른 부서까지 똑같은 Skill을 쓰게 된 사례가 있었습니다. 작은 한 자동화가 조직 안에서 표준 업무 도구가 되는 시점이 옵니다. 그게 가이드를 다 읽으신 분들의 자연스러운 도착점입니다.

가이드 이후의 학습 — 무엇을 더 봐야 하는가

이 가이드는 입구일 뿐입니다. 한 달쯤 지나면 자연스럽게 다음 영역들이 궁금해지실 겁니다. 미리 어디로 가야 할지 길을 적어둡니다.

깊이 있는 공식 자료

Anthropic Engineering Blog — Claude Code의 설계 결정과 내부 고민이 가장 잘 보이는 곳입니다. 분기에 한 번 정도 정독하시면 도구의 다음 변화를 미리 느낄 수 있습니다.
Anthropic Cookbook (GitHub) — 실전 코드 예제 모음. 우리 가이드의 추상화를 코드로 보고 싶을 때 펼치세요.
Claude Code GitHub Issues — 오픈된 이슈를 한 시간만 훑어도 도구의 한계와 곧 풀릴 문제들이 한눈에 들어옵니다.

한국어 커뮤니티

한국어 슬랙 커뮤니티 — 같은 막힘을 먼저 만난 분들이 답을 가지고 있을 확률이 가장 높은 곳입니다.
GPTaku 유튜브 — 한국어 사례 영상. 텍스트로 안 와닿을 때 영상을 한 번 보시면 시각적 감이 잡힙니다.
로컬 강의·밋업 — 분기마다 진행되는 오프라인 강의. 직접 옆에 앉아서 손을 움직이는 경험이 한 번은 필요합니다.

인접 도구·개념

MCP 생태계 — Anthropic 공식 MCP 서버 목록을 한 번 훑어보세요. 본인 업무에 직접 닿는 한두 개를 찾으면 자동화가 한 단계 점프합니다.
Git의 깊은 부분 — git stash, git rebase -i, git reflog. 클로드가 만든 코드를 다루다 보면 결국 git 깊은 곳까지 닿습니다. 가이드 이후에는 git 자체에 한 시간 투자할 가치가 있습니다.
셸 스크립트 기초 — bash·zsh의 alias·함수 정도만 손에 붙어도 클로드와의 협업이 두 배로 매끄러워집니다.

💡 한 번은 이런 일이 있었습니다. 강의 6개월차 수강생분이 "이제 Claude 없이는 일을 못하겠다"라고 하시면서, 동시에 "그래서 git을 진지하게 공부했어요"라고 하셨습니다. AI 도구를 깊게 쓰면 결국 인접 도구의 기본기로 돌아옵니다. 클로드가 만든 코드를 자주 다루다 보면 git이 필요해지고, 자동화를 만들다 보면 셸 스크립트가 필요해지고, 외부 연결을 시도하면 MCP가 필요해집니다.

자주 빠지는 함정 — 가이드 이후 한 달 시점

3~4주차에 가장 자주 빠지는 함정 셋을 정리해 둡니다. 미리 알면 한 번은 비껴 갈 수 있습니다.

함정 1 — 자동화를 너무 많이 만들기

첫 자동화가 손에 붙으면 자연스럽게 두 번째, 세 번째를 만들고 싶어집니다. 여기서 멈추셔야 합니다. 자동화 셋이 동시에 굴러가기 시작하면 어느 자동화가 어느 결과를 만들었는지 추적이 어려워집니다. 자동화는 한 달에 하나씩 추가하는 리듬이 가장 안전합니다. 첫 달에 하나, 둘째 달에 하나, 셋째 달에 하나 — 이 속도가 결국 가장 빠른 길입니다.

함정 2 — Plan Mode를 안 쓰는 습관

가이드 16장에서 다룬 Plan Mode를 처음에는 잘 쓰시다가, 손이 익으면 슬그머니 안 쓰게 됩니다. 큰 작업 직전에는 늘 Plan Mode를 켜는 습관이 1년 뒤까지 가는 분들의 공통점이었습니다. 작은 작업까지 매번 켜라는 게 아닙니다. 큰 작업 직전, 그 한 번만 켜면 사고의 90%가 막힙니다.

함정 3 — CLAUDE.md를 안 갱신하는 습관

가이드 8장의 CLAUDE.md를 처음에는 정성껏 작성하시다가, 한 달쯤 지나면 갱신을 잊습니다. 새로 알게 된 규칙을 한 줄씩 추가하는 습관이 클로드 코드를 진짜로 본인 도구로 만드는 핵심입니다. 한 줄이면 됩니다. "이 프로젝트에서는 X 라이브러리는 쓰지 마", "에러 메시지는 한국어로", "테스트는 jest 기준으로" — 한 달에 다섯 줄만 보태도 6개월 뒤 CLAUDE.md는 자기 일의 결이 그대로 묻어나는 문서가 됩니다.

💡 한 번은 이런 일이 있었습니다. 한 분의 6개월차 CLAUDE.md를 봤을 때 본문 길이가 처음의 5배가 되어 있었습니다. 그 분은 "이게 제 일하는 방식이에요"라고 하셨고, 실제로 그 문서만 봐도 그분이 어떤 결로 일하는지가 보였습니다. CLAUDE.md는 본인의 작업 자서전이 됩니다.

한 페이지 참조 카드

공식 문서  : 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

피드백·오탈자 제보·새 챕터 요청 모두 환영합니다. 감사합니다.

변경 이력

2026-05-21 — 공식 문서 기준 종합 점검

공식 문서가 docs.claude.com → code.claude.com으로 이전된 시점에 맞춰 30개 챕터 전수 점검 + 아키텍처 정비를 진행했습니다.

사실관계 정정 (P0)

25장 전면 재작성 — /voice·/mobile·/sandbox 슬래시 명령은 공식에 존재하지 않습니다. 음성은 iOS Claude 앱·웹의 마이크 입력으로, 모바일은 claude --teleport·Remote Control·Channels로, sandbox는 OS 격리 모드(macOS Seatbelt / Linux landlock / Windows AppContainer)로 정정. 챕터 제목도 "모바일·웹·샌드박스 실전 활용"으로 변경했습니다.
18장 Sub-agents — 내장 Explore에 "Haiku 모델 고정"이라 적혀 있던 부분 완화. 공식 문서는 모델 고정을 명시하지 않습니다.
06장 플러그인 — MCP 서버 저장소 경로를 anthropics/mcp-servers(잘못) → modelcontextprotocol/servers와 Anthropic Directory로 정정.
29장(이 페이지)에 남아 있던 옛 도메인 docs.claude.com/... 링크를 code.claude.com/docs/en/overview로 교체.

구버전·일관성 보강 (P1)

03장 Pro 플랜의 "Opus 1M 추가 사용량" 표현을 "Max 이상에서 본격 사용" 늬앙스로 완화.
12장 인증 종료를 /logout 슬래시와 claude logout 두 경로 모두 안내, CLI 옵션은 claude --help로 최신 확인하라는 주의 추가.
14장 — Computer Use는 Claude API 도구이지 Claude Code 기능이 아님을 명시. /loop는 Routines(/schedule)로 정정. /voice는 iOS·웹 마이크로 정정. /effort 레벨은 모델별로 가용 범위가 다르다는 단서 추가.
16장 hooks 이벤트 수를 "약 29개" → "20여 개"로 완화 (공식 목록이 빠르게 변동).
17장 Skills frontmatter 표를 확장 (argument-hint, arguments, effort, agent, hooks, paths, shell). ${CLAUDE_SKILL_DIR} 변수 한 줄 추가. .claude/commands/도 정식 동작함을 명시.
20장 비용 챕터에 5시간 롤링 + 주간 한도(weekly limit) 한 줄 보강. anthropic.com/pricing → claude.com/pricing로 통일.
21장 — "Agent SDK CLI" 표현이 부정확. 공식은 claude -p / --print 비대화형 모드라고 부르며, Agent SDK는 별도 제품임을 명시.

소소한 보강 (P2)

01장 진입점 카드에 iOS Claude 앱·Slack @Claude·Chrome 디버깅 통합 한 줄 추가.
04장 node -v 점검에 "npm 설치한 경우에 한정 (네이티브 인스톨러는 Node 불필요)" 단서.
09장 .claude/commands/ 설명에 Skills(.claude/skills/<name>/SKILL.md) 권장 한 줄.
12장 Docker node:20 권장 줄에 "네이티브 인스톨러는 Node 불필요" 단서.
17-statusline-cost에 플러그인 subagentStatusLine 한 줄.
23장 worktree에 WorktreeCreate/WorktreeRemove Hook 자동화 한 줄.

사이트 인프라

Next.js 16 컨벤션에 맞춰 middleware.ts → proxy.ts로 마이그레이션 (런타임은 동일, 다음 메이저 호환).
미사용 의존성 6종 제거 (remark, remark-parse, remark-rehype, rehype-stringify, unified, rehype-highlight).
sections.json에 Zod 스키마 검증 도입 — id/order 중복은 빌드 실패로 즉시 차단.
"23장" 하드코딩 제거 — Hero, 메타, OpenGraph 모두 sections.length 기반 동적 계산. 챕터 추가 시 자동 반영.
GA4를 @next/third-parties/google로 마이그레이션, 호스트별 SSR 매칭.
TypeScript target ES2017 → ES2022, next.config.ts에 images.formats(avif/webp) + compiler.removeConsole 추가.

2026-05-21 (2차) — 5팀 병렬 정밀 점검 후속

같은 날 5개 점검팀(콘텐츠 4팀 + 인프라 1팀)을 병렬로 돌려 30개 챕터를 한 번 더 훑은 결과 발견된 항목을 정리했습니다.

사실관계 정정

08장 CLAUDE.md 우선순위 재정밀화 — managed/Enterprise 정책을 Mermaid·본문·요약표에 모두 추가. CLAUDE.local.md 자동 .gitignore는 "/init --personal 옵션 사용 시"로 단서화. ./.claude/CLAUDE.md도 공식 지원 명시.
08장 영문 템플릿 — "Always write in Korean"이 영문 가이드 예시에 잔존 → "Match the language of the prompt"로 정정.
09·10장 Shift+Tab — "Plan ↔ 일반 토글" 단순화 표현을 공식대로 "default → acceptEdits → plan 3모드 순환"으로 통일. 07장과 정합.
12장 인증 로그아웃 — claude logout(비공식 표기)을 공식 claude auth logout로 정정. /logout 슬래시도 병기.
12장 파일 복구 — git checkout --를 modern Git의 git restore로 통일 (11장과 일관). ko/en 동시.
14장 /voice·/loop 잔존 정리 — mermaid 노드·표·체크리스트에 남아 있던 슬래시 명령 표현을 "iOS·웹 마이크 입력" / "Routines(/schedule)"로 일괄 정정. L80 디스클레이머와 정합.
17-skills frontmatter "Skills로 통합" 표현 완화 — .claude/commands/도 정식 동작함을 명시. 두 메커니즘은 별개이며 같은 이름이 있으면 Skill이 우선한다는 점 추가.
16-hooks — WorktreeCreate·WorktreeRemove 이벤트를 본문 이벤트 목록에 추가 (이미 23장에서만 언급).
25장 인용 정정 — "다음 장(22. 다음 단계 & 리소스)" → 실제 22장 H1 본문 제목 "22. 가이드를 마치며 — 지금 알고 있는 것들"로 정정.

구조·일관성

06장 헤딩 중복 — "다음으로: 핵심 개념 한 바퀴" 헤딩이 챕터 중간·끝 두 번 등장 → 중간 헤딩을 "잠깐 정리"로 변경, 체크리스트와 다음 장 안내가 챕터 끝에 오도록 재배치. ko/en 동일.
00장 en 단락 중복 — 거의 같은 의미의 두 단락 → 한 단락만 유지.
02장 수치 일치 — ko "1분이 채 안 걸렸습니다" / en "in 40 seconds" 불일치 → "40초"로 통일.
03장 ko 마무리 체크리스트 — en에는 있었지만 ko에 누락 → 추가. "다섯 가지 작은 습관"도 ko 4개 → en 5개와 일치하도록 보강.
20-cost ko — "비용 절약 체크리스트" 블록이 두 번 등장 → 11항목 완전판만 유지. L450 ****…**** 마크다운 오타 → 정상 **…**로.
24장 우선순위 표 — 18장(closest-wins)과 결이 다르던 표 순서를 "프로젝트 > 개인 > 엔터프라이즈"로 재정렬 + 캡션 추가.

ko↔en 분량 격차 해소

16-hooks ko 1417줄 vs en 562줄 → en이 28개 섹션 번역 추가되어 1437줄로 동등 분량 (Hooks JSON 문법, 전체 이벤트 목록(Worktree 포함), 팀 도입 후기, FAQ, 고급 시나리오 등).
11-git-with-teacher ko 426줄 vs en 333줄 → en에 PAT 안내·"Git이 설치 안 됐다" Q&A·"브랜치는 혼자 쓸 때도 유용"·"GitHub Actions" 등 5개 섹션 번역 추가 → 425줄로 동등.
05-workflow en — "워크플로우를 망치는 나쁜 습관들(함정 ①~④)" 섹션을 영어로 번역해 ko 동일 위치에 추가.

영문 페이지 이미지 경로 — 04·09·14·15·16·17장 6곳에서 영문 페이지인데 src가 /images/docs/ko/...였던 것을 /images/docs/...로 정정.

소소한 보강 — 00장 "2026년 4월" → "2026년 5월" 시점 갱신, 09장 /model alias에 opus[1m]·sonnet[1m] 추가, 폰트 fallback 스택에 CJK(Apple SD Gothic Neo/Noto Sans KR/Malgun Gothic) 명시 — 본문 부호(, . ·)가 가로획처럼 보이던 렌더링 이슈 해소. Hero "23장" 하드코딩 3곳 추가 발견·제거(totalChapters props로 분리).

Claude Code, 처음부터 끝까지

00. 시작하기 전에

Q1. 같은 회사 도구인데 Cowork와 결이 다른 이유는?

왜 Cowork는 안전하지만 느리고 비쌀까

두 도구를 함께 써야 하는 시점

Q2. 데스크톱 앱이 편한데 굳이 검은 화면으로 옮기면 무엇을 얻나요?

이유 1: 동시에 여러 일이 굴러가는 흐름

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

이유 3: 안정성 — 좁혀지지만 아직은 차이가 있는

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

옮길 시점을 알아채는 신호 세 가지

Q3. 첫 명령을 쳐봤는데 아무 것도 안 일어나면 정상인가요?

1단계 — 남이 만든 결과물부터 둘러보기

2단계 — "만들어줘" 대신 "물어봐"

그래서 첫 명령이 조용해도 괜찮은 이유

Q4. 1주일 써보니 토큰이 다 떨어지는데 제가 잘못 쓰고 있나요?

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

Max로 올라가면 무엇이 바뀌는가

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

어떤 플랜을 고를까 — 내 상황별 권장

이 장을 덮기 전에

01. 클로드 코드, 한 줄로 정리하면

한 장면으로 머릿속에 박는 30초 정의

같은 모델, 다른 쓰임새 — 웹 챗봇과의 다섯 갈래 비교

직군별 풍경 세 장면 — 같은 도구, 다른 결

어떤 사람에게 효과가 큰가 — 세 부류

어디서 돌릴 수 있나 — 입구 네 곳

5분 체험 — 폴더 하나를 던져보기

한 줄로 마무리하면

이 장을 덮기 전에

02. 클로드 코드, 사실 코딩보다 이쪽에서 더 썼습니다

Claude.ai 채팅과 비교해서 뭐가 다른 건가요

코딩 영역에서 할 수 있는 일

자연어로 지시하면 됩니다

바이브코딩: 분위기로 만드는 소프트웨어

더 잘 굴리는 네 가지 습관

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

리서치 & 분석

문서 & 콘텐츠 제작

데이터 처리

학습 보조

비즈니스 워크플로우

개인 AI 워크스페이스

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

시간 기준으로 보는 비교: 회의록 정리

한 줄로 줄이면

이 장을 덮기 전에

03. 요금제 안내

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

플랜별 차이를 한눈에

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

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

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

비용 구조: 큰 그림

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

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

03과 20의 역할 분담

이 장을 떠나기 전에

터미널에 처음 명령어를 쳤을 때: 설치부터 첫 실행까지

설치 전에: 환경 점검 세 가지

내 OS에서 동작하나요

하드웨어 기준이 있나요

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

OS별 설치: 어느 길로 들어가든 결과는 같습니다

macOS · Linux · WSL에서

Windows에서: 네 가지 입구

WSL vs PowerShell, 뭘 고르면 되나요

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

Alpine Linux 추가 패키지

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

로그인 흐름을 그림으로

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

설치가 잘 됐는지 확인하는 두 가지 명령

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

처음 만나는 벽: 가장 흔한 세 가지 상황

상황 ① · curl: command not found

상황 ② · claude: command not found

상황 ③ · Windows에서 "Git이 없습니다" 메시지

설치가 끝났다면

이어서 알아두면 좋은 것들

Claude Code,
처음부터 끝까지

상황 ① · `curl: command not found`

상황 ② · `claude: command not found`

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

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