Claude Code 모드(Mods)란? 설치법과 안전 수칙 정리 | DAKER 커뮤니티

Claude Code 모드(Mods)는 Claude Code 안에서 직접 실행되는 JavaScript·TypeScript 이벤트 핸들러를 플러그인으로 묶은 기능입니다. 도구 호출, 프롬프트 제출, 화면 그리기 같은 이벤트가 생길 때마다 모드의 함수가 불려서 그 이벤트를 지켜보거나, 바꾸거나, 아예 대신 처리할 수 있습니다. 터미널은 Claude Code v2.1.287부터, 데스크톱 앱은 v2.1.286부터 기본으로 켜져 있습니다. 이 글은 Anthropic 공식 문서와 발표 글을 바탕으로 모드가 무엇이고, 어떻게 설치하며, 무엇을 조심해야 하는지 정리합니다.

Claude 공식 로고와 DAKER 공식 워드마크가 오른쪽 위에 놓인 Claude Code 모드 소개 10초 모션 미리보기
Claude Code 모드 10초 모션 미리보기 (무음, 원본 MP4는 글 아래 첨부)

Claude Code 모드를 알게 된 계기: StefanCho 영상

DAKER에 앞서 소개한 StefanCho의 영상 정리 글 Claude Code·Codex 요즘 작업 방식에서 StefanCho는 최근 가장 관심 있게 본 기능으로 모드를 꼽았습니다. 응답 턴이 끝나면 세션의 HTML 리포트를 찾아 직접 만든 macOS 앱의 웹뷰로 띄우고, 화면 녹화 중에는 API 키처럼 생긴 문자열을 가려 보여 주는 REC 모드를 직접 만들어 시연했습니다. 원본 영상은 유튜브에서 볼 수 있습니다.

Claude Code 모드와 기존 훅의 차이

Anthropic은 모드를 소개하며 기존 훅이 할 수 없던 일을 모드가 맡는다고 설명합니다.

훅은 이벤트를 다시 쓰거나, 새 UI를 그리거나, 기능을 교체할 수 없지만 모드는 할 수 있습니다. (Anthropic, Customize Claude Code with mods)

설정 파일에 적는 기존 훅(settings hook)은 셸 명령이나 HTTP 요청을 Claude Code 바깥에서 실행합니다. 반면 모드의 핸들러는 Claude Code 프로세스 안에서 함수로 실행됩니다. 공식 문서는 모드가 할 수 있는 일을 다섯 가지로 정리합니다(Mods overview).

Claude Code 모드 설치 방법

모드는 플러그인 안에 들어 있어서 일반 플러그인처럼 마켓플레이스에서 설치합니다. 공식 문서의 예시는 your-org 마켓플레이스의 token-chart 플러그인입니다.

claude --version                              # 2.1.287 이상인지 확인
claude plugin install token-chart@your-org    # 셸에서 설치
/plugin install token-chart@your-org          # 세션 안에서 설치
/reload-plugins                               # 열린 세션에 바로 적용

세션에 어떤 모드가 올라왔는지는 /plugin을 열면 탭 아래 1 mod active · first-mod 같은 줄로 확인할 수 있습니다. 직접 만들고 싶다면 세션에서 원하는 기능을 설명하면 됩니다. Claude Code에는 모드 작성용 plugin-authoring 스킬이 내장 모드로 들어 있어, Claude가 TypeScript를 쓰고 설치하고 세션에 핫 리로드까지 합니다.

모드 하나는 파일 세 개면 됩니다

공식 문서의 최소 예시는 .claude-plugin/plugin.json(매니페스트), hooks/hooks.json(코드 파일 위치), hooks/register.js(훅 모듈) 세 파일로 구성됩니다. register.js는 tool.call 이벤트에서 도구 호출 수를 세고, ui.render 이벤트에서 스피너 옆에 tool calls: 3…처럼 개수를 붙입니다. 핸들러는 ($, e, next) 형태로, next(e)를 호출하면 원래 동작을 이어 가고, 이벤트를 바꿔 넘기거나 직접 응답할 수도 있습니다.

Anthropic은 token-weather(컨텍스트 창 예보), blast-radius(rm -rf·강제 푸시 같은 위험 명령 보류), replay-theater(/replay로 직전 턴 편집 되감기) 세 샘플 모드를 claude-code-playground 저장소에서 공유합니다. /diff, AGENTS.md 로딩 같은 Claude Code 자체 기능도 이제 내장 모드로 돌아갑니다.

설치 전에 꼭 확인할 안전 수칙

모드는 샌드박스 없이 사용자 권한으로 실행됩니다. 공식 문서는 이 점을 분명히 적어 둡니다.

모드는 사용자 권한으로 실행되는 코드입니다. 파일을 읽고 쓰고, 프로세스를 시작하고, 네트워크 요청을 보낼 수 있습니다. 신뢰하는 작성자와 마켓플레이스의 모드만 설치하세요. (Mods overview)

환경 변수나 설정 파일에 둔 API 키를 읽을 수 있고, 모든 프롬프트와 도구 호출을 보며, 묻기 전에 도구 호출을 승인할 수도 있습니다. 그래서 설치 전에 저장소를 받아 claude plugin validate ./some-mod로 어떤 이벤트를 다루고 어떤 호출을 하는지 먼저 확인하는 것이 좋습니다. 문제가 생기면 /plugin에서 해당 플러그인을 끄거나, --safe-mode로 한 세션만 모두 끄거나, ~/.claude/settings.json에 "disableAllHooks": true를 넣어 설치한 모드를 전부 멈출 수 있습니다. 팀·엔터프라이즈 환경에서는 내장 모드 sec-default가 먼저 로드되어 사용자 모드가 권한 거부 규칙을 덮어쓰지 못하게 막습니다.

AI 대회 참가자에게 쓸모 있는 활용

대회 코드를 에이전트에게 오래 맡기는 참가자라면 모드로 실수를 줄일 수 있습니다. 예를 들어 tool.call 훅으로 제출 파일이나 학습 데이터 폴더를 지우는 명령을 보류하고, 화면 녹화나 발표 시연 때는 키 문자열을 가리고, 턴이 끝날 때마다 실험 리포트를 패널에 띄울 수 있습니다. 다만 모드 자체가 강한 권한을 가지므로, 공개 모드를 쓸 때는 반드시 소스와 validate 결과를 먼저 보세요. Anthropic의 claude-code 저장소는 2026년 10월 15일 기준 GitHub 별 약 15만 900개이며, 내장 모드 소스 일부가 mods 폴더에 공개되어 있습니다.

출처