2장. Claude Code의 무기 6가지

이 장이 끝나면: CLAUDE.md·Skills·Subagents·Slash 명령·Hooks·MCP가 각각 무엇이고 어떤 문제를 푸는 도구인지 구분할 수 있다. 그리고 "역할을 어디에 담을 것인가"라는 질문에 답할 기준이 생긴다.

2.1 개념 — 왜 기능이 여섯 가지나 필요한가

지시 한 번으로 온티켓 소개 페이지를 만들 수 있었다. 이 방식만으로도 간단한 것은 얼마든지 만들 수 있다. 그런데 프로젝트가 커지고 파일이 수십 개가 되면, 네 가지 문제가 반드시 나타난다. 미리 알고 가자.

이 네 가지 문제를 먼저 이해하는 것이 이 장의 절반이다. 기능 여섯 개의 이름과 사용법을 외우는 것보다, "이 기능은 어떤 문제를 해결하려고 만들어졌는가"를 아는 편이 훨씬 오래 남는다. 도구는 잊어도 문제는 계속 마주치기 때문이다. 그리고 이 네 문제는 온티켓에서만 생기는 것이 아니라, 규모가 조금이라도 있는 모든 협업 — 사람끼리의 협업이든, 사람과 AI의 협업이든 — 에서 똑같이 나타난다. 그래서 해법도 회사가 사람을 조직하는 방식과 놀랄 만큼 닮았다.

문제 1 — AI가 잊는다. Claude Code와의 대화(세션)는 영원하지 않다. 내일 아침 새 세션을 열면 AI는 어제 우리가 정한 규칙 — "프론트에서 DB에 직접 접근하지 않는다" 같은 — 을 모른다. 매 세션 처음부터 다시 설명할 것인가?

여기서 '세션(session)'이라는 말을 짚어 두자. 세션은 원래 '한 번의 모임·한 차례의 진행'을 뜻한다. 회의 한 건, 상담 한 회차를 세션이라 부르는 것과 같다. Claude Code에서 세션이란 claude를 실행해서 대화를 시작한 순간부터, 그 창을 닫거나 /exit으로 끝낼 때까지의 한 판을 말한다. 이 한 판 안에서 오간 모든 말은 AI가 기억하지만, 판이 끝나면 그 기억은 사라진다. 다음 날 여는 것은 어제 이어서가 아니라 새 판이다.

왜 매번 잊게 만들었을까? 게을러서가 아니라 구조상 그렇다. AI는 대화하는 동안 지금까지 오간 말 전체를 컨텍스트(context) 라는 작업 공간에 올려 두고 참고한다. 컨텍스트는 '문맥·맥락'이라는 뜻인데, 쉽게 말하면 AI가 지금 답을 만들 때 눈앞에 펼쳐 놓고 보는 '책상 위'다. 이 책상에는 한계가 있어서 무한정 쌓을 수 없고, 세션이 끝나면 책상을 통째로 비운다. 그래서 어제의 결정은 오늘 책상에 없다. 사람으로 치면, 매일 아침 기억을 잃고 출근하는 유능한 신입이다. 실력은 뛰어난데 어제 회의를 기억하지 못한다. 이런 신입에게 우리가 하는 일은 뻔하다 — 매일 아침 다시 브리핑하거나, 아니면 책상에 항상 붙여 두는 메모를 만들어 준다. 후자가 바로 첫 번째 무기다.

문제 2 — 같은 지시를 반복한다. "PM처럼 요구사항을 분석해서 PRD를 써줘. PRD에는 목표·범위·완료기준이 들어가고, 형용사는 전부 측정 가능한 기준으로 바꾸고…" — 이 지시를 기획 문서가 필요할 때마다 처음부터 다시 칠 것인가?

이것은 '잊는다'와는 다른 종류의 낭비다. AI가 기억을 못 해서가 아니라, 애초에 매번 길게 설명해야 하는 일이라서 생긴다. 좋은 지시일수록 길고 정교한데, 그 좋은 지시를 머릿속이나 메모장에 넣어 두고 매번 복사해 붙이는 것은 사람 쪽의 반복 노동이다. 회사에서 같은 일이 반복되면 우리는 '업무 매뉴얼'이나 '표준 양식'을 만든다. 신입이 올 때마다 구두로 설명하는 대신 문서 하나를 건네고 "이대로 하라"고 한다. 두 번째 무기가 정확히 이 매뉴얼이다.

문제 3 — 하나의 AI가 모든 일을 한다. 코드를 만든 AI에게 "네가 만든 코드를 검토해봐"라고 하면 어떻게 될까. 자기가 짠 코드를 자기가 검사하는 구조다. 회사에서 개발자가 자기 코드를 스스로 승인해서 배포하는 것과 같다. 검토자는 다른 사람이어야 하고, 검토자에게는 고칠 권한이 없어야 한다. AI에게도 같은 구조가 필요하다.

이 문제는 두 겹이다. 첫째는 '독립성' — 방금 코드를 짠 당사자는 그 코드에 애착과 선입견이 있어서, 자기 논리의 빈틈을 잘 보지 못한다. 사람도 자기 글의 오타를 못 잡는다. 둘째는 '권한' — 검토자가 발견한 김에 직접 고쳐 버리면, 무엇이 왜 잘못됐는지 남지 않고 검토라는 절차 자체가 유명무실해진다. 그래서 조직은 '만드는 사람'과 '보는 사람'을 나누고, 보는 사람에게는 고칠 손을 애초에 주지 않는다. 감사팀에게 장부를 고칠 권한을 주지 않는 것과 같다. 네 번째 무기가 이 분리를 가능하게 한다.

문제 4 — 부탁은 어겨진다. "절대 .env 파일은 건드리지 마"라고 말해 두어도, AI가 작업에 몰두하다 보면 어길 수 있다. 사람도 그렇다. 회사가 중요한 규칙을 '당부'가 아니라 '시스템'으로 막는 이유다(권한 없는 서버엔 아예 접속이 안 되는 것처럼). 말로 하는 부탁이 아니라 어길 수 없는 장치가 필요하다.

여기서 한 가지 오해를 미리 풀자. "AI가 규칙을 어긴다"는 말이 "AI가 반항한다"는 뜻은 아니다. AI는 악의로 규칙을 깨지 않는다. 다만 한 번에 여러 목표를 좇다 보면, "이 파일을 고치지 마"라는 예전 당부보다 지금 눈앞의 "이 기능을 완성하라"가 더 크게 보여서, 결과적으로 당부를 지나칠 수 있다. 사람이 마감에 쫓기면 안전 수칙을 건너뛰는 것과 같다. 그래서 정말 중요한 규칙은 '지켜 주기를 바라는 당부'가 아니라 '지킬 수밖에 없는 구조'로 만들어야 한다. 공사장에서 "위험하니 들어가지 마세요" 팻말과, 아예 잠겨 있어 열 수 없는 문은 다르다. 다섯 번째 무기가 이 잠긴 문이다.

Claude Code의 여섯 기능은 정확히 이 문제들에 대한 답이다.

이제 하나씩 자세히 본다. 각 기능마다 (1) 무엇인지 (2) 어디에 저장하는지(파일 위치) (3) 온티켓에서 어떻게 쓸지를 확인한다. 파일 위치를 굳이 배우는 이유가 있다 — 전부 프로젝트 폴더 안의 평범한 텍스트 파일이라는 사실이 중요하기 때문이다. 팀 설정이 파일이면 Git으로 관리되고, 동료에게 복사해 줄 수 있고, AI에게 만들게 할 수도 있다.

이 마지막 문장은 이 장 전체를 관통하는 핵심이라 한 번 더 풀어 둘 값어치가 있다. 다른 많은 AI 도구는 설정을 그 회사의 서버나 웹 화면 안에 숨겨 둔다. 그러면 그 설정은 나만의 것이고, 남에게 넘기려면 스크린샷을 찍어 설명하는 수밖에 없다. Claude Code는 정반대다. 기억도, 절차도, 전문가 정의도, 강제 규칙도 전부 프로젝트 폴더 안의 텍스트 파일이다. 텍스트 파일이라는 것은 곧 — 눈으로 읽어 검토할 수 있고, Git으로 버전을 관리하며 "누가 언제 왜 이 규칙을 바꿨는지" 이력이 남고, 동료에게 폴더째 복사해 주면 그 사람의 Claude Code도 똑같이 행동하고, 무엇보다 그 파일을 만드는 일조차 Claude Code에게 시킬 수 있다는 뜻이다. 설정이 코드처럼 관리된다는 이 성질을, 뒤에서 각 기능마다 반복해서 확인하게 된다.

