클로드 코드 Mods 나왔다 | 플러그인·훅·스킬과 뭐가 다른가, 설치 전에 볼 권한

클로드 코드에 "모드(Mods)"라는 확장 방식이 새로 생겼습니다. 10월 1일 나온 2.1.287 변경 기록 첫 줄이 "Added Claude Mods: plugins may now modify deeper behavior"입니다. 스킬, 훅, MCP, 플러그인에 이어 또 하나가 늘어난 셈이라 "그래서 이건 뭐가 다른데?"가 먼저 궁금해집니다.

결론부터 말하면 모드는 플러그인 안에 넣는 자바스크립트·타입스크립트 함수이고, 클로드 코드 프로세스 안에서 직접 돕니다. 그래서 화면을 새로 그리고 도구 호출을 가로챌 만큼 강력하지만, 샌드박스 밖에서 내 권한으로 돈다는 점도 같이 알아야 합니다. 공식 문서와 깃허브 소스를 기준으로 정리했습니다.

Claude Mods는 클로드 코드 2.1.287(2026년 10월 1일)에 추가된 확장 방식으로, 플러그인 안에 든 자바스크립트·타입스크립트 이벤트 처리 함수다. 기존 설정 훅이 셸 명령을 바깥에서 실행하는 것과 달리 모드는 클로드 코드 안에서 돌며 화면 패널을 그리고 도구 호출·프롬프트를 바꾸거나 대신 처리할 수 있다. 2.1.287 이상에서는 기본으로 켜져 있고, 얼리 액세스 때 쓰던 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS 환경 변수는 무시되므로 지워야 한다. 내장 모드 You should know는 기본 꺼짐이며 /plugin enable cc-plugin-you-should-know@builtin으로 켠다. 모드는 샌드박스로 격리되지 않고 사용자 권한으로 파일·환경 변수·네트워크에 접근하므로, 설치 전 claude plugin validate로 하는 일을 확인해야 한다.

목차

1. 2.1.287에서 무엇이 들어왔나

2. 설정 훅·스킬·MCP와 무엇이 다른가

3. 켜고 끄기: 2.1.287부터 기본으로 켜져 있다

4. 설치 전에 볼 것: 모드는 샌드박스 밖에서 내 권한으로 돈다

5. 내 클로드 코드는 아직 2.1.280이었다

1. 2.1.287에서 무엇이 들어왔나

클로드 코드 변경 기록의 10월 1일 항목에는 모드 관련 줄이 두 개 있습니다. 하나는 "플러그인이 이제 더 깊은 동작을 바꿀 수 있다"는 Claude Mods 추가이고, 다른 하나는 내장 모드 "You should know"입니다. 긴 작업을 하는 동안 옆에서 보조 에이전트가 지켜보다가 나나 클로드가 놓칠 만한 것을 알려 주는 기능입니다.

출처: 클로드 코드 변경 기록 갈무리

앤트로픽은 9월 3일 깃허브 이슈 #91870에서 "함수 훅(function hooks)" 제안을 공개하고 의견을 받았습니다. 9월 9일 업데이트에서 제품 이름을 Claude Mods로 정했고, 10월 1일 같은 이슈에 "We're live!"라는 공지가 올라왔습니다. 개발 용어인 함수 훅은 모드가 만들어지는 기본 단위로 그대로 남습니다.

핵심 모드는 새 설치 형식이 아니라 "함수 훅을 쓰는 플러그인"입니다. 설치·업데이트·삭제는 기존 플러그인과 같은 /plugin 메뉴와 마켓플레이스로 합니다.

2. 설정 훅·스킬·MCP와 무엇이 다른가

모드 공식 문서는 네 가지를 이렇게 나눕니다. 설정 훅·스킬·상태 줄·MCP는 클로드 코드 바깥에서 스크립트를 돌리거나 클로드에게 글과 도구를 건네는 방식이고, 모드만 클로드 코드 안에서 돕니다.

