Claude Code 모드란 무엇인가요?

Claude Code 모드란 무엇일까요? 모드는 직접 작성한 JavaScript 또는 TypeScript를 Claude Code 안에서 실행하는 플러그인으로, Claude Code의 모양과 동작을 바꿀 수 있습니다. 프롬프트 위에 한 줄을 그리거나, 상태 표시줄에 숫자를 넣거나, 위험한 셸 명령을 거부하거나, 슬래시 명령을 추가할 수 있습니다. 모드는 Claude Code 2.1.287에서 도입되었으며 기본적으로 켜져 있습니다.

이 가이드에서는 모드가 무엇으로 이루어져 있는지, 무엇에 접근할 수 있고 무엇에는 접근할 수 없는지, 설정 hooks, MCP 서버, 스킬과 어떻게 다른지, 그리고 설치해도 안전한지 판단하는 방법을 설명합니다. 마지막에는 2분 만에 만들 수 있는 실제로 작동하는 모드를 소개합니다.

Claude Code 모드는 무엇인가요?#

모드는 파일 하나가 더 있는 일반적인 Claude Code 플러그인입니다. 그 파일이 바로 hooks 모듈입니다. 이 모듈은 register(on, options) 함수를 내보냅니다. Claude Code가 플러그인을 로드하면 register를 호출하고, 모드는 on(...)을 사용해 "도구가 곧 실행된다", "턴이 끝났다", "스피너를 그리는 중이다" 같은 이벤트를 구독합니다.

각 핸들러는 세 개의 인수를 받습니다.

• $: 모드 API입니다. 모드가 일으키는 모든 효과는 이것을 거칩니다. $.ui.status, $.ui.toast, $.process.run, $.fs.read, $.command.register 등이 있습니다.
• e: 이벤트입니다. 예를 들어 곧 실행될 Bash 명령이 여기에 담깁니다.
• next: 이벤트를 Claude Code 본래의 동작으로 넘겨 줍니다.

핸들러는 관찰(next(e)를 호출하고 결과를 살펴봄), 재작성(변경한 이벤트로 next를 호출), 응답(next를 호출하지 않고 자체 결과를 반환함. 가드가 도구 호출을 거부하는 방식이 이것입니다) 중 하나를 할 수 있습니다.

플러그인을 모드로 만드는 것은 키 하나입니다. hooks/hooks.json에 modules가 있으면 그 플러그인은 모드입니다.

{
  "modules": ["./register.js"]
}

모드는 Claude Code 프로세스 안에서 사용자 권한으로 실행됩니다. 샌드박스에 격리되지 않습니다. 그 대신 얻는 이점은 모든 효과가 반드시 $를 거쳐야 한다는 점입니다. 덕분에 Claude Code는 실행하기 전에 모드의 소스를 읽고, 어떤 이벤트를 처리하며 어떤 API를 호출하는지 정확하게 나열할 수 있습니다.

모드는 무엇을 바꿀 수 있나요?#

이벤트 목록은 길지만, 대부분의 모드는 몇 가지 영역만 사용합니다.

모드는 이 밖에도 창을 열고, Claude가 호출할 도구를 등록하고, 서브에이전트를 실행하고, 파일을 읽고 쓰고, HTTP 요청을 보내고, 작은 키-값 저장소에 데이터를 보관할 수 있습니다. 이 모든 기능은 $ 호출이며, 검증 결과에 나타납니다.

모드 UI는 터미널(JetBrains 플러그인 포함)과 데스크톱 앱의 Code 탭에서 그려집니다. VS Code 확장의 채팅 패널, claude -p, Agent SDK에서는 hooks는 계속 실행되지만 아무것도 그려지지 않습니다. 따라서 가드는 헤드리스 실행에서도 계속 사용자를 보호하지만, 상태 표시줄 모드는 텍스트를 표시할 곳이 없을 뿐입니다.

모드, hooks, MCP 서버, 스킬은 어떻게 다른가요?#

이 네 가지 확장 방식은 이름만 비슷할 뿐 실제로는 서로 다릅니다.

• 설정 hooks는 정해진 시점(도구 실행 전, 도구 실행 후, 중지 시)에 셸 명령을 실행합니다. 별도의 프로세스로서 stdin과 stdout의 JSON으로 Claude Code와 통신합니다. UI를 그리거나 실시간 상태를 유지할 수 없습니다.
• 모드는 타입이 지정된 API로 프로세스 안에서 실행됩니다. hook이 할 수 있는 일은 물론, 렌더링 위치에 그리기, 명령과 도구 등록, 그리고 스피너 그리기나 컴팩션 시작처럼 hooks로는 볼 수 없는 이벤트에 반응할 수 있습니다.
• MCP 서버는 프로토콜을 통해 Claude에게 새로운 도구와 데이터 소스를 제공합니다. 언제 호출할지는 Claude가 결정합니다. Claude Code의 인터페이스를 바꾸거나 내장 도구를 가로채지는 않습니다.
• 스킬은 작업이 일치할 때 Claude가 불러오는 지침과 파일입니다. Claude Code가 하는 일이 아니라 Claude가 아는 내용을 바꿉니다.

