29단계훅·서브에이전트·MCP로 넓히기

걸리는 시간 · 읽기 약 10분 · 따라 하기 약 60분 · 난이도 ★★★ 심화 · 화면 확인 2026.09.27

이 단계를 마치면

• 훅, 서브에이전트, MCP, 슬래시 명령, 스킬이 각각 무엇을 하는지 비개발자의 말로 설명할 수 있습니다.
• 내 도구의 규칙 가운데 "부탁으로 충분한 것"과 "장치로 옮길 것"을 나눌 수 있습니다.
• 새 기능을 붙이기 전에 무엇을 공식 문서에서 확인하고 누구에게 물어야 하는지 압니다.

CLAUDE.md에 분명히 적어 두었습니다. "인증키는 코드에 적지 않는다." 그런데 어느 날 커밋 목록을 훑어보다가, 새로 붙인 기능 파일 한가운데 키 값이 버젓이 적혀 있는 것을 발견합니다. 규칙을 적었는데 왜 지켜지지 않았을까요? 그리고 다음에는 어떻게 막을까요?

23단계에서 CLAUDE.md를 소개할 때 규칙은 "확인할 수 있는 문장"으로 쓰라고 했습니다. 그렇게 쓰면 대부분 지켜집니다. 하지만 대부분일 뿐입니다. CLAUDE.md는 Claude가 읽고 따르려고 애쓰는 부탁입니다. 대화가 길어지거나 일이 복잡해지면 부탁 하나쯤은 놓칠 수 있습니다. 사람도 마찬가지입니다. 인수인계서에 적혀 있다고 신입이 모든 줄을 지키지는 않습니다. 그래서 회사는 중요한 것일수록 사람의 기억에 맡기지 않고 결재 시스템이나 출입 통제 같은 장치로 만듭니다.

Claude Code에도 그런 장치들이 있습니다. 이 단계에서는 다섯 가지를 비개발자의 눈으로 살펴봅니다. 지금 모두 쓸 필요는 없습니다. 무엇이 있는지 알아 두면, 막혔을 때 "이건 훅으로 풀 문제구나" 하고 이름을 떠올릴 수 있습니다. 그 이름만 알면 공식 문서에서 찾아 읽거나 Claude에게 계획을 물을 수 있습니다.

훅: 부탁을 장치로. 훅(hook)은 "파일을 고친 직후", "명령을 실행하기 직전", "작업을 마쳤을 때"처럼 정해진 순간에 미리 적어 둔 명령이 반드시 실행되게 하는 기능입니다. Claude가 기억하든 말든 상관없이 돈다는 점이 CLAUDE.md와 다릅니다. 예를 들어 "파일을 저장할 때마다 인증키처럼 보이는 문자열이 있는지 검사하고, 있으면 멈춘다"는 훅을 두면, 앞의 장면 같은 일은 커밋 전에 걸립니다. "파일을 고친 뒤에는 늘 검사 명령을 돌린다", "특정 폴더의 파일은 고치지 못하게 막는다" 같은 쓰임도 흔합니다.

어떤 규칙을 훅으로 옮길지는 28단계의 질문 하나로 정합니다. 어겼을 때 되돌릴 수 있습니까? 색이 조금 다른 것은 되돌리면 그만이니 CLAUDE.md로 충분합니다. 인증키가 공개되거나 개인정보가 내려받는 파일에 섞이는 일은 되돌릴 수 없습니다. 그런 규칙이 훅의 후보입니다. 다만 훅은 컴퓨터에서 실제로 실행되는 명령입니다. 잘못 만들면 작업이 계속 멈추거나, 원하지 않는 명령이 매번 돌 수도 있습니다. 훅을 어디에 어떤 형식으로 적는지는 버전에 따라 바뀔 수 있으니 공식 문서에서 확인하고, 처음에는 Claude에게 "이 규칙을 훅으로 만드는 계획만 보여 줘"라고 요청해 읽은 뒤 진행합시다. 회사 PC라면 IT 담당자에게 한 번 보여 주는 것도 좋습니다.

