CUBE.ai

AI 정보

클로드 코드 Mods, 코드 몇 줄로 클로드 코드를 내 것으로 만드는 법

2026.10.11

들어가며

클로드 코드 Mods, 코드 몇 줄로 클로드 코드를 내 것으로 만드는 법

클로드 코드를 쓰다 보면 이런 생각이 한 번쯤 듭니다. "스피너 옆에 지금 컨텍스트가 얼마나 찼는지 보여주면 좋겠는데", "git push --force는 무조건 막고 싶은데", "/diff 화면이 내 취향이 아닌데". 지금까지는 Anthropic이 그 기능을 만들어 주길 기다리거나, 설정 파일에 셸 스크립트를 걸어 두는 정도가 최선이었죠.

2026년 10월 1일, 이 판이 바뀌었습니다. Mods가 나왔거든요. 이름이 비슷해서 헷갈리기 쉬운데, 권한 모드(mode)가 아니라 게임의 '모드(mod)'처럼 클로드 코드 자체를 개조하는 기능입니다.

오늘 수업은 세 덩어리로 진행합니다.

먼저 왜 Mods가 필요했는지, 그리고 Mod가 클로드 코드 안에서 어떻게 끼어드는지 원리를 잡습니다. 이벤트와 next()라는 두 단어만 이해하면 나머지는 쉽게 따라옵니다.

다음으로 훅·스킬·MCP와 비교해서 Mod의 자리를 정확히 찍고, 실제 파일 세 개짜리 Mod를 해부한 뒤, Mod로 바꿀 수 있는 것들을 구경합니다.

마지막으로 보안과 실전입니다. Mod는 강력한 만큼 위험하기도 해서, 무엇을 믿고 설치할지 판단하는 법과 첫 Mod를 만드는 순서를 정리합니다.

미리 결론을 살짝 말씀드리면, Mod는 "클로드 코드에 기능을 하나 더 붙이는 것"이 아니라 클로드 코드가 일하는 길목마다 내 코드를 세워 두는 것입니다. 그 길목이 무엇인지부터 볼까요? 출발점은 기존의 '훅'입니다.

1. 훅만으로는 왜 부족했을까?

지도의 맨 왼쪽, 출발점입니다. Mods를 이해하려면 먼저 그 이전 세대인 훅의 한계를 알아야 합니다.

바깥 경비와 매장 리모델링_helpers.webp

클로드 코드에는 원래 훅(hook)이 있었습니다. 설정 파일에 "Claude가 도구를 쓰기 직전에 이 셸 스크립트를 실행해 줘"라고 적어 두는 방식이에요. 문서에서는 이제 Mod의 훅과 구분하려고 이걸 설정 훅(settings hook)이라고 부릅니다.

설정 훅도 꽤 쓸모 있습니다. 특정 명령을 막거나, 로그를 남기거나, 포매터를 돌릴 수 있죠. 그런데 한계가 분명했어요. Anthropic은 발표문에서 훅으로는 이벤트를 다시 쓰거나, 새 UI를 그리거나, 기존 기능을 갈아 끼울 수 없다고 직접 짚었습니다.

비유를 들어 볼게요. 설정 훅은 가게 문 앞에 세워 둔 경비원입니다. 손님(명령)이 들어올 때 "들어가세요" 또는 "안 됩니다"는 말할 수 있어요. 하지만 가게 안으로 들어와서 진열대를 옮기거나, 간판을 새로 달거나, 계산대를 바꿀 권한은 없습니다. 경비원은 바깥에서 따로 움직이는 사람이니까요.

실제로 설정 훅은 클로드 코드 바깥에서 실행되는 별도 프로세스입니다. 스크립트가 JSON을 받아 처리하고 결과를 돌려주는 구조라, 클로드 코드의 화면이나 내부 동작에는 손댈 수 없었죠.

개발자들은 더 많은 걸 원했습니다. 기능이 나올 때까지 기다리지 않고 직접 클로드 코드를 손보고 싶다는 요청이 계속 들어왔고, Anthropic은 출시 전에 GitHub에 설계안을 공개해 피드백을 받은 뒤 Mods를 내놓았습니다.

정리하면, 설정 훅이 "문 앞에서 허락만 하는 경비원"이었다면 Mod는 가게 안에 들어와 리모델링까지 할 수 있는 권한입니다. 그럼 그 권한이 정확히 어떤 원리로 작동하는지 들어가 보겠습니다.

참고 자료(2)

