Claude Code Mods 심층 가이드: 개념·사용법·실무 활용과 한계

먼저 정리할 것: /mods는 어떤 기능인가

작업을 맡긴 뒤 터미널을 보고 있어도 정작 궁금한 정보는 흩어져 있다. 문맥을 얼마나 썼는지, 어떤 변경이 이루어졌는지, 지금 기다리는 것이 모델 응답인지 사람의 판단인지 매번 대화를 거슬러 올라가 확인한다. Mods가 겨냥하는 영역은 이런 작업 중의 관찰과 조작이다.

/mods라는 표현으로 찾았다면 먼저 Claude의 Mods 소개 페이지와 Claude Code 안에서 입력하는 명령을 구분하자. 이 글이 다루는 것은 Claude Code Mods다. 일반 Claude 웹 채팅에서 /mods를 입력해 켜는 기능으로 설명하지 않는다. 확인한 공식 관리 명령은 /plugin, 직접 만드는 진입점은 /plugin-authoring이다. 플러그인 명령 문서는 터미널 셸의 claude plugin …과 세션 안의 /plugin도 구별한다.

기준일은 2026년 10월 6일, 예제를 검사한 CLI는 2.1.289다. 기능 설명은 공식 문서에, 실무 판단은 이 글의 분석에, 실행 결과는 첨부한 예제 테스트에 근거한다. 서로 다른 근거를 한꺼번에 “실사용 검증”이라고 부르지 않는다.

Mods의 구조: 모델에게 설명하는 것을 넘어 앱의 동작을 연결한다

공식 개요에 따르면 mod는 이벤트 처리 코드를 담은 플러그인이다. JavaScript 또는 TypeScript 함수가 Claude Code 안에서 실행되며 이벤트를 관찰하거나 변경하고, 직접 응답할 수 있다. Plugin은 배포·설치 단위이고 Mod는 그 안의 기능이다. 모든 플러그인이 mod인 것은 아니다.

예를 들어 “수정한 파일을 마지막에 요약해줘”는 모델에 주는 지시다. 반면 사용자가 기록한 조건과 미해결 질문을 패널에 두고 다음 요청에 한 번 첨부하는 기능은 앱에 추가한 코드다. 전자는 문맥과 모델 판단의 영향을 받고, 후자는 작성한 분기와 상태 관리가 맞는지 검토해야 한다.

다음은 이벤트 처리 구조를 단순화한 그림이다. 여러 mod가 있으면 중간 단계가 이어진다.

프롬프트·도구 호출·화면 그리기 등의 이벤트
        ↓
mod의 처리 함수 ($, e, next)
        ├─ next(e)          → 다음 처리기로 원래 이벤트 전달
        ├─ next({...e, …})  → 바꾼 이벤트 전달
        └─ 결과 직접 반환   → 뒤의 처리를 실행하지 않고 응답

$는 기능을 호출하는 API, e는 이벤트 데이터, next는 다음 처리기다. 도구 호출의 기본 처리에는 권한 확인과 실제 실행이 포함된다. 따라서 반환값을 직접 만드는 코드는 단순한 화면 장식보다 영향이 크다. “실행하지 않았음”을 성공처럼 꾸미면 사용자가 보는 설명과 실제 상태가 벌어질 수 있다.

Skills·Hooks·MCP와 비교하면 무엇을 선택해야 할까

기능 이름보다 문제가 발생하는 위치를 먼저 찾는 편이 낫다. 다음 표는 공식 개요의 구분을 바탕으로 정리한 선택 기준이다.

필요한 변화	먼저 검토할 수단	예시
답변·작업 절차를 반복해서 안내	Skills·프로젝트 지침	리뷰 순서, 문서 작성 형식
특정 이벤트에 스크립트나 검사를 연결	설정 파일의 Hooks	저장 후 포맷 검사
외부 서비스의 자료·도구 제공	MCP	이슈 조회, 사내 자료 검색
진행 중 상태·UI·명령·이벤트 흐름 확장	Mods	문맥 사용량 표시, 변경 검토 패널
여러 확장을 묶어 배포·관리	Plugins	팀에서 쓰는 기능 묶음

가령 “PR 리뷰를 회사 양식으로 작성”하는 문제라면 우선 지침으로 해결해볼 수 있다. “리뷰 도중 CI 상태를 항상 보면서 실패한 검사로 이동”하고 싶다면 연결할 데이터와 UI가 필요해진다. 이때 외부 조회를 담당하는 기능과 화면을 구성하는 mod가 함께 쓰일 수 있다. MCP의 역할은 별도 분석에서 더 자세히 다뤘다.

이 구분은 어느 방식이 더 고급이라는 순위가 아니다. 같은 결과를 얻는다면 유지보수할 코드가 적은 쪽이 유리하다. 사람이 한 번 물으면 될 정보를 보여주려고 상시 폴링과 자동 요약을 모두 붙이는 것은 비용을 늘릴 수 있다.

실제 활용: 공식 예제에서 읽을 수 있는 세 가지 방향

공식 소개에는 Token weather, Blast radius, Replay theater가 나온다. 각각 문맥 사용량을 표시하고, 영향이 큰 명령의 실행 판단을 돕고, 변경을 순서대로 되짚는 예제다. 이 글에서는 해당 예제들을 설치·실행하지 않았다. 아래의 업무 설계는 소개된 기능에서 확장한 분석이다.