서브에이전트: 일을 나눠 맡기기. 서브에이전트는 주된 Claude가 일부 일을 떼어 맡기는 보조 에이전트입니다. 보조는 자기 몫의 일만 보고 결과를 돌려줍니다. 이것이 쓸모 있는 이유는 두 가지입니다. 첫째, 검토를 따로 맡길 수 있습니다. 만든 쪽이 검토까지 하면 자기가 세운 가정 안에서만 보게 됩니다. 검토만 맡은 보조에게 "휴대폰 화면에서 가려지는 버튼이 없는지", "개인정보가 보이는 곳이 없는지"만 보게 하면 만든 쪽이 놓친 것이 보입니다. 둘째, 큰일을 쪼갤 수 있습니다. 여러 파일을 한꺼번에 조사해야 할 때 보조 여럿이 나눠 읽고 요약만 가져오면, 주된 대화는 깔끔하게 유지됩니다.

비개발자에게 중요한 것은 역할을 좁게 주는 일입니다. "검토해 줘"보다 "이 세 가지만 확인해서 예·아니오와 근거로 알려 줘"가 낫습니다. 제1부에서 질문을 구체적으로 다듬던 원리가 그대로 통합니다. 서브에이전트를 따로 정의해 두고 되풀이해 쓰는 방법도 있는데, 그 형식은 공식 문서를 봅시다.

MCP: 바깥 도구를 잇는 표준. MCP(Model Context Protocol)는 Claude 같은 AI가 외부 도구와 자료에 접속하는 방식을 하나로 맞춘 공개 표준입니다. Claude Code에 MCP 서버를 등록하면 사내 문서 창고, 이슈 관리 도구, 데이터베이스, 내 컴퓨터의 다른 프로그램 같은 것을 대화 안에서 불러 쓸 수 있습니다. 콘센트 모양이 같으면 어느 회사 기기든 꽂을 수 있듯, MCP를 지원하는 도구라면 같은 방식으로 붙습니다. 예를 들어 AI 모델과 데이터셋이 모인 Hugging Face도 MCP 서버를 공개하고 있어서, Claude Code에 붙이면 작업 도중에 쓸 만한 모델이나 공개 데이터셋, 관련 논문을 찾아볼 수 있습니다. 연결하는 순서와 주의할 점은 제8부 64단계에서 다룹니다.

연결은 편리한 만큼 문도 넓힙니다. 한번 연결하면 Claude가 그 도구의 자료를 읽고, 도구에 따라서는 쓰거나 보낼 수도 있습니다. 그러니 28단계의 표를 여기에도 그대로 적용합니다. 읽기만 하는 연결부터 시작하고, 쓰기나 보내기가 되는 연결은 사람이 확인하는 단계를 둡니다. 누가 만든 MCP 서버인지, 회사가 허락한 것인지도 먼저 확인합니다. 회사 도구와 연결하는 일은 제8부에서 본격적으로 다루니, 여기서는 Claude Code에도 같은 길이 열려 있다는 것만 알아 둡시다.

슬래시 명령과 스킬: 반복을 줄이는 법. 23단계에서 /init을 써 봤습니다. 이렇게 /로 시작하는 명령이 슬래시 명령입니다. 기본으로 들어 있는 명령 말고도, 자주 하는 요청을 명령으로 만들어 두고 짧게 불러 쓸 수 있습니다. 예컨대 "커밋 전에 휴대폰 화면 확인, 인증키 검사, 바뀐 파일 목록 보고"를 늘 같은 순서로 시킨다면, 그 요청을 명령 하나로 묶어 두면 됩니다. 지금 쓸 수 있는 명령은 Claude Code 안에서 /help로 확인할 수 있고, 기본 명령과 나만의 명령을 만드는 폴더는 23단계의 "자주 쓰는 / 명령어"에 정리해 두었습니다. 이 단계의 장치들도 명령으로 들여다볼 수 있습니다. 훅은 /hooks, 서브에이전트는 /agents, MCP 연결은 /mcp로 지금 무엇이 켜져 있는지 확인하고 관리합니다. 메뉴 모양은 버전에 따라 다릅니다.

