[opencode 시즌 2 심화 — 나만의 도메인 특화 에이전트 만들기] 8/12화: opencode 슬래시 커맨드 워크플로우 자동화 5가지 실전 패턴 2026

시리즈 안내 — Phase D 확장 개발의 시작

이 글은 「opencode 시즌 2 심화 — 나만의 도메인 특화 에이전트 만들기」 8일차입니다. 오늘부터 Phase D(확장 개발)에 진입합니다. 7일 동안 에이전트의 뼈대를 세우고, 권한을 조이고, 모델을 배치하고, 팀을 짜고, 컨텍스트를 엔지니어링했습니다. 이제 그 에이전트에게 ‘버튼 하나로 복잡한 워크플로우를 실행하라’고 명령하는 방법을 다룹니다.

시즌 1에서 opencode의 기본 슬래시 커맨드(/init, /compact 등)를 소개했던 걸 기억하시나요? 오늘은 그 커맨드를 직접 설계합니다. .opencode/commands/ 디렉토리에 마크다운 파일 하나를 놓으면 그것이 곧 opencode 슬래시 커맨드가 됩니다. 단순한 프롬프트 바로가기가 아니라, named arguments로 입력을 구조화하고 서브에이전트를 호출하며 멀티스텝 워크플로우를 자동화하는 강력한 도구입니다.

어제 7일차에서는 컨텍스트 엔지니어링으로 에이전트가 프로젝트의 규칙과 패턴을 ‘학습’하게 만들었습니다. 오늘은 그 컨텍스트 위에 반복 작업을 한 줄로 축약하는 커맨드를 올립니다.

오늘의 핵심 3가지

• 슬래시 커맨드 frontmatter 심화 — description, arguments, named args의 정확한 문법과 동작 원리
• 5가지 실전 커맨드 패턴 — /commit, /deploy-check, /review, /optimize, /context-load를 완전한 코드로 제공
• 커맨드에서 서브에이전트 호출 — 6일차에 만든 전문가 팀을 커맨드 한 줄로 소환하는 오케스트레이션

opencode 슬래시 커맨드의 구조 — 파일 하나가 곧 명령이다

opencode 슬래시 커맨드의 원리는 놀라울 정도로 단순합니다. .opencode/commands/ 디렉토리에 .md 파일을 넣으면, 파일 이름이 곧 커맨드 이름이 됩니다. commit.md를 만들면 /commit으로 호출할 수 있습니다.

각 커맨드 파일은 두 부분으로 구성됩니다:

• YAML frontmatter — 커맨드의 메타데이터(설명, 인자 정의)
• Markdown 본문 — 에이전트에게 전달될 프롬프트 템플릿

가장 간단한 형태부터 보겠습니다:

# .opencode/commands/hello.md
---
description: "인사말을 생성합니다"
---
안녕하세요! 현재 프로젝트의 상태를 요약해주세요.
$ARGUMENTS

/hello 최근 변경 사항 위주로라고 입력하면, $ARGUMENTS 자리에 “최근 변경 사항 위주로”가 대입됩니다. 이것만으로도 자주 쓰는 프롬프트를 재사용할 수 있지만, 진짜 위력은 named arguments와 서브에이전트 연동에서 나옵니다.

스코프: 글로벌 vs 프로젝트 로컬

2일차에서 에이전트 정의의 스코프를 다뤘던 것처럼, 슬래시 커맨드도 두 계층으로 나뉩니다:

• 글로벌: ~/.config/opencode/commands/ — 어떤 프로젝트에서든 사용 가능
• 프로젝트 로컬: .opencode/commands/ — 해당 프로젝트 전용

같은 이름의 커맨드가 양쪽에 있으면 프로젝트 로컬이 우선합니다. 팀 공통 커맨드는 저장소에 커밋하고, 개인 습관 커맨드는 글로벌에 두는 게 실전 패턴입니다.

Frontmatter 심화 — Named Arguments로 입력을 구조화하기

$ARGUMENTS는 편리하지만, 여러 인자를 받아야 할 때는 구분이 모호해집니다. Named arguments를 쓰면 각 인자를 명확하게 정의하고, 필수 여부를 지정하며, 프롬프트 내에서 개별적으로 참조할 수 있습니다.