[짚고 가기] 이 절에서 중요한 것은 기능 이름 암기가 아니라 "네 문제 → 여섯 기능"의 대응이다. 위 문제 표를 놓고, "AI가 어제 정한 규칙을 오늘 잊었다. 어느 무기?"처럼 스스로 문제를 던져 기능을 맞혀 보면 개념이 붙는다. 반대로 기능을 하나 골라 "이건 어떤 문제를 해결하나?"를 되물어도 좋다. 개발 경험이 없을수록 회사 비유(매일 기억 잃는 신입, 업무 매뉴얼, 감사팀, 잠긴 문)가 훨씬 잘 와닿는다. 6개를 한 번에 다 외우려 하지 말고, "문제가 생겨야 도구가 필요하다"는 순서로 따라가는 것이 이 장을 읽는 요령이다.

2.2 여섯 가지 무기

1. CLAUDE.md — 프로젝트의 기억

무엇인가. 프로젝트 폴더에 두는 특별한 파일이다. Claude Code는 세션을 시작할 때 이 파일을 자동으로 읽는다. 여기 적힌 내용은 매번 다시 말하지 않아도 AI가 알고 시작한다.

'자동으로 읽는다'가 이 기능의 전부이자 핵심이다. 앞 절의 비유로 돌아가면, CLAUDE.md는 매일 기억을 잃는 유능한 신입의 책상에 붙여 둔 상시 메모다. 신입이 출근해 자리에 앉는 순간(세션 시작) 가장 먼저 보는 것이 이 메모다. 그래서 우리가 다시 브리핑하지 않아도, "우리 서비스는 온티켓이고, 프론트는 화면만 담당한다"는 대전제를 이미 알고 일을 시작한다. 파일 이름이 전부 대문자인 CLAUDE.md인 것도 이유가 있다 — README.md처럼, 폴더에서 눈에 잘 띄라고 관례적으로 대문자를 쓴다. Claude Code가 이 이름을 특별히 알아보고 자동으로 집어 든다.

한 가지 흔한 오해. "CLAUDE.md에 적으면 AI가 반드시 그대로 한다"고 믿는 학생이 많은데, 정확히는 항상 읽히지만 반드시 지켜지는 것은 아니다. 이것은 강제가 아니라 지침이다 (강제는 뒤의 Hook이 맡는다). 책상 위 메모를 신입이 매일 보긴 하지만, 급할 때 깜박할 수도 있는 것과 같다. 그래서 CLAUDE.md에는 '지켜 주면 좋은 규칙'을 담고, '어기면 사고 나는 규칙'은 Hook으로 이중으로 막는다. 이 구분을 이 장 마지막 데모에서 직접 확인한다.

어디에 저장하는가.

이 두 위치의 차이가 중요하다. 프로젝트 폴더의 CLAUDE.md는 그 프로젝트에 딸려 다니므로, Git으로 팀 전체가 공유한다 — "우리 온티켓 팀은 이렇게 일한다"는 팀 규약이다. 반면 ~/.claude/CLAUDE.md의 ~는 '내 홈 폴더'를 가리키는 기호로, 여기 둔 메모는 프로젝트를 가리지 않고 내 컴퓨터의 모든 작업에 적용된다 — "나는 항상 이렇게 대답받고 싶다"는 개인 취향이다. 예를 들어 "모든 응답은 한국어로, 결론부터"는 온티켓만의 규칙이 아니라 내 성향이므로 전역에 두는 편이 맞다. 두 파일이 동시에 있으면 둘 다 읽히고, 프로젝트 규칙과 개인 취향이 함께 반영된다.

무엇을 넣는가. 기준은 하나다 — "AI가 모르고, 모르면 실수하는 것".

# 온티켓 (OnTicket)

(주)승승장구의 티켓 예매 서비스. web/(프론트)과 api/(API 서버)로 나뉜다.

## 규칙
- 프론트(web/)는 화면만 담당한다. DB 접근·검증 로직 금지 — 반드시 api/를 거친다
- 모든 금액 계산은 서버(api/)에서 한다
- .env 파일은 절대 커밋하지 않는다

반대로 넣지 말아야 할 것도 있다. 일반적인 코딩 상식("함수는 짧게" 같은)은 AI가 이미 안다. 파일이 길어질수록 정작 중요한 규칙이 묻힌다. 짧고, 이 프로젝트에만 해당하는 사실만 남기는 것이 요령이다.

왜 짧아야 하는지 원리를 알면 규칙을 스스로 지키게 된다. CLAUDE.md는 매 세션 자동으로 읽혀 앞 절에서 말한 '책상 위(컨텍스트)'에 항상 올라간다. 책상 넓이는 한정돼 있으므로, 메모가 두툼할수록 정작 일할 공간이 줄고, 중요한 세 줄이 잡다한 서른 줄 사이에 파묻혀 눈에 안 들어온다. 좋은 CLAUDE.md의 감별법은 간단하다 — "이걸 AI가 몰라서 지난번에 사고가 났다"고 말할 수 있는 항목만 남긴다. 예컨대 "이 프로젝트는 금액을 원 단위 정수로만 다룬다(소수점 금지)"는 몰라서 사고가 나는 것이지만, "변수 이름은 의미 있게 짓는다"는 AI가 이미 아는 상식이라 굳이 적을 필요가 없다.

이럴 때 이렇게 쓴다 — CLAUDE.md 활용 사례. 어떤 프로젝트든 "매번 다시 설명하게 되는 것"이 있다면 그것이 CLAUDE.md감이다.

이 표를 개발 바깥으로 넓혀 보면 CLAUDE.md의 쓸모가 더 분명해진다. 코드 프로젝트가 아니어도 된다. 예를 들어 원고를 쓰는 폴더의 CLAUDE.md에 "이 책은 '독자'가 아니라 '수강생'이라 부른다", "이모지를 쓰지 않는다", "문장은 '~다'로 끝맺는다"라고 적어 두면, 그 폴더에서 글을 고칠 때마다 매번 당부하지 않아도 톤이 유지된다. 회계 자료 폴더라면 "금액은 천 단위 콤마, 통화는 원화 기준"을 적어 둔다. CLAUDE.md는 '코드 규칙'이 아니라 '이 폴더에서 일할 때의 상시 전제'를 담는 그릇이라고 이해하면 응용 범위가 넓어진다.

CLAUDE.md를 만드는 프롬프트도 두 갈래로 익혀 두면 좋다. 하나는 이미 코드가 있는 프로젝트에 초안을 자동으로 뽑는 /init(뒤의 Slash 절에서 다룬다)이고, 다른 하나는 빈 프로젝트에서 내용을 불러 주고 만들게 하는 방식이다.

온티켓에서. 스택과 아키텍처가 정해지는 대로 CLAUDE.md를 만들고, 규칙이 생길 때마다 여기에 쌓는다.

[짚고 가기] 가장 흔히 저지르는 실수는 CLAUDE.md를 '설명서'로 착각해 프로젝트 소개를 장황하게 쓰는 것이다. "AI가 몰라서 사고 나는 것만" 담는다는 기준을 계속 떠올리면 된다. 또 하나 헷갈리기 쉬운 점 — "규칙을 적었는데 AI가 안 지킨다." CLAUDE.md는 지침이지 강제가 아니며, 강제는 뒤에서 배울 Hook이 맡는다. 이 구분은 이 장 마지막 데모(규칙이 실제로 작동하는지 시험하기)에서 직접 눈으로 확인하게 된다.

2. Skills — 재사용하는 절차

무엇인가. 특정 종류의 일을 시킬 때마다 반복하게 되는 지시·체크리스트·절차를 파일로 만들어 둔 것이다. 한 번 만들면 두 가지 방식으로 쓰인다.

• 자동 호출: 관련된 요청이 오면 Claude가 알아서 그 스킬을 참고한다
• 수동 호출: /스킬이름 으로 직접 부른다

