Mod란 무엇인가
Anthropic의 문서는 다음과 같은 정의로 시작합니다. "mod는 Claude Code의 모양과 동작을 변경하는 플러그인입니다."
mod는 코드입니다. "JavaScript 또는 TypeScript 이벤트 핸들러로 구성됩니다. 도구 호출, 프롬프트 제출 또는 인터페이스의 일부가 그려지는 등의 이벤트가 발생할 때 Claude Code가 핸들러를 호출하며, 핸들러는 해당 이벤트를 감시하거나 변경하거나 제어할 수 있습니다."
문서에서는 이러한 핸들러를 hook이라고 부르는데, 이는 Claude Code에 이미 설정 파일에서 구성하는 hook이 있기 때문에 혼동될 수 있습니다. mod 페이지에서 Anthropic은 설정 파일 방식의 hook을 'settings hook'이라고 부릅니다. 차이점은 실행 위치에 있습니다. "mod의 핸들러는 Claude Code 내부에서 실행되는 함수입니다."
작은 mod는 플러그인 매니페스트, 코드를 가리키는 hooks.json, 그리고 핸들러를 등록하는 코드 파일 등 세 개의 파일로 구성됩니다.
Mod가 할 수 있는 일
mod는 Claude Code 내부에서 실행되기 때문에, Anthropic은 settings hook, skill, 상태 표시줄(status lines), MCP 서버가 할 수 없는 다음과 같은 기능들을 나열합니다.
- 사용 가능한 인터페이스 그리기: 대화 기록 옆의 창이나 프롬프트 위의 밴드 등을 탭, 버튼, 텍스트 필드와 함께 구성할 수 있습니다.
- Claude Code 자체 인터페이스 다시 그리기: 도구 호출 행, 스피너, 또는 Claude가 질문하는 대화 상자 등을 수정할 수 있습니다.
- 도구 호출이나 요청에 개입: 예를 들어 질문을 받는 동안 도구 호출을 대기시키거나, 요청을 다른 모델로 보내는 등의 작업이 가능합니다.
- 명령어에서 자체 코드 실행: Claude의 턴 없이 즉시 실행되는
/command를 만들 수 있으며, Claude가 작업 중일 때도 실행 가능합니다. - hook 간 데이터 공유: 한 hook이 기록한 내용을 다른 hook이 표시할 수 있습니다.
Claude Code의 일부 기능 자체도 mod로 구축되었습니다. 내장 목록에는 /diff와 "AGENTS.md를 프로젝트 지침으로 로드하는" 내장 mod가 포함되어 있습니다. /plugin의 Installed 탭에서 내장 mod를 볼 수 있지만, "내장 mod는 업데이트하거나 삭제할 수 없습니다."
Mod와 settings hook, skill, 플러그인, MCP 서버의 차이점
플러그인. mod는 플러그인과 별개의 것이 아닙니다. 마켓플레이스에서 플러그인 형태로 설치되며, 하나의 플러그인은 mod와 함께 skill, 명령어, 에이전트, MCP 서버를 포함할 수 있습니다.
Settings hooks. settings hook은 수명 주기 이벤트 발생 시 Claude Code가 실행하는 셸 명령, HTTP 요청 또는 프롬프트입니다. 도구 호출이나 프롬프트를 허용, 차단 또는 변경할 수 있고 Claude에게 컨텍스트를 추가할 수 있지만, 아무것도 그릴 수는 없습니다. settings hook과 컨텍스트 추가 기능에 대해서는 Claude Code hook이란 무엇인가 가이드에서 다룬 바 있습니다.
Skills. skill은 Claude가 읽는 지침이 담긴 SKILL.md 파일입니다. 이는 Claude가 알고 행하는 바를 바꾸는 것이지, Claude Code의 동작을 바꾸는 것이 아닙니다.
MCP 서버. MCP 서버는 Claude가 외부 시스템에 접근할 수 있는 도구를 제공합니다.
Anthropic의 비교를 요약하자면, 창, 프롬프트 위 밴드, 커스텀 명령어가 필요하거나 이벤트를 다시 작성하고 싶을 때 mod를 선택하면 됩니다. 만약 settings hook, skill 또는 MCP 서버가 이미 필요한 기능을 수행한다면, 문서는 mod를 작성하기 전에 그것들을 먼저 비교해 볼 것을 권장합니다.
Mod 설치 및 신뢰 여부 결정
mod는 다른 플러그인과 동일한 방식으로 설치합니다. 세션 내에서 /plugin install 뒤에 플러그인 이름, @, 마켓플레이스 이름을 입력하여 실행합니다. 세션이 열려 있는 동안 셸에서 설치했다면 /reload-plugins를 실행하여 로드합니다.
Anthropic은 또한 공개 저장소에 샘플 mod를 공유하고 있습니다. 예를 들어 프롬프트 위에 컨텍스트 창의 예측치를 그리는 mod나, 위험한 셸 명령을 대기시키고 무엇이 변경될지 보여주는 mod 등이 있습니다.
설치하기 전에 경고를 진지하게 받아들이십시오. "mod는 사용자의 권한으로 실행되는 코드입니다." 문서에는 mod가 로드된 후 접근할 수 있는 항목들이 나열되어 있습니다. 여기에는 파일, 환경 변수, 설정 파일, 그리고 "사용자가 보내는 모든 프롬프트와 Claude가 수행하는 모든 도구 호출"을 포함한 세션 정보가 포함됩니다.
또한, "mod는 샌드박스화되지 않습니다." 샌드박싱을 켜면 Claude가 실행하는 Bash 명령은 격리되지만, mod가 시작한 프로세스는 그 밖에서 실행됩니다.
제한 사항도 있습니다. "mod는 Claude Code 인터페이스의 많은 부분을 다시 스타일링할 수 있지만, 권한 요청 프롬프트는 수정할 수 없습니다." 또한 Anthropic은 로드 시 기본적으로 사용자의 mod가 규칙이나 hook이 차단했을 도구 호출을 승인하지 못하도록 막는 내장 보호 장치를 설명합니다.
설치 전 mod의 기능을 확인하려면 해당 폴더에서 claude plugin validate를 실행하세요. 출력 결과에는 mod가 처리하는 이벤트와 Claude Code에 요청하는 작업 목록이 표시됩니다.
Mod가 실행되는 위치
mod는 Claude Code CLI, Claude Desktop 앱의 Code 탭, 그리고 VS Code 확장 프로그램에서 작동합니다. Anthropic의 표에는 다음과 같은 특수 사례가 추가되어 있습니다.
claude -p및 Agent SDK: hook은 실행되지만 아무것도 그려지지 않습니다.- 원격 제어(Remote Control): 사용자의 머신 세션에서 hook이 실행되며, 해당 터미널에 그림이 나타납니다.
- 클라우드 세션: 클라우드 세션에 도달하는 플러그인의 hook은 실행되지만 아무것도 그려지지 않습니다.
- Desktop 앱의 WSL 세션: 플러그인을 사용할 수 없으므로 mod가 실행되지 않습니다.
그리기 기능이 있는 mod는 실행 위치를 확인하고 대화 기록의 한 줄이나 명령어의 텍스트 응답으로 대체(fallback)할 수 있습니다.
세션 간 유지되는 데이터
이 부분은 mod에 의존하기 전에 반드시 이해해야 할 내용입니다. Anthropic 문서는 다음과 같이 설명합니다. "mod가 값을 보관하는 위치에 따라 값의 유지 기간이 결정됩니다. 모듈이 다시 로드될 때까지, 세션이 끝날 때까지, 또는 한 세션에서 다음 세션까지 유지됩니다."
세 가지 위치가 있습니다.
모듈 수준 변수(Module-level variable). 개발 중에 파일을 저장할 때마다 발생하는 모듈 재로드 시점까지 유지됩니다. Anthropic은 이를 손실될 수 있는 값으로 설명합니다.
$.state. "세션이 종료되거나 사용자가 /clear, /resume 또는 /branch를 실행할 때"까지 유지됩니다. 모듈 재로드 시에도 유지되어야 하는 인터페이스 관련 값들을 위한 것입니다. 도입부 예시에서 /clear 이후 창이 비워진 이유가 바로 이것입니다.
$.store. mod가 값을 삭제하거나, 어떤 세션도 cleanupPeriodDays 기간 동안 store를 읽거나 쓰지 않을 때까지 유지됩니다. Anthropic은 이를 "머신의 모든 세션이 공유하는 키-값 저장소"라고 설명합니다. 이는 ~/.claude/plugins/store/ 아래 플러그인 자체의 JSON 파일로 저장되며, 문서에서는 설정, 기록 및 "사용자가 다음에 다시 찾을 것으로 예상하는 모든 것"을 위한 용도라고 명시합니다.
따라서 어제의 총계를 기억했던 카운터는 $.store에 있었고, 초기화된 창은 $.state에서 데이터를 가져오고 있었던 것입니다.
잘 만들어진 mod는 이 둘을 연결합니다. Anthropic은 세션이 시작될 때 mod가 $.store에서 저장된 값을 $.state로 복사한다면, /clear, /resume 또는 /branch 이후에 다시 복사해야 한다고 언급합니다. 이러한 명령어들이 $.state를 초기화하고 세션 시작 hook이 다시 실행되지 않기 때문입니다. 데이터가 사라지면 안 되는데 mod의 디스플레이가 초기화된다면, 개발자가 바로 이 부분을 확인해야 합니다.
두 가지 실질적인 점이 뒤따릅니다. mod의 store는 사용자의 머신에 있으며 그곳의 세션들에 의해 공유되므로, 팀원이나 다른 컴퓨터에서 볼 수 있는 것과는 다릅니다. 또한 아무런 작업이 발생하지 않으면 Claude Code가 다른 곳에서 사용하는 것과 동일한 보존 기간의 적용을 받습니다.
Mod 비활성화 방법
"mod는 기본적으로 켜져 있습니다." 이를 중단하기 위해 Anthropic은 세 가지 수준을 제시합니다.
- 개별 mod:
/plugin의 Installed 탭에서 해당 플러그인을 비활성화하거나 삭제합니다. - 한 세션 동안 모든 설치된 mod:
--safe-mode로 Claude Code를 시작합니다. 이는 다른 커스터마이징도 함께 비활성화합니다. - 모든 세션의 모든 설치된 mod:
~/.claude/settings.json에서disableAllHooks를true로 설정합니다. 설정 hook과 커스텀 상태 표시줄도 중단됩니다.
내장 mod는 다릅니다. "disableAllHooks, --bare, --safe-mode와 같이 설치된 mod를 중단하는 설정과 플래그는 내장 mod를 중단시키지 않습니다." 조직에서는 관리형 설정을 통해 로드되는 mod를 제한할 수도 있습니다.
사람들이 흔히 겪는 시행착오
mod의 창이 /clear 이후에도 유지될 것이라 기대함. $.state는 /clear, /resume, /branch 시 초기화됩니다.
다른 머신에서도 mod의 데이터가 있을 것이라 기대함. $.store는 해당 데이터가 저장된 머신의 세션들 사이에서만 공유됩니다.
확인 없이 설치함. claude plugin validate를 실행하여 mod가 무엇을 하는지 확인하세요.
샌드박스가 mod까지 보호할 것이라 가정함. mod는 샌드박스화되지 않습니다.
프로젝트 지식 저장에 mod를 사용함. mod는 Claude Code의 동작을 변경합니다. 프로젝트 지식은 지침 파일에 보관해야 합니다.
해결책: 동작에는 mod를 사용하고, 컨텍스트는 다른 곳에 보관하기
1단계: 설치 전 mod의 기능 확인
해당 폴더에서 claude plugin validate를 실행하고 나열된 이벤트와 호출을 읽어보세요.
2단계: 각 값의 저장 위치 파악
mod를 작성한다면 /clear 이후에도 유지되어야 하는 값은 $.store에 넣고, 초기화 후에는 이를 다시 $.state로 로드하세요.
3단계: 프로젝트 지식은 지침 파일에 보관
컨벤션과 구조는 프로젝트 지침으로 로드되는 CLAUDE.md 또는 AGENTS.md에 속합니다.
4단계: 세션에서 배운 내용 기록
mod의 창은 진행 상황을 추적할 수 있지만, 그 이면의 결정 사항은 세션과 머신보다 오래 지속되는 곳에 기록되어야 합니다.
MemoryLake에서 설정하기
mod는 세션에서 일어나는 일을 확인하기에 좋은 방법입니다. 하지만 어떤 방식이 효과적이었는지 또는 왜 특정 파일에 접근하면 안 되는지와 같은 세션의 결정과 교훈은 /clear 시 초기화되지 않고 특정 머신에 묶이지 않는 보금자리가 필요합니다.
MemoryLake는 결정, 컨벤션, 학습된 교훈과 같은 프로젝트 컨텍스트를 위한 기억 계층(memory layer)입니다. 사용자가 관리하는 한 곳에 보관되며 ChatGPT, Claude Code, Codex 등 연결된 어시스턴트에서 사용할 수 있습니다.
사용자는 자신의 언어로 직접 항목을 작성합니다. 사용자의 mod, $.state 또는 $.store, 플러그인, 설정 파일, 세션 또는 공급업체의 저장소에서 아무것도 읽거나 쓰거나 삭제하지 않습니다. mod와 그 상태는 Anthropic이 설명하는 방식 그대로 작동합니다.
1단계: API 키 생성
로그인 후 대시보드에서 키를 생성합니다. 다른 자격 증명과 마찬가지로 플러그인이나 mod 코드에 노출되지 않도록 주의하세요.

