[opencode 12일 집중 — 터미널 네이티브 AI 코딩 에이전트 완전 정복] 8/12화: opencode 커스텀 슬래시 커맨드 만들기 — Named Arguments 실전 가이드

이 글은 「opencode 12일 집중」 8일차로, opencode의 슬래시 커맨드를 직접 만들고 활용하는 방법을 다룹니다.

어제(7일차)는 AGENTS.md로 프로젝트의 컨텍스트를 에이전트에 주입하는 방법을 다뤘습니다. 오늘부터는 Phase 3 확장·고급 편입니다. 첫 주제는 커스텀 슬래시 커맨드 — 매번 비슷한 프롬프트를 치는 반복 노동에서 벗어나는 가장 직접적인 방법입니다.

오늘의 핵심 3가지

• 마크다운 파일 하나가 곧 슬래시 커맨드다 — .opencode/commands/에 .md 파일을 놓으면 /project:이름으로 즉시 호출됩니다.
• $ARGUMENTS와 Named Placeholder로 입력값을 동적으로 주입할 수 있습니다. $FILE, $LANGUAGE 같은 변수를 선언하면 실행 시 입력창이 뜹니다.
• 프론트매터(YAML)로 커맨드에 설명을 달고, 팀 전체가 git으로 공유할 수 있습니다.

슬래시 커맨드, 왜 필요한가

코드 리뷰를 요청할 때마다 이런 프롬프트를 치고 있진 않으신가요?

"이 파일을 리뷰해줘. 보안 취약점, 성능 이슈, 코딩 컨벤션 위반을 중점적으로 봐줘.
결과는 심각도별로 정리하고, 각 항목에 수정 제안을 포함해줘."

매번 이걸 타이핑하거나 어딘가에서 복사해 오는 건 비효율적입니다. AGENTS.md가 프로젝트의 정적 맥락을 잡아준다면, 커스텀 슬래시 커맨드는 반복되는 작업 패턴을 재사용 가능한 단위로 만들어 줍니다.

opencode의 커스텀 커맨드는 놀라울 정도로 단순합니다. 마크다운 파일 하나가 곧 커맨드입니다. 별도의 플러그인 시스템도, 복잡한 DSL도 없습니다.

커맨드의 두 가지 스코프

opencode는 커맨드를 두 곳에서 찾습니다.

1. 프로젝트 커맨드 — 팀과 공유

# 프로젝트 루트 기준
.opencode/commands/review.md      → /project:review
.opencode/commands/test-gen.md    → /project:test-gen
.opencode/commands/docs/api.md    → /project:docs/api

프로젝트 디렉터리의 .opencode/commands/ 아래에 놓은 .md 파일은 /project:파일명으로 호출됩니다. 하위 폴더를 만들면 /project:폴더/파일명 형태로 네임스페이스가 잡힙니다.

이 파일들은 git에 커밋할 수 있습니다. 팀원 전체가 동일한 커맨드 세트를 공유하게 되는 셈입니다. 7일차에서 다룬 AGENTS.md와 함께 커밋하면, 프로젝트의 AI 워크플로우가 코드베이스에 버전 관리되는 효과를 얻습니다.

2. 유저 커맨드 — 개인 습관

# 글로벌 설정 디렉터리
~/.config/opencode/commands/explain.md   → /user:explain
~/.config/opencode/commands/refactor.md  → /user:refactor

개인 홈 디렉터리의 전역 설정 경로에 놓은 커맨드는 /user:이름으로 호출됩니다. 어떤 프로젝트에서든 사용할 수 있는 개인용 매크로입니다.

정리하면 이렇습니다.

• /project:* — 이 프로젝트에서만. git으로 팀 공유 가능.
• /user:* — 모든 프로젝트에서. 내 머신에만 존재.

TUI에서 /를 입력하면 사용 가능한 모든 커맨드(내장 + 프로젝트 + 유저)가 퍼지 검색 목록으로 나타납니다. 4일차에서 다룬 TUI 단축키와 자연스럽게 이어지는 부분입니다.

첫 번째 커맨드 만들기

바로 실습해 보겠습니다. 코드 리뷰 커맨드를 만들어 봅시다.

실습: /project:review 만들기

# 디렉터리 생성
mkdir -p .opencode/commands