1. 상태를 보여주면 다음 행동이 달라지는가

문맥 사용량을 보여주는 패널은 긴 코드 분석에서 유용할 수 있다. 그러나 비율만 커다랗게 표시하면 경고등이 하나 늘어난다. 사용자가 그 정보를 보고 “결정 사항을 짧게 정리하고 다음 조사로 넘어간다”처럼 행동할 수 있어야 가치가 생긴다.

도입 시에는 표시할 숫자와 행동을 짝지어 보자. 문맥 사용량 옆에는 현재 조사 범위, CI 상태 옆에는 대상 커밋과 확인 시각, 작업 기록 옆에는 아직 확인하지 않은 항목을 둔다. 상태의 최신성이 빠지면 오래된 성공 표시가 오히려 판단을 흐릴 수 있다. 문맥 사용량이 곧 답변 정확도라는 의미도 아니다.

2. 승인 횟수보다 판단에 필요한 정보를 줄인다

명령을 실행할지 물어보는 창 자체는 새롭지 않다. 가치가 있는 부분은 사람이 판단하기 전에 변경 대상과 되돌릴 방법을 이해하도록 돕는 것이다. 배포 준비 업무라면 환경·버전·변경 범위를 한곳에 보여주는 구성을 생각할 수 있다.

다만 확인창을 붙였다고 모든 실행 경로를 통제하는 것은 아니다. 문자열 패턴으로 명령을 찾는 구현은 다른 표기나 래퍼 스크립트를 놓칠 수 있다. 기능의 목적을 “실수를 줄이는 보조 UI”로 둘지, “강제 정책”으로 둘지 처음부터 구분해야 테스트도 맞게 설계할 수 있다.

3. 수정의 양보다 검토의 순서를 바꾼다

변경 재생은 코드를 처음 보는 사람의 이해를 돕는다. 인증 로직·테스트·문서를 어떤 순서로 바꿨는지 따라가면 최종 diff만 볼 때 놓치는 가정을 발견할 수 있다. 동시에 기록된 편집 순서가 논리적 설명 순서와 같지는 않다. 중간에 되돌린 수정도 있기 때문이다.

따라서 변경 이력을 읽은 뒤에는 최종 diff와 요구사항을 다시 연결해야 한다. “Replay를 끝까지 봄”보다 “요구사항별 최종 변경과 테스트를 확인함”을 검토 완료 조건으로 삼는 편이 낫다. 에이전트의 가치가 작업 완료와 복구 비용에 달려 있다는 제품 관점의 분석과도 연결된다.

업무별로 작게 시작하는 설계안

아래는 구현 완료된 제품 목록이 아니라 직접 만들 때 사용할 설계안이다.

업무	첫 mod의 범위	도입 효과를 확인할 질문
레거시 코드 분석	읽기·수정·셸 호출 기록 조회	같은 자료를 반복해서 찾는 이유를 파악하는가?
PR 검토	현재 커밋의 검사 상태를 요청 시 조회	다른 창으로 이동하는 횟수와 상태 오독이 줄어드는가?
데이터 분석	데이터 버전·가정·미확인 항목 표시	그래프 작성 후 빠진 조건을 발견하는가?
기술 문서 작성	용어·독자·완료 기준을 고정해 표시	긴 작업에서 작성 기준이 바뀌는 것을 줄이는가?
팀 온보딩	자주 쓰는 확인 명령과 설명 제공	신규 구성원이 명령의 의미까지 이해하는가?

UI는 Pane·AbovePrompt 같은 확장 지점에 붙인다. 터미널과 Desktop에서 같은 요소가 모두 지원되는 것은 아니며, 그리는 함수만 작성해도 패널이 저절로 열리는 것은 아니다. 기능을 늘리기 전에 좁은 창에서도 핵심 정보가 남는지 확인할 필요가 있다.

Claude Code UI 지도: 어디에 무엇을 보여줘야 할까

좋은 mod는 정보를 더 많이 보여주는 것에서 끝나지 않는다. 지금 읽어야 할 정보, 계속 비교할 정보, 잠깐 확인하고 잊어도 될 정보를 다른 자리에 둔다. 예를 들어 복사 완료 메시지와 복구 방법을 결정하는 질문이 같은 크기의 패널을 차지할 필요는 없다.

아래 그림은 공식 렌더링 지점을 바탕으로 직접 그린 설명용 구성도다. 실제 앱의 스크린샷이나 하나의 mod가 만든 완성 화면은 아니다. 창 크기에 따라 달라지는 배치를 이해하기 위한 지도이며, 그림 속 문구도 배치 설명용 예시다.

A~F 영역별 정보 배치 기준

아래의 위치·API 이름은 공식 문서를 따르며, 추천 정보와 피할 배치는 이 글의 설계 판단이다. 알림 API는 렌더링 지점 이름과 구별해 표기했다. UI 레퍼런스 · 알림 API