CLAUDE.md가 '항상 붙어 있는 메모'라면, 스킬은 '서랍 속 매뉴얼'이다. 필요할 때만 꺼내 펼친다. 앞 절 문제 2 — "PM처럼 요구사항을 분석해서…"라는 긴 지시를 매번 다시 치는 낭비 — 를 없애는 장치다. 그 긴 지시를 파일 하나에 잘 적어 두면, 다음부터는 "PRD 써줘" 한마디, 혹은 /pm 한 번으로 그 매뉴얼 전체가 펼쳐진다.

어디에 저장하는가. 스킬 하나가 폴더 하나다. 폴더 안의 SKILL.md가 본체다.

'스킬 하나 = 폴더 하나'라는 점을 눈여겨보자. CLAUDE.md는 파일 한 장이지만, 스킬은 폴더다. 폴더인 이유는 뒤에서 다시 나오는데 — 매뉴얼 본체(SKILL.md) 말고도 참고 자료 (양식, 용어집, 좋은 예시)를 같은 폴더에 함께 담을 수 있기 때문이다. 즉 스킬은 '지시문 한 장'이 아니라 '그 일에 필요한 자료 묶음 전체'를 담는 그릇이다.

SKILL.md의 맨 위에는 어떤 상황에서 이 스킬을 쓰는지 설명(description)을 적는다. Claude는 이 설명을 보고 자동 호출 여부를 판단한다. 본문에는 절차와 기준을 적는다.

---
description: 요구사항을 PRD로 정리할 때 사용. 회의록·메모에서 요구를 추려
  목표/범위/완료기준을 만든다. 형용사는 측정 가능한 기준으로 바꾼다.
---
너는 (주)승승장구의 PM이다.
1. 입력 문서에서 요구를 전부 나열한다
2. '예쁘게' 같은 형용사는 측정 가능한 완료기준으로 바꾼다
3. 3일 MVP에 넣을 것과 뺄 것을 나눠 제안한다
...

위 코드에서 맨 위 --- 두 줄 사이에 낀 부분을 frontmatter(프론트매터) 라고 부른다. '앞머리에 붙이는 정보'라는 뜻으로, 원래 책 앞쪽의 제목·저자 같은 서지 정보를 가리키던 출판 용어다. 문서 본문 앞에 붙는 '메타 정보'라고 이해하면 된다. 여기서는 이 스킬이 무엇인지, 언제 불려야 하는지를 적는 자리다. Claude는 본문을 매번 다 읽어 보지 않고, 이 짧은 description만 훑어서 "지금 들어온 요청이 이 스킬을 부를 상황인가"를 판단한다. 그래서 description을 어떻게 쓰느냐가 자동 호출의 성패를 가른다. "PRD 만들 때 사용"처럼 막연히 쓰면 잘 안 불리고, "회의록·메모에서 요구를 추려 목표/범위/완료기준을 만들 때"처럼 상황과 입력을 구체적으로 쓰면 정확히 불린다. 사람에게 일을 맡길 때 "기획 좀 해줘"보다 "이 회의록에서 요구사항 뽑아 PRD로 정리해줘"가 명확한 것과 같다.

--- 아래 본문은 그 스킬이 불렸을 때 AI가 따르는 실제 지시서다. 위 예처럼 "너는 승승장구의 PM이다"로 역할을 준 뒤, 번호를 매긴 절차와 기준을 적는다. 여기가 길고 자세할수록 좋다 — 매번 칠 필요가 없으니, 평소라면 귀찮아서 생략했을 세세한 기준까지 넉넉히 적어 둘 수 있다. 이것이 스킬의 진짜 이득이다.

CLAUDE.md와의 차이. CLAUDE.md는 항상 읽힌다(그래서 짧아야 한다). 스킬의 본문은 그 일을 할 때만 읽힌다. 그래서 긴 절차·자세한 기준은 스킬에 담는 것이 맞다. "CLAUDE.md의 어떤 절이 사실이 아니라 절차가 되어 간다면 스킬로 옮겨라"가 공식 문서의 조언이다.

이 차이를 책상 비유로 정리하면 깔끔하다. CLAUDE.md는 책상에 늘 펼쳐 둔 메모라 자리를 늘 차지하니 짧아야 하고, 스킬은 서랍에 넣어 두었다가 그 일을 할 때만 꺼내 펼치는 매뉴얼이라 두꺼워도 된다. 그래서 판단 기준은 이렇게 된다 — 항상 알아야 하는 짧은 '사실'이면 CLAUDE.md, 특정 상황에만 펼치는 긴 '절차'면 스킬. "우리 금액은 서버에서 계산한다"는 사실이니 CLAUDE.md, "PRD를 쓸 때는 이런 여덟 단계를 밟는다"는 절차이니 스킬이다.

이럴 때 이렇게 쓴다 — Skill 활용 사례. 개발만이 아니다. 반복되는 모든 일이 스킬 후보다. 미리 분명히 해 두자 — 아래 표의 스킬들은 어디서 내려받는 것이 아니라 전부 내가 직접 만드는 것이다. .claude/skills/weekly-report/SKILL.md 파일을 만들면 그 순간 /weekly-report 명령이 생긴다. 이름도 내가 짓는다. (만드는 작업 자체도 Claude Code에게 시키면 된다. 참고로 동료나 커뮤니티가 만든 스킬 파일을 복사해 와서 쓰는 것도 가능하다 — 결국 폴더 안의 텍스트 파일이므로.)

이 표에서 눈여겨볼 것은 절반 이상이 '코딩'이 아니라는 점이다. 주간보고, 번역, 견적서, 정산 정리, 블로그 초안 — 전부 사무직이 매주·매달 반복하는 일이다. 스킬은 개발자만의 도구가 아니라 "내가 매번 같은 방식으로 하는 일"이 있는 모든 사람의 도구다. 판별법은 간단하다. 어떤 일을 하고 나서 "아, 이거 다음에 또 이렇게 해야 하는데"라는 생각이 들면, 그 순간이 스킬로 만들 신호다. 특히 절차가 정해져 있고(빈 값 검사 → 중복 제거 → 요약), 매번 같은 양식이 필요하고(견적서·릴리즈 노트), 지켜야 할 규칙이 있는(용어집·말투) 일일수록 스킬의 효과가 크다.

포인트가 하나 있다. 스킬 폴더에는 SKILL.md 말고도 참고 파일(용어집, 양식, 좋은 예시)을 함께 넣을 수 있다. 즉 스킬은 "내 일의 매뉴얼 폴더"를 통째로 담는 그릇이다. 한 번 잘 만들어 두면 회사를 옮겨도, 프로젝트가 바뀌어도 들고 다닐 수 있다(개인 스킬).

이 '참고 파일 동봉'이 스킬을 강력하게 만든다. 예를 들어 /translate 스킬 폴더에 용어집.md를 함께 넣어 두면, 번역할 때마다 "이 회사에서 booking은 '예매', reservation은 '예약'으로 구분해서 옮겨라" 같은 규칙을 매번 설명하지 않아도 스킬이 그 파일을 참고해 일관되게 번역한다. /estimate 스킬 폴더에는 회사 견적서 빈 양식과 좋은 견적서 예시 두어 개를 넣어 둔다. AI는 그 예시를 본보기 삼아 같은 구조로 채운다. 사람 신입에게 "이 매뉴얼과 지난번 잘 된 사례를 보고 이대로 해"라고 자료 묶음을 통째로 건네는 것과 똑같다.

스킬을 만드는 프롬프트도 익혀 두자. 스킬은 손으로 폴더와 파일을 만들 필요 없이, 말로 만들게 하는 것이 정석이다.

온티켓에서. PM, UI 디자이너 같은 '만드는 역할'들을 스킬로 만든다.

여기서 '만드는 역할'이라는 표현을 기억해 두자. 이 장 뒤쪽 '역할에 맞는 기능 선택하기'에서 '보는 역할'과 대비하는 핵심 개념이 된다. PM·디자이너처럼 무언가를 산출하는 역할은 스킬에 담아도 되지만, 리뷰어·QA처럼 검증하는 역할은 스킬이 아니라 다음다음에 나올 Subagent에 담아야 한다. 왜인지는 그 절에서 밝힌다.

