Free

Slash Command 심화: 서브에이전트와 도구 연계

@file 참조, allowed-tools, 서브에이전트, MCP 도구로 slash command를 단축키에서 팀 워크플로 라이브러리로 업그레이드한다.

앞의 두 편에서는 slash command가 무엇인지(Markdown 파일 하나), 그리고 ! 접두사로 shell 출력을 context에 주입하는 법을 다뤘다. 이번 편은 더 무거운 주제다—하나의 command로 Claude Code의 가장 강력한 기능들(파일 참조, 서브에이전트, MCP 도구)을 편성하고, 권한까지 제대로 관리하는 법.

이 수준에 오면 command는 더 이상 "프롬프트 단축키"가 아니라, 재사용 가능한 작은 워크플로가 된다.

@file 참조: !cat보다 적합한 정적 주입

!cat file.md도 파일 내용을 context에 넣을 수 있지만, shell을 거치기 때문에 단점이 있다. 매번 서브프로세스가 뜨고, 경로에 공백이나 특수 문자가 있으면 이스케이프가 필요하며, Claude Code는 그걸 "파일 하나"가 아니라 그냥 텍스트로 본다.

@ 참조는 네이티브다.

---
description: 프로젝트 규약에 맞춰 변경 사항 리뷰
---

참고 규약:

@.claude/context/coding-standards.md
@.claude/context/security-checklist.md

아래 git diff의 변경 사항을 리뷰하고, 규약 위반 부분을 모두 짚어주세요.

!`git diff HEAD`

@경로는 Claude Code에 "이 파일을 첨부로 대화에 붙여라"라고 지시한다. 차이는 이렇다.

상황 !cat 사용 @ 사용
경로가 인수($ARGUMENTS)에서 옴 ✅ !cat만 가능 ❌ @는 변수 확장 안 됨
고정된 규약·템플릿 ⚠️ 가능하지만 무거움 ✅ 네이티브, shell 생략
동적 콘텐츠(diff·로그·테스트 결과) ✅ ! 필수 ❌ 불가

원칙: 정적 파일은 @, 동적 출력은 !, 인수 경로는 !cat $ARGUMENTS.

allowed-tools: command에 권한 경계 설정

기본적으로 command 실행 중 모델은 세션의 모든 도구를 쓸 수 있다. 이게 원하는 게 아닐 때가 있다—예컨대 /review는 읽기 전용 리뷰인데, 모델이 "이왕 하는 김에" 한 줄 고치는 건 반갑지 않다.

frontmatter에 allowed-tools를 추가하면, command가 도는 동안 나열된 도구만 쓸 수 있게 된다.

---
description: 읽기 전용 코드 리뷰
allowed-tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*)
---

현재 브랜치와 master의 차이를 리뷰. 읽기만 하고 수정은 하지 말 것.

!`git diff master...HEAD`

핵심 포인트:

  • Bash(git diff:*)는 세밀한 권한 부여—git diff로 시작하는 bash 호출만 허용, git push는 차단된다
  • Read / Grep / Glob은 명시적으로 읽기 전용 도구만 부여
  • Edit / Write는 나열하지 않았으니, 모델이 수정하려 해도 호출이 안 된다

반대로 /deploy 같은 고권한 command에서도 같은 방식이 먹힌다.

---
description: 현재 브랜치 배포
allowed-tools: Bash(kamal deploy:*), Bash(git push:*), Read
---

"이 command가 무엇을 할 수 있는지"를 못 박아두는 편이, 실행할 때마다 사람 손으로 bash 승인을 받는 것보다 훨씬 믿을 만하다.

서브에이전트 호출: context 잡아먹는 작업을 격리

메인 대화의 context를 순식간에 터뜨리는 작업들이 있다—수십 파일을 돌며 함수의 모든 호출 지점 찾기, 코드베이스 전체 통계 내기, 큰 로그를 긁어서 분석하기. 이걸 메인 대화에서 직접 하면 수천 줄 출력이 context에 남아 이후 대화가 느리고 둔해진다.

정답은 그 일을 subagent에 맡기는 것. 서브에이전트는 독립된 context에서 돌고, 끝나면 결론만 메인 대화로 돌려준다. command에서는 명시적으로 지시만 하면 된다.

---
description: 특정 심볼의 모든 사용처 심층 조사
allowed-tools: Task
---

Explore 서브에이전트로 다음 심볼의 모든 사용처를 심층 조사: $ARGUMENTS

서브에이전트는 다음을 다룰 것:
- 모든 호출 지점(테스트 파일 포함)
- 커버되는 비즈니스 시나리오
- 동등한 대체 구현 존재 여부

서브에이전트가 돌아오면 300자 이하 요약만 돌려줄 것. 원본 코드 조각은 붙이지 말 것.

/trace SomeClass#some_method를 실행하면 Claude Code가 Explore 서브에이전트를 띄워 코드베이스를 병렬로 스캔하고, 메인 대화에는 정제된 결론만 돌아온다. grep 출력도 파일 조각도 없이, context는 깔끔하게 유지된다.

한 걸음 더:

---
description: 세 가지 후보안 병렬 조사
allowed-tools: Task
---

서브에이전트 3개를 병렬로 띄워, 각자 다음 구현 경로를 조사:

1. 기존 ActiveJob + Sidekiq
2. Solid Queue
3. 자체 경량 큐

각 에이전트는: 작업량, 리스크, 기존 코드에 미치는 침습도를 답할 것. 세 결론이 다 오면 비교는 내가 한다.