구분	정체	바꿀 수 있는 것	이럴 때 고른다
모드	플러그인 안의 JS·TS 함수, 클로드 코드 프로세스 안에서 실행	도구 호출, 프롬프트, 명령, 턴, 화면 구성	패널·명령을 추가하거나 이벤트를 고쳐 쓰고 싶을 때
설정 훅	settings.json에 적은 셸 명령·HTTP 요청·프롬프트	도구 호출 허용 여부, 인자·결과, 추가 맥락	가진 스크립트로 막거나 기록만 하면 될 때
스킬	클로드가 읽는 SKILL.md 지침	클로드가 아는 것과 하는 방식	같은 지시를 자꾸 붙여 넣을 때
MCP 서버	도구를 주는 외부 프로세스·서비스	클로드가 가진 도구	외부 시스템에 닿아야 할 때

출처: 깃허브 anthropics/claude-code 갈무리

앤트로픽은 클로드 코드에 들어간 모드 넷의 소스를 깃허브 mods 폴더에 공개했습니다. /diff 패널을 그리는 diff, AGENTS.md를 지침으로 읽는 agents-md, 사용자가 설치한 모드가 조직의 관리 설정과 도구 정책에 손대지 못하게 막는 sec-default, 분석 기록을 보내는 telemetry입니다. 원래 클로드 코드 기능이던 것을 모드 형태로 옮기고 있다는 뜻이라, 직접 모드를 만들 사람에게는 가장 좋은 예제입니다.

3. 켜고 끄기: 2.1.287부터 기본으로 켜져 있다

출처: 클로드 코드 공식 문서 갈무리

공식 문서 기준으로 모드는 클로드 코드 2.1.287 이상에서 기본으로 켜져 있습니다. 셸에서 claude --version으로 버전을 보고, 낮으면 업데이트하면 됩니다. 이 세션이 어떤 모드를 불러왔는지는 /plugin을 열면 탭 아래 흐린 줄에 "1 mod active · 이름"처럼 나옵니다.

끄고 싶은 범위	방법
모드 하나	/plugin의 Installed 탭에서 그 플러그인을 끄거나 삭제
이번 세션만 전부	claude --safe-mode로 시작(다른 사용자 설정도 함께 빠짐)
내가 설치한 모드 전부, 계속	~/.claude/settings.json에 "disableAllHooks": true (설정 훅·상태 줄도 같이 멈춤)

내장 모드는 이 설정으로 멈추지 않습니다. 대신 /plugin의 Installed 탭 Built-in 목록에서 하나씩 끌 수 있습니다(조직 설정을 지키는 sec-default는 끌 수 없습니다). You should know만 기본 꺼짐이라, 쓰려면 클로드 코드 입력창에 아래 명령을 넣습니다.

You should know 켜기

/plugin enable cc-plugin-you-should-know@builtin

변경 기록은 이 모드가 퍼스트파티 세션에서 텔레메트리를 켠 경우에 동작한다고 적었습니다. 공식 문서도 조직에 따라 Show disabled 목록에 보일 때만 켤 수 있다고 덧붙였습니다.

출처: 클로드 코드 공식 문서 갈무리

주의 9월 얼리 액세스 때 공유된 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1을 아직 셸 설정에 넣어 두었다면 지우세요. 공식 문서는 2.1.287부터 이 변수를 무시하므로 0으로 바꿔도 모드가 꺼지지 않는다고 밝혔습니다. 끄고 싶다면 위 표의 방법을 써야 합니다. 다만 깃허브 README에는 "함수 훅이 켜진 곳에서만 로드되고 API는 예고 없이 바뀔 수 있다"는 얼리 액세스 경고가 아직 남아 있습니다.

4. 설치 전에 볼 것: 모드는 샌드박스 밖에서 내 권한으로 돈다

여기가 이 글에서 가장 중요한 부분입니다. 공식 문서는 모드를 "내 권한으로 클로드 코드 안에서 도는 코드"라고 설명하고, 믿을 수 있는 작성자와 마켓플레이스에서만 설치하라고 합니다.

출처: 클로드 코드 공식 문서 갈무리

모드가 할 수 있는 것	뜻
내 컴퓨터에서 나처럼 행동	내 계정이 닿는 파일 읽기·쓰기, 프로그램 실행, 네트워크 요청
비밀값 읽기	환경 변수와 설정 파일 속 API 키까지
세션 보기·바꾸기	모든 프롬프트와 도구 호출을 보고, 고쳐 쓰거나 대신 입력
묻지 않고 승인	물어봐야 할 도구 호출을 먼저 승인할 수 있음
사용량 쓰기	내 요금제나 API 키로 모델 호출