2단계: 첫 번째 기억 업로드
해결책 4단계에서 작성한 내용부터 시작하세요. 최근 세션의 결정 사항, 의존하는 컨벤션, 다시 배우고 싶지 않은 교훈 등을 입력합니다. 항목당 하나의 결정을 권장합니다.

3단계: AI 및 에이전트 연결
Claude Code와 사용하는 다른 어시스턴트를 연결합니다. 새로운 세션이나 다른 머신에서도 동일한 항목을 활용할 수 있습니다.

실제적인 변화
첫 번째 차이점은 /clear를 실행해도 더 이상 컨텍스트 손실 비용이 발생하지 않는다는 점입니다. mod의 디스플레이는 초기화될 수 있지만, 결정 사항은 여전히 기록되어 있습니다.
두 번째는 휴대성입니다. 학습한 내용이 한 머신의 저장소에 묶이지 않습니다.
세 번째는 깔끔한 분리입니다. mod는 Claude Code의 동작을 처리하고, 프로젝트 컨텍스트는 한 곳에 모여 관리됩니다.
Claude Code Mod 모범 사례
mod를 코드로 취급하세요. 사용자의 권한으로 실행되며 샌드박스화되지 않습니다.
설치 전 검증하세요. claude plugin validate는 mod가 하는 일을 나열합니다.
셸 설치 후 다시 로드하세요. 열려 있는 세션에서 /reload-plugins를 실행하세요.
세 가지 수명 주기를 파악하세요. 변수, $.state, $.store는 각각 유지되는 기간이 다릅니다.
/clear 시 초기화를 예상하세요. $.state는 기본값으로 돌아갑니다.
문제 해결 시 --safe-mode를 사용하세요. 한 세션 동안 설치된 mod를 비활성화합니다.
컨텍스트를 mod에 두지 마세요. 지침 파일과 직접 관리하는 기억(memory)을 사용하세요.
결론
Claude Code mod는 Claude Code 내부에서 실행되는 JavaScript 또는 TypeScript 핸들러로 구성된 플러그인입니다. settings hook, skill, MCP 서버가 할 수 없는 창과 밴드 그리기, 인터페이스 재구성, 도구 호출 및 요청 개입, 명령어 추가 등을 수행할 수 있습니다. 또한 사용자의 권한으로 실행되며 샌드박스화되지 않으므로 설치 전에 반드시 검증해야 합니다.
mod가 유지하는 데이터는 저장 위치에 따라 다릅니다. 모듈 변수는 재로드 시까지, $.state는 세션 종료 또는 /clear, /resume, /branch 실행 시까지 유지되며, $.store는 머신의 세션 간에 공유되어 삭제되거나 만료될 때까지 지속됩니다. 이 모든 것보다 오래 지속되어야 하는 컨텍스트의 경우, 직접 관리하는 곳에 기록해 두시기 바랍니다.