[짚고 가기] 스킬과 CLAUDE.md는 헷갈리기 쉽다. "사실이냐 절차냐, 항상 필요하냐 가끔 필요하냐"로 가르는 한 문장을 기억해 두면 된다. 또 하나 — "스킬을 어디서 다운받나" 싶을 수 있는데, 앞의 굵은 문장대로 직접 만드는 것이고, 만드는 것조차 Claude Code에게 시킨다. 실제로 "commit-msg 스킬 만들어줘"라고 한 번 시켜 보면, .claude/skills/ 밑에 폴더와 SKILL.md가 생기는 것을 눈으로 확인할 수 있다 — "설정이 곧 텍스트 파일"이라는 이 장의 주제가 여기서 실감난다.

3. Slash 명령 — /이름 한마디

무엇인가. 슬래시(/)로 시작하는 명령이다. 두 종류가 있다.

• 내장 명령: Claude Code에 처음부터 들어 있다. /help(도움말), /compact(대화 압축), /init(CLAUDE.md 초안 생성) 등
• 스킬 호출: 위에서 만든 스킬을 /스킬이름으로 직접 부르는 것

슬래시 명령을 별개의 일곱 번째 무기가 아니라 앞 스킬의 '손잡이'로 보는 것이 정확하다. 스킬은 두 가지로 불린다고 했다 — 관련 요청이 오면 알아서 불리는 자동 호출, 그리고 내가 직접 부르는 수동 호출. 이 수동 호출의 방아쇠가 바로 슬래시다. 사람에게 비유하면, 스킬은 '그 일을 할 줄 아는 능력'이고 슬래시는 '그 사람을 콕 집어 부르는 호출 벨'이다. 자동 호출에만 맡기면 원할 때 안 불릴 수 있으니, 확실히 지금 이 절차를 쓰고 싶을 때 /이름으로 손수 부른다.

과거에는 '커스텀 슬래시 명령'이라는 별도 기능이 있었지만, 지금은 스킬로 통합되었다. /pm 이라고 치면 pm 스킬이 실행된다 — 즉 슬래시 명령을 따로 만드는 게 아니라, 스킬을 만들면 슬래시 명령이 생기는 것이다. (옛 방식인 .claude/commands/ 폴더의 파일도 여전히 동작한다.)

이 '통합' 이야기 때문에 오래된 자료를 본 학생이 혼란스러워할 수 있어 정리해 둔다. 예전에는 스킬과 슬래시 명령이 별개의 두 기능이어서 각각 따로 만들어야 했다. 지금은 하나로 합쳐져, 스킬을 하나 만들면 같은 이름의 슬래시 명령이 공짜로 딸려 온다. 그러니 "슬래시 명령을 만드는 법"을 따로 배울 필요가 없다 — 스킬을 만들면 끝이다. 인터넷의 옛 글에 나오는 .claude/commands/ 방식도 호환을 위해 여전히 작동하지만, 지금 새로 만들 때는 스킬로 가면 된다.

이럴 때 이렇게 쓴다 — Slash 명령 활용 사례.

• /init — 이미 코드가 있는 프로젝트에 Claude Code를 처음 도입할 때. 코드베이스를 훑어 CLAUDE.md 초안을 자동으로 만들어 준다
• /compact — 긴 대화로 세션이 무거워졌을 때 지금까지의 내용을 요약·압축한다
• /code-review — 내장 스킬. 지금까지의 코드 변경을 리뷰받는다
• /weekly-report 지난주 — 스킬 이름 뒤에 인자를 붙여 입력을 넘길 수 있다

이 네 가지를 조금 더 풀어 두면 실전에서 바로 쓸 수 있다.

• /init은 남이 이미 만들어 둔 프로젝트를 넘겨받았을 때 특히 유용하다. 폴더 구조와 주요 파일을 AI가 스스로 훑어, "이 프로젝트는 이런 스택이고 이런 규칙으로 보인다"는 CLAUDE.md 초안을 만들어 준다. 백지에서 쓰는 것보다 훨씬 낫다 — 초안을 손보기만 하면 된다.
• /compact는 앞 절에서 말한 '책상(컨텍스트)'이 꽉 찰 때 쓴다. 대화가 길어지면 책상에 옛 내용이 잔뜩 쌓여 느려지고 흐려지는데, /compact는 지금까지의 대화를 짧은 요약으로 갈아 끼워 책상을 정리한다. 핵심 결론은 남기고 잡담은 버리는 셈이다. 긴 작업 중간에 한 번씩 눌러 주면 세션이 가벼워진다.
• /code-review는 내가 만들지 않아도 처음부터 들어 있는 내장 스킬이다. 지금까지의 코드 변경을 검토받고 싶을 때 부른다.
• /weekly-report 지난주처럼 이름 뒤에 붙이는 말을 인자(引數, argument) 라고 부른다. 스킬에 넘겨 주는 '입력값'이라는 뜻이다. /pm 킥오프_회의록.md라면 'pm 스킬을 부르되, 이 회의록 파일을 재료로 삼아라'가 된다. 같은 스킬을 매번 다른 재료로 돌릴 수 있게 해 주는 장치다.

온티켓에서. /pm 킥오프_회의록.md 처럼 역할 스킬을 호출하는 데 주로 쓴다.

[짚고 가기] 슬래시 명령은 개념이 얕아 길게 볼 것이 없다. "스킬을 만들면 딸려 오는 손잡이"라는 한 줄이면 충분하다. 다만 /init과 /compact는 실제 실습에서 자주 쓰게 되므로 이름만이라도 익혀 두자. 특히 /compact는 세션이 느려질 때의 처방으로 뒤 장 실습 내내 요긴하다. 터미널에서 슬래시(/)를 쳐 보면 사용 가능한 명령 목록이 뜨니, 직접 눌러 보며 탐색해 보면 좋다.

4. Subagents — 독립된 전문가

무엇인가. 본 대화와 분리된 별도의 AI 작업자다. 두 가지가 핵심이다.

첫째, 독립 컨텍스트. 서브에이전트는 자기만의 대화 공간에서 일한다. 본 대화의 선입견 없이 일하고, 긴 작업 내용으로 본 대화를 어지럽히지도 않는다.

'컨텍스트'는 앞에서 본 그 '책상'이다. 지금까지의 무기들은 전부 하나의 책상(본 대화) 위에서 벌어지는 일이었다. Subagent는 다르다 — 별도의 방에 자기 책상을 따로 차린 또 다른 작업자다. 이 '방을 분리한다'는 것이 두 가지 이득을 낳는다. 하나는 선입견 차단이다. 본 대화에서 방금 코드를 짠 흐름을 모르는 채, 새 사람이 백지 상태로 코드만 보고 검토하니 더 냉정하게 본다. 다른 하나는 책상 정리다. 예컨대 테스트를 돌리면 수백 줄의 로그가 쏟아지는데, 이걸 본 대화 책상에 올리면 정작 중요한 내용이 파묻힌다. Subagent가 자기 방에서 그 수백 줄을 다 보고, 본 대화에는 "12개 통과, 2개 실패, 원인은 이것"이라는 결론만 가져온다. 지저분한 중간 과정을 격리하는 것이다.

둘째 — 이것이 결정적인데 — 도구 권한을 따로 정할 수 있다. 서브에이전트를 정의할 때 "이 에이전트는 파일을 읽을 수만 있고, 고칠 수는 없다"처럼 쓸 수 있는 도구의 목록을 제한할 수 있다.

이 둘째 성질이 Subagent를 다른 다섯 무기와 근본적으로 다르게 만든다. 앞 절의 문제 3 — "만든 사람이 자기 것을 검사하면 형식적인 절차가 된다" — 을 진짜로 푸는 열쇠가 여기 있다. Claude Code에게는 파일을 읽는 도구(Read), 고치는 도구(Edit·Write), 명령을 실행하는 도구(Bash) 등 여러 '도구'가 있다. Subagent를 정의할 때 이 도구 목록에서 편집 도구를 빼 버리면, 그 작업자는 아무리 원해도 파일을 고칠 손이 없다. "고치지 말아 달라"는 부탁이 아니라, 애초에 고칠 수단을 손에서 뺏은 것이다. 이것이 왜 결정적인지는 바로 다음 항목과 이 장 뒤쪽 '역할에 맞는 기능 선택하기'에서 이어진다.

