Claude Code의 플러그인은 스킬과 훅 등 확장 기능을 묶어 공유하는 단위이고, 훅은 특정 이벤트가 일어날 때 지정한 동작을 실행하는 장치입니다. 둘은 역할이 다릅니다. 스킬은 작업 지식을 제공하고, 훅은 도구 실행 전후 같은 시점에 자동화된 처리를 연결할 수 있습니다.
훅으로 일부 도구 호출을 막을 수 있지만, 훅을 하나 설치했다고 전체 시스템의 안전이 보장되지는 않습니다. 어떤 이벤트에서 실행되는지, 실패·시간 초과 시 어떻게 동작하는지, 실제 권한과 샌드박스가 어떻게 설정됐는지 확인해야 합니다.
스킬·서브에이전트·훅·플러그인은 무엇이 다를까?
Claude Code 플러그인 공식 문서는 스킬, 에이전트, 훅 등 확장 기능을 플러그인으로 묶어 공유하는 방식을 설명합니다. 개별 기능을 프로젝트나 사용자 설정으로 관리할 수도 있으며 플러그인이 유일한 공유 방법은 아닙니다.
| 구성 요소 | 역할 | 확인할 질문 |
|---|---|---|
| 스킬 | 특정 작업에 필요한 지침과 자료 제공 | 언제 적용되며 어떤 내용이 전달되는가? |
| 서브에이전트 | 분리된 작업을 수행하도록 구성한 보조 에이전트 | 어떤 도구와 정보에 접근하는가? |
| 훅 | 특정 이벤트에서 명령이나 처리를 실행 | 언제 작동하고 실패하면 어떻게 되는가? |
| 플러그인 | 여러 확장 구성 요소를 묶어 배포·관리 | 출처와 버전, 포함된 실행 코드를 신뢰할 수 있는가? |
예를 들어 팀이 문서 점검 지침과 작업 완료 알림을 함께 배포한다면 스킬과 훅을 플러그인에 담을 수 있습니다. 이 예시는 이해를 돕기 위한 가상 구성입니다. 스킬을 어떻게 작성하고 검증할지는 Claude Code 스킬 설계에서 이어서 살펴볼 수 있습니다.
훅은 언제 실행될까?
훅은 도구 사용 전, 도구 사용 후, 세션 시작 등 지정한 이벤트에 연결됩니다. 공식 훅 가이드는 훅을 사용해 자동 검증이나 후속 처리를 연결하는 방법을 설명합니다.
실행 전과 실행 후의 차이가 중요합니다. PreToolUse는 도구 실행 전에 개입할 수 있지만 PostToolUse는 도구가 실행된 뒤입니다. 실행 후 훅이 문제를 발견해도 이미 일어난 파일 변경이나 외부 요청이 자동으로 취소되는 것은 아닙니다.
종료 코드 2는 언제 차단할까?
Claude Code 훅 참조 문서에 따르면 차단할 수 있는 이벤트에서 명령 훅이 종료 코드 2를 반환하면 해당 동작을 막을 수 있습니다. 예를 들어 PreToolUse의 경우 도구 호출을 차단하고 오류 메시지를 전달할 수 있습니다.
하지만 종료 코드 2의 효과는 이벤트마다 다릅니다. 이미 실행이 끝난 PostToolUse는 그 도구 호출을 되돌릴 수 없고, 일부 이벤트는 같은 방식으로 차단하지 않습니다. 따라서 ‘모든 훅에서 2를 반환하면 모든 작업이 중단된다’고 보면 안 됩니다.
또한 종료 코드 1이나 실행 실패를 항상 무시한다고 단정해서도 안 됩니다. 현재 공식 문서는 이벤트와 onFailure 설정에 따라 오류·시간 초과 처리 방식이 달라질 수 있음을 설명합니다. 사용하는 버전의 문서와 실제 설정을 확인하고 정상·위험·실패·시간 초과 사례를 각각 시험하세요.
훅을 보안 경계로 사용할 때의 한계
훅이 검사하는 입력과 적용되는 도구 범위를 잘못 정하면 예상하지 못한 경로가 남을 수 있습니다. 예를 들어 특정 명령 문자열만 막는 규칙은 다른 프로그램이나 다른 형태의 명령으로 수행되는 동일한 작업을 놓칠 수 있습니다.
중요한 보호는 훅 하나에만 맡기지 말고 파일·네트워크 권한, 샌드박스, 비밀정보 관리, 변경 검토와 백업을 함께 설계하세요. AI 에이전트 로컬 권한 관리에서는 이 통제들이 서로 어떻게 다른지 설명합니다.
플러그인 자체도 실행 코드를 포함할 수 있으므로 출처와 권한을 확인해야 합니다. 팀에 배포하기 전에는 무엇을 설치하고 어떤 이벤트에서 어떤 명령을 실행하는지 검토하고, 버전이 바뀌었을 때도 다시 살펴보세요.
로컬 모델과 함께 쓸 때도 따로 확인하세요
원문은 플러그인과 로컬 모델을 함께 사용하면 외부 전송이 완전히 차단된다고 설명했지만, 로컬 모델을 실행해도 연결된 도구나 로그, 네트워크를 통해 데이터가 이동할 수 있습니다. 플러그인 포장, 모델 실행 위치와 네트워크 차단은 서로 다른 설정입니다.
또한 원문은 로컬 실행 지연의 원인을 특정 캐시 헤더 하나로 단정했습니다. 실제 속도는 모델 크기, 장비 메모리, 실행 엔진, 컨텍스트와 설정에 따라 달라질 수 있으므로 해당 환경에서 측정해야 합니다. 로컬·클라우드 모델 조합에서 데이터 경로와 비용을 확인하는 기준을 볼 수 있습니다.
적용 전에 점검할 것
- 플러그인의 출처·버전과 포함된 스킬·훅의 실행 내용을 확인합니다.
- 막으려는 동작에 실행 전 이벤트가 실제로 적용되는지 시험합니다.
- 정상 동작이 불필요하게 차단되지 않는지와 위험 동작이 막히는지 함께 확인합니다.
- 훅 실행 실패와 시간 초과가 허용·차단 중 어떻게 처리되는지 점검합니다.
- 파일·네트워크 권한과 복구 가능한 백업을 별도로 준비합니다.
자주 묻는 질문
스킬을 플러그인으로 묶으면 보안 규칙이 자동으로 강제되나요?
아닙니다. 스킬은 지침이며 플러그인은 확장 기능을 묶는 방식입니다. 반드시 막아야 하는 행동은 적절한 권한·훅·격리 설정으로 별도 검증해야 합니다.
훅이 종료 코드 2를 반환하면 모든 이벤트가 차단되나요?
아닙니다. 이벤트마다 효과가 다릅니다. 이미 완료된 작업을 실행 후 훅이 되돌리는 것은 아니며 해당 이벤트의 공식 동작을 확인해야 합니다.
훅이 오류로 실행되지 않으면 무조건 안전하게 멈추나요?
설정과 이벤트에 따라 다를 수 있습니다. 실패·시간 초과 처리 방식을 확인하고 실제로 시험하세요.
참고 자료
다음 한 걸음
내 환경에서 막힌 부분은 실행 단계와 함께 질문해 주세요. 바꿔 만든 결과도 함께 나눌 수 있습니다.