AIDive

영상 팩

Claude Code mod: 출처 기반 결론, 측정 결과, 월요일 체크리스트

읽는 데 9분

TL;DR

  • 10개 mod 중 3개만 남깁니다: collision-guard, model-router, auto-handoff. 셋 모두 헤드리스 읽기 작업에서 측정된 오버헤드가 거의 0이었고, 각각 이름을 댈 수 있는 문제를 해결합니다.
  • next-steps는 삭제합니다. 조건을 충족하는 답변마다 세션을 fork하며, 이번 측정에서 턴당 출력 토큰 +250, +2850 ms가 들었습니다. 제안을 그리지 않는 화면에서도 마찬가지였습니다.
  • cache-keeper(+1589 ms, 모델 ping 비용 발생), recording-mode(저장된 기록이 아니라 화면 표시만 가립니다), session-bookmarks(모델 호출, 프로세스 실행, 파일 쓰기가 가능한 북마크)도 삭제합니다.
  • goal-meter, repo-heatmap, flight-recorder는 시각 효과가 필요한 게 아니라면 삭제합니다. 비용은 거의 없지만 측정된 이점도 없었습니다.
  • 모든 guard mod는 기본적으로 fail open입니다. .catch 핸들러가 없으면 throw한 guard는 건너뛰어지고 명령이 실행됩니다.
  • mod는 샌드박스 안에서 돌지 않습니다. 설치 전에 claude plugin validate 출력을 읽으세요.

측정 결과가 말해 주는 것

화제성과 규모. 출시 트윗은 2026-10-03에 스냅샷을 찍었을 때 조회수 4,138,918, 좋아요 20,021, 북마크 13,440이었습니다 s11. 커뮤니티 카탈로그에는 873개 후보 저장소에 걸쳐 mod 1018개가 올라 있습니다. 스캔은 2026-10-03에 Claude Code 2.1.288 기준으로 했습니다 s9.

mod는 이벤트에 연결되는 함수입니다. 이벤트 전, 후, 대신, 또는 이벤트를 감싸는 방식으로 실행할 수 있습니다 s1. mod에는 Claude Code v2.1.287 이상이 필요하며 기본으로 켜져 있습니다 s2.

먼저 보안. Anthropic 본인의 표현은 이렇습니다. "Mods run with the same access to your machine as Claude Code itself. They aren't sandboxed" s1. mod가 시작한 프로세스는 샌드박스를 켜도 샌드박스 밖에서 실행됩니다 s2. Read(.env)를 거부해 두어도 mod는 $.fs.read로 그 파일을 읽거나, 읽는 프로그램을 실행할 수 있습니다 s6. 카탈로그 스캔에서 409개 mod가 호스트 프로세스를 실행하고, 167개가 파일을 쓰고, 150개가 네트워크에 접근하며, 28개는 이 버전에서 validate에 실패합니다 s9.

홍보와 실제 권한 범위. 정적 감사에서 session-bookmarks는 $.model.complete, $.process.run, $.fs.write를 호출했습니다. 북마크 기능치고는 전체 mod 중 가장 넓은 권한입니다. next-steps는 fs도 process도 env도 쓰지 않아 가장 작았습니다. 이 감사에는 claude plugin validate가 출력하는 calls:와 env reads: 줄을 사용했습니다 s6.

대표 mod에는 턴마다 비용이 있습니다. next-steps는 turn.complete에서 $.model.fork로 세션을 fork하며, README는 fork가 "costs about one short reply"라고 밝힙니다 s10. 제안은 터미널에서만 그려지고 다른 화면에는 아무것도 표시되지 않습니다 s10. fork를 끄는 옵션은 없습니다. 헤드리스 측정에서 출력 토큰 +250, 시간 +2850 ms가 늘었고, 아무것도 표시되지 않는데도 fork 분량이 세션 사용량에 잡혔습니다 s10.

문서에 명시된 한도. 훅 실행 시간은 이벤트당 10초, $.fs 읽기와 쓰기는 파일당 4 MiB, $.store는 JSON 총 4 MiB로 제한됩니다 s3.