어디에 저장하는가.

파일 맨 위에 이름·설명·허용 도구 목록을 적고, 본문에 그 역할의 지시를 적는다.

---
name: code-reviewer
description: 코드 변경을 검토한다. 커밋 전에 사용.
tools: Read, Grep, Glob        # 읽기·검색만. 편집 도구(Edit, Write)가 없다
---
너는 (주)승승장구의 코드 리뷰어다. 문제를 등급(Blocker/Major/Minor)으로
분류해 보고만 하라. 코드를 직접 고치지 마라 — 애초에 고칠 도구도 없다.
...

이 파일도 스킬처럼 맨 위에 frontmatter(앞의 --- 사이 부분)를 둔다. 다만 항목이 하나 더 있다 — tools다. 여기 적은 도구만 이 에이전트가 쓸 수 있다. 위 예의 tools: Read, Grep, Glob을 뜯어 보면, Read는 파일 읽기, Grep은 파일 안에서 특정 문구 찾기, Glob은 이름 패턴으로 파일 목록 뽑기다 — 셋 다 '보는' 도구뿐이고 '고치는' 도구(Edit·Write)가 목록에 없다. 그래서 이 리뷰어는 코드를 샅샅이 읽고 검색해 문제를 짚을 수는 있어도, 손을 대는 것은 물리적으로 불가능하다. 주석에 적힌 "애초에 고칠 도구도 없다"가 이 뜻이다. 본문에 "고치지 마라"라고 적은 것은 예의상 한 번 더 말한 것일 뿐, 진짜 강제력은 tools 목록에서 나온다.

이럴 때 이렇게 쓴다 — Subagent 활용 사례. 공통점은 "본 대화와 분리해야 이득"이라는 것이다 — 권한을 빼앗기 위해서든, 지저분한 중간 과정을 격리하기 위해서든.

이 표를 관통하는 두 가지 분리 이유를 다시 나눠 보면 이해가 또렷해진다.

• 권한을 빼앗기 위한 분리: 코드리뷰어·보안검토자·문서교정자·계약서검토가 여기 든다. 이들의 생명은 '보되 고치지 않는다'이므로, 편집 도구를 빼는 것 자체가 목적이다. 특히 계약서·회계·원고처럼 원본을 함부로 바꾸면 안 되는 자료를 다룰 때, "고치지 마세요"라는 당부 대신 "고칠 손이 없는 검토자"에게 맡기는 것이 안전의 격을 바꾼다.
• 지저분한 과정을 격리하기 위한 분리: 테스트 러너·리서치 담당이 여기 든다. 이들은 고치고 말고가 아니라, 작업 과정에서 나오는 방대한 중간 산물(테스트 로그 수백 줄, 웹 검색 수십 페이지)을 본 대화 책상에 쏟지 않기 위해 방을 나눈다. 결론만 깔끔하게 받는다.

이 발상은 온티켓 밖에서 특히 빛난다. 예를 들어 논문이나 보고서를 쓰는 사람은 '자료 조사 담당' 서브에이전트에게 웹 검색 권한만 주어 긴 조사를 시키고, 본 대화에는 출처와 요약만 받는다. 법무·계약 실무에서는 '조항 검토' 서브에이전트에게 읽기 권한만 주어 위험 조항을 표시하게 하되, 계약서 원본은 절대 못 고치게 한다. 공통 원리는 하나다 — "이 일은 보기만 해야 한다"거나 "이 과정은 시끄러우니 딴 방에서 하라"면 Subagent로 뺀다.

Subagent를 만드는 프롬프트도 익혀 두자. 핵심은 '허용 도구'를 명시하는 것이다.

온티켓에서. 코드리뷰어·디자인리뷰어·QA·보안검토자 — 즉 '보는 역할' 전부가 서브에이전트가 된다. 이유는 이 장의 끝에서 자세히 다룬다.

[짚고 가기] Subagent는 이 장에서 개념적으로 가장 무거운 무기다. 두 이득(독립 컨텍스트 / 권한 제한) 중 놓치기 쉬운 것은 둘째다. "스킬에게 '고치지 마'라고 적으면 되지 않나?"라는 의문이 들 텐데, 이것이 곧 '역할에 맞는 기능 선택하기'의 핵심 질문으로 이어진다. 여기서는 그 차이가 이 장에서 제일 중요한 원칙이라는 것만 기억하고, 답은 조금 뒤 그 절에서 확인하자. 앞의 코드 예시에서 tools 목록에 Edit·Write가 빠져 있다는 점을 눈여겨보면 이해가 빨라진다.

5. Hooks — 규칙을 코드로 강제한다

무엇인가. Claude Code가 특정 행동을 하려는 순간에 자동으로 실행되는 검사 장치다. 대표적인 것이 PreToolUse 훅 — AI가 도구(파일 수정, 명령 실행 등)를 쓰기 직전에 끼어들어 검사하고, 조건에 걸리면 그 행동 자체를 차단한다.

'훅(hook)'이라는 말은 '갈고리'라는 뜻이다. AI가 어떤 행동을 하려는 흐름의 특정 지점에 갈고리를 걸어 두었다가, 그 지점을 지날 때 낚아채 미리 정해 둔 검사를 실행하는 장치라 그렇게 부른다. 이름에서 오는 이미지 그대로다 — 흐름이 갈고리에 '탁' 걸린다.

PreToolUse라는 이름도 뜯어 보면 뜻이 그대로 드러난다. Pre(이전) + Tool(도구) + Use(사용) — '도구를 쓰기 이전'이다. 앞 절에서 Claude Code에게는 여러 '도구' (파일 편집, 명령 실행 등)가 있다고 했는데, PreToolUse 훅은 AI가 그 도구를 실제로 쓰기 직전 순간에 걸리는 갈고리다. 그래서 나쁜 일이 벌어진 뒤 되돌리는 게 아니라, 벌어지기 전에 막는다. 예컨대 AI가 .env 파일을 고치려고 편집 도구를 막 쓰려는 그 찰나에 훅이 끼어들어, "이 파일은 보호 대상"이라 판단하면 편집 자체를 무산시킨다. AI가 아무리 그 파일을 고치려 해도 손이 닿기 직전에 막히는 것이다. (참고로 Pre가 있으니 반대인 PostToolUse — '도구를 쓴 직후'에 거는 갈고리 — 도 있다. 파일을 고칠 때마다 포맷터를 자동으로 돌리는 것 같은 '뒤처리'에 쓴다.)

부탁과 훅의 차이를 분명히 하자.

이 표가 이 장의 두 번째 핵심 대비다(첫째는 뒤에서 볼 스킬 대 서브에이전트). CLAUDE.md에 "하지 마"라고 적는 것은 AI의 선의에 기대는 것이고, Hook은 선의와 무관하게 물리적으로 막는 것이다. 왜 둘 다 필요한가? 세상 모든 규칙을 Hook으로 만들면 너무 뻣뻣해지기 때문이다. "함수는 짧게" 같은 권고는 어겨도 사고가 안 나니 지침이면 충분하고, ".env를 커밋하면 회사 비밀번호가 통째로 유출된다" 같은 규칙은 한 번이라도 어기면 끝장이니 잠긴 문이어야 한다. 어겼을 때의 피해가 되돌릴 수 없는 규칙만 Hook으로 올린다 — 이 감각을 익히는 것이 이 무기의 핵심이다.

어디에 저장하는가. 설정 파일(.claude/settings.json)에 등록한다. "어떤 도구 사용에 반응할지"와 "그때 실행할 검사"를 적는 방식이다. 직접 작성이 어렵다면 — 걱정할 것 없다. 훅을 만드는 일도 Claude Code에게 시키면 된다.

여기서 settings.json이라는 파일 이름이 처음 나온다. .json은 '설정을 사람도 읽고 프로그램도 읽을 수 있게 적는 표준 형식'이라고만 알아 두면 된다(JavaScript Object Notation의 약자다). 지금 그 문법을 배울 필요는 전혀 없다 — 앞 문장 그대로, 훅 설정을 쓰는 일 자체를 ".env 파일을 고치려 하면 막는 훅을 만들어줘"처럼 말로 시키면 Claude Code가 이 파일에 알아서 적어 준다. 우리가 할 일은 '무엇을 막고 싶은지'를 정하는 사람의 판단이지, JSON 문법이 아니다.

