> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryvox.co/llms.txt
> Use this file to discover all available pages before exploring further.

# AGENTS

# vox.ai 문서 작성 규칙

이 문서는 `domains/voxai/docs/` 내 모든 MDX 페이지에 적용되는 작성 규칙이다.
새 페이지를 만들거나 기존 페이지를 수정할 때 반드시 따른다.

***

## 1. 브랜드 표기

* 서비스명은 **vox.ai** 로 표기한다 (대문자 X, 마침표 포함).
* "VOX", "Vox", "voxai" 등 다른 표기를 사용하지 않는다.

## 2. 시각 자료

페이지에 시각 자료를 적극 활용한다. 텍스트만으로 설명이 충분해도, 대시보드 화면이나 절차가 포함되면 반드시 시각 자료를 넣는다.

| 유형          | 사용 시점                        | 예시                                             |
| ----------- | ---------------------------- | ---------------------------------------------- |
| **이미지**     | 대시보드 UI, 설정 화면, 결과 화면을 설명할 때 | 스크린샷, 다이어그램                                    |
| **Mermaid** | 절차, 흐름, 상태 전이를 설명할 때         | `sequenceDiagram`, `flowchart`, `stateDiagram` |

### 이미지 규칙

* `/images/` 디렉토리에 저장한다.
* 파일명은 `섹션-설명.png` 형식으로 작성한다 (예: `deploy-batch-campaign-dialog.png`).
* 아직 이미지가 없으면 `{/* screenshot: 설명 */}` 주석을 남겨 위치를 표시한다.

### Mermaid 규칙

* 코드 블록으로 삽입한다: ` ```mermaid `
* 노드 텍스트는 한국어로 작성한다.
* 3단계 이상의 절차, 분기가 있는 흐름에 사용한다.

## 3. 언어 원칙

**한영 병기를 하지 않는다.** 한국어 또는 영어 중 하나만 선택한다.

| 규칙                   | 올바른 예                         | 잘못된 예                |
| -------------------- | ----------------------------- | -------------------- |
| 한국어 용어가 있으면 한국어 사용   | 음성 에이전트                       | 음성 에이전트(Voice Agent) |
| 고유명사는 원어 유지          | MCP, SDK, API, SIP, DTMF      | 엠씨피, 에스디케이           |
| UI 레이블은 실제 화면 표기를 따름 | **Settings** → **Connectors** | 설정 → 커넥터             |
| 코드, CLI 명령은 영어       | `mint dev`                    | `민트 개발서버 실행`         |

## 4. Mintlify 컴포넌트 활용

`MINTLIFY.md`와 Mintlify MCP를 참고하여 best practice를 따른다.

### 필수 frontmatter

```yaml theme={null}
---
title: 페이지 제목
description: "한 줄 요약 (검색 노출용)"
---
```

### 컴포넌트 선택 기준

| 상황           | 컴포넌트                                     |
| ------------ | ---------------------------------------- |
| 순서가 있는 절차    | `<Steps>` + `<Step>`                     |
| 택일 옵션        | `<Tabs>` + `<Tab>`                       |
| 부가 정보 접기     | `<Accordion>`                            |
| 페이지 카드 네비게이션 | `<CardGroup>` + `<Card>`                 |
| 주의/팁/정보      | `<Warning>`, `<Tip>`, `<Note>`, `<Info>` |
| 코드 다중 언어     | `<CodeGroup>`                            |

## 5. 페이지 간 링크

### 내부 링크 적극 활용

문서에서 다른 페이지에서 이미 설명한 개념이 등장하면, 해당 단어를 내부 링크로 연결한다.

```mdx theme={null}
[에이전트 버전 관리](/docs/build/versioning)를 설정하면 배포 전에 변경 사항을 검증할 수 있습니다.
```

### 참고 안내

섹션 끝에서 관련 페이지로 안내할 때는 아래 패턴을 사용한다.

```mdx theme={null}
<Note>
  자세한 내용은 [대량 발신](/docs/operate/deploy/outbound-batch) 페이지를 참고하세요.
</Note>
```

### 링크 규칙

* 경로는 루트 상대 경로, 확장자 없이 작성한다: `/docs/build/versioning`
* 외부 링크는 전체 URL을 사용한다 (새 탭으로 자동 오픈).

## 6. 연관 검색어 섹션

AI 검색 엔진이 페이지를 정확히 찾을 수 있도록, 모든 페이지의 **가장 아래**에 연관 검색어 섹션을 넣는다.

```mdx theme={null}
---

<Accordion title="연관 검색어">
  대량 발신, 캠페인, 아웃바운드, 배치 콜, bulk call, outbound campaign, 대량 통화
</Accordion>
```

* 한국어 키워드와 영어 키워드를 쉼표로 나열한다.
* 사용자가 검색할 법한 동의어, 유사어, 약어를 포함한다.
* 본문에 등장하지 않는 관련 용어도 포함할 수 있다.

## 7. 문체와 품질 검수

작성 완료 후 아래 세 가지 skill을 순서대로 실행하여 검수한다.

| 순서 | Skill              | 목적                         |
| -- | ------------------ | -------------------------- |
| 1  | `/grammar-checker` | 맞춤법, 띄어쓰기, 조사 오류 교정        |
| 2  | `/style-guide`     | 용어 통일, 문체 일관성 확인           |
| 3  | `/humanizer`       | AI 특유 패턴 제거, 자연스러운 문장으로 변환 |

### 문체 규칙

* **경어체(합쇼체)** 를 사용한다: "\~합니다", "\~하세요"
* 수동태를 피하고 능동태로 쓴다: "설정됩니다" → "설정하세요"
* 한 문장은 40자 이내로 짧게 끊는다.
* 불필요한 접속사("또한", "그리고", "이를 통해")를 줄인다.

### 용어 통일

| 통일 용어  | 사용하지 않는 표현            |
| ------ | --------------------- |
| 에이전트   | 봇, 챗봇, AI 어시스턴트       |
| 통화 기록  | 콜 로그, call log, 통화 로그 |
| 대시보드   | 콘솔, 관리자 페이지           |
| 워크스페이스 | 작업공간, workspace       |

***

## 체크리스트

새 페이지를 작성하거나 기존 페이지를 수정할 때 아래를 확인한다.

* [ ] vox.ai 표기가 올바른가
* [ ] 대시보드 설명에 이미지(또는 placeholder 주석)가 있는가
* [ ] 절차 설명에 Mermaid 다이어그램을 활용했는가
* [ ] 한영 병기 없이 한국어 또는 영어 하나만 사용했는가
* [ ] Mintlify 컴포넌트를 적절히 활용했는가
* [ ] 다른 페이지로 링크할 수 있는 용어에 내부 링크를 걸었는가
* [ ] 페이지 하단에 연관 검색어 섹션이 있는가
* [ ] `/grammar-checker` → `/style-guide` → `/humanizer` 검수를 완료했는가