특히 샌드박스를 켜 둬도 소용이 없다는 점을 기억해야 합니다. 샌드박스는 클로드가 실행하는 Bash 명령을 가두는 장치라서, 모드가 직접 띄운 프로세스는 그 밖에서 돕니다. 반대로 모드가 바꿀 수 없는 것도 하나 있습니다. 권한 확인 창은 다시 그리거나 내용을 바꿀 수 없습니다.

반응형

설치 전에 하는 일 미리 보기

git clone https://github.com/작성자/some-mod
claude plugin validate ./some-mod
# 출력의 hooks: 줄 = 가로채는 이벤트
# 출력의 calls: 줄 = 파일 읽기·프로세스 실행·네트워크 요청 등

claude plugin validate는 모드를 실행하지 않고 어떤 이벤트를 가로채고 무엇을 요청하는지만 보여 줍니다. 제 판단으로는 calls에 네트워크 요청이나 프로세스 실행이 보이는데 설명에 그 이유가 없다면 설치하지 않는 게 맞습니다. 커뮤니티 모음 사이트에 올라온 모드도 마찬가지입니다.

5. 내 클로드 코드는 아직 2.1.280이었다

재구성한 예시 화면

이 글을 쓰면서 10월 2일 제 맥에서 claude --version을 쳐 보니 2.1.280이었습니다. 모드가 요구하는 2.1.287보다 낮아서, 이 상태로는 모드를 쓸 수 없습니다. 자동 업데이트를 꺼 두었거나 회사에서 버전을 고정한 경우라면 비슷할 겁니다.

업데이트한 뒤에도 서드파티 모드를 바로 깔기보다, 공개된 내장 모드 소스를 claude --plugin-dir mods/diff처럼 직접 불러와 구조를 읽어 보는 쪽을 권합니다. 모드가 실제로 어떤 이벤트에 붙는지 감이 잡히면 남이 만든 모드를 검토할 때 무엇을 봐야 할지도 보입니다.

Q. 클로드 코드 모드를 쓰려면 환경 변수를 켜야 하나요?

아닙니다. 2.1.287 이상에서는 기본으로 켜져 있고, 공식 문서는 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS를 무시하니 지우라고 안내합니다.

Q. 모드와 기존 훅은 같이 쓸 수 있나요?

같이 돕니다. 공식 문서는 settings.json에 적는 기존 방식을 "설정 훅", 모드의 처리 함수를 "훅"으로 구분해 부르며, 한 플러그인에 모드·스킬·MCP 서버를 함께 담을 수도 있습니다.

Q. 샌드박스를 켜면 모드도 막히나요?

막히지 않습니다. 샌드박스는 클로드가 실행하는 Bash 명령만 격리하고, 모드가 띄운 프로세스는 그 밖에서 돕니다.

Q. 설치한 모드를 한 번에 끄려면?

이번 세션만이면 claude --safe-mode, 계속이면 ~/.claude/settings.json에 "disableAllHooks": true를 넣습니다. 내장 모드는 이 방법으로 꺼지지 않으니 /plugin에서 따로 끕니다.

3줄 핵심 요약

1. Claude Mods는 2.1.287(10월 1일)에 들어온, 클로드 코드 안에서 도는 JS·TS 함수형 플러그인이다.
2. 2.1.287 이상은 기본으로 켜져 있고, 얼리 액세스용 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS는 무시되니 지운다.
3. 모드는 샌드박스 밖에서 내 권한으로 돈다. 설치 전 claude plugin validate로 calls를 확인한다.

마치며

지금 터미널에서 claude --version부터 쳐 보세요. 2.1.287 이상이라면 /plugin을 열어 Built-in 목록에 어떤 모드가 켜져 있는지 확인하고, 셸 설정 파일에 예전 환경 변수가 남아 있는지도 함께 지워 두면 됩니다.

NEXT READ

이어서 읽어 볼 글

01  코딩 에이전트에게 권한을 얼마나 줄까 · 샌드박스와 승인 설정

02  클로드 코드 세션끼리 대화한다 · 클로드 코드 확장 기능 하나 더

#클로드코드,#ClaudeCode,#ClaudeMods,#클로드코드플러그인,#클로드코드훅,#앤트로픽,#AI코딩,#에이전트보안,#플러그인,#코드노트