영역	대응하는 기능	두기 좋은 정보	피할 배치
A. 대화·도구 결과	UserMessage, AssistantMessage, ToolUse, ToolResult, CommandOutput	특정 파일 수정·도구 실행에 딸린 결과, 명령으로 요청한 보고서	현재 상태를 매초 새 대화 행으로 쌓기
B. 상세 패널	Pane	diff, 체크리스트, 조건·가정·질문, 선택·복사 버튼	단순 완료 알림마다 큰 패널을 자동으로 열기
C. 입력창 위 요약 띠	AbovePrompt	문맥 상태, 미해결 항목 수, 다음 행동으로 가는 짧은 안내	긴 원문·전체 로그·수십 개 버튼
D. 진행 표시	Spinner, ToolProgress	지금 하는 일, 기다리는 이유, 측정할 수 있는 작업 진척	알 수 없는 남은 시간이나 성공률을 표시
E. 입력창 아래 상태	$.ui.status 알림 API, 별도 지점인 SessionMode·PromptHint	조회 실패처럼 해결 전까지 남겨둘 상태, 모드·입력 안내	장문의 판단 근거를 한 줄에 압축
F. 일시 알림	$.ui.toast 알림 API	복사 완료, 새 결과 도착, 패널 준비됨	읽지 않으면 위험한 경고나 유일한 오류 설명

E의 기능들을 하나의 API로 생각하면 안 된다. $.ui.status는 mod 이름과 경고 표식이 붙는 지속 메시지이고, SessionMode와 PromptHint는 기존 UI의 서로 다른 지점이다. 기존 statusLine 설정과도 별개의 방식이다. ToolProgress처럼 터미널에만 있는 지점도 있으므로 Desktop까지 지원하려면 레퍼런스의 환경별 표를 확인한다.

넓은 창의 옆 패널과 좁은 창의 위 패널은 같은 Pane이다

Pane은 넓은 전체화면 터미널에서 대화 옆에 붙을 수 있고, 그 밖의 배치에서는 입력창 위의 상자로 나타난다. AbovePrompt도 입력창 위에 있지만 별도의 공유 공간이다. 따라서 “화면 아래쪽에 보인다”는 이유만으로 둘을 같은 기능으로 보면 안 된다. 배치 규칙

레이아웃을 설계할 때는 “오른쪽 사이드바를 만들어줘”보다 “넓은 창에서는 비교하며 읽고, 좁은 창에서는 위쪽 패널에서 스크롤할 상세 목록을 만들어줘”라는 요구가 정확하다. 좌우 배치를 고정해 생각하면 좁은 창에서 표가 잘리거나 버튼이 읽기 흐름을 밀어낸다.

키보드 사용도 포함해야 한다. 패널에 초점을 옮겨 Tab·Enter로 조작할 수 있는지, Esc로 빠져나올 수 있는지, 입력 중인 프롬프트를 갑자기 가리지 않는지 확인한다. 이 글의 보드는 사용자가 /handoff를 입력할 때 패널을 열고, Esc로 닫을 수 있게 만들었다.

실제 사례 1: Token Weather는 왜 입력창 바로 위에 있을까

Anthropic의 Token Weather는 문맥 사용량과 최근 변화량을 입력창 위 한 줄에 표시한다. 공식 글에서 동작 화면과 제작 과정을 볼 수 있다. Token Weather 사례

이 정보를 보는 순간은 보통 “다음 자료를 더 넣을까, 지금까지의 결정을 정리할까”를 판단할 때다. 그래서 다음 요청을 입력하는 곳 가까이에 두는 배치가 자연스럽다. 상태를 확인하려고 별도 패널을 열 필요도 없다.

이 원리를 다른 업무에 적용하면 보고서 작성에는 “출처 미확인 항목”, 데이터 분석에는 “현재 데이터 버전”, 배포 준비에는 “현재 대상 환경”을 짧게 둘 수 있다. 이는 추가 설계 예시다. 상태가 바뀌었다면 확인 시점도 함께 보여줘야 오래된 정보가 현재 사실처럼 읽히지 않는다.

실제 사례 2: Replay Theater는 요약과 상세를 나눈다

Replay Theater는 턴이 끝나면 입력창 위에 안내를 내고, 사용자가 열면 Pane에서 편집 내용을 단계별 diff와 이동 버튼으로 보여준다. 공식 사례에는 넓은 전체화면 배치와 80열 창의 위쪽 배치가 함께 나온다. Replay Theater 동작 화면

여기에는 두 단계가 있다. 요약 띠는 “검토할 변경이 있다”는 사실을 알려주고, 패널은 “어떤 변경인지 비교한다”는 일을 맡는다. 모든 diff를 요약 띠에 넣으면 다음 프롬프트를 쓰는 공간을 빼앗는다. 반대로 검토할 항목이 있다는 표시조차 숨겨두면 사용자가 패널을 열 이유를 알 수 없다.

PR 검토 도구를 설계한다면 같은 원리를 쓸 수 있다. 띠에는 미검토 항목 수와 열기 동작, 패널에는 파일별 변경·요구사항·검사 근거를 둔다. “검사 결과 없음”과 “검사 통과”는 문구와 상태를 구분한다. 초록색 하나로 둘을 합치면 UI가 잘못된 확신을 준다.

실제 사례 3: Blast Radius는 결정에 필요한 근거를 곁에 둔다