이럴 때 이렇게 쓴다 — Hook 활용 사례. "사람이 실수해도, AI가 깜박해도 막혀야 하는 것"이 전부 훅감이다.

이 표에서 rm -rf와 DROP TABLE이 무엇인지 초심자를 위해 짚어 둔다. rm -rf는 터미널에서 '파일·폴더를 되묻지 않고 통째로 지우는' 명령이고, DROP TABLE은 데이터베이스에서 '표(테이블) 하나를 통째로 없애는' 명령이다. 둘 다 한 번 실행되면 되돌리기가 지극히 어렵다 — 그래서 이런 '되돌릴 수 없는 파괴 명령'이야말로 Hook으로 막는 대표 사례다. AI가 실수로든, 사용자가 무심코든 이런 명령에 손을 대려는 순간 갈고리에 걸려 무산된다.

주목할 것은 표의 아래쪽 절반(스타일 자동화, 보호 구역, 완료 알림)이 '차단'만이 아니라는 점이다. Hook은 '나쁜 일을 막는' 데만 쓰이는 게 아니라 '좋은 일을 자동으로 시키는' 데도 쓰인다. 파일을 고칠 때마다 포맷터를 돌려 코드 모양을 자동으로 다듬거나, 긴 작업이 끝나면 소리로 알려 주는 것처럼. 온티켓 밖으로 넓히면, '회계 데이터 폴더는 어떤 수정도 차단', '계약서 원본 폴더 보호'처럼 개발과 무관한 자료 보호에도 그대로 쓸 수 있다. 어떤 일이 벌어지는 순간을 낚아채 자동으로 무언가를 한다 — 이것이 Hook의 본질이고, 막느냐 시키느냐는 그 응용일 뿐이다.

온티켓에서. .env 수정·커밋 차단(보안), DB 파괴 명령(DROP) 차단(DBA), 테스트 실패 상태의 커밋 차단(QA) — '어기면 사고가 나는 규칙'들을 훅으로 세운다.

[짚고 가기] Hook에서 가장 헷갈리는 것은 CLAUDE.md와의 경계다. "둘 다 규칙 아닌가" 싶을 때는 위 '안내문 대 잠긴 문' 비유로 되돌아가면 된다. 결정적 질문 하나 — "어기면 되돌릴 수 있는 일인가?"를 던져 보면 지침/강제가 스스로 갈린다. 되돌릴 수 있으면 CLAUDE.md(지침), 되돌릴 수 없으면 Hook(강제)이다. 훅 설정 파일을 손으로 직접 쓸 필요는 없다 — "말로 시키면 만들어 준다"는 것만 기억하면 되고, JSON 문법까지 파고들 필요는 없다.

6. MCP — 외부 세계와의 연결

무엇인가. MCP(Model Context Protocol)는 Claude Code를 프로젝트 폴더 밖의 시스템과 연결하는 표준 규격이다. 기본 상태의 Claude Code는 내 폴더의 파일과 터미널 명령만 다룰 수 있다. MCP 서버를 연결하면 GitHub 이슈, 데이터베이스, 브라우저, 사내 API 같은 외부 시스템을 AI가 직접 읽고(권한을 주면 조작도) 할 수 있다.

이름을 풀어 보면 정체가 드러난다. Model(AI 모델) + Context(맥락·정보) + Protocol(규약) — 'AI 모델에게 바깥 정보를 물어다 주는 표준 약속'이다. 여기서 '프로토콜(규약)'이 핵심어다. 프로토콜이란 서로 다른 것들이 대화하기로 미리 정한 공통 언어를 말한다. 나라마다 콘센트 모양이 다르면 여행이 번거롭지만, 규격이 통일되면 어느 나라 기기든 꽂힌다. MCP가 바로 그 통일된 규격이다. 이 약속을 따르면, GitHub든 데이터베이스든 노션이든 같은 방식으로 Claude Code에 연결된다. 그래서 새로운 시스템을 붙일 때마다 방식을 새로 배울 필요가 없다.

'MCP 서버'라는 말도 짚어 두자. 여기서 서버는 거창한 컴퓨터가 아니라, 특정 외부 시스템과 Claude Code 사이에서 통역을 맡는 작은 연결 프로그램을 가리킨다. 'GitHub용 MCP 서버', '데이터베이스용 MCP 서버'처럼 붙이려는 대상마다 짝이 되는 서버가 있고, 그것을 하나 연결하면 그 대상과 이야기할 통로가 열린다. 콘센트 비유를 이으면, MCP 서버는 'GitHub 전용 어댑터', 'DB 전용 어댑터'인 셈이다. 어댑터를 꽂으면 그 기기와 통한다.

왜 이것이 필요한가? 앞 장에서 우리가 겪었던 '복사-붙여넣기 택배 기사' 문제를 떠올리면 된다. GitHub 이슈 내용을 AI에게 주려면, 지금까지는 사람이 브라우저에서 긁어다 붙여넣어야 했다. DB의 지난주 매출을 물으려면 사람이 직접 조회해 표를 복사해 와야 했다. MCP는 이 '사람이 실어 나르는' 단계를 없앤다 — AI가 직접 그 시스템에 가서 본다. 폴더 안에 갇혀 있던 AI에게 바깥으로 난 문을 열어 주는 것이다.

연결 방법. 터미널에서 claude mcp add ... 명령으로 추가하거나, 프로젝트의 .mcp.json 파일에 적어 팀과 공유한다. 이것 역시 Claude Code에게 시켜도 된다.

두 방법의 차이는 앞의 CLAUDE.md와 같은 결이다. claude mcp add로 붙이면 내 컴퓨터에서만 연결되고, .mcp.json 파일에 적어 Git으로 공유하면 팀원 모두가 같은 외부 연결을 쓴다. "우리 온티켓 팀은 모두 이 GitHub 저장소와 이 모니터링 시스템에 연결한다"를 파일 하나로 공유하는 것이다. 여기서도 이 장의 주제가 반복된다 — 외부 연결 설정조차 결국 폴더 안의 텍스트 파일이라, 검토하고 공유하고 AI에게 만들게 할 수 있다.

중요한 원칙 — 읽기 전용부터. 외부 시스템 연결은 강력한 만큼 위험하다. 처음엔 조회 권한만 주고, 조작 권한은 필요가 증명된 뒤에 늘린다.

이 원칙은 아무리 강조해도 지나치지 않다. MCP로 DB를 연결한다는 것은, AI에게 실제 운영 중인 데이터에 손을 뻗을 통로를 준다는 뜻이다. 여기에 처음부터 '쓰기·삭제' 권한까지 주면, AI가 조회 질의를 짜려다 실수로 데이터를 바꾸거나 지우는 사고가 이론상 가능해진다. 그래서 순서를 지킨다 — 먼저 읽기 전용으로 연결해 "조회는 정확히 되는가"를 충분히 확인한 뒤에, 정말 필요하다고 판단될 때만 조작 권한을 조금씩 연다. 앞 장에서 배운 '퍼미션'의 정신 — 되돌리기 어려운 일일수록 신중히 — 이 MCP에서 시스템 설계 차원으로 확장된 것이다. 이 '읽기 전용부터'는 위험을 막을 뿐 아니라, 조회만으로도 이미 대부분의 쓸모(현황 파악, 분석, 원인 추적)를 얻을 수 있기 때문에 실용적으로도 옳다.

이럴 때 이렇게 쓴다 — MCP 활용 사례. 복사-붙여넣기로 나르던 외부 정보를 AI가 직접 가서 보게 만드는 것이 핵심이다.

이 표의 각 줄이 없앴을 '사람의 실어 나르기'를 상상하면 MCP의 가치가 체감된다. 브라우저 연결이 특히 인상적이다 — 지금까지 AI는 자기가 만든 화면을 스스로 볼 수 없어서, 사람이 브라우저를 열어 "이렇게 나왔어"라고 스크린샷을 찍어 줘야 했다. 브라우저 MCP를 붙이면 AI가 스스로 페이지를 열어 확인하고 잘못된 곳을 찾는다. "되는지 눈으로 봐"라는 지시가 비로소 문자 그대로 가능해진다. 노션·슬랙 연결은 개발 밖에서도 쓸모가 크다 — 회의록과 대화를 AI가 직접 가져와 요구사항 문서로 정리하니, 회의 내용을 복사해 붙이는 수고가 사라진다.