2. Mod는 무엇이고, 어떻게 끼어들까?

지도의 두 번째 구역, 원리를 다루는 곳입니다. 오늘 수업에서 가장 중요한 개념이 여기 있습니다.

이벤트 기반 컨베이어 워크플로우.webp

공식 정의부터 짧게 보겠습니다. Mod는 클로드 코드의 동작과 모양을 바꾸는 플러그인이고, JavaScript나 TypeScript로 쓴 이벤트 핸들러로 이루어져 있습니다.

여기서 키워드는 이벤트입니다. 클로드 코드는 무언가를 할 때마다 "나 지금 이거 한다"고 신호를 냅니다. 도구를 호출할 때(tool.call), 프롬프트를 보낼 때(prompt.submit), 화면의 한 부분을 그릴 때(ui.render), 세션을 시작할 때(session.start)처럼요. Mod는 이 신호에 함수를 걸어 두는 겁니다.

택배 분류 컨베이어 벨트를 떠올려 보세요. 상자(이벤트)가 벨트를 타고 흘러가고, 벨트 옆에는 검수 직원(Mod의 훅)이 줄지어 서 있습니다. 벨트 끝에는 실제 배송 기계(클로드 코드 본래 동작)가 있고요. 각 직원은 세 가지 중 하나를 할 수 있습니다.

  • 지켜보기(Observe): 상자를 보고 기록만 한 뒤 그대로 다음으로 넘깁니다.
  • 바꾸기(Rewrite): 송장을 고쳐 붙여서 넘깁니다.
  • 대신 처리하기(Answer): 상자를 벨트에서 빼서 직접 처리합니다. 뒤쪽 직원과 배송 기계는 이 상자를 보지도 못해요.

코드에서는 이 세 가지가 next라는 함수 하나로 갈립니다. 모든 훅은 ($, e, next) 세 개의 인자를 받아요. $는 Mod가 쓸 수 있는 API, e는 이벤트 데이터, next는 다음 직원에게 넘기는 함수입니다.

on('tool.call', async ($, e, next) => {
  $.ui.log('Claude가 곧 ' + e.tool + '을 사용합니다')  // 지켜보기
  return next(e)                                         // 그대로 넘기기
})

next(e)를 그대로 부르면 지켜보기, 고친 복사본으로 부르면 바꾸기, 아예 부르지 않고 결과를 돌려주면 대신 처리하기입니다. 웹 개발을 해 보신 분이라면 익숙하실 거예요. Express나 Koa의 미들웨어 체인과 똑같은 구조입니다.

여러 Mod가 같은 이벤트를 잡으면 불러온 순서대로 줄을 섭니다. 먼저 선 Mod가 이벤트를 가장 먼저 보고, 결과는 가장 나중에 봅니다. 그래서 서로 다른 사람이 만든 Mod를 쌓아 올릴 수 있죠. 그렇다면 기존의 훅, 스킬, MCP와는 어떻게 다를까요?

참고 자료(2)

3. 훅·스킬·MCP와는 무엇이 다를까?

지도 가운데의 비교 구역입니다. 클로드 코드를 확장하는 방법이 이제 네 가지가 됐으니, 각자의 자리를 정리해 둬야 헷갈리지 않습니다.

스킬과 도구가 모이는 작업 공간.webp

공구함에 칸이 네 개 있다고 생각해 보세요.

Mod설정 훅스킬MCP 서버
정체클로드 코드 안에서 도는 함수이벤트 때 실행되는 셸 명령·HTTP 요청Claude가 읽는 SKILL.md 지침서도구를 제공하는 외부 프로세스
바꾸는 것도구 호출, 프롬프트, 명령, 턴, 화면진행 여부, 도구 인자·결과Claude가 아는 것과 하는 방식Claude가 쓸 수 있는 도구 목록
화면 그리기가능불가불가불가
작성 언어JS / TS스크립트 + settings.json마크다운아무 언어

비유로 정리하면 이렇습니다. 스킬은 업무 매뉴얼이에요. Claude가 읽고 따릅니다. MCP는 외부와 연결된 전화기예요. 사내 시스템이나 GitHub에 연락할 수단을 줍니다. 설정 훅은 문지기고요. 그리고 Mod는 사무실 내부 공사 공구입니다. 칸막이를 옮기고, 게시판을 새로 달고, 업무 흐름 중간에 결재 단계를 끼워 넣을 수 있죠.

