Claude Code Mod가 '에러 없이 아무것도 그려지지 않을' 때 확인해야 할 3가지 지점

원문 발행 2026. 10. 13. 02:50원문 언어 일본어AI 한국어 번역Zenn AI 원문 보기

요약

Claude Code Mods 작성 시 에러 없이 아무런 반응이 없을 때 확인해야 할 세 가지 주요 원인과 해결책을 제시합니다. 플러그인 전체 로딩 실패, 후크 작동 오류, 구성 요소 규칙 위반 등 각 단계별로 발생 가능한 문제점과 수정 방법을 상세히 안내합니다.

핵심 포인트

플러그인 전체가 읽히지 않으면 정적 검사(Static Inspection) 문제를 확인하세요.
후크는 Node/브라우저 환경이 아닌 특수 환경에서 작동하므로, `process`나 `setTimeout` 사용에 주의해야 합니다.
구성 요소 규칙 위반 시에는 `undefined`나 `false`를 전달했는지 점검하고 필수 항목을 채워야 합니다.

Claude Code의 Mods를 작성하면서 가장 많은 시간을 소모한 부분은 에러는 발생하지 않는데 아무 일도 일어나지 않는 경우였습니다. 배너(帯)도, 필드(欄)도 표시되지 않고 로그에도 눈에 띄는 것이 없습니다.

데스크톱 앱(Code 탭)에서 9가지 기능을 담은 플러그인을 구동하기까지, 이 '조용히 사라지는' 현상의 원인이 3가지로 나뉜다는 것을 알게 되었습니다. 위에서부터 확인하는 것이 빠릅니다.

확인한 버전: Claude Code 2.1.286~2.1.288 (2026년 10월, Windows).

요약표

증상	확인할 곳	흔한 원인
플러그인 전체가 읽히지 않음	1. 정적 검사(Static Inspection)	`$`를 변수에 할당했거나, 다른 파일의 함수에 전달했거나, 동적 import 사용
읽혔으나, 후크(Hook)가 작동하지 않음	2. 실행 환경 (Execution Environment)	`process`나 `setTimeout`이 없거나, 10초를 초과함
후크는 작동하나, 원래 표시 그대로임	3. 구성 요소의 규칙 (Component Rules)	`undefined`나 `false`를 전달했거나, 필수 항목이 없음

1. 정적 검사에 걸리는 경우

로딩 시 모듈 소스가 검사되는데, 여기서 문제가 생기면 플러그인 전체가 읽히지 않습니다.

잘못된 작성법	수정 방법
`const s = $.store; s.get(k)`	`$.store.get(k)`와 같이 한 번에 작성하기
`const { store } = $`	분할 할당하지 않기
`helper($)` (`helper`가 다른 파일일 경우)	`$`를 전달할 수 있는 것은 같은 파일의 가장 바깥 함수뿐입니다.
`on(eventName, ...)` (이름이 변수인 경우)	이벤트 이름은 문자열 그대로 작성해야 합니다.
`await import('./x.mjs')`	동적 import는 사용할 수 없습니다.
플러그인 외부 파일을 import	플러그인 안에 포함시키기

놓치기 쉬운 점이 2가지 있습니다.

검사는 import한 대상 파일에서 이루어집니다. 공통 부품에 임시로 작성했던 on()도 추적됩니다.
해당 버전에 없는 이벤트를 등록하면, Mod 전체가 읽히지 않습니다. ui.fault는 데스크톱에 기본 포함된 2.1.286 버전에는 없고, 단말기의 새로운 버전에서 작동하던 Mod가 데스크톱에서는 사라졌습니다.

같은 이벤트/같은 매처 조합을 2번 등록하는 것도 문제가 됩니다. 여러 기능이 AbovePrompt를 사용하고 싶다면, 한 번만 등록하고 내부에서 분기 처리해야 합니다.

먼저 claude plugin validate .을 실행하는 것이 첫 번째 단계입니다.

2. 후크의 실행 환경에 없는 것을 사용하는 경우

후크는 Node도 브라우저도 아닌 환경에서 작동합니다.

없는 것: :process, :setTimeout, :setInterval, :Buffer, :DOM`
있는 것: :AbortController, :TextEncoder/:TextDecoder (utf-8만), :URL, :atob/:btoa, :structuredClone, :crypto, :performance

자신의 코드는 $.clock.sleep(ms)나 $.clock.every(...)로 바꿔주면 됩니다. 곤란한 것은 npm 부품을 포함했을 때인데, 로딩 순간에 process.env를 읽으려다 실패하여 Mod 전체가 조용히 사라집니다. 그 부품 파일의 맨 위에 해당 환경에서만 작동하는 대체 코드를 넣으니 통했습니다.

const process = { env: {} }
const setTimeout = () => 0

또 하나는 시간입니다. 후크는 1회당 최대 10초이며, 이를 초과하면 건너뜁니다. 허가 감시자(tool.check)에서 무거운 처리를 하면, 감시자가 그냥 지나갑니다.

3. 반환된 트리가 구성 요소의 규칙에 맞지 않는 경우

ui.render가 반환한 트리가 규칙에 맞지 않으면, Claude Code는 에러를 내지 않고 자체적으로 표시를 그립니다. 이 배너(帯)가 사라지고 원래 상태로 돌아가는 것뿐이라 가장 알아차리기 어렵습니다.

작성 방식	결과
値が `undefined` 인 항목을 전달하는 경우	맞지 않게 처리될 수 있음
`autoFocus: false` ・`focus: false`
예외 ( `true`만 전달하거나 생략)	`Button`의 `plain: false`
데스크톱에서 그려지지 않는 경우 (`true`이거나 생략)	`Svg`에 `source` 또는 `alt`가 없음
그려지지 않음 (둘 다 필수)	`Client`의 props에 `undefined`
맞지 않음 (JSON 값만)

조건부 항목을 작성하면 undefined가 자연스럽게 섞이기 때문에, 부품을 만드는 함수를 한 곳에서 감싸서 처리하고 있습니다.

// 값이 없는 항목은 부품에 전달하지 않음
function strip(raw) {
const out = {}
...

`e.surface`

덧붙여: 면의 판별은 $.ui.resolve(e)
표는 모든 부품 이름으로 채워져 있기 때문에, t.Svg가 있는지 여부만으로는 단말기인지 데스크톱인지를 구별할 수 없습니다. e.surface ('terminal' 또는 'desktop')로 구분합니다. Svg는 데스크톱에서만, Raster는 단말기에서만 사용됩니다.

요약

claude plugin validate .로 정적 검사 -
process ・setTimeout과 10초 -
undefined ・false ・필수 항목

제가 걸린 '아무것도 안 나오는' 경우는 전부 이 세 가지 중 하나였습니다.

데스크톱 버전에서 제대로 그려지는 공개 Mod는 modscode의 도감에 코드와 함께 재현된 화면과 함께 나열되어 있습니다. 작동하는 예제 코드를 읽는 것이 가장 빠릅니다.

데스크톱 버전에서 걸린 함정은 Zenn의 본 Claude에게 시세를 파악하게 하고, 매매를 시키게 하는 ― 데스크톱 버전 Claude Code의 Mods로 AI 트레이드 화면을 만든 실전 기록에 32개가 모여 있습니다 (1~2장 무료).

Discussion

AI 자동 생성 콘텐츠

원문 바로가기