# .opencode/commands/review.md
---
description: "코드 리뷰를 수행합니다"
arguments:
  - name: "target"
    description: "리뷰 대상 파일 또는 디렉토리 경로"
    required: true
  - name: "focus"
    description: "리뷰 관점 (security | performance | readability)"
    required: false
  - name: "severity"
    description: "최소 보고 심각도 (info | warning | error)"
    required: false
---
## 코드 리뷰 요청

대상: $target
관점: $focus (미지정 시 전체 관점으로 리뷰)
최소 심각도: $severity (미지정 시 warning 이상)

다음 체크리스트에 따라 리뷰해주세요:
{file:./prompts/review-checklist.md}

호출할 때는 이렇게 씁니다:

/review target:src/api/handler.py focus:security severity:error

각 인자가 $target, $focus, $severity로 정확히 대입됩니다. required: true인 인자를 빠뜨리면 opencode가 입력을 요청합니다.

frontmatter에서 사용할 수 있는 키 정리

키	타입	필수	설명
description	string	권장	커맨드 목록에 표시되는 설명. /help에도 노출
arguments	array	선택	named arguments 배열. 각 항목에 name, description, required
arguments[].name	string	필수	인자 이름. 본문에서 $name으로 참조
arguments[].description	string	권장	인자 설명
arguments[].required	boolean	선택	기본값 false. true면 누락 시 입력 요청

본문에서 사용하는 특수 변수는 두 가지입니다:

• $ARGUMENTS — 전체 인자 문자열 (named arguments를 정의하지 않았을 때 유용)
• $argname — named argument의 개별 값

여기에 7일차에서 배운 {file:./path} 패턴을 결합하면, 프롬프트 본문을 외부 파일로 분리해 버전 관리와 재사용성을 높일 수 있습니다.

opencode 슬래시 커맨드 실전 5가지 — 워크플로우 자동화 패턴

이론은 여기까지. 지금부터 실무에서 바로 쓸 수 있는 5가지 커맨드를 완전한 코드로 제공합니다. 각 커맨드는 독립적으로 동작하지만, 뒤에서 이들을 파이프라인으로 연결하는 패턴도 다룹니다.

패턴 1: /commit — Conventional Commit 자동 생성

가장 많이 쓰게 될 커맨드입니다. git diff --staged를 분석해서 Conventional Commits 규약에 맞는 커밋 메시지를 생성합니다.

# .opencode/commands/commit.md
---
description: "스테이징된 변경 사항을 분석해 Conventional Commit 메시지를 생성합니다"
arguments:
  - name: "scope"
    description: "커밋 스코프 (예: api, auth, cli). 미지정 시 자동 추론"
    required: false
  - name: "breaking"
    description: "breaking change 여부 (yes/no). 기본값 no"
    required: false
---
## 커밋 메시지 생성

### 절차
1. `git diff --staged`를 실행해 스테이징된 변경 사항을 확인하세요.
2. 변경 내용을 분석해 아래 규칙에 따라 커밋 메시지를 작성하세요.
3. 작성한 메시지를 보여주고 사용자 확인을 받으세요.
4. 확인되면 `git commit -m "메시지"` 를 실행하세요.

### Conventional Commit 규칙
- 형식: `<type>(<scope>): <subject>`
- type: feat, fix, refactor, docs, test, chore, build, perf, ci 중 선택
- scope: $scope (미지정이면 변경 파일 경로에서 추론)
- subject: 50자 이내, 명령형, 소문자 시작, 마침표 없음
- breaking change: $breaking (yes이면 type 뒤에 ! 추가, 본문에 BREAKING CHANGE: 기술)

### 품질 체크
- 하나의 커밋에 하나의 논리적 변경만 포함되는지 확인
- 스테이징되지 않은 관련 파일이 있으면 경고
- 테스트 파일 변경이 있는데 소스 변경이 없으면 type을 test로

### 금지 사항
- 모델 식별자, API 키, 절대 경로를 메시지에 포함하지 않을 것
- --no-verify 플래그 사용 금지

사용 예시:

/commit scope:auth breaking:yes