여기서 핵심 차이는 "안에서 도느냐, 밖에서 도느냐"입니다. 스킬, 설정 훅, MCP는 모두 클로드 코드 바깥에서 스크립트를 돌리거나 텍스트·도구를 건네주는 방식이에요. Mod만 클로드 코드 안에서 돌아갑니다. 그래서 화면을 그리고, 이벤트를 고쳐 쓰고, 기본 기능을 갈아 끼울 수 있는 거죠.

그러니 선택 기준도 간단합니다. 같은 지시를 채팅에 자꾸 붙여 넣고 있다면 스킬, Claude가 외부 시스템에 접근해야 하면 MCP, 이미 있는 스크립트로 막거나 기록만 하면 되면 설정 훅. 화면에 뭔가 띄우거나, 커스텀 명령을 만들거나, 이벤트 자체를 바꿔야 할 때 비로소 Mod를 꺼내면 됩니다. 그리고 이 넷은 한 플러그인 안에 함께 담을 수 있어요.

참고로 다른 도구들도 비슷한 방향으로 가고 있습니다. Cursor도 에이전트 루프 앞뒤에서 도는 훅 스크립트를 지원하고, Pi 같은 코딩 에이전트는 TypeScript 확장으로 런타임 기능을 붙입니다. "에이전트를 사용자가 직접 개조한다"는 흐름이 업계 전체에서 진행 중인 셈이에요. 자, 그럼 Mod 하나를 직접 뜯어볼까요?

참고 자료(3)

4. Mod 하나는 어떻게 생겼을까?

지도의 해부도 구역입니다. 원리를 알았으니 실물을 열어 보겠습니다.

블록에서 호출까지, 플러그인 흐름도.webp

Mod는 플러그인이라서 폴더 하나에 파일 세 개면 충분합니다.

first-mod/
├── .claude-plugin/
│   └── plugin.json   ← 신분증
└── hooks/
    ├── hooks.json    ← 안내판
    └── register.js   ← 엔진

레고 세트로 비유하면, plugin.json은 상자 겉면의 이름표입니다. 이름, 버전, 설명이 적혀 있죠. hooks.json은 "엔진은 이 봉투에 있어요"라는 안내판이에요. 여기에 modules 키로 코드 파일 경로를 적어 두면, 그게 있다는 사실만으로 이 플러그인은 Mod가 됩니다.

{
  "description": "The first-mod hooks module",
  "modules": ["./register.js"]
}

그리고 진짜 일을 하는 register.js입니다. 공식 문서의 첫 예제는 Claude가 도구를 몇 번 호출했는지 세서 스피너 옆에 보여주는 Mod예요.

let calls = 0  // 두 훅이 함께 쓰는 변수

export function register(on) {
  // Claude가 도구를 쓰기 직전마다 실행
  on('tool.call', async ($, e, next) => {
    calls += 1
    $.ui.invalidate('ui.render')  // 화면 다시 그려 달라고 요청
    return next(e)                // 도구는 평소처럼 실행
  })

  // 스피너를 그릴 때마다 실행
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
  })
}

이걸 켜면 Claude가 일하는 동안 스피너가 Thinking · tool calls: 3…처럼 바뀝니다. 2섹션에서 배운 걸로 읽어 보면, 첫 번째 훅은 지켜보기, 두 번째 훅은 바꾸기예요.

눈여겨볼 점이 두 가지 있습니다. 첫째, 두 훅이 calls라는 변수를 공유합니다. 한 훅이 기록한 걸 다른 훅이 보여 줄 수 있다는 것, 이게 바깥에서 따로 도는 설정 훅으로는 못 하던 일이에요. 둘째, on('ui.render', { component: 'Spinner' }, ...)의 가운데 객체는 매처(matcher)라는 필터입니다. 스피너를 그릴 때만 이 훅이 돌게 하는 거죠.

Node.js도, 번들러도, 빌드 단계도 필요 없습니다. 클로드 코드가 .js와 .ts 파일을 그대로 읽어요. 이제 이 구조로 무엇까지 바꿀 수 있는지 구경해 보겠습니다.

참고 자료(2)

5. Mod로 어디까지 바꿀 수 있을까?

지도 오른쪽의 활용 구역입니다. 원리와 구조를 알았으니, 이제 무엇을 할 수 있는지 사례로 보겠습니다.

모드의 권한 한계 안내도.webp

스마트폰을 처음 샀을 때를 생각해 보세요. 홈 화면에 위젯을 올리고, 알림 규칙을 정하고, 기본 앱을 다른 앱으로 바꾸잖아요. Mod도 클로드 코드에 대해 그런 일을 합니다. 크게 네 갈래예요.

