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

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

이 단계를 마치면

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

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

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

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

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

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

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

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

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

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

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

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

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

윤 과장이 이 가운데 무엇을 골랐는지 보자.

현장 장면

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

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

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

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

따라 하기

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 연결