전체 그림
Claude Code를 스마트한 IDE 플러그인 생태계라고 생각해보면 이해가 빠르다.
┌──────────────────────────────────────────────────┐
│ Claude Code │
│ │
│ Hooks → 항상 자동 실행되는 트리거 │
│ Skills → 나만의 커스텀 명령어 │
│ SubAgents → 전문 분야별 보조 에이전트 │
│ Plugins → 위 셋을 묶어 팀과 공유 │
│ Marketplace → 플러그인 앱스토어 │
└──────────────────────────────────────────────────┘
각각을 하나씩 살펴보자.
1. Hooks — 항상 자동으로 해야 하는 것들
개념
코드를 수정할 때마다 prettier를 실행하고 싶다면 어떻게 할까? Claude에게 "수정하고 나서 꼭 포매팅 해줘"라고 부탁할 수 있지만, 까먹고 빠뜨릴 수 있다는 가능성이 있다. Hook은 이러한 문제를 해결한다.
즉, 특정 이벤트가 발생하면 AI 판단 없이 항상, 반드시 실행되는 쉘 명령이다. 자연어로 요청하는게 아닌 쉘 명령어이기 때문에 deterministic 한 실행이다.
파일 수정 완료
↓
PostToolUse Hook 자동 발동
↓
prettier --write 실행 (Claude는 이 과정을 '항상' 실행)주요 이벤트 종류
| 이벤트 | 언제 실행되는가 |
|---|---|
PreToolUse |
도구 실행 직전 (차단 가능) |
PostToolUse |
도구 실행 직후 |
SessionStart |
세션 시작/재개 시 |
Notification |
Claude가 입력 대기 시 |
Stop |
Claude 응답 완료 시 |
설정 예시
// .claude/settings.json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
}
]
}
]
}
}실제로 많이 쓰이는 Hook
.env 파일 보호 — Claude가 민감한 파일을 실수로 수정하지 못하도록 차단한다. exit 코드 2를 반환하면 작업이 즉시 중단된다.
#!/bin/bash
FILE=$(cat | jq -r '.tool_input.file_path // empty')
if [[ "$FILE" == *".env"* ]]; then
echo ".env 파일은 수정할 수 없습니다" >&2
exit 2
fi
작업 완료 데스크탑 알림 — 오래 걸리는 작업이 끝났을 때 알림을 받는다.
# Notification 훅
osascript -e 'display notification "Claude가 응답을 기다리고 있습니다" with title "Claude Code"'
Bash 명령 감사 로그 — 어떤 명령이 언제 실행됐는지 기록한다.
# PostToolUse 훅 (matcher: "Bash")
jq -r '"[\(now | todate)] \(.tool_input.command)"' >> ~/.claude/bash-audit.log
테스트 통과 검증 — Claude가 "완료"라고 선언하기 전에 실제로 테스트를 돌린다.
{
"type": "agent",
"prompt": "테스트 스위트를 실행하고 모두 통과하는지 확인하라. 실패하면 이유를 알려라.",
"timeout": 120
}
Hook을 사용할 때 종료 코드의 의미를 알아두면 훨씬 유연하게 활용할 수 있다.
| 종료 코드 | 동작 |
|---|---|
0 |
작업 진행, stdout은 Claude 컨텍스트에 추가 |
2 |
작업 차단, stderr 내용이 Claude에게 전달 |
| 기타 | 작업 진행, stderr는 로깅만 |
2. Skills — Claude에게 커스텀 명령 가르치기
개념
매번 아래와 같은 긴 지침을 타이핑하고 있는 문제를 Skill로 해결할 수 있다.
"커밋 메시지 작성해줘. Conventional Commits 형식으로, 한국어로, 변경사항 요약은 bullet point로..."
이걸 /commit 하나로 줄일 수 있다.
Skill은 재사용 가능한 지침 파일이다. .claude/skills/ 폴더에 Markdown 파일로 저장하고, /스킬명으로 호출한다.
/commit 입력
↓
Claude가 commit.md 파일을 읽는다
↓
파일에 정의된 단계별 지침을 따른다파일 구조
---
name: commit
description: Conventional Commits 형식으로 커밋 메시지 작성
---
# 커밋 메시지 작성 가이드
1. git diff --staged 로 변경사항 확인
2. 변경 유형 파악 (feat/fix/refactor/docs/chore)
3. 한국어로 간결하게 작성
4. 커밋 전 사용자에게 확인 받기실제로 많이 쓰이는 Skill
/commit — 스테이지된 변경사항을 분석해 Conventional Commits 형식의 커밋 메시지를 자동 생성한다.
/debug — 오류 메시지를 받으면 원인 분석 → 가설 수립 → 검증 → 수정 순서로 체계적으로 접근하도록 유도한다. Claude가 "일단 이것저것 시도해보는" 방식에서 벗어나게 만드는 데 효과적이다.
/pr-review — PR의 diff를 읽고 코드 품질, 보안 이슈, 누락된 테스트를 체크리스트 형식으로 검토한다.
/explain — 선택한 코드 블록을 주니어 개발자도 이해할 수 있는 언어로 설명한다.
/deploy — 배포 전 체크리스트 확인 → 빌드 → 테스트 → 배포 → 결과 확인까지 단계를 자동화한다.
3. SubAgents — 전문가에게 위임하기
개념
Claude Code와 대화하다 보면 이런 상황이 생긴다.
"이 버그 고치기 전에 코드베이스 전체에서 관련 패턴 좀 찾아줘."
Claude가 직접 탐색하면 수천 줄의 탐색 과정이 현재 대화 컨텍스트에 쌓인다. 나중엔 Claude가 앞서 논의했던 맥락을 "잊어버리는" 것처럼 느껴지는 이유가 여기에 있다. SubAgent는 이 문제를 해결한다. 별도의 독립된 Claude 인스턴스가 특정 작업을 맡아 처리하고, 결과 요약만 메인 대화에 돌려준다.
메인 Claude (대화 컨텍스트 유지)
↓ 탐색 작업 위임
Explore SubAgent (독립 컨텍스트, 읽기 전용)
↓ 탐색 완료
"src/api/ 에서 관련 패턴 12개 발견" 요약 반환
↓
메인 Claude가 요약을 받아 계속 작업내장 SubAgent 종류
| SubAgent | 특징 | 주 용도 |
|---|---|---|
Explore |
빠름, 읽기 전용 | 코드베이스 탐색, 파일 검색 |
Plan |
신중, 분석적 | 구현 계획 수립, 아키텍처 설계 |
general-purpose |
범용 | 복잡한 멀티스텝 작업 |
실제로 많이 쓰이는 SubAgent 패턴
코드베이스 탐색 — "이 프로젝트에서 인증 관련 코드가 어디에 있는지 찾아줘"라고 하면 Explore Agent가 전체 탐색을 맡아 메인 대화 컨텍스트를 깔끔하게 유지한다.
병렬 작업 — 독립적인 모듈 여러 개를 각각 다른 SubAgent에 맡겨 동시에 처리한다. 순차 처리 대비 시간을 크게 줄일 수 있다.
격리된 코드 리뷰 — PR diff를 별도 컨텍스트에서 리뷰하고 요약만 전달받는다. 리뷰 과정의 노이즈가 메인 대화를 오염시키지 않는다.
4. Plugins — 팀 설정을 한 번에 공유하는 방법
개념
Hooks, Skills, SubAgents를 열심히 만들었는데, 팀원도 같은 환경을 쓰게 하려면 어떻게 해야 할까. 파일을 하나씩 Slack으로 공유하거나 위키에 설정 방법을 적어두는 방식은 반드시 누락이 생긴다.
Plugin은 이 모든 것을 하나의 설치 가능한 패키지로 묶는다.
/plugin install github:our-company/dev-tools한 줄이면 팀원 모두가 동일한 환경을 갖게 된다.
Plugin 구조
our-company-dev-tools/
├── .claude-plugin/
│ └── plugin.json ← 패키지 이름, 버전, 설명
├── skills/
│ ├── commit.md ← /our-tools:commit
│ ├── deploy.md ← /our-tools:deploy
│ └── pr-review.md ← /our-tools:pr-review
├── agents/
│ └── code-reviewer.md ← 코드 리뷰 전담 에이전트
├── hooks/
│ └── hooks.json ← 포매팅, 파일 보호 훅
└── .mcp.json ← MCP 서버 설정 (선택)Skills는 플러그인 이름으로 네임스페이스가 붙어 충돌을 방지한다. /commit이 아니라 /our-tools:commit으로 호출하는 식이다.
실제로 많이 쓰이는 Plugin
Code Intelligence Plugin — LSP 서버를 번들로 포함해 더 정확한 코드 분석을 제공한다.
GitHub Plugin — GitHub MCP 서버 포함. PR 생성/리뷰/머지를 Claude Code 안에서 처리한다.
Figma Plugin — Figma MCP 서버 포함. 디자인 파일을 읽어 컴포넌트 코드를 자동 생성한다.
Security Scanner Plugin — 코드 수정 시마다 자동으로 보안 취약점을 스캔하는 Hook을 포함한다.
5. Marketplace — 만들어진 것을 가져다 쓰기
개념
플러그인을 처음부터 만들지 않아도 된다. 다른 사람이 만들어놓은 Plugin을 찾아 설치할 수 있는 곳이 Marketplace다.
# Anthropic 공식 마켓플레이스 추가
/plugin marketplace add anthropics/official-plugins
# 원하는 플러그인 설치
/plugin install github-tools
/plugin install code-intelligence마켓플레이스 소스는 GitHub 레포, Git URL, 로컬 경로 모두 가능하다. 이 덕분에 회사 내부 전용 마켓플레이스도 만들 수 있다. 자세한 방법은 다음 글에서 다룬다.
정리
| 상황 | 사용할 것 |
|---|---|
| 파일 수정 후 자동 포매팅 | Hook |
| "커밋 메시지 써줘"를 명령어로 | Skill |
| 코드베이스 탐색을 메인 대화와 분리 | SubAgent |
| 팀 전체에 설정 공유 | Plugin |
| 만들어진 도구 설치 | Marketplace |
Claude Code를 단순한 AI 채팅 도구로 쓰는 것과, 이 다섯 가지 개념을 활용해 팀 맞춤형 환경을 구축하는 것은 생산성에서 큰 차이를 만들어낸다.
댓글