Claude Code Mods 공식 출시 — 이벤트 훅과 보안 조건으로 읽는 ‘도구를 도구로 바꾸는’ 단계예요

이 글은 Anthropic 공식 블로그의 Claude Code Mods 발표 원문을 근거로 확인한 내용이에요. 원문은 2026년 10월 1일에 공개됐고, 제가 직접 요청해 확인한 날짜는 2026년 10월 6일이에요. 여기에 공식 시작 가이드(2026-10-01 게시, 2026-10-06 확인)의 실제 명령어와 코드 예시를 보강했어요. 기능 자체는 개발자 도구의 이야기지만, 이 글은 AI 도구가 ‘도구의 도구’로 바뀌는 단계를 비개발자 눈높이에서 읽는 걸 목표로 해요. 새 기능이 나왔을 때 어디까지가 사실이고 어디서부터 확인이 필요한지를 가르는 연습이기도 해요.

Claude Code 위에서 돌아가는 작은 함수, Mods가 나왔어요

공식 발표 기준으로 정리하면 이래요. Anthropic은 2026년 10월 1일 Claude Code Mods를 공식 출시했고, Mods는 Claude Code의 동작을 바꾸는 소규모 TypeScript 함수예요. 프롬프트를 다시 쓰거나, 새로운 화면 요소를 더하거나, 내장 기능을 다른 것으로 교체하는 일이 가능해졌어요. 동작 범위는 Claude Code CLI와 데스크톱 앱이고, 공식 가이드는 v2.1.287 이상부터 기본 활성화된다고 명시하고 있어요. 배포는 기존 플러그인 규칙을 그대로 따라요. Mods는 플러그인 안에 담겨 설치·공유되고, 기존의 플러그인 마켓플레이스 허용·차단 통제도 동일하게 적용돼요.

초보자 관점에서 가장 중요한 문장은 ‘직접 작성하지 않아도 된다’는 부분이에요. 공식 발표는 mod를 직접 작성하거나 Claude Code에게 시켜서 작성할 수 있다고 안내해요. 원하는 기능을 말하면 Claude가 TypeScript 코드를 쓰고, 설치하고, 세션 안에서 바로 다시 불러온다는 게 공식 설명이에요. 코딩을 몰라도 기능을 ‘주문’할 수 있게 됐다는 뜻이라, AI 도구를 쓰는 사람과 만드는 사람의 경계가 한 단계 더 흐려지는 변화예요.

Mods는 이벤트 훅으로 동작해요

작동 원리는 공식 발표의 한 문단에 정리돼 있어요. Claude Code는 무언가를 할 때마다 이벤트를 내보내요. 도구를 호출할 때, 권한을 요청할 때, 화면의 일부를 그릴 때가 그 예시예요. mod는 이 이벤트 중 하나에 연결되는 함수예요. 이벤트 전에 실행되거나, 이벤트 후에 실행되거나, 이벤트 대신 실행되거나, 이벤트를 감싸서 앞뒤 모두에서 실행될 수 있어요. 하나의 함수로 mod가 할 수 있는 일은 공식 발표가 예시로 든 이래요. 모델에 닿기 전에 프롬프트를 다시 쓰기, 도구 호출을 차단·재작성·재시도하기, 권한 요청을 승인하거나 거부하기, 도구 출력을 Claude가 읽기 전에 가리기(시크릿 마스킹), 화면에 버튼과 입력 추가하기예요. 이 네 위치를 표로 정리하면 아래와 같아요.

여러 mod가 같은 이벤트에 걸릴 때의 규칙도 공식 발표에 있어요. 로드된 순서대로 실행되고, 먼저 로드된 mod가 이벤트를 가장 먼저 보고 결과는 가장 나중에 본대요. 덕분에 서로 다른 제작자의 mod를 겹겹이 쌓을 수 있다는 설명이에요. 이 ‘순서’ 규칙은 뒤에서 다룰 조직 통제(sec-default가 먼저 로드되는 구조)의 기반이 돼요.

실제 코드가 어떻게 생겼는지는 공식 시작 가이드의 예시가 가장 정확한 근거예요. 가이드의 Blast Radius 예시는 위험한 명령을 실행 전에 가로채 영향 범위를 계산하고, 사용자에게 진행·취소를 묻는 mod예요. 아래는 가이드에 공개된 코드 원문이에요(원문 주석 그대로예요).

