> ## 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.

# TEST

# LLM Agent E2E Test Missions

이 문서는 vox.ai의 LLM-facing 제품(docs, MCP, skills/plugins)이
외부 LLM 에이전트 관점에서 정상 동작하는지 검증하는 E2E 테스트 미션을 정의한다.

## 테스트 원칙

* 테스트 에이전트는 vox.ai 내부 코드를 모른다. 공개된 문서와 도구만 사용한다.
* 진입점은 항상 `https://docs.tryvox.co/llms.txt` 이다.
* 각 미션은 독립적으로 수행 가능해야 한다.
* 실패 지점은 제품(docs/MCP/skills) 중 어디의 문제인지 분류한다.

## 대상 제품

| 제품            | 소스                      | 배포 URL                                     |
| ------------- | ----------------------- | ------------------------------------------ |
| Docs          | `domains/voxai/docs/`   | `https://docs.tryvox.co`                   |
| Skills/Plugin | `domains/voxai/skills/` | `https://github.com/vox-public/vox-skills` |
| MCP           | `domains/voxai/mcp/`    | `https://mcp.tryvox.co/mcp`                |

## 참고 문서

Plugin 시스템별 참고 자료는 `_references/` 디렉토리에 있다.

| 파일                                   | 내용                                        |
| ------------------------------------ | ----------------------------------------- |
| `_references/claude-code-plugins.md` | Claude Code plugin 구조, 설치, 매니페스트 스키마      |
| `_references/codex-plugins.md`       | Codex plugin 구조, 마켓플레이스, Claude Code와의 차이 |
| `_references/cowork-plugins.md`      | Claude Cowork 커넥터 등록, 제약사항                |

## 실행 루프

미션은 한 번 실행으로 끝나지 않는다.
통과할 때까지 아래 루프를 반복한다.

```
┌─────────────────────────────────────────────────┐
│  1. 미션 하달                                     │
│     오케스트레이터가 에이전트 브리핑을 준비한다          │
│                     ↓                            │
│  2. 에이전트 spawn                                │
│     격리된 subagent를 생성하고 미션 프롬프트를 전달한다  │
│                     ↓                            │
│  3. 실패 보고 수거                                 │
│     에이전트가 막힌 지점, 원인, 에러를 수거한다         │
│                     ↓                            │
│  4. 원인 분류 → 코드 수정                           │
│     Docs / Skills / MCP 중 해당 레포를 수정한다      │
│                     ↓                            │
│  5. 배포                                         │
│     수정한 레포를 배포한다                           │
│                     ↓                            │
│  6. 재테스트                                      │
│     동일 미션으로 다시 에이전트를 spawn한다            │
│     → 통과하면 종료, 실패하면 3번으로 복귀            │
└─────────────────────────────────────────────────┘
```

### 역할 분리

| 역할           | 누구                     | 하는 일                          |
| ------------ | ---------------------- | ----------------------------- |
| **오케스트레이터**  | 사람 + 메인 Claude Code 세션 | 미션 하달, 실패 보고 분석, 코드 수정, 배포 판단 |
| **테스트 에이전트** | spawn된 subagent        | 미션 수행, 막힌 지점 보고. 내부 코드 접근 불가  |

### 실패 보고 형식

```
## 실패 보고

### 도달한 단계
Step N: (단계 이름)

### 막힌 지점
(구체적으로 어떤 행동을 시도했고 어디서 막혔는지)

### 에러 내용
(에러 메시지, HTTP 상태 코드, 도구 응답 등 원문)

### 시도한 우회
(다른 방법을 시도했다면 무엇을, 왜 실패했는지)

### 원인 추정
Docs / Skills / MCP / Infra 중 하나 + 이유
```

## develop 환경

프로덕션 배포 전에 develop 기준으로 E2E 테스트를 수행한다.

| 제품            | 프로덕션                        | develop                               |
| ------------- | --------------------------- | ------------------------------------- |
| Docs          | `https://docs.tryvox.co`    | `mintlify dev` (로컬)                   |
| Skills/Plugin | `main` branch               | `main` branch (직접 push)               |
| MCP           | `https://mcp.tryvox.co/mcp` | `https://vox-mcp-develop.fly.dev/mcp` |

Plugin 설치 후 MCP URL을 develop(`https://vox-mcp-develop.fly.dev/mcp`)으로 바꿔서 테스트하면 된다.