# 커맨드 파일 작성
cat > .opencode/commands/review.md << 'EOF'
---
description: 코드 리뷰 수행 — 보안·성능·컨벤션 중심
---

아래 파일을 코드 리뷰해 주세요.

## 리뷰 기준

1. **보안 취약점**: 인젝션, 인증 우회, 민감 정보 노출
2. **성능 이슈**: N+1 쿼리, 불필요한 루프, 메모리 누수 가능성
3. **코딩 컨벤션**: 프로젝트 스타일 가이드 준수 여부

## 출력 형식

심각도(Critical/Warning/Info)별로 그룹화하고,
각 항목에 **파일:라인** + **수정 제안 코드 블록**을 포함해 주세요.

$ARGUMENTS
EOF

이제 opencode TUI에서 이렇게 사용합니다.

/project:review src/auth/login.ts

$ARGUMENTS 자리에 src/auth/login.ts가 들어갑니다. 커맨드 뒤에 적은 모든 텍스트가 $ARGUMENTS를 대체합니다.

프론트매터(Frontmatter)의 역할

파일 상단의 YAML 프론트매터(---로 감싼 블록)는 커맨드의 메타데이터입니다.

---
description: 코드 리뷰 수행 — 보안·성능·컨벤션 중심
---

description 필드의 값은 TUI의 커맨드 목록에서 커맨드 이름 옆에 표시됩니다. /를 눌러 커맨드를 탐색할 때 이 설명이 보이므로, 팀원이 커맨드의 용도를 파악하는 데 도움이 됩니다.

프론트매터는 선택사항입니다. 없어도 커맨드는 정상 동작합니다. 하지만 커맨드가 늘어날수록 설명이 있는 편이 관리하기 수월합니다.

$ARGUMENTS — 자유 형식 입력

$ARGUMENTS는 가장 기본적인 입력 메커니즘입니다. 슬래시 커맨드 뒤에 사용자가 적은 텍스트 전체가 이 자리에 들어갑니다.

---
description: 함수 단위 설명 생성
---

다음 코드를 분석하고 한국어로 설명해 주세요.
각 매개변수의 역할, 반환값, 부수효과(side effect)가 있다면 명시해 주세요.

$ARGUMENTS

호출 예시:

/project:explain calculateRiskScore 함수 — src/risk/engine.ts에 있음

$ARGUMENTS에 calculateRiskScore 함수 — src/risk/engine.ts에 있음 전체가 치환됩니다. 간단하고 직관적입니다.

하지만 $ARGUMENTS 하나로는 부족한 상황이 있습니다. 여러 개의 서로 다른 값을 구조적으로 받고 싶을 때 — 그래서 Named Arguments가 존재합니다.

Named Arguments — 구조화된 다중 입력

커맨드 템플릿 안에 $ARGUMENTS 대신 $VARIABLE_NAME 형태의 이름 붙은 플레이스홀더를 사용하면, opencode가 각 변수에 대해 개별 입력창을 띄워 줍니다.

실습: 다중 인자 커맨드 만들기

cat > .opencode/commands/test-gen.md << 'EOF'
---
description: 테스트 코드 생성기 — 언어·프레임워크·파일 지정
---

다음 조건에 맞는 테스트 코드를 생성해 주세요.

- **대상 파일**: $FILE
- **테스트 프레임워크**: $FRAMEWORK
- **커버리지 목표**: $COVERAGE

## 요구사항

1. 정상 경로(happy path)와 예외 경로(edge case)를 모두 포함
2. 각 테스트에 한국어 설명 주석 추가
3. Given-When-Then 패턴 사용
4. mock/stub이 필요한 외부 의존성은 명시적으로 분리

대상 파일을 먼저 읽고 분석한 뒤 테스트를 작성해 주세요.
EOF

이 커맨드를 호출하면:

/project:test-gen

opencode가 순서대로 세 가지를 물어봅니다.

1. FILE — 대상 파일 경로 입력
2. FRAMEWORK — 테스트 프레임워크 입력 (예: vitest, pytest, jest)
3. COVERAGE — 커버리지 목표 입력 (예: 80%, 핵심 로직 100%)

각 값이 템플릿의 해당 위치에 치환되어 최종 프롬프트가 완성됩니다. $ARGUMENTS처럼 모든 걸 한 줄에 적을 필요 없이, 구조화된 입력을 받을 수 있습니다.