Blast Radius는 위험할 수 있는 명령을 대기시키고 영향 범위와 진행·취소 선택지를 보여주는 공식 예제다. 패널 배치가 안 되는 경우 요약 띠 쪽에 보고서를 표시하는 대체 경로도 소개한다. Blast Radius 사례

이 사례에서 배울 것은 경고창의 크기보다 근거와 결정을 가깝게 둔다는 점이다. 버튼만 남기고 대상 파일·환경·예상 변경을 다른 화면으로 보내면 사용자는 기억에 의존해 선택한다. 수량이 많을 때는 요약과 상세 목록을 분리하되, 상세를 다시 확인할 길은 남겨둬야 한다.

이런 mod의 질문 UI를 Claude Code의 기본 권한 확인창과 혼동하면 안 된다. 권한 확인창은 mod가 바꿀 수 있는 렌더링 지점이 아니다. AskUserQuestion은 별도의 질문 UI다. 예쁜 확인 화면을 만들었다는 것과 실제 권한 정책을 강제했다는 것은 다른 주장이다. 기존 UI의 변경 범위

위 세 공식 예제는 공개된 설명과 시연을 분석했다. 이번 글에서 직접 실행한 예제는 아래의 Handoff board다.

실제 사례 4: 인수인계 보드는 어떤 정보를 어디에 뒀나

이 글의 Handoff board 0.1.0은 실제로 Pane을 사용한다. 기능을 쉽게 추적할 수 있도록 목표부터 다음 세션으로 넘기는 동작까지 한 패널 안에 두었다.

패널 안 위치	현재 예제의 내용	이렇게 둔 이유
맨 위	목표	항목을 읽기 전에 이번 작업의 기준을 확인
목표 바로 아래	메모리 보관 안내·한 번 첨부 예약 상태	저장됐다는 오해와 의도하지 않은 문맥 전달을 줄임
목록 앞	미해결 질문 입력	방금 발견한 의문을 목록에 바로 추가
본문	조건·가정·질문과 항목별 처리 버튼	항목과 그 항목에 적용할 행동을 붙여 둠
목록 뒤	한 번 첨부·인수인계 복사	전체 내용을 확인한 다음 실행
마지막	조작 결과·실패 안내	복사 실패 등을 패널에서 다시 확인

후속 버전에서 개선한다면 C 영역에는 “미해결 질문 수·첨부 예약 여부·보드 열기”만 두고 B 영역의 상세 목록으로 연결할 수 있다. 단, 현재 다운로드하는 0.1.0에는 이 요약 띠 기능이 없다. 이 배치는 개선 설계이며 구현 완료 목록이 아니다.

UI를 추가하기 전에 확인할 다섯 가지

1. 정보의 수명: 순간 피드백인가, 해결 전까지 남아야 하는 상태인가? 복사 성공은 짧게, 복사 실패의 복구 방법은 다시 찾을 수 있게 둔다.
2. 정보의 소속: 특정 실행 결과인가, 작업 전체의 상태인가? 파일별 오류는 해당 결과나 상세 패널에 붙인다.
3. 사용자의 다음 행동: 보고 끝나는가, 비교·선택해야 하는가? 비교할 자료와 버튼을 가까이 둔다.
4. 좁은 창과 다른 확장: 패널이 위로 이동해도 읽을 수 있는가? 공유하는 AbovePrompt에서 뒤의 mod가 그린 내용을 보존하는가?
5. 사람에게 보이기와 모델에 전달하기: 화면 표시만으로 모델이 내용을 읽는다고 가정하지 않는다. Handoff board는 표시와 attach를 분리했다.

마지막 기준은 특히 중요하다. 화면을 채우는 것과 Claude에게 문맥을 보내는 것은 서로 다른 동작이다. UI 설계에는 무엇을 어디에 보여줄지뿐 아니라 누가 읽는 정보이며 어떤 시점에 모델로 보낼지까지 포함돼야 한다.

사용 전 확인: 버전·앱·입력 위치

공식 지원 범위 기준으로 터미널은 Claude Code 2.1.287 이상, Desktop Code는 내장 Claude Code 2.1.286 이상에서 Mods를 사용할 수 있다. 이 글의 실제 검사는 터미널 CLI 2.1.289에서 했다.

사용하는 환경	이벤트 처리	mod UI
터미널·에디터 안의 통합 터미널	지원	지원
Desktop의 로컬 Code 세션	지원	지원, 일부 요소 차이
VS Code 확장의 채팅 화면	지원	미지원
claude -p·Agent SDK	지원	미지원
Desktop의 WSL 세션	플러그인 미지원	미지원

먼저 운영체제 터미널에서 버전을 확인한다.

claude --version
claude plugin --help

그다음 Claude Code 세션 안에서는 /plugin을 열어 활성 mod를 확인한다. 터미널의 claude --version과 Desktop의 내장 버전은 같다고 가정하지 말자. Desktop에서는 Code 세션의 /status로 확인한다.

초기 실험 안내에서 사용하던 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS는 2.1.287 이상에서 무시된다. 0으로 설정하는 방식은 비활성화 방법이 아니다. 끄는 방법은 아래의 복구 절차를 따른다.

시작하는 두 경로: 만들어 달라고 요청하기, 검토한 코드를 불러오기

Claude에게 만들게 할 때

