하네스 엔지니어링 위키

내 패턴 · 진입점과 플러그인 로딩 (settings.json -> 마켓플레이스 -> 플러그인)

Properties2
tags기능분해, mine, entrypoint-plugin-loading
aliases진입점과 플러그인 로딩, settings-marketplace-plugin

13 min read

내 패턴 · 진입점과 플러그인 로딩 (settings.json -> 마켓플레이스 -> 플러그인)

한 줄 요약

에이전트(클로드 코드)는 켜질 때 settings.json 한 장을 먼저 읽고, 거기 적힌 주소를 따라가 플러그인 하나를 통째로 자기 능력으로 장착한다. 왜 배우나: “능력 하나씩 설치”가 아니라 “스위치 하나로 한 묶음”이 어떻게 가능한지 알아야, 직접 플러그인을 만들거나 고장 난 로딩을 고칠 수 있다.

그림

flowchart TD
    A[프로세스 부팅] --> B["settings.json 읽기<br/>모델 / 켤 플러그인 / 마켓플레이스 주소"]
    B --> C["settings.local.json 병합<br/>권한 오버레이만"]
    C --> D["installed_plugins.json 조회<br/>설치 경로 / 버전 / 커밋 해시"]
    D --> E[각 플러그인 plugin.json 매니페스트 펼치기]
    E --> F1[스킬 등록]
    E --> F2[슬래시 명령 등록]
    E --> F3[서브에이전트 자동발견 등록]
    E --> F4[훅 자동발견 등록]
    E --> F5[MCP 외부도구 서버 기동]
    F1 & F2 & F3 & F4 & F5 --> G["시스템 리마인더로<br/>능력 카탈로그를 모델 앞에 깔기"]
    G --> H[모델 실행 루프 시작]

쉽게 풀기

비유: 컴퓨터 켤 때의 BIOS. 전원을 넣으면 화면이 나오기도 전에 BIOS가 “어떤 장치를 붙일지” 목록부터 읽는다. 클로드 코드도 생각을 시작하기 전, 부팅 단계에서 settings.json이라는 “장착 명세서” 한 장을 먼저 펼친다.

명세서에는 딱 세 가지가 적혀 있다.

  1. 어떤 두뇌를 쓸지 — 모델 (model)
  2. 어떤 장비를 켤지 — 플러그인 (enabledPlugins)
  3. 장비를 어디서 가져오는지 — 마켓플레이스 git 주소 (extraKnownMarketplaces)

이어서 그 주소를 따라가 플러그인의 명세서(plugin.json) 를 펼친다. 가전 박스를 하나 열면 본체·리모컨·충전기·설명서가 한꺼번에 나오듯, 플러그인 하나를 켜면 그 안의 스킬·슬래시 명령·서브에이전트·훅·MCP 가 같이 딸려 와 한 번에 등록된다.

flowchart LR
    SW["플러그인 1개<br/>(단일 스위치 ON)"] --> P[plugin.json 매니페스트]
    P --> S[스킬]
    P --> C[슬래시 명령]
    P --> A[서브에이전트]
    P --> H[훅]
    P --> M[MCP 도구]

가장 중요한 한 가지

능력을 하나하나 따로 설치하지 않는다. “플러그인 1개”라는 단일 스위치만 켜면 그 안의 모든 능력이 함께 주입된다 — 이 챕터의 핵심.

왜 모델이 이걸 알아야 하나? 모델은 자기 앞 컨텍스트에 “부를 수 있는 도구 목록”이 깔려 있어야만 호출할 수 있다. 목록에 없으면 그 능력은 없는 것과 같다. 그래서 진입점 로딩은 “이번 세션에서 쓸 능력의 총목록”을 모델 앞에 미리 펼쳐주는 절차다.

핵심 정리

파일역할한 줄 비유
settings.json진입점. 모델·플러그인·마켓플레이스 선언장착 명세서(BIOS)
settings.local.json로컬 권한만 덧대는 오버레이이 자리에서만 통하는 허가증
installed_plugins.json실제 설치 레코드(락파일)영수증·재고 대장
plugin.json플러그인이 가진 능력 선언박스 안 구성품 목록

