packages/web/src/content/docs/ko/commands.mdx

---
title: 명령어
description: 반복적인 작업을 위한 커스텀 명령을 만드세요.
---

커스텀 명령을 사용하면 TUI에서 해당 명령이 실행될 때 사용할 프롬프트를 미리 정의할 수 있습니다.

```bash frame="none"
/my-command
```

---

커스텀 명령은 `/init`, `/undo`, `/redo`, `/share`, `/help` 같은 내장 명령과 별도로 추가됩니다. [더 알아보기](/docs/tui#commands).

---

## 명령 파일 만들기

커스텀 명령은 `commands/` 디렉터리에 Markdown 파일을 만들어 정의합니다.

예: `.opencode/commands/test.md`

```md title=".opencode/commands/test.md"
---
description: Run tests with coverage
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.
```

프런트매터(frontmatter)에는 명령 속성을 정의하고, 본문은 템플릿 프롬프트가 됩니다.

명령 이름 앞에 `/`를 붙여 실행합니다.

```bash frame="none"
"/test"
```

---

## 구성

커스텀 명령은 OpenCode 설정으로 추가하거나, `commands/` 디렉터리에 Markdown 파일을 만들어 추가할 수 있습니다.

---

### JSON

OpenCode [config](/docs/config)의 `command` 옵션을 사용합니다.

```json title="opencode.jsonc" {4-12}
{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    // This becomes the name of the command
    "test": {
      // This is the prompt that will be sent to the LLM
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      // This is shown as the description in the TUI
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}
```

이제 TUI에서 다음처럼 실행할 수 있습니다.

```bash frame="none"
/test
```

---

### Markdown

Markdown 파일로도 명령을 정의할 수 있습니다. 아래 경로 중 하나에 두면 됩니다.

- 전역: `~/.config/opencode/commands/`
- 프로젝트별: `.opencode/commands/`

```markdown title="~/.config/opencode/commands/test.md"
---
description: Run tests with coverage
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.
```

Markdown 파일명이 명령 이름이 됩니다. 예를 들어 `test.md`라면 아래처럼 실행합니다.

```bash frame="none"
/test
```

---

## 프롬프트 구성

커스텀 명령 프롬프트는 몇 가지 특수 플레이스홀더(placeholder)와 문법을 지원합니다.

---

### 인수

`$ARGUMENTS` 플레이스홀더로 명령 인수를 전달할 수 있습니다.

```md title=".opencode/commands/component.md"
---
description: Create a new component
---

Create a new React component named $ARGUMENTS with TypeScript support.
Include proper typing and basic structure.
```

인수를 넣어 실행하면:

```bash frame="none"
/component Button
```

`$ARGUMENTS`가 `Button`으로 치환됩니다.

위치 인수도 사용할 수 있습니다.

- `$1` - 첫 번째 인수
- `$2` - 두 번째 인수
- `$3` - 세 번째 인수
- 이후 동일

예시:

```md title=".opencode/commands/create-file.md"
---
description: Create a new file with content
---

Create a file named $1 in the directory $2
with the following content: $3
```

실행:

```bash frame="none"
/create-file config.json src "{ \"key\": \"value\" }"
```

치환 결과:

- `$1` -> `config.json`
- `$2` -> `src`
- `$3` -> `{ "key": "value" }`

---

### 셸 출력

_!`command`_ 문법으로 [bash 명령](/docs/tui#bash-commands)의 출력 결과를 프롬프트에 주입할 수 있습니다.

예를 들어 테스트 커버리지 분석 명령을 만들면:

```md title=".opencode/commands/analyze-coverage.md"
---
description: Analyze test coverage
---

Here are the current test results:
!`npm test`

Based on these results, suggest improvements to increase coverage.
```

최근 변경 리뷰용으로는:

```md title=".opencode/commands/review-changes.md"
---
description: Review recent changes
---

Recent git commits:
!`git log --oneline -10`

Review these changes and suggest any improvements.
```

명령은 프로젝트 루트 디렉터리에서 실행되며, 출력 결과는 프롬프트 본문에 포함됩니다.

---

### 파일 참조

`@` 뒤에 파일명을 붙여 명령에 파일을 포함할 수 있습니다.

```md title=".opencode/commands/review-component.md"
---
description: Review component
---

Review the component in @src/components/Button.tsx.
Check for performance issues and suggest improvements.
```

파일 내용은 자동으로 프롬프트에 포함됩니다.

---

## 옵션

구성 옵션을 자세히 살펴봅니다.

---

### 템플릿

`template` 옵션은 명령 실행 시 LLM에 전달할 프롬프트를 정의합니다.

```json title="opencode.json"
{
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes."
    }
  }
}
```

이 옵션은 **필수**입니다.

---

### 설명

`description` 옵션으로 명령의 짧은 설명을 추가할 수 있습니다.

```json title="opencode.json"
{
  "command": {
    "test": {
      "description": "Run tests with coverage"
    }
  }
}
```

이 설명은 TUI에서 명령을 입력할 때 표시됩니다.

---

### 에이전트

`agent` 설정으로 이 명령을 실행할 [agent](/docs/agents)를 지정할 수 있습니다.
지정한 값이 [subagent](/docs/agents/#subagents)면 기본적으로 subagent 호출이 실행됩니다.
이 동작을 끄려면 `subtask`를 `false`로 설정하세요.

```json title="opencode.json"
{
  "command": {
    "review": {
      "agent": "plan"
    }
  }
}
```

이 옵션은 **선택**입니다. 지정하지 않으면 현재 에이전트가 기본값으로 사용됩니다.

---

### 서브태스크

`subtask` 불리언(boolean)을 사용하면 명령이 [subagent](/docs/agents/#subagents) 호출을 강제로 트리거합니다.
주 컨텍스트를 오염시키고 싶지 않을 때 유용하며, [agent](/docs/agents) 설정의 `mode`가 `primary`여도 subagent로 실행합니다.

```json title="opencode.json"
{
  "command": {
    "analyze": {
      "subtask": true
    }
  }
}
```

이 옵션은 **선택**입니다.

---

### 모델

`model` 설정으로 이 명령의 기본 모델을 오버라이드할 수 있습니다.

```json title="opencode.json"
{
  "command": {
    "analyze": {
      "model": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}
```

이 옵션은 **선택**입니다.

---

## 내장 명령

OpenCode는 `/init`, `/undo`, `/redo`, `/share`, `/help` 등 여러 내장 명령을 제공합니다. [더 알아보기](/docs/tui#commands).

:::note
커스텀 명령은 내장 명령을 덮어쓸 수 있습니다.
:::

같은 이름으로 커스텀 명령을 정의하면 내장 명령보다 커스텀 명령이 우선합니다.