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