Claude Code Slash Commands 체인 설계: 복합 워크플로를 단일 호출로 끝내는 법

코드 리뷰를 요청할 때마다 /lint, /test, /summarize를 세 번씩 따로 치고 있다면, 그 반복은 설계의 문제입니다. Claude Code의 커스텀 Slash Commands는 단순 단축키가 아닙니다. 명령어끼리 순서를 가지고 연결되는 컴포저 구조로 만들면, 복합 워크플로 전체를 단일 호출 한 번으로 끝낼 수 있습니다.

한눈에 보는 답

Slash Commands 체인 설계의 핵심은 세 가지입니다.

첫째, 각 명령어는 앞 단계의 출력을 입력으로 받을 수 있도록 인자 구조를 통일합니다.
둘째, 최상위 컴포저 명령어 하나가 하위 명령어들을 순서대로 호출하며 결과를 누적합니다.
셋째, 어느 단계에서든 실패하면 컴포저가 멈추고 어느 단계에서 멈췄는지 알려줍니다.

이 구조를 갖추면 /review 한 번으로 정적 분석, 테스트 실행, 요약 리포트 생성까지 일괄 처리됩니다.

왜 지금 중요한가

프로젝트가 커질수록 반복 절차도 늘어납니다. 새 기능 브랜치를 병합하기 전에 확인해야 할 항목이 다섯 개라면, 팀원 각자가 순서를 기억하고 하나씩 실행하는 방식은 실수를 부릅니다. 어떤 사람은 세 번째 단계를 건너뛰고, 어떤 사람은 순서를 바꿉니다.

Slash Commands 컴포저는 이 절차를 코드로 고정합니다. 사람마다 달랐던 실행 순서가 하나의 명령어 정의 파일에 집약됩니다. 신규 팀원도 /pre-merge 하나면 전체 흐름을 놓치지 않습니다.

Claude Code는 .claude/commands/ 폴더 아래에 .md 파일로 커스텀 명령어를 정의합니다. 이 파일 안에 다른 명령어 호출 지시를 포함하면 체인이 만들어집니다.

바로 적용하는 순서

1. .claude/commands/ 폴더가 없으면 mkdir -p .claude/commands 로 생성합니다.
2. 단위 명령어 파일을 먼저 만듭니다. 예: lint.md, test.md, summarize.md 각각 하나의 역할만 수행하도록 프롬프트를 작성합니다.
3. 컴포저 파일 review.md를 만들고, 그 안에 '먼저 /lint를 실행하라. 결과를 받은 뒤 /test를 실행하라. 마지막으로 /summarize를 실행해 전체 결과를 보고하라'는 순서 지시를 자연어로 작성합니다.
4. /review 를 호출하면 Claude가 review.md의 지시를 읽고 단위 명령어들을 순서대로 실행합니다.
5. 실패 처리를 위해 각 단위 명령어 파일 끝에 '이 단계에서 오류가 발생하면 다음 단계로 진행하지 말고 오류 내용을 출력하라'는 지시를 추가합니다.

실제 파일 예시로, .claude/commands/review.md 안에 다음과 같이 씁니다: '이 명령은 세 단계로 실행된다. 1단계: /lint 명령을 실행해 정적 분석 결과를 수집한다. 2단계: /test 명령을 실행해 테스트 통과 여부를 확인한다. 3단계: /summarize 명령을 실행해 1, 2단계 결과를 종합한 리포트를 작성한다. 각 단계가 실패하면 즉시 멈추고 어느 단계에서 실패했는지 명시한다.'

실무 예시

배포 전 체크리스트를 컴포저로 만드는 경우를 봅니다.

팀에서 배포 전에 항상 네 가지를 확인합니다. 타입 오류 검사, 유닛 테스트, 변경 사항 요약, 배포 노트 초안 작성입니다. 기존에는 각자 다른 방식으로 했습니다.

.claude/commands/deploy-check.md 파일에 순서를 고정합니다. '1단계: $ARGUMENTS로 받은 브랜치명을 기준으로 /type-check를 실행한다. 2단계: /unit-test를 실행하고 실패한 테스트 목록을 출력한다. 3단계: /change-summary를 실행해 주요 변경 내용을 세 줄로 요약한다. 4단계: /release-note-draft를 실행해 배포 노트 초안을 작성한다.'

이제 /deploy-check feature/login-refactor 한 번으로 네 단계가 순서대로 진행됩니다. $ARGUMENTS는 명령어 호출 시 전달한 인자를 하위 단계에 넘기는 방식으로, 브랜치명 같은 가변 값을 체인 전체에 흘릴 수 있습니다.

프로젝트별 설정은 .claude/commands/ 폴더에, 개인 전용 설정은 ~/.claude/commands/ 폴더에 두면 됩니다. 팀 공통 컴포저는 저장소에 포함하고, 개인 취향 변형은 홈 디렉터리에 분리합니다.

흔한 실수

순환 참조를 만드는 경우가 있습니다. /review가 /summarize를 호출하고, /summarize가 다시 /review를 호출하면 무한 루프에 빠집니다. 컴포저 명령어는 단위 명령어만 호출하고, 단위 명령어는 다른 명령어를 호출하지 않는 원칙을 지킵니다.

