Claude Code 모드 시작하기

Claude Code의 동작과 UI를 바꾸는 JavaScript/TypeScript 확장인 모드(mod) 로, 세션 안에서 이벤트를 관찰하고 도구 실행에 개입하거나 맞춤 패널을 표시할 수 있음
원하는 기능을 자연어로 요청해 모드를 만들 수 있으며 , 핫 리로드로 세션을 재시작하지 않고 수정 결과를 확인할 수 있음
약 80줄의 Token Weather 예제는 컨텍스트 사용량을 날씨와 작은 차트로 표시하며, 매 턴 자동으로 갱신됨
Blast Radius 는 위험한 명령이 실행되기 전 영향을 보여주고 승인을 받으며, Replay Theater 는 직전 턴의 파일 변경을 하나씩 살펴보게 함
Claude Code 2.1.287 이상 에서 기본 지원하며 일반 플러그인처럼 설치·공유함. Claude Code와 같은 접근 권한으로 실행되므로 신뢰할 수 있는 모드만 설치해야 함
모드로 Claude Code의 동작과 화면 바꾸기
모드(mod) 는 Claude Code 세션 안에서 실행되는 JavaScript/TypeScript 확장으로, 설정이나 스킬보다 깊게 동작과 UI를 바꿀 수 있음
자주 확인하는 정보를 표시하거나, 특정 명령 앞에 확인 절차를 두거나, 원하는 방식의 변경 검토 화면을 만들 수 있음
터미널과 데스크톱 앱에서 맞춤 UI를 표시할 수 있음
기존 설정 훅은 이벤트마다 셸 명령을 실행하지만, 모드는 한 번 로드된 뒤 세션에 상주 함
상태를 유지하면서 이벤트에 따라 화면을 갱신하고, 패널을 열거나 슬래시 명령과 모델이 사용할 도구를 등록할 수 있음
프롬프트 제출, 도구 호출, 턴과 세션의 시작·종료, UI 렌더링 등의 이벤트에 훅을 연결함
이벤트를 그대로 넘기며 관찰하거나, 입력을 수정하거나, 기본 동작 대신 직접 처리할 수 있음
Claude Code의 AGENTS.md 지원과 /diff

패널 도 모드로 구현되어 있음
테스트를 포함한 소스는 공개 저장소 의 mods/

에서 확인할 수 있음
원하는 기능을 자연어로 요청하기
claude

를 실행하고 원하는 모드를 자연어로 설명 하면 Claude Code가 구현할 수 있음
핫 리로드를 허용하면 턴이 끝날 때 모드가 나타나며, 이후 수정도 세션을 재시작하지 않고 확인할 수 있음
“컨텍스트 사용량을 프롬프트 위에 표시해줘”, “끝에 달러 비용도 추가해줘”처럼 결과를 설명하고 반복해서 다듬을 수 있음
이렇게 만든 모드는 해당 세션에만 로드되고 폴더도 나중에 정리되므로, 계속 사용하려면 별도로 복사해 플러그인으로 설치 해야 함
Token Weather: 컨텍스트 사용량을 날씨로 표시하기
약 80줄의 코드 로 프롬프트 위에 컨텍스트 사용률, 사용 토큰 수, 최근 12턴의 작은 차트와 직전 턴 대비 증감을 표시함
사용량이 늘면 맑음, 흐림, 소나기, 폭풍으로 표시가 바뀌고, 창이 거의 차면 압축이 필요하다는 신호를 보여줌
세션 시작과 매 턴 종료 후 사용량을 읽어 표시줄을 자동으로 갱신 함
기록을 모듈 변수 대신 $.state

에 저장해 핫 리로드 이후에도 유지함
화면 너비가 부족하면 차트와 증감 표시를 생략함
Blast Radius: 위험한 명령의 영향을 먼저 확인하기
파일 삭제, Git 변경 폐기, 강제 푸시, 데이터베이스 마이그레이션 같은 명령을 실행 전에 보류하고 영향 범위를 표시 함
삭제할 파일이나 버릴 변경 사항 등을 확인한 뒤 진행하거나 취소할 수 있음
취소하면 Claude에 이유를 포함한 거부 결과를 반환함
Git 상태 조회와 시험 실행 등 도구 자체의 기능 을 사용해 영향 보고서를 만듦
터미널이 넓으면 옆 패널에, 좁으면 프롬프트 위에 표시함
안전망이지 권한 시스템은 아님
명령 문자열을 검사하므로 별칭이나 내부에서 삭제 명령을 실행하는 스크립트 등은 놓칠 수 있음
반드시 차단해야 하는 작업은 별도의 권한 규칙으로 제한해야 함
Replay Theater: 한 턴의 파일 변경을 차례로 살펴보기
턴이 진행되는 동안 Edit와 Write 호출의 파일명과 변경 전후 내용 을 기록함
턴이 끝나면 r

또는 /replay

로 검토 패널을 열 수 있음
번호가 붙은 단계와 이전·다음 버튼으로 변경 사항을 하나씩 확인함
파일 수정을 차단하거나 바꾸지 않고 관찰만 함
화면이 넓으면 오른쪽에 패널을 열고, 좁으면 프롬프트 위에 표시함
직접 개발하고 검증하기
Claude Code 2.1.287 이상 에서 기본 지원하며, 별도의 활성화 설정은 필요 없음
일반 플러그인 폴더에 매니페스트와 훅 모듈을 두고, 이벤트별 동작을 등록하는 구조임
claude --plugin-dir ./token-weather

로 로드하면 파일을 저장할 때마다 모듈을 다시 불러옴
API는 릴리스마다 바뀔 수 있으므로, 로드 시 생성되는 .claude-plugin/types/

의 타입 선언 을 해당 버전의 기준으로 사용해야 함
claude plugin validate

로 구조와 타입 계약을 확인하고, claude plugin test

로 실제 Claude Code 런타임에서 테스트할 수 있음
핫 리로드 이후에도 필요한 데이터는 $.state

에 보관하고, UI가 나타나지 않으면 claude --debug

로그로 원인을 확인함
설치·공유와 활용 아이디어
일반 플러그인과 같은 방식으로 설치하고 공유 함
마켓플레이스 파일을 포함한 GitHub 저장소를 등록하고, 플러그인을 설치한 뒤 /reload-plugins

로 불러올 수 있음
모드가 포함된 플러그인은 Claude 디렉터리 에도 제출할 수 있음
모드는 게시자가 작성한 코드이며 사용자 컴퓨터에서 Claude Code와 같은 접근 권한으로 실행 됨
패키지를 설치할 때처럼 저장소를 확인하고 신뢰하는 게시자의 모드만 설치해야 함
비용과 사용 한도 표시, 프롬프트에 팀 규칙 추가, 읽은 파일을 보여주는 패널, 긴 작업의 완료 알림 등을 만들 수 있음
운영 환경의 Kubernetes 컨텍스트 확인이나 Terraform 적용 전 검토처럼 자체 기술 스택에 맞춘 확인 절차 도 추가할 수 있음
댓글과 토론