Claude Code 모드가 생겼습니다: 해커톤 세션이 길어질수록 차오르는 컨텍스트를 프롬프트 위 한 줄 계기판으로 먼저 봅니다 | DAKER 커뮤니티

해커톤에서 Claude Code를 몇 시간씩 띄워 두면 두 가지를 자주 놓칩니다. 지금 컨텍스트가 얼마나 찼는지, 그리고 방금 응답에서 어떤 파일이 바뀌었는지입니다. Anthropic의 Claude 채널이 10월 5일 올린 3분 21초짜리 영상 Mods in Claude Code: change how Claude Code works는 이 불편을 사용자가 직접 고치는 기능인 모드(mods)를 소개합니다. 결론부터 말하면 모드는 Claude Code 세션 안에서 실행되는 작은 JavaScript·TypeScript 파일이고, 화면에 그려지는 내용과 프롬프트에 들어가는 내용, 모델이 부르는 도구 호출까지 바꿀 수 있습니다. 대회 참가자가 오늘 해 볼 만한 첫 작업은 프롬프트 바로 위에 컨텍스트 사용량을 보여 주는 한 줄짜리 계기판입니다.

터미널 프롬프트 위 날씨 아이콘 게이지를 바라보는 개발자를 그린 만화풍 생성 이미지와 제목 Claude Code 모드로 컨텍스트를 눈으로 봅니다
설명용 생성 이미지입니다.

Claude Code 모드는 플러그인 안에 들어간 미들웨어입니다

영상에서 Anthropic의 Lydia는 모드를 따로 배우는 새 형식이 아니라 기존 플러그인의 연장으로 설명합니다. 같은 plugin.json, 같은 hooks.json을 쓰되 hooks.json에 modules라는 키가 하나 더 붙고, 이 키가 가리키는 TypeScript 파일이 실제 모드라는 설명입니다. 10월 1일 claude.dev 블로그에 올라온 공식 가이드 Getting started with Claude Code mods도 같은 구조를 보여 줍니다. 모듈은 register(on, options)를 내보내고, 그 안에서 on(event, matcher, hook)으로 이벤트마다 함수를 붙입니다.

모든 함수는 같은 세 값을 받습니다. 첫째 $는 Claude Code와 대화하는 통로로, UI 그리기, 모델 호출, 파일 읽기가 모두 여기에 모여 있습니다. 둘째 e는 지금 일어나는 이벤트의 데이터입니다. 셋째 next는 이벤트를 다음 플러그인과 Claude Code 본래 동작으로 넘기는 함수입니다. 영상은 이를 웹 개발자에게 익숙한 비유로 정리합니다.

Express를 써 봤다면, 모드는 Claude Code 안에 내장된 미들웨어와 거의 같습니다.

Claude Code에는 도구 호출, 권한 확인, 메시지 처리, 프롬프트 전송 같은 내부 이벤트가 수십 개 있고, 등록한 함수는 해당 이벤트가 발생할 때마다 Claude Code 자신의 처리 직전에 실행됩니다. 공식 가이드는 이벤트 범위를 도구 호출, 제출된 프롬프트, 응답의 시작과 끝, 세션의 시작과 끝, 슬래시 명령, 그리고 화면의 각 부분이 그려질 때 발생하는 ui.render로 정리합니다.

훅 하나로 할 수 있는 일은 관찰, 고쳐 쓰기, 직접 답하기 세 가지입니다

공식 가이드는 훅의 동작을 세 갈래로 나눕니다. 대회 중에 어떤 모드를 만들지 고를 때 이 구분부터 정해 두면 설계가 단순해집니다.

동작방법가이드가 든 예
관찰next(e)를 먼저 기다린 뒤 결과를 살펴봅니다파일 수정을 모두 기록하거나 응답이 끝날 때마다 수치를 읽습니다
고쳐 쓰기바꾼 이벤트를 next에 넘깁니다나머지 처리 과정이 보게 될 명령을 더 안전한 명령으로 바꿉니다
직접 답하기next를 부르지 않고 deny 같은 값을 돌려줍니다도구 호출을 거절하거나 명령·도구를 모드가 직접 처리합니다

영상의 표현대로 next에 넘긴 값이 곧 Claude Code가 실제로 하는 일입니다. 명령을 바꿔서 넘기면 바뀐 명령이 실행되고, next를 부르지 않고 직접 값을 돌려주면 Claude Code는 자기 처리 대신 그 답을 받아들입니다. 모드는 DOM도 Node도 없는 별도 샌드박스에서 실행되므로 바깥과의 모든 연결은 $를 거칩니다.