Named Arguments 작명 규칙

• 변수 이름은 $ + 대문자 영문자/숫자/밑줄로 구성합니다. 예: $FILE, $TEST_TYPE, $TARGET_DIR
• 같은 변수를 템플릿 안에서 여러 번 사용하면, 입력은 한 번만 받되 모든 위치에 동일한 값이 들어갑니다.
• $ARGUMENTS와 Named Arguments를 한 파일에 섞어 쓸 수도 있지만, 가독성을 위해 하나의 패턴으로 통일하는 것을 권장합니다.

실전 커맨드 레시피 5선

실무에서 바로 쓸 수 있는 커맨드를 다섯 가지 소개합니다. 복사해서 .opencode/commands/에 저장하세요.

1. 커밋 메시지 생성기

cat > .opencode/commands/commit-msg.md << 'EOF'
---
description: Conventional Commit 형식 커밋 메시지 생성
---

현재 git diff (staged 기준)를 분석하고,
Conventional Commits 형식의 커밋 메시지를 작성해 주세요.

형식: (): 

- type: feat, fix, refactor, docs, test, chore, build 중 선택
- scope: 변경된 모듈/디렉터리 이름
- subject: 50자 이내 영문 (명령형)

본문(body)은 한국어로, 왜 이 변경이 필요한지 2~3줄로 설명해 주세요.
Breaking change가 있으면 BREAKING CHANGE: 푸터를 추가해 주세요.
EOF

사용법: /project:commit-msg — 별도 인자 없이 현재 diff를 자동으로 분석합니다.

2. API 엔드포인트 스캐폴딩

cat > .opencode/commands/api-scaffold.md << 'EOF'
---
description: REST API 엔드포인트 보일러플레이트 생성
---

다음 사양으로 API 엔드포인트를 생성해 주세요.

- **리소스 이름**: $RESOURCE
- **HTTP 메서드**: $METHOD
- **프레임워크**: $FRAMEWORK

## 생성 파일 목록

1. 라우터/컨트롤러
2. 요청/응답 DTO (유효성 검증 포함)
3. 서비스 레이어 (비즈니스 로직 스텁)
4. 단위 테스트 파일

기존 프로젝트의 디렉터리 구조와 네이밍 컨벤션을 따라 주세요.
AGENTS.md에 컨벤션 정보가 있으면 참고해 주세요.
EOF

사용법: /project:api-scaffold → RESOURCE(예: user-profile), METHOD(예: GET, POST), FRAMEWORK(예: FastAPI, Express)를 차례로 입력합니다.

3. 마이그레이션 리뷰어

cat > .opencode/commands/migration-check.md << 'EOF'
---
description: DB 마이그레이션 파일 안전성 점검
---

다음 마이그레이션 파일을 점검해 주세요.

대상: $FILE

## 점검 항목

1. **하위 호환성**: 기존 데이터가 유실되거나 깨지는 구문이 없는가
2. **롤백 가능성**: down 마이그레이션이 정상 작동하는가
3. **잠금(lock) 위험**: 대규모 테이블에 ALTER 시 락 시간 추정
4. **인덱스**: 새 컬럼에 필요한 인덱스가 누락되지 않았는가
5. **NULL 처리**: NOT NULL 추가 시 기본값 전략이 있는가

프로덕션 환경(수백만 행 테이블)을 가정하고 분석해 주세요.
EOF

4. 의존성 업그레이드 분석

cat > .opencode/commands/dep-upgrade.md << 'EOF'
---
description: 패키지 업그레이드 영향도 분석
---

$PACKAGE를 $FROM_VERSION에서 $TO_VERSION으로 업그레이드하려고 합니다.

다음을 분석해 주세요.

1. **Breaking Changes**: 해당 버전 구간의 주요 변경사항
2. **영향 범위**: 프로젝트에서 이 패키지를 사용하는 파일 목록
3. **마이그레이션 필요 코드**: 수정이 필요한 부분과 수정 방법
4. **테스트 영향**: 기존 테스트 중 깨질 가능성이 있는 것

가능하면 changelog 정보 기반으로 구체적으로 답변해 주세요.
EOF

네 개의 Named Arguments($PACKAGE, $FROM_VERSION, $TO_VERSION)가 순서대로 입력창에 나타납니다.