온티켓에서. 배포된 서비스의 DB를 MCP로 읽기 전용 연결해 두면, 장애 분석 때 AI가 직접 주문 상태를 조회할 수 있다.

이 온티켓 사례가 '읽기 전용부터' 원칙과 정확히 맞물린다는 점을 눈여겨보자. 실제 운영 DB에는 고객들의 진짜 주문이 들어 있으니, 여기에 쓰기 권한을 주는 것은 위험하다. 하지만 읽기 전용이라면 아무것도 망가뜨리지 않으면서 "지금 결제 실패한 주문이 몇 건인지, 언제부터 늘었는지"를 AI가 직접 조회해 장애 원인을 좁힐 수 있다. 위험은 0에 가깝고 쓸모는 크다 — 읽기 전용부터 시작하라는 원칙의 교과서적 예다.

[짚고 가기] MCP는 6개 무기 중 가장 '바깥세상'과 닿아 있어 흥미롭지만, 지금 당장 실제 연결까지 해 볼 필요는 없다. 개념(폴더 밖으로 난 문)과 원칙(읽기 전용부터)만 확실히 잡아 두고, 연결 실습은 뒤 장에서 다룬다. "MCP 서버가 무엇이냐"가 아리송하다면, 붙이려는 시스템마다 있는 전용 어댑터 프로그램이라는 콘센트 비유가 가장 이해하기 쉽다. 앞 장의 '복사-붙여넣기 택배 기사'를 떠올려 "그 택배를 없애는 것이 MCP"라고 연결하면, 앞 장과 이 장이 하나의 이야기로 꿰인다.

2.3 역할에 맞는 기능 선택하기

AI 개발팀에 새로운 역할을 추가할 때는 "이 역할에는 어떤 기능이 적합할까?"를 먼저 생각해야 한다. 선택 기준은 다음과 같다.

위 표는 이 장에서 배운 기능의 용도와 선택 기준을 정리한 것이다. 여섯 기능을 하나씩 배울 때는 서로 별개처럼 느껴질 수 있지만, 실제로 AI 개발팀을 구성하려면 각 역할에 어떤 기능을 사용할지 정해야 한다. 위 표가 그 선택의 기준이 된다. 앞으로 온티켓에 PM, 디자이너, 리뷰어, QA, 보안검토자, DBA 등의 역할을 추가할 때마다 이 표를 참고해 "이 역할에는 어떤 기능이 적합할까?"를 먼저 생각해 보자.

검증 역할은 왜 반드시 Subagent로 만드는가

여기서 이 과정의 중요한 원칙을 분명히 해 두자.

결과물을 만드는 역할은 Skill로 정의해도 되지만, 검증하는 역할은 반드시 Subagent로 정의한다.

이유는 수정 권한을 분리해야 하기 때문이다. 검토자는 코드를 직접 고치지 않고 문제를 지적하는 역할이다. 만든 사람이 직접 고치면서 검토까지 하면 검토가 형식적인 절차에 그치기 쉽다. 그런데 스킬은 현재 대화에서 실행되므로 그 대화에서 사용할 수 있는 도구를 그대로 사용한다. 파일 편집 도구도 마찬가지다. 스킬에 "고치지 마"라고 적어도 수정 권한이 없어지는 것은 아니다. 그저 지시를 내려 둔 상태다.

앞에서 배운 스킬의 실행 방식을 떠올려 보자. 스킬에 적은 '고치지 마'가 지시에 그치는 이유는 스킬이 현재 대화의 실행 환경과 도구를 그대로 사용하기 때문이다. 현재 대화에서 파일 편집 도구를 사용할 수 있다면, 스킬을 실행할 때도 그 도구를 사용할 수 있다. 따라서 스킬 본문에 "고치지 마"라고 적는 것만으로는 편집 도구 사용을 차단할 수 없다. 수정할 수 있는 상태에서 수정하지 말라고 지시하는 것과, 수정 권한 자체를 제한하는 것은 다르다.

서브에이전트는 다르다. 정의할 때 사용할 수 있는 도구 목록에서 편집 도구를 제외하면, 그 에이전트는 파일을 직접 수정할 수 없다. 지시로 금지하는 대신 권한으로 제한하는 것이다.

앞에서 설명했듯이 서브에이전트는 현재 대화와 분리된 환경에서 실행된다. 사용할 수 있는 도구도 별도로 지정한다. 이 목록에서 편집 도구를 제외하면, 검토자가 코드를 수정하려 해도 사용할 도구가 없다. "수정하지 마세요"라는 지시를 잘 따르기를 기대하는 대신, 처음부터 수정할 수 없도록 설정하는 것이다. '수정 권한은 주되 사용하지 말라고 지시하는 것'과 '수정 권한을 주지 않는 것'의 차이다. 지시와 권한 제한을 구분하는 것이 이 장의 핵심이다.

이렇게 권한을 분리하면 검토의 독립성을 지킬 수 있다. 회사에서 감사팀에게 장부 수정 권한을 주지 않는 것과 같은 이유다. 검토와 수정을 서로 다른 담당자가 맡는 것이다.

따라서 역할에 따라 도구 권한을 다르게 설정한다. 결과물을 만드는 역할(PM·디자이너·개발자)은 파일을 수정할 수 있어야 하므로 Skill로 충분하다. 반면 검증하는 역할(리뷰어·QA·보안·감리)은 독립적으로 판단할 수 있도록 수정 권한을 제한해야 하므로 반드시 Subagent로 만든다. 만드는 역할과 검토하는 역할의 실행 환경과 권한을 분리하는 것이 AI 개발팀의 품질을 유지하는 기반이 된다.

[짚고 가기] 이 절은 이 장의 핵심이다. 앞에서 미뤄 둔 "스킬에 '고치지 마'라고 적으면 되지 않나?"라는 질문에 답할 수 있어야 한다. '스킬은 현재 대화의 도구를 그대로 사용하므로 수정하지 말라는 지시만 할 수 있고, 서브에이전트는 도구 목록을 따로 지정하므로 수정 권한을 제한할 수 있다'고 구분하면 된다. 감사팀 비유를 함께 떠올려도 좋다. 완료 기준 체크리스트의 세 번째 항목 ("권한이라는 단어로 설명")도 이 차이를 이해했는지 확인하는 질문이다. 다음 절로 넘어가기 전에 "검증 역할은 왜 Subagent로 만들어야 하는가"를 자기 말로 설명해 보자.

2.4 데모 따라하기 — 첫 번째 기억 심기

1시간 수업이므로 실습은 가볍게 하나만 한다. 온티켓 프로젝트에 첫 기억(CLAUDE.md)을 심고, 정말 기억하는지 확인한다.

실습이 하나뿐인 데는 이유가 있다. 여섯 무기 중 CLAUDE.md 하나만 손으로 만들어 봐도, "설정이 곧 폴더 안 텍스트 파일"이라는 이 장의 핵심이 몸에 새겨진다. 나머지 다섯 무기도 전부 같은 원리 — 파일을 만들면 기능이 생긴다 — 이므로, 하나를 제대로 체험하면 나머지는 연역된다. 그리고 이 데모는 단순히 파일을 만드는 데서 끝나지 않고, CLAUDE.md가 (1) 자동으로 읽히는지 (2) 행동에 영향을 주는지 (3) 그럼에도 강제가 아니라 지침인지까지 세 단계로 확인한다. 이 세 확인이 앞의 '여섯 가지 무기'에서 배운 CLAUDE.md의 성질을 그대로 눈앞에서 재현한다.

따라하기 1 — CLAUDE.md 만들기

온티켓 프로젝트 폴더(onticket)에서 Claude Code를 열고 지시한다.

이 프로젝트의 CLAUDE.md를 만들어줘. 내용은 이렇게:
- (주)승승장구의 티켓 예매 서비스 '온티켓' 프로젝트다
- 모든 문서와 주석은 한국어로 쓴다
- 아직 기획 단계이므로, 내가 명시적으로 시키기 전에는 코드 파일을 만들지 않는다