기존 설정 훅과의 차이도 분명합니다. 설정 훅은 이벤트마다 셸 명령을 실행하고 표준 입출력으로 JSON을 주고받습니다. 모드는 한 번 불러오면 세션 내내 남아 있으므로 상태를 유지할 수 있고, 이벤트에 맞춰 갱신되는 UI를 그리며, 옆 패널을 열거나 프로세스를 실행하거나 슬래시 명령과 모델이 부를 수 있는 도구를 등록할 수 있습니다. 가이드에 따르면 AGENTS.md 지원과 대화 옆에 뜨는 /diff 패널처럼 Claude Code 자체 기능 일부도 모드로 만들어져 있고, 그 소스와 테스트는 공개 저장소 anthropics/claude-code의 mods 폴더에서 읽을 수 있습니다.

영상 속 세 가지 모드는 모두 작은 불편 하나에서 출발합니다

영상 앞부분에서 소개하는 모드는 세 가지입니다. 첫째는 컨텍스트가 어떻게 채워지고 있는지 프롬프트 바로 위에 실시간으로 보여 주는 모드입니다. 둘째는 실행 중인 에이전트만이 아니라 프로젝트의 모든 에이전트를 옆 패널에 나열하고, 클릭 한 번으로 새로 시작하게 해 주는 모드입니다. 셋째는 화면 녹화를 할 때 이메일 주소가 보이지 않도록, 마우스를 올렸을 때만 주소를 드러내는 모드입니다.

영상 후반부는 이메일 모드를 처음부터 만듭니다. 응답을 화면에 그리는 render 이벤트에 함수를 등록하고, 화면에 나가기 직전의 응답 텍스트에서 이메일 주소마다 마우스를 올려야 보이는 블록을 만든 뒤, next를 부르지 않고 그 결과를 돌려줍니다. 그러면 Claude Code는 모드가 만든 버전을 그립니다. 흥미로운 대목은 그다음입니다. 이메일을 숨긴 상태에서 Claude에게 메시지 작성을 부탁해도 Claude는 실제 주소를 그대로 사용합니다.

화면에 그리는 단계를 바꾼 모드는 사용자에게 보이는 것만 바꾸고, 모델이 보는 내용은 바꾸지 않습니다.

대회 참가자에게 이 점은 양쪽으로 의미가 있습니다. 시연 영상을 녹화하거나 발표 중에 화면을 공유할 때 개인 정보가 덜 노출되도록 다듬을 수 있습니다. 반대로 화면에서 가렸다고 해서 모델에게서 정보를 숨긴 것은 아니므로, 민감한 키나 개인 정보를 모델에 넘기지 않는 문제는 따로 다뤄야 합니다.

공식 가이드의 첫 예제 Token Weather는 약 80줄입니다

공식 가이드가 빈 폴더에서부터 만드는 첫 모드는 Token Weather입니다. 응답이 끝날 때마다 컨텍스트 창이 얼마나 찼는지 읽어서 프롬프트 위에 한 줄로 그립니다. 날씨 아이콘, 사용 비율, 전체 창 대비 사용 토큰 수, 최근 기록의 작은 막대 그래프, 직전 응답이 늘린 양이 한 줄에 들어갑니다. 가이드는 이 모드의 길이를 약 80줄로 소개합니다.

컨텍스트 사용 비율표시
25% 미만☀ Clear
25~49%☁ Cloudy
50~74%☂ Showers
75~89%☇ Storm
90% 이상↯ Compact soon

가이드의 실제 세션 예시에서는 200k 창을 쓰는 세션이 세 번의 응답 동안 18%, 67%, 81%로 차오르며 표시가 Clear에서 Showers, Storm으로 바뀝니다. 수치는 $.session.usage()에서 읽으며, 상태 표시줄과 같은 값을 돌려줍니다. 가이드는 이 호출이 세부 내역을 요청할 때만 토큰 계산 요청을 보낸다고 설명합니다.

만드는 과정에서 기억할 점은 세 가지입니다. 먼저 Claude Code 2.1.287 이상이 필요하고, 모드는 기본으로 켜져 있어 따로 설정할 것이 없습니다. 다음으로 기록은 모듈 변수가 아니라 $.state에 두어야 합니다. 파일을 저장할 때마다 모듈이 새로 불러와지면서 모듈 변수는 초기화되지만, $.state에 둔 값은 세션 동안 유지됩니다. 마지막으로 claude plugin validate가 매니페스트와 모듈 소스를 읽어 어떤 이벤트에 훅을 걸고 무엇을 호출하는지 보고하며, claude plugin test로 테스트 파일을 실제 Claude Code 런타임에서 돌릴 수 있습니다.

대회 마감 주간에 쓸모 있는 모드는 위험 명령 확인과 수정 되돌려 보기입니다

