Claude Code에 '긴급 정지'와 '위험 명령어 차단' 기능을 추가한 플러그인 제작 (표준 라이브러리만 사용)

Claude Code에게 작업을 맡기다 보면, '지금은 멈추고 싶다'라는 순간이 있습니다. 저의 경우 예약 게시나 상품 공개 등 외부로 쓰기(쓰기 작업)를 맡기고 있기 때문에, 멈추고 싶을 때 확실히 멈출 수 있는 메커니즘이 필요하게 되었습니다.

그래서 Claude Code의 **훅(Hook)**인 PreToolUse / PostToolUse를 사용해서, 쓰기 관련 도구 호출에 가드레일을 거는 플러그인을 만들었습니다. 파이썬 표준 라이브러리만으로 구성된 단일 스크립트입니다.

기능

적용 대상은 Bash・Write・Edit・MultiEdit・NotebookEdit (무언가를 변경하는 호출)입니다.

• 긴급 정지(Emergency Stop): 프로젝트에 .claude/STOP 파일을 두면 모든 쓰기 작업이 멈춥니다 (~/.claude/STOP의 경우 전체 프로젝트, 환경 변수 AGENT_STOP=1도 가능). - 위험 명령어 차단: main으로 force-push, rm -rf ~, curl ... | sh, DROP DATABASE, git reset --hard origin/main, chmod -R 777 등을 막습니다. - 일일 호출 횟수 제한: 예를 들어 '게시물 스크립트는 하루 2회까지'와 같이 프로젝트별로 설정할 수 있습니다. - 기록(Logging): 실행 전에 attempt, 후에 done을 .claude/guardrails/ledger.jsonl에 기록합니다. done이 없는 attempt는 '완료 여부를 알 수 없는 호출'이므로, 재실행 전에 확인할 수 있습니다.

작동을 멈춘 이유도 Claude 측에 표시되며, '의도된 작업이라면 사용자에게 설정 변경을 요청하도록'이라는 메시지도 함께 전달합니다.

설치

Claude Code에서 다음 두 줄을 실행합니다.

/plugin marketplace add neuralalpha-ai/agent-guardrails
/plugin install agent-guardrails@neuralalpha

python3가 PATH에 있어야 합니다 (Windows의 경우 python만 있다면, 훅이 실패하여 '막지 않는' 쪽으로 작동합니다).

설정 (선택 사항)

프로젝트의 .claude/guardrails.json에 작성합니다.

{
"allow_ids": ["curl-pipe-shell"],
"deny": [
...

설계 시 유의한 점

• 설정 파일이 손상되었을 때도 멈추도록: JSON 작성 오류로 규칙이 조용히 무효화되는 것이 가장 위험하므로, 읽을 수 없는 설정은 '차단'하도록 했습니다. - 가드레일 자체의 예상치 못한 에러는 막지 않음: 반대로 스크립트 버그로 세션 전체가 멈추는 것도 곤란하므로, 그 외의 내부 오류는 통과시키고 기록에만 남깁니다. - 막는 것은 사람이 해제: /agent-guardrails:stop-agent off를 요청해도 Claude는 STOP 파일을 지울 수 없습니다 (쓰기가 차단되어 있으므로). 해제는 사람의 조작에 맡겼습니다.

한계점

이것은 'Claude Code의 도구 호출'에 대한 가드레일입니다. cron이나 CI, 자신의 봇처럼 Claude Code 외부에서 실행되는 스크립트는 관찰하지 않습니다. 해당 경우에는 스크립트 자체에 동일한 메커니즘(기록장・긴급 정지・횟수 제한)을 구현해야 합니다. 그 아이디어는 이전 글에 작성했습니다.

무인으로 쓰기를 시키기 전 체크 항목 (25개 항목・한국어・PDF)은 무료로 배포하고 있습니다.

스크립트 측의 기록장(1파일)은 여기입니다.

Discussion