위 프롬프트를 그대로 복사해 입력하면 된다. 다른 내용으로 바꿔서 해 보고 싶다면 자유롭게 바꿔도 좋다.

퍼미션 요청을 읽고 승인한다. 왼쪽 탐색기에 CLAUDE.md가 생긴다. 열어서 읽어 보자 — 평범한 텍스트 파일이다.

이 지시가 앞 장에서 배운 좋은 지시의 기본형을 그대로 따르고 있음을 짚어 두면 좋다. '무엇을'(CLAUDE.md를 만들어라)만 말하고 '어떻게'(파일 형식·마크다운 문법)는 AI에게 맡겼으며, 담을 내용 세 줄을 구체적으로 불러 주어 결과가 흔들리지 않게 했다. 그리고 "열어서 읽어 보자 — 평범한 텍스트 파일이다"라는 마지막 문장이 이 장 전체의 주제를 학생의 눈으로 확인시키는 대목이다. 특별한 데이터베이스도, 숨은 설정 화면도 아니라, 내가 열어 읽고 고칠 수 있는 텍스트 한 장이 곧 'AI의 기억'이라는 사실을 여기서 실감한다.

따라하기 2 — 기억하는지 시험하기

새 세션에서 확인해야 진짜다.

[잠깐] 먼저 Claude Code를 재시작한다. 입력창에 /exit 를 쳐서 종료하고, 터미널에 다시 claude 를 입력해 새로 시작한다. 이 단계를 건너뛰면 이 실습은 아무것도 증명하지 못한다 — 같은 세션에서는 방금 나눈 대화 때문에 AI가 기억하는 것처럼 보일 뿐이다.

새로 시작한 세션에서 묻는다.

이 프로젝트가 뭐 하는 프로젝트인지, 지금 지켜야 할 규칙이 뭔지 말해봐.

위 프롬프트를 그대로 복사해 입력하면 된다. 다른 내용으로 바꿔서 해 보고 싶다면 자유롭게 바꿔도 좋다.

방금 시작한 세션인데도 승승장구·온티켓·"코드 파일을 만들지 않는다"는 규칙을 알고 있을 것이다. 우리가 다시 말해 준 적이 없는데도 — CLAUDE.md가 자동으로 읽혔기 때문이다.

'새 세션에서 확인해야 진짜'인 이유를 이 장 첫머리의 세션 개념과 연결하면 이 실습의 의미가 살아난다. 만약 /exit 없이 같은 세션에서 물었다면, AI가 방금 우리가 부른 내용을 '책상 위'에 아직 두고 있어서 기억하는 게 당연하다 — 그건 CLAUDE.md 덕분인지 알 수 없다. 그래서 일부러 세션을 끊어 책상을 통째로 비운 뒤, 완전히 새 판에서 묻는다. 그런데도 안다면, 그 앎의 출처는 하나뿐 — 새 세션이 시작하며 CLAUDE.md를 자동으로 읽었다는 것이다. 이 '한 번 껐다 켜서 확인'이 자동 로딩을 증명하는 결정적 절차다.

따라하기 3 — 규칙이 실제로 작동하는지 시험하기

내친김에 규칙을 시험해 보자.

메인 페이지 코드를 좀 더 화려하게 고쳐줘.

위 프롬프트를 그대로 복사해 입력하면 된다. 다른 내용으로 바꿔서 해 보고 싶다면 자유롭게 바꿔도 좋다.

제대로 동작한다면, Claude는 곧바로 고치는 대신 "CLAUDE.md에 '명시적으로 시키기 전에는 코드 파일을 만들지 않는다'는 규칙이 있는데, 진행할까요?"와 비슷하게 확인을 구할 것이다. 규칙이 기억을 넘어 행동에 영향을 주는 것까지 확인했다.

(다만 기억하자 — CLAUDE.md는 어디까지나 지침이다. 어기면 절대 안 되는 규칙은 나중에 Hook으로 강제한다 — 데이터베이스를 세울 때 첫 Hook을 건다. 지침과 강제의 구분, 그것이 오늘 배운 핵심이다.)

이 마지막 시험이 앞의 두 단계보다 한 걸음 더 나아간 지점이다. 바로 앞의 '기억하는지 시험하기'는 CLAUDE.md가 '읽힌다'(기억)를 확인했다면, 여기서는 그 기억이 '행동을 바꾼다'(제어)를 확인한다. 단순히 프로젝트 설명을 앵무새처럼 되뇌는 게 아니라, 우리가 심어 둔 규칙이 실제로 AI의 다음 행동을 멈춰 세우는 것을 눈으로 본다. 그리고 괄호 안 문장이 이 장을 마무리 짓는다 — 방금 AI가 규칙을 '지켜 줬지만', 이것은 어디까지나 지침이라 어길 수도 있었다는 점. 정말 어기면 안 되는 것(예: .env 커밋)은 부탁이 아니라 Hook이라는 잠긴 문으로 막는다. 지침(CLAUDE.md)과 강제(Hook)의 이 구분이, 여섯 무기를 관통하는 오늘의 결론이다.

[짚고 가기] '기억하는지 시험하기'에서 /exit 없이 그냥 이어서 물어보기 쉬운데, 그러면 "같은 세션이라 당연히 기억하는 것"이라 증명이 되지 않는다 — 반드시 껐다 켜야 자동 로딩이 증명된다. 마지막 '규칙 시험'의 결과는 매번 똑같지 않을 수 있다(규칙을 무시하고 그대로 고쳐 버리는 경우도 드물게 있다). 그런 결과가 나와도 당황할 것 없다 — CLAUDE.md는 지침이라 이렇게 새어 나갈 수 있고, 그래서 진짜 중요한 규칙은 Hook으로 막는다는 것을 오히려 눈으로 확인하는 셈이다. 실패조차 이 책의 결론을 증명하는 재료가 된다.

완료 기준 체크리스트

• 여섯 기능의 이름과 각각이 푸는 문제를 짝지어 말할 수 있다
• CLAUDE.md가 프로젝트에 존재하고, 새 세션이 그 내용을 기억한다
• "검증 역할은 왜 Subagent여야 하는가"를 권한이라는 단어로 설명할 수 있다

2.5 정리

• 프로젝트가 커지면 네 가지 문제 — 잊는다, 반복한다, 혼자 다 한다, 부탁은 어겨진다 — 가 나타난다. 여섯 기능이 그 답이다.
• CLAUDE.md는 항상 읽히는 짧은 기억, Skill은 필요할 때 읽히는 절차, Slash 명령은 스킬을 부르는 손잡이다(커스텀 명령은 스킬로 통합되었다).
• Subagent는 독립 컨텍스트에 도구 권한까지 제한할 수 있는 유일한 그릇이다. 그래서 검증 직군은 예외 없이 Subagent에 담는다.
• Hook은 부탁이 아니라 강제다. 어기면 사고 나는 규칙은 Hook으로 세운다.
• MCP는 폴더 밖 세계와의 연결이며, 읽기 전용부터 시작한다.
• 이 여섯 개는 전부 프로젝트 안의 텍스트 파일·설정이다. Git으로 관리되고, 복사해서 공유할 수 있고, 만드는 일 자체를 AI에게 시킬 수 있다.

정리를 한 문장으로 압축하면 이렇다 — 여섯 무기는 각기 다른 문제를 해결하기 위해 만들어졌지만, 전부 '폴더 안의 텍스트 파일'이라는 한 몸이다. 그래서 이것들은 회사의 조직도처럼 서로 맞물린다. CLAUDE.md가 팀의 상시 규약이라면, Skill은 각 직무의 업무 매뉴얼, Subagent는 권한이 분리된 독립 부서, Hook은 어길 수 없는 사내 통제, MCP는 바깥 세계와의 연결 창구다. 앞으로 온티켓의 AI 개발팀을 한 자리씩 세울 때마다, 우리는 "이 역할은 어느 그릇에 담는가"라는 이 장의 질문으로 돌아온다. 무기의 이름은 잊어도 좋다 — 네 가지 문제와, '만드는 사람과 검토하는 사람을 그릇으로 가른다'는 원칙만 손에 쥐고 있으면, 나머지는 필요할 때 다시 펼쳐 보면 된다.