자동발견 vs 명시선언 — 매니페스트에 적어야 등록되는 것과, 약속된 경로에 두면 알아서 잡히는 것이 나뉜다.

flowchart TD
    PJ[plugin.json] -->|명시 선언| E1["skills / commands / mcpServers"]
    PJ -.약속된 경로.-> E2["hooks/hooks.json<br/>agents/*.md (자동 발견)"]
    E1 & E2 --> R["플러그인 1개 = 훅+스킬+명령+에이전트+MCP 한 번에 주입"]

로딩 순서 체크리스트(부팅 시 실제 일어나는 일)

  • settings.json을 읽어 모델·플러그인·마켓플레이스 주소 확정
  • settings.local.json의 권한을 위에 덧댐(덮어쓰기 아님, 보태기)
  • installed_plugins.json에서 캐시 경로·버전·커밋 해시 조회
  • 각 플러그인의 plugin.json을 펼쳐 능력 등록
  • 시스템 리마인더로 카탈로그를 모델 앞에 주입한 뒤 실행 루프 시작

실제 예시

진입점부터 능력 등록까지, 실제 디스크 파일을 따라간다. 아래는 핵심 발췌이며 전문은 접이식으로 둔다.

// ~/.claude/settings.json (핵심)
{
  "model": "opus[1m]",
  "enabledPlugins": { "oh-my-claudecode@omc": true /* ...외 3개 */ },
  "extraKnownMarketplaces": {
    "omc": { "source": { "source": "git", "url": "https://github.com/Yeachan-Heo/oh-my-claudecode.git" } }
  },
  "skipDangerousModePermissionPrompt": true
}

단일 진입 계약의 물증

같은 폴더 marketplaces/omc/ 안에 skills/, commands/, agents/(19개), hooks/hooks.json, .mcp.json(서버 t)이 동시에 존재한다. 매니페스트엔 skills/commands/mcpServers만 적혀 있어도 hooks/hooks.json과 agents/*.md는 규약 경로에서 자동 발견된다.

직접 만들 때 템플릿

// 1) 진입점 ~/.claude/settings.json
{
  "model": "opus[1m]",
  "enabledPlugins": { "my-plugin@my-marketplace": true },
  "extraKnownMarketplaces": {
    "my-marketplace": { "source": { "source": "git", "url": "https://github.com/me/my-marketplace.git" } }
  }
}
// 2) 매니페스트 my-plugin/.claude-plugin/plugin.json
{
  "name": "my-plugin", "version": "0.1.0", "description": "한 줄 설명",
  "skills": ["./skills/hello/"], "commands": "./commands/", "mcpServers": "./.mcp.json"
}

자동발견 배치 — 같은 플러그인 폴더에 두기만 하면 등록된다.

  • hooks/hooks.json → SessionStart/UserPromptSubmit 훅
  • agents/*.md → 서브에이전트 · commands/*.md → 슬래시 명령 · skills/<name>/SKILL.md → 스킬

요약 & 셀프체크

3줄 요약

  1. 클로드 코드는 부팅 시 settings.json을 먼저 읽어 모델·플러그인·마켓플레이스 주소를 정한다.
  2. 그 주소를 따라가 plugin.json을 펼치면 명시 선언(스킬·명령·MCP)과 자동발견(훅·에이전트)이 한꺼번에 능력으로 등록된다.
  3. 등록 결과가 시스템 리마인더로 모델 앞에 깔린 뒤에야 실행 루프가 시작된다 — 목록에 없으면 모델은 그 능력을 못 부른다.

스스로 답해보기

  • 플러그인 1개를 켰을 때, 매니페스트에 적지 않았는데도 자동 등록되는 능력 두 가지는?
  • oh-my-claudecode@omc에서 @ 뒤의 omc는 어디서 정의된 이름과 일치해야 하는가?
  • 로컬에서만 sudo npm 실행을 허용하려면 어느 파일의 어느 키에 적는가?

연결

MINE_개요 · _분석축_루브릭

Codex 교차검증

(원문 노트에 별도 Codex 교차검증 섹션 없음 — 신규 사실 추가 없이 보존 차원에서 비워 둠. 검증 결과가 생기면 이 콜아웃에 누적한다.)

그래프 뷰

백링크