5. PR 설명 생성기

cat > .opencode/commands/pr-desc.md << 'EOF'
---
description: Pull Request 설명 자동 생성
---

현재 브랜치의 커밋 히스토리와 변경된 파일을 분석해서
PR 설명을 작성해 주세요.

## 형식

### 개요
(이 PR이 해결하는 문제를 2~3줄로)

### 변경 사항
(파일/모듈별 주요 변경을 불릿으로)

### 테스트
(어떤 테스트를 추가/수정했는지, 수동 테스트가 필요하면 절차)

### 체크리스트
- [ ] 유닛 테스트 통과
- [ ] lint/format 통과
- [ ] 문서 업데이트 (해당 시)
- [ ] 마이그레이션 (해당 시)

$ARGUMENTS
EOF

사용법: /project:pr-desc 관련 이슈: #142 — $ARGUMENTS로 추가 맥락을 넘길 수 있습니다. 인자 없이 /project:pr-desc만 쳐도 동작합니다. $ARGUMENTS가 비어 있으면 해당 부분이 빈 문자열로 치환됩니다.

슬래시 커맨드 설계 팁

하나의 커맨드, 하나의 목적

커맨드 하나에 너무 많은 걸 담으면 프롬프트가 길어지고 결과 품질이 떨어집니다. “리뷰하고 테스트 생성하고 문서도 써 줘”보다는 /project:review, /project:test-gen, /project:docs로 분리하는 게 낫습니다.

AGENTS.md와의 협업

커맨드 템플릿 안에 프로젝트 컨벤션을 일일이 적을 필요 없습니다. “AGENTS.md에 정의된 컨벤션을 따라 주세요”라는 한 줄이면 충분합니다. opencode는 커맨드를 실행할 때 AGENTS.md를 이미 컨텍스트에 포함하고 있으므로, 중복 없이 두 레이어가 협력합니다.

• AGENTS.md = “이 프로젝트는 이런 곳이야” (정적 맥락)
• 커스텀 커맨드 = “이 작업은 이렇게 해 줘” (동적 지시)

하위 폴더로 카테고리 관리

커맨드가 10개를 넘어가면 카테고리별 하위 폴더가 유용합니다.

.opencode/commands/
├── review/
│   ├── security.md     → /project:review/security
│   ├── performance.md  → /project:review/performance
│   └── style.md        → /project:review/style
├── gen/
│   ├── test.md         → /project:gen/test
│   ├── docs.md         → /project:gen/docs
│   └── api.md          → /project:gen/api
└── ops/
    ├── commit-msg.md   → /project:ops/commit-msg
    └── pr-desc.md      → /project:ops/pr-desc

TUI에서 /project:review/까지만 치면 하위 커맨드들이 퍼지 검색으로 필터링됩니다.

팀 공유 전략

.opencode/commands/는 git에 커밋합니다. PR 리뷰를 통해 팀의 커맨드 품질을 관리하세요.

# .gitignore — 커맨드 디렉터리는 추적 대상
# (기본적으로 .opencode/ 전체를 ignore하고 있다면 예외 추가)
!.opencode/commands/

신규 팀원이 합류하면 git clone만으로 프로젝트의 AI 워크플로우가 함께 따라옵니다. AGENTS.md(7일차) + 커스텀 커맨드(오늘)를 합치면, 팀의 AI 사용 패턴이 코드베이스에 버전 관리되는 셈입니다.

고급 패턴: 컨텍스트 파일 참조와 조합

@ 파일 참조와 슬래시 커맨드 조합

4일차에서 다룬 @ 파일 퍼지 검색을 슬래시 커맨드와 함께 쓸 수 있습니다. 커맨드가 실행된 후에도 대화가 이어지므로, 추가 파일을 @로 첨부하며 맥락을 보충할 수 있습니다.

# 먼저 커맨드로 리뷰 시작
/project:review src/auth/login.ts

# 에이전트 응답 후, 관련 파일 추가 컨텍스트로 제공
"@src/auth/types.ts 이 타입 정의도 함께 보고 리뷰 보완해 줘"

커맨드 체이닝 패턴

하나의 세션에서 여러 커맨드를 순서대로 실행하는 것도 자연스럽습니다.

