프롬프트 · CLAUDE.md · 스킬 · 훅 — 뭘 어디에 써야 하나
목차
- 왜 같은 지시를 여섯 번이나 다시 타이핑하게 될까?
- 네 가지는 결국 뭐가 다를까? — 새 직원 한 명이 들어왔다고 생각해보기
- 아무 데나 적으면 왜 안 될까? — 눈에 안 보이는 토큰 비용
- 질문 네 개면 자리를 정할 수 있을까?
- 실제 사례에 결정 트리를 대보면 어떻게 될까?
- CLAUDE.md는 왜 자꾸 뚱뚱해질까?
- 서브에이전트와 MCP는 이 지도의 어디쯤일까?
전체 지도
자, 본격적으로 들어가기 전에 지도 한 장부터 펼치겠습니다. 오늘 우리가 돌아볼 땅은 생각보다 좁아요. 가운데 네 개의 서랍이 있고, 그 서랍을 여는 열쇠는 질문 네 개뿐입니다. 왼쪽에서는 "왜 이게 문제인가"를, 가운데에서는 "네 개가 어떻게 다른가"와 "얼마나 비싼가"를, 오른쪽에서는 "그래서 어디에 넣을 것인가"를 다룹니다. 아래쪽 구석에 작게 그려진 두 칸은 오늘의 주인공이 아닙니다. 헷갈리기 쉬워서 자리만 표시해 둔 이웃 동네예요.
이 글을 다 읽고 나서 딱 하나만 캡처해 가신다면 4번 섹션의 그림이면 됩니다. 나머지는 전부 그 그림을 설명하고 뒷받침하는 이야기라고 생각하셔도 좋습니다.
1. 왜 같은 지시를 여섯 번이나 다시 타이핑하게 될까?
지도에서 보면 지금은 맨 왼쪽, 출발점입니다.
이번 주에 이런 문장을 몇 번이나 치셨나요. "우리 프로젝트는 클래스 컴포넌트 안 쓰고 함수형만 씁니다." 저는 지난주에 여섯 번 쳤습니다. 새 대화를 열 때마다, 새 파일을 만들 때마다, 어제 분명히 말했던 그 이야기를 처음부터 다시 했어요. 그러다 문득 이런 생각이 들더군요. 나 지금 뭐 하고 있는 거지?
이건 AI가 멍청해서 생기는 일이 아닙니다. 대화창은 원래 그렇게 생긴 물건이에요. 카페에서 옆자리 사람에게 길을 알려주는 상황을 떠올려 보세요. 그 사람이 자리를 뜨면 대화는 사라집니다. 다음에 다른 사람이 와서 같은 걸 물으면, 당연히 처음부터 다시 설명해야죠. 대화창에 적은 지시는 딱 그 수준의 수명을 가집니다. 창을 닫으면 끝이에요.
그래서 저는 훈련생들에게 이렇게 말합니다. 같은 말을 반복하고 있다면, 그건 AI를 탓할 일이 아니라 "말할 자리를 잘못 골랐다"는 신호입니다. 반복은 버그가 아니라 알림입니다. "이 지시는 대화창보다 더 오래 사는 곳에 적혀야 한다"고 알려주는 거죠.
그럼 대화창 말고 어디에 적어야 할까요? 다행히 후보는 그렇게 많지 않습니다. 자리는 딱 네 군데예요. 프롬프트, CLAUDE.md, 스킬, 훅. 그리고 이 네 군데 중 어디를 고를지는 질문 네 개면 결정됩니다. 오늘 글의 약속은 이게 전부입니다. 네 개의 자리, 네 개의 질문.
혹시 지금 "스킬이 뭔데요?", "훅은 또 뭐야?" 하는 생각이 드셨다면 아주 정상입니다. 용어는 다음 섹션에서 회사 조직에 빗대어 한 번에 정리하고 들어가겠습니다.
참고: Steering Claude Code: when to use CLAUDE.md, skills, hooks, and subagents — Anthropic
2. 네 가지는 결국 뭐가 다를까? — 새 직원 한 명이 들어왔다고 생각해보기
지도의 두 번째 가지, 네 개의 서랍에 이름을 붙이는 자리입니다.
용어를 하나씩 정의하는 대신, 비유 하나를 심어놓고 글 끝까지 쓰겠습니다. AI 코딩 도구를 오늘 입사한 신입 사원 한 명이라고 생각해보세요. 실력은 좋은데 우리 회사가 처음인 사람이요. 이 사람에게 일을 시키는 방법은 현실에서도 네 가지입니다.
| 항목 | 회사로 치면 | 언제 읽히나 |
|---|---|---|
| 프롬프트 | 지금 자리에서 하는 구두 지시 | 이번 대화에서만 |
| CLAUDE.md | 사원 수칙 / 온보딩 문서 | 매번, 무조건 |
| 스킬 | 캐비닛 속 업무 매뉴얼 | 그 업무일 때만 꺼내서 |
| 훅 | 출입문 보안 게이트 | 사람 판단과 무관하게 자동 |
프롬프트는 지금 옆에 가서 "이건 이렇게 해주세요"라고 말하는 겁니다. 빠르고 편한데, 그 사람이 퇴근하면 사라져요.
CLAUDE.md는 입사 첫날 손에 쥐여주는 사원 수칙입니다. 프로젝트 루트에 두는 마크다운 파일이고, 세션이 시작될 때마다 통째로 읽힙니다. "우리는 pnpm 씁니다", "API 핸들러는 여기 있습니다" 같은, 어떤 일을 하든 알고 있어야 하는 것들의 자리예요.
스킬은 캐비닛에 꽂혀 있는 업무 매뉴얼입니다. SKILL.md 파일 하나와 필요하면 스크립트 몇 개가 든 폴더인데, 재미있는 건 평소엔 표지만 보인다는 점입니다. 신입이 캐비닛 앞을 지나가며 등에 붙은 제목만 읽고 있다가, "아 지금 이 업무네" 싶을 때 그 책을 꺼내 펼치는 구조죠.
훅은 출입문 보안 게이트입니다. 사원이 착한지 나쁜지, 오늘 기분이 어떤지와 아무 상관이 없어요. 카드를 안 찍으면 문이 안 열립니다. 실제로도 훅은 파일 편집 후나 명령 실행 전 같은 특정 시점에 셸 스크립트를 돌리는 장치라, 모델이 무슨 판단을 하든 무조건 실행됩니다.
여기서 오늘의 핵심 한 줄이 나옵니다. 네 가지의 차이는 "기능"이 아니라 "언제 읽히는가"입니다. 이 축 하나만 잡으면 나머지는 저절로 따라옵니다. 그런데 말이죠, "언제 읽히는가"가 왜 그렇게 중요할까요? 읽히는 횟수가 곧 돈이기 때문입니다.
참고: Steering Claude Code — Anthropic · How Claude remembers your project — Claude Code Docs · Hooks reference — Claude Code Docs
3. 아무 데나 적으면 왜 안 될까? — 눈에 안 보이는 토큰 비용
지도 가운데, 대부분의 소개 글이 그냥 지나치는 칸입니다.
대부분의 글은 "이건 이런 거예요"까지만 말하고 끝냅니다. 하지만 실무에서 자리를 잘못 고르면 아픈 이유는 개념이 아니라 비용 때문이에요. 숫자를 보겠습니다.
CLAUDE.md는 매 요청마다 전액을 냅니다. 세션이 시작될 때 통째로 컨텍스트에 들어가고, 대화가 압축(compaction)되면 다시 주입됩니다. 공식 문서의 권고는 명확합니다. 파일 하나당 200줄 이내로 유지하라는 거예요. 실무 가이드들은 이를 토큰으로 환산해 2,000토큰 안쪽을 상한선으로 잡습니다. 여기 적힌 300번째 줄은, 오늘 여러분이 CSS 한 줄 고칠 때도 꼬박꼬박 값을 치릅니다.
스킬은 표지값만 상시로 냅니다. 스킬 하나가 평소 차지하는 건 이름과 설명 한 줄, 대략 20~100토큰 수준입니다. 그러다 요청과 맞아떨어지면 그때 본문이 로드되고, 그 본문은 대개 수백 토큰에서 수천 토큰이에요. 이 구조를 점진적 공개(progressive disclosure) 라고 부릅니다. 도서관 비유로 돌아가면, 책등의 제목만 읽고 다니다가 필요한 책 한 권만 뽑아 드는 거죠. 참고 파일이나 스크립트는 한 단계 더 뒤에 숨어 있어서, 스크립트는 실행 결과만 들어오고 코드 자체는 컨텍스트에 오지도 않습니다.
훅은 모델을 거치지 않으니 토큰 비용이 0입니다. 셸에서 도는 프로그램이니까요. 다만 그 훅이 뱉은 출력이 모델에게 전달되는 순간, 그 출력만큼은 비용이 됩니다. 그러니 훅이 로그를 200줄씩 토해내게 만들면 안 되겠죠.
여기서 초보자들이 가장 자주 하는 오해 하나를 풀고 가겠습니다. "스킬 많이 깔면 느려지지 않나요?" 아닙니다. 스킬 20개를 깔아도 대기 비용은 다 합쳐서 1,000토큰 남짓이에요. 오히려 CLAUDE.md를 길게 쓰는 쪽이 훨씬 비쌉니다. 스킬 20개보다 CLAUDE.md 300줄이 더 무겁다는 얘기입니다. 게다가 파일이 길어질수록 지시를 지키는 비율 자체가 떨어진다는 게 공식 문서의 경고이기도 합니다.
정리하면 이렇습니다. 자리를 고른다는 건 취향의 문제가 아니라 "이 문장에 매번 돈을 낼 것인가, 필요할 때만 낼 것인가" 를 정하는 일입니다.
참고: Agent Skills overview — Claude Platform Docs · Skills vs Hooks vs Prompts: Claude Code Decision Guide (2026) — explainx.ai · How Claude remembers your project — Claude Code Docs
4. 질문 네 개면 자리를 정할 수 있을까?
지도의 정중앙입니다. 오늘 글에서 딱 하나만 가져가신다면 이 그림입니다.
비용 감각까지 챙기셨으니 이제 결정만 남았습니다. 위에서 아래로 내려가면서, 처음 "예"가 나오는 곳에서 멈추면 됩니다. 아래로 더 내려가지 마세요. 순서 자체가 답의 일부입니다.
① 이번 한 번만 필요한가? → 프롬프트 오늘만, 이 파일만, 이 실험만. 그렇다면 그냥 대화창에 치세요. 재사용할 일 없는 지시를 파일로 만드는 것도 낭비입니다.
② 모든 작업에 항상 적용되나? → CLAUDE.md 여기서 "항상"은 문자 그대로입니다. 버그를 고칠 때도, 테스트를 쓸 때도, 문서를 다듬을 때도 참이어야 해요. 하나라도 예외가 떠오르면 이건 CLAUDE.md 감이 아닙니다.
③ 특정 작업일 때만, 여러 단계로 반복되나? → 스킬 조건이 두 개라는 데 주목하세요. "특정 작업일 때만"(항상은 아니고) 그리고 "여러 단계"(한 줄 규칙이 아니고). 이 둘이 동시에 참일 때가 스킬의 자리입니다.
④ AI 판단과 무관하게 무조건 실행돼야 하나? → 훅 "되도록 해주세요"가 아니라 "안 하면 진행 불가"인 것들이요. CLAUDE.md에 적은 규칙은 지시이지 강제가 아닙니다. 공식 문서도 이 점을 분명히 합니다. 반드시 막아야 한다면 훅으로 내려야 해요. 그래서 저는 이렇게 구분합니다. 사원 수칙에 "금고 열지 마세요"라고 쓰는 것과, 금고에 자물쇠를 다는 것은 다른 일입니다.
혹시 ②와 ③ 사이에서 헤매신다면 판별식이 하나 있습니다. "이걸 몰라도 되는 작업이 존재하는가?" 존재하면 스킬, 존재하지 않으면 CLAUDE.md입니다.
참고: Skills vs Hooks vs Prompts: Claude Code Decision Guide (2026) — explainx.ai · How Claude remembers your project — Claude Code Docs
5. 실제 사례에 결정 트리를 대보면 어떻게 될까?
지도에서 결정 트리 바로 오른쪽, 손에 쥐여드리는 칸입니다.
트리는 눈으로 볼 땐 다 쉬워 보입니다. 진짜 실력은 애매한 걸 만났을 때 나오죠. 다섯 장을 서랍에 넣어보겠습니다.
"이번 컴포넌트만 타입스크립트로 짜주세요" → 프롬프트. 질문 ①에서 바로 멈춥니다. 이번만이니까요.
"우리는 Tailwind만 씁니다" → CLAUDE.md. 컴포넌트를 만들든 버그를 잡든 스타일을 건드리는 순간 항상 참입니다. 게다가 한 줄짜리 규칙이라 절차도 아니고요.
"DB 마이그레이션 절차 7단계" → 스킬. 마이그레이션은 매일 하는 일이 아닙니다(항상 ✕). 그런데 할 때는 순서를 정확히 밟아야 하죠(여러 단계 ○). 질문 ③에 정확히 걸립니다.
"커밋 전에는 항상 린트" → 훅. 여기서 헷갈리기 쉽습니다. "항상"이라는 단어 때문에 ②로 가고 싶어지거든요. 하지만 다시 물어보세요. 이건 알고 있어야 할 사실인가요, 무조건 일어나야 할 사건인가요? 후자입니다. CLAUDE.md에 적으면 "잊어버릴 수도 있는 규칙"이 되고, 훅으로 만들면 잊어버릴 수가 없습니다.
"PR 설명문 작성 규칙" → 스킬. 마지막이 제일 갈리는 지점이라 조금 더 붙이겠습니다. 많은 분이 이걸 CLAUDE.md에 넣습니다. "우리 팀 PR 규칙인데 당연히 항상 적용해야지" 싶어서요. 그런데 질문 ②를 정직하게 던져보세요. 모든 작업이 PR로 끝나나요? 아닙니다. 로컬에서 실험만 하고 버리는 작업, 로그만 들여다보는 작업, 문서만 고치는 작업 — PR과 무관한 시간이 훨씬 깁니다. 그 모든 순간에 "PR 본문에는 변경 사유를 먼저 쓰고, 스크린샷은 접은 블록에 넣고…" 하는 서너 문단이 컨텍스트를 차지하는 거예요. 반면 스킬로 두면 PR을 쓸 때만 펼쳐집니다. "우리 팀 규칙이니까 항상"과 "모든 작업에 항상"은 다른 말입니다. 이 문장 하나가 CLAUDE.md 백 줄을 지켜줍니다.
참고: Claude Code Skills in 2026: The Complete Guide — Totalum · Skills vs Hooks vs Prompts — explainx.ai
6. CLAUDE.md는 왜 자꾸 뚱뚱해질까?
지도의 오른쪽 아래, 경고 표지가 붙은 칸입니다.
제가 본 CLAUDE.md 중 최고 기록은 400줄이 넘었습니다. 열어보니 절반이 절차서였어요. 배포 순서, 마이그레이션 순서, 릴리스 체크리스트… 전부 훌륭한 문서였지만 자리가 틀렸습니다. 신입에게 준 사원 수칙 안에 "DB 마이그레이션 7단계"가 들어 있는 셈이거든요. 그 신입은 오타 하나 고치러 들어올 때도 마이그레이션 절차를 처음부터 끝까지 읽고 시작합니다.
증상은 대체로 이렇게 나타납니다. 파일은 300줄을 넘겼는데, 그런데도 규칙이 잘 안 지켜집니다. 이게 참 얄궂은 대목이에요. 길게 썼으니 더 확실히 지켜질 것 같은데 실제로는 반대입니다. 공식 문서도 "긴 파일은 컨텍스트를 더 쓰고 준수율을 떨어뜨린다"고 못 박고 있어요. 사람도 똑같잖아요. 규칙 열 개는 외우지만 백 개는 아무도 안 봅니다.
처방은 잘라내는 게 아니라 옮기는 것입니다. 이 구분이 중요해요. 필요한 내용이라서 쓴 건데 무작정 지우면 그 지식은 사라집니다. 절차서는 스킬로 옮기세요. 내용은 그대로 살아 있고, 필요할 때만 펼쳐집니다.
한 가지 더 알아두면 좋은 중간 선택지가 있습니다. 경로 기반 규칙(path-scoped rules) 이에요. .claude/rules/ 폴더에 파일을 두고 프론트매터에 paths: ["src/api/**/*.ts"] 처럼 적어두면, Claude가 그 경로의 파일을 건드릴 때만 로드됩니다. "API 핸들러는 반드시 입력을 검증한다" 같은 규칙이 여기 딱 맞아요. 절차는 아니라서 스킬은 과하고, 그렇다고 모든 작업에 필요하지도 않은 규칙 — CLAUDE.md와 스킬 사이에 낀 문장들의 집입니다.
그러니 CLAUDE.md가 두꺼워졌다면 이렇게 세 갈래로 분류해보세요. 절차인가 → 스킬. 특정 폴더에서만 참인가 → 경로 규칙. 반드시 강제돼야 하나 → 훅. 이렇게 덜어내고 나면 정작 남는 건 몇십 줄입니다. 그리고 그 몇십 줄은 아주 잘 지켜집니다.
참고: How Claude remembers your project — Claude Code Docs · Skills vs Hooks vs Prompts — explainx.ai
7. 서브에이전트와 MCP는 이 지도의 어디쯤일까?
지도 맨 아래 구석, 작게 표시해 둔 이웃 동네입니다. 짧게 짚고 나오겠습니다.
검색하다 보면 이 두 단어가 꼭 같이 나옵니다. 그래서 "이것도 적을 자리인가?" 하고 헷갈리시는데, 결론부터 말하면 둘 다 다른 층에 있습니다.
서브에이전트는 다른 방에 인턴을 따로 붙이는 것에 가깝습니다. 독립된 문맥에서 일을 시키고, 끝나면 결과 요약만 받아옵니다. 로그 수천 줄을 뒤지는 작업을 메인 대화에서 하면 그 쓰레기가 전부 컨텍스트에 남지만, 인턴을 시키면 "이 세 줄이 문제입니다"만 돌아오죠. 문맥이 섞이면 안 되는 큰 작업용입니다. 자리가 아니라 작업 방식이에요.
MCP는 저장 위치가 아니라 외부 시스템으로 가는 통로입니다. 사내 DB나 이슈 트래커를 열 수 있는 열쇠를 쥐여주는 쪽에 가깝습니다. 스킬이 "이 업무는 이렇게 합니다"라는 매뉴얼이라면, MCP는 "그 업무를 하려면 이 문을 열어야 합니다"의 문이에요. 실제로 스킬이 MCP로 열린 도구를 불러 쓰기도 하니, 경쟁 관계가 아니라 층이 다릅니다.
여기서 더 깊이 들어가면 오늘의 결정 트리가 묻힙니다. "이건 다른 층위다"만 챙기시면 충분합니다. 서브에이전트와 MCP를 제대로 다루는 건 별도의 글이 필요한 주제예요.
참고: Steering Claude Code — Anthropic · Claude Code Skills in 2026: The Complete Guide (vs Hooks, vs Subagents, vs MCP) — Totalum
마무리 — 3번 규칙
오늘 이야기를 실제 습관으로 바꾸는 방법은 딱 하나입니다. 같은 지시를 세 번 반복했다면, 그때가 프롬프트를 벗어날 때입니다. 한 번은 우연이고 두 번은 그럴 수 있는 일이지만, 세 번째는 신호예요. 그 순간 손을 멈추고 질문 네 개를 던지시면 됩니다.
그리고 시작은 작게 하세요. CLAUDE.md 10줄이면 충분합니다. 처음부터 완벽한 규칙 문서를 쓰려고 하면 300줄짜리 괴물이 태어나고, 그 괴물은 아무도 안 지킵니다. 스킬은 실제로 반복이 확인된 다음에 만드세요. 아직 두 번밖에 안 한 절차를 미리 매뉴얼로 만드는 건 상상 속 문제를 푸는 일입니다.
다음 글에서는 그 CLAUDE.md 10줄에 실제로 무엇을 적을지, 잘 지켜지는 규칙 파일은 어떻게 생겼는지를 예시와 함께 다루겠습니다.
댓글
불러오는 중입니다…