제작 안내에 따라 /plugin-authoring을 호출하거나 원하는 mod를 자연어로 요청할 수 있다. 요청은 “편리한 대시보드”보다 데이터·동작·실패 조건을 명시하는 편이 낫다. 예를 들면 다음과 같다. 아래는 제작 요청 예시이며 완성된 기능이 아니다.

현재 작업의 검토 항목을 보여주는 Claude Code mod를 만들어줘.
사용자가 직접 입력한 항목만 메모리에 보관하고,
항목별 완료 표시는 사용자가 선택하게 해줘.
파일·네트워크·모델 호출 없이 시작해줘.
세션을 다시 열면 목록이 유지되지 않는다는 점을 화면에 표시하고,
추가·완료·초기화와 잘못된 입력의 테스트도 작성해줘.

생성된 코드는 세션별 ~/.claude/dev-mods/…에 들어간다. 자동 다시 불러오기를 승인한 뒤 확인하고, 계속 보관할 것은 별도 폴더로 복사해야 한다. Not now는 영구 차단이 아니다. 파일이 남아 있으면 해당 세션을 다시 시작할 때 로드될 수 있다는 점이 현재 문서에 명시돼 있다. 실행하지 않을 코드는 해당 mod 폴더를 제거해야 한다.

로컬 폴더를 검토하고 한 세션에서 써볼 때

로컬 로드에는 마켓플레이스 등록이 필요 없다. 먼저 파일을 읽고, 아래처럼 검사한 뒤 시작한다. 여기서 ./handoff-board는 다음 절의 다운로드를 풀어 얻는 폴더다.

claude plugin validate ./handoff-board
claude plugin test ./handoff-board
claude --plugin-dir ./handoff-board

--plugin-dir는 그 세션에 불러오는 방법이다. 여러 사람에게 계속 배포하려면 마켓플레이스 관리가 별도로 필요하다. 등록된 마켓플레이스의 플러그인 설치 형식은 claude plugin install 이름@마켓플레이스이며 이 한글 표기는 실제 이름으로 바꿔야 한다. 외부 셸에서 설치·갱신한 내용을 열린 세션에 반영하려면 /reload-plugins를 쓴다. 명령·로드 범위 근거

직접 써볼 예제: 대화가 길어져도 판단을 잃지 않는 인수인계 보드

AI와 한 시간 동안 기능을 검토했다고 하자. 처음에는 “기존 사용자의 로그인은 유지”가 조건이었다. 중간에는 “모든 고객 기기가 패스키를 지원한다”는 확인되지 않은 가정이 나왔다. 마지막에는 휴대폰 분실 후 복구 방법이 미해결로 남았다. 이 셋을 단순히 “결정 사항”으로 요약하면 조건·추측·미해결 문제가 같은 사실처럼 다음 작업으로 넘어갈 수 있다.

이 문제를 다루려고 Handoff board 0.1.0을 직접 만들었다. 대화를 자동으로 요약하는 대신 사용자가 중요한 항목을 분류해 붙잡아 두는 작은 작업 보드다. 기술 기획, 구현, 자료 조사에 같은 방식으로 쓸 수 있다.

인수인계 보드 ZIP 다운로드 · 실행 검증 기록

보드가 하는 네 가지 일

• 조건과 가정을 분리한다. 유지할 조건은 keep, 확인 전 가정은 assume, 남은 질문은 ask로 입력한다.
• 작업 옆에 보여준다. /handoff로 패널을 열어 목록을 보고 질문을 추가하거나 직접 처리 표시를 한다.
• 필요한 순간 한 번만 상기시킨다. attach를 선택하면 다음 프롬프트에 보드 내용을 첨부한다. 그다음 요청에는 자동으로 반복하지 않는다.
• 다음 세션으로 가져갈 메모를 만든다. copy로 분류된 인수인계 문서를 복사하거나 export로 출력한다. 별도 요약 모델은 부르지 않는다.

패널의 항목을 읽는 것만으로 Claude가 모두 기억하도록 만들지는 않는다. 사람에게 보여주기와 모델에 전달하기를 구분한 것이 이 예제의 핵심이다. attach를 선택해야 다음 요청의 추가 문맥에 들어가며, cancel로 취소할 수 있다. 보드 내용을 자동으로 발송하거나 새 대화를 시작하지 않는다.

실습 1: 패스키 도입 검토에서 가정을 사실로 넘기지 않기

ZIP을 풀면 handoff-board 폴더가 나온다. 파일을 살펴본 다음 운영체제 터미널에서 검사하고 세션을 시작한다.

claude plugin validate ./handoff-board
claude plugin test ./handoff-board
claude --plugin-dir ./handoff-board

이후 명령은 Claude Code 세션 안에서 한 줄씩 입력한다. 아래의 기기 지원 문장은 일부러 검증하지 않은 가정으로 적은 예시이며 사실 주장이나 도입 권고가 아니다.

/handoff goal 기존 계정의 로그인 경로를 보존하며 패스키 도입 검토
/handoff keep 기존 비밀번호 로그인은 제거하지 않는다
/handoff assume 고객의 모든 기기가 패스키를 지원한다
/handoff ask 휴대폰 분실 후 복구 경로는 무엇인가?
/handoff