대략적인 기준은 이렇습니다. Claude가 새로운 것을 알거나 할 수 있게 하고 싶다면 스킬이나 MCP 서버를 선택하세요. Claude Code 자체가 다르게 보이거나 동작하게 하고 싶다면 모드를 작성하세요.

Claude Code 모드는 안전한가요?#

모드는 터미널에서 할 수 있는 일이라면 무엇이든 할 수 있으므로, 다른 개발자 도구를 설치할 때처럼 신중하게 다루세요. 다음 세 가지 습관이 위험을 줄여 줍니다.

1. validate 출력을 읽으세요. claude plugin validate <dir>는 모듈에 대해 hooks: 줄과 calls: 줄을 출력합니다. 상태 표시줄 모드인데 $.http.fetch나 $.fs.write가 나열된다면 더 자세히 살펴볼 필요가 있습니다.
2. 권한 배지를 확인하세요. ClaudeMods의 모든 모드 페이지는 이러한 호출을 "명령어 실행"이나 "도구 호출 가로채기" 같은 쉬운 라벨로 바꾸고, 모드가 각 권한을 왜 필요로 하는지 한 문장으로 설명합니다.
3. 끄는 방법을 알아 두세요. /plugin disable <name>은 모드 하나를 끕니다. claude --safe-mode는 모든 모드가 비활성화된 상태로 세션을 시작합니다. 설정의 "disableAllHooks": true는 모드를 계속 꺼 둡니다.

조직은 더 나아갈 수 있습니다. 관리자는 관리형 모드만 허용하고, --plugin-dir을 통한 사이드로딩을 차단하며, 승인된 가드 모드를 사용자가 설치한 모든 것보다 먼저 실행되도록 순서를 지정할 수 있습니다. 자세한 내용은 모드 관리자 문서에 있습니다.

어떤 Claude Code 버전이 필요한가요?#

claude --version을 실행하세요. 터미널에서는 2.1.287 이상이 필요합니다. 데스크톱 앱은 자체 Claude Code 사본을 포함하고 있으며, 2.1.286부터 모드가 작동합니다. 이 사이트의 모든 모드에는 마지막으로 테스트한 버전이 표시되어 있으며, 이 글을 쓰는 시점에서는 2.1.291입니다.

작은 모드를 직접 만들어 작동 방식 확인하기#

파일 세 개면 충분합니다. 다음과 같은 구조를 만드세요.

hello-status/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

.claude-plugin/plugin.json:

{
  "name": "hello-status",
  "version": "0.1.0",
  "description": "Writes a fixed message to the Claude Code status line",
  "author": { "name": "Your Name" }
}

hooks/hooks.json에는 앞에서 본 modules 키를 넣고 ./register.js를 가리키도록 합니다. 그다음 hooks/register.js를 작성합니다.

export function register(on) {
  on('session.start', async ($, e, next) => {
    const started = await next(e)
    $.ui.status('hello from my first mod')
    return started
  })
}

실행하기 전에 검사하세요.

claude plugin validate ./hello-status

Claude Code 2.1.291에서는 다음과 같이 출력됩니다.

  ❯ ./register.js hooks: session.start
  ❯ ./register.js calls: $.ui.status

✔ Validation passed

이제 이번 실행에만 모드를 로드한 상태로 세션을 시작합니다.

claude --plugin-dir ./hello-status

상태 표시줄에 메시지가 표시됩니다. register.js를 수정하고 저장하면 Claude Code가 다시 시작하지 않고 모듈을 다시 로드합니다. 모드는 hello-status@inline으로 로드되며 종료하면 사라집니다. 테스트와 배포 방법은 모드 튜토리얼에서 다룹니다.

모드는 어디에서 찾을 수 있나요?#

모드는 플러그인 마켓플레이스를 통해 배포됩니다. 마켓플레이스는 marketplace.json이 있는 Git 저장소나 URL입니다. ClaudeMods도 마켓플레이스를 하나 운영하고 있으며, 디렉터리에 있는 모든 모드에는 데모 녹화, 설치 명령, 옵션, 실제로 작업을 수행하는 코드, 사용하는 권한을 보여 주는 페이지가 있습니다. 각 모드는 페이지가 공개되기 전에 실제 Claude Code 빌드에서 검증, 테스트, 녹화를 거칩니다.

모드를 추가할 준비가 되셨나요? Claude Code 모드 설치 방법에서 모든 설치 방법과 업데이트, 제거 방법을 확인하세요.