// 출처: claude.dev 공식 가이드 "Getting started with Claude Code mods"
// (Addy Osmani, 2026-10-01 게시, 2026-10-06 확인)의 Blast Radius 예시 원문 발췌예요.
on("tool.call", { tool: "Bash" }, async ($, e, next) => {
  const risk = classify(String(e.command ?? ""));
  if (risk === null) return next(e);                 // everything else runs as normal

  const report = await measure($, risk, await $.session.cwd());  // git status, git clean -n, du, ...
  held = { command: e.command, risk, report, decision: null };
  const opened = await $.ui.open({ id: "blast-radius", title: "Blast Radius", focus: true });
  if (!opened.isPlaced) held.where = "band";         // too narrow for a pane: draw above the prompt

  while (held.decision === null && !next.signal.aborted) {
    await $.process.run(["sleep", "0.25"]);          // time inside $ calls doesn't count against the hook's time limit
  }
  if (held.decision === "proceed") return next(e);   // let it run
  return { deny: `Blast Radius held this command: the user pressed Cancel. It would have: ${report.summary}.` };
});

이 코드가 보여 주는 입력·출력·조건을 풀면 이래요. 입력은 Bash 도구 호출 이벤트(명령 문자열)이고, 처리는 위험 분류 → 영향 범위 계산 → 화면 열기 → 사용자 결정 대기 순이며, 출력은 ‘그대로 실행(next)’ 또는 ‘거부(deny)’ 둘 중 하나예요. 발췌 과정에서 앞뒤 문맥 일부는 생략했으므로 전체 코드와 동작 조건은 공식 가이드 원문을 직접 읽어야 해요. 가이드는 이 도구에 대해 “안전망이지 권한 시스템이 아니다”라고 정의해요. 명령 문자열을 읽는 방식이라 명령 치환이나 별칭, rm을 내부에서 부르는 스크립트는 그냥 지나갈 수 있고, 확실한 차단이 필요하면 권한 규칙을 쓰라고 안내해요. 편리한 도구의 한계를 공식이 스스로 밝힌 대표적인 사례예요.

조직 계정에서는 sec-default가 먼저 로드돼요

Mods의 배포 단위가 플러그인이라는 건 조직 관리와 직접 연결돼요. 공식 발표 기준으로 Team·Enterprise 요금제에서는 소유자가 관리 콘솔에서 마켓플레이스 허용·차단을 설정하고, Claude API·서드파티 API 요금제에서는 관리자가 관리형 설정을 사용자 기기에 배포해요. 그리고 Team·Enterprise 요금제와 관리형 설정이 적용된 기기에서는 sec-default(‘security default’)라는 내장 mod가 가장 먼저 로드돼요. 이 mod는 사용자가 설치한 mod가 권한 거부 규칙을 덮어쓰는 것 같은 위험 동작을 차단하고, 소스 코드를 공개해서 무엇을 제한하는지 볼 수 있어요. 관리자가 자신의 mod를 먼저 로드할 때도 sec-default를 목록에 유지하라는 안내가 함께 있어요.

공식 발표가 드는 조직 활용 예시는 세 가지예요. 대화 옆 창에 CI/CD 파이프라인 상태를 보여 주고 빌드 결과에 따라 갱신하는 mod, 명령이 프로덕션 설정을 만지기 전에 확인을 요구하는 mod, 가장 먼저 로드돼 다른 모든 mod의 호출을 기록하는 감사 로깅 mod예요. AI 도구에 조직의 규칙을 코드로 얹는 그림이라, 도구 도입을 승인하는 입장에서 봐야 할 지점이 분명해져요.

샌드박스가 없다는 조건을 앞세워 읽어요

이번 발표에서 기능 소개만큼 중요한 게 보안 조건이에요. 공식 발표는 그대로예요. “Mods run with the same access to your machine as Claude Code itself. They aren’t sandboxed” — mod는 Claude Code 자신과 동일한 머신 접근 권한으로 실행되고, 샌드박스로 격리되지 않는다는 뜻이에요. 그래서 신뢰하는 출처에서 만든 mod만 설치하라는 경고를 공식이 직접 명시했고, 컴퓨터에 코드를 설치할 때와 같은 주의를 당부하고 있어요. 공식 가이드는 설치 전에 게시자의 저장소를 직접 읽어 보라고 권하고, 실행 없이 mod가 무엇을 하는지 확인하는 명령도 제공해요.

가이드의 Token Weather 예시를 검증한 실제 출력이 확인 도구의 역할을 잘 보여 줘요. 아래처럼 mod가 어떤 이벤트에 연결되고 어떤 API를 호출하는지 목록으로 나타나요. 가이드는 validate가 매니페스트와 모듈 소스를 Claude Code가 로드할 때와 같은 방식으로 읽어 어떤 이벤트를 훅하고 무엇을 호출하는지 보고한다고 설명해요. 설치 전에 이 목록을 읽으면 ‘이 코드가 내 머신에서 무엇을 하려는지’를 실행 전에 판단할 수 있어요.

