반복 프롬프트를 한 단어로 | Custom Commands

Overview

앞 레슨에서 매뉴얼이 두꺼워질 때 Rules로 주제별 파일을 나눠 정리했습니다. 규칙은 정리됐지만, 같은 세션에서 또 다른 반복이 눈에 띕니다. 코드 리뷰·커밋·문서화처럼 자주 쓰는 프롬프트를 매번 똑같이 타이핑하고 있다면, 그 시간도 함께 누적됩니다.

이번 레슨에서는 반복 프롬프트를 마크다운 파일 하나로 저장하고 슬래시 한 단어로 호출하는 Custom Command를 배웁니다.

학습 목표

• Custom Command 가 어떤 문제를 해결하는지 이해합니다
• .claude/commands/ 에 마크다운 파일을 작성해 자신만의 Command 를 만들 수 있습니다
• $ARGUMENTS 와 frontmatter 로 재사용 가능한 Command 를 설계할 수 있습니다

시작하기 전 확인사항

• 실습 프로젝트의 시작 브랜치로 전환합니다 (git checkout ch06-02)

ch06-02 브랜치는 이 레슨의 시작점입니다. Rules 레슨에서 만든 .claude/rules/ 가 이미 포함되어 있습니다.

매번 반복되는 프롬프트의 비용

Claude Code에 커밋 메시지를 부탁할 때마다 같은 말을 반복하고 있다면, 그 시간은 누적됩니다.

방금 변경한 것을 보고 Conventional Commit 형식으로 메시지를 작성해줘. type 은 feat/fix/refactor/chore 중에 적절한 걸로, scope 와 description 까지 같이.

처음에는 괜찮습니다. 하지만 하루에 5번, 일주일이면 25번 같은 프롬프트를 입력합니다. 복사-붙여넣기로 해결할 수도 있지만, 매번 어디에 저장해뒀는지 찾아야 합니다.

Rules가 매뉴얼의 반복을 .claude/rules/ 로 쪼개 해결했다면, 프롬프트의 반복은 .claude/commands/ 로 묶어 해결합니다. 자주 쓰는 프롬프트를 파일 하나에 저장하고 /commit 처럼 슬래시 한 단어로 호출합니다.

Custom Command: 마크다운 파일 하나

Custom Command는 .claude/commands/ 폴더 안의 마크다운 파일입니다. 파일 이름이 곧 Command 이름이 됩니다. commit.md 를 만들면 /commit 으로 호출합니다.

.claude/
  commands/
    commit.md       -> /commit
    doc.md          -> /doc
    review.md       -> /review

Command 를 점진적으로 확장하기

Command 는 처음부터 완성본을 만들 필요가 없습니다. 기본 프롬프트 한 줄에서 시작해 $ARGUMENTS 로 유연성을 더하고, 필요해지면 frontmatter 로 동작을 조정합니다. 같은 파일을 세 단계에 걸쳐 키웁니다.

기본 프롬프트: 마크다운 한 줄

마크다운 파일 하나면 Command가 됩니다. .claude/commands/commit.md 를 다음과 같이 작성합니다.

변경사항을 확인하고 Conventional Commit 형식으로 커밋해줘.

커밋 메시지 규칙:
- 형식: <type>(<scope>): <description>
- type: feat, fix, refactor, test, docs, chore

이제 Claude Code에서 /commit 을 입력하면 이 내용이 프롬프트로 전달됩니다. 매번 같은 말을 타이핑할 필요가 없습니다.

$ARGUMENTS: 호출할 때 입력 전달

Command를 호출할 때 추가 입력을 넘길 수 있습니다. $ARGUMENTS 는 그 입력이 들어가는 자리입니다.

위 commit.md 에 $ARGUMENTS 를 추가해 보겠습니다.

변경사항을 확인하고 Conventional Commit 형식으로 커밋해줘.

$ARGUMENTS 가 있으면 커밋 메시지에 반영해줘.

커밋 메시지 규칙:
- 형식: <type>(<scope>): <description>
- type: feat, fix, refactor, test, docs, chore

/commit 필터 탭 추가 를 입력하면 $ARGUMENTS 자리에 필터 탭 추가 가 들어갑니다. Claude가 변경사항과 이 힌트를 함께 보고 커밋 메시지를 씁니다. 인자 없이 /commit 만 입력해도 Claude가 변경사항을 직접 읽고 메시지를 만듭니다.

frontmatter: 설명·도구·모델 제어

Command 파일 상단에 YAML frontmatter를 추가하면 동작을 더 세밀하게 조정할 수 있습니다.

같은 commit.md 에 frontmatter를 추가합니다.

---
description: "Conventional Commit 형식으로 커밋"
allowed-tools: Bash(git status *) Bash(git diff *) Bash(git add *) Bash(git commit *)
---

변경사항을 확인하고 Conventional Commit 형식으로 커밋해줘.

$ARGUMENTS 가 있으면 커밋 메시지에 반영해줘.

