16. Plugins(플러그인)

플러그인이란

지금까지 4부에서 본 Skill·Subagent·Hook·MCP 서버는 각각 .claude/ 디렉터리에 따로 설정했습니다. 플러그인은 이것들을 하나의 버전 관리되는 설치 단위로 묶는 패키징 층입니다.

📌 핵심 — 플러그인은 새 능력을 만들지 않습니다. 기존 능력을 포장합니다. 플러그인이 담을 수 있는 모든 것(스킬·서브에이전트·훅·MCP 서버)은 이미 .claude/에서 단독으로 설정할 수 있는 것들입니다. 플러그인은 그것들을 함께 여행하게 만들 뿐입니다.

비유하자면, 플러그인은 앱 스토어의 앱입니다. 흩어진 설정 파일들을 일일이 복사하는 대신, 한 번의 설치로 검증된 구성 묶음을 받습니다.

왜 플러그인인가: 핸드오프 문제

대부분의 Claude Code 커스터마이징은 개인 습관으로 시작합니다. .claude/commands/에 명령을 넣고, .claude/skills/에 SKILL.md를 떨구고, settings.json에 훅을 엮으면 내 세션이 날카로워집니다. 그런데 동료가 "그거 어떻게 했어?"라고 물으면, 깔끔하게 넘겨줄 방법이 없습니다.

flowchart TB
    subgraph Before["플러그인 없이"]
        F1[채팅에 파일 붙여넣기]:::danger
        F2[아무도 안 따르는 README]:::danger
        F3[.claude/ 커밋하고 동기화 기도]:::danger
    end
    subgraph After["플러그인으로"]
        P[하나의 버전 단위<br/>설치·업데이트·신뢰]:::result
    end
    Before -.해결.-> After

    classDef danger fill:#EF9A9A,stroke:#E53935,color:#000
    classDef result fill:#A5D6A7,stroke:#43A047,color:#000

플러그인이 주는 세 가지:

1. 묶음(bundling): "deploy 워크플로우"가 슬래시 명령 + 사전 점검 훅 + 플랫폼 MCP 서버 + 릴리스 노트 서브에이전트로 이뤄진다면, 단독으론 네 곳에 흩어지지만 플러그인으론 한 단위로 다닙니다.
2. 배포(distribution): 동료가 명령 하나로 설치하고, 마켓플레이스가 나중에 업데이트할 수 있습니다.
3. 정렬(alignment): 저장소·관리 설정으로 배포하면 모두가 같은 표준을 로드하고, .claude/를 손으로 동기화하라고 부탁할 필요가 없습니다.

무엇을 묶을 수 있나

플러그인은 자체 완결적 디렉터리로, 다음을 묶습니다:

플러그인 정의는 .claude-plugin/plugin.json에 들어갑니다. 플러그인 스킬은 충돌 방지를 위해 자동으로 네임스페이스가 붙습니다(예: /security:scan).

⚠️ 플러그인 배포 시 보안 제약

보안상, 플러그인이 배포하는 서브에이전트는 hooks·mcpServers·permissionMode를 선언할 수 없습니다. 즉 설치된 플러그인이 당신 몰래 훅을 심거나 권한 모드를 바꾸지 못하게 막혀 있습니다.

플러그인 서브에이전트가 쓸 수 있는 frontmatter는 정해진 집합입니다: name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background, isolation(값은 worktree만).

마켓플레이스에서 찾고 설치하기

마켓플레이스는 여러 플러그인을 하나의 레지스트리로 배포하는 GitHub 저장소입니다.

# 세션 안에서 마켓플레이스 둘러보기
/plugin

# 마켓플레이스 추가 후 설치
/plugin marketplace add anthropics/claude-code
/plugin install <플러그인이름>

⚠️ 설치 전 점검: 3rd-party 플러그인은 파일을 읽고, 명령을 실행하고, 데이터를 외부로 보낼 수 있습니다. 설치 전 권한·스크립트·훅·서비스 연결을 확인하세요. 1차 벤더·검증된 플러그인을 선호하는 게 14장의 MCP 보안 수칙과 같은 맥락입니다.

팀에 배포하는 패턴

flowchart TB
    Dev[내 .claude/ 설정]:::user --> Pack[플러그인으로 패키징<br/>plugin.json]:::tool
    Pack --> MP[마켓플레이스 게시<br/>GitHub repo]:::tool
    MP --> Team[팀원: /plugin install 한 번]:::result
    MP --> Update[중앙에서 업데이트]:::result

    classDef user fill:#FFE082,stroke:#F9A825,color:#000
    classDef tool fill:#90CAF9,stroke:#1E88E5,color:#000
    classDef result fill:#A5D6A7,stroke:#43A047,color:#000

4부 마무리: 확장 층의 큰 그림

flowchart TB
    subgraph Knowledge["지식"]
        CM[CLAUDE.md]:::know
        SK[Skills]:::know
    end
    subgraph Workers["일꾼"]
        SA[Subagents]:::sub
        AT[Agent Teams]:::sub
    end
    subgraph Control["제어·연결"]
        HK[Hooks]:::danger
        MC[MCP 서버]:::tool
    end
    PL[Plugins<br/>위 모두를 묶어 배포]:::pkg

    Knowledge --> PL
    Workers --> PL
    Control --> PL

    classDef know fill:#CE93D8,stroke:#8E24AA,color:#000
    classDef sub fill:#80DEEA,stroke:#00ACC1,color:#000
    classDef danger fill:#EF9A9A,stroke:#E53935,color:#000
    classDef tool fill:#90CAF9,stroke:#1E88E5,color:#000
    classDef pkg fill:#A5D6A7,stroke:#43A047,color:#000

• 지식(CLAUDE.md·Skills): 반복 설명에 지쳤을 때
• 일꾼(Subagents·Agent Teams): 병렬·컨텍스트 격리가 필요할 때
• 제어·연결(Hooks·MCP): 강제 규칙·외부 시스템이 필요할 때
• 플러그인: 위 모두를 묶어 공유·배포

이 장에서 배운 것

• 플러그인은 Skill·Subagent·Hook·MCP를 하나의 버전 단위로 묶는 패키징 층이다. 새 능력이 아니라 포장이다.
• 핸드오프(공유) 문제를 풀어준다: 묶음·배포·정렬.
• 보안상 플러그인 서브에이전트는 hooks·mcpServers·permissionMode를 선언할 수 없다.
• /plugin으로 마켓플레이스를 둘러보고 /plugin install로 설치하되, 설치 전 권한·연결을 점검한다.
• 한 저장소면 .claude/, 조직 전체면 플러그인.

✍️ 확인 문제

1. "플러그인은 새 능력을 만들지 않는다"는 말의 의미는 무엇인가요?
2. 플러그인이 배포하는 서브에이전트가 hooks·mcpServers·permissionMode를 선언하지 못하게 막은 이유는 무엇일까요?
3. 어떤 확장을 한 저장소에만 쓸지, 조직 전체에 쓸지에 따라 .claude/와 플러그인 중 무엇을 고르나요?

🎉 4부 완료! 가장 큰 산을 넘었습니다. 다음 장부터는 5부 통합과 자동화입니다.
다음 장: 17. IDE·데스크톱·웹·모바일