***

## 실행 Runbook

미션 실행 시 아래 순서를 따른다. 각 미션이 독립적으로 실행 가능하게 유지한다.

### 1. 환경 준비

* **오케스트레이터 세션**: vox-mono 작업 디렉토리의 메인 Claude Code 세션. 세 레포(`docs`, `skills`, `mcp`) 모두에 접근 가능.
* **테스트 계정**: vox.ai 테스트 전용 계정 1개(구매/결제 가능 상태). 프로덕션 고객 데이터와 섞이지 않도록 별도 워크스페이스를 쓴다.
* **테스트 전화번호**: 수신 가능한 개인 번호 1개. Mission 완료 시 실제 통화가 걸려온다.
* **MCP 환경**: 프로덕션은 `https://mcp.tryvox.co/mcp`, develop 검증은 `https://vox-mcp-develop.fly.dev/mcp`.
* **세션 격리**: 테스트 에이전트는 vox-mono 소스를 볼 수 없는 상태에서 실행한다. 오케스트레이터 세션의 Agent tool로 새 서브에이전트를 spawn하고, 브리핑에 공개 URL(`https://docs.tryvox.co/llms.txt`)만 제공한다.

### 2. 미션 실행

1. 오케스트레이터가 Mission N 브리핑을 준비하고 `[CLIENT]`, `[TEST_PHONE_NUMBER]` 같은 변수를 치환한다.
2. 서브에이전트를 spawn한다. 경로별로 AI 앱이 달라야 하므로 각 경로는 별도 실행 lane을 사용한다:
   * 경로 1A(Claude Code): 동일 Claude Code 인스턴스의 subagent
   * 경로 1B(Codex): 별도 Codex 세션(수동 실행 후 transcript 수집)
   * 경로 1C(Cowork): Cowork 앱에서 수동 실행 후 transcript 수집
3. 서브에이전트가 최종 보고를 반환하면 오케스트레이터가 기록한다.

### 3. 결과 기록

각 실행 결과는 `domains/voxai/docs/_references/test-runs/<YYYY-MM-DD>/<mission-id>-<path>.md`에 남긴다(커밋하지 않을 수도 있음, gitignore 정책은 별도 판단).

* 통과 시: 체크리스트 + 각 step의 실제 명령/응답 요약
* 실패 시: "실패 보고" 섹션(도달 단계·막힌 지점·에러·시도한 우회·원인 추정)을 그대로 복사

### 4. 원인 분류 → 수정 → 재실행

실패 보고의 `원인 추정`을 기준으로 수정 대상 레포를 정한다. 수정 범위가 여러 레포에 걸치면 레포별 별도 커밋으로 처리한다. 동일 미션을 다시 spawn해 통과 여부만 본다.

### 5. Pass/Fail 종합 판정

한 미션의 **모든 경로**가 통과해야 미션이 통과한 것으로 본다. 한 경로만 통과한 상태에서는 미션을 close하지 않는다.

***

## Mission 1: Plugin 설치 → 첫 아웃바운드 콜

### 목표

LLM 에이전트가 vox.ai 문서를 따라 plugin을 설치하고, 에이전트를 생성한 뒤,
아웃바운드 테스트 콜을 발신하기까지의 전체 온보딩 플로우를 검증한다.

### 온보딩 경로

이 미션은 **3개 클라이언트** 각각에서 성공해야 한다.
각 경로별로 독립적으로 테스트한다.

| 경로     | 클라이언트         | plugin 설치 방법                                                                                          | MCP 등록 방식         |
| ------ | ------------- | ----------------------------------------------------------------------------------------------------- | ----------------- |
| **1A** | Claude Code   | `/plugin marketplace add vox-public/vox-skills` → `/plugin install vox-ai@vox-ai` → `/reload-plugins` | `.mcp.json` 자동 등록 |
| **1B** | Codex         | `codex marketplace add vox-public/vox-skills` → App `Plugins` 또는 CLI `/plugins`에서 `vox-ai` 설치         | `.mcp.json` 자동 등록 |
| **1C** | Claude Cowork | 사용자 지정 → 개인 플러그인 → 마켓플레이스 추가 `vox-public/vox-skills` → 커넥터 메뉴에서 `vox`/`vox-docs` 설치·연결                | `.mcp.json` 자동 등록 |