커밋 메시지 규칙:
- 형식: <type>(<scope>): <description>
- type: feat, fix, refactor, test, docs, chore

자주 쓰는 필드는 네 가지입니다.

• allowed-tools: 지정한 도구는 승인 없이 자동 실행됩니다. 처음에는 이 필드 없이 실행한 뒤, 승인을 반복 요청하는 도구를 확인하고 추가합니다. Bash(git diff *) 는 "git diff로 시작하는 모든 명령 허용"이라는 뜻입니다. 괄호 안의 * 가 와일드카드라 뒤따르는 인자에 관계없이 허용하되 git push 같은 다른 명령은 차단합니다. Read, Grep 처럼 도구 이름만 적으면 해당 도구 전체를 허용합니다.
• model: 단순한 포맷 변환에는 haiku 를, 복잡한 아키텍처 리뷰에는 sonnet 을 쓸 수 있습니다.

[실습] Todo 앱에 Command 만들기

지금까지 배운 내용을 적용해서, Todo 앱 프로젝트에서 실제로 쓸 수 있는 Custom Command 를 만들어 보겠습니다.

Step 1: commands 폴더 만들기

프로젝트 루트에 .claude/commands/ 폴더를 만듭니다. .claude/ 가 이미 있다면 commands/ 만 추가합니다.

mkdir -p .claude/commands

Step 2: commit Command 저장하기

앞에서 단계별로 만든 commit.md 의 최종본을 .claude/commands/commit.md 에 저장합니다.

---
description: "Conventional Commit 형식으로 커밋"
allowed-tools: Bash(git status *) Bash(git diff *) Bash(git add *) Bash(git commit *)
---

변경사항을 확인하고 Conventional Commit 형식으로 커밋해줘.

$ARGUMENTS 가 있으면 커밋 메시지에 반영해줘.

커밋 메시지 규칙:
- 형식: <type>(<scope>): <description>
- type: feat, fix, refactor, test, docs, chore

Step 3: Command 사용해보기

저장한 Command 를 실제로 실행해 봅니다. 인자 자리에 작업 요약을 한 줄 적습니다.

/commit 필터 탭 추가

allowed-tools 에 git 명령을 지정해뒀으므로, 승인 없이 변경사항 확인부터 커밋까지 한 번에 끝납니다.

핵심 포인트 정리

1. Custom Command 는 마크다운 파일 하나: .claude/commands/ 에 commit.md 를 넣으면 /commit 으로 호출합니다. 복잡한 설정이 필요 없습니다.
2. 점진적으로 확장하는 구조: 기본 프롬프트 → $ARGUMENTS → frontmatter 순으로 필요한 만큼만 덧붙이면 됩니다.
3. 수동 호출이 핵심: Command 는 직접 / 로 꺼낼 때만 로드됩니다. 자동 로드가 없는 만큼 Context 부담 없이 자주 쓰는 워크플로우를 모아둘 수 있습니다.

FAQ

• Q: Command 파일 안에서 다른 파일을 참조할 수 있나요?

  • A: @ 문법으로 파일을 참조할 수 있습니다. 예를 들어 Command 안에 @./STYLE_GUIDE.md 를 넣으면 해당 파일 내용이 프롬프트에 포함됩니다. 스타일 가이드나 규칙 문서를 참조할 때 유용합니다.

• Q: Command와 CLAUDE.md에 같은 내용을 넣으면 어떤 차이가 있나요?

  • A: CLAUDE.md는 매 대화마다 자동 로드됩니다. Command는 호출할 때만 로드됩니다. 항상 적용되어야 하는 규칙은 CLAUDE.md에, 특정 작업에서만 필요한 프롬프트는 Command에 넣으면 Context를 효율적으로 쓸 수 있습니다.

• Q: Command를 중첩해서 호출할 수 있나요?

  • A: Command 안에서 다른 Command를 직접 호출하는 기능은 지원되지 않습니다. 여러 단계를 하나로 묶고 싶다면, 하나의 Command 파일에 전체 워크플로우를 작성하는 방식이 현재 가장 좋습니다.

• Q: 반복 프롬프트를 텍스트 파일로 저장해두고 복사-붙여넣기하면 안 되나요?

  • A: 기술적으로는 가능하지만 Custom Command가 더 효율적입니다. 텍스트 파일은 저장 위치를 매번 찾아야 하고, 버전 관리도 어렵습니다. Command는 프로젝트 폴더 안에서 git으로 관리되고, / 한 번으로 즉시 호출되며, $ARGUMENTS 로 재사용 가능합니다.

이어서 배울 내용

Custom Command로 반복 프롬프트를 제거했지만, 프로젝트가 커지면 또 다른 문제가 생깁니다. 코드 리뷰 규칙·배포 절차·테스트 전략처럼 지침이 늘면 CLAUDE.md가 다시 비대해지고, Rules로 쪼개도 전역 규칙이 쌓이면 지침의 저주가 반복됩니다.

다음 레슨에서는 이 한계를 해결하는 새로운 기능 Skill 을 배웁니다.