Claude Code Mods 사용법: 스킬·MCP 차이와 안전한 설치 가이드
Claude Code를 쓰다 보면 반복 지침은 스킬로 정리하고, 외부 서비스는 MCP로 연결하며, 위험한 명령은 훅으로 막게 됩니다. 그런데 도구 호출을 잠시 멈춰 검토 화면을 띄우거나, 프롬프트 위에 상태 정보를 표시하거나, Claude Code의 동작 자체를 이벤트 단위로 바꾸고 싶다면 기존 방식만으로는 한계가 있습니다. Claude Mods는 이 빈자리를 채우는 새로운 확장 방식입니다.
Mods는 Claude Code v2.1.287에서 추가됐습니다. 단순한 화면 꾸미기 기능이 아니라 JavaScript 또는 TypeScript 이벤트 핸들러가 Claude Code 프로세스 안에서 실행되며, 프롬프트·도구 호출·명령·턴·인터페이스를 관찰하거나 수정하고 경우에 따라 대신 처리할 수 있습니다. 그만큼 강력하지만, 설치한 사용자와 같은 권한으로 실행되고 별도의 샌드박스가 없다는 점을 먼저 이해해야 합니다.
Claude Mods란 무엇인가
Mod는 Claude Code 플러그인 안에 들어가는 이벤트 처리 코드입니다. Claude가 도구를 호출하려는 순간, 사용자가 프롬프트를 제출한 순간, 스피너나 도구 행을 그리는 순간처럼 특정 이벤트가 발생하면 등록된 함수가 호출됩니다. 함수는 이벤트를 그대로 통과시키고 기록만 할 수도 있고, 내용을 바꿔 다음 단계로 넘길 수도 있으며, 원래 동작을 실행하지 않고 자체 결과를 돌려줄 수도 있습니다.
공식 문서는 이를 세 가지 동작으로 설명합니다. 관찰은 도구 호출 횟수나 실행 시간을 기록하는 방식, 재작성은 프롬프트나 도구 인수 또는 UI 속성을 바꾸는 방식, 대신 처리는 위험한 명령을 거절하거나 자체 명령 결과를 반환하는 방식입니다. 이 차이 때문에 Mods는 단순 지침 파일이나 외부 도구 연결보다 Claude Code의 실행 흐름에 더 가깝습니다.
스킬·설정 훅·MCP와 무엇이 다른가
| 방식 | 정체 | 주로 바꾸는 것 | 적합한 상황 |
|---|---|---|---|
| Mod | 프로세스 내부 JS/TS 이벤트 핸들러 | 도구 호출, 프롬프트, 명령, 턴, UI | 패널·상태 표시, 이벤트 재작성, 자체 명령 |
| 설정 훅 | 설정 파일에 연결한 셸·HTTP·프롬프트 | 이벤트 허용·차단, 인수·결과, 컨텍스트 | 기존 스크립트로 정책·감사 로그 적용 |
| 스킬 | Claude가 읽는 SKILL.md 지침 | Claude가 아는 내용과 작업 순서 | 반복하는 절차와 팀 규칙 전달 |
| MCP 서버 | 외부 프로세스나 서비스가 제공하는 도구 | Claude가 호출할 수 있는 기능 | GitHub·데이터베이스·사내 API 연결 |
선택 기준은 “무엇을 추가하려는가”입니다. 같은 설명을 계속 입력한다면 스킬이 맞고, 외부 시스템의 데이터를 읽거나 작업을 수행해야 한다면 MCP가 맞습니다. 기존 스크립트로 명령을 차단하거나 로그를 남기는 정도라면 설정 훅이 단순합니다. 반면 인터페이스에 패널을 만들고, 도구 호출 전후의 흐름을 바꾸고, 여러 이벤트가 공유하는 상태를 표시해야 한다면 Mod가 필요합니다. 하나의 플러그인 안에 Mod·스킬·MCP 서버를 함께 넣을 수도 있으므로 반드시 하나만 고르는 구조는 아닙니다.
시작 전 준비사항
- Claude Code 2.1.287 이상: 터미널에서
claude --version으로 확인합니다. - 신뢰할 수 있는 작업 폴더: Claude가 세션 안에서 Mod를 작성하고 로드하려면 해당 workspace의 신뢰 승인이 필요합니다.
- 코드 검토 수단: 저장소의 작성자, 변경 이력, 라이선스뿐 아니라 실제 hooks와 API 호출을 확인해야 합니다.
- 최소 권한 환경: 비밀키가 많은 개인 홈 디렉터리보다 별도의 개발 사용자나 제한된 프로젝트 폴더에서 먼저 시험하는 편이 안전합니다.
초기 접근 때 쓰던 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS 환경 변수는 2.1.287 이상에서 무시됩니다. 값을 0으로 바꾸는 방식으로 Mods를 끌 수 없으며, 공식 비활성화 방법을 사용해야 합니다.
설치 전에 꼭 검증하는 순서
1. 파일을 먼저 확보하고 작성자를 확인한다
Mod는 마켓플레이스에서 플러그인 형태로 설치할 수 있지만, 설치 명령부터 실행하지 않는 것이 좋습니다. 저장소를 먼저 열어 .claude-plugin/plugin.json, hooks/hooks.json, 실제 register.js 또는 TypeScript 파일을 확인합니다. 네트워크 주소, 프로세스 실행, 환경 변수 접근, 파일 쓰기가 있는지 살펴봅니다.
2. 실행하지 않고 정적 검증한다
claude plugin validate ./some-modvalidate는 Mod 코드를 실행하지 않고 manifest와 hooks module을 분석합니다. 결과의 hooks: 줄은 어떤 이벤트를 받는지, calls: 줄은 파일·프로세스·네트워크·UI 등 어떤 Mods API를 호출하는지 보여줍니다. 설명에는 단순 상태 표시라고 되어 있는데 $.process.run, $.fs.write, 네트워크 호출이 나타난다면 설치를 멈추고 이유를 확인해야 합니다.
3. 한 세션에서만 시험한다
claude --plugin-dir ./some-mod로컬 디렉터리를 --plugin-dir로 로드하면 영구 설치 전에 한 세션에서 동작을 확인할 수 있습니다. 세션에서 /plugin을 열어 활성 Mod 이름이 표시되는지 보고, 예상한 이벤트에서만 작동하는지 확인합니다. 개발 중 파일을 바꾸면 핫 리로드가 가능하지만, 변경 후에는 검증 명령을 다시 실행하는 편이 안전합니다.
4. 신뢰가 확보된 뒤 설치한다
/plugin install token-chart@your-org
# 또는 셸에서
claude plugin install token-chart@your-org셸에서 설치하거나 업데이트하는 동안 Claude Code 세션이 열려 있었다면 /reload-plugins로 다시 불러옵니다. 그렇지 않으면 다음 세션부터 로드됩니다. 사용자 전체, 특정 프로젝트, 현재 사용자와 프로젝트에만 적용하는 local 범위가 다르므로 팀 저장소에는 범위를 명확히 정해야 합니다.
직접 만드는 가장 작은 구조
first-mod/
├── .claude-plugin/
│ └── plugin.json
└── hooks/
├── hooks.json
└── register.jsplugin.json은 플러그인 manifest, hooks.json은 hooks module의 경로, register.js는 이벤트 처리 함수를 담습니다. Node.js 프로젝트나 별도 번들러가 필수는 아니며 Claude Code가 JavaScript와 TypeScript 파일을 직접 로드할 수 있습니다.
처음부터 복잡한 자동 승인 Mod를 만들기보다 읽기 전용 관찰부터 시작하는 것이 좋습니다. 예를 들어 tool.call 이벤트에서 호출 수를 세고, ui.render 이벤트에서 스피너 옆에 숫자를 표시하면 이벤트 공유 상태와 UI 갱신을 모두 연습할 수 있습니다. 공식 튜토리얼도 이 방식의 first-mod를 사용합니다.
실용적인 활용 예시 3가지
예시 1. 컨텍스트와 도구 사용량 표시
긴 세션에서 어떤 도구가 얼마나 자주 호출되는지, 컨텍스트가 얼마나 차는지 프롬프트 위에 표시할 수 있습니다. 입력은 도구 호출 이벤트와 사용량 정보이고, 산출물은 세션 안의 작은 상태 행입니다. 검토 기준은 표시를 꺼도 Claude의 원래 동작이 바뀌지 않는지, 외부 전송 없이 로컬 상태만 읽는지입니다. 단순 지표 표시라면 파일 쓰기나 네트워크 권한은 필요하지 않아야 합니다.
예시 2. 위험 명령의 변경 범위 미리보기
공식 샘플 blast-radius처럼 rm -rf나 force push 전에 실행을 잠시 멈추고 예상 변경 범위를 보여주는 흐름을 만들 수 있습니다. 입력은 셸 명령과 대상 경로, 산출물은 진행 또는 취소 버튼이 있는 확인 화면입니다. 다만 “위험 명령을 잡는다”는 설명만 믿어서는 안 됩니다. 파이프, 환경 변수, 복합 명령 등 우회 형태를 처리하는지 테스트하고, 조직의 deny 정책을 대체하는 유일한 방어선으로 사용하지 않아야 합니다.
예시 3. 팀용 정책·감사 Mod
조직 관리자는 사용자 Mod가 로드되기 전에 등록 정보를 검사하거나, 파일 쓰기와 프로세스 실행 이벤트를 감사 로그에 남기는 관리형 Mod를 배포할 수 있습니다. 입력은 plugin 등록과 tool 호출 이벤트, 산출물은 허용·거절 결정과 감사 기록입니다. 여기서는 로그에 프롬프트 원문이나 비밀값이 섞이지 않도록 마스킹 기준을 먼저 정하고, 사용자 설치 Mod를 허용할지 allowManagedModsOnly로 제한할지 정책을 문서화해야 합니다.
가장 중요한 보안 사실
Mod는 샌드박스되지 않습니다. 설치한 사용자 계정이 읽고 쓸 수 있는 파일에 접근하고, 프로세스를 시작하며, 네트워크 요청을 보낼 수 있습니다. 환경 변수와 설정 파일의 API 키를 읽을 수 있고, 사용자가 보낸 프롬프트와 Claude의 도구 호출을 볼 수 있으며, 이벤트를 바꾸거나 모델 사용량을 소비할 수도 있습니다.
Claude Code의 sandbox를 켜더라도 격리되는 것은 Claude가 실행하는 Bash 명령입니다. Mod가 직접 시작한 프로세스는 그 샌드박스 밖에서 실행됩니다. 따라서 “sandbox를 사용 중이니 출처를 모르는 Mod도 안전하다”는 판단은 틀립니다. 가장 효과적인 순서는 신뢰할 작성자 선택, 소스 검토, claude plugin validate, 제한된 폴더의 일회성 로드, 필요한 기능만 영구 설치입니다.
또한 Mod는 권한 요청 화면 자체를 위조할 수는 없지만, 설정에 따라 도구 호출을 사용자가 보기 전에 승인할 수 있습니다. 개인 환경에서는 항상 허용 범위를 넓히지 말고, 조직 환경에서는 관리형 guard와 deny 정책을 기본으로 두어야 합니다.
끄기와 복구 방법
- 하나만 끄기:
/plugin의 Installed 탭에서 해당 플러그인을 disable 또는 uninstall합니다. - 현재 세션의 설치 Mod 전체 끄기:
claude --safe-mode로 시작합니다. 다른 사용자 커스터마이징도 함께 꺼집니다. - 모든 세션의 사용자 설치 Mod 끄기:
~/.claude/settings.json에"disableAllHooks": true를 설정합니다. 설정 훅과 사용자 상태 표시도 함께 중지될 수 있습니다. - 조직에서 사용자 Mod 차단: 관리 설정의
allowManagedModsOnly를 사용합니다.
주의할 점은 Mod를 껐다고 플러그인 전체가 사라지는 것은 아니라는 사실입니다. 같은 플러그인에 포함된 스킬, 명령, 에이전트, MCP 서버는 계속 로드될 수 있습니다. 문제가 지속되면 플러그인의 나머지 구성 요소와 설정 범위까지 확인해야 합니다.
도입 판단 체크리스트
- 이 요구사항은 스킬이나 설정 훅으로 더 단순하게 해결할 수 없는가?
- Mod가 요구하는 hooks와 calls가 설명된 기능에 비해 과도하지 않은가?
- 비밀정보가 있는 환경 변수와 사용자 홈 파일에 접근할 이유가 있는가?
- 영구 설치 전
--plugin-dir로 한 세션 시험을 했는가? - 중지 명령과 복구 방법을 팀원이 알고 있는가?
- 업데이트할 때 변경 내역과
validate결과를 다시 확인하는가?
Claude Mods의 장점은 Claude Code를 팀 작업 방식에 맞게 깊게 바꿀 수 있다는 점입니다. 하지만 “설치하기 쉬운 플러그인”보다 “내 권한으로 실행되는 코드”에 가깝게 다뤄야 합니다. 처음에는 읽기 전용 상태 표시처럼 실패 영향이 작은 Mod로 구조를 익히고, 위험 명령 차단이나 자동 승인처럼 권한에 영향을 주는 기능은 별도의 코드 검토와 조직 정책을 거쳐 도입하는 것이 안전합니다.
English version: https://en.stackfinch.com/2026/10/claude-code-mods-guide-build-install.html
공식 출처
- Claude Code Docs: Mods overview
- Claude Code Docs: Create a mod
- Claude Code Docs: Manage mods for your organization
- Anthropic Claude Code CHANGELOG
자료 확인일: 2026년 10월 4일
댓글
댓글 쓰기