# 출처: claude.dev 공식 가이드(2026-10-01 게시, 2026-10-06 확인)의
# claude plugin validate 실행 예시 발췌예요.
$ claude plugin validate ./token-weather
  > types ./types/index.d.ts declares state: token-weather.readings
  > ./token-weather.mjs hooks: session.start, turn.complete, ui.render{component=AbovePrompt}
  > ./token-weather.mjs calls: $.session.usage (via takeReading), $.state.get, $.state.set (via takeReading), $.ui.resolve
  > ./token-weather.mjs state writes: token-weather.readings
  > ./token-weather.mjs state reads: token-weather.readings
√ Validation passed

새 도구를 설치할 때의 판단 순서를 결정 흐름으로 정리하면 아래 그림과 같아요. 공식 경고와 가이드 권고를 순서로 옮긴 것이고, 개인 계정과 조직 계정의 차이도 한 단계에 넣었어요.

내장 기능도 mod로 옮겨가고 있어요

공식 발표의 방향 선언도 눈여겨볼 부분이에요. Claude Code의 일부 내장 기능은 이제 mod로 배포되고 있어요. 대표적으로 내장 /diff 기능이 mod로 이식돼서, /plugin에서 끄거나 자신만의 버전으로 교체할 수 있게 됐어요. Anthropic은 시간이 지나면 더 많은 내장 기능을 mod로 옮기고, Claude Code를 작은 코어로 줄여 원하는 기능만 얹는 방향으로 간다고 밝혔어요. 도구를 ‘통째로 쓰는 것’에서 ‘필요한 조각을 골라 조립하는 것’으로 바꾸는 설계예요. 공식 문서는 /diff 창과 AGENTS.md 지원처럼 이미 mod로 구현된 내장 기능의 소스가 공개 저장소에 있다는 점도 알려 주고 있어요.

출시 직후 확인된 초기 활용 신호예요

공식 발표와 같은 날인 2026년 10월 1일, 공식 시작 가이드가 올라왔고(Token Weather·Blast Radius·Replay Theater 세 가지 예시 mod를 직접 만들어 보는 11분 분량 튜토리얼이에요), 한국어 권에서도 바로 소개가 시작됐어요. 위키트리는 10월 4일에 이 기능을 ‘훅이 못 하던 프롬프트·화면까지 개발자가 고친다’는 제목의 보도로 정리했고, 국내 개발자 블로그는 10월 1일 공식 가이드의 한국어 요약 튜토리얼을 공개했어요. 공식 문서와 국어 해설이 일주일 안에 함께 나오는 건, 주제가 이미 실사용 단계에 들어갔다는 초기 신호로 읽혀요. 다만 이 신호들은 기능의 일반 성능·안정성을 증명하는 게 아니라 ‘무엇을 어떻게 시작하는지’를 보여 주는 자료라는 범위는 유지할게요.

오늘의 배울 점과 다음 적용

이 부분부터는 Editor_K의 해석이에요. 공식 발표와 공식 가이드가 확인한 사실과 구분해서 읽어 주세요.

• (가) 배운 판단 — 이번 발표의 본질은 ‘AI 도구가 도구의 도구로 바뀌는 단계’라는 점이에요. 새 기능을 기다리는 사용자에서, 이벤트 훅으로 직접 바꾸는 사용자로 역할이 이동하고 있어요. 동시에 그 도구는 샌드박스 없이 내 권한으로 도는 타인의 코드예요. 편리함과 책임이 같은 비율로 커지는 변화라서, ‘설치 출처를 확인하는 습관’이 새 기능 자체만큼 중요한 학습 항목이 됐어요.
• (나) 적용할 장면 — 반복되는 업무에 AI 도구를 붙일 때 세 가지를 순서대로 시도해 볼 수 있어요. (1) 우리 팀이 매일 확인하는 상태(승인 대기·일정·파이프라인)를 보여 주는 관제 화면 만들기, (2) 위험한 작업(삭제·대량 변경) 전에 영향 범위를 보여 주고 확인받는 가드 만들기, (3) 도구 사용 기록을 자동으로 남기는 로그 만들기. 셋 다 공식 발표가 든 조직 예시와 같은 모양이라, ‘말로 기능을 주문하는’ 초보자 실습의 좋은 첫 후보예요.
• (다) 확인할 조건 — 적용 전에 조직 계정인지 개인 계정인지 먼저 확인해요. 조직 계정이라면 관리자가 어떤 마켓플레이스를 허용했는지와 sec-default 통제 범위가 실무 연결점이 되고, 개인 계정이라면 설치 전 확인 절차(출처 신뢰 → 저장소 검토 → validate)를 스스로 지켜야 해요. 도구 실행 권한이 내 계정 전체라는 점, 그래서 실습용 환경과 실제 업무 환경을 분리해야 한다는 전제도 함께 가져가세요.