패널에는 #1 유지할 조건, #2 미검증 가정, #3 미해결 질문이 나뉘어 표시된다. 좁은 터미널에서는 일부만 보일 수 있다. 패널에 초점을 옮긴 뒤 아래로 스크롤하거나 창을 넓혀 나머지 항목을 확인한다. 패널을 닫아도 메모리는 유지되며 명령으로 다시 열 수 있다.

구현을 시작하기 전에 다음 순서로 현재 판단을 다시 전달한다.

/handoff attach
지금 구현하지 말고, 지원 기기 범위와 복구 경로를 먼저 검토해줘.

두 번째 줄은 실제 모델에 보내는 요청이므로 자신의 사용량을 소비한다. mod는 사용자가 쓴 요청 문장을 바꾸지 않고, 이미 존재하는 추가 문맥 뒤에 보드 내용을 붙인다. “모든 기기 지원”을 미검증 가정으로 표시한 상태로 전달한다. 이것이 답변 품질을 보장하지는 않지만, 적어도 넘기는 메모의 상태를 사용자가 통제할 수 있다.

복구 문제를 직접 확인했다면 /handoff done 3으로 처리 표시한다. 잘못 표시했다면 /handoff reopen 3으로 되돌린다. 처리 표시는 사용자의 기록이며 mod가 자료나 코드를 검사해서 내린 판정은 아니다. 실제 복구 설계의 쟁점은 패스키 심층 분석도 참고할 수 있다.

실습 2: 기술 보고서의 전제와 조사 공백을 다음 날로 넘기기

같은 보드를 GPU 비용 비교 보고서에도 쓸 수 있다. 예를 들어 다음처럼 기록한다. 새 연습을 시작하려면 먼저 기존 보드를 내보내고 /handoff reset CONFIRM으로 비운다.

/handoff goal 두 GPU 운영안의 비용 비교 보고서 작성
/handoff keep 가격은 확인 날짜·통화·지역을 함께 기록
/handoff assume 두 운영안의 처리량이 같다고 가정
/handoff ask 유휴 시간과 데이터 전송 비용이 포함됐는가?
/handoff copy

다음 세션에 복사한 메모를 붙여넣으면 목표·조건·가정·질문을 구분한 문서로 넘어간다. 모델에게 대화 전체를 다시 요약시키는 과정은 없다. 복사가 지원되지 않거나 실패하면 /handoff export로 텍스트를 출력해 가져갈 수 있다.

여기서 중요한 것은 “처리량이 같다”는 전제가 조사 과정에서 어느새 확정 사실이 되는 일을 줄이는 것이다. 실제 수치와 출처는 별도 문서에 남겨야 한다. 이 보드는 근거 자료를 대신 저장하거나 가정의 참·거짓을 판단하지 않는다.

명령을 다시 찾을 때 보는 표

명령	하는 일
/handoff	패널 열기
/handoff goal 내용	목표 설정·교체
/handoff keep 내용	유지할 조건 추가
/handoff assume 내용	미검증 가정 추가
/handoff ask 내용	미해결 질문 추가
/handoff done 번호 · reopen 번호	처리 표시·취소
/handoff attach · cancel	다음 프롬프트 한 번 첨부·취소
/handoff copy · export	인수인계 복사·텍스트 출력
/handoff reset CONFIRM	메모와 첨부 예약 초기화

항목은 최대 30개, 각 내용은 500자까지다. 데이터를 메모리에만 보관하므로 모듈 재로딩·프로세스 종료 전에 내보내야 한다. 자동 영구 저장, 복사한 메모의 보드 자동 복원, 여러 세션 간 동기화는 제공하지 않는다. 새 세션에 붙여넣는 것은 모델에 메모를 전달하는 것이며 보드 데이터 가져오기 기능은 아니다.

추가 문맥으로 첨부하거나 export한 내용은 대화에 들어간다. 입력한 메모가 비공개 저장소에만 머무른다고 생각하면 안 된다. 첨부 예약은 사용자 입력만을 골라내지 않고 다음 prompt.submit 이벤트에 적용되므로, 자동 프롬프트를 보내는 다른 mod와 함께 쓴다면 예약 시점을 주의해야 한다.

구현에서 눈여겨볼 부분

ZIP에는 아래 원본 파일과 README·라이선스를 담았다. 별도 npm 패키지나 예제 전용 API 키는 필요 없다.

handoff-board/
├── .claude-plugin/plugin.json
├── hooks/hooks.json
├── hooks/register.js
├── tests/board.test.ts
├── README.md
└── LICENSE

hooks.json의 modules는 ./register.js를 가리킨다. 경로 기준은 플러그인 루트가 아니라 hooks.json이 있는 폴더다. 형식과 이벤트 목록은 Mods 레퍼런스를 따른다.

다음은 한 번 첨부하는 핵심 부분이다. packet()은 모델이 만든 요약이 아니라 입력 항목을 구획에 맞게 조합한 문자열이다.

on('prompt.submit', async ($, e, next) => {
  if (!armed) return next(e);
  const result = await next({
    ...e,
    context: [...(e.context ?? []), packet()]
  });
  if (result.drop === undefined) {
    armed = false;
    notice = '인수인계를 한 번 첨부했습니다.';
    $.ui.invalidate('ui.render');
  }
  return result;
});