# 1단계: 코드 리뷰
/project:review src/payment/processor.ts

# (리뷰 결과 확인 후)

# 2단계: 리뷰에서 발견된 이슈를 바탕으로 테스트 보강
/project:test-gen
  → FILE: src/payment/processor.ts
  → FRAMEWORK: jest
  → COVERAGE: 리뷰에서 지적된 edge case 중심

# 3단계: 커밋 메시지 생성
/project:commit-msg

각 커맨드의 결과가 세션 컨텍스트에 남아 있으므로, 이전 단계의 출력을 다음 단계가 참조할 수 있습니다.

유저 커맨드 — 프로젝트를 넘어서

프로젝트에 종속되지 않는 개인 습관은 유저 커맨드로 만듭니다.

# 글로벌 커맨드 디렉터리 생성
mkdir -p ~/.config/opencode/commands

# 범용 설명 커맨드
cat > ~/.config/opencode/commands/explain.md << 'EOF'
---
description: 코드 조각을 초보자 눈높이로 설명
---

다음 코드를 설명해 주세요.

- 대상 독자: 주니어 개발자 (경력 1년 미만)
- 한국어로 설명
- 각 줄의 역할을 주석으로 달아 주세요
- 사용된 패턴이나 관용구가 있으면 이름과 함께 설명

$ARGUMENTS
EOF

# 범용 리팩터링 커맨드
cat > ~/.config/opencode/commands/refactor.md << 'EOF'
---
description: 리팩터링 제안 — 동작 변경 없이 구조 개선
---

다음 코드를 리팩터링해 주세요.

## 원칙
- 외부에서 본 동작(입출력)은 변경하지 않는다
- 가독성, 유지보수성, 테스트 용이성 향상에 집중
- 변경 전후를 diff로 보여준다

## 기법 우선순위
1. 함수 추출 (Extract Function)
2. 조기 반환 (Early Return)
3. 매직 넘버 → 상수
4. 중첩 조건문 평탄화

$ARGUMENTS
EOF

이제 어느 프로젝트에서든 /user:explain, /user:refactor를 바로 사용할 수 있습니다.

Gotcha 미니 코너

함정: $HOME이나 $PATH 같은 셸 환경변수와 이름 충돌

Named Arguments의 변수명은 $로 시작합니다. 만약 $HOME, $PATH, $USER처럼 셸 환경변수와 동일한 이름을 쓰면 어떻게 될까요? opencode의 커맨드 파서는 셸과 분리되어 있어서 직접적인 충돌은 발생하지 않지만, 커맨드 파일을 heredoc(<< EOF)이나 echo로 생성할 때 셸이 먼저 변수를 치환해 버립니다.

# 잘못된 예 — 셸이 $FILE을 빈 문자열로 치환해 버림
cat > .opencode/commands/bad.md << EOF
대상 파일: $FILE
EOF

# 올바른 예 — 작은따옴표 EOF로 치환 방지
cat > .opencode/commands/good.md << 'EOF'
대상 파일: $FILE
EOF

<< 'EOF'(따옴표 있음)와 << EOF(따옴표 없음)의 차이입니다. 이 글의 모든 실습 예제는 'EOF'를 쓰고 있으니 그대로 복사하면 안전합니다. 에디터로 직접 파일을 만들 때는 이 문제가 없습니다.

정리

커스텀 슬래시 커맨드는 단순한 편의 기능이 아닙니다. 팀의 AI 워크플로우를 표준화하고 버전 관리하는 인프라입니다.

• .opencode/commands/*.md → /project:이름 (팀 공유, git 커밋)
• ~/.config/opencode/commands/*.md → /user:이름 (개인용, 전역)
• $ARGUMENTS로 자유 입력, Named Arguments($VARIABLE)로 구조화된 입력
• 프론트매터 description으로 TUI 목록에 설명 표시
• AGENTS.md와 함께 커밋하면 프로젝트의 AI 사용 패턴이 코드와 함께 진화

내일(9일차)에는 opencode의 확장성을 극대화하는 MCP(Model Context Protocol) 서버 연동을 다룹니다. 사내 RAG 시스템, 외부 API, 데이터베이스를 에이전트의 도구로 연결하는 방법 — 금융IT 도메인의 실제 적용 사례도 함께 소개합니다.

---