① 화면을 그린다. 대화창 옆에 패널을 열거나, 입력창 위에 띠를 두를 수 있습니다. 탭, 버튼, 입력창도 넣을 수 있고요. Anthropic이 공개한 샘플 token-weather는 컨텍스트 창이 얼마나 찼는지 일기예보처럼 보여줍니다.

② 도구 호출을 지킨다. tool.call에서 next를 부르지 않고 { deny: '...' }를 돌려주면 명령이 실행되지 않습니다.

on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
  if (/git push .*--force/.test(e.command)) {
    return { deny: '이 저장소에서는 강제 푸시 금지. 새 브랜치로 푸시하세요.' }
  }
  return next(e)
})

deny 문구는 Claude가 도구 결과로 읽으니, Claude가 따를 수 있는 지시문으로 쓰는 게 요령입니다. 한 걸음 더 나가 $.ui.ask로 "이 명령 실행할까요?" 하고 사람에게 물어본 뒤 진행할 수도 있어요. 샘플 blast-radius가 바로 이렇게 위험한 명령을 붙잡고 무엇이 바뀌는지 보여준 다음 진행·취소 버튼을 띄웁니다.

③ 프롬프트를 손본다. prompt.submit에서 사용자가 쓴 글은 그대로 두고, Claude만 읽는 맥락을 덧붙일 수 있습니다. 예를 들어 "PR"이라는 단어가 나오면 현재 브랜치 이름을 슬쩍 붙여 주는 식이죠.

④ 기본 기능을 갈아 끼운다. 사실 클로드 코드의 /diff도 이제 Mod입니다. 마음에 안 들면 /plugin에서 끄거나 내 버전으로 바꿀 수 있어요. Anthropic은 앞으로 더 많은 기본 기능을 Mod로 옮겨서, 작은 핵심만 남기고 필요한 것만 다시 붙이는 구조로 가겠다고 밝혔습니다.

팀 단위로는 CI 상태를 옆 패널에 띄우는 Mod, 운영 설정을 건드리는 명령 앞에 확인 단계를 끼우는 Mod, 다른 모든 Mod의 호출을 기록하는 감사 로그 Mod 같은 예시도 소개됐습니다.

단, 한 가지는 바꿀 수 없습니다. 권한 확인 창이에요. Mod는 화면 대부분을 다시 그릴 수 있지만, 권한 프롬프트가 보여주는 내용만큼은 손댈 수 없게 막혀 있습니다. 왜 그런지는 다음 섹션의 주제와 이어집니다.

참고 자료(3)

6. 남이 만든 Mod, 믿고 설치해도 될까?

지도 아래쪽의 경고 구역입니다. 지금까지 본 강력함의 뒷면을 확인할 차례예요.

열쇠부터 보안 승인까지의 배송 흐름.webp

결론부터 말하겠습니다. Mod는 샌드박스 안에서 돌지 않습니다. 클로드 코드와 똑같은 권한으로, 여러분 컴퓨터에서 여러분으로서 실행돼요. 공식 문서가 꼽는 Mod의 손이 닿는 범위는 이렇습니다.

  • 내 계정이 접근할 수 있는 모든 파일 읽고 쓰기, 프로그램 실행, 네트워크 요청
  • 환경 변수와 설정 파일 속 API 키 읽기
  • 내가 보내는 모든 프롬프트와 Claude의 모든 도구 호출 보기
  • 프롬프트나 도구 호출 고쳐 쓰기, 내가 묻기 전에 도구 호출 승인하기
  • 내 요금제로 모델 호출하기

이건 집 열쇠 복사본을 건네는 것과 같습니다. 친구에게 화분 물 주기를 부탁하며 열쇠를 줄 수는 있죠. 하지만 열쇠를 받은 사람은 화분만 볼 수도, 서랍을 열어 볼 수도 있습니다. 그래서 열쇠는 믿을 수 있는 사람에게만 줍니다. Mod도 믿을 수 있는 작성자와 마켓플레이스에서만 설치하라는 게 공식 안내입니다. 샌드박스를 켜 둬도 그건 Claude가 실행하는 Bash 명령에만 적용되고, Mod가 띄운 프로세스는 그 밖에서 돈다는 점도 기억해 두세요.

그럼 열쇠를 주기 전에 무엇을 할 수 있을까요? 설치 전에 내용물을 검사할 수 있습니다.

claude plugin validate ./some-mod