스킬은 한 걸음 더 나갑니다. 특정 일을 하는 방법, 양식, 참고 자료를 한 꾸러미로 묶어 두면 Claude가 그 일이 필요할 때 꺼내 씁니다. 우리 회사 보고서 서식이나 24단계에서 해 본 파일 합치기 절차 같은 것이 좋은 후보입니다. 스킬은 Claude Code뿐 아니라 Claude의 여러 화면에서 쓰이며, 만드는 법과 다듬는 법은 제6부 전체에서 다룹니다. 이 부에서는 "매번 같은 설명을 하는 일이 CLAUDE.md로도 넘친다면 스킬을 떠올린다"는 정도만 기억하면 됩니다.

어디서부터 시작할까. 다섯 가지를 한꺼번에 들일 필요는 없습니다. 오히려 그러면 무엇이 문제를 일으켰는지 가려내기 어렵습니다. 순서는 이렇게 권합니다. 같은 요청을 세 번 이상 타이핑했다면 슬래시 명령부터. 규칙이 한 번이라도 어겨졌고 그 결과가 되돌리기 어렵다면 훅. 검토에서 계속 같은 종류의 실수를 놓친다면 서브에이전트. 다른 프로그램의 자료를 손으로 복사해 붙이는 일이 잦다면 MCP. 무엇을 붙이든 먼저 계획을 받고, 공식 문서로 형식을 확인하고, 붙인 뒤에는 일부러 규칙을 어기는 요청을 해서 정말 막히는지 시험합니다.

윤 과장이 이 가운데 무엇을 골랐는지 봅시다.

현장 장면

28단계의 날씨 소동이 끝난 다음 주, 윤 과장은 한 가지가 계속 마음에 걸렸습니다. 인증키가 화면 코드에 들어간 일은 CLAUDE.md에 규칙을 적기 전이었지만, 적은 뒤라고 해서 절대 다시 생기지 않는다고 장담할 수 있을까요? 윤 과장은 Claude Code에게 물었습니다. "인증키로 보이는 문자열이 파일에 들어가면 커밋 전에 멈추게 할 수 있어? 고치지 말고 계획만."

돌아온 계획에는 훅이 들어 있었습니다. 파일을 고칠 때마다 키처럼 보이는 문자열을 찾아보고, 찾으면 작업을 멈추고 알리는 방식이었습니다. 윤 과장은 계획의 한 대목을 가리키며 물었습니다. "이 검사가 .env.local까지 뒤지면 늘 멈추는 거 아니야?" Claude는 그 파일은 검사 대상에서 빼겠다고 계획을 고쳤습니다. 윤 과장은 IT팀 한 선임에게 계획을 보여 주고 괜찮다는 답을 받은 뒤 적용했습니다. 시험도 잊지 않았습니다. 가짜 키 문자열을 넣은 줄을 추가해 달라고 하자 훅이 작업을 멈췄습니다. 처음으로 규칙이 장치가 되는 순간이었습니다.

다음은 검토였습니다. 윤 과장은 매번 푸시 전에 "휴대폰 화면에서 확인해 줘"라고 했지만, 만든 Claude가 스스로 확인하는 방식이라 늘 "문제없습니다"가 돌아왔습니다. 이번에는 검토만 맡는 서브에이전트에게 세 가지를 따로 보게 했습니다. 좁은 화면에서 가려지는 버튼, 우리말이 아닌 오류 문구, 사람 이름이 그대로 보이는 곳. 첫 검토에서 "저장" 버튼이 작은 휴대폰에서 키보드에 가려진다는 지적이 나왔습니다. 만든 쪽은 한 번도 말하지 않은 문제였습니다.

