Claude Code Mods 도입 전 확인할 권한과 호환성 체크리스트

Claude Code에 작업 상태 패널이나 자체 명령을 더하고 싶다면 Mods가 새로운 선택지다. 다만 업무용 환경에 들이기 전에는 화면보다 먼저 확인할 것이 있다. 누가 만든 코드인지, 무엇에 접근하는지, 내가 사용하는 실행 환경에서 어디까지 동작하는지다.

2026년 10월 1일 공개된 Anthropic 공식 안내에 따르면 Mods는 Claude Code 2.1.287 이상에서 기본 활성화되어 있다. 향후 제공을 예고한 기능이 아니라 해당 버전에서 사용할 수 있는 기능이다. 다만 안내는 API가 릴리스 사이에 바뀔 수 있다고 명시한다. 아래 내용은 2026년 10월 4일 확인한 공식 문서를 기준으로 정리했다.

1. 먼저 필요한 확장인지 판단하기

Mod는 플러그인으로 배포되는 JavaScript·TypeScript 이벤트 처리 코드다. Claude Code 내부에서 프롬프트나 도구 호출에 관여하고, 화면 구성 요소를 추가하거나 바꿀 수 있다.

선택 기준은 작업의 목적이다. 반복 지침을 정리하려면 Skill, 외부 시스템의 도구를 연결하려면 MCP, 기존 스크립트를 이벤트에 맞춰 실행하려면 설정 훅부터 검토할 수 있다. 별도 패널이나 상호작용 화면이 필요할 때 Mods의 차이가 선명해진다. 공식 비교 안내도 이 구분을 제시한다.

2. 화면이 작아도 권한은 작지 않다

Mods는 설치한 사용자의 권한으로 실행된다. 여기서 보안상 중요한 점은 Mods 자체에 파일·프로세스 접근을 격리하는 샌드박스가 제공되지 않는다는 것이다. 파일 읽기·쓰기, 프로세스 실행, 네트워크 요청에 접근할 수 있다. 환경 변수나 설정에 둔 비밀값, 세션의 프롬프트와 도구 호출도 검토 대상이다. Bash 샌드박스를 켰다는 이유만으로 Mod가 실행하는 프로세스까지 격리된다고 보면 안 된다. 공식 권한 설명

따라서 도입할 때는 작성자와 저장소, 검토할 버전을 함께 기록하는 편이 좋다. “상태만 보여 준다”는 소개와 실제 코드의 접근 범위가 맞는지 확인하자. 화면 기능의 크기를 신뢰 수준의 근거로 삼기는 어렵다.

3. 실행 전에 validate 출력을 읽기

플러그인 파일을 확보한 뒤 터미널에서 다음 명령으로 검사할 수 있다. some-mod는 검토할 플러그인 디렉터리로 바꾼다.

claude plugin validate ./some-mod

공식 제작 문서에 따르면 이 명령은 Mod 코드를 실행하거나 세션을 시작하지 않고 매니페스트와 소스를 정적으로 분석한다. hooks는 처리하는 이벤트, calls는 호출하는 Mods API를 보여 준다. 환경 변수를 사용하는 코드는 env reads와 env writes도 살펴볼 수 있다.

  • 파일·프로세스: $.fs.read, $.fs.write, $.process.run, $.process.spawn이 필요한 이유를 확인한다.
  • 통신·비밀값: $.http.fetch의 목적지와 $.env.get, $.settings.read로 읽는 값의 용도를 확인한다.
  • 비용·세션 변경: $.model.complete로 모델을 호출하는지, $.prompt.submit으로 프롬프트를 넣는지 확인한다.
  • 승인 흐름: tool.check 이벤트가 있다면 어떤 조건으로 도구 호출을 허용하거나 거절하는지 읽는다.

각 항목의 의미는 관리자용 검토 안내에서 확인할 수 있다. validate는 코드가 사용하는 기능을 확인하는 출발점이다. 작성자의 신뢰성이나 통신 목적지의 적절성까지 보증하는 보안 인증으로 해석하지 말고, 출력 목록을 실제 코드와 대조하자.

4. 훅 실행과 화면 표시를 따로 확인하기

같은 Mod라도 실행 위치에 따라 보이는 결과가 달라진다. 공식 지원 범위는 다음과 같다.

  • 터미널 CLI: 훅과 사용자 지정 화면을 지원한다.
  • Desktop 앱의 Code 탭: 둘 다 지원하되, 터미널 전용 요소는 제외된다.
  • VS Code 확장의 채팅 패널, claude -p, Agent SDK: 플러그인을 로드한 세션에서 훅은 실행되지만 사용자 지정 화면은 표시되지 않는다.
  • Desktop의 WSL 세션: 플러그인을 사용할 수 없어 Mods도 실행되지 않는다.

VS Code 확장 채팅 패널에서는 Mod 화면이 보이지 않아도 훅은 실행될 수 있다. 같은 VS Code 안에서도 통합 터미널에서 CLI를 실행하면 지원 범위가 달라지므로, 문제를 재현할 때 실행 위치를 함께 기록하자. 화면이 없는 환경에서 필요한 정보는 텍스트로도 확인할 수 있게 설계하는 편이 실용적이다.

5. 호환 버전과 되돌리는 방법을 남기기

공유할 Mod의 README에는 실제로 확인한 Claude Code 버전을 적어 두자. 공식 레퍼런스도 온라인 타입 선언과 설치 버전이 다르면 해당 버전이 생성한 선언을 우선하라고 설명한다.

제작 문서에 따르면 --plugin-dir로 로드하거나 Claude가 만든 Mod에는 .claude-plugin/types/ 아래에 해당 빌드의 타입 선언이 생성된다. 새 버전으로 올린 뒤에는 이 선언과 실제 동작을 함께 확인하는 것이 좋다. 이 글에서는 Mod를 설치하거나 성능·호환성 테스트를 수행하지 않았다.

문제가 생기면 설치한 플러그인을 개별 비활성화하거나, 원인 분리를 위해 새 세션을 다음과 같이 시작할 수 있다.

claude --safe-mode

CLI 문서의 safe mode는 설정 문제를 진단하기 위한 옵션이다. 조직이 관리하는 것을 포함해 설치된 Mods와 여러 사용자 지정 기능이 함께 꺼지므로, 정상 동작만 확인하고 곧바로 특정 Mod를 원인으로 단정하지 말자. 인증·기본 도구·권한 처리는 유지되며 관리 정책도 적용된다. Mods 관리 문서는 내장 Mods가 이 차단 설정들의 대상이 아니라는 점도 구분한다.

팀 도입 전에 남길 네 가지 답

작성자와 검토 버전은 무엇인가? 필요한 파일·통신·모델 호출 범위는 어디까지인가? 팀이 쓰는 각 화면에서 어떻게 동작하는가? 문제가 생겼을 때 무엇을 끄고 다시 확인할 것인가?

이 네 가지가 정리되면 Mods를 들일 이유와 운영 부담을 함께 판단하기 쉬워진다. 조직 전체에 적용할 때는 allowManagedModsOnly 등 관리 정책도 검토하자. 개인 설정과 조직의 managed settings는 적용 범위가 다르므로, 이름이 비슷한 차단 옵션을 그대로 복사하기보다 담당 관리자가 정책의 영향을 확인하는 과정이 필요하다.

작성: David Cho · zzodosa life
확인 기준: 2026년 10월 4일 공식 문서. 예시 명령은 독자의 검토 절차를 설명하기 위한 것으로, 이 글의 실행 결과가 아니다.

댓글

댓글 쓰기