Claude Code mod는 Skill이나 테마보다 훨씬 깊게 Claude Code의 동작을 바꿉니다. 프롬프트를 다시 쓰고, 도구 호출을 막거나 바꾸며, 사용자 인터페이스와 일부 권한 처리 흐름을 확장할 수 있습니다. 다만 기본 권한 확인 프롬프트 자체를 다시 그리거나 표시 내용을 바꾸는 것은 허용되지 않습니다.
따라서 “재미있는 플러그인”이 아니라 코드 패키지로 검토해야 합니다. 이 글은 2026년 10월 6일 기준 공식 문서와 공개 저장소를 확인해, 무엇이 달라졌고 설치 전에 무엇을 봐야 하는지 정리한 고급 가이드입니다. 이 환경에서는 외부 mod를 설치하거나 실행하지 않았습니다.
Claude Code Mod는 무엇인가?
mod는 JavaScript 또는 TypeScript 이벤트 핸들러로 Claude Code의 화면과 행동을 바꾸는 플러그인입니다. Claude Code가 도구를 호출하거나, 프롬프트를 전송하거나, 화면 일부를 그릴 때 이벤트가 발생하고 mod가 그 이벤트를 관찰·수정·대체할 수 있습니다.
Anthropic은 Claude Code CLI와 Claude Desktop 앱의 Code 탭에서 mod를 지원한다고 설명합니다. 현재 관리 문서는 mod가 Claude Code 2.1.286 이상에서 기본 활성화된다고 안내합니다. 별도의 시작 가이드는 2.1.287 이상을 기준으로 설명하므로, 실제 사용 전 설치된 버전과 최신 문서를 함께 확인해야 합니다. mod API는 릴리스 사이에서 바뀔 수 있습니다.
Skills·MCP·기존 Hooks와 무엇이 다른가?
| 방식 | 주요 역할 | Claude Code 내부 동작 변경 |
|---|---|---|
| Skills | 작업 지침과 절차를 제공 | 제한적 |
| MCP 서버 | 외부 데이터와 도구를 연결 | 주로 도구 제공 |
| 설정 Hooks | 이벤트마다 셸 명령·HTTP 요청·프롬프트 실행 | 이벤트 반응 중심 |
| Mods | 이벤트 수정, UI 추가, 기능 대체, 새 명령·도구 등록 | 넓음 |
기존 방식으로 해결할 수 있다면 더 단순한 쪽이 낫습니다. 예를 들어 반복 지침만 필요하면 Skill, 외부 시스템의 기능이 필요하면 MCP, 파일 수정 뒤 검사 스크립트를 돌리려면 설정 Hook이 적합할 수 있습니다. mod는 실시간 UI나 도구 호출 가로채기처럼 내부 확장이 필요할 때 검토할 대상입니다.
mod가 할 수 있는 일
- 모델에 전달되기 전 프롬프트를 다시 작성한다.
- 도구 호출을 차단·수정·재시도한다.
- 도구 출력에서 비밀값을 가린 뒤 Claude가 읽게 한다.
- 터미널이나 데스크톱 앱에 버튼·입력창·상태 패널을 추가한다.
- 슬래시 명령이나 모델이 호출할 새 도구를 등록한다.
- 여러 이벤트의 상태를 공유해 사용량이나 편집 기록을 표시한다.
Anthropic은 일부 기본 기능도 mod 형태로 제공하기 시작했습니다. 공개 저장소에는 /diff, AGENTS.md 지원, 조직 정책을 보호하는 sec-default 등의 소스와 테스트가 올라와 있습니다.
가장 중요한 사실: mod는 샌드박스가 아니다
공식 문서는 mod가 설치한 사용자의 권한으로 실행되며 자체 샌드박스가 없다고 분명히 밝힙니다. Claude Code의 Bash 샌드박스를 켜더라도 mod 자체와 mod가 시작한 프로세스는 그 샌드박스 밖에서 실행될 수 있습니다. 파일을 읽고 쓸 수 있고, 프로세스를 시작하고, 네트워크 요청을 보낼 수 있으므로 일반 패키지나 실행 파일처럼 검토해야 합니다.
설치 기준: 마켓플레이스에 있다는 사실보다 소스, 배포자, 업데이트 경로, 요청 권한을 먼저 확인하세요.
설치 전 보안 체크리스트
1. 배포자와 저장소가 같은 주체인지 확인한다
플러그인 디렉터리의 이름만 보지 말고 연결된 저장소, 소유 조직, 최근 커밋, 릴리스 태그를 확인합니다. 유명 mod와 이름만 같은 복제 저장소는 제외해야 합니다.
2. 이벤트와 사용 기능을 확인한다
어떤 이벤트에 연결되는지 살펴보세요. tool.call, 프롬프트 제출, UI 렌더링, 세션 시작 같은 이벤트 중 무엇을 가로채는지에 따라 영향 범위가 달라집니다. 네트워크, 파일, 프로세스, 환경변수 접근이 목적에 비해 과하지 않은지도 봐야 합니다.
3. 설치 스크립트와 자동 업데이트 경로를 읽는다
mod 본문만 안전해 보여도 설치 과정에서 별도 스크립트를 실행하거나 외부 바이너리를 내려받을 수 있습니다. 의존성 잠금 파일과 업데이트 출처가 고정되어 있는지 확인하세요.
4. 비밀값 처리 방식을 본다
API 키나 토큰을 가려 주는 mod라도 먼저 그 값을 읽을 수 있어야 작동합니다. 로그, 원격 분석, 오류 보고, 네트워크 전송 코드가 있는지 확인해야 합니다. “화면에서 숨김”과 “외부로 전송하지 않음”은 다른 문제입니다.
5. 최소 권한의 테스트 환경에서 시작한다
중요 저장소나 프로덕션 자격 증명이 없는 별도 폴더에서 먼저 확인합니다. Git 상태를 깨끗하게 만들고, 테스트용 파일로 읽기·쓰기 범위를 관찰하세요. 회사 장비라면 관리자 정책과 허용된 플러그인 목록을 우선해야 합니다.
설치 후에는 어떻게 검증하나?
직접 만든 mod라면 공식 도구로 구조와 테스트를 확인할 수 있습니다.
claude --version
claude plugin validate ./my-mod
claude plugin test ./my-modvalidate는 매니페스트, 훅, 상태 선언과 호출 기능을 점검하고, test는 Claude Code 런타임을 대상으로 테스트를 실행합니다. 통과했다는 사실이 악성 동작이 없다는 보증은 아니지만, 문법 오류와 선언 누락, 기대한 이벤트 동작을 확인하는 기본 단계입니다.
설치 뒤에는 다음을 다시 확인하세요.
- Claude Code 시작 시 예상한 mod만 로드되는가?
- 파일 수정과 프로세스 실행이 설명된 범위 안인가?
- 외부 네트워크 요청이 필요한 기능인가?
- 권한 거부 규칙을 우회하려는 동작이 없는가?
- 업데이트 뒤 소스와 권한 범위가 달라지지 않았는가?
팀과 기업은 sec-default만 믿어도 될까?
Team·Enterprise 조직이나 managed settings가 적용된 환경에서는 내장 sec-default가 사용자 설치 mod보다 바깥쪽에서 실행되어 조직의 관리 설정, 도구 정책, 권한 거부 규칙을 사용자 mod가 무력화하지 못하도록 보호합니다. 단, 실제 로드 순서는 관리 설정에 따라 달라질 수 있습니다. 관리자는 allowManagedModsOnly를 사용해 조직 소유로 분류된 mod만 실행되도록 제한할 수 있습니다.
하지만 sec-default는 모든 사용자 mod를 자동으로 안전하게 만드는 백신이 아닙니다. 조직 정책을 침범하지 못하게 막는 기본 가드에 가깝습니다. 데이터 접근 범위, 공급망, 네트워크 전송, 업무별 허용 목록은 별도로 관리해야 합니다.
어떤 경우에 mod를 쓰지 않는 편이 낫나?
- 간단한 지침이나 템플릿이면 Skill로 충분한 경우
- 외부 도구 연결만 필요해 MCP 서버로 해결되는 경우
- 한 번의 검사 명령이면 설정 Hook으로 처리되는 경우
- 소스를 읽기 어렵고 신뢰할 배포 경로가 없는 경우
- 프로덕션 자격 증명과 고객 데이터가 있는 환경에서 검증이 부족한 경우
자주 묻는 질문
Claude에게 mod를 만들어 달라고 해도 되나?
공식 가이드는 자연어로 mod 생성을 요청하고 핫 리로드로 확인하는 흐름을 제공합니다. 다만 생성된 코드도 외부 패키지와 똑같이 검토·검증·테스트해야 합니다.
마켓플레이스 mod는 Anthropic이 보증하나?
디렉터리나 마켓플레이스에서 찾았다는 사실만으로 안전성과 품질이 보장되지는 않습니다. 공식 문서도 신뢰하는 작성자와 출처의 mod만 설치하라고 안내합니다.
mod가 권한 확인 창까지 마음대로 바꿀 수 있나?
아니요. mod는 도구 호출의 승인·거부에는 관여할 수 있지만, 공식 문서상 기본 권한 확인 프롬프트의 표시 내용 자체를 바꿀 수는 없습니다. 조직 정책과 사용자 mod의 허용 범위는 관리 설정과 내장 가드의 통제를 받습니다.
정리
Claude Code mod의 장점은 Claude Code 자체를 업무 방식에 맞게 바꿀 수 있다는 점입니다. 동시에 로컬 파일, 프로세스, 네트워크에 접근할 수 있는 코드가 세션에 로드되어 이벤트가 발생할 때 실행된다는 뜻이기도 합니다. 먼저 Skill·MCP·기존 Hook으로 해결되는지 확인하고, mod가 꼭 필요하다면 소스 검토, 최소 권한 테스트, 검증 명령, 업데이트 재검토를 설치 조건으로 두는 편이 안전합니다.
출처 및 확인일
- Anthropic, 「Customize Claude Code with mods in TypeScript」, 2026-10-01, https://claude.com/blog/claude-code-mods, 확인 2026-10-06
- Anthropic, 「Mods overview」, 게시일 미표기, https://code.claude.com/docs/en/plugins/mods/overview, 확인 2026-10-06
- Anthropic, 「Manage mods for your organization」, 게시일 미표기, https://code.claude.com/docs/en/plugins/mods/admin, 확인 2026-10-06
- Anthropic, 「Getting started with Claude Code mods」, 게시일 미표기, https://claude.dev/blog/getting-started-with-claude-code-mods/, 확인 2026-10-06
- Anthropic, 「anthropics/claude-code: mods」, 게시일 미표기, https://github.com/anthropics/claude-code/tree/main/mods, 확인 2026-10-06
'💻IT' 카테고리의 다른 글
| GPT-6 Intelligent UI 사용법: 화면보다 출처와 계산식을 확인하는 법 (0) | 2026.10.09 |
|---|---|
| Claude Code가 고쳤다는데 파일이 안 보일 때: 삭제보다 먼저 확인할 6곳 (0) | 2026.10.09 |
| GPT-6 프롬프트 캐싱 사용법: 긴 에이전트 작업의 API 비용 줄이기 (0) | 2026.10.07 |
| Claude Sonnet 5.5 vs Opus 5.5: 속도·비용·업무별 선택 기준 (0) | 2026.10.06 |
| ChatGPT dots 설정법: 상시 에이전트에 맡기기 전 권한 체크리스트 (0) | 2026.10.06 |