3개의 서브에이전트가 동시에 돌고, 메인 대화는 한 번만 기다리면 된다. command가 제공하는 가장 큰 레버리지 중 하나다—"결론을 얻는 데 토큰이 많이 드는 조사 태스크"를 원클릭 워크플로로 만드는 것.

MCP 도구 호출: command를 외부 시스템에 연결

세션에 MCP 서버(Linear, GitHub, Sentry, 자체 DB 프록시 등)가 붙어 있다면, command에서 모델에 직접 이 도구들을 쓰도록 지시할 수 있다.

---
description: Linear issue에서 구현 todo 생성
allowed-tools: mcp__linear__*, Read, Grep
---

Linear issue $ARGUMENTS의 전체 설명과 댓글을 가져오세요.

코드베이스 현황(Grep/Read로 관련 파일 직접 탐색)과 결합해 구현 todo 작성:
- 어느 파일을 수정해야 하는지
- 각 단계가 독립 커밋인지, 한 번에 묶는지
- PM에게 먼저 확인할 모호한 지점

코드는 쓰지 말고 계획만 낼 것.

mcp__linear__*는 모든 Linear MCP 도구를 허용하므로, 모델이 issue 상세·댓글·상태를 가져올 수 있다. command 전체가 "티켓에서 구현 계획으로" 가는 워크플로의 입구가 된다.

주의: allowed-tools에 MCP 도구 이름을 쓸 때는 전체 접두사(mcp__<서버>__<도구>)를 써야 한다. 그렇지 않으면 권한이 적용되지 않는다.

command 조합의 함정: slash는 재귀 확장되지 않는다

흔한 오해: /review의 파일 안에 /test라고 쓰면 test command가 트리거될 거라 생각하는 것. 안 된다. slash command는 사용자 입력의 최상위에서 단 한 번만 확장된다. command 내부의 /xxx는 그냥 텍스트다—모델은 읽지만 Claude Code는 실행하지 않는다.

여러 command를 조합하려면 다음과 같은 방법이 맞다.

방법 A: 공용 로직을 context 파일로 빼고, 각 command에서 @나 !cat으로 참조

@.claude/context/review-checklist.md
@.claude/context/security-checklist.md

방법 B: command 안에 "/review와 똑같이 하라"고 쓰고 핵심 지시를 반복

우아하진 않지만 잘 먹힌다. 프롬프트가 분명하면 모델은 같은 방식으로 처리한다.

방법 C: 한 command가 Task 도구로 서브에이전트를 띄우고, 서브에이전트 프롬프트에서 같은 context 파일들을 재사용

진짜 워크플로 오케스트레이션은 결국 다 이 길로 간다. 부모 command가 조정과 집계를 맡고, 서브에이전트가 실제 단계를 수행한다.

피해야 할 안티패턴: 하나의 command를 수백 줄로 써서 한 번의 지시로 전부 하려는 것. 입자도가 깨지면 유지 비용이 폭증하고, 한 번의 실행이 토큰 예산을 다 잡아먹는다.

세 무기의 사용 시점

@, !, 서브에이전트, MCP 도구까지 갖춰지면 Claude Code에서 command에 "외부 능력"을 주입하는 메커니즘은 거의 다 나왔다. 선택법:

필요 1순위
고정된 규약·템플릿·컨텍스트 문서 @file 참조
실시간 상태(diff·로그·테스트 결과·DB 쿼리) !shell 주입
매개변수화된 파일 내용 !cat $ARGUMENTS
context를 먹는 조사·크로스 파일 검색 Task 경유 서브에이전트
외부 시스템(이슈 트래커·모니터링·프로덕션 데이터) MCP 도구 + allowed-tools
다단계 직렬/병렬 워크플로 부모 command가 서브에이전트 조정

권한 경계는 allowed-tools로 명시적으로 선언하자. 특히 팀이 공유하는 command라면—할 수 있는 일을 못 박아두는 편이 매번 수동 승인에 기대는 것보다 믿을 만하다.

프로덕션에 가까운 예시

지금까지의 내용을 다 합쳐본다—"Linear ticket에서 구현 경로 조사"하는 command:

---
description: Linear ticket에서 구현 방안 생성
allowed-tools: mcp__linear__*, Task, Read, Grep, Glob, Bash(git log:*)
---

## 컨텍스트

@.claude/context/architecture.md
@.claude/context/coding-standards.md

## 현재 리포 상태

!`git log --oneline -10`

## 태스크

Linear ticket $ARGUMENTS의 설명, 댓글, 연관 ticket을 가져오세요.

이어서 서브에이전트 2개를 병렬로 띄움:
1. 첫 번째: 코드베이스에서 관련된 기존 구현과 재사용 가능한 모듈 탐색
2. 두 번째: 리스크 평가—이 변경이 건드리는 고트래픽 경로, 테스트 커버리지 누락 지점

둘 다 돌아오면 출력:
- 구현 단계(의존 순서대로)
- 리스크 목록
- 권장 커밋 입자도

코드는 쓰지 말 것.

/plan ENG-4213을 실행하면 하나의 command가 전 과정을 돈다: 티켓 로딩 → 코드베이스 병렬 조사 → 리스크 평가 → 방안 집계. 사용자가 할 일은 결과물을 보고 시작할지 결정하는 것뿐이다.

이걸로 slash command 시리즈 첫 세 편의 호가 닫힌다: 재사용 가능한 프롬프트 정의(intro) → 동적 컨텍스트 주입(context) → 도구와 서브에이전트 편성(이번 편). 이 수준까지 오면 .claude/commands/는 더 이상 단축키 디렉터리가 아니라, 팀이 공유하는 작은 워크플로 라이브러리다.