마지막으로 윤 과장은 매번 길게 치던 확인 요청을 "푸시 전 점검"이라는 명령 하나로 묶었습니다. 욕심이 난 것도 있었습니다. 사내 문서 창고를 MCP로 연결해 방문처 업종 목록을 자동으로 불러오면 좋겠다는 생각이었습니다. 하지만 누가 만든 연결인지, 회사가 허락한 것인지 알 수 없었습니다. 윤 과장은 그 생각을 "다음에 붙일 것" 목록에 적고, IT팀과 이야기해 보겠다고 메모했습니다. 그리고 하나를 더 적었습니다. "내려받는 파일에도 사람 이름 규칙이 지켜지는지 훅으로 검사할 것." 이 메모가 왜 중요했는지는 제4부 끝 39단계의 발표장에서 드러납니다.

따라 하기

1. 내 도구의 CLAUDE.md에 적힌 규칙을 모두 읽고, 각 규칙 옆에 "어기면 되돌릴 수 있나"를 적습니다. 성공 기준: 되돌릴 수 없는 규칙이 하나 이상 표시돼 있습니다.
2. 그 가운데 하나를 골라 아래 첫 번째 프롬프트로 훅 계획만 받습니다. 공식 문서에서 훅 설정 방법을 한 번 읽습니다. 성공 기준: 계획에 언제 실행되는지, 무엇을 검사하는지, 걸리면 어떻게 되는지가 들어 있습니다.
3. (회사 PC라면 IT 담당자 확인 뒤) 훅을 적용하고, 일부러 규칙을 어기는 요청을 합니다. 성공 기준: 훅이 작업을 멈추거나 경고합니다.
4. 아래 두 번째 프롬프트로 검토만 맡는 서브에이전트에게 세 가지를 확인하게 합니다. 성공 기준: 항목마다 예·아니오와 근거가 돌아옵니다.
5. Claude Code 안에서 /help로 쓸 수 있는 명령을 확인하고, 내가 자주 치는 요청 하나를 적어 둡니다. 성공 기준: 명령으로 묶을 후보가 하나 정해집니다.
6. 연결하고 싶은 바깥 도구가 있다면 이름, 만든 곳, 읽기·쓰기 여부를 적어 "다음에 붙일 것" 목록에 올립니다. 성공 기준: 허락을 받기 전에는 연결하지 않았습니다.

복사해 쓰는 프롬프트

CLAUDE.md의 이 규칙이 꼭 지켜졌으면 해: [규칙 한 문장].
이 규칙을 훅으로 만들 수 있는지 알려 주고, 가능하다면 계획만 보여 줘. 아직 설정은 바꾸지 마.
- 언제 실행되는지(어떤 순간에)
- 무엇을 검사하는지, 걸리면 어떻게 되는지
- 잘못 걸릴 수 있는 경우와 그걸 피하는 방법
- 설정이 어디에 저장되고, 되돌리려면 어떻게 하는지
확실하지 않은 부분은 공식 문서에서 확인해야 한다고 표시해 줘.

검토만 맡는 보조를 따로 두고, 방금 바꾼 내용을 아래 세 가지만 확인하게 해 줘. 고치지는 말고 보고만.
1. [확인할 것 1, 예: 좁은 휴대폰 화면에서 가려지는 버튼이 있는가]
2. [확인할 것 2, 예: 사람 이름이 성 외에 그대로 보이는 곳이 있는가]
3. [확인할 것 3]
항목마다 예·아니오, 근거가 된 파일과 위치를 적어 줘. 확인하지 못한 항목은 확인하지 못했다고 적어 줘.

막히면 이렇게

스스로 점검

• ☐ 훅과 CLAUDE.md 규칙의 차이를 한 문장으로 말할 수 있습니까?
• ☐ 되돌릴 수 없는 규칙 하나를 골라 훅 후보로 적어 두었습니까?
• ☐ 바깥 도구를 연결하기 전에 만든 곳과 권한을 확인해야 한다는 것을 압니까?

기억할 것

• CLAUDE.md는 부탁, 훅은 장치입니다. 어기면 되돌릴 수 없는 규칙만 훅으로 옮기고, 옮긴 뒤에는 일부러 어겨 시험합니다.
• 서브에이전트에는 좁은 역할을, MCP에는 좁은 권한을 줍니다. 설정 방법은 늘 공식 문서에서 확인합니다.

더 알아보기 · 훅 · 서브에이전트 · MCP 연결