이 설계는 매 요청에 같은 메모를 무조건 덧붙이지 않고, 사람이 필요한 시점을 선택하게 한다. 앞선 추가 문맥을 보존하고, 다른 처리기가 요청을 중단했다면 첨부 예약을 유지한다. 작은 기능이어도 이런 실패·조합 조건이 실제 사용감을 좌우한다.

무엇을 실제로 검증했는가

macOS arm64, Claude Code 2.1.289에서 정적 검사와 공식 테스트 실행기를 실행했다. validate는 통과했고, 이 mod의 API 호출 목록에는 명령 등록과 UI 표시·복사만 나타났다. 파일·네트워크·추가 모델 호출 코드는 없다. 프롬프트에 메모를 첨부하는 기능은 별도의 prompt.submit 이벤트 처리로 구현했다. 정적 목록이 안전성 인증인 것은 아니다.

공식 테스트 실행기에서는 14 pass, 0 fail을 확인했다. 주요 검증 범위는 다음과 같다.

검증 영역	실제 확인한 동작
명령과 메모	등록·패널 열기·종류별 구분·처리 취소
잘못된 입력	빈 입력·길이·번호 검사, 30개 한도
문맥 첨부	기존 문맥 보존, 한 번만 첨부, 중단 시 예약 유지·취소
복사·초기화	복사 성공·실패 분기, 명시적 초기화 토큰
UI 모의 검사	터미널·Desktop 요소 트리에서 입력·버튼 조작
다른 확장과의 공존	다른 패널의 그리기를 가로채지 않음

자동 테스트의 UI 검사는 요소 트리와 이벤트를 확인한다. 실제 앱의 픽셀이나 모든 운영체제의 클립보드를 검사하는 것은 아니다. 별도로 실제 터미널 세션에서 목표·조건·가정·질문 입력, 패널 표시, 처리 표시, 인수인계 텍스트 출력까지 확인했다. 모델에 요청을 보내 효과를 비교하는 실험, 실제 Desktop 화면, 실제 클립보드 전송은 이번 검증 범위에 포함하지 않았다.

더 발전시키면 유용할 세 가지 사례

아래는 추가로 설계할 수 있는 아이디어이며 다운로드 예제에 구현한 기능은 아니다. 입력·결과·주의할 점을 먼저 정리하면 Claude에게 제작을 요청하기도 쉬워진다.

아이디어	어떻게 쓰나	설계에서 놓치면 안 되는 점
근거의 유효기간 보드	가격·지원 버전·출처 확인일을 붙이고 보고서 내보내기 전에 오래된 항목을 표시	날짜 경과는 재확인 신호일 뿐, 내용이 틀렸다는 판정이 아님
실험 갈림길 비교판	A안·B안의 가정, 기대 결과, 실제 관측을 나란히 두고 다음 실험을 선택	예상치와 관측치를 별도 필드로 보관. 실패한 실험도 남김
검토 공백 지도	PR의 변경 파일을 요구사항·테스트 근거와 연결해 연결이 없는 부분을 표시	테스트 파일 존재와 통과를 구분. 코드 실행·결과 파싱은 별도 구현

예를 들어 “검토 공백 지도”를 만든다면 첫 버전은 파일명과 사용자가 연결한 요구사항만 보여줄 수 있다. 그다음 신뢰할 수 있는 테스트 결과를 읽고, 마지막에 필요한 부분만 모델에게 설명시키는 순서로 확장한다. 처음부터 자동 합격 판정까지 넣는 것보다 어느 단계가 유용한지 판단하기 쉽다.

비용과 신뢰: 화면 확장도 실행 코드다

작은 명령이 항상 모델을 부르는 것은 아니다. Handoff board의 메모 정리는 코드만 실행한다. 다만 첨부한 메모는 이후 요청의 문맥을 늘린다. 반면 자동 요약을 위해 $.model.complete나 대화 문맥을 사용하는 $.model.fork를 추가하면 사용자의 플랜 또는 API 사용량을 소비한다. Mods API 문서

예를 들어 매 턴 요약을 만들기로 했다면, 비용을 판단할 항목은 실행 빈도 × 호출당 문맥량 × 사용하는 모델이다. 실제 금액을 측정하지 않았으므로 절감률을 제시할 수는 없다. 먼저 필요할 때 누르는 명령으로 시작하고, 반복 사용이 확인된 뒤 자동화하는 방식이 합리적이다. 실패 시 재시도가 또 다른 요약을 부르는 순환도 살펴야 한다.

권한은 더 신중히 봐야 한다. Mods는 사용자 권한으로 실행되며, mod가 시작한 프로세스는 Claude의 Bash sandbox와 같은 보호를 받는다고 볼 수 없다. 환경변수·파일·네트워크를 다루는 코드는 그 범위를 읽고 결정해야 한다. 공식 신뢰 경계

또한 권한 문서는 mod의 tool.check가 일부 승인 결정을 바꿀 수 있음을 설명한다. 관리 설정이 있거나 Team·Enterprise로 로그인한 환경에서는 deny 규칙이 기본적으로 우선하지만, 그 밖의 환경까지 동일한 보호를 가정할 수 없다. “내 설정에 금지 규칙이 있으니 어떤 mod도 문제없다”는 결론은 성립하지 않는다.