guard는 fail open입니다. 문서에 따르면 .catch 핸들러가 없는 훅이 throw하거나, 타임아웃되거나, 잘못된 형태를 반환하면 건너뛰어지고 그 자리에서 다음 핸들러가 실행됩니다 s7. 직접 재현했습니다. .catch 없이 throw하는 Bash guard에서는 touch ./marker-failopen.txt가 파일을 만들었습니다. 같은 guard에 {deny}를 반환하는 .catch를 붙이자 파일이 만들어지지 않았습니다. 한 현장 보고에서는 guard가 켜져 있고 실행 중인데도 아무 일도 하지 않았고, plugin list는 계속 "enabled"로 표시했습니다 s8.

2.1.288에는 열려 있는 버그가 있습니다. await next(e) 뒤에 반환한 deny가 도구를 멈추지 못했고, 모델에는 쓰기가 실패했다고 알렸는데도 파일은 3번 중 3번 모두 써졌습니다 s5.

mod와 settings 훅 비교. settings 훅은 호출마다 프로세스를 띄웁니다. 실행 비용을 측정하니 true 바이너리는 2.2 ms, bash -c 'exit 0'은 8.3 ms, python3 -c 'pass'는 26.1 ms, node -e ''는 43.1 ms였습니다. 주당 도구 호출 5,993회 기준으로 node 훅은 258 s가 듭니다. 프로세스 내부에서 도는 mod는 이 비용이 없습니다. 이미 이벤트를 차단, 허용, 기록하는 스크립트가 있다면 문서는 settings 훅을 권합니다 s2. 한 마이그레이션 보고에서는 셸 훅 27개가 mod 5개로 줄었습니다 s8.

마스킹은 화면 표시에만 적용됩니다. recording-mode는 ui.render가 그리는 내용만 고칩니다. ~/.claude/history.jsonl에는 입력한 그대로의 프롬프트가 남고, 한 테스터는 자신의 canary 문자열을 트랜스크립트의 queue-operation 항목에서 7번 찾았습니다 s5.

mod가 동작하지 않는 곳. 헤드리스 claude -p와 Agent SDK는 훅을 실행하지만 아무것도 그리지 않습니다. Desktop WSL 세션은 둘 다 실행하지 않습니다 s2.

카탈로그 신뢰도. 한 테스터가 버튼으로 $.process.run을 통해 프로그램을 실행하고 홈 디렉터리에 파일을 쓰는 mod를 게시했습니다. 경고 없이 다른 mod와 똑같이 설치되었습니다 s5. 이는 직접 게시한 개념 증명이며, 실제로 확인된 공격은 아닙니다.

측정 결과

데이터: 실제 환경의 최근 7일. 세션 85개, 프로젝트 4개, 사용자 프롬프트 882개, 어시스턴트 턴 11,010회, 도구 호출 5,993회. 벤치마크는 Claude Code 2.1.288(macOS)에서 실행했습니다.

config dur ms Δdur out tok Δout task ok
baseline 3980 0 247 0 3/3
next-steps 6830 +2850 497 +250 3/3
cache-keeper 5569 +1589 367 +120 3/3
recording-mode 8240 +4260* 598 +351* 3/3
goal-meter 3722 -258 244 -3 3/3
collision-guard 4565 +585 376 +129* 3/3
repo-heatmap 4119 +139 257 +10 3/3
flight-recorder 3949 -31 261 +14 3/3
model-router 3698 -282 238 -9 3/3
session-bookmarks 4152 +172 235 -12 3/3
auto-handoff 4051 +71 248 +1 3/3

*가 붙은 행은 답변 편차일 가능성이 높습니다. recording-mode는 측정 중 꺼져 있었고, 꺼져 있으면 아무것도 주입하지 않습니다.

다시 돌려 보는 절차:

  1. mod를 하나씩 설치하고 claude plugin validate를 통과하는지 확인합니다.
  2. 같은 읽기 전용 작업을 haiku에서 claude -p로 헤드리스 실행합니다. config마다 3번 반복하고 소요 시간과 출력 토큰의 중앙값을 구합니다.
  3. 소요 시간과 출력 토큰의 차이만 인용합니다. USD 비용은 config 간 캐시 순서에 따라 달라지므로 무시합니다.
  4. 실행 비용은 각 훅 본문을 30번 실행한 시간의 중앙값을 구해, 주당 도구 호출 횟수를 곱합니다.