이 명령은 코드를 실행하지 않고, 이 Mod가 어떤 이벤트에 끼어드는지(hooks:)와 어떤 API를 부르는지(calls:)를 목록으로 보여줍니다. Mod는 바깥 세상에 손댈 때 반드시 $ API를 거쳐야 하는 구조라서, 이렇게 정적 분석만으로 "하는 일 목록"을 뽑을 수 있는 거예요.

끄는 방법도 단계별로 있습니다. Mod 하나는 /plugin의 Installed 탭에서, 한 세션 전체는 --safe-mode로, 직접 설치한 모든 Mod는 설정 파일에 "disableAllHooks": true로 끌 수 있습니다.

팀·기업 플랜에는 울타리가 하나 더 있습니다. sec-default라는 내장 Mod가 줄의 맨 앞에 서서, 사용자가 설치한 Mod가 조직의 deny 규칙을 뒤집는 것 같은 위험한 행동을 막아요. 관리자가 정한 설정 훅 역시 모든 Mod보다 먼저 돌고, 거기서 막힌 건 최종 결정입니다. 이제 이 모든 걸 알고 첫 Mod를 만들어 보죠.

참고 자료(3)

7. 첫 Mod는 어떻게 시작할까?

지도의 마지막 칸, 실습 구역입니다. 순서대로 따라 하면 오늘 바로 첫 Mod를 띄울 수 있어요.

요청부터 공유까지 단계별 안내.webp

요리를 처음 배울 때는 레시피를 그대로 따라 하고, 익숙해지면 간을 바꾸죠. Mod도 처음엔 Claude에게 만들어 달라고 하는 것부터 시작하는 게 가장 빠릅니다. 클로드 코드로 클로드 코드를 개조하는 셈이에요.

0단계. 버전 확인. Mods는 터미널에서 Claude Code v2.1.287 이상, 데스크톱 앱 Code 탭에서는 v2.1.286 이상에서 동작합니다. claude --version으로 확인하세요.

1단계. 말로 요청하기. 세션에서 "입력창 위에 현재 git 브랜치를 보여주는 mod 만들어줘"처럼 원하는 걸 말합니다. Claude는 내장 스킬 plugin-authoring을 참고해 ~/.claude/dev-mods/세션ID/ 아래에 Mod를 씁니다. ~/.claude는 보호 경로라서 Manual이나 acceptEdits 모드에서는 파일마다 승인을 요청받아요.

2단계. 핫 리로드 승인. 첫 파일이 저장되면 "이 세션에서 핫 리로드를 켤까요?"라고 묻습니다. Enable for this session을 고르면 턴이 끝날 때 Mod가 로드되고, 이후 수정할 때마다 자동으로 다시 불러옵니다.

3단계. 확인하고 다듬기. /plugin의 Installed 탭에 Mod가 보이는지 확인하고, 마음에 안 드는 부분은 Claude에게 말로 고쳐 달라고 하세요.

4단계. 내 것으로 옮기기. 세션이 만든 Mod 폴더는 일정 기간 뒤 정리됩니다. 계속 쓰려면 ~/mods/git-branch 같은 곳으로 폴더를 복사하고, 이렇게 불러옵니다.

claude --plugin-dir ~/mods/git-branch

5단계. 검사하고 테스트하기. claude plugin validate로 이벤트 이름 오타 같은 실수를 잡고, claude plugin test로 세션 없이 자동 테스트를 돌릴 수 있습니다. 로드할 때 생기는 .claude-plugin/types/ 폴더의 타입 정의 파일이 내 버전의 이벤트와 API를 정확히 알려 주니, 문서보다 이 파일을 믿으세요.

6단계. 공유하기. 몇 명이면 폴더째 전달하고, 팀이면 사내 마켓플레이스에, 모두에게라면 Anthropic 디렉터리에 제출합니다. 이름을 claude-로 시작하면 검증에서 떨어지니 주의하세요.

마지막으로 어디서 보이는지도 알아 두세요. 훅은 대부분의 환경에서 돌지만, Mod가 그린 화면은 터미널과 데스크톱 앱에서만 보입니다. VS Code 확장 채팅 패널, claude -p, 클라우드 세션에서는 그림 없이 훅만 동작해요.

오늘의 핵심을 한 줄로 정리하면 이겁니다. 기능을 기다리지 말고, 길목에 내 코드를 세워라. 단, 열쇠는 믿는 사람에게만.

참고 자료(3)

댓글

불러오는 중입니다…