[태그:] 자바스크립트 확장

  • Claude Code의 클로드코드 모드 첫걸음 — 80줄로 만드는 안전장치와 맞춤 UI

    Claude Code의 클로드코드 모드 첫걸음 — 80줄로 만드는 안전장치와 맞춤 UI

    핵심 요약

    • mod는 Claude Code 세션 안에서 한 번 로드되어 상주하는 JS/TS 확장으로, 셸 명령 기반의 기존 훅과 달리 상태를 유지하면서 이벤트를 관찰·중재하고 맞춤 UI를 표시할 수 있음
    • 프롬프트 제출, 도구 호출, 턴과 세션의 시작·종료, UI 렌더링 등 다단계 이벤트에 훅을 연결할 수 있으며, 이벤트를 그대로 넘기거나 입력을 수정하거나 직접 처리하는 세 가지 모드를 지원함
    • Claude Code의 AGENTS.md 지원과 /diff 패널도 mod로 구현되어 있어, mod가 단순 부가 기능이 아닌 핵심 UI 컴포넌트의 기반이라는 점이 확인됨

    mod는 단순 테마가 아니라 세션에 상주하면서 이벤트를 관찰·중재하고 UI까지 다시 그릴 수 있는 Claude Code의 ‘두 번째 운영체제 레이어’이며, 핵심은 원하는 동작을 자연어로 묘사하고 $.state에 상태를 두는 것만으로 안전 가드, 비용 표시, 워크플로우 검수를 즉시 추가할 수 있다는 점임

    목차

    Claude Code를 본격적으로 쓰기 시작하면 가장 먼저 부딪히는 불만은 “이 화면을 내 워크플로우에 맞게 조금만 바꿀 수 없을까”입니다. ~/.claude/hooks.json에 셸 스크립트를 걸어 안전장치를 만드는 방식은 익숙하지만, 매번 외부 프로세스를 띄워야 하고 상태를 유지할 방법이 없으며 UI까지 건드릴 수는 없습니다. 바로 그 자리에 들어온 것이 클로드코드 모드(mod)입니다. 2.1.287 버전부터 별도 활성화 없이 기본 지원되며, AGENTS.md와 /diff 패널이 이미 mod로 구현되어 있다는 사실이 그 위상을 잘 보여줍니다.

    개념 정리: 어떤 이벤트를 어디까지 가로챌 수 있는가

    mod는 세션이 살아 있는 동안 한 번 로드되어 상주하는 JS/TS 확장입니다. 프롬프트 제출, 도구 호출, 턴과 세션의 시작·종료, UI 렌더링 같은 다단계 이벤트에 훅을 걸 수 있고, 이벤트를 그대로 흘려보낼지(observe), 입력을 수정해 넘길지(intervene), 아니면 직접 처리해 종료할지(consume) 선택할 수 있습니다. 일반 플러그인과 동일한 manifest와 훅 모듈 구조를 따르지만, 클로드코드 모드만의 결정적 차이는 셸이 아니라 V8 같은 임베디드 런타임 안에서 돌아간다는 점입니다. 덕분에 컨텍스트 사용량을 그래프로 그리고, 위험 명령 실행 직전에 영향 범위를 시각화하고, 변경된 파일을 한 턴 단위로 되짚는 일이 전부 사용자가 만든 작은 모듈로 가능해집니다.

    사례 1: Token Weather — 80줄짜리 컨텍스트 날씨 예보

    약 80줄짜리 Token Weather는 mod가 얼마나 간결할 수 있는지를 보여주는 예시입니다. 모듈은 매 턴의 토큰 사용량을 $.state에 누적하고, 컨텍스트 한도 대비 비율을 날씨로 매핑합니다 — 50% 미만은 맑음, 70% 근처는 흐림, 85%부터 소나기, 95% 이상은 폭풍. 프롬프트 입력란 위에 미니 차트(최근 12턴)와 함께 직전 턴 대비 증감량을 표시하고, 임계치를 넘으면 “/compact를 권장합니다” 같은 안내를 함께 띄웁니다. 상태를 보존하지 못하면 매 핫 리로드마다 차트가 0으로 리셋되는데, 이 함정에 빠지지 않으려면 모듈 변수가 아니라 $.state에 두는 것이 핵심입니다. 필자가 첫 mod를 만들 때 가장 자주 놓친 부분이 바로 이 지점이었습니다.

    사례 2: Blast Radius — 위험 명령 직전의 영향 시각화

    rm -rf, git reset –hard, git push –force, prisma migrate deploy 같은 명령은 실행한 뒤에는 되돌리기 어렵습니다. Blast Radius는 도구 호출 직전에 훅을 걸어 위험 패턴을 식별하고, 그 시점의 git status, 변경 파일 수, 푸시 대상 브랜치 같은 영향을 옆 패널 또는 프롬프트 위 모달로 정리해 보여줍니다. 터미널 폭이 좁아지면 자동으로 상단 배너로 전환되는 반응형 레이아웃도 모듈 안에서 처리합니다. 승인 버튼을 누르기 전에는 도구가 실행되지 않습니다.

    다만 별칭이나 회사 내부 래퍼 스크립트는 문자열 매칭으로 절대 다 잡히지 않습니다. 차단이 필요한 작업은 settings.json의 permissions.allow/deny에 별도로 등록해 두는 편이 안전합니다. Blast Radius는 “주의 환기”까지 책임지고, 차단 자체는 권한 레이어가 맡는 역할 분담이 권장 구성입니다.

    사례 3: Replay Theater — 한 턴의 변경을 단계별로 되짚기

    한 턴 안에서 Edit/Write가 여러 번 호출되면, 어떤 파일이 어떤 순서로 어떻게 바뀌었는지 머릿속으로 따라가기 어렵습니다. Replay Theater는 Edit/Write 이벤트를 가로채 파일명·변경 전·변경 후 스냅샷을 배열에 쌓고, r 또는 /replay를 누르면 단계별 diff 패널을 옆에 띄웁니다. Blast Radius처럼 실행을 막지는 않고, 관찰과 검수에만 집중합니다. 코드 리뷰 문화가 강하지 않은 팀에서 PR 직전 self-review 단계로 쓰면 효과가 큽니다.

    현업에서 가장 흔히 놓치는 함정은 “이벤트 객체에 들어 있는 file_path와 old_content가 비어 있을 수 있다”는 점입니다. Read 이후의 Edit는 old_content가 보장되지 않으므로, 빈 문자열을 그대로 diff 뷰어에 넘기지 않고 플레이스홀더로 표시하는 식의 방어 코드가 필요합니다.

    직접 만들기: 자연어 한 줄로 시작하는 워크플로

    mod를 만드는 절차는 의외로 평범합니다. 빈 폴더에서 claude –plugin-dir ./my-first-mod를 실행해 세션을 띄우고, “프롬프트 위에 컨텍스트 사용량을 그래프로 보여줘”라고 자연어로 설명하면 Claude Code가 manifest와 훅 모듈을 직접 작성합니다. 파일을 저장하는 순간 플러그인이 핫 리로드되어 세션을 재시작하지 않아도 바로 반영됩니다. UI가 보이지 않으면 claude –debug로 로그를 따라가면 어떤 이벤트 단계에서 실패했는지 짚을 수 있습니다.

    작업이 끝났다면 claude plugin validate로 manifest 계약과 타입을 정적으로 검증하고, claude plugin test로 실제 런타임에서 동작을 확인합니다. 릴리스마다 API 시그니처가 조금씩 바뀌기 때문에, .claude-plugin/types/에 그 버전의 타입 선언이 생성된다면 그걸 기준으로 import해서 쓰면 타입 안정성을 확보할 수 있습니다.

    상태 관리와 디버깅: $.state가 답이다

    핫 리로드 이후에도 살아남아야 하는 데이터는 무조건 $.state에 둡니다. 모듈 최상위 변수로 배열을 선언해 두면 reload 순간 GC 대상이 되어 초기화되지만, $.state는 Claude Code 런타임이 명시적으로 보존해주는 영역입니다. 토큰 누적, 최근 변경 이력, 사용자가 고정한 임계치 같은 값은 전부 이쪽으로 모아야 합니다. UI가 아예 그려지지 않는다면 1) manifest의 event 등록 키 오타, 2) 타입 정의 누락으로 인한 require 실패, 3) 모듈 export 누락을 순서대로 확인합니다. 이 세 가지가 실제로 디버깅 시간의 대부분을 차지합니다.

    배포와 보안: 게시자 신뢰가 곧 통제 수단이다

    세션 안에서 만들어진 mod는 기본적으로 그 세션에만 로드됩니다. 계속 쓰려면 ~/.claude/plugins/ 아래 폴더로 복사하거나, GitHub에 마켓플레이스 파일을 함께 두고 등록해 /reload-plugins로 재로드해야 합니다. 일반 플러그인과 같은 워크플로라서 Claude 디렉터리에도 그대로 제출 가능합니다.

    여기서 짚고 넘어가야 할 것이 보안입니다. mod는 게시자 코드가 Claude Code 본체와 동일한 권한으로 사용자 컴퓨터에서 실행됩니다. 사용자 컴퓨터에서 직접 코드가 실행된다는 점은 온디바이스 AI 워크플로에서도 핵심 통제 포인트로 반복되는 사안이라, mod의 권한 모델을 다룰 때도 같은 기준으로 검토하는 것이 안전합니다. Cantina의 apex-flash-1 사례가 보여주듯 신뢰할 수 없는 코드가 임의 권한을 얻는 경로는 정적 분석 한 번으로 막기 어렵습니다. 게시자 신뢰, 소스 검토, 최소 권한 원칙을 항상 병행해야 합니다.

    마무리: 오늘 짜증 난 한 가지 동작부터 감싸자

    클로드코드 모드는 “두 번째 운영체제 레이어”라는 표현이 과장되지 않습니다. 원하는 동작을 자연어로 묘사하고 상태를 $.state에 두는 것만으로 안전 가드, 비용 표시, 워크플로우 검수를 바로 붙일 수 있기 때문입니다. 비용/한도 표시, 팀 규칙 주입, K8s 컨텍스트 확인, Terraform 적용 전 검토 같은 아이디어는 전부 첫 mod를 만든 다음 주말이면 충분합니다. 처음부터 거대한 플러그인을 설계하려 하지 말고, 오늘 짜증 났던 한 가지 동작부터 80줄짜리 모드로 감싸 보는 것이 가장 빠른 길입니다. 더 많은 예제와 시연 영상은 원문 가이드에서 확인할 수 있습니다.

    지금 바로 해볼 것

    • mkdir my-first-mod && cd my-first-mod으로 빈 폴더를 만들고 claude –plugin-dir .로 세션을 띄운 뒤 “프롬프트 위에 컨텍스트 사용량을 그래프로 그려줘”라고 한 줄 요청해 manifest와 훅 모듈이 자동 생성되는지 확인한다.
    • 생성된 훅 모듈에서 누적 카운터를 모듈 변수가 아닌 $.state에 저장하도록 고치고, 파일 저장 직후 핫 리로드로 차트가 0으로 리셋되지 않는지 검증한다.
    • 위험 명령 가드가 필요하면 hooks 모듈에 PreToolUse 훅을 걸어 “rm -rf”·”git push –force”·”prisma migrate deploy” 패턴을 매칭하고, 매칭 결과를 모달로 띄우는 30줄짜리 가이드를 추가한다. 본 차단이 필요하면 settings.json의 permissions.deny에 같은 패턴을 별도 등록한다.
    • claude plugin validate ./my-first-mod로 manifest와 타입 계약을 정적으로 검사하고, claude plugin test ./my-first-mod로 실제 런타임에서 이벤트 흐름이 의도대로 흘러가는지 회귀 테스트를 만든다.
    • 작업이 끝나면 모듈을 ~/.claude/plugins/로 복사하거나 GitHub 마켓플레이스 파일과 함께 등록한 뒤 /reload-plugins로 영구 적용 여부를 확인한다.

    자주 묻는 질문

    기존 hooks.json에 등록한 셸 스크립트와 mod는 어떻게 나눠 쓰나요?

    상태 없이 한 줄짜리 가드(예: 위험 명령 차단, 로그 적재)만 필요하다면 hooks.json의 셸 훅이 가볍고 충분합니다. 세션이 살아 있는 동안 누적된 컨텍스트를 보여주거나, 도구 호출을 중재하거나, UI를 그려야 한다면 mod로 옮기는 편이 낫습니다. 권한 거부는 결국 settings.json의 permissions가 가장 신뢰할 수 있는 레이어라서, 차단 자체는 셸 훅이나 mod가 아니라 권한 규칙에 두는 구성을 권장합니다.

    릴리스마다 API가 바뀔까봐 신규 mod 도입을 망설이는데, 안정적으로 가는 방법이 있나요?

    해당 버전으로 로드했을 때 .claude-plugin/types/에 생성되는 타입 선언을 그대로 import해서 쓰고, 이벤트 이름은 상수로 감싸두면 시그니처가 바뀌는 시점에 컴파일 에러로 즉시 잡힙니다. plugin test로 핵심 이벤트 흐름을 시나리오화해 두면 업그레이드 당일 회귀 여부를 빠르게 가려낼 수 있습니다.

    팀 전체에 표준 mod를 배포하려면 어떤 흐름이 현실적인가요?

    사내 GitHub에 마켓플레이스 파일을 포함한 단일 저장소를 두고, 모듈들은 모두 코드 리뷰를 거치게 합니다. 신규 입사자는 등록 명령 한 줄로 동일 세트를 받을 수 있고, 게시자 신뢰가 코드 리뷰 기록으로 남는다는 점이 mod의 강력한 권한을 상쇄하는 핵심 통제입니다.

    참고 원문

    이 기사는 다음 원문을 확인해 작성했습니다: geeknews — Claude Code 모드(mod) 시작하기