에이전트가 diff를 읽고 feat(auth)!: replace JWT with session-based authentication 같은 메시지를 제안합니다. 핵심은 규칙을 커맨드에 내장함으로써 매번 “Conventional Commit 규칙에 맞게 작성해줘”라고 타이핑할 필요가 없다는 것입니다.

패턴 2: /deploy-check — 배포 전 체크리스트 실행

배포 전에 반드시 확인해야 할 항목들을 자동화합니다. 금융IT처럼 배포 전 체크리스트가 필수인 환경에서 특히 유용합니다.

# .opencode/commands/deploy-check.md
---
description: "배포 전 체크리스트를 자동 실행합니다"
arguments:
  - name: "env"
    description: "배포 환경 (dev | staging | prod)"
    required: true
  - name: "skip-test"
    description: "테스트 스킵 여부 (yes/no). 기본값 no"
    required: false
---
## 배포 전 체크리스트 — $env 환경

아래 항목을 순서대로 검사하고, 각 항목마다 ✅ PASS 또는 ❌ FAIL 표시를 해주세요.
하나라도 FAIL이면 최종 판정을 ❌ 배포 불가로 내려주세요.

### 1단계: 코드 품질
- [ ] lint 통과: 프로젝트의 린터를 실행하세요 (ruff, eslint 등 프로젝트에 맞는 것)
- [ ] 타입 체크 통과: 타입 체커가 설정되어 있으면 실행
- [ ] 포맷 체크: 코드 포매터 확인

### 2단계: 테스트
- [ ] 단위 테스트 통과 (skip-test가 $skip-test 인 경우 스킵 가능, 단 prod 환경에서는 스킵 불가)
- [ ] 테스트 커버리지 확인 (가능한 경우)