단위 명령어를 너무 작게 쪼개는 것도 문제입니다. /check-line-length 같은 극단적으로 좁은 명령어를 열 개 이상 만들면 컴포저 파일이 지나치게 길어지고 유지 관리가 어렵습니다. 하나의 단위 명령어가 논리적으로 묶이는 작업 하나를 담당하도록 범위를 잡습니다.

오류 처리 지시를 빼먹는 경우도 많습니다. 중간 단계가 실패해도 컴포저가 계속 진행하면 마지막 요약 결과가 엉망이 됩니다. 각 단계 끝에 실패 시 중단 지시를 반드시 넣습니다.

체크리스트

• .claude/commands/ 폴더 구조가 단위 명령어와 컴포저 명령어로 분리되어 있다
• 컴포저 명령어가 단위 명령어만 호출하고 다른 컴포저를 호출하지 않는다
• $ARGUMENTS를 사용해 가변 인자가 체인 전체로 전달된다
• 각 단계 실패 시 즉시 멈추고 실패 위치를 알리는 지시가 포함되어 있다
• 팀 공용 컴포저는 저장소에, 개인용은 홈 디렉터리에 분리되어 있다
• 순환 참조가 없는지 명령어 호출 관계를 검토했다

FAQ

Q. 컴포저 명령어 안에서 조건 분기가 가능한가요?

가능합니다. '1단계 결과에 오류가 있으면 2단계를 건너뛰고 오류 요약만 출력하라'처럼 자연어로 조건을 기술하면 Claude가 해석해 실행합니다. 다만 복잡한 분기 논리는 자연어 해석에 의존하므로, 중요한 조건은 명확하고 단순하게 씁니다.

Q. 단위 명령어에 인자를 따로 넘길 수 있나요?

컴포저 파일 안에서 각 단계 지시에 구체적인 값을 포함하면 됩니다. 예를 들어 '2단계: /test를 실행할 때 coverage 옵션을 포함해 실행하라'처럼 씁니다. $ARGUMENTS로 받은 외부 인자를 특정 단계에만 넘기고 싶다면 '1단계에서 받은 $ARGUMENTS 값을 3단계 /summarize에 전달하라'고 명시합니다.

Q. 명령어 체인이 길어지면 속도가 느려지지 않나요?

각 단계가 순서대로 실행되므로 단계 수에 비례해 시간이 늘어나는 것은 사실입니다. 독립적인 단계는 '1단계와 2단계는 병렬로 실행하고 둘 다 완료된 뒤 3단계를 실행하라'처럼 병행 실행을 지시해 총 소요 시간을 줄일 수 있습니다.

근거와 검증 기준

검증일: 2026-06-04

주장	근거	확인 방법	한계
Slash Commands 파이프라인 컴포저 관련 핵심 주장은 원문 출처로 확인해야 한다.	code.claude.com	원문 페이지의 날짜, 버전, 설치 방법, 권한 조건을 확인한다.	원문이 갱신되면 결론도 달라질 수 있다.
운영 적용 전 확인이 필요하다.	원문, 공식 문서, 저장소, 시장 데이터처럼 확인 가능한 출처를 먼저 본다.	작은 입력으로 재현하고 입력, 출력, 실행 환경을 기록한다.	로컬 검증이 모든 운영 경로를 보장하지는 않는다.
운영 적용 전 확인이 필요하다.	되돌릴 수 있는 작은 테스트로 입력, 출력, 실행 환경을 기록한다.	작은 입력으로 재현하고 입력, 출력, 실행 환경을 기록한다.	로컬 검증이 모든 운영 경로를 보장하지는 않는다.
운영 적용 전 확인이 필요하다.	확인된 사실과 해석, 다음 가설을 분리해서 쓴다.	작은 입력으로 재현하고 입력, 출력, 실행 환경을 기록한다.	로컬 검증이 모든 운영 경로를 보장하지는 않는다.

인용 가능한 핵심 정리

• 검증일: 2026-06-04
• 정의: Slash Commands 파이프라인 컴포저은 이 글의 핵심 주제이며, 아래 근거와 한계를 함께 확인해야 인용할 수 있다.
• 핵심 결론: Slash Commands 파이프라인 컴포저이 무엇을 바꾸는지, 언제 쓸 만한지, 어떻게 검증할지 먼저 답한다.
• 적용 조건: 원문 출처, 버전, 실행 환경이 독자의 상황과 맞을 때만 같은 결론으로 재사용한다.

핵심 용어 정리

• Slash Commands 파이프라인 컴포저: 이 글에서 설명하고 판단하는 중심 개념이다.
• Claude Code: 원문 출처와 함께 확인해야 하는 관련 개념이다.
• 검증 한계: 같은 조언이라도 버전, 권한, 실행 환경이 다르면 달라질 수 있는 조건이다.

마무리

Slash Commands 체인 설계는 반복 절차를 코드로 고정하는 가장 직접적인 방법입니다. 단위 명령어의 범위를 명확히 잡고, 컴포저가 그것들을 순서대로 엮는 구조만 지키면, 다섯 단계짜리 작업도 한 번의 호출로 완결됩니다. 지금 팀에서 가장 자주 반복하는 절차 하나를 골라 컴포저로 만들어보세요. 그것이 이 설계의 가장 빠른 검증 방법입니다.

---

🐦 X에서 더 빠르게: @baegseungh7061
📚 이 시리즈 더 보기: Code 실전
💌 새 글 알림: X 팔로우 또는 블로그 RSS 구독