English · 한국어 · 日本語 · 中文 · Español · Français · Deutsch · Português
**소프트웨어처럼 책을 만들자.** 책, RFC, 백서, 디자인 문서, 기술 가이드 같은 장폼 지식을 고립된 프롬프트가 아닌 **구조화된 산출물**로 만드는 다단계 파이프라인. 백지에서 출판 가능한 EPUB/PDF까지. `Phase 0: Onboarding → Phase 1: Ideation → Phase 2: Outlining → Phase 3: Drafting → Phase 4: Editing → Phase 5: Publishing`
## 왜 Velith인가?
대부분의 AI "글쓰기 도구"는 프롬프트 하나와 빈 화면이 전부입니다 — 챕터가 단절되고, 문체가 흔들리며, 구조가 없습니다. Velith는 정반대입니다: 쓰기 전에 검증하고, 각 단계에서 품질을 관리하며, 원고 전체의 연속성을 끝까지 유지하는 **계획 후 실행 파이프라인**입니다.
스펙·테스트·리뷰 없이 코드를 배포하지 않듯이 — 개요, 연속성 검사, 편집 패스 없이 책(또는 RFC, 백서)을 배포하지 마세요. Velith는 소프트웨어 엔지니어링의 규율을 장폼 지식으로 가져옵니다.
## 벤치마크
파이프라인이 비정형 입력에 무엇을 하는지 — [직접 체험하기 →](https://huggingface.co/spaces/epicsaga/Velith)
| 지표 | 원본 입력 | Velith 파이프라인 적용 후 |
|------|-----------|---------------------------|
| 구조 점수 | 2–4 / 10 | 6–9 / 10 |
| 중복률 | 20–45% n-gram 중복 | < 10% (통합 후) |
| AI 슬롭 마커 | 1,000단어당 6–20개 | style-doctor가 감지 및 제거 |
| 챕터 계층 | 없음 | 감지 후 상호 참조 포함 매핑 |
| 일관성 점수 | 0.3–1.5 / 10 | 섹션 재구성으로 개선 |
| | 기능 | 중요한 이유 |
|--|------|-------------|
| 📋 | 6단계 파이프라인 | 각 단계에서 검증 후 진행 — 재작업 없음 |
| 📖 | 7가지 장르 템플릿 | 소설, 논픽션, 기술서, 대본, 시, 게임 시나리오, 학술 (+ genre-creator로 커스텀) |
| 🤖 | 8개 전문 에이전트 | 설계, 초안, 장면 생성, 연속성, 문체, 표지, 삽화, 마케팅 |
| ✏️ | 5단계 편집 | 평가 → 개발 편집 → 라인 편집 → 교열 → 최종 교정 |
| 🔄 | 어디서든 재개 | 완료된 챕터 건너뜀, 중단 지점에서 재개 |
| 📦 | EPUB, PDF, MOBI, TXT, Markdown | Pandoc + Calibre로 출판 준비 완료 파일 생성 |
## 하나의 파이프라인, 다양한 산출물
Velith는 책 파이프라인으로 출시되지만, 동일한 6단계는 **모든 장폼 구조화 지식**에 적용됩니다. 산출물이 300페이지 소설이든 12페이지 RFC든 관계없습니다 — 계획 후 실행 흐름, 품질 관문, 에이전트가 모두 동일합니다.
| 산출물 | 장르 스킬 | 일반적 출력 |
|--------|----------|-------------|
| 소설 / 스토리 | `book-fiction` | EPUB / PDF / MOBI |
| 논픽션 도서 | `book-nonfiction` | EPUB / PDF |
| RFC / 디자인 문서 | `book-technical` | Markdown / PDF |
| 백서 / 연구 보고서 | `book-academic` | PDF (인용 포함) |
| 강의 자료 / 튜토리얼 | `book-technical` | EPUB / PDF |
| 게임 시나리오 / 로어 바이블 | `book-game` | Markdown / EPUB |
## 비교
| | Velith | 단순 프롬프트 | Notion AI | Jasper / Sudowrite | Scrivener |
|--|-----------|-------------|-----------|-------------------|-----------|
| 구조 검증 | 단계별 관문 파이프라인 | 없음 | 없음 | 기본 템플릿 | 수동 |
| 챕터 간 연속성 | 전담 에이전트 | 수동 | 없음 | 제한적 | 수동 |
| AI 슬롭 감지 | 내장 (style-doctor) | 없음 | 없음 | 없음 | 없음 |
| 장르 인식 | 8가지 장르 시스템 + 커스텀 | 프롬프트에 따라 다름 | 없음 | 소설 중심 | 없음 |
| 출력 형식 | EPUB, PDF, MOBI, TXT, Markdown | 복사-붙여넣기 | Markdown / PDF | DOCX, 제한적 | DOCX, PDF |
| 품질 관문 | 모든 단계 | 없음 | 없음 | 없음 | 없음 |
| 필요 조건 | Claude Code, Codex CLI, Agy, Cursor, Cline, Aider | 모든 LLM | Notion 구독 | 구독 | 라이선스 |
| 완전한 제어 | 프롬프트 수준 | 완전 | 블랙박스 | 블랙박스 | 완전 |
## 설치
### Claude Code
```bash
# epicsagas 마켓플레이스 추가 (아직 추가하지 않은 경우)
claude plugin marketplace add epicsagas
# velith 설치
claude plugin install velith@epicsagas
```
**사전 요건:** [Claude Code](https://claude.ai/code) CLI가 설치되고 인증되어 있어야 합니다.
### Codex CLI (OpenAI)
```bash
codex plugin marketplace add epicsagas/plugins
```
**사전 요건:** [Codex CLI](https://github.com/openai/codex)가 설치되고 OpenAI API 키가 구성되어 있어야 합니다.
### Agy (Antigravity)
```bash
agy plugin install https://github.com/epicsagas/Velith
```
Agy가 리포지토리 루트에서 스킬과 에이전트를 자동으로 인식합니다. 별도 설정이 필요 없습니다.
**사전 요건:** [Agy](https://antigravity.google/docs/cli-install)가 설치되고 구성되어 있어야 합니다.
### Cursor
Velith는 `.cursor/rules/`에 컨텍스트 규칙을 제공하여 Cursor 에이전트가 출판 파이프라인, 장르 패턴, 편집 기준을 완전히 인식할 수 있도록 합니다.
프로젝트를 Cursor에서 열면 규칙이 자동으로 로드됩니다. `.cursor/rules/` 디렉토리를 프로젝트에 복사하기만 하면 됩니다.
**사전 요건:** [Cursor](https://cursor.sh)가 설치되어 있어야 합니다.
### Cline
Velith는 저장소 루트에 `.clinerules` 프로젝트 수준 지침을 제공합니다. 프로젝트 디렉토리에서 작업하면 Cline이 자동으로 읽어옵니다.
**사전 요건:** VS Code 또는 JetBrains에 [Cline](https://github.com/cline/cline) 확장이 설치되어 있어야 합니다.
### Aider
Velith는 `CONVENTIONS.md`에 작성 규칙을 제공하며, `.aider.conf.yml`을 통해 자동 로드됩니다.
```bash
aider # CONVENTIONS.md가 자동 로드됨
```
**사전 요건:** [Aider](https://aider.chat)가 설치되고 API 키가 구성되어 있어야 합니다.
## 빠른 시작
```bash
# 새 책 프로젝트 시작
> /book-init
# 현재 단계를 자동 감지하고 계속
> /loom
```
플러그인이 다음 과정을 안내합니다:
1. **Onboarding** — 장르, 독자, 언어, 소스 자료, 스타일 가이드
2. **Ideation** — 시장 조사, 개념 정제, 경쟁 도서
3. **Outlining** — 스펙, 의존성, 상호 참조를 포함한 전체 챕터 개요
4. **Drafting** — 병렬 서브에이전트로 챕터별 생성
5. **Editing** — 5단계 파이프라인: 평가 → 개발 편집 → 라인 편집 → 교열 → 최종 교정
6. **Publishing** — EPUB/PDF/MOBI 변환, 메타데이터, 마케팅 계획
## 스킬
| 스킬 | 단계 | 설명 |
|------|------|------|
| `/loom` | 라우터 | 단계 자동 감지 및 라우팅 |
| `/book-init` | 0 | 새 책 프로젝트 시작 — 장르, 독자, 스타일 가이드 |
| `/book-ideation` | 1 | 개념 생성 및 검증, 경쟁 분석 |
| `/book-outline` | 2 | 챕터 개요 작성 (의존성 포함) |
| `/book-draft` | 3 | 챕터 초안 작성 (전체/특정/재개, 병렬 에이전트) |
| `/book-edit` | 4 | 5단계 편집 파이프라인 |
| `/book-publish` | 5 | EPUB/PDF/MOBI 변환, 표지, 마케팅 |
| `/book-illustrate` | 3-5 | 내지 삽화 — 장면 추출, 스타일 일관 프롬프트, 배치 계획 |
| `/book-status` | — | 터미널 대시보드 + `--ui` 브라우저 대시보드 |
| `/book-fiction` | — | 소설 패턴 (15비트, Snowflake, 캐릭터 바이블) |
| `/book-nonfiction` | — | 논픽션 패턴 (문제-해결, 근거 계층) |
| `/book-technical` | — | 기술서 패턴 (개념 기울기, 코드, 실습) |
| `/book-screenplay` | — | 대본 패턴 (3막 구조, 대화, A/B 스토리) |
| `/book-poetry` | — | 시 패턴 (형식, 심상, 연 구조) |
| `/book-game` | — | 게임 시나리오 패턴 (퀘스트 트리, 분기, 로어 바이블) |
| `/book-academic` | — | 학술 패턴 (IMRAD, 문헌 고찰, 논증 체인) |
| `/book-genre-creator` | — | 장르 선택 가이드 및 커스텀 장르 생성 위저드 |
## 에이전트
| 에이전트 | 역할 |
|----------|------|
| `book-architect` | 구조 검증, 개요 점수화, 페이싱 확인 |
| `chapter-writer` | 장르 템플릿으로 챕터 초안 생성 |
| `continuity-editor` | 챕터 간 일관성 (용어, 참조, 타임라인) |
| `style-doctor` | 문체/톤 일관성, AI 슬롭 감지 |
| `scene-generator` | GMC+RDD 구조로 장면 분석 (소설 전용) |
| `cover-designer` | 표지 개념 + Midjourney/DALL-E 이미지 프롬프트 |
| `illustrator` | 내지 삽화 — 장면 추출, 스타일 바이블, 프롬프트 생성 |
| `marketing-expert` | 독자 페르소나, 채널 전략, 12주 런치 캘린더 |
## 시각적 대시보드
`/book-status --ui`는 브라우저에서 Svelte 기반 진행 대시보드를 엽니다. 대시보드는 5초마다 자동 새로고침됩니다:
- 6단계 파이프라인 추적기 (Onboarding → Ideation → Outlining → Drafting → Editing → Publishing)
- 8개 에이전트 상태 카드 (book-architect, chapter-writer, continuity-editor, cover-designer, illustrator, marketing-expert, scene-generator, style-doctor)
- 챕터 개요, 초안 목록, 5단계 편집 칸반
- 출력 파일 상태 (EPUB/PDF/MOBI/TXT/MD) 및 발행 체크리스트
- 프로젝트 설정 및 명령어 레퍼런스
대시보드는 프로젝트별 `status.json` 파일에서 동적으로 읽습니다. 사전 빌드된 `dist/`가 포함되어 있어 플러그인 사용자는 빌드 단계가 필요 없습니다.
개발 환경에서 로컬 실행:
```bash
cd dashboard
npm install
npm run dev # http://localhost:5173
npm run build # dist/ 재빌드
```
## 설계 원칙
- **계획 후 실행** — 개요 먼저, 검증 후 작성
- **멱등성** — 완료된 챕터 건너뜀, 중단 지점에서 재개
- **토큰 효율** — 전체 텍스트가 아닌 요약 기반 컨텍스트
- **장르 인식** — 장르별 다른 구조, 템플릿, 검증
- **품질 관문** — 각 단계는 기준을 통과해야 다음으로 진행
## 외부 의존성
EPUB/PDF 출력 (Phase 5):
```bash
brew install pandoc # EPUB/PDF 변환
brew install texlive # CJK/한국어 지원 PDF
brew install --cask calibre # MOBI (Kindle) 변환 — 선택 사항
```
### 문제 해결