가이드는 Token Weather 뒤에 두 개의 큰 모드를 더 보여 줍니다. Blast Radius는 Claude가 Bash로 rm -rf, git reset --hard, git clean, 강제 푸시, 데이터베이스 마이그레이션을 부를 때 실행을 멈추고, 그 명령이 무엇을 건드릴지 계산한 뒤 Proceed와 Cancel 버튼이 있는 패널을 띄웁니다. 가이드의 녹화 예시에서는 rm -rf build를 붙잡아 지워질 파일 9개, 1.1MB를 먼저 보여 줍니다. 제출 직전에 결과 파일이나 학습 산출물을 실수로 지우는 일을 막는 데 바로 쓸 수 있는 형태입니다.

다만 가이드는 이 모드의 한계도 함께 적어 둡니다. 명령 문자열을 읽는 방식이라 $(…) 치환, 별칭, rm을 부르는 스크립트는 걸러지지 않습니다.

Blast Radius는 안전망일 뿐 권한 시스템이 아니므로, 확실하게 막아야 하는 명령은 권한 규칙으로 막아야 합니다.

Replay Theater는 응답 하나가 진행되는 동안 일어난 Edit와 Write 호출을 모두 기록해 두었다가, 응답이 끝난 뒤 r 키나 /replay 명령으로 수정 내역을 하나씩 넘겨 보게 해 줍니다. 수정을 막거나 바꾸지 않고 관찰만 하는 모드입니다. 여러 파일에 걸친 리팩터링 뒤 제출 코드를 다시 확인할 때 diff를 한 단계씩 따라가는 용도로 쓸 수 있습니다.

오늘 해 볼 한 가지는 컨텍스트 계기판을 Claude에게 만들게 하는 일입니다

공식 가이드가 권하는 지름길은 API를 먼저 공부하지 않고 원하는 모드를 Claude에게 설명하는 방식입니다. Claude Code가 모드 작성법을 알고 있으므로, 무엇을 보고 싶은지만 적으면 됩니다. 순서는 다음과 같습니다.

  1. 터미널에서 claude --version을 실행해 2.1.287 이상인지 확인합니다.
  2. claude로 세션을 열고, 프롬프트 위에 컨텍스트 사용 비율과 사용 토큰 수, 최근 기록 그래프, 직전 응답이 늘린 양을 한 줄로 보여 주는 모드를 만들어 달라고 요청합니다. 가이드의 원래 프롬프트도 보여 줄 항목을 한 줄씩 적는 형태입니다.
  3. 세션 중 핫 리로드를 켤지 한 번 묻는데, 허용하면 응답이 끝날 때 계기판이 나타납니다. 이후에는 경고 기준을 70%로 낮추는 식으로 말로 고쳐도 그 자리에서 바뀝니다.
  4. 이렇게 만든 모드는 해당 세션에서만 불러와지고 폴더도 나중에 정리되므로, 계속 쓰려면 폴더를 밖으로 복사해 일반 플러그인처럼 설치합니다.

팀으로 대회에 나간다면 이 모드를 마켓플레이스 파일이 있는 저장소에 넣어 두는 방법도 있습니다. 가이드는 /plugin marketplace add, /plugin install, /reload-plugins 세 명령으로 설치할 수 있다고 안내합니다. 팀원 모두가 같은 계기판을 보면 긴 세션을 정리할 시점을 맞추기도 쉬워집니다.

남이 만든 모드를 설치하기 전에 저장소부터 읽어야 합니다

모드는 내 컴퓨터에서 Claude Code와 같은 권한으로 실행되는 코드이고, Anthropic이 아니라 배포한 사람이 작성한 코드입니다. 공식 가이드도 패키지를 설치할 때처럼 저장소를 먼저 읽고 믿을 수 있는 사람의 모드만 설치하라고 당부합니다. 또 모드 API는 릴리스마다 바뀔 수 있으며, Claude Code가 모드를 불러올 때마다 .claude-plugin/types/ 폴더에 써 주는 타입 선언이 해당 버전의 기준이라고 밝힙니다. 대회 도중 Claude Code를 업데이트했다면 직접 만든 모드가 여전히 검증을 통과하는지 claude plugin validate로 한 번 확인해 두는 편이 안전합니다.

출처

가이드는 세 모드가 각각 질문 하나에서 나왔다고 말합니다. 컨텍스트가 얼마나 찼는지, 이 명령이 무엇을 지우려는지, Claude가 방금 무엇을 바꿨는지입니다. 여러분이 대회 중 Claude Code를 쓰면서 가장 자주 확인하고 싶었던 것은 무엇입니까? 만들고 싶은 모드가 있다면 댓글로 아이디어를 남겨 주시면 반갑겠습니다.