Claude Code Mods와 Hooks 차이: TypeScript 검증 로직과 멀티 모델 역할 분담
확장 수단 네 가지의 역할 구분, 샌드박스 없는 Mods의 보안 규칙, 모델별 작업 배분

핵심 요약
- Claude Code Mods는 내부 이벤트에 연결되는 TypeScript 함수로, 단순 셸 호출인 Hooks보다 세밀하게 프롬프트와 도구 입출력을 가공할 수 있다.
- Mods는 샌드박스 없이 사용자 권한으로 실행되므로, 팀·엔터프라이즈 환경에서는 최상단에 로드되는 내장 sec-default 가드를 유지하고 검증된 사내 코드만 로드해야 한다.
- 설계·추론은 상위 모델(Opus 계열), 메인 구현은 중형 모델(Sonnet 계열), 단순 탐색·로그 요약은 경량 모델(Haiku 계열)로 나누는 멀티 모델 오케스트레이션을 결합하면 비용과 속도를 동시에 최적화할 수 있다.
2026년 10월 초 Anthropic은 Claude Code 내부의 생명주기(Lifecycle) 이벤트에 직접 개입해 프롬프트를 재작성하거나 도구 호출을 가로채고 UI 패널까지 제어할 수 있는 새로운 확장 체계인 Mods를 도입했다. 이 글은 기존 셸 스크립트 기반 Hooks나 마크다운 기반 Skills를 넘어, Claude Code Mods에 연결할 검증 로직을 TypeScript로 작성하는 실습과 내장 보안 가드(sec-default)의 동작 원리, 그리고 Haiku·Sonnet·Opus 계열 모델을 역할별로 묶어 쓰는 멀티 모델 오케스트레이션 전략을 다룬다.
Mods 개념 정리: 왜 기존 Hooks와 별개로 TypeScript 기반 Mods가 나왔나
Claude Code Mods 실습 가이드에 따르면, 2026년 10월 도입된 Mods(v2.1.286+ 계열부터 본격 지원)는 Claude Code 프로세스 내부 이벤트에 연결되는 작은 JavaScript/TypeScript 모듈이다.
기존에도 Claude Code 훅으로 수정 직후·작업 종료 전 자동 검증 붙이기에서 다룬 것처럼 settings.json에 셸 명령어를 적는 Hooks가 있었지만, 외부 프로세스를 매번 띄워야 하고 대화 컨텍스트나 프롬프트 배열, 터미널 UI 상태를 프로그래밍 방식으로 세밀하게 조작하기에는 한계가 있었다.
반면 Mods는 TypeScript 함수 체인으로 동작하며 다음과 같은 작업이 가능하다.
- 프롬프트 및 컨텍스트 변환: 모델로 요청이 전송되기 직전 특정 코딩 규칙이나 동적 시스템 상태를 주입하거나 민감한 문자열을 마스킹한다.
- 도구 실행 인터셉트 및 자동 후처리: 파일 쓰기(
Write,Edit) 도구가 성공한 직후 조건부로 포매터와 관련된 단위 테스트만 골라 실행하고 그 결과를 에이전트 턴 안에 바로 합친다. - 내장
sec-default우선 로드 구조: Team 및 Enterprise 플랜이나 관리형 설정(managed-settings.json)이 활성화된 환경에서는 Anthropic의 내장 보안 Mod인 **sec-default(cc-plugin-sec-default@builtin)**가 사용자 Mod보다 항상 먼저 체인 최상단에 로드되어 조직의 보안 정책과 권한 차단 규칙이 우회되지 않도록 보호한다.
실습: 파일 수정 후 자동 포맷과 관련 테스트를 실행하는 TypeScript 검증 로직 만들기
프로젝트 내 .tsx 또는 .ts 파일이 수정될 때마다 Biome 포맷을 맞추고 대응하는 .test.ts 파일이 있으면 실행해 실패 로그를 에이전트에게 돌려주는 로직을 작성한다. Mods의 이벤트 이름과 등록 방식은 Claude Code 버전에 따라 달라질 수 있으므로, 검증 로직은 Mods API와 분리한 순수 함수로 만들고 연결 지점은 Claude Code 공식 문서에서 사용 중인 버전 기준으로 확인한다.
단계별 구현 절차
- 저장소에
tools/auto-verify.ts를 만들어 Mods 쪽 코드가 얇게 유지되도록 검증 로직을 분리한다. - 전달받은 파일 경로가
.ts또는.tsx인지 검사하고, 아니면 아무것도 하지 않는다. - 포매터와 테스트 러너를 실행하고, 실패하면 에이전트가 다음 턴에서 고칠 수 있도록 오류 출력을 문자열로 돌려준다.
- 사용 중인 버전의 문서에서 도구 실행 완료 이벤트를 찾아
Edit,Write호출 뒤에 이 함수를 부르도록 연결한다.
// tools/auto-verify.ts
import { execFileSync } from "node:child_process";
import { existsSync } from "node:fs";
export function verifyChangedFile(filePath: string): string | null {
if (!/\.(ts|tsx)$/.test(filePath)) return null;
try {
// 1. 수정된 파일 포맷팅
execFileSync("npx", ["biome", "format", "--write", filePath], {
stdio: "pipe",
});
// 2. 대응하는 테스트 파일(.test.ts / .test.tsx)이 있으면 실행
const testPath = filePath.replace(/\.(ts|tsx)$/, ".test.$1");
if (existsSync(testPath)) {
execFileSync("npx", ["vitest", "run", testPath], { stdio: "pipe" });
return `[auto-verify] 포맷팅 및 ${testPath} 테스트 통과`;
}
} catch (err: any) {
const stderr = err.stderr?.toString() || err.message;
return `[auto-verify 경고] 자동 검증 실패:\n${stderr}`;
}
return null;
}
인자 배열을 분리하는 execFileSync를 쓰면 파일 경로에 셸 메타문자가 섞여도 명령으로 해석되지 않는다. 같은 함수는 Mods 대신 셸 기반 PostToolUse Hook에서도 호출할 수 있다.
보안 경고: Mods는 샌드박스가 없다 — 팀 배포 전 반드시 지킬 규칙
Mods를 도입할 때 가장 주의해야 할 보안 사실은 Mods가 별도의 격리된 VM이나 웹어셈블리 샌드박스에서 도는 것이 아니라, Claude Code를 실행한 사용자의 로컬 머신 권한 그대로 실행된다는 점이다.
즉, 인터넷에서 검증되지 않은 서드파티 Mod 패키지를 무심코 설치하면 로컬 .env 파일, SSH 키, AWS 자격 증명에 그대로 접근할 수 있다. 따라서 팀 환경에서는 다음 세 가지 방어 규칙을 적용해야 한다.
- 외부 서드파티 Mod 무검증 실행 금지: 사내에서 사용하는 모든 Mod는 Git 저장소 내에 짧은 TypeScript 소스로 직접 커밋해 PR 코드 리뷰를 거치게 한다.
- 엔터프라이즈
allowManagedModsOnly설정 활용: 조직 관리자는managed-settings.json에서"allowManagedModsOnly": true를 켜 승인되지 않은 개인 설치 Mod의 로드를 원천 차단할 수 있다. sec-default@builtin체인 유지: 관리자가 커스텀 플러그인 순서를 지정(prependPlugins등)하더라도sec-default가 빠지지 않도록 설정을 검증해야 한다.
멀티 모델 오케스트레이션: Haiku · Sonnet · Opus 계열 역할 분담 전략
멀티 모델 조합 팁에서 강조하듯, 모든 작업을 가장 비싸고 무거운 단일 모델 하나로 처리하면 토큰 한도(Rate Limit)가 금방 소진되고 응답 대기 시간도 길어진다. 자주 권장되는 패턴은 에이전트와 서브에이전트, 그리고 Mod 라우팅을 통해 모델마다 가장 잘하는 역할만 맡기는 오케스트레이션이다.
- 아키텍처 설계 및 난해한 버그 추론 (Opus 계열 상위 모델): 코드 전체를 다 쓰게 하지 않고, 처음에 요구사항의 엣지 케이스를 짚어내거나 다중 파일 리팩토링 계획(Plan)을 세우는 단계, 그리고 원인을 알 수 없는 레이스 컨디션을 분석할 때만 제한적으로 호출한다.
- 일상적인 컴포넌트 구현 및 코드 수정 (Sonnet 계열): 계획이 확정된 뒤 실제 React 컴포넌트 작성, API 라우트 연결, 테스트 코드 구현처럼 입출력 속도와 코딩 정확도의 균형이 중요한 메인 워커로 지정한다.
- 빠른 파일 탐색, 로그 요약, 린트 수정 (Haiku 계열):
수백 개 파일에서 특정 심볼 위치를 찾거나, 긴 테스트 실패 로그에서 핵심 스택 트레이스만 발라내는 서브에이전트(
Explore등)에는 경량 모델을 배정해 비용과 지연을 최소화한다.
서브에이전트 단위로 모델과 역할을 분리하는 구체적인 파일 설정은 Claude Code Subagents로 탐색·구현·리뷰 작업을 역할별로 나누는 방법과 Claude Code Skills·Hooks·Subagents 차이와 함께 쓰는 구성법에서 이어서 확인할 수 있다.
비교표: Skills vs Plugins vs Mods vs Hooks 역할 구분
확장 수단이 네 가지로 늘어나면서 무엇을 써야 할지 헷갈릴 때는 아래 기준으로 선택한다.
| 구분 | 동작 형태 | 주된 역할 및 개입 시점 | 보안·권한 특성 | 프론트엔드 팀 추천 용도 |
|---|---|---|---|---|
| Skills | SKILL.md 마크다운 + 참조 스크립트 | 특정 도메인 작업 지침·절차 주입 (온디맨드 로드) | 프롬프트 지침 중심 (낮은 위험) | 디자인 시스템 규칙, 번들 최적화 절차 공유 |
| Hooks | settings.json 내 셸 명령어 | PreToolUse, PostToolUse, Stop 시 외부 CLI 호출 | 로컬 셸 실행 | 간단한 tsc --noEmit, 커밋 전 정적 검사 |
| Mods | TypeScript / JS 함수 체인 | 프롬프트 재작성, 도구 입출력 가공, 런타임 상태 제어 | 샌드박스 없음 (프로세스 전체 권한, sec-default 선행) | 동적 컨텍스트 주입, 민감 정보 마스킹, 조건부 테스트 연쇄 실행 |
| Plugins | Skills + MCP + Hooks/Mods 패키징 번들 | 여러 확장 요소를 하나의 배포 단위로 묶음 | 포함된 구성 요소의 권한을 따름 | 사내 표준 프론트엔드 에이전트 환경 일괄 배포 |
초보자가 자주 실수하는 포인트
- 마크다운 SKILL.md로 충분한 코딩 컨벤션 안내까지 전부 TypeScript Mod로 짜는 실수: 단순 스타일 가이드나 프레임워크 사용법은 SKILL.md로 두는 것이 유지보수가 훨씬 쉽다. Mod는 입출력 데이터를 코드로 변환하거나 강제 제어가 필요할 때만 쓴다.
- 도구 실행 완료 이벤트 안에서 수십 초가 걸리는 전체 E2E 테스트 스위트를 동기로 돌리는 실수: 매번 파일을 수정할 때마다 에이전트 응답이 멈추게 된다. 파일 저장 시점 Mod에는 수정된 단일 파일의 포매터와 단위 테스트(1~2초 이내)만 연결해야 한다.
체크리스트
- 작성한 Mod 코드에서 execSync 대신 인자 배열이 분리된 execFileSync를 사용해 파일 경로를 통한 명령어 인젝션을 방지했는가?
- 팀 저장소에 커밋된 Mod에 외부 알 수 없는 도메인으로 코드를 전송하는 네트워크 호출이 없는지 리뷰했는가?
- 엔터프라이즈 관리 설정(managed-settings.json)에서 sec-default가 정상 활성화되어 있는가?
- 서브에이전트 설정 파일(.claude/agents/*.md)에 작업 난이도에 맞는 model 필드가 각각 지정되어 있는가?
자주 묻는 질문
기존에 만들어 둔 PostToolUse 셸 Hook이 있는데 전부 Mods로 바꿔야 하나요?
바꿀 필요 없다. 단순한 린터 실행이나 알림 전송처럼 한 줄짜리 셸 명령어로 잘 동작하는 작업은 기존 Hooks로 두는 것이 간결하다. 도구 호출 인자와 출력 텍스트를 파싱해 조건부로 프롬프트를 고쳐 쓰거나 여러 단계의 TypeScript 로직을 태워야 할 때만 Mods로 전환하면 된다.
프론트엔드 팀이 처음 Claude Code 확장 구성을 시작할 때 어떤 순서로 도입하는 것이 좋나요?
1단계로 팀 공통 코딩·디자인 규칙을 담은 Skills(SKILL.md)를 만들고, 2단계로 파일 수정 후 타입 체크를 돌리는 간단한 Hooks를 붙인 뒤, 3단계로 탐색/구현 모델을 나누는 Subagents 멀티 모델 설정과 팀 전용 보안·자동화 Mods를 추가하는 순서를 권장한다.
참고 자료 · 검증 기준
- Anthropic Launched Mods for Claude Code: Let's Build a Tiny One in TypeScript
- Claude Code Multi-Model Orchestration Tips (Jev-X)
- Claude Code Official Documentation - Extensions & Managed Security
위 자료와 내용을 대조한 날짜: . 도구·서비스 정책은 이후 바뀔 수 있으므로 적용 전 공식 문서를 다시 확인하세요.
이 글은 실제 실무 환경 테스트 및 검증된 기술 자료를 바탕으로 작성되었으며, 환경 변화에 따라 지속적으로 갱신됩니다.