차단 기능을 만든다면 오류 시 동작도 중요하다. 이벤트 문서에 따르면 next를 호출하기 전에 실패한 hook은 기본적으로 건너뛸 수 있다. 차단 의도라면 실패 시 거절하도록 처리하는 설계가 필요하다. 그마저 Git 서버의 브랜치 보호나 배포 서비스의 권한을 대체하지 않는다.

팀에서는 개별 사용자에게 금지 문구를 적어 주는 것과 정책을 배포하는 것을 구별해야 한다. 조직 관리 문서의 allowManagedModsOnly는 내장 guard의 관리 설정에 두는 옵션이다. 일반 사용자 설정에 같은 이름을 적는다고 조직 정책이 되는 것이 아니다. 검토할 코드 버전·배포 경로·업데이트 책임자를 함께 정해야 한다.

안 될 때 확인하는 순서와 끄는 방법

실패 원인을 찾을 때는 무조건 환경변수를 추가하기보다 명령·로드·이벤트·UI 순으로 좁혀 보자. 다음 표는 공식 문제 해결 문서에 근거한다.

증상	우선 확인
plugin test 명령이 없음	claude --version, 현재 CLI의 plugin --help
검사 성공인데 hooks:가 없음	hooks/hooks.json의 modules 키와 경로
/plugin 활성 목록에 없음	신뢰 확인, 비활성 설정, 조직 정책, debug 로그의 로드 거부 이유
명령은 등록됐지만 답이 없음	command.run의 이름 일치와 hook 오류
UI만 보이지 않음	해당 앱의 UI 지원, 패널을 여는 코드, 렌더링 오류
업데이트가 반영되지 않음	열린 세션에서 /reload-plugins 실행 여부

로그가 필요하면 claude --debug로 실행해 mod 이름과 hook skipped, not loaded 같은 메시지를 찾는다. 공유 전에는 프롬프트·경로·비밀정보가 포함됐는지 먼저 확인한다.

하나만 끄려면 /plugin의 Installed에서 해당 플러그인을 비활성화하거나 제거한다. 설치한 확장들을 한 세션에서 배제해 원인을 비교할 때는 claude --safe-mode를 사용할 수 있으나, 다른 사용자 설정도 함께 제한된다. 사용자 설정의 disableAllHooks는 Hooks·상태줄 등에도 영향을 주며 조직 관리 대상은 남을 수 있다. 내장 기능까지 모두 끈다는 뜻으로 해석해서는 안 된다. 비활성화 범위

도입 판단: 나만의 Claude Code가 실제로 더 나은가

평가는 화려한 패널 수가 아니라 반복해서 겪는 불편 하나가 줄었는가로 시작하면 된다. 다음 순서는 이 글에서 제안하는 소규모 도입 방법이다.

1. 문제 하나를 고른다. 예: 긴 작업에서 미검증 가정과 결정 사항이 뒤섞인다.
2. 정보만 보여준다. 자동 승인·외부 쓰기·자동 모델 호출은 필요가 확인된 뒤 별도로 설계한다.
3. 비교할 작업을 정한다. 비슷한 과제에서 mod 사용 전후의 확인 시간·놓친 항목·오탐을 기록한다.
4. 실패 조건을 시험한다. 자료 없음, 오래된 상태, 중단, 초기화, 로드 실패, 다른 확장과의 충돌을 포함한다.
5. 유지 책임을 정한다. CLI 갱신 시 다시 검사할 사람과 되돌릴 버전을 남긴다.

Mods의 가장 큰 가능성은 Claude Code를 각자의 업무에 맞는 작업 화면으로 바꾸는 데 있다. 효과가 큰 기능은 대개 모델에게 더 많은 일을 시키기 전에 사람이 현재 상태를 더 정확히 이해하도록 돕는다. 그렇게 얻은 이해가 다음 행동을 바꿀 때, 확장은 장식 이상의 가치를 갖는다.

자주 묻는 질문

/mods를 입력하면 시작할 수 있나?

이 글에서 확인한 공식 시작 경로는 /plugin과 /plugin-authoring이다. /mods를 모든 Claude 환경의 기본 명령으로 가정하지 말고, 사용 중인 Claude Code의 명령 목록을 확인하자.

코딩을 못해도 만들 수 있나?

자연어로 제작을 요청할 수 있다. 다만 완성된 파일은 실행 코드이므로 어떤 자료를 읽고 어떤 동작을 하는지 확인할 필요가 있다. 처음에는 저장·통신 없이 상태를 보여주는 작은 기능이 이해하기 쉽다.

Mods를 설치하면 모델 성능이 올라가나?

모델 자체의 성능 향상을 보장하지 않는다. 정보 제시와 작업 흐름을 개선할 수 있다는 것이 핵심이다. 이 글에서도 생산성이나 정확도 향상률은 측정하지 않았다.

테스트가 통과하면 바로 팀에 배포해도 되나?

첨부 테스트가 확인한 것은 제한된 이벤트와 응답이다. 실제 앱·권한·다른 플러그인·업데이트 환경에서 별도 확인이 필요하다. 먼저 소수 사용자의 반복 업무에 적용해 가치와 유지 비용을 함께 살펴보자.