[AI] 클로드 코드(Claude Code) Custom Command 활용 사례 및 예시

 

1. 클로드 코드(Claude Code) Custom Command 활용 사례 및 예시 

---

[Claude Code Custom Command 활용 사례 및 예시]

최근 많은 개발자들이 Claude Code, Gemini CLI와 같은 AI 기반 코딩 도구를 활용하여 개발 생산성을 높이고 있다. 이러한 도구들은 코드 작성, 디버깅, 문서화 등 다양한 작업을 자동화하는 데 도움을 준다. 그 중에서도 핵심 기능 중 하나는 바로 Custom Command라고 볼 수 있다. Claude Code의 Custom Command는 사용자가 자신만의 명령어를 정의하고 실행할 수 있는 기능으로, 이를 통해 자신만의 맞춤형 명령어를 만들어 반복적인 작업을 간소화할 수 있다. 이번에는 몇 가지의 Custom Command 활용 사례와 예시를 살펴보자.

• IntelliJ HTTP 파일 생성 자동화
• PR 생성 자동화
• 코드 리뷰 자동화

 

 

1. IntelliJ HTTP 파일 생성 자동화

IntelliJ IDE에서는 HTTP 요청을 간편하게 보낼 수 있는 HttpClient 라는 도구를 지원하고 있다. IntelliJ HTTP는 포스트맨과 같은 API 테스트 도구와 유사한 기능을 제공하는데, 버전 관리가 가능하고 그 기능이 IDE에 통합되어 있는 등의 장점이 있다. 개인적으로는 IntelliJ HTTP 파일을 클래스 이름과 동일한 경로에 동일한 이름으로 구성하는 방식을 선호한다.

 

 

문제는 매번 컨트롤러 클래스를 생성할 때마다 수동으로 HTTP 파일을 생성하는 것이 번거롭다는 점이다. 이를 해결하기 위해 Claude Code Custom Command를 활용하여 HTTP 파일 생성을 자동화할 수 있다.

---
description: IntelliJ HTTP 파일 생성
allowed-tools: Read, Write, Edit, Grep, Glob
argument-hint: [controller-file-path]
---

# IntelliJ HTTP 파일 생성

컨트롤러 파일을 기반으로 HTTP 테스트 파일을 자동 생성합니다.

## 작업 흐름

### 1. 컨트롤러 파일 입력 처리
컨트롤러 파일 경로를 다음 순서로 결정합니다:

1. **직접 제공된 파일 사용**: `$ARGUMENTS`로 제공된 컨트롤러 파일 경로 사용
2. **사용자 입력 요청**: 파일이 제공되지 않으면 개발자에게 컨트롤러 파일 경로 요청

### 2. 컨트롤러 파일 분석

#### 컨트롤러 파일 정보 추출
제공된 컨트롤러 파일에서 다음 정보를 추출합니다:

1. **파일 경로**: 절대 경로로 변환 (예: `@test-api/...` → 실제 경로)
2. **디렉토리**: 컨트롤러 파일이 위치한 디렉토리
3. **파일명**: 확장자 제거 후 HTTP 파일명 생성

#### 컨트롤러 파일 경로 형식
- 상대 경로: `test-api/src/main/kotlin/com/mangkyu/api/app/test/api/DebuggingTestController.kt`
- 절대 경로: `/Users/mangkyu/IdeaProjects/mangkyu/api/src/main/kotlin/...`
- 모노레포 스타일: `@test-api/src/main/kotlin/com/mangkyu/api/app/test/api/DebuggingTestController.kt`

### 3. HTTP 파일 위치 결정

**HTTP 파일 생성 규칙:**
- 컨트롤러 파일과 동일한 디렉토리에 생성
- 컨트롤러 파일명의 확장자만 `.http`로 변경
- 예: `DebuggingTestController.kt` → `DebuggingTestController.http`

**기존 HTTP 파일 처리:**
- 동일한 위치에 HTTP 파일이 이미 존재하면 기존 파일에 API 추가
- 중복되지 않는 새로운 API만 추가
- 컨트롤러 코드와 동일한 순서대로 새로운 HTTP 요청 추가
- **기존 파일에서 헤더 값 추출하여 일관성 있게 사용**

### 4. 컨트롤러 분석 및 HTTP 요청 생성

#### 컨트롤러 파일 읽기
- 컨트롤러 파일을 읽어 모든 엔드포인트 추출
- 각 메서드의 HTTP 메서드, URL, 요청/응답 타입 파악

#### HTTP 요청 생성
다음 정보를 이용하여 HTTP 요청 작성:
- **HTTP 메서드**: `@PostMapping`, `@GetMapping`, `@PutMapping`, `@DeleteMapping` 등에서 추출
- **엔드포인트**: `@PostMapping("/api/1.0/...")` 에서 URL 추출
- **요청 본문**: `@RequestBody` 매개변수 타입 분석
- **헤더**: `@RequestHeader` 매개변수 분석
- **설명**: `@Operation(summary = "...")` 또는 주석에서 추출

