플러그인 만들기 — Claude Code에 나만의 기능 추가하는 법

:::callout type=info 이 튜토리얼은 Claude Code 1.x / slash command 플러그인 기준입니다 (2026-04). 도구 업데이트 시 검토 필요. :::

Claude Code에는 /help, /clear 같은 기본 슬래시 명령이 있다. 하지만 실제 프로젝트에서는 팀 고유의 작업 흐름이 필요하다. 플러그인(커스텀 slash command)을 만들면 /deploy, /review, /daily-report 같은 자신만의 명령어로 반복 작업을 한 번에 실행할 수 있다. 마크다운 파일 하나면 충분하다.

플러그인 구조 이해하기

Claude Code의 플러그인은 마크다운 파일 하나다. .claude/commands/ 디렉터리에 저장하면 슬래시 명령으로 자동 인식된다.

.claude/
└── commands/
    ├── deploy.md       → /deploy
    ├── review.md       → /review
    └── daily-report.md → /daily-report

파일 이름이 명령어 이름이 된다. deploy.md를 만들면 /deploy로 호출된다.

준비물

• Claude Code CLI (최신 버전)
• 프로젝트 루트의 .claude/ 디렉터리
• 구현할 작업 시나리오
• 예상 시간: 15분

1단계 — 디렉터리 생성

mkdir -p .claude/commands

전역으로 설치하려면 ~/.claude/commands/를 사용한다.

2단계 — 첫 번째 플러그인 작성

/daily-report 명령을 만든다. 매일 작업 현황을 요약해서 출력하는 명령이다.

.claude/commands/daily-report.md 파일을 생성하고 다음 내용을 작성한다.

# daily-report

오늘의 작업 현황을 요약합니다.

## 실행 순서

1. `git log --oneline --since=midnight`로 오늘 커밋 목록을 확인합니다.
2. `.sync/codespace-pending.jsonl`을 읽어 미처리 큐를 파악합니다.
3. 결과를 다음 형식으로 출력합니다:

### 오늘의 커밋
(git log 결과)

### 미처리 항목
(pending 큐 내용)

### 다음 우선 작업
(판단 기반 제안 1~3개)

3단계 — 인자 받는 플러그인

$ARGUMENTS 변수를 사용하면 명령어에 인자를 넘길 수 있다.

.claude/commands/deploy.md:

# deploy

$ARGUMENTS 환경에 배포를 실행합니다.

지원 환경: staging | production

## 실행 순서

1. `npm run lint:gha`로 GHA 문법 검사
2. `npm run build`로 빌드 검증
3. $ARGUMENTS 환경에 맞는 배포 명령 실행
4. 배포 URL과 결과를 텔레그램으로 알림

호출 시 /deploy staging처럼 사용한다.

4단계 — 전역 플러그인으로 등록

여러 프로젝트에서 공통으로 쓰는 명령이라면 ~/.claude/commands/에 저장한다.

cp .claude/commands/daily-report.md ~/.claude/commands/

전역 명령은 모든 프로젝트에서 동일하게 호출된다.

결과 확인

Claude Code에서 /를 입력하면 등록된 커스텀 명령 목록이 자동 완성으로 표시된다. /daily-report를 실행하면 명령 파일에 작성한 지침대로 Claude가 순서대로 작업을 수행한다.

주의사항

• 플러그인 파일은 마크다운이지만, 실제 실행은 Claude가 읽고 해석하는 방식이다. 쉘 스크립트가 아니다
• 복잡한 로직은 플러그인에서 Bash 도구 호출로 위임하는 것이 효율적이다
• 플러그인 이름에 공백 사용 불가. kebab-case를 권장한다

다음 단계

훅(Hook)과 플러그인을 결합하면 더 강력한 자동화가 가능하다. 훅으로 PreToolUse 가드를 설정하고, 플러그인으로 복잡한 작업 흐름을 지시하는 구조를 실험해 보자.

관련 가이드: 훅-설정하기 / claude-md / mcp-입문