[Claude Code] 커스텀 명령어 설정하기

1. 커스텀 명령어란?

- 기본으로 제공하는 명령어들 외에 개인이 직접 추가할 수 있는 명령어

- 반복적인 작업들을 간단한 명령어로 자동화할 수 있음

- 클로드 코드의 경우에는 마크다운 파일로 정의 가능함

 

 

2. 커스텀 명령의 범위

1) 전역 명령어

- 모든 프로젝트에 공통으로 적용

- 경로: ~/.claude/commands/

 

2) 프로젝트 명령어

- 현재 작업중인 프로젝트에 적용

- 경로: .claude/commands/

 

 

3. 커스텀 명령어 적용법

- commands 폴더에 [명령어].md 이름의 파일을 생성하고 그 안에 프롬프트를 넣으면, 클로드 코드에서 /[명령어] 로 실행할 수 있다.

- 아래 예시에서는 /analyze, /deploy, /fix-issue 명령을 사용할 수 있게 된 것이다.

 

- 각 마크다운 파일에는 해당 명령 실행시 수행할 작업을 지시하면 된다. 간단한 예시로, 배포를 위한 /deploy 동작을 지시해보았다.

<!-- .claude/commands/deploy.md -->
---
allowed-tools: Bash, Read
argument-hint: [environment]
description: 지정한 환경으로 배포 전 체크리스트 실행
---

## 현재 브랜치
!`git branch --show-current`

## 미커밋 변경사항
!`git status`

## 테스트 결과
!`npm test 2>&1`

## 빌드 결과
!`npm run build 2>&1`

## 환경변수 파일 확인
!`ls .env.$1 2>&1`

위 결과를 바탕으로:
1. 각 단계의 성공/실패 여부를 정리해주세요
2. 실패한 단계가 있으면 즉시 중단하고 이유와 해결 방법을 설명해주세요
3. 모든 단계가 통과되면 $1 환경으로 배포해도 좋다고 최종 확인해주세요

 

참고)

- ! 기호

• 실제로 명령을 실행하라는 의미. !를 제외하면 명령을 미리 실행해서 결과를 컨텍스트에 넣는 대신, Claude가 스스로 판단해서 필요할 때 실행하게 된다. 순서나 타이밍을 보장할 수 없어서 의도한 대로 동작하지 않을 수 있다.

- argument-hint

• argument-hint로 명령 옵션(인수)을 주었다. /deploy test 나 /deploy production 과 같이 사용하면 된다. 인수들은 마크다운 파일 내에서 $1, $2... 과 같이 변수로 사용 가능하다. 위 예시에서는 첫 번째 인수밖에 없기 때문에 $1로 받는 내용만 있다.
• $ARGUMENTS 라는 변수도 제공하는데, 모든 인수를 통째로 하나의 문자열로 받는 경우 사용한다.
• 문장을 인수로 주고 싶다면, /deploy "fix login bug" production 과 같이 큰 따옴표로 감싸 하나의 인수로 만들면 된다.

 

파일을 저장하고 Claude Code를 다시 실행했더니, 명령어 목록에 /deploy가 잘 뜨는 모습이다!

 

argument-hint 에 대한 placeholder 까지 잘 적용된 모습이다.

 

 

4. 스킬과의 차이점

/context를 통해 Skills를 확인할 수 있는데, 커스텀 명령어와 유사한 개념이다. 스킬은 다음과 같은 차이점이 있다.

- .claude/skills/ 디렉토리에 md 파일로 설정

- /명령어 형태로 직접 실행하는 대신, 클로드 코드가 요청의 성격을 파악해서 자동으로 적합한 스킬을 불러와 실행한다.

 

기회가 된다면 Skills에 대해 상세히 설명하는 포스팅을 올려보고자 한다.

 

 

5. 더 스마트하게 활용하기

커스텀 명령의 내부 동작 과정이 길다면 맨 아래에 이런 문구를 붙히면 좋다.

각 단계별로 실패하면 즉시 중단하고 해당 단계에서 발생한 오류를 보고해줘.

 

커스텀 명령어를 클로드 코드에게 스스로 만들게 하는 방법도 활용해볼 수 있다.

.claude/commands/[명령어].md를 만들어서 다음 작업을 순서대로 수행하게 해줘.

1. ...
2. ...
3. ...
...

각 단계별로 실패하면 즉시 중단하고 해당 단계에서 발생한 오류를 보고해줘.

 

구체적인 과정을 어떻게 구상해야할지 잘 모르겠다면, 클로드 코드에게 원하는 기능을 명시하고 해당 기능에 필요한 커스텀 명령들을 직접 구상하고 만들어달라고 할 수도 있다.