한계와 남은 질문

• 이 글의 사실 근거는 공식 발표와 공식 가이드예요. 실제 mod를 만들어 돌려 본 독립 검증은 포함되지 않았고, 코드 예시 두 개는 공식 가이드의 발췌·축약이라 전체 동작을 대표하지 않아요.
• 위치별 훅 예시 배치(표 1)는 Editor_K 재구성이에요. 실제 API에서 이벤트별로 어떤 위치·메서드 조합이 허용되는지는 공식 문서의 개별 계약을 확인해야 해요.
• 초기 활용 신호 섹션의 국어 자료는 공식 문서의 요약·보도라서, 새로 검증한 사실이 아니에요. 마켓플레이스의 심사 기준이나 문제 있는 mod의 추적 방법 같은 질문에는 아직 공식 답이 없다는 지적도 외부 분석에서 확인돼요.
• 남은 질문 — 비개발자가 ‘말로 주문해 만든’ mod를 조직에서 안전하게 공유하려면 코드 검토를 누가, 어떤 절차로 맡아야 할지는 우리 환경의 규칙으로 정해야 해요. 실습 관점에서 검토 절차까지 포함한 소규모 가드 만들기를 후속 글에서 다뤄볼게요.

출처와 시각자료

메인 원문: Anthropic, “Customize Claude Code with mods in TypeScript” — 원문 링크 (2026-10-01 게시, 2026-10-06 확인). 출시 사실·이벤트 훅 원리·로드 순서·샌드박스 없음 경고·sec-default·조직 활용 예시·/diff 내장 mod화는 이 원문에서 직접 확인했어요. oEmbed discovery 태그는 2026-10-06 재요청 실측에서 확인되지 않았어요.

보조 근거 1: Addy Osmani, “Getting started with Claude Code mods”, claude.dev — 공식 가이드 링크 (2026-10-01 게시, 2026-10-06 확인). v2.1.287 기본 활성 문구, claude plugin validate 출력 예시, Blast Radius 코드 예시, 설치 전 저장소 검토 권고는 이 가이드에서 확인했어요.

보조 근거 2(초기 활용 신호): 위키트리, “클로드 코드 ‘모드’, 훅이 못 하던 프롬프트·화면까지 개발자가 고친다…샌드박스는 없다” (2026-10-04 보도, 2026-10-06 확인), datanexus-kr 개발자 블로그의 공식 가이드 한국어 튜토리얼 (2026-10-01 게시, 2026-10-06 확인). 두 자료 모두 공식 문서 기반의 요약·보도라 이 글에서 새로 검증한 사실은 아니에요.

OMW 보존분: 공식 발표 원문 발췌는 Edu 지식베이스(OMW) raw 폴더에 2026-10-05 수집본으로 보존돼 있고, 이 글의 사실 대조에 함께 사용했어요.

관련 글: Replit Agent 4로 부서 전용 대시보드를 직접 만들었어요 — 비개발자도(2026-09-28) · OpenAI DevDay 2026 총정리 — 대화형 챗봇에서 ‘일을 하는’ AI로(2026-09-30) — 에이전트가 일을 실행하는 흐름을 다룬 두 글에 이어, 이번 글은 그 에이전트 도구 자체를 규칙으로 바꾸는 단계를 읽었어요.

시각자료 출처

이미지 1·2: AI 생성 이미지(gpt-image-2, 2026-10-05 생성, Edu 교육기획). 텍스트를 넣지 않은 독창적 일러스트예요. 두 장 모두 텍스트 굽음 검사(2026-10-06, 밴드별 성분 분석 1차 + 정밀 프로브 2차)를 통과했어요. 생성 프롬프트 요지와 사용 위치는 미디어 라이브러리 기록(alt·제목·캡션)과 프로젝트 자산 장부에 남겼어요.

표·다이어그램·코드: 표 1의 네 훅 위치 정의는 Anthropic 공식 발표(2026-10-06 확인), 위치별 예시 배치는 Editor_K 재구성이에요. 설치 전 5단 결정 다이어그램은 공식 발표의 샌드박스 없음·신뢰 출처 경고와 공식 가이드의 설치 전 검토·validate 권고를 Editor_K가 순서로 재구성한 거예요. 코드 블록 2개는 claude.dev 공식 가이드(2026-10-01 게시, 2026-10-06 확인)의 실행 예시 발췌예요.