월요일에 할 일

  • 설치한 모든 mod에 claude plugin validate를 실행하고 calls:와 env reads: 줄을 읽습니다.
  • 권한 범위(프로세스, fs 쓰기, 모델 호출)가 맡은 일보다 큰 mod는 끕니다.
  • 주로 헤드리스 실행, VS Code 패널, SDK에서 작업한다면 next-steps를 끕니다. 거기서는 제안이 그려지지 않습니다.
  • 의존하는 모든 guard mod에 { deny: ... }를 반환하는 .catch 핸들러를 추가합니다.
  • 각 guard가 fail closed인지 확인합니다. 일부러 throw하게 만들고, 마커 파일을 만드는 명령을 실행해서 파일이 생기지 않는지 봅니다.
  • ~/.claude/history.jsonl이나 트랜스크립트에 비밀이 남지 않도록 마스킹 mod에 의존하지 마세요. 둘 다 디스크에서 직접 확인합니다.
  • node나 python을 쓰는 호출별 셸 훅은, 주당 도구 호출 수에 비해 실행 비용이 누적된다면 프로세스 내부 mod나 컴파일된 바이너리로 바꿉니다.
  • 끄는 방법을 익혀 둡니다: /plugin에서 mod 하나 비활성화, 한 세션만이라면 --safe-mode, 전체라면 ~/.claude/settings.json의 "disableAllHooks": true.

더 읽어 보기

  • 직접 만들어 보기: 약 80줄짜리 mod를 만드는 실습 안내로, 중요한 함정도 다룹니다(모듈 수준 상태는 핫 리로드 때 초기화되므로 데이터는 $.state에 두세요) s4.
  • mod, 훅, 스킬, settings 중 무엇을 쓸지는 자신의 기록으로 정하기: 한 실무자는 먼저 세션 로그에서 반복되는 문제를 찾아보라고 제안합니다 s12.
  • guard를 쓰기 전에 전체 이벤트 목록과 한도를 읽어 보세요 s3.
  • 조직 단위 관리는 여기서 다루지 않습니다. 혼자 개발하는 사람에게 해당하는 요점은 하나입니다. sec-default는 머신에 managed settings가 있거나 Team 또는 Enterprise 플랜으로 로그인했을 때 로드되며, 다른 제한은 추가하지 않습니다 s6.
  • 설계의 배경, 2.1.288에서 고쳐진 worktree 격리 버그, 런타임 내부 구조는 공개 스레드에 있습니다 s5.
  • Anthropic의 샘플 mod(token-weather, blast-radius, replay-theater)는 지원 없이 공유되는 것으로 표시되어 있습니다 s2.

출처

FAQ

mod는 샌드박스 안에서 실행되나요?

아니요. Anthropic은 mod가 Claude Code 자체와 같은 권한으로 머신에 접근한다고 말합니다 s1. mod가 시작한 프로그램도 샌드박스 밖에서 실행됩니다 s2.

guard mod가 크래시하면 어떻게 되나요?

.catch 핸들러가 없으면 건너뛰어지고 명령이 실행됩니다 s7. { deny: ... }를 반환하는 .catch를 추가해 fail closed로 만드세요.

mod가 토큰을 쓰나요?

모델을 호출할 때만 씁니다. 실행해 본 10개 중 측정 가능한 비용이 나온 것은 next-steps와 cache-keeper였고, 나머지는 이번 측정에서 뚜렷한 오버헤드가 보이지 않았습니다.

mod를 빠르게 끄려면 어떻게 하나요?

/plugin에서 하나를 비활성화하거나, --safe-mode로 세션을 시작하거나, ~/.claude/settings.json에 "disableAllHooks": true를 설정합니다 s2. 이 중 어느 것도 내장 mod는 멈추지 못합니다.

설치하기 전에 mod가 무엇을 하는지 확인할 수 있나요?

네. claude plugin validate가 훅, API 호출, 읽는 환경 변수를 나열해 줍니다 s6.