### 핵심 판정 기준

> **MCP 직접 연결 명령(`claude mcp add ...`)을 실행했다면 실패다.**
>
> 세 경로 모두 Plugin 설치를 통해 `.mcp.json`이 자동으로 MCP를 등록해야 한다.
> 에이전트가 docs에서 `claude mcp add` 명령을 찾아 실행하는 것은
> plugin 온보딩 경로가 아닌 수동 연결이므로 실패로 판정한다.

### 전제조건

| 항목   | 요구사항                                                  |
| ---- | ----------------------------------------------------- |
| 런타임  | 경로별 클라이언트 (Claude Code / Codex / Cowork)              |
| 인증   | vox.ai 계정 (OAuth 또는 API 키)                            |
| 전화번호 | 테스트 수신용 전화번호 1개                                       |
| 네트워크 | `docs.tryvox.co`, `mcp.tryvox.co`, `github.com` 접근 가능 |

### 에이전트 브리핑

아래는 테스트 LLM 에이전트에게 전달할 미션 프롬프트다.
`[CLIENT]`와 `[TEST_PHONE_NUMBER]`는 실행 시 치환한다.

```
당신은 vox.ai를 처음 사용하는 개발자입니다.
현재 [CLIENT]를 사용하고 있습니다.

아래 문서를 시작점으로 삼아 음성 에이전트를 만들고 테스트 통화까지 완료하세요.

진입점: https://docs.tryvox.co/llms.txt

목표:
1. vox.ai plugin을 설치하세요.
2. 에이전트를 만들 수 있는 도구(MCP)에 연결되었는지 확인하세요.
3. 간단한 고객 상담 에이전트를 만드세요.
4. 만든 에이전트로 [TEST_PHONE_NUMBER]에 테스트 전화를 거세요.

규칙:
- 위 진입점 문서에서 출발하여 필요한 정보를 스스로 찾으세요.
- 문서에 없는 정보는 추측하지 마세요.
- plugin 설치를 통해 MCP 연결이 자동으로 되는 것이 이상적입니다.
- 각 단계를 완료할 때마다 결과를 기록하세요.
- 막히는 부분이 있으면 어디서 왜 막혔는지 상세히 기록하세요.

최종 보고:
- 모든 단계를 완료했으면 각 단계의 결과를 요약하세요.
- 막힌 단계가 있으면 아래 형식으로 보고하세요:

  ## 실패 보고
  ### 도달한 단계
  ### 막힌 지점
  ### 에러 내용
  ### 시도한 우회
  ### 원인 추정 (Docs / Skills / MCP / Infra 중 하나 + 이유)
```

### 검증 단계

#### Step 1: 진입점 접근

| 항목        | 내용                                      |
| --------- | --------------------------------------- |
| 행동        | `https://docs.tryvox.co/llms.txt` fetch |
| 성공 기준     | 200 응답, 문서 인덱스 수신                       |
| 실패 → Docs | llms.txt 미배포 또는 경로 오류                   |

#### Step 2: Plugin 설치

경로별로 기대하는 행동이 다르다.

**경로 1A (Claude Code)**:

| 항목          | 내용                                                                                                    |
| ----------- | ----------------------------------------------------------------------------------------------------- |
| 행동          | docs(`/docs/ai/claude-code`)에서 plugin 설치 명령을 찾아 실행                                                    |
| 기대 명령       | `/plugin marketplace add vox-public/vox-skills` → `/plugin install vox-ai@vox-ai` → `/reload-plugins` |
| 성공 기준       | plugin 설치 완료, `/plugin` 목록에 `vox-ai` 등록, `vox-ai:*` 스킬이 세션에 로드                                        |
| 실패 → Docs   | 설치 명령을 문서에서 찾지 못함, 또는 stale 명령(`claude plugin ...` CLI나 `npx skills add`)을 안내                         |
| 실패 → Skills | GitHub 레포 접근 불가, `.claude-plugin/marketplace.json` 오류, skill 미등록                                      |

**경로 1B (Codex)**:

| 항목          | 내용                                       |
| ----------- | ---------------------------------------- |
| 행동          | docs에서 Codex plugin 설치 방법을 찾아 실행         |
| 기대 행동       | `/plugins`에서 vox.ai 검색 또는 마켓플레이스 추가 후 설치 |
| 성공 기준       | plugin 설치 완료, vox.ai 도구 사용 가능            |
| 실패 → Docs   | Codex 경로 안내 누락                           |
| 실패 → Skills | `.codex-plugin/plugin.json` 미제공 또는 구조 오류 |

**경로 1C (Cowork)**:

| 항목          | 내용                                             |
| ----------- | ---------------------------------------------- |
| 행동          | docs에서 Cowork plugin 설치 방법을 찾아 실행              |
| 기대 행동       | Cowork 앱 Browse plugins에서 설치 또는 커스텀 plugin 업로드 |
| 성공 기준       | plugin 설치 완료, 도구 호출 가능                         |
| 실패 → Docs   | Cowork plugin 설치 안내 누락 또는 불명확                  |
| 실패 → Skills | plugin 파일 구조 오류, Cowork 호환 문제                  |

#### Step 3: MCP 자동 등록 확인

| 항목           | 내용                                     |
| ------------ | -------------------------------------- |
| 행동           | plugin 설치 후 MCP 도구 사용 가능 여부 확인         |
| 성공 기준        | `list_agents` 등 vox MCP 도구가 자동으로 사용 가능 |
| **자동 실패 조건** | 에이전트가 `claude mcp add` 명령을 실행함 (모든 경로) |
| 실패 → Skills  | `.mcp.json` 누락 또는 자동 등록 실패             |
| 실패 → MCP     | 서버 다운, 도구 미노출                          |

#### Step 4: 에이전트 생성

| 항목          | 내용                               |
| ----------- | -------------------------------- |
| 행동          | `create_agent` MCP 도구 호출         |
| 성공 기준       | agent\_id 반환, `get_agent`로 조회 성공 |
| 실패 → Skills | onboarding skill의 가이드 부족         |
| 실패 → MCP    | create\_agent schema 불명확, API 에러 |

#### Step 5: 아웃바운드 콜 발신

| 항목         | 내용                                  |
| ---------- | ----------------------------------- |
| 행동         | `create_call` MCP 도구로 테스트 번호에 전화 발신 |
| 성공 기준      | call\_id 반환, 실제 전화 수신               |
| 실패 → MCP   | 발신 번호 없음 안내 부족, 파라미터 설명 부족          |
| 실패 → Infra | SIP/텔레포니 문제 (이 테스트 범위 밖)            |

### 실패 원인 분류

| 분류         | 수정 대상                   | 배포 방법                               |
| ---------- | ----------------------- | ----------------------------------- |
| **Docs**   | `domains/voxai/docs/`   | Mintlify 자동 배포 (push to main)       |
| **Skills** | `domains/voxai/skills/` | GitHub push (vox-public/vox-skills) |
| **MCP**    | `domains/voxai/mcp/`    | Fly.io 배포                           |
| **Infra**  | 범위 밖                    | 별도 대응                               |

### 경로별 체크리스트

#### 경로 1A: Claude Code

```
[ ] Step 1: llms.txt 접근 — 200 응답
[ ] Step 2: Plugin 설치 — skill 목록에 vox 등록
[ ] Step 3: MCP 자동 등록 — claude mcp add 실행 없이 도구 사용 가능
[ ] Step 4: 에이전트 생성 — agent_id 반환
[ ] Step 5: 아웃바운드 콜 — 전화 수신
```

#### 경로 1B: Codex

```
[ ] Step 1: llms.txt 접근 — 200 응답
[ ] Step 2: Plugin 설치 — Codex plugin directory에서 설치 성공
[ ] Step 3: MCP 자동 등록 — 수동 설정 없이 도구 사용 가능
[ ] Step 4: 에이전트 생성 — agent_id 반환
[ ] Step 5: 아웃바운드 콜 — 전화 수신
```

#### 경로 1C: Claude Cowork

```
[ ] Step 1: llms.txt 접근 — 200 응답
[ ] Step 2: Plugin 설치 — Cowork 앱에서 plugin 설치 성공
[ ] Step 3: MCP 자동 등록 — 수동 설정 없이 도구 사용 가능
[ ] Step 4: 에이전트 생성 — agent_id 반환
[ ] Step 5: 아웃바운드 콜 — 전화 수신
```

***

## Mission 2: (미정)

## Mission 3: (미정)