### 3단계: Git 상태
- [ ] 커밋되지 않은 변경 사항 없음
- [ ] 현재 브랜치가 최신 상태 (origin과 동기화)
- [ ] $env 환경용 브랜치 규칙 확인 (prod → main 또는 release/* 에서만)

### 4단계: 환경별 추가 검사
- [ ] 환경 변수 / 설정 파일이 $env 에 맞게 설정되어 있는지 확인
- [ ] 마이그레이션 스크립트가 있다면 pending 여부 확인
- [ ] CHANGELOG 또는 릴리즈 노트 업데이트 여부

### 최종 판정
모든 항목의 결과를 표로 요약하고, 최종 배포 가/불가 판정을 내려주세요.

사용 예시:

/deploy-check env:staging
/deploy-check env:prod skip-test:no

에이전트가 실제로 린트, 테스트, git 상태를 순서대로 확인하고 표 형태로 결과를 보고합니다. prod 환경에서는 테스트 스킵이 불가능하도록 규칙이 프롬프트에 내장되어 있는 점에 주목하세요. 이것이 ‘프롬프트로 정책을 인코딩하는’ 패턴입니다.

패턴 3: /review — 서브에이전트 연동 코드 리뷰

6일차에서 만든 서브에이전트 팀을 커맨드로 소환하는 패턴입니다. 이것이 오늘의 핵심 연결 고리입니다.

# .opencode/commands/review.md
---
description: "코드 리뷰를 수행합니다. 보안 관점은 SecurityAuditor에게 위임합니다"
arguments:
  - name: "target"
    description: "리뷰 대상 파일 또는 디렉토리"
    required: true
  - name: "focus"
    description: "리뷰 관점 (all | security | performance | readability)"
    required: false
  - name: "output"
    description: "결과 형식 (inline | summary | checklist)"
    required: false
---
## 코드 리뷰 — $target

관점: $focus (미지정 시 all)
출력 형식: $output (미지정 시 checklist)

### 리뷰 절차

1. 대상 파일을 읽으세요: $target
2. 아래 관점별 체크리스트를 적용하세요.

### 관점별 체크리스트

#### 가독성 (focus가 all 또는 readability일 때)
- 함수/변수 이름이 의도를 드러내는가
- 단일 책임 원칙을 따르는가
- 주석 없이 코드만으로 의도가 파악되는가
- 매직 넘버가 상수로 추출되었는가

#### 성능 (focus가 all 또는 performance일 때)
- 불필요한 반복 순회가 없는가
- 데이터 구조 선택이 적절한가
- N+1 쿼리 패턴이 없는가
- 캐싱이 필요한 지점이 누락되지 않았는가

#### 보안 (focus가 all 또는 security일 때)
- **@SecurityAuditor 에게 보안 리뷰를 위임**하세요
- 위임 시 대상 파일 경로와 함께 다음을 전달:
  "다음 파일의 보안 리뷰를 수행해주세요: $target
   OWASP Top 10 관점에서 검사하고, 입력 검증·인증·인가·암호화 항목을 포함해주세요."

### 결과 형식
- inline: 코드에 인라인 코멘트 형태로 제공
- summary: 요약 보고서 형태
- checklist: 체크리스트 표 형태 (기본값)

### 심각도 분류
각 발견 사항에 다음 심각도를 부여하세요:
- 🔴 Critical — 즉시 수정 필요
- 🟡 Warning — 개선 권장
- 🟢 Info — 참고 사항

사용 예시:

/review target:src/api/handler.py focus:security output:checklist

여기서 주목할 점은 보안 관점 리뷰를 @SecurityAuditor 서브에이전트에게 위임하는 부분입니다. 6일차에서 만든 서브에이전트의 description에 “보안 감사”가 포함되어 있으면 에이전트가 이를 인식하고 자동으로 위임합니다. 슬래시 커맨드가 서브에이전트 오케스트레이션의 트리거 역할을 하는 것입니다.

패턴 4: /optimize — 성능 최적화 워크플로우

# .opencode/commands/optimize.md
---
description: "파일 또는 함수의 성능을 분석하고 최적화 방안을 제안합니다"
arguments:
  - name: "target"
    description: "최적화 대상 파일 또는 함수"
    required: true
  - name: "metric"
    description: "최적화 기준 (speed | memory | bundle-size)"
    required: false
  - name: "constraint"
    description: "제약 조건 (예: 'Python 3.11 호환', '외부 라이브러리 추가 불가')"
    required: false
---
## 성능 최적화 — $target

최적화 기준: $metric (미지정 시 speed)
제약 조건: $constraint (미지정 시 없음)

### 분석 절차

**1단계: 현재 상태 파악**
- 대상 코드를 읽고 현재 시간/공간 복잡도를 분석하세요
- 핫 패스(가장 자주 실행되는 경로)를 식별하세요
- 병목 지점을 3개 이내로 좁히세요

**2단계: 최적화 방안 제안**
각 병목에 대해:
- 현재 코드 (Before)
- 제안 코드 (After)
- 예상 개선폭 (정성적 평가: 미미 / 보통 / 상당)
- 트레이드오프 (가독성, 메모리, 호환성 등)

**3단계: 적용**
- 사용자가 승인한 방안만 적용하세요
- 적용 후 기존 테스트가 통과하는지 반드시 확인하세요
- 적용하지 않을 것: 과도한 추상화, premature optimization, 가독성을 크게 해치는 변경

### 금지 사항
- 프로파일링 없이 추측으로 최적화하지 않을 것
- 제약 조건($constraint)을 위반하는 방안은 제안하지 않을 것

사용 예시:

/optimize target:src/core/queue.py metric:speed constraint:asyncio만 사용

패턴 5: /context-load — 프로젝트 컨텍스트 일괄 로드

7일차의 컨텍스트 엔지니어링을 커맨드로 패키지합니다. 새 대화를 시작할 때마다 에이전트에게 프로젝트의 핵심 컨텍스트를 일괄 주입합니다.

# .opencode/commands/context-load.md
---
description: "프로젝트 컨텍스트를 일괄 로드합니다. 새 대화 시작 시 사용"
arguments:
  - name: "depth"
    description: "컨텍스트 깊이 (minimal | standard | deep)"
    required: false
---
## 프로젝트 컨텍스트 로드 — $depth 모드

### minimal 모드 (기본)
다음 파일들을 읽고 프로젝트 구조를 파악하세요:
- AGENTS.md (에이전트 팀 구조와 규칙)
- 프로젝트 루트의 README.md (프로젝트 개요)
- 디렉토리 트리 (2단계 깊이)

### standard 모드 ($depth가 standard 또는 deep일 때 추가)
위에 더해:
- package.json 또는 pyproject.toml (의존성)
- tsconfig.json 또는 설정 파일 (빌드 설정)
- .opencode/agents/ 디렉토리의 모든 에이전트 정의 파일
- 최근 git log 5개

### deep 모드 ($depth가 deep일 때 추가)
위에 더해:
- src/ 디렉토리의 주요 진입점 파일들
- tests/ 디렉토리 구조
- docs/ 디렉토리의 아키텍처 문서
- .opencode/commands/ 의 사용 가능한 커맨드 목록

### 출력 형식
읽은 내용을 바탕으로 다음을 요약하세요:
1. **프로젝트 요약** (한 줄)
2. **기술 스택** (불릿)
3. **에이전트 팀 구성** (있는 경우)
4. **사용 가능한 커맨드** (있는 경우)
5. **현재 작업 컨텍스트** (git status 기반)

"컨텍스트 로드 완료. 무엇을 도와드릴까요?" 로 마무리하세요.

사용 예시:

/context-load depth:standard

새 대화를 시작하면 습관처럼 /context-load를 먼저 치는 것입니다. 에이전트가 프로젝트를 파악하는 데 걸리는 탐색 시간을 확정적으로 단축합니다.

커맨드에서 서브에이전트를 호출하는 3가지 패턴

패턴 3의 /review에서 이미 서브에이전트 연동을 보여드렸습니다. 이 패턴을 정리하면 세 가지로 나뉩니다:

패턴 A: @멘션 직접 호출

# 커맨드 본문 안에서
@SecurityAuditor 에게 보안 리뷰를 위임하세요: $target

가장 직관적입니다. 에이전트 이름을 명시하므로 정확히 어떤 서브에이전트가 호출되는지 보장됩니다.

패턴 B: description 기반 자동 위임

# 커맨드 본문 안에서
이 작업의 테스트 작성 부분은 테스트 전문 에이전트에게 위임하세요.

서브에이전트의 description에 “테스트”가 포함되어 있으면 Primary가 자동으로 매칭합니다. 유연하지만, 매칭이 모호할 수 있습니다.

패턴 C: 멀티스텝 오케스트레이션

# 커맨드 본문 안에서
다음 순서로 작업을 진행하세요:
1. 먼저 코드를 분석하세요 (직접 수행)
2. @Reviewer 에게 코드 리뷰를 요청하세요
3. 리뷰 결과를 받으면 @Tester 에게 테스트 작성을 요청하세요
4. 모든 결과를 종합해 최종 보고서를 작성하세요

순차적 파이프라인입니다. 에이전트가 각 단계의 결과를 다음 단계의 입력으로 사용합니다. 이 패턴이 내일 다룰 플러그인과 결합되면 훨씬 더 강력해집니다.

워크플로우 파이프라인 — 커맨드를 연결하는 메타 커맨드

개별 커맨드가 유용하지만, 진짜 자동화의 가치는 여러 커맨드를 하나의 워크플로우로 엮을 때 나옵니다. opencode에는 커맨드 간 파이프라인 문법이 별도로 없지만, 메타 커맨드 패턴으로 이를 구현할 수 있습니다.

# .opencode/commands/ship.md
---
description: "코드 변경을 리뷰 → 테스트 → 커밋 → 배포 체크까지 한 번에 수행합니다"
arguments:
  - name: "target"
    description: "변경된 주요 파일 또는 디렉토리"
    required: true
  - name: "env"
    description: "배포 환경 (dev | staging | prod)"
    required: true
---
## Ship 워크플로우 — $target → $env

이 워크플로우는 4단계로 구성됩니다. 각 단계를 순서대로 수행하세요.
어떤 단계에서든 ❌ FAIL이 나오면 즉시 중단하고 사용자에게 보고하세요.

---

### Stage 1: 코드 리뷰
$target 경로의 변경된 파일을 리뷰하세요.

체크리스트:
- 가독성: 함수/변수명, 단일 책임, 매직 넘버
- 보안: @SecurityAuditor 에게 보안 검사 위임
- 성능: 불필요한 반복, N+1 쿼리, 캐싱 누락

리뷰 결과에 🔴 Critical이 1개 이상이면 → FAIL (중단)

---

### Stage 2: 테스트 실행
프로젝트의 테스트를 실행하세요.
- 실행 명령어는 프로젝트 설정에서 자동 감지 (pytest / jest / go test 등)
- 테스트 실패 시 → FAIL (중단)
- 커버리지가 이전보다 떨어지면 경고 (중단은 아님)

---

### Stage 3: 커밋
스테이징된 변경 사항으로 커밋 메시지를 생성하세요.
- Conventional Commit 규약 준수
- scope는 $target 경로에서 추론
- 사용자 확인 후 커밋 실행

---

### Stage 4: 배포 전 체크 ($env)
$env 환경 기준으로 배포 체크리스트를 실행하세요.
- lint, 타입 체크 (Stage 1에서 이미 확인했으면 스킵 가능)
- git 상태 확인 (Stage 3에서 커밋했으므로 clean해야 함)
- 환경별 추가 검사

---

### 최종 보고
4단계 결과를 아래 형식으로 요약하세요:

| Stage | 결과 | 비고 |
|-------|------|------|
| 코드 리뷰 | ✅/❌ | ... |
| 테스트 | ✅/❌ | ... |
| 커밋 | ✅/❌ | 커밋 해시 |
| 배포 체크 | ✅/❌ | ... |

**최종 판정: 배포 가능 / 배포 불가**

사용 예시:

/ship target:src/api/ env:staging

이 하나의 커맨드가 리뷰 → 테스트 → 커밋 → 배포 체크를 순차적으로 수행합니다. 각 단계에서 실패하면 즉시 중단하고 보고합니다. 기존에 만든 개별 커맨드의 로직을 메타 커맨드 안에 인라인으로 넣었지만, 규모가 커지면 {file:./prompts/review-stage.md}처럼 외부 파일로 분리하는 것이 관리하기 편합니다.

실전 디렉토리 구조 — 오늘까지 만든 모든 것

7일간 쌓아온 결과물의 전체 디렉토리 구조를 정리합니다:

.opencode/
├── agents/                    # 6일차: 서브에이전트 팀
│   ├── reviewer.md
│   ├── tester.md
│   ├── refactorer.md
│   └── security-auditor.md
├── commands/                  # 오늘: 슬래시 커맨드
│   ├── commit.md
│   ├── deploy-check.md
│   ├── review.md
│   ├── optimize.md
│   ├── context-load.md
│   └── ship.md               # 메타 커맨드
└── plugins/                   # 내일 예정
    └── (아직 비어 있음)

prompts/                       # 7일차: 외부화된 프롬프트
├── review-checklist.md
├── commit-rules.md
└── security-policy.md

AGENTS.md                      # 7일차: 프로젝트 레벨 컨텍스트
opencode.json                  # 2일차: 기본 설정

이 구조는 팀 저장소에 그대로 커밋됩니다. 새 동료가 들어오면 /context-load depth:deep 한 번으로 프로젝트를 파악하고, /review와 /commit으로 팀의 코드 규약을 자연스럽게 따르게 됩니다.

커맨드 설계 원칙 4가지

5가지 패턴을 보면서 자연스럽게 감을 잡으셨겠지만, 좋은 opencode 슬래시 커맨드를 만드는 원칙을 명시적으로 정리합니다:

원칙 1: 단일 목적 (Single Purpose)

하나의 커맨드는 하나의 명확한 작업을 수행합니다. /commit이 리뷰까지 하지 않습니다. 복합 작업이 필요하면 /ship처럼 메타 커맨드를 만드세요.

원칙 2: 실패 시 중단 (Fail Fast)

각 단계에서 실패 조건을 명시하고, 실패 시 다음 단계로 넘어가지 않도록 합니다. 에이전트는 기본적으로 ‘뭔가 해보려고’ 하는 성향이 있으므로, 명시적으로 중단하라고 지시해야 합니다.

원칙 3: 금지 사항 명시 (Negative Constraints)

“하지 마세요”를 쓰는 것이 “하세요”만큼 중요합니다. /commit의 “–no-verify 금지”, /optimize의 “프로파일링 없이 추측 금지”처럼 에이전트가 빠지기 쉬운 함정을 커맨드에 미리 막아두세요.

원칙 4: 출력 형식 고정 (Structured Output)

결과의 형식을 커맨드에서 지정합니다. 표, 체크리스트, 요약 등 일관된 형식으로 출력하면 매번 다른 포맷으로 답하는 문제를 방지합니다.

고급 팁: {file:} 패턴으로 커맨드 프롬프트 모듈화하기

커맨드 본문이 길어지면 관리가 어려워집니다. 7일차에서 배운 {file:} 패턴을 적극 활용하세요:

# .opencode/commands/review.md (경량 버전)
---
description: "코드 리뷰를 수행합니다"
arguments:
  - name: "target"
    description: "리뷰 대상"
    required: true
  - name: "focus"
    description: "리뷰 관점"
    required: false
---
## 코드 리뷰 — $target

관점: $focus

{file:./prompts/review-checklist.md}

보안 관점이 포함되면:
{file:./prompts/security-policy.md}

이렇게 하면 체크리스트와 보안 정책을 여러 커맨드에서 재사용할 수 있습니다. /ship 메타 커맨드의 리뷰 단계에서도, 독립 /review 커맨드에서도 같은 체크리스트를 참조합니다.

# prompts/review-checklist.md

### 코드 리뷰 체크리스트

#### 구조
- [ ] 함수가 30줄을 초과하지 않는가
- [ ] 파일당 책임이 하나인가
- [ ] 순환 의존이 없는가

#### 명명
- [ ] 변수명이 역할을 드러내는가
- [ ] boolean 변수는 is/has/can 접두사를 사용하는가
- [ ] 함수명은 동사로 시작하는가

#### 에러 처리
- [ ] 외부 입출력에서 에러를 처리하는가
- [ ] 사용자에게 의미 있는 에러 메시지를 전달하는가
- [ ] 에러 로그에 충분한 컨텍스트가 포함되는가

프롬프트 파일이 곧 팀의 코딩 표준 문서가 됩니다. 코드 리뷰 기준이 바뀌면 prompts/review-checklist.md 하나만 수정하면 모든 커맨드에 즉시 반영됩니다.

Gotcha 미니 코너 — 커맨드 이름에 하이픈 쓸 때 주의

파일 이름이 곧 커맨드 이름이므로, deploy-check.md를 만들면 /deploy-check으로 호출합니다. 여기서 빠지기 쉬운 함정:

함정: deployCheck.md처럼 camelCase로 파일을 만들면 /deployCheck이 됩니다. 터미널에서 타이핑할 때 대소문자를 정확히 맞춰야 합니다. kebab-case(하이픈 연결)를 권장합니다 — 타이핑이 편하고, 팀원 간 일관성을 유지하기 좋습니다.

추가 함정: 파일 이름에 공백이 들어가면 커맨드가 등록되지 않을 수 있습니다. deploy check.md는 안 됩니다. 반드시 deploy-check.md처럼 하이픈이나 언더스코어로 연결하세요.

또 하나, arguments에서 name 필드에 하이픈을 쓰면(예: skip-test) 본문에서 $skip-test로 참조해야 합니다. 에이전트가 하이픈을 변수 구분자로 잘못 해석하는 경우가 간혹 있으므로, 인자 이름은 camelCase 또는 언더스코어(skipTest 또는 skip_test)를 쓰는 것이 더 안전합니다.

오늘의 완전한 설정 파일 — 커맨드 6개 세트

오늘 제시한 6개 커맨드를 한 번에 프로젝트에 적용하려면, 아래 디렉토리와 파일을 그대로 생성하세요. opencode 공식 문서의 Custom Commands 섹션에서 최신 문법을 확인할 수 있습니다.

mkdir -p .opencode/commands
mkdir -p prompts

가장 핵심적인 /commit 커맨드부터 만들어서 체감한 뒤, 나머지를 하나씩 추가하는 것을 권장합니다. /ship 메타 커맨드는 개별 커맨드가 안정화된 후에 마지막으로 만드세요.

전체 커맨드를 opencode.json과 함께 사용하는 예시:

{
  "default_agent": "Build",
  "agent": {
    "Build": {
      "model": "anthropic/claude-sonnet-4-10",
      "description": "코드 구현과 수정을 담당하는 기본 에이전트"
    }
  },
  "permission": {
    "allow": [
      "Read(*)",
      "Glob(*)",
      "Grep(*)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(git status*)"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(git push --force*)"
    ]
  }
}

커맨드 파일에서 git diff --staged를 실행하라고 지시하므로, opencode.json의 permission에 "Bash(git diff*)"가 allow로 들어가야 에이전트가 사용자 확인 없이 바로 실행할 수 있습니다. 4일차에서 배운 권한 설계가 여기서 직접 연결됩니다.

커맨드가 만드는 변화 — 반복 제거의 복리 효과

하루에 커밋을 10번 한다고 가정합시다. 매번 “Conventional Commit 규칙에 맞게 커밋 메시지를 작성해줘, scope는 api이고, breaking change는 없어”라고 타이핑하면 약 30초. /commit scope:api는 3초. 하루 4분 30초, 한 달이면 2시간입니다.

하지만 진짜 가치는 시간 절약이 아닙니다. 규칙이 커맨드에 내장되어 있으므로 팀 전체가 같은 포맷, 같은 체크리스트, 같은 정책을 따르게 됩니다. 신규 팀원이 Conventional Commit 규약을 몰라도, /commit만 치면 규약에 맞는 메시지가 나옵니다.

이것이 바로 에이전트 기반 워크플로우 자동화의 본질입니다. 개인의 생산성을 높이는 도구에서, 팀의 일관성을 보장하는 인프라로 전환되는 순간입니다.

내일 예고 — 플러그인으로 에이전트에게 새 능력 부여하기

오늘 만든 커맨드들은 에이전트의 기존 도구(파일 읽기, bash 실행, 서브에이전트 호출)를 조합해 워크플로우를 만들었습니다. 내일 9일차에서는 에이전트에게 완전히 새로운 도구를 만들어 줍니다 — .opencode/plugins/ 디렉토리에 TypeScript로 네이티브 플러그인을 작성하는 핸즈온입니다. 배포 전 자동 태깅, PR 본문 자동 생성 같은 기능을 플러그인으로 구현합니다. Phase D의 클라이맥스인 9일차, 기대해주세요.

Photo by Sulaiman Afrij on Pexels

Photo by Jesús Esteban San José on Pexels

---

자주 묻는 질문

opencode 슬래시 커맨드는 어떻게 만드나요?

.opencode/commands/ 디렉토리에 마크다운(.md) 파일을 생성하면 됩니다. 파일 이름이 곧 커맨드 이름이 되어, 예를 들어 commit.md를 만들면 /commit으로 호출할 수 있습니다. 파일은 YAML frontmatter(설명, 인자 정의)와 Markdown 본문(프롬프트 템플릿) 두 부분으로 구성됩니다.

opencode 슬래시 커맨드에서 named arguments와 $ARGUMENTS의 차이점은 무엇인가요?

$ARGUMENTS는 커맨드 뒤에 입력한 텍스트 전체를 하나의 문자열로 대입하는 간단한 방식입니다. 반면 named arguments는 각 인자를 이름, 설명, 필수 여부로 명확하게 정의하여 여러 인자를 구조화해서 받을 수 있고, 프롬프트 내에서 개별적으로 참조할 수 있어 복잡한 워크플로우에 적합합니다.

opencode 슬래시 커맨드의 글로벌과 프로젝트 로컬 스코프는 어떻게 다른가요?

글로벌 커맨드는 ~/.config/opencode/commands/에 두어 어떤 프로젝트에서든 사용할 수 있고, 프로젝트 로컬 커맨드는 .opencode/commands/에 두어 해당 프로젝트 전용으로 동작합니다. 같은 이름의 커맨드가 양쪽에 있으면 프로젝트 로컬이 우선하며, 팀 공통 커맨드는 저장소에 커밋하고 개인 습관 커맨드는 글로벌에 두는 것이 실전 패턴입니다.