Claude Code Mods 쓰기 전 확인할 것, 2.1.287보다 낮으면 아무 일도 일어나지 않는다

Mod를 올렸는데 화면에 아무 변화가 없다면, 코드보다 먼저 볼 곳이 있습니다. 버전입니다.

Mod는 Claude Code 터미널판 2.1.287부터 기본으로 켜져 있습니다. 그보다 낮은 판에서는 오류도 안 나고 그냥 조용히 아무 일도 일어나지 않습니다. 이번 편에서는 Mod를 쓰기 전에 확인할 네 가지를 실제 화면으로 순서대로 보겠습니다.

실습 환경: Windows 11, PowerShell, Claude Code 2.1.296, 2026-10-11 확인.

1. 버전부터 확인한다

셸에서 한 줄이면 됩니다.

claude --version

claude --version 결과. 2.1.287 이상이면 Mod를 쓸 수 있다

제 PC는 2.1.296이라 조건을 넘습니다. 숫자가 2.1.287보다 낮다면 Claude Code를 먼저 업데이트하세요.

데스크톱 앱의 Code 탭을 쓰는 분은 기준이 조금 다릅니다. 데스크톱 앱은 자기 안에 Claude Code를 따로 들고 있고, 2.1.286부터 Mod가 동작합니다. 확인은 Code 탭의 로컬 세션에서 /status를 입력하고 Claude Code 줄의 버전을 보면 됩니다.

어디서 쓰나	최소 버전	확인 방법
터미널(claude)	2.1.287	claude --version
데스크톱 앱 Code 탭	2.1.286	세션에서 /status

얼리 액세스 때 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS 환경변수를 넣어 둔 분은 지우는 게 좋습니다. 2.1.287부터는 이 값을 읽지 않아서, 0으로 둬도 Mod가 꺼지지 않습니다.

2. 처음 여는 폴더에서는 신뢰 확인부터 나온다

Mod와 직접 상관은 없지만, 처음 실습 폴더를 만들고 claude를 실행하면 이 화면에서 한 번 멈춥니다.

새 폴더에서 claude를 처음 실행하면 나오는 신뢰 확인 화면

기본 선택이 No, exit로 되어 있습니다. 내가 만든 폴더라면 아래 화살표로 Yes, I trust this folder를 고르고 Enter를 누릅니다. 이 폴더 안에서 Claude Code가 파일을 읽고 고치고 실행할 수 있게 된다는 확인입니다.

남에게 받은 저장소라면 여기서 바로 Yes를 누르지 말고 안을 먼저 훑어보세요. 3편에서 다루겠지만, 폴더 안에 Mod나 훅이 들어 있으면 그 코드도 내 권한으로 돌게 됩니다.

3. 내장 Mod는 이미 돌고 있다

Mod를 하나도 설치하지 않았어도, Claude Code 기능 일부는 이미 Mod로 만들어져 있습니다. /plugin을 입력하고 Tab으로 Installed 탭에 간 뒤, 검색칸에 cc-plugin을 치면 내장 Mod만 추려 볼 수 있습니다.

/plugin → Installed 탭에서 cc-plugin 검색. 내장 Mod 다섯 개가 보인다

제 화면에는 다섯 개가 나왔습니다. 공식 문서 설명과 맞춰 보면 이렇습니다.

이름	하는 일
cc-plugin-agents-md	AGENTS.md 파일을 프로젝트 지시문으로 읽어 들인다
cc-plugin-diff	/diff 명령과 그 패널을 맡는다
cc-plugin-plugin-authoring	Claude가 Mod를 만들 때 쓰는 스킬을 준다(Mod 코드는 없음)
cc-plugin-telemetry	Claude Code와 내장 Mod의 사용 통계를 보낸다
cc-plugin-you-should-know	긴 작업 중 놓치기 쉬운 것을 프롬프트 위에 알려 준다(기본 꺼짐)

마지막 you-should-know는 기본으로 꺼져 있어서 동그라미가 비어 있습니다. 5편에서 이걸 켜서 실제로 무엇을 알려 주는지 보겠습니다.

4. 내가 올린 Mod가 실렸는지는 한 줄로 본다

1편에서 만든 first-mod를 --plugin-dir로 올린 세션에서 /plugin을 열면, 탭 바로 아래에 흐린 글씨로 한 줄이 생깁니다.

탭 아래 「1 mod active · first-mod」. 내가 올린 Mod가 실렸다는 뜻

1 mod active · first-mod. 실린 Mod 개수와 이름입니다. 내장 Mod는 여기 세지 않습니다. 분명히 설치했는데 이름이 안 보인다면 그 Mod는 로드되지 않은 것이고, 원인은 9편(설치·삭제·오류 해결)에서 다룹니다.

Mod를 끄는 방법도 미리 알아 두자

문제가 생겼을 때 바로 끌 수 있어야 마음 편히 시험해 볼 수 있습니다. 범위별로 셋입니다.

끄는 범위	방법
Mod 하나	/plugin → Installed 탭에서 그 플러그인을 끄거나 지운다
설치한 Mod 전부, 이번 세션만	claude --safe-mode로 시작(다른 사용자 설정도 같이 꺼진다)
설치한 Mod 전부, 모든 세션	~/.claude/settings.json에 "disableAllHooks": true

세 번째는 범위가 넓습니다. 설정 파일에 걸어 둔 훅과 사용자 상태줄까지 같이 멈춥니다. 그리고 이 방법들로는 내장 Mod가 꺼지지 않습니다. 내장 Mod는 /plugin에서 하나씩 끕니다.

어디서 실행하느냐에 따라 보이는 것이 다르다

마지막으로, Mod의 훅은 거의 모든 곳에서 돌지만 화면에 그리는 것은 터미널과 데스크톱 앱에서만 보입니다.

실행 환경	훅 동작	화면 표시
터미널 claude (편집기 내장 터미널 포함)	O	O
데스크톱 앱 Code 탭	O	O (터미널 전용 요소 제외)
VS Code 확장 채팅 패널	O	X
claude -p, Agent SDK	O	X
데스크톱 앱의 WSL 세션	X	X

VS Code 확장에서 1편의 스피너 숫자가 안 보이는 건 고장이 아니라 원래 그렇습니다. 실습은 터미널에서 하는 걸 권합니다.

정리 대신 체크리스트

• claude --version 결과가 2.1.287 이상인가 (데스크톱은 2.1.286)
• 예전에 넣은 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS가 남아 있지 않은가
• /plugin → Installed에서 내장 Mod가 보이는가
• 내가 올린 Mod가 N mod active 줄에 이름으로 나오는가
• 문제가 생기면 끌 방법(--safe-mode)을 알고 있는가

다음 편은 이름이 비슷해서 가장 많이 헷갈리는 다섯 가지, Plugin·Hook·Skill·MCP·Mod의 차이를 표 한 장으로 정리합니다.

참고한 공식 문서: Mods overview (code.claude.com)

그러면 오늘도 모두 스테이블 하세요.