**HTTP 요청 형식 예시:**
```http
### 사용자 여권 정보 삭제
POST {{host}}/api/1.0/test/debugging/delete-passport
Content-Type: application/json
user-id: 29048025
```

### 5. 헤더 값 일관성 유지
#### 헤더 처리
**헤더 값 결정 우선순위:**
1. **기존 HTTP 파일의 값 사용**: 같은 디렉토리나 근처 HTTP 파일에서 발견된 값
2. **패턴 일관성 유지**: 프로젝트 내에서 사용되는 헤더 타입 일관성
3. **기본값 사용**: 기존 값이 없는 경우에만 기본값 적용

#### 헤더 값 예시
```http
# user-Id 사용하는 경우
user-Id: 28603805
```

### 6. API 설명 규칙
- `###` 뒤에 API 목적을 한국어로 간략히 설명
- 컨트롤러 파일에 주석이 있다면 해당 설명 사용
- 메서드명이나 URL에서 목적을 유추하여 설명 생성

## 사용 예시

```
# 컨트롤러 파일 경로와 함께 실행
/back:http @test-api/src/main/kotlin/com/mangkyu/api/app/test/api/DebuggingTestController.kt

# 절대 경로로 실행
/back:http /Users/mangkyu/IdeaProjects/test/test-api/src/main/kotlin/com/mangkyu/api/app/test/api/DebuggingTestController.kt

# 파일 경로 없이 실행 (자동 검색 또는 사용자 입력 요청)
/back:http
```

## 기존 파일 병합 예시

기존 HTTP 파일이 있는 경우:
```http
### 기존 API (헤더 값 참고)
GET {{host}}/api/v1/users
User-Id: 28603805

### 새로 추가되는 API (동일한 헤더 값 사용)
POST {{host}}/api/v1/users
Content-Type: application/json
User-Id: 28603805

{
    "name": "사용자명"
}
```

 

 

이를 활용하면 다음과 같은 명령어로 컨트롤러 파일을 전달하여 HTTP 파일을 자동으로 생성할 수 있다.

 

 

 

 

2. PR 생성 자동화

개발자들은 종종 GitHub 웹페이지에서 Pull Request(PR)를 생성하는 작업을 수행한다. 이 과정은 간단해 보이지만, 커밋, 스쿼시, 브랜치 생성, 커밋 메시지 작성, PR 제목 및 설명 작성 등 여러 단계를 거쳐야 한다. 이러한 반복적인 작업을 자동화하기 위해 Claude Code Custom Command를 활용할 수 있다. GitHub는 GitHub CLI(Command Line Interface)를 제공하여 터미널에서 GitHub 작업을 수행할 수 있도록 지원한다. 해당 기능을 Custom Command와 결합하면 PR 생성 과정을 자동화할 수 있는데, 이때 얻을 수 있는 또 다른 이점으로 GitHub CLI가 설치되어 있지 않은 경우 자동으로 설치를 시도하는 기능을 추가할 수 있다는 점이다. 이를 통해 우리는 직접 필요한 도구를 설치하는 번거로움 없이 PR 생성 작업을 수행할 수 있다.

---
description: 커밋 없이 Pull Request 생성
allowed-tools: Bash(git *), Bash(gh *), Bash(brew install gh)
argument-hint: [PR-title]
---

# Pull Request 생성 (커밋 없음)

현재 변경사항으로 Pull Request를 생성합니다. 추가 커밋은 하지 않습니다.

## 작업 흐름

### 1. Git 상태 확인
현재 git 상태를 확인합니다:
- Current git status: !`git status`
- Current branch: !`git branch --show-current`
- Recent commits: !`git log --oneline -5`
- Commits ahead of develop: !`git rev-list --count HEAD ^develop 2>/dev/null || echo "0"`

### 2. 커밋 이력 확인 및 브랜치 처리
다음 순서로 브랜치 상태를 확인하고 처리합니다:

1. **develop과의 커밋 차이 확인**: `git rev-list --count HEAD ^develop`로 앞선 커밋 수 확인
2. **커밋이 있는 경우**:
    - 최신 커밋 메시지 확인: !`git log -1 --pretty=format:"%s"`
    - 커밋 메시지에서 티켓 번호 추출 (예: `[MKU-51]`, `MKU-51:` 등)
    - 추출된 티켓 번호로 새 브랜치 생성하여 전환
3. **커밋이 없는 경우**: 기존 로직대로 티켓 번호 확인

### 3. 티켓 번호 확인
티켓 번호를 다음 순서로 확인합니다:

1. **커밋 메시지에서 추출**: 커밋이 있는 경우 최신 커밋 메시지에서 티켓 번호 추출
2. **현재 브랜치명에서 추출**: 브랜치명이 `MKU-51`, `PROJ-123` 등의 형식인 경우
3. **ARGUMENTS에서 추출**: `$ARGUMENTS`에 `[MKU-51]` 형식이 포함된 경우
4. **사용자에게 요청**: 위 방법들로 찾을 수 없는 경우 사용자에게 티켓 번호 입력 요청

### 4. 브랜치 생성 및 PR 생성
- **중요**: `git add` 또는 `git commit`을 절대 실행하지 마세요.
- **커밋이 있고 티켓 번호가 추출된 경우**:
    - 추출된 티켓 번호로 새 브랜치 생성 (예: `MKU-51`)
    - 현재 변경사항을 새 브랜치로 이동
- **현재 브랜치가 `develop`인 경우**: 확인된 티켓 번호로 새 브랜치 생성 (예: `MKU-51`)
- **현재 브랜치가 이미 티켓 번호 형식인 경우**: 현재 브랜치에서 바로 PR 생성
- **현재 브랜치가 티켓 형식이 아닌 경우**: 티켓 번호로 새 브랜치 생성 후 PR 생성

### 5. PR 제목 규칙
- 형식: `[TICKET-ID] Korean description`
- 예시: `[MKU-51] IP 정보로 countryCode 조회 API 구현`
- **커밋 메시지 활용**: 커밋이 있는 경우 커밋 메시지를 기반으로 PR 제목 생성
- PR 제목이 `$ARGUMENTS`에 제공되지 않은 경우: 변경사항을 한국어로 요약하여 생성

### 6. PR 완료 작업
- 대상 브랜치는 항상 `develop`
- PR 생성 후 리뷰어 할당
- PR 페이지를 브라우저에서 열기

## GitHub CLI 요구사항

이 명령어는 GitHub CLI (`gh`)가 필요합니다. 설치되지 않은 경우 자동으로 설치를 시도합니다.

## 사용 예시

```
# 티켓 번호와 제목을 함께 제공
/pr-without-commit [MKU-51] IP 정보로 countryCode 조회 API 구현

# 제목만 제공 (티켓 번호는 브랜치명에서 추출)
/pr-without-commit API 성능 개선 작업

# 인수 없이 실행 (티켓 번호와 제목 모두 자동 처리)
/pr-without-commit
```

## 티켓 번호 처리 예시

- **커밋이 있고 메시지가 `[MKU-51] API 구현`인 경우**: 티켓 번호 `MKU-51`로 새 브랜치 생성하여 PR 생성
- **브랜치 `MKU-51`에서 실행**: 티켓 번호는 `MKU-51` 사용
- **브랜치 `feature/new-api`에서 `/pr-without-commit [PROJ-123] 새 API 구현` 실행**: 티켓 번호는 `PROJ-123` 사용
- **브랜치 `main`에서 `/pr-without-commit 버그 수정` 실행**: 사용자에게 티켓 번호 입력 요청

## 커밋 기반 브랜치 전환 예시

- **develop 브랜치에서 커밋 후 실행**: 커밋 메시지에서 티켓 번호 추출하여 새 브랜치 생성
- **feature 브랜치에서 커밋 후 실행**: 커밋 메시지 기반으로 적절한 티켓 번호 브랜치로 전환
- **커밋 메시지 예시**: `[MKU-51] API 엔드포인트 추가` → `MKU-51` 브랜치 생성

 

 

해당 기능을 활용하면 손쉽게 PR 작성 과정을 자동화하고, 해당 시점에 우리는 부가적인 작업을 수행하여 생산성을 높일 수 있다. 해당 명령어에 PR 제목이나 내용 형식을 추가한다면, 팀 전반적으로 일관된 PR 작성 규칙을 유지하는 데에도 도움이 될 것이다.

 

 

3. 코드 리뷰 자동화

그 외에도 코드 리뷰 역시 자동화를 통해 생산성을 높일 수 있는 영역이다. Claude Code Custom Command를 활용하여 코드 리뷰 요청을 자동으로 생성하고, 리뷰어를 할당하는 작업을 자동화할 수 있다. 이를 통해 개발자들은 코드 리뷰 프로세스를 간소화하고, 더 빠르게 피드백을 받을 수 있다. GitHub App과 연동하면 코드 리뷰된 항목을 PR에 코멘트로 남기는 작업도 자동화할 수 있다. 해당 부분은 직접 연동해보도록 하자.

 

 

만약 이러한 부분을 직접 구현하고 연동하는 것이 부담스럽다면, 상용 도구 중 하나인 Code Rabbit의 AI Review 도구를 사용할 수도 있다. 이를 활용하면 다음과 같이 개선할 여지가 있는 코드에 코드 리뷰 코멘트를 달아준다.

 

 

 

 

 

 

Custom Command는 Claude Code 사용자들에게 강력한 도구로, 반복적인 작업을 자동화하고 개발 생산성을 높이는 데 큰 도움을 준다. IntelliJ HTTP 파일 생성, PR 생성, 코드 리뷰 자동화 등 다양한 활용 사례를 통해 우리는 개발 프로세스를 더욱 효율적으로 만들 수 있다. 앞으로도 Custom Command를 활용하여 더 많은 작업을 자동화하고, 개